@nugehs/bouncer 0.1.0

package/src/lib/doctor.js

@@ -0,0 +1,49 @@
+import fs from "node:fs";
+import { loadPacks } from "./packs.js";
+import { buildContext } from "./engine.js";
+
+/** Sanity-check that config resolves, the target repo exists, the adapter loads, and packs parse. */
+export function getDoctorReport(cfg) {
+  const checks = [];
+
+  const repoOk = fs.existsSync(cfg.target.repoRoot);
+  checks.push({ name: "target repo", ok: repoOk, detail: cfg.target.repoRoot });
+
+  let filesScanned = 0;
+  let adapterOk = false;
+  try {
+    const ctx = buildContext(cfg);
+    adapterOk = true;
+    filesScanned = ctx.files.length;
+  } catch (error) {
+    checks.push({ name: "adapter", ok: false, detail: error.message });
+  }
+  if (adapterOk) {
+    checks.push({ name: "adapter", ok: true, detail: `${cfg.target.adapter} · ${filesScanned} files visible` });
+  }
+
+  let packsOk = false;
+  let packList = [];
+  try {
+    const packs = loadPacks(cfg);
+    packsOk = true;
+    packList = packs.map((p) => `${p.id} (${p.rules.length} rules)`);
+  } catch (error) {
+    checks.push({ name: "packs", ok: false, detail: error.message });
+  }
+  if (packsOk) {
+    checks.push({ name: "packs", ok: true, detail: packList.join(", ") });
+  }
+
+  const ok = checks.every((c) => c.ok);
+  return { ok, configPath: cfg._path, checks };
+}
+
+export function formatDoctorReport(report) {
+  const lines = ["", "  bouncer doctor", `  config: ${report.configPath}`, ""];
+  for (const c of report.checks) {
+    lines.push(`    ${c.ok ? "✓" : "✗"} ${c.name}: ${c.detail}`);
+  }
+  lines.push("", `  ${report.ok ? "✓ all checks passed" : "✗ some checks failed"}`, "");
+  return lines.join("\n");
+}

package/src/lib/engine.js

@@ -0,0 +1,229 @@
+import fs from "node:fs";
+import path from "node:path";
+import { walk, matchesAnyGlob } from "./walk.js";
+import * as nextAdapter from "./adapters/next.js";
+import * as reactNativeAdapter from "./adapters/react-native.js";
+
+const ADAPTERS = {
+  next: nextAdapter,
+  "react-native": reactNativeAdapter,
+};
+
+const MAX_HITS_PER_RULE = 8;
+
+/**
+ * Build a scan context for a target repo: the list of relative source paths plus a
+ * lazy, cached file reader. Shared across every rule so the repo is walked once.
+ */
+function buildContext(cfg) {
+  const adapter = ADAPTERS[cfg.target.adapter];
+  if (!adapter) throw new Error(`Unknown target adapter: ${cfg.target.adapter}`);
+
+  const root = cfg.target.repoRoot;
+  const exts = new Set(adapter.SOURCE_EXT);
+  const roots = cfg.target.roots && cfg.target.roots.length ? cfg.target.roots : ["."];
+
+  const files = [];
+  const seen = new Set();
+  for (const r of roots) {
+    const base = path.resolve(root, r);
+    for (const abs of walk(base, (name) => extOk(name, exts))) {
+      if (seen.has(abs)) continue;
+      seen.add(abs);
+      files.push({ abs, rel: path.relative(root, abs).split(path.sep).join("/") });
+    }
+  }
+
+  const cache = new Map();
+  const readFile = (abs) => {
+    if (cache.has(abs)) return cache.get(abs);
+    let text = "";
+    try {
+      text = fs.readFileSync(abs, "utf8");
+    } catch {
+      text = "";
+    }
+    cache.set(abs, text);
+    return text;
+  };
+
+  return { adapter, files, readFile, root };
+}
+
+function extOk(name, exts) {
+  // governance artifacts may be .md/.mdx/.pdf — allow anything; ext-filtering is a
+  // soft optimisation, surface globs do the real narrowing.
+  const dot = name.lastIndexOf(".");
+  if (dot === -1) return false;
+  const ext = name.slice(dot);
+  return exts.has(ext) || [".md", ".mdx", ".json", ".yml", ".yaml", ".pdf"].includes(ext);
+}
+
+/**
+ * Evaluate one assertion node.
+ * Returns { ok, hits, scanned } where `scanned` is how many files the node looked at
+ * (0 => the surface could not be located => the rule is "unknown", not a pass).
+ */
+function evalNode(node, ctx) {
+  if (!node || typeof node !== "object") {
+    throw new Error(`Invalid assertion node: ${JSON.stringify(node)}`);
+  }
+
+  if (Array.isArray(node.allOf)) {
+    const parts = node.allOf.map((n) => evalNode(n, ctx));
+    return {
+      ok: parts.every((p) => p.ok),
+      hits: parts.flatMap((p) => p.hits),
+      scanned: parts.reduce((a, p) => a + p.scanned, 0),
+    };
+  }
+
+  if (Array.isArray(node.anyOf)) {
+    const parts = node.anyOf.map((n) => evalNode(n, ctx));
+    return {
+      ok: parts.some((p) => p.ok),
+      hits: parts.filter((p) => p.ok).flatMap((p) => p.hits),
+      scanned: parts.reduce((a, p) => a + p.scanned, 0),
+    };
+  }
+
+  if (node.not) {
+    const r = evalNode(node.not, ctx);
+    return { ok: !r.ok, hits: r.hits, scanned: r.scanned };
+  }
+
+  if (typeof node.find === "string") {
+    return evalFind(node, ctx);
+  }
+
+  if (Array.isArray(node.allInFile)) {
+    return evalAllInFile(node, ctx);
+  }
+
+  throw new Error(`Assertion node has no allOf/anyOf/not/find/allInFile: ${JSON.stringify(node)}`);
+}
+
+function evalFind(node, ctx) {
+  const globs = ctx.adapter.resolveSurface(node.in ?? "any");
+  const expect = node.expect === "absent" ? "absent" : "present";
+  let regex;
+  try {
+    regex = new RegExp(node.find, node.flags || "i");
+  } catch (error) {
+    throw new Error(`Bad regex in rule (find: ${node.find}): ${error.message}`);
+  }
+
+  const matchedFiles = ctx.files.filter((f) => matchesAnyGlob(f.rel, globs));
+  const hits = [];
+  for (const f of matchedFiles) {
+    const text = ctx.readFile(f.abs);
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      if (regex.test(lines[i])) {
+        hits.push({ file: f.rel, line: i + 1, excerpt: lines[i].trim().slice(0, 160) });
+        if (hits.length >= MAX_HITS_PER_RULE) break;
+      }
+    }
+    if (hits.length >= MAX_HITS_PER_RULE) break;
+  }
+
+  const present = hits.length > 0;
+  const ok = expect === "absent" ? !present : present;
+  return { ok, hits, scanned: matchedFiles.length };
+}
+
+// Stronger probe: every pattern must co-occur in a SINGLE file — and, when
+// `within` is set, within a window of that many lines of each other (i.e. the same
+// settings block / object literal). The window is what makes this meaningfully
+// more precise than "all appear somewhere in a big file".
+function evalAllInFile(node, ctx) {
+  const globs = ctx.adapter.resolveSurface(node.in ?? "any");
+  const expect = node.expect === "absent" ? "absent" : "present";
+  const within = Number.isFinite(node.within) ? node.within : null;
+  let regexes;
+  try {
+    regexes = node.allInFile.map((p) => new RegExp(p, node.flags || "i"));
+  } catch (error) {
+    throw new Error(`Bad regex in rule (allInFile): ${error.message}`);
+  }
+
+  const matchedFiles = ctx.files.filter((f) => matchesAnyGlob(f.rel, globs));
+  let satisfied = false;
+  const hits = [];
+  for (const f of matchedFiles) {
+    const text = ctx.readFile(f.abs);
+    const lines = text.split("\n");
+    // For each pattern, the set of line numbers (0-based) it matches.
+    const perPattern = regexes.map((re) => {
+      const ls = [];
+      for (let i = 0; i < lines.length; i++) if (re.test(lines[i])) ls.push(i);
+      return ls;
+    });
+    if (perPattern.some((ls) => ls.length === 0)) continue; // a pattern is absent → file can't satisfy
+
+    const anchor = findWindow(perPattern, within);
+    if (anchor) {
+      satisfied = true;
+      for (let p = 0; p < regexes.length; p++) {
+        const ln = anchor[p];
+        hits.push({ file: f.rel, line: ln + 1, excerpt: lines[ln].trim().slice(0, 160) });
+      }
+      break;
+    }
+  }
+
+  const ok = expect === "absent" ? !satisfied : satisfied;
+  return { ok, hits: hits.slice(0, MAX_HITS_PER_RULE), scanned: matchedFiles.length };
+}
+
+// Find one matching line per pattern such that max-min <= within. With no window,
+// any combination works (first match of each). Returns the chosen line per pattern.
+function findWindow(perPattern, within) {
+  if (within == null) return perPattern.map((ls) => ls[0]);
+  // Anchor on each match of the first pattern; require every other pattern to have
+  // a match inside [anchor - within, anchor + within].
+  for (const anchor of perPattern[0]) {
+    const chosen = [anchor];
+    let ok = true;
+    for (let p = 1; p < perPattern.length; p++) {
+      const near = perPattern[p].find((ln) => Math.abs(ln - anchor) <= within);
+      if (near === undefined) {
+        ok = false;
+        break;
+      }
+      chosen.push(near);
+    }
+    if (ok) return chosen;
+  }
+  return null;
+}
+
+/** Evaluate a single rule into a finding. */
+export function evalRule(rule, ctx, packMeta) {
+  const r = evalNode(rule.assert, ctx);
+  let status;
+  if (r.scanned === 0) status = "unknown";
+  else status = r.ok ? "pass" : "fail";
+
+  return {
+    packId: packMeta.id,
+    packTitle: packMeta.title,
+    authority: packMeta.authority,
+    ruleId: rule.id,
+    standard: rule.standard,
+    severity: rule.severity || "medium",
+    surface: surfaceLabel(rule.surface ?? rule.assert),
+    intent: rule.intent,
+    fix: rule.fix,
+    status,
+    scanned: r.scanned,
+    hits: r.hits.slice(0, MAX_HITS_PER_RULE),
+  };
+}
+
+function surfaceLabel(spec) {
+  if (typeof spec === "string") return spec;
+  return undefined;
+}
+
+export { buildContext };

package/src/lib/init.js

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CONFIG_TEMPLATE } from "./config.js";
+
+/** Write a starter bouncer.config.json into `dir` (default cwd). Never overwrites without --force. */
+export function initProject(dir = ".", { force = false } = {}) {
+  const target = path.resolve(dir, "bouncer.config.json");
+  if (fs.existsSync(target) && !force) {
+    return { created: false, path: target, reason: "exists (use --force to overwrite)" };
+  }
+  fs.writeFileSync(target, JSON.stringify(CONFIG_TEMPLATE, null, 2) + "\n");
+  return { created: true, path: target };
+}
+
+export function formatInitSummary(result) {
+  if (result.created) {
+    return `\n  ✓ wrote ${result.path}\n\n  Next:\n    bouncer check\n    bouncer report --out bouncer-report.html\n`;
+  }
+  return `\n  • ${result.path} already ${result.reason}\n`;
+}

package/src/lib/mcp.js

@@ -0,0 +1,195 @@
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { fileURLToPath } from "node:url";
+import { loadConfig } from "./config.js";
+import { runCheck, listRules, explainRule, availablePacks } from "./packs.js";
+
+const protocolVersion = "2025-06-18";
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+
+const tools = [
+  {
+    name: "compliance_check",
+    title: "Compliance Controls Check",
+    description:
+      "Run the configured regulation rule packs against the target repo and return per-control verdicts (pass/fail/unknown) with file-level evidence. Deterministic; no LLM involved.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        config: { type: "string", description: "Path to bouncer.config.json. Defaults to searching up from cwd." },
+        packs: { type: "array", items: { type: "string" }, description: "Restrict to these pack ids (e.g. uk-osa, uk-aadc)." },
+        status: { type: "string", description: "Filter findings: fail, unknown, or all (default)." },
+      },
+    },
+  },
+  {
+    name: "list_rules",
+    title: "List Compliance Rules",
+    description: "List every rule the configured packs apply, with standard, severity, and surface. No scanning.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        config: { type: "string", description: "Path to bouncer.config.json." },
+      },
+    },
+  },
+  {
+    name: "explain_rule",
+    title: "Explain Compliance Rule",
+    description: "Explain a single rule: the legal standard, intent, fix, and exactly how bouncer checks it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ruleId: { type: "string", description: "Rule id, e.g. aadc.geolocation-default-off." },
+        config: { type: "string", description: "Path to bouncer.config.json." },
+      },
+      required: ["ruleId"],
+    },
+  },
+  {
+    name: "list_packs",
+    title: "List Rule Packs",
+    description: "List the regulation rule packs bundled with bouncer (and any local pack dirs).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        config: { type: "string", description: "Optional bouncer.config.json to include its packDirs." },
+      },
+    },
+  },
+];
+
+export async function startMcpServer({ input = process.stdin, output = process.stdout } = {}) {
+  // A client that hangs up mid-write produces EPIPE; exit quietly rather than crash-logging.
+  output.on("error", (err) => {
+    if (err && err.code === "EPIPE") process.exit(0);
+    throw err;
+  });
+
+  const rl = readline.createInterface({ input, crlfDelay: Infinity });
+
+  for await (const line of rl) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    let message;
+    try {
+      message = JSON.parse(trimmed);
+    } catch (error) {
+      writeMessage(output, errorResponse(null, -32700, `Parse error: ${error.message}`));
+      continue;
+    }
+
+    const response = await handleMessage(message);
+    if (response) writeMessage(output, response);
+  }
+}
+
+async function handleMessage(message) {
+  if (!message || message.jsonrpc !== "2.0" || typeof message.method !== "string") {
+    return errorResponse(message?.id ?? null, -32600, "Invalid JSON-RPC request");
+  }
+
+  try {
+    switch (message.method) {
+      case "initialize":
+        return successResponse(message.id, {
+          protocolVersion,
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: packageJson.name, version: packageJson.version },
+        });
+      case "notifications/initialized":
+        return undefined;
+      case "ping":
+        return successResponse(message.id, {});
+      case "tools/list":
+        return successResponse(message.id, { tools });
+      case "tools/call":
+        return successResponse(message.id, await callTool(message.params));
+      default:
+        return errorResponse(message.id, -32601, `Method not found: ${message.method}`);
+    }
+  } catch (error) {
+    const code = error instanceof McpProtocolError ? error.code : -32603;
+    return errorResponse(message.id, code, error instanceof Error ? error.message : String(error));
+  }
+}
+
+async function callTool(params = {}) {
+  if (!params || typeof params !== "object") throw new McpProtocolError(-32602, "Tool call params must be an object");
+  const name = params.name;
+  if (typeof name !== "string" || !name.trim()) throw new McpProtocolError(-32602, "Tool name is required");
+  const args = params.arguments ?? {};
+  if (!args || typeof args !== "object" || Array.isArray(args)) {
+    throw new McpProtocolError(-32602, "Tool arguments must be an object");
+  }
+
+  let result;
+  try {
+    result = dispatchTool(name, args);
+  } catch (error) {
+    if (error instanceof McpProtocolError) throw error;
+    return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true };
+  }
+
+  return {
+    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    structuredContent: result,
+    isError: false,
+  };
+}
+
+function dispatchTool(name, args) {
+  switch (name) {
+    case "compliance_check": {
+      const cfg = withPacks(loadConfig(args.config), args.packs);
+      const result = runCheck(cfg);
+      const filter = args.status || "all";
+      if (filter !== "all") {
+        result.findings = result.findings.filter((f) => (filter === "fail" ? f.status === "fail" : f.status !== "pass"));
+      }
+      return result;
+    }
+    case "list_rules":
+      return { rules: listRules(loadConfig(args.config)) };
+    case "explain_rule":
+      return explainRule(loadConfig(args.config), requiredString(args.ruleId, "ruleId"));
+    case "list_packs": {
+      const dirs = args.config ? loadConfig(args.config).packDirs : [];
+      return { packs: availablePacks(dirs) };
+    }
+    default:
+      throw new McpProtocolError(-32601, `Unknown tool: ${name}`);
+  }
+}
+
+function withPacks(cfg, packs) {
+  if (Array.isArray(packs) && packs.length) cfg.packs = packs;
+  return cfg;
+}
+
+function requiredString(value, label) {
+  if (typeof value !== "string" || !value.trim()) throw new McpProtocolError(-32602, `${label} is required`);
+  return value;
+}
+
+function successResponse(id, result) {
+  return { jsonrpc: "2.0", id, result };
+}
+
+function errorResponse(id, code, message) {
+  return { jsonrpc: "2.0", id, error: { code, message } };
+}
+
+function writeMessage(output, message) {
+  output.write(JSON.stringify(message) + "\n");
+}
+
+class McpProtocolError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}

package/src/lib/output.js

@@ -0,0 +1,49 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function printText(text) {
+  process.stdout.write(`${text}\n`);
+}
+
+export function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function writeArtifact(targetPath, contents) {
+  const absolutePath = path.resolve(targetPath);
+  fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+  fs.writeFileSync(absolutePath, contents);
+  return { path: absolutePath };
+}
+
+export function printHelp() {
+  printText(`bouncer — static compliance-controls checker
+
+Verifies the controls a regulation requires actually exist in your code,
+expressed as deterministic rule packs. Runs in CI. No LLM required.
+
+Usage:
+  bouncer check [--config file] [--pack id...] [--status fail|unknown|all] [--json] [--no-fail]
+  bouncer report [--config file] [--out file]      Write a self-contained HTML audit report
+  bouncer list [--config file] [--json]            List every rule the configured packs apply
+  bouncer explain <ruleId> [--config file]         Show what a rule requires and how it is checked
+  bouncer packs [--json]                           List the rule packs shipped with bouncer
+  bouncer init [path]                              Write a starter bouncer.config.json
+  bouncer doctor [--config file] [--json]          Sanity-check config, adapter, and pack loading
+  bouncer mcp                                      Start the MCP server (stdio)
+  bouncer help
+
+Examples:
+  bouncer init .
+  bouncer check
+  bouncer check --pack uk-aadc --status fail
+  bouncer report --out bouncer-report.html
+  bouncer explain aadc.geolocation-default-off
+  bouncer packs
+
+Verdicts:
+  pass     the required control was found
+  fail     the control is required for a surface that exists, but no evidence was found
+  unknown  the surface could not be located in this repo (can't determine — not a pass)
+`);
+}