@mrsf/cli 0.1.0

package/dist/lib/validator.js

@@ -0,0 +1,177 @@
+/**
+ * MRSF Validator — JSON Schema + cross-field validation per §10.
+ */
+import AjvModule from "ajv";
+import addFormatsModule from "ajv-formats";
+// ESM interop: handle both default and namespace imports
+const Ajv = AjvModule.default ?? AjvModule;
+const addFormats = addFormatsModule.default ?? addFormatsModule;
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { computeHash } from "./writer.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+let _schemaCache = null;
+async function loadSchema() {
+    if (_schemaCache)
+        return _schemaCache;
+    // The schema lives at the repo root, two levels up from dist/lib/
+    const candidates = [
+        path.resolve(__dirname, "../../../mrsf.schema.json"), // from dist/lib/
+        path.resolve(__dirname, "../../../../mrsf.schema.json"), // fallback
+        path.resolve(process.cwd(), "mrsf.schema.json"), // cwd fallback
+    ];
+    for (const candidate of candidates) {
+        try {
+            const raw = await readFile(candidate, "utf-8");
+            _schemaCache = JSON.parse(raw);
+            return _schemaCache;
+        }
+        catch {
+            // try next
+        }
+    }
+    throw new Error("Could not locate mrsf.schema.json");
+}
+/**
+ * Validate an MRSF document (parsed object).
+ */
+export async function validate(doc, options = {}) {
+    const errors = [];
+    const warnings = [];
+    // ── JSON Schema validation ──
+    const rawSchema = await loadSchema();
+    // Ajv 8 doesn't natively support 2020-12; strip $schema to use draft-07 mode
+    const { $schema, ...schema } = rawSchema;
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    addFormats(ajv);
+    const ajvValidate = ajv.compile(schema);
+    const schemaValid = ajvValidate(doc);
+    if (!schemaValid && ajvValidate.errors) {
+        for (const err of ajvValidate.errors) {
+            errors.push({
+                severity: "error",
+                message: `${err.instancePath || "/"}: ${err.message ?? "schema error"}`,
+                path: err.instancePath || "/",
+            });
+        }
+    }
+    // ── Cross-field validation (§10) ──
+    if (Array.isArray(doc.comments)) {
+        const ids = new Set();
+        for (let i = 0; i < doc.comments.length; i++) {
+            const c = doc.comments[i];
+            const prefix = `/comments/${i}`;
+            // Unique id check
+            if (c.id) {
+                if (ids.has(c.id)) {
+                    errors.push({
+                        severity: "error",
+                        message: `Duplicate comment id "${c.id}"`,
+                        path: `${prefix}/id`,
+                        commentId: c.id,
+                    });
+                }
+                ids.add(c.id);
+            }
+            // end_line ≥ line
+            if (c.line != null && c.end_line != null && c.end_line < c.line) {
+                errors.push({
+                    severity: "error",
+                    message: `end_line (${c.end_line}) must be ≥ line (${c.line})`,
+                    path: `${prefix}/end_line`,
+                    commentId: c.id,
+                });
+            }
+            // end_column ≥ start_column when same line
+            if (c.start_column != null &&
+                c.end_column != null &&
+                (c.line == null || c.end_line == null || c.line === c.end_line) &&
+                c.end_column < c.start_column) {
+                errors.push({
+                    severity: "error",
+                    message: `end_column (${c.end_column}) must be ≥ start_column (${c.start_column}) on the same line`,
+                    path: `${prefix}/end_column`,
+                    commentId: c.id,
+                });
+            }
+            // selected_text length
+            if (c.selected_text && c.selected_text.length > 4096) {
+                errors.push({
+                    severity: "error",
+                    message: `selected_text exceeds 4096 characters (${c.selected_text.length})`,
+                    path: `${prefix}/selected_text`,
+                    commentId: c.id,
+                });
+            }
+            // text length
+            if (c.text && c.text.length > 16384) {
+                warnings.push({
+                    severity: "warning",
+                    message: `text exceeds recommended 16384 characters (${c.text.length})`,
+                    path: `${prefix}/text`,
+                    commentId: c.id,
+                });
+            }
+            // selected_text_hash consistency
+            if (c.selected_text && c.selected_text_hash) {
+                const expected = computeHash(c.selected_text);
+                if (c.selected_text_hash !== expected) {
+                    warnings.push({
+                        severity: "warning",
+                        message: `selected_text_hash mismatch (expected ${expected.slice(0, 12)}…, got ${c.selected_text_hash.slice(0, 12)}…)`,
+                        path: `${prefix}/selected_text_hash`,
+                        commentId: c.id,
+                    });
+                }
+            }
+            // reply_to resolution
+            if (c.reply_to && !ids.has(c.reply_to)) {
+                // Check forward references too
+                const allIds = doc.comments.map((x) => x.id);
+                if (!allIds.includes(c.reply_to)) {
+                    warnings.push({
+                        severity: "warning",
+                        message: `reply_to "${c.reply_to}" does not resolve to any comment id in this file`,
+                        path: `${prefix}/reply_to`,
+                        commentId: c.id,
+                    });
+                }
+            }
+            // Missing selected_text warning
+            if (c.line != null && !c.selected_text) {
+                warnings.push({
+                    severity: "warning",
+                    message: `Comment has line anchors but no selected_text — anchoring will be fragile across edits`,
+                    path: `${prefix}/selected_text`,
+                    commentId: c.id,
+                });
+            }
+        }
+    }
+    const valid = errors.length === 0 && (!options.strict || warnings.length === 0);
+    return { valid, errors, warnings };
+}
+/**
+ * Validate from a file path — convenience wrapper.
+ */
+export async function validateFile(filePath, options = {}) {
+    const { parseSidecar } = await import("./parser.js");
+    try {
+        const doc = await parseSidecar(filePath);
+        return validate(doc, options);
+    }
+    catch (e) {
+        return {
+            valid: false,
+            errors: [
+                {
+                    severity: "error",
+                    message: `Failed to parse: ${e.message}`,
+                },
+            ],
+            warnings: [],
+        };
+    }
+}
+//# sourceMappingURL=validator.js.map

package/dist/lib/writer.d.ts

@@ -0,0 +1,30 @@
+/**
+ * MRSF Writer — serialize MrsfDocument back to YAML or JSON.
+ *
+ * Preserves comment order per §10.1.
+ * Auto-computes selected_text_hash when selected_text changes.
+ */
+import type { MrsfDocument, Comment } from "./types.js";
+/**
+ * Compute SHA-256 hex hash of a string (UTF-8).
+ */
+export declare function computeHash(text: string): string;
+/**
+ * Ensure selected_text_hash is consistent for a comment.
+ * If selected_text is present, computes/updates the hash.
+ * If selected_text is absent, removes the hash.
+ */
+export declare function syncHash(comment: Comment): Comment;
+/**
+ * Serialize an MrsfDocument to YAML.
+ */
+export declare function toYaml(doc: MrsfDocument): string;
+/**
+ * Serialize an MrsfDocument to JSON.
+ */
+export declare function toJson(doc: MrsfDocument): string;
+/**
+ * Write an MrsfDocument to disk. Detects format from file extension.
+ */
+export declare function writeSidecar(filePath: string, doc: MrsfDocument): Promise<void>;
+//# sourceMappingURL=writer.d.ts.map

package/dist/lib/writer.js

@@ -0,0 +1,62 @@
+/**
+ * MRSF Writer — serialize MrsfDocument back to YAML or JSON.
+ *
+ * Preserves comment order per §10.1.
+ * Auto-computes selected_text_hash when selected_text changes.
+ */
+import { writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import yaml from "js-yaml";
+/**
+ * Compute SHA-256 hex hash of a string (UTF-8).
+ */
+export function computeHash(text) {
+    return createHash("sha256").update(text, "utf-8").digest("hex");
+}
+/**
+ * Ensure selected_text_hash is consistent for a comment.
+ * If selected_text is present, computes/updates the hash.
+ * If selected_text is absent, removes the hash.
+ */
+export function syncHash(comment) {
+    if (comment.selected_text != null && comment.selected_text.length > 0) {
+        comment.selected_text_hash = computeHash(comment.selected_text);
+    }
+    else {
+        delete comment.selected_text_hash;
+    }
+    return comment;
+}
+/**
+ * Serialize an MrsfDocument to YAML.
+ */
+export function toYaml(doc) {
+    return yaml.dump(doc, {
+        lineWidth: -1, // no wrapping
+        quotingType: '"',
+        forceQuotes: false,
+        noRefs: true,
+        sortKeys: false, // preserve insertion order
+    });
+}
+/**
+ * Serialize an MrsfDocument to JSON.
+ */
+export function toJson(doc) {
+    return JSON.stringify(doc, null, 2) + "\n";
+}
+/**
+ * Write an MrsfDocument to disk. Detects format from file extension.
+ */
+export async function writeSidecar(filePath, doc) {
+    const abs = path.resolve(filePath);
+    const isJson = abs.endsWith(".review.json");
+    // Sync hashes for all comments before writing
+    for (const comment of doc.comments) {
+        syncHash(comment);
+    }
+    const content = isJson ? toJson(doc) : toYaml(doc);
+    await writeFile(abs, content, "utf-8");
+}
+//# sourceMappingURL=writer.js.map

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@mrsf/cli",
+  "version": "0.1.0",
+  "description": "CLI and library for the Markdown Review Sidecar Format (MRSF)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "mrsf": "./dist/bin.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "cp ../LICENSE . && npm run build && npm test",
+    "postpublish": "rm -f LICENSE"
+  },
+  "keywords": [
+    "markdown",
+    "review",
+    "sidecar",
+    "mrsf",
+    "anchoring",
+    "comments"
+  ],
+  "license": "MIT",
+  "author": "Wictor Wilén (https://github.com/wictorwilen)",
+  "homepage": "https://github.com/wictorwilen/MRSF/tree/main/cli#readme",
+  "bugs": {
+    "url": "https://github.com/wictorwilen/MRSF/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wictorwilen/MRSF.git",
+    "directory": "cli"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "fastest-levenshtein": "^1.0.16",
+    "js-yaml": "^4.1.0",
+    "uuid": "^11.1.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.13.10",
+    "@types/uuid": "^10.0.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9"
+  }
+}