@mrsf/cli 0.2.3 → 0.3.1

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/bin.js

@@ -49,7 +49,7 @@ function showBanner() {
   ${chalk.cyan.bold("╔╦╗")}${chalk.blue.bold("╦═╗")}${chalk.magenta.bold("╔═╗")}${chalk.yellow.bold("╔═╗")}
   ${chalk.cyan.bold("║║║")}${chalk.blue.bold("╠╦╝")}${chalk.magenta.bold("╚═╗")}${chalk.yellow.bold("╠╣")}
   ${chalk.cyan.bold("╩ ╩")}${chalk.blue.bold("╩╚═")}${chalk.magenta.bold("╚═╝")}${chalk.yellow.bold("╚")}
-  ${chalk.dim("Markdown Review Sidecar Format")}  ${chalk.dim.italic(`v${version}`)}
+  ${chalk.dim("Markdown Review Sidecar Format")}  ${chalk.dim.italic(`v${version} (Node.js)`)}
   ${chalk.dim.underline(repo)}
 `;
     process.stderr.write(banner + "\n");
@@ -59,8 +59,8 @@ showBanner();
 const program = new Command();
 program
     .name("mrsf")
-    .description("Markdown Review Sidecar Format — CLI & toolkit")
-    .version(version)
+    .description("Markdown Review Sidecar Format — CLI & toolkit (Node.js)")
+    .version(`${version} (Node.js)`)
     .option("--cwd <dir>", "Working directory")
     .option("--config <path>", "Path to .mrsf.yaml")
     .option("--no-color", "Disable colour output")

package/dist/commands/validate.js

@@ -42,11 +42,11 @@ export function registerValidate(program) {
                 console.log(`${icon} ${sp}`);
             }
             for (const e of result.errors) {
-                console.log(chalk.red(`  error: ${e.message}${e.path ? ` (${e.path})` : ""}`));
+                console.log(chalk.red(`  ERROR: ${e.message}${e.path ? ` (${e.path})` : ""}`));
             }
             for (const w of result.warnings) {
                 const fn = opts.strict ? chalk.red : chalk.yellow;
-                console.log(fn(`  ${opts.strict ? "error" : "warn"}: ${w.message}${w.path ? ` (${w.path})` : ""}`));
+                console.log(fn(`  ${opts.strict ? "ERROR" : "WARN"}: ${w.message}${w.path ? ` (${w.path})` : ""}`));
             }
             if (verbose) {
                 console.log(chalk.dim(`  ${result.errors.length} error(s), ${result.warnings.length} warning(s)`));

package/dist/commands/watch.js

@@ -66,11 +66,11 @@ function printValidateResults(label, result, strict) {
     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})` : ""}`));
+        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";
+        const tag = strict ? "ERROR" : "WARN";
         console.log(fn(`    ${tag}: ${w.message}${w.path ? ` (${w.path})` : ""}`));
     }
 }

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/discovery.js

@@ -38,7 +38,7 @@ export async function loadConfig(workspaceRoot, configPath) {
     if (!existsSync(cfgPath))
         return null;
     const raw = await readFile(cfgPath, "utf-8");
-    const parsed = yaml.load(raw);
+    const parsed = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
     if (!parsed || typeof parsed !== "object")
         return null;
     const config = {};

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

@@ -32,7 +32,7 @@ export function parseSidecarContent(content, filenameHint) {
     }
     else {
         try {
-            parsed = yaml.load(trimmed);
+            parsed = yaml.load(trimmed, { schema: yaml.JSON_SCHEMA });
         }
         catch (e) {
             throw new Error(`Failed to parse YAML: ${e.message}`);
@@ -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, { 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,
+    };
+}
 /**
  * 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/validator.js

@@ -16,8 +16,11 @@ async function loadSchema() {
     if (_schemaCache)
         return _schemaCache;
     // The schema lives at the repo root, two levels up from dist/lib/
+    // When installed as a package, it's at the package root (cli/)
     const candidates = [
-        path.resolve(__dirname, "../../../mrsf.schema.json"), // from dist/lib/
+        path.resolve(__dirname, "mrsf.schema.json"), // same dir (esbuild bundle, e.g. MCP server)
+        path.resolve(__dirname, "../../mrsf.schema.json"), // from dist/lib/ → cli/ (installed package)
+        path.resolve(__dirname, "../../../mrsf.schema.json"), // from dist/lib/ → repo root (dev)
         path.resolve(__dirname, "../../../../mrsf.schema.json"), // fallback
         path.resolve(process.cwd(), "mrsf.schema.json"), // cwd fallback
     ];

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,48 @@ 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 (v instanceof Date)
+        return JSON.stringify(v.toISOString());
     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 +338,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 +370,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 +380,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 +392,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 +432,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 +449,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 +526,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/mrsf.schema.json

@@ -0,0 +1,113 @@
+
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/wictorwilen/MRSF/raw/main/mrsf.schema.json",
+  "title": "Markdown Review Sidecar Format (MRSF) v1.0",
+  "description": "Schema for MRSF review sidecar files. See MRSF-v1.0.md for the full specification.",
+  "type": "object",
+  "required": ["mrsf_version", "document", "comments"],
+  "additionalProperties": true,
+  "properties": {
+    "mrsf_version": {
+      "type": "string",
+      "pattern": "^1\\.\\d+$",
+      "description": "MRSF format version. MUST be a supported major.minor version (e.g., 1.0)."
+    },
+    "document": {
+      "type": "string",
+      "description": "Relative path to the Markdown document being reviewed."
+    },
+    "comments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "author", "timestamp", "text", "resolved"],
+        "additionalProperties": true,
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Globally unique, opaque, collision-resistant identifier for the comment."
+          },
+          "author": {
+            "type": "string",
+            "description": "Creator of the comment. SHOULD follow the convention 'Display Name (identifier)'."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO 8601 / RFC 3339 timestamp of comment creation; SHOULD include timezone offset."
+          },
+          "text": {
+            "type": "string",
+            "maxLength": 16384,
+            "description": "The content of the review comment. MUST be plain text."
+          },
+          "resolved": {
+            "type": "boolean",
+            "description": "Whether the comment has been resolved."
+          },
+          "commit": {
+            "type": "string",
+            "description": "Git commit hash associated with the comment. SHOULD be the full (long) SHA."
+          },
+          "type": {
+            "type": "string",
+            "description": "Categorization of the comment. Recommended values listed in examples.",
+            "examples": [
+              "suggestion",
+              "issue",
+              "question",
+              "accuracy",
+              "style",
+              "clarity"
+            ]
+          },
+          "severity": {
+            "type": "string",
+            "description": "Importance level of the comment.",
+            "enum": ["low", "medium", "high"]
+          },
+          "reply_to": {
+            "type": "string",
+            "description": "ID of another comment in the same file that this comment replies to."
+          },
+          "line": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Starting line number (1-based) in the target document."
+          },
+          "end_line": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Ending line number (inclusive, 1-based). MUST be >= line."
+          },
+          "start_column": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Starting column index (0-based) within the starting line."
+          },
+          "end_column": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Ending column index. MUST be >= start_column when on the same line."
+          },
+          "selected_text": {
+            "type": "string",
+            "maxLength": 4096,
+            "description": "Exact text selected by the reviewer. SHOULD NOT be modified by re-anchoring tools. SHOULD NOT exceed 4096 characters."
+          },
+          "anchored_text": {
+            "type": "string",
+            "maxLength": 4096,
+            "description": "Text currently found at the resolved anchor position. Populated by re-anchoring tools when the document text differs from selected_text. SHOULD be omitted when identical to selected_text."
+          },
+          "selected_text_hash": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$",
+            "description": "Hex-encoded SHA-256 hash of selected_text. Immutable after creation; used for fast exact-match detection during re-anchoring, integrity verification, and staleness checks. SHOULD NOT be modified by re-anchoring tools unless selected_text is also replaced (opt-in behaviour), in which case it MUST be recomputed."
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrsf/cli",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "CLI and library for the Markdown Review Sidecar Format (MRSF)",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,8 +31,13 @@
     "review",
     "sidecar",
     "mrsf",
+    "sidemark",
     "anchoring",
-    "comments"
+    "comments",
+    "cli",
+    "yaml",
+    "validation",
+    "reanchor"
   ],
   "license": "MIT",
   "author": "Wictor Wilén (https://github.com/wictorwilen)",
@@ -48,6 +53,7 @@
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
+    "mrsf.schema.json",
     "README.md",
     "LICENSE"
   ],
@@ -66,6 +72,7 @@
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.13.10",
     "@types/uuid": "^10.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
     "typescript": "^5.8.2",
     "vitest": "^3.0.9"
   }