@mrsf/cli 0.2.3 → 0.3.0

package/README.md

@@ -1,6 +1,11 @@
 # MRSF CLI
 
-Command-line tool and Node.js library for the **Markdown Review Sidecar Format** ([MRSF v1.0](../MRSF-v1.0.md)).
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![MRSF v1.0 Draft](https://img.shields.io/badge/MRSF-v1.0%20Draft-blue)](MRSF-v1.0.md)
+[![@mrsf/cli on npm](https://img.shields.io/npm/v/@mrsf/cli?label=%40mrsf%2Fcli)](https://www.npmjs.com/package/@mrsf/cli)
+[![npm downloads (cli)](https://img.shields.io/npm/dm/@mrsf/cli?label=cli%20downloads)](https://www.npmjs.com/package/@mrsf/cli)
+
+Command-line tool and Node.js library for **Sidemark** — the **Markdown Review Sidecar Format** ([MRSF v1.0](../MRSF-v1.0.md)).
 
 Validate sidecars, add and resolve review comments, re-anchor comments after document edits, and integrate MRSF into CI/CD pipelines — all from the terminal.
 
@@ -340,16 +345,18 @@ The CLI is built library-first. All functionality is available as importable fun
 ```typescript
 import {
   parseSidecar,
+  parseSidecarLenient,
   writeSidecar,
   validate,
   reanchorDocument,
   addComment,
   resolveComment,
+  removeComment,
   filterComments,
   summarize,
   discoverSidecar,
   discoverAllSidecars,
-} from "mrsf";
+} from "@mrsf/cli";
 
 // Validate a sidecar programmatically
 const doc = await parseSidecar("docs/api.md.review.yaml");

package/dist/index.d.ts

@@ -7,7 +7,8 @@
 export type { MrsfDocument, Comment, 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, readDocumentLines, } from "./lib/parser.js";
+export { parseSidecar, parseSidecarContent, parseSidecarLenient, parseSidecarContentLenient, readDocumentLines, } from "./lib/parser.js";
+export type { LenientParseResult } from "./lib/parser.js";
 export { computeHash, syncHash, toYaml, toJson, writeSidecar, } from "./lib/writer.js";
 export { validate, validateFile } from "./lib/validator.js";
 export { exactMatch, normalizedMatch, fuzzySearch, combinedScore, } from "./lib/fuzzy.js";

package/dist/index.js

@@ -9,7 +9,7 @@ export { findWorkspaceRoot, loadConfig, discoverSidecar, sidecarToDocument, disc
 // File resolution
 export { resolveSidecarPaths } from "./lib/resolve-files.js";
 // Parsing
-export { parseSidecar, parseSidecarContent, readDocumentLines, } from "./lib/parser.js";
+export { parseSidecar, parseSidecarContent, parseSidecarLenient, parseSidecarContentLenient, readDocumentLines, } from "./lib/parser.js";
 // Writing
 export { computeHash, syncHash, toYaml, toJson, writeSidecar, } from "./lib/writer.js";
 // Validation

package/dist/lib/parser.d.ts

@@ -1,7 +1,16 @@
 /**
  * MRSF Parser — load and parse MRSF sidecar files (YAML or JSON).
  */
-import type { MrsfDocument } from "./types.js";
+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 an MRSF sidecar file from disk.
  */
@@ -11,6 +20,18 @@ export declare function parseSidecar(filePath: string): Promise<MrsfDocument>;
  * Detects JSON vs YAML based on content or optional filename hint.
  */
 export declare function parseSidecarContent(content: string, filenameHint?: string): MrsfDocument;
+/**
+ * Lenient parse: attempts to parse a sidecar file from disk without
+ * throwing.  On complete failure, returns `{ doc: null, error }`.
+ * On success, returns `{ doc }`.  For partially-corrupted YAML (where
+ * the top-level parses but some comments are malformed), attempts to
+ * salvage individual well-formed comments.
+ */
+export declare function parseSidecarLenient(filePath: string): Promise<LenientParseResult>;
+/**
+ * Lenient parse from string content.
+ */
+export declare function parseSidecarContentLenient(content: string, filenameHint?: string): LenientParseResult;
 /**
  * Read a Markdown document from disk and return its lines.
  * Lines are 1-indexed in the returned array (index 0 is unused).

package/dist/lib/parser.js

@@ -43,6 +43,132 @@ export function parseSidecarContent(content, filenameHint) {
     }
     return parsed;
 }
+/**
+ * Lenient parse: attempts to parse a sidecar file from disk without
+ * throwing.  On complete failure, returns `{ doc: null, error }`.
+ * On success, returns `{ doc }`.  For partially-corrupted YAML (where
+ * the top-level parses but some comments are malformed), attempts to
+ * salvage individual well-formed comments.
+ */
+export async function parseSidecarLenient(filePath) {
+    const abs = path.resolve(filePath);
+    let content;
+    try {
+        content = await readFile(abs, "utf-8");
+    }
+    catch (e) {
+        return { doc: null, error: `Cannot read file: ${e.message}` };
+    }
+    return parseSidecarContentLenient(content, abs);
+}
+/**
+ * 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);
+    }
+    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);
+            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,
+    };
+}
 /**
  * Read a Markdown document from disk and return its lines.
  * Lines are 1-indexed in the returned array (index 0 is unused).

package/dist/lib/writer.d.ts

@@ -37,6 +37,9 @@ export declare function toJson(doc: MrsfDocument): string;
  * whitespace byte-for-byte for unchanged content.
  *
  * For new files or JSON, writes from scratch.
+ *
+ * Writes to the same file path are serialized (queued) to prevent race
+ * conditions from concurrent calls.  All writes are atomic (temp + rename).
  */
 export declare function writeSidecar(filePath: string, doc: MrsfDocument): Promise<void>;
 //# sourceMappingURL=writer.d.ts.map

package/dist/lib/writer.js

@@ -10,12 +10,62 @@
  *
  * Auto-computes selected_text_hash when selected_text changes.
  */
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile, writeFile, rename, unlink } from "node:fs/promises";
 import { existsSync } from "node:fs";
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import path from "node:path";
 import { Document, Parser, CST, parse as yamlParse } from "yaml";
 /* ------------------------------------------------------------------ */
+/*  Per-file write serialization                                       */
+/* ------------------------------------------------------------------ */
+/**
+ * Map of absolute file paths to pending write promises.
+ * Ensures that concurrent writes to the same sidecar file are serialized
+ * (queued), preventing race conditions during the read-modify-write cycle.
+ */
+const writeQueue = new Map();
+/**
+ * Enqueue a write operation for the given file path, ensuring only one
+ * write executes at a time per file.
+ */
+function enqueueWrite(abs, fn) {
+    const prev = writeQueue.get(abs) ?? Promise.resolve();
+    const next = prev.then(fn, fn); // run fn even if previous write failed
+    writeQueue.set(abs, next);
+    // Clean up map entry when the queue drains
+    next.then(() => {
+        if (writeQueue.get(abs) === next)
+            writeQueue.delete(abs);
+    }, () => {
+        if (writeQueue.get(abs) === next)
+            writeQueue.delete(abs);
+    });
+    return next;
+}
+/* ------------------------------------------------------------------ */
+/*  Atomic file write                                                  */
+/* ------------------------------------------------------------------ */
+/**
+ * Atomically write content to a file by writing to a temporary file in
+ * the same directory, then renaming.  On POSIX this is atomic; on
+ * Windows it replaces the target.
+ */
+async function atomicWriteFile(filePath, content) {
+    const tmp = filePath + "." + randomBytes(6).toString("hex") + ".tmp";
+    try {
+        await writeFile(tmp, content, "utf-8");
+        await rename(tmp, filePath);
+    }
+    catch (err) {
+        // Clean up temp file on failure
+        try {
+            await unlink(tmp);
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+}
+/* ------------------------------------------------------------------ */
 /*  Hash helpers                                                       */
 /* ------------------------------------------------------------------ */
 /**
@@ -51,22 +101,46 @@ const COMMENT_KEY_ORDER = [
  * Convert a JS value to its YAML source text representation.
  * Strings that require quoting get double-quoted; numbers and booleans
  * are plain scalars.
+ *
+ * Uses an allowlist approach: only strings that consist entirely of
+ * "safe" characters are emitted as bare scalars.  Everything else is
+ * double-quoted via JSON.stringify, which is always valid YAML.
  */
 function valueToSource(v) {
     if (typeof v === "number" || typeof v === "boolean")
         return String(v);
     if (typeof v === "string") {
-        // Strings that need quoting
-        if (/[:\n"{}[\],&#*?|><!%@`]/.test(v) ||
-            v.includes(" #") ||
-            v === "" ||
-            v === "true" ||
-            v === "false" ||
-            v === "null" ||
-            /^\d/.test(v)) {
+        // Empty string must be quoted
+        if (v === "")
+            return JSON.stringify(v);
+        // YAML reserved words / null aliases must be quoted
+        if (v === "true" || v === "false" || v === "null" ||
+            v === "True" || v === "False" || v === "Null" ||
+            v === "TRUE" || v === "FALSE" || v === "NULL" ||
+            v === "yes" || v === "no" || v === "on" || v === "off" ||
+            v === "Yes" || v === "No" || v === "On" || v === "Off" ||
+            v === "YES" || v === "NO" || v === "ON" || v === "OFF" ||
+            v === "~" || v === ".inf" || v === "-.inf" || v === ".nan") {
+            return JSON.stringify(v);
+        }
+        // Strings starting with digits (could be parsed as number) must be quoted
+        if (/^\d/.test(v))
             return JSON.stringify(v);
+        // Allowlist: safe plain scalars consist of word chars, hyphens (not
+        // leading), dots, slashes, spaces (not leading/trailing), parentheses,
+        // and @ — but NO YAML indicators or ambiguous sequences.
+        // A safe string:
+        //   • starts with a letter, underscore
+        //   • contains only [A-Za-z0-9 _./()@+-] (note: hyphen mid-string is OK)
+        //   • does NOT contain " #" (inline comment)
+        //   • does NOT start with "- " or end with ":"
+        //   • has no leading/trailing whitespace
+        //   • contains no newlines or tabs
+        if (/^[A-Za-z_][A-Za-z0-9 _./()\-@+]*$/.test(v) && !v.includes(" #") && !/\s$/.test(v)) {
+            return v;
         }
-        return v;
+        // Everything else: double-quote (JSON.stringify handles escaping)
+        return JSON.stringify(v);
     }
     return String(v);
 }
@@ -262,22 +336,31 @@ export function toJson(doc) {
  * whitespace byte-for-byte for unchanged content.
  *
  * For new files or JSON, writes from scratch.
+ *
+ * Writes to the same file path are serialized (queued) to prevent race
+ * conditions from concurrent calls.  All writes are atomic (temp + rename).
  */
 export async function writeSidecar(filePath, doc) {
     const abs = path.resolve(filePath);
+    return enqueueWrite(abs, () => writeSidecarInternal(abs, doc));
+}
+/**
+ * Internal implementation of writeSidecar (runs inside the per-file queue).
+ */
+async function writeSidecarInternal(abs, doc) {
     const isJson = abs.endsWith(".review.json");
     if (isJson) {
         // For JSON, always sync hashes and write fresh
         for (const comment of doc.comments)
             syncHash(comment);
-        await writeFile(abs, toJson(doc), "utf-8");
+        await atomicWriteFile(abs, toJson(doc));
         return;
     }
     // ── YAML round-trip path ──────────────────────────────────────────
     if (!existsSync(abs)) {
         for (const comment of doc.comments)
             syncHash(comment);
-        await writeFile(abs, toYaml(doc), "utf-8");
+        await atomicWriteFile(abs, toYaml(doc));
         return;
     }
     let raw;
@@ -285,7 +368,7 @@ export async function writeSidecar(filePath, doc) {
         raw = await readFile(abs, "utf-8");
     }
     catch {
-        await writeFile(abs, toYaml(doc), "utf-8");
+        await atomicWriteFile(abs, toYaml(doc));
         return;
     }
     // Parse to CST tokens
@@ -295,7 +378,7 @@ export async function writeSidecar(filePath, doc) {
     }
     catch {
         // Unparseable — write fresh
-        await writeFile(abs, toYaml(doc), "utf-8");
+        await atomicWriteFile(abs, toYaml(doc));
         return;
     }
     // Also parse to plain JS object for value comparison (so we compare
@@ -307,6 +390,13 @@ export async function writeSidecar(filePath, doc) {
     catch {
         // ignore — we'll fall through to source-level comparison
     }
+    // ── Structural validation of parsed YAML ──────────────────────────
+    // If CST parsed OK but the content isn't a valid MrsfDocument shape
+    // (e.g. comments is not an array due to injection), discard and write fresh.
+    if (currentDoc && (!Array.isArray(currentDoc.comments))) {
+        await atomicWriteFile(abs, toYaml(doc));
+        return;
+    }
     // Build lookup of current parsed values by comment id
     const currentById = new Map();
     if (currentDoc?.comments) {
@@ -340,7 +430,7 @@ export async function writeSidecar(filePath, doc) {
     }
     const docToken = findCstDocument(tokens);
     if (!docToken?.value || docToken.value.type !== "block-map") {
-        await writeFile(abs, toYaml(doc), "utf-8");
+        await atomicWriteFile(abs, toYaml(doc));
         return;
     }
     const body = docToken.value;
@@ -357,7 +447,7 @@ export async function writeSidecar(filePath, doc) {
     const commentsEntry = findCstMapEntry(body, "comments");
     if (!commentsEntry?.value || commentsEntry.value.type !== "block-seq") {
         // No existing comments seq — write fresh
-        await writeFile(abs, toYaml(doc), "utf-8");
+        await atomicWriteFile(abs, toYaml(doc));
         return;
     }
     const seq = commentsEntry.value;
@@ -434,6 +524,6 @@ export async function writeSidecar(filePath, doc) {
     }
     // ── Stringify via CST (byte-identical for untouched content) ───────
     const result = tokens.map((t) => CST.stringify(t)).join("");
-    await writeFile(abs, result, "utf-8");
+    await atomicWriteFile(abs, result);
 }
 //# sourceMappingURL=writer.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrsf/cli",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "CLI and library for the Markdown Review Sidecar Format (MRSF)",
   "type": "module",
   "main": "./dist/index.js",