@cudoment/cudoc 0.1.0

package/dist/internal/core/query/nodes.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Reading a stored tree.
+ *
+ * Exporting the AST is only half of what it is for. The other half is a page
+ * that pulls a table, a paragraph or a whole section out of another document
+ * and renders it in place — and that side needs to locate things in a tree it
+ * did not build, without re-parsing the source it came from.
+ *
+ * These are the primitives for that: they answer "which node is next", "where
+ * does this section end", "what does this subtree say". What counts as the
+ * right node for a particular embed stays with the caller, because that is a
+ * documentation-set convention rather than something cudoc can know.
+ */
+import type { Node, Parent } from "unist";
+/** Reading order, not tree depth: `before` walks towards the start. */
+export type Direction = "before" | "after";
+export type FindSiblingOptions = {
+    direction: Direction;
+    /** Node type to accept, such as `"table"`. Any type when omitted. */
+    type?: string;
+    /**
+     * Index the search stops at, exclusive. Usually a section boundary, so a
+     * lookup cannot quietly reach into the next section and return its table.
+     */
+    boundary?: number;
+    /** Further condition, evaluated only on nodes that passed `type`. */
+    accept?: (node: Node) => boolean;
+};
+/**
+ * The nearest sibling in one direction that matches.
+ *
+ * `boundary` is what keeps an embed honest: without it, "the table after this
+ * heading" silently becomes "the next table in the document", and a section
+ * with no table of its own borrows the following section's.
+ */
+export declare const findSiblingNode: <T extends Node = Node>(parent: Parent, index: number, { accept, boundary, direction, type }: FindSiblingOptions) => T | undefined;
+export type NodeTextOptions = {
+    /**
+     * Descend into node types this does not know, such as a host's own JSX
+     * element. On by default, because a stored tree is full of them and dropping
+     * their text silently loses content.
+     */
+    includeUnknown?: boolean;
+    /**
+     * Placed between two blocks. Inline nodes are always joined directly, so a
+     * badge in the middle of a sentence does not split it.
+     */
+    blockSeparator?: string;
+    /** Separates columns when reading a whole Markdown or HTML table row. */
+    tableCellSeparator?: string;
+};
+/**
+ * The visible text of a subtree.
+ *
+ * Blocks are included, unlike `getInlineText`, which stops at phrasing content:
+ * an embed usually wants what a section says, and a section is blocks. They are
+ * separated rather than concatenated, so a heading does not run into the
+ * paragraph beneath it.
+ */
+export declare const getNodeText: (nodes: readonly Node[], options?: NodeTextOptions) => string;
+//# sourceMappingURL=nodes.d.ts.map

package/dist/internal/core/query/nodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes.d.ts","sourceRoot":"","sources":["../../../../src/internal/core/query/nodes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,OAAO,CAAA;AAEzC,uEAAuE;AACvE,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAA;AAE1C,MAAM,MAAM,kBAAkB,GAAG;IAC/B,SAAS,EAAE,SAAS,CAAA;IACpB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,qEAAqE;IACrE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAA;CACjC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,IAAI,GAAG,IAAI,EACnD,QAAQ,MAAM,EACd,OAAO,MAAM,EACb,uCAAuC,kBAAkB,KACxD,CAAC,GAAG,SAoBN,CAAA;AASD,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,yEAAyE;IACzE,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GACtB,OAAO,SAAS,IAAI,EAAE,EACtB,UAAS,eAAoB,KAC5B,MAgBF,CAAA"}

package/dist/internal/core/query/nodes.js

@@ -0,0 +1,151 @@
+/**
+ * Reading a stored tree.
+ *
+ * Exporting the AST is only half of what it is for. The other half is a page
+ * that pulls a table, a paragraph or a whole section out of another document
+ * and renders it in place — and that side needs to locate things in a tree it
+ * did not build, without re-parsing the source it came from.
+ *
+ * These are the primitives for that: they answer "which node is next", "where
+ * does this section end", "what does this subtree say". What counts as the
+ * right node for a particular embed stays with the caller, because that is a
+ * documentation-set convention rather than something cudoc can know.
+ */
+/**
+ * The nearest sibling in one direction that matches.
+ *
+ * `boundary` is what keeps an embed honest: without it, "the table after this
+ * heading" silently becomes "the next table in the document", and a section
+ * with no table of its own borrows the following section's.
+ */
+export const findSiblingNode = (parent, index, { accept, boundary, direction, type }) => {
+    const step = direction === "before" ? -1 : 1;
+    const limit = direction === "before"
+        ? Math.max(boundary ?? -1, -1)
+        : Math.min(boundary ?? parent.children.length, parent.children.length);
+    for (let i = index + step; direction === "before" ? i > limit : i < limit; i += step) {
+        const node = parent.children[i];
+        if (!node)
+            continue;
+        if (type !== undefined && node.type !== type)
+            continue;
+        if (accept && !accept(node))
+            continue;
+        return node;
+    }
+    return undefined;
+};
+const LINE_BREAK_ELEMENTS = new Set(["br"]);
+const isLineBreak = (node) => node.type === "break" ||
+    ((node.type === "mdxJsxTextElement" || node.type === "mdxJsxFlowElement") &&
+        LINE_BREAK_ELEMENTS.has(String(node.name)));
+/**
+ * The visible text of a subtree.
+ *
+ * Blocks are included, unlike `getInlineText`, which stops at phrasing content:
+ * an embed usually wants what a section says, and a section is blocks. They are
+ * separated rather than concatenated, so a heading does not run into the
+ * paragraph beneath it.
+ */
+export const getNodeText = (nodes, options = {}) => {
+    const { blockSeparator = "\n" } = options;
+    let text = "";
+    let previousWasBlock = false;
+    for (const node of nodes) {
+        const part = textOfNode(node, options);
+        if (!part)
+            continue;
+        const block = isBlock(node);
+        if (text && (block || previousWasBlock))
+            text += blockSeparator;
+        text += part;
+        previousWasBlock = block;
+    }
+    return text;
+};
+const textOfNode = (node, options) => {
+    const { includeUnknown = true } = options;
+    if (node.type === "text" ||
+        node.type === "inlineCode" ||
+        node.type === "code") {
+        return String(node.value ?? "");
+    }
+    if (isLineBreak(node))
+        return "\n";
+    if (!hasChildren(node))
+        return "";
+    if (!KNOWN_PARENTS.has(node.type) && !includeUnknown)
+        return "";
+    if (node.type === "tableRow" || elementName(node) === "tr") {
+        return node.children
+            .map((child) => textOfNode(child, options))
+            .join(options.tableCellSeparator ?? "\t");
+    }
+    return getNodeText(node.children, options);
+};
+/** Node types whose children are always part of the text. */
+const KNOWN_PARENTS = new Set([
+    "root",
+    "blockquote",
+    "delete",
+    "emphasis",
+    "heading",
+    "link",
+    "linkReference",
+    "list",
+    "listItem",
+    "paragraph",
+    "strong",
+    "table",
+    "tableCell",
+    "tableRow",
+]);
+/**
+ * Types that occupy a line of their own. Only used to decide where a separator
+ * goes, so an unknown element counts as inline and stays in its sentence.
+ */
+const BLOCK_TYPES = new Set([
+    "blockquote",
+    "code",
+    "definition",
+    "footnoteDefinition",
+    "heading",
+    "html",
+    "list",
+    "listItem",
+    "mdxJsxFlowElement",
+    "mdxjsEsm",
+    "paragraph",
+    "table",
+    "tableRow",
+    "thematicBreak",
+]);
+const BLOCK_ELEMENTS = new Set([
+    "p",
+    "div",
+    "section",
+    "article",
+    "aside",
+    "blockquote",
+    "pre",
+    "ul",
+    "ol",
+    "li",
+    "table",
+    "thead",
+    "tbody",
+    "tfoot",
+    "tr",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+]);
+const elementName = (node) => node.type === "mdxJsxTextElement" || node.type === "mdxJsxFlowElement"
+    ? node.name
+    : undefined;
+const isBlock = (node) => BLOCK_TYPES.has(node.type) || BLOCK_ELEMENTS.has(elementName(node) ?? "");
+const hasChildren = (node) => "children" in node && Array.isArray(node.children);
+//# sourceMappingURL=nodes.js.map

package/dist/internal/core/query/nodes.js.map

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

package/dist/internal/core/query/sections.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Locating and slicing the section a heading introduces.
+ *
+ * This is what an embed is usually after: a page links to
+ * `guide/limits#rate-limits` and wants that section's content, not the whole
+ * document. The anchor id is the right key for it — an author chose it, and it
+ * survives the heading being reworded, which is the entire reason cudoc has
+ * explicit anchors.
+ */
+import type { Heading, Root } from "mdast";
+import type { Parent } from "unist";
+export type AnchorLookupOptions = {
+    /** Element name the id is read from. Matches the heading metadata options. */
+    anchorName?: string;
+    /** Attribute the id is read from. */
+    idAttribute?: string;
+    /** Attribute the badge is read from. */
+    badgeAttribute?: string;
+};
+/**
+ * An id as written in a link: a leading `#` is dropped and percent-encoding is
+ * undone, so `#rate%20limits` and `rate limits` find the same heading.
+ */
+export declare const normalizeAnchorId: (anchorId: string | undefined) => string | undefined;
+/** Reads the anchor id a heading carries, if it has one. */
+export declare const getHeadingAnchorId: (heading: Heading, options?: AnchorLookupOptions) => string | undefined;
+/**
+ * Reads the badge a heading carries.
+ *
+ * It sits in an attribute rather than in the heading's children, so collecting
+ * the heading's text does not find it — which is usually what you want for a
+ * title, and never what you want when the badge is the point.
+ */
+export declare const getHeadingBadge: (heading: Heading, options?: AnchorLookupOptions) => string | undefined;
+export type HeadingLocation = {
+    heading: Heading;
+    parent: Parent;
+    index: number;
+};
+/** Finds the heading carrying `anchorId`, with enough context to slice from. */
+export declare const findHeadingByAnchorId: (tree: Root, anchorId: string, options?: AnchorLookupOptions) => HeadingLocation | undefined;
+/**
+ * The index the section starting at `index` ends at, exclusive.
+ *
+ * A section ends at the next heading of the same depth or shallower, which is
+ * how a reader sees it: an `h3` closes an `h3`, an `h2` closes both.
+ */
+export declare const findSectionEnd: (parent: Parent, index: number, depth: number) => number;
+/** The heading that introduces the section containing the one at `index`. */
+export declare const findParentHeading: (parent: Parent, index: number, depth: number) => Heading | undefined;
+export type SliceSectionOptions = AnchorLookupOptions & {
+    /** Retain the link, image and footnote definitions used by the slice. On by default. */
+    includeDefinitions?: boolean;
+    /**
+     * Prepend the enclosing heading when the target is at this depth or deeper.
+     *
+     * A deep section is often meaningless alone — "Requirements" says nothing
+     * without the API name above it — so an embed can ask for that context. Off
+     * unless a depth is given.
+     */
+    contextHeadingFromDepth?: number;
+};
+/**
+ * The section a heading introduces, as a tree of its own.
+ *
+ * The result keeps the root's `data`, so a stored tree's schema version travels
+ * with the slice and a consumer can still validate what it was handed.
+ * Returns `undefined` when no heading carries the id; the caller knows what a
+ * broken embed reference should do, and it is rarely "throw".
+ */
+export declare const sliceSectionByAnchorId: (tree: Root, anchorId: string, options?: SliceSectionOptions) => Root | undefined;
+//# sourceMappingURL=sections.d.ts.map

package/dist/internal/core/query/sections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sections.d.ts","sourceRoot":"","sources":["../../../../src/internal/core/query/sections.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAGV,OAAO,EACP,IAAI,EAEL,MAAM,OAAO,CAAA;AACd,OAAO,KAAK,EAAQ,MAAM,EAAE,MAAM,OAAO,CAAA;AASzC,MAAM,MAAM,mBAAmB,GAAG;IAChC,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,wCAAwC;IACxC,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC5B,UAAU,MAAM,GAAG,SAAS,KAC3B,MAAM,GAAG,SAUX,CAAA;AAED,4DAA4D;AAC5D,eAAO,MAAM,kBAAkB,GAC7B,SAAS,OAAO,EAChB,UAAS,mBAAwB,KAChC,MAAM,GAAG,SAUX,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAC1B,SAAS,OAAO,EAChB,UAAS,mBAAwB,KAChC,MAAM,GAAG,SAIT,CAAA;AAEH,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,GAChC,MAAM,IAAI,EACV,UAAU,MAAM,EAChB,UAAS,mBAAwB,KAChC,eAAe,GAAG,SAgBpB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GACzB,QAAQ,MAAM,EACd,OAAO,MAAM,EACb,OAAO,MAAM,KACZ,MAMF,CAAA;AAED,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,MAAM,EACd,OAAO,MAAM,EACb,OAAO,MAAM,KACZ,OAAO,GAAG,SAQZ,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG,mBAAmB,GAAG;IACtD,wFAAwF;IACxF,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;;;OAMG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAA;CACjC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,GACjC,MAAM,IAAI,EACV,UAAU,MAAM,EAChB,UAAS,mBAAwB,KAChC,IAAI,GAAG,SA2BT,CAAA"}

package/dist/internal/core/query/sections.js

@@ -0,0 +1,178 @@
+/**
+ * Locating and slicing the section a heading introduces.
+ *
+ * This is what an embed is usually after: a page links to
+ * `guide/limits#rate-limits` and wants that section's content, not the whole
+ * document. The anchor id is the right key for it — an author chose it, and it
+ * survives the heading being reworded, which is the entire reason cudoc has
+ * explicit anchors.
+ */
+import { visit } from "unist-util-visit";
+import { extractAnchorId, findAnchorNode, DEFAULT_ANCHOR_NAME, } from "../syntax/heading-metadata.js";
+import { readStringAttribute } from "../mdx/jsx.js";
+/**
+ * An id as written in a link: a leading `#` is dropped and percent-encoding is
+ * undone, so `#rate%20limits` and `rate limits` find the same heading.
+ */
+export const normalizeAnchorId = (anchorId) => {
+    const trimmed = anchorId?.trim().replace(/^#/, "");
+    if (!trimmed)
+        return undefined;
+    try {
+        return decodeURIComponent(trimmed);
+    }
+    catch {
+        // A malformed escape is not worth failing over; compare it as written.
+        return trimmed;
+    }
+};
+/** Reads the anchor id a heading carries, if it has one. */
+export const getHeadingAnchorId = (heading, options = {}) => {
+    // Hosts and heading-ids put the rendered id here. Prefer it if another
+    // plugin supplied an id that differs from the metadata anchor.
+    const id = heading.data
+        ?.hProperties?.id;
+    if (typeof id === "string" && id)
+        return id;
+    return extractAnchorId(findAnchorNode(heading.children, options.anchorName ?? DEFAULT_ANCHOR_NAME), options.idAttribute ?? "id");
+};
+/**
+ * Reads the badge a heading carries.
+ *
+ * It sits in an attribute rather than in the heading's children, so collecting
+ * the heading's text does not find it — which is usually what you want for a
+ * title, and never what you want when the badge is the point.
+ */
+export const getHeadingBadge = (heading, options = {}) => readStringAttribute(findAnchorNode(heading.children, options.anchorName ?? DEFAULT_ANCHOR_NAME), options.badgeAttribute ?? "badge");
+/** Finds the heading carrying `anchorId`, with enough context to slice from. */
+export const findHeadingByAnchorId = (tree, anchorId, options = {}) => {
+    const target = normalizeAnchorId(anchorId);
+    if (!target)
+        return undefined;
+    let found;
+    visit(tree, "heading", (node, index, parent) => {
+        if (found || typeof index !== "number" || !parent)
+            return;
+        const heading = node;
+        if (normalizeAnchorId(getHeadingAnchorId(heading, options)) !== target) {
+            return;
+        }
+        found = { heading, index, parent: parent };
+    });
+    return found;
+};
+/**
+ * The index the section starting at `index` ends at, exclusive.
+ *
+ * A section ends at the next heading of the same depth or shallower, which is
+ * how a reader sees it: an `h3` closes an `h3`, an `h2` closes both.
+ */
+export const findSectionEnd = (parent, index, depth) => {
+    for (let i = index + 1; i < parent.children.length; i += 1) {
+        const node = parent.children[i];
+        if (node?.type === "heading" && node.depth <= depth)
+            return i;
+    }
+    return parent.children.length;
+};
+/** The heading that introduces the section containing the one at `index`. */
+export const findParentHeading = (parent, index, depth) => {
+    for (let i = index - 1; i >= 0; i -= 1) {
+        const node = parent.children[i];
+        if (node?.type === "heading" && node.depth < depth) {
+            return node;
+        }
+    }
+    return undefined;
+};
+/**
+ * The section a heading introduces, as a tree of its own.
+ *
+ * The result keeps the root's `data`, so a stored tree's schema version travels
+ * with the slice and a consumer can still validate what it was handed.
+ * Returns `undefined` when no heading carries the id; the caller knows what a
+ * broken embed reference should do, and it is rarely "throw".
+ */
+export const sliceSectionByAnchorId = (tree, anchorId, options = {}) => {
+    const location = findHeadingByAnchorId(tree, anchorId, options);
+    if (!location)
+        return undefined;
+    const { heading, index, parent } = location;
+    const { contextHeadingFromDepth } = options;
+    const contextHeading = contextHeadingFromDepth !== undefined &&
+        heading.depth >= contextHeadingFromDepth
+        ? findParentHeading(parent, index, heading.depth)
+        : undefined;
+    const section = parent.children.slice(index, findSectionEnd(parent, index, heading.depth));
+    const children = contextHeading ? [contextHeading, ...section] : section;
+    if (options.includeDefinitions !== false) {
+        appendReferencedDefinitions(tree, children);
+    }
+    return {
+        ...tree,
+        children,
+    };
+};
+// Definitions are document-scoped. A reference inside the slice may be
+// resolved by a definition after the next heading, including a footnote that
+// itself refers to a link or another footnote. Keep only those dependencies.
+const appendReferencedDefinitions = (tree, children) => {
+    const definitions = new Map();
+    const key = (type, identifier) => `${type}:${identifier.toUpperCase()}`;
+    visit(tree, (node) => {
+        if (node.type !== "definition" && node.type !== "footnoteDefinition")
+            return;
+        const id = key(node.type, node.identifier);
+        if (!definitions.has(id))
+            definitions.set(id, node);
+    });
+    // Markdown resolves duplicate definitions to the first one in the full
+    // document. Remove later duplicates from the slice so they cannot take over
+    // when the original first definition is appended below. Clone only affected
+    // parents; never edit the source tree's children.
+    const removeShadowed = (node) => {
+        if (node.type === "definition" || node.type === "footnoteDefinition") {
+            const definition = node;
+            if (definitions.get(key(node.type, definition.identifier)) !== definition)
+                return undefined;
+        }
+        if (!("children" in node) || !Array.isArray(node.children))
+            return node;
+        const original = node.children;
+        const kept = original.flatMap((child) => {
+            const next = removeShadowed(child);
+            return next ? [next] : [];
+        });
+        return kept.length === original.length &&
+            kept.every((child, index) => child === original[index])
+            ? node
+            : { ...node, children: kept };
+    };
+    const retained = children.flatMap((child) => {
+        const next = removeShadowed(child);
+        return next ? [next] : [];
+    });
+    children.splice(0, children.length, ...retained);
+    const included = new Set();
+    visit({ type: "root", children }, (node) => {
+        if (node.type === "definition" || node.type === "footnoteDefinition")
+            included.add(node);
+    });
+    // Appended definitions are visited on later iterations; `included` also
+    // makes cyclic footnote references finite.
+    for (let index = 0; index < children.length; index += 1) {
+        visit(children[index], (node) => {
+            if (node.type !== "linkReference" &&
+                node.type !== "imageReference" &&
+                node.type !== "footnoteReference")
+                return;
+            const type = node.type === "footnoteReference" ? "footnoteDefinition" : "definition";
+            const definition = definitions.get(key(type, node.identifier));
+            if (definition && !included.has(definition)) {
+                included.add(definition);
+                children.push(definition);
+            }
+        });
+    }
+};
+//# sourceMappingURL=sections.js.map

package/dist/internal/core/query/sections.js.map

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

package/dist/internal/core/query/tables.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Reading values out of a table.
+ *
+ * An embed that shows "the method and the endpoint for this API" is reading two
+ * cells of a table in another document. Addressing them by row and column is
+ * blunt, but it is what the document actually offers: a Markdown table has no
+ * field names.
+ */
+import type { CudocTable } from "../ast/types.js";
+import type { Node } from "unist";
+/** A `[row, column]` pair, both zero-based, with the header row as row 0. */
+export type CellPosition = readonly [row: number, column: number];
+/**
+ * The children of each addressed cell, in the order asked for.
+ *
+ * A missing cell yields an empty array rather than throwing: a table that is
+ * one column short is a document problem, and the caller is the one that can
+ * say what to do about it.
+ */
+export declare const getTableCellNodes: (table: CudocTable, positions: readonly CellPosition[]) => Node[][];
+/** The text of each addressed cell, or `undefined` where the cell is empty. */
+export declare const getTableCellText: (table: CudocTable, positions: readonly CellPosition[]) => (string | undefined)[];
+/** The header row's text, for matching a column by name rather than index. */
+export declare const getTableHeaderTexts: (table: CudocTable) => string[];
+/**
+ * The index of the column whose header matches, or -1.
+ *
+ * Comparison collapses whitespace, so a header wrapped across lines in the
+ * source still matches what the author sees.
+ */
+export declare const findTableColumnIndex: (table: CudocTable, headerTexts: readonly string[]) => number;
+//# sourceMappingURL=tables.d.ts.map

package/dist/internal/core/query/tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../../../src/internal/core/query/tables.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAGjC,6EAA6E;AAC7E,MAAM,MAAM,YAAY,GAAG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAEjE;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC5B,OAAO,UAAU,EACjB,WAAW,SAAS,YAAY,EAAE,KACjC,IAAI,EAAE,EAIL,CAAA;AAEJ,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,GAC3B,OAAO,UAAU,EACjB,WAAW,SAAS,YAAY,EAAE,KACjC,CAAC,MAAM,GAAG,SAAS,CAAC,EAInB,CAAA;AAEJ,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,GAAI,OAAO,UAAU,KAAG,MAAM,EAQ7D,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,OAAO,UAAU,EACjB,aAAa,SAAS,MAAM,EAAE,KAC7B,MAIF,CAAA"}

package/dist/internal/core/query/tables.js

@@ -0,0 +1,46 @@
+/**
+ * Reading values out of a table.
+ *
+ * An embed that shows "the method and the endpoint for this API" is reading two
+ * cells of a table in another document. Addressing them by row and column is
+ * blunt, but it is what the document actually offers: a Markdown table has no
+ * field names.
+ */
+import { getNodeText } from "./nodes.js";
+/**
+ * The children of each addressed cell, in the order asked for.
+ *
+ * A missing cell yields an empty array rather than throwing: a table that is
+ * one column short is a document problem, and the caller is the one that can
+ * say what to do about it.
+ */
+export const getTableCellNodes = (table, positions) => positions.map(([row, column]) => {
+    const cell = table.children[row]?.children[column];
+    return cell ? [...cell.children] : [];
+});
+/** The text of each addressed cell, or `undefined` where the cell is empty. */
+export const getTableCellText = (table, positions) => getTableCellNodes(table, positions).map((children) => {
+    const text = getNodeText(children).trim();
+    return text || undefined;
+});
+/** The header row's text, for matching a column by name rather than index. */
+export const getTableHeaderTexts = (table) => {
+    const header = table.children[0];
+    if (!header)
+        return [];
+    return header.children.map((cell) => getNodeText(cell.children)
+        .replace(/\s+/g, " ")
+        .trim());
+};
+/**
+ * The index of the column whose header matches, or -1.
+ *
+ * Comparison collapses whitespace, so a header wrapped across lines in the
+ * source still matches what the author sees.
+ */
+export const findTableColumnIndex = (table, headerTexts) => {
+    const headers = getTableHeaderTexts(table);
+    const wanted = headerTexts.map((text) => text.replace(/\s+/g, " ").trim());
+    return headers.findIndex((header) => wanted.includes(header));
+};
+//# sourceMappingURL=tables.js.map

package/dist/internal/core/query/tables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tables.js","sourceRoot":"","sources":["../../../../src/internal/core/query/tables.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAKxC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,KAAiB,EACjB,SAAkC,EACxB,EAAE,CACZ,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,EAAE;IAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IAClD,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,GAAI,IAAI,CAAC,QAAmB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;AACnD,CAAC,CAAC,CAAA;AAEJ,+EAA+E;AAC/E,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,KAAiB,EACjB,SAAkC,EACV,EAAE,CAC1B,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE;IACnD,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAA;IACzC,OAAO,IAAI,IAAI,SAAS,CAAA;AAC1B,CAAC,CAAC,CAAA;AAEJ,8EAA8E;AAC9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,KAAiB,EAAY,EAAE;IACjE,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;IAChC,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAA;IACtB,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAClC,WAAW,CAAC,IAAI,CAAC,QAAkB,CAAC;SACjC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CACV,CAAA;AACH,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,KAAiB,EACjB,WAA8B,EACtB,EAAE;IACV,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAA;IAC1C,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAA;IAC1E,OAAO,OAAO,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAA;AAC/D,CAAC,CAAA"}

package/dist/internal/core/selectors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Declarative selectors.
+ *
+ * A caller cannot pass a predicate function through a bundler config, so the
+ * conditions a transform needs are described as plain data and evaluated here.
+ */
+import type { Heading, Parent, PhrasingContent } from "mdast";
+import type { AncestorLocation } from "./walk.js";
+/** Concatenates the text of a phrasing subtree, ignoring node kinds. */
+export declare const getInlineText: (nodes: readonly PhrasingContent[]) => string;
+/** Collapses runs of whitespace and lowercases, for tolerant comparison. */
+export declare const normalizeTitle: (value: string) => string;
+/** Drops every space, so a title written with or without one still matches. */
+export declare const compactTitle: (value: string) => string;
+/** Collapses whitespace but keeps case, for exact header matching. */
+export declare const normalizeHeaderText: (value: string) => string;
+/** Identifies a section by the heading that introduces it. */
+export type SectionSelector = {
+    /** Accepted heading depth, or depths. Any depth when omitted. */
+    depth?: number | number[];
+    /** Accepted heading titles. Compared case-insensitively, spacing-tolerant. */
+    titles: string[];
+};
+export declare const assertSectionSelector: (value: unknown, optionPath: string) => SectionSelector;
+/**
+ * Tests a heading against a selector.
+ *
+ * Both a whitespace-normalized and a space-free comparison are accepted, so an
+ * author writing the title with or without an internal space still matches.
+ */
+export declare const matchesSectionHeading: (heading: Heading, selector: SectionSelector, 
+/** Text extractor, so a caller can strip generated nodes first. */
+readText?: (heading: Heading) => string) => boolean;
+/**
+ * Finds the heading that introduces the node at `index`.
+ *
+ * The search continues through ancestors, because a table may sit inside a
+ * container whose own siblings hold the heading.
+ */
+export declare const findPreviousHeading: (parent: Parent, index: number, ancestors?: AncestorLocation[]) => Heading | undefined;
+//# sourceMappingURL=selectors.d.ts.map

package/dist/internal/core/selectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.d.ts","sourceRoot":"","sources":["../../../src/internal/core/selectors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,OAAO,CAAA;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAEjD,wEAAwE;AACxE,eAAO,MAAM,aAAa,GAAI,OAAO,SAAS,eAAe,EAAE,KAAG,MACP,CAAA;AAW3D,4EAA4E;AAC5E,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,MACE,CAAA;AAEjD,+EAA+E;AAC/E,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,MACH,CAAA;AAE1C,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,GAAI,OAAO,MAAM,KAAG,MACjB,CAAA;AAEnC,8DAA8D;AAC9D,MAAM,MAAM,eAAe,GAAG;IAC5B,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACzB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB,CAAA;AAED,eAAO,MAAM,qBAAqB,GAChC,OAAO,OAAO,EACd,YAAY,MAAM,KACjB,eAwBF,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAChC,SAAS,OAAO,EAChB,UAAU,eAAe;AACzB,mEAAmE;AACnE,WAAU,CAAC,OAAO,EAAE,OAAO,KAAK,MACF,KAC7B,OAeF,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,MAAM,EACd,OAAO,MAAM,EACb,YAAW,gBAAgB,EAAO,KACjC,OAAO,GAAG,SAqBZ,CAAA"}