@fitsummehari/mergeguard 0.1.0

package/examples/github/mergeguard.yml

@@ -0,0 +1,32 @@
+name: MergeGuard
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  security-events: write
+
+# Default: Node + offline verifier (reproducible). Optional Laya: see docs/LAYA.md.
+jobs:
+  mergeguard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Install MergeGuard
+        run: npm install --save-dev @fitsummehari/mergeguard
+      - name: Review pull request diff
+        run: npx mergeguard review --verifier offline --base "origin/${{ github.base_ref }}" --head "${{ github.event.pull_request.head.sha }}"
+      - name: Write SARIF
+        if: always()
+        run: npx mergeguard review --verifier offline --base "origin/${{ github.base_ref }}" --head "${{ github.event.pull_request.head.sha }}" --fail-on none --format sarif --output mergeguard.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        continue-on-error: true
+        with:
+          sarif_file: mergeguard.sarif

package/examples/gitlab/mergeguard.yml

@@ -0,0 +1,15 @@
+# Default: Node + offline verifier. Optional Laya: see docs/LAYA.md.
+mergeguard:
+  stage: test
+  image: node:22
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+  before_script:
+    - npm install --save-dev @fitsummehari/mergeguard
+    - git fetch origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+  script:
+    - npx mergeguard review --verifier offline --base "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" --head "$CI_COMMIT_SHA" --format gitlab --output gl-code-quality-report.json
+  artifacts:
+    when: always
+    reports:
+      codequality: gl-code-quality-report.json

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@fitsummehari/mergeguard",
+  "version": "0.1.0",
+  "description": "Local-first semantic code-change gate that reviews Git diffs before push or merge",
+  "type": "module",
+  "bin": {
+    "mergeguard": "bin/mergeguard.js"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src",
+    "scripts/laya_bridge.py",
+    "docs/ARCHITECTURE.md",
+    "docs/CONFIGURATION.md",
+    "docs/DETECTORS.md",
+    "docs/INTEGRATIONS.md",
+    "docs/LAYA.md",
+    "docs/LIMITATIONS.md",
+    "docs/MIGRATION_FROM_V1.md",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test --test-concurrency=1 tests/*.test.js",
+    "check": "node scripts/check.js",
+    "pack:list": "npm pack --dry-run",
+    "prepublishOnly": "npm run check"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FitsumMehari/MergeGuard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/FitsumMehari/MergeGuard/issues"
+  },
+  "homepage": "https://github.com/FitsumMehari/MergeGuard#readme",
+  "keywords": [
+    "git",
+    "code-review",
+    "pre-push",
+    "static-analysis",
+    "security",
+    "ci",
+    "sarif",
+    "semantic-analysis"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/laya_bridge.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""Tiny stdio bridge: Node MergeGuard -> local Python Laya. No server."""
+import json
+import sys
+
+
+def main():
+    payload = json.load(sys.stdin)
+    from laya import Router
+
+    router = Router(preload=False)
+    questions = payload["questions"]
+    model = payload.get("model")
+    max_len = int(payload.get("max_len") or 4096)
+    output = []
+    for item in payload.get("items", []):
+        kwargs = {"max_len": max_len}
+        if model:
+            kwargs["model"] = model
+        result = router.predict(item["state"], questions, **kwargs)
+        output.append({"id": item.get("id"), "answers": result.get("answers", {}), "routing": result.get("routing")})
+    json.dump({"items": output}, sys.stdout, ensure_ascii=False)
+
+
+if __name__ == "__main__":
+    main()

package/src/ci.js

@@ -0,0 +1,58 @@
+import { installSpec } from "./package-meta.js";
+
+export function githubWorkflow() {
+  const pkg = installSpec();
+  return `name: MergeGuard
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  security-events: write
+
+# Default: Node + offline verifier (reproducible). Optional Laya: see docs/LAYA.md.
+jobs:
+  mergeguard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Install MergeGuard
+        run: npm install --save-dev ${pkg}
+      - name: Review pull request diff
+        run: npx mergeguard review --verifier offline --base "origin/\${{ github.base_ref }}" --head "\${{ github.event.pull_request.head.sha }}"
+      - name: Write SARIF
+        if: always()
+        run: npx mergeguard review --verifier offline --base "origin/\${{ github.base_ref }}" --head "\${{ github.event.pull_request.head.sha }}" --fail-on none --format sarif --output mergeguard.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        continue-on-error: true
+        with:
+          sarif_file: mergeguard.sarif
+`;
+}
+
+export function gitlabWorkflow() {
+  const pkg = installSpec();
+  return `mergeguard:
+  stage: test
+  image: node:22
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+  # Default: Node + offline verifier. Optional Laya: see docs/LAYA.md.
+  before_script:
+    - npm install --save-dev ${pkg}
+    - git fetch origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+  script:
+    - npx mergeguard review --verifier offline --base "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" --head "$CI_COMMIT_SHA" --format gitlab --output gl-code-quality-report.json
+  artifacts:
+    when: always
+    reports:
+      codequality: gl-code-quality-report.json
+`;
+}

package/src/cli.js

@@ -0,0 +1,229 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { review } from "./review.js";
+import { renderReport } from "./reporters/index.js";
+import { installHook, uninstallHook, hookStatus } from "./hook.js";
+import { githubWorkflow, gitlabWorkflow } from "./ci.js";
+import { writeDefaultConfig } from "./config.js";
+import { repositoryRoot } from "./git.js";
+import { collectDoctorReport, formatDoctorReport } from "./doctor.js";
+import { VERSION } from "./version.js";
+
+const MACHINE_FORMATS = new Set(["json", "sarif", "gitlab"]);
+
+export async function main(argv) {
+  const args = [...argv];
+  if (args.includes("--version") || args[0] === "version") {
+    console.log(`mergeguard ${VERSION}`);
+    return 0;
+  }
+  if (args.includes("--help") || args[0] === "help" || args.length === 0) {
+    console.log(help());
+    return 0;
+  }
+  if (args[0]?.startsWith("-")) args.unshift("review");
+  const [command, ...rest] = args;
+  if (command === "review") return reviewCommand(rest);
+  if (command === "hook") return hookCommand(rest);
+  if (command === "init") return initCommand(rest);
+  if (command === "doctor") return doctorCommand(rest);
+  if (command === "ci") return ciCommand(rest);
+  throw new Error(`Unknown command '${command}'. Run mergeguard --help.`);
+}
+
+async function reviewCommand(args) {
+  const opts = parseArgs(args, {
+    booleans: new Set(["staged", "push", "no-ai", "verbose", "no-color", "no-untracked"]),
+    values: new Set(["base", "head", "format", "output", "fail-on", "verifier", "config", "confidence", "max-files", "max-candidates"]),
+  });
+  const format = opts.format || "terminal";
+  if (!["terminal", "json", "sarif", "gitlab"].includes(format)) {
+    throw new Error(`Unknown output format '${format}'. Use terminal, json, sarif, or gitlab.`);
+  }
+  let pushInput;
+  if (opts.push && !process.stdin.isTTY) pushInput = await readStdin();
+  const result = await review({
+    staged: opts.staged,
+    push: opts.push,
+    pushInput,
+    base: opts.base,
+    head: opts.head,
+    verifier: opts.verifier === "deterministic" ? "offline" : opts.verifier,
+    noAi: opts["no-ai"],
+    failOn: opts["fail-on"],
+    configPath: opts.config,
+    confidence: numberOption(opts.confidence),
+    maxFiles: intOption(opts["max-files"]),
+    maxCandidates: intOption(opts["max-candidates"]),
+    includeUntracked: !opts["no-untracked"],
+  });
+  const color = !opts["no-color"] && process.stdout.isTTY && format === "terminal";
+  const output = renderReport(result, format, { verbose: opts.verbose, color });
+  if (MACHINE_FORMATS.has(format)) process.stderr.write(`${briefStatus(result)}\n`);
+  if (opts.output) {
+    const dest = resolve(opts.output);
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, output.endsWith("\n") ? output : `${output}\n`);
+    if (MACHINE_FORMATS.has(format)) process.stderr.write(`MergeGuard wrote ${format} report to ${dest}\n`);
+    else process.stdout.write(output.endsWith("\n") ? output : `${output}\n`);
+  } else {
+    process.stdout.write(output.endsWith("\n") ? output : `${output}\n`);
+  }
+  return result.blocking ? 1 : 0;
+}
+
+function briefStatus(result) {
+  const counts = ["critical", "high", "medium", "low", "info"].filter((s) => result.summary[s]).map((s) => `${result.summary[s]} ${s}`);
+  const body = counts.length ? counts.join(", ") : "no reportable findings";
+  return `MergeGuard: ${result.findings.length} finding${result.findings.length === 1 ? "" : "s"} (${body}) — ${result.passed ? "PASS" : "BLOCKED"}`;
+}
+
+function hookCommand(args) {
+  const action = args[0] || "status";
+  const force = args.includes("--force");
+  if (action === "install") {
+    const result = installHook(process.cwd(), { force });
+    console.log(`${result.message}\n${result.path}`);
+    return 0;
+  }
+  if (action === "uninstall") {
+    const result = uninstallHook();
+    console.log(`${result.message}\n${result.path}`);
+    return 0;
+  }
+  if (action === "status") {
+    const result = hookStatus();
+    console.log(result.installed ? `installed: ${result.path}` : `not installed: ${result.path}`);
+    return 0;
+  }
+  throw new Error("Usage: mergeguard hook install|uninstall|status [--force]");
+}
+
+function initCommand(args) {
+  let root;
+  try { root = repositoryRoot(); } catch { root = process.cwd(); }
+  const path = writeDefaultConfig(root, { force: args.includes("--force") });
+  console.log(`Created ${path}`);
+  if (args.includes("--hook")) {
+    const result = installHook(root);
+    console.log(result.message);
+  }
+  return 0;
+}
+
+function doctorCommand(args = []) {
+  const report = collectDoctorReport();
+  if (args.includes("--json")) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  } else {
+    console.log(formatDoctorReport(report));
+  }
+  return report.ok ? 0 : 2;
+}
+
+function ciCommand(args) {
+  const provider = args[0];
+  const write = args.includes("--write");
+  const force = args.includes("--force");
+  let text;
+  let dest;
+  if (provider === "github") {
+    text = githubWorkflow();
+    dest = ".github/workflows/mergeguard.yml";
+  } else if (provider === "gitlab") {
+    text = gitlabWorkflow();
+    dest = ".gitlab-ci.mergeguard.yml";
+  } else {
+    throw new Error("Usage: mergeguard ci github|gitlab [--write] [--force]");
+  }
+  if (!write) {
+    process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+    return 0;
+  }
+  const root = repositoryRoot();
+  const path = resolve(root, dest);
+  if (existsSync(path) && !force) throw new Error(`${path} already exists (use --force to replace it)`);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, text.endsWith("\n") ? text : `${text}\n`);
+  console.log(`Wrote ${path}`);
+  return 0;
+}
+
+function parseArgs(args, schema) {
+  const out = {};
+  for (let i = 0; i < args.length; i++) {
+    const token = args[i];
+    if (!token.startsWith("--")) throw new Error(`Unexpected argument '${token}'`);
+    const eq = token.indexOf("=");
+    const key = token.slice(2, eq > 0 ? eq : undefined);
+    if (schema.booleans.has(key)) {
+      out[key] = true;
+      continue;
+    }
+    if (!schema.values.has(key)) throw new Error(`Unknown option '--${key}'`);
+    const value = eq > 0 ? token.slice(eq + 1) : args[++i];
+    if (value === undefined || value.startsWith("--")) throw new Error(`Option '--${key}' requires a value`);
+    out[key] = value;
+  }
+  return out;
+}
+
+function numberOption(value) {
+  if (value === undefined) return undefined;
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0 || n > 1) throw new Error("--confidence must be between 0 and 1");
+  return n;
+}
+
+function intOption(value) {
+  if (value === undefined) return undefined;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1) throw new Error("numeric limit options must be positive integers");
+  return n;
+}
+
+async function readStdin() {
+  let text = "";
+  for await (const chunk of process.stdin) text += chunk;
+  return text;
+}
+
+function help() {
+  return `MergeGuard ${VERSION}
+Local-first semantic code-change gate for Git diffs.
+
+USAGE
+  mergeguard review [options]
+  mergeguard hook install|uninstall|status
+  mergeguard init [--hook] [--force]
+  mergeguard doctor [--json]
+  mergeguard ci github|gitlab [--write] [--force]
+
+REVIEW SCOPES
+  mergeguard review                     Working tree + staged + untracked vs HEAD
+  mergeguard review --staged            Staged changes only
+  mergeguard review --base main         Branch diff from merge-base(main, HEAD)
+  mergeguard review --base main --head SHA
+  mergeguard review --push              Outgoing commits (normally called by pre-push hook)
+
+OPTIONS
+  --format terminal|json|sarif|gitlab  (machine formats stay parseable on stdout)
+  --output FILE
+  --fail-on critical|high|medium|low|info|none
+  --verifier auto|offline|deterministic|laya|jev
+  --no-ai                               Force deterministic/offline verification
+  --config FILE                         Explicit config path
+  --confidence 0..1
+  --max-files N
+  --max-candidates N
+  --no-untracked
+  --verbose
+  --no-color
+  --version
+
+EXIT CODES
+  0  Review completed; no blocking finding
+  1  Review completed; blocking finding present
+  2  MergeGuard/config/runtime failure
+`;
+}

package/src/config.js

@@ -0,0 +1,137 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { CATEGORIES, SEVERITIES, parseSimpleYaml } from "./utils.js";
+
+export const defaultConfig = Object.freeze({
+  version: 1,
+  failOn: "high",
+  verifier: "offline",
+  confidence: 0.62,
+  maxFiles: 300,
+  maxCandidates: 120,
+  contextFiles: 24,
+  contextChars: 18_000,
+  ignore: [
+    "node_modules/**", "vendor/**", "dist/**", "build/**", "coverage/**", ".next/**", ".git/**",
+    "**/*.min.js", "**/*.map", "**/generated/**",
+  ],
+  categories: Object.fromEntries(CATEGORIES.map((category) => [category, true])),
+  laya: { python: undefined, model: undefined, maxLen: 4096 },
+  jev: { url: "https://api.typesafe.ai/v1/systemone", model: "jev-latest" },
+});
+
+export function loadConfig(root, explicitPath) {
+  const candidates = explicitPath
+    ? [resolve(root, explicitPath)]
+    : [resolve(root, ".mergeguard.yml"), resolve(root, ".mergeguard.yaml"), resolve(root, ".mergeguard.json")];
+  const path = candidates.find(existsSync);
+  if (!path) return { config: structuredClone(defaultConfig), path: undefined, warnings: [] };
+  let parsed;
+  const text = readFileSync(path, "utf8");
+  try {
+    parsed = path.endsWith(".json") ? JSON.parse(text) : parseSimpleYaml(text);
+  } catch (error) {
+    throw new Error(`Could not parse ${path}: ${error.message}`);
+  }
+  return { config: normalizeConfig(parsed), path, warnings: unknownKeyWarnings(parsed, path) };
+}
+
+export function normalizeConfig(input = {}) {
+  const config = structuredClone(defaultConfig);
+  if (input.fail_on !== undefined || input.failOn !== undefined) {
+    const failOn = String(input.fail_on ?? input.failOn).toLowerCase();
+    if (![...SEVERITIES, "none"].includes(failOn)) throw new Error(`fail_on must be one of: ${[...SEVERITIES, "none"].join(", ")}`);
+    config.failOn = failOn;
+  }
+  if (input.verifier !== undefined) {
+    let verifier = typeof input.verifier === "object" ? input.verifier.engine : input.verifier;
+    if (verifier === "deterministic") verifier = "offline";
+    if (verifier && !["auto", "offline", "laya", "jev"].includes(verifier)) throw new Error("verifier must be auto, offline, deterministic, laya, or jev");
+    if (verifier) config.verifier = verifier;
+  }
+  if (input.confidence !== undefined) {
+    const value = Number(typeof input.confidence === "object" ? input.confidence.report : input.confidence);
+    if (Number.isFinite(value) && value >= 0 && value <= 1) config.confidence = value;
+  }
+  const maxFiles = Number(input.max_files ?? input.maxFiles);
+  if (Number.isInteger(maxFiles) && maxFiles > 0) config.maxFiles = Math.min(maxFiles, 5000);
+  const maxCandidates = Number(input.max_candidates ?? input.maxCandidates);
+  if (Number.isInteger(maxCandidates) && maxCandidates > 0) config.maxCandidates = Math.min(maxCandidates, 1000);
+  const contextFiles = Number(input.context_files ?? input.contextFiles);
+  if (Number.isInteger(contextFiles) && contextFiles > 0) config.contextFiles = Math.min(contextFiles, 100);
+  const contextChars = Number(input.context_chars ?? input.contextChars);
+  if (Number.isInteger(contextChars) && contextChars > 0) config.contextChars = Math.min(contextChars, 200_000);
+
+  const ignore = input.exclude?.paths ?? input.exclude ?? input.ignore?.paths ?? input.ignore;
+  if (Array.isArray(ignore)) config.ignore = ignore.filter((x) => typeof x === "string" && x.trim());
+
+  const review = input.review ?? input.categories;
+  if (review && typeof review === "object") {
+    for (const category of CATEGORIES) {
+      if (typeof review[category] === "boolean") config.categories[category] = review[category];
+    }
+  }
+
+  if (input.laya && typeof input.laya === "object") {
+    if (input.laya.python) config.laya.python = String(input.laya.python);
+    if (input.laya.model) config.laya.model = String(input.laya.model);
+    const maxLen = Number(input.laya.max_len ?? input.laya.maxLen);
+    if (Number.isInteger(maxLen) && maxLen >= 256) config.laya.maxLen = Math.min(maxLen, 8192);
+  }
+  if (input.jev && typeof input.jev === "object") {
+    if (input.jev.url) config.jev.url = String(input.jev.url);
+    if (input.jev.model) config.jev.model = String(input.jev.model);
+  }
+  return config;
+}
+
+export function writeDefaultConfig(root, { force = false } = {}) {
+  const path = resolve(root, ".mergeguard.yml");
+  if (existsSync(path) && !force) throw new Error(`${path} already exists (use --force to replace it)`);
+  const text = [
+    "# MergeGuard configuration",
+    "version: 1",
+    "fail_on: high",
+    "# Use offline in CI for identical results across machines.",
+    "# auto picks local Laya when installed and is environment-dependent.",
+    "verifier:",
+    "  engine: offline",
+    "",
+    "confidence: 0.62",
+    "",
+    "exclude:",
+    "  - node_modules/**",
+    "  - vendor/**",
+    "  - dist/**",
+    "  - build/**",
+    "  - coverage/**",
+    "  - generated/**",
+    "",
+    "review:",
+    "  correctness: true",
+    "  security: true",
+    "  concurrency: true",
+    "  database: true",
+    "  authorization: true",
+    "  tenant-isolation: true",
+    "  reliability: true",
+    "  performance: true",
+    "  api: true",
+    "",
+  ].join("\n");
+  writeFileSync(path, text);
+  return path;
+}
+
+const KNOWN_ROOT_KEYS = new Set([
+  "version", "fail_on", "failOn", "verifier", "confidence", "ignore", "exclude", "review",
+  "categories", "laya", "jev", "max_files", "maxFiles", "max_candidates", "maxCandidates",
+  "context_files", "contextFiles", "context_chars", "contextChars",
+]);
+
+function unknownKeyWarnings(parsed, path) {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return [];
+  return Object.keys(parsed)
+    .filter((key) => !KNOWN_ROOT_KEYS.has(key))
+    .map((key) => `${path}: unknown config key '${key}' was ignored`);
+}