claude-crap 0.1.2

package/src/adapters/common.ts

@@ -0,0 +1,133 @@
+/**
+ * Shared types and helpers for per-scanner SARIF adapters.
+ *
+ * Every adapter in this directory converts a scanner's native output
+ * into a `PersistedSarif` 2.1.0 document that the `SarifStore` can
+ * ingest directly. The adapters also enrich the finding `properties`
+ * bag with a stable `effortMinutes` field so the Stop quality gate and
+ * the Technical Debt Ratio computation can treat every source tool
+ * uniformly.
+ *
+ * Rule-level effort estimates live in `DEFAULT_EFFORT_BY_SEVERITY`.
+ * Individual adapters may override the default per rule id when the
+ * scanner attaches a more specific hint.
+ *
+ * @module adapters/common
+ */
+
+import type { PersistedSarif } from "../sarif/sarif-store.js";
+import type { SarifLevel } from "../sarif/sarif-builder.js";
+
+/**
+ * The canonical list of scanners claude-crap understands. The
+ * `ingest_scanner_output` MCP tool uses this as its `enum` constraint,
+ * so keeping it narrow prevents drift.
+ */
+export const KNOWN_SCANNERS = ["semgrep", "eslint", "bandit", "stryker"] as const;
+
+/**
+ * Union of supported scanner identifiers.
+ */
+export type KnownScanner = (typeof KNOWN_SCANNERS)[number];
+
+/**
+ * Default remediation effort in minutes per SARIF severity level. These
+ * numbers are deliberately conservative — real projects should override
+ * them per rule via adapter-specific rule maps or via SARIF properties.
+ *
+ * The mapping follows the common-sense rule that every bug takes at
+ * least a test plus a patch, so even a note-level finding costs time.
+ */
+export const DEFAULT_EFFORT_BY_SEVERITY: Readonly<Record<SarifLevel, number>> = Object.freeze({
+  error: 60,
+  warning: 30,
+  note: 10,
+  none: 5,
+});
+
+/**
+ * Envelope common to every adapter output. Adapters return a
+ * `PersistedSarif` document and a small stats block describing what
+ * they saw, so the MCP tool handler can echo those stats back to the
+ * LLM even when the SarifStore rejects duplicates.
+ */
+export interface AdapterResult {
+  /** Normalized SARIF 2.1.0 document ready for `SarifStore.ingestRun`. */
+  readonly document: PersistedSarif;
+  /** Scanner identifier, propagated into every finding's `properties.sourceTool`. */
+  readonly sourceTool: KnownScanner;
+  /** Raw number of findings the adapter read from the scanner's native output. */
+  readonly findingCount: number;
+  /** Total estimated remediation effort across all findings, in minutes. */
+  readonly totalEffortMinutes: number;
+}
+
+/**
+ * Build a `PersistedSarif` document from a flat list of already-mapped
+ * result entries. Every adapter produces its results with the same
+ * shape and then calls this helper to wrap them in a valid 2.1.0 envelope.
+ *
+ * @param sourceTool  Stable scanner identifier (e.g. `"semgrep"`).
+ * @param version     Adapter version string stored in `tool.driver.version`.
+ * @param results     Pre-built SARIF `result` entries.
+ */
+export function wrapResultsInSarif(
+  sourceTool: KnownScanner,
+  version: string,
+  results: ReadonlyArray<object>,
+): PersistedSarif {
+  return {
+    $schema: "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0.json",
+    version: "2.1.0",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: sourceTool,
+            version,
+          },
+        },
+        results: results as ReadonlyArray<SarifResultShape>,
+      },
+    ],
+  } as PersistedSarif;
+}
+
+/**
+ * Narrow structural contract of a SARIF `result` object. We type it
+ * loosely so adapters can emit the minimum required fields without
+ * importing the full SARIF spec types from `sarif-store.ts`.
+ */
+interface SarifResultShape {
+  readonly ruleId: string;
+  readonly level?: SarifLevel;
+  readonly message: { readonly text: string };
+  readonly locations?: ReadonlyArray<{
+    readonly physicalLocation?: {
+      readonly artifactLocation?: { readonly uri?: string };
+      readonly region?: {
+        readonly startLine?: number;
+        readonly startColumn?: number;
+        readonly endLine?: number;
+        readonly endColumn?: number;
+      };
+    };
+  }>;
+  readonly properties?: Record<string, unknown>;
+}
+
+/**
+ * Estimate remediation effort for a single finding given its severity
+ * and an optional rule-specific override. Returns `minutes` clamped to
+ * a non-negative integer.
+ *
+ * @param level     SARIF severity level (`"error"`, `"warning"`, ...).
+ * @param override  Optional rule-specific effort in minutes.
+ */
+export function estimateEffortMinutes(level: SarifLevel | undefined, override?: number): number {
+  if (typeof override === "number" && Number.isFinite(override) && override >= 0) {
+    return Math.round(override);
+  }
+  const base = DEFAULT_EFFORT_BY_SEVERITY[level ?? "warning"];
+  return Math.max(0, Math.round(base ?? 30));
+}

package/src/adapters/eslint.ts

@@ -0,0 +1,187 @@
+/**
+ * ESLint adapter.
+ *
+ * ESLint's default JSON output (`eslint -f json .`) is NOT SARIF.
+ * This adapter converts it into a SARIF 2.1.0 document with one
+ * `result` per ESLint `messages[]` entry, mapping ESLint's numeric
+ * severity to SARIF levels:
+ *
+ *   severity 0 → "note"     (parser info / disabled)
+ *   severity 1 → "warning"
+ *   severity 2 → "error"
+ *
+ * ESLint's JSON shape:
+ *
+ *   [
+ *     {
+ *       "filePath": "/abs/path/to/foo.js",
+ *       "messages": [
+ *         {
+ *           "ruleId": "no-unused-vars",
+ *           "severity": 1,
+ *           "message": "'foo' is defined but never used.",
+ *           "line": 10,
+ *           "column": 5,
+ *           "endLine": 10,
+ *           "endColumn": 8
+ *         }
+ *       ],
+ *       "errorCount": 0,
+ *       "warningCount": 1,
+ *       "fatalErrorCount": 0,
+ *       "source": "...",
+ *       "usedDeprecatedRules": []
+ *     }
+ *   ]
+ *
+ * We preserve the full `line`/`column` range when ESLint provides one
+ * so the dashboard's hot-spot table can show a precise location.
+ *
+ * @module adapters/eslint
+ */
+
+import type { SarifLevel } from "../sarif/sarif-builder.js";
+import {
+  estimateEffortMinutes,
+  wrapResultsInSarif,
+  type AdapterResult,
+  type KnownScanner,
+} from "./common.js";
+
+const ESLINT: KnownScanner = "eslint";
+
+/**
+ * ESLint JSON file entry as produced by `eslint -f json`. We type it
+ * permissively because many ESLint fields are optional depending on
+ * version and plugin.
+ */
+interface EslintFileReport {
+  readonly filePath?: string;
+  readonly messages?: ReadonlyArray<EslintMessage>;
+}
+
+interface EslintMessage {
+  readonly ruleId?: string | null;
+  readonly severity?: number;
+  readonly message?: string;
+  readonly line?: number;
+  readonly column?: number;
+  readonly endLine?: number;
+  readonly endColumn?: number;
+  readonly fatal?: boolean;
+}
+
+/**
+ * Accept ESLint native JSON output and return a normalized
+ * `PersistedSarif` document plus counts.
+ *
+ * @param input Raw ESLint JSON (string or parsed array).
+ * @returns     Adapter result.
+ * @throws      When the input is not a valid ESLint report.
+ */
+export function adaptEslint(input: unknown): AdapterResult {
+  const parsed = typeof input === "string" ? (JSON.parse(input) as unknown) : input;
+  if (!Array.isArray(parsed)) {
+    throw new Error(`[adapter:eslint] expected an array of file reports`);
+  }
+
+  const results: Array<ReturnType<typeof buildSarifResult>> = [];
+  let totalEffortMinutes = 0;
+
+  for (const fileReport of parsed as ReadonlyArray<EslintFileReport>) {
+    const filePath = fileReport?.filePath;
+    if (typeof filePath !== "string" || !filePath) continue;
+    const messages = Array.isArray(fileReport.messages) ? fileReport.messages : [];
+    for (const msg of messages) {
+      const level = mapSeverity(msg.severity);
+      const ruleId = typeof msg.ruleId === "string" ? msg.ruleId : "eslint.unknown";
+      const line = typeof msg.line === "number" && msg.line > 0 ? msg.line : 1;
+      const column = typeof msg.column === "number" && msg.column > 0 ? msg.column : 1;
+      const effort = estimateEffortMinutes(level);
+      totalEffortMinutes += effort;
+      results.push(
+        buildSarifResult({
+          ruleId,
+          level,
+          message: msg.message ?? ruleId,
+          uri: filePath,
+          startLine: line,
+          startColumn: column,
+          endLine: typeof msg.endLine === "number" ? msg.endLine : undefined,
+          endColumn: typeof msg.endColumn === "number" ? msg.endColumn : undefined,
+          effortMinutes: effort,
+        }),
+      );
+    }
+  }
+
+  return {
+    document: wrapResultsInSarif(ESLINT, "unknown", results),
+    sourceTool: ESLINT,
+    findingCount: results.length,
+    totalEffortMinutes,
+  };
+}
+
+/**
+ * Translate ESLint's numeric severity to a SARIF level. ESLint uses:
+ *
+ *   0 = off / disabled   → `"note"` (informational)
+ *   1 = warn             → `"warning"`
+ *   2 = error            → `"error"`
+ *
+ * Unknown values default to `"warning"` so the finding is still
+ * visible without being treated as a blocker.
+ */
+function mapSeverity(severity: number | undefined): SarifLevel {
+  switch (severity) {
+    case 2:
+      return "error";
+    case 1:
+      return "warning";
+    case 0:
+      return "note";
+    default:
+      return "warning";
+  }
+}
+
+/**
+ * Assemble a SARIF `result` object from the narrow set of fields an
+ * ESLint message provides. The shape matches what the SarifStore
+ * expects when hydrating a finding from a persisted document.
+ */
+function buildSarifResult(opts: {
+  ruleId: string;
+  level: SarifLevel;
+  message: string;
+  uri: string;
+  startLine: number;
+  startColumn: number;
+  endLine?: number | undefined;
+  endColumn?: number | undefined;
+  effortMinutes: number;
+}) {
+  return {
+    ruleId: opts.ruleId,
+    level: opts.level,
+    message: { text: opts.message },
+    locations: [
+      {
+        physicalLocation: {
+          artifactLocation: { uri: opts.uri },
+          region: {
+            startLine: opts.startLine,
+            startColumn: opts.startColumn,
+            ...(opts.endLine !== undefined ? { endLine: opts.endLine } : {}),
+            ...(opts.endColumn !== undefined ? { endColumn: opts.endColumn } : {}),
+          },
+        },
+      },
+    ],
+    properties: {
+      sourceTool: ESLINT,
+      effortMinutes: opts.effortMinutes,
+    },
+  };
+}

package/src/adapters/index.ts

@@ -0,0 +1,78 @@
+/**
+ * Public SDK entry point for the per-scanner SARIF adapters.
+ *
+ * Adapters convert a scanner's native output (SARIF, JSON, or some
+ * other structured format) into a normalized `PersistedSarif`
+ * document that the `SarifStore` can ingest directly. Every adapter
+ * enriches its findings with a stable `effortMinutes` value on the
+ * `properties` bag so the Stop quality gate and the project score
+ * engine can compute a Technical Debt Ratio.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import {
+ *   adaptScannerOutput,
+ *   adaptSemgrep,
+ *   adaptEslint,
+ *   adaptBandit,
+ *   adaptStryker,
+ * } from "claude-crap/adapters";
+ *
+ * const result = adaptScannerOutput("eslint", rawJsonFromEslint);
+ * sarifStore.ingestRun(result.document, result.sourceTool);
+ * ```
+ *
+ * @module adapters
+ */
+
+export { adaptSemgrep } from "./semgrep.js";
+export { adaptEslint } from "./eslint.js";
+export { adaptBandit } from "./bandit.js";
+export { adaptStryker } from "./stryker.js";
+
+export {
+  DEFAULT_EFFORT_BY_SEVERITY,
+  KNOWN_SCANNERS,
+  estimateEffortMinutes,
+  wrapResultsInSarif,
+} from "./common.js";
+
+export type { AdapterResult, KnownScanner } from "./common.js";
+
+import { adaptSemgrep } from "./semgrep.js";
+import { adaptEslint } from "./eslint.js";
+import { adaptBandit } from "./bandit.js";
+import { adaptStryker } from "./stryker.js";
+import type { AdapterResult, KnownScanner } from "./common.js";
+
+/**
+ * Route a raw scanner output to the correct adapter based on its
+ * name. Preferred entry point for the `ingest_scanner_output` MCP
+ * tool — the dispatch is a single switch so the compiler can verify
+ * every case with `never` exhaustiveness.
+ *
+ * @param scanner   One of the known scanner identifiers.
+ * @param rawOutput The scanner's native output (string or parsed).
+ * @returns         A normalized `AdapterResult`.
+ * @throws          When `scanner` is unknown or the raw output is malformed.
+ */
+export function adaptScannerOutput(
+  scanner: KnownScanner,
+  rawOutput: unknown,
+): AdapterResult {
+  switch (scanner) {
+    case "semgrep":
+      return adaptSemgrep(rawOutput);
+    case "eslint":
+      return adaptEslint(rawOutput);
+    case "bandit":
+      return adaptBandit(rawOutput);
+    case "stryker":
+      return adaptStryker(rawOutput);
+    default: {
+      const exhaustive: never = scanner;
+      throw new Error(`[adapters] Unknown scanner: ${String(exhaustive)}`);
+    }
+  }
+}

package/src/adapters/semgrep.ts

@@ -0,0 +1,150 @@
+/**
+ * Semgrep adapter.
+ *
+ * Semgrep already emits SARIF 2.1.0 natively when invoked with
+ * `--sarif`, so this adapter's job is not translation but
+ * **enrichment**: we walk every `result` entry and stamp a
+ * `properties.effortMinutes` value so the Stop quality gate can
+ * compute a Technical Debt Ratio, plus we normalize the
+ * `properties.sourceTool` field so downstream consumers always know
+ * the finding came from Semgrep.
+ *
+ * If the caller passes a string, we parse it as JSON. If they pass an
+ * object that already matches the SARIF 2.1.0 envelope, we use it
+ * directly. Anything else throws a descriptive error that the MCP
+ * tool handler surfaces back to the LLM.
+ *
+ * @module adapters/semgrep
+ */
+
+import type { PersistedSarif } from "../sarif/sarif-store.js";
+import type { SarifLevel } from "../sarif/sarif-builder.js";
+import {
+  estimateEffortMinutes,
+  type AdapterResult,
+  type KnownScanner,
+} from "./common.js";
+
+const SEMGREP: KnownScanner = "semgrep";
+
+/**
+ * Rule-id effort overrides. Semgrep emits lots of stylistic rules
+ * that take less than a minute to fix and a handful of deep security
+ * rules that deserve more budget than the default warning tier. The
+ * list below is intentionally short — teams should extend it.
+ */
+const SEMGREP_EFFORT_OVERRIDES: ReadonlyMap<RegExp, number> = new Map([
+  [/security\./i, 90],
+  [/sqli|xss|ssrf|rce|deserial|crypto/i, 120],
+  [/style\./i, 5],
+  [/formatting\./i, 3],
+]);
+
+/**
+ * Accept a Semgrep SARIF document (as a string or object) and return
+ * an enriched `PersistedSarif` with effort estimates and a normalized
+ * `sourceTool` field.
+ *
+ * @param input     Raw SARIF document from Semgrep (`JSON.stringify`ed or parsed).
+ * @returns         The enriched document plus per-run stats.
+ * @throws          When the input is not a SARIF 2.1.0 document.
+ */
+export function adaptSemgrep(input: unknown): AdapterResult {
+  const doc = coerceToSarif(input);
+
+  let findingCount = 0;
+  let totalEffortMinutes = 0;
+
+  // We deep-clone the document so callers don't observe a mutation on
+  // the value they passed us. JSON round-trip is cheap here; a
+  // typical Semgrep SARIF report is well under 1 MB.
+  //
+  // We operate on the cloned value through a loose `Record`-based view
+  // to keep the adapter agnostic to the full SARIF schema — the
+  // canonical types live in `sarif-store.ts` and we only care about a
+  // handful of fields here. The final return casts through `unknown`
+  // because the JSON round-trip is shape-preserving by construction.
+  const cloned = JSON.parse(JSON.stringify(doc)) as {
+    runs?: Array<Record<string, unknown>>;
+  };
+  const runs = Array.isArray(cloned.runs) ? cloned.runs : [];
+
+  for (const run of runs) {
+    const rawResults = run["results"];
+    const results = Array.isArray(rawResults) ? (rawResults as Array<Record<string, unknown>>) : [];
+    for (const result of results) {
+      findingCount += 1;
+      const ruleId = typeof result["ruleId"] === "string" ? (result["ruleId"] as string) : "";
+      const level = result["level"] as SarifLevel | undefined;
+      const override = matchOverride(ruleId);
+      const effort = estimateEffortMinutes(level, override);
+      totalEffortMinutes += effort;
+      const existingProps =
+        result["properties"] && typeof result["properties"] === "object"
+          ? (result["properties"] as Record<string, unknown>)
+          : {};
+      result["properties"] = {
+        ...existingProps,
+        sourceTool: SEMGREP,
+        effortMinutes: effort,
+      };
+    }
+
+    // Overwrite tool.driver.name so store-level filters always match
+    // `"semgrep"` regardless of the label Semgrep reported. Preserve
+    // the existing version and rules[] array when present.
+    const existingTool = (run["tool"] as Record<string, unknown> | undefined) ?? {};
+    const existingDriver = (existingTool["driver"] as Record<string, unknown> | undefined) ?? {};
+    const driverOut: Record<string, unknown> = {
+      name: SEMGREP,
+      version: typeof existingDriver["version"] === "string" ? existingDriver["version"] : "unknown",
+    };
+    if (Array.isArray(existingDriver["rules"])) {
+      driverOut["rules"] = existingDriver["rules"];
+    }
+    run["tool"] = { driver: driverOut };
+  }
+
+  return {
+    document: cloned as unknown as PersistedSarif,
+    sourceTool: SEMGREP,
+    findingCount,
+    totalEffortMinutes,
+  };
+}
+
+/**
+ * Accept either a pre-parsed SARIF object or a JSON string and return
+ * a strongly-typed `PersistedSarif`. Throws on malformed input.
+ *
+ * @param input Raw caller-provided value.
+ */
+function coerceToSarif(input: unknown): PersistedSarif {
+  const parsed = typeof input === "string" ? (JSON.parse(input) as unknown) : input;
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error(`[adapter:semgrep] input is not a SARIF object`);
+  }
+  const doc = parsed as { version?: unknown; runs?: unknown };
+  if (doc.version !== "2.1.0") {
+    throw new Error(
+      `[adapter:semgrep] expected SARIF version 2.1.0, got ${String(doc.version)}`,
+    );
+  }
+  if (!Array.isArray(doc.runs)) {
+    throw new Error(`[adapter:semgrep] document is missing a runs[] array`);
+  }
+  return parsed as PersistedSarif;
+}
+
+/**
+ * Return the effort override (in minutes) matching the first pattern
+ * that matches the given rule id, or `undefined` when none match.
+ *
+ * @param ruleId Semgrep rule identifier.
+ */
+function matchOverride(ruleId: string): number | undefined {
+  for (const [pattern, minutes] of SEMGREP_EFFORT_OVERRIDES) {
+    if (pattern.test(ruleId)) return minutes;
+  }
+  return undefined;
+}