@commentray/core 0.0.2 → 0.0.5

package/dist/marker-validation.js

@@ -0,0 +1,138 @@
+import { parseAnchor } from "./anchors.js";
+import { assertValidMarkerId } from "./marker-ids.js";
+import { parseCommentrayRegionBoundary } from "./source-markers.js";
+/**
+ * Scans a single source file for Commentray region / marker boundaries and reports:
+ * - invalid ids (syntax that matched but fails `assertValidMarkerId` — rare),
+ * - duplicate **start** for the same id before its `end`,
+ * - orphan **end** lines,
+ * - **start** without a matching **end** (unclosed region).
+ */
+export function validateMarkerBoundariesInSource(sourceText, sourcePath) {
+    const issues = [];
+    const lines = sourceText.replaceAll("\r\n", "\n").split("\n");
+    const pendingStartLine = new Map();
+    for (let line0 = 0; line0 < lines.length; line0++) {
+        const hit = parseCommentrayRegionBoundary(lines[line0] ?? "");
+        if (!hit)
+            continue;
+        try {
+            assertValidMarkerId(hit.id);
+        }
+        catch (e) {
+            issues.push({
+                level: "error",
+                message: `${sourcePath}:${line0 + 1}: ${e instanceof Error ? e.message : String(e)}`,
+            });
+            continue;
+        }
+        const loc = `${sourcePath}:${line0 + 1}`;
+        if (hit.kind === "start") {
+            const priorStart = pendingStartLine.get(hit.id);
+            if (priorStart !== undefined) {
+                const prev = priorStart + 1;
+                issues.push({
+                    level: "error",
+                    message: `${loc}: duplicate commentray start for id "${hit.id}" (also opened at line ${prev}). Close the previous region first, or use a unique id per region.`,
+                });
+                continue;
+            }
+            pendingStartLine.set(hit.id, line0);
+            continue;
+        }
+        const start0 = pendingStartLine.get(hit.id);
+        if (start0 === undefined) {
+            issues.push({
+                level: "error",
+                message: `${loc}: commentray end for id "${hit.id}" has no matching start in this file.`,
+            });
+            continue;
+        }
+        pendingStartLine.delete(hit.id);
+    }
+    for (const [id, line0] of pendingStartLine) {
+        issues.push({
+            level: "error",
+            message: `${sourcePath}:${line0 + 1}: commentray start for id "${id}" has no matching end in this file.`,
+        });
+    }
+    return issues;
+}
+function markerIdFromBlock(block) {
+    try {
+        const a = parseAnchor(block.anchor);
+        if (a.kind === "marker")
+            return a.id;
+    }
+    catch {
+        return null;
+    }
+    if (typeof block.markerId === "string" && block.markerId.trim() !== "") {
+        try {
+            return assertValidMarkerId(block.markerId);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Index-level rules for stable cross-references:
+ * - **Error** if the same `(sourcePath, marker id)` is claimed by **different** block `id`s
+ *   (e.g. two Angle files disagree).
+ * - **Warn** if the same marker id string is reused across **different** source files
+ *   (repo-wide ambiguity for links and search — allowed, but noisy).
+ */
+export function validateIndexMarkerSemantics(index) {
+    const issues = [];
+    const bySourceAndMarker = new Map();
+    const byMarkerRepoWide = new Map();
+    for (const [commentrayPath, entry] of Object.entries(index.byCommentrayPath)) {
+        for (const block of entry.blocks) {
+            const mid = markerIdFromBlock(block);
+            if (mid === null)
+                continue;
+            const key = `${entry.sourcePath}\0${mid}`;
+            const loc = {
+                sourcePath: entry.sourcePath,
+                commentrayPath,
+                blockId: block.id,
+            };
+            const list = bySourceAndMarker.get(key) ?? [];
+            list.push(loc);
+            bySourceAndMarker.set(key, list);
+            const sources = byMarkerRepoWide.get(mid) ?? new Set();
+            sources.add(entry.sourcePath);
+            byMarkerRepoWide.set(mid, sources);
+        }
+    }
+    for (const [composite, locs] of bySourceAndMarker) {
+        if (locs.length < 2)
+            continue;
+        const sep = composite.indexOf("\0");
+        const sourcePath = composite.slice(0, sep);
+        const mid = composite.slice(sep + 1);
+        const blockIds = new Set(locs.map((l) => l.blockId));
+        if (blockIds.size > 1) {
+            const detail = locs.map((l) => `${l.blockId} (${l.commentrayPath})`).join(", ");
+            issues.push({
+                level: "error",
+                message: `Marker id "${mid}" for source "${sourcePath}" is indexed with different block ids: ${detail}. ` +
+                    `One physical region should map to one block id (e.g. align Angle files or deduplicate).`,
+            });
+        }
+    }
+    for (const [mid, sources] of byMarkerRepoWide) {
+        if (sources.size <= 1)
+            continue;
+        const paths = [...sources].sort((a, b) => a.localeCompare(b)).join(", ");
+        issues.push({
+            level: "warn",
+            message: `Marker id "${mid}" is reused across different source files (${paths}). ` +
+                `That is valid for independent regions, but ambiguous for repo-wide links — consider namespaced ids (e.g. "${mid}--dashboard", "${mid}--api").`,
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=marker-validation.js.map

package/dist/marker-validation.js.map

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

package/dist/metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAA0B,MAAM,YAAY,CAAC;AAE1E,wBAAgB,UAAU,IAAI,eAAe,CAE5C;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAiBhE"}
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,eAAe,EAAoD,MAAM,YAAY,CAAC;AAEpG,wBAAgB,UAAU,IAAI,eAAe,CAE5C;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAwBhE"}

package/dist/metadata.js

@@ -1,4 +1,7 @@
-import { CURRENT_SCHEMA_VERSION } from "./model.js";
+import { parseAnchor } from "./anchors.js";
+import { describeIndexSchemaRemediation } from "./index-schema-messages.js";
+import { assertValidMarkerId } from "./marker-ids.js";
+import { coerceIndexSchemaVersion, CURRENT_SCHEMA_VERSION } from "./model.js";
 export function emptyIndex() {
     return { schemaVersion: CURRENT_SCHEMA_VERSION, byCommentrayPath: {} };
 }
@@ -7,9 +10,12 @@ export function assertValidIndex(value) {
         throw new TypeError("index.json must be a JSON object");
     }
     const obj = value;
-    const schemaVersion = obj.schemaVersion;
+    const schemaVersion = coerceIndexSchemaVersion(obj.schemaVersion);
+    if (schemaVersion === null) {
+        throw new TypeError(`index.json schemaVersion must be an integer (got ${String(obj.schemaVersion)})`);
+    }
     if (schemaVersion !== CURRENT_SCHEMA_VERSION) {
-        throw new Error(`Unsupported schemaVersion: ${String(schemaVersion)}`);
+        throw new Error(`index.json schemaVersion mismatch. ${describeIndexSchemaRemediation(obj.schemaVersion)}`);
     }
     const byCommentrayPath = obj.byCommentrayPath;
     if (typeof byCommentrayPath !== "object" || byCommentrayPath === null) {
@@ -18,7 +24,7 @@ export function assertValidIndex(value) {
     for (const [key, entry] of Object.entries(byCommentrayPath)) {
         validateCommentrayEntry(key, entry);
     }
-    return obj;
+    return { ...obj, schemaVersion: CURRENT_SCHEMA_VERSION };
 }
 function validateCommentrayEntry(commentrayPathKey, entry) {
     if (typeof entry !== "object" || entry === null) {
@@ -40,17 +46,35 @@ function validateCommentrayEntry(commentrayPathKey, entry) {
     for (const block of e.blocks)
         validateBlock(commentrayPathKey, block);
 }
-function validateBlock(commentrayPathKey, block) {
-    if (typeof block !== "object" || block === null) {
-        throw new TypeError(`Invalid block under ${commentrayPathKey}`);
+function parseValidatedMarkerId(commentrayPathKey, raw) {
+    try {
+        return assertValidMarkerId(raw);
     }
-    const b = block;
-    if (typeof b.id !== "string") {
-        throw new TypeError(`block.id must be a string under ${commentrayPathKey}`);
+    catch (e) {
+        throw new TypeError(`block.id invalid under ${commentrayPathKey}: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
     }
-    if (typeof b.anchor !== "string") {
-        throw new TypeError(`block.anchor must be a string under ${commentrayPathKey}`);
+}
+function parseValidatedAnchor(commentrayPathKey, raw) {
+    try {
+        return parseAnchor(raw);
+    }
+    catch (e) {
+        throw new TypeError(`Invalid block.anchor under ${commentrayPathKey}: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+    }
+}
+function assertBlockMarkerAnchorConsistency(commentrayPathKey, b, bid, parsedAnchor) {
+    if (parsedAnchor.kind === "marker" && parsedAnchor.id !== bid) {
+        throw new TypeError(`block.id must match marker anchor id (got id=${b.id}, anchor=${b.anchor}) under ${commentrayPathKey}`);
     }
+    if (parsedAnchor.kind === "marker" &&
+        b.markerId !== undefined &&
+        typeof b.markerId === "string" &&
+        b.markerId.trim() !== "" &&
+        assertValidMarkerId(b.markerId) !== parsedAnchor.id) {
+        throw new TypeError(`block.markerId must match marker anchor id under ${commentrayPathKey} (block ${b.id})`);
+    }
+}
+function validateBlockOptionalFields(commentrayPathKey, b) {
     if (b.lastVerifiedCommit !== undefined && typeof b.lastVerifiedCommit !== "string") {
         throw new TypeError(`block.lastVerifiedCommit must be a string when present under ${commentrayPathKey}`);
     }
@@ -60,22 +84,27 @@ function validateBlock(commentrayPathKey, block) {
     if (b.markerId !== undefined && typeof b.markerId !== "string") {
         throw new TypeError(`block.markerId must be a string when present under ${commentrayPathKey}`);
     }
-    if (b.fingerprint !== undefined)
-        validateFingerprint(commentrayPathKey, b.fingerprint);
-}
-function validateFingerprint(commentrayPathKey, fp) {
-    if (typeof fp !== "object" || fp === null) {
-        throw new TypeError(`block.fingerprint must be an object under ${commentrayPathKey}`);
+    if (b.snippet !== undefined && typeof b.snippet !== "string") {
+        throw new TypeError(`block.snippet must be a string when present under ${commentrayPathKey}`);
     }
-    const f = fp;
-    if (typeof f.startLine !== "string") {
-        throw new TypeError(`block.fingerprint.startLine must be a string under ${commentrayPathKey}`);
+    if (b.fingerprint !== undefined) {
+        throw new TypeError(`block.fingerprint is no longer supported under ${commentrayPathKey}; re-open the repo to migrate index.json`);
     }
-    if (typeof f.endLine !== "string") {
-        throw new TypeError(`block.fingerprint.endLine must be a string under ${commentrayPathKey}`);
+}
+function validateBlock(commentrayPathKey, block) {
+    if (typeof block !== "object" || block === null) {
+        throw new TypeError(`Invalid block under ${commentrayPathKey}`);
     }
-    if (typeof f.lineCount !== "number" || !Number.isInteger(f.lineCount) || f.lineCount < 1) {
-        throw new TypeError(`block.fingerprint.lineCount must be a positive integer under ${commentrayPathKey}`);
+    const b = block;
+    if (typeof b.id !== "string") {
+        throw new TypeError(`block.id must be a string under ${commentrayPathKey}`);
+    }
+    const bid = parseValidatedMarkerId(commentrayPathKey, b.id);
+    if (typeof b.anchor !== "string") {
+        throw new TypeError(`block.anchor must be a string under ${commentrayPathKey}`);
     }
+    const parsedAnchor = parseValidatedAnchor(commentrayPathKey, b.anchor);
+    assertBlockMarkerAnchorConsistency(commentrayPathKey, b, bid, parsedAnchor);
+    validateBlockOptionalFields(commentrayPathKey, b);
 }
 //# sourceMappingURL=metadata.js.map

package/dist/metadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAE1E,MAAM,UAAU,UAAU;IACxB,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,EAAE,EAAE,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,MAAM,IAAI,SAAS,CAAC,kCAAkC,CAAC,CAAC;IAC1D,CAAC;IACD,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,MAAM,aAAa,GAAG,GAAG,CAAC,aAAa,CAAC;IACxC,IAAI,aAAa,KAAK,sBAAsB,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,8BAA8B,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,MAAM,gBAAgB,GAAG,GAAG,CAAC,gBAAgB,CAAC;IAC9C,IAAI,OAAO,gBAAgB,KAAK,QAAQ,IAAI,gBAAgB,KAAK,IAAI,EAAE,CAAC;QACtE,MAAM,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAC;IACvE,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAC5D,uBAAuB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,GAAsB,CAAC;AAChC,CAAC;AAED,SAAS,uBAAuB,CAAC,iBAAyB,EAAE,KAAc;IACxE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,MAAM,IAAI,SAAS,CAAC,2BAA2B,iBAAiB,EAAE,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,IAAI,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,IAAI,SAAS,CAAC,0BAA0B,iBAAiB,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,OAAO,CAAC,CAAC,cAAc,KAAK,QAAQ,EAAE,CAAC;QACzC,MAAM,IAAI,SAAS,CAAC,8BAA8B,iBAAiB,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,CAAC,CAAC,cAAc,KAAK,iBAAiB,EAAE,CAAC;QAC3C,MAAM,IAAI,SAAS,CACjB,kDAAkD,iBAAiB,WAAW,CAAC,CAAC,cAAc,GAAG,CAClG,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,SAAS,CAAC,+BAA+B,iBAAiB,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,CAAC,CAAC,MAAM;QAAE,aAAa,CAAC,iBAAiB,EAAE,KAAK,CAAC,CAAC;AACxE,CAAC;AAED,SAAS,aAAa,CAAC,iBAAyB,EAAE,KAAc;IAC9D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,MAAM,IAAI,SAAS,CAAC,uBAAuB,iBAAiB,EAAE,CAAC,CAAC;IAClE,CAAC;IACD,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,IAAI,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;QAC7B,MAAM,IAAI,SAAS,CAAC,mCAAmC,iBAAiB,EAAE,CAAC,CAAC;IAC9E,CAAC;IACD,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QACjC,MAAM,IAAI,SAAS,CAAC,uCAAuC,iBAAiB,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,IAAI,CAAC,CAAC,kBAAkB,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,kBAAkB,KAAK,QAAQ,EAAE,CAAC;QACnF,MAAM,IAAI,SAAS,CACjB,gEAAgE,iBAAiB,EAAE,CACpF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,CAAC,gBAAgB,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,gBAAgB,KAAK,QAAQ,EAAE,CAAC;QAC/E,MAAM,IAAI,SAAS,CACjB,8DAA8D,iBAAiB,EAAE,CAClF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC/D,MAAM,IAAI,SAAS,CAAC,sDAAsD,iBAAiB,EAAE,CAAC,CAAC;IACjG,CAAC;IACD,IAAI,CAAC,CAAC,WAAW,KAAK,SAAS;QAAE,mBAAmB,CAAC,iBAAiB,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;AACzF,CAAC;AAED,SAAS,mBAAmB,CAAC,iBAAyB,EAAE,EAAW;IACjE,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;QAC1C,MAAM,IAAI,SAAS,CAAC,6CAA6C,iBAAiB,EAAE,CAAC,CAAC;IACxF,CAAC;IACD,MAAM,CAAC,GAAG,EAA6B,CAAC;IACxC,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,SAAS,CAAC,sDAAsD,iBAAiB,EAAE,CAAC,CAAC;IACjG,CAAC;IACD,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QAClC,MAAM,IAAI,SAAS,CAAC,oDAAoD,iBAAiB,EAAE,CAAC,CAAC;IAC/F,CAAC;IACD,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;QACzF,MAAM,IAAI,SAAS,CACjB,gEAAgE,iBAAiB,EAAE,CACpF,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"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"}

package/dist/migrate-angles-layout.d.ts

@@ -0,0 +1,27 @@
+import type { CommentrayIndex } from "./model.js";
+export type FlatCompanionEntry = {
+    /** Repo-relative path, e.g. `.commentray/source/README.md.md`. */
+    flatCommentrayPath: string;
+    /** Repo-relative primary source path, e.g. `README.md`. */
+    sourcePath: string;
+};
+export type AnglesMigrationMove = {
+    fromRepoRel: string;
+    toRepoRel: string;
+    sourcePath: string;
+};
+export type AnglesMigrationPlan = {
+    moves: AnglesMigrationMove[];
+    /** Old flat companion path → new angle Markdown path (repo-relative). */
+    flatToAnglePath: Map<string, string>;
+};
+/**
+ * Lists every flat-layout companion Markdown file under `{storage}/source/`.
+ * Returns an empty list when Angles layout is already enabled (sentinel present).
+ */
+export declare function discoverFlatCompanionMarkdownFiles(repoRoot: string, storageDir?: string): Promise<FlatCompanionEntry[]>;
+/** `rel` is relative to `{storage}/source/` using `/` separators. */
+export declare function flatRelToSourcePath(relFromSourceDir: string): string;
+export declare function planAnglesMigrationFromCompanions(companions: FlatCompanionEntry[], angleId: string, storageDir: string): AnglesMigrationPlan;
+export declare function rewriteIndexKeysForAnglesMigration(index: CommentrayIndex, flatToAnglePath: Map<string, string>): CommentrayIndex;
+//# sourceMappingURL=migrate-angles-layout.d.ts.map

package/dist/migrate-angles-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-angles-layout.d.ts","sourceRoot":"","sources":["../src/migrate-angles-layout.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAwB,MAAM,YAAY,CAAC;AAQxE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,kEAAkE;IAClE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,yEAAyE;IACzE,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC,CAAC;AAEF;;;GAGG;AACH,wBAAsB,kCAAkC,CACtD,QAAQ,EAAE,MAAM,EAChB,UAAU,SAAgB,GACzB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA2B/B;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAKpE;AAED,wBAAgB,iCAAiC,CAC/C,UAAU,EAAE,kBAAkB,EAAE,EAChC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,mBAAmB,CAerB;AAED,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,eAAe,EACtB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,eAAe,CAOjB"}

package/dist/migrate-angles-layout.js

@@ -0,0 +1,72 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertValidAngleId } from "./angles.js";
+import { commentrayAnglesLayoutEnabled, commentrayMarkdownPathForAngle, normalizeRepoRelativePath, } from "./paths.js";
+import { collectMdRelPathsUnderSourceAbs } from "./walk-commentray-source-md.js";
+/**
+ * Lists every flat-layout companion Markdown file under `{storage}/source/`.
+ * Returns an empty list when Angles layout is already enabled (sentinel present).
+ */
+export async function discoverFlatCompanionMarkdownFiles(repoRoot, storageDir = ".commentray") {
+    if (commentrayAnglesLayoutEnabled(repoRoot, storageDir)) {
+        return [];
+    }
+    const storageNorm = normalizeRepoRelativePath(storageDir.replaceAll("\\", "/"));
+    const sourceAbs = path.join(repoRoot, ...storageNorm.split("/"), "source");
+    let stat;
+    try {
+        stat = await fs.stat(sourceAbs);
+    }
+    catch {
+        return [];
+    }
+    if (!stat.isDirectory()) {
+        return [];
+    }
+    const rels = await collectMdRelPathsUnderSourceAbs(sourceAbs);
+    const out = [];
+    for (const rel of rels) {
+        if (rel === ".default" || rel.startsWith(".default/"))
+            continue;
+        if (!rel.endsWith(".md"))
+            continue;
+        const sourcePath = flatRelToSourcePath(rel);
+        const flatCommentrayPath = path.posix.join(storageNorm, "source", rel);
+        out.push({ flatCommentrayPath, sourcePath });
+    }
+    out.sort((a, b) => a.flatCommentrayPath.localeCompare(b.flatCommentrayPath));
+    return out;
+}
+/** `rel` is relative to `{storage}/source/` using `/` separators. */
+export function flatRelToSourcePath(relFromSourceDir) {
+    if (!relFromSourceDir.endsWith(".md")) {
+        throw new Error(`Expected *.md under source, got: ${relFromSourceDir}`);
+    }
+    return relFromSourceDir.slice(0, Math.max(0, relFromSourceDir.length - 3));
+}
+export function planAnglesMigrationFromCompanions(companions, angleId, storageDir) {
+    const id = assertValidAngleId(angleId);
+    const moves = [];
+    const flatToAnglePath = new Map();
+    for (const c of companions) {
+        const toRepoRel = commentrayMarkdownPathForAngle(c.sourcePath, id, storageDir);
+        if (c.flatCommentrayPath === toRepoRel)
+            continue;
+        moves.push({
+            fromRepoRel: c.flatCommentrayPath,
+            toRepoRel: toRepoRel,
+            sourcePath: c.sourcePath,
+        });
+        flatToAnglePath.set(c.flatCommentrayPath, toRepoRel);
+    }
+    return { moves, flatToAnglePath };
+}
+export function rewriteIndexKeysForAnglesMigration(index, flatToAnglePath) {
+    const next = {};
+    for (const [k, entry] of Object.entries(index.byCommentrayPath)) {
+        const newKey = flatToAnglePath.get(k) ?? k;
+        next[newKey] = { ...entry, commentrayPath: newKey };
+    }
+    return { ...index, byCommentrayPath: next };
+}
+//# sourceMappingURL=migrate-angles-layout.js.map

package/dist/migrate-angles-layout.js.map

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

package/dist/migrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EAGrB,MAAM,YAAY,CAAC;AAIpB,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAqCvF"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,YAAY,CAAC;AAIpB,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAuDvF"}

package/dist/migrate.js

@@ -1,4 +1,5 @@
-import { CURRENT_SCHEMA_VERSION, } from "./model.js";
+import { describeIndexSchemaRemediation } from "./index-schema-messages.js";
+import { coerceIndexSchemaVersion, CURRENT_SCHEMA_VERSION, } from "./model.js";
 const LEGACY_SCHEMA_VERSION = 2;
 /** Returns migrated index and whether the file should be rewritten. */
 export function migrateIndex(raw) {
@@ -9,7 +10,10 @@ export function migrateIndex(raw) {
         };
     }
     const obj = raw;
-    const version = obj.schemaVersion;
+    const version = coerceIndexSchemaVersion(obj.schemaVersion);
+    if (version === null && obj.schemaVersion !== undefined) {
+        throw new TypeError(`Invalid index schemaVersion: ${String(obj.schemaVersion)}`);
+    }
     if (version === CURRENT_SCHEMA_VERSION) {
         const index = obj;
         return { index, changed: false };
@@ -24,7 +28,7 @@ export function migrateIndex(raw) {
             byCommentrayPath,
         };
         const before = JSON.stringify({
-            schemaVersion: version ?? 0,
+            schemaVersion: version === undefined ? 0 : version,
             bySourceFile: obj.bySourceFile ?? {},
             byCommentrayPath: obj.byCommentrayPath ?? {},
         });
@@ -32,7 +36,19 @@ export function migrateIndex(raw) {
         const changed = before !== after;
         return { index: next, changed };
     }
-    throw new Error(`Cannot migrate from schemaVersion ${String(version)}`);
+    if (typeof version === "number" && version > CURRENT_SCHEMA_VERSION) {
+        /**
+         * Future CLI may bump `schemaVersion` before every consumer updates. Prefer opening
+         * the repo over hard failure: keep `byCommentrayPath` as parsed, stamp this build’s
+         * schema, and let `assertValidIndex` reject only truly incompatible shapes.
+         */
+        const byCommentrayPath = toByCommentrayPath(obj);
+        return {
+            index: { schemaVersion: CURRENT_SCHEMA_VERSION, byCommentrayPath },
+            changed: true,
+        };
+    }
+    throw new Error(`Cannot migrate index.json from schemaVersion ${String(obj.schemaVersion)}. ${describeIndexSchemaRemediation(obj.schemaVersion)}`);
 }
 function toByCommentrayPath(obj) {
     if (obj.byCommentrayPath &&

package/dist/migrate.js.map

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

package/dist/model.d.ts

@@ -1,21 +1,3 @@
-/**
- * Content fingerprint of a source range, used to re-resolve the block's
- * anchor after lines drift (insertions or deletions in the source).
- *
- * A fingerprint is intentionally narrow: trimmed text of the first and last
- * lines plus the original line count. Re-resolution is a search, not a
- * guarantee: when the fingerprint still appears uniquely near the old
- * location we silently update the line numbers; otherwise we surface a
- * diagnostic so a human can decide.
- */
-export type CommentrayBlockFingerprint = {
-    /** Trimmed content of the first line of the original range. */
-    startLine: string;
-    /** Trimmed content of the last line of the original range. */
-    endLine: string;
-    /** Number of lines the range originally spanned (end - start + 1). */
-    lineCount: number;
-};
 /** Commentray block aligned to a region of a primary source file. */
 export type CommentrayBlock = {
     /** Stable id within the commentray markdown file. */
@@ -23,16 +5,16 @@ export type CommentrayBlock = {
     /** Human or machine anchor string (see anchor grammar in docs). */
     anchor: string;
     /**
-     * Optional drift-resolution fingerprint. Present when the block's range
-     * was captured from source content; absent when the anchor is purely a
-     * symbol or marker reference that does not need content-based re-sync.
+     * Optional unified-diff–style capture of the anchored source lines (see
+     * `block-snippet.ts`). Self-contained string in index.json — not a nested
+     * JSON region object.
      */
-    fingerprint?: CommentrayBlockFingerprint;
+    snippet?: string;
     /**
-     * Optional marker-based anchor. When set, drift resolution looks for a
-     * pair of host-language comments of the form `commentray:start id=<markerId>`
-     * and `commentray:end` in the source; the lines between them become the
-     * block's effective range. Markers are drift-proof but invasive.
+     * When the anchor is `marker:<id>`, the same id appears in source as the
+     * region name `commentray:<id>` (e.g. `//#region` / `//#endregion` in
+     * TypeScript, aligned with the Region Marker extension), or in legacy
+     * `commentray:start id=…` / `commentray:end id=…` line comments.
      */
     markerId?: string;
     /** Last human-verified commit (full SHA) when this block was considered accurate. */
@@ -59,4 +41,9 @@ export type CommentrayIndex = {
     byCommentrayPath: Record<string, SourceFileIndexEntry>;
 };
 export declare const CURRENT_SCHEMA_VERSION: 3;
+/**
+ * Normalizes `index.json` `schemaVersion` after `JSON.parse` (integer, or
+ * rare string forms like `"3"`).
+ */
+export declare function coerceIndexSchemaVersion(raw: unknown): number | undefined | null;
 //# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,qEAAqE;AACrE,MAAM,MAAM,eAAe,GAAG;IAC5B,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,WAAW,CAAC,EAAE,0BAA0B,CAAC;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B,CAAC;AAEF,2EAA2E;AAC3E,MAAM,MAAM,eAAe,GAAG;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CACxD,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAG,CAAU,CAAC"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,MAAM,MAAM,eAAe,GAAG;IAC5B,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B,CAAC;AAEF,2EAA2E;AAC3E,MAAM,MAAM,eAAe,GAAG;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CACxD,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAG,CAAU,CAAC;AAEjD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,CAQhF"}

package/dist/model.js

@@ -1,2 +1,18 @@
 export const CURRENT_SCHEMA_VERSION = 3;
+/**
+ * Normalizes `index.json` `schemaVersion` after `JSON.parse` (integer, or
+ * rare string forms like `"3"`).
+ */
+export function coerceIndexSchemaVersion(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw === "number" && Number.isInteger(raw))
+        return raw;
+    if (typeof raw === "string") {
+        const t = raw.trim();
+        if (/^\d+$/.test(t))
+            return Number.parseInt(t, 10);
+    }
+    return null;
+}
 //# sourceMappingURL=model.js.map

package/dist/model.js.map

@@ -1 +1 @@
-{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAgEA,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAU,CAAC"}
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AA6CA,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAU,CAAC;AAEjD;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAY;IACnD,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IACjE,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QACrB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;YAAE,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/paths.d.ts

@@ -11,8 +11,14 @@
  * `..` segments are traversal.
  */
 export declare function normalizeRepoRelativePath(relativePath: string): string;
+/**
+ * Resolve `repoRelative` under `repoRootAbs` after {@link normalizeRepoRelativePath} validation,
+ * then assert the absolute path cannot escape `repoRootAbs` (defense in depth for index or
+ * nav-derived paths, not only hand-edited config).
+ */
+export declare function resolvePathUnderRepoRoot(repoRootAbs: string, repoRelative: string): string;
 /** Commentray Markdown path for a repo-relative source file (implicit default angle, flat layout). */
-export declare function commentrayMarkdownPath(sourceRepoRelativePath: string): string;
+export declare function commentrayMarkdownPath(sourceRepoRelativePath: string, storageDir?: string): string;
 /**
  * Repo-relative path to the **Angles sentinel**: if this path exists as a file or directory under
  * the storage root, the repository opts into per-source **Angles** layout (see `docs/spec/storage.md`).

package/dist/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAWtE;AAED,sGAAsG;AACtG,wBAAgB,sBAAsB,CAAC,sBAAsB,EAAE,MAAM,GAAG,MAAM,CAG7E;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,SAAgB,GAAG,MAAM,CAG/E;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,UAAU,SAAgB,GACzB,OAAO,CAIT;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,sBAAsB,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM,EACf,UAAU,SAAgB,GACzB,MAAM,CAKR;AAED,uDAAuD;AACvD,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAWtE;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAS1F;AAED,sGAAsG;AACtG,wBAAgB,sBAAsB,CACpC,sBAAsB,EAAE,MAAM,EAC9B,UAAU,SAAgB,GACzB,MAAM,CAIR;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,SAAgB,GAAG,MAAM,CAG/E;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,UAAU,SAAgB,GACzB,OAAO,CAIT;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,sBAAsB,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM,EACf,UAAU,SAAgB,GACzB,MAAM,CAKR;AAED,uDAAuD;AACvD,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD"}

package/dist/paths.js

@@ -25,10 +25,26 @@ export function normalizeRepoRelativePath(relativePath) {
     }
     return segments.join("/");
 }
+/**
+ * Resolve `repoRelative` under `repoRootAbs` after {@link normalizeRepoRelativePath} validation,
+ * then assert the absolute path cannot escape `repoRootAbs` (defense in depth for index or
+ * nav-derived paths, not only hand-edited config).
+ */
+export function resolvePathUnderRepoRoot(repoRootAbs, repoRelative) {
+    const rel = normalizeRepoRelativePath(repoRelative);
+    const root = path.resolve(repoRootAbs);
+    const resolved = path.resolve(root, rel);
+    const back = path.relative(root, resolved);
+    if (back.startsWith("..") || path.isAbsolute(back)) {
+        throw new Error(`Resolved path leaves repository root: ${repoRelative}`);
+    }
+    return resolved;
+}
 /** Commentray Markdown path for a repo-relative source file (implicit default angle, flat layout). */
-export function commentrayMarkdownPath(sourceRepoRelativePath) {
+export function commentrayMarkdownPath(sourceRepoRelativePath, storageDir = ".commentray") {
     const normalized = normalizeRepoRelativePath(sourceRepoRelativePath);
-    return path.posix.join(".commentray", "source", `${normalized}.md`);
+    const root = normalizeRepoRelativePath(storageDir.replaceAll("\\", "/"));
+    return path.posix.join(root, "source", `${normalized}.md`);
 }
 /**
  * Repo-relative path to the **Angles sentinel**: if this path exists as a file or directory under