@mrsf/cli 0.3.1 → 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/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/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/types.d.ts

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

package/dist/lib/writer.js

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

package/package.json

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