111 lines
3.5 KiB
Markdown
111 lines
3.5 KiB
Markdown
---
|
|
id: "01-build-catalog-command"
|
|
title: "Build the documentation catalog command"
|
|
status: done
|
|
wave: 1
|
|
depends_on: []
|
|
plan: "plan.md"
|
|
requirements: []
|
|
acceptance_criteria: []
|
|
system_design: []
|
|
---
|
|
|
|
# Task 01: Build the documentation catalog command
|
|
|
|
## Summary
|
|
|
|
Add one tested Python command that discovers architecture decisions and
|
|
specifications from repository source files.
|
|
|
|
## In scope
|
|
|
|
- Add `scripts/list-docs.py` with `decisions`, `specs`, and `validate`
|
|
subcommands.
|
|
- Add decision filters for status, area, and case-insensitive text.
|
|
- Add specification filters for system, kind, status, and case-insensitive
|
|
text.
|
|
- Add Markdown, path-only, and JSON output.
|
|
- Add deterministic sorting and actionable validation errors.
|
|
- Add focused tests in `scripts/list-docs.test.py`.
|
|
|
|
## Out of scope
|
|
|
|
- Editing any tracked documentation catalog.
|
|
- Changing the metadata format of existing documents.
|
|
- Adding a Python package dependency.
|
|
|
|
## Implementation details
|
|
|
|
Use only the Python standard library. Accept an internal root override in tests
|
|
so fixtures use temporary directories. Keep repository paths relative in all
|
|
output and errors.
|
|
|
|
Decision parsing must support metadata forms already present in the repository.
|
|
Use the filename stem as the identifier. Use the first ADR heading as the title.
|
|
Read status, date, and area from the metadata block. Filter status by its leading
|
|
class, such as `accepted`, while displaying the complete value.
|
|
|
|
Specification parsing derives `system` and `kind` from the path. Recognized
|
|
kinds are `system`, `glossary`, `requirement`, `system-design`, `product`, and
|
|
`legacy`. Both the catalog and the specification linter use
|
|
`scripts/spec_metadata.py` for path classification, frontmatter parsing, and
|
|
status sets.
|
|
|
|
The JSON output contains a top-level schema version and an ordered `documents`
|
|
array. Each item contains the common path, title, and type fields plus the
|
|
type-specific metadata. Empty filters return an empty successful result.
|
|
|
|
## Acceptance
|
|
|
|
- The command finds every valid decision and specification source file.
|
|
- Repeated runs on the same tree produce byte-identical output.
|
|
- Every documented filter works alone and with other filters.
|
|
- Each output format represents the same ordered result set.
|
|
- Invalid metadata returns a nonzero exit status and identifies the file.
|
|
- Tests cover existing ADR metadata variants, every specification source kind,
|
|
and specification frontmatter errors.
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
python3 scripts/list-docs.test.py
|
|
python3 scripts/list-docs.py validate
|
|
python3 scripts/list-docs.py decisions --status accepted --format markdown
|
|
python3 scripts/list-docs.py specs --system ui --kind requirement --format paths
|
|
```
|
|
|
|
## Files likely touched
|
|
|
|
- `scripts/list-docs.py`
|
|
- `scripts/list-docs.test.py`
|
|
- `scripts/spec_metadata.py`
|
|
- `scripts/lint-spec-files.py`
|
|
|
|
## Dependencies
|
|
|
|
None.
|
|
|
|
## Risks
|
|
|
|
- Loose ADR parsing can hide malformed files. Keep accepted variants explicit
|
|
and reject ambiguous metadata.
|
|
- Markdown titles can contain table delimiters. Escape cells in the formatter.
|
|
|
|
## Parallelism
|
|
|
|
`sequential`
|
|
|
|
## Inputs
|
|
|
|
- `docs/decisions/*.md`
|
|
- `docs/specs/**/*.md`
|
|
- `scripts/lint-spec-files.py`
|
|
- `docs/decisions/2026-09-07-on-demand-document-catalogs.md`
|
|
|
|
## Results
|
|
|
|
Done. The catalog command discovers every supported decision and specification
|
|
source kind. Product documents and valid glossaries are not legacy sources.
|
|
Malformed system README metadata fails validation with the source path. The
|
|
focused tests, repository validation, and documented filter examples pass.
|