## tools/

Utility scripts for the Architect language tools project.

Scripts are split into two tiers:

- **`tools/`** — entry points called directly via `npm run …`
- **`tools/shared/`** — helper modules imported by the entry points; not called directly

---

### Entry points (`tools/`)

| Script | npm command(s) | Purpose |
|---|---|---|
| `generate-diagnostic-docs.js` | `docs:diagnostics` | Injects a per-rule summary table into `README.md` |
| `generate-comprehensive-diagnostic-reference.js` | `docs:diagnostics`, `docs:diagnostics:reference`, `docs:diagnostics:check` | Builds `dev-docs/DIAGNOSTICS_COMPREHENSIVE_REFERENCE.md`; also exports `buildDiagnosticRows` and `buildCoverageMap` for use by the HTML report |
| `generate-diagnostic-html-report.js` | `docs:diagnostics` | Builds `dev-docs/DIAGNOSTICS_COMPREHENSIVE_REFERENCE.html` — a self-contained interactive report with filters and sorting |
| `validate-builtins.js` | `pretest`, `validate:builtins` | Verifies built-in function registry completeness |
| `validate-diagnostic-coverage.js` | `ci:diagnostics` | Checks all diagnostic IDs have catalog entries |
| `validate-settings-registration.js` | `ci:diagnostics`, `validate:settings-registration` | Checks all rules are registered in `package.json` `contributes.configuration` |

### Shared helpers (`tools/shared/`)

| Module | Consumers | Purpose |
|---|---|---|
| `settings-metadata.js` | `generate-diagnostic-docs.js`, `generate-comprehensive-diagnostic-reference.js`, `validate-settings-registration.js` | Reads VS Code settings contributions from `package.json`; maps rule IDs to their setting keys and groups |
| `diagnostic-report-columns.js` | `generate-comprehensive-diagnostic-reference.js`, `generate-diagnostic-html-report.js` | Column manifest for the comprehensive reference reports — declares order, labels, sortable, filterable, and searchable flags for every column |

---

### Adding a new script

Only add scripts here if they serve a permanent, ongoing purpose (build step, CI gate, or developer tool). Temporary one-off scripts should be run from a local scratch directory and not committed.

- If the script is a standalone entry point, add it to `tools/` and register it in `package.json`.
- If it is a shared helper with no direct `npm run` command, add it to `tools/shared/`.
