claude-crap 0.1.2

package/plugin/hooks/lib/hook-io.mjs

@@ -0,0 +1,151 @@
+// @ts-check
+/**
+ * Shared I/O helpers for every claude-crap hook script.
+ *
+ * Every hook in the plugin shares the same stdin/stdout/stderr contract
+ * with Claude Code (see https://code.claude.com/docs/en/hooks):
+ *
+ *   - stdin  : JSON payload with `session_id`, `tool_name`, `tool_input`,
+ *              `tool_response`, `hook_event_name`, ...
+ *   - stdout : Free-form text, stored in the hooks transcript.
+ *   - stderr : Injected into the agent's context when the hook exits
+ *              with code 2 (blocking) or captured for diagnostics when
+ *              the hook exits with any non-zero code.
+ *
+ * This module factors that contract out so individual hooks can focus
+ * on their rules and not re-implement stdin parsing or error framing.
+ *
+ * @module hooks/lib/hook-io
+ */
+
+/**
+ * Exit codes accepted by Claude Code hooks.
+ *
+ * - `ALLOW` (0)   — hook passed, tool call proceeds.
+ * - `BLOCK` (2)   — hook blocks the tool call; stderr goes to the agent.
+ * - `INTERNAL` (1) — hook itself errored; fail-open semantics applied.
+ */
+export const ExitCodes = Object.freeze({
+  ALLOW: 0,
+  INTERNAL: 1,
+  BLOCK: 2,
+});
+
+/**
+ * Read stdin to EOF and parse it as JSON.
+ *
+ * @returns {Promise<object>} The parsed JSON payload.
+ * @throws  When stdin is empty or not valid JSON.
+ */
+export async function readStdinJson() {
+  /** @type {Buffer[]} */
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(/** @type {Buffer} */ (chunk));
+  }
+  const raw = Buffer.concat(chunks).toString("utf8").trim();
+  if (!raw) {
+    throw new Error("stdin was empty — claude-crap hook expected a JSON payload");
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`stdin is not valid JSON: ${/** @type {Error} */ (err).message}`);
+  }
+}
+
+/**
+ * Render a blocking message framed in the same box style used by the
+ * PreToolUse hook. The agent sees this text on stderr when a blocking
+ * hook exits with code 2, so it must be imperative and corrective.
+ *
+ * @param {Object} opts
+ * @param {string} opts.title   - Short hook identifier (e.g. `"PostToolUse"`, `"Stop gate"`).
+ * @param {string} opts.ruleId  - Stable rule identifier.
+ * @param {string} opts.tool    - The tool call being evaluated (or `"-"`).
+ * @param {string} opts.reason  - The corrective message for the agent.
+ * @returns {string}             A multi-line formatted box.
+ */
+export function formatBlockingMessage({ title, ruleId, tool, reason }) {
+  return [
+    `╭─ claude-crap :: ${title} BLOCKED ───────────────────────────────`,
+    `│ rule : ${ruleId}`,
+    `│ tool : ${tool}`,
+    `│`,
+    ...reason.split("\n").map((line) => `│ ${line}`),
+    `╰──────────────────────────────────────────────────────────────────`,
+  ].join("\n");
+}
+
+/**
+ * Render a non-blocking warning. PostToolUse emits these on stderr; the
+ * LLM reads them but the tool call is not aborted. The format is
+ * intentionally different from a block so the agent can tell them apart.
+ *
+ * @param {Object} opts
+ * @param {string} opts.title
+ * @param {string} opts.ruleId
+ * @param {string} opts.tool
+ * @param {string} opts.reason
+ * @returns {string}
+ */
+export function formatWarningMessage({ title, ruleId, tool, reason }) {
+  return [
+    `┌─ claude-crap :: ${title} WARNING ───────────────────────────────`,
+    `│ rule : ${ruleId}`,
+    `│ tool : ${tool}`,
+    `│`,
+    ...reason.split("\n").map((line) => `│ ${line}`),
+    `└──────────────────────────────────────────────────────────────────`,
+  ].join("\n");
+}
+
+/**
+ * Print a blocking message to stderr and exit with code 2.
+ * Does not return.
+ *
+ * @param {Object} opts
+ * @param {string} opts.title
+ * @param {string} opts.ruleId
+ * @param {string} opts.tool
+ * @param {string} opts.reason
+ * @returns {never}
+ */
+export function blockAndExit(opts) {
+  process.stderr.write(formatBlockingMessage(opts) + "\n");
+  process.exit(ExitCodes.BLOCK);
+}
+
+/**
+ * Print a warning to stderr without blocking. Returns so the caller
+ * can keep processing additional findings.
+ *
+ * @param {Object} opts
+ * @param {string} opts.title
+ * @param {string} opts.ruleId
+ * @param {string} opts.tool
+ * @param {string} opts.reason
+ */
+export function warnNonBlocking(opts) {
+  process.stderr.write(formatWarningMessage(opts) + "\n");
+}
+
+/**
+ * Wrap a hook's `main` function in a uniform failure harness. When the
+ * user code throws, we log the error to stderr and exit with the
+ * INTERNAL code — the user is never deadlocked by a broken hook.
+ *
+ * @param {string} hookName         Human-readable hook identifier for logs.
+ * @param {() => Promise<void>} fn  Async entrypoint.
+ */
+export async function runHook(hookName, fn) {
+  try {
+    await fn();
+  } catch (err) {
+    process.stderr.write(
+      `[claude-crap] ${hookName}: internal error: ${/** @type {Error} */ (err).message}\n` +
+        `[claude-crap] falling back to permissive mode (fail-open).\n`,
+    );
+    process.exit(ExitCodes.INTERNAL);
+  }
+}

package/plugin/hooks/lib/quality-gate.mjs

@@ -0,0 +1,329 @@
+// @ts-check
+/**
+ * Shared quality-gate evaluator used by the Stop and SubagentStop hooks.
+ *
+ * The evaluator is a pure function of:
+ *
+ *   - the current claude-crap configuration (read from env),
+ *   - the consolidated SARIF file on disk (optional — a missing file
+ *     is treated as "no findings yet"),
+ *   - a coarse workspace LOC count (bounded walk of the project tree).
+ *
+ * It produces a structured verdict with one `failures[]` entry per
+ * violated policy. The calling hook then decides whether to block
+ * (exit 2) or allow (exit 0) based on whether any failures were found.
+ *
+ * Engine imports (CRAP / TDR letter classification) come from the
+ * esbuild-produced bundle at `plugin/bundle/tdr-engine.mjs`, so the
+ * math stays in one place and the hook cannot drift from the server.
+ *
+ * @module hooks/lib/quality-gate
+ */
+
+import { promises as fs } from "node:fs";
+import { resolve, join, isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+
+// Import the TDR engines from the bundled MCP server. The relative path
+// resolves from `hooks/lib/` up to `plugin/bundle/`. Requires the
+// plugin to have been built at least once via `npm run build:plugin`.
+const HOOK_DIR = dirname(fileURLToPath(import.meta.url));
+const TDR_ENGINE_PATH = resolve(HOOK_DIR, "..", "..", "bundle", "tdr-engine.mjs");
+
+/**
+ * @typedef {"A" | "B" | "C" | "D" | "E"} MaintainabilityRating
+ */
+
+/**
+ * @typedef {Object} QualityGateConfig
+ * @property {string}                workspaceRoot          Absolute path to the project root.
+ * @property {string}                sarifReportPath        Absolute path to the consolidated SARIF file.
+ * @property {number}                crapThreshold
+ * @property {MaintainabilityRating} tdrMaxRating
+ * @property {number}                minutesPerLoc
+ */
+
+/**
+ * @typedef {Object} GateFailure
+ * @property {string} ruleId
+ * @property {string} message
+ */
+
+/**
+ * @typedef {Object} GateVerdict
+ * @property {boolean}                   passed
+ * @property {GateFailure[]}             failures
+ * @property {Object}                    summary
+ * @property {number}                    summary.totalFindings
+ * @property {number}                    summary.errorFindings
+ * @property {number}                    summary.warningFindings
+ * @property {number}                    summary.noteFindings
+ * @property {number}                    summary.remediationMinutes
+ * @property {number}                    summary.physicalLoc
+ * @property {number}                    summary.tdrPercent
+ * @property {MaintainabilityRating}     summary.tdrRating
+ * @property {string[]}                  summary.toolsSeen
+ */
+
+/**
+ * Load the claude-crap configuration from environment variables. Hooks
+ * read the same `CLAUDE_PLUGIN_OPTION_*` family of variables that the
+ * MCP server uses, so the two always agree.
+ *
+ * @returns {QualityGateConfig}
+ */
+export function loadQualityGateConfig() {
+  const workspaceRoot = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+  const sarifOutputDir =
+    process.env.CLAUDE_PLUGIN_OPTION_SARIF_OUTPUT_DIR ?? ".claude-crap/reports";
+  const sarifReportDir = isAbsolute(sarifOutputDir)
+    ? sarifOutputDir
+    : resolve(workspaceRoot, sarifOutputDir);
+  const sarifReportPath = join(sarifReportDir, "latest.sarif");
+
+  const crapThreshold = Number(process.env.CLAUDE_PLUGIN_OPTION_CRAP_THRESHOLD ?? 30);
+  const tdrMaxRating = /** @type {MaintainabilityRating} */ (
+    process.env.CLAUDE_PLUGIN_OPTION_TDR_MAINTAINABILITY_MAX_RATING ?? "C"
+  );
+  const minutesPerLoc = Number(process.env.CLAUDE_PLUGIN_OPTION_MINUTES_PER_LINE_OF_CODE ?? 30);
+
+  return { workspaceRoot, sarifReportPath, crapThreshold, tdrMaxRating, minutesPerLoc };
+}
+
+/**
+ * Read and parse the consolidated SARIF file. Returns an empty findings
+ * list when the file does not exist (fresh workspace, no gate runs yet).
+ *
+ * @param {string} path Absolute path to the SARIF file.
+ * @returns {Promise<{findings: Array<{ruleId: string, level: string, uri: string, effortMinutes: number, sourceTool: string}>, toolsSeen: Set<string>}>}
+ */
+async function readConsolidatedFindings(path) {
+  const findings = [];
+  const toolsSeen = new Set();
+  let raw;
+  try {
+    raw = await fs.readFile(path, "utf8");
+  } catch (err) {
+    const error = /** @type {NodeJS.ErrnoException} */ (err);
+    if (error.code === "ENOENT") return { findings, toolsSeen };
+    throw error;
+  }
+  const doc = JSON.parse(raw);
+  if (!doc || !Array.isArray(doc.runs)) return { findings, toolsSeen };
+
+  for (const run of doc.runs) {
+    const results = Array.isArray(run.results) ? run.results : [];
+    for (const result of results) {
+      const loc = result.locations?.[0]?.physicalLocation;
+      const uri = loc?.artifactLocation?.uri ?? "<unknown>";
+      const effort =
+        typeof result.properties?.effortMinutes === "number"
+          ? result.properties.effortMinutes
+          : 0;
+      const sourceTool =
+        typeof result.properties?.sourceTool === "string"
+          ? result.properties.sourceTool
+          : run.tool?.driver?.name ?? "unknown";
+      findings.push({
+        ruleId: String(result.ruleId ?? "unknown"),
+        level: String(result.level ?? "warning"),
+        uri,
+        effortMinutes: effort,
+        sourceTool,
+      });
+      toolsSeen.add(sourceTool);
+    }
+  }
+  return { findings, toolsSeen };
+}
+
+/**
+ * Directories we do not descend into when estimating workspace LOC. These
+ * are either dependency caches, build artifacts, or VCS metadata that the
+ * TDR policy is not meant to penalize.
+ */
+const LOC_WALK_SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  "target",
+  ".venv",
+  "venv",
+  "__pycache__",
+  ".cache",
+  ".next",
+  ".nuxt",
+  ".claude-crap",
+  ".codesight",
+]);
+
+/**
+ * Extensions we treat as "code" for the LOC count. Anything else is
+ * ignored by the walker.
+ */
+const LOC_CODE_EXTENSIONS = new Set([
+  ".ts",
+  ".tsx",
+  ".mts",
+  ".cts",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".java",
+  ".cs",
+  ".go",
+  ".rs",
+  ".rb",
+  ".php",
+  ".swift",
+  ".kt",
+  ".scala",
+  ".dart",
+  ".vue",
+]);
+
+/**
+ * Maximum number of files the walker will open before giving up. Protects
+ * against pathological repos where the walk would dominate the hook's
+ * 120-second budget. When hit, we return the partial count and warn.
+ */
+const MAX_FILES_WALKED = 20_000;
+
+/**
+ * Count physical lines of code across the workspace. Skips dependency
+ * and build directories and never follows symlinks. Returns the total
+ * physical LOC and the number of files it actually read.
+ *
+ * @param {string} workspaceRoot
+ * @returns {Promise<{physicalLoc: number, filesWalked: number, truncated: boolean}>}
+ */
+export async function estimateWorkspaceLoc(workspaceRoot) {
+  let physicalLoc = 0;
+  let filesWalked = 0;
+  let truncated = false;
+
+  /** @param {string} dir */
+  async function walk(dir) {
+    if (truncated) return;
+    /** @type {import("node:fs").Dirent[]} */
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (truncated) return;
+      if (entry.name.startsWith(".") && entry.name !== ".claude-plugin") {
+        // Hidden files are skipped except the plugin dir itself (tiny).
+        continue;
+      }
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (LOC_WALK_SKIP_DIRS.has(entry.name)) continue;
+        await walk(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const lower = entry.name.toLowerCase();
+      const dot = lower.lastIndexOf(".");
+      if (dot < 0) continue;
+      const ext = lower.substring(dot);
+      if (!LOC_CODE_EXTENSIONS.has(ext)) continue;
+      filesWalked += 1;
+      if (filesWalked > MAX_FILES_WALKED) {
+        truncated = true;
+        return;
+      }
+      try {
+        const content = await fs.readFile(full, "utf8");
+        if (content.length > 0) {
+          // `split(/\r?\n/)` overcounts by 1 when the file ends in a
+          // newline, so we fix that here to match editor behavior.
+          const newlineCount = content.split(/\r?\n/).length;
+          physicalLoc += content.endsWith("\n") ? newlineCount - 1 : newlineCount;
+        }
+      } catch {
+        // Unreadable file (permissions, binary). Skip silently.
+      }
+    }
+  }
+
+  await walk(workspaceRoot);
+  return { physicalLoc, filesWalked, truncated };
+}
+
+/**
+ * Evaluate the quality gate against the current workspace state. Pure
+ * function of its inputs — perform side effects (stdout / stderr / exit)
+ * in the calling hook script.
+ *
+ * @param {QualityGateConfig} config
+ * @returns {Promise<GateVerdict>}
+ */
+export async function evaluateQualityGate(config) {
+  const { classifyTdr, ratingIsWorseThan } = await import(TDR_ENGINE_PATH);
+
+  const { findings, toolsSeen } = await readConsolidatedFindings(config.sarifReportPath);
+  const { physicalLoc } = await estimateWorkspaceLoc(config.workspaceRoot);
+
+  const remediationMinutes = findings.reduce((sum, f) => sum + f.effortMinutes, 0);
+  const errorFindings = findings.filter((f) => f.level === "error").length;
+  const warningFindings = findings.filter((f) => f.level === "warning").length;
+  const noteFindings = findings.filter((f) => f.level === "note").length;
+
+  // Guard against divide-by-zero on a truly empty workspace.
+  const safeLoc = Math.max(physicalLoc, 1);
+  const developmentCost = config.minutesPerLoc * safeLoc;
+  const tdrPercent = (remediationMinutes / developmentCost) * 100;
+  const tdrRating = /** @type {MaintainabilityRating} */ (classifyTdr(tdrPercent));
+
+  /** @type {GateFailure[]} */
+  const failures = [];
+
+  // Policy 1 — TDR rating must not exceed the configured tolerance.
+  if (ratingIsWorseThan(tdrRating, config.tdrMaxRating)) {
+    failures.push({
+      ruleId: "SONAR-GATE-TDR",
+      message:
+        `Maintainability rating ${tdrRating} is worse than the policy limit ` +
+        `${config.tdrMaxRating}. Current TDR = ${tdrPercent.toFixed(2)}% ` +
+        `(${remediationMinutes} min of remediation over ${physicalLoc} LOC). ` +
+        `Corrective action: resolve enough findings to reduce the TDR below the bracket for ` +
+        `rating ${config.tdrMaxRating}, then re-run the Stop hook.`,
+    });
+  }
+
+  // Policy 2 — no error-level findings may survive the gate.
+  if (errorFindings > 0) {
+    failures.push({
+      ruleId: "SONAR-GATE-ERRORS",
+      message:
+        `The consolidated SARIF report contains ${errorFindings} finding(s) at level "error". ` +
+        `CLAUDE.md forbids closing a task with unresolved reliability or security errors. ` +
+        `Corrective action: open 'sonar://reports/latest.sarif' via the MCP server and fix every ` +
+        `error-level finding before retrying the Stop hook.`,
+    });
+  }
+
+  return {
+    passed: failures.length === 0,
+    failures,
+    summary: {
+      totalFindings: findings.length,
+      errorFindings,
+      warningFindings,
+      noteFindings,
+      remediationMinutes,
+      physicalLoc,
+      tdrPercent: Number(tdrPercent.toFixed(4)),
+      tdrRating,
+      toolsSeen: Array.from(toolsSeen),
+    },
+  };
+}

package/plugin/hooks/lib/test-harness.mjs

@@ -0,0 +1,152 @@
+// @ts-check
+/**
+ * Deterministic test-file resolver.
+ *
+ * Given a production source file (e.g. `src/foo/bar.ts`), this module
+ * enumerates the conventional locations where a matching test file
+ * would live and returns the first existing match — or `null` when
+ * none of the candidates exist.
+ *
+ * The resolver is a pure function of the filesystem; it never reads
+ * file contents, never invokes a test runner, and never calls the
+ * MCP server. Fast enough to run inside a hook's 15-second budget.
+ *
+ * Supported conventions (in priority order):
+ *
+ *   1. Sibling `<base>.test.<ext>` / `<base>.spec.<ext>`
+ *   2. Dedicated `__tests__/<base>.test.<ext>` directory
+ *   3. Mirror tree under `tests/`, `test/`, or `__tests__/` at the repo root
+ *   4. Python `test_<base>.py` variant
+ *
+ * New conventions can be added by extending the `candidatePaths` helper.
+ *
+ * @module hooks/lib/test-harness
+ */
+
+import { promises as fs } from "node:fs";
+import { dirname, extname, basename, join, relative, resolve, sep } from "node:path";
+
+/**
+ * Result returned by {@link findTestFile}.
+ *
+ * @typedef {Object} TestFileResolution
+ * @property {string | null} testFile    Absolute path to the first matching test file, or `null`.
+ * @property {string[]}      candidates  Absolute paths of every location the resolver tried.
+ * @property {boolean}       isTestFile  `true` if the input itself is a test file (resolver was a no-op).
+ */
+
+const TEST_SUFFIX_PATTERN = /\.(test|spec)\./;
+
+/**
+ * Return `true` if the given path is already a test file. Useful so the
+ * PostToolUse hook does not ask "where is the test for your test file?".
+ *
+ * @param {string} filePath Absolute or relative source path.
+ * @returns {boolean}
+ */
+export function isTestFile(filePath) {
+  const base = basename(filePath);
+  if (TEST_SUFFIX_PATTERN.test(base)) return true;
+  if (base.startsWith("test_") && base.endsWith(".py")) return true;
+  const parts = filePath.split(sep);
+  return parts.includes("__tests__") || parts.includes("tests") || parts.includes("test");
+}
+
+/**
+ * Enumerate every plausible test file path for a given production source
+ * file. Does not touch the filesystem — the caller is expected to probe
+ * existence separately (see {@link findTestFile}).
+ *
+ * Supported conventions, in the order they are probed:
+ *
+ *   1. Sibling `<base>.test.<ext>` / `<base>.spec.<ext>`
+ *   2. Sibling `__tests__/<base>.test.<ext>`
+ *   3. Mirror tree under `tests/`, `test/`, or `__tests__/` at the
+ *      workspace root (e.g. `tests/src/foo/bar.test.ts`)
+ *   4. Nearest-ancestor flat test directory: walk up from the source
+ *      file's directory toward the workspace root, and at every
+ *      ancestor check for `tests/<base>.test.<ext>`. Matches layouts
+ *      where tests live in a single flat directory near the source.
+ *   5. Python-specific variants.
+ *
+ * @param {string} workspaceRoot Absolute path to the workspace root.
+ * @param {string} filePath      Absolute path to the production file.
+ * @returns {string[]}           Ordered list of absolute candidate paths.
+ */
+export function candidatePaths(workspaceRoot, filePath) {
+  const absSource = resolve(filePath);
+  const ext = extname(absSource);
+  const base = basename(absSource, ext);
+  const dir = dirname(absSource);
+  const absWorkspace = resolve(workspaceRoot);
+  const relFromRoot = relative(absWorkspace, absSource);
+  const relDir = dirname(relFromRoot);
+
+  const candidates = new Set();
+
+  // 1. Sibling <base>.test.<ext> / <base>.spec.<ext>
+  candidates.add(join(dir, `${base}.test${ext}`));
+  candidates.add(join(dir, `${base}.spec${ext}`));
+
+  // 2. Sibling __tests__/<base>.test.<ext>
+  candidates.add(join(dir, "__tests__", `${base}.test${ext}`));
+  candidates.add(join(dir, "__tests__", `${base}.spec${ext}`));
+
+  // 3. Mirror tree under tests/, test/, __tests__ at the repo root.
+  for (const testRoot of ["tests", "test", "__tests__"]) {
+    candidates.add(join(absWorkspace, testRoot, relDir, `${base}.test${ext}`));
+    candidates.add(join(absWorkspace, testRoot, relDir, `${base}.spec${ext}`));
+    candidates.add(join(absWorkspace, testRoot, relDir, `${base}${ext}`));
+  }
+
+  // 4. Nearest-ancestor flat test directory. Walk up from the source
+  //    directory to the workspace root, probing for a flat test layout
+  //    at each ancestor level.
+  let current = dir;
+  while (current.length >= absWorkspace.length) {
+    for (const testRoot of ["tests", "test", "__tests__"]) {
+      candidates.add(join(current, testRoot, `${base}.test${ext}`));
+      candidates.add(join(current, testRoot, `${base}.spec${ext}`));
+      candidates.add(join(current, testRoot, `${base}${ext}`));
+    }
+    if (current === absWorkspace) break;
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  // 5. Python: sibling test_<base>.py, and tests/test_<base>.py.
+  if (ext === ".py") {
+    candidates.add(join(dir, `test_${base}.py`));
+    candidates.add(join(absWorkspace, "tests", `test_${base}.py`));
+    candidates.add(join(absWorkspace, "tests", relDir, `test_${base}.py`));
+  }
+
+  return Array.from(candidates);
+}
+
+/**
+ * Probe the filesystem and return the first candidate that exists, or
+ * `null` when none of them do. Returns early with `isTestFile: true` if
+ * the input path is already a test file.
+ *
+ * @param {string} workspaceRoot Absolute path to the workspace root.
+ * @param {string} filePath      Absolute or workspace-relative path.
+ * @returns {Promise<TestFileResolution>}
+ */
+export async function findTestFile(workspaceRoot, filePath) {
+  const absolute = resolve(filePath);
+  if (isTestFile(absolute)) {
+    return { testFile: absolute, candidates: [absolute], isTestFile: true };
+  }
+  const candidates = candidatePaths(workspaceRoot, absolute);
+  for (const candidate of candidates) {
+    try {
+      await fs.access(candidate);
+      return { testFile: candidate, candidates, isTestFile: false };
+    } catch {
+      // Probe next candidate.
+    }
+  }
+  return { testFile: null, candidates, isTestFile: false };
+}