@commentray/core 0.0.2 → 0.0.5

package/dist/scroll-sync.js

@@ -1,5 +1,8 @@
 import { parseAnchor } from "./anchors.js";
-const BLOCK_MARKER_RE = /<!-- commentray:block id=([a-z0-9]+) -->/;
+import { MARKER_ID_BODY } from "./marker-ids.js";
+import { sourceLineRangeForMarkerId } from "./source-markers.js";
+export { pickCommentrayLineForSourceScroll, pickSourceLine0ForCommentrayScroll, } from "./block-scroll-pickers.js";
+const BLOCK_MARKER_RE = new RegExp(`<!-- commentray:block id=(${MARKER_ID_BODY}) -->`);
 function markerLineByIdFromMarkdown(markdown) {
     const map = new Map();
     const lines = markdown.split("\n");
@@ -11,11 +14,12 @@ function markerLineByIdFromMarkdown(markdown) {
     return map;
 }
 /**
- * Correlate index blocks (line anchors + ids) with `<!-- commentray:block id=… -->`
- * markers in commentray. Only `lines:` anchors with a visible
- * marker participate. Sorted by `sourceStart`.
+ * Correlate index blocks with `<!-- commentray:block id=… -->` markers in
+ * commentray. Supports legacy `lines:` anchors and `marker:` anchors (the
+ * latter needs `sourceText` to resolve marker comments in the primary file).
+ * Sorted by `sourceStart`.
  */
-export function buildBlockScrollLinks(index, sourceRelative, commentrayPath, commentrayMarkdown) {
+export function buildBlockScrollLinks(index, sourceRelative, commentrayPath, commentrayMarkdown, sourceText) {
     const entry = index?.byCommentrayPath[commentrayPath];
     if (!entry || entry.sourcePath !== sourceRelative || entry.blocks.length === 0)
         return [];
@@ -23,58 +27,33 @@ export function buildBlockScrollLinks(index, sourceRelative, commentrayPath, com
     const links = [];
     for (const block of entry.blocks) {
         const anchor = parseAnchor(block.anchor);
-        if (anchor.kind !== "lines")
-            continue;
         const commentrayLine = markerLineById.get(block.id);
         if (commentrayLine === undefined)
             continue;
-        links.push({
-            commentrayLine,
-            sourceStart: anchor.range.start,
-            sourceEnd: anchor.range.end,
-        });
+        if (anchor.kind === "lines") {
+            links.push({
+                id: block.id,
+                commentrayLine,
+                sourceStart: anchor.range.start,
+                sourceEnd: anchor.range.end,
+            });
+            continue;
+        }
+        if (anchor.kind === "marker") {
+            if (sourceText === undefined)
+                continue;
+            const range = sourceLineRangeForMarkerId(sourceText, anchor.id);
+            if (range === null)
+                continue;
+            links.push({
+                id: block.id,
+                commentrayLine,
+                sourceStart: range.start,
+                sourceEnd: range.end,
+            });
+        }
     }
     links.sort((a, b) => a.sourceStart - b.sourceStart);
     return links;
 }
-/**
- * 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=scroll-sync.js.map

package/dist/scroll-sync.js.map

@@ -1 +1 @@
-{"version":3,"file":"scroll-sync.js","sourceRoot":"","sources":["../src/scroll-sync.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scroll-sync.js","sourceRoot":"","sources":["../src/scroll-sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAGjE,OAAO,EACL,iCAAiC,EACjC,kCAAkC,GACnC,MAAM,2BAA2B,CAAC;AAEnC,MAAM,eAAe,GAAG,IAAI,MAAM,CAAC,6BAA6B,cAAc,OAAO,CAAC,CAAC;AAEvF,SAAS,0BAA0B,CAAC,QAAgB;IAClD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7C,IAAI,KAAK;YAAE,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAyC,EACzC,cAAsB,EACtB,cAAsB,EACtB,kBAA0B,EAC1B,UAAmB;IAEnB,MAAM,KAAK,GAAG,KAAK,EAAE,gBAAgB,CAAC,cAAc,CAAC,CAAC;IACtD,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,UAAU,KAAK,cAAc,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC1F,MAAM,cAAc,GAAG,0BAA0B,CAAC,kBAAkB,CAAC,CAAC;IACtE,MAAM,KAAK,GAAsB,EAAE,CAAC;IACpC,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACzC,MAAM,cAAc,GAAG,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACpD,IAAI,cAAc,KAAK,SAAS;YAAE,SAAS;QAC3C,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC5B,KAAK,CAAC,IAAI,CAAC;gBACT,EAAE,EAAE,KAAK,CAAC,EAAE;gBACZ,cAAc;gBACd,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK;gBAC/B,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG;aAC5B,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,IAAI,UAAU,KAAK,SAAS;gBAAE,SAAS;YACvC,MAAM,KAAK,GAAG,0BAA0B,CAAC,UAAU,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;YAChE,IAAI,KAAK,KAAK,IAAI;gBAAE,SAAS;YAC7B,KAAK,CAAC,IAAI,CAAC;gBACT,EAAE,EAAE,KAAK,CAAC,EAAE;gBACZ,cAAc;gBACd,WAAW,EAAE,KAAK,CAAC,KAAK;gBACxB,SAAS,EAAE,KAAK,CAAC,GAAG;aACrB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;IACpD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/source-markers.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Line comment leader for **generic** `commentray:start` / `end` markers
+ * (`// …`, `# …`, etc.). Not used for `#region` family languages.
+ */
+export declare function lineCommentLeaderForLanguage(languageId: string): string;
+/**
+ * Insertion fragments for wrapping the selection (apply **end** first, then
+ * **start**, so stable offsets). Pass the same indentation string Region Marker
+ * uses (leading whitespace of the first selected line).
+ */
+export declare function commentrayRegionInsertions(languageId: string, markerId: string, indent?: string): {
+    start: string;
+    end: string;
+};
+export type RegionBoundaryKind = "start" | "end";
+/** Detect a Commentray region, generic marker, or legacy marker line; id is lower-case. */
+export declare function parseCommentrayRegionBoundary(line: string): {
+    kind: RegionBoundaryKind;
+    id: string;
+} | null;
+/**
+ * 1-based inclusive source lines **between** paired region / generic / legacy marker lines.
+ */
+export declare function sourceLineRangeForMarkerId(sourceText: string, markerId: string): {
+    start: number;
+    end: number;
+} | null;
+//# sourceMappingURL=source-markers.d.ts.map

package/dist/source-markers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-markers.d.ts","sourceRoot":"","sources":["../src/source-markers.ts"],"names":[],"mappings":"AAyGA;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAMvE;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,SAAK,GACV;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAuDhC;AAED,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,KAAK,CAAC;AAEjD,2FAA2F;AAC3F,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,GACX;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA8CjD;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf;IACD,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb,GAAG,IAAI,CAgBP"}

package/dist/source-markers.js

@@ -0,0 +1,241 @@
+import { assertValidMarkerId, MARKER_ID_BODY } from "./marker-ids.js";
+/**
+ * Source delimiters for block anchors:
+ *
+ * 1. **Region convention** — where editors commonly fold `//#region` /
+ *    `//#endregion`, `#region` / `#endregion`, `#pragma region`, etc. (aligned
+ *    with [Region Marker](https://marketplace.visualstudio.com/items?itemName=txava.region-marker)),
+ *    Commentray uses the region **name** `commentray:<id>`.
+ *
+ * 2. **Generic comments** — for languages without a shared region idiom, we
+ *    use ordinary line or block comments and our own `commentray:start id=<id>` /
+ *    `commentray:end id=<id>` tokens (still parsed by {@link parseCommentrayRegionBoundary}).
+ *
+ * Legacy pairs that only use (2) remain valid everywhere.
+ */
+const COMMENTRAY_TAG = (id) => `commentray:${id.trim().toLowerCase()}`;
+/** `//#region commentray:<id>` — JS/TS ecosystem & CSS preprocessors that use `//`. */
+const SLASH_REGION_LANGUAGES = new Set([
+    "javascript",
+    "javascriptreact",
+    "typescript",
+    "typescriptreact",
+    "js",
+    "jsx",
+    "tsx",
+    "mjs",
+    "cjs",
+    "vue",
+    "svelte",
+    "astro",
+    "scss",
+    "less",
+    "stylus",
+]);
+/** `#region commentray:<id>` — same shape as Region Marker for these ids. */
+const HASH_REGION_LANGUAGES = new Set([
+    "ruby",
+    "csharp",
+    "coffeescript",
+    "powershell",
+    "perl",
+    "raku",
+    "crystal",
+]);
+const PRAGMA_REGION = new Set(["c", "cpp", "cuda-cpp", "objective-c", "objective-cpp"]);
+const VB_REGION = new Set(["vb"]);
+const LUA_REGION = new Set(["lua"]);
+const HTML_FAMILY = new Set(["html", "xml", "handlebars", "vue-html"]);
+const PYTHONIC = new Set(["python", "jupyter"]);
+/** `# …` line comments for generic markers (no `#region` folding convention). */
+const GENERIC_HASH_LANGUAGES = new Set([
+    "dockerfile",
+    "makefile",
+    "cmake",
+    "yaml",
+    "yml",
+    "toml",
+    "ini",
+    "properties",
+    "git-commit",
+    "sql",
+    "r",
+    "shellscript",
+    "bash",
+    "sh",
+    "zsh",
+    "fish",
+]);
+function regionConvention(languageId) {
+    const id = languageId.toLowerCase();
+    if (id === "css")
+        return "generic-block-css";
+    if (PYTHONIC.has(id))
+        return "python";
+    if (PRAGMA_REGION.has(id))
+        return "pragma";
+    if (VB_REGION.has(id))
+        return "vb";
+    if (HTML_FAMILY.has(id))
+        return "html";
+    if (LUA_REGION.has(id))
+        return "lua";
+    if (HASH_REGION_LANGUAGES.has(id))
+        return "hash-region";
+    if (SLASH_REGION_LANGUAGES.has(id))
+        return "slash-region";
+    if (GENERIC_HASH_LANGUAGES.has(id))
+        return "generic-hash";
+    return "generic-line";
+}
+/**
+ * Line comment leader for **generic** `commentray:start` / `end` markers
+ * (`// …`, `# …`, etc.). Not used for `#region` family languages.
+ */
+export function lineCommentLeaderForLanguage(languageId) {
+    const id = languageId.toLowerCase();
+    if (GENERIC_HASH_LANGUAGES.has(id))
+        return "# ";
+    if (id === "lua")
+        return "-- ";
+    if (id === "vb")
+        return "' ";
+    return "// ";
+}
+/**
+ * Insertion fragments for wrapping the selection (apply **end** first, then
+ * **start**, so stable offsets). Pass the same indentation string Region Marker
+ * uses (leading whitespace of the first selected line).
+ */
+export function commentrayRegionInsertions(languageId, markerId, indent = "") {
+    const id = assertValidMarkerId(markerId);
+    const tag = COMMENTRAY_TAG(id);
+    const ind = indent;
+    const conv = regionConvention(languageId);
+    switch (conv) {
+        case "slash-region":
+            return {
+                start: `${ind}//#region ${tag}\n`,
+                end: `\n${ind}//#endregion ${tag}`,
+            };
+        case "hash-region":
+            return {
+                start: `${ind}#region ${tag}\n`,
+                end: `\n${ind}#endregion ${tag}`,
+            };
+        case "pragma":
+            return {
+                start: `${ind}#pragma region ${tag}\n`,
+                end: `\n${ind}#pragma endregion ${tag}`,
+            };
+        case "vb":
+            return {
+                start: `${ind}#Region ${tag}\n`,
+                end: `\n${ind}#End Region ${tag}`,
+            };
+        case "html":
+            return {
+                start: `${ind}<!-- #region ${tag} -->\n`,
+                end: `\n${ind}<!-- #endregion ${tag} -->`,
+            };
+        case "python":
+            return {
+                start: `${ind}# region ${tag}\n`,
+                end: `\n${ind}# endregion ${tag}`,
+            };
+        case "lua":
+            return {
+                start: `${ind}--#region ${tag}\n`,
+                end: `\n${ind}--#endregion ${tag}`,
+            };
+        case "generic-block-css":
+            return {
+                start: `${ind}/* commentray:start id=${id} */\n`,
+                end: `\n${ind}/* commentray:end id=${id} */`,
+            };
+        case "generic-hash":
+        case "generic-line": {
+            const leader = lineCommentLeaderForLanguage(languageId);
+            return {
+                start: `${ind}${leader}commentray:start id=${id}\n`,
+                end: `\n${ind}${leader}commentray:end id=${id}`,
+            };
+        }
+    }
+}
+/** Detect a Commentray region, generic marker, or legacy marker line; id is lower-case. */
+export function parseCommentrayRegionBoundary(line) {
+    const probe = line.trim();
+    const mid = MARKER_ID_BODY;
+    const startPatterns = [
+        new RegExp(`^//#region\\s+commentray:(${mid})\\s*$`, "i"),
+        new RegExp(`^#region\\s+commentray:(${mid})\\s*$`, "i"),
+        new RegExp(`^#pragma\\s+region\\s+commentray:(${mid})\\s*$`, "i"),
+        new RegExp(`^#Region\\s+commentray:(${mid})\\s*$`, "i"),
+        new RegExp(`^#\\s*region\\s+commentray:(${mid})\\s*$`, "i"),
+        new RegExp(`^<!--\\s*#region\\s+commentray:(${mid})\\s*-->\\s*$`, "i"),
+        new RegExp(`^--#region\\s+commentray:(${mid})\\s*$`, "i"),
+        new RegExp(`^/\\*\\s*commentray:start\\s+id=(${mid})\\s*\\*/\\s*$`, "i"),
+        new RegExp(`commentray:start\\s+id=(${mid})\\b`, "i"),
+    ];
+    const endPatterns = [
+        new RegExp(`^//#endregion\\s+commentray:(${mid})\\s*$`, "i"),
+        new RegExp(`^#endregion\\s+commentray:(${mid})\\s*$`, "i"),
+        new RegExp(`^#pragma\\s+endregion\\s+commentray:(${mid})\\s*$`, "i"),
+        new RegExp(`^#End\\s+Region\\s+commentray:(${mid})\\s*$`, "i"),
+        new RegExp(`^#\\s*endregion\\s+commentray:(${mid})\\s*$`, "i"),
+        new RegExp(`^<!--\\s*#endregion\\s+commentray:(${mid})\\s*-->\\s*$`, "i"),
+        new RegExp(`^--#endregion\\s+commentray:(${mid})\\s*$`, "i"),
+        new RegExp(`^/\\*\\s*commentray:end\\s+id=(${mid})\\s*\\*/\\s*$`, "i"),
+        new RegExp(`commentray:end\\s+id=(${mid})\\b`, "i"),
+    ];
+    for (const re of startPatterns) {
+        const m = re.exec(probe);
+        if (m) {
+            try {
+                return { kind: "start", id: assertValidMarkerId(m[1]) };
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    for (const re of endPatterns) {
+        const m = re.exec(probe);
+        if (m) {
+            try {
+                return { kind: "end", id: assertValidMarkerId(m[1]) };
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * 1-based inclusive source lines **between** paired region / generic / legacy marker lines.
+ */
+export function sourceLineRangeForMarkerId(sourceText, markerId) {
+    const id = assertValidMarkerId(markerId);
+    const lines = sourceText.split("\n");
+    let startIdx = -1;
+    let endIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const hit = parseCommentrayRegionBoundary(lines[i]);
+        if (hit?.id !== id)
+            continue;
+        if (hit.kind === "start" && startIdx < 0)
+            startIdx = i;
+        else if (hit.kind === "end" && startIdx >= 0 && endIdx < 0)
+            endIdx = i;
+    }
+    if (startIdx < 0 || endIdx < 0 || endIdx < startIdx + 2)
+        return null;
+    const start = startIdx + 2;
+    const end = endIdx;
+    if (end < start)
+        return null;
+    return { start, end };
+}
+//# sourceMappingURL=source-markers.js.map

package/dist/source-markers.js.map

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

package/dist/validate-project.d.ts

@@ -1,4 +1,4 @@
-import type { CommentrayIndex } from "./model.js";
+import { type CommentrayIndex } from "./model.js";
 export type ValidationIssue = {
     level: "error" | "warn";
     message: string;
@@ -7,6 +7,14 @@ export type ValidationResult = {
     issues: ValidationIssue[];
 };
 export declare function validateProject(repoRoot: string): Promise<ValidationResult>;
+/**
+ * Reads `index.json`, applies schema migration and snippet/fingerprint normalization,
+ * and persists when anything changed. Throws if the file is missing or not valid JSON.
+ */
+export declare function refreshIndexMigrationsOnDisk(repoRoot: string): Promise<{
+    index: CommentrayIndex;
+    changed: boolean;
+}>;
 export declare function readIndex(repoRoot: string): Promise<CommentrayIndex | null>;
 /**
  * Write the metadata index to the default location under `repoRoot`, creating

package/dist/validate-project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-project.d.ts","sourceRoot":"","sources":["../src/validate-project.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,MAAM,eAAe,GAAG;IAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B,CAAC;AAEF,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAyCjF;AAiBD,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAmBjF;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF"}
+{"version":3,"file":"validate-project.d.ts","sourceRoot":"","sources":["../src/validate-project.ts"],"names":[],"mappings":"AAOA,OAAO,EAAoD,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAUpG,MAAM,MAAM,eAAe,GAAG;IAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B,CAAC;AA+EF,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA8CjF;AAiBD;;;GAGG;AACH,wBAAsB,4BAA4B,CAChD,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAqBvD;AAED,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CASjF;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF"}

package/dist/validate-project.js

@@ -2,9 +2,82 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { loadCommentrayConfig } from "./config.js";
 import { parseGithubRepoWebUrl } from "./github-url.js";
+import { normalizeCommentrayIndex } from "./index-normalize.js";
 import { assertValidIndex } from "./metadata.js";
 import { migrateIndex } from "./migrate.js";
-import { defaultMetadataIndexPath } from "./paths.js";
+import { coerceIndexSchemaVersion, CURRENT_SCHEMA_VERSION } from "./model.js";
+import { defaultMetadataIndexPath, normalizeRepoRelativePath } from "./paths.js";
+import { validateIndexMarkerSemantics, validateMarkerBoundariesInSource, } from "./marker-validation.js";
+import { loadGitTrackedSourceTextsOutsideIndex } from "./git-relocation-scan.js";
+import { relocationHintMessages } from "./relocation-hints.js";
+import { GitScmProvider } from "./scm/git-scm-provider.js";
+async function collectIssuesForLoadedIndex(repoRoot, index) {
+    const issues = [];
+    for (const issue of validateIndexMarkerSemantics(index)) {
+        issues.push({ level: issue.level, message: issue.message });
+    }
+    const uniqueSourcesNorm = [
+        ...new Set(Object.values(index.byCommentrayPath).map((e) => normalizeRepoRelativePath(e.sourcePath))),
+    ];
+    const indexedSourceTexts = new Map();
+    const missingSourcesNorm = new Set();
+    for (const norm of uniqueSourcesNorm) {
+        const abs = path.join(repoRoot, ...norm.split("/"));
+        try {
+            const text = await fs.readFile(abs, "utf8");
+            indexedSourceTexts.set(norm, text);
+        }
+        catch {
+            missingSourcesNorm.add(norm);
+            const affected = Object.values(index.byCommentrayPath)
+                .filter((e) => normalizeRepoRelativePath(e.sourcePath) === norm)
+                .map((e) => e.commentrayPath);
+            const uniqAffected = [...new Set(affected)].sort((a, b) => a.localeCompare(b));
+            issues.push({
+                level: "warn",
+                message: `Primary source "${norm}" is not readable (deleted, moved, or not checked out). ` +
+                    `Commentray: ${uniqAffected.join(", ")}. ` +
+                    `If Git renamed it, try: commentray sync-moved-paths --from HEAD~1 --to HEAD`,
+            });
+        }
+    }
+    for (const [norm, text] of indexedSourceTexts) {
+        for (const issue of validateMarkerBoundariesInSource(text, norm)) {
+            issues.push({ level: issue.level, message: issue.message });
+        }
+    }
+    if (missingSourcesNorm.size === 0)
+        return issues;
+    let gitRenames;
+    try {
+        const scm = new GitScmProvider();
+        if (scm.listPathRenamesBetweenTreeishes) {
+            gitRenames = await scm.listPathRenamesBetweenTreeishes(repoRoot, "HEAD~1", "HEAD");
+        }
+    }
+    catch {
+        /* no Git or shallow history — hints still run without renames */
+    }
+    let textsForRelocationHints = indexedSourceTexts;
+    try {
+        const extra = await loadGitTrackedSourceTextsOutsideIndex(repoRoot, new Set(indexedSourceTexts.keys()));
+        if (extra.size > 0) {
+            textsForRelocationHints = new Map([...extra, ...indexedSourceTexts]);
+        }
+    }
+    catch {
+        /* not a git checkout or ls-files failed — use indexed primaries only */
+    }
+    for (const hint of relocationHintMessages({
+        index,
+        missingSourcePathsNorm: missingSourcesNorm,
+        gitRenames,
+        indexedSourceTextsByPath: textsForRelocationHints,
+    })) {
+        issues.push({ level: "warn", message: hint });
+    }
+    return issues;
+}
 export async function validateProject(repoRoot) {
     const issues = [];
     let config;
@@ -31,9 +104,10 @@ export async function validateProject(repoRoot) {
             });
         }
     }
+    let index = null;
     try {
-        const idx = await readIndex(repoRoot);
-        if (idx === null) {
+        index = await readIndex(repoRoot);
+        if (index === null) {
             issues.push({ level: "warn", message: `No metadata index at ${defaultMetadataIndexPath()}` });
         }
     }
@@ -43,6 +117,9 @@ export async function validateProject(repoRoot) {
             message: `Invalid metadata index: ${err instanceof Error ? err.message : String(err)}`,
         });
     }
+    if (index) {
+        issues.push(...(await collectIssuesForLoadedIndex(repoRoot, index)));
+    }
     pushRelativeGithubLinkConfigWarnings(config, issues);
     return { issues };
 }
@@ -58,21 +135,35 @@ function pushRelativeGithubLinkConfigWarnings(config, issues) {
             "not a repository home URL (expected https://github.com/owner/repo). Link rewriting is skipped at build time.",
     });
 }
-export async function readIndex(repoRoot) {
+/**
+ * Reads `index.json`, applies schema migration and snippet/fingerprint normalization,
+ * and persists when anything changed. Throws if the file is missing or not valid JSON.
+ */
+export async function refreshIndexMigrationsOnDisk(repoRoot) {
     const indexPath = path.join(repoRoot, defaultMetadataIndexPath());
+    const raw = await fs.readFile(indexPath, "utf8");
+    const parsed = JSON.parse(raw);
+    const priorSchema = typeof parsed === "object" && parsed !== null
+        ? coerceIndexSchemaVersion(parsed.schemaVersion)
+        : null;
+    if (typeof priorSchema === "number" && priorSchema > CURRENT_SCHEMA_VERSION) {
+        const metaDir = path.dirname(indexPath);
+        const backupName = `index.schema-${String(priorSchema)}-backup-${String(Date.now())}.json`;
+        await fs.writeFile(path.join(metaDir, backupName), raw, "utf8");
+    }
+    const { index: migrated, changed: schemaChanged } = migrateIndex(parsed);
+    const { index: normalized, changed: snippetChanged } = normalizeCommentrayIndex(migrated);
+    const index = assertValidIndex(normalized);
+    const changed = schemaChanged || snippetChanged;
+    if (changed) {
+        await writeIndex(repoRoot, index);
+    }
+    return { index, changed };
+}
+export async function readIndex(repoRoot) {
     try {
-        const raw = await fs.readFile(indexPath, "utf8");
-        const parsed = JSON.parse(raw);
-        try {
-            return assertValidIndex(parsed);
-        }
-        catch {
-            const { index, changed } = migrateIndex(parsed);
-            if (changed) {
-                await writeIndex(repoRoot, index);
-            }
-            return assertValidIndex(index);
-        }
+        const { index } = await refreshIndexMigrationsOnDisk(repoRoot);
+        return index;
     }
     catch (err) {
         const code = err.code;

package/dist/validate-project.js.map

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

package/dist/walk-commentray-source-md.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Lists every `*.md` path relative to `sourceAbs`, POSIX separators, skipping `.default`.
+ */
+export declare function collectMdRelPathsUnderSourceAbs(sourceAbs: string): Promise<string[]>;
+//# sourceMappingURL=walk-commentray-source-md.d.ts.map

package/dist/walk-commentray-source-md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk-commentray-source-md.d.ts","sourceRoot":"","sources":["../src/walk-commentray-source-md.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,wBAAsB,+BAA+B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAuB1F"}