@mrsf/cli 0.1.0

package/dist/lib/comments.js

@@ -0,0 +1,228 @@
+/**
+ * MRSF Comment Operations — CRUD for sidecar comments.
+ */
+import { randomUUID } from "node:crypto";
+import { computeHash } from "./writer.js";
+import { getCurrentCommit, isGitAvailable } from "./git.js";
+// ---------------------------------------------------------------------------
+// Add
+// ---------------------------------------------------------------------------
+/**
+ * Add a new comment to a document. Mutates doc.comments in place.
+ * Returns the created comment.
+ */
+export async function addComment(doc, opts, repoRoot) {
+    const id = opts.id ?? randomUUID();
+    const timestamp = opts.timestamp ?? new Date().toISOString();
+    // Auto-detect commit from HEAD when git is available
+    let commit = opts.commit;
+    if (!commit && repoRoot && (await isGitAvailable())) {
+        commit = (await getCurrentCommit(repoRoot)) ?? undefined;
+    }
+    const comment = {
+        id,
+        author: opts.author,
+        timestamp,
+        text: opts.text,
+        resolved: false,
+    };
+    // Optional anchoring fields
+    if (opts.line != null)
+        comment.line = opts.line;
+    if (opts.end_line != null)
+        comment.end_line = opts.end_line;
+    if (opts.start_column != null)
+        comment.start_column = opts.start_column;
+    if (opts.end_column != null)
+        comment.end_column = opts.end_column;
+    if (opts.type)
+        comment.type = opts.type;
+    if (opts.severity)
+        comment.severity = opts.severity;
+    if (opts.reply_to)
+        comment.reply_to = opts.reply_to;
+    if (commit)
+        comment.commit = commit;
+    doc.comments.push(comment);
+    return comment;
+}
+/**
+ * Populate selected_text from document lines (reads the file content region).
+ * Should be called after addComment if the caller provides line info but not selected_text.
+ */
+export function populateSelectedText(comment, documentLines) {
+    if (comment.selected_text)
+        return; // already set
+    if (comment.line == null)
+        return;
+    const startIdx = comment.line - 1;
+    const endIdx = (comment.end_line ?? comment.line) - 1;
+    if (startIdx < 0 || endIdx >= documentLines.length)
+        return;
+    if (startIdx === endIdx) {
+        let line = documentLines[startIdx];
+        if (comment.start_column != null && comment.end_column != null) {
+            line = line.slice(comment.start_column, comment.end_column);
+        }
+        comment.selected_text = line;
+    }
+    else {
+        const lines = [];
+        for (let i = startIdx; i <= endIdx; i++) {
+            let l = documentLines[i];
+            if (i === startIdx && comment.start_column != null) {
+                l = l.slice(comment.start_column);
+            }
+            if (i === endIdx && comment.end_column != null) {
+                l = l.slice(0, comment.end_column);
+            }
+            lines.push(l);
+        }
+        comment.selected_text = lines.join("\n");
+    }
+    // Also set the hash
+    if (comment.selected_text) {
+        comment.selected_text_hash = computeHash(comment.selected_text);
+    }
+}
+// ---------------------------------------------------------------------------
+// Resolve / Unresolve
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a comment by id. Per §9, resolving a parent does NOT
+ * automatically resolve its replies.
+ *
+ * Returns true if the comment was found and updated.
+ */
+export function resolveComment(doc, commentId, cascade = false) {
+    const comment = doc.comments.find((c) => c.id === commentId);
+    if (!comment)
+        return false;
+    comment.resolved = true;
+    if (cascade) {
+        // Cascade to direct replies only
+        for (const c of doc.comments) {
+            if (c.reply_to === commentId) {
+                c.resolved = true;
+            }
+        }
+    }
+    return true;
+}
+/**
+ * Unresolve a comment by id.
+ */
+export function unresolveComment(doc, commentId) {
+    const comment = doc.comments.find((c) => c.id === commentId);
+    if (!comment)
+        return false;
+    comment.resolved = false;
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Remove
+// ---------------------------------------------------------------------------
+/**
+ * Remove a comment by id. Returns true if found and removed.
+ */
+export function removeComment(doc, commentId) {
+    const idx = doc.comments.findIndex((c) => c.id === commentId);
+    if (idx === -1)
+        return false;
+    doc.comments.splice(idx, 1);
+    return true;
+}
+// ---------------------------------------------------------------------------
+// List / Filter
+// ---------------------------------------------------------------------------
+/**
+ * Filter comments based on criteria.
+ */
+export function filterComments(comments, filter) {
+    return comments.filter((c) => {
+        if (filter.open === true && c.resolved)
+            return false;
+        if (filter.resolved === true && !c.resolved)
+            return false;
+        if (filter.author && c.author !== filter.author)
+            return false;
+        if (filter.type && c.type !== filter.type)
+            return false;
+        if (filter.severity && c.severity !== filter.severity)
+            return false;
+        if (filter.orphaned === true && c.x_reanchor_status !== "orphaned")
+            return false;
+        if (filter.orphaned === false && c.x_reanchor_status === "orphaned")
+            return false;
+        return true;
+    });
+}
+/**
+ * Get a list of threads — groups of comments by their root ID via reply_to.
+ * Returns a map of root comment ID → [root, ...replies in order].
+ */
+export function getThreads(comments) {
+    const threads = new Map();
+    const replyMap = new Map(); // child id → root id
+    // First pass: find all roots and build reply chains
+    for (const c of comments) {
+        if (!c.reply_to) {
+            threads.set(c.id, [c]);
+        }
+        else {
+            replyMap.set(c.id, c.reply_to);
+        }
+    }
+    // Resolve transitive reply_to chains to roots
+    function findRoot(id) {
+        const parent = replyMap.get(id);
+        if (!parent)
+            return id;
+        return findRoot(parent);
+    }
+    // Second pass: attach replies to their root thread
+    for (const c of comments) {
+        if (c.reply_to) {
+            const rootId = findRoot(c.id);
+            if (!threads.has(rootId)) {
+                threads.set(rootId, []);
+            }
+            threads.get(rootId).push(c);
+        }
+    }
+    return threads;
+}
+/**
+ * Generate summary statistics for a comment list.
+ */
+export function summarize(comments) {
+    const summary = {
+        total: comments.length,
+        open: 0,
+        resolved: 0,
+        orphaned: 0,
+        threads: 0,
+        byType: {},
+        bySeverity: {},
+    };
+    const roots = new Set();
+    for (const c of comments) {
+        if (c.resolved)
+            summary.resolved++;
+        else
+            summary.open++;
+        if (c.x_reanchor_status === "orphaned")
+            summary.orphaned++;
+        if (c.type) {
+            summary.byType[c.type] = (summary.byType[c.type] ?? 0) + 1;
+        }
+        if (c.severity) {
+            summary.bySeverity[c.severity] = (summary.bySeverity[c.severity] ?? 0) + 1;
+        }
+        if (!c.reply_to)
+            roots.add(c.id);
+    }
+    summary.threads = roots.size;
+    return summary;
+}
+//# sourceMappingURL=comments.js.map

package/dist/lib/discovery.d.ts

@@ -0,0 +1,40 @@
+/**
+ * MRSF Discovery — resolve sidecar file paths per §3.3.
+ *
+ * Discovery order:
+ *  1. Check for .mrsf.yaml at repo/workspace root → use sidecar_root if defined.
+ *  2. Otherwise, co-located sidecar next to the Markdown file.
+ */
+import type { MrsfConfig } from "./types.js";
+/**
+ * Find the workspace / repo root by walking up from `startDir` looking for
+ * `.mrsf.yaml` or `.git`.
+ */
+export declare function findWorkspaceRoot(startDir: string): string;
+/**
+ * Load and validate .mrsf.yaml config. Returns null if not found.
+ */
+export declare function loadConfig(workspaceRoot: string, configPath?: string): Promise<MrsfConfig | null>;
+/**
+ * Given a Markdown document path (relative to workspace root), resolve the
+ * sidecar file path according to §3.3 discovery order.
+ *
+ * Returns an absolute path to the sidecar.
+ */
+export declare function discoverSidecar(documentPath: string, options?: {
+    cwd?: string;
+    configPath?: string;
+}): Promise<string>;
+/**
+ * Given a sidecar file path, resolve the Markdown document path.
+ * Strips .review.yaml or .review.json suffix.
+ * Returns an absolute path to the document.
+ */
+export declare function sidecarToDocument(sidecarPath: string, options?: {
+    cwd?: string;
+}): string;
+/**
+ * Discover all sidecar files in a directory (recursive).
+ */
+export declare function discoverAllSidecars(dirPath: string): Promise<string[]>;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/lib/discovery.js

@@ -0,0 +1,125 @@
+/**
+ * MRSF Discovery — resolve sidecar file paths per §3.3.
+ *
+ * Discovery order:
+ *  1. Check for .mrsf.yaml at repo/workspace root → use sidecar_root if defined.
+ *  2. Otherwise, co-located sidecar next to the Markdown file.
+ */
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+const CONFIG_FILENAME = ".mrsf.yaml";
+const SIDECAR_SUFFIX = ".review.yaml";
+const SIDECAR_SUFFIX_JSON = ".review.json";
+/**
+ * Find the workspace / repo root by walking up from `startDir` looking for
+ * `.mrsf.yaml` or `.git`.
+ */
+export function findWorkspaceRoot(startDir) {
+    let dir = path.resolve(startDir);
+    const { root } = path.parse(dir);
+    while (dir !== root) {
+        if (existsSync(path.join(dir, CONFIG_FILENAME)) ||
+            existsSync(path.join(dir, ".git"))) {
+            return dir;
+        }
+        dir = path.dirname(dir);
+    }
+    return path.resolve(startDir);
+}
+/**
+ * Load and validate .mrsf.yaml config. Returns null if not found.
+ */
+export async function loadConfig(workspaceRoot, configPath) {
+    const cfgPath = configPath
+        ? path.resolve(configPath)
+        : path.join(workspaceRoot, CONFIG_FILENAME);
+    if (!existsSync(cfgPath))
+        return null;
+    const raw = await readFile(cfgPath, "utf-8");
+    const parsed = yaml.load(raw);
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const config = {};
+    if (typeof parsed.sidecar_root === "string") {
+        const sr = parsed.sidecar_root;
+        // Reject absolute paths
+        if (path.isAbsolute(sr)) {
+            throw new Error(`.mrsf.yaml: sidecar_root must be a relative path (got "${sr}")`);
+        }
+        // Reject path traversal
+        if (sr.includes("..")) {
+            throw new Error(`.mrsf.yaml: sidecar_root must not contain ".." (got "${sr}")`);
+        }
+        config.sidecar_root = sr;
+    }
+    return config;
+}
+/**
+ * Given a Markdown document path (relative to workspace root), resolve the
+ * sidecar file path according to §3.3 discovery order.
+ *
+ * Returns an absolute path to the sidecar.
+ */
+export async function discoverSidecar(documentPath, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const workspaceRoot = findWorkspaceRoot(cwd);
+    const config = await loadConfig(workspaceRoot, options.configPath);
+    // Normalize to a workspace-relative path
+    const relDoc = path.isAbsolute(documentPath)
+        ? path.relative(workspaceRoot, documentPath)
+        : documentPath;
+    if (config?.sidecar_root) {
+        // §3.2 — alternate sidecar location
+        return path.join(workspaceRoot, config.sidecar_root, relDoc + SIDECAR_SUFFIX);
+    }
+    // §3.1 — co-located
+    return path.join(workspaceRoot, relDoc + SIDECAR_SUFFIX);
+}
+/**
+ * Given a sidecar file path, resolve the Markdown document path.
+ * Strips .review.yaml or .review.json suffix.
+ * Returns an absolute path to the document.
+ */
+export function sidecarToDocument(sidecarPath, options = {}) {
+    const abs = path.resolve(sidecarPath);
+    if (abs.endsWith(SIDECAR_SUFFIX)) {
+        return abs.slice(0, -SIDECAR_SUFFIX.length);
+    }
+    else if (abs.endsWith(SIDECAR_SUFFIX_JSON)) {
+        return abs.slice(0, -SIDECAR_SUFFIX_JSON.length);
+    }
+    return abs;
+}
+/**
+ * Discover all sidecar files in a directory (recursive).
+ */
+export async function discoverAllSidecars(dirPath) {
+    const { readdir, stat } = await import("node:fs/promises");
+    const results = [];
+    async function walk(dir) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === "node_modules" || entry.name === ".git")
+                    continue;
+                await walk(full);
+            }
+            else if (entry.name.endsWith(SIDECAR_SUFFIX) ||
+                entry.name.endsWith(SIDECAR_SUFFIX_JSON)) {
+                results.push(full);
+            }
+        }
+    }
+    const s = await stat(dirPath);
+    if (s.isFile()) {
+        results.push(path.resolve(dirPath));
+    }
+    else {
+        await walk(path.resolve(dirPath));
+    }
+    return results;
+}
+//# sourceMappingURL=discovery.js.map

package/dist/lib/fuzzy.d.ts

@@ -0,0 +1,39 @@
+/**
+ * MRSF Fuzzy Matching Engine
+ *
+ * Provides exact, normalized, token-level LCS, and character-level
+ * Levenshtein matching for re-anchoring selected_text.
+ */
+import type { FuzzyCandidate } from "./types.js";
+/**
+ * Find all exact occurrences of `needle` in lines (1-based array).
+ */
+export declare function exactMatch(lines: string[], needle: string): FuzzyCandidate[];
+/**
+ * Find matches after normalizing whitespace.
+ */
+export declare function normalizedMatch(lines: string[], needle: string): FuzzyCandidate[];
+/**
+ * Score two texts using token-level LCS.
+ * Returns 0.0–1.0.
+ */
+export declare function tokenLcsScore(a: string, b: string): number;
+/**
+ * Normalized Levenshtein similarity 0.0–1.0.
+ */
+export declare function levenshteinScore(a: string, b: string): number;
+/**
+ * Compute a combined similarity score between two text fragments.
+ * Blends token LCS (structural) and Levenshtein (character-level).
+ */
+export declare function combinedScore(needle: string, candidate: string): number;
+/**
+ * Search the document for fuzzy matches of `needle`.
+ *
+ * @param lines     1-based line array (index 0 unused).
+ * @param needle    The original selected_text.
+ * @param threshold Minimum score to include (0.0–1.0).
+ * @param hintLine  Optional original line number for proximity scoring.
+ */
+export declare function fuzzySearch(lines: string[], needle: string, threshold?: number, hintLine?: number): FuzzyCandidate[];
+//# sourceMappingURL=fuzzy.d.ts.map