@open-agent-toolkit/cli 0.3.32 → 0.3.34

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

@@ -1,7 +1,99 @@
-import { readFile } from 'node:fs/promises';
-import { basename, dirname, extname, join, relative, resolve } from 'node:path';
+import { readdir, readFile } from 'node:fs/promises';
+import { basename, dirname, extname, join, posix, relative, resolve, } from 'node:path';
 import { createExclusionMatcher, isExcludedPath, } from '../../docs/shared/exclusions.js';
 import { dirExists, fileExists } from '../../../fs/io.js';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+/**
+ * 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 class DocsContentsError extends Error {
+    indexPath;
+    line;
+    constructor(message, indexPath, line) {
+        super(message);
+        this.indexPath = indexPath;
+        this.line = line;
+        this.name = 'DocsContentsError';
+    }
+}
+/** Reader page extensions: Fumadocs renders `.md` and `.mdx` pages. */
+export const PAGE_EXTENSIONS = ['.md', '.mdx'];
+/** Every non-excluded directory and reader page under the docs root. */
+export async function inventoryDocs(docsRoot, matcher) {
+    const directories = [];
+    const pages = [];
+    async function walk(relativeDir) {
+        directories.push(relativeDir);
+        const entries = await readdir(join(docsRoot, relativeDir), {
+            withFileTypes: true,
+        });
+        for (const entry of entries) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules') {
+                continue;
+            }
+            const entryPath = posix.join(relativeDir, entry.name);
+            if (entry.isDirectory()) {
+                if (matcher.excludesDirectory(entryPath))
+                    continue;
+                await walk(entryPath);
+            }
+            else if (entry.isFile() &&
+                PAGE_EXTENSIONS.includes(extname(entry.name))) {
+                if (!matcher.excludesFile(entryPath))
+                    pages.push(entryPath);
+            }
+        }
+    }
+    await walk('.');
+    directories.sort();
+    pages.sort();
+    return { directories, pages };
+}
+/**
+ * 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 function isIndexOnlyLeaf(dirRelativePath, pagePaths) {
+    const prefix = dirRelativePath === '.' ? '' : `${dirRelativePath}/`;
+    const ownIndex = `${prefix}index.md`;
+    let hasIndex = false;
+    for (const path of pagePaths) {
+        if (!path.startsWith(prefix))
+            continue;
+        if (path !== ownIndex)
+            return false;
+        hasIndex = true;
+    }
+    return hasIndex;
+}
+/** A Contents href naming a heading on the same page, such as `#setup`. */
+export function isSamePageAnchor(href) {
+    return href.trim().startsWith('#');
+}
+const inlineMarkdown = unified().use(remarkParse);
+/**
+ * Whether a Contents entry is a real Markdown link to a same-page fragment.
+ * The Contents grammar is line-based, so it captures destinations such as
+ * `#a b`, `#a(b` or `#a\` that Markdown does not parse as links; those render
+ * as plain text and no link rule would ever validate them. The CommonMark
+ * parser the reader check uses decides, over the authored link text rather
+ * than the `href` truncated at the first `)`, so balanced `#a(b)` and escaped
+ * `#a\(b\)` fragments stay links. The links rule then checks the URL remark
+ * parsed against the page's headings.
+ */
+function isMarkdownSamePageLink(entry) {
+    const tree = inlineMarkdown.parse(entry.source ?? `[${entry.title}](${entry.href})`);
+    const paragraph = tree.children?.length === 1 ? tree.children[0] : undefined;
+    const link = paragraph?.type === 'paragraph' ? paragraph.children?.[0] : undefined;
+    return (link?.type === 'link' &&
+        link.position?.start.offset === 0 &&
+        (link.url ?? '').startsWith('#'));
+}
 /** Mask fenced examples without changing authored source line numbers. */
 function unfencedLines(markdown) {
     let fence;
@@ -34,14 +126,14 @@ export function parseIndexContents(markdown, sourcePath = 'index.md', options =
     const lines = unfencedLines(markdown);
     const headingIndex = contentsHeadingIndex(lines);
     if (headingIndex < 0) {
-        throw new Error(`Missing required ## Contents section in ${sourcePath}`);
+        throw new DocsContentsError(`Missing required ## Contents section in ${sourcePath}`, sourcePath);
     }
     const entries = [];
     let group;
     let groupEntries = 0;
     const checkGroup = () => {
         if (group && groupEntries === 0) {
-            throw new Error(`${sourcePath}:${group.line}: Contents group "${group.title}" has no entries`);
+            throw new DocsContentsError(`${sourcePath}:${group.line}: Contents group "${group.title}" has no entries`, sourcePath);
         }
     };
     for (let i = headingIndex + 1; i < lines.length; i += 1) {
@@ -56,7 +148,7 @@ export function parseIndexContents(markdown, sourcePath = 'index.md', options =
             continue;
         }
         if (/^\s*[*+]\s+\[[^\]]+\]\([^)]+\)/.test(line)) {
-            throw new Error(`${sourcePath}:${i + 1}: Contents links must use a dash (-) bullet`);
+            throw new DocsContentsError(`${sourcePath}:${i + 1}: Contents links must use a dash (-) bullet`, sourcePath);
         }
         const match = line.match(/^\s*-\s+\[([^\]]+)\]\(([^)]+)\)/);
         if (match) {
@@ -72,6 +164,7 @@ export function parseIndexContents(markdown, sourcePath = 'index.md', options =
                             .replace(/^\s*[-–—:]\s*/, '')
                             .trim(),
                         separator: /^\s*([-–—:])/.exec(line.slice(match[0].length))?.[1],
+                        source: line.slice(match[0].indexOf('[')),
                     }
                     : {}),
             });
@@ -80,22 +173,47 @@ export function parseIndexContents(markdown, sourcePath = 'index.md', options =
     }
     checkGroup();
     if (entries.length === 0 && !options.allowEmpty) {
-        throw new Error(`No machine-readable links found under ## Contents in ${sourcePath}`);
+        throw new DocsContentsError(`No machine-readable links found under ## Contents in ${sourcePath}`, sourcePath);
     }
     return entries;
 }
 function toPosixPath(path) {
     return path.replaceAll('\\', '/');
 }
+/**
+ * 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 async function resolveEntryTarget(docsRoot, directoryPath, dirRelativePath, entry, 
 /**
  * Page extensions a Contents link may target. MkDocs renders only `.md`;
  * Fumadocs also renders `.mdx` pages.
  */
-pageExtensions = ['.md'], matcher) {
+pageExtensions = ['.md'], matcher, options = {}) {
+    const indexPath = join(docsRoot, dirRelativePath, 'index.md');
+    const fail = (message) => {
+        throw new DocsContentsError(message, indexPath, entry.line);
+    };
+    if (isSamePageAnchor(entry.href)) {
+        if (!options.indexOnlyLeaf) {
+            fail(`Contents link "${entry.href}" in ${indexPath} is a same-page anchor; Contents must link pages or sections unless index.md is the only reader page in its directory and it has no child sections.`);
+        }
+        if (!isMarkdownSamePageLink(entry)) {
+            fail(`Contents link "${entry.href}" in ${indexPath} is not a valid Markdown link; fix its destination (escape or remove spaces and unbalanced parentheses).`);
+        }
+        return {
+            kind: 'anchor',
+            path: toPosixPath(posix.join(dirRelativePath, 'index.md')),
+        };
+    }
     const href = entry.href.split('#', 1)[0]?.trim() ?? '';
     if (!href) {
-        throw new Error(`Invalid contents link "${entry.href}" in ${join(docsRoot, dirRelativePath, 'index.md')}`);
+        fail(`Invalid contents link "${entry.href}" in ${indexPath}`);
     }
     let targetPath = resolve(directoryPath, href);
     if (!href.endsWith('.md')) {
@@ -108,16 +226,16 @@ pageExtensions = ['.md'], matcher) {
     if (relativeTargetPath.startsWith('../') ||
         relativeTargetPath === '..' ||
         relativeTargetPath.length === 0) {
-        throw new Error(`Contents link "${entry.href}" escapes the docs directory from ${join(docsRoot, dirRelativePath, 'index.md')}`);
+        fail(`Contents link "${entry.href}" escapes the docs directory from ${indexPath}`);
     }
     if (matcher && isExcludedPath(matcher, relativeTargetPath)) {
         return { kind: 'excluded', path: relativeTargetPath };
     }
     if (!(await fileExists(targetPath))) {
-        throw new Error(`Contents link "${entry.href}" in ${join(docsRoot, dirRelativePath, 'index.md')} does not resolve to a Markdown file`);
+        fail(`Contents link "${entry.href}" in ${indexPath} does not resolve to a Markdown file`);
     }
     if (!pageExtensions.includes(extname(targetPath))) {
-        throw new Error(`Contents link "${entry.href}" in ${join(docsRoot, dirRelativePath, 'index.md')} must point to a Markdown file or directory index`);
+        fail(`Contents link "${entry.href}" in ${indexPath} must point to a Markdown file or directory index`);
     }
     if (basename(targetPath) === 'index.md') {
         return {
@@ -139,16 +257,20 @@ export async function buildDocsNavTree(options) {
         throw new Error(`Missing required index.md at ${indexPath}`);
     }
     const indexMarkdown = await readFile(indexPath, 'utf8');
-    const contentsEntries = parseIndexContents(indexMarkdown, indexPath);
+    const contentsEntries = parseIndexContents(indexMarkdown, indexPath, {
+        locations: true,
+    });
     const matcher = createExclusionMatcher(options.nonReaderPaths ?? []);
+    const pagePaths = options.pagePaths ?? (await inventoryDocs(options.docsRoot, matcher)).pages;
+    const indexOnlyLeaf = isIndexOnlyLeaf(dirRelativePath, pagePaths);
     const nav = dirRelativePath === '.'
         ? [{ Home: 'index.md' }]
         : [toPosixPath(join(dirRelativePath, 'index.md'))];
     let currentGroup;
     let groupNav = nav;
     for (const entry of contentsEntries) {
-        const resolvedTarget = await resolveEntryTarget(options.docsRoot, directoryPath, dirRelativePath, entry, ['.md'], matcher);
-        if (resolvedTarget.kind === 'excluded')
+        const resolvedTarget = await resolveEntryTarget(options.docsRoot, directoryPath, dirRelativePath, entry, ['.md'], matcher, { indexOnlyLeaf });
+        if (resolvedTarget.kind === 'excluded' || resolvedTarget.kind === 'anchor')
             continue;
         if (resolvedTarget.kind === 'section' &&
             resolvedTarget.path === toPosixPath(join(dirRelativePath, 'index.md'))) {
@@ -175,6 +297,7 @@ export async function buildDocsNavTree(options) {
                 dirRelativePath: childDirRelativePath,
                 visitedDirectories: childVisitedDirectories,
                 nonReaderPaths: options.nonReaderPaths,
+                pagePaths,
             }),
         });
     }

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":"AAwBA;;;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;AAMD,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAGlD,CAAC;AACH,eAAO,MAAM,kBAAkB,QACoB,CAAC;AACpD,eAAO,MAAM,aAAa,QAC6D,CAAC;AASxF;;;;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;AAkLD;;;;;;;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

@@ -1,54 +1,26 @@
-import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { readFile, writeFile } from 'node:fs/promises';
 import { basename, extname, join, posix } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { createExclusionMatcher, } from '../../docs/shared/exclusions.js';
 import { getFrontmatterBlock, parseFrontmatterScalarFields, } from '../../shared/frontmatter.js';
 import { fileExists } from '../../../fs/io.js';
-import { parseIndexContents, resolveEntryTarget, } from './contents.js';
-const PAGE_EXTENSIONS = ['.md', '.mdx'];
+import { inventoryDocs, isIndexOnlyLeaf, PAGE_EXTENSIONS, parseIndexContents, resolveEntryTarget, } from './contents.js';
 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*(```|~~~)/;
 function parentDir(path) {
     return posix.dirname(path);
 }
-async function inventoryDocs(docsRoot, matcher) {
-    const directories = [];
-    const pages = [];
-    async function walk(relativeDir) {
-        directories.push(relativeDir);
-        const entries = await readdir(join(docsRoot, relativeDir), {
-            withFileTypes: true,
-        });
-        for (const entry of entries) {
-            if (entry.name.startsWith('.') || entry.name === 'node_modules') {
-                continue;
-            }
-            const entryPath = posix.join(relativeDir, entry.name);
-            if (entry.isDirectory()) {
-                if (matcher.excludesDirectory(entryPath))
-                    continue;
-                await walk(entryPath);
-            }
-            else if (entry.isFile() &&
-                PAGE_EXTENSIONS.includes(extname(entry.name))) {
-                if (!matcher.excludesFile(entryPath))
-                    pages.push(entryPath);
-            }
-        }
-    }
-    await walk('.');
-    directories.sort();
-    pages.sort();
-    return { directories, pages };
-}
 /**
  * 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
@@ -104,7 +76,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 +132,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)) {
@@ -171,7 +143,8 @@ function hasImplicitIndex(relativeDir, existing) {
 }
 async function buildFolderPages(docsRoot, relativeDir, markdown, implicitIndex, matcher, inventory, nonIndexUrls) {
     const indexPath = join(docsRoot, relativeDir, 'index.md');
-    const entries = parseIndexContents(markdown, indexPath);
+    const entries = parseIndexContents(markdown, indexPath, { locations: true });
+    const indexOnlyLeaf = isIndexOnlyLeaf(relativeDir, inventory.pages);
     // A folder the loader gives no implicit index (the docs root, a `root: true`
     // folder) must list `index` to show its landing page. Elsewhere, listing
     // `index` would demote the folder index to an ordinary child, so it is left
@@ -179,8 +152,10 @@ async function buildFolderPages(docsRoot, relativeDir, markdown, implicitIndex,
     const pages = implicitIndex ? [] : ['index'];
     let currentGroup;
     for (const entry of entries) {
-        const target = await resolveEntryTarget(docsRoot, join(docsRoot, relativeDir), relativeDir, entry, PAGE_EXTENSIONS, matcher);
-        if (target.kind === 'excluded')
+        const target = await resolveEntryTarget(docsRoot, join(docsRoot, relativeDir), relativeDir, entry, PAGE_EXTENSIONS, matcher, { indexOnlyLeaf });
+        // Same-page anchors in an index-only leaf are an in-page table of
+        // contents, not navigation.
+        if (target.kind === 'excluded' || target.kind === 'anchor')
             continue;
         const targetDir = parentDir(target.path);
         let item;

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;AAoHD;;;;;;;;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"}