feat(converter): implement deterministic JSON to Markdown article converter (spec 005)

2026-08-21 10:30:14 -03:00
parent 64dfd842de
commit 926a6b8cfc
58 changed files with 20138 additions and 2301 deletions
@@ -0,0 +1,31 @@
+# CLI Contract: `convert_article_to_markdown.py`
+
+**Feature**: `005-convert-json-markdown` | **Date**: 2026-08-21
+
+## 1. Script Signature
+
+```bash
+python scripts/convert_article_to_markdown.py -i <input_path> [-o <output_path>]
+```
+
+## 2. Command-Line Arguments
+
+| Flag | Long Option | Type | Required | Default | Description |
+|---|---|---|:---:|---|---|
+| `-i` | `--input` | String / Path | Yes | — | Path to the source JSON file containing exactly one article object. |
+| `-o` | `--output` | String / Path | No | `<input_stem>.md` | Destination path for the generated Markdown file. |
+
+## 3. Exit Codes
+
+| Exit Code | Meaning | Standard Streams Behavior |
+|:---:|---|---|
+| `0` | **Success**: Article converted and Markdown written atomically. | Diagnostic info on `stderr`, clean execution. |
+| `1` | **Runtime / Validation Error**: Malformed JSON, root `articles` array, missing mandatory fields (title, original URL, body), invalid selected extractor, or write failure. | Descriptive error message printed to `stderr`. Pre-existing target file unmodified. |
+| `2` | **Argument Error**: Missing required `-i/--input` argument, unrecognized arguments, or invalid CLI usage. | Standard `argparse` usage and error output printed to `stderr`. |
+
+## 4. Standard Stream Behavior
+
+- **`stdout`**: Reserved. No Markdown text is dumped to `stdout` when generating file output.
+- **`stderr`**: Receives progress/error diagnostics, e.g.:
+  - `[INFO] Converted 'out/article_001.json' -> 'out/article_001.md' (extractor: trafilatura)`
+  - `[ERROR] Invalid input: JSON contains batch 'articles' array. Only single article JSON files are accepted.`
@@ -0,0 +1,38 @@
+# Markdown Schema Contract: Output Article Markdown
+
+**Feature**: `005-convert-json-markdown` | **Date**: 2026-08-21
+
+## 1. Output Document Specification
+
+The generated Markdown document MUST strictly adhere to the following template structure:
+
+```markdown
+# {Resolved Title}
+
+{Resolved Subtitle/Description - OMITTED IF ABSENT OR EQUAL TO TITLE}
+
+**Autor:** {Resolved Authors joined by ", " - OMITTED IF ABSENT}
+**Publicado em:** {Resolved Publication Date - OMITTED IF ABSENT}
+**Site:** {Resolved Site Name - OMITTED IF ABSENT}
+**Categoria:** {Resolved Categories joined by ", " - OMITTED IF ABSENT}
+**Tags:** {Resolved Tags joined by ", " - OMITTED IF ABSENT}
+**Palavras-chave:** {Resolved Keywords joined by ", " - OMITTED IF ABSENT}
+**Idioma:** {Resolved Language Code - OMITTED IF ABSENT}
+**Fonte original:** [{Resolved Original URL}]({Resolved Original URL})
+
+![Imagem principal]({Resolved Top Image URL - OMITTED IF ABSENT})
+
+---
+
+{Converted Markdown Body Content}
+```
+
+## 2. Formatting & Syntax Constraints
+
+1. **Character Encoding**: UTF-8 without BOM.
+2. **Line Delimiters**: UNIX-style `LF` (`\n`).
+3. **Trailing Whitespace**: Stripped from every line.
+4. **Blank Lines**: Maximum of 2 consecutive newline characters (`\n\n`), preventing excessive vertical spacing.
+5. **EOF Delimiter**: Ends with exactly one trailing newline character (`\n`).
+6. **No Placeholders**: Never print `null`, `None`, `N/A`, `unknown`, `[no-author]`, or empty metadata labels (e.g. `**Autor:** `).
+7. **No Internal Leakage**: Never output `selected_extractor` name, scoring metrics, or JSON internals in the final document.