Skip to content

Commit 96b2f97

Browse files
aborrusoaborruso
committed
feat: aggiungi flag CLI --art per filtrare articoli specifici nei documenti
1 parent e7645e9 commit 96b2f97

4 files changed

Lines changed: 225 additions & 0 deletions

File tree

‎openspec/changes/add-article-filter-flag/proposal.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Add Article Filter Flag
2+
3+
## Why
4+
Users currently need to manually construct URLs with `~artN` syntax to filter a specific article from normattiva.it documents. This requires knowledge of the URL structure and makes it harder to work with local XML files. A dedicated `--art` flag simplifies article filtering and works consistently with both URLs and local files.
5+
6+
## What Changes
7+
- Add `--art` CLI flag accepting article numbers (e.g., `4`, `16bis`, `3ter`)
8+
- Filter XML content to show only the specified article in markdown output
9+
- Override any existing `~artN` in URL when `--art` is provided
10+
- Support article extensions (bis, ter, quater, quinquies, etc.)
11+
- Work with both normattiva.it URLs and local XML files
12+
13+
## Impact
14+
- Affected specs: `cli-interface`, `markdown-conversion`
15+
- Affected code:
16+
- `src/normattiva2md/cli.py` - add `--art` argument
17+
- `src/normattiva2md/markdown_converter.py` - apply article filtering
18+
- `src/normattiva2md/xml_parser.py` - use existing `filter_xml_to_article()` function
19+
- No breaking changes
20+
- Backward compatible (optional parameter)

‎openspec/changes/add-article-filter-flag/specs/cli-interface/spec.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# cli-interface Delta Specification
2+
3+
## ADDED Requirements
4+
5+
### Requirement: Article Filter Parameter
6+
The system SHALL provide a command-line flag to filter output to a specific article without modifying the input URL or requiring knowledge of URL syntax.
7+
8+
#### Scenario: Basic Article Filter
9+
- **WHEN** user runs `normattiva2md --art 4 input.xml output.md`
10+
- **THEN** system SHALL download/parse the full XML
11+
- **AND** output markdown SHALL contain only article 4
12+
- **AND** all other articles SHALL be excluded from output
13+
14+
#### Scenario: Article with Extension
15+
- **WHEN** user runs `normattiva2md --art 16bis "URL" output.md`
16+
- **THEN** system SHALL filter to article 16-bis
17+
- **AND** extension SHALL be recognized without hyphen (bis, ter, quater, etc.)
18+
- **AND** common extensions SHALL be supported (bis through decies, vices, tricies, quadragies)
19+
20+
#### Scenario: Article Filter with Local File
21+
- **WHEN** user runs `normattiva2md --art 3 local.xml output.md`
22+
- **THEN** system SHALL filter the local XML file
23+
- **AND** work identically to URL-based filtering
24+
- **AND** no network access SHALL be required
25+
26+
#### Scenario: Article Filter with Normattiva URL
27+
- **WHEN** user provides normattiva.it URL without `~artN` and `--art 5` flag
28+
- **THEN** system SHALL download full document
29+
- **AND** filter output to article 5 only
30+
- **AND** URL SHALL remain unmodified during download
31+
32+
### Requirement: Parameter Priority Handling
33+
The system SHALL handle conflicts between URL-embedded article references and the `--art` flag, giving priority to the explicit flag.
34+
35+
#### Scenario: Override URL Article Reference
36+
- **WHEN** user runs `normattiva2md --art 2 "https://...~art5" output.md`
37+
- **THEN** `--art 2` flag SHALL take precedence
38+
- **AND** output SHALL contain only article 2
39+
- **AND** URL's `~art5` SHALL be ignored for filtering purposes
40+
- **AND** system SHALL download the full document (not filtered by URL)
41+
42+
#### Scenario: Nonexistent Article
43+
- **WHEN** user specifies `--art 999` for a document without article 999
44+
- **THEN** system SHALL output empty body (no articles)
45+
- **AND** print warning to stderr: "Warning: Article 999 not found in document"
46+
- **AND** metadata/frontmatter SHALL still be included
47+
- **AND** exit code SHALL be 0 (success)
48+
49+
### Requirement: Help Documentation
50+
The system SHALL document the `--art` flag in help text with clear examples.
51+
52+
#### Scenario: Help Text Display
53+
- **WHEN** user runs `normattiva2md --help`
54+
- **THEN** help SHALL include `--art` parameter description
55+
- **AND** examples SHALL show numeric articles (e.g., `--art 4`)
56+
- **AND** examples SHALL show articles with extensions (e.g., `--art 16bis`)
57+
- **AND** explain behavior with both URLs and local files

‎openspec/changes/add-article-filter-flag/specs/markdown-conversion/spec.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# markdown-conversion Delta Specification
2+
3+
## MODIFIED Requirements
4+
5+
### Requirement: Article Filtering During Conversion
6+
The conversion process SHALL support filtering XML content to a specific article before generating markdown output.
7+
8+
#### Scenario: Filter Article Before Conversion
9+
- **WHEN** article filter is requested via `--art` parameter
10+
- **THEN** system SHALL use `filter_xml_to_article()` to extract target article
11+
- **AND** conversion SHALL process only the filtered article
12+
- **AND** metadata/frontmatter SHALL reflect the full document
13+
- **AND** title SHALL indicate filtered view (e.g., "Art. 4 - [article title]")
14+
15+
#### Scenario: Preserve Document Structure
16+
- **WHEN** converting a filtered article
17+
- **THEN** article numbering SHALL be preserved as-is
18+
- **AND** article SHALL maintain proper markdown heading level (# Art. N)
19+
- **AND** paragraphs and lists SHALL retain correct formatting
20+
- **AND** legislative modifications `(( ))` SHALL be preserved
21+
22+
#### Scenario: Handle Article Extensions in eId
23+
- **WHEN** filtering article with extension (e.g., `--art 16bis`)
24+
- **THEN** system SHALL construct eId as `art_16bis` (no hyphen)
25+
- **AND** search XML using constructed eId format
26+
- **AND** support common extensions: bis, ter, quater, quinquies, sexies, septies, octies, novies, decies, vices, tricies, quadragies
27+
- **AND** case-insensitive matching for extensions
28+
29+
#### Scenario: Empty Result for Missing Article
30+
- **WHEN** requested article is not found in XML
31+
- **THEN** markdown body SHALL be empty (only metadata/frontmatter)
32+
- **AND** warning SHALL be printed to stderr
33+
- **AND** conversion SHALL complete successfully
34+
- **AND** output file SHALL be created with metadata only
35+
36+
#### Scenario: Integration with Existing Features
37+
- **WHEN** article filter is combined with `--with-urls`
38+
- **THEN** reference URLs SHALL still be generated
39+
- **AND** URLs SHALL point to correct articles in cited documents
40+
- **WHEN** article filter is combined with `--with-references`
41+
- **THEN** cited documents SHALL NOT be filtered (download full documents)
42+
- **AND** only main document SHALL be filtered to specified article

‎openspec/changes/add-article-filter-flag/tasks.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# Implementation Tasks
2+
3+
## 1. CLI Interface
4+
5+
- [ ] 1.1 Add `--art` argument to argparse in `cli.py`
6+
- Accept string input (e.g., "4", "16bis", "3ter")
7+
- Add to help text with examples
8+
- Document interaction with URL-based `~artN`
9+
10+
- [ ] 1.2 Update help examples in `cli.py`
11+
- Add example: `normattiva2md --art 4 input.xml output.md`
12+
- Add example: `normattiva2md --art 16bis "URL" output.md`
13+
- Add example: `normattiva2md --art 3 --with-urls "URL" output.md`
14+
15+
- [ ] 1.3 Add validation for `--art` parameter
16+
- Check format matches pattern: `^\d+[a-z]*$` (number + optional extension)
17+
- Warn if invalid format but continue processing
18+
- Handle case-insensitive extensions
19+
20+
## 2. Article Filtering Logic
21+
22+
- [ ] 2.1 Create article eId construction function
23+
- Convert user input "4" → "art_4"
24+
- Convert user input "16bis" → "art_16bis"
25+
- Handle common extensions (bis through quadragies)
26+
- Place in `xml_parser.py` or create new `article_utils.py`
27+
28+
- [ ] 2.2 Integrate filtering in conversion flow
29+
- In `cli.py`, pass `--art` value to conversion function
30+
- Call `filter_xml_to_article()` before markdown conversion
31+
- Handle None return (article not found)
32+
- Print warning to stderr when article not found
33+
34+
- [ ] 2.3 Update `convert_akomantoso_to_markdown_improved()`
35+
- Accept optional `article_filter` parameter
36+
- Apply filtering after XML parsing, before conversion
37+
- Preserve metadata extraction from full document
38+
- Adjust title in output when filtered
39+
40+
## 3. URL Handling
41+
42+
- [ ] 3.1 Handle URL with existing `~artN`
43+
- When `--art` is provided, it overrides URL's `~artN`
44+
- Download full document (ignore URL article reference)
45+
- Apply filtering using `--art` value instead
46+
47+
- [ ] 3.2 Ensure compatibility with `--completo` flag
48+
- If both `--completo` and `--art` provided, `--art` takes precedence
49+
- Document this behavior in help text
50+
51+
## 4. Integration with Existing Features
52+
53+
- [ ] 4.1 Test `--art` with `--with-urls`
54+
- Verify reference URLs are generated correctly
55+
- Ensure URLs point to proper articles in cited documents
56+
57+
- [ ] 4.2 Test `--art` with `--with-references`
58+
- Main document should be filtered
59+
- Referenced documents should NOT be filtered (download full)
60+
61+
- [ ] 4.3 Test `--art` with `--provvedimenti`
62+
- Both features should work independently
63+
- CSV export should work with filtered markdown
64+
65+
## 5. Testing
66+
67+
- [ ] 5.1 Unit tests for eId construction
68+
- Test numeric articles: "1", "4", "99"
69+
- Test extensions: "16bis", "3ter", "5quater"
70+
- Test edge cases: invalid formats
71+
72+
- [ ] 5.2 Integration tests via Makefile
73+
- Test with local XML file
74+
- Test with normattiva.it URL
75+
- Test with URL containing `~artN` (override scenario)
76+
- Test with nonexistent article number
77+
78+
- [ ] 5.3 Test article extension variations
79+
- Test all common extensions (bis through decies)
80+
- Test case insensitivity
81+
- Test less common extensions (vices, tricies, quadragies)
82+
83+
## 6. Documentation
84+
85+
- [ ] 6.1 Update README.md with `--art` examples
86+
- Add to CLI usage section
87+
- Show combination with other flags
88+
89+
- [ ] 6.2 Update CLAUDE.md project instructions
90+
- Document new `--art` parameter
91+
- Explain filtering behavior
92+
93+
- [ ] 6.3 Update URL_NORMATTIVA.md if needed
94+
- Cross-reference `--art` flag as alternative to `~artN`
95+
- Explain when to use each approach
96+
97+
## 7. Validation
98+
99+
- [ ] 7.1 Run `openspec validate add-article-filter-flag --strict`
100+
- Resolve any validation errors
101+
- Ensure all requirements have scenarios
102+
103+
- [ ] 7.2 Test with real normattiva.it documents
104+
- Test Decreto Legge with multiple articles
105+
- Test document with articles containing extensions
106+
- Verify output markdown quality

0 commit comments

Comments
 (0)