Files
kandev/docs/plans/docs-catalog-discovery/task-01-build-catalog-command.md
T
2026-09-12 17:23:20 +01:00

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.