@open-agent-toolkit/cli 0.3.26 → 0.3.28

package/assets/templates/docs-app-mkdocs/docs/contributing.md

@@ -1,29 +1,125 @@
+---
+title: Contributing
+description: 'Authoring contract, generated files, supported syntax and validation.'
+---
+
 # Contributing to {{SITE_NAME}}
 
-Documentation should ship with the code it explains. This docs app is scaffolded to give contributors and agents a shared contract for navigation, Markdown features, and local tooling.
+Ship documentation with the behavior it explains. Use the [docs toolchain guide](contributing/docs-toolchain.md) for setup and validation and [contributor guides](contributing/index.md) as the local map.
+
+Agent working rules: `../AGENTS.md` (app-root source file).
+
+## Authored and generated files
+
+| Surface                                              | Owner and action                                                          |
+| ---------------------------------------------------- | ------------------------------------------------------------------------- |
+| `docs/**/*.md`, including `docs/**/index.md`         | Authored source; edit purpose and Contents maps directly.                 |
+| `AGENTS.md` and this contributor guide               | Authored working rules and human guidance; keep their audiences separate. |
+| `mkdocs.yml` outside `nav:`                          | Authored framework configuration.                                         |
+| `mkdocs.yml` `nav:`                                  | Committed derived sidebar; regenerate with nav sync.                      |
+| `site/`                                              | Generated site output; do not edit.                                       |
+| `requirements.txt`, `setup-docs.sh`, package scripts | Authored toolchain; changing pins needs an explicit tooling review.       |
+
+MkDocs 1.4.2 has no configurable rendering exclusion: non-reader pages leave nav/manifest but still render as routes. Do not promise private draft routes or add an exclusion plugin as an implicit repair.
+
+This MkDocs/Material scaffold is **legacy**. [Material's upstream changelog](https://squidfunk.github.io/mkdocs-material/changelog/) states that it is in maintenance mode, with critical bug fixes and security updates through **May 5, 2027**, then upstream maintenance ends. The team identifies [Zensical](https://zensical.org/) as its maintained successor. This date applies to Material, not MkDocs core. Existing Python pins remain unchanged; the maintenance statement does not promise backports to these exact old pins. Plan an explicit tooling review before adopting this path for a new site.
 
 ## Navigation contract
 
-- Every documentation directory must contain an `index.md`.
-- Each `index.md` must include a `## Contents` section.
-- The `## Contents` section is the machine-readable local map for sibling pages and child directories.
-- `overview.md` is deprecated in favor of `index.md`.
+Fresh scaffolds set `use_directory_urls: false` in `mkdocs.yml`. Pages use `.html` URLs: `contributing.md` renders as `contributing.html`, and the local map `contributing/index.md` renders as `contributing/index.html`. Keep both source files and `.md`-suffixed authored links; MkDocs resolves them to the distinct rendered destinations. Changing this setting requires reviewing published URLs and inbound links.
+
+Every content directory has an authored `index.md` with a useful purpose paragraph and one `## Contents` local map. Prefer `.md` pages with nonempty `title` and `description` frontmatter and exactly one document H1. `overview.md` is deprecated.
+
+Within `## Contents`, use dash-only links to sibling pages or child indexes, optionally followed by a description. A `### Label` starts a group and must contain at least one authored entry before the next group/end. Entries before the first group are ungrouped. A `*` or `+` link bullet, or an empty authored group, is an error naming the file and line. The map ends at the next level-two heading; fenced examples are ignored. A self-index link retains the existing landing-page behavior. Optional Markdown inventories keep deterministic fallback when Contents is missing; MkDocs nav sync needs authored maps to construct navigation. The pinned MkDocs build can still render pages absent from its navigation.
+
+```markdown
+## Contents
+
+- [Start here](getting-started.md) - The first safe result.
+
+### Contributor guides
+
+- [Toolchain](contributing/index.md) - Local setup and authoring.
+```
+
+`documentation.navOwner: nav-sync` means nav sync owns derived navigation. With `hand-authored` or undeclared ownership, do not silently regenerate; agree the ownership/change first. Configured `documentation.nonReaderPaths` omits drafts/templates from navigation and manifests; an explicit Contents link does not override an exclusion. `documentation.excludes` affects only the manifest. Do not add an exclusion to hide an unlisted reader page.
+
+## Add, move or rename a page
+
+1. Read the nearest authored map and choose a path in its scope; create a child `index.md` when adding a directory.
+2. Add useful title/description frontmatter, one H1, and the page's reader outcome. Use `.md`-suffixed source links such as `[Guide](guide.md)` and `[Section](section/index.md)`.
+3. Update the nearest Contents map. For a move/rename, update both source and destination maps and every inbound link in the same change. Review old published URLs; agree a redirect or a static stub/recovery page when needed.
+4. Refresh owned navigation, run the checks below and inspect the rendered links/navigation before committing. Never repair drift by hand-editing derived files.
+
+## Supported Markdown features
 
-## Local workflow
+Use the least complex layer that expresses the reader's need: **Markdown → existing transform → MDX**. Ordinary prose stays `.md`. Fumadocs MDX is for actual JSX/component needs; MkDocs does not compile MDX. MDX is excluded from OAT's Markdown manifest and the Fumadocs agent Markdown endpoints.
 
-1. Install Python dependencies:
+Tables, task lists, fenced code, callouts, Mermaid and `=== "Title"` tabs are supported by the configured framework pipeline. Tabs may contain links, GFM and nested tabs in Fumadocs. Use a language on every fence and `bash` for shell commands.
 
-   ```bash
-   pnpm docs:setup
-   ```
+=== "Syntax"
 
-2. Run the live preview:
+    ````text
+    === "Example"
 
-   ```bash
-   pnpm docs:dev
-   ```
+        > [!NOTE]
+        > Read the local map before editing.
 
-3. Run Markdown formatting and linting as configured for this docs app.
+        | Check | Result |
+        | --- | --- |
+        | Reader links | Resolve |
+
+        ```bash
+        cd {{APP_CWD}}
+        pnpm docs:lint
+        ```
+    ````
+
+=== "Rendered"
+
+    === "Example"
+
+        > [!NOTE]
+        > Read the local map before editing.
+
+        | Check | Result |
+        | --- | --- |
+        | Reader links | Resolve |
+
+        ```bash
+        cd {{APP_CWD}}
+        pnpm docs:lint
+        ```
+
+Not configured: arbitrary custom components, executable notebooks, API playgrounds or screenshot testing. Do not describe those as supported without an approved configuration and a working example. Check the actual package scripts: lint is {{LINT_STATUS}} and formatting is {{FORMAT_STATUS}}; disabled scripts only print a message.
+
+## Diagrams and accessibility
+
+Run the app’s docs:check script (from the repository root: `cd {{APP_CWD}} && pnpm docs:check`) before committing. It checks reader metadata/maps/links, navigation, contributor commands and real Mermaid syntax without building the site. Errors fail; warnings prompt review. Fix authored sources, then explicitly sync owned navigation and retry.
+
+Mermaid is the diagram source of truth. Important or phone-sized diagrams also get matching `<name>-light.svg` and `<name>-dark.svg` assets. Change the Mermaid and both SVGs in the same commit, preserving nodes, edges and labels. Each SVG uses `role="img"`, a descriptive `<title>` and `<desc>` (connected with `aria-labelledby`), a legible viewBox and readable labels. Keep image alt text concise, about 155 characters or less, and describe the diagram's meaning without inventing claims.
+
+=== "Syntax"
+
+    ````text
+    === "Mermaid source"
+
+        ```mermaid
+        flowchart LR
+          A[Read local map] --> B[Make a focused edit]
+        ```
+    ````
+
+=== "Rendered"
+
+    ```mermaid
+    flowchart LR
+      accTitle: Documentation edit
+      accDescr: Read the local map before making a focused edit.
+      A[Read local map] --> B[Make a focused edit]
+    ```
+
+Put diagram assets under `docs/assets/diagrams/` and link relative to the source page. Keep both SVG variants with the source; automatic light/dark image selection is not configured in this MkDocs scaffold. Inspect theme contrast manually; do not claim the Fumadocs image/basePath behavior here.
 
 ## Installed plugins
 
@@ -112,9 +208,3 @@ Supports tabbed content blocks for related workflows or platform variants.
 ### `toc`
 
 Adds table-of-contents anchors and permalinks for headings.
-
-## Agent guidance
-
-- Treat `index.md` plus its `## Contents` section as the local discovery source of truth.
-- Prefer linking to source files and commands explicitly when documenting behavior.
-- When adding a new plugin or extension, update this guide with what it does and how to use it.

package/assets/templates/docs-app-mkdocs/docs/getting-started.md

@@ -1,28 +1,10 @@
-# Getting Started
-
-Use this guide to set up your local environment and preview {{SITE_NAME}}.
-
-## Prerequisites
-
-- Node.js 22+
-- pnpm 10+
-- Python 3.11+ for MkDocs tooling
+---
+title: Getting Started
+description: 'Reach the first safe reader result with {{SITE_NAME}}.'
+---
 
-## Install documentation tooling
-
-```bash
-pnpm docs:setup
-```
-
-## Run the docs locally
-
-```bash
-pnpm docs:dev
-```
+# Getting Started
 
-## Editing workflow
+Start with the [documentation map](index.md), choose the guide for your task, and confirm its prerequisites before changing anything. Your first safe result is to identify the right procedure and its expected outcome.
 
-1. Update Markdown files under `docs/`.
-2. Check the preview site for formatting and navigation.
-3. Run the formatter and linter before committing.
-4. Keep every directory discoverable through its `index.md` file.
+Replace this starter paragraph with one concrete, low-risk reader task for your product: the input, the command or action, and the result the reader can verify. Keep contributor setup in the [docs toolchain guide](contributing/docs-toolchain.md).

package/assets/templates/docs-app-mkdocs/docs/index.md

@@ -1,8 +1,13 @@
+---
+title: '{{SITE_NAME}}'
+description: '{{PAGE_DESCRIPTION}}'
+---
+
 # {{SITE_NAME}}
 
 Use this site as the central documentation hub for the repository. It is organized to support both human readers and AI agents, with every directory exposing an `index.md` entrypoint.
 
 ## Contents
 
-- [Getting Started](getting-started.md) - Set up the local docs toolchain and preview the site.
-- [Contributing](contributing.md) - Authoring conventions, plugin inventory, and navigation rules.
+- [Getting Started](getting-started.md) - Reach the first safe reader result.
+- [Contributing](contributing/index.md) - Authoring contract and local toolchain setup.

package/assets/templates/docs-app-mkdocs/gitignore.template

@@ -0,0 +1,8 @@
+# Dependencies
+node_modules/
+
+# MkDocs build output
+site/
+
+# Python virtual environment
+.venv/

package/assets/templates/docs-app-mkdocs/mkdocs.yml

@@ -1,5 +1,6 @@
 site_name: {{SITE_NAME}}
 docs_dir: './docs'
+use_directory_urls: false
 
 site_description: {{SITE_NAME}}
 

package/assets/templates/docs-app-mkdocs/package.json.template

@@ -6,12 +6,13 @@
   "description": "MkDocs Material documentation for {{SITE_NAME}}.",
   "scripts": {
     "docs:dev": "mkdocs serve",
-    "docs:build": "{{NAV_SYNC_CHECK_CMD}} && mkdocs build",
+    "docs:build": "{{DOCS_CHECK_CMD}} && {{NAV_SYNC_CHECK_CMD}} && mkdocs build",
     "docs:setup": "sh ./setup-docs.sh",
+    "docs:check": "{{DOCS_CHECK_CMD}}",
     "docs:lint": "{{DOCS_LINT_SCRIPT}}",
     "docs:format": "{{DOCS_FORMAT_SCRIPT}}",
     "docs:format:check": "{{DOCS_FORMAT_CHECK_SCRIPT}}",
-    "test": "echo 'Documentation tests complete'"
+    "test": "{{DOCS_CHECK_CMD}}"
   },
   "devDependencies": {
     "@open-agent-toolkit/cli": "{{OAT_CLI_DEP}}"{{DEV_DEPENDENCIES}}

package/dist/commands/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"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"}

package/dist/commands/config/index.js

@@ -11,6 +11,7 @@ import { compileDispatchCeilingPreset } from '../../config/dispatch-ceiling-pres
 import { normalizeDispatchMatrix, validateDispatchRouteTarget, walkDispatchMatrix, } from '../../config/dispatch-matrix.js';
 import { formatDispatchNotices, terminalReviewerNoticesForMatrix, } from '../../config/dispatch-notices.js';
 import { dispatchPolicyModeDescription, dispatchPolicyPolicyDescription, managedDispatchPolicyValueList, } from '../../config/dispatch-policy-options.js';
+import { normalizeDocumentationCheck } from '../../config/documentation-check.js';
 import { parseJsonConfig } from '../../config/json.js';
 import { DEFAULT_INSTRUCTION_SYNC_STRATEGY, INSTRUCTION_SYNC_STRATEGIES, VALID_DISPATCH_POLICY_MODES, VALID_MANAGED_DISPATCH_POLICIES, MAX_GATE_TIMEOUT_MS, MIN_GATE_TIMEOUT_MS, isValidGateTimeoutMs, isValidProjectLogDigestBound, normalizeWorkflowPostImplementSequence, normalizeDocumentationGuidance, normalizeDocumentationIa, normalizeDocumentationNavOwner, readOatConfig, readOatConfigForDefaultScopeRepair, readOatConfigForDocumentationExcludesRepair, readOatConfigForInstructionPointerExcludesRepair, readOatConfigForInstructionSyncStrategyRepair, readOatConfigWithWarnings, readOatLocalConfig, readUserConfig, writeOatConfig, writeOatLocalConfig, writeUserConfig, VALID_POST_IMPLEMENT_LEGACY_SEQUENCES, } from '../../config/oat-config.js';
 import { getOwnKey, setOwnKey } from '../../config/own-keys.js';
@@ -67,6 +68,7 @@ const KEY_ORDER = [
     'archive.awsRegion',
     'autoReviewAtCheckpoints',
     'lastPausedProject',
+    'documentation.check',
     'documentation.ia',
     'documentation.nonReaderPaths',
     'documentation.navOwner',
@@ -242,6 +244,17 @@ const CONFIG_CATALOG = [
         description: 'Deprecated compatibility alias for workflow.autoReviewAtHillCheckpoints. Prefer `oat config set workflow.autoReviewAtHillCheckpoints <true|false>`.',
         deprecated: { supersededBy: 'workflow.autoReviewAtHillCheckpoints' },
     },
+    {
+        key: 'documentation.check',
+        group: 'Shared Repo (.oat/config.json)',
+        scope: 'shared repo',
+        file: '.oat/config.json',
+        type: 'JSON object',
+        defaultValue: 'null (portable checker defaults)',
+        mutability: 'read/write',
+        owningCommand: 'oat config set documentation.check <JSON>',
+        description: 'Portable docs rule severities, named thresholds, reason-bearing path exceptions, provenance patterns and diagram base ref.',
+    },
     {
         key: 'documentation.ia',
         group: 'Shared Repo (.oat/config.json)',
@@ -1822,6 +1835,7 @@ async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, d
     const effectiveSurface = surface === 'auto' ? defaultSurfaceForKey(key) : surface;
     if (key === 'documentation.nonReaderPaths' ||
         key === 'documentation.guidance' ||
+        key === 'documentation.check' ||
         key === 'documentation.ia' ||
         key === 'documentation.navOwner') {
         const configPath = effectiveSurface === 'user'
@@ -1831,7 +1845,13 @@ async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, d
         const trimmed = rawValue.trim();
         let value;
         try {
-            if (key === 'documentation.nonReaderPaths') {
+            if (key === 'documentation.check') {
+                const parsed = JSON.parse(trimmed);
+                if (parsed === null)
+                    throw new Error('Expected a checker JSON object.');
+                value = normalizeDocumentationCheck(parsed);
+            }
+            else if (key === 'documentation.nonReaderPaths') {
                 const paths = parseDocumentationExcludes(rawValue);
                 value = paths.length > 0 ? paths : undefined;
             }
@@ -1848,8 +1868,10 @@ async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, d
                         : normalizeDocumentationGuidance(trimmed.startsWith('[') ? JSON.parse(trimmed) : trimmed, configPath, effectiveSurface === 'user' ? 'user' : 'shared');
             }
         }
-        catch {
-            throw new Error(`Invalid ${key} value: ${key === 'documentation.ia' ? 'expected IA JSON with preset, repo-relative decision, optional tracks and verification' : key === 'documentation.navOwner' ? 'expected nav-sync or hand-authored' : 'expected a non-empty path/URL string or ordered non-empty string array'}.`);
+        catch (error) {
+            if (key === 'documentation.check')
+                throw error;
+            throw new Error(`Invalid ${key} value: ${key === 'documentation.ia' ? 'expected IA JSON with preset, repo-relative decision, optional tracks and verification' : key === 'documentation.navOwner' ? 'expected nav-sync or hand-authored' : 'expected a non-empty path/URL string or ordered non-empty string array'}.`, { cause: error });
         }
         let raw = { version: 1 };
         try {
@@ -2450,6 +2472,7 @@ async function unsetConfigValue(repoRoot, userConfigDir, key, surface, dependenc
 async function removeFromSurface(repoRoot, userConfigDir, key, effectiveSurface, path, dependencies) {
     if (key === 'documentation.nonReaderPaths' ||
         key === 'documentation.guidance' ||
+        key === 'documentation.check' ||
         key === 'documentation.ia' ||
         key === 'documentation.navOwner') {
         const configPath = effectiveSurface === 'user'
@@ -2577,6 +2600,15 @@ async function removeConfigPathOnDisk(configPath, path) {
     if (!isRecord(parsed)) {
         return null;
     }
+    // Checker null is malformed rather than an inherited unset sentinel.
+    if (path.join('.') === 'documentation.check' &&
+        isRecord(parsed.documentation) &&
+        Object.hasOwn(parsed.documentation, 'check')) {
+        return {
+            ...parsed,
+            documentation: withoutOwnKey(parsed.documentation, 'check'),
+        };
+    }
     const { next, removed } = removeConfigPath(parsed, path);
     return removed ? next : null;
 }

package/dist/commands/docs/check/check.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createDocsCheckCommand(): Command;
+//# sourceMappingURL=check.d.ts.map

package/dist/commands/docs/check/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/check.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,wBAAgB,sBAAsB,IAAI,OAAO,CA4DhD"}

package/dist/commands/docs/check/check.js

@@ -0,0 +1,48 @@
+import { buildCommandContext } from '../../../app/command-context.js';
+import { readGlobalOptions } from '../../shared/shared.utils.js';
+import { Command } from 'commander';
+import { checkDocs } from './checker.js';
+export function createDocsCheckCommand() {
+    return new Command('check')
+        .description('Read-only portable reader, navigation, command and diagram validation')
+        .option('--target-dir <dir>', 'Docs app root or literal Markdown content root')
+        .option('--rule <id...>', 'Run only these stable rule IDs (repeatable)', (values, previous) => previous.concat(values), [])
+        .action(async (options, command) => {
+        const context = buildCommandContext(readGlobalOptions(command));
+        let result;
+        try {
+            result = await checkDocs({
+                cwd: context.cwd,
+                targetDir: options.targetDir,
+                rules: options.rule,
+            });
+            process.exitCode = result.summary.errors ? 1 : 0;
+        }
+        catch (error) {
+            const message = error.message;
+            result = {
+                summary: { errors: 1, warnings: 0 },
+                findings: [
+                    {
+                        ruleId: 'configuration',
+                        severity: 'error',
+                        path: '.oat/config.json',
+                        message,
+                    },
+                ],
+            };
+            // Invalid input/config is actionable. Unexpected filesystem/runtime
+            // failures retain the CLI's separate runtime-error exit convention.
+            process.exitCode = error.code ? 2 : 1;
+        }
+        if (context.json)
+            context.logger.json(result);
+        else {
+            for (const f of result.findings) {
+                const location = `${f.path}${f.line === undefined ? '' : `:${f.line}`}`;
+                context.logger[f.severity === 'error' ? 'error' : 'warn'](`${location} [${f.ruleId}] ${f.message}`);
+            }
+            context.logger.info(`Docs check: ${result.summary.errors} error(s), ${result.summary.warnings} warning(s).`);
+        }
+    });
+}

package/dist/commands/docs/check/check.types.d.ts

@@ -0,0 +1,17 @@
+import type { DocsCheckRule } from '../../../config/documentation-check.js';
+export interface DocsFinding {
+    ruleId: DocsCheckRule | 'configuration';
+    severity: 'error' | 'warn';
+    path: string;
+    line?: number;
+    message: string;
+}
+export interface DocsCheckResult {
+    summary: {
+        errors: number;
+        warnings: number;
+    };
+    findings: DocsFinding[];
+}
+export type Report = (rule: DocsCheckRule, severity: 'error' | 'warn', path: string, message: string, line?: number) => void;
+//# sourceMappingURL=check.types.d.ts.map

package/dist/commands/docs/check/check.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.types.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/check.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,aAAa,GAAG,eAAe,CAAC;IACxC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AACD,MAAM,MAAM,MAAM,GAAG,CACnB,IAAI,EAAE,aAAa,EACnB,QAAQ,EAAE,OAAO,GAAG,MAAM,EAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,KACV,IAAI,CAAC"}

package/dist/commands/docs/check/check.types.js

@@ -0,0 +1 @@
+export {};

package/dist/commands/docs/check/checker.d.ts

@@ -0,0 +1,8 @@
+import type { DocsCheckResult } from './check.types.js';
+/** Read-only portable checker. Output paths are content-root-relative POSIX. */
+export declare function checkDocs(options: {
+    cwd: string;
+    targetDir?: string;
+    rules?: string[];
+}): Promise<DocsCheckResult>;
+//# sourceMappingURL=checker.d.ts.map

package/dist/commands/docs/check/checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checker.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/checker.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAuB,MAAM,eAAe,CAAC;AAQ1E,gFAAgF;AAChF,wBAAsB,SAAS,CAAC,OAAO,EAAE;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,OAAO,CAAC,eAAe,CAAC,CAwF3B"}

package/dist/commands/docs/check/checker.js

@@ -0,0 +1,82 @@
+import { createExclusionMatcher, isExcludedPath, } from '../../docs/shared/exclusions.js';
+import { DOCS_CHECK_RULES, } from '../../../config/documentation-check.js';
+import { checkCommands } from './commands.js';
+import { checkDiagrams } from './diagrams.js';
+import { readPage, readerFiles, resolveCheckTarget } from './files.js';
+import { checkNavigation } from './navigation.js';
+import { checkProvenance, checkReaders } from './reader-rules.js';
+/** Read-only portable checker. Output paths are content-root-relative POSIX. */
+export async function checkDocs(options) {
+    const unknown = options.rules?.find((rule) => !DOCS_CHECK_RULES.includes(rule));
+    if (unknown)
+        throw new Error(`Unknown docs check rule "${unknown}". Choose: ${DOCS_CHECK_RULES.join(', ')}.`);
+    const target = await resolveCheckTarget(options.cwd, options.targetDir);
+    const policy = target.documentation.check;
+    const findings = [];
+    const exceptions = policy?.exceptions?.map((e) => ({
+        ...e,
+        matcher: createExclusionMatcher([e.path]),
+    })) ?? [];
+    const report = (ruleId, defaultSeverity, path, message, line) => {
+        if (options.rules?.length && !options.rules.includes(ruleId))
+            return;
+        let severity = policy?.rules?.[ruleId] ?? defaultSeverity;
+        for (const e of exceptions)
+            if (e.rule === ruleId && isExcludedPath(e.matcher, path))
+                severity = e.severity ?? 'off';
+        if (severity === 'off')
+            return;
+        findings.push({
+            ruleId,
+            severity,
+            path,
+            ...(line === undefined ? {} : { line }),
+            message,
+        });
+    };
+    const pages = [];
+    for (const path of await readerFiles(target)) {
+        try {
+            const page = await readPage(target, path);
+            pages.push(page);
+            if (page.frontmatterError)
+                report('frontmatter', 'error', path, page.frontmatterError, 1);
+        }
+        catch (error) {
+            const code = error?.code;
+            const safeCode = typeof code === 'string' && /^[A-Z][A-Z0-9_]*$/.test(code)
+                ? code
+                : 'UNKNOWN';
+            report('frontmatter', 'error', path, `Cannot read documentation source (${safeCode}); check file permissions and readability.`, 1);
+        }
+    }
+    await checkReaders(target, pages, report);
+    checkProvenance(target, pages, report);
+    if (!options.rules?.length || options.rules.includes('navigation'))
+        await checkNavigation(target, report);
+    if (!options.rules?.length || options.rules.includes('commands'))
+        await checkCommands(target, pages, report);
+    if (!options.rules?.length ||
+        options.rules.some((r) => [
+            'mermaid',
+            'diagram-accessibility',
+            'diagram-pairs',
+            'diagram-freshness',
+            'image-alt',
+        ].includes(r)))
+        await checkDiagrams(target, pages, report);
+    findings.sort((a, b) => a.path < b.path
+        ? -1
+        : a.path > b.path
+            ? 1
+            : (a.line ?? 0) - (b.line ?? 0) ||
+                a.ruleId.localeCompare(b.ruleId) ||
+                a.message.localeCompare(b.message));
+    return {
+        summary: {
+            errors: findings.filter((f) => f.severity === 'error').length,
+            warnings: findings.filter((f) => f.severity === 'warn').length,
+        },
+        findings,
+    };
+}

package/dist/commands/docs/check/commands.d.ts

@@ -0,0 +1,5 @@
+import type { Report } from './check.types.js';
+import { type CheckTarget } from './files.js';
+import type { ParsedPage } from './markdown.js';
+export declare function checkCommands(target: CheckTarget, pages: ParsedPage[], report: Report): Promise<void>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands/docs/check/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/commands.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAA0B,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAgI7C,wBAAsB,aAAa,CACjC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAyJf"}