@commentray/core 0.0.1 → 0.0.2

package/dist/angles-toml.d.ts

@@ -0,0 +1,18 @@
+export type UpsertAngleDefinitionInput = {
+    id: string;
+    title?: string;
+    /** When true, set `angles.default_angle` to this id after the merge. */
+    makeDefault?: boolean;
+};
+/**
+ * Ensures `{storage.dir}/source/.default` exists so the repository uses **Angles** on-disk layout
+ * (see `docs/spec/storage.md`).
+ */
+export declare function ensureAnglesSentinelFile(repoRoot: string, storageDir: string): Promise<void>;
+/**
+ * Reads `.commentray.toml`, appends a new `[[angles.definitions]]` row (or throws if the id
+ * already exists), validates via {@link mergeCommentrayConfig}, and writes the file back using
+ * TOML stringify (comments and key order are not preserved).
+ */
+export declare function upsertAngleDefinitionInCommentrayToml(repoRoot: string, input: UpsertAngleDefinitionInput): Promise<void>;
+//# sourceMappingURL=angles-toml.d.ts.map

package/dist/angles-toml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"angles-toml.d.ts","sourceRoot":"","sources":["../src/angles-toml.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,0BAA0B,GAAG;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAMF;;;GAGG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;GAIG;AACH,wBAAsB,qCAAqC,CACzD,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,IAAI,CAAC,CAmCf"}

package/dist/angles-toml.js

@@ -0,0 +1,62 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parse as parseToml, stringify } from "@iarna/toml";
+import { assertValidAngleId } from "./angles.js";
+import { mergeCommentrayConfig } from "./config.js";
+import { commentrayAnglesSentinelPath } from "./paths.js";
+const MINIMAL_NEW_TOML = `[storage]
+dir = ".commentray"
+`;
+/**
+ * Ensures `{storage.dir}/source/.default` exists so the repository uses **Angles** on-disk layout
+ * (see `docs/spec/storage.md`).
+ */
+export async function ensureAnglesSentinelFile(repoRoot, storageDir) {
+    const rel = commentrayAnglesSentinelPath(storageDir);
+    const absolute = path.join(repoRoot, ...rel.split("/"));
+    await fs.mkdir(path.dirname(absolute), { recursive: true });
+    try {
+        await fs.access(absolute);
+    }
+    catch {
+        await fs.writeFile(absolute, "# Commentray Angles layout sentinel (see docs/spec/storage.md).\n", "utf8");
+    }
+}
+/**
+ * Reads `.commentray.toml`, appends a new `[[angles.definitions]]` row (or throws if the id
+ * already exists), validates via {@link mergeCommentrayConfig}, and writes the file back using
+ * TOML stringify (comments and key order are not preserved).
+ */
+export async function upsertAngleDefinitionInCommentrayToml(repoRoot, input) {
+    const id = assertValidAngleId(input.id);
+    const configPath = path.join(repoRoot, ".commentray.toml");
+    let raw = "";
+    try {
+        raw = await fs.readFile(configPath, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT")
+            throw err;
+    }
+    const parsed = raw.trim() ? parseToml(raw) : {};
+    const angles = parsed.angles ?? {};
+    const definitions = [...(angles.definitions ?? [])];
+    if (definitions.some((d) => d && typeof d === "object" && "id" in d && String(d.id) === id)) {
+        throw new Error(`Angle "${id}" is already listed in [angles].definitions`);
+    }
+    definitions.push({
+        id,
+        title: input.title?.trim() || undefined,
+    });
+    angles.definitions = definitions;
+    if (input.makeDefault === true || definitions.length === 1) {
+        angles.default_angle = id;
+    }
+    parsed.angles = angles;
+    mergeCommentrayConfig(parsed);
+    const serialized = stringify(parsed);
+    const body = raw.trim() ? serialized : `${MINIMAL_NEW_TOML.trim()}\n\n${serialized}`;
+    await fs.writeFile(configPath, `${body}\n`, "utf8");
+}
+//# sourceMappingURL=angles-toml.js.map

package/dist/angles-toml.js.map

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

package/dist/angles.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Validates and returns a trimmed Angle id. Used for TOML `angles.*` keys and path segments.
+ * Rejects empty, `.`, `..`, and anything outside `[a-zA-Z0-9_-]` so paths stay predictable and safe.
+ */
+export declare function assertValidAngleId(angleId: string): string;
+//# sourceMappingURL=angles.d.ts.map

package/dist/angles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"angles.d.ts","sourceRoot":"","sources":["../src/angles.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQ1D"}

package/dist/angles.js

@@ -0,0 +1,14 @@
+/** Allowed characters for an Angle id (folder / file segment). */
+const ANGLE_ID_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+/**
+ * Validates and returns a trimmed Angle id. Used for TOML `angles.*` keys and path segments.
+ * Rejects empty, `.`, `..`, and anything outside `[a-zA-Z0-9_-]` so paths stay predictable and safe.
+ */
+export function assertValidAngleId(angleId) {
+    const t = angleId.trim();
+    if (t === "." || t === ".." || !ANGLE_ID_RE.test(t)) {
+        throw new Error(`Invalid angle id "${angleId}" (use 1–64 characters from [a-zA-Z0-9_-] only; not "." or "..")`);
+    }
+    return t;
+}
+//# sourceMappingURL=angles.js.map

package/dist/angles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"angles.js","sourceRoot":"","sources":["../src/angles.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,WAAW,GAAG,uBAAuB,CAAC;AAE5C;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IACzB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CACb,qBAAqB,OAAO,kEAAkE,CAC/F,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/blocks.d.ts

@@ -0,0 +1,66 @@
+import type { CommentrayBlock, CommentrayIndex } from "./model.js";
+/** 1-based inclusive range of source lines a block points to. */
+export type BlockRange = {
+    startLine: number;
+    endLine: number;
+};
+export type CreateBlockForRangeInput = {
+    /**
+     * Repo-relative path to the primary source file. Shown in the block's
+     * heading so readers can see where the range lives without leaving the
+     * commentary pane.
+     */
+    sourcePath: string;
+    /** Full source text (lines separated by `\n`). */
+    sourceText: string;
+    /** Selected range to anchor the block to. */
+    range: BlockRange;
+    /** Optional explicit id; one is generated when omitted. */
+    id?: string;
+    /** Seam for deterministic tests. Default: `Math.random`. */
+    rng?: () => number;
+};
+export type CreatedBlock = {
+    block: CommentrayBlock;
+    /**
+     * Markdown fragment to append to the commentray file. Starts with the
+     * invisible `<!-- commentray:block ... -->` marker and ends with a
+     * trailing newline so subsequent appends stay separated.
+     */
+    markdown: string;
+    /**
+     * 0-based line offset within `markdown` where the author's caret should
+     * land after insertion — the placeholder line ready to be overwritten.
+     */
+    caretLineOffset: number;
+};
+/**
+ * Create a block (domain entity) together with the Markdown fragment that
+ * carries it in the commentary file. Pure: no I/O, deterministic when a
+ * fixed `rng` and `id` are supplied.
+ */
+export declare function createBlockForRange(input: CreateBlockForRangeInput): CreatedBlock;
+/**
+ * Append `blockMarkdown` to existing commentary content, guaranteeing a
+ * single blank-line separator regardless of how the existing content ended.
+ */
+export declare function appendBlockToCommentray(existing: string, blockMarkdown: string): string;
+export type AddBlockToIndexInput = {
+    sourcePath: string;
+    commentrayPath: string;
+    block: CommentrayBlock;
+};
+/**
+ * Return a new index with the block added under the given source file.
+ * The source entry is created lazily when it does not exist yet. Throws
+ * when the block id already exists under that source so callers cannot
+ * silently corrupt the index.
+ */
+export declare function addBlockToIndex(index: CommentrayIndex, input: AddBlockToIndexInput): CommentrayIndex;
+/**
+ * Six-character base-36 id. Alphabet excludes uppercase so ids are case-
+ * insensitive-safe on filesystems and URLs. Collision space ≈ 2 billion,
+ * comfortably larger than any plausible per-file block count.
+ */
+export declare function generateBlockId(rng?: () => number): string;
+//# sourceMappingURL=blocks.d.ts.map

package/dist/blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EAEf,eAAe,EAEhB,MAAM,YAAY,CAAC;AAEpB,iEAAiE;AACjE,MAAM,MAAM,UAAU,GAAG;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,KAAK,EAAE,UAAU,CAAC;IAClB,2DAA2D;IAC3D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,eAAe,CAAC;IACvB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC;AAMF;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,GAAG,YAAY,CASjF;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAKvF;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,eAAe,CAAC;CACxB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,oBAAoB,GAC1B,eAAe,CAuBjB;AAKD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,MAAoB,GAAG,MAAM,CAMvE"}

package/dist/blocks.js

@@ -0,0 +1,101 @@
+import { formatLineRange } from "./anchors.js";
+const BLOCK_MARKER_PREFIX = "<!-- commentray:block id=";
+const BLOCK_MARKER_SUFFIX = " -->";
+const CARET_PLACEHOLDER = "_(write commentary here)_";
+/**
+ * Create a block (domain entity) together with the Markdown fragment that
+ * carries it in the commentary file. Pure: no I/O, deterministic when a
+ * fixed `rng` and `id` are supplied.
+ */
+export function createBlockForRange(input) {
+    const range = clampRange(input.range, input.sourceText);
+    const anchor = formatLineRange({ start: range.startLine, end: range.endLine });
+    const fingerprint = computeFingerprint(input.sourceText, range);
+    const id = input.id ?? generateBlockId(input.rng);
+    const block = { id, anchor, fingerprint };
+    const markdown = renderBlockMarkdown({ block, sourcePath: input.sourcePath, range });
+    const caretLineOffset = placeholderLineOffset(markdown);
+    return { block, markdown, caretLineOffset };
+}
+/**
+ * Append `blockMarkdown` to existing commentary content, guaranteeing a
+ * single blank-line separator regardless of how the existing content ended.
+ */
+export function appendBlockToCommentray(existing, blockMarkdown) {
+    const trimmed = existing.replace(/\s+$/, "");
+    const body = trimmed.length === 0 ? "" : `${trimmed}\n\n`;
+    const fragment = blockMarkdown.endsWith("\n") ? blockMarkdown : `${blockMarkdown}\n`;
+    return `${body}${fragment}`;
+}
+/**
+ * Return a new index with the block added under the given source file.
+ * The source entry is created lazily when it does not exist yet. Throws
+ * when the block id already exists under that source so callers cannot
+ * silently corrupt the index.
+ */
+export function addBlockToIndex(index, input) {
+    const key = input.commentrayPath;
+    const existing = index.byCommentrayPath[key];
+    if (existing && existing.sourcePath !== input.sourcePath) {
+        throw new Error(`commentrayPath ${key} is already indexed for ${existing.sourcePath}, not ${input.sourcePath}`);
+    }
+    const previousBlocks = existing?.blocks ?? [];
+    if (previousBlocks.some((b) => b.id === input.block.id)) {
+        throw new Error(`block id ${input.block.id} already exists under ${key}; choose a different id`);
+    }
+    const nextEntry = {
+        sourcePath: input.sourcePath,
+        commentrayPath: input.commentrayPath,
+        blocks: [...previousBlocks, input.block],
+    };
+    return {
+        schemaVersion: index.schemaVersion,
+        byCommentrayPath: { ...index.byCommentrayPath, [key]: nextEntry },
+    };
+}
+const ID_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+const ID_LENGTH = 6;
+/**
+ * Six-character base-36 id. Alphabet excludes uppercase so ids are case-
+ * insensitive-safe on filesystems and URLs. Collision space ≈ 2 billion,
+ * comfortably larger than any plausible per-file block count.
+ */
+export function generateBlockId(rng = Math.random) {
+    let id = "";
+    for (let i = 0; i < ID_LENGTH; i++) {
+        id += ID_ALPHABET[Math.floor(rng() * ID_ALPHABET.length)];
+    }
+    return id;
+}
+function clampRange(range, sourceText) {
+    const lineCount = Math.max(1, sourceText.split("\n").length);
+    const start = Math.max(1, Math.min(Math.floor(range.startLine), lineCount));
+    const endRaw = Math.max(start, Math.floor(range.endLine));
+    const end = Math.min(endRaw, lineCount);
+    return { startLine: start, endLine: end };
+}
+function computeFingerprint(sourceText, range) {
+    const lines = sourceText.split("\n");
+    const startText = (lines[range.startLine - 1] ?? "").trim();
+    const endText = (lines[range.endLine - 1] ?? "").trim();
+    return {
+        startLine: startText,
+        endLine: endText,
+        lineCount: range.endLine - range.startLine + 1,
+    };
+}
+function renderBlockMarkdown(args) {
+    const marker = `${BLOCK_MARKER_PREFIX}${args.block.id}${BLOCK_MARKER_SUFFIX}`;
+    const heading = `## \`${args.sourcePath}\` ${rangeLabel(args.range)}`;
+    return `${marker}\n${heading}\n\n${CARET_PLACEHOLDER}\n`;
+}
+function rangeLabel(range) {
+    if (range.startLine === range.endLine)
+        return `line ${range.startLine}`;
+    return `lines ${range.startLine}–${range.endLine}`;
+}
+function placeholderLineOffset(markdown) {
+    const lines = markdown.split("\n");
+    return Math.max(0, lines.indexOf(CARET_PLACEHOLDER));
+}
+//# sourceMappingURL=blocks.js.map

package/dist/blocks.js.map

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

package/dist/commentray-path-resolution.d.ts

@@ -0,0 +1,20 @@
+import type { ResolvedCommentrayConfig } from "./config.js";
+/**
+ * When Angles layout is on and the user has not configured a default, tools pick this id so a
+ * concrete file path exists (`…/main.md`). Authors may rename via `[angles]` in `.commentray.toml`.
+ */
+export declare const FALLBACK_DEFAULT_ANGLE_ID: "main";
+export declare function defaultAngleIdForOpen(config: ResolvedCommentrayConfig): string;
+export type ResolvedCommentrayMarkdownPath = {
+    /** Repo-relative path to the paired `.md` file. */
+    commentrayPath: string;
+    /** Present when `{storage}/source/.default` exists (Angles layout). */
+    angleId: string | null;
+    anglesLayout: boolean;
+};
+/**
+ * Resolves the commentray Markdown path for a primary source file, honoring Angles layout and
+ * optional explicit `angleId` (when Angles layout is active).
+ */
+export declare function resolveCommentrayMarkdownPath(repoRoot: string, sourceRepoRelativePath: string, config: ResolvedCommentrayConfig, angleId?: string | null): ResolvedCommentrayMarkdownPath;
+//# sourceMappingURL=commentray-path-resolution.d.ts.map

package/dist/commentray-path-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commentray-path-resolution.d.ts","sourceRoot":"","sources":["../src/commentray-path-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAQ5D;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAG,MAAe,CAAC;AAEzD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,wBAAwB,GAAG,MAAM,CAK9E;AAED,MAAM,MAAM,8BAA8B,GAAG;IAC3C,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,sBAAsB,EAAE,MAAM,EAC9B,MAAM,EAAE,wBAAwB,EAChC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,GACtB,8BAA8B,CAkBhC"}

package/dist/commentray-path-resolution.js

@@ -0,0 +1,38 @@
+import { assertValidAngleId } from "./angles.js";
+import { commentrayAnglesLayoutEnabled, commentrayMarkdownPath, commentrayMarkdownPathForAngle, } from "./paths.js";
+/**
+ * When Angles layout is on and the user has not configured a default, tools pick this id so a
+ * concrete file path exists (`…/main.md`). Authors may rename via `[angles]` in `.commentray.toml`.
+ */
+export const FALLBACK_DEFAULT_ANGLE_ID = "main";
+export function defaultAngleIdForOpen(config) {
+    if (config.angles.defaultAngleId)
+        return config.angles.defaultAngleId;
+    const first = config.angles.definitions[0];
+    if (first)
+        return first.id;
+    return FALLBACK_DEFAULT_ANGLE_ID;
+}
+/**
+ * Resolves the commentray Markdown path for a primary source file, honoring Angles layout and
+ * optional explicit `angleId` (when Angles layout is active).
+ */
+export function resolveCommentrayMarkdownPath(repoRoot, sourceRepoRelativePath, config, angleId) {
+    const anglesLayout = commentrayAnglesLayoutEnabled(repoRoot, config.storageDir);
+    if (!anglesLayout) {
+        return {
+            commentrayPath: commentrayMarkdownPath(sourceRepoRelativePath),
+            angleId: null,
+            anglesLayout: false,
+        };
+    }
+    const id = angleId !== undefined && angleId !== null && String(angleId).trim() !== ""
+        ? assertValidAngleId(String(angleId))
+        : defaultAngleIdForOpen(config);
+    return {
+        commentrayPath: commentrayMarkdownPathForAngle(sourceRepoRelativePath, id, config.storageDir),
+        angleId: id,
+        anglesLayout: true,
+    };
+}
+//# sourceMappingURL=commentray-path-resolution.js.map

package/dist/commentray-path-resolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commentray-path-resolution.js","sourceRoot":"","sources":["../src/commentray-path-resolution.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EACL,6BAA6B,EAC7B,sBAAsB,EACtB,8BAA8B,GAC/B,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAe,CAAC;AAEzD,MAAM,UAAU,qBAAqB,CAAC,MAAgC;IACpE,IAAI,MAAM,CAAC,MAAM,CAAC,cAAc;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC;IACtE,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAC3C,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC,EAAE,CAAC;IAC3B,OAAO,yBAAyB,CAAC;AACnC,CAAC;AAUD;;;GAGG;AACH,MAAM,UAAU,6BAA6B,CAC3C,QAAgB,EAChB,sBAA8B,EAC9B,MAAgC,EAChC,OAAuB;IAEvB,MAAM,YAAY,GAAG,6BAA6B,CAAC,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAChF,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO;YACL,cAAc,EAAE,sBAAsB,CAAC,sBAAsB,CAAC;YAC9D,OAAO,EAAE,IAAI;YACb,YAAY,EAAE,KAAK;SACpB,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,GACN,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE;QACxE,CAAC,CAAC,kBAAkB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACrC,CAAC,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC;IACpC,OAAO;QACL,cAAc,EAAE,8BAA8B,CAAC,sBAAsB,EAAE,EAAE,EAAE,MAAM,CAAC,UAAU,CAAC;QAC7F,OAAO,EAAE,EAAE;QACX,YAAY,EAAE,IAAI;KACnB,CAAC;AACJ,CAAC"}

package/dist/config.d.ts

@@ -8,10 +8,29 @@ export type CommentrayToml = {
     render?: {
         mermaid?: boolean;
         syntaxTheme?: string;
+        /**
+         * When true, `https://github.com/<owner>/<repo>/blob|tree/<branch>/…` links in commentray
+         * Markdown are rewritten to paths relative to the generated HTML file (see
+         * `static_site.github_url` for owner/repo). Requires a parseable repository URL.
+         */
+        relative_github_blob_links?: boolean;
     };
     anchors?: {
         defaultStrategy?: string[];
     };
+    /**
+     * Named **Angles** — multiple commentrays per source file (see `docs/spec/storage.md`).
+     * Keys use snake_case in TOML (`[angles]`).
+     */
+    angles?: {
+        /** Which Angle is selected by default in tooling and the static viewer (must match a `definitions` id when that list is non-empty). */
+        default_angle?: string;
+        /** Optional list of known Angles with display titles for UI (static browser, editor). */
+        definitions?: {
+            id: string;
+            title?: string;
+        }[];
+    };
     /**
      * Optional settings for publishing a single-file static “code browser” (GitHub Pages, etc.).
      * Keys use snake_case in TOML (`[static_site]`).
@@ -27,14 +46,41 @@ export type CommentrayToml = {
         commentray_markdown?: string;
         /** @deprecated Renamed to `commentray_markdown`. */
         commentary_markdown?: string;
+        /** Branch name embedded in GitHub blob URLs for `related_github_files` (default `main`). */
+        github_blob_branch?: string;
+        /**
+         * Optional toolbar links on the static code browser: open other repo files on GitHub
+         * (single-page Pages deploys cannot serve arbitrary paths next to `index.html`).
+         */
+        related_github_files?: {
+            label?: string;
+            path: string;
+        }[];
     };
 };
+export type ResolvedGithubNavLink = {
+    label: string;
+    href: string;
+};
 export type ResolvedStaticSite = {
     title: string;
     introMarkdown: string;
     githubUrl: string | null;
+    /** Branch used when building `relatedGithubNav` blob URLs. */
+    githubBlobBranch: string;
     sourceFile: string;
     commentrayMarkdownFile: string;
+    /** Toolbar “Also on GitHub …” links for the static code browser. */
+    relatedGithubNav: ResolvedGithubNavLink[];
+};
+export type ResolvedAngleDefinition = {
+    id: string;
+    title: string;
+};
+export type ResolvedAngles = {
+    /** When `definitions` is non-empty, this must match one of them (enforced at merge). */
+    defaultAngleId: string | null;
+    definitions: ResolvedAngleDefinition[];
 };
 export type ResolvedCommentrayConfig = {
     storageDir: string;
@@ -42,10 +88,12 @@ export type ResolvedCommentrayConfig = {
     render: {
         mermaid: boolean;
         syntaxTheme: string;
+        relativeGithubBlobLinks: boolean;
     };
     anchors: {
         defaultStrategy: string[];
     };
+    angles: ResolvedAngles;
     staticSite: ResolvedStaticSite;
 };
 export declare function mergeCommentrayConfig(parsed: CommentrayToml | null): ResolvedCommentrayConfig;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3B,GAAG,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5B,MAAM,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACzC;;;OAGG;IACH,WAAW,CAAC,EAAE;QACZ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,yEAAyE;QACzE,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,wFAAwF;QACxF,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,uEAAuE;QACvE,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,oDAAoD;QACpD,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,KAAK,CAAC;IACnB,MAAM,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAClD,OAAO,EAAE;QAAE,eAAe,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACvC,UAAU,EAAE,kBAAkB,CAAC;CAChC,CAAC;AAkFF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,wBAAwB,CAmB7F;AAED,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAY9F"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3B,GAAG,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5B,MAAM,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB;;;;WAIG;QACH,0BAA0B,CAAC,EAAE,OAAO,CAAC;KACtC,CAAC;IACF,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACzC;;;OAGG;IACH,MAAM,CAAC,EAAE;QACP,uIAAuI;QACvI,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,yFAAyF;QACzF,WAAW,CAAC,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;KAChD,CAAC;IACF;;;OAGG;IACH,WAAW,CAAC,EAAE;QACZ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,yEAAyE;QACzE,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,wFAAwF;QACxF,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,uEAAuE;QACvE,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,oDAAoD;QACpD,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,4FAA4F;QAC5F,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B;;;WAGG;QACH,oBAAoB,CAAC,EAAE;YAAE,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;KAC3D,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,oEAAoE;IACpE,gBAAgB,EAAE,qBAAqB,EAAE,CAAC;CAC3C,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE,MAAM,MAAM,cAAc,GAAG;IAC3B,wFAAwF;IACxF,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,WAAW,EAAE,uBAAuB,EAAE,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,KAAK,CAAC;IACnB,MAAM,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,uBAAuB,EAAE,OAAO,CAAA;KAAE,CAAC;IACpF,OAAO,EAAE;QAAE,eAAe,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACvC,MAAM,EAAE,cAAc,CAAC;IACvB,UAAU,EAAE,kBAAkB,CAAC;CAChC,CAAC;AA+JF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,wBAAwB,CAsB7F;AAED,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAY9F"}

package/dist/config.js

@@ -1,19 +1,25 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { parse as parseToml } from "@iarna/toml";
+import { assertValidAngleId } from "./angles.js";
+import { githubRepoBlobFileUrl, parseGithubRepoWebUrl } from "./github-url.js";
 import { normalizeRepoRelativePath } from "./paths.js";
 const defaultStaticSite = {
     title: "Commentray",
     introMarkdown: "",
     githubUrl: null,
+    githubBlobBranch: "main",
     sourceFile: "README.md",
     commentrayMarkdownFile: "",
+    relatedGithubNav: [],
 };
+const defaultAngles = { defaultAngleId: null, definitions: [] };
 const defaultConfig = {
     storageDir: ".commentray",
     scmProvider: "git",
-    render: { mermaid: true, syntaxTheme: "github-dark" },
+    render: { mermaid: true, syntaxTheme: "github-dark", relativeGithubBlobLinks: false },
     anchors: { defaultStrategy: ["symbol", "lines"] },
+    angles: { ...defaultAngles },
     staticSite: { ...defaultStaticSite },
 };
 function nonEmptyTrimmed(s) {
@@ -52,17 +58,70 @@ function assertStorageDirNotInsideGit(value) {
             `Git treats .git/ as opaque metadata and routine operations can wipe it.`);
     }
 }
+function mergeAngleDefinitions(raw) {
+    if (!raw?.length)
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const row of raw) {
+        const id = assertValidAngleId(row.id);
+        if (seen.has(id)) {
+            throw new Error(`Duplicate angles.definitions id: ${id}`);
+        }
+        seen.add(id);
+        const title = row.title?.trim() || id;
+        out.push({ id, title });
+    }
+    return out;
+}
+function resolveAngles(parsed) {
+    const a = parsed.angles;
+    if (!a) {
+        return { ...defaultAngles };
+    }
+    const definitions = mergeAngleDefinitions(a.definitions);
+    const defaultRaw = a.default_angle?.trim();
+    const defaultAngleId = defaultRaw ? assertValidAngleId(defaultRaw) : null;
+    if (definitions.length > 0 &&
+        defaultAngleId &&
+        !definitions.some((d) => d.id === defaultAngleId)) {
+        throw new Error(`angles.default_angle "${defaultAngleId}" must match one of angles.definitions (got: ${definitions.map((d) => d.id).join(", ")})`);
+    }
+    return { defaultAngleId, definitions };
+}
+function mergeRelatedGithubNav(githubUrl, branch, raw) {
+    const gh = githubUrl ? parseGithubRepoWebUrl(githubUrl) : null;
+    if (!gh || !raw?.length)
+        return [];
+    const b = branch.trim() || defaultStaticSite.githubBlobBranch;
+    const out = [];
+    for (const row of raw) {
+        if (!row?.path?.trim())
+            continue;
+        const p = normalizeRepoRelativePath(row.path.trim());
+        const label = row.label?.trim() || path.posix.basename(p);
+        out.push({
+            label,
+            href: githubRepoBlobFileUrl(gh.owner, gh.repo, b, p),
+        });
+    }
+    return out;
+}
 function resolveStaticSite(parsed) {
     const ss = parsed.static_site;
     const mdFile = ss?.commentray_markdown?.trim() ??
         ss?.commentary_markdown?.trim() ??
         defaultStaticSite.commentrayMarkdownFile;
+    const githubUrl = nonEmptyTrimmed(ss?.github_url);
+    const githubBlobBranch = nonEmptyTrimmed(ss?.github_blob_branch) ?? defaultStaticSite.githubBlobBranch;
     return {
         title: nonEmptyTrimmed(ss?.title) ?? defaultStaticSite.title,
         introMarkdown: ss?.intro ?? defaultStaticSite.introMarkdown,
-        githubUrl: nonEmptyTrimmed(ss?.github_url),
+        githubUrl,
+        githubBlobBranch,
         sourceFile: nonEmptyTrimmed(ss?.source_file) ?? defaultStaticSite.sourceFile,
         commentrayMarkdownFile: mdFile,
+        relatedGithubNav: mergeRelatedGithubNav(githubUrl, githubBlobBranch, ss?.related_github_files),
     };
 }
 function assertSafeConfigPaths(parsed) {
@@ -72,6 +131,9 @@ function assertSafeConfigPaths(parsed) {
     assertSafeRepoRelativePath("static_site.source_file", ss?.source_file);
     assertSafeRepoRelativePath("static_site.commentray_markdown", ss?.commentray_markdown);
     assertSafeRepoRelativePath("static_site.commentary_markdown", ss?.commentary_markdown);
+    for (let i = 0; i < (ss?.related_github_files?.length ?? 0); i++) {
+        assertSafeRepoRelativePath(`static_site.related_github_files[${i}].path`, ss?.related_github_files?.[i]?.path);
+    }
 }
 export function mergeCommentrayConfig(parsed) {
     if (!parsed)
@@ -87,10 +149,12 @@ export function mergeCommentrayConfig(parsed) {
         render: {
             mermaid: parsed.render?.mermaid ?? defaultConfig.render.mermaid,
             syntaxTheme: parsed.render?.syntaxTheme ?? defaultConfig.render.syntaxTheme,
+            relativeGithubBlobLinks: parsed.render?.relative_github_blob_links ?? defaultConfig.render.relativeGithubBlobLinks,
         },
         anchors: {
             defaultStrategy: parsed.anchors?.defaultStrategy ?? defaultConfig.anchors.defaultStrategy,
         },
+        angles: resolveAngles(parsed),
         staticSite: resolveStaticSite(parsed),
     };
 }

package/dist/config.js.map

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

package/dist/github-url.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parses a GitHub repository web URL into owner + repo name (no API calls).
+ * Accepts optional trailing slash and `.git` suffix.
+ */
+export declare function parseGithubRepoWebUrl(url: string): {
+    owner: string;
+    repo: string;
+} | null;
+/**
+ * Builds a `https://github.com/owner/repo/blob/<branch>/path` URL for a repo-relative file path.
+ * Used for static-site “open another file” links when only `_site/index.html` is deployed.
+ */
+export declare function githubRepoBlobFileUrl(owner: string, repo: string, branch: string, repoRelativePath: string): string;
+//# sourceMappingURL=github-url.d.ts.map

package/dist/github-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-url.d.ts","sourceRoot":"","sources":["../src/github-url.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAKzF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,MAAM,GACvB,MAAM,CAOR"}