@mrsf/cli 0.3.0 → 0.4.0

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.
 
 ---
 

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/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/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

@@ -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";
@@ -14,6 +14,6 @@ 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 { 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

@@ -21,5 +21,5 @@ export { isGitAvailable, findRepoRoot, getCurrentCommit, isStale, getDiff, getLi
 // Re-anchoring
 export { reanchorComment, 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/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.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}`);
@@ -74,7 +74,7 @@ export function parseSidecarContentLenient(content, filenameHint) {
     // First, try a normal parse
     let parsed;
     try {
-        parsed = isJson ? JSON.parse(trimmed) : yaml.load(trimmed);
+        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
@@ -143,7 +143,7 @@ function salvageYaml(content) {
             continue;
         // Wrap in a minimal YAML array context and try to parse
         try {
-            const parsed = yaml.load(trimmed);
+            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") {

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

@@ -107,6 +107,8 @@ const COMMENT_KEY_ORDER = [
  * 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") {
@@ -148,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";
 /**
@@ -349,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/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.3.0",
+  "version": "0.4.0",
   "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"
   }