@mrsf/cli 0.4.3 → 0.6.0

package/dist/lib/reanchor.d.ts

@@ -12,7 +12,7 @@
  *   Step 4  – orphan
  */
 import type { MrsfDocument, ReanchorOptions, ReanchorResult } from "./types.js";
-export { applyReanchorResults, DEFAULT_THRESHOLD, HIGH_THRESHOLD, reanchorComment, reanchorDocumentLines, reanchorDocumentText, toReanchorLines, } from "./reanchor-core.js";
+export { applyReanchorResults, DEFAULT_THRESHOLD, HIGH_THRESHOLD, reanchorComment, reanchorDocumentLines, reanchorDocumentText, resolveAnchor, toReanchorLines, } from "./reanchor-core.js";
 /**
  * Re-anchor all comments in an MRSF document.
  */

package/dist/lib/reanchor.js

@@ -18,7 +18,7 @@ import { sidecarToDocument } from "./discovery.js";
 import { parseSidecar } from "./parser.js";
 import { writeSidecar } from "./writer.js";
 import path from "node:path";
-export { applyReanchorResults, DEFAULT_THRESHOLD, HIGH_THRESHOLD, reanchorComment, reanchorDocumentLines, reanchorDocumentText, toReanchorLines, } from "./reanchor-core.js";
+export { applyReanchorResults, DEFAULT_THRESHOLD, HIGH_THRESHOLD, reanchorComment, reanchorDocumentLines, reanchorDocumentText, resolveAnchor, toReanchorLines, } from "./reanchor-core.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -31,6 +31,7 @@ export { applyReanchorResults, DEFAULT_THRESHOLD, HIGH_THRESHOLD, reanchorCommen
 export async function reanchorDocument(doc, documentLines, opts = {}) {
     const results = [];
     const threshold = opts.threshold ?? DEFAULT_THRESHOLD;
+    const proximityWindow = opts.proximityWindow;
     // Determine git context
     let diffHunks;
     let commitIsStale = false;
@@ -51,17 +52,18 @@ export async function reanchorDocument(doc, documentLines, opts = {}) {
                         diffHunks: hunks,
                         threshold,
                         commitIsStale: true,
+                        proximityWindow,
                     });
                     results.push(result);
                     continue;
                 }
                 // non-stale or no commit
-                results.push(reanchorComment(comment, documentLines, { threshold, commitIsStale: false }));
+                results.push(reanchorComment(comment, documentLines, { threshold, commitIsStale: false, proximityWindow }));
             }
             return results;
         }
     }
-    return reanchorDocumentLines(doc, documentLines, { threshold });
+    return reanchorDocumentLines(doc, documentLines, { threshold, proximityWindow });
 }
 /**
  * High-level re-anchor for a single sidecar file path.

package/dist/lib/schema.d.ts

@@ -0,0 +1,106 @@
+export declare const mrsfSchema: {
+    $schema: string;
+    $id: string;
+    title: string;
+    description: string;
+    type: string;
+    required: string[];
+    additionalProperties: boolean;
+    properties: {
+        mrsf_version: {
+            type: string;
+            pattern: string;
+            description: string;
+        };
+        document: {
+            type: string;
+            description: string;
+        };
+        comments: {
+            type: string;
+            items: {
+                type: string;
+                required: string[];
+                additionalProperties: boolean;
+                properties: {
+                    id: {
+                        type: string;
+                        description: string;
+                    };
+                    author: {
+                        type: string;
+                        description: string;
+                    };
+                    timestamp: {
+                        type: string;
+                        format: string;
+                        description: string;
+                    };
+                    text: {
+                        type: string;
+                        maxLength: number;
+                        description: string;
+                    };
+                    resolved: {
+                        type: string;
+                        description: string;
+                    };
+                    commit: {
+                        type: string;
+                        description: string;
+                    };
+                    type: {
+                        type: string;
+                        description: string;
+                        examples: string[];
+                    };
+                    severity: {
+                        type: string;
+                        description: string;
+                        enum: string[];
+                    };
+                    reply_to: {
+                        type: string;
+                        description: string;
+                    };
+                    line: {
+                        type: string;
+                        minimum: number;
+                        description: string;
+                    };
+                    end_line: {
+                        type: string;
+                        minimum: number;
+                        description: string;
+                    };
+                    start_column: {
+                        type: string;
+                        minimum: number;
+                        description: string;
+                    };
+                    end_column: {
+                        type: string;
+                        minimum: number;
+                        description: string;
+                    };
+                    selected_text: {
+                        type: string;
+                        maxLength: number;
+                        description: string;
+                    };
+                    anchored_text: {
+                        type: string;
+                        maxLength: number;
+                        description: string;
+                    };
+                    selected_text_hash: {
+                        type: string;
+                        pattern: string;
+                        description: string;
+                    };
+                };
+            };
+        };
+    };
+};
+//# sourceMappingURL=schema.d.ts.map

package/dist/lib/schema.js

@@ -0,0 +1,3 @@
+import mrsfSchemaJson from "../../mrsf.schema.json" with { type: "json" };
+export const mrsfSchema = mrsfSchemaJson;
+//# sourceMappingURL=schema.js.map

package/dist/lib/serialize.d.ts

@@ -0,0 +1,37 @@
+/**
+ * MRSF string (de)serialization — pure, dependency-light helpers that parse and
+ * serialize MRSF sidecar content to/from strings.
+ *
+ * This module intentionally has **no Node-only imports** (no `node:fs`,
+ * `node:path`, `node:crypto`, …) so it can be consumed from browser/host
+ * adapters via the slim `@mrsf/cli/browser` entry point. Filesystem-bound
+ * helpers (read/discover/write a file) live in `parser.ts` / `writer.ts`.
+ */
+import type { MrsfDocument, Comment } from "./types.js";
+/** Result from a lenient (non-throwing) parse attempt. */
+export interface LenientParseResult {
+    /** Fully parsed document, or null if parsing failed entirely. */
+    doc: MrsfDocument | null;
+    /** If parsing failed or produced warnings, the error message. */
+    error?: string;
+    /** Comments that could be salvaged from a partially-corrupted sidecar. */
+    partialComments?: Comment[];
+}
+/**
+ * Parse MRSF sidecar content from a string.
+ * Detects JSON vs YAML based on content or optional filename hint.
+ */
+export declare function parseSidecarContent(content: string, filenameHint?: string): MrsfDocument;
+/**
+ * Lenient parse from string content.
+ */
+export declare function parseSidecarContentLenient(content: string, filenameHint?: string): LenientParseResult;
+/**
+ * Serialize an MrsfDocument to YAML (for new files / non-round-trip use).
+ */
+export declare function toYaml(doc: MrsfDocument): string;
+/**
+ * Serialize an MrsfDocument to JSON.
+ */
+export declare function toJson(doc: MrsfDocument): string;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/lib/serialize.js

@@ -0,0 +1,170 @@
+/**
+ * MRSF string (de)serialization — pure, dependency-light helpers that parse and
+ * serialize MRSF sidecar content to/from strings.
+ *
+ * This module intentionally has **no Node-only imports** (no `node:fs`,
+ * `node:path`, `node:crypto`, …) so it can be consumed from browser/host
+ * adapters via the slim `@mrsf/cli/browser` entry point. Filesystem-bound
+ * helpers (read/discover/write a file) live in `parser.ts` / `writer.ts`.
+ */
+import yaml from "js-yaml";
+import { Document } from "yaml";
+// ---------------------------------------------------------------------------
+// Parsing (string → document)
+// ---------------------------------------------------------------------------
+/**
+ * Parse MRSF sidecar content from a string.
+ * Detects JSON vs YAML based on content or optional filename hint.
+ */
+export function parseSidecarContent(content, filenameHint) {
+    const trimmed = content.trim();
+    let parsed;
+    // Detect JSON by content or filename
+    const isJson = trimmed.startsWith("{") ||
+        (filenameHint && filenameHint.endsWith(".review.json"));
+    if (isJson) {
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch (e) {
+            throw new Error(`Failed to parse JSON: ${e.message}`);
+        }
+    }
+    else {
+        try {
+            parsed = yaml.load(trimmed, { schema: yaml.JSON_SCHEMA });
+        }
+        catch (e) {
+            throw new Error(`Failed to parse YAML: ${e.message}`);
+        }
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("MRSF sidecar must be a YAML/JSON object");
+    }
+    return parsed;
+}
+/**
+ * Lenient parse from string content.
+ */
+export function parseSidecarContentLenient(content, filenameHint) {
+    const trimmed = content.trim();
+    if (!trimmed) {
+        return { doc: null, error: "File is empty" };
+    }
+    const isJson = trimmed.startsWith("{") ||
+        (filenameHint && filenameHint.endsWith(".review.json"));
+    // First, try a normal parse
+    let parsed;
+    try {
+        parsed = isJson ? JSON.parse(trimmed) : yaml.load(trimmed, { schema: yaml.JSON_SCHEMA });
+    }
+    catch (e) {
+        // Total parse failure — try to salvage what we can from YAML
+        if (!isJson) {
+            return salvageYaml(trimmed);
+        }
+        return { doc: null, error: `Failed to parse JSON: ${e.message}` };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { doc: null, error: "MRSF sidecar must be a YAML/JSON object" };
+    }
+    const obj = parsed;
+    const doc = {
+        mrsf_version: typeof obj.mrsf_version === "string" ? obj.mrsf_version : "1.0",
+        document: typeof obj.document === "string" ? obj.document : "unknown",
+        comments: [],
+    };
+    if (!Array.isArray(obj.comments)) {
+        return {
+            doc,
+            error: "comments field is not an array — file may be corrupted",
+        };
+    }
+    // Validate each comment individually
+    const good = [];
+    const bad = [];
+    for (let i = 0; i < obj.comments.length; i++) {
+        const c = obj.comments[i];
+        if (c && typeof c === "object" && !Array.isArray(c) && typeof c.id === "string") {
+            good.push(c);
+        }
+        else {
+            bad.push(i);
+        }
+    }
+    doc.comments = good;
+    if (bad.length > 0) {
+        return {
+            doc,
+            error: `${bad.length} comment(s) at indices [${bad.join(", ")}] were malformed and skipped`,
+            partialComments: good,
+        };
+    }
+    return { doc };
+}
+/**
+ * Attempt to extract individual comment blocks from corrupted YAML by
+ * splitting on `- id:` patterns and parsing each block independently.
+ */
+function salvageYaml(content) {
+    const salvaged = [];
+    let mrsf_version = "1.0";
+    let document = "unknown";
+    // Try to extract top-level fields from the beginning
+    const versionMatch = content.match(/^mrsf_version:\s*["']?([^"'\n]+)/m);
+    if (versionMatch)
+        mrsf_version = versionMatch[1].trim();
+    const docMatch = content.match(/^document:\s*["']?([^"'\n]+)/m);
+    if (docMatch)
+        document = docMatch[1].trim();
+    // Split on comment block boundaries (- id: ...)
+    const blocks = content.split(/(?=^  - id:\s)/m);
+    for (const block of blocks) {
+        const trimmed = block.trim();
+        if (!trimmed.startsWith("- id:"))
+            continue;
+        // Wrap in a minimal YAML array context and try to parse
+        try {
+            const parsed = yaml.load(trimmed, { schema: yaml.JSON_SCHEMA });
+            if (Array.isArray(parsed) && parsed.length > 0) {
+                const c = parsed[0];
+                if (c && typeof c === "object" && typeof c.id === "string") {
+                    salvaged.push(c);
+                }
+            }
+            else if (parsed && typeof parsed === "object" && typeof parsed.id === "string") {
+                salvaged.push(parsed);
+            }
+        }
+        catch {
+            // This block is unparseable — skip
+        }
+    }
+    const doc = {
+        mrsf_version,
+        document,
+        comments: salvaged,
+    };
+    return {
+        doc: salvaged.length > 0 ? doc : null,
+        error: `YAML parse failed. Salvaged ${salvaged.length} comment(s) from raw content.`,
+        partialComments: salvaged.length > 0 ? salvaged : undefined,
+    };
+}
+// ---------------------------------------------------------------------------
+// Serialization (document → string)
+// ---------------------------------------------------------------------------
+/**
+ * Serialize an MrsfDocument to YAML (for new files / non-round-trip use).
+ */
+export function toYaml(doc) {
+    const yamlDoc = new Document(doc);
+    return yamlDoc.toString({ lineWidth: 0 });
+}
+/**
+ * Serialize an MrsfDocument to JSON.
+ */
+export function toJson(doc) {
+    return JSON.stringify(doc, null, 2) + "\n";
+}
+//# sourceMappingURL=serialize.js.map

package/dist/lib/types.d.ts

@@ -40,6 +40,7 @@ export interface MrsfConfig {
 export type DiagnosticSeverity = "error" | "warning";
 export interface ValidationDiagnostic {
     severity: DiagnosticSeverity;
+    code: string;
     message: string;
     /** Path within the document, e.g. "/comments/0/end_line". */
     path?: string;
@@ -69,6 +70,23 @@ export interface ReanchorResult {
     /** Human-readable explanation of the resolution. */
     reason: string;
 }
+export interface AnchorPosition {
+    status: ReanchorStatus;
+    score: number;
+    /** Absolute 0-based character offset in normalized document text (start). */
+    from?: number;
+    /** Absolute 0-based character offset in normalized document text (end, exclusive). */
+    to?: number;
+    /** 1-based start line. */
+    line?: number;
+    /** 1-based end line. */
+    endLine?: number;
+    /** 0-based start column. */
+    startColumn?: number;
+    /** 0-based end column. */
+    endColumn?: number;
+    reason: string;
+}
 export interface FuzzyCandidate {
     /** Matched text in the document. */
     text: string;
@@ -154,6 +172,13 @@ export interface ReanchorOptions extends BaseOptions {
     fromCommit?: string;
     /** Update selected_text to match anchored_text (opt-in per §6.2). */
     updateText?: boolean;
+    /**
+     * Proximity window (in lines) for the §7.4 step 1a relocation guard.
+     * A lone exact match farther than this from the original line, when the
+     * original position's text has changed, is kept in place and flagged for
+     * re-anchoring rather than relocated with full confidence. Default 5.
+     */
+    proximityWindow?: number;
     /** Force-anchor: update commit to HEAD and clear audit fields for high-confidence results. */
     force?: boolean;
 }

package/dist/lib/validate-core.d.ts

@@ -0,0 +1,6 @@
+import type { MrsfDocument, ValidationDiagnostic, ValidationResult } from "./types.js";
+export type HashFunction = (text: string) => string;
+export declare function validateDocument(doc: MrsfDocument, schema?: object): ValidationResult;
+export declare function validateSchema(doc: MrsfDocument, rawSchema: object, errors: ValidationDiagnostic[]): void;
+export declare function validateCrossFields(doc: MrsfDocument, errors: ValidationDiagnostic[], warnings: ValidationDiagnostic[], hash?: HashFunction): void;
+//# sourceMappingURL=validate-core.d.ts.map

package/dist/lib/validate-core.js

@@ -0,0 +1,128 @@
+import AjvModule from "ajv";
+import addFormatsModule from "ajv-formats";
+import { mrsfSchema } from "./schema.js";
+const Ajv = AjvModule.default ?? AjvModule;
+const addFormats = addFormatsModule.default ?? addFormatsModule;
+export function validateDocument(doc, schema = mrsfSchema) {
+    const errors = [];
+    const warnings = [];
+    validateSchema(doc, schema, errors);
+    validateCrossFields(doc, errors, warnings);
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+export function validateSchema(doc, rawSchema, errors) {
+    const { $schema, ...schema } = rawSchema;
+    void $schema;
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    addFormats(ajv);
+    const ajvValidate = ajv.compile(schema);
+    const schemaValid = ajvValidate(doc);
+    if (!schemaValid && ajvValidate.errors) {
+        for (const err of ajvValidate.errors) {
+            errors.push({
+                severity: "error",
+                code: "schema-violation",
+                message: `${err.instancePath || "/"}: ${err.message ?? "schema error"}`,
+                path: err.instancePath || "/",
+            });
+        }
+    }
+}
+export function validateCrossFields(doc, errors, warnings, hash) {
+    if (!Array.isArray(doc.comments))
+        return;
+    const ids = new Set();
+    const allIds = doc.comments.map((x) => x.id);
+    for (let i = 0; i < doc.comments.length; i++) {
+        const c = doc.comments[i];
+        const prefix = `/comments/${i}`;
+        if (c.id) {
+            if (ids.has(c.id)) {
+                errors.push({
+                    severity: "error",
+                    code: "duplicate-id",
+                    message: `Duplicate comment id "${c.id}"`,
+                    path: `${prefix}/id`,
+                    commentId: c.id,
+                });
+            }
+            ids.add(c.id);
+        }
+        if (c.line != null && c.end_line != null && c.end_line < c.line) {
+            errors.push({
+                severity: "error",
+                code: "end-line-before-line",
+                message: `end_line (${c.end_line}) must be ≥ line (${c.line})`,
+                path: `${prefix}/end_line`,
+                commentId: c.id,
+            });
+        }
+        if (c.start_column != null &&
+            c.end_column != null &&
+            (c.line == null || c.end_line == null || c.line === c.end_line) &&
+            c.end_column < c.start_column) {
+            errors.push({
+                severity: "error",
+                code: "end-column-before-start-column",
+                message: `end_column (${c.end_column}) must be ≥ start_column (${c.start_column}) on the same line`,
+                path: `${prefix}/end_column`,
+                commentId: c.id,
+            });
+        }
+        if (c.selected_text && c.selected_text.length > 4096) {
+            errors.push({
+                severity: "error",
+                code: "selected-text-too-long",
+                message: `selected_text exceeds 4096 characters (${c.selected_text.length})`,
+                path: `${prefix}/selected_text`,
+                commentId: c.id,
+            });
+        }
+        if (c.text && c.text.length > 16384) {
+            warnings.push({
+                severity: "warning",
+                code: "text-too-long",
+                message: `text exceeds recommended 16384 characters (${c.text.length})`,
+                path: `${prefix}/text`,
+                commentId: c.id,
+            });
+        }
+        // Browser-safe callers do not get the Node SHA-256 implementation.
+        // The hash check runs only when a hash function is injected by the Node validator.
+        if (hash && c.selected_text && c.selected_text_hash) {
+            const expected = hash(c.selected_text);
+            if (c.selected_text_hash !== expected) {
+                warnings.push({
+                    severity: "warning",
+                    code: "hash-mismatch",
+                    message: `selected_text_hash mismatch (expected ${expected.slice(0, 12)}…, got ${c.selected_text_hash.slice(0, 12)}…)`,
+                    path: `${prefix}/selected_text_hash`,
+                    commentId: c.id,
+                });
+            }
+        }
+        if (c.reply_to && !ids.has(c.reply_to) && !allIds.includes(c.reply_to)) {
+            warnings.push({
+                severity: "warning",
+                code: "unresolved-reply-to",
+                message: `reply_to "${c.reply_to}" does not resolve to any comment id in this file`,
+                path: `${prefix}/reply_to`,
+                commentId: c.id,
+            });
+        }
+        if (c.line != null && !c.selected_text) {
+            warnings.push({
+                severity: "warning",
+                code: "missing-selected-text",
+                message: "Comment has line anchors but no selected_text — anchoring will be fragile across edits",
+                path: `${prefix}/selected_text`,
+                commentId: c.id,
+            });
+        }
+    }
+}
+//# sourceMappingURL=validate-core.js.map