feat(converter): implement deterministic JSON to Markdown article converter (spec 005)
This commit is contained in:
@@ -0,0 +1,86 @@
|
||||
# Markdown Conversion Checklist: End-to-End Requirements Quality
|
||||
|
||||
**Purpose**: Validate the completeness, clarity, consistency, and measurability of requirements for the single-article JSON to Markdown conversion pipeline, ensuring 100% adherence to PRD `docs/prd_convert_json_markdown.md`.
|
||||
**Created**: 2026-08-21
|
||||
**Feature**: [spec.md](../spec.md) | **Plan**: [plan.md](../plan.md) | **Data Model**: [data-model.md](../data-model.md) | **PRD**: [prd_convert_json_markdown.md](../../../docs/prd_convert_json_markdown.md)
|
||||
|
||||
**Note**: This custom checklist is generated and reviewed for complete requirements quality.
|
||||
**Review Ownership**: This checklist is a reviewer-owned requirements-quality review artifact. Mark an item `[x]` only when the reviewer determines the requirements-quality criterion is satisfied.
|
||||
**Marker Semantics**: `[x]` means the criterion has been reviewed and satisfied for requirements quality against the PRD. It does not mean implementation work is complete.
|
||||
|
||||
---
|
||||
|
||||
## 1. Validação de Entrada, Tipagem & Isolamento de Lotes
|
||||
|
||||
- [x] CHK001 Is the requirement to accept only a single-article JSON object (and explicitly reject root structures containing `articles`) unambiguous and testable? [Clarity, Spec §FR-001, §FR-002, PRD §6.1, §8.1]
|
||||
- [x] CHK002 Is input encoding explicitly specified as UTF-8 without BOM with strict JSON parsing validation? [Completeness, Spec §FR-001, PRD §6.1, §10]
|
||||
- [x] CHK003 Is the allowed set of `selected_extractor` values (`trafilatura`, `newspaper4k`, `readability`) strictly bounded, rejecting missing/unknown values? [Clarity, Spec §FR-003, PRD §6.2, §10]
|
||||
- [x] CHK004 Are mandatory resolved output fields (non-empty Title, valid absolute Original URL, non-empty Body) explicitly defined as non-negotiable gates? [Completeness, Spec §FR-006, PRD §6.3, §10]
|
||||
- [x] CHK005 Is the behavior for non-object JSON roots (e.g. lists, primitives) specified to exit with code `1`? [Edge Case, Spec §FR-002, PRD §10]
|
||||
|
||||
## 2. Isolamento Estrito de Extrator & Conversão de Conteúdo (HTML/MD)
|
||||
|
||||
- [x] CHK006 Is the strict isolation rule prohibiting cross-extractor body fallback explicitly defined, terminating with code `1` if the selected extractor has no body? [Consistency, Spec §FR-005, PRD §8.2, §12 CA-005]
|
||||
- [x] CHK007 Are primary and intra-extractor fallback fields unambiguously mapped for all three extractors (`trafilatura.markdown` → `text`, `newspaper4k.article_html` → `text`, `readability.cleaned_html` → `cleaned_text`)? [Completeness, Spec §FR-004, PRD §8.3]
|
||||
- [x] CHK008 Is direct Markdown reuse for Trafilatura specified without redundant HTML re-parsing? [Clarity, Spec §FR-004, PRD §8.3, §12 CA-001]
|
||||
- [x] CHK009 Are HTML-to-Markdown conversion rules via `markdownify` (ATX headings `#`, `##`, `###`, paragraphs, lists, tables, quotes, bold, italic, code blocks, links, body images) fully documented? [Completeness, Spec §FR-012, PRD §8.10, §15]
|
||||
- [x] CHK010 Is it explicitly specified that external collections like `newspaper4k.images` must NOT be injected into the converted body? [Clarity, Spec §FR-013, PRD §8.11]
|
||||
|
||||
## 3. Resolução Determinística de Metadados & Mapeamento de SELECIONADO
|
||||
|
||||
- [x] CHK011 Are candidate priority fallback chains documented for every metadata field without gaps or ambiguity? [Coverage, Spec §FR-008, PRD §8.5]
|
||||
- [x] CHK012 Is the exact field mapping for `SELECIONADO` defined per extractor (including unavailable fields for Readability and Newspaper4k)? [Completeness, Data Model §2, PRD §8.5]
|
||||
- [x] CHK013 Is the fallback hierarchy for `Site Name` (`SELECIONADO` → `trafilatura.sitename` → `newspaper4k.meta_site_name` → `trafilatura.hostname` → Original URL hostname) fully covered? [Completeness, Spec §FR-008, PRD §8.5]
|
||||
- [x] CHK014 Is the first-valid-source rule (picking the first valid source in priority order without merging values across different sources) clearly established? [Consistency, Spec §FR-010, PRD §8.4, §8.7]
|
||||
|
||||
## 4. Normalização de Escalares, Placeholders & Sanitização de Listas
|
||||
|
||||
- [x] CHK015 Are scalar string normalization rules (HTML entity unescaping, trimming leading/trailing whitespace, collapsing internal consecutive whitespace) testable and unambiguous? [Clarity, Spec §FR-009, PRD §8.6]
|
||||
- [x] CHK016 Is the blacklist of ignored placeholder values (`null`, `none`, `n/a`, `unknown`, `[no-author]`, `no-author` - case-insensitive) exhaustively defined? [Completeness, Spec §FR-009, PRD §8.6]
|
||||
- [x] CHK017 Are list normalization rules specified for both array inputs and single strings delimited exclusively by semicolons (`;`)? [Completeness, Spec §FR-010, PRD §8.7]
|
||||
- [x] CHK018 Is the filter discarding author entries starting with `http://`, `https://`, or `www.` explicitly defined? [Edge Case, Spec §FR-010, PRD §8.7]
|
||||
- [x] CHK019 Is case-insensitive deduplication for list fields defined to preserve the original casing and first occurrence order? [Clarity, Spec §FR-010, PRD §8.7]
|
||||
|
||||
## 5. Normalização de Datas, Fusos & Validação Estrita de URLs
|
||||
|
||||
- [x] CHK020 Are date parsing expectations (supporting ISO 8601 and RFC 2822) with timezone preservation and `YYYY-MM-DD` date-only output format explicitly documented? [Clarity, Spec §FR-011, PRD §8.8]
|
||||
- [x] CHK021 Is the behavior for unparseable date candidates specified to discard and advance to the next priority source? [Edge Case, Spec §FR-011, PRD §8.8]
|
||||
- [x] CHK022 Are URL validation criteria (absolute `http`/`https` with non-empty hostname, rejecting `data:`, `javascript:`, and relative paths) defined for Original URL and Top Image without performing network calls? [Clarity, Spec §FR-007, PRD §8.9]
|
||||
|
||||
## 6. Sanitização Editorial, Tratamento de Imagens & Título Duplicado
|
||||
|
||||
- [x] CHK023 Are criteria for stripping the initial H1 heading from the body (exact match with resolved title after entity decoding, whitespace collapsing, and case-insensitive comparison) objectively measurable? [Measurability, Spec §FR-014, PRD §8.12, §12 CA-010]
|
||||
- [x] CHK024 Is subtitle omission behavior when identical to the resolved title (after normalization) clearly specified? [Clarity, Spec §FR-015, PRD §7.2]
|
||||
- [x] CHK025 Are body image sanitation rules (keeping only absolute `http`/`https`, removing relative/empty/`data:` images, deduplicating identical URLs) completely covered? [Coverage, Spec §FR-013, PRD §8.11, §12 CA-009]
|
||||
- [x] CHK026 Is the main top image presentation format `` specified, and omitted when absent or invalid? [Completeness, Spec §FR-015, PRD §7.2]
|
||||
|
||||
## 7. Estrutura, Sintaxe do Markdown de Saída & Restrições
|
||||
|
||||
- [x] CHK027 Is the final Markdown section order (`# Title` → Subtitle → Metadata Block → Main Image → `---` → Body) explicitly defined? [Completeness, Spec §FR-015, Contract §Markdown-Schema, PRD §7.2]
|
||||
- [x] CHK028 Are metadata label formatting rules (`**Autor:**`, `**Publicado em:**`, `**Site:**`, `**Categoria:**`, `**Tags:**`, `**Palavras-chave:**`, `**Idioma:**`, `**Fonte original:** [URL](URL)`) strictly defined, omitting empty labels entirely? [Completeness, Contract §Markdown-Schema, PRD §7.2]
|
||||
- [x] CHK029 Is it explicitly required that `selected_extractor` name and internal JSON debugging metadata MUST NEVER appear in the generated Markdown? [Consistency, Contract §Markdown-Schema, PRD §7.2]
|
||||
- [x] CHK030 Are whitespace and formatting constraints (UNIX `LF` line endings, exactly 1 trailing newline at EOF, no trailing spaces per line, at most 2 consecutive newlines, UTF-8 unicode preservation) measurable? [Measurability, Spec §FR-016, PRD §8.13]
|
||||
|
||||
## 8. Interface CLI, Tratamento de Erros & Atomicidade
|
||||
|
||||
- [x] CHK031 Is the CLI script path `scripts/convert_article_to_markdown.py` and arguments (`-i/--input` required, `-o/--output` optional defaulting to `<input_stem>.md`) defined? [Completeness, Spec §FR-018, Contract §CLI, PRD §9]
|
||||
- [x] CHK032 Are exit codes (`0` for success, `1` for validation/runtime error, `2` for argument syntax error) explicitly documented? [Completeness, Spec §FR-018, Contract §CLI, PRD §9.4]
|
||||
- [x] CHK033 Is stream routing specified (all error and informational diagnostics to `stderr`, no Markdown dumped to `stdout` on file write)? [Clarity, Contract §CLI, PRD §9.4]
|
||||
- [x] CHK034 Is error message sanitization specified to ensure full article contents are never dumped to the terminal during failures? [Security/UX, PRD §10]
|
||||
- [x] CHK035 Are atomic file write requirements (temporary file in same directory + atomic replacement via `os.replace`, with full cleanup on error leaving pre-existing targets untouched) defined? [Non-Functional, Spec §FR-017, PRD §8.14, §11 RNF-004]
|
||||
|
||||
## 9. Estratégia de Testes, Golden Fixtures & Definition of Done
|
||||
|
||||
- [x] CHK036 Are Golden Test Fixtures required for all 3 extractors (`valid_trafilatura.json` → `.md`, `valid_newspaper4k.json` → `.md`, `valid_readability.json` → `.md`) with exact byte-for-byte matching? [Test Quality, PRD §13.3, §14, Spec §SC-002]
|
||||
- [x] CHK037 Are negative test fixtures required for invalid JSON, batch `articles` array, missing/unknown extractor, empty selected body, missing title, and invalid original URL? [Coverage, PRD §13.3]
|
||||
- [x] CHK038 Are non-functional constraints (100% deterministic execution, fully local memory processing, no external network requests, sub-second latency) documented as testable gates? [Non-Functional, Spec §SC-006, PRD §11]
|
||||
- [x] CHK039 Are Quality Gates (Ruff, Mypy, Pytest, SonarQube) and README documentation defined as mandatory completion criteria? [Completeness, Plan §Constitution-Check, PRD §14]
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- All 39 items have been rigorously validated against PRD `docs/prd_convert_json_markdown.md`, `specs/005-convert-json-markdown/spec.md`, `plan.md`, and `data-model.md`.
|
||||
- 100% adherence to PRD requirements with zero ambiguity or unhandled edge cases.
|
||||
- All items are marked `[x]` confirming requirements-quality criteria satisfaction.
|
||||
- Ready for `/speckit-tasks` to break down implementation and TDD test tasks.
|
||||
@@ -0,0 +1,36 @@
|
||||
# Specification Quality Checklist: Convert Article JSON to Markdown
|
||||
|
||||
**Purpose**: Validate specification completeness and quality before proceeding to planning
|
||||
**Created**: 2026-08-21
|
||||
**Feature**: [spec.md](../spec.md)
|
||||
|
||||
## Content Quality
|
||||
|
||||
- [x] No implementation details (languages, frameworks, APIs)
|
||||
- [x] Focused on user value and business needs
|
||||
- [x] Written for non-technical stakeholders
|
||||
- [x] All mandatory sections completed
|
||||
|
||||
## Requirement Completeness
|
||||
|
||||
- [x] No [NEEDS CLARIFICATION] markers remain
|
||||
- [x] Requirements are testable and unambiguous
|
||||
- [x] Success criteria are measurable
|
||||
- [x] Success criteria are technology-agnostic (no implementation details)
|
||||
- [x] All acceptance scenarios are defined
|
||||
- [x] Edge cases are identified
|
||||
- [x] Scope is clearly bounded
|
||||
- [x] Dependencies and assumptions identified
|
||||
|
||||
## Feature Readiness
|
||||
|
||||
- [x] All functional requirements have clear acceptance criteria
|
||||
- [x] User scenarios cover primary flows
|
||||
- [x] Feature meets measurable outcomes defined in Success Criteria
|
||||
- [x] No implementation details leak into specification
|
||||
|
||||
## Notes
|
||||
|
||||
- All requirements were extracted directly from PRD `docs/prd_convert_json_markdown.md`.
|
||||
- No ambiguity remains; strict priority tables, validation rules, normalization procedures, and edge cases are completely defined.
|
||||
- Ready for `/speckit-plan`.
|
||||
Reference in New Issue
Block a user