@dogsbay/format-starlight 0.2.0-beta.13 → 0.2.0-beta.130

package/dist/cli.js

@@ -3,11 +3,15 @@ import { join, relative, dirname } from "node:path";
 import { parseMeta } from "@dogsbay/types";
 import { starlightToTree as starlightToTreeLegacy, extractFrontmatter } from "./parse.js";
 import { starlightToTree as starlightToTreeMdx } from "./parse-mdx.js";
+import { jsxPropsToJinja, newStats as newJsxStats } from "./jsx-to-jinja.js";
+import { DirectiveTable, escapeStrayOpeners, restoreDirectives } from "./template-tokens.js";
+import { TemplatePages, dogsbayMdToTree, extractHeadings, treeToDogsbayMd } from "@dogsbay/format-dogsbay-md/browser";
 import { cloudflareAdapter } from "./adapters/cloudflare.js";
 import { buildNavFromDirectory, buildNavFromConfig } from "./nav.js";
-const ADAPTERS = {
+export const STARLIGHT_ADAPTERS = {
     cloudflare: cloudflareAdapter,
 };
+const ADAPTERS = STARLIGHT_ADAPTERS;
 /**
  * Detect if a directory contains a Starlight docs source.
  *
@@ -136,22 +140,347 @@ async function importStarlight(source, opts) {
     if (opts.partialsDir) {
         partialsDir = opts.partialsDir;
     }
+    // Where the images live. Found the same way as partialsDir, because it is
+    // the same Astro layout: `src/content/docs` and `src/assets` are siblings
+    // under `src/`.
+    //
+    // Without this the conversion emitted `/_assets/images/x.png` refs and
+    // nothing ever copied a file there — every local image on a converted site
+    // was a 404. The reference survived and the file did not, which is why a
+    // page count, a retention score and a clean exit all looked fine.
+    let assetsDir;
+    searchDir = docsDir;
+    for (let depth = 0; depth < 10; depth++) {
+        const candidate = join(searchDir, "src", "assets");
+        if (existsSync(candidate)) {
+            assetsDir = candidate;
+            break;
+        }
+        const sibling = join(dirname(searchDir), "assets");
+        if (existsSync(sibling)) {
+            assetsDir = sibling;
+            break;
+        }
+        const parent = dirname(searchDir);
+        if (parent === searchDir)
+            break;
+        searchDir = parent;
+    }
+    // Product/brand icons, mounted under `_assets/icons` to match the refs the
+    // adapters emit for them.
+    let iconsDir;
+    searchDir = docsDir;
+    for (let depth = 0; depth < 10; depth++) {
+        const candidate = join(searchDir, "src", "icons");
+        if (existsSync(candidate)) {
+            iconsDir = candidate;
+            break;
+        }
+        const parent = dirname(searchDir);
+        if (parent === searchDir)
+            break;
+        searchDir = parent;
+    }
+    // Component sources, for recovering an accessible description from a
+    // component we cannot render. Same sibling layout as assets and partials.
+    let componentsDir;
+    searchDir = docsDir;
+    for (let depth = 0; depth < 10; depth++) {
+        const candidate = join(searchDir, "src", "components");
+        if (existsSync(candidate)) {
+            componentsDir = candidate;
+            break;
+        }
+        const parent = dirname(searchDir);
+        if (parent === searchDir)
+            break;
+        searchDir = parent;
+    }
+    /**
+     * The `aria-label` (or `<figcaption>`) a component declares about itself.
+     *
+     * Cloudflare's diagrams are Astro components — inline SVG, a web component,
+     * CSS animation — with no image file to carry across. But their `aria-label`
+     * is a full description written by their docs team, and it is the
+     * information the diagram exists to convey. Recovering it turns a silent
+     * hole into a described placeholder; nothing else about the component can
+     * survive a conversion to markdown.
+     */
+    /** `tag\u0000how` → count of conversions to a lesser form. */
+    const degraded = new Map();
+    const DESCRIBED = "its description only: the diagram is drawn by the component";
+    /** Tag → component file, from the site's `src/components.ts` barrel (what `~/components` imports resolve to). */
+    let barrel;
+    let byName;
+    /**
+     * Where the page being parsed imports each component from: a path under
+     * `~/components/` (that file), `null` for the barrel (`~/components`),
+     * or `false` for anywhere else (a package, a relative file) — then no
+     * description is claimed: a same-named file under components/ would be the
+     * WRONG component, and its label would hide the loss as a success.
+     */
+    let pageImports = new Map();
+    const importsOf = (src) => {
+        const map = new Map();
+        for (const m of src.matchAll(/^import\s+(?:(\w+)|\{([^}]*)\})\s+from\s+["']([^"']+)["']/gm)) {
+            const from = m[3];
+            const where = from === "~/components" ? null : from.startsWith("~/components/") && from.endsWith(".astro") ? from.slice("~/components/".length) : false;
+            if (m[1])
+                map.set(m[1], where);
+            for (const n of (m[2] ?? "").split(",")) {
+                const name = n.trim().split(/\s+as\s+/).pop();
+                if (name)
+                    map.set(name, where === false ? false : null);
+            }
+        }
+        return map;
+    };
+    const componentFile = (tag) => {
+        if (!componentsDir)
+            return undefined;
+        const imported = pageImports.get(tag);
+        if (imported === false)
+            return undefined;
+        if (typeof imported === "string") {
+            const f = join(componentsDir, imported);
+            return existsSync(f) ? f : undefined;
+        }
+        if (!barrel) {
+            barrel = new Map();
+            try {
+                const src = readFileSync(join(dirname(componentsDir), "components.ts"), "utf-8");
+                for (const m of src.matchAll(/export\s*\{\s*default\s+as\s+(\w+)\s*\}\s*from\s*["']\.\/components\/([^"']+\.astro)["']/g)) {
+                    barrel.set(m[1], join(componentsDir, m[2]));
+                }
+            }
+            catch {
+                // No barrel: the directory guesses below.
+            }
+        }
+        const candidates = [barrel.get(tag), join(componentsDir, `${tag}.astro`), join(componentsDir, "cf", `${tag}.astro`)];
+        const found = candidates.find((f) => !!f && existsSync(f));
+        if (found)
+            return found;
+        // Imported from the barrel but not in it: nothing to guess.
+        if (imported === null)
+            return undefined;
+        // Pages also import components by PATH (`~/components/realtime/sfu/X.astro`),
+        // outside the barrel: a name unique under components/ is that file.
+        if (!byName) {
+            byName = new Map();
+            const seen = new Set();
+            const walk = (dir) => {
+                for (const e of readdirSync(dir, { withFileTypes: true })) {
+                    const p = join(dir, e.name);
+                    if (e.isDirectory())
+                        walk(p);
+                    else if (e.name.endsWith(".astro")) {
+                        const n = e.name.slice(0, -6);
+                        if (seen.has(n))
+                            byName.delete(n);
+                        else
+                            byName.set(n, p);
+                        seen.add(n);
+                    }
+                }
+            };
+            try {
+                walk(componentsDir);
+            }
+            catch {
+                // An unreadable folder: fewer components described.
+            }
+        }
+        return byName.get(tag);
+    };
+    const describeComponent = (tag) => {
+        const file = componentFile(tag);
+        if (!file)
+            return undefined;
+        const raw = readFileSync(file, "utf-8");
+        // The template only: a string in the frontmatter script is not a label.
+        const fmEnd = raw.startsWith("---") ? raw.indexOf("\n---", 3) : -1;
+        const source = raw.slice(fmEnd < 0 ? 0 : fmEnd + 4);
+        // 20+ characters: a sub-part label ("Tools") must not stand in for the
+        // whole diagram.
+        const aria = source.match(/aria-label="([^"{}]{20,})"/);
+        // A caption may hold markup (`<strong>`, links): its TEXT is the description.
+        const caption = aria ? undefined : source.match(/<figcaption[^>]*>([\s\S]*?)<\/figcaption>/);
+        // `{" "}` and other string literals are text; a dynamic `{…}` is refused
+        // (it would leave "Figure : …"); common entities decoded.
+        const captionSrc = caption?.[1].replace(/\{\s*(["'])([^"']*)\1\s*\}/g, "$2");
+        const captionText = captionSrc && !/[{}]/.test(captionSrc)
+            ? captionSrc
+                .replace(/<[^>]+>/g, "")
+                .replace(/&(mdash|ndash|rsquo|lsquo|rdquo|ldquo|amp|nbsp|hellip|rarr);/g, (_m, e) => ({ mdash: "—", ndash: "–", rsquo: "’", lsquo: "‘", rdquo: "”", ldquo: "“", amp: "&", nbsp: " ", hellip: "…", rarr: "→" })[e])
+            : undefined;
+        const text = (aria?.[1] ?? (captionText && captionText.replace(/\s+/g, " ").trim().length >= 20 ? captionText : undefined))?.replace(/\s+/g, " ").trim();
+        // A placeholder is a loss: reported, not silent (9 uses were).
+        if (text)
+            degraded.set(`${tag}\u0000${DESCRIBED}`, (degraded.get(`${tag}\u0000${DESCRIBED}`) ?? 0) + 1);
+        return text;
+    };
     // Parse all pages
     const mdxFiles = walkMdxFiles(docsDir, docsDir);
     const pages = [];
+    /** Components no builtin or adapter mapping claimed. */
+    const dropped = new Map();
+    const record = (tag, slug) => {
+        const entry = dropped.get(tag) ?? { count: 0, pages: new Set() };
+        entry.count++;
+        entry.pages.add(slug);
+        dropped.set(tag, entry);
+    };
     // Custom taxonomy names from dogsbay.config.yml's `taxonomies:` block
     // (threaded through cli's import-content.ts).
     const taxonomyNames = Array.isArray(opts.taxonomyNames)
         ? opts.taxonomyNames
         : undefined;
+    // Template mode (`--partial-mode template`, plans/page-templates.md):
+    // `<Render>` becomes `{% with %}{% include %}` and each referenced partial
+    // becomes a TEMPLATE partial. Only a Dogsbay-MD output can carry that
+    // (convert refuses other targets); `inline` is the default everywhere.
+    const templateMode = opts.partialMode === "template" && Boolean(partialsDir) && adapter?.resolveIncludes !== undefined;
+    // INLINE mode (the default) for Cloudflare is template mode PLUS rendering:
+    // the same conversion, then every page's includes are rendered in memory
+    // with the shared TemplatePages and the result parsed back. Inline output
+    // therefore equals the template-mode build by construction. (A resolver
+    // that spliced partial MDX into the page left unevaluated conditionals,
+    // stray code blocks and empty tabs.)
+    const inlineMode = !templateMode && opts.partialMode !== "include" && Boolean(partialsDir) && adapter?.name === "cloudflare";
+    const converting = templateMode || inlineMode;
+    // Inline mode (the default) renders each partial in place on the SAME
+    // converter template mode uses (inline-partials.ts).
+    const usedPartials = [];
+    /** Parameter names callers pass to each partial (`product/file`). */
+    const passedParams = new Map();
+    const restoreStats = { escaped: 0, inCode: 0 };
+    const inlined = new Map();
+    let templateIncludes = 0;
+    const apiRequests = { converted: 0, left: 0, missing: new Set() };
+    const apiSchema = loadApiSchema(opts.apiSchema);
+    // The schema is used by the converting modes only (inline, template):
+    // parsed and then silently ignored was the failure mode.
+    if (apiSchema && !converting) {
+        console.warn(`warning: --api-schema is used with the cloudflare adapter and a partials directory, in inline or template partial mode; it was ignored here.`);
+    }
+    const includeOptionsFor = (product, directives, onUse, names, pageDir) => converting
+        ? {
+            mode: "template",
+            pageDir,
+            defaultProduct: product,
+            directives,
+            names,
+            onApiRequest: (converted) => (converted ? apiRequests.converted++ : apiRequests.left++),
+            apiSchema,
+            onApiMissing: (key) => apiRequests.missing.add(key),
+            onDegraded: (tag, how) => {
+                const key = `${tag}\u0000${how}`;
+                degraded.set(key, (degraded.get(key) ?? 0) + 1);
+            },
+            onTemplateInclude: ({ product: p, file, params }) => {
+                templateIncludes++;
+                const key = `${p}/${file}`;
+                usedPartials.push(key);
+                const passed = passedParams.get(key) ?? new Set();
+                for (const n of params)
+                    passed.add(n);
+                passedParams.set(key, passed);
+                onUse?.();
+            },
+            onInlined: ({ reason }) => inlined.set(reason, (inlined.get(reason) ?? 0) + 1),
+        }
+        : undefined;
+    // Include mode splices partial TEXT into the page at parse time, so the
+    // escapes the page's partials wrote count for it too — only the partials
+    // it names (every partial's escapes would excuse leaks on unrelated pages).
+    // Converting modes scan each partial on its own, below.
+    const partialCache = new Map();
+    // A `<ProductChangelog>` page splices changelog ENTRIES into itself: their
+    // escapes count too (`Array\<Number>` in an entry was reported as a leak).
+    let changelogCache;
+    const changelogEscapes = () => {
+        if (changelogCache)
+            return changelogCache;
+        changelogCache = new Map();
+        const dir = partialsDir ? join(dirname(partialsDir), "changelog") : undefined;
+        const walkDir = (d) => {
+            for (const e of readdirSync(d, { withFileTypes: true })) {
+                const p = join(d, e.name);
+                if (e.isDirectory())
+                    walkDir(p);
+                else if (/\.mdx?$/.test(e.name))
+                    for (const n of escapedIn(readFileSync(p, "utf-8")).keys())
+                        changelogCache.set(n, Infinity);
+            }
+        };
+        try {
+            if (dir && existsSync(dir))
+                walkDir(dir);
+        }
+        catch {
+            // Unreadable: fewer escapes excused, never fewer leaks reported.
+        }
+        return changelogCache;
+    };
+    const includedEscapes = (source, product, depth = 0) => {
+        const names = new Map();
+        if (converting || !partialsDir || depth > 8)
+            return names;
+        for (const m of source.matchAll(/<Render\b[^>]*?\bfile=["']([^"']+)["'][^>]*>/g)) {
+            const prod = /\bproduct=["']([^"']+)["']/.exec(m[0])?.[1] ?? product;
+            const path = join(partialsDir, prod, `${m[1]}.mdx`);
+            let found = partialCache.get(path);
+            if (!found) {
+                let text = "";
+                try {
+                    text = readFileSync(path, "utf-8");
+                }
+                catch {
+                    // A missing partial is reported by the include path, not here.
+                }
+                found = escapedIn(text, includedEscapes(text, prod, depth + 1));
+                partialCache.set(path, found);
+            }
+            // A partial can be included more than once: its escapes are not counted.
+            for (const n of found.keys())
+                names.set(n, Infinity);
+        }
+        return names;
+    };
     for (const { filePath, slug } of mdxFiles) {
         const content = readFileSync(filePath, "utf-8");
+        let usesTemplates = false;
+        const directives = new DirectiveTable();
         const { frontmatter, raw, body } = extractFrontmatter(content);
+        pageImports = importsOf(body);
         // Use new MDX parser (markdown-it-mdx-jsx plugin) by default
         // Fall back to legacy regex parser with --legacy-parser flag
         const useLegacy = opts.legacyParser === true;
         const starlightToTree = useLegacy ? starlightToTreeLegacy : starlightToTreeMdx;
-        const tree = starlightToTree(body, { adapter, partialsDir });
+        const tree = starlightToTree(body, {
+            adapter,
+            partialsDir,
+            frontmatter: raw,
+            onDrop: (tag) => record(tag, slug),
+            describeComponent,
+            // A <Render> with no product= means the page's own product: its first path segment.
+            includeOptions: includeOptionsFor(slug.split("/")[0], directives, () => (usesTemplates = true), undefined, dirname(filePath)),
+        });
+        if (usesTemplates)
+            restoreDirectives(tree, directives, restoreStats);
+        // Catch what the callback cannot: a component nested inside a MAPPED
+        // container is not dropped, it LEAKS — its opening tag lands in the page
+        // as visible text and its body often becomes a code block, because nothing
+        // claimed the block. `<LinkTitleCard>` inside `<CardGrid>` did exactly
+        // that on Cloudflare's AI Search overview while the drop warning stayed
+        // silent.
+        //
+        // Scanning the finished tree catches every route into the output, present
+        // and future, in one place. `code` nodes are skipped: a code sample
+        // containing `<Response>` is content, not a leak.
+        for (const tag of leakedComponentTags(tree, escapedIn(body, new Map([...includedEscapes(body, slug.split("/")[0]), ...(body.includes("<ProductChangelog") ? changelogEscapes() : [])]))))
+            record(tag, slug);
         // Extract headings from tree
         const headings = tree
             .filter((n) => n.type === "heading")
@@ -196,7 +525,9 @@ async function importStarlight(source, opts) {
                 ],
             });
         }
-        const title = frontmatter.title || slug;
+        // A template page's title is rendered too: a literal `{{` in it would be syntax.
+        // (Template mode only: in inline mode the page is rendered here and its title never is.)
+        const title = usesTemplates && templateMode ? escapeStrayOpeners(frontmatter.title || slug) : frontmatter.title || slug;
         const meta = parseMeta(raw, { slug, taxonomyNames });
         pages.push({
             slug,
@@ -206,8 +537,164 @@ async function importStarlight(source, opts) {
             redirect,
             frontmatter: raw,
             meta,
+            ...(usesTemplates ? { template: true } : {}),
         });
     }
+    if (converting) {
+        const stats = newJsxStats();
+        const converted = new Set();
+        let undeclaredPassed = 0;
+        const partialPages = [];
+        for (let i = 0; i < usedPartials.length; i++) {
+            const key = usedPartials[i];
+            if (converted.has(key))
+                continue;
+            converted.add(key);
+            const [product, ...rest] = key.split("/");
+            const file = rest.join("/");
+            const source = readFileSync(join(partialsDir, product, `${file}.mdx`), "utf-8");
+            const { raw, body } = extractFrontmatter(source);
+            pageImports = importsOf(body);
+            const names = new Set();
+            const directives = new DirectiveTable();
+            const partialStats = { ...newJsxStats(), names, table: directives };
+            const withoutImports = body.replace(/^import\s+\{[\s\S]*?\}\s+from\s+["'][^"']*["']\s*;?\s*$/gm, "");
+            const jinja = jsxPropsToJinja(withoutImports, partialStats);
+            stats.converted += partialStats.converted;
+            stats.refused += partialStats.refused;
+            for (const s of partialStats.refusedSamples)
+                if (stats.refusedSamples.length < 20)
+                    stats.refusedSamples.push(`${key}: ${s}`);
+            const tree = starlightToTreeMdx(jinja, {
+                adapter,
+                partialsDir,
+                onDrop: (tag) => record(tag, `_partials/${key}`),
+                describeComponent,
+                // Every partial a nested <Render> names is queued for conversion too.
+                // A nested <Render> with no product= is reported, not guessed: in
+                // Cloudflare it takes the product of the PAGE being built.
+                includeOptions: includeOptionsFor(undefined, directives, undefined, names),
+            });
+            restoreDirectives(tree, directives, restoreStats);
+            // Leaks inside a partial count too (they reach every page including it).
+            for (const tag of leakedComponentTags(tree, escapedIn(source)))
+                record(tag, `_partials/${key}`);
+            stats.markdownInlined += partialStats.markdownInlined;
+            // Cloudflare declares `params: [a, b?]` on most partials — the same
+            // syntax template partials use. One that reads props without declaring
+            // them gets every name it reads, as optional (Cloudflare does not
+            // validate those either).
+            const declared = Array.isArray(raw.params) && raw.params.every((p) => typeof p === "string") ? raw.params : undefined;
+            // Declared parameters, plus every `props` name the converted body reads
+            // or forwards, as optional: an undeclared read would otherwise be a
+            // strict-undefined error on every page that does not pass it.
+            const declaredNames = new Set((declared ?? []).map((p) => p.replace(/\?$/, "")));
+            const readOnly = [...names].filter((n) => !declaredNames.has(n)).sort().map((n) => `${n}?`);
+            const baseParams = declared || readOnly.length ? [...(declared ?? []), ...readOnly] : undefined;
+            // Each partial is its own MDX document upstream, so each numbers its
+            // own footnotes from 1; spliced into one page they collided and the
+            // first `[^1]:` won (warp-client/get-started lost its RHEL note).
+            relabelFootnotes(tree, (label) => `${key.split("/").pop().replace(/[^A-Za-z0-9_-]/g, "")}-${label}`);
+            const page = { slug: `_partials/${key}`, title: "", tree, headings: [], fragment: true, template: true };
+            partialPages.push({ key, page, baseParams });
+            pages.push(page);
+        }
+        // Parameters are settled only once every caller is known: a partial may
+        // be converted before another partial, later in the queue, passes it a
+        // name. Names callers pass that a partial does not declare were
+        // tolerated by Cloudflare's build and would be refused by a template
+        // partial, so they are declared as optional — and counted.
+        for (const { key, page, baseParams } of partialPages) {
+            let params = baseParams;
+            if (params) {
+                const known = new Set(params.map((p) => p.replace(/\?$/, "")));
+                const extra = [...(passedParams.get(key) ?? [])].filter((n) => !known.has(n)).sort();
+                if (extra.length) {
+                    params = [...params, ...extra.map((n) => `${n}?`)];
+                    undeclaredPassed += extra.length;
+                }
+            }
+            if (params)
+                page.templateParams = params;
+        }
+        // Inline mode: render each page's includes now, parse the result back,
+        // and drop the partials (they are spliced into the pages).
+        let rendered = 0;
+        const renderFailures = [];
+        if (inlineMode) {
+            const fragments = new Map();
+            for (const { page } of partialPages) {
+                const body = treeToDogsbayMd(page.tree, page.templateParams ? { frontmatter: { params: page.templateParams } } : undefined);
+                // Same hazard as the page reparse below: a partial opening with `---`.
+                fragments.set(`${page.slug}.md`, page.templateParams ? body : `---\n---\n${body}`);
+            }
+            const templates = new TemplatePages({ load: (p) => fragments.get(p), sourceDefault: true });
+            const partialSet = new Set(partialPages.map((p) => p.page));
+            for (let k = pages.length - 1; k >= 0; k--)
+                if (partialSet.has(pages[k]))
+                    pages.splice(k, 1);
+            for (const page of pages) {
+                if (!page.template)
+                    continue;
+                const path = `${page.slug || "index"}.md`;
+                try {
+                    const md = await templates.render(treeToDogsbayMd(page.tree), path, page.frontmatter ?? {});
+                    // An empty front matter block first: a page whose body opens with
+                    // a thematic break (`---`) was otherwise read as front matter, and
+                    // everything up to the next rule vanished (waiting-room/get-started).
+                    page.tree = dogsbayMdToTree(`---\n---\n${md}`).tree;
+                    // Partial labels (`linux-1`) back to 1..n, in order of first reference.
+                    const order = new Map();
+                    collectFootnoteRefs(page.tree, (label) => order.has(label) || order.set(label, String(order.size + 1)));
+                    if (order.size)
+                        relabelFootnotes(page.tree, (label) => order.get(label) ?? label);
+                    page.headings = extractHeadings(page.tree).map((h) => ({ depth: h.depth, text: h.text, slug: h.slug }));
+                    delete page.template;
+                    rendered++;
+                }
+                catch (err) {
+                    renderFailures.push(`${path}: ${err.message.slice(0, 160)}`);
+                }
+            }
+            // A page that did not render keeps directive nodes no exporter but
+            // dogsbay-md emits, and its partials were removed above: its partial
+            // content is simply gone. That must not exit 0 (the rule for includes
+            // everywhere, plans/page-templates.md).
+            if (renderFailures.length && opts.allowMissingIncludes !== true) {
+                throw new Error(`${renderFailures.length} page(s) could not render their partials:\n` +
+                    renderFailures.slice(0, 20).map((f) => `  ${f}`).join("\n") +
+                    "\nRe-run with --allow-missing-includes to write them without that content.");
+            }
+        }
+        const inlinedTotal = [...inlined.values()].reduce((a, b) => a + b, 0);
+        const lines = [
+            inlineMode
+                ? `partials: ${templateIncludes} <Render> converted and rendered in place on ${rendered} page(s), ${converted.size} partial(s)`
+                : `template partials: ${templateIncludes} <Render> → {% include %}, ${converted.size} partial(s) converted`,
+            ...(renderFailures.length ? [`  ${renderFailures.length} page(s) could not be rendered; their partial content is MISSING (--allow-missing-includes):`, ...renderFailures.slice(0, 8).map((f) => `    ${f}`)] : []),
+            `  props expressions: ${stats.converted} converted, ${stats.refused} left as written; ${stats.markdownInlined} <Markdown> wrapper(s) replaced by their text`,
+            `  ${undeclaredPassed} parameter(s) callers pass but partials did not declare, added as optional`,
+            ...(inlineMode ? [] : [`  ${restoreStats.escaped} stray template opener(s) in template pages escaped to print literally`]),
+            ...(apiRequests.converted || apiRequests.left
+                ? [
+                    `  ${apiRequests.converted} <APIRequest> converted to curl ` +
+                        (apiSchema
+                            ? `with titles, auth and permission panels from ${String(opts.apiSchema)} (${apiRequests.missing.size} operation(s) not in it${apiRequests.missing.size ? `: ${[...apiRequests.missing].slice(0, 3).join(", ")}${apiRequests.missing.size > 3 ? ", …" : ""}` : ""}); \`code\` line highlights are not carried`
+                            : "(without the token-permission panel, title and `code` line highlights; the first two come from the OpenAPI schema — pass a local copy with --api-schema)") +
+                        (apiRequests.left ? `; ${apiRequests.left} left as written (props not readable)` : ""),
+                ]
+                : []),
+            ...[...degraded].map(([key, n]) => {
+                const [tag, how] = key.split("\u0000");
+                return `  ${n} <${tag}> converted to a lesser form (${how})`;
+            }),
+            ...(restoreStats.fencesMarked ? [`  ${restoreStats.fencesMarked} code block(s) take a parameter and are marked {minja} so it renders`] : []),
+            ...(restoreStats.inCode ? [`  ${restoreStats.inCode} directive(s) landed inside code and will show literally — check those pages`] : []),
+            ...(inlinedTotal ? [`  ${inlinedTotal} <Render> left as tags or inlined the old way (reported as unmapped):`, ...[...inlined].sort((a, b) => b[1] - a[1]).slice(0, 8).map(([r, n]) => `    ×${n} ${r}`)] : []),
+            ...(stats.refusedSamples.length ? ["  expressions left as written (first few):", ...stats.refusedSamples.slice(0, 8).map((s) => `    ${s}`)] : []),
+        ];
+        console.warn(lines.join("\n"));
+    }
     // Set site name from opts or infer
     if (!opts.siteName && pages.length > 0) {
         const indexPage = pages.find((p) => p.slug === "index" || p.slug === "");
@@ -215,16 +702,194 @@ async function importStarlight(source, opts) {
             opts.siteName = indexPage.title;
         }
     }
-    return { pages, nav };
+    // Say what was dropped, loudly and countably.
+    //
+    // A component nothing claimed is CONTENT THAT IS NOT ON THE PAGE — the
+    // Cloudflare AI Search overview lost its architecture diagram this way, and
+    // the only way anyone found out was comparing the converted page with the
+    // live one by eye. There is no ledger on this path, so the warning IS the
+    // report: it names each tag, how many times it appeared and how many pages
+    // it touched, so `convert … 2>&1 | grep "dropped"` answers "how much of this
+    // corpus does this affect" without reading any output files.
+    if (dropped.size > 0) {
+        const rows = [...dropped.entries()]
+            .sort((a, b) => b[1].count - a[1].count)
+            .map(([tag, d]) => `    <${tag}> ×${d.count} on ${d.pages.size} page(s): ${[...d.pages].slice(0, 3).join(", ")}${d.pages.size > 3 ? ", …" : ""}`);
+        const total = [...dropped.values()].reduce((n, d) => n + d.count, 0);
+        console.warn(`warning: ${total} unmapped component(s) — dropped, or leaked into the ` +
+            `page as literal text:\n${rows.join("\n")}\n` +
+            `  Map them with an adapter, or accept the loss knowingly.`);
+    }
+    return {
+        pages,
+        nav,
+        // Contents land in `public/_assets/`, matching the `/_assets/…` refs the
+        // parser now emits for the `~/assets/` alias.
+        ...(assetsDir || iconsDir
+            ? {
+                assetMounts: [
+                    ...(assetsDir ? [{ dir: assetsDir }] : []),
+                    ...(iconsDir ? [{ dir: iconsDir, into: "icons" }] : []),
+                ],
+            }
+            : {}),
+    };
+}
+/**
+ * Component tags left as literal text/HTML in a finished tree.
+ *
+ * A CamelCase tag only — `<ACCOUNT_ID>` and `<API_TOKEN>` are placeholders the
+ * docs write on purpose, and flagging those would bury the real signal.
+ */
+/** Rename every footnote label in a tree (references and definitions). */
+function relabelFootnotes(nodes, rename) {
+    const walk = (value) => {
+        if (Array.isArray(value))
+            return value.forEach(walk);
+        if (!value || typeof value !== "object")
+            return;
+        const node = value;
+        if (node.type === "footnote-ref" && typeof node.label === "string")
+            node.label = rename(node.label);
+        if (node.type === "footnote-def" && node.props && typeof node.props === "object") {
+            const props = node.props;
+            if (typeof props.label === "string") {
+                const label = rename(props.label);
+                Object.assign(props, { label, id: `fn-${label}`, backrefId: `fnref-${label}` });
+            }
+        }
+        for (const [k, v] of Object.entries(node))
+            if (k !== "props" && typeof v === "object")
+                walk(v);
+    };
+    walk(nodes);
+}
+function collectFootnoteRefs(nodes, visit) {
+    const walk = (value) => {
+        if (Array.isArray(value))
+            return value.forEach(walk);
+        if (!value || typeof value !== "object")
+            return;
+        const node = value;
+        if (node.type === "footnote-ref" && typeof node.label === "string")
+            visit(node.label);
+        for (const [k, v] of Object.entries(node))
+            if (k !== "props" && typeof v === "object")
+                walk(v);
+    };
+    walk(nodes);
+}
+/**
+ * Names the source writes ESCAPED (`Promise\<ArrayBuffer>`), with how many
+ * times: that is prose about a type, rendered as text, and parsed text no
+ * longer shows the backslash. Reporting them was ~40 false leaks
+ * (`<ArrayBuffer>`, `<Response>`, `<CryptoKey>` …) on the Cloudflare corpus.
+ * Each escape excuses ONE text occurrence, so a real leak of the same name
+ * on the page is still reported.
+ */
+function escapedIn(source, also) {
+    const names = new Map(also);
+    // `\<Name` and `&lt;Name` (an entity, decoded to text by the parser: `<code>Promise&lt;WorkflowInstance&gt;</code>`).
+    for (const m of source.matchAll(/(?:\\<|&lt;)\/?([A-Z][A-Za-z0-9]*)/g))
+        names.set(m[1], (names.get(m[1]) ?? 0) + 1);
+    return names;
+}
+function leakedComponentTags(nodes, escapes = new Map()) {
+    const found = [];
+    const excused = new Map(escapes);
+    const scan = (list) => {
+        for (const node of list) {
+            if (node.type === "code" || node.type === "diagram")
+                continue;
+            const inline = (node.inline ?? []).filter((i) => i.type !== "code");
+            // Inline text is JOINED: a multi-line tag arrives as `<APIRequest`, then
+            // a separate newline node, and no single piece matched. Inline raw HTML
+            // is joined too, with text standing in as spaces, and scanned as HTML.
+            const text = inline.map((i) => (i.type === "html-inline" ? " " : (i.text ?? " "))).join("");
+            const html = inline.map((i) => (i.type === "html-inline" ? (i.html ?? "") : " ")).join("");
+            for (const [source, isText] of [[node.html, false], [html, false], [text, true]]) {
+                if (typeof source !== "string")
+                    continue;
+                // Inline code is skipped above: `Promise<Response>` is a type, not a
+                // leaked component (it was 60 false reports).
+                // `</?` — a leak is often only the CLOSING tag, when the opener was
+                // consumed by the container above it but the closer had nothing to
+                // pair with. Matching openers alone missed exactly that case.
+                // A lowercase letter ANYWHERE, not straight after the capital: that
+                // skipped `<APIRequest>` and every other name opening with an acronym,
+                // while the point was only to skip ALL-CAPS placeholders (`<ACCOUNT_ID>`).
+                for (const m of source.matchAll(/<\/?([A-Z][A-Za-z0-9]*[a-z][A-Za-z0-9]*)[\s/>]/g)) {
+                    // Only TEXT is excused by an escape: in raw HTML `<String>` is a tag
+                    // (a backticked `Map<Array<String>>` in a `<td>` is not code there).
+                    const left = excused.get(m[1]) ?? 0;
+                    if (isText && left > 0) {
+                        excused.set(m[1], left - 1);
+                        continue;
+                    }
+                    found.push(m[1]);
+                }
+            }
+            if (node.children)
+                scan(node.children);
+        }
+    };
+    scan(nodes);
+    return found;
+}
+/**
+ * `--api-schema <openapi.json>`: the operations `<APIRequest>` looks up, by
+ * `METHOD /path`. Read as JSON — never fetched, never executed; only the
+ * operation fields the component reads are kept (the file is ~11 MB).
+ */
+function loadApiSchema(file) {
+    if (typeof file !== "string" || !file)
+        return undefined;
+    let doc;
+    try {
+        doc = JSON.parse(readFileSync(file, "utf-8"));
+    }
+    catch (e) {
+        throw new Error(`--api-schema ${file}: not readable as JSON (${e.message})`);
+    }
+    const ops = new Map();
+    for (const [path, item] of Object.entries(doc.paths ?? {})) {
+        for (const [method, raw] of Object.entries(item ?? {})) {
+            if (!["get", "put", "post", "delete", "patch", "head", "options"].includes(method) || !raw || typeof raw !== "object")
+                continue;
+            const o = raw;
+            const security = Array.isArray(o.security) ? o.security.flatMap((r) => (r && typeof r === "object" ? Object.keys(r) : [])) : undefined;
+            const groups = Array.isArray(o["x-api-token-group"]) ? o["x-api-token-group"].filter((g) => typeof g === "string") : undefined;
+            ops.set(`${method.toUpperCase()} ${path}`, {
+                ...(typeof o.summary === "string" ? { summary: o.summary } : {}),
+                ...(security ? { security } : {}),
+                ...(groups ? { tokenGroups: groups } : {}),
+            });
+        }
+    }
+    return ops;
 }
 export const plugin = {
     name: "starlight",
     canImport: true,
     canExport: false,
     detectSource: detectStarlightSource,
-    exportOptions: [
-        { flags: "--adapter <name>", description: "Site adapter for custom components (e.g. cloudflare)" },
+    // importOptions, not exportOptions: this plugin declares `canExport: false`,
+    // so an export-side declaration described a flag on a command that does not
+    // exist — and `convert`'s "unusable flag" warning reads the IMPORT list, so
+    // `--adapter cloudflare` was reported as ignored while being consumed. That
+    // warning is load-bearing on this corpus: the adapter is the difference
+    // between every `<Render>` partial resolving and none of them.
+    importOptions: [
+        {
+            flags: "--adapter <name>",
+            description: `Site adapter for custom components (${Object.keys(STARLIGHT_ADAPTERS).join(", ")})`,
+        },
+        {
+            flags: "--api-schema <file>",
+            description: "Cloudflare: a local copy of the API's OpenAPI schema (openapi.json), for <APIRequest> titles, auth and permission panels",
+        },
     ],
+    exportOptions: [],
     async import(source, opts) {
         return importStarlight(source, opts);
     },