@mrsf/cli 0.2.1 → 0.2.3

package/README.md

@@ -242,6 +242,48 @@ mrsf rename docs/old-name.md docs/new-name.md
 
 Updates the `document` field inside the sidecar, writes it to the new path, and removes the old sidecar file.
 
+### `mrsf watch [files...]`
+
+Watch files for changes and continuously validate (and optionally reanchor).
+
+```bash
+# Validate all sidecars on every change
+mrsf watch
+
+# Watch specific files
+mrsf watch docs/api.md docs/guide.md
+
+# Auto-reanchor when Markdown files change
+mrsf watch --reanchor
+
+# Preview reanchor changes without writing
+mrsf watch --reanchor --dry-run
+
+# Custom threshold and strict validation
+mrsf watch --reanchor --threshold 0.8 --strict
+```
+
+**Trigger rules** (avoids feedback loops):
+
+| File type | Action |
+|---|---|
+| `.md` (Markdown) | Reanchor (if `--reanchor` is set), then validate sidecar |
+| `.review.yaml` / `.review.json` | Validate only |
+
+| Option | Description |
+|---|---|
+| `--reanchor` | Auto-reanchor when Markdown files change |
+| `-n, --dry-run` | Preview reanchor changes without writing |
+| `-t, --threshold <n>` | Fuzzy match threshold 0.0–1.0 (default `0.6`) |
+| `-s, --strict` | Treat validation warnings as errors |
+| `--no-git` | Disable git integration |
+| `--from <commit>` | Override from-commit for reanchor |
+| `--update-text` | Update `selected_text` on reanchor |
+| `-f, --force` | Force reanchor — update commit, clear audit fields |
+| `--debounce <ms>` | Debounce interval in ms (default `300`) |
+
+Press `Ctrl+C` to stop — a summary of events, reanchors, and errors is printed.
+
 ## Global Options
 
 These apply to all commands:

package/dist/bin.js

@@ -17,6 +17,7 @@ import { registerList } from "./commands/list.js";
 import { registerInit } from "./commands/init.js";
 import { registerStatus } from "./commands/status.js";
 import { registerRename } from "./commands/rename.js";
+import { registerWatch } from "./commands/watch.js";
 /* ── Banner ────────────────────────────────────────────────────────── */
 /**
  * Detect CI/CD or non-interactive environments where the banner should
@@ -73,5 +74,6 @@ registerList(program);
 registerInit(program);
 registerStatus(program);
 registerRename(program);
+registerWatch(program);
 program.parse();
 //# sourceMappingURL=bin.js.map

package/dist/commands/watch.d.ts

@@ -0,0 +1,24 @@
+/**
+ * mrsf watch — Monitor files and validate / reanchor on change.
+ *
+ * By default, validation is run on every change.  Pass `--reanchor` to
+ * also auto-fix drifted anchors when a Markdown file is saved.
+ *
+ * Trigger rules (avoids feedback loops):
+ *   - `.md` change       → reanchor (if enabled), then validate sidecar
+ *   - `.review.yaml/json` change → validate only
+ */
+import type { Command } from "commander";
+export interface WatchOptions {
+    reanchor?: boolean;
+    dryRun?: boolean;
+    threshold: string;
+    git: boolean;
+    from?: string;
+    updateText?: boolean;
+    force?: boolean;
+    strict?: boolean;
+    debounce: string;
+}
+export declare function registerWatch(program: Command): void;
+//# sourceMappingURL=watch.d.ts.map

package/dist/commands/watch.js

@@ -0,0 +1,277 @@
+/**
+ * mrsf watch — Monitor files and validate / reanchor on change.
+ *
+ * By default, validation is run on every change.  Pass `--reanchor` to
+ * also auto-fix drifted anchors when a Markdown file is saved.
+ *
+ * Trigger rules (avoids feedback loops):
+ *   - `.md` change       → reanchor (if enabled), then validate sidecar
+ *   - `.review.yaml/json` change → validate only
+ */
+import path from "node:path";
+import chalk from "chalk";
+import { watch as chokidarWatch } from "chokidar";
+import { findWorkspaceRoot, discoverSidecar, sidecarToDocument, } from "../lib/discovery.js";
+import { resolveSidecarPaths } from "../lib/resolve-files.js";
+import { validateFile } from "../lib/validator.js";
+import { reanchorFile } from "../lib/reanchor.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const SIDECAR_EXTS = [".review.yaml", ".review.json"];
+function isSidecar(file) {
+    return SIDECAR_EXTS.some((ext) => file.endsWith(ext));
+}
+function timestamp() {
+    return new Date().toLocaleTimeString("en-GB", { hour12: false });
+}
+function statusIcon(status) {
+    switch (status) {
+        case "anchored":
+            return chalk.green("●");
+        case "shifted":
+            return chalk.blue("↕");
+        case "fuzzy":
+            return chalk.yellow("≈");
+        case "ambiguous":
+            return chalk.magenta("?");
+        case "orphaned":
+            return chalk.red("✗");
+        default:
+            return "·";
+    }
+}
+function printReanchorResults(label, results, changed, written, dryRun, verbose) {
+    const prefix = dryRun ? chalk.dim("[dry-run] ") : "";
+    console.log(`  ${prefix}${chalk.cyan("reanchor")} ${label}`);
+    for (const r of results) {
+        const icon = statusIcon(r.status);
+        const line = r.newLine != null ? `:${r.newLine}` : "";
+        console.log(`    ${icon} ${r.commentId}${line} — ${r.reason}`);
+        if (verbose && r.score != null) {
+            console.log(`        score: ${r.score.toFixed(3)}`);
+        }
+    }
+    if (!dryRun && written) {
+        console.log(`  ${chalk.green("✓")} ${changed} comment(s) updated`);
+    }
+    else if (dryRun) {
+        console.log(`  ${chalk.dim(`${changed} comment(s) would change`)}`);
+    }
+}
+function printValidateResults(label, result, strict) {
+    const effectiveValid = strict
+        ? result.valid && result.warnings.length === 0
+        : result.valid;
+    const icon = effectiveValid ? chalk.green("✓") : chalk.red("✗");
+    console.log(`  ${chalk.cyan("validate")} ${icon} ${label}`);
+    for (const e of result.errors) {
+        console.log(chalk.red(`    error: ${e.message}${e.path ? ` (${e.path})` : ""}`));
+    }
+    for (const w of result.warnings) {
+        const fn = strict ? chalk.red : chalk.yellow;
+        const tag = strict ? "error" : "warn";
+        console.log(fn(`    ${tag}: ${w.message}${w.path ? ` (${w.path})` : ""}`));
+    }
+}
+export function registerWatch(program) {
+    program
+        .command("watch [files...]")
+        .description("Watch files for changes and validate (+ optionally reanchor)")
+        .option("--reanchor", "Auto-reanchor when Markdown files change")
+        .option("-n, --dry-run", "Preview reanchor changes without writing")
+        .option("-t, --threshold <n>", "Fuzzy match threshold 0.0–1.0", "0.6")
+        .option("-s, --strict", "Treat validation warnings as errors")
+        .option("--no-git", "Disable git integration")
+        .option("--from <commit>", "Override from-commit for reanchor")
+        .option("--update-text", "Update selected_text on reanchor")
+        .option("-f, --force", "Force reanchor — update commit, clear audit fields")
+        .option("--debounce <ms>", "Debounce interval in ms", "300")
+        .action(async (files, opts) => {
+        const parentOpts = program.opts();
+        const cwd = parentOpts.cwd ?? process.cwd();
+        const quiet = parentOpts.quiet ?? false;
+        const verbose = parentOpts.verbose ?? false;
+        const debounceMs = parseInt(opts.debounce, 10) || 300;
+        const threshold = parseFloat(opts.threshold);
+        const noGit = !opts.git;
+        // ── Resolve watch targets ────────────────────────────
+        let watchPaths;
+        if (files.length === 0) {
+            // Watch the whole workspace
+            const root = findWorkspaceRoot(cwd) ?? cwd;
+            watchPaths = [root];
+        }
+        else {
+            // Resolve explicit paths — collect both sidecars and documents
+            const sidecarPaths = await resolveSidecarPaths(files, cwd);
+            const docPaths = sidecarPaths.map((sp) => sidecarToDocument(sp));
+            watchPaths = [...new Set([...sidecarPaths, ...docPaths])];
+        }
+        // ── Start watcher ────────────────────────────────────
+        const watcher = chokidarWatch(watchPaths, {
+            ignoreInitial: true,
+            ignored: [
+                "**/node_modules/**",
+                "**/.git/**",
+                ...(files.length === 0
+                    ? []
+                    : [
+                    // When watching specific files, chokidar might get
+                    // extra events from parent dirs — no extra ignores needed.
+                    ]),
+            ],
+            // Only watch files matching our extensions when watching a dir
+            ...(files.length === 0
+                ? {}
+                : {}),
+        });
+        // Track debounce per file
+        const timers = new Map();
+        // Track files we just wrote (to skip re-trigger)
+        const selfWrites = new Set();
+        // Stats
+        let totalEvents = 0;
+        let totalErrors = 0;
+        let totalReanchors = 0;
+        // ── Event handler ────────────────────────────────────
+        async function handleChange(filePath) {
+            const abs = path.resolve(filePath);
+            const rel = path.relative(cwd, abs);
+            // Skip files we just wrote ourselves
+            if (selfWrites.has(abs)) {
+                selfWrites.delete(abs);
+                return;
+            }
+            // Only process markdown and sidecar files
+            const isSidecarFile = isSidecar(abs);
+            const isMarkdown = abs.endsWith(".md");
+            if (!isSidecarFile && !isMarkdown)
+                return;
+            totalEvents++;
+            if (!quiet) {
+                console.log(`\n${chalk.dim(`[${timestamp()}]`)} ${chalk.bold(rel)}`);
+            }
+            if (isSidecarFile) {
+                // ── Sidecar changed → validate ──────────────────
+                await runValidate(abs, rel);
+            }
+            else if (isMarkdown) {
+                // ── Markdown changed → reanchor (opt-in) + validate sidecar ──
+                let sidecarPath;
+                try {
+                    sidecarPath = await discoverSidecar(abs, { cwd });
+                }
+                catch {
+                    // No sidecar for this markdown file — skip silently
+                    if (verbose) {
+                        console.log(chalk.dim(`  no sidecar found — skipping`));
+                    }
+                    return;
+                }
+                if (opts.reanchor) {
+                    await runReanchor(sidecarPath, rel);
+                }
+                // Validate the sidecar in all modes
+                await runValidate(sidecarPath, path.relative(cwd, sidecarPath));
+            }
+        }
+        async function runValidate(sidecarPath, label) {
+            try {
+                const result = await validateFile(sidecarPath);
+                const effectiveValid = opts.strict
+                    ? result.valid && result.warnings.length === 0
+                    : result.valid;
+                if (!effectiveValid)
+                    totalErrors++;
+                if (!quiet || !effectiveValid) {
+                    printValidateResults(label, result, !!opts.strict);
+                }
+            }
+            catch (err) {
+                totalErrors++;
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(chalk.red(`  validate ✗ ${label}: ${msg}`));
+            }
+        }
+        async function runReanchor(sidecarPath, label) {
+            try {
+                const { results, changed, written } = await reanchorFile(sidecarPath, {
+                    cwd,
+                    dryRun: opts.dryRun,
+                    threshold,
+                    noGit,
+                    fromCommit: opts.from,
+                    updateText: opts.updateText,
+                    force: opts.force,
+                });
+                totalReanchors++;
+                if (written) {
+                    // Mark the sidecar as self-written to avoid re-triggering
+                    selfWrites.add(path.resolve(sidecarPath));
+                }
+                const orphaned = results.filter((r) => r.status === "orphaned").length;
+                if (orphaned > 0)
+                    totalErrors++;
+                if (!quiet) {
+                    printReanchorResults(label, results, changed, written, !!opts.dryRun, verbose);
+                }
+            }
+            catch (err) {
+                totalErrors++;
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(chalk.red(`  reanchor ✗ ${label}: ${msg}`));
+            }
+        }
+        // ── Wire events with debounce ────────────────────────
+        function onFileChange(filePath) {
+            const abs = path.resolve(filePath);
+            const existing = timers.get(abs);
+            if (existing)
+                clearTimeout(existing);
+            timers.set(abs, setTimeout(() => {
+                timers.delete(abs);
+                handleChange(abs).catch((err) => {
+                    console.error(chalk.red(`  unexpected error: ${String(err)}`));
+                });
+            }, debounceMs));
+        }
+        watcher.on("change", onFileChange);
+        watcher.on("add", onFileChange);
+        // ── Startup banner ───────────────────────────────────
+        if (!quiet) {
+            const mode = opts.reanchor
+                ? opts.dryRun
+                    ? "validate + reanchor (dry-run)"
+                    : "validate + reanchor"
+                : "validate";
+            const pathDesc = files.length === 0
+                ? "workspace"
+                : `${watchPaths.length} path(s)`;
+            console.log(chalk.green(`Watching ${pathDesc} — mode: ${chalk.bold(mode)}`));
+            console.log(chalk.dim("Press Ctrl+C to stop.\n"));
+        }
+        // ── Graceful shutdown ────────────────────────────────
+        async function shutdown() {
+            // Clear pending debounce timers
+            for (const t of timers.values())
+                clearTimeout(t);
+            timers.clear();
+            await watcher.close();
+            if (!quiet) {
+                console.log(`\n${chalk.dim("──────────────────────────────────────")}`);
+                console.log(`Events processed: ${totalEvents}  |  ` +
+                    `Reanchors: ${totalReanchors}  |  ` +
+                    `Errors: ${totalErrors}`);
+            }
+            process.exit(totalErrors > 0 ? 1 : 0);
+        }
+        process.on("SIGINT", () => void shutdown());
+        process.on("SIGTERM", () => void shutdown());
+        // Keep the process alive
+        await new Promise(() => {
+            // Never resolves — the process runs until interrupted
+        });
+    });
+}
+//# sourceMappingURL=watch.js.map

package/dist/index.d.ts

@@ -14,5 +14,5 @@ export { exactMatch, normalizedMatch, fuzzySearch, combinedScore, } from "./lib/
 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 type { CommentSummary } from "./lib/comments.js";
+export type { CommentSummary, RemoveCommentOptions } from "./lib/comments.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/comments.d.ts

@@ -23,10 +23,23 @@ export declare function resolveComment(doc: MrsfDocument, commentId: string, cas
  * Unresolve a comment by id.
  */
 export declare function unresolveComment(doc: MrsfDocument, commentId: string): boolean;
+export interface RemoveCommentOptions {
+    /**
+     * When true, also delete all direct replies instead of promoting them.
+     * Default: false (promote replies per §9.1).
+     */
+    cascade?: boolean;
+}
 /**
- * Remove a comment by id. Returns true if found and removed.
+ * Remove a comment by id. Per §9.1, direct replies are promoted:
+ * their anchor fields are inherited from the parent (when absent),
+ * and their `reply_to` is re-pointed to the parent's parent (or cleared).
+ *
+ * If `cascade` is true, direct replies are removed along with the parent.
+ *
+ * Returns true if the comment was found and removed.
  */
-export declare function removeComment(doc: MrsfDocument, commentId: string): boolean;
+export declare function removeComment(doc: MrsfDocument, commentId: string, opts?: RemoveCommentOptions): boolean;
 /**
  * Filter comments based on criteria.
  */

package/dist/lib/comments.js

@@ -122,14 +122,58 @@ export function unresolveComment(doc, commentId) {
 // ---------------------------------------------------------------------------
 // Remove
 // ---------------------------------------------------------------------------
+/** Anchor fields that a reply may inherit from its parent on deletion. */
+const ANCHOR_FIELDS = [
+    "line",
+    "end_line",
+    "start_column",
+    "end_column",
+    "selected_text",
+    "selected_text_hash",
+    "anchored_text",
+    "commit",
+];
 /**
- * Remove a comment by id. Returns true if found and removed.
+ * Remove a comment by id. Per §9.1, direct replies are promoted:
+ * their anchor fields are inherited from the parent (when absent),
+ * and their `reply_to` is re-pointed to the parent's parent (or cleared).
+ *
+ * If `cascade` is true, direct replies are removed along with the parent.
+ *
+ * Returns true if the comment was found and removed.
  */
-export function removeComment(doc, commentId) {
-    const idx = doc.comments.findIndex((c) => c.id === commentId);
-    if (idx === -1)
+export function removeComment(doc, commentId, opts) {
+    const comment = doc.comments.find((c) => c.id === commentId);
+    if (!comment)
         return false;
-    doc.comments.splice(idx, 1);
+    if (opts?.cascade) {
+        // Remove direct replies first
+        doc.comments = doc.comments.filter((c) => c.id === commentId || c.reply_to !== commentId);
+    }
+    else {
+        // Promote direct replies (§9.1)
+        for (const c of doc.comments) {
+            if (c.reply_to !== commentId)
+                continue;
+            // Copy missing anchor fields from the parent
+            for (const field of ANCHOR_FIELDS) {
+                if (c[field] == null && comment[field] != null) {
+                    c[field] = comment[field];
+                }
+            }
+            // Re-point reply_to to grandparent (or clear if parent was root)
+            if (comment.reply_to) {
+                c.reply_to = comment.reply_to;
+            }
+            else {
+                delete c.reply_to;
+            }
+        }
+    }
+    // Remove the parent comment itself
+    const idx = doc.comments.findIndex((c) => c.id === commentId);
+    if (idx !== -1)
+        doc.comments.splice(idx, 1);
     return true;
 }
 // ---------------------------------------------------------------------------

package/dist/lib/writer.js

@@ -393,6 +393,45 @@ export async function writeSidecar(filePath, doc) {
         }
     }
     seq.items = newSeqItems;
+    // ── Fix first-item indentation after reorder / removal ────────────
+    //
+    // In the YAML CST, the `comments:` map-entry's `sep` array often
+    // contains trailing whitespace (space tokens) that provide the indent
+    // *before* the first seq-item indicator (`-`).  Non-first seq items
+    // carry their own leading space tokens in `start`.
+    //
+    // When the original first item is removed and a formerly non-first
+    // item becomes the new first, those extra space tokens stack with
+    // the sep whitespace, doubling the indent.  We fix this by stripping
+    // any leading space tokens (before the `seq-item-ind`) from the new
+    // first item's start — the sep already provides that whitespace.
+    //
+    // We also ensure the previous item's value ends with a newline so
+    // subsequent items render on their own line.
+    // ──────────────────────────────────────────────────────────────────
+    if (newSeqItems.length > 0) {
+        const originalFirstIdx = seq.items === newSeqItems ? 0 : -1; // always true after assignment
+        const origFirstItem = existingById.size > 0
+            ? [...existingById.values()].find((e) => e.index === 0)
+            : undefined;
+        const newFirst = newSeqItems[0];
+        // Check if the new first item is NOT the original first item
+        const isOriginalFirst = origFirstItem &&
+            seq.items[0]?.value === origFirstItem.map;
+        if (!isOriginalFirst && newFirst.start) {
+            // Strip leading space tokens before the seq-item-ind
+            const dashIdx = newFirst.start.findIndex((t) => t.type === "seq-item-ind");
+            if (dashIdx > 0) {
+                // Remove all tokens before the dash that are space/newline
+                const toRemove = newFirst.start
+                    .slice(0, dashIdx)
+                    .every((t) => t.type === "space" || t.type === "newline");
+                if (toRemove) {
+                    newFirst.start.splice(0, dashIdx);
+                }
+            }
+        }
+    }
     // ── Stringify via CST (byte-identical for untouched content) ───────
     const result = tokens.map((t) => CST.stringify(t)).join("");
     await writeFile(abs, result, "utf-8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrsf/cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "CLI and library for the Markdown Review Sidecar Format (MRSF)",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,6 +55,7 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "chalk": "^5.4.1",
+    "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "fastest-levenshtein": "^1.0.16",
     "js-yaml": "^4.1.0",