Runtime Tools

Runtime Tools

The reusable runtime is implemented with maintained Node.js built-ins only. It has no package dependencies and is designed for deterministic output across Windows and Linux.

中文概览：四个脚本应作为一个整体复制。索引负责生成、查询与新鲜度检查；治理检查负责元数据和边界；链接检查负责本地 Markdown 目标。

Runtime files

File	Responsibility
docs-toolkit.mjs	shared CLI parsing, paths, metadata, links, config validation, and atomic writes
document-index.mjs	deterministic Markdown/JSON index, bounded query, freshness check, and watch mode
check-doc-governance.mjs	metadata, lifecycle, directory, line-limit, archive, and generated-banner checks
check-markdown-links.mjs	local Markdown file and anchor validation

The last three files import docs-toolkit.mjs; copy all four together.

Document index commands

node scripts/document-index.mjs [generate|check|query <term>|watch]
                                [--repo <path>]
                                [--config <path>]

Command	Behavior	Writes files?
generate	builds the current index and atomically updates changed outputs	Yes
check	compares expected content with committed outputs; fails if missing or stale	No
query <term>	returns bounded JSON matches by metadata, path, heading, stable ID, or body text	No
watch	generates once, then refreshes when Markdown changes	Yes

With the default configuration, generation writes:

docs/generated/document-index.md
docs/generated/document-index.json

The Markdown file is compact navigation. The JSON file contains full headings, line numbers, access levels, metadata, and stable identifiers for tool consumption.

Generate and check

node scripts/document-index.mjs generate
node scripts/document-index.mjs check

Generation is deterministic: running it twice against the same repository state produces identical bytes. check computes the expected content without modifying the files.

Query

node scripts/document-index.mjs query payments
node scripts/document-index.mjs query ADR-042
node scripts/document-index.mjs query docs/operations

Query results are JSON and include at most 20 documents. Each match can contain heading matches, stable-identifier matches, and up to five body excerpts. Results prefer routing documents, then on-demand, source, historical, and derived documents. Exact stable-ID searches favor decision or ADR paths.

The result reports matchCount, returnedCount, and truncated, so callers know when the bounded result omitted additional documents.

Watch

node scripts/document-index.mjs watch

Watch mode combines native file events with a periodic snapshot fallback because recursive filesystem events vary across operating systems and Node.js releases. Stop it with Ctrl+C.

Watch mode is developer feedback, not shared-state enforcement. Pre-commit generation and CI check are the correctness boundary when no watcher is running.

Governance check

node scripts/check-doc-governance.mjs [--repo <path>] [--config <path>]

The check fails when it finds any of the following:

• an unknown top-level directory under the documentation root;
• missing YAML front matter or required metadata in active documents;
• a status outside allowedStatuses;
• an invalid last-reviewed date;
• a superseded document without superseded-by;
• an active document over its configured line limit;
• an archived document claiming active status;
• a generated Markdown file without a <!-- GENERATED by ... --> banner.

Directories in excludedFromMetadata remain visible to the documentation system but are not required to carry active-document metadata.

Markdown link check

node scripts/check-markdown-links.mjs [--repo <path>]

The checker validates local Markdown targets, GitHub-style heading anchors, and explicit HTML id or name anchors. It ignores external URLs and links inside fenced code blocks.

Absolute local filesystem links are rejected as non-portable. Adapt the slugging rules if the target documentation renderer does not follow GitHub semantics.

Suggested package scripts

{
  "scripts": {
    "docs:index:generate": "node scripts/document-index.mjs generate",
    "docs:index:check": "node scripts/document-index.mjs check",
    "docs:index:query": "node scripts/document-index.mjs query",
    "docs:index:watch": "node scripts/document-index.mjs watch",
    "docs:governance:check": "node scripts/check-doc-governance.mjs",
    "docs:links:check": "node scripts/check-markdown-links.mjs"
  }
}

Merge these entries into existing scripts and hooks; do not replace project-specific security or contract checks.

Suggested CI order

1. Generate or check any stack-specific code graph.
2. Check the document index for freshness.
3. Check documentation governance.
4. Check Markdown links and formatting.
5. Run normal project validation.

Exit code 0 means the command completed successfully. Usage or configuration errors exit with 2; validation failures exit non-zero and are suitable for CI gates.