pasika 0.2.0 → 0.3.1

package/README.md

@@ -1,60 +1,83 @@
 # pasika
 
-Reusable agent setup package.
+Documentation, the lint rules derived from it, and the CLI that applies and diagnoses both.
 
-`pasika` stores portable agent setup assets that individual repos can apply or adapt.
-
-## Scope
-
-This repo intentionally starts narrow:
-
-- reusable agent setup assets only
-- shared docs at the repo root
-- no project-specific workflows or business logic
+`pasika` owns the framework's documentation and turns it into checks. Every requirement in `docs/` is recorded in an enforcement registry that says which ESLint rule, which `pasika` check, or which human judgment covers it — and CI fails when a requirement has no answer.
 
 ## Layout
 
 ```text
 docs/
-  code-organization-guide/
-  documentation-guide/
-  styling-guide/
-  agent-conventions.md
+  agent-policy.md                 # repo-wide requirements (Policy)
+  code-organization-guide/        # placement, extraction, module conventions
+  documentation-guide/            # how documents themselves are written
+  framework-adoption-guide/       # adopting and updating the framework
+  styling-guide/                  # Tailwind theme, composition, variants, states
+enforcement/
+  registry.json                   # requirement → enforcement, keyed by content hash
+  coverage.ts                     # reconciles the docs against the registry
+  docs-check.ts                   # the documentation guide, mechanically
 eslint/
-  pasika/
-    rules/
-dist/
-  ...
+  pasika/rules/                   # the lint rules, with fixture tests beside them
+cli/
+  index.ts                        # the `pasika` command
 ```
 
-## What belongs here
+## Documentation
 
-- portable setup scripts
-- shared naming and layout conventions
-- reusable source-organization lint rules
+Documents come in four kinds — Guide, Rule, Policy, and Reference — each with a template and a creation rule under `docs/documentation-guide/`. A Rule owns requirements about one subject and demonstrates them with paired Incorrect/Correct examples; a Reference describes and defines but never constrains; a Policy document collects repo-wide requirements that span unrelated subjects; a Guide sequences the others into workflows. Each guide owns its own glossary, so a term is defined beside the workflow that uses it.
 
-## What stays in project repos
+## Enforcement
 
-- final agent config folders in project repos
-- project-specific rules, agents, and prompts
-- repository-specific plugin choices
-- scripts that depend on a specific app, CI setup, or codebase
+Requirements are identified by a hash of their canonical text, not by a hand-written id, so rewording one is visible:
 
-## Development
+```jsonc
+{
+  "doc": "code-organization-guide/rules/no-mixed-concerns-rule.md",
+  "text": "A .tsx file that defines a component MUST contain exactly one component.",
+  "hash": "b19fe3bd34",
+  "kind": "eslint",
+  "ref": "pasika/no-mixed-concerns",
+  "note": "counts exported components; a second component that is not exported is not detected"
+}
+```
+
+The `note` field is where a check's known gap is recorded, so a partial check never reads as a complete one.
+
+| Kind | Meaning |
+| --- | --- |
+| `eslint` | An ESLint rule reports it, and a fixture test titled with the requirement pins it |
+| `doctor` | A `pasika doctor` check reports it |
+| `docs-check` | A `pasika docs` check reports it |
+| `planned` | Mechanically checkable, not written yet; `note` names the intended check |
+| `judgment` | No mechanical check can decide it; `note` says why |
+| `permission` | The requirement grants permission, so there is nothing to check |
+
+`pasika coverage` fails when a requirement is unclassified, when its text changed, when it disappeared, when its `ref` names a check that does not exist, or when a lint-enforced requirement has no test. Confirm a reworded requirement with `pasika coverage --accept`.
+
+## Commands
 
 ```bash
-npm run lint
-npm run typecheck
-npm run build
+npx pasika docs                # check a docs/ folder against the documentation guide
+npx pasika docs --dir content  # check another folder
+npx pasika coverage            # check that every requirement has recorded enforcement
+npx pasika coverage --accept   # record reworded and removed requirements
 ```
 
-## ESLint Pasika Ruleset
+Both accept `--json` for agent use.
 
-Pasika ships enforceable lint rules derived from its documentation. Each rule carries a `@see` annotation linking to its source doc so future audits can verify rule/doc alignment.
+A requirement `coverage` reports as `new` is classified with the hash it prints:
 
-### Usage with Zirka (recommended)
+```bash
+npx pasika coverage --classify d311a1457a --kind eslint --ref pasika/import-boundaries
+npx pasika coverage --classify 041b665bd7 --kind judgment --note "no check can compare against the previous state"
+```
 
-Enable pasika through Zirka's `styleguide`:
+The command refuses a hash no requirement has, a `ref` naming a rule or check that does not exist, a `ref` on a kind that nothing reports, and `judgment` or `planned` without a note — so a mismatch cannot reach the registry by hand. Re-running it on an already-classified requirement reclassifies it and reports what it was.
+
+## ESLint ruleset
+
+### With Zirka (recommended)
 
 ```ts
 // eslint.config.ts
@@ -70,34 +93,47 @@ const { eslintConfig } = styleguide({
 export default eslintConfig;
 ```
 
-### Usage without Zirka
-
-Import the config directly and compose with your own:
+### Without Zirka
 
 ```ts
 // eslint.config.ts
 import { pasikaConfig } from "pasika/eslint";
-import { RuleSeverity, styleguide } from "zirka";
 
-const { eslintConfig } = styleguide({
-  next: RuleSeverity.Error,
-  node: RuleSeverity.Error,
-  typescript: RuleSeverity.Error,
-});
-
-export default [...((await eslintConfig) ?? []), pasikaConfig];
+export default [pasikaConfig];
 ```
 
-### Rule → Doc Mapping
+The ruleset applies to `src/**` only, so a repository without a `src/` tree passes it trivially.
+
+| Rule | Enforces |
+| --- | --- |
+| `pasika/filename-case` | kebab-case for files that define no component |
+| `pasika/import-boundaries` | The shorter of the relative path and the `@/*` alias, and the layer boundaries |
+| `pasika/no-mixed-concerns` | One exported React component per `.tsx` file |
+| `pasika/no-arbitrary-tailwind` | No arbitrary `-[value]` classes, including inside `cn()` conditionals |
+| `pasika/enforce-cn-merge` | `cn()` instead of `+` or template literals; at most five classes per group |
+| `pasika/enforce-cva-variant-props` | `VariantProps<typeof …>` instead of hand-written unions |
+| `pasika/enforce-barrel-exports` | A nested `index.ts` re-exports only its component |
+| `pasika/component-placement` † | The folder a component's consumers imply |
+| `pasika/support-file-placement` † | The folder a hook, type, schema, constant, or utility belongs in |
+
+Run `pasika coverage --json` for the exact requirement each rule covers.
+
+### † Cross-file rules
 
-Every rule's source file declares the documentation it enforces. Use this table to trace a lint hit back to its reasoning:
+Where a component or support file belongs depends on which files import it, so these two rules index the whole `src/` tree instead of looking at one file. Two consequences:
 
-| Rule | Enforces | Source Doc |
-|---|---|---|
-| `pasika/filename-case` | Smart/PascalCase vs dumb/kebab-case file names | `docs/code-organization-guide/rules/smart-vs-dumb-component-rule.md` |
-| `pasika/import-boundaries` | Relative vs `@/*` imports, layer boundaries | `docs/code-organization-guide/rules/exports-and-imports-rule.md` |
-| `pasika/no-mixed-concerns` | One React component per `.tsx` file | `docs/code-organization-guide/rules/no-mixed-concerns-rule.md` |
-| `pasika/no-arbitrary-tailwind` | No arbitrary `-[value]` Tailwind classes | `docs/styling-guide/rules/arbitrary-value-rule.md` |
-| `pasika/enforce-cn-merge` | Use `cn()` not `+`/template literals; ≤5 classes per group | `docs/styling-guide/rules/class-composition-rule.md` |
-| `pasika/enforce-cva-variant-props` | Use `VariantProps<typeof>` not manual union types | `docs/styling-guide/rules/component-variant-rule.md` |
-| `pasika/enforce-barrel-exports` | Nested `index.ts` only re-exports the parent component | `docs/code-organization-guide/rules/folder-nesting-rule.md` |
+- **Do not pass `--cache`.** Move a file and the finding belongs to a *different* file, whose cache entry is unchanged — so ESLint would replay a stale verdict. `agent-policy.md` requires lint commands to run without it.
+- The index is read from disk rather than from ESLint's file list, so a partial run such as `lint-staged` still judges against the true graph.
+
+Both are inert in a repository with no `src/` tree.
+
+## Development
+
+```bash
+npm run lint
+npm run typecheck
+npm run test
+npm run docs
+npm run coverage
+npm run build
+```

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { Command } from "commander";
+import { buildCoverageReport, classifyRequirement, readRegistry, writeRegistry, } from "../enforcement/coverage.js";
+import { enforcementKindSchema } from "../enforcement/types.js";
+import { checkDocs } from "../enforcement/docs-check.js";
+const REGISTRY_RELATIVE_PATH = path.join("enforcement", "registry.json");
+/** Walks up from `startDir` to the directory that holds the enforcement registry. */
+function findRegistryRoot(startDir) {
+    let dir = path.resolve(startDir);
+    for (;;) {
+        if (existsSync(path.join(dir, REGISTRY_RELATIVE_PATH)))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+const ISSUE_LABELS = {
+    new: "new       ",
+    changed: "changed   ",
+    removed: "removed   ",
+    "unknown-ref": "bad ref   ",
+    "missing-test": "no test   ",
+};
+function truncate(text, width) {
+    return text.length <= width ? text : `${text.slice(0, width - 1)}…`;
+}
+const program = new Command();
+program.name("pasika").description("Applies and diagnoses the pasika framework.");
+program
+    .command("docs")
+    .description("Check documentation against the documentation guide.")
+    .option("--dir <path>", "documentation folder to check", "docs")
+    .option("--json", "print findings as JSON")
+    .action((options) => {
+    const docsRoot = path.resolve(options.dir);
+    if (!existsSync(docsRoot)) {
+        console.error(`No documentation folder at ${docsRoot}`);
+        process.exit(1);
+    }
+    const { docs, findings } = checkDocs(docsRoot);
+    if (options.json) {
+        console.log(JSON.stringify({ documents: docs.length, findings }, undefined, 2));
+        process.exit(findings.length > 0 ? 1 : 0);
+    }
+    for (const finding of findings) {
+        console.log(`  ✗ ${finding.doc}:${String(finding.line)}  ${finding.check}  ${finding.message}`);
+    }
+    console.log(findings.length === 0
+        ? `\n✓ ${String(docs.length)} documents pass`
+        : `\n${String(docs.length)} documents checked · ${String(findings.length)} findings`);
+    process.exit(findings.length > 0 ? 1 : 0);
+});
+program
+    .command("coverage")
+    .description("Check that every documented requirement has recorded enforcement.")
+    .option("--accept", "rehash reworded requirements and drop removed ones")
+    .option("--classify <hash>", "record how one requirement is checked")
+    .option("--kind <kind>", "enforcement kind for --classify")
+    .option("--ref <id>", "rule or check id for --classify")
+    .option("--note <text>", "why it is not checked, or what the check misses")
+    .option("--json", "print the report as JSON")
+    .action((options) => {
+    const root = findRegistryRoot(process.cwd());
+    if (!root) {
+        console.error(`No ${REGISTRY_RELATIVE_PATH} found in this directory or any parent.`);
+        process.exit(1);
+    }
+    const docsRoot = path.join(root, "docs");
+    if (!existsSync(docsRoot)) {
+        console.error(`No documentation folder at ${docsRoot}. Run coverage inside the pasika repository.`);
+        process.exit(1);
+    }
+    const registryPath = path.join(root, REGISTRY_RELATIVE_PATH);
+    if (options.classify !== undefined) {
+        const kind = enforcementKindSchema.safeParse(options.kind);
+        if (!kind.success) {
+            console.error(`✗ --kind must be one of ${enforcementKindSchema.options.join(", ")}.`);
+            process.exit(1);
+        }
+        try {
+            const result = classifyRequirement({
+                docsRoot,
+                registry: readRegistry(registryPath),
+                input: { hash: options.classify, kind: kind.data, ref: options.ref, note: options.note },
+            });
+            writeRegistry(registryPath, result.registry);
+            const change = result.previousKind === undefined
+                ? `recorded as ${result.requirement.kind}`
+                : `reclassified from ${result.previousKind} to ${result.requirement.kind}`;
+            console.log(`✓ ${change}: ${result.requirement.text}`);
+        }
+        catch (error) {
+            console.error(`✗ ${error instanceof Error ? error.message : String(error)}`);
+            process.exit(1);
+        }
+    }
+    const report = buildCoverageReport({
+        docsRoot,
+        registry: readRegistry(registryPath),
+        rulesDir: path.join(root, "eslint", "pasika", "rules"),
+    });
+    if (options.json) {
+        console.log(JSON.stringify(report, undefined, 2));
+        process.exit(report.issues.length > 0 ? 1 : 0);
+    }
+    for (const issue of report.issues) {
+        const where = issue.line === undefined ? issue.doc : `${issue.doc}:${String(issue.line)}`;
+        console.log(`  ✗ ${ISSUE_LABELS[issue.kind]} ${truncate(issue.text, 76)}`);
+        console.log(`              ${where}${issue.detail ? `\n              ${issue.detail}` : ""}`);
+    }
+    const { counts } = report;
+    console.log([
+        "",
+        `${String(report.total)} requirements · ${String(report.mechanical)} mechanically enforced`,
+        `  eslint ${String(counts.eslint)} · doctor ${String(counts.doctor)} · docs-check ${String(counts["docs-check"])}`,
+        `  planned ${String(counts.planned)} · judgment ${String(counts.judgment)} · permission ${String(counts.permission)}`,
+        `  unclassified ${String(report.issues.filter((issue) => issue.kind === "new").length)}`,
+    ].join("\n"));
+    if (options.accept) {
+        writeRegistry(registryPath, report.nextRegistry);
+        const accepted = report.issues.filter((issue) => issue.kind === "changed" || issue.kind === "removed");
+        console.log(`\nAccepted ${String(accepted.length)} change(s) into ${REGISTRY_RELATIVE_PATH}.`);
+        console.log("Requirements reported as new still need a classification.");
+        process.exit(report.issues.some((issue) => issue.kind === "new") ? 1 : 0);
+    }
+    process.exit(report.issues.length > 0 ? 1 : 0);
+});
+program.parse();

package/dist/enforcement/coverage.d.ts

@@ -0,0 +1,51 @@
+import { type EnforcementKind, type Registry, type Requirement } from "./types.js";
+export interface CoverageIssue {
+    kind: "new" | "changed" | "removed" | "unknown-ref" | "missing-test";
+    doc: string;
+    line?: number;
+    text: string;
+    /** Hash of the requirement as it reads now, so a new entry can be recorded without recomputing it. */
+    hash?: string;
+    detail?: string;
+}
+export interface CoverageReport {
+    counts: Record<EnforcementKind, number>;
+    total: number;
+    mechanical: number;
+    issues: CoverageIssue[];
+    /** Registry updated for `--accept`: reworded requirements rehashed, removed ones dropped. */
+    nextRegistry: Registry;
+}
+export declare function buildCoverageReport(options: {
+    docsRoot: string;
+    registry: Registry;
+    rulesDir: string;
+}): CoverageReport;
+export interface ClassifyInput {
+    /** Hash of the requirement, as `coverage` prints it. */
+    hash: string;
+    kind: EnforcementKind;
+    ref?: string;
+    note?: string;
+}
+export interface ClassifyResult {
+    registry: Registry;
+    requirement: Requirement;
+    /** The kind this requirement carried before, when it was already classified. */
+    previousKind?: EnforcementKind;
+}
+/**
+ * Records how a requirement is checked.
+ *
+ * Validates that the requirement exists in the documentation as written, that a
+ * ref names a check that exists, and that the kinds which are meaningless
+ * without an explanation carry one. Throws with a readable message otherwise, so
+ * the caller can print it and exit.
+ */
+export declare function classifyRequirement(options: {
+    docsRoot: string;
+    registry: Registry;
+    input: ClassifyInput;
+}): ClassifyResult;
+export declare function readRegistry(registryPath: string): Registry;
+export declare function writeRegistry(registryPath: string, registry: Registry): void;

package/dist/enforcement/coverage.js

@@ -0,0 +1,210 @@
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { pasikaRuleIds } from "../eslint/pasika/index.js";
+import { DOCS_CHECKS } from "./docs-check.js";
+import { parseDocs } from "./parse-docs.js";
+import { MECHANICAL_KINDS, registrySchema } from "./types.js";
+/** Ratio of shared words, used only to guess which stored requirement a reworded bullet came from. */
+function similarity(left, right) {
+    const leftWords = new Set(left.toLowerCase().split(/\W+/).filter(Boolean));
+    const rightWords = new Set(right.toLowerCase().split(/\W+/).filter(Boolean));
+    const shared = [...leftWords].filter((word) => rightWords.has(word)).length;
+    const union = new Set([...leftWords, ...rightWords]).size;
+    return union === 0 ? 0 : shared / union;
+}
+/** Titles passed to `describe` or `test` in the rule test files. */
+function collectTestTitles(rulesDir) {
+    const titles = new Set();
+    for (const entry of readdirSync(rulesDir)) {
+        if (!entry.endsWith(".test.ts"))
+            continue;
+        const body = readFileSync(path.join(rulesDir, entry), "utf8");
+        for (const match of body.matchAll(/\b(?:describe|test|it)\(\s*"(?<title>(?:[^"\\]|\\.)*)"/g)) {
+            titles.add((match.groups?.title ?? "").replaceAll('\\"', '"'));
+        }
+    }
+    return titles;
+}
+/** A requirement several checks cover lists them comma-separated. */
+function refParts(ref) {
+    return (ref ?? "")
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean);
+}
+function isRefKnown(requirement, docsChecks) {
+    const parts = refParts(requirement.ref);
+    if (requirement.kind === "eslint")
+        return parts.length > 0 && parts.every((part) => pasikaRuleIds.includes(part));
+    if (requirement.kind === "docs-check")
+        return parts.length > 0 && parts.every((part) => docsChecks.has(part));
+    // Doctor checks do not exist yet, so a `doctor` entry is a forward reference.
+    return true;
+}
+export function buildCoverageReport(options) {
+    const { docsRoot, registry, rulesDir } = options;
+    const docs = parseDocs(docsRoot);
+    const docsChecks = new Set(DOCS_CHECKS);
+    const testTitles = collectTestTitles(rulesDir);
+    const byHash = new Map(registry.requirements.map((requirement) => [requirement.hash, requirement]));
+    const matched = new Set();
+    const issues = [];
+    const counts = {
+        eslint: 0,
+        doctor: 0,
+        "docs-check": 0,
+        judgment: 0,
+        permission: 0,
+        planned: 0,
+    };
+    const nextRequirements = [];
+    const parsed = docs.flatMap((doc) => doc.requirements.map((requirement) => ({ doc: doc.doc, requirement })));
+    for (const { doc, requirement } of parsed) {
+        const recorded = byHash.get(requirement.hash);
+        if (recorded) {
+            matched.add(requirement.hash);
+            counts[recorded.kind] += 1;
+            nextRequirements.push({ ...recorded, doc });
+            if (!isRefKnown(recorded, docsChecks)) {
+                issues.push({
+                    kind: "unknown-ref",
+                    doc,
+                    line: requirement.line,
+                    text: requirement.text,
+                    detail: `${recorded.kind} ref "${recorded.ref ?? "(none)"}" does not exist`,
+                });
+            }
+            if (recorded.kind === "eslint" && !testTitles.has(requirement.text)) {
+                issues.push({
+                    kind: "missing-test",
+                    doc,
+                    line: requirement.line,
+                    text: requirement.text,
+                    detail: `no rule test is titled with this requirement`,
+                });
+            }
+            continue;
+        }
+        // Not recorded under this hash: either a reworded requirement or a new one.
+        const candidate = registry.requirements
+            .filter((entry) => entry.doc === doc && !matched.has(entry.hash))
+            .map((entry) => ({ entry, score: similarity(entry.text, requirement.text) }))
+            .sort((left, right) => right.score - left.score)
+            .find(({ score }) => score >= 0.5);
+        if (candidate) {
+            matched.add(candidate.entry.hash);
+            counts[candidate.entry.kind] += 1;
+            nextRequirements.push({ ...candidate.entry, doc, text: requirement.text, hash: requirement.hash });
+            issues.push({
+                kind: "changed",
+                doc,
+                line: requirement.line,
+                text: requirement.text,
+                hash: requirement.hash,
+                detail: `was "${candidate.entry.text}" — re-verify ${candidate.entry.kind}${candidate.entry.ref ? ` ${candidate.entry.ref}` : ""}`,
+            });
+        }
+        else {
+            issues.push({ kind: "new", doc, line: requirement.line, text: requirement.text, hash: requirement.hash });
+        }
+    }
+    for (const entry of registry.requirements) {
+        if (matched.has(entry.hash))
+            continue;
+        issues.push({
+            kind: "removed",
+            doc: entry.doc,
+            text: entry.text,
+            detail: `recorded as ${entry.kind}${entry.ref ? ` ${entry.ref}` : ""} but the bullet is gone`,
+        });
+    }
+    const total = parsed.length;
+    let mechanical = 0;
+    for (const kind of MECHANICAL_KINDS)
+        mechanical += counts[kind];
+    return {
+        counts,
+        total,
+        mechanical,
+        issues,
+        nextRegistry: { requirements: nextRequirements },
+    };
+}
+/**
+ * Records how a requirement is checked.
+ *
+ * Validates that the requirement exists in the documentation as written, that a
+ * ref names a check that exists, and that the kinds which are meaningless
+ * without an explanation carry one. Throws with a readable message otherwise, so
+ * the caller can print it and exit.
+ */
+export function classifyRequirement(options) {
+    const { docsRoot, registry, input } = options;
+    const parsed = parseDocs(docsRoot).flatMap((doc) => doc.requirements.map((requirement) => ({ doc: doc.doc, requirement })));
+    const match = parsed.find((entry) => entry.requirement.hash === input.hash);
+    if (!match) {
+        throw new Error(`No requirement in the documentation has hash "${input.hash}". Run coverage to list them.`);
+    }
+    const refs = refParts(input.ref);
+    if (input.kind === "eslint") {
+        if (refs.length === 0)
+            throw new Error('Kind "eslint" needs --ref naming the rule that reports it.');
+        const unknown = refs.filter((ref) => !pasikaRuleIds.includes(ref));
+        if (unknown.length > 0) {
+            throw new Error(`--ref ${unknown.map((ref) => `"${ref}"`).join(", ")} is not a rule in the plugin.`);
+        }
+    }
+    else if (input.kind === "docs-check") {
+        if (refs.length === 0)
+            throw new Error('Kind "docs-check" needs --ref naming the check that reports it.');
+        const known = new Set(DOCS_CHECKS);
+        const unknown = refs.filter((ref) => !known.has(ref));
+        if (unknown.length > 0) {
+            throw new Error(`--ref ${unknown.map((ref) => `"${ref}"`).join(", ")} is not a documentation check.`);
+        }
+    }
+    else if (input.kind !== "doctor" && refs.length > 0) {
+        throw new Error(`Kind "${input.kind}" takes no --ref, because nothing reports it.`);
+    }
+    if ((input.kind === "judgment" || input.kind === "planned") && (input.note ?? "").trim() === "") {
+        const reason = input.kind === "judgment" ? "why no check can decide it" : "the check that should cover it";
+        throw new Error(`Kind "${input.kind}" needs --note naming ${reason}.`);
+    }
+    const requirement = {
+        doc: match.doc,
+        text: match.requirement.text,
+        hash: match.requirement.hash,
+        kind: input.kind,
+        ...(refs.length > 0 ? { ref: refs.join(", ") } : {}),
+        ...((input.note ?? "").trim() === "" ? {} : { note: input.note?.trim() }),
+    };
+    const existing = registry.requirements.find((entry) => entry.hash === input.hash);
+    const requirements = registry.requirements.filter((entry) => entry.hash !== input.hash);
+    requirements.push(requirement);
+    return { registry: { requirements }, requirement, previousKind: existing?.kind };
+}
+export function readRegistry(registryPath) {
+    const parsed = JSON.parse(readFileSync(registryPath, "utf8"));
+    const result = registrySchema.safeParse(parsed);
+    if (!result.success) {
+        throw new Error(`${registryPath} is not a valid enforcement registry:\n${z.prettifyError(result.error)}`);
+    }
+    return result.data;
+}
+/**
+ * Code-point order on doc then text. Deliberately not `localeCompare`, whose
+ * result depends on the host's locale data — a generated file that is committed
+ * has to sort the same way everywhere.
+ */
+function compareRequirements(left, right) {
+    if (left.doc !== right.doc)
+        return left.doc < right.doc ? -1 : 1;
+    if (left.text !== right.text)
+        return left.text < right.text ? -1 : 1;
+    return 0;
+}
+export function writeRegistry(registryPath, registry) {
+    const sorted = { requirements: [...registry.requirements].sort(compareRequirements) };
+    writeFileSync(registryPath, `${JSON.stringify(sorted, null, 2)}\n`);
+}

package/dist/enforcement/docs-check.d.ts

@@ -0,0 +1,17 @@
+import { type ParsedDoc } from "./parse-docs.js";
+/**
+ * Identifiers of the documentation checks. The enforcement registry points at
+ * these, so renaming one is a change the registry has to follow.
+ */
+export declare const DOCS_CHECKS: readonly ["doc-kind-suffix", "title-matches-file-name", "overview-present", "overview-length", "guide-overview-no-links", "guide-step-single-sentence", "guide-step-single-link", "guide-states-no-requirement", "guide-folder-entry-point", "requirement-present", "rule-paired-examples", "example-heading-description", "policy-no-examples", "policy-single-document", "no-cross-document-link", "reference-no-rfc-vocabulary", "reference-block-headings", "support-document-placement", "no-template-prompt"];
+export type DocsCheck = (typeof DOCS_CHECKS)[number];
+export interface DocsFinding {
+    doc: string;
+    line: number;
+    check: DocsCheck;
+    message: string;
+}
+export declare function checkDocs(docsRoot: string): {
+    docs: ParsedDoc[];
+    findings: DocsFinding[];
+};