jamdesk 1.1.148 → 1.1.150

package/dist/lib/fix-engine.js

@@ -0,0 +1,236 @@
+/**
+ * Deterministic Doc-Warning Fix Engine.
+ *
+ * AUTO-SYNCED: This file is automatically copied from build-service by vendor.js.
+ * DO NOT EDIT directly - edit builder/build-service/lib/fix-engine.ts instead.
+ */
+/** A markdown heading entry (not a <Step> or <Update> component anchor). */
+export function isMarkdownHeading(h) {
+    return h.stepNumber == null && !h.isUpdate;
+}
+/** True iff `candidate` is an exact heading id on `headings`. The canonical
+ *  guard for any externally-sourced (e.g. AI) anchor suggestion — the engine
+ *  itself uses the same `allIds.includes(...)` check inside fixBrokenLink's
+ *  `emit`. Phase 2's AI tier MUST route every suggestion through this so a
+ *  hallucinated fragment can never be written. Pure, dependency-free. */
+export function isRealAnchor(candidate, headings) {
+    if (!candidate)
+        return false;
+    return headings.some((h) => h.id === candidate);
+}
+/** Substring appended to the skip reason when the deterministic engine defers an
+ *  anchor to the AI tier. Exported so the AI-tier callers match on this constant
+ *  instead of a re-typed literal — producer and consumer cannot drift. */
+export const NEEDS_AI_MARKER = '(needs AI)';
+// ---- Edit application -----------------------------------------------------
+// A flagged href is always the target of a markdown link `](href)` or an
+// `href="…"`/`href='…'` attribute, so in source it is bounded on the left by a
+// delimiter — never by another URL/path character. A match whose preceding char
+// IS a path character is the href appearing as a SUBSTRING inside a longer URL
+// (e.g. `/setup#x` inside `/guide/setup#x`) and must be skipped, or the edit
+// would corrupt an unrelated, valid link on the same line.
+const URL_PATH_CHAR = /[A-Za-z0-9\-._~%/#?:@]/;
+/** Index of the next occurrence of `href` at/after `from` that sits at a link
+ *  boundary (not as a substring inside a longer path), or -1. */
+function findHrefBoundary(line, href, from) {
+    let pos = line.indexOf(href, from);
+    while (pos !== -1) {
+        if (pos === 0 || !URL_PATH_CHAR.test(line[pos - 1]))
+            return pos;
+        pos = line.indexOf(href, pos + 1);
+    }
+    return -1;
+}
+/**
+ * Apply edits, replacing each edit's oldText with newText on its specific
+ * (1-indexed) source line. Line-scoped, so an identical href on another line
+ * (e.g. a code sample) is never touched. Within a line: oldText is matched at a
+ * link boundary (so a short href is never replaced inside a longer one),
+ * matching runs against the ORIGINAL line (so an edit whose newText contains its
+ * oldText is never re-matched), and edits apply right-to-left so earlier
+ * positions keep their indices. Identical oldTexts on one line consume
+ * successive occurrences. Throws if a line is out of range or an oldText is
+ * absent — a missing match means the source changed since the fix was derived,
+ * and a partial/wrong edit must never be written.
+ */
+export function applyEdits(content, edits) {
+    if (edits.length === 0)
+        return content;
+    const lines = content.split('\n');
+    const byLine = new Map();
+    for (const edit of edits) {
+        const list = byLine.get(edit.line);
+        if (list)
+            list.push(edit);
+        else
+            byLine.set(edit.line, [edit]);
+    }
+    for (const [line, lineEdits] of byLine) {
+        const idx = line - 1;
+        if (idx < 0 || idx >= lines.length) {
+            throw new Error(`applyEdits: line ${line} out of range (${lines.length} lines)`);
+        }
+        const src = lines[idx];
+        // Resolve every edit to a concrete [start,end) span on the ORIGINAL line.
+        const spans = [];
+        const nextFrom = new Map();
+        for (const edit of lineEdits) {
+            const from = nextFrom.get(edit.oldText) ?? 0;
+            const start = findHrefBoundary(src, edit.oldText, from);
+            if (start === -1) {
+                throw new Error(`applyEdits: oldText not found on line ${line}: ${JSON.stringify(edit.oldText)}`);
+            }
+            const end = start + edit.oldText.length;
+            nextFrom.set(edit.oldText, end);
+            spans.push({ start, end, newText: edit.newText });
+        }
+        // Apply right-to-left so an earlier span's indices survive later edits.
+        spans.sort((a, b) => b.start - a.start);
+        let out = src;
+        for (const s of spans)
+            out = out.slice(0, s.start) + s.newText + out.slice(s.end);
+        lines[idx] = out;
+    }
+    return lines.join('\n');
+}
+// ---- Distance / nearest-slug (ported from validate-links.cjs) -------------
+const MAX_SUGGESTION_DISTANCE = 2;
+export function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = new Array(b.length + 1);
+    let curr = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 0; i < a.length; i++) {
+        curr[0] = i + 1;
+        for (let j = 0; j < b.length; j++) {
+            const cost = a[i] === b[j] ? 0 : 1;
+            curr[j + 1] = Math.min(curr[j] + 1, prev[j + 1] + 1, prev[j] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[b.length];
+}
+export function closestSlug(fragment, slugs) {
+    if (!fragment)
+        return null;
+    let best = null;
+    let bestDist = Infinity;
+    let secondDist = Infinity;
+    for (const slug of slugs) {
+        if (Math.abs(fragment.length - slug.length) > MAX_SUGGESTION_DISTANCE)
+            continue;
+        const d = levenshtein(fragment, slug);
+        if (d < bestDist) {
+            secondDist = bestDist;
+            bestDist = d;
+            best = slug;
+        }
+        else if (d < secondDist) {
+            secondDist = d;
+        }
+    }
+    return best !== null && bestDist >= 1 && bestDist <= MAX_SUGGESTION_DISTANCE && bestDist < secondDist
+        ? best
+        : null;
+}
+// ---- Link + locale helpers ------------------------------------------------
+export function parseHref(href) {
+    const i = href.indexOf('#');
+    if (i === -1)
+        return { path: href, fragment: null };
+    return { path: i === 0 ? null : href.slice(0, i), fragment: href.slice(i + 1) || null };
+}
+export function normalizeLinkPath(linkPath, hostAtDocs) {
+    let p = linkPath;
+    if (hostAtDocs && p.startsWith('/docs/'))
+        p = p.slice('/docs/'.length);
+    if (p.startsWith('/'))
+        p = p.slice(1);
+    return p.replace(/\.mdx$/, '');
+}
+/** The default-locale twin of a localized page path, or null if already default. */
+export function defaultTwinPath(pagePath, locales) {
+    const segments = pagePath.split('/');
+    const first = segments[0];
+    if (first !== locales.defaultCode && locales.codes.includes(first)) {
+        return segments.slice(1).join('/');
+    }
+    return null;
+}
+// ---- Broken-link fixer ----------------------------------------------------
+function skip(reason) {
+    return { status: 'skipped', edits: [], reason };
+}
+export const fixBrokenLink = (warning, ctx) => {
+    const { path: linkPath, fragment } = parseHref(warning.link);
+    if (!fragment)
+        return skip('not a fragment link — out of scope for phase 1');
+    if (!linkPath)
+        return skip('same-page fragment — out of scope for phase 1');
+    if (warning.line == null)
+        return skip('warning has no line — cannot place a safe edit');
+    const targetPage = ctx.resolveLinkPagePath(linkPath);
+    if (!targetPage)
+        return skip('target page could not be resolved');
+    const targetHeadings = ctx.headingsOf(targetPage);
+    if (!targetHeadings)
+        return skip('target page headings could not be read');
+    const allIds = targetHeadings.map((h) => h.id);
+    // (0) Re-derivation: may already be valid in current source.
+    if (allIds.includes(fragment))
+        return skip('already valid — fragment exists on target');
+    // Emit only a fragment that is a REAL anchor on the target (never point at a
+    // non-existent or wrong-kind id), reconstructing the href (no substring replace).
+    const emit = (candidate, reason) => {
+        if (!allIds.includes(candidate))
+            return skip('internal: candidate is not a real anchor — refusing');
+        return {
+            status: 'fixed',
+            edits: [{ file: warning.file, line: warning.line, oldText: warning.link, newText: linkPath + '#' + candidate }],
+            reason,
+        };
+    };
+    // (1) Cross-locale positional map FIRST (high precision for localized targets).
+    // Ordinals over MARKDOWN headings only (so <Step>/<Update> can't misalign them),
+    // but the emitted id is the target heading's REAL id (full-set dedup).
+    const twinPage = defaultTwinPath(targetPage, ctx.locales);
+    if (twinPage) {
+        const twinHeadings = ctx.headingsOf(twinPage);
+        if (twinHeadings) {
+            const twinMd = twinHeadings.filter(isMarkdownHeading);
+            const targetMd = targetHeadings.filter(isMarkdownHeading);
+            const ordinal = twinMd.findIndex((h) => h.id === fragment);
+            if (ordinal !== -1 && twinMd.length === targetMd.length && targetMd[ordinal]) {
+                return emit(targetMd[ordinal].id, `cross-locale positional map: #${fragment} → #${targetMd[ordinal].id}`);
+            }
+        }
+    }
+    // (2) Near-miss fallback (typos within the same language).
+    const near = closestSlug(fragment, allIds);
+    if (near)
+        return emit(near, `near-miss: #${fragment} → #${near}`);
+    return skip(`no confident deterministic fix — structures diverge or target is ambiguous ${NEEDS_AI_MARKER}`);
+};
+// ---- Registry + engine entry point ----------------------------------------
+/** Fixer registry keyed by BuildWarningType. Phase 1: broken_link only. */
+export const FIXERS = {
+    broken_link: fixBrokenLink,
+};
+/**
+ * Run the registered fixer for a warning. Deterministic-first is implemented
+ * inside each fixer (exact strategies, then 'skipped' for AI cases). The AI
+ * fallback tier is wired in Phase 2; until then a 'skipped' result is terminal.
+ */
+export function runFixer(warning, ctx) {
+    const fixer = FIXERS[warning.type];
+    if (!fixer)
+        return skip(`no fixer registered for type "${warning.type}"`);
+    return fixer(warning, ctx);
+}
+//# sourceMappingURL=fix-engine.js.map

package/dist/lib/fix-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fix-engine.js","sourceRoot":"","sources":["../../src/lib/fix-engine.ts"],"names":[],"mappings":"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"}

package/dist/lib/frontmatter-write.d.ts

@@ -0,0 +1,4 @@
+/** Set a single frontmatter field, preserving the body. gray-matter round-trips
+ *  via matter.stringify (already used elsewhere in the CLI dep tree). */
+export declare function setFrontmatterField(source: string, key: string, value: string): string;
+//# sourceMappingURL=frontmatter-write.d.ts.map

package/dist/lib/frontmatter-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter-write.d.ts","sourceRoot":"","sources":["../../src/lib/frontmatter-write.ts"],"names":[],"mappings":"AAGA;yEACyE;AACzE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAItF"}

package/dist/lib/frontmatter-write.js

@@ -0,0 +1,10 @@
+// builder/cli/src/lib/frontmatter-write.ts
+import matter from 'gray-matter';
+/** Set a single frontmatter field, preserving the body. gray-matter round-trips
+ *  via matter.stringify (already used elsewhere in the CLI dep tree). */
+export function setFrontmatterField(source, key, value) {
+    const parsed = matter(source);
+    const data = { ...parsed.data, [key]: value };
+    return matter.stringify(parsed.content, data);
+}
+//# sourceMappingURL=frontmatter-write.js.map

package/dist/lib/frontmatter-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter-write.js","sourceRoot":"","sources":["../../src/lib/frontmatter-write.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC;yEACyE;AACzE,MAAM,UAAU,mBAAmB,CAAC,MAAc,EAAE,GAAW,EAAE,KAAa;IAC5E,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,EAAE,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC;IAC9C,OAAO,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AAChD,CAAC"}

package/dist/lib/heading-extractor.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Heading Extractor (slug ids matching rehype-slug / the real DOM).
+ *
+ * AUTO-SYNCED: This file is automatically copied from build-service by vendor.js.
+ * DO NOT EDIT directly - edit builder/build-service/lib/heading-extractor.ts instead.
+ */
+export interface HeadingInfo {
+    id: string;
+    text: string;
+    level: number;
+    line: number;
+    /** When the entry is a <Step> inside a <Steps> block, this is its 1-based index within the block. */
+    stepNumber?: number;
+    /** True when the entry came from an <Update label="..."> anchor (vs a markdown heading). */
+    isUpdate?: boolean;
+}
+/**
+ * Generate a URL-friendly slug from heading text.
+ *
+ * Delegates to github-slugger — the SAME library `rehype-slug` uses to assign the
+ * real heading `id` attributes during MDX compile (wired in render-doc-page.tsx).
+ * Using it here keeps the "On this page" TOC, <Update>/<Step> anchors, and the
+ * link validator byte-for-byte aligned with the actual DOM ids — including for
+ * non-ASCII headings, where the previous `[^a-z0-9]+ -> '-'` implementation
+ * diverged (accents/apostrophes/underscores became dashes) and produced dead
+ * anchors (e.g. heading "Abrir cualquier página" → real id `abrir-cualquier-página`,
+ * but the old slug was `abrir-cualquier-p-gina`).
+ *
+ * Stateless: repeated calls with the same text return the same slug. For
+ * per-document uniqueness across duplicate headings, use a `GithubSlugger`
+ * instance (as extractHeadings does) — it mirrors rehype-slug's `-1`/`-2`
+ * suffixing exactly.
+ *
+ * Mirrored in scripts/validate-links.cjs (CJS — can't import the ESM-only
+ * github-slugger), where the algorithm + regex are replicated and guarded by a
+ * drift test (`validate-links-slug.test.ts`). Keep both in sync.
+ */
+export declare function generateSlug(text: string): string;
+/**
+ * Extract all heading slugs from MDX content.
+ * Includes markdown headings, <Update label="..."> component anchors,
+ * and <Step title="..."> entries inside <Steps> blocks (with per-block numbering).
+ * Skips content inside fenced code blocks.
+ *
+ * A single page-scoped `GithubSlugger` assigns ids so duplicate titles (across
+ * H2s, Update labels, and Steps) get `-1`, `-2`, ... suffixes in source order —
+ * the same algorithm rehype-slug applies to the real markdown-heading DOM ids.
+ */
+export declare function extractHeadings(content: string): HeadingInfo[];
+/**
+ * Build a map of page path -> heading slug set.
+ * Keys are page paths without .mdx extension (matching docs.json navigation format).
+ * Skips API endpoint pages (they generate dynamic anchors at render time).
+ *
+ * Unlike buildHeadingMapFromFiles() in validate-links.cjs, this doesn't add dual
+ * keys for index pages. The CJS validator handles index resolution via
+ * getTargetHeadingSlugs() which derives the key from the filesystem path.
+ *
+ * @param fileContents - Map of relative file paths (with .mdx) to content.
+ *   Keys come from build.ts fileContents Map (e.g., 'getting-started.mdx', 'api/auth.mdx').
+ */
+export declare function buildHeadingMap(fileContents: Map<string, string>): Map<string, Set<string>>;
+//# sourceMappingURL=heading-extractor.d.ts.map

package/dist/lib/heading-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heading-extractor.d.ts","sourceRoot":"","sources":["../../src/lib/heading-extractor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,qGAAqG;IACrG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAqBD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,CAgF9D;AAaD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAU1B"}

package/dist/lib/heading-extractor.js

@@ -0,0 +1,171 @@
+/**
+ * Heading Extractor (slug ids matching rehype-slug / the real DOM).
+ *
+ * AUTO-SYNCED: This file is automatically copied from build-service by vendor.js.
+ * DO NOT EDIT directly - edit builder/build-service/lib/heading-extractor.ts instead.
+ */
+import GithubSlugger, { slug as githubSlug } from 'github-slugger';
+/**
+ * Generate a URL-friendly slug from heading text.
+ *
+ * Delegates to github-slugger — the SAME library `rehype-slug` uses to assign the
+ * real heading `id` attributes during MDX compile (wired in render-doc-page.tsx).
+ * Using it here keeps the "On this page" TOC, <Update>/<Step> anchors, and the
+ * link validator byte-for-byte aligned with the actual DOM ids — including for
+ * non-ASCII headings, where the previous `[^a-z0-9]+ -> '-'` implementation
+ * diverged (accents/apostrophes/underscores became dashes) and produced dead
+ * anchors (e.g. heading "Abrir cualquier página" → real id `abrir-cualquier-página`,
+ * but the old slug was `abrir-cualquier-p-gina`).
+ *
+ * Stateless: repeated calls with the same text return the same slug. For
+ * per-document uniqueness across duplicate headings, use a `GithubSlugger`
+ * instance (as extractHeadings does) — it mirrors rehype-slug's `-1`/`-2`
+ * suffixing exactly.
+ *
+ * Mirrored in scripts/validate-links.cjs (CJS — can't import the ESM-only
+ * github-slugger), where the algorithm + regex are replicated and guarded by a
+ * drift test (`validate-links-slug.test.ts`). Keep both in sync.
+ */
+export function generateSlug(text) {
+    return githubSlug(text);
+}
+const HEADING_REGEX = /^(#{1,6})\s+(.+)$/;
+const FENCE_REGEX = /^(`{3,}|~{3,})/;
+// Global + matchAll (like STEP_TITLE_REGEX below) so multiple inline <Update>
+// tags on one line each get an anchor, and `[^>]*` so `label=` need not be the
+// first attribute (e.g. `<Update date=".." label="..">`). Alternation (not a
+// character class) keeps an apostrophe inside a double-quoted label from
+// terminating the capture. MUST only be used with matchAll — direct test/exec
+// would share lastIndex across calls and miscount.
+const UPDATE_LABEL_REGEX = /<Update\s+[^>]*label=(?:"([^"]+)"|'([^']+)')/g;
+const STEPS_OPEN_REGEX = /<Steps(\s|>)/;
+const STEPS_CLOSE_REGEX = /<\/Steps>/;
+// Global flag — we iterate with matchAll so authors who inline multiple
+// <Step> tags on one line get every one numbered.
+// Alternation (not a character class) keeps the capture from terminating on
+// apostrophes inside double-quoted attribute values (e.g. `<Step title="You're Live">`).
+// MUST only be used with matchAll — direct `test`/`exec` would share
+// lastIndex across calls and miscount.
+const STEP_TITLE_REGEX = /<Step\s+[^>]*title=(?:"([^"]+)"|'([^']+)')/g;
+/**
+ * Extract all heading slugs from MDX content.
+ * Includes markdown headings, <Update label="..."> component anchors,
+ * and <Step title="..."> entries inside <Steps> blocks (with per-block numbering).
+ * Skips content inside fenced code blocks.
+ *
+ * A single page-scoped `GithubSlugger` assigns ids so duplicate titles (across
+ * H2s, Update labels, and Steps) get `-1`, `-2`, ... suffixes in source order —
+ * the same algorithm rehype-slug applies to the real markdown-heading DOM ids.
+ */
+export function extractHeadings(content) {
+    const headings = [];
+    const lines = content.split('\n');
+    let inCodeBlock = false;
+    let fencePattern = '';
+    // Boolean (not depth counter) — resets on every <Steps> open so an unclosed
+    // block can't stick the counter across subsequent blocks.
+    let inStepsBlock = false;
+    let stepCounter = 0;
+    // Page-scoped slugger so duplicate titles get -1, -2, ... suffixes in source
+    // order, matching rehype-slug's per-document GithubSlugger.
+    const slugger = new GithubSlugger();
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const fenceMatch = line.match(FENCE_REGEX);
+        if (fenceMatch) {
+            if (!inCodeBlock) {
+                inCodeBlock = true;
+                fencePattern = fenceMatch[1];
+                continue;
+            }
+            else if (line.startsWith(fencePattern)) {
+                inCodeBlock = false;
+                fencePattern = '';
+                continue;
+            }
+        }
+        if (inCodeBlock)
+            continue;
+        // <Steps> open resets the per-block counter unconditionally. Ordering
+        // matters: open-reset must run BEFORE step matching on the same line so
+        // `<Steps><Step title="A">...</Step>` numbers "A" as 1.
+        if (STEPS_OPEN_REGEX.test(line)) {
+            inStepsBlock = true;
+            stepCounter = 0;
+        }
+        const headingMatch = line.match(HEADING_REGEX);
+        if (headingMatch) {
+            const level = headingMatch[1].length;
+            const text = headingMatch[2].trim();
+            if (generateSlug(text)) {
+                const id = slugger.slug(text);
+                headings.push({ id, text, level, line: i + 1 });
+            }
+        }
+        for (const match of line.matchAll(UPDATE_LABEL_REGEX)) {
+            const text = match[1] ?? match[2];
+            if (!generateSlug(text))
+                continue;
+            const id = slugger.slug(text);
+            headings.push({ id, text, level: 2, line: i + 1, isUpdate: true });
+        }
+        if (inStepsBlock) {
+            for (const match of line.matchAll(STEP_TITLE_REGEX)) {
+                const text = match[1] ?? match[2];
+                if (!generateSlug(text))
+                    continue;
+                stepCounter += 1;
+                const id = slugger.slug(text);
+                headings.push({
+                    id,
+                    text,
+                    level: 3,
+                    line: i + 1,
+                    stepNumber: stepCounter,
+                });
+            }
+        }
+        // </Steps> close runs AFTER step matching so `</Steps>` on the same line
+        // as the last <Step> still picks up that step.
+        if (STEPS_CLOSE_REGEX.test(line)) {
+            inStepsBlock = false;
+        }
+    }
+    return headings;
+}
+/**
+ * Check if MDX content has api: or openapi: in its frontmatter.
+ * API endpoint pages generate dynamic anchor IDs at render time (#param-*, etc.)
+ * that aren't in the MDX source, so fragment validation is skipped for them.
+ */
+function hasApiFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return false;
+    return /^(openapi|api):/m.test(match[1]);
+}
+/**
+ * Build a map of page path -> heading slug set.
+ * Keys are page paths without .mdx extension (matching docs.json navigation format).
+ * Skips API endpoint pages (they generate dynamic anchors at render time).
+ *
+ * Unlike buildHeadingMapFromFiles() in validate-links.cjs, this doesn't add dual
+ * keys for index pages. The CJS validator handles index resolution via
+ * getTargetHeadingSlugs() which derives the key from the filesystem path.
+ *
+ * @param fileContents - Map of relative file paths (with .mdx) to content.
+ *   Keys come from build.ts fileContents Map (e.g., 'getting-started.mdx', 'api/auth.mdx').
+ */
+export function buildHeadingMap(fileContents) {
+    const map = new Map();
+    for (const [filePath, content] of fileContents) {
+        if (hasApiFrontmatter(content))
+            continue;
+        const headings = extractHeadings(content);
+        const slugs = new Set(headings.map((h) => h.id));
+        const pagePath = filePath.replace(/\.mdx$/, '');
+        map.set(pagePath, slugs);
+    }
+    return map;
+}
+//# sourceMappingURL=heading-extractor.js.map

package/dist/lib/heading-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heading-extractor.js","sourceRoot":"","sources":["../../src/lib/heading-extractor.ts"],"names":[],"mappings":"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"}

package/dist/lib/missing-description-scan.d.ts

@@ -0,0 +1,7 @@
+export interface MissingDescription {
+    file: string;
+    title: string;
+    pageText: string;
+}
+export declare function scanMissingDescriptions(pagePaths: string[], readPage: (p: string) => string | null): MissingDescription[];
+//# sourceMappingURL=missing-description-scan.d.ts.map

package/dist/lib/missing-description-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-description-scan.d.ts","sourceRoot":"","sources":["../../src/lib/missing-description-scan.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,kBAAkB;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;CAAE;AAEtF,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EAAE,EACnB,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GACrC,kBAAkB,EAAE,CAetB"}

package/dist/lib/missing-description-scan.js

@@ -0,0 +1,20 @@
+// builder/cli/src/lib/missing-description-scan.ts
+import matter from 'gray-matter';
+export function scanMissingDescriptions(pagePaths, readPage) {
+    const out = [];
+    for (const page of pagePaths) {
+        const src = readPage(page);
+        if (src == null)
+            continue;
+        const parsed = matter(src);
+        const desc = parsed.data.description?.trim();
+        if (desc)
+            continue; // already has one
+        const title = parsed.data.title?.trim() ||
+            parsed.content.match(/^#\s+(.+)$/m)?.[1]?.trim() ||
+            page.split('/').pop() || page;
+        out.push({ file: `${page}.mdx`, title, pageText: parsed.content.trim() });
+    }
+    return out;
+}
+//# sourceMappingURL=missing-description-scan.js.map

package/dist/lib/missing-description-scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-description-scan.js","sourceRoot":"","sources":["../../src/lib/missing-description-scan.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,OAAO,MAAM,MAAM,aAAa,CAAC;AAIjC,MAAM,UAAU,uBAAuB,CACrC,SAAmB,EACnB,QAAsC;IAEtC,MAAM,GAAG,GAAyB,EAAE,CAAC;IACrC,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,GAAG,IAAI,IAAI;YAAE,SAAS;QAC1B,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,IAAI,GAAI,MAAM,CAAC,IAAI,CAAC,WAAkC,EAAE,IAAI,EAAE,CAAC;QACrE,IAAI,IAAI;YAAE,SAAS,CAAC,kBAAkB;QACtC,MAAM,KAAK,GACR,MAAM,CAAC,IAAI,CAAC,KAA4B,EAAE,IAAI,EAAE;YACjD,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE;YAChD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC;QAChC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,IAAI,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.148",
+  "version": "1.1.150",
   "description": "CLI for Jamdesk — build, preview, and deploy documentation sites from MDX. Dev server with hot reload, 50+ components, OpenAPI support, AI search, and Mintlify migration",
   "keywords": [
     "jamdesk",
@@ -128,9 +128,9 @@
   "devDependencies": {
     "@mdx-js/mdx": "^3.1.1",
     "@types/fs-extra": "^11.0.0",
-    "@types/node": "^25.8.0",
+    "@types/node": "^25.9.3",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.9"
   },
   "engines": {
     "node": ">=20.0.0"

package/vendored/components/mdx/Accordion.tsx

@@ -35,6 +35,10 @@ export const Accordion = memo(function Accordion({
 
   return (
     <div className="border border-[var(--color-border)] rounded-lg mb-2 last:mb-0 not-prose overflow-hidden">
+      {/* WAI-ARIA accordion pattern: the heading WRAPS the toggle button. A heading
+          nested inside the button would be pruned from the a11y tree (button name is
+          computed from contents) and flagged by axe — so it goes on the outside. */}
+      <div role="heading" aria-level={3}>
       <button
         type="button"
         onClick={() => setIsOpen(!isOpen)}
@@ -66,7 +70,8 @@ export const Accordion = memo(function Accordion({
           aria-hidden="true"
         />
       </button>
-      
+      </div>
+
       {/* Content */}
       <div
         className={`overflow-hidden transition-all duration-200 ${

package/vendored/components/mdx/ApiEndpoint.tsx

@@ -64,7 +64,7 @@ export function ApiEndpoint({ method, path, baseUrl = 'https://api.jamdesk.com/a
   };
 
   return (
-    <div data-api-endpoint="true" className="flex items-center gap-3 px-3 py-1.5 rounded-xl border border-[var(--color-border)] bg-[var(--color-bg-primary)] mb-4 not-prose">
+    <div data-api-endpoint="true" data-markdown-ignore className="flex items-center gap-3 px-3 py-1.5 rounded-xl border border-[var(--color-border)] bg-[var(--color-bg-primary)] mb-4 not-prose">
       {/* Method badge */}
       <span className={`px-2.5 py-1 text-xs font-bold rounded-md ${colors.bg} ${colors.text}`}>
         {method}

package/vendored/components/mdx/MDXComponents.tsx

@@ -414,7 +414,20 @@ export const MDXComponents = {
     // Check for mermaid diagrams - render with Mermaid component
     if (language === 'mermaid') {
       const diagramCode = extractTextFromChildren(children);
-      return <Mermaid>{diagramCode}</Mermaid>;
+      return (
+        <>
+          <Mermaid>{diagramCode}</Mermaid>
+          {/* Crawler / AI fallback: the client-only SVG leaves the server HTML empty.
+              Use <noscript>, NOT sr-only: a JS-disabled crawler reads it, while users
+              with JS (and screen readers) get the real rendered diagram and never see
+              duplicate text. */}
+          {diagramCode.trim() && (
+            <noscript>
+              <pre>{diagramCode}</pre>
+            </noscript>
+          )}
+        </>
+      );
     }
 
     // Check for HTTP code blocks - render with special styling