@mrsf/cli 0.3.1 → 0.4.1

package/README.md

@@ -82,6 +82,15 @@ mrsf add docs/api.md \
   --author "alice" \
   --text "Good catch, fixed in abc123" \
   --reply-to 3eeccbd3
+
+# Attach tool-specific x_* metadata
+mrsf add docs/api.md \
+  --author "bot" \
+  --text "Flagging this for follow-up" \
+  --line 27 \
+  --ext x_source=triage-bot \
+  --ext x_score=0.91 \
+  --ext 'x_labels=["needs-review","docs"]'
 ```
 
 | Option | Description |
@@ -96,6 +105,9 @@ mrsf add docs/api.md \
 | `--severity <level>` | Importance: `low`, `medium`, `high` |
 | `--reply-to <id>` | Reply to an existing comment by ID |
 | `--selected-text <text>` | Override auto-detected selected text |
+| `--ext <key=value>` | Add an `x_*` extension field; repeat for multiple fields |
+
+`--ext` values are stored as flat `x_*` fields in the sidecar. Primitive JSON literals like numbers, `true`, `false`, and `null` are parsed automatically, and objects/arrays can be passed as JSON.
 
 ---
 
@@ -372,6 +384,26 @@ const updated = addComment(doc, lines, {
 await writeSidecar("docs/api.md.review.yaml", updated);
 ```
 
+### Browser-safe reanchoring
+
+The default `@mrsf/cli` entrypoint is Node-oriented and includes file system and git-backed helpers such as `parseSidecar`, `readDocumentLines`, and `reanchorFile`. For browser bundles and editor integrations, use the `@mrsf/cli/browser` subpath instead.
+
+`@mrsf/cli/browser` exports the pure text-based matching and reanchoring primitives only:
+
+```typescript
+import {
+  applyReanchorResults,
+  reanchorDocumentText,
+} from "@mrsf/cli/browser";
+
+const results = reanchorDocumentText(sidecar, markdownText);
+const changed = applyReanchorResults(sidecar, results);
+
+console.log(changed, results.map((result) => result.status));
+```
+
+Use this entrypoint when you already have the document text and sidecar object in memory. It intentionally excludes Node-only helpers such as sidecar discovery, file parsing, file writing, and git-aware diff reanchoring.
+
 ## Configuration
 
 Place a `.mrsf.yaml` at your repository root to configure sidecar discovery:

package/dist/browser.d.ts

@@ -0,0 +1,4 @@
+export type { Comment, DiffHunk, FuzzyCandidate, MrsfDocument, ReanchorResult, ReanchorStatus, } from "./lib/types.js";
+export { combinedScore, exactMatch, fuzzySearch, levenshteinScore, normalizedMatch, tokenLcsScore, } from "./lib/fuzzy.js";
+export { applyReanchorResults, DEFAULT_THRESHOLD, HIGH_THRESHOLD, reanchorComment, reanchorDocumentLines, reanchorDocumentText, toReanchorLines, } from "./lib/reanchor-core.js";
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.js

@@ -0,0 +1,3 @@
+export { combinedScore, exactMatch, fuzzySearch, levenshteinScore, normalizedMatch, tokenLcsScore, } from "./lib/fuzzy.js";
+export { applyReanchorResults, DEFAULT_THRESHOLD, HIGH_THRESHOLD, reanchorComment, reanchorDocumentLines, reanchorDocumentText, toReanchorLines, } from "./lib/reanchor-core.js";
+//# sourceMappingURL=browser.js.map

package/dist/commands/add.js

@@ -8,6 +8,46 @@ import { parseSidecar, readDocumentLines } from "../lib/parser.js";
 import { writeSidecar } from "../lib/writer.js";
 import { addComment, populateSelectedText } from "../lib/comments.js";
 import { findRepoRoot } from "../lib/git.js";
+function collectOptionValues(value, previous) {
+    previous.push(value);
+    return previous;
+}
+function parseExtensionValue(rawValue) {
+    const trimmed = rawValue.trim();
+    if (/^(true|false|null)$/u.test(trimmed)) {
+        return JSON.parse(trimmed);
+    }
+    if (/^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?$/u.test(trimmed)) {
+        return JSON.parse(trimmed);
+    }
+    if ((trimmed.startsWith("{") && trimmed.endsWith("}")) || (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Invalid JSON extension value '${rawValue}': ${message}`);
+        }
+    }
+    return rawValue;
+}
+function parseExtensionFlags(flags) {
+    if (!flags || flags.length === 0)
+        return undefined;
+    const entries = flags.map((flag) => {
+        const separatorIndex = flag.indexOf("=");
+        if (separatorIndex <= 0) {
+            throw new Error(`Invalid --ext value '${flag}'. Expected key=value.`);
+        }
+        const key = flag.slice(0, separatorIndex).trim();
+        const rawValue = flag.slice(separatorIndex + 1);
+        if (!key) {
+            throw new Error(`Invalid --ext value '${flag}'. Expected a non-empty key.`);
+        }
+        return [key, parseExtensionValue(rawValue)];
+    });
+    return Object.fromEntries(entries);
+}
 export function registerAdd(program) {
     program
         .command("add <document>")
@@ -22,6 +62,7 @@ export function registerAdd(program) {
         .option("--severity <level>", "Severity: low | medium | high")
         .option("--reply-to <id>", "Reply to an existing comment")
         .option("--selected-text <text>", "Selected text to attach")
+        .option("--ext <key=value>", "Comment extension field keyed by x_* (repeatable)", collectOptionValues, [])
         .action(async (document, opts) => {
         const parentOpts = program.opts();
         const cwd = parentOpts.cwd ?? process.cwd();
@@ -58,6 +99,7 @@ export function registerAdd(program) {
             type: opts.type,
             severity: opts.severity,
             reply_to: opts.replyTo,
+            extensions: parseExtensionFlags(opts.ext),
         }, repoRoot ?? undefined);
         // Auto-populate selected_text from the document if not provided
         if (opts.selectedText) {

package/dist/commands/watch.js

@@ -253,6 +253,7 @@ export function registerWatch(program) {
         }
         // ── Graceful shutdown ────────────────────────────────
         async function shutdown() {
+            cleanupSignalHandlers();
             // Clear pending debounce timers
             for (const t of timers.values())
                 clearTimeout(t);
@@ -266,8 +267,19 @@ export function registerWatch(program) {
             }
             process.exit(totalErrors > 0 ? 1 : 0);
         }
-        process.on("SIGINT", () => void shutdown());
-        process.on("SIGTERM", () => void shutdown());
+        const onSigint = () => {
+            void shutdown();
+        };
+        const onSigterm = () => {
+            void shutdown();
+        };
+        function cleanupSignalHandlers() {
+            process.off("SIGINT", onSigint);
+            process.off("SIGTERM", onSigterm);
+        }
+        process.on("SIGINT", onSigint);
+        process.on("SIGTERM", onSigterm);
+        watcher.once("close", cleanupSignalHandlers);
         // Keep the process alive
         await new Promise(() => {
             // Never resolves — the process runs until interrupted

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  * Usage:
  *   import { validate, reanchorFile, addComment, ... } from "mrsf";
  */
-export type { MrsfDocument, Comment, MrsfConfig, DiagnosticSeverity, ValidationDiagnostic, ValidationResult, ReanchorStatus, ReanchorResult, FuzzyCandidate, DiffHunk, AddCommentOptions, CommentFilter, AnchorHealth, StatusResult, BaseOptions, ReanchorOptions, ValidateOptions, } from "./lib/types.js";
+export type { MrsfDocument, Comment, CommentExtensions, CommentExtensionValue, MrsfConfig, DiagnosticSeverity, ValidationDiagnostic, ValidationResult, ReanchorStatus, ReanchorResult, FuzzyCandidate, DiffHunk, AddCommentOptions, CommentFilter, AnchorHealth, StatusResult, BaseOptions, ReanchorOptions, ValidateOptions, } from "./lib/types.js";
 export { findWorkspaceRoot, loadConfig, discoverSidecar, sidecarToDocument, discoverAllSidecars, } from "./lib/discovery.js";
 export { resolveSidecarPaths } from "./lib/resolve-files.js";
 export { parseSidecar, parseSidecarContent, parseSidecarLenient, parseSidecarContentLenient, readDocumentLines, } from "./lib/parser.js";
@@ -13,7 +13,7 @@ export { computeHash, syncHash, toYaml, toJson, writeSidecar, } from "./lib/writ
 export { validate, validateFile } from "./lib/validator.js";
 export { exactMatch, normalizedMatch, fuzzySearch, combinedScore, } from "./lib/fuzzy.js";
 export { isGitAvailable, findRepoRoot, getCurrentCommit, isStale, getDiff, getLineShift, getFileAtCommit, getStagedFiles, detectRenames, parseDiffHunks, } from "./lib/git.js";
-export { reanchorComment, reanchorDocument, applyReanchorResults, reanchorFile, } from "./lib/reanchor.js";
-export { addComment, populateSelectedText, resolveComment, unresolveComment, removeComment, filterComments, getThreads, summarize, } from "./lib/comments.js";
+export { DEFAULT_THRESHOLD, HIGH_THRESHOLD, reanchorComment, reanchorDocumentLines, reanchorDocumentText, toReanchorLines, reanchorDocument, applyReanchorResults, reanchorFile, } from "./lib/reanchor.js";
+export { addComment, normalizeCommentExtensions, populateSelectedText, resolveComment, unresolveComment, removeComment, filterComments, getThreads, summarize, } from "./lib/comments.js";
 export type { CommentSummary, RemoveCommentOptions } from "./lib/comments.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -19,7 +19,7 @@ export { exactMatch, normalizedMatch, fuzzySearch, combinedScore, } from "./lib/
 // Git
 export { isGitAvailable, findRepoRoot, getCurrentCommit, isStale, getDiff, getLineShift, getFileAtCommit, getStagedFiles, detectRenames, parseDiffHunks, } from "./lib/git.js";
 // Re-anchoring
-export { reanchorComment, reanchorDocument, applyReanchorResults, reanchorFile, } from "./lib/reanchor.js";
+export { DEFAULT_THRESHOLD, HIGH_THRESHOLD, reanchorComment, reanchorDocumentLines, reanchorDocumentText, toReanchorLines, reanchorDocument, applyReanchorResults, reanchorFile, } from "./lib/reanchor.js";
 // Comments
-export { addComment, populateSelectedText, resolveComment, unresolveComment, removeComment, filterComments, getThreads, summarize, } from "./lib/comments.js";
+export { addComment, normalizeCommentExtensions, populateSelectedText, resolveComment, unresolveComment, removeComment, filterComments, getThreads, summarize, } from "./lib/comments.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/comments.d.ts

@@ -1,7 +1,8 @@
 /**
  * MRSF Comment Operations — CRUD for sidecar comments.
  */
-import type { AddCommentOptions, Comment, CommentFilter, MrsfDocument } from "./types.js";
+import type { AddCommentOptions, Comment, CommentFilter, CommentExtensions, MrsfDocument } from "./types.js";
+export declare function normalizeCommentExtensions(extensions?: Record<string, unknown>): CommentExtensions;
 /**
  * Add a new comment to a document. Mutates doc.comments in place.
  * Returns the created comment.

package/dist/lib/comments.js

@@ -7,6 +7,49 @@ import { getCurrentCommit, isGitAvailable } from "./git.js";
 // ---------------------------------------------------------------------------
 // Add
 // ---------------------------------------------------------------------------
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function isCommentExtensionValue(value) {
+    if (value == null)
+        return true;
+    switch (typeof value) {
+        case "boolean":
+        case "string":
+            return true;
+        case "number":
+            return Number.isFinite(value);
+        case "object": {
+            if (Array.isArray(value)) {
+                return value.every((item) => isCommentExtensionValue(item));
+            }
+            if (!isPlainObject(value)) {
+                return false;
+            }
+            return Object.values(value).every((item) => isCommentExtensionValue(item));
+        }
+        default:
+            return false;
+    }
+}
+export function normalizeCommentExtensions(extensions) {
+    if (!extensions)
+        return {};
+    const normalizedEntries = [];
+    for (const [key, value] of Object.entries(extensions)) {
+        if (!key.startsWith("x_")) {
+            throw new Error(`Comment extension key '${key}' must start with 'x_'.`);
+        }
+        if (!isCommentExtensionValue(value)) {
+            throw new Error(`Comment extension '${key}' must be JSON-serializable (null, boolean, finite number, string, array, or plain object).`);
+        }
+        normalizedEntries.push([key, value]);
+    }
+    return Object.fromEntries(normalizedEntries);
+}
 /**
  * Add a new comment to a document. Mutates doc.comments in place.
  * Returns the created comment.
@@ -43,6 +86,7 @@ export async function addComment(doc, opts, repoRoot) {
         comment.reply_to = opts.reply_to;
     if (commit)
         comment.commit = commit;
+    Object.assign(comment, normalizeCommentExtensions(opts.extensions));
     doc.comments.push(comment);
     return comment;
 }

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

@@ -0,0 +1,21 @@
+import type { Comment, DiffHunk, MrsfDocument, ReanchorResult } from "./types.js";
+export declare const HIGH_THRESHOLD = 0.8;
+export declare const DEFAULT_THRESHOLD = 0.6;
+export declare function toReanchorLines(documentText: string): string[];
+export declare function reanchorComment(comment: Comment, documentLines: string[], opts?: {
+    diffHunks?: DiffHunk[];
+    threshold?: number;
+    commitIsStale?: boolean;
+}): ReanchorResult;
+export declare function reanchorDocumentLines(doc: MrsfDocument, documentLines: string[], opts?: {
+    threshold?: number;
+}): ReanchorResult[];
+export declare function reanchorDocumentText(doc: MrsfDocument, documentText: string, opts?: {
+    threshold?: number;
+}): ReanchorResult[];
+export declare function applyReanchorResults(doc: MrsfDocument, results: ReanchorResult[], opts?: {
+    updateText?: boolean;
+    force?: boolean;
+    headCommit?: string;
+}): number;
+//# sourceMappingURL=reanchor-core.d.ts.map

package/dist/lib/reanchor-core.js

@@ -0,0 +1,298 @@
+import { exactMatch, fuzzySearch, normalizedMatch, } from "./fuzzy.js";
+export const HIGH_THRESHOLD = 0.8;
+export const DEFAULT_THRESHOLD = 0.6;
+export function toReanchorLines(documentText) {
+    return ["", ...documentText.replace(/\r\n/g, "\n").split("\n")];
+}
+export function reanchorComment(comment, documentLines, opts = {}) {
+    const threshold = opts.threshold ?? DEFAULT_THRESHOLD;
+    const commentId = comment.id;
+    const selectedText = comment.selected_text;
+    if (!selectedText && comment.line == null) {
+        return {
+            commentId,
+            status: "anchored",
+            score: 1.0,
+            reason: "Document-level comment (no anchor needed).",
+        };
+    }
+    if (comment.line != null && opts.diffHunks?.length) {
+        const { shift, modified } = getLineShift(opts.diffHunks, comment.line);
+        if (!selectedText) {
+            const shiftedLine = comment.line + shift;
+            const lineSpan = comment.end_line != null ? comment.end_line - comment.line : 0;
+            const shiftedEndLine = comment.end_line != null ? shiftedLine + lineSpan : undefined;
+            return {
+                commentId,
+                status: shift === 0 ? "anchored" : "shifted",
+                score: 1.0,
+                newLine: shiftedLine,
+                newEndLine: shiftedEndLine,
+                reason: shift === 0
+                    ? "Line-only comment unchanged (diff confirms position)."
+                    : `Line-only comment shifted by ${shift > 0 ? "+" : ""}${shift} line(s) via diff.`,
+            };
+        }
+        if (!modified) {
+            const shiftedLine = comment.line + shift;
+            const lineSpan = comment.end_line != null ? comment.end_line - comment.line : 0;
+            const shiftedEndLine = comment.end_line != null ? shiftedLine + lineSpan : undefined;
+            const textAtShifted = extractText(documentLines, shiftedLine, shiftedEndLine, comment.start_column, comment.end_column);
+            if (textAtShifted === selectedText) {
+                return {
+                    commentId,
+                    status: shift === 0 ? "anchored" : "shifted",
+                    score: 1.0,
+                    newLine: shiftedLine,
+                    newEndLine: shiftedEndLine,
+                    reason: shift === 0
+                        ? "Diff confirms text unchanged at original position."
+                        : `Diff shifted by ${shift > 0 ? "+" : ""}${shift} line(s).`,
+                };
+            }
+        }
+    }
+    if (selectedText) {
+        const exactCandidates = exactMatch(documentLines, selectedText);
+        if (exactCandidates.length === 1) {
+            const candidate = exactCandidates[0];
+            return {
+                commentId,
+                status: "anchored",
+                score: 1.0,
+                newLine: candidate.line,
+                newEndLine: candidate.endLine,
+                newStartColumn: candidate.startColumn,
+                newEndColumn: candidate.endColumn,
+                reason: "Exact text match (unique).",
+            };
+        }
+        if (exactCandidates.length > 1 && comment.line != null) {
+            const best = closestToLine(exactCandidates, comment.line);
+            return {
+                commentId,
+                status: "anchored",
+                score: 1.0,
+                newLine: best.line,
+                newEndLine: best.endLine,
+                newStartColumn: best.startColumn,
+                newEndColumn: best.endColumn,
+                reason: `Exact text match (${exactCandidates.length} occurrences; chose nearest to original line ${comment.line}).`,
+            };
+        }
+        const normCandidates = normalizedMatch(documentLines, selectedText);
+        if (normCandidates.length === 1) {
+            const candidate = normCandidates[0];
+            return {
+                commentId,
+                status: "fuzzy",
+                score: candidate.score,
+                newLine: candidate.line,
+                newEndLine: candidate.endLine,
+                newStartColumn: candidate.startColumn,
+                newEndColumn: candidate.endColumn,
+                anchoredText: candidate.text,
+                previousSelectedText: selectedText,
+                reason: "Normalized whitespace match.",
+            };
+        }
+        const fuzzyCandidates = fuzzySearch(documentLines, selectedText, HIGH_THRESHOLD, comment.line);
+        if (fuzzyCandidates.length === 1 || (fuzzyCandidates.length > 0 && fuzzyCandidates[0].score >= HIGH_THRESHOLD)) {
+            const best = fuzzyCandidates.length === 1
+                ? fuzzyCandidates[0]
+                : closestToLine(fuzzyCandidates, comment.line ?? 1);
+            return {
+                commentId,
+                status: "fuzzy",
+                score: best.score,
+                newLine: best.line,
+                newEndLine: best.endLine,
+                newStartColumn: best.startColumn,
+                newEndColumn: best.endColumn,
+                anchoredText: best.text,
+                previousSelectedText: selectedText,
+                reason: `High-confidence fuzzy match (score ${best.score.toFixed(3)}).`,
+            };
+        }
+    }
+    if (comment.line != null) {
+        const lineIdx = comment.line;
+        if (lineIdx > 0 && lineIdx < documentLines.length) {
+            const qualifier = opts.commitIsStale
+                ? " (commit is stale — line may have shifted)"
+                : "";
+            if (selectedText) {
+                const lineText = documentLines[lineIdx];
+                const candidates = fuzzySearch(["", lineText], selectedText, DEFAULT_THRESHOLD);
+                if (candidates.length > 0) {
+                    return {
+                        commentId,
+                        status: "fuzzy",
+                        score: candidates[0].score,
+                        newLine: comment.line,
+                        newEndLine: comment.end_line,
+                        anchoredText: candidates[0].text,
+                        previousSelectedText: selectedText,
+                        reason: `Line-fallback with fuzzy text match (score ${candidates[0].score.toFixed(3)})${qualifier}.`,
+                    };
+                }
+            }
+            const isLineOnly = !selectedText;
+            return {
+                commentId,
+                status: isLineOnly ? "anchored" : (opts.commitIsStale ? "ambiguous" : "anchored"),
+                score: isLineOnly ? 1.0 : (opts.commitIsStale ? 0.5 : 0.8),
+                newLine: comment.line,
+                newEndLine: comment.end_line,
+                reason: isLineOnly
+                    ? "Line-only comment (no selected_text to verify)."
+                    : `Line/column fallback${qualifier}.`,
+            };
+        }
+    }
+    if (selectedText) {
+        const lowCandidates = fuzzySearch(documentLines, selectedText, threshold, comment.line);
+        if (lowCandidates.length === 1) {
+            const candidate = lowCandidates[0];
+            return {
+                commentId,
+                status: "fuzzy",
+                score: candidate.score,
+                newLine: candidate.line,
+                newEndLine: candidate.endLine,
+                newStartColumn: candidate.startColumn,
+                newEndColumn: candidate.endColumn,
+                anchoredText: candidate.text,
+                previousSelectedText: selectedText,
+                reason: `Low-threshold fuzzy match (score ${candidate.score.toFixed(3)}).`,
+            };
+        }
+        if (lowCandidates.length > 1) {
+            const best = lowCandidates[0];
+            return {
+                commentId,
+                status: "ambiguous",
+                score: best.score,
+                newLine: best.line,
+                newEndLine: best.endLine,
+                reason: `Ambiguous: ${lowCandidates.length} fuzzy matches (best score ${best.score.toFixed(3)}).`,
+            };
+        }
+    }
+    return {
+        commentId,
+        status: "orphaned",
+        score: 0,
+        reason: "No match found. Comment is orphaned.",
+    };
+}
+export function reanchorDocumentLines(doc, documentLines, opts = {}) {
+    return doc.comments.map((comment) => reanchorComment(comment, documentLines, opts));
+}
+export function reanchorDocumentText(doc, documentText, opts = {}) {
+    return reanchorDocumentLines(doc, toReanchorLines(documentText), opts);
+}
+export function applyReanchorResults(doc, results, opts = {}) {
+    let changed = 0;
+    const resultMap = new Map(results.map((result) => [result.commentId, result]));
+    for (const comment of doc.comments) {
+        const result = resultMap.get(comment.id);
+        if (!result)
+            continue;
+        let isChanged = false;
+        if (result.newLine != null && result.newLine !== comment.line) {
+            comment.line = result.newLine;
+            isChanged = true;
+        }
+        if (result.newEndLine != null && result.newEndLine !== comment.end_line) {
+            comment.end_line = result.newEndLine;
+            isChanged = true;
+        }
+        if (result.newStartColumn != null && result.newStartColumn !== comment.start_column) {
+            comment.start_column = result.newStartColumn;
+            isChanged = true;
+        }
+        if (result.newEndColumn != null && result.newEndColumn !== comment.end_column) {
+            comment.end_column = result.newEndColumn;
+            isChanged = true;
+        }
+        if (result.anchoredText != null && result.anchoredText !== comment.selected_text) {
+            if (opts.updateText) {
+                comment.selected_text = result.anchoredText;
+                delete comment.anchored_text;
+            }
+            else {
+                comment.anchored_text = result.anchoredText;
+            }
+            isChanged = true;
+        }
+        else if (result.anchoredText != null && result.anchoredText === comment.selected_text) {
+            if (comment.anchored_text) {
+                delete comment.anchored_text;
+                isChanged = true;
+            }
+        }
+        if (isChanged || result.status !== "anchored") {
+            comment.x_reanchor_status = result.status;
+            comment.x_reanchor_score = result.score;
+        }
+        if (opts.force
+            && opts.headCommit
+            && (result.status === "anchored" || result.status === "shifted")
+            && result.score >= HIGH_THRESHOLD) {
+            comment.commit = opts.headCommit;
+            delete comment.x_reanchor_status;
+            delete comment.x_reanchor_score;
+            if (comment.anchored_text && comment.anchored_text === comment.selected_text) {
+                delete comment.anchored_text;
+            }
+            isChanged = true;
+        }
+        if (isChanged) {
+            changed += 1;
+        }
+    }
+    return changed;
+}
+function extractText(lines, line, endLine, startColumn, endColumn) {
+    const startIdx = line;
+    const endIdx = endLine ?? line;
+    if (startIdx < 1 || endIdx >= lines.length)
+        return null;
+    if (startIdx === endIdx) {
+        const text = lines[startIdx];
+        if (startColumn != null && endColumn != null) {
+            return text.slice(startColumn, endColumn);
+        }
+        return text;
+    }
+    const result = [];
+    for (let index = startIdx; index <= endIdx; index += 1) {
+        let currentLine = lines[index];
+        if (index === startIdx && startColumn != null)
+            currentLine = currentLine.slice(startColumn);
+        if (index === endIdx && endColumn != null)
+            currentLine = currentLine.slice(0, endColumn);
+        result.push(currentLine);
+    }
+    return result.join("\n");
+}
+function closestToLine(candidates, targetLine) {
+    return candidates.reduce((best, candidate) => Math.abs(candidate.line - targetLine) < Math.abs(best.line - targetLine) ? candidate : best);
+}
+function getLineShift(diffHunks, line) {
+    let shift = 0;
+    let modified = false;
+    for (const hunk of diffHunks) {
+        const oldStart = hunk.oldStart;
+        const oldEnd = hunk.oldStart + Math.max(hunk.oldCount, 1) - 1;
+        if (line >= oldStart && line <= oldEnd && hunk.oldCount > 0) {
+            modified = true;
+        }
+        if (line > oldEnd || (hunk.oldCount === 0 && line >= oldStart)) {
+            shift += hunk.newCount - hunk.oldCount;
+        }
+    }
+    return { shift, modified };
+}
+//# sourceMappingURL=reanchor-core.js.map

package/dist/lib/reanchor.d.ts

@@ -11,15 +11,8 @@
  *   Step 3  – lower-threshold fuzzy ≥ configured threshold (0.6)
  *   Step 4  – orphan
  */
-import type { Comment, MrsfDocument, ReanchorOptions, ReanchorResult, DiffHunk } from "./types.js";
-/**
- * Re-anchor a single comment against the current document lines.
- */
-export declare function reanchorComment(comment: Comment, documentLines: string[], opts?: {
-    diffHunks?: DiffHunk[];
-    threshold?: number;
-    commitIsStale?: boolean;
-}): ReanchorResult;
+import type { MrsfDocument, ReanchorOptions, ReanchorResult } from "./types.js";
+export { applyReanchorResults, DEFAULT_THRESHOLD, HIGH_THRESHOLD, reanchorComment, reanchorDocumentLines, reanchorDocumentText, toReanchorLines, } from "./reanchor-core.js";
 /**
  * Re-anchor all comments in an MRSF document.
  */
@@ -27,15 +20,6 @@ export declare function reanchorDocument(doc: MrsfDocument, documentLines: strin
     documentPath?: string;
     repoRoot?: string;
 }): Promise<ReanchorResult[]>;
-/**
- * Apply re-anchor results to the document's comments.
- * Mutates the document in place and returns the number of changed comments.
- */
-export declare function applyReanchorResults(doc: MrsfDocument, results: ReanchorResult[], opts?: {
-    updateText?: boolean;
-    force?: boolean;
-    headCommit?: string;
-}): number;
 /**
  * High-level re-anchor for a single sidecar file path.
  */

package/dist/lib/reanchor.js

@@ -11,236 +11,17 @@
  *   Step 3  – lower-threshold fuzzy ≥ configured threshold (0.6)
  *   Step 4  – orphan
  */
-import { findRepoRoot, getCurrentCommit, getDiff, getLineShift, isGitAvailable, } from "./git.js";
-import { exactMatch, fuzzySearch, normalizedMatch, } from "./fuzzy.js";
+import { findRepoRoot, getCurrentCommit, getDiff, isGitAvailable, } from "./git.js";
+import { applyReanchorResults, DEFAULT_THRESHOLD, reanchorComment, reanchorDocumentLines, } from "./reanchor-core.js";
 import { readDocumentLines } from "./parser.js";
 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";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
-const HIGH_THRESHOLD = 0.8;
-const DEFAULT_THRESHOLD = 0.6;
-// ---------------------------------------------------------------------------
-// Single comment re-anchoring
-// ---------------------------------------------------------------------------
-/**
- * Re-anchor a single comment against the current document lines.
- */
-export function reanchorComment(comment, documentLines, opts = {}) {
-    const threshold = opts.threshold ?? DEFAULT_THRESHOLD;
-    const commentId = comment.id;
-    const selectedText = comment.selected_text;
-    // No selected_text and no line — nothing to anchor
-    if (!selectedText && comment.line == null) {
-        return {
-            commentId,
-            status: "anchored",
-            score: 1.0,
-            reason: "Document-level comment (no anchor needed).",
-        };
-    }
-    // -----------------------------------------------------------------------
-    // Step 0: Diff-based shift
-    // -----------------------------------------------------------------------
-    if (comment.line != null && opts.diffHunks?.length) {
-        const { shift, modified } = getLineShift(opts.diffHunks, comment.line);
-        // For line-only comments (no selected_text), apply the diff shift directly
-        if (!selectedText) {
-            const shiftedLine = comment.line + shift;
-            const lineSpan = comment.end_line != null ? comment.end_line - comment.line : 0;
-            const shiftedEndLine = comment.end_line != null ? shiftedLine + lineSpan : undefined;
-            return {
-                commentId,
-                status: shift === 0 ? "anchored" : "shifted",
-                score: 1.0,
-                newLine: shiftedLine,
-                newEndLine: shiftedEndLine,
-                reason: shift === 0
-                    ? "Line-only comment unchanged (diff confirms position)."
-                    : `Line-only comment shifted by ${shift > 0 ? "+" : ""}${shift} line(s) via diff.`,
-            };
-        }
-        if (!modified) {
-            const shiftedLine = comment.line + shift;
-            const lineSpan = comment.end_line != null ? comment.end_line - comment.line : 0;
-            const shiftedEndLine = comment.end_line != null ? shiftedLine + lineSpan : undefined;
-            // Verify the selected text still matches at the shifted position
-            const textAtShifted = extractText(documentLines, shiftedLine, shiftedEndLine, comment.start_column, comment.end_column);
-            if (textAtShifted === selectedText) {
-                return {
-                    commentId,
-                    status: shift === 0 ? "anchored" : "shifted",
-                    score: 1.0,
-                    newLine: shiftedLine,
-                    newEndLine: shiftedEndLine,
-                    reason: shift === 0
-                        ? "Diff confirms text unchanged at original position."
-                        : `Diff shifted by ${shift > 0 ? "+" : ""}${shift} line(s).`,
-                };
-            }
-        }
-        // Fall through — line was modified or text doesn't match after shift
-    }
-    // -----------------------------------------------------------------------
-    // Step 1: Exact text match
-    // -----------------------------------------------------------------------
-    if (selectedText) {
-        const exactCandidates = exactMatch(documentLines, selectedText);
-        if (exactCandidates.length === 1) {
-            const c = exactCandidates[0];
-            return {
-                commentId,
-                status: "anchored",
-                score: 1.0,
-                newLine: c.line,
-                newEndLine: c.endLine,
-                newStartColumn: c.startColumn,
-                newEndColumn: c.endColumn,
-                reason: "Exact text match (unique).",
-            };
-        }
-        if (exactCandidates.length > 1 && comment.line != null) {
-            // Disambiguate by proximity to original line
-            const best = closestToLine(exactCandidates, comment.line);
-            return {
-                commentId,
-                status: "anchored",
-                score: 1.0,
-                newLine: best.line,
-                newEndLine: best.endLine,
-                newStartColumn: best.startColumn,
-                newEndColumn: best.endColumn,
-                reason: `Exact text match (${exactCandidates.length} occurrences; chose nearest to original line ${comment.line}).`,
-            };
-        }
-        // -----------------------------------------------------------------------
-        // Step 1.5: Normalized + high-threshold fuzzy match
-        // -----------------------------------------------------------------------
-        // Try whitespace-normalized match first
-        const normCandidates = normalizedMatch(documentLines, selectedText);
-        if (normCandidates.length === 1) {
-            const c = normCandidates[0];
-            return {
-                commentId,
-                status: "fuzzy",
-                score: c.score,
-                newLine: c.line,
-                newEndLine: c.endLine,
-                newStartColumn: c.startColumn,
-                newEndColumn: c.endColumn,
-                anchoredText: c.text,
-                previousSelectedText: selectedText,
-                reason: "Normalized whitespace match.",
-            };
-        }
-        // High threshold fuzzy
-        const fuzzyCandidates = fuzzySearch(documentLines, selectedText, HIGH_THRESHOLD, comment.line);
-        if (fuzzyCandidates.length === 1 || (fuzzyCandidates.length > 0 && fuzzyCandidates[0].score >= HIGH_THRESHOLD)) {
-            const best = fuzzyCandidates.length === 1
-                ? fuzzyCandidates[0]
-                : closestToLine(fuzzyCandidates, comment.line ?? 1);
-            return {
-                commentId,
-                status: "fuzzy",
-                score: best.score,
-                newLine: best.line,
-                newEndLine: best.endLine,
-                newStartColumn: best.startColumn,
-                newEndColumn: best.endColumn,
-                anchoredText: best.text,
-                previousSelectedText: selectedText,
-                reason: `High-confidence fuzzy match (score ${best.score.toFixed(3)}).`,
-            };
-        }
-    }
-    // -----------------------------------------------------------------------
-    // Step 2: Line/column fallback
-    // -----------------------------------------------------------------------
-    if (comment.line != null) {
-        const lineIdx = comment.line - 1;
-        if (lineIdx >= 0 && lineIdx < documentLines.length) {
-            const qualifier = opts.commitIsStale
-                ? " (commit is stale — line may have shifted)"
-                : "";
-            // If we have selected_text, check if current line text is a decent fuzzy match
-            if (selectedText) {
-                const lineText = documentLines[lineIdx];
-                const candidates = fuzzySearch([lineText], selectedText, DEFAULT_THRESHOLD);
-                if (candidates.length > 0) {
-                    return {
-                        commentId,
-                        status: "fuzzy",
-                        score: candidates[0].score,
-                        newLine: comment.line,
-                        newEndLine: comment.end_line,
-                        anchoredText: candidates[0].text,
-                        previousSelectedText: selectedText,
-                        reason: `Line-fallback with fuzzy text match (score ${candidates[0].score.toFixed(3)})${qualifier}.`,
-                    };
-                }
-            }
-            // Pure line fallback
-            // If there's no selected_text, the comment is purely line-anchored.
-            // A commit change alone doesn't make it ambiguous — we accept it as-is.
-            const isLineOnly = !selectedText;
-            return {
-                commentId,
-                status: isLineOnly ? "anchored" : (opts.commitIsStale ? "ambiguous" : "anchored"),
-                score: isLineOnly ? 1.0 : (opts.commitIsStale ? 0.5 : 0.8),
-                newLine: comment.line,
-                newEndLine: comment.end_line,
-                reason: isLineOnly
-                    ? "Line-only comment (no selected_text to verify)."
-                    : `Line/column fallback${qualifier}.`,
-            };
-        }
-    }
-    // -----------------------------------------------------------------------
-    // Step 3: Lower-threshold fuzzy search
-    // -----------------------------------------------------------------------
-    if (selectedText) {
-        const lowCandidates = fuzzySearch(documentLines, selectedText, threshold, comment.line);
-        if (lowCandidates.length === 1) {
-            const c = lowCandidates[0];
-            return {
-                commentId,
-                status: "fuzzy",
-                score: c.score,
-                newLine: c.line,
-                newEndLine: c.endLine,
-                newStartColumn: c.startColumn,
-                newEndColumn: c.endColumn,
-                anchoredText: c.text,
-                previousSelectedText: selectedText,
-                reason: `Low-threshold fuzzy match (score ${c.score.toFixed(3)}).`,
-            };
-        }
-        if (lowCandidates.length > 1) {
-            // Ambiguous — multiple low-confidence matches
-            const best = lowCandidates[0];
-            return {
-                commentId,
-                status: "ambiguous",
-                score: best.score,
-                newLine: best.line,
-                newEndLine: best.endLine,
-                reason: `Ambiguous: ${lowCandidates.length} fuzzy matches (best score ${best.score.toFixed(3)}).`,
-            };
-        }
-    }
-    // -----------------------------------------------------------------------
-    // Step 4: Orphan
-    // -----------------------------------------------------------------------
-    return {
-        commentId,
-        status: "orphaned",
-        score: 0,
-        reason: "No match found. Comment is orphaned.",
-    };
-}
 // ---------------------------------------------------------------------------
 // Batch re-anchoring
 // ---------------------------------------------------------------------------
@@ -280,87 +61,7 @@ export async function reanchorDocument(doc, documentLines, opts = {}) {
             return results;
         }
     }
-    // No git — pure text-based re-anchoring
-    for (const comment of doc.comments) {
-        results.push(reanchorComment(comment, documentLines, { threshold }));
-    }
-    return results;
-}
-/**
- * Apply re-anchor results to the document's comments.
- * Mutates the document in place and returns the number of changed comments.
- */
-export function applyReanchorResults(doc, results, opts = {}) {
-    let changed = 0;
-    const resultMap = new Map(results.map((r) => [r.commentId, r]));
-    for (const comment of doc.comments) {
-        const result = resultMap.get(comment.id);
-        if (!result)
-            continue;
-        let isChanged = false;
-        if (result.newLine != null && result.newLine !== comment.line) {
-            comment.line = result.newLine;
-            isChanged = true;
-        }
-        if (result.newEndLine != null && result.newEndLine !== comment.end_line) {
-            comment.end_line = result.newEndLine;
-            isChanged = true;
-        }
-        if (result.newStartColumn != null && result.newStartColumn !== comment.start_column) {
-            comment.start_column = result.newStartColumn;
-            isChanged = true;
-        }
-        if (result.newEndColumn != null && result.newEndColumn !== comment.end_column) {
-            comment.end_column = result.newEndColumn;
-            isChanged = true;
-        }
-        // Handle anchored_text / selected_text per §6.2 & §7.4 Step 3a.
-        // By default, selected_text is preserved (SHOULD NOT modify).
-        // anchored_text records the text currently at the resolved position.
-        if (result.anchoredText != null && result.anchoredText !== comment.selected_text) {
-            if (opts.updateText) {
-                // Opt-in: replace selected_text and clear anchored_text
-                comment.selected_text = result.anchoredText;
-                delete comment.anchored_text;
-            }
-            else {
-                // Default: preserve selected_text, record current text in anchored_text
-                comment.anchored_text = result.anchoredText;
-            }
-            isChanged = true;
-        }
-        else if (result.anchoredText != null && result.anchoredText === comment.selected_text) {
-            // Text matches exactly — clear any stale anchored_text
-            if (comment.anchored_text) {
-                delete comment.anchored_text;
-                isChanged = true;
-            }
-        }
-        // Audit fields (x_ extension prefix per §10)
-        if (isChanged || result.status !== "anchored") {
-            comment.x_reanchor_status = result.status;
-            comment.x_reanchor_score = result.score;
-        }
-        // --force: firmly anchor high-confidence results
-        // Update commit to HEAD and clear audit fields so the comment
-        // won't be re-evaluated on the next reanchor run.
-        if (opts.force &&
-            opts.headCommit &&
-            (result.status === "anchored" || result.status === "shifted") &&
-            result.score >= HIGH_THRESHOLD) {
-            comment.commit = opts.headCommit;
-            delete comment.x_reanchor_status;
-            delete comment.x_reanchor_score;
-            // Clear stale anchored_text since anchor is now confirmed
-            if (comment.anchored_text && comment.anchored_text === comment.selected_text) {
-                delete comment.anchored_text;
-            }
-            isChanged = true;
-        }
-        if (isChanged)
-            changed++;
-    }
-    return changed;
+    return reanchorDocumentLines(doc, documentLines, { threshold });
 }
 /**
  * High-level re-anchor for a single sidecar file path.
@@ -394,38 +95,4 @@ export async function reanchorFile(sidecarPath, opts = {}) {
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-/**
- * Extract text from document lines at the given position.
- * Lines array is 1-based (index 0 is unused), so lines[line] is the content.
- */
-function extractText(lines, line, endLine, startColumn, endColumn) {
-    const startIdx = line; // 1-based array: lines[1] = first line
-    const endIdx = endLine ?? line;
-    if (startIdx < 1 || endIdx >= lines.length)
-        return null;
-    if (startIdx === endIdx) {
-        const text = lines[startIdx];
-        if (startColumn != null && endColumn != null) {
-            return text.slice(startColumn, endColumn);
-        }
-        return text;
-    }
-    // Multi-line
-    const result = [];
-    for (let i = startIdx; i <= endIdx; i++) {
-        let l = lines[i];
-        if (i === startIdx && startColumn != null)
-            l = l.slice(startColumn);
-        if (i === endIdx && endColumn != null)
-            l = l.slice(0, endColumn);
-        result.push(l);
-    }
-    return result.join("\n");
-}
-/**
- * Pick the candidate closest to a hint line.
- */
-function closestToLine(candidates, targetLine) {
-    return candidates.reduce((best, c) => Math.abs(c.line - targetLine) < Math.abs(best.line - targetLine) ? c : best);
-}
 //# sourceMappingURL=reanchor.js.map

package/dist/lib/types.d.ts

@@ -30,6 +30,10 @@ export interface Comment {
     /** Catch-all for unknown / x_-prefixed extension fields. */
     [key: string]: unknown;
 }
+export type CommentExtensionValue = null | boolean | number | string | CommentExtensionValue[] | {
+    [key: string]: CommentExtensionValue;
+};
+export type CommentExtensions = Record<`x_${string}`, CommentExtensionValue>;
 export interface MrsfConfig {
     sidecar_root?: string;
 }
@@ -106,6 +110,8 @@ export interface AddCommentOptions {
     id?: string;
     /** Override auto-generated timestamp. */
     timestamp?: string;
+    /** Tool-specific extension fields keyed by x_*. */
+    extensions?: CommentExtensions;
 }
 export interface CommentFilter {
     open?: boolean;

package/dist/lib/writer.js

@@ -150,6 +150,16 @@ function valueToSource(v) {
 function valueType(v) {
     return valueToSource(v).startsWith('"') ? "double-quoted-scalar" : "scalar";
 }
+function isStructuredValue(value) {
+    if (value == null)
+        return false;
+    if (Array.isArray(value))
+        return true;
+    return typeof value === "object" && !(value instanceof Date);
+}
+function hasStructuredCommentExtensions(doc) {
+    return doc.comments.some((comment) => Object.entries(comment).some(([key, value]) => !COMMENT_KEY_ORDER.includes(key) && value !== undefined && isStructuredValue(value)));
+}
 /* ·· CST node construction ············································ */
 const NL = "\n";
 /**
@@ -351,17 +361,21 @@ export async function writeSidecar(filePath, doc) {
  */
 async function writeSidecarInternal(abs, doc) {
     const isJson = abs.endsWith(".review.json");
+    for (const comment of doc.comments)
+        syncHash(comment);
     if (isJson) {
-        // For JSON, always sync hashes and write fresh
-        for (const comment of doc.comments)
-            syncHash(comment);
+        // For JSON, always write fresh
         await atomicWriteFile(abs, toJson(doc));
         return;
     }
+    // The CST patcher only supports scalar map values. Fall back to full YAML
+    // serialisation when comment extensions include arrays or objects.
+    if (hasStructuredCommentExtensions(doc)) {
+        await atomicWriteFile(abs, toYaml(doc));
+        return;
+    }
     // ── YAML round-trip path ──────────────────────────────────────────
     if (!existsSync(abs)) {
-        for (const comment of doc.comments)
-            syncHash(comment);
         await atomicWriteFile(abs, toYaml(doc));
         return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrsf/cli",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "CLI and library for the Markdown Review Sidecar Format (MRSF)",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,6 +9,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./browser": {
+      "import": "./dist/browser.js",
+      "types": "./dist/browser.d.ts"
     }
   },
   "bin": {
@@ -72,8 +76,8 @@
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.13.10",
     "@types/uuid": "^10.0.0",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/coverage-v8": "^4.0.18",
     "typescript": "^5.8.2",
-    "vitest": "^3.0.9"
+    "vitest": "^4.0.18"
   }
 }