@commentray/render 0.0.2 → 0.0.5

package/dist/block-stretch-layout.d.ts

@@ -0,0 +1,30 @@
+import { type CommentrayIndex } from "@commentray/core";
+import { type CommentrayOutputUrlOptions } from "./markdown-pipeline.js";
+export type BlockStretchTableOptions = {
+    code: string;
+    language: string;
+    commentrayMarkdown: string;
+    index: CommentrayIndex;
+    sourceRelative: string;
+    commentrayPathRel: string;
+    commentrayOutputUrls?: CommentrayOutputUrlOptions;
+};
+export declare function splitCommentrayMarkdownSegments(markdown: string): {
+    preamble: string;
+    segments: {
+        id: string;
+        body: string;
+    }[];
+};
+/**
+ * When index blocks + markdown markers align, builds a two-column table in the spirit of
+ * GitHub **blame**: **one row per block** (plus one row per unmapped source line). The code
+ * and commentary cells share the **same row height** — whichever side is taller sets the
+ * row; the shorter side is top-aligned with natural empty space below inside its cell.
+ * A single outer scroll (`shell--stretch-rows`) keeps both columns in lockstep.
+ */
+export declare function tryBuildBlockStretchTableHtml(opts: BlockStretchTableOptions): Promise<{
+    preambleHtml: string;
+    tableInnerHtml: string;
+} | null>;
+//# sourceMappingURL=block-stretch-layout.d.ts.map

package/dist/block-stretch-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-stretch-layout.d.ts","sourceRoot":"","sources":["../src/block-stretch-layout.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EAGrB,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EAAE,KAAK,0BAA0B,EAAwB,MAAM,wBAAwB,CAAC;AAO/F,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,eAAe,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,CAAC,EAAE,0BAA0B,CAAC;CACnD,CAAC;AAEF,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,MAAM,GAAG;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC1C,CA6BA;AAgBD;;;;;;GAMG;AACH,wBAAsB,6BAA6B,CACjD,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CA8ElE"}

package/dist/block-stretch-layout.js

@@ -0,0 +1,104 @@
+import { MARKER_ID_BODY, buildBlockScrollLinks, } from "@commentray/core";
+import { escapeHtml } from "./html-utils.js";
+import { renderHighlightedCodeLineRows } from "./highlighted-code-lines.js";
+import { renderMarkdownToHtml } from "./markdown-pipeline.js";
+const BLOCK_MARKER_LINE = new RegExp(`^<!--\\s*commentray:block\\s+id=(${MARKER_ID_BODY})\\s*-->$`, "i");
+export function splitCommentrayMarkdownSegments(markdown) {
+    const lines = markdown.split("\n");
+    const preambleLines = [];
+    const segments = [];
+    let seenMarker = false;
+    let currentId = null;
+    const currentBody = [];
+    function flush() {
+        if (currentId !== null) {
+            segments.push({ id: currentId, body: currentBody.join("\n").trimEnd() });
+            currentBody.length = 0;
+        }
+    }
+    for (const line of lines) {
+        const m = BLOCK_MARKER_LINE.exec(line);
+        if (m && m[1] !== undefined) {
+            seenMarker = true;
+            flush();
+            currentId = m[1];
+        }
+        else if (!seenMarker) {
+            preambleLines.push(line);
+        }
+        else {
+            currentBody.push(line);
+        }
+    }
+    flush();
+    return { preamble: preambleLines.join("\n").trimEnd(), segments };
+}
+/** Renders a contiguous 0-based inclusive range of source lines into one stacked column. */
+async function renderCodeLineStack(lines, startLine0, endLine0, language) {
+    const slice = lines.slice(startLine0, endLine0 + 1).join("\n");
+    const inner = await renderHighlightedCodeLineRows(slice, language, {
+        lineIndexOffset: startLine0,
+    });
+    return `<div class="stretch-code-stack">${inner}</div>`;
+}
+/**
+ * When index blocks + markdown markers align, builds a two-column table in the spirit of
+ * GitHub **blame**: **one row per block** (plus one row per unmapped source line). The code
+ * and commentary cells share the **same row height** — whichever side is taller sets the
+ * row; the shorter side is top-aligned with natural empty space below inside its cell.
+ * A single outer scroll (`shell--stretch-rows`) keeps both columns in lockstep.
+ */
+export async function tryBuildBlockStretchTableHtml(opts) {
+    const links = buildBlockScrollLinks(opts.index, opts.sourceRelative, opts.commentrayPathRel, opts.commentrayMarkdown, opts.code);
+    if (links.length === 0)
+        return null;
+    const { preamble, segments } = splitCommentrayMarkdownSegments(opts.commentrayMarkdown);
+    const mdOpts = { commentrayOutputUrls: opts.commentrayOutputUrls };
+    const renderedById = new Map();
+    for (const s of segments) {
+        renderedById.set(s.id, await renderMarkdownToHtml(s.body.trim().length > 0 ? s.body : " ", mdOpts));
+    }
+    const lines = opts.code.split("\n");
+    const lineToBlock = new Map();
+    for (const b of links) {
+        for (let L = b.sourceStart; L <= b.sourceEnd; L++) {
+            lineToBlock.set(L, b);
+        }
+    }
+    const rows = [];
+    let i = 0;
+    while (i < lines.length) {
+        const L = i + 1;
+        const b = lineToBlock.get(L);
+        if (!b) {
+            const codeLineHtml = await renderHighlightedCodeLineRows(lines[i] ?? "", opts.language, {
+                lineIndexOffset: i,
+                omitLineStackWrapper: true,
+            });
+            rows.push(`<tr class="stretch-row stretch-row--gap"><td class="stretch-code">${codeLineHtml}</td>` +
+                `<td class="stretch-doc stretch-doc--gap"><span class="stretch-gap-mark" aria-hidden="true">—</span></td></tr>`);
+            i += 1;
+            continue;
+        }
+        if (i !== b.sourceStart - 1) {
+            throw new Error(`block-stretch desync at 0-based index ${String(i)} (block ${b.id} should start at index ${String(b.sourceStart - 1)})`);
+        }
+        const start0 = b.sourceStart - 1;
+        const end0 = b.sourceEnd - 1;
+        const stackHtml = await renderCodeLineStack(lines, start0, end0, opts.language);
+        const docInner = renderedById.get(b.id) ??
+            `<p class="stretch-doc-missing"><em>No commentary segment for block <code>${escapeHtml(b.id)}</code>.</em></p>`;
+        rows.push(`<tr class="stretch-row stretch-row--block"><td class="stretch-code">${stackHtml}</td>` +
+            `<td class="stretch-doc"><div class="stretch-doc-inner">${docInner}</div></td></tr>`);
+        i = end0 + 1;
+    }
+    const preambleHtml = preamble.trim().length > 0
+        ? `<section class="stretch-preamble" aria-label="Introduction">${await renderMarkdownToHtml(preamble, mdOpts)}</section>`
+        : "";
+    const tableInnerHtml = `<table class="block-stretch pane--code" id="code-pane" role="presentation">` +
+        `<colgroup><col class="stretch-col-code" /><col class="stretch-col-doc" /></colgroup>` +
+        `<tbody>\n${rows.join("\n")}\n</tbody>` +
+        `</table>`;
+    return { preambleHtml, tableInnerHtml };
+}
+//# sourceMappingURL=block-stretch-layout.js.map

package/dist/block-stretch-layout.js.map

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

package/dist/build-commentray-nav-search.d.ts

@@ -0,0 +1,62 @@
+export declare const COMMENTRAY_NAV_SEARCH_SCHEMA_VERSION: 1;
+/** One searchable unit for a future hub or external tooling — never primary source lines. */
+export type CommentrayNavSearchRow = {
+    kind: "sourcePath";
+    sourcePath: string;
+    commentrayPath: string;
+} | {
+    kind: "commentrayPath";
+    sourcePath: string;
+    commentrayPath: string;
+} | {
+    kind: "commentrayLine";
+    sourcePath: string;
+    commentrayPath: string;
+    line: number;
+    text: string;
+};
+/** One indexed source ↔ commentray pair with absolute GitHub blob links for static hub pages. */
+export type DocumentedPairNav = {
+    sourcePath: string;
+    commentrayPath: string;
+    sourceOnGithub: string;
+    commentrayOnGithub: string;
+    /**
+     * When the static Pages build emits per-pair browse HTML (e.g. `_site/browse/…html`), a URL
+     * relative to the site root `index.html` (e.g. `./browse/x.html`) so the hub can open the same
+     * Commentray UI for other files without leaving the site.
+     */
+    staticBrowseUrl?: string;
+};
+export type CommentrayNavSearchDocument = {
+    schemaVersion: typeof COMMENTRAY_NAV_SEARCH_SCHEMA_VERSION;
+    rows: CommentrayNavSearchRow[];
+    /** Present when `githubBlobBase` was passed to the builder — drives the documented-files tree. */
+    documentedPairs?: DocumentedPairNav[];
+};
+export type BuildCommentrayNavSearchFallback = {
+    /** Repo-relative primary path (toolbar / manifest label). */
+    sourcePath: string;
+    /** Repo-relative commentray Markdown path. */
+    commentrayPath: string;
+    /** Absolute path to that Markdown file on disk. */
+    markdownAbs: string;
+};
+export type BuildCommentrayNavSearchGithubBlobBase = {
+    owner: string;
+    repo: string;
+    branch: string;
+};
+/**
+ * Builds a JSON-serialisable search corpus: **filenames / paths** plus **commentray Markdown lines**
+ * for each indexed pair. Primary source file contents are intentionally omitted.
+ *
+ * When `githubBlobBase` is set, `documentedPairs` lists every pair with GitHub **blob** URLs for
+ * the static hub tree and outbound links.
+ *
+ * Pairs are merged from the metadata index, a walk of the configured storage `source` tree for
+ * every `*.md` companion (flat or Angles layout), and an optional single-page `fallback`. For the
+ * same `commentrayPath`, the index wins over disk-inferred paths.
+ */
+export declare function buildCommentrayNavSearchDocument(repoRoot: string, fallback?: BuildCommentrayNavSearchFallback, githubBlobBase?: BuildCommentrayNavSearchGithubBlobBase, storageDir?: string): Promise<CommentrayNavSearchDocument>;
+//# sourceMappingURL=build-commentray-nav-search.d.ts.map

package/dist/build-commentray-nav-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-commentray-nav-search.d.ts","sourceRoot":"","sources":["../src/build-commentray-nav-search.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,oCAAoC,EAAG,CAAU,CAAC;AAE/D,6FAA6F;AAC7F,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GAClE;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GACtE;IACE,IAAI,EAAE,gBAAgB,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEN,iGAAiG;AACjG,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,aAAa,EAAE,OAAO,oCAAoC,CAAC;IAC3D,IAAI,EAAE,sBAAsB,EAAE,CAAC;IAC/B,kGAAkG;IAClG,eAAe,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,gCAAgC,GAAG;IAC7C,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,sCAAsC,GAAG;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAmFF;;;;;;;;;;GAUG;AACH,wBAAsB,gCAAgC,CACpD,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,gCAAgC,EAC3C,cAAc,CAAC,EAAE,sCAAsC,EACvD,UAAU,SAAgB,GACzB,OAAO,CAAC,2BAA2B,CAAC,CAmCtC"}

package/dist/build-commentray-nav-search.js

@@ -0,0 +1,98 @@
+import { readFile } from "node:fs/promises";
+import { discoverCommentrayPairsOnDisk, githubRepoBlobFileUrl, readIndex, resolvePathUnderRepoRoot, } from "@commentray/core";
+export const COMMENTRAY_NAV_SEARCH_SCHEMA_VERSION = 1;
+function buildDocumentedPairs(pairs, gh) {
+    const { owner, repo, branch } = gh;
+    const uniq = new Map();
+    for (const { sourcePath, commentrayPath } of pairs) {
+        const key = `${sourcePath}\0${commentrayPath}`;
+        if (uniq.has(key))
+            continue;
+        uniq.set(key, {
+            sourcePath,
+            commentrayPath,
+            sourceOnGithub: githubRepoBlobFileUrl(owner, repo, branch, sourcePath),
+            commentrayOnGithub: githubRepoBlobFileUrl(owner, repo, branch, commentrayPath),
+        });
+    }
+    return [...uniq.values()].sort((a, b) => a.sourcePath === b.sourcePath
+        ? a.commentrayPath.localeCompare(b.commentrayPath)
+        : a.sourcePath.localeCompare(b.sourcePath));
+}
+function mergeNavSearchPairs(indexPairs, diskPairs, fallback) {
+    const byCr = new Map();
+    for (const p of diskPairs) {
+        byCr.set(p.commentrayPath, { sourcePath: p.sourcePath, commentrayPath: p.commentrayPath });
+    }
+    for (const e of indexPairs) {
+        byCr.set(e.commentrayPath, { sourcePath: e.sourcePath, commentrayPath: e.commentrayPath });
+    }
+    if (fallback !== undefined) {
+        const fp = {
+            sourcePath: fallback.sourcePath,
+            commentrayPath: fallback.commentrayPath,
+        };
+        if (!byCr.has(fp.commentrayPath)) {
+            byCr.set(fp.commentrayPath, fp);
+        }
+    }
+    return [...byCr.values()].sort((a, b) => a.commentrayPath.localeCompare(b.commentrayPath));
+}
+function markdownAbsForMergedPair(repoRoot, pair, fallback) {
+    if (fallback !== undefined &&
+        pair.commentrayPath === fallback.commentrayPath &&
+        pair.sourcePath === fallback.sourcePath) {
+        return fallback.markdownAbs;
+    }
+    return resolvePathUnderRepoRoot(repoRoot, pair.commentrayPath);
+}
+async function appendPairRowsSync(rows, sourcePath, commentrayPath, markdownAbs) {
+    rows.push({ kind: "sourcePath", sourcePath, commentrayPath });
+    rows.push({ kind: "commentrayPath", sourcePath, commentrayPath });
+    try {
+        const md = await readFile(markdownAbs, "utf8");
+        const lines = md.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            rows.push({ kind: "commentrayLine", sourcePath, commentrayPath, line: i, text: lines[i] });
+        }
+    }
+    catch {
+        /* keep path rows when the companion file is missing */
+    }
+}
+/**
+ * Builds a JSON-serialisable search corpus: **filenames / paths** plus **commentray Markdown lines**
+ * for each indexed pair. Primary source file contents are intentionally omitted.
+ *
+ * When `githubBlobBase` is set, `documentedPairs` lists every pair with GitHub **blob** URLs for
+ * the static hub tree and outbound links.
+ *
+ * Pairs are merged from the metadata index, a walk of the configured storage `source` tree for
+ * every `*.md` companion (flat or Angles layout), and an optional single-page `fallback`. For the
+ * same `commentrayPath`, the index wins over disk-inferred paths.
+ */
+export async function buildCommentrayNavSearchDocument(repoRoot, fallback, githubBlobBase, storageDir = ".commentray") {
+    const rows = [];
+    const idx = await readIndex(repoRoot);
+    const indexPairs = idx !== null && Object.keys(idx.byCommentrayPath).length > 0
+        ? Object.entries(idx.byCommentrayPath).map(([crPath, e]) => ({
+            commentrayPath: crPath,
+            sourcePath: e.sourcePath,
+        }))
+        : [];
+    const diskPairs = await discoverCommentrayPairsOnDisk(repoRoot, storageDir);
+    const merged = mergeNavSearchPairs(indexPairs, diskPairs, fallback);
+    if (merged.length === 0) {
+        return { schemaVersion: COMMENTRAY_NAV_SEARCH_SCHEMA_VERSION, rows };
+    }
+    for (const p of merged) {
+        await appendPairRowsSync(rows, p.sourcePath, p.commentrayPath, markdownAbsForMergedPair(repoRoot, p, fallback));
+    }
+    const documentedPairs = githubBlobBase !== undefined ? buildDocumentedPairs(merged, githubBlobBase) : undefined;
+    return {
+        schemaVersion: COMMENTRAY_NAV_SEARCH_SCHEMA_VERSION,
+        rows,
+        ...(documentedPairs ? { documentedPairs } : {}),
+    };
+}
+//# sourceMappingURL=build-commentray-nav-search.js.map

package/dist/build-commentray-nav-search.js.map

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

package/dist/build-stamp.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Human-readable “when was this HTML built” line for static pages, using the
+ * **Node process** local timezone and a zone name/offset from `Intl` (not UTC-only).
+ */
+export declare function formatCommentrayBuiltAtLocal(date: Date): string;
+//# sourceMappingURL=build-stamp.d.ts.map

package/dist/build-stamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-stamp.d.ts","sourceRoot":"","sources":["../src/build-stamp.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAgB/D"}

package/dist/build-stamp.js

@@ -0,0 +1,23 @@
+/**
+ * Human-readable “when was this HTML built” line for static pages, using the
+ * **Node process** local timezone and a zone name/offset from `Intl` (not UTC-only).
+ */
+export function formatCommentrayBuiltAtLocal(date) {
+    try {
+        return new Intl.DateTimeFormat(undefined, {
+            weekday: "short",
+            year: "numeric",
+            month: "short",
+            day: "numeric",
+            hour: "2-digit",
+            minute: "2-digit",
+            second: "2-digit",
+            hour12: false,
+            timeZoneName: "longOffset",
+        }).format(date);
+    }
+    catch {
+        return date.toISOString();
+    }
+}
+//# sourceMappingURL=build-stamp.js.map

package/dist/build-stamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-stamp.js","sourceRoot":"","sources":["../src/build-stamp.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,4BAA4B,CAAC,IAAU;IACrD,IAAI,CAAC;QACH,OAAO,IAAI,IAAI,CAAC,cAAc,CAAC,SAAS,EAAE;YACxC,OAAO,EAAE,OAAO;YAChB,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,OAAO;YACd,GAAG,EAAE,SAAS;YACd,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,KAAK;YACb,YAAY,EAAE,YAAY;SAC3B,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC;IAC5B,CAAC;AACH,CAAC"}