@open-agent-toolkit/cli 0.3.32 → 0.3.34

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

@@ -111,6 +111,38 @@ export async function checkCommands(target, pages, report) {
     if (!docs.length)
         return;
     const manifests = await packages(target);
+    // A framework app's own contributing pages usually speak from the app
+    // directory. Its package is tried first; the repository root remains the
+    // fallback context, so pages written from the repository root still resolve.
+    // Literal Markdown roots keep the repository-root context only.
+    const appContext = target.framework !== 'markdown' &&
+        target.appRoot !== target.repoRoot &&
+        manifests.some((item) => item.root === target.appRoot)
+        ? target.appRoot
+        : undefined;
+    const manifestName = (pkg, labelled) => {
+        const name = posix(relative(target.repoRoot, join(pkg.root, 'package.json'))) ||
+            'package.json';
+        if (!labelled)
+            return name;
+        return pkg.root === target.appRoot
+            ? `${name} (app root)`
+            : pkg.root === target.repoRoot
+                ? `${name} (repository root)`
+                : name;
+    };
+    const lookup = async (root) => {
+        if (!root || !inside(target.repoRoot, root) || !(await present(root)))
+            return undefined;
+        let current = root;
+        while (inside(target.repoRoot, current)) {
+            const pkg = manifests.find((item) => item.root === current);
+            if (pkg || current === target.repoRoot)
+                return pkg;
+            current = dirname(current);
+        }
+        return undefined;
+    };
     for (const p of docs)
         for (const node of p.nodes) {
             if (node.type !== 'code' && node.type !== 'inlineCode')
@@ -119,7 +151,11 @@ export async function checkCommands(target, pages, report) {
                 node.lang &&
                 !['sh', 'shell', 'bash', 'zsh', 'console', 'powershell'].includes(node.lang))
                 continue;
-            let cwd = target.repoRoot;
+            // Each block starts in the repository-root context and, for framework
+            // apps, also in the app-root context; literal `cd` moves both.
+            let contexts = appContext
+                ? [appContext, target.repoRoot]
+                : [target.repoRoot];
             const start = node.position?.start;
             const openingLine = p.source.split(/\r?\n/).at((start?.line ?? 1) - 1) ?? '';
             const fenced = node.type === 'code' &&
@@ -137,36 +173,34 @@ export async function checkCommands(target, pages, report) {
                         continue;
                     const words = tokens(segment);
                     if (words[0] === 'cd') {
-                        cwd =
-                            words[1] && !illustrative(words[1]) && cwd
-                                ? resolve(cwd, words[1])
-                                : undefined;
+                        contexts = contexts.map((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;
+                    const moves = [];
                     let filter;
                     let index = manager + 1;
                     while (words[index]?.startsWith('-')) {
                         const option = words[index++];
                         if (['-w', '--workspace-root'].includes(option))
-                            root = target.repoRoot;
+                            moves.push(() => 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;
+                            moves.push((root) => root && dir && !illustrative(dir)
+                                ? resolve(root, dir)
+                                : undefined);
                         }
                         else if (['-r', '--recursive', '--workspace'].includes(option))
-                            root = undefined;
+                            moves.push(() => undefined);
                     }
                     let script = words[index];
                     if (!script)
@@ -190,29 +224,32 @@ export async function checkCommands(target, pages, report) {
                         illustrative(script) ||
                         (filter && illustrative(filter)))
                         continue;
-                    let pkg;
+                    const candidates = [];
                     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];
+                            candidates.push(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);
+                    else {
+                        for (const cwd of contexts) {
+                            const pkg = await lookup(moves.reduce((root, move) => move(root), cwd));
+                            if (pkg && !candidates.includes(pkg))
+                                candidates.push(pkg);
                         }
                     }
-                    if (!pkg)
+                    if (!candidates.length) {
                         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)) {
+                        continue;
+                    }
+                    let pkg;
+                    for (const candidate of candidates) {
+                        if (Object.hasOwn(candidate.scripts ?? {}, script)) {
+                            pkg = candidate;
+                            break;
+                        }
                         // 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' &&
@@ -220,12 +257,19 @@ export async function checkCommands(target, pages, report) {
                             !/[\\/]/.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);
+                            (await Promise.all([candidate.root, target.repoRoot].map((binRoot) => present(join(binRoot, 'node_modules/.bin', script))))).some(Boolean);
+                        if (installedBinary) {
+                            pkg = candidate;
+                            break;
+                        }
                     }
-                    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);
+                    if (!pkg)
+                        report('commands', 'error', p.path, `Script "${script}" does not exist in ${candidates
+                            .map((candidate) => manifestName(candidate, candidates.length > 1))
+                            .join(' or ')}.`, line);
+                    else if (Object.hasOwn(pkg.scripts ?? {}, script) &&
+                        /^\s*echo(?:\s|$)/.test(pkg.scripts[script]))
+                        report('commands', 'warn', p.path, `Script "${script}" is an echo stub in ${manifestName(pkg, false)}.`, line);
                 }
             }
         }

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

@@ -11,6 +11,8 @@ export interface CheckTarget {
     framework: 'markdown' | 'fumadocs' | 'mkdocs';
     documentation: OatDocumentationConfig;
     matcher: ExclusionMatcher;
+    /** Human notices about how an explicit target was interpreted. */
+    notices: string[];
 }
 export declare function resolveCheckTarget(cwd: string, targetDir?: string): Promise<CheckTarget>;
 export declare function readerFiles(target: CheckTarget): Promise<string[]>;

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

@@ -1 +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"}
+{"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;IAC1B,kEAAkE;IAClE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AACD,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,WAAW,CAAC,CAiFtB;AACD,wBAAsB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA6BxE;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

@@ -70,6 +70,16 @@ export async function resolveCheckTarget(cwd, targetDir) {
         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 : {};
+    const notices = [];
+    if (targetDir !== undefined && configured && doc.root && !matching) {
+        const configuredTooling = doc.tooling === 'fumadocs' || doc.tooling === 'mkdocs'
+            ? doc.tooling
+            : undefined;
+        if (matchesContent && configuredTooling && framework === 'markdown')
+            notices.push(`Notice: --target-dir ${targetDir} is the content directory of the configured ${configuredTooling} app ${doc.root}; it is checked as Markdown, so navigation is skipped. Pass --target-dir ${doc.root} to include navigation.`);
+        else if (!matchesContent)
+            notices.push(`Notice: --target-dir ${targetDir} is not the configured documentation.root (${doc.root}); checking it as ${framework === 'markdown' ? 'a literal Markdown root' : `a ${framework} app`} without the configured documentation policy. Omit --target-dir to check ${doc.root}.`);
+    }
     return {
         repoRoot,
         appRoot,
@@ -77,6 +87,7 @@ export async function resolveCheckTarget(cwd, targetDir) {
         framework,
         documentation,
         matcher: createExclusionMatcher(documentation.nonReaderPaths ?? []),
+        notices,
     };
 }
 export async function readerFiles(target) {
@@ -87,6 +98,11 @@ export async function readerFiles(target) {
         });
         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));
+            // Installed dependencies and hidden tool state (.git, .oat, .next, ...)
+            // are never reader content, even under a broad explicit target.
+            if (e.isDirectory() &&
+                (e.name === 'node_modules' || e.name.startsWith('.')))
+                continue;
             if (e.isDirectory() && !isExcludedPath(target.matcher, path, true))
                 await walk(path);
             else if (e.isFile() &&

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

@@ -1,4 +1,14 @@
 import type { Report } from './check.types.js';
 import { type CheckTarget } from './files.js';
-export declare function checkNavigation(target: CheckTarget, report: Report): Promise<void>;
+/**
+ * `navOwner: nav-sync` keeps strict generated freshness. Hand-authored and
+ * undeclared navigation gets the membership-and-order comparison (issue #367
+ * P21/G5): separators, labels, links, rest entries and borrowed pages are the
+ * author's presentation, never generator output to match.
+ *
+ * `reported` tells whether an error-severity finding already exists for a
+ * rule, path and line. A policy-downgraded finding does not count: the defect
+ * still stops navigation, so navigation keeps reporting it as an error.
+ */
+export declare function checkNavigation(target: CheckTarget, report: Report, reported: (ruleId: string, path: string, line?: number) => boolean): Promise<void>;
 //# sourceMappingURL=navigation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/navigation.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAW,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAgCpD,wBAAsB,eAAe,CACnC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAmGf"}
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/navigation.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE1D;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,GACjE,OAAO,CAAC,IAAI,CAAC,CAyEf"}

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

@@ -1,42 +1,20 @@
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { isDeepStrictEqual } from 'node:util';
-import { buildDocsNavTree } from '../../docs/nav/contents.js';
+import { relative } from 'node:path';
+import { DocsContentsError } from '../../docs/nav/contents.js';
 import { syncFumadocsNavigation } from '../../docs/nav/fumadocs.js';
+import { compareFumadocsMembership, compareMkDocsMembership, } from '../../docs/nav/membership.js';
 import { syncDocsNavigation } from '../../docs/nav/sync.js';
-import YAML from 'yaml';
-import { present } from './files.js';
-function pageIdentity(item) {
-    // Hand-authored collision links can use their own display labels.
-    return item.replace(/^\[[^\]]*\]\((.*)\)$/, '[]($1)').replace(/^\.\//, '');
-}
-function navIdentity(value, expected) {
-    if (!Array.isArray(value))
-        return value;
-    return value.map((item, index) => {
-        if (typeof item === 'string')
-            return item;
-        if (typeof item !== 'object' || item === null)
-            return item;
-        const entry = Object.entries(item)[0];
-        if (!entry)
-            return item;
-        const expectedItem = Array.isArray(expected) ? expected[index] : undefined;
-        const children = expectedItem && typeof expectedItem === 'object'
-            ? Object.values(expectedItem)[0]
-            : undefined;
-        // The Contents-derived tree identifies sections by their direct landing path.
-        // Actual landing/page labels are presentation; explicit group labels remain meaningful.
-        const section = Array.isArray(children) &&
-            children.some((child) => typeof child === 'string' && child.endsWith('/index.md'));
-        return Array.isArray(entry[1])
-            ? {
-                [section ? '$section' : entry[0]]: navIdentity(entry[1], children),
-            }
-            : entry[1];
-    });
-}
-export async function checkNavigation(target, report) {
+import { inside, posix } from './files.js';
+/**
+ * `navOwner: nav-sync` keeps strict generated freshness. Hand-authored and
+ * undeclared navigation gets the membership-and-order comparison (issue #367
+ * P21/G5): separators, labels, links, rest entries and borrowed pages are the
+ * author's presentation, never generator output to match.
+ *
+ * `reported` tells whether an error-severity finding already exists for a
+ * rule, path and line. A policy-downgraded finding does not count: the defect
+ * still stops navigation, so navigation keeps reporting it as an error.
+ */
+export async function checkNavigation(target, report, reported) {
     if (target.framework === 'markdown')
         return;
     try {
@@ -48,31 +26,14 @@ export async function checkNavigation(target, report) {
                 check: true,
                 nonReaderPaths,
             });
-            for (const file of result.metaFiles) {
-                let stale = file.changed;
-                if (!generated) {
-                    if (!(await present(join(target.contentRoot, file.path))))
-                        continue;
-                    try {
-                        const actual = JSON.parse(await readFile(join(target.contentRoot, file.path), 'utf8'));
-                        if (actual &&
-                            typeof actual === 'object' &&
-                            !Array.isArray(actual) &&
-                            !Object.hasOwn(actual, 'pages'))
-                            continue;
-                        stale =
-                            !Array.isArray(actual.pages) ||
-                                !isDeepStrictEqual(actual.pages.map((p) => typeof p === 'string' ? pageIdentity(p) : p), file.meta.pages.map(pageIdentity));
-                    }
-                    catch {
-                        report('navigation', 'error', file.path, 'Cannot read or parse meta.json; check file permissions and JSON syntax.');
-                        continue;
-                    }
-                }
-                if (stale)
-                    report('navigation', 'error', file.path, generated
-                        ? 'Generated navigation is stale; run oat docs nav sync.'
-                        : 'Navigation membership/order differs from authored Contents; update pages or Contents.');
+            if (generated) {
+                for (const file of result.metaFiles)
+                    if (file.changed)
+                        report('navigation', 'error', file.path, 'Generated navigation is stale; run oat docs nav sync.');
+            }
+            else {
+                for (const issue of await compareFumadocsMembership(target.contentRoot, result.metaFiles))
+                    report('navigation', 'error', issue.path, issue.message, issue.line);
             }
             for (const path of result.unlisted)
                 report('navigation', 'error', path, 'Reader page/folder is unlisted in authored Contents and would be hidden from navigation.');
@@ -87,18 +48,28 @@ export async function checkNavigation(target, report) {
                 report('navigation', 'error', path, 'Generated navigation is stale; run oat docs nav sync.');
         }
         else {
-            const expected = await buildDocsNavTree({
+            for (const issue of await compareMkDocsMembership({
+                appRoot: target.appRoot,
                 docsRoot: target.contentRoot,
                 nonReaderPaths,
-            });
-            const actual = YAML.parse(await readFile(join(target.appRoot, 'mkdocs.yml'), 'utf8'));
-            if (!actual || !Object.hasOwn(actual, 'nav'))
-                return;
-            if (!isDeepStrictEqual(navIdentity(actual.nav, expected), navIdentity(expected, expected)))
-                report('navigation', 'error', 'mkdocs.yml', 'Navigation membership/order differs from authored Contents; update nav or Contents.');
+            }))
+                report('navigation', 'error', issue.path, issue.message, issue.line);
         }
     }
     catch (error) {
+        if (error instanceof DocsContentsError &&
+            inside(target.contentRoot, error.indexPath)) {
+            // Navigation stops at the first invalid Contents map. directory-index
+            // resolves every map the same way and reports each defect at its own
+            // index.md, so repeat it here only when that rule did not report it as
+            // an error: it was not selected, policy downgraded it, or the defect is
+            // framework-only (MkDocs nav accepts only .md targets, while the reader
+            // check also accepts .mdx).
+            const path = posix(relative(target.contentRoot, error.indexPath));
+            if (!reported('directory-index', path, error.line))
+                report('navigation', 'error', path, error.message, error.line);
+            return;
+        }
         report('navigation', 'error', 'index.md', error.message);
     }
 }

package/dist/commands/docs/check/reader-rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reader-rules.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/reader-rules.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvD,wBAAsB,YAAY,CAChC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CA4Vf;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,GACb,IAAI,CA+CN"}
+{"version":3,"file":"reader-rules.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/reader-rules.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvD,wBAAsB,YAAY,CAChC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAgWf;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,GACb,IAAI,CA+CN"}

package/dist/commands/docs/check/reader-rules.js

@@ -1,5 +1,5 @@
 import { dirname, extname, join, resolve } from 'node:path';
-import { parseIndexContents, resolveEntryTarget, } from '../../docs/nav/contents.js';
+import { isIndexOnlyLeaf, parseIndexContents, resolveEntryTarget, } from '../../docs/nav/contents.js';
 import { isExcludedPath } from '../../docs/shared/exclusions.js';
 import { DOCS_CHECK_THRESHOLDS } from '../../../config/documentation-check.js';
 import { containedFile, inside, posix, present, readerDirectories, } from './files.js';
@@ -10,11 +10,13 @@ export async function checkReaders(target, pages, report) {
         ...target.documentation.check?.thresholds,
     };
     const byPath = new Map(pages.map((p) => [p.path, p]));
-    const dirs = readerDirectories(pages.map((p) => p.path));
+    const pagePaths = pages.map((p) => p.path);
+    const dirs = readerDirectories(pagePaths);
     const separators = new Map();
     for (const dir of dirs) {
         const path = posix(join(dir, 'index.md'));
         const page = byPath.get(path);
+        const indexOnlyLeaf = isIndexOnlyLeaf(dir, pagePaths);
         let grouped = false;
         if (!page)
             report('directory-index', 'error', path, 'Reader-bearing directory needs index.md with a nonempty ## Contents map.');
@@ -36,7 +38,9 @@ export async function checkReaders(target, pages, report) {
                         separators.set(entry.separator, { path, line: entry.line });
                     try {
                         // Existing strict Contents resolution owns local map semantics.
-                        await resolveEntryTarget(target.contentRoot, join(target.contentRoot, dir), dir, entry, ['.md', '.mdx'], target.matcher);
+                        // Leaf same-page anchors resolve without error; the links rule
+                        // below reports any that name a missing heading.
+                        await resolveEntryTarget(target.contentRoot, join(target.contentRoot, dir), dir, entry, ['.md', '.mdx'], target.matcher, { indexOnlyLeaf });
                     }
                     catch (error) {
                         report('directory-index', 'error', path, String(error.message), entry.line);
@@ -78,12 +82,11 @@ export async function checkReaders(target, pages, report) {
         }
         const count = pages.filter((p) => dirname(p.path) === dir).length;
         const child = dirs.some((d) => d !== dir && (dir === '.' || d.startsWith(`${dir}/`)));
-        if (!child) {
-            if (count === 1 && page)
-                report('leaf-size', 'error', path, 'Index-only leaf has no reader destination; flatten it or add its reader pages.');
-            else if (count === 2)
-                report('leaf-size', 'warn', path, 'Leaf has only two direct reader pages including index.md; consider flattening.');
-        }
+        // A single-page section renders fine, so its shape is a style suggestion.
+        if (indexOnlyLeaf)
+            report('leaf-size', 'warn', path, 'Index-only leaf; consider flattening it to a single page or adding reader pages.');
+        else if (!child && count === 2)
+            report('leaf-size', 'warn', path, 'Leaf has only two direct reader pages including index.md; consider flattening.');
         if (!grouped) {
             if (count > t.folderError)
                 report('folder-size', 'error', path, `Folder has ${count} direct reader pages including index; maximum ${t.folderError} without groups.`);

package/dist/commands/docs/nav/contents.d.ts

@@ -5,11 +5,45 @@ export interface DocsContentsEntry {
     line?: number;
     description?: string;
     separator?: string;
+    /**
+     * The authored line from the link's opening `[` onward. `href` is captured
+     * only up to the first `)`, so Markdown-level validation reads this instead.
+     */
+    source?: string;
     group?: {
         title: string;
         line: number;
     };
 }
+/**
+ * A defect in one index.md Contents map. `indexPath` is the index file that
+ * contains it, as the caller named it, and `line` the entry line when the
+ * entries were parsed with locations, so a consumer that only sees the thrown
+ * error can still report it against the file that contains it.
+ */
+export declare class DocsContentsError extends Error {
+    readonly indexPath: string;
+    readonly line?: number | undefined;
+    constructor(message: string, indexPath: string, line?: number | undefined);
+}
+export interface DocsInventory {
+    /** Docs-relative POSIX directory paths, `.` for the docs root. */
+    directories: string[];
+    /** Docs-relative POSIX page paths. */
+    pages: string[];
+}
+/** Reader page extensions: Fumadocs renders `.md` and `.mdx` pages. */
+export declare const PAGE_EXTENSIONS: readonly string[];
+/** Every non-excluded directory and reader page under the docs root. */
+export declare function inventoryDocs(docsRoot: string, matcher: ExclusionMatcher): Promise<DocsInventory>;
+/**
+ * Whether a directory is an index-only leaf: its own `index.md` is the only
+ * reader page in it or below it, so it renders as a single-page section.
+ * `pagePaths` are docs-relative POSIX reader page paths.
+ */
+export declare function isIndexOnlyLeaf(dirRelativePath: string, pagePaths: readonly string[]): boolean;
+/** A Contents href naming a heading on the same page, such as `#setup`. */
+export declare function isSamePageAnchor(href: string): boolean;
 /** Shared discovery lets inventory generation retain its no-map fallback. */
 export declare function hasIndexContents(markdown: string): boolean;
 export declare function parseIndexContents(markdown: string, sourcePath?: string, options?: {
@@ -22,14 +56,28 @@ interface BuildDocsNavTreeOptions {
     dirRelativePath?: string;
     visitedDirectories?: Set<string>;
     nonReaderPaths?: readonly string[];
+    /** Reader page inventory; the root call computes it once. */
+    pagePaths?: readonly string[];
 }
+/**
+ * Resolve one Contents entry to the page or section it places in navigation.
+ *
+ * Contents is machine-readable navigation, so every entry must target a page
+ * or a section index. The one exception is an index-only leaf: a single-page
+ * section may list same-page heading anchors as an in-page table of contents.
+ * Those resolve to `anchor` and place nothing in navigation; the `links` check
+ * rule validates that each heading exists.
+ */
 export declare function resolveEntryTarget(docsRoot: string, directoryPath: string, dirRelativePath: string, entry: DocsContentsEntry, 
 /**
  * Page extensions a Contents link may target. MkDocs renders only `.md`;
  * Fumadocs also renders `.mdx` pages.
  */
-pageExtensions?: readonly string[], matcher?: ExclusionMatcher): Promise<{
-    kind: 'page' | 'section' | 'excluded';
+pageExtensions?: readonly string[], matcher?: ExclusionMatcher, options?: {
+    /** The directory is an index-only leaf (see {@link isIndexOnlyLeaf}). */
+    indexOnlyLeaf?: boolean;
+}): Promise<{
+    kind: 'page' | 'section' | 'excluded' | 'anchor';
     path: string;
 }>;
 export declare function buildDocsNavTree(options: BuildDocsNavTreeOptions): Promise<DocsNavTree>;

package/dist/commands/docs/nav/contents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contents.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/contents.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,kCAAkC,CAAC;AAG1C,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACzC;AA8BD,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,UAAU,SAAa,EACvB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1D,iBAAiB,EAAE,CA8DrB;AAED,MAAM,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;AAE/E,UAAU,uBAAuB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAMD,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,EACvB,KAAK,EAAE,iBAAiB;AACxB;;;GAGG;AACH,cAAc,GAAE,SAAS,MAAM,EAAY,EAC3C,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAuElE;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,WAAW,CAAC,CA0EtB"}
+{"version":3,"file":"contents.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/contents.ts"],"names":[],"mappings":"AAWA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,kCAAkC,CAAC;AAK1C,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACzC;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAGxC,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;IAHxB,YACE,OAAO,EAAE,MAAM,EACN,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,MAAM,YAAA,EAIvB;CACF;AAED,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,sCAAsC;IACtC,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,uEAAuE;AACvE,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAAoB,CAAC;AAElE,wEAAwE;AACxE,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CA8BxB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAUT;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AA+DD,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,UAAU,SAAa,EACvB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1D,iBAAiB,EAAE,CAqErB;AAED,MAAM,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;AAE/E,UAAU,uBAAuB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,6DAA6D;IAC7D,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B;AAMD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,EACvB,KAAK,EAAE,iBAAiB;AACxB;;;GAGG;AACH,cAAc,GAAE,SAAS,MAAM,EAAY,EAC3C,OAAO,CAAC,EAAE,gBAAgB,EAC1B,OAAO,GAAE;IACP,yEAAyE;IACzE,aAAa,CAAC,EAAE,OAAO,CAAC;CACpB,GACL,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;IACjD,IAAI,EAAE,MAAM,CAAC;CACd,CAAC,CAyED;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,WAAW,CAAC,CAkFtB"}