@rightkit/doc-render 0.0.0-stage → 0.1.0

package/dist/detectors/index.js

@@ -0,0 +1,85 @@
+import { CONFIDENCE_THRESHOLD } from "./types";
+import { calloutDetector } from "./callout.js";
+import { frontmatterDetector } from "./frontmatter.js";
+import { stepperDetector } from "./stepper.js";
+import { comparisonDetector } from "./comparison.js";
+import { faqDetector } from "./faq.js";
+import { richTableDetector } from "./richTable.js";
+import { descriptionListDetector } from "./descriptionList.js";
+export * from "./types";
+// Priority order: most specific / least ambiguous first.
+const DETECTORS = [
+    frontmatterDetector,
+    calloutDetector,
+    richTableDetector,
+    faqDetector,
+    descriptionListDetector,
+    comparisonDetector,
+    stepperDetector,
+];
+const HINT_RE = /<!--\s*(?:doc|viewright):\s*(frontmatter|callout|stepper|comparison|faq|richTable|descriptionList)\s*-->/i;
+function parseHint(node) {
+    if (node.type !== "html")
+        return null;
+    const m = HINT_RE.exec(node.value ?? "");
+    return m ? m[1] : null;
+}
+/**
+ * The confidence gate. Walks top-level nodes, runs detectors, and decides per block:
+ *   - hit at/above threshold (or forced by a hint) → semantic component
+ *   - hit below threshold                          → plain markdown (silent fallback)
+ *   - no hit                                       → plain markdown
+ * Returns a flat block list the renderer maps to React.
+ */
+export function buildBlocks(nodes) {
+    const blocks = [];
+    let pendingHint = null;
+    let plainRun = [];
+    const flushPlain = () => {
+        if (plainRun.length) {
+            blocks.push({ kind: "plain", nodes: plainRun });
+            plainRun = [];
+        }
+    };
+    let i = 0;
+    while (i < nodes.length) {
+        const node = nodes[i];
+        const hint = parseHint(node);
+        if (hint) {
+            pendingHint = hint;
+            i += 1; // the hint comment itself never renders
+            continue;
+        }
+        let chosen = null;
+        for (const detect of DETECTORS) {
+            const hit = detect(nodes, i, pendingHint);
+            if (hit && (!chosen || hit.confidence > chosen.confidence || hit.forced)) {
+                chosen = hit;
+                if (hit.forced)
+                    break;
+            }
+        }
+        if (chosen && (chosen.confidence >= CONFIDENCE_THRESHOLD || chosen.forced)) {
+            flushPlain();
+            const startNode = nodes[i];
+            const endNode = nodes[i + chosen.consumed - 1];
+            const start = startNode.position?.start.offset ?? 0;
+            const end = endNode.position?.end.offset ?? startNode.position?.start.offset ?? 0;
+            blocks.push({ kind: "semantic", hit: chosen, position: { start, end } });
+            i += chosen.consumed;
+        }
+        else if (chosen) {
+            // Below threshold: render the nodes the detector eyed as ordinary markdown.
+            for (let k = 0; k < chosen.consumed; k++)
+                plainRun.push(nodes[i + k]);
+            i += chosen.consumed;
+        }
+        else {
+            plainRun.push(node);
+            i += 1;
+        }
+        pendingHint = null;
+    }
+    flushPlain();
+    return blocks;
+}

package/dist/detectors/nodeText.d.ts

@@ -0,0 +1,3 @@
+import type { RootContent } from "mdast";
+/** Flatten the visible text of an mdast node (headings, paragraphs, list items, etc.). */
+export declare function nodeText(node: RootContent | undefined): string;

package/dist/detectors/nodeText.js

@@ -0,0 +1,11 @@
+/** Flatten the visible text of an mdast node (headings, paragraphs, list items, etc.). */
+export function nodeText(node) {
+    if (!node)
+        return "";
+    const anyNode = node;
+    if (typeof anyNode.value === "string")
+        return anyNode.value;
+    if (Array.isArray(anyNode.children))
+        return anyNode.children.map((c) => nodeText(c)).join("");
+    return "";
+}

package/dist/detectors/richTable.d.ts

@@ -0,0 +1,10 @@
+import type { Detector } from "./types";
+export interface RichTableData {
+    headers: string[];
+    rows: string[][];
+    /** Column index → true when every body cell parses as a number (enables sort + bar viz). */
+    numericColumns: boolean[];
+    align: Array<"left" | "right" | "center" | null>;
+}
+/** GFM table → sortable rich table. Always claims a table; confidence reflects how "data-like" it is. */
+export declare const richTableDetector: Detector;

package/dist/detectors/richTable.js

@@ -0,0 +1,35 @@
+import { nodeText } from "./nodeText.js";
+function cells(row) {
+    return row.children.map((c) => nodeText(c).trim());
+}
+function isNumeric(v) {
+    if (v === "")
+        return false;
+    return !Number.isNaN(Number(v.replace(/[,$%\s]/g, "")));
+}
+/** GFM table → sortable rich table. Always claims a table; confidence reflects how "data-like" it is. */
+export const richTableDetector = (nodes, index, hint) => {
+    const node = nodes[index];
+    if (node?.type !== "table")
+        return null;
+    const table = node;
+    const [headRow, ...bodyRows] = table.children;
+    if (!headRow)
+        return null;
+    const headers = cells(headRow);
+    const rows = bodyRows.map(cells);
+    const cols = headers.length;
+    const numericColumns = [];
+    for (let c = 0; c < cols; c++) {
+        const colVals = rows.map((r) => r[c] ?? "");
+        numericColumns[c] = colVals.length > 0 && colVals.every(isNumeric);
+    }
+    const align = (table.align ?? []).map((a) => a ?? null);
+    const data = { headers, rows, numericColumns, align };
+    if (hint === "richTable")
+        return { kind: "richTable", confidence: 1, consumed: 1, data, forced: true };
+    // A table with numeric columns benefits from sort/bars; a tiny 1-row table barely does.
+    const hasNumeric = numericColumns.some(Boolean);
+    const confidence = hasNumeric && rows.length >= 2 ? 0.85 : rows.length >= 2 ? 0.65 : 0.3;
+    return { kind: "richTable", confidence, consumed: 1, data };
+};

package/dist/detectors/stepper.d.ts

@@ -0,0 +1,12 @@
+import type { Detector } from "./types";
+export interface StepperData {
+    title: string | null;
+    steps: string[];
+}
+/**
+ * Stepper: an ordered list, optionally introduced by a process-keyword heading.
+ * - heading + ordered list with a process word → high confidence
+ * - bare ordered list                          → low confidence (gate falls back to plain)
+ * - explicit hint                              → forced
+ */
+export declare const stepperDetector: Detector;

package/dist/detectors/stepper.js

@@ -0,0 +1,58 @@
+import { nodeText } from "./nodeText.js";
+// Process-keyword vocabulary — one signal among several.
+const PROCESS_WORDS = /\b(steps?|how\s*to|guide|recipe|instructions?|setup|set\s*up|process|walkthrough|tutorial|procedure|getting\s+started)\b/i;
+// Imperative verbs that step instructions commonly start with — a strong structural signal
+// that an ordered list is procedural (vs. e.g. a ranked list of nouns).
+const STEP_VERB = /^(add|allow|apply|build|call|change|check|choose|click|clone|close|configure|connect|copy|create|define|delete|deploy|disable|download|edit|enable|enter|export|extract|fill|find|fix|fold|get|go|import|init|insert|install|launch|load|lock|make|mark|merge|move|navigate|open|paste|pick|place|press|pull|push|read|register|reload|remove|rename|repeat|replace|restart|run|save|select|set|ship|start|stop|switch|tap|test|toggle|turn|type|update|upload|use|verify|visit|wait|write)\b/i;
+/**
+ * Stepper: an ordered list, optionally introduced by a process-keyword heading.
+ * - heading + ordered list with a process word → high confidence
+ * - bare ordered list                          → low confidence (gate falls back to plain)
+ * - explicit hint                              → forced
+ */
+export const stepperDetector = (nodes, index, hint) => {
+    let listIndex = index;
+    let heading = null;
+    if (nodes[index]?.type === "heading" && nodes[index + 1]?.type === "list") {
+        heading = nodes[index];
+        listIndex = index + 1;
+    }
+    else if (nodes[index]?.type !== "list") {
+        return null;
+    }
+    const list = nodes[listIndex];
+    if (list.type !== "list" || !list.ordered)
+        return null;
+    const steps = list.children
+        .filter((c) => c.type === "listItem")
+        .map((li) => nodeText(li).trim())
+        .filter(Boolean);
+    if (steps.length < 2)
+        return null;
+    const title = heading ? nodeText(heading).trim() : null;
+    const consumed = heading ? 2 : 1;
+    if (hint === "stepper") {
+        return {
+            kind: "stepper",
+            confidence: 1,
+            consumed,
+            data: { title, steps },
+            forced: true,
+        };
+    }
+    // Multi-signal score: combine independent weak signals rather than a single keyword.
+    const verbRatio = steps.filter((s) => STEP_VERB.test(s)).length / steps.length;
+    let confidence = 0.2; // bare ordered list — below threshold, renders as plain
+    if (title && PROCESS_WORDS.test(title))
+        confidence += 0.45; // process-keyword heading
+    else if (title)
+        confidence += 0.12; // some heading
+    if (verbRatio >= 0.6)
+        confidence += 0.4; // most items start with an imperative verb
+    else if (verbRatio >= 0.3)
+        confidence += 0.2;
+    if (steps.length >= 3)
+        confidence += 0.1; // a real procedure tends to have ≥3 steps
+    confidence = Math.min(confidence, 0.95);
+    return { kind: "stepper", confidence, consumed, data: { title, steps } };
+};

package/dist/detectors/types.d.ts

@@ -0,0 +1,26 @@
+import type { RootContent } from "mdast";
+/** Confidence threshold above which a semantic component renders instead of plain markdown. */
+export declare const CONFIDENCE_THRESHOLD = 0.6;
+export type SemanticKind = "frontmatter" | "callout" | "stepper" | "comparison" | "faq" | "richTable" | "descriptionList";
+/**
+ * A detector inspects a slice of top-level mdast nodes and either claims them
+ * (returning a hit) or declines (returning null → silent fallback to plain markdown).
+ * Detectors are pure: no I/O, no side effects. Fixture-testable in isolation.
+ */
+export interface DetectorHit {
+    kind: SemanticKind;
+    /** 0..1. The gate renders a component only at or above CONFIDENCE_THRESHOLD. */
+    confidence: number;
+    /** How many consecutive top-level nodes (starting at the offered index) this hit consumes. */
+    consumed: number;
+    /** Parsed payload the matching component renders from. */
+    data: unknown;
+    /** True when an explicit `<!-- doc: KIND --> (legacy `viewright:` accepted)` hint forced this hit. */
+    forced?: boolean;
+}
+/**
+ * @param nodes  full list of top-level nodes
+ * @param index  current position to attempt a match at
+ * @param hint   explicit component hint active at this position, if any
+ */
+export type Detector = (nodes: RootContent[], index: number, hint: SemanticKind | null) => DetectorHit | null;

package/dist/detectors/types.js

@@ -0,0 +1,2 @@
+/** Confidence threshold above which a semantic component renders instead of plain markdown. */
+export const CONFIDENCE_THRESHOLD = 0.6;

package/dist/footnotes.d.ts

@@ -0,0 +1,12 @@
+import type { Root, RootContent } from "mdast";
+export interface Footnote {
+    num: number;
+    children: RootContent[];
+}
+export type FootnoteMap = Map<string, Footnote>;
+/** Resolved footnote definitions for the current document, keyed by identifier. */
+export declare const FootnotesContext: import("react").Context<FootnoteMap | null>;
+/** Collect footnote definitions (top-level nodes) and number them in document order. */
+export declare function collectFootnotes(tree: Root): FootnoteMap;
+/** Heading slug matching GitHub's exact algorithm — so anchors match rendered GitHub READMEs. */
+export declare function slug(text: string): string;

package/dist/footnotes.js

@@ -0,0 +1,23 @@
+import { createContext } from "react";
+/** Resolved footnote definitions for the current document, keyed by identifier. */
+export const FootnotesContext = createContext(null);
+/** Collect footnote definitions (top-level nodes) and number them in document order. */
+export function collectFootnotes(tree) {
+    const map = new Map();
+    let n = 0;
+    for (const node of tree.children) {
+        if (node.type === "footnoteDefinition") {
+            const def = node;
+            if (!map.has(def.identifier)) {
+                n += 1;
+                map.set(def.identifier, { num: n, children: def.children ?? [] });
+            }
+        }
+    }
+    return map;
+}
+import { slug as ghSlug } from "github-slugger";
+/** Heading slug matching GitHub's exact algorithm — so anchors match rendered GitHub READMEs. */
+export function slug(text) {
+    return ghSlug(text);
+}

package/dist/headingSlugs.d.ts

@@ -0,0 +1,4 @@
+import type { Root, Heading } from "mdast";
+export type HeadingSlugMap = Map<Heading, string>;
+export declare const HeadingSlugContext: import("react").Context<HeadingSlugMap | null>;
+export declare function buildHeadingSlugs(tree: Root): HeadingSlugMap;

package/dist/headingSlugs.js

@@ -0,0 +1,19 @@
+import { createContext } from "react";
+import GithubSlugger from "github-slugger";
+import { nodeText } from "./detectors/nodeText.js";
+export const HeadingSlugContext = createContext(null);
+export function buildHeadingSlugs(tree) {
+    const slugger = new GithubSlugger();
+    const map = new Map();
+    const walk = (nodes) => {
+        for (const n of nodes) {
+            if (n.type === "heading")
+                map.set(n, slugger.slug(nodeText(n)));
+            const kids = n.children;
+            if (kids)
+                walk(kids);
+        }
+    };
+    walk(tree.children);
+    return map;
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { MarkdownRenderer, HtmlRenderer, renderMarkdown, renderHtml } from "./renderers.js";
+export type { MarkdownRendererProps, HtmlRendererProps } from "./renderers.js";
+export { parseMarkdown, parseToTree, clearMarkdownParseCache, getMarkdownParseCacheEntryCount } from "./parseMarkdown.js";
+export { safeLinkHref, safeImageHref, sanitizeHtml, sanitizeMarkdownHtml, isSafeUri } from "./security.js";
+export { buildHeadingSlugs } from "./headingSlugs.js";
+export { collectFootnotes } from "./footnotes.js";
+export { formatCitation, formatBibliographyEntry, formatNames, formatYear, buildBibliographyMap } from "./citations/formatter.js";
+export type { CslEntry, CslName, BibliographyEntry, CitationMatch } from "./citations/types.js";
+export { buildBlocks } from "./detectors/index.js";
+export type { Block } from "./detectors/index.js";
+export type { Detector, DetectorHit, SemanticKind } from "./detectors/types.js";
+export { remarkCitations } from "./remarkCitations.js";
+export { remarkDefListAbbr } from "./remarkDefListAbbr.js";
+export { remarkWikiLink } from "./remarkWikiLink.js";
+export { resolveShikiLanguage, ensureShikiLanguage, getShikiHighlighter } from "./shikiHighlighter.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+export { MarkdownRenderer, HtmlRenderer, renderMarkdown, renderHtml } from "./renderers.js";
+export { parseMarkdown, parseToTree, clearMarkdownParseCache, getMarkdownParseCacheEntryCount } from "./parseMarkdown.js";
+export { safeLinkHref, safeImageHref, sanitizeHtml, sanitizeMarkdownHtml, isSafeUri } from "./security.js";
+export { buildHeadingSlugs } from "./headingSlugs.js";
+export { collectFootnotes } from "./footnotes.js";
+export { formatCitation, formatBibliographyEntry, formatNames, formatYear, buildBibliographyMap } from "./citations/formatter.js";
+export { buildBlocks } from "./detectors/index.js";
+export { remarkCitations } from "./remarkCitations.js";
+export { remarkDefListAbbr } from "./remarkDefListAbbr.js";
+export { remarkWikiLink } from "./remarkWikiLink.js";
+export { resolveShikiLanguage, ensureShikiLanguage, getShikiHighlighter } from "./shikiHighlighter.js";

package/dist/parseMarkdown.d.ts

@@ -0,0 +1,7 @@
+import type { Root } from "mdast";
+import { type Block } from "./detectors/index.js";
+export declare function parseToTree(source: string): Root;
+export declare function parseMarkdown(source: string): Block[];
+export declare function clearMarkdownParseCache(): void;
+export declare function getMarkdownParseCacheEntryCount(): number;
+export type { Block } from "./detectors/index.js";

package/dist/parseMarkdown.js

@@ -0,0 +1,39 @@
+import { unified } from "unified";
+import remarkFrontmatter from "remark-frontmatter";
+import remarkGfm from "remark-gfm";
+import remarkMath from "remark-math";
+import remarkParse from "remark-parse";
+import remarkSmartypants from "remark-smartypants";
+import { buildBlocks } from "./detectors/index.js";
+import { remarkCitations } from "./remarkCitations.js";
+import { remarkDefListAbbr } from "./remarkDefListAbbr.js";
+import { remarkWikiLink } from "./remarkWikiLink.js";
+const processor = unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkFrontmatter, ["yaml"])
+    .use(remarkMath)
+    .use(remarkWikiLink)
+    .use(remarkDefListAbbr)
+    .use(remarkCitations)
+    .use(remarkSmartypants);
+const cache = new Map();
+const MAX_CACHE = 8;
+export function parseToTree(source) {
+    const cached = cache.get(source);
+    if (cached) {
+        cache.delete(source);
+        cache.set(source, cached);
+        return cached;
+    }
+    const tree = processor.runSync(processor.parse(source));
+    cache.set(source, tree);
+    while (cache.size > MAX_CACHE)
+        cache.delete(cache.keys().next().value);
+    return tree;
+}
+export function parseMarkdown(source) {
+    return buildBlocks(parseToTree(source).children);
+}
+export function clearMarkdownParseCache() { cache.clear(); }
+export function getMarkdownParseCacheEntryCount() { return cache.size; }

package/dist/remarkCitations.d.ts

@@ -0,0 +1,13 @@
+import type { Root } from "mdast";
+export interface CitationNode {
+    type: "citation";
+    key: string;
+    locator?: string;
+    children: [];
+}
+export interface BibliographyNode {
+    type: "bibliography";
+    children: [];
+}
+/** Transform `[@key]` / `[@key p.12]` into citation nodes and `[bibliography]` markers into bibliography blocks. */
+export declare function remarkCitations(): (tree: Root) => void;

package/dist/remarkCitations.js

@@ -0,0 +1,78 @@
+const CITATION_RE = /\[(@([^\]\s]+)(?:\s+([^\]]+))?)\]/g;
+const BIBLIOGRAPHY_RE = /^\s*\[bibliography\]\s*$/i;
+/** Transform `[@key]` / `[@key p.12]` into citation nodes and `[bibliography]` markers into bibliography blocks. */
+export function remarkCitations() {
+    return (tree) => {
+        tree.children = processTopLevel(tree.children);
+    };
+}
+function processTopLevel(children) {
+    const out = [];
+    for (const child of children) {
+        if (child.type === "paragraph" && isBibliographyMarker(child)) {
+            out.push({
+                type: "bibliography",
+                children: [],
+                position: child.position,
+            });
+            continue;
+        }
+        if ("children" in child && Array.isArray(child.children)) {
+            out.push({
+                ...child,
+                children: processChildren(child.children),
+            });
+            continue;
+        }
+        out.push(child);
+    }
+    return out;
+}
+function isBibliographyMarker(node) {
+    const text = (node.children ?? [])
+        .map((child) => (child.type === "text" ? child.value : ""))
+        .join("");
+    return BIBLIOGRAPHY_RE.test(text);
+}
+function processChildren(children) {
+    const out = [];
+    for (const child of children) {
+        if (child.type === "text" && typeof child.value === "string") {
+            const split = splitCitations(child.value);
+            if (split) {
+                out.push(...split);
+                continue;
+            }
+        }
+        if ("children" in child && Array.isArray(child.children)) {
+            out.push({
+                ...child,
+                children: processChildren(child.children),
+            });
+            continue;
+        }
+        out.push(child);
+    }
+    return out;
+}
+function splitCitations(value) {
+    const parts = [];
+    let lastIndex = 0;
+    let match = CITATION_RE.exec(value);
+    while (match !== null) {
+        if (match.index > lastIndex) {
+            parts.push({ type: "text", value: value.slice(lastIndex, match.index) });
+        }
+        const locator = match[3]?.trim();
+        parts.push({ type: "citation", key: match[2] ?? "", locator, children: [] });
+        lastIndex = match.index + match[0].length;
+        CITATION_RE.lastIndex = lastIndex;
+        match = CITATION_RE.exec(value);
+    }
+    if (parts.length === 0)
+        return null;
+    if (lastIndex < value.length) {
+        parts.push({ type: "text", value: value.slice(lastIndex) });
+    }
+    return parts;
+}

package/dist/remarkDefListAbbr.d.ts

@@ -0,0 +1,30 @@
+import type { Root, RootContent, Text } from "mdast";
+export interface DescriptionTerm {
+    type: "descriptionTerm";
+    children: RootContent[];
+}
+export interface DescriptionDetails {
+    type: "descriptionDetails";
+    children: RootContent[];
+}
+export interface DescriptionItem {
+    type: "descriptionItem";
+    terms: DescriptionTerm[];
+    details: DescriptionDetails[];
+}
+export interface DescriptionList {
+    type: "descriptionList";
+    children: DescriptionItem[];
+}
+export interface AbbreviationDefinition {
+    type: "abbreviationDefinition";
+    short: string;
+    long: string;
+}
+export interface Abbr {
+    type: "abbr";
+    title: string;
+    children: Text[];
+}
+/** Transform Pandoc-style definition lists and abbreviation definitions into custom mdast nodes. */
+export declare function remarkDefListAbbr(): (tree: Root) => void;