blob: d7a8691c6a55eac2a926778a7eb6d2a0959a36eb [file] [view]
# check-doc-inventory.py
Checks that the list of Juneau modules in `artifact-paths.json` matches the `modules[]` of the projects in `src/data/projects.ts`, and that `artifact-packages.json` and the allow-list agree with it.
## When to use
- After a module is added, renamed or removed, to see which inventory entries must change.
- Before publishing, as a drift check that needs no build tooling.
- For page frontmatter, sidebars and links, use `verify-docs.py` instead.
## Usage
```bash
python3 scripts/check-doc-inventory.py
python3 scripts/check-doc-inventory.py --strict
python3 scripts/check-doc-inventory.py --json
```
Standard library only; it does not invoke Maven or Docusaurus.
## Options
| Option | Argument | Default | Meaning |
|---|---|---|---|
| `--strict` | none | off | Warnings also make the exit code non-zero. |
| `--json` | none | off | Print a JSON report (`summary` and `findings`) instead of text. |
| `--docs-dir` | directory | parent of `scripts/` | Docs root to check. |
## What it does
1. Loads `artifact-paths.json`, `artifact-packages.json`, the projects from `src/data/projects.ts` (through `project_index.py`) and `scripts/check-doc-inventory-allowlist.txt` (one module name per line, `#` comments; missing file means empty).
2. Computes the publishable modules: every key of `artifact-paths.json` minus the `AGGREGATOR_POMS` set (defined in `project_index.py`) minus the allow-list.
3. **inventory:** every publishable module must be in some project's `modules[]`; a module in none (and not allow-listed) is an error, as is an unreadable `projects.ts`.
4. **stale-rows:** every module in a project's `modules[]` must be a key of `artifact-paths.json`.
5. **packages:** every `artifact-packages.json` key must be a key of `artifact-paths.json` (error); a publishable module with no packages entry is a warning.
6. **allowlist:** each allow-list entry must exist in `artifact-paths.json` (error), and must not also be in a project's `modules[]` (error).
7. Prints the findings grouped as errors, warnings and notes, with a final count line.
## Output and exit codes
Text report on stdout (or JSON with `--json`); nothing is written. The text ends with `check-doc-inventory: N errors, M warnings`.
| Code | Meaning |
|---|---|
| 0 | No errors (and no warnings under `--strict`). |
| 1 | At least one error, or a warning under `--strict`. |
| 2 | `artifact-paths.json` or `artifact-packages.json` is missing. |
## Gotchas
- `AGGREGATOR_POMS` is in `project_index.py`; update it when the reactor structure changes.
- Both JSON files are regenerated or refreshed by `build-docs.py`, so run this after a build if you want it to see current modules.
- `modules[]` entries are read by the strict `projects.ts` parser; a format error in that file is reported as an `inventory` error with its line number.
## See also
- `verify-docs.py`, `build-docs.py`