@commentray/core 0.0.1 → 0.0.4

package/dist/anchors.d.ts

@@ -8,6 +8,9 @@ export type ParsedAnchor = {
 } | {
     kind: "symbol";
     name: string;
+} | {
+    kind: "marker";
+    id: string;
 } | {
     kind: "opaque";
     raw: string;
@@ -16,7 +19,10 @@ export type ParsedAnchor = {
  * Minimal anchor grammar (versioned; see docs/spec/anchors.md).
  * - lines:12-34
  * - symbol:SomeName
+ * - marker:<id> (paired **region** comments in source — `//#region commentray:<id>` /
+ *   `//#endregion commentray:<id>` in JS/TS, matching [Region Marker](https://marketplace.visualstudio.com/items?itemName=txava.region-marker) defaults; legacy `commentray:start id=<id>` / `commentray:end` still parses)
  */
 export declare function parseAnchor(anchor: string): ParsedAnchor;
 export declare function formatLineRange(range: LineRange): string;
+export declare function formatMarkerAnchor(markerId: string): string;
 //# sourceMappingURL=anchors.d.ts.map

package/dist/anchors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"anchors.d.ts","sourceRoot":"","sources":["../src/anchors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpC;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAkBxD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAExD"}
+{"version":3,"file":"anchors.d.ts","sourceRoot":"","sources":["../src/anchors.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpC;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAuBxD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAExD;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE3D"}

package/dist/anchors.js

@@ -1,10 +1,18 @@
+import { assertValidMarkerId, MARKER_ID_BODY } from "./marker-ids.js";
 /**
  * Minimal anchor grammar (versioned; see docs/spec/anchors.md).
  * - lines:12-34
  * - symbol:SomeName
+ * - marker:<id> (paired **region** comments in source — `//#region commentray:<id>` /
+ *   `//#endregion commentray:<id>` in JS/TS, matching [Region Marker](https://marketplace.visualstudio.com/items?itemName=txava.region-marker) defaults; legacy `commentray:start id=<id>` / `commentray:end` still parses)
  */
 export function parseAnchor(anchor) {
     const trimmed = anchor.trim();
+    const markerMatch = new RegExp(`^marker:(${MARKER_ID_BODY})$`, "i").exec(trimmed);
+    if (markerMatch) {
+        const id = assertValidMarkerId(markerMatch[1]);
+        return { kind: "marker", id };
+    }
     const linesMatch = /^lines:(\d+)-(\d+)$/.exec(trimmed);
     if (linesMatch) {
         const start = Number(linesMatch[1]);
@@ -26,4 +34,7 @@ export function parseAnchor(anchor) {
 export function formatLineRange(range) {
     return `lines:${range.start}-${range.end}`;
 }
+export function formatMarkerAnchor(markerId) {
+    return `marker:${assertValidMarkerId(markerId)}`;
+}
 //# sourceMappingURL=anchors.js.map

package/dist/anchors.js.map

@@ -1 +1 @@
-{"version":3,"file":"anchors.js","sourceRoot":"","sources":["../src/anchors.ts"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9B,MAAM,UAAU,GAAG,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACvD,IAAI,UAAU,EAAE,CAAC;QACf,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QAClC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,GAAG,GAAG,KAAK,EAAE,CAAC;YACjF,MAAM,IAAI,KAAK,CAAC,yBAAyB,MAAM,EAAE,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC;IAClD,CAAC;IACD,MAAM,WAAW,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACnC,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,MAAM,EAAE,CAAC,CAAC;QAC/D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAClC,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAgB;IAC9C,OAAO,SAAS,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;AAC7C,CAAC"}
+{"version":3,"file":"anchors.js","sourceRoot":"","sources":["../src/anchors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAUtE;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9B,MAAM,WAAW,GAAG,IAAI,MAAM,CAAC,YAAY,cAAc,IAAI,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAClF,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,EAAE,GAAG,mBAAmB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAChC,CAAC;IACD,MAAM,UAAU,GAAG,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACvD,IAAI,UAAU,EAAE,CAAC;QACf,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QAClC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,GAAG,GAAG,KAAK,EAAE,CAAC;YACjF,MAAM,IAAI,KAAK,CAAC,yBAAyB,MAAM,EAAE,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC;IAClD,CAAC;IACD,MAAM,WAAW,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACnC,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,MAAM,EAAE,CAAC,CAAC;QAC/D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAClC,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAgB;IAC9C,OAAO,SAAS,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,OAAO,UAAU,mBAAmB,CAAC,QAAQ,CAAC,EAAE,CAAC;AACnD,CAAC"}

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":"AAQA,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/block-scroll-pickers.d.ts

@@ -0,0 +1,22 @@
+/** One block as needed for scroll correlation (0-based commentray line, 1-based source range). */
+export type BlockScrollLink = {
+    /** Same id as `<!-- commentray:block id=… -->` and `index.json` blocks[]. */
+    id: string;
+    commentrayLine: number;
+    sourceStart: number;
+    sourceEnd: number;
+};
+/**
+ * Choose which commentray line (0-based) to reveal so the commentary matches
+ * the top of the source viewport. Prefers the block whose source range
+ * **contains** the top line; otherwise the nearest preceding block; if above
+ * all blocks, the first block.
+ */
+export declare function pickCommentrayLineForSourceScroll(blocks: BlockScrollLink[], topSourceLine1Based: number): number | null;
+/**
+ * Choose a 0-based source line to reveal from the top of the commentray
+ * viewport: the block whose marker is at or above that line wins; reveal the
+ * start of its source range.
+ */
+export declare function pickSourceLine0ForCommentrayScroll(blocks: BlockScrollLink[], topCommentrayLine0Based: number): number | null;
+//# sourceMappingURL=block-scroll-pickers.d.ts.map

package/dist/block-scroll-pickers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-scroll-pickers.d.ts","sourceRoot":"","sources":["../src/block-scroll-pickers.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,MAAM,MAAM,eAAe,GAAG;IAC5B,6EAA6E;IAC7E,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,eAAe,EAAE,EACzB,mBAAmB,EAAE,MAAM,GAC1B,MAAM,GAAG,IAAI,CAaf;AAED;;;;GAIG;AACH,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,eAAe,EAAE,EACzB,uBAAuB,EAAE,MAAM,GAC9B,MAAM,GAAG,IAAI,CAQf"}

package/dist/block-scroll-pickers.js

@@ -0,0 +1,41 @@
+/**
+ * Choose which commentray line (0-based) to reveal so the commentary matches
+ * the top of the source viewport. Prefers the block whose source range
+ * **contains** the top line; otherwise the nearest preceding block; if above
+ * all blocks, the first block.
+ */
+export function pickCommentrayLineForSourceScroll(blocks, topSourceLine1Based) {
+    if (blocks.length === 0)
+        return null;
+    const inside = blocks.find((b) => b.sourceStart <= topSourceLine1Based && topSourceLine1Based <= b.sourceEnd);
+    if (inside)
+        return inside.commentrayLine;
+    if (topSourceLine1Based < blocks[0].sourceStart)
+        return blocks[0].commentrayLine;
+    let best = blocks[0];
+    for (const b of blocks) {
+        if (b.sourceStart <= topSourceLine1Based)
+            best = b;
+        else
+            break;
+    }
+    return best.commentrayLine;
+}
+/**
+ * Choose a 0-based source line to reveal from the top of the commentray
+ * viewport: the block whose marker is at or above that line wins; reveal the
+ * start of its source range.
+ */
+export function pickSourceLine0ForCommentrayScroll(blocks, topCommentrayLine0Based) {
+    if (blocks.length === 0)
+        return null;
+    let best = blocks[0];
+    for (const b of blocks) {
+        if (b.commentrayLine <= topCommentrayLine0Based)
+            best = b;
+        else
+            break;
+    }
+    return best.sourceStart - 1;
+}
+//# sourceMappingURL=block-scroll-pickers.js.map

package/dist/block-scroll-pickers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-scroll-pickers.js","sourceRoot":"","sources":["../src/block-scroll-pickers.ts"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,MAAM,UAAU,iCAAiC,CAC/C,MAAyB,EACzB,mBAA2B;IAE3B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CACxB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,IAAI,mBAAmB,IAAI,mBAAmB,IAAI,CAAC,CAAC,SAAS,CAClF,CAAC;IACF,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC,cAAc,CAAC;IACzC,IAAI,mBAAmB,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC;IACjF,IAAI,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACrB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,WAAW,IAAI,mBAAmB;YAAE,IAAI,GAAG,CAAC,CAAC;;YAC9C,MAAM;IACb,CAAC;IACD,OAAO,IAAI,CAAC,cAAc,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kCAAkC,CAChD,MAAyB,EACzB,uBAA+B;IAE/B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACrB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,cAAc,IAAI,uBAAuB;YAAE,IAAI,GAAG,CAAC,CAAC;;YACrD,MAAM;IACb,CAAC;IACD,OAAO,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;AAC9B,CAAC"}

package/dist/block-snippet.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Self-contained, diff-inspired capture of the source lines a block refers to.
+ * Stored as a single string in index.json (not a nested JSON object).
+ *
+ * Format (v1): header line `commentray-snippet/v1`, then one line per source
+ * line using unified-diff **context** style: each line begins with a single
+ * space followed by the trimmed source line (empty lines are a lone leading space).
+ */
+export declare const COMMENTRAY_SNIPPET_HEADER_V1: "commentray-snippet/v1";
+export declare function buildCommentraySnippetV1(trimmedLines: string[]): string;
+/** Returns trimmed lines, or null if the string is not a valid v1 snippet. */
+export declare function parseCommentraySnippetV1(snippet: string): string[] | null;
+//# sourceMappingURL=block-snippet.d.ts.map

package/dist/block-snippet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-snippet.d.ts","sourceRoot":"","sources":["../src/block-snippet.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,EAAG,uBAAgC,CAAC;AAE7E,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,MAAM,CAKvE;AAED,8EAA8E;AAC9E,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAUzE"}

package/dist/block-snippet.js

@@ -0,0 +1,30 @@
+/**
+ * Self-contained, diff-inspired capture of the source lines a block refers to.
+ * Stored as a single string in index.json (not a nested JSON object).
+ *
+ * Format (v1): header line `commentray-snippet/v1`, then one line per source
+ * line using unified-diff **context** style: each line begins with a single
+ * space followed by the trimmed source line (empty lines are a lone leading space).
+ */
+export const COMMENTRAY_SNIPPET_HEADER_V1 = "commentray-snippet/v1";
+export function buildCommentraySnippetV1(trimmedLines) {
+    const body = trimmedLines.map((line) => ` ${line}`).join("\n");
+    return body.length === 0
+        ? COMMENTRAY_SNIPPET_HEADER_V1
+        : `${COMMENTRAY_SNIPPET_HEADER_V1}\n${body}`;
+}
+/** Returns trimmed lines, or null if the string is not a valid v1 snippet. */
+export function parseCommentraySnippetV1(snippet) {
+    const lines = snippet.replace(/\r\n/g, "\n").split("\n");
+    if (lines.length === 0 || lines[0] !== COMMENTRAY_SNIPPET_HEADER_V1)
+        return null;
+    const out = [];
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.startsWith(" "))
+            return null;
+        out.push(line.slice(1));
+    }
+    return out;
+}
+//# sourceMappingURL=block-snippet.js.map

package/dist/block-snippet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-snippet.js","sourceRoot":"","sources":["../src/block-snippet.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,uBAAgC,CAAC;AAE7E,MAAM,UAAU,wBAAwB,CAAC,YAAsB;IAC7D,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/D,OAAO,IAAI,CAAC,MAAM,KAAK,CAAC;QACtB,CAAC,CAAC,4BAA4B;QAC9B,CAAC,CAAC,GAAG,4BAA4B,KAAK,IAAI,EAAE,CAAC;AACjD,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,wBAAwB,CAAC,OAAe;IACtD,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,4BAA4B;QAAE,OAAO,IAAI,CAAC;IACjF,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QACvC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,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":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAwB,MAAM,YAAY,CAAC;AAEzF,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 { buildCommentraySnippetV1 } from "./block-snippet.js";
+import { formatMarkerAnchor } from "./anchors.js";
+import { assertValidMarkerId } from "./marker-ids.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 id = input.id !== undefined ? assertValidMarkerId(input.id) : generateBlockId(input.rng);
+    const anchor = formatMarkerAnchor(id);
+    const snippet = snippetFromRange(input.sourceText, range);
+    const block = { id, anchor, markerId: id, snippet };
+    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 snippetFromRange(sourceText, range) {
+    const lines = sourceText.split("\n");
+    const trimmed = [];
+    for (let ln = range.startLine; ln <= range.endLine; ln++) {
+        trimmed.push((lines[ln - 1] ?? "").trim());
+    }
+    return buildCommentraySnippetV1(trimmed);
+}
+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-index-renames.d.ts

@@ -0,0 +1,21 @@
+import type { ResolvedCommentrayConfig } from "./config.js";
+import type { CommentrayIndex } from "./model.js";
+import type { ScmPathRename } from "./scm/scm-provider.js";
+export type { ScmPathRename as PathRename } from "./scm/scm-provider.js";
+/**
+ * When Angles layout is active, returns the angle id segment from a commentray path under
+ * `{storage}/source/<sourcePath>/<angle>.md`, or null if the path does not match that shape.
+ */
+export declare function inferAngleIdFromCommentrayPath(commentrayPath: string, sourcePath: string, storageDir: string): string | null;
+/**
+ * Applies Git-style **full-path** renames to `index.json` entries:
+ * - exact renames on `sourcePath` and `commentrayPath` (string equality),
+ * - when `sourcePath` changes, recomputes `commentrayPath` from layout rules so companion paths stay paired.
+ *
+ * Renames should be sorted longest-`from` first by the caller; this function sorts defensively.
+ */
+export declare function applyPathRenamesToCommentrayIndex(index: CommentrayIndex, renames: readonly ScmPathRename[], repoRoot: string, config: ResolvedCommentrayConfig): {
+    index: CommentrayIndex;
+    changed: boolean;
+};
+//# sourceMappingURL=commentray-index-renames.d.ts.map

package/dist/commentray-index-renames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commentray-index-renames.d.ts","sourceRoot":"","sources":["../src/commentray-index-renames.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAwB,MAAM,YAAY,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAQ3D,YAAY,EAAE,aAAa,IAAI,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAazE;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CASf;AAED;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,wBAAwB,GAC/B;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CA6D9C"}

package/dist/commentray-index-renames.js

@@ -0,0 +1,85 @@
+import { assertValidAngleId } from "./angles.js";
+import { commentrayAnglesLayoutEnabled, commentrayMarkdownPath, commentrayMarkdownPathForAngle, normalizeRepoRelativePath, } from "./paths.js";
+function applyExactPathRenames(repoRelativePath, renames) {
+    let p = normalizeRepoRelativePath(repoRelativePath);
+    for (const { from, to } of renames) {
+        if (p === from)
+            p = to;
+    }
+    return p;
+}
+/**
+ * When Angles layout is active, returns the angle id segment from a commentray path under
+ * `{storage}/source/<sourcePath>/<angle>.md`, or null if the path does not match that shape.
+ */
+export function inferAngleIdFromCommentrayPath(commentrayPath, sourcePath, storageDir) {
+    const sd = normalizeRepoRelativePath(storageDir.replaceAll("\\", "/"));
+    const src = normalizeRepoRelativePath(sourcePath);
+    const prefix = `${sd}/source/${src}/`;
+    if (!commentrayPath.startsWith(prefix))
+        return null;
+    const rest = commentrayPath.slice(prefix.length);
+    if (!rest.endsWith(".md"))
+        return null;
+    const id = rest.slice(0, -".md".length);
+    return id.length > 0 ? id : null;
+}
+/**
+ * Applies Git-style **full-path** renames to `index.json` entries:
+ * - exact renames on `sourcePath` and `commentrayPath` (string equality),
+ * - when `sourcePath` changes, recomputes `commentrayPath` from layout rules so companion paths stay paired.
+ *
+ * Renames should be sorted longest-`from` first by the caller; this function sorts defensively.
+ */
+export function applyPathRenamesToCommentrayIndex(index, renames, repoRoot, config) {
+    const sorted = [...renames]
+        .map((r) => ({
+        from: normalizeRepoRelativePath(r.from),
+        to: normalizeRepoRelativePath(r.to),
+    }))
+        .filter((r) => r.from !== r.to)
+        .sort((a, b) => b.from.length - a.from.length);
+    if (sorted.length === 0)
+        return { index, changed: false };
+    const anglesLayout = commentrayAnglesLayoutEnabled(repoRoot, config.storageDir);
+    const next = {};
+    let changed = false;
+    for (const [, entry] of Object.entries(index.byCommentrayPath)) {
+        const sp = applyExactPathRenames(entry.sourcePath, sorted);
+        let cp = applyExactPathRenames(entry.commentrayPath, sorted);
+        if (sp !== entry.sourcePath) {
+            if (anglesLayout) {
+                const angleId = inferAngleIdFromCommentrayPath(entry.commentrayPath, entry.sourcePath, config.storageDir);
+                if (angleId) {
+                    try {
+                        cp = commentrayMarkdownPathForAngle(sp, assertValidAngleId(angleId), config.storageDir);
+                    }
+                    catch {
+                        /* keep cp from exact renames if angle segment is not a valid id */
+                    }
+                }
+            }
+            else {
+                cp = commentrayMarkdownPath(sp, config.storageDir);
+            }
+        }
+        const newEntry = {
+            ...entry,
+            sourcePath: sp,
+            commentrayPath: cp,
+        };
+        if (sp !== entry.sourcePath || cp !== entry.commentrayPath) {
+            changed = true;
+        }
+        if (next[cp]) {
+            throw new Error(`After applying renames, two index entries map to the same commentrayPath "${cp}" ` +
+                `(merge or fix renames before retrying).`);
+        }
+        next[cp] = newEntry;
+    }
+    return {
+        index: { schemaVersion: index.schemaVersion, byCommentrayPath: next },
+        changed,
+    };
+}
+//# sourceMappingURL=commentray-index-renames.js.map

package/dist/commentray-index-renames.js.map

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