@open-agent-toolkit/cli 0.3.32 → 0.3.33

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,10 @@
 import type { Report } from './check.types.js';
-import { type CheckTarget } from './files.js';
+import type { CheckTarget } 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.
+ */
 export declare function checkNavigation(target: CheckTarget, report: Report): 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":"AAOA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CA0Df"}

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

@@ -1,41 +1,12 @@
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { isDeepStrictEqual } from 'node:util';
-import { buildDocsNavTree } 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];
-    });
-}
+/**
+ * `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.
+ */
 export async function checkNavigation(target, report) {
     if (target.framework === 'markdown')
         return;
@@ -48,31 +19,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,15 +41,12 @@ 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) {

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

@@ -27,6 +27,9 @@ export interface SyncFumadocsNavigationResult {
      */
     unlisted: string[];
 }
+export declare const FUMADOCS_REST_ITEMS: ReadonlySet<string>;
+export declare const FUMADOCS_SEPARATOR: RegExp;
+export declare const FUMADOCS_LINK: RegExp;
 /**
  * Reduce a Markdown heading to the plain text a sidebar shows: images and
  * links keep their text, code spans keep their content, and emphasis and
@@ -35,6 +38,12 @@ export interface SyncFumadocsNavigationResult {
 export declare function stripInlineMarkdown(text: string): string;
 /** Folder title: frontmatter `title`, else the first H1 outside code fences. */
 export declare function resolveFolderTitle(markdown: string): string | undefined;
+/**
+ * The URL Fumadocs assigns a page, following `getSlugs` in fumadocs-core's
+ * slugs plugin with the scaffolded `baseUrl: '/'`: group folders are dropped,
+ * segments are URI-encoded, and an `index` file maps to its folder.
+ */
+export declare function pageUrl(pagePath: string, nonIndexUrls?: ReadonlySet<string>): string;
 /**
  * The `pages` item for a page or folder in the same directory. A name the
  * builder would read as a directive (`!hidden`, `z...a`, `---`, ...) is
@@ -42,6 +51,26 @@ export declare function resolveFolderTitle(markdown: string): string | undefined
  * the same file; every other name is written as is.
  */
 export declare function toFumadocsPageItem(name: string): string;
+/**
+ * Build one folder's `pages` from its index.md Contents map.
+ *
+ * A page in this folder or an immediate subfolder is referenced by name.
+ * Local same-name page/folder collisions use a precise source-file item, as
+ * does `../contributing.md` from its own contributing/ map: pinned core16.10.2
+ * selects the folder first for an extensionless reference. Other non-local
+ * targets become link entries. There is never a `"..."` rest entry: pages the Contents map does
+ * not list stay out of the tree and are reported instead.
+ */
+/**
+ * Whether the fumadocs-core 16.10.2 page-tree builder supplies this folder's
+ * `index` page on its own, given the folder's effective metadata.
+ *
+ * `buildFolder` attaches `<folder>/index` as the folder index only when the
+ * folder is not a root folder (the docs root, or a preserved `root: true`)
+ * and no `pagesIndex` names a different page. Otherwise the page is shown
+ * only if `pages` lists it.
+ */
+export declare function hasImplicitIndex(relativeDir: string, existing: Record<string, unknown> | null): boolean;
 /**
  * Write one strict `meta.json` per docs directory that has an index.md,
  * derived from that index's Contents map, and report every page the

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

@@ -1 +1 @@
-{"version":3,"file":"fumadocs.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/fumadocs.ts"],"names":[],"mappings":"AAoBA;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,4BAA4B;IAC3C,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA6DD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQxD;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoCvE;AAsCD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAqND;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,GAAG,OAAO,CAAC,4BAA4B,CAAC,CA8ExC"}
+{"version":3,"file":"fumadocs.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/fumadocs.ts"],"names":[],"mappings":"AAoBA;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,4BAA4B;IAC3C,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAOD,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAGlD,CAAC;AACH,eAAO,MAAM,kBAAkB,QACoB,CAAC;AACpD,eAAO,MAAM,aAAa,QAC6D,CAAC;AAmDxF;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQxD;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoCvE;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,QAAQ,EAAE,MAAM,EAChB,YAAY,GAAE,WAAW,CAAC,MAAM,CAAa,GAC5C,MAAM,CAgBR;AAYD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAOD;;;;;;;;;GASG;AACH;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GACvC,OAAO,CAUT;AA8KD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,GAAG,OAAO,CAAC,4BAA4B,CAAC,CA8ExC"}

package/dist/commands/docs/nav/fumadocs.js

@@ -10,9 +10,12 @@ const GROUP_FOLDER = /^\(.+\)$/;
 // The `pages` item grammar of the fumadocs-core 16.10.2 page-tree builder
 // (`resolveFolderItem`): exact rest entries, separators, links, and the
 // exclude and extract prefixes are checked before an item is read as a path.
-const FUMADOCS_REST_ITEMS = new Set(['...', 'z...a']);
-const FUMADOCS_SEPARATOR = /^---(?:\[(?<icon>[^\]]+)])?(?<name>.+)---|^---$/;
-const FUMADOCS_LINK = /^(?<external>external:)?(?:\[(?<icon>[^\]]+)])?\[(?<name>[^\]]+)]\((?<url>[^)]+)\)$/;
+export const FUMADOCS_REST_ITEMS = new Set([
+    '...',
+    'z...a',
+]);
+export const FUMADOCS_SEPARATOR = /^---(?:\[(?<icon>[^\]]+)])?(?<name>.+)---|^---$/;
+export const FUMADOCS_LINK = /^(?<external>external:)?(?:\[(?<icon>[^\]]+)])?\[(?<name>[^\]]+)]\((?<url>[^)]+)\)$/;
 const FUMADOCS_PREFIXES = ['!', '...'];
 const H1 = /^#\s+(.+?)\s*#*\s*$/;
 const FENCE = /^\s*(```|~~~)/;
@@ -104,7 +107,7 @@ export function resolveFolderTitle(markdown) {
  * slugs plugin with the scaffolded `baseUrl: '/'`: group folders are dropped,
  * segments are URI-encoded, and an `index` file maps to its folder.
  */
-function pageUrl(pagePath, nonIndexUrls = new Set()) {
+export function pageUrl(pagePath, nonIndexUrls = new Set()) {
     const slugs = parentDir(pagePath)
         .split('/')
         .filter((segment) => segment.length > 0 && segment !== '.')
@@ -160,7 +163,7 @@ function hrefFragment(href) {
  * and no `pagesIndex` names a different page. Otherwise the page is shown
  * only if `pages` lists it.
  */
-function hasImplicitIndex(relativeDir, existing) {
+export function hasImplicitIndex(relativeDir, existing) {
     if (relativeDir === '.' ||
         existing?.root === true ||
         (typeof existing?.root === 'string' && existing.root.trim().length > 0)) {

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

@@ -0,0 +1,37 @@
+import { type FumadocsMetaFile } from './fumadocs.js';
+/**
+ * One way a hand-authored (or undeclared) sidebar disagrees with the authored
+ * Contents maps. The comparison checks membership and relative order only:
+ * separators, labels, link items, rest entries and pages borrowed from another
+ * folder are the author's presentation and are never compared with generator
+ * output.
+ */
+export interface NavMembershipIssue {
+    /** Content-relative path of the meta.json, or `mkdocs.yml`. */
+    path: string;
+    kind: 'missing' | 'dangling' | 'order' | 'malformed' | 'unreadable';
+    message: string;
+    line?: number;
+}
+/**
+ * Compare present Fumadocs `meta.json` files with the Contents-derived
+ * expectation in `metaFiles` (from a `check` run of nav sync).
+ *
+ * A Contents entry is reachable when its folder's `pages` lists it, a rest
+ * entry shows it, any other `pages` entry borrows it, or a root-relative link
+ * item points at its URL. An absent meta.json or one without `pages` uses the
+ * loader's folder order and is skipped.
+ */
+export declare function compareFumadocsMembership(docsRoot: string, metaFiles: readonly FumadocsMetaFile[]): Promise<NavMembershipIssue[]>;
+/**
+ * Compare a hand-authored MkDocs `nav:` with the Contents maps: every
+ * Contents page appears, every local nav page exists, and the entries of
+ * each Contents map (pages and section landing pages) keep their order. Section labels, nesting and external
+ * links are the author's. Returns no issues when `nav` is absent.
+ */
+export declare function compareMkDocsMembership(options: {
+    appRoot: string;
+    docsRoot: string;
+    nonReaderPaths?: readonly string[];
+}): Promise<NavMembershipIssue[]>;
+//# sourceMappingURL=membership.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"membership.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/membership.ts"],"names":[],"mappings":"AAMA,OAAO,EAML,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,WAAW,GAAG,YAAY,CAAC;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAqHD;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,SAAS,gBAAgB,EAAE,GACrC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAoS/B;AAeD;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAAC,OAAO,EAAE;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAwEhC"}