claude-crap 0.1.2

package/scripts/postinstall.mjs

@@ -0,0 +1,127 @@
+// @ts-check
+/**
+ * npm `postinstall` hook for the claude-crap package.
+ *
+ * Runs automatically after every `npm install` (or
+ * `npx claude-crap install` of the package). Its job is to
+ * ensure both build surfaces exist:
+ *
+ *   - `dist/`                      — npm library distribution (tsc)
+ *   - `plugin/bundle/mcp-server.mjs` — git plugin distribution (esbuild)
+ *
+ * so the MCP server, the hooks, and the dashboard can all start
+ * without a manual build step from the user. We intentionally keep
+ * this tiny — heavier validation belongs in `doctor`.
+ *
+ * Behavior:
+ *
+ *   - If `dist/index.js` already exists, print a one-line welcome and
+ *     exit 0. This is the common case when the package was installed
+ *     from a pre-built npm tarball.
+ *   - Otherwise spawn `tsc -p tsconfig.json` to build `dist/` from the
+ *     shipped `src/` sources. If that fails, print a warning with the
+ *     exact command the user can run manually, but still exit 0 so
+ *     `npm install` is not aborted (the user may still want a
+ *     source-only install for inspection).
+ *   - npm sets `INIT_CWD` to the package being installed — we use
+ *     that to resolve paths so `npm install claude-crap` from a
+ *     parent project also works.
+ *
+ * We never write to stdout unless we have something useful to say,
+ * to stay friendly inside larger `npm install` output.
+ *
+ * @module scripts/postinstall
+ */
+
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Skip the whole postinstall during `npm ci` in production-only
+// environments where build tools may be missing. Users can opt out
+// by setting `CLAUDE_CRAP_SKIP_POSTINSTALL=1`.
+if (process.env.CLAUDE_CRAP_SKIP_POSTINSTALL) {
+  process.exit(0);
+}
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = resolve(HERE, "..");
+
+/** @returns {Promise<boolean>} */
+async function distIsBuilt() {
+  try {
+    await fs.access(join(PLUGIN_ROOT, "dist", "index.js"));
+    await fs.access(join(PLUGIN_ROOT, "plugin", "bundle", "mcp-server.mjs"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Spawn `tsc` (via npx so it resolves from the package's own devDeps)
+ * and pipe its output through to stderr so the user sees build errors
+ * in context with the rest of the npm install output.
+ *
+ * @returns {Promise<number>} Exit code from tsc.
+ */
+function runBuild() {
+  return new Promise((resolvePromise) => {
+    const child = spawn(
+      process.execPath,
+      [join(PLUGIN_ROOT, "node_modules", "typescript", "bin", "tsc"), "-p", "tsconfig.json"],
+      { cwd: PLUGIN_ROOT, stdio: ["ignore", "inherit", "inherit"] },
+    );
+    child.on("exit", (code) => {
+      if (code !== 0) return resolvePromise(code ?? 1);
+      const bundler = spawn(
+        process.execPath,
+        [join(PLUGIN_ROOT, "scripts", "bundle-plugin.mjs")],
+        { cwd: PLUGIN_ROOT, stdio: ["ignore", "inherit", "inherit"] }
+      );
+      bundler.on("exit", (bc) => resolvePromise(bc ?? 1));
+      bundler.on("error", () => resolvePromise(1));
+    });
+    child.on("error", () => resolvePromise(1));
+  });
+}
+
+async function main() {
+  // Already built? One-line banner and we're done.
+  if (await distIsBuilt()) {
+    process.stderr.write(
+      "claude-crap: ✓ prebuilt dist/ detected. Run `npx claude-crap install` to finish setup.\n",
+    );
+    return;
+  }
+
+  // Not built yet — try to build with the bundled TypeScript. If
+  // TypeScript is missing (production-only install), warn and exit.
+  try {
+    await fs.access(join(PLUGIN_ROOT, "node_modules", "typescript", "bin", "tsc"));
+  } catch {
+    process.stderr.write(
+      "claude-crap: ! dist/ is missing and TypeScript is not installed. " +
+        "Run `npm install` with devDependencies enabled and then `npx claude-crap install`.\n",
+    );
+    return;
+  }
+
+  process.stderr.write("claude-crap: building entrypoints ...\n");
+  const code = await runBuild();
+  if (code !== 0) {
+    process.stderr.write(
+      `claude-crap: ! build failed (exit ${code}). ` +
+        `Run \`npm run build && npm run build:plugin\` from ${PLUGIN_ROOT} to see the full error.\n`,
+    );
+    return;
+  }
+  process.stderr.write("claude-crap: ✓ build complete. Next: `npx claude-crap install`.\n");
+}
+
+main().catch((err) => {
+  process.stderr.write(`claude-crap postinstall: ${err?.message ?? err}\n`);
+  // Do not fail the install — the user can still run the plugin.
+  process.exit(0);
+});

package/scripts/run-tests.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * Portable test runner for the `npm test` family of scripts.
+ *
+ * Why this exists: `node --test` on Node 20.x does NOT expand `**`
+ * recursive globs. It treats the literal pattern as a file path and
+ * fails with `Could not find '.../src/tests/**\/*.test.ts'`. Node
+ * 22+ handles the glob, which is why the suite passes locally on a
+ * developer machine running Node 22 but fails on the GitHub Actions
+ * Node 20 matrix job.
+ *
+ * Rather than pin Node 22 in CI (which would lock the `engines` floor
+ * at 22 and drop Node 20 support), this runner does the glob expansion
+ * in userland using `fast-glob` (already a runtime dependency) and
+ * hands the discovered file list to `node --test` as explicit paths.
+ * The result works on every Node release since 18.x, on every shell
+ * (bash / zsh / sh / Windows cmd), and on every OS.
+ *
+ * Usage from `package.json#scripts`:
+ *
+ *   "test":             "node ./scripts/run-tests.mjs \"./src/tests/**\/*.test.ts\"",
+ *   "test:adapters":    "node ./scripts/run-tests.mjs \"./src/tests/adapters/**\/*.test.ts\"",
+ *   "test:integration": "node ./scripts/run-tests.mjs \"./src/tests/integration/**\/*.test.ts\"",
+ *
+ * Multiple patterns can be passed as separate arguments. Explicit
+ * file paths are accepted too — fast-glob returns them verbatim when
+ * no glob characters are present, so mixing files and patterns works.
+ *
+ * Exits with the subprocess exit code so CI reports test failures
+ * correctly. Exits non-zero immediately when no patterns are given
+ * or when a pattern matches zero files (both signal a misconfigured
+ * script, never a flaky runner).
+ *
+ * @module scripts/run-tests
+ */
+
+import { spawn } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import fastGlob from "fast-glob";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = resolve(HERE, "..");
+
+const patterns = process.argv.slice(2);
+if (patterns.length === 0) {
+  process.stderr.write(
+    "[run-tests] no patterns supplied — usage: node ./scripts/run-tests.mjs <glob> [<glob>...]\n",
+  );
+  process.exit(1);
+}
+
+// fast-glob returns forward-slash POSIX paths even on Windows, which
+// is exactly what `node --test` wants, so we do not normalize.
+const files = await fastGlob(patterns, {
+  cwd: PLUGIN_ROOT,
+  absolute: false,
+  onlyFiles: true,
+  // `**` is fast-glob's default recursive matcher, matching the
+  // pattern shape we had in the previous `node --test` invocation.
+  // We keep `dot: false` so hidden files are not considered.
+});
+
+if (files.length === 0) {
+  process.stderr.write(
+    `[run-tests] no test files matched any of: ${patterns.join(", ")}\n` +
+      `[run-tests] cwd: ${PLUGIN_ROOT}\n`,
+  );
+  process.exit(1);
+}
+
+const child = spawn(
+  process.execPath,
+  ["--import", "tsx", "--test", ...files],
+  {
+    stdio: "inherit",
+    cwd: PLUGIN_ROOT,
+  },
+);
+
+child.on("error", (err) => {
+  process.stderr.write(`[run-tests] failed to spawn node --test: ${err.message}\n`);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.stderr.write(`[run-tests] node --test killed by signal ${signal}\n`);
+    process.exit(1);
+    return;
+  }
+  process.exit(code ?? 1);
+});

package/scripts/status.mjs

@@ -0,0 +1,110 @@
+// @ts-check
+/**
+ * `claude-crap status` — show resolved paths and runtime state.
+ *
+ * Designed to be the first thing you run when someone asks
+ * "is claude-crap working?". It reports:
+ *
+ *   - Plugin version (from package.json)
+ *   - Plugin root (where the CLI resolved it to)
+ *   - Node.js version in use
+ *   - Whether dist/ is built
+ *   - Whether the SARIF store has a consolidated report yet
+ *   - Currently configured thresholds (CRAP, TDR rating, LOC cost)
+ *
+ * Does not attempt to verify anything — that's what `doctor` is for.
+ * Always exits 0.
+ *
+ * @module scripts/status
+ */
+
+import { promises as fs } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { printBanner, printKv, paint } from "./lib/cli-ui.mjs";
+
+/**
+ * @typedef {Object} CommandContext
+ * @property {string}   pluginRoot
+ * @property {string[]} argv
+ */
+
+/**
+ * Status entrypoint.
+ *
+ * @param {CommandContext} ctx
+ * @returns {Promise<number>}
+ */
+export default async function status(ctx) {
+  printBanner("claude-crap :: status");
+
+  // -- plugin version
+  const pkg = await readJson(join(ctx.pluginRoot, "package.json"));
+  printKv("version", String(pkg.version ?? "unknown"));
+
+  // -- plugin root
+  printKv("plugin root", ctx.pluginRoot);
+  printKv("workspace cwd", process.cwd());
+  printKv("Node.js", process.versions.node);
+
+  // -- entrypoints
+  const distEntry = join(ctx.pluginRoot, "dist", "index.js");
+  const distOk = await exists(distEntry);
+  printKv("dist/index.js", distOk ? paint.green("built") : paint.red("MISSING"));
+
+  const gitEntry = join(ctx.pluginRoot, "plugin", "bundle", "mcp-server.mjs");
+  const gitOk = await exists(gitEntry);
+  printKv("plugin/bundle/...", gitOk ? paint.green("built") : paint.red("MISSING"));
+
+  // -- SARIF store
+  const sarifDir = resolve(process.cwd(), ".claude-crap", "reports");
+  const sarifPath = join(sarifDir, "latest.sarif");
+  const sarifOk = await exists(sarifPath);
+  printKv("SARIF report", sarifOk ? sarifPath : paint.yellow("<not yet generated>"));
+
+  // -- dashboard port
+  const port = process.env.CLAUDE_PLUGIN_OPTION_DASHBOARD_PORT ?? "5117";
+  printKv("dashboard port", port);
+
+  // -- thresholds
+  process.stdout.write(`\n${paint.bold("  Current policy (from env):")}\n`);
+  printKv("CRAP threshold", process.env.CLAUDE_PLUGIN_OPTION_CRAP_THRESHOLD ?? "30 (default)");
+  printKv("TDR max rating", process.env.CLAUDE_PLUGIN_OPTION_TDR_MAINTAINABILITY_MAX_RATING ?? "C (default)");
+  printKv("minutes / LOC", process.env.CLAUDE_PLUGIN_OPTION_MINUTES_PER_LINE_OF_CODE ?? "30 (default)");
+
+  process.stdout.write(
+    `\n${paint.dim("Run `claude-crap doctor` for a full diagnostic pass.")}\n`,
+  );
+  return 0;
+}
+
+/**
+ * Read and parse a JSON file. Returns `{}` when the file is missing
+ * so the caller's property accesses always work.
+ *
+ * @param {string} path
+ * @returns {Promise<Record<string, unknown>>}
+ */
+async function readJson(path) {
+  try {
+    const raw = await fs.readFile(path, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * `true` when `path` exists on disk and is readable.
+ *
+ * @param {string} path
+ * @returns {Promise<boolean>}
+ */
+async function exists(path) {
+  try {
+    await fs.access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/scripts/uninstall.mjs

@@ -0,0 +1,72 @@
+// @ts-check
+/**
+ * `claude-crap uninstall` — clean up plugin state and print the
+ * Claude Code unregister command.
+ *
+ * Like `install`, this subcommand does NOT try to edit Claude Code's
+ * own settings file. It:
+ *
+ *   1. Prints the native `/plugin uninstall claude-crap` command the
+ *      user should run from inside Claude Code.
+ *   2. Optionally removes the `.claude-crap/` scratch directory from
+ *      the current workspace when called with `--purge`. Without the
+ *      flag we leave the SARIF reports in place so the user can diff
+ *      them against a re-install.
+ *
+ * Always exits 0.
+ *
+ * @module scripts/uninstall
+ */
+
+import { promises as fs } from "node:fs";
+import { resolve } from "node:path";
+
+import { printBanner, paint, icons } from "./lib/cli-ui.mjs";
+
+/**
+ * @typedef {Object} CommandContext
+ * @property {string}   pluginRoot
+ * @property {string[]} argv
+ */
+
+/**
+ * Uninstall entrypoint.
+ *
+ * @param {CommandContext} ctx
+ * @returns {Promise<number>}
+ */
+export default async function uninstall(ctx) {
+  printBanner("claude-crap :: uninstall");
+
+  const purge = ctx.argv.includes("--purge");
+  const scratch = resolve(process.cwd(), ".claude-crap");
+
+  if (purge) {
+    try {
+      await fs.rm(scratch, { recursive: true, force: true });
+      process.stdout.write(`  ${paint.green(icons.ok)} Removed ${scratch}\n`);
+    } catch (err) {
+      process.stdout.write(
+        `  ${paint.yellow(icons.warn)} Could not remove ${scratch}: ${/** @type {Error} */ (err).message}\n`,
+      );
+    }
+  } else {
+    process.stdout.write(
+      `  ${paint.dim(icons.info)} Leaving ${scratch} in place. Use ${paint.bold("claude-crap uninstall --purge")} to remove SARIF reports.\n`,
+    );
+  }
+
+  process.stdout.write(
+    [
+      "",
+      paint.bold("  Next step — unregister from Claude Code:"),
+      "",
+      `    ${paint.cyan("/plugin uninstall claude-crap")}`,
+      "",
+      paint.dim("  If you installed via `npx`, also remove the npm package:"),
+      `    ${paint.cyan("npm uninstall -g claude-crap")}`,
+      "",
+    ].join("\n"),
+  );
+  return 0;
+}

package/src/adapters/bandit.ts

@@ -0,0 +1,191 @@
+/**
+ * Bandit adapter.
+ *
+ * Bandit is a Python security linter. When run with `-f json` it
+ * emits a JSON report shaped like this (abbreviated):
+ *
+ *   {
+ *     "results": [
+ *       {
+ *         "filename": "app.py",
+ *         "line_number": 42,
+ *         "col_offset": 5,
+ *         "test_id": "B608",
+ *         "test_name": "hardcoded_sql_expressions",
+ *         "issue_severity": "HIGH",       // LOW | MEDIUM | HIGH
+ *         "issue_confidence": "HIGH",     // LOW | MEDIUM | HIGH
+ *         "issue_text": "Possible SQL injection via string-based query construction.",
+ *         "issue_cwe": { "id": 89 }
+ *       }
+ *     ],
+ *     "metrics": { ... },
+ *     "errors": [ ... ]
+ *   }
+ *
+ * This adapter converts each `results[]` entry into a SARIF 2.1.0
+ * `result`, mapping Bandit severity levels to SARIF levels:
+ *
+ *   LOW     → "note"
+ *   MEDIUM  → "warning"
+ *   HIGH    → "error"
+ *
+ * Every finding gets a rule id of `bandit.<test_id>` (e.g.
+ * `bandit.B608`) so it is trivial to correlate with Bandit's own docs
+ * from inside the claude-crap dashboard.
+ *
+ * @module adapters/bandit
+ */
+
+import type { SarifLevel } from "../sarif/sarif-builder.js";
+import {
+  estimateEffortMinutes,
+  wrapResultsInSarif,
+  type AdapterResult,
+  type KnownScanner,
+} from "./common.js";
+
+const BANDIT: KnownScanner = "bandit";
+
+interface BanditReport {
+  readonly results?: ReadonlyArray<BanditFinding>;
+}
+
+interface BanditFinding {
+  readonly filename?: string;
+  readonly line_number?: number;
+  readonly col_offset?: number;
+  readonly test_id?: string;
+  readonly test_name?: string;
+  readonly issue_severity?: string;
+  readonly issue_confidence?: string;
+  readonly issue_text?: string;
+  readonly issue_cwe?: { readonly id?: number };
+}
+
+/**
+ * Accept a Bandit JSON report and return a normalized
+ * `PersistedSarif` document.
+ *
+ * @param input Raw Bandit JSON (string or parsed object).
+ * @returns     Adapter result.
+ * @throws      When the input does not look like a Bandit report.
+ */
+export function adaptBandit(input: unknown): AdapterResult {
+  const parsed = typeof input === "string" ? (JSON.parse(input) as unknown) : input;
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error(`[adapter:bandit] expected a JSON object`);
+  }
+  const report = parsed as BanditReport;
+  if (!Array.isArray(report.results)) {
+    throw new Error(`[adapter:bandit] report is missing a results[] array`);
+  }
+
+  const results: Array<ReturnType<typeof buildSarifResult>> = [];
+  let totalEffortMinutes = 0;
+
+  for (const finding of report.results) {
+    const filename = finding.filename;
+    if (typeof filename !== "string" || !filename) continue;
+    const level = mapSeverity(finding.issue_severity);
+    // High-severity security findings cost more to fix than the
+    // generic default, so we bias the budget toward reality. Bandit
+    // is always security-focused, so every finding is treated as a
+    // security issue for TDR accounting downstream.
+    const effortOverride = level === "error" ? 120 : level === "warning" ? 60 : 20;
+    const effort = estimateEffortMinutes(level, effortOverride);
+    totalEffortMinutes += effort;
+
+    const testId = finding.test_id ?? "unknown";
+    const ruleId = `bandit.${testId}`;
+    const messageText =
+      finding.issue_text ??
+      `${finding.test_name ?? "Bandit finding"} (${finding.issue_severity ?? "UNKNOWN"})`;
+
+    const startLine =
+      typeof finding.line_number === "number" && finding.line_number > 0
+        ? finding.line_number
+        : 1;
+    const startColumn =
+      typeof finding.col_offset === "number" && finding.col_offset >= 0
+        ? finding.col_offset + 1
+        : 1;
+
+    results.push(
+      buildSarifResult({
+        ruleId,
+        level,
+        message: messageText,
+        uri: filename,
+        startLine,
+        startColumn,
+        effortMinutes: effort,
+        cwe: finding.issue_cwe?.id,
+        confidence: finding.issue_confidence,
+      }),
+    );
+  }
+
+  return {
+    document: wrapResultsInSarif(BANDIT, "unknown", results),
+    sourceTool: BANDIT,
+    findingCount: results.length,
+    totalEffortMinutes,
+  };
+}
+
+/**
+ * Map Bandit's `issue_severity` string to a SARIF level. Unknown
+ * values default to `"warning"` so findings are still surfaced.
+ */
+function mapSeverity(severity: string | undefined): SarifLevel {
+  switch ((severity ?? "").toUpperCase()) {
+    case "HIGH":
+      return "error";
+    case "MEDIUM":
+      return "warning";
+    case "LOW":
+      return "note";
+    default:
+      return "warning";
+  }
+}
+
+/**
+ * Build the SARIF `result` object for a single Bandit finding. We
+ * stash the CWE id and Bandit confidence in the `properties` bag so
+ * consumers can surface them in the dashboard hot-spot view.
+ */
+function buildSarifResult(opts: {
+  ruleId: string;
+  level: SarifLevel;
+  message: string;
+  uri: string;
+  startLine: number;
+  startColumn: number;
+  effortMinutes: number;
+  cwe?: number | undefined;
+  confidence?: string | undefined;
+}) {
+  return {
+    ruleId: opts.ruleId,
+    level: opts.level,
+    message: { text: opts.message },
+    locations: [
+      {
+        physicalLocation: {
+          artifactLocation: { uri: opts.uri },
+          region: {
+            startLine: opts.startLine,
+            startColumn: opts.startColumn,
+          },
+        },
+      },
+    ],
+    properties: {
+      sourceTool: BANDIT,
+      effortMinutes: opts.effortMinutes,
+      ...(typeof opts.cwe === "number" ? { cwe: opts.cwe } : {}),
+      ...(typeof opts.confidence === "string" ? { confidence: opts.confidence } : {}),
+    },
+  };
+}