@cudoment/cudoc 0.4.0 → 0.6.0

package/dist/node/check.js

@@ -9,10 +9,20 @@
  * It resolves through the same code the build uses, so a reference this reports
  * as fine is one the build can resolve.
  */
-import { parseEmbedSpec } from "./resolve-embed.js";
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm";
+import remarkFrontmatter from "remark-frontmatter";
+import remarkMdx from "remark-mdx";
+import { visit } from "unist-util-visit";
+import { capturedImage } from "../document.js";
+import { DEFAULT_TABLE_COLUMNS, buildEmbedRow, extractCell, parseEmbedSpec, resolveDocumentReference, } from "./resolve-embed.js";
+import { compileReplacedSection, replacedSectionSource, sectionText, unreplaceableSection, } from "./replace.js";
 import { collectSections } from "../sections.js";
-import { resolveLocalTarget } from "./local-target.js";
-/** A heading id that a slugger disambiguated, such as `overview-1`. */
+import { isExternalPath, resolveLocalTarget, } from "./local-target.js";
+import { resolveRoots } from "./roots.js";
+import { EXTERNAL_URL, decodeComponent, idsInNode } from "./references.js";
+/** The shape of a heading id a slugger disambiguated, such as `overview-1`. */
 const SUFFIXED = /-\d+$/;
 const walkNodes = (node, visit) => {
     visit(node);
@@ -23,19 +33,46 @@ const walkNodes = (node, visit) => {
  *
  * Both halves matter. The ids answer whether a link resolves; the origin
  * answers whether it will keep resolving, because a generated id depends on how
- * many same-named headings precede it.
+ * many same-named headings precede it. Besides headings, an id an element in
+ * raw HTML declares is an anchor too, and one the author wrote.
  */
 export function collectAnchors(tree) {
     const anchors = [];
     walkNodes(tree, (node) => {
-        if (node.type !== "heading")
+        if (node.type !== "heading") {
+            for (const id of idsInNode(node))
+                if (id)
+                    anchors.push({ id, explicit: true });
             return;
+        }
         const id = node.data?.hProperties?.id;
         if (typeof id === "string" && id)
             anchors.push({ id, explicit: node.data?.cudoc?.explicitId === true });
     });
     return anchors;
 }
+/**
+ * The ids a section can be embedded from: headings only, since an id raw HTML
+ * declares starts no section.
+ */
+const sectionIds = (anchors, tree) => {
+    const headings = new Set();
+    walkNodes(tree, (node) => {
+        const id = node.type === "heading" ? node.data?.hProperties?.id : undefined;
+        if (typeof id === "string" && id)
+            headings.add(id);
+    });
+    return anchors.map((entry) => entry.id).filter((id) => headings.has(id));
+};
+/**
+ * The anchor a fragment names, if the document has it. Hosts percent-encode a
+ * fragment that is not ASCII, so `#개요` may arrive as `#%EA%B0%9C%EC%9A%94`;
+ * either spelling names the same heading.
+ */
+const findAnchor = (anchors, fragment) => {
+    const decoded = decodeComponent(fragment);
+    return anchors.find((entry) => entry.id === fragment || entry.id === decoded);
+};
 /**
  * Where a reference sits in the original Markdown.
  *
@@ -119,6 +156,9 @@ const unportableComponents = (tree) => {
             return;
         if (!node.type.startsWith("mdx") && !node.type.endsWith("Directive"))
             return;
+        // A host's component for a Markdown image renders as that image.
+        if (capturedImage(node))
+            return;
         names.add(node.name ? `<${node.name}>` : node.type);
     });
     return [...names];
@@ -132,14 +172,120 @@ const headingText = (node) => {
     });
     return text;
 };
-/** The line each `cudoc-embed` fence opens on, in source order. */
-const embedFenceLines = (text) => {
-    const lines = [];
-    text.split("\n").forEach((line, index) => {
-        if (/^\s*(?:`{3,}|~{3,})cudoc-embed\s*$/.test(line))
-            lines.push(index + 1);
+/**
+ * The `cudoc-embed` fences of a source, in order, as Markdown parses them: a
+ * fence shown inside a longer fence or an indented code block is example
+ * text, and one inside a quote or a list item is a block like any other. The
+ * source is parsed as Markdown with GFM and front matter, as MDX for an `.mdx`
+ * file.
+ */
+const parsedFences = (text, mdx) => {
+    try {
+        const processor = unified()
+            .use(remarkParse)
+            .use(remarkGfm)
+            .use(remarkFrontmatter);
+        if (mdx)
+            processor.use(remarkMdx);
+        const fences = [];
+        visit(processor.parse(text), "code", (node) => {
+            if (node.lang === "cudoc-embed" && node.position)
+                fences.push({
+                    line: node.position.start.line,
+                    column: node.position.start.column,
+                    value: node.value,
+                });
+        });
+        return fences;
+    }
+    catch {
+        // A host's own syntax may not parse here; the line scan below answers.
+        return undefined;
+    }
+};
+/**
+ * The same fences found line by line: a fence is closed the way Markdown
+ * closes it, by the same character, at least as long, and nothing after it,
+ * and its text is the lines between, less the opening fence's indentation.
+ */
+const scannedFences = (text) => {
+    const found = [];
+    let open;
+    text.split(/\r?\n/).forEach((line, index) => {
+        const match = line.match(/^(\s*)(`{3,}|~{3,})(.*)$/);
+        if (open) {
+            const [, , marker = "", rest = ""] = match ?? [];
+            if (marker[0] === open.char &&
+                marker.length >= open.length &&
+                !rest.trim())
+                open = undefined;
+            else
+                open.content?.push(line.replace(open.indent, ""));
+            return;
+        }
+        if (!match)
+            return;
+        const [, indent = "", marker = "", rest = ""] = match;
+        open = {
+            char: marker[0],
+            length: marker.length,
+            indent: new RegExp(`^ {0,${indent.length}}`),
+        };
+        if (rest.trim().split(/\s+/)[0] !== "cudoc-embed")
+            return;
+        open.content = [];
+        found.push({
+            line: index + 1,
+            column: indent.length + 1,
+            content: open.content,
+        });
     });
-    return lines;
+    return found.map(({ content, ...fence }) => ({
+        ...fence,
+        value: content.join("\n"),
+    }));
+};
+/** Block text as hosts may differ in keeping it: without `\r` or trailing whitespace. */
+const comparable = (value) => value
+    .replace(/\r/g, "")
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .join("\n")
+    .trimEnd();
+/**
+ * The fence of each of a document's embed blocks, given their text in order,
+ * or nothing when neither reading of the source finds those blocks in that
+ * order: a host whose syntax reads a block differently from Markdown would
+ * otherwise put a block's error on another block's fence.
+ */
+const embedFences = (text, mdx, values) => {
+    const wanted = values.map(comparable);
+    const found = (fences) => fences !== undefined &&
+        fences.length === wanted.length &&
+        fences.every((fence, index) => comparable(fence.value) === wanted[index]);
+    const parsed = parsedFences(text, mdx);
+    if (found(parsed))
+        return parsed;
+    const scanned = scannedFences(text);
+    return found(scanned) ? scanned : [];
+};
+/**
+ * Where an error in an embed block sits in the file. The YAML parser counts
+ * from the block's first line and column: the file's line adds the fence's,
+ * and the file's column adds whatever stands before the block's text on that
+ * line, indentation, a quote's `>` or a list item's offset alike. An error
+ * without a coordinate sits on the fence.
+ */
+const blockPosition = (lines, fence, at) => {
+    if (!at)
+        return { line: fence.line, column: fence.column };
+    const line = fence.line + at.line;
+    const source = (lines[line - 1] ?? "").trimEnd();
+    const text = (comparable(fence.value).split("\n")[at.line - 1] ?? "").trimEnd();
+    const before = source.endsWith(text)
+        ? source.length - text.length
+        : fence.column - 1;
+    return { line, column: before + at.col };
 };
 /**
  * Whether a rule finds anything, asked the way the resolver asks it.
@@ -171,11 +317,25 @@ const matchedRules = (slice, rules) => {
     return matched;
 };
 export function checkReferences(library, options = {}) {
-    const sourceRoot = options.sourceRoot ?? library.sourceRoot;
+    const roots = options.roots !== undefined || options.sourceRoot !== undefined
+        ? resolveRoots(options)
+        : library.roots;
+    const targetRoots = {
+        assetDirs: options.assetDirs,
+        withoutBase: options.withoutBase,
+        externalPaths: options.externalPaths,
+    };
     const ignore = new Set(options.ignore ?? []);
     const issues = [];
     let checkedReferences = 0;
+    // Where a copied component can render at all: an MDX host compiles the
+    // spliced nodes with its own component mapping, a Markdown host cannot.
+    const mdxHost = ["next", "docusaurus", "nextra"].includes(library.options.host ?? "");
     const anchorsById = new Map(library.documents.map((doc) => [doc.id, collectAnchors(doc.tree)]));
+    const sectionsById = new Map(library.documents.map((doc) => [
+        doc.id,
+        sectionIds(anchorsById.get(doc.id), doc.tree),
+    ]));
     const byId = new Map(library.documents.map((doc) => [doc.id, doc]));
     const report = (doc, 
     /** A `position` given here wins; otherwise it is recovered from the source. */
@@ -194,11 +354,12 @@ export function checkReferences(library, options = {}) {
     };
     /** Resolves `other.md#anchor` or a bare `#anchor` against the library. */
     const checkDocumentLink = (doc, url) => {
-        const [pathname, anchor] = url.split("#");
+        const [address = "", anchor] = url.split("#");
+        // A query names no other document: `guide/?tab=1` is still `guide/`.
+        const pathname = address.replace(/\?.*$/, "");
         let target = doc;
         if (pathname) {
-            const id = resolveDocumentId(doc, pathname);
-            const found = id === undefined ? undefined : byId.get(id);
+            const found = resolveDocument(doc, pathname);
             if (!found)
                 return false; // not a document link; the asset pass handles it
             target = found;
@@ -206,7 +367,7 @@ export function checkReferences(library, options = {}) {
         if (!anchor)
             return true;
         const anchors = anchorsById.get(target.id) ?? [];
-        const match = anchors.find((entry) => entry.id === anchor);
+        const match = findAnchor(anchors, anchor);
         if (!match) {
             report(doc, {
                 code: "missing-anchor",
@@ -217,7 +378,12 @@ export function checkReferences(library, options = {}) {
             });
             return true;
         }
-        if (!match.explicit && SUFFIXED.test(match.id))
+        // Only a suffix a slugger added is fragile: `## Version 2` is `version-2`
+        // because of its own text, and stays so. A repeat shows as the bare id
+        // being there too.
+        if (!match.explicit &&
+            SUFFIXED.test(match.id) &&
+            anchors.some((entry) => entry.id === match.id.replace(SUFFIXED, "")))
             report(doc, {
                 code: "unstable-anchor-link",
                 severity: "warning",
@@ -227,21 +393,135 @@ export function checkReferences(library, options = {}) {
         return true;
     };
     /**
-     * A link's document id, if it names a document in this library.
+     * The document a link names, if it names one in this library.
      *
      * Hosts do not agree on how a link looks once compiled. Docusaurus and
      * Next.js leave `reference.md`, Nextra drops the extension, and VitePress
      * rewrites it to the deployed `./reference.html`. All three mean the same
-     * document, so any of those endings resolves to the same id.
+     * document, so any of those endings resolves to the same id. A relative
+     * path resolves in the library's coordinates, so it can reach another root
+     * exactly when the bases mirror the directories; a root-relative one names
+     * a library path directly, and then once more with the deployment base
+     * removed, the way the exporter looks a route up.
      */
-    const resolveDocumentId = (doc, pathname) => {
-        if (/^(?:[a-z][\w+.-]*:|\/\/)/i.test(pathname))
+    const resolveDocument = (doc, pathname) => {
+        if (EXTERNAL_URL.test(pathname))
             return undefined;
-        const decoded = decodeURIComponent(pathname);
-        const joined = decoded.startsWith("/")
-            ? decoded.slice(1)
-            : posixJoin(dirname(doc.sourcePath), decoded);
-        return normalize(joined).replace(/\.(?:mdx?|html?)$/i, "");
+        const decoded = decodeComponent(pathname);
+        // A directory, `./` or `guide/` as VitePress writes a link to an
+        // `index.md`, names that directory's index document; spelled with its
+        // trailing slash, it does even beside a `guide.md`.
+        const lookup = (value) => {
+            const normalized = normalize(value);
+            if (normalized === undefined)
+                return undefined;
+            const id = normalized.replace(/\.(?:mdx?|html?)$/i, "");
+            const index = byId.get(normalized ? `${normalized}/index` : "index");
+            if (value === "" || /(?:^|\/)(?:\.\.?)?$/.test(value))
+                return index ?? byId.get(id);
+            return byId.get(id) ?? index;
+        };
+        if (!decoded.startsWith("/"))
+            return lookup(posixJoin(dirname(doc.sourcePath), decoded));
+        const direct = lookup(decoded.slice(1));
+        if (direct || !options.withoutBase)
+            return direct;
+        return lookup(options.withoutBase(decoded).replace(/^\//, ""));
+    };
+    /**
+     * What an embed copies from one selected section: the section as
+     * collected, or, under replacement rules, its rewritten Markdown compiled
+     * again, which is the copy the resolver builds and expands. Without a
+     * synchronous host compiler, which `cudoc check` never has, the standalone
+     * compiler reads the rewritten Markdown with the library's options.
+     *
+     * `undefined` when the copy cannot be built here: the resolver refuses the
+     * rules, the snapshot or a repeated section id, which fails the build on
+     * its own, or the standalone compiler cannot read what only the host's
+     * parser accepts, such as Docusaurus's `{#id}` or an HTML comment in MDX.
+     * The section as collected is not a stand-in, because the rules may have
+     * changed exactly what an inspection looks for, so the caller skips it.
+     * Each copy is compiled once however many inspections and chains read it.
+     */
+    const rewritten = new Map();
+    const copiedTree = (document, section, spec) => {
+        const rules = spec.replace ?? [];
+        if (!rules.length)
+            return section.tree;
+        const includeChildren = spec.select?.includeChildren;
+        const key = JSON.stringify([
+            document.id,
+            section.anchorId ?? null,
+            includeChildren ?? true,
+            rules,
+        ]);
+        if (rewritten.has(key))
+            return rewritten.get(key);
+        let copy;
+        try {
+            copy = compileReplacedSection(library, document, replacedSectionSource(document, section.anchorId, rules, includeChildren), { standalone: true });
+        }
+        catch {
+            copy = undefined;
+        }
+        rewritten.set(key, copy);
+        return copy;
+    };
+    /**
+     * The chain of sections that brings an embed back to itself, as the
+     * resolver would report it, or `undefined`. It follows the embeds inside
+     * each copied section — only those are expanded, after the embed's own
+     * replacement rules have rewritten it — and stops at the depth the
+     * resolver gives up at.
+     */
+    const embedCycle = (spec, from, active) => {
+        for (const source of spec.sources ?? []) {
+            let resolved;
+            try {
+                resolved = resolveDocumentReference(library, String(source), from);
+            }
+            catch {
+                continue; // reported as a missing source
+            }
+            const { document, anchor } = resolved;
+            const key = `${document.id}#${anchor ?? "*"}`;
+            if (active.includes(key) || active.length >= 64)
+                return [...active, key];
+            let sections;
+            try {
+                sections =
+                    anchor || spec.select
+                        ? collectSections(document.tree, {
+                            ...spec.select,
+                            ...(anchor ? { anchors: [anchor] } : {}),
+                        })
+                        : [{ tree: document.tree }];
+            }
+            catch {
+                continue; // reported as a missing section
+            }
+            for (const section of sections) {
+                let found;
+                const copy = copiedTree(document, section, spec);
+                if (!copy)
+                    continue; // what it would expand cannot be told here
+                walkNodes(copy, (node) => {
+                    if (found || node.type !== "code" || node.lang !== "cudoc-embed")
+                        return;
+                    let nested;
+                    try {
+                        nested = parseEmbedSpec(node.value ?? "");
+                    }
+                    catch {
+                        return; // reported where it is written
+                    }
+                    found = embedCycle(nested, document.id, [...active, key]);
+                });
+                if (found)
+                    return found;
+            }
+        }
+        return undefined;
     };
     for (const doc of library.documents) {
         // Anchors the document declares, before anything references them.
@@ -276,7 +556,9 @@ export function checkReferences(library, options = {}) {
                 });
         });
         walkNodes(doc.tree, (node) => {
-            const url = node.type === "link" || node.type === "image" ? node.url : undefined;
+            const captured = capturedImage(node);
+            const image = node.type === "image" || captured !== undefined;
+            const url = node.type === "link" || node.type === "image" ? node.url : captured?.url;
             if (typeof url !== "string" || !url)
                 return;
             // A heading permalink is machinery the host inserted, not something an
@@ -285,31 +567,43 @@ export function checkReferences(library, options = {}) {
             if (node.data?.cudoc?.kind === "permalink")
                 return;
             checkedReferences++;
-            if (/^(?:[a-z][\w+.-]*:|\/\/)/i.test(url))
+            if (EXTERNAL_URL.test(url))
                 return; // external
+            // Another application's path on the same host: nothing here to check.
+            if (isExternalPath(url, options.externalPaths))
+                return;
             if (node.type === "link" && checkDocumentLink(doc, url))
                 return;
             if (url.startsWith("#"))
                 return; // handled above as a same-document anchor
-            if (!sourceRoot)
+            if (!roots)
                 return;
             const target = resolveLocalTarget(url, doc.sourcePath, {
-                ...options,
-                sourceRoot,
+                ...targetRoots,
+                roots,
             });
             if (target.kind === "missing")
                 report(doc, {
-                    code: node.type === "image" ? "missing-asset" : "missing-document",
+                    code: image ? "missing-asset" : "missing-document",
                     severity: "error",
-                    message: node.type === "image"
-                        ? `no file for image ${url}; check sourceRoot and assetDirs`
+                    message: image
+                        ? `no file for image ${url}; check the collection roots and assetDirs`
                         : `no document or file for ${url}`,
                     reference: url,
                 });
         });
         // Fence lines are read from the source because collection strips positions,
         // and they are what turns a YAML error's own coordinate into a file one.
-        const fences = embedFenceLines(doc.source?.text ?? "");
+        const values = [];
+        walkNodes(doc.tree, (node) => {
+            if (node.type === "code" && node.lang === "cudoc-embed")
+                values.push(node.value ?? "");
+        });
+        const sourceText = doc.source?.text ?? "";
+        const fences = values.length
+            ? embedFences(sourceText, doc.source?.format === "mdx", values)
+            : [];
+        const sourceLines = sourceText.split(/\r?\n/);
         let blockNumber = 0;
         walkNodes(doc.tree, (node) => {
             if (node.type !== "code" || node.lang !== "cudoc-embed")
@@ -320,10 +614,8 @@ export function checkReferences(library, options = {}) {
                 spec = parseEmbedSpec(node.value ?? "");
             }
             catch (error) {
-                // The YAML parser counts from the start of the block; an author counts
-                // from the start of the file. Add the fence so both agree.
-                const at = error.linePos?.[0];
-                const line = fence === undefined ? undefined : fence + (at?.line ?? 0);
+                const position = fence &&
+                    blockPosition(sourceLines, fence, error.linePos?.[0]);
                 report(doc, {
                     code: "invalid-embed-spec",
                     severity: "error",
@@ -336,50 +628,67 @@ export function checkReferences(library, options = {}) {
                         .replace(/\s*at line \d+, column \d+:?\s*$/, "")
                         .trim(),
                     reference: `embed block ${blockNumber}`,
-                    position: line === undefined
-                        ? undefined
-                        : {
-                            start: { line, column: at?.col ?? 1 },
-                            end: { line, column: at?.col ?? 1 },
-                        },
+                    position: position && { start: position, end: position },
                 });
                 return;
             }
+            const cycle = embedCycle(spec, doc.id, []);
+            if (cycle)
+                report(doc, {
+                    code: "cyclic-embed",
+                    severity: "error",
+                    message: `embed block ${blockNumber} never finishes: ${cycle.join(" -> ")}. Each embed copies content that embeds the next, back to the first.`,
+                    reference: `embed block ${blockNumber}`,
+                    position: fence && {
+                        start: { line: fence.line, column: fence.column },
+                        end: { line: fence.line, column: fence.column },
+                    },
+                });
             for (const reference of spec.sources ?? []) {
                 checkedReferences++;
-                const [pathname, anchor] = String(reference).split("#");
-                const id = resolveDocumentId(doc, pathname);
-                const target = id === undefined ? undefined : byId.get(id);
-                if (!target) {
+                // The resolver's own reading of the source, so an embed this passes
+                // is one the build can find.
+                let resolved;
+                try {
+                    resolved = resolveDocumentReference(library, String(reference), doc.id);
+                }
+                catch (error) {
                     report(doc, {
                         code: "missing-embed-source",
                         severity: "error",
-                        message: `embed source ${reference} does not name a collected document`,
+                        message: error.message.replace(/^cudoc: /, ""),
                         reference: String(reference),
                     });
                     continue;
                 }
-                const anchors = anchorsById.get(target.id) ?? [];
-                if (anchor && !anchors.some((entry) => entry.id === anchor)) {
+                const { document: target, anchor } = resolved;
+                const sections = sectionsById.get(target.id) ?? [];
+                if (anchor && !sections.includes(anchor)) {
                     report(doc, {
                         code: "missing-embed-anchor",
                         severity: "error",
                         message: `${target.id} has no section #${anchor} to embed`,
                         reference: String(reference),
-                        available: anchors.map((entry) => entry.id),
+                        available: sections,
                     });
                     continue;
                 }
                 // The same selection the resolver will apply, so what is inspected is
-                // what would actually be copied. `select.anchors` can name a section
-                // that does not exist, which `collectSections` rejects; the build hits
-                // the same error, so it is reported rather than swallowed.
-                const selection = anchor ? { anchors: [anchor] } : spec.select;
+                // what would actually be copied: a section named in the source is
+                // combined with `select`, as the resolver combines them. `select`
+                // can name a section that does not exist, which `collectSections`
+                // rejects; the build hits the same error, so it is reported rather
+                // than swallowed.
+                const selection = anchor || spec.select
+                    ? { ...spec.select, ...(anchor ? { anchors: [anchor] } : {}) }
+                    : undefined;
                 let copied;
                 try {
                     copied = selection
                         ? collectSections(target.tree, selection)
                         : [{ anchorId: undefined, tree: target.tree }];
+                    if (!copied.length)
+                        throw new Error("no sections matched");
                 }
                 catch (error) {
                     report(doc, {
@@ -387,26 +696,32 @@ export function checkReferences(library, options = {}) {
                         severity: "error",
                         message: `${target.id}: ${error.message.replace(/^cudoc: /, "")}`,
                         reference: String(reference),
-                        available: anchors.map((entry) => entry.id),
+                        available: sections,
                     });
                     continue;
                 }
                 // Replacement runs on the original Markdown, not the tree, so the
-                // slices are recomputed the way `transformedSection` cuts them. A rule
+                // text is read through `sectionText`, as the resolver reads it. A rule
                 // that matches no slice changed nothing, and the embed silently shows
                 // the source's own wording in a place written to expect otherwise.
                 const rules = spec.replace ?? [];
+                // The resolver refuses rules on a section inside another block whose
+                // text read on its own is not that section, and the build stops there.
+                if (rules.length)
+                    for (const section of copied) {
+                        const problem = unreplaceableSection(target, section.anchorId, spec.select?.includeChildren);
+                        if (problem)
+                            report(doc, {
+                                code: "unreplaceable-embed-section",
+                                severity: "error",
+                                message: problem,
+                                reference: String(reference),
+                            });
+                    }
                 if (rules.length && target.source) {
                     const matched = rules.map(() => false);
                     for (const section of copied) {
-                        const range = section.anchorId
-                            ? target.source.sections[section.anchorId]
-                            : undefined;
-                        const slice = range
-                            ? target.source.text.slice(range.start, spec.select?.includeChildren === false
-                                ? (range.ownEnd ?? range.end)
-                                : range.end)
-                            : target.source.text;
+                        const slice = sectionText(target, section.anchorId, spec.select?.includeChildren);
                         matchedRules(slice, rules).forEach((hit, index) => {
                             if (hit)
                                 matched[index] = true;
@@ -423,19 +738,83 @@ export function checkReferences(library, options = {}) {
                         });
                     });
                 }
-                // A summary table carries heading text and nothing else, so whatever
-                // else the body holds never travels. Replacement above still applies,
-                // because it reaches the title and summary columns.
-                if (typeof spec.render === "object" && spec.render?.type === "table")
+                // What the rest inspects is the copy itself, after the rules above
+                // have rewritten it, as the resolver builds it. A section whose copy
+                // cannot be built here is left out rather than guessed at.
+                const copies = copied.flatMap((section) => {
+                    const tree = copiedTree(target, section, spec);
+                    return tree ? [{ anchorId: section.anchorId, tree }] : [];
+                });
+                // A table carries extracted text and nothing else, so whatever else
+                // the body holds never travels. What can go wrong is a column that
+                // finds nothing in a row: the resolver renders an empty cell, and the
+                // author would only notice by reading the page.
+                if (typeof spec.render === "object" && spec.render?.type === "table") {
+                    const columns = spec.render.columns ?? DEFAULT_TABLE_COLUMNS;
+                    for (const section of copies) {
+                        const row = buildEmbedRow(target, section.anchorId, section.tree);
+                        columns.forEach((column, index) => {
+                            // A shorthand column is best effort: `summary` of a section
+                            // that opens with a table is legitimately blank. A column
+                            // written as a mapping states what every row must have.
+                            if (typeof column === "string")
+                                return;
+                            let problem;
+                            try {
+                                problem = extractCell(library, column, row, {
+                                    documentId: doc.id,
+                                }).problem;
+                            }
+                            catch (error) {
+                                // An extractor the configuration does not register is a
+                                // setting problem, reported once per column like a bad key.
+                                report(doc, {
+                                    code: "invalid-embed-spec",
+                                    severity: "error",
+                                    message: error.message.replace(/^cudoc: /, ""),
+                                    reference: String(reference),
+                                });
+                                return;
+                            }
+                            if (!problem)
+                                return;
+                            const header = typeof column === "string"
+                                ? column
+                                : (column.header ??
+                                    (typeof column.value === "string" ? column.value : ""));
+                            report(doc, {
+                                code: "empty-embed-cell",
+                                severity: "warning",
+                                message: `column ${index + 1}${header ? ` "${header}"` : ""} is empty for the row from ${row.document.id}${row.section.anchorId ? `#${row.section.anchorId}` : ""}: ${problem}`,
+                                reference: String(reference),
+                            });
+                        });
+                    }
                     continue;
+                }
                 const names = [
-                    ...new Set(copied.flatMap((section) => unportableComponents(section.tree))),
+                    ...new Set(copies.flatMap((section) => unportableComponents(section.tree))),
                 ];
                 if (names.length)
                     report(doc, {
                         code: "unportable-embed-component",
                         severity: "warning",
-                        message: `this embed copies ${names.join(", ")} out of ${target.id}. A host that owns those components renders them, but standalone HTML export has no renderer for them and fails. Keep embedded sections to Markdown, or pass a renderer for each name.`,
+                        message: mdxHost
+                            ? `this embed copies ${names.join(", ")} out of ${target.id}. The host renders them where the copy is spliced in, but standalone HTML export has no renderer for them and fails. Keep embedded sections to Markdown, or pass a renderer for each name.`
+                            : `this embed copies ${names.join(", ")} out of ${target.id}. Neither this host nor standalone HTML export can render them. Keep embedded sections to Markdown, or pass a renderer for each name.`,
+                        reference: String(reference),
+                    });
+                // A component the source file imports for itself does not travel
+                // with the copy: the export drops the import, and the embedding
+                // document has no binding for the name unless it imports it too.
+                const orphaned = names
+                    .map((name) => name.replace(/^<|>$/g, "").split(".")[0])
+                    .filter((name) => target.imports?.includes(name) && !doc.imports?.includes(name));
+                if (orphaned.length)
+                    report(doc, {
+                        code: "imported-embed-component",
+                        severity: "error",
+                        message: `this embed copies ${orphaned.map((name) => `<${name}>`).join(", ")} out of ${target.id}, which imports ${orphaned.length === 1 ? "it" : "them"} in its own file. ${doc.id} has no such import, so the spliced copy cannot render ${orphaned.length === 1 ? "it" : "them"}. Provide the component through the host's shared components, import it in ${doc.id} as well, or move it out of the embedded section.`,
                         reference: String(reference),
                     });
             }
@@ -443,22 +822,24 @@ export function checkReferences(library, options = {}) {
     }
     return { issues, documentCount: library.documents.length, checkedReferences };
 }
-// Posix path helpers, kept local so this module stays usable without importing
-// the whole node path surface into a browser-safe boundary by accident.
+// Posix path helpers for library paths, which are always `/`-separated
+// whatever the platform, so `node:path` with its native separators would be
+// the wrong tool even on Node.
 const dirname = (value) => {
     const at = value.lastIndexOf("/");
     return at <= 0 ? "." : value.slice(0, at);
 };
 const posixJoin = (base, value) => base === "." ? value : `${base}/${value}`;
+/** The normalized path, or `undefined` when `..` climbs out of the library. */
 const normalize = (value) => {
     const out = [];
     for (const part of value.split("/")) {
         if (!part || part === ".")
             continue;
-        if (part === "..")
-            out.pop();
-        else
+        if (part !== "..")
             out.push(part);
+        else if (!out.pop())
+            return undefined;
     }
     return out.join("/");
 };