@commentray/core 0.0.2 → 0.0.4

package/dist/index-schema-messages.js

@@ -0,0 +1,26 @@
+import { CURRENT_SCHEMA_VERSION } from "./model.js";
+function formatObservedSchema(raw) {
+    if (raw === undefined)
+        return "missing";
+    if (typeof raw === "number" || typeof raw === "string")
+        return String(raw);
+    return JSON.stringify(raw);
+}
+/**
+ * Recovery steps when `index.json` `schemaVersion` does not match this build’s
+ * {@link CURRENT_SCHEMA_VERSION} (shown explicitly so you know which number to target).
+ */
+export function describeIndexSchemaRemediation(observedSchema) {
+    const obs = formatObservedSchema(observedSchema);
+    return (`This install expects "schemaVersion": ${String(CURRENT_SCHEMA_VERSION)} in index.json (bundled @commentray/core). ` +
+        `This file has ${obs}. ` +
+        `What to do: ` +
+        `(1) Upgrade Commentray from the same git revision as the index author — from the repo run \`bash scripts/install-extension.sh\` ` +
+        `or \`npm run extension:dogfood\`, then **Developer: Reload Window**. ` +
+        `(2) If the index was written by a *newer* CLI, install that newer Commentray, or open the repo with *this* build: ` +
+        `readIndex downgrades a newer numeric schema after writing a backup under \`.commentray/metadata/\` ` +
+        `named \`index.schema-<old>-backup-<timestamp>.json\`. ` +
+        `(3) Last resort after copying \`.commentray/metadata/\` elsewhere: set \`"schemaVersion": ${String(CURRENT_SCHEMA_VERSION)}\` ` +
+        `only if the rest of the JSON still matches this version’s validator.`);
+}
+//# sourceMappingURL=index-schema-messages.js.map

package/dist/index-schema-messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-schema-messages.js","sourceRoot":"","sources":["../src/index-schema-messages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,SAAS,oBAAoB,CAAC,GAAY;IACxC,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3E,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,8BAA8B,CAAC,cAAuB;IACpE,MAAM,GAAG,GAAG,oBAAoB,CAAC,cAAc,CAAC,CAAC;IACjD,OAAO,CACL,yCAAyC,MAAM,CAAC,sBAAsB,CAAC,6CAA6C;QACpH,iBAAiB,GAAG,IAAI;QACxB,cAAc;QACd,kIAAkI;QAClI,uEAAuE;QACvE,oHAAoH;QACpH,qGAAqG;QACrG,wDAAwD;QACxD,6FAA6F,MAAM,CAAC,sBAAsB,CAAC,KAAK;QAChI,sEAAsE,CACvE,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export type { CommentrayBlock, CommentrayBlockFingerprint, CommentrayIndex, SourceFileIndexEntry, } from "./model.js";
-export { CURRENT_SCHEMA_VERSION } from "./model.js";
+export type { CommentrayBlock, CommentrayIndex, SourceFileIndexEntry } from "./model.js";
+export { coerceIndexSchemaVersion, CURRENT_SCHEMA_VERSION } from "./model.js";
 export type { AddBlockToIndexInput, BlockRange, CreateBlockForRangeInput, CreatedBlock, } from "./blocks.js";
 export { addBlockToIndex, appendBlockToCommentray, createBlockForRange, generateBlockId, } from "./blocks.js";
 export { assertValidAngleId } from "./angles.js";
@@ -12,16 +12,25 @@ export type { CommentrayToml, ResolvedAngleDefinition, ResolvedAngles, ResolvedC
 export { loadCommentrayConfig, mergeCommentrayConfig } from "./config.js";
 export { githubRepoBlobFileUrl, parseGithubRepoWebUrl } from "./github-url.js";
 export { assertValidIndex, emptyIndex } from "./metadata.js";
+export { describeIndexSchemaRemediation } from "./index-schema-messages.js";
 export { migrateIndex } from "./migrate.js";
 export type { ParsedAnchor } from "./anchors.js";
 export { formatLineRange, parseAnchor } from "./anchors.js";
-export type { ScmProvider } from "./scm/scm-provider.js";
-export { GitScmProvider } from "./scm/git-scm-provider.js";
+export type { ScmPathRename, ScmProvider } from "./scm/scm-provider.js";
+export { GitScmProvider, parseGitRenameLines } from "./scm/git-scm-provider.js";
+export { applyPathRenamesToCommentrayIndex, inferAngleIdFromCommentrayPath, } from "./commentray-index-renames.js";
+export type { PathRename } from "./commentray-index-renames.js";
 export type { BlockDiagnostic } from "./staleness.js";
 export { diagnoseBlock } from "./staleness.js";
 export type { ValidationIssue, ValidationResult } from "./validate-project.js";
-export { readIndex, validateProject, writeIndex } from "./validate-project.js";
+export { readIndex, refreshIndexMigrationsOnDisk, validateProject, writeIndex, } from "./validate-project.js";
 export { runCommanderMain } from "./cli-bootstrap.js";
 export type { BlockScrollLink } from "./scroll-sync.js";
 export { buildBlockScrollLinks, pickCommentrayLineForSourceScroll, pickSourceLine0ForCommentrayScroll, } from "./scroll-sync.js";
+export { commentrayRegionInsertions, lineCommentLeaderForLanguage, parseCommentrayRegionBoundary, sourceLineRangeForMarkerId, } from "./source-markers.js";
+export type { CommentrayMarkerPair } from "./region-marker-convert.js";
+export { convertCommentraySourceMarkersToLanguage, findCommentrayMarkerPairs, leadingIndentOfLine, } from "./region-marker-convert.js";
+export { MARKER_ID_BODY, assertValidMarkerId, normaliseMarkerSlugOrThrow } from "./marker-ids.js";
+export type { MarkerValidationIssue } from "./marker-validation.js";
+export { validateIndexMarkerSemantics, validateMarkerBoundariesInSource, } from "./marker-validation.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,eAAe,EACf,0BAA0B,EAC1B,eAAe,EACf,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,YAAY,EACV,oBAAoB,EACpB,UAAU,EACV,wBAAwB,EACxB,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,wBAAwB,EAAE,qCAAqC,EAAE,MAAM,kBAAkB,CAAC;AACnG,YAAY,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,iCAAiC,CAAC;AACzC,YAAY,EAAE,8BAA8B,EAAE,MAAM,iCAAiC,CAAC;AACtF,OAAO,EACL,6BAA6B,EAC7B,4BAA4B,EAC5B,sBAAsB,EACtB,8BAA8B,EAC9B,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,cAAc,EACd,uBAAuB,EACvB,cAAc,EACd,wBAAwB,EACxB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC5D,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EACL,qBAAqB,EACrB,iCAAiC,EACjC,kCAAkC,GACnC,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,4 +1,4 @@
-export { CURRENT_SCHEMA_VERSION } from "./model.js";
+export { coerceIndexSchemaVersion, CURRENT_SCHEMA_VERSION } from "./model.js";
 export { addBlockToIndex, appendBlockToCommentray, createBlockForRange, generateBlockId, } from "./blocks.js";
 export { assertValidAngleId } from "./angles.js";
 export { ensureAnglesSentinelFile, upsertAngleDefinitionInCommentrayToml } from "./angles-toml.js";
@@ -7,11 +7,17 @@ export { commentrayAnglesLayoutEnabled, commentrayAnglesSentinelPath, commentray
 export { loadCommentrayConfig, mergeCommentrayConfig } from "./config.js";
 export { githubRepoBlobFileUrl, parseGithubRepoWebUrl } from "./github-url.js";
 export { assertValidIndex, emptyIndex } from "./metadata.js";
+export { describeIndexSchemaRemediation } from "./index-schema-messages.js";
 export { migrateIndex } from "./migrate.js";
 export { formatLineRange, parseAnchor } from "./anchors.js";
-export { GitScmProvider } from "./scm/git-scm-provider.js";
+export { GitScmProvider, parseGitRenameLines } from "./scm/git-scm-provider.js";
+export { applyPathRenamesToCommentrayIndex, inferAngleIdFromCommentrayPath, } from "./commentray-index-renames.js";
 export { diagnoseBlock } from "./staleness.js";
-export { readIndex, validateProject, writeIndex } from "./validate-project.js";
+export { readIndex, refreshIndexMigrationsOnDisk, validateProject, writeIndex, } from "./validate-project.js";
 export { runCommanderMain } from "./cli-bootstrap.js";
 export { buildBlockScrollLinks, pickCommentrayLineForSourceScroll, pickSourceLine0ForCommentrayScroll, } from "./scroll-sync.js";
+export { commentrayRegionInsertions, lineCommentLeaderForLanguage, parseCommentrayRegionBoundary, sourceLineRangeForMarkerId, } from "./source-markers.js";
+export { convertCommentraySourceMarkersToLanguage, findCommentrayMarkerPairs, leadingIndentOfLine, } from "./region-marker-convert.js";
+export { MARKER_ID_BODY, assertValidMarkerId, normaliseMarkerSlugOrThrow } from "./marker-ids.js";
+export { validateIndexMarkerSemantics, validateMarkerBoundariesInSource, } from "./marker-validation.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAOpD,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,wBAAwB,EAAE,qCAAqC,EAAE,MAAM,kBAAkB,CAAC;AAEnG,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,6BAA6B,EAC7B,4BAA4B,EAC5B,sBAAsB,EACtB,8BAA8B,EAC9B,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AASpB,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EACL,qBAAqB,EACrB,iCAAiC,EACjC,kCAAkC,GACnC,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAO9E,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,wBAAwB,EAAE,qCAAqC,EAAE,MAAM,kBAAkB,CAAC;AAEnG,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,6BAA6B,EAC7B,4BAA4B,EAC5B,sBAAsB,EACtB,8BAA8B,EAC9B,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AASpB,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChF,OAAO,EACL,iCAAiC,EACjC,8BAA8B,GAC/B,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EACL,SAAS,EACT,4BAA4B,EAC5B,eAAe,EACf,UAAU,GACX,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EACL,qBAAqB,EACrB,iCAAiC,EACjC,kCAAkC,GACnC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,0BAA0B,EAC1B,4BAA4B,EAC5B,6BAA6B,EAC7B,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wCAAwC,EACxC,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAElG,OAAO,EACL,4BAA4B,EAC5B,gCAAgC,GACjC,MAAM,wBAAwB,CAAC"}

package/dist/marker-ids.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Marker / block ids used in `marker:<id>` anchors, `markerId` in the index, and
+ * `commentray:<id>` / `commentray:start id=<id>` in source. Designed so authors
+ * can type **short slugs** (`intro`, `auth-flow`, `todo_1`) while tooling stays strict.
+ */
+/** Body: 1–64 chars, ASCII letters, digits, hyphen, underscore; must not be empty after trim. */
+export declare const MARKER_ID_BODY = "[a-z0-9][a-z0-9_-]{0,63}";
+/**
+ * Validates and returns the normalised (lower-case) marker id, or throws with a
+ * message suitable for CLI / editor output.
+ */
+export declare function assertValidMarkerId(raw: string): string;
+/**
+ * Turns free-form author input into a valid marker id when possible: lower-case,
+ * spaces → hyphens, strips other punctuation. Throws if the result is empty or
+ * still invalid — callers may fall back to {@link generateBlockId} from `blocks.js`.
+ */
+export declare function normaliseMarkerSlugOrThrow(raw: string): string;
+//# sourceMappingURL=marker-ids.d.ts.map

package/dist/marker-ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker-ids.d.ts","sourceRoot":"","sources":["../src/marker-ids.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,iGAAiG;AACjG,eAAO,MAAM,cAAc,6BAA6B,CAAC;AAIzD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CASvD;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAW9D"}

package/dist/marker-ids.js

@@ -0,0 +1,38 @@
+/**
+ * Marker / block ids used in `marker:<id>` anchors, `markerId` in the index, and
+ * `commentray:<id>` / `commentray:start id=<id>` in source. Designed so authors
+ * can type **short slugs** (`intro`, `auth-flow`, `todo_1`) while tooling stays strict.
+ */
+/** Body: 1–64 chars, ASCII letters, digits, hyphen, underscore; must not be empty after trim. */
+export const MARKER_ID_BODY = "[a-z0-9][a-z0-9_-]{0,63}";
+const MARKER_ID_RE = new RegExp(`^${MARKER_ID_BODY}$`, "i");
+/**
+ * Validates and returns the normalised (lower-case) marker id, or throws with a
+ * message suitable for CLI / editor output.
+ */
+export function assertValidMarkerId(raw) {
+    const id = raw.trim().toLowerCase();
+    if (!MARKER_ID_RE.test(id)) {
+        throw new Error(`Invalid marker id "${raw}". Use 1–64 characters: a–z, 0–9, hyphen (-), underscore (_); ` +
+            `must start with a letter or digit. Examples: intro, auth-flow, block_01, a3f9k2`);
+    }
+    return id;
+}
+/**
+ * Turns free-form author input into a valid marker id when possible: lower-case,
+ * spaces → hyphens, strips other punctuation. Throws if the result is empty or
+ * still invalid — callers may fall back to {@link generateBlockId} from `blocks.js`.
+ */
+export function normaliseMarkerSlugOrThrow(raw) {
+    const slug = raw
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, "-")
+        .replace(/[^a-z0-9_-]+/g, "")
+        .replace(/-+/g, "-")
+        .replace(/_+/g, "_")
+        .replace(/^-+|-+$/g, "")
+        .replace(/^_|_$/g, "");
+    return assertValidMarkerId(slug);
+}
+//# sourceMappingURL=marker-ids.js.map

package/dist/marker-ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker-ids.js","sourceRoot":"","sources":["../src/marker-ids.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,iGAAiG;AACjG,MAAM,CAAC,MAAM,cAAc,GAAG,0BAA0B,CAAC;AAEzD,MAAM,YAAY,GAAG,IAAI,MAAM,CAAC,IAAI,cAAc,GAAG,EAAE,GAAG,CAAC,CAAC;AAE5D;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,MAAM,EAAE,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,sBAAsB,GAAG,gEAAgE;YACvF,iFAAiF,CACpF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAW;IACpD,MAAM,IAAI,GAAG,GAAG;SACb,IAAI,EAAE;SACN,WAAW,EAAE;SACb,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC;SAC5B,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACzB,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC"}

package/dist/marker-validation.d.ts

@@ -0,0 +1,22 @@
+import type { CommentrayIndex } from "./model.js";
+export type MarkerValidationIssue = {
+    level: "error" | "warn";
+    message: string;
+};
+/**
+ * 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 declare function validateMarkerBoundariesInSource(sourceText: string, sourcePath: string): MarkerValidationIssue[];
+/**
+ * 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 declare function validateIndexMarkerSemantics(index: CommentrayIndex): MarkerValidationIssue[];
+//# sourceMappingURL=marker-validation.d.ts.map

package/dist/marker-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker-validation.d.ts","sourceRoot":"","sources":["../src/marker-validation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlD,MAAM,MAAM,qBAAqB,GAAG;IAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjF;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAC9C,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,qBAAqB,EAAE,CAkDzB;AAmBD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,eAAe,GAAG,qBAAqB,EAAE,CAuD5F"}

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":"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"}
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAqB,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAwB,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpG,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,wBAAwB,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAClE,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;QAC3B,MAAM,IAAI,SAAS,CACjB,oDAAoD,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,GAAG,CACjF,CAAC;IACJ,CAAC;IACD,IAAI,aAAa,KAAK,sBAAsB,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CACb,sCAAsC,8BAA8B,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,CAC1F,CAAC;IACJ,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,EAAE,GAAG,GAAG,EAAE,aAAa,EAAE,sBAAsB,EAAqB,CAAC;AAC9E,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,sBAAsB,CAAC,iBAAyB,EAAE,GAAW;IACpE,IAAI,CAAC;QACH,OAAO,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,SAAS,CACjB,0BAA0B,iBAAiB,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAC5F,EAAE,KAAK,EAAE,CAAC,EAAE,CACb,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,oBAAoB,CAAC,iBAAyB,EAAE,GAAW;IAClE,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,SAAS,CACjB,8BAA8B,iBAAiB,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAChG,EAAE,KAAK,EAAE,CAAC,EAAE,CACb,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,kCAAkC,CACzC,iBAAyB,EACzB,CAA0B,EAC1B,GAAW,EACX,YAA0B;IAE1B,IAAI,YAAY,CAAC,IAAI,KAAK,QAAQ,IAAI,YAAY,CAAC,EAAE,KAAK,GAAG,EAAE,CAAC;QAC9D,MAAM,IAAI,SAAS,CACjB,gDAAgD,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,MAAM,WAAW,iBAAiB,EAAE,CACvG,CAAC;IACJ,CAAC;IACD,IACE,YAAY,CAAC,IAAI,KAAK,QAAQ;QAC9B,CAAC,CAAC,QAAQ,KAAK,SAAS;QACxB,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ;QAC9B,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE;QACxB,mBAAmB,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,YAAY,CAAC,EAAE,EACnD,CAAC;QACD,MAAM,IAAI,SAAS,CACjB,oDAAoD,iBAAiB,WAAW,CAAC,CAAC,EAAE,GAAG,CACxF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,2BAA2B,CAAC,iBAAyB,EAAE,CAA0B;IACxF,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,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC7D,MAAM,IAAI,SAAS,CAAC,qDAAqD,iBAAiB,EAAE,CAAC,CAAC;IAChG,CAAC;IACD,IAAI,CAAC,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CACjB,kDAAkD,iBAAiB,0CAA0C,CAC9G,CAAC;IACJ,CAAC;AACH,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,MAAM,GAAG,GAAG,sBAAsB,CAAC,iBAAiB,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IAC5D,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QACjC,MAAM,IAAI,SAAS,CAAC,uCAAuC,iBAAiB,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,MAAM,YAAY,GAAG,oBAAoB,CAAC,iBAAiB,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;IACvE,kCAAkC,CAAC,iBAAiB,EAAE,CAAC,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC;IAC5E,2BAA2B,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC;AACpD,CAAC"}

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":"AAAA,OAAO,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,EAGL,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,MAAM,qBAAqB,GAAG,CAAU,CAAC;AAEzC,uEAAuE;AACvE,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC5C,OAAO;YACL,KAAK,EAAE,EAAE,aAAa,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,EAAE,EAAE;YACtE,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,GAA8B,CAAC;IAC3C,MAAM,OAAO,GAAG,wBAAwB,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC5D,IAAI,OAAO,KAAK,IAAI,IAAI,GAAG,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QACxD,MAAM,IAAI,SAAS,CAAC,gCAAgC,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;IACnF,CAAC;IAED,IAAI,OAAO,KAAK,sBAAsB,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,GAAsB,CAAC;QACrC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACnC,CAAC;IAED,IACE,OAAO,KAAK,qBAAqB;QACjC,OAAO,KAAK,SAAS;QACrB,OAAO,KAAK,CAAC;QACb,OAAO,KAAK,CAAC,EACb,CAAC;QACD,MAAM,gBAAgB,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;QACjD,MAAM,IAAI,GAAoB;YAC5B,aAAa,EAAE,sBAAsB;YACrC,gBAAgB;SACjB,CAAC;QACF,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC;YAC5B,aAAa,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO;YAClD,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,EAAE;YACpC,gBAAgB,EAAE,GAAG,CAAC,gBAAgB,IAAI,EAAE;SAC7C,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,OAAO,GAAG,MAAM,KAAK,KAAK,CAAC;QACjC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAClC,CAAC;IAED,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,GAAG,sBAAsB,EAAE,CAAC;QACpE;;;;WAIG;QACH,MAAM,gBAAgB,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;QACjD,OAAO;YACL,KAAK,EAAE,EAAE,aAAa,EAAE,sBAAsB,EAAE,gBAAgB,EAAE;YAClE,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,KAAK,CACb,gDAAgD,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,KAAK,8BAA8B,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,CAClI,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB,CAAC,GAA4B;IACtD,IACE,GAAG,CAAC,gBAAgB;QACpB,OAAO,GAAG,CAAC,gBAAgB,KAAK,QAAQ;QACxC,GAAG,CAAC,gBAAgB,KAAK,IAAI,EAC7B,CAAC;QACD,MAAM,GAAG,GAAyC,EAAE,CAAC;QACrD,KAAK,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,gBAA2C,CAAC,EAAE,CAAC;YACzF,GAAG,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,MAAM,YAAY,GAAG,GAAG,CAAC,YAAY,CAAC;IACtC,MAAM,GAAG,GAAyC,EAAE,CAAC;IACrD,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;QAC9D,OAAO,GAAG,CAAC;IACb,CAAC;IACD,KAAK,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAuC,CAAC,EAAE,CAAC;QAChF,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;QACnC,MAAM,EAAE,GAAG,IAAI,CAAC,cAAc,CAAC;QAC/B,IAAI,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,6CAA6C,EAAE,EAAE,CAAC,CAAC;QACrE,CAAC;QACD,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACzC,CAAC;IACD,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,IAAI,OAAO,CAAC,CAAC,cAAc,KAAK,QAAQ,EAAE,CAAC;QACzC,OAAO,CAAyB,CAAC;IACnC,CAAC;IACD,IAAI,OAAO,CAAC,CAAC,cAAc,KAAK,QAAQ,EAAE,CAAC;QACzC,MAAM,EAAE,cAAc,EAAE,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC;QACtC,OAAO,EAAE,GAAG,IAAI,EAAE,cAAc,EAAE,cAAc,EAA0B,CAAC;IAC7E,CAAC;IACD,OAAO,CAAyB,CAAC;AACnC,CAAC"}