@fitsummehari/mergeguard 0.1.0

package/src/git.js

@@ -0,0 +1,269 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { matchesAnyGlob, normalizePath } from "./utils.js";
+import { safeJoin } from "./paths.js";
+
+const ZERO_SHA = /^0+$/;
+export const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+const MAX_FILE_BYTES = 2_000_000;
+
+export function git(args, { cwd = process.cwd(), input, allowFailure = false, encoding = "utf8" } = {}) {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      input,
+      encoding,
+      maxBuffer: 64 * 1024 * 1024,
+      windowsHide: true,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch (error) {
+    if (allowFailure) return undefined;
+    const stderr = error?.stderr?.toString?.().trim();
+    throw new Error(stderr || `git ${args.join(" ")} failed`);
+  }
+}
+
+export function repositoryRoot(cwd = process.cwd()) {
+  const root = git(["rev-parse", "--show-toplevel"], { cwd, allowFailure: true })?.trim();
+  if (!root) throw new Error("Not inside a Git repository");
+  return root;
+}
+
+export function gitAvailable() {
+  return Boolean(git(["--version"], { allowFailure: true }));
+}
+
+export function hooksDirectory(root) {
+  const configured = git(["config", "--get", "core.hooksPath"], { cwd: root, allowFailure: true })?.trim();
+  if (configured) {
+    const resolved = configured.startsWith("/") || /^[A-Za-z]:/.test(configured)
+      ? configured
+      : safeJoin(root, configured) || `${root}/${configured.replaceAll("\\", "/")}`;
+    return resolved;
+  }
+  const gitDir = git(["rev-parse", "--git-path", "hooks"], { cwd: root }).trim();
+  return gitDir.startsWith("/") || /^[A-Za-z]:/.test(gitDir) ? gitDir : `${root}/${gitDir}`;
+}
+
+export function resolveReviewScope(root, options = {}) {
+  const hasHead = Boolean(git(["rev-parse", "--verify", "HEAD"], { cwd: root, allowFailure: true }));
+  const initialBase = hasHead ? "HEAD" : EMPTY_TREE;
+  if (options.push) return resolvePushScope(root, options.pushInput);
+  if (options.staged) {
+    return {
+      mode: "staged",
+      label: "staged changes",
+      diffArgs: ["diff", "--cached", "--find-renames", initialBase],
+      baseRef: initialBase,
+      headKind: "index",
+      headRef: undefined,
+    };
+  }
+  if (options.base || options.head) {
+    const base = options.base || defaultBaseRef(root);
+    const head = options.head || "HEAD";
+    if (!git(["rev-parse", "--verify", base], { cwd: root, allowFailure: true })) {
+      throw new Error(`Unknown Git ref '${base}'. Fetch the base branch or pass an existing --base.`);
+    }
+    if (!git(["rev-parse", "--verify", head], { cwd: root, allowFailure: true })) {
+      throw new Error(`Unknown Git ref '${head}'.`);
+    }
+    const mergeBase = git(["merge-base", base, head], { cwd: root, allowFailure: true })?.trim();
+    if (!mergeBase) throw new Error(`Could not find a merge-base between ${base} and ${head}`);
+    return {
+      mode: "range",
+      label: `${base}...${head}`,
+      diffArgs: ["diff", "--find-renames", `${base}...${head}`],
+      baseRef: mergeBase,
+      headKind: "ref",
+      headRef: head,
+    };
+  }
+  return {
+    mode: "working",
+    label: hasHead ? "working tree vs HEAD" : "working tree vs empty repository",
+    diffArgs: ["diff", "--find-renames", initialBase],
+    baseRef: initialBase,
+    headKind: "working",
+    headRef: undefined,
+  };
+}
+
+function resolvePushScope(root, pushInput) {
+  const lines = String(pushInput ?? "").trim().split(/\r?\n/).filter(Boolean);
+  for (const line of lines) {
+    const [localRef, localSha, remoteRef, remoteSha] = line.trim().split(/\s+/);
+    if (!localSha || ZERO_SHA.test(localSha)) continue;
+    let baseRef = remoteSha && !ZERO_SHA.test(remoteSha) ? remoteSha : undefined;
+    if (!baseRef) {
+      const remoteName = process.env.MERGEGUARD_REMOTE || "origin";
+      const target = remoteDefaultRef(root, remoteName);
+      if (target) baseRef = git(["merge-base", localSha, target], { cwd: root, allowFailure: true })?.trim();
+    }
+    if (!baseRef) baseRef = EMPTY_TREE;
+    return {
+      mode: "push",
+      label: `${localRef || "local"} → ${remoteRef || "remote"}`,
+      diffArgs: ["diff", "--find-renames", `${baseRef}..${localSha}`],
+      baseRef,
+      headKind: "ref",
+      headRef: localSha,
+    };
+  }
+
+  const head = git(["rev-parse", "HEAD"], { cwd: root, allowFailure: true })?.trim();
+  if (!head) {
+    return {
+      mode: "push",
+      label: "initial push",
+      diffArgs: ["diff", "--find-renames", EMPTY_TREE],
+      baseRef: EMPTY_TREE,
+      headKind: "working",
+      headRef: undefined,
+    };
+  }
+  const upstream = git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"], { cwd: root, allowFailure: true })?.trim();
+  const target = upstream || defaultBaseRef(root);
+  const base = git(["merge-base", head, target], { cwd: root, allowFailure: true })?.trim();
+  if (!base) {
+    return {
+      mode: "push",
+      label: "initial push",
+      diffArgs: ["diff", "--find-renames", `${EMPTY_TREE}..${head}`],
+      baseRef: EMPTY_TREE,
+      headKind: "ref",
+      headRef: head,
+    };
+  }
+  return { mode: "push", label: `${target}..HEAD`, diffArgs: ["diff", "--find-renames", `${base}..${head}`], baseRef: base, headKind: "ref", headRef: head };
+}
+
+function remoteDefaultRef(root, remote = "origin") {
+  const symbolic = git(["symbolic-ref", `refs/remotes/${remote}/HEAD`], { cwd: root, allowFailure: true })?.trim();
+  if (symbolic) return symbolic.replace(/^refs\/remotes\//, "");
+  for (const candidate of [`${remote}/main`, `${remote}/master`]) {
+    if (git(["rev-parse", "--verify", candidate], { cwd: root, allowFailure: true })) return candidate;
+  }
+  return undefined;
+}
+
+export function defaultBaseRef(root, remote = "origin") {
+  const symbolic = git(["symbolic-ref", `refs/remotes/${remote}/HEAD`], { cwd: root, allowFailure: true })?.trim();
+  if (symbolic) return symbolic.replace(/^refs\/remotes\//, "");
+  for (const candidate of [`${remote}/main`, `${remote}/master`, "main", "master"]) {
+    if (git(["rev-parse", "--verify", candidate], { cwd: root, allowFailure: true })) return candidate;
+  }
+  const parent = git(["rev-parse", "--verify", "HEAD^"], { cwd: root, allowFailure: true })?.trim();
+  if (parent) return "HEAD^";
+  throw new Error("Could not infer a review base. Pass --base <ref> explicitly.");
+}
+
+export function collectChangedFiles(root, scope, { includeUntracked = true, maxFiles = 300, ignore = [] } = {}) {
+  const diffArgs = scope.diffArgs.slice(1);
+  const raw = git(["diff", "--name-status", "-z", ...diffArgs], { cwd: root, encoding: "buffer" });
+  const tokens = raw.toString("utf8").split("\0").filter(Boolean);
+  const entries = [];
+  for (let i = 0; i < tokens.length; ) {
+    const statusToken = tokens[i++];
+    const code = statusToken[0];
+    if (code === "R" || code === "C") {
+      const previousPath = normalizePath(tokens[i++] || "");
+      const path = normalizePath(tokens[i++] || "");
+      entries.push({ path, previousPath, status: code === "R" ? "renamed" : "added" });
+    } else {
+      const path = normalizePath(tokens[i++] || "");
+      entries.push({ path, status: code === "A" ? "added" : code === "D" ? "deleted" : "modified" });
+    }
+  }
+
+  if (scope.mode === "working" && includeUntracked) {
+    const untrackedRaw = git(["ls-files", "--others", "--exclude-standard", "-z"], { cwd: root, encoding: "buffer" });
+    for (const path of untrackedRaw.toString("utf8").split("\0").filter(Boolean)) {
+      const normalized = normalizePath(path);
+      if (!entries.some((entry) => entry.path === normalized)) entries.push({ path: normalized, status: "added", untracked: true });
+    }
+  }
+
+  const reviewable = entries.filter((entry) => entry.path && !matchesAnyGlob(entry.path, ignore) && safeJoin(root, entry.path));
+  const totalFiles = reviewable.length;
+  const ignoredFiles = entries.length - reviewable.length;
+  const limited = reviewable.slice(0, maxFiles);
+  const files = limited.map((entry) => hydrateChangedFile(root, scope, entry));
+  return { files, totalFiles, ignoredFiles, truncated: totalFiles > maxFiles };
+}
+
+function hydrateChangedFile(root, scope, entry) {
+  let patch;
+  let headContent;
+  let baseContent;
+  if (entry.untracked) {
+    headContent = safeReadWorking(root, entry.path);
+    patch = createAddedPatch(entry.path, headContent || "");
+  } else {
+    const args = scope.diffArgs.slice(1);
+    patch = git(["diff", "--no-ext-diff", "--unified=3", ...args, "--", entry.path], { cwd: root, allowFailure: true }) || "";
+    headContent = entry.status === "deleted" ? undefined : readHeadContent(root, scope, entry.path);
+  }
+  if (scope.baseRef && entry.status !== "added") baseContent = gitShow(root, scope.baseRef, entry.previousPath || entry.path);
+  const { additions, deletions } = patchStats(patch);
+  return { ...entry, additions, deletions, patch, headContent, baseContent };
+}
+
+function readHeadContent(root, scope, path) {
+  if (scope.headKind === "working") return safeReadWorking(root, path);
+  if (scope.headKind === "index") return gitShow(root, "", path, true);
+  return gitShow(root, scope.headRef || "HEAD", path);
+}
+
+function safeReadWorking(root, path) {
+  const full = safeJoin(root, path);
+  if (!full || !existsSync(full)) return undefined;
+  try {
+    const buffer = readFileSync(full);
+    if (buffer.includes(0)) return undefined;
+    return buffer.length > MAX_FILE_BYTES ? buffer.subarray(0, MAX_FILE_BYTES).toString("utf8") : buffer.toString("utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+function gitShow(root, ref, path, index = false) {
+  if (!safeJoin(root, path)) return undefined;
+  const spec = index ? `:${path}` : `${ref}:${path}`;
+  const result = git(["show", spec], { cwd: root, allowFailure: true, encoding: "buffer" });
+  if (!result || result.includes(0)) return undefined;
+  return result.length > MAX_FILE_BYTES ? result.subarray(0, MAX_FILE_BYTES).toString("utf8") : result.toString("utf8");
+}
+
+function createAddedPatch(path, content) {
+  const lines = content.split(/\r?\n/);
+  return `diff --git a/${path} b/${path}\nnew file mode 100644\n--- /dev/null\n+++ b/${path}\n@@ -0,0 +1,${lines.length} @@\n${lines.map((line) => `+${line}`).join("\n")}`;
+}
+
+function patchStats(patch = "") {
+  let additions = 0;
+  let deletions = 0;
+  for (const line of patch.split(/\r?\n/)) {
+    if (line.startsWith("+") && !line.startsWith("+++")) additions++;
+    else if (line.startsWith("-") && !line.startsWith("---")) deletions++;
+  }
+  return { additions, deletions };
+}
+
+export function repositoryInfo(root) {
+  const headSha = git(["rev-parse", "HEAD"], { cwd: root, allowFailure: true })?.trim() || "working";
+  const branch = git(["branch", "--show-current"], { cwd: root, allowFailure: true })?.trim() || "detached";
+  const remoteUrl = git(["config", "--get", "remote.origin.url"], { cwd: root, allowFailure: true })?.trim();
+  return { root, headSha, branch, remoteUrl };
+}
+
+export function trackedFiles(root, { limit = 4000 } = {}) {
+  const raw = git(["ls-files", "-z"], { cwd: root, encoding: "buffer" });
+  const files = raw.toString("utf8").split("\0").filter(Boolean).map(normalizePath);
+  return files.slice(0, limit);
+}
+
+export function emptyTree() {
+  return EMPTY_TREE;
+}

package/src/hook.js

@@ -0,0 +1,79 @@
+import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { hooksDirectory, repositoryRoot } from "./git.js";
+import { installSpec } from "./package-meta.js";
+
+const START = "# >>> mergeguard >>>";
+const END = "# <<< mergeguard <<<";
+
+export function hookPath(root) {
+  return join(hooksDirectory(root), "pre-push");
+}
+
+export function installHook(cwd = process.cwd(), { force = false } = {}) {
+  const root = repositoryRoot(cwd);
+  const path = hookPath(root);
+  let existing = existsSync(path) ? readFileSync(path, "utf8") : "#!/bin/sh\n\n";
+  if (existing.includes(START)) return { path, changed: false, message: "MergeGuard pre-push hook is already installed." };
+  if (!existing.startsWith("#!")) {
+    if (!force) throw new Error(`Existing pre-push hook has no shebang: ${path}. Use --force to prepend one safely.`);
+    existing = `#!/bin/sh\n${existing}`;
+  }
+  const pkg = installSpec();
+  const block = `
+${START}
+# MergeGuard reviews the outgoing push range. Bypass with: git push --no-verify
+input=$(cat)
+ROOT="$(git rev-parse --show-toplevel </dev/null)" || exit 2
+cd "$ROOT" || exit 2
+export MERGEGUARD_REMOTE="$1"
+run_mergeguard() {
+  if [ -n "$MERGEGUARD_BIN" ]; then
+    "$MERGEGUARD_BIN" review --push
+  elif [ -x "$ROOT/node_modules/.bin/mergeguard" ]; then
+    "$ROOT/node_modules/.bin/mergeguard" review --push
+  elif command -v mergeguard >/dev/null 2>&1; then
+    mergeguard review --push
+  else
+    echo "MergeGuard is not installed in this repository." >&2
+    echo "Install with: npm install -D ${pkg}" >&2
+    echo "Do not install the unscoped npm name mergeguard (different package)." >&2
+    echo "Or set MERGEGUARD_BIN to the mergeguard executable." >&2
+    exit 2
+  fi
+}
+printf '%s\\n' "$input" | run_mergeguard
+status=$?
+if [ "$status" -eq 1 ]; then
+  echo "MergeGuard blocked this push. Fix the findings, or bypass with: git push --no-verify" >&2
+  exit 1
+fi
+if [ "$status" -ne 0 ]; then exit "$status"; fi
+${END}
+`;
+  writeFileSync(path, `${existing.trimEnd()}\n${block}`);
+  try { chmodSync(path, 0o755); } catch { /* Windows may lack POSIX chmod */ }
+  return { path, changed: true, message: "MergeGuard pre-push hook installed." };
+}
+
+export function uninstallHook(cwd = process.cwd()) {
+  const root = repositoryRoot(cwd);
+  const path = hookPath(root);
+  if (!existsSync(path)) return { path, changed: false, message: "No pre-push hook exists." };
+  const existing = readFileSync(path, "utf8");
+  if (!existing.includes(START)) return { path, changed: false, message: "MergeGuard is not installed in the pre-push hook." };
+  const cleaned = existing.replace(new RegExp(`\\n?${escapeRegExp(START)}[\\s\\S]*?${escapeRegExp(END)}\\n?`, "m"), "\n");
+  writeFileSync(path, `${cleaned.trimEnd()}\n`);
+  return { path, changed: true, message: "MergeGuard block removed; other pre-push hook content was preserved." };
+}
+
+export function hookStatus(cwd = process.cwd()) {
+  const root = repositoryRoot(cwd);
+  const path = hookPath(root);
+  const installed = existsSync(path) && readFileSync(path, "utf8").includes(START);
+  return { path, installed };
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/index.js

@@ -0,0 +1,9 @@
+/**
+ * Public Node API. Prefer this over parsing CLI output.
+ * @module mergeguard
+ */
+export { review, reviewChangeSet } from "./review.js";
+export { loadConfig, normalizeConfig, defaultConfig } from "./config.js";
+export { renderReport, toSarif, toGitLabCodeQuality } from "./reporters/index.js";
+export { detectLaya } from "./verifiers/index.js";
+export { VERSION } from "./version.js";

package/src/languages.js

@@ -0,0 +1,29 @@
+import { extname, basename } from "node:path";
+
+const BY_EXT = new Map([
+  [".js", "javascript"], [".jsx", "javascript"], [".mjs", "javascript"], [".cjs", "javascript"],
+  [".ts", "typescript"], [".tsx", "typescript"], [".mts", "typescript"], [".cts", "typescript"],
+  [".py", "python"], [".pyi", "python"],
+  [".java", "java"], [".kt", "kotlin"], [".kts", "kotlin"],
+  [".go", "go"], [".php", "php"], [".rb", "ruby"], [".cs", "csharp"],
+  [".rs", "rust"], [".cpp", "cpp"], [".cc", "cpp"], [".cxx", "cpp"], [".c", "c"], [".h", "c"], [".hpp", "cpp"],
+  [".swift", "swift"], [".scala", "scala"], [".ex", "elixir"], [".exs", "elixir"],
+  [".sql", "sql"], [".sh", "shell"], [".bash", "shell"], [".zsh", "shell"], [".ps1", "powershell"],
+  [".tf", "terraform"], [".tfvars", "terraform"],
+  [".vue", "vue"], [".svelte", "svelte"],
+]);
+
+export function languageForPath(path) {
+  const name = basename(path).toLowerCase();
+  if (name === "dockerfile" || name.startsWith("dockerfile.")) return "dockerfile";
+  if (name === "gemfile") return "ruby";
+  if (name === "makefile") return "make";
+  if (/\.ya?ml$/.test(name)) return "yaml";
+  if (name.endsWith(".json")) return "json";
+  if (name.endsWith(".xml")) return "xml";
+  return BY_EXT.get(extname(name)) || "text";
+}
+
+export function isCodePath(path) {
+  return languageForPath(path) !== "text" && !["json", "yaml", "xml", "make", "dockerfile"].includes(languageForPath(path));
+}

package/src/package-meta.js

@@ -0,0 +1,17 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const pkg = JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
+
+/** npm registry name from package.json (scoped). Product and CLI remain "MergeGuard" / "mergeguard". */
+export const NPM_PACKAGE_NAME = pkg.name;
+
+/** Spec for `npm install --save-dev …`. */
+export function installSpec() {
+  return NPM_PACKAGE_NAME;
+}
+
+/** One-off npx without a prior local install (avoids the unrelated unscoped `mergeguard` package). */
+export function oneOffNpx(command = "review") {
+  return `npx --package=${NPM_PACKAGE_NAME} mergeguard ${command}`;
+}

package/src/paths.js

@@ -0,0 +1,33 @@
+import { lstatSync, realpathSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { normalizePath } from "./utils.js";
+
+/** Join a repository-relative path only if it stays inside root. */
+export function safeJoin(root, relativePath) {
+  const normalized = normalizePath(String(relativePath || ""));
+  if (!normalized || normalized.includes("\0") || isAbsolute(normalized) || /^[A-Za-z]:/.test(normalized)) {
+    return undefined;
+  }
+  if (normalized.split("/").some((part) => part === "..")) return undefined;
+  const rootResolved = resolve(root);
+  const full = resolve(rootResolved, normalized);
+  const rel = relative(rootResolved, full);
+  if (!rel || rel.startsWith("..") || isAbsolute(rel)) return undefined;
+  try {
+    const stat = lstatSync(full);
+    if (stat.isSymbolicLink()) {
+      const real = realpathSync(full);
+      const rootWithSep = rootResolved.endsWith(sep) ? rootResolved : `${rootResolved}${sep}`;
+      if (real !== rootResolved && !real.startsWith(rootWithSep)) return undefined;
+    } else if (!stat.isFile() && !stat.isDirectory()) {
+      return undefined;
+    }
+  } catch {
+    return full;
+  }
+  return full;
+}
+
+export function stripControlChars(text) {
+  return String(text ?? "").replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, "");
+}

package/src/reporters/gitlab.js

@@ -0,0 +1,16 @@
+export function toGitLabCodeQuality(result) {
+  return result.findings.map((finding) => ({
+    description: `${finding.title}: ${finding.description}`,
+    check_name: finding.detector || "mergeguard",
+    fingerprint: finding.id,
+    severity: mapSeverity(finding.severity),
+    location: {
+      path: finding.file.replaceAll("\\", "/"),
+      lines: { begin: finding.startLine || 1, end: finding.endLine || finding.startLine || 1 },
+    },
+  }));
+}
+
+function mapSeverity(severity) {
+  return { critical: "blocker", high: "critical", medium: "major", low: "minor", info: "info" }[severity] || "major";
+}

package/src/reporters/index.js

@@ -0,0 +1,13 @@
+import { terminalReport } from "./terminal.js";
+import { toSarif } from "./sarif.js";
+import { toGitLabCodeQuality } from "./gitlab.js";
+
+export function renderReport(result, format = "terminal", options = {}) {
+  if (format === "terminal") return terminalReport(result, options);
+  if (format === "json") return JSON.stringify(result, null, 2);
+  if (format === "sarif") return JSON.stringify(toSarif(result), null, 2);
+  if (format === "gitlab") return JSON.stringify(toGitLabCodeQuality(result), null, 2);
+  throw new Error(`Unknown output format '${format}'. Use terminal, json, sarif, or gitlab.`);
+}
+export { toSarif } from "./sarif.js";
+export { toGitLabCodeQuality } from "./gitlab.js";

package/src/reporters/sarif.js

@@ -0,0 +1,55 @@
+const INFORMATION_URI = "https://github.com/FitsumMehari/MergeGuard";
+
+export function toSarif(result) {
+  const rules = new Map();
+  for (const finding of result.findings) {
+    const id = finding.detector || finding.id;
+    if (!rules.has(id)) {
+      rules.set(id, {
+        id,
+        name: String(id).replace(/[^A-Za-z0-9_-]/g, "-"),
+        shortDescription: { text: finding.title },
+        fullDescription: { text: finding.description },
+        help: { text: finding.remediation || finding.description },
+        defaultConfiguration: { level: sarifLevel(finding.severity) },
+        properties: { category: finding.category, severity: finding.severity, tags: [finding.category, finding.severity] },
+      });
+    }
+  }
+  return {
+    version: "2.1.0",
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    runs: [{
+      tool: {
+        driver: {
+          name: "MergeGuard",
+          version: result.version,
+          informationUri: INFORMATION_URI,
+          rules: [...rules.values()],
+        },
+      },
+      results: result.findings.map((finding) => ({
+        ruleId: finding.detector || finding.id,
+        level: sarifLevel(finding.severity),
+        message: { text: `${finding.title}: ${finding.description}${finding.remediation ? ` Fix: ${finding.remediation}` : ""}` },
+        locations: [{
+          physicalLocation: {
+            artifactLocation: { uri: finding.file.replaceAll("\\", "/") },
+            region: { startLine: finding.startLine || 1, ...(finding.endLine ? { endLine: finding.endLine } : {}) },
+          },
+        }],
+        partialFingerprints: { mergeguardFindingId: finding.id },
+        properties: {
+          category: finding.category,
+          severity: finding.severity,
+          confidence: finding.confidence,
+          verifier: finding.verification?.provider,
+        },
+      })),
+    }],
+  };
+}
+
+function sarifLevel(severity) {
+  return severity === "critical" || severity === "high" ? "error" : severity === "medium" ? "warning" : "note";
+}

package/src/reporters/terminal.js

@@ -0,0 +1,48 @@
+import { isAtLeastSeverity } from "../utils.js";
+
+export function terminalReport(result, { color = process.stdout.isTTY && !process.env.NO_COLOR, verbose = false } = {}) {
+  const c = color ? colors : plain;
+  const lines = [];
+  lines.push(`${c.bold("MergeGuard")}  ${c.dim(result.scope.label)}`);
+  lines.push(`${result.summary.filesReviewed} changed file${result.summary.filesReviewed === 1 ? "" : "s"} reviewed${result.summary.ignoredFiles ? ` · ${result.summary.ignoredFiles} ignored` : ""} · verifier: ${result.verifier}`);
+  if (result.warnings.length) for (const warning of result.warnings) lines.push(c.yellow(`warning: ${warning}`));
+  lines.push("");
+
+  if (!result.findings.length) {
+    lines.push(c.green("✓ No reportable issues found."));
+  } else {
+    for (const finding of result.findings) {
+      const sev = severityLabel(finding.severity, c);
+      const location = `${finding.file}${finding.startLine ? `:${finding.startLine}` : ""}`;
+      lines.push(`${sev}  ${c.bold(location)}`);
+      lines.push(c.bold(finding.title));
+      lines.push(finding.description);
+      if (finding.evidence?.[0]) lines.push(`${c.dim("Evidence:")} ${finding.evidence[0]}`);
+      if (finding.remediation) lines.push(`${c.dim("Fix:")} ${finding.remediation}`);
+      lines.push(`${c.dim("Confidence:")} ${Math.round(finding.confidence * 100)}% · ${c.dim("verified by:")} ${finding.verification.provider}`);
+      if (verbose) {
+        const v = finding.verification;
+        lines.push(c.dim(`plausible=${v.plausible} reachable=${v.reachable} impact=${v.impact} protection=${v.existingProtection} report=${v.worthReporting}`));
+      }
+      lines.push("");
+    }
+  }
+
+  const parts = ["critical", "high", "medium", "low", "info"].filter((s) => result.summary[s]).map((s) => `${result.summary[s]} ${s}`);
+  if (parts.length) lines.push(parts.join(" · "));
+  if (result.blocking) lines.push(c.red(c.bold(`BLOCKED — finding at or above '${result.failOn}' threshold.`)));
+  else lines.push(c.green(c.bold("PASS")));
+  return lines.join("\n");
+}
+
+function severityLabel(severity, c) {
+  const text = severity.toUpperCase().padEnd(8);
+  if (severity === "critical" || severity === "high") return c.red(text);
+  if (severity === "medium") return c.yellow(text);
+  if (severity === "low") return c.cyan(text);
+  return c.dim(text);
+}
+
+const wrap = (code) => (text) => `\x1b[${code}m${text}\x1b[0m`;
+const colors = { bold: wrap(1), dim: wrap(2), red: wrap(31), green: wrap(32), yellow: wrap(33), cyan: wrap(36) };
+const plain = { bold: String, dim: String, red: String, green: String, yellow: String, cyan: String };