@open-agent-toolkit/cli 0.3.26 → 0.3.28

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

@@ -0,0 +1,232 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { createExclusionMatcher } from '../../docs/shared/exclusions.js';
+import YAML from 'yaml';
+import { inside, posix, present } from './files.js';
+const BUILTINS = new Set([
+    'add',
+    'install',
+    'i',
+    'exec',
+    'dlx',
+    'remove',
+    'rm',
+    'uninstall',
+    'update',
+    'up',
+    'outdated',
+    'list',
+    'ls',
+    'why',
+    'link',
+    'unlink',
+    'import',
+    'rebuild',
+    'prune',
+    'fetch',
+    'store',
+    'config',
+    'setup',
+    'env',
+    'help',
+    'init',
+    'create',
+    'publish',
+    'pack',
+    'audit',
+    'licenses',
+    'patch',
+    'patch-commit',
+    'patch-remove',
+    'deploy',
+    'dedupe',
+    'approve-builds',
+    'ignored-builds',
+    'server',
+    'self-update',
+    'root',
+    'bin',
+    'version',
+]);
+const illustrative = (value) => /[<$`{}]|\.\.\./.test(value);
+function tokens(source) {
+    return (source.match(/"(?:\\.|[^"\\])*"|'[^']*'|[^\s]+/g) ?? []).map((t) => /^['"]/.test(t) ? t.slice(1, -1) : t);
+}
+async function packages(target) {
+    let patterns = [];
+    if (await present(join(target.repoRoot, 'pnpm-workspace.yaml'))) {
+        const config = YAML.parse(await readFile(join(target.repoRoot, 'pnpm-workspace.yaml'), 'utf8'));
+        patterns = config.packages?.filter((p) => !p.startsWith('!')) ?? [];
+    }
+    const match = createExclusionMatcher(patterns);
+    // A proper pattern prefix can still contain a member below it. A globstar
+    // prefix remains open at every depth. Reuse the membership matcher.
+    const descend = createExclusionMatcher(patterns.flatMap((pattern) => {
+        const parts = pattern.trim().replace(/\/+$/, '').split('/');
+        return parts.flatMap((part, index) => index < parts.length - 1 || part === '**'
+            ? [parts.slice(0, index + 1).join('/')]
+            : []);
+    }));
+    const excluded = createExclusionMatcher((await present(join(target.repoRoot, 'pnpm-workspace.yaml')))
+        ? (YAML.parse(await readFile(join(target.repoRoot, 'pnpm-workspace.yaml'), 'utf8')).packages ?? [])
+            .filter((p) => p.startsWith('!'))
+            .map((p) => p.slice(1))
+        : []);
+    const result = [];
+    const add = async (root) => {
+        if (!(await present(join(root, 'package.json'))))
+            return;
+        const p = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+        result.push({ root, name: p.name, scripts: p.scripts });
+    };
+    await add(target.repoRoot);
+    if (target.appRoot !== target.repoRoot)
+        await add(target.appRoot);
+    if (patterns.length) {
+        const walk = async (root) => {
+            for (const e of await readdir(root, { withFileTypes: true })) {
+                if (!e.isDirectory() ||
+                    e.name.startsWith('.') ||
+                    e.name === 'node_modules')
+                    continue;
+                const dir = join(root, e.name);
+                const rel = posix(relative(target.repoRoot, dir));
+                if (excluded.excludesDirectory(rel))
+                    continue;
+                if (match.excludesDirectory(rel)) {
+                    if (!result.some((p) => p.root === dir))
+                        await add(dir);
+                }
+                // Package patterns, rather than arbitrary repo fixtures, define scope.
+                if (descend.excludesDirectory(rel))
+                    await walk(dir);
+            }
+        };
+        await walk(target.repoRoot);
+    }
+    return result;
+}
+export async function checkCommands(target, pages, report) {
+    const docs = pages.filter((p) => /(?:^|\/)contributing(?:\.mdx?$|\/)/.test(p.path));
+    if (!docs.length)
+        return;
+    const manifests = await packages(target);
+    for (const p of docs)
+        for (const node of p.nodes) {
+            if (node.type !== 'code' && node.type !== 'inlineCode')
+                continue;
+            if (node.type === 'code' &&
+                node.lang &&
+                !['sh', 'shell', 'bash', 'zsh', 'console', 'powershell'].includes(node.lang))
+                continue;
+            let cwd = target.repoRoot;
+            const start = node.position?.start;
+            const openingLine = p.source.split(/\r?\n/).at((start?.line ?? 1) - 1) ?? '';
+            const fenced = node.type === 'code' &&
+                /^(?:`{3,}|~{3,})/.test(openingLine.slice((start?.column ?? 1) - 1));
+            for (const [lineIndex, original] of (node.value ?? '')
+                .split('\n')
+                .entries()) {
+                const line = (node.position?.start.line ?? 1) + lineIndex + (fenced ? 1 : 0);
+                // Split shell command boundaries while retaining quoted arguments. No
+                // subprocess is executed, and placeholders are never guessed.
+                const segments = original.match(/(?:"(?:\\.|[^"\\])*"|'[^']*'|[^;&\n])+/g) ?? [];
+                for (let segment of segments) {
+                    segment = segment.replace(/^\s*\$\s+/, '').trim();
+                    if (!segment || segment.startsWith('#'))
+                        continue;
+                    const words = tokens(segment);
+                    if (words[0] === 'cd') {
+                        cwd =
+                            words[1] && !illustrative(words[1]) && cwd
+                                ? resolve(cwd, words[1])
+                                : undefined;
+                        continue;
+                    }
+                    const manager = words.findIndex((w) => w === 'pnpm' || w === 'npm');
+                    if (manager < 0)
+                        continue;
+                    const kind = words[manager];
+                    let root = cwd;
+                    let filter;
+                    let index = manager + 1;
+                    while (words[index]?.startsWith('-')) {
+                        const option = words[index++];
+                        if (['-w', '--workspace-root'].includes(option))
+                            root = target.repoRoot;
+                        else if (option === '--filter' || option === '-F')
+                            filter = words[index++];
+                        else if (option.startsWith('--filter='))
+                            filter = option.slice(9);
+                        else if (['--dir', '-C', '--prefix'].includes(option)) {
+                            const dir = words[index++];
+                            root =
+                                root && dir && !illustrative(dir)
+                                    ? resolve(root, dir)
+                                    : undefined;
+                        }
+                        else if (['-r', '--recursive', '--workspace'].includes(option))
+                            root = undefined;
+                    }
+                    let script = words[index];
+                    if (!script)
+                        continue;
+                    if (kind === 'npm' &&
+                        script !== 'run' &&
+                        script !== 'run-script' &&
+                        script !== 'test' &&
+                        script !== 'start')
+                        continue;
+                    const explicitRun = script === 'run' || script === 'run-script';
+                    if (explicitRun) {
+                        index++;
+                        while (words[index]?.startsWith('-'))
+                            index++;
+                        script = words[index];
+                    }
+                    else if (BUILTINS.has(script))
+                        continue;
+                    if (!script ||
+                        illustrative(script) ||
+                        (filter && illustrative(filter)))
+                        continue;
+                    let pkg;
+                    if (filter) {
+                        const selected = manifests.filter((item) => item.name === filter ||
+                            (filter.startsWith('./') &&
+                                posix(relative(target.repoRoot, item.root)) ===
+                                    filter.slice(2)));
+                        if (selected.length === 1)
+                            pkg = selected[0];
+                    }
+                    else if (root &&
+                        inside(target.repoRoot, root) &&
+                        (await present(root))) {
+                        let current = root;
+                        while (inside(target.repoRoot, current)) {
+                            pkg = manifests.find((item) => item.root === current);
+                            if (pkg || current === target.repoRoot)
+                                break;
+                            current = dirname(current);
+                        }
+                    }
+                    if (!pkg)
+                        report('commands', 'error', p.path, `Cannot resolve package context for ${kind} ${script}${filter ? ` (--filter ${filter})` : ''}; use literal cd, -w or --filter.`, line);
+                    else if (!Object.hasOwn(pkg.scripts ?? {}, script)) {
+                        // pnpm shorthand can invoke an installed local binary. Explicit run
+                        // remains script-only; never execute a binary or search system PATH.
+                        const installedBinary = kind === 'pnpm' &&
+                            !explicitRun &&
+                            !/[\\/]/.test(script) &&
+                            script !== '.' &&
+                            script !== '..' &&
+                            (await Promise.all([pkg.root, target.repoRoot].map((binRoot) => present(join(binRoot, 'node_modules/.bin', script))))).some(Boolean);
+                        if (!installedBinary)
+                            report('commands', 'error', p.path, `Script "${script}" does not exist in ${posix(relative(target.repoRoot, join(pkg.root, 'package.json'))) || 'package.json'}.`, line);
+                    }
+                    else if (/^\s*echo(?:\s|$)/.test(pkg.scripts[script]))
+                        report('commands', 'warn', p.path, `Script "${script}" is an echo stub in ${posix(relative(target.repoRoot, join(pkg.root, 'package.json')))}.`, line);
+                }
+            }
+        }
+}

package/dist/commands/docs/check/diagrams.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 checkDiagrams(target: CheckTarget, pages: ParsedPage[], report: Report): Promise<void>;
+//# sourceMappingURL=diagrams.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"diagrams.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/diagrams.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAKL,KAAK,WAAW,EACjB,MAAM,SAAS,CAAC;AACjB,OAAO,EAKL,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AAsEpB,wBAAsB,aAAa,CACjC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CA2Of"}

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

@@ -0,0 +1,197 @@
+import { execFile } from 'node:child_process';
+import { readFile, readdir } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { DOCS_CHECK_THRESHOLDS } from '../../../config/documentation-check.js';
+import { containedFile, inside, posix, present, } from './files.js';
+import { attributes, htmlNodes, parsePage, } from './markdown.js';
+import { parseMermaid } from './mermaid-runtime.js';
+const exec = promisify(execFile);
+async function git(target, args) {
+    return (await exec('git', ['-C', target.repoRoot, ...args], {
+        maxBuffer: 16 * 1024 * 1024,
+    })).stdout;
+}
+function sourceDiagrams(page) {
+    return page.nodes.filter((n) => n.type === 'code' && n.lang?.toLowerCase() === 'mermaid');
+}
+function imageFile(target, page, href) {
+    if (/^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(href))
+        return undefined;
+    let decoded;
+    try {
+        decoded = decodeURIComponent(href.split(/[?#]/)[0]);
+    }
+    catch {
+        return undefined;
+    }
+    const root = decoded.startsWith('/')
+        ? join(target.appRoot, 'public')
+        : target.contentRoot;
+    const path = decoded.startsWith('/')
+        ? resolve(root, `.${decoded}`)
+        : resolve(target.contentRoot, dirname(page.path), decoded);
+    return inside(root, path) ? { root, path } : undefined;
+}
+function diagramSection(page, node, tabsOnly = true) {
+    const line = node.position?.start.line ?? 1;
+    const tabs = page.nodes
+        .filter((n) => n.name === 'Tabs' &&
+        (n.position?.start.line ?? Infinity) <= line &&
+        (n.position?.end.line ?? 0) >= line)
+        .at(-1);
+    if (tabsOnly && tabs?.position)
+        return { start: tabs.position.start.line, end: tabs.position.end.line + 1 };
+    // The containing authored section (and nested tab group) owns association;
+    // diagrams in another heading never satisfy this diagram's pair contract.
+    const headings = page.nodes.filter((n) => n.type === 'heading' && (n.depth ?? 7) <= 3);
+    const before = headings
+        .filter((n) => (n.position?.start.line ?? 1) < line)
+        .at(-1);
+    const after = headings.find((n) => (n.position?.start.line ?? 1) > line &&
+        (n.depth ?? 7) <= (before?.depth ?? 3));
+    return {
+        start: before?.position?.start.line ?? 1,
+        end: after?.position?.start.line ?? Infinity,
+    };
+}
+export async function checkDiagrams(target, pages, report) {
+    const altMax = target.documentation.check?.thresholds?.altMax ??
+        DOCS_CHECK_THRESHOLDS.altMax;
+    const assets = new Map();
+    const associations = [];
+    for (const page of pages) {
+        for (const image of page.links.filter((l) => l.image)) {
+            const alt = image.alt?.trim() ?? '';
+            const slug = basename(image.href)
+                .replace(/\.[^.]+$/, '')
+                .replace(/[-_]/g, ' ')
+                .toLowerCase();
+            if (!alt ||
+                alt.length > altMax ||
+                !/\s/.test(alt) ||
+                alt.toLowerCase().replace(/[-_]/g, ' ') === slug)
+                report('image-alt', 'warn', page.path, `Image alt text is empty, filename/slug-like or longer than ${altMax} characters.`, image.line);
+            const asset = imageFile(target, page, image.href);
+            if (!asset || !/\.svg$/i.test(asset.path))
+                continue;
+            if (/(?:^|[\\/])diagrams[\\/]/.test(asset.path) ||
+                /-(light|dark)\.svg$/.test(asset.path))
+                assets.set(asset.path, asset);
+            if (/-(light|dark)\.svg$/.test(asset.path)) {
+                const other = asset.path.replace(/-(light|dark)\.svg$/, (_, theme) => `-${theme === 'light' ? 'dark' : 'light'}.svg`);
+                const referenced = page.links.some((l) => l.image && imageFile(target, page, l.href)?.path === other);
+                if (!referenced)
+                    report('diagram-pairs', 'error', page.path, `Diagram must reference both light and dark SVGs: ${basename(asset.path)}.`, image.line);
+            }
+            const section = diagramSection(page, {
+                type: 'image',
+                position: {
+                    start: { line: image.line, column: 1 },
+                    end: { line: image.line, column: 1 },
+                },
+            }, false);
+            const description = page.nodes.some((n) => n.type === 'paragraph' &&
+                (n.position?.start.line ?? 0) >= section.start &&
+                (n.position?.end.line ?? Infinity) < section.end &&
+                n.children?.some((c) => c.type === 'text' && c.value?.trim()));
+            const associated = image.describedBy
+                ?.split(/\s+/)
+                .some((id) => page.anchors.has(id));
+            if (assets.has(asset.path) && !description && !associated)
+                report('diagram-accessibility', 'warn', page.path, 'Rendered diagram needs page-visible explanatory text or an associated HTML long description; SVG desc alone is insufficient.', image.line);
+        }
+        for (const node of sourceDiagrams(page)) {
+            const line = node.position?.start.line ?? 1;
+            try {
+                await parseMermaid(node.value ?? '');
+            }
+            catch (error) {
+                report('mermaid', 'error', page.path, `Invalid Mermaid: ${error.message}`, line);
+            }
+            if (!/^\s*accTitle\s*:/m.test(node.value ?? '') ||
+                !/^\s*accDescr\s*(?::|\{)/m.test(node.value ?? ''))
+                report('diagram-accessibility', 'warn', page.path, 'Mermaid needs accTitle and accDescr for accessibility.', line);
+            const section = diagramSection(page, node);
+            const pairs = page.links
+                .filter((l) => l.image && l.line >= section.start && l.line < section.end)
+                .map((l) => imageFile(target, page, l.href)?.path)
+                .filter((p) => !!p && /-(light|dark)\.svg$/.test(p));
+            if (pairs.length)
+                associations.push({ page, node, pairs });
+        }
+    }
+    // Inspect only conventional diagram directories or explicit paired refs;
+    // ordinary SVG logos remain ordinary assets.
+    for (const root of [join(target.appRoot, 'public'), target.contentRoot]) {
+        const diagrams = join(root, 'diagrams');
+        if (!(await present(diagrams)))
+            continue;
+        const walk = async (dir) => {
+            for (const entry of await readdir(dir, { withFileTypes: true })) {
+                const path = join(dir, entry.name);
+                if (entry.isDirectory())
+                    await walk(path);
+                else if (entry.isFile() && path.endsWith('.svg'))
+                    assets.set(path, { root, path });
+            }
+        };
+        await walk(diagrams);
+    }
+    for (const { root, path } of assets.values()) {
+        const label = posix(relative(target.contentRoot, path));
+        if (!(await containedFile(root, path))) {
+            report('diagram-pairs', 'error', label, 'Referenced diagram SVG does not exist inside its asset root.');
+            continue;
+        }
+        if (/-(light|dark)\.svg$/.test(path)) {
+            const sibling = path.replace(/-(light|dark)\.svg$/, (_, theme) => `-${theme === 'light' ? 'dark' : 'light'}.svg`);
+            if (!(await containedFile(root, sibling)))
+                report('diagram-pairs', 'error', label, 'Diagram SVG is missing its light/dark sibling.');
+        }
+        const nodes = htmlNodes(await readFile(path, 'utf8'));
+        const svg = nodes.find((n) => n.nodeName === 'svg');
+        const title = nodes.find((n) => n.nodeName === 'title' && n.childNodes?.some((c) => c.value?.trim()));
+        const desc = nodes.find((n) => n.nodeName === 'desc' && n.childNodes?.some((c) => c.value?.trim()));
+        if (!svg || attributes(svg).role !== 'img' || !title || !desc)
+            report('diagram-accessibility', 'error', label, 'Diagram SVG requires role="img", a nonempty title and desc.');
+    }
+    if (!associations.length)
+        return;
+    const base = target.documentation.check?.diagramBaseRef ?? 'origin/main';
+    try {
+        const mergeBase = (await git(target, ['merge-base', 'HEAD', base])).trim();
+        const committed = (await git(target, ['diff', '--name-only', '-z', mergeBase, 'HEAD', '--'])).split('\0');
+        const working = (await git(target, ['diff', '--name-only', '-z', 'HEAD', '--'])).split('\0');
+        const untracked = (await git(target, [
+            'ls-files',
+            '--others',
+            '--exclude-standard',
+            '-z',
+            '--',
+        ])).split('\0');
+        const changed = new Set([...committed, ...working, ...untracked]);
+        for (const { page, node, pairs } of associations) {
+            const sourcePath = posix(relative(target.repoRoot, join(target.contentRoot, page.path)));
+            if (!changed.has(sourcePath))
+                continue;
+            let old;
+            try {
+                old = parsePage(page.path, await git(target, ['show', `${mergeBase}:${sourcePath}`]));
+            }
+            catch {
+                /* new page */
+            }
+            const current = sourceDiagrams(page).map((n) => n.value);
+            const previous = old ? sourceDiagrams(old).map((n) => n.value) : [];
+            const index = sourceDiagrams(page).indexOf(node);
+            if (current[index] === previous[index] || previous.includes(node.value))
+                continue;
+            if (pairs.some((path) => !changed.has(posix(relative(target.repoRoot, path)))))
+                report('diagram-freshness', 'warn', page.path, 'Mermaid source changed without both associated SVGs in the same committed/working-tree change.', node.position?.start.line);
+        }
+    }
+    catch {
+        report('diagram-freshness', 'warn', 'index.md', `Diagram diff check unverified: no usable Git merge base for "${base}"; static checks still ran.`);
+    }
+}

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

@@ -0,0 +1,21 @@
+import { type ExclusionMatcher } from '../../docs/shared/exclusions.js';
+import { type OatDocumentationConfig } from '../../../config/oat-config.js';
+import { type ParsedPage } from './markdown.js';
+export declare function posix(path: string): string;
+export declare function inside(root: string, path: string): boolean;
+export declare function present(path: string): Promise<boolean>;
+export interface CheckTarget {
+    repoRoot: string;
+    appRoot: string;
+    contentRoot: string;
+    framework: 'markdown' | 'fumadocs' | 'mkdocs';
+    documentation: OatDocumentationConfig;
+    matcher: ExclusionMatcher;
+}
+export declare function resolveCheckTarget(cwd: string, targetDir?: string): Promise<CheckTarget>;
+export declare function readerFiles(target: CheckTarget): Promise<string[]>;
+export declare function readPage(target: CheckTarget, path: string): Promise<ParsedPage>;
+/** Never follow a link outside its allowed root, including symlink escapes. */
+export declare function containedFile(root: string, path: string): Promise<boolean>;
+export declare function readerDirectories(paths: string[]): string[];
+//# sourceMappingURL=files.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/files.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAExD,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1C;AACD,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAQ1D;AACD,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAa5D;AAKD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;IAC9C,aAAa,EAAE,sBAAsB,CAAC;IACtC,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AACD,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,WAAW,CAAC,CAiEtB;AACD,wBAAsB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAsBxE;AACD,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,UAAU,CAAC,CAKrB;AACD,+EAA+E;AAC/E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,CAAC,CAMlB;AACD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAU3D"}

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

@@ -0,0 +1,121 @@
+import { readFile, readdir, realpath, stat } from 'node:fs/promises';
+import { dirname, join, relative, resolve, isAbsolute } from 'node:path';
+import { createExclusionMatcher, isExcludedPath, } from '../../docs/shared/exclusions.js';
+import { readOatConfig, resolveDocumentationContentRoot, } from '../../../config/oat-config.js';
+import { resolveProjectRoot } from '../../../fs/paths.js';
+import { parsePage } from './markdown.js';
+export function posix(path) {
+    return path.replaceAll('\\', '/');
+}
+export function inside(root, path) {
+    const rel = relative(root, path);
+    return (rel !== '..' &&
+        !rel.startsWith('../') &&
+        !rel.startsWith('..\\') &&
+        !isAbsolute(rel));
+}
+export async function present(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (['ENOENT', 'ENOTDIR'].includes(error.code ?? ''))
+            return false;
+        throw error;
+    }
+}
+// Preserve the lexical missing-path diagnostic, but compare existing aliases by identity.
+async function canonicalPath(path) {
+    return (await present(path)) ? realpath(path) : path;
+}
+export async function resolveCheckTarget(cwd, targetDir) {
+    let repoRoot;
+    try {
+        repoRoot = await resolveProjectRoot(cwd);
+    }
+    catch {
+        repoRoot = cwd;
+    }
+    repoRoot = await realpath(repoRoot);
+    const config = await readOatConfig(repoRoot);
+    const doc = config.documentation ?? {};
+    const configured = doc.root
+        ? await canonicalPath(resolve(repoRoot, doc.root))
+        : undefined;
+    const requested = resolve(cwd, targetDir ?? configured ?? join(repoRoot, 'docs'));
+    const appRoot = await canonicalPath(requested);
+    const matching = configured === appRoot;
+    const framework = matching && doc.tooling === 'markdown'
+        ? 'markdown'
+        : (await present(join(appRoot, 'mkdocs.yml')))
+            ? 'mkdocs'
+            : (await Promise.all(['ts', 'mts', 'js', 'mjs'].map((ext) => present(join(appRoot, `source.config.${ext}`))))).some(Boolean)
+                ? 'fumadocs'
+                : matching && (doc.tooling === 'mkdocs' || doc.tooling === 'fumadocs')
+                    ? doc.tooling
+                    : 'markdown';
+    // The established resolver owns configured nested docs semantics. An
+    // unrelated explicit Markdown root remains literal, even with a docs child.
+    const configuredContent = await resolveDocumentationContentRoot(repoRoot, config);
+    const configuredContentPath = configuredContent
+        ? await canonicalPath(resolve(repoRoot, configuredContent))
+        : undefined;
+    const contentRoot = matching && configuredContentPath
+        ? configuredContentPath
+        : framework === 'markdown'
+            ? appRoot
+            : join(appRoot, 'docs');
+    if (!(await present(contentRoot)))
+        throw new Error(`Docs content directory does not exist: ${contentRoot}. Set documentation.root or pass --target-dir.`);
+    const matchesContent = configuredContentPath !== undefined && configuredContentPath === appRoot;
+    const documentation = matching || matchesContent ? doc : {};
+    return {
+        repoRoot,
+        appRoot,
+        contentRoot: await realpath(contentRoot),
+        framework,
+        documentation,
+        matcher: createExclusionMatcher(documentation.nonReaderPaths ?? []),
+    };
+}
+export async function readerFiles(target) {
+    const files = [];
+    const walk = async (dir) => {
+        const entries = await readdir(join(target.contentRoot, dir), {
+            withFileTypes: true,
+        });
+        for (const e of entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+            const path = posix(join(dir, e.name));
+            if (e.isDirectory() && !isExcludedPath(target.matcher, path, true))
+                await walk(path);
+            else if (e.isFile() &&
+                /\.mdx?$/.test(e.name) &&
+                !isExcludedPath(target.matcher, path))
+                files.push(path);
+        }
+    };
+    await walk('');
+    return files;
+}
+export async function readPage(target, path) {
+    return parsePage(path, await readFile(join(target.contentRoot, path), 'utf8'));
+}
+/** Never follow a link outside its allowed root, including symlink escapes. */
+export async function containedFile(root, path) {
+    if (!inside(root, path) || !(await present(path)))
+        return false;
+    return (inside(await realpath(root), await realpath(path)) &&
+        (await stat(path)).isFile());
+}
+export function readerDirectories(paths) {
+    const dirs = new Set(['.']);
+    for (const path of paths) {
+        let dir = dirname(path);
+        while (dir !== '.') {
+            dirs.add(posix(dir));
+            dir = dirname(dir);
+        }
+    }
+    return [...dirs].sort();
+}

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

@@ -0,0 +1,60 @@
+export interface MarkdownNode {
+    type: string;
+    name?: string;
+    value?: string;
+    depth?: number;
+    url?: string;
+    alt?: string;
+    identifier?: string;
+    lang?: string | null;
+    children?: MarkdownNode[];
+    position?: {
+        start: {
+            line: number;
+            column: number;
+            offset?: number;
+        };
+        end: {
+            line: number;
+            column: number;
+            offset?: number;
+        };
+    };
+}
+export interface PageLink {
+    href: string;
+    line: number;
+    image: boolean;
+    alt?: string;
+    html?: boolean;
+    describedBy?: string;
+}
+export interface ParsedPage {
+    path: string;
+    source: string;
+    body: string;
+    frontmatter: Record<string, unknown>;
+    frontmatterError?: string;
+    nodes: MarkdownNode[];
+    anchors: Set<string>;
+    links: PageLink[];
+    text: string;
+}
+export declare function nodeText(node: MarkdownNode): string;
+interface HtmlNode {
+    nodeName: string;
+    value?: string;
+    attrs?: Array<{
+        name: string;
+        value: string;
+    }>;
+    childNodes?: HtmlNode[];
+    sourceCodeLocation?: {
+        startLine: number;
+    };
+}
+export declare function htmlNodes(html: string): HtmlNode[];
+export declare function attributes(node: HtmlNode): Record<string, string>;
+export declare function parsePage(path: string, source: string): ParsedPage;
+export {};
+//# sourceMappingURL=markdown.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/markdown.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE;QACT,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACzD,GAAG,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KACxD,CAAC;CACH;AACD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AACD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACrB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AACD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAInD;AACD,UAAU,QAAQ;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,UAAU,CAAC,EAAE,QAAQ,EAAE,CAAC;IACxB,kBAAkB,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5C;AACD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE,CAQlD;AACD,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEjE;AACD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAoGlE"}