@commentray/core 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export type { CommentrayBlock, CommentrayIndex, SourceFileIndexEntry } from "./model.js";
+export { CURRENT_SCHEMA_VERSION } from "./model.js";
+export { commentrayMarkdownPath, defaultMetadataIndexPath, normalizeRepoRelativePath, } from "./paths.js";
+export type { CommentrayToml, ResolvedCommentrayConfig, ResolvedStaticSite } from "./config.js";
+export { loadCommentrayConfig, mergeCommentrayConfig } from "./config.js";
+export { assertValidIndex, emptyIndex } from "./metadata.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 { BlockDiagnostic } from "./staleness.js";
+export { diagnoseBlock } from "./staleness.js";
+export type { ValidationIssue, ValidationResult } from "./validate-project.js";
+export { readIndex, validateProject } from "./validate-project.js";
+export { runCommanderMain } from "./cli-bootstrap.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,cAAc,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAChG,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC1E,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,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+export { CURRENT_SCHEMA_VERSION } from "./model.js";
+export { commentrayMarkdownPath, defaultMetadataIndexPath, normalizeRepoRelativePath, } from "./paths.js";
+export { loadCommentrayConfig, mergeCommentrayConfig } from "./config.js";
+export { assertValidIndex, emptyIndex } from "./metadata.js";
+export { migrateIndex } from "./migrate.js";
+export { formatLineRange, parseAnchor } from "./anchors.js";
+export { GitScmProvider } from "./scm/git-scm-provider.js";
+export { diagnoseBlock } from "./staleness.js";
+export { readIndex, validateProject } from "./validate-project.js";
+export { runCommanderMain } from "./cli-bootstrap.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC1E,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,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/metadata.d.ts

@@ -0,0 +1,4 @@
+import { type CommentrayIndex } from "./model.js";
+export declare function emptyIndex(): CommentrayIndex;
+export declare function assertValidIndex(value: unknown): CommentrayIndex;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -0,0 +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"}

package/dist/metadata.js

@@ -0,0 +1,55 @@
+import { CURRENT_SCHEMA_VERSION } from "./model.js";
+export function emptyIndex() {
+    return { schemaVersion: CURRENT_SCHEMA_VERSION, bySourceFile: {} };
+}
+export function assertValidIndex(value) {
+    if (typeof value !== "object" || value === null) {
+        throw new Error("index.json must be a JSON object");
+    }
+    const obj = value;
+    const schemaVersion = obj.schemaVersion;
+    if (schemaVersion !== CURRENT_SCHEMA_VERSION) {
+        throw new Error(`Unsupported schemaVersion: ${String(schemaVersion)}`);
+    }
+    const bySourceFile = obj.bySourceFile;
+    if (typeof bySourceFile !== "object" || bySourceFile === null) {
+        throw new Error("index.json.bySourceFile must be an object");
+    }
+    for (const [key, entry] of Object.entries(bySourceFile)) {
+        validateSourceEntry(key, entry);
+    }
+    return obj;
+}
+function validateSourceEntry(sourcePath, entry) {
+    if (typeof entry !== "object" || entry === null) {
+        throw new Error(`Invalid index entry for ${sourcePath}`);
+    }
+    const e = entry;
+    if (typeof e.sourcePath !== "string")
+        throw new Error(`Missing sourcePath for ${sourcePath}`);
+    if (typeof e.commentrayPath !== "string") {
+        throw new Error(`Missing commentrayPath for ${sourcePath}`);
+    }
+    if (!Array.isArray(e.blocks))
+        throw new Error(`blocks must be an array for ${sourcePath}`);
+    for (const block of e.blocks)
+        validateBlock(sourcePath, block);
+}
+function validateBlock(sourcePath, block) {
+    if (typeof block !== "object" || block === null) {
+        throw new Error(`Invalid block under ${sourcePath}`);
+    }
+    const b = block;
+    if (typeof b.id !== "string")
+        throw new Error(`block.id must be a string under ${sourcePath}`);
+    if (typeof b.anchor !== "string") {
+        throw new Error(`block.anchor must be a string under ${sourcePath}`);
+    }
+    if (b.lastVerifiedCommit !== undefined && typeof b.lastVerifiedCommit !== "string") {
+        throw new Error(`block.lastVerifiedCommit must be a string when present under ${sourcePath}`);
+    }
+    if (b.lastVerifiedBlob !== undefined && typeof b.lastVerifiedBlob !== "string") {
+        throw new Error(`block.lastVerifiedBlob must be a string when present under ${sourcePath}`);
+    }
+}
+//# sourceMappingURL=metadata.js.map

package/dist/metadata.js.map

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

package/dist/migrate.d.ts

@@ -0,0 +1,7 @@
+import { type CommentrayIndex } from "./model.js";
+/** Returns migrated index and whether the file should be rewritten. */
+export declare function migrateIndex(raw: unknown): {
+    index: CommentrayIndex;
+    changed: boolean;
+};
+//# sourceMappingURL=migrate.d.ts.map

package/dist/migrate.d.ts.map

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

package/dist/migrate.js

@@ -0,0 +1,54 @@
+import { CURRENT_SCHEMA_VERSION, } from "./model.js";
+/** Returns migrated index and whether the file should be rewritten. */
+export function migrateIndex(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        return {
+            index: { schemaVersion: CURRENT_SCHEMA_VERSION, bySourceFile: {} },
+            changed: true,
+        };
+    }
+    const obj = raw;
+    const version = obj.schemaVersion;
+    if (version === CURRENT_SCHEMA_VERSION) {
+        return { index: obj, changed: false };
+    }
+    if (version === undefined || version === 0 || version === 1) {
+        const bySourceFile = normalizeBySourceFile(obj.bySourceFile);
+        const next = {
+            schemaVersion: CURRENT_SCHEMA_VERSION,
+            bySourceFile,
+        };
+        const before = JSON.stringify({
+            schemaVersion: version ?? 0,
+            bySourceFile: obj.bySourceFile ?? {},
+        });
+        const after = JSON.stringify(next);
+        const changed = before !== after;
+        return { index: next, changed };
+    }
+    throw new Error(`Cannot migrate from schemaVersion ${String(version)}`);
+}
+function normalizeBySourceFile(by) {
+    if (typeof by !== "object" || by === null)
+        return {};
+    const out = {};
+    for (const [k, entry] of Object.entries(by)) {
+        out[k] = normalizeEntry(entry);
+    }
+    return out;
+}
+function normalizeEntry(entry) {
+    if (typeof entry !== "object" || entry === null) {
+        throw new Error("Invalid index entry");
+    }
+    const e = entry;
+    if (typeof e.commentrayPath === "string") {
+        return e;
+    }
+    if (typeof e.commentaryPath === "string") {
+        const { commentaryPath, ...rest } = e;
+        return { ...rest, commentrayPath: commentaryPath };
+    }
+    return e;
+}
+//# sourceMappingURL=migrate.js.map

package/dist/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,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,YAAY,EAAE,EAAE,EAAE;YAClE,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,GAA8B,CAAC;IAC3C,MAAM,OAAO,GAAG,GAAG,CAAC,aAAa,CAAC;IAClC,IAAI,OAAO,KAAK,sBAAsB,EAAE,CAAC;QACvC,OAAO,EAAE,KAAK,EAAE,GAAsB,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC3D,CAAC;IACD,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,EAAE,CAAC;QAC5D,MAAM,YAAY,GAAG,qBAAqB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QAC7D,MAAM,IAAI,GAAoB;YAC5B,aAAa,EAAE,sBAAsB;YACrC,YAAY;SACb,CAAC;QACF,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC;YAC5B,aAAa,EAAE,OAAO,IAAI,CAAC;YAC3B,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,EAAE;SACrC,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;IACD,MAAM,IAAI,KAAK,CAAC,qCAAqC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;AAC1E,CAAC;AAED,SAAS,qBAAqB,CAAC,EAAW;IACxC,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IACrD,MAAM,GAAG,GAAyC,EAAE,CAAC;IACrD,KAAK,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,EAA6B,CAAC,EAAE,CAAC;QACvE,GAAG,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACjC,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"}

package/dist/model.d.ts

@@ -0,0 +1,27 @@
+/** Commentray block aligned to a region of a primary source file. */
+export type CommentrayBlock = {
+    /** Stable id within the commentray markdown file. */
+    id: string;
+    /** Human or machine anchor string (see anchor grammar in docs). */
+    anchor: string;
+    /** Last human-verified commit (full SHA) when this block was considered accurate. */
+    lastVerifiedCommit?: string;
+    /** Git blob id at verification time for the primary file (when known). */
+    lastVerifiedBlob?: string;
+    /** Optional notes for agents or reviewers. */
+    notes?: string;
+};
+export type SourceFileIndexEntry = {
+    /** Repo-relative path to the primary file this commentray belongs to. */
+    sourcePath: string;
+    /** Repo-relative path to the Markdown commentray file. */
+    commentrayPath: string;
+    blocks: CommentrayBlock[];
+};
+/** Root metadata document stored as JSON under `.commentray/metadata/`. */
+export type CommentrayIndex = {
+    schemaVersion: number;
+    bySourceFile: Record<string, SourceFileIndexEntry>;
+};
+export declare const CURRENT_SCHEMA_VERSION: 2;
+//# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

@@ -0,0 +1 @@
+{"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,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,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CACpD,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAG,CAAU,CAAC"}

package/dist/model.js

@@ -0,0 +1,2 @@
+export const CURRENT_SCHEMA_VERSION = 2;
+//# sourceMappingURL=model.js.map

package/dist/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AA4BA,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAU,CAAC"}

package/dist/paths.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Normalize a repo-relative path to POSIX separators and reject anything that
+ * would escape the repository root when joined with it.
+ *
+ * Rejects:
+ *   - Windows drive letters (e.g. `C:\foo`).
+ *   - `..` path segments, which would let a config value or CLI argument walk
+ *     out of the repo root.
+ *
+ * Accepts filenames that merely *contain* dots like `..name.ts`; only whole
+ * `..` segments are traversal.
+ */
+export declare function normalizeRepoRelativePath(relativePath: string): string;
+/** Commentray Markdown path for a repo-relative source file. */
+export declare function commentrayMarkdownPath(sourceRepoRelativePath: string): string;
+/** Default metadata index location (repo-relative). */
+export declare function defaultMetadataIndexPath(): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAWtE;AAED,gEAAgE;AAChE,wBAAgB,sBAAsB,CAAC,sBAAsB,EAAE,MAAM,GAAG,MAAM,CAG7E;AAED,uDAAuD;AACvD,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD"}

package/dist/paths.js

@@ -0,0 +1,35 @@
+import path from "node:path";
+/**
+ * Normalize a repo-relative path to POSIX separators and reject anything that
+ * would escape the repository root when joined with it.
+ *
+ * Rejects:
+ *   - Windows drive letters (e.g. `C:\foo`).
+ *   - `..` path segments, which would let a config value or CLI argument walk
+ *     out of the repo root.
+ *
+ * Accepts filenames that merely *contain* dots like `..name.ts`; only whole
+ * `..` segments are traversal.
+ */
+export function normalizeRepoRelativePath(relativePath) {
+    const posix = relativePath.replaceAll("\\", "/");
+    if (/^[a-zA-Z]:\//.test(posix)) {
+        throw new Error(`Path must be repository-relative (got absolute: ${relativePath})`);
+    }
+    const stripped = posix.replace(/^\/+/, "");
+    const segments = stripped.split("/").filter((s) => s !== "" && s !== ".");
+    if (segments.some((s) => s === "..")) {
+        throw new Error(`Path escapes repository root: ${relativePath}`);
+    }
+    return segments.join("/");
+}
+/** Commentray Markdown path for a repo-relative source file. */
+export function commentrayMarkdownPath(sourceRepoRelativePath) {
+    const normalized = normalizeRepoRelativePath(sourceRepoRelativePath);
+    return path.posix.join(".commentray", "source", `${normalized}.md`);
+}
+/** Default metadata index location (repo-relative). */
+export function defaultMetadataIndexPath() {
+    return path.posix.join(".commentray", "metadata", "index.json");
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,yBAAyB,CAAC,YAAoB;IAC5D,MAAM,KAAK,GAAG,YAAY,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACjD,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,mDAAmD,YAAY,GAAG,CAAC,CAAC;IACtF,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;IAC1E,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,iCAAiC,YAAY,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,sBAAsB,CAAC,sBAA8B;IACnE,MAAM,UAAU,GAAG,yBAAyB,CAAC,sBAAsB,CAAC,CAAC;IACrE,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,EAAE,QAAQ,EAAE,GAAG,UAAU,KAAK,CAAC,CAAC;AACtE,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,wBAAwB;IACtC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC;AAClE,CAAC"}

package/dist/scm/git-scm-provider.d.ts

@@ -0,0 +1,6 @@
+import type { ScmProvider } from "./scm-provider.js";
+export declare class GitScmProvider implements ScmProvider {
+    getBlobIdAtHead(repoRoot: string, repoRelativePath: string): Promise<string | null>;
+    isAncestor(repoRoot: string, possibleAncestor: string, commit: string): Promise<boolean>;
+}
+//# sourceMappingURL=git-scm-provider.d.ts.map

package/dist/scm/git-scm-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-scm-provider.d.ts","sourceRoot":"","sources":["../../src/scm/git-scm-provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA0BrD,qBAAa,cAAe,YAAW,WAAW;IAC1C,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAgBnF,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAW/F"}

package/dist/scm/git-scm-provider.js

@@ -0,0 +1,50 @@
+import { spawn } from "node:child_process";
+function runGit(repoRoot, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("git", args, {
+            cwd: repoRoot,
+            env: process.env,
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => {
+            stdout += String(d);
+        });
+        child.stderr.on("data", (d) => {
+            stderr += String(d);
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            resolve({ code: code ?? 1, stdout, stderr });
+        });
+    });
+}
+export class GitScmProvider {
+    async getBlobIdAtHead(repoRoot, repoRelativePath) {
+        const posixPath = repoRelativePath.replaceAll("\\", "/").replace(/^\/+/, "");
+        const spec = `HEAD:${posixPath}`;
+        const { code, stdout, stderr } = await runGit(repoRoot, ["rev-parse", spec]);
+        if (code !== 0) {
+            if (/fatal: Not a valid object name/.test(stderr) ||
+                /fatal: Path .* does not exist/.test(stderr)) {
+                return null;
+            }
+            throw new Error(`git rev-parse failed (${code}): ${stderr.trim()}`);
+        }
+        return stdout.trim() || null;
+    }
+    async isAncestor(repoRoot, possibleAncestor, commit) {
+        const { code, stderr } = await runGit(repoRoot, [
+            "merge-base",
+            "--is-ancestor",
+            possibleAncestor,
+            commit,
+        ]);
+        if (code === 0)
+            return true;
+        if (code === 1)
+            return false;
+        throw new Error(`git merge-base failed (${code}): ${stderr.trim()}`);
+    }
+}
+//# sourceMappingURL=git-scm-provider.js.map

package/dist/scm/git-scm-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-scm-provider.js","sourceRoot":"","sources":["../../src/scm/git-scm-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAG3C,SAAS,MAAM,CACb,QAAgB,EAChB,IAAc;IAEd,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE;YAC/B,GAAG,EAAE,QAAQ;YACb,GAAG,EAAE,OAAO,CAAC,GAAG;SACjB,CAAC,CAAC;QACH,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAkB,EAAE,EAAE;YAC7C,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC;QACtB,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAkB,EAAE,EAAE;YAC7C,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC;QACtB,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC1B,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAmB,EAAE,EAAE;YACxC,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QAC/C,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,OAAO,cAAc;IACzB,KAAK,CAAC,eAAe,CAAC,QAAgB,EAAE,gBAAwB;QAC9D,MAAM,SAAS,GAAG,gBAAgB,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC7E,MAAM,IAAI,GAAG,QAAQ,SAAS,EAAE,CAAC;QACjC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC;QAC7E,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;YACf,IACE,gCAAgC,CAAC,IAAI,CAAC,MAAM,CAAC;gBAC7C,+BAA+B,CAAC,IAAI,CAAC,MAAM,CAAC,EAC5C,CAAC;gBACD,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,yBAAyB,IAAI,MAAM,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACtE,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,QAAgB,EAAE,gBAAwB,EAAE,MAAc;QACzE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE;YAC9C,YAAY;YACZ,eAAe;YACf,gBAAgB;YAChB,MAAM;SACP,CAAC,CAAC;QACH,IAAI,IAAI,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAC5B,IAAI,IAAI,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,MAAM,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACvE,CAAC;CACF"}

package/dist/scm/scm-provider.d.ts

@@ -0,0 +1,8 @@
+/** Pluggable SCM integration; Git is the default implementation. */
+export type ScmProvider = {
+    /** Object id for file at HEAD (Git blob), or null if unknown/untracked. */
+    getBlobIdAtHead(repoRoot: string, repoRelativePath: string): Promise<string | null>;
+    /** True if `possibleAncestor` is an ancestor of `commit` (inclusive). */
+    isAncestor(repoRoot: string, possibleAncestor: string, commit: string): Promise<boolean>;
+};
+//# sourceMappingURL=scm-provider.d.ts.map

package/dist/scm/scm-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scm-provider.d.ts","sourceRoot":"","sources":["../../src/scm/scm-provider.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,MAAM,MAAM,WAAW,GAAG;IACxB,2EAA2E;IAC3E,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACpF,yEAAyE;IACzE,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1F,CAAC"}

package/dist/scm/scm-provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scm-provider.js.map

package/dist/scm/scm-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scm-provider.js","sourceRoot":"","sources":["../../src/scm/scm-provider.ts"],"names":[],"mappings":""}

package/dist/staleness.d.ts

@@ -0,0 +1,17 @@
+import type { CommentrayBlock } from "./model.js";
+import type { ScmProvider } from "./scm/scm-provider.js";
+export type BlockDiagnostic = {
+    blockId: string;
+    anchor: string;
+    kind: "broken_anchor" | "review_needed";
+    detail: string;
+};
+export declare function diagnoseBlock(args: {
+    repoRoot: string;
+    sourceRepoRelativePath: string;
+    headCommit: string;
+    blobAtHead: string | null;
+    block: CommentrayBlock;
+    scm: ScmProvider;
+}): Promise<BlockDiagnostic | null>;
+//# sourceMappingURL=staleness.d.ts.map

package/dist/staleness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staleness.d.ts","sourceRoot":"","sources":["../src/staleness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,eAAe,GAAG,eAAe,CAAC;IACxC,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,eAAe,CAAC;IACvB,GAAG,EAAE,WAAW,CAAC;CAClB,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CA4ClC"}

package/dist/staleness.js

@@ -0,0 +1,44 @@
+import { parseAnchor } from "./anchors.js";
+export async function diagnoseBlock(args) {
+    const { block, scm, repoRoot, headCommit, blobAtHead } = args;
+    try {
+        parseAnchor(block.anchor);
+    }
+    catch (err) {
+        return {
+            blockId: block.id,
+            anchor: block.anchor,
+            kind: "broken_anchor",
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+    if (!block.lastVerifiedCommit)
+        return null;
+    const isReachable = await scm.isAncestor(repoRoot, block.lastVerifiedCommit, headCommit);
+    if (!isReachable) {
+        return {
+            blockId: block.id,
+            anchor: block.anchor,
+            kind: "review_needed",
+            detail: "lastVerifiedCommit is not an ancestor of HEAD",
+        };
+    }
+    if (block.lastVerifiedBlob && blobAtHead && block.lastVerifiedBlob !== blobAtHead) {
+        return {
+            blockId: block.id,
+            anchor: block.anchor,
+            kind: "review_needed",
+            detail: "Primary file content at HEAD differs from lastVerifiedBlob",
+        };
+    }
+    if (!blobAtHead) {
+        return {
+            blockId: block.id,
+            anchor: block.anchor,
+            kind: "review_needed",
+            detail: "Source file is not tracked at HEAD; cannot fingerprint blob",
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=staleness.js.map

package/dist/staleness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staleness.js","sourceRoot":"","sources":["../src/staleness.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAS3C,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAOnC;IACC,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IAC9D,IAAI,CAAC;QACH,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,OAAO,EAAE,KAAK,CAAC,EAAE;YACjB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,IAAI,EAAE,eAAe;YACrB,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACzD,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,kBAAkB;QAAE,OAAO,IAAI,CAAC;IAE3C,MAAM,WAAW,GAAG,MAAM,GAAG,CAAC,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,kBAAkB,EAAE,UAAU,CAAC,CAAC;IACzF,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO;YACL,OAAO,EAAE,KAAK,CAAC,EAAE;YACjB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,IAAI,EAAE,eAAe;YACrB,MAAM,EAAE,+CAA+C;SACxD,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,CAAC,gBAAgB,IAAI,UAAU,IAAI,KAAK,CAAC,gBAAgB,KAAK,UAAU,EAAE,CAAC;QAClF,OAAO;YACL,OAAO,EAAE,KAAK,CAAC,EAAE;YACjB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,IAAI,EAAE,eAAe;YACrB,MAAM,EAAE,4DAA4D;SACrE,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO;YACL,OAAO,EAAE,KAAK,CAAC,EAAE;YACjB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,IAAI,EAAE,eAAe;YACrB,MAAM,EAAE,6DAA6D;SACtE,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/validate-project.d.ts

@@ -0,0 +1,11 @@
+import type { CommentrayIndex } from "./model.js";
+export type ValidationIssue = {
+    level: "error" | "warn";
+    message: string;
+};
+export type ValidationResult = {
+    issues: ValidationIssue[];
+};
+export declare function validateProject(repoRoot: string): Promise<ValidationResult>;
+export declare function readIndex(repoRoot: string): Promise<CommentrayIndex | null>;
+//# sourceMappingURL=validate-project.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate-project.d.ts","sourceRoot":"","sources":["../src/validate-project.ts"],"names":[],"mappings":"AAKA,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,CA2CjF;AAED,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAUjF"}

package/dist/validate-project.js

@@ -0,0 +1,64 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { loadCommentrayConfig } from "./config.js";
+import { assertValidIndex } from "./metadata.js";
+import { defaultMetadataIndexPath } from "./paths.js";
+export async function validateProject(repoRoot) {
+    const issues = [];
+    let config;
+    try {
+        config = await loadCommentrayConfig(repoRoot);
+    }
+    catch (err) {
+        issues.push({
+            level: "error",
+            message: `Failed to load .commentray.toml: ${err instanceof Error ? err.message : String(err)}`,
+        });
+        return { issues };
+    }
+    const storageAbs = path.join(repoRoot, config.storageDir);
+    for (const sub of ["source", "metadata"]) {
+        const p = path.join(storageAbs, sub);
+        try {
+            await fs.stat(p);
+        }
+        catch {
+            issues.push({
+                level: "warn",
+                message: `Missing directory: ${path.join(config.storageDir, sub)}`,
+            });
+        }
+    }
+    const indexPath = path.join(repoRoot, defaultMetadataIndexPath());
+    try {
+        const raw = await fs.readFile(indexPath, "utf8");
+        assertValidIndex(JSON.parse(raw));
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            issues.push({ level: "warn", message: `No metadata index at ${defaultMetadataIndexPath()}` });
+        }
+        else {
+            issues.push({
+                level: "error",
+                message: `Invalid metadata index: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+    return { issues };
+}
+export async function readIndex(repoRoot) {
+    const indexPath = path.join(repoRoot, defaultMetadataIndexPath());
+    try {
+        const raw = await fs.readFile(indexPath, "utf8");
+        return assertValidIndex(JSON.parse(raw));
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+//# sourceMappingURL=validate-project.js.map

package/dist/validate-project.js.map

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

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@commentray/core",
+  "version": "0.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Commentray models, validation, SCM adapters, and staleness helpers",
+  "license": "MPL-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@iarna/toml": "^2.2.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.1"
+  }
+}