claude-crap 0.1.2

package/src/metrics/workspace-walker.ts

@@ -0,0 +1,146 @@
+/**
+ * Bounded workspace walker.
+ *
+ * Counts physical lines of code across a workspace, skipping directories
+ * that should not contribute to the Technical Debt Ratio (dependency
+ * caches, build artifacts, VCS metadata, etc.) and capping the file
+ * count to keep the walk well under the Stop hook's 120-second budget
+ * even on pathological repositories.
+ *
+ * This is the TypeScript twin of `hooks/lib/quality-gate.mjs#estimateWorkspaceLoc`.
+ * The two are independent so neither side has to import files from outside
+ * its own project tree.
+ *
+ * @module metrics/workspace-walker
+ */
+
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Result returned by {@link estimateWorkspaceLoc}.
+ */
+export interface WorkspaceWalkResult {
+  /** Total physical lines of code across every file the walker read. */
+  readonly physicalLoc: number;
+  /** Number of code files the walker visited. */
+  readonly fileCount: number;
+  /** `true` when the walker hit {@link MAX_FILES_WALKED} and stopped early. */
+  readonly truncated: boolean;
+}
+
+/**
+ * Directories that should never contribute to the LOC count. Dependency
+ * caches, build artifacts, VCS metadata, claude-crap's own state.
+ */
+const SKIP_DIRS: ReadonlySet<string> = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  "target",
+  ".venv",
+  "venv",
+  "__pycache__",
+  ".cache",
+  ".next",
+  ".nuxt",
+  ".claude-crap",
+  ".codesight",
+]);
+
+/**
+ * Extensions the walker treats as "code". Anything else is ignored,
+ * including markdown, JSON, YAML, lockfiles, and binaries.
+ */
+const CODE_EXTENSIONS: ReadonlySet<string> = new Set([
+  ".ts",
+  ".tsx",
+  ".mts",
+  ".cts",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".java",
+  ".cs",
+  ".go",
+  ".rs",
+  ".rb",
+  ".php",
+  ".swift",
+  ".kt",
+  ".scala",
+  ".dart",
+  ".vue",
+]);
+
+/**
+ * Hard cap on the number of files the walker will read. Protects against
+ * pathological repositories where the walk would otherwise dominate the
+ * Stop hook's budget. When hit, the walker returns the partial count
+ * with `truncated: true` and the caller may decide how to react.
+ */
+export const MAX_FILES_WALKED = 20_000;
+
+/**
+ * Walk a workspace and return its physical LOC + file count. Never
+ * follows symbolic links. Skips hidden directories except `.claude-plugin`
+ * (which is tiny and contains the manifest).
+ *
+ * @param workspaceRoot Absolute path to the workspace root.
+ * @returns             A {@link WorkspaceWalkResult} snapshot.
+ */
+export async function estimateWorkspaceLoc(workspaceRoot: string): Promise<WorkspaceWalkResult> {
+  let physicalLoc = 0;
+  let fileCount = 0;
+  let truncated = false;
+
+  async function walk(dir: string): Promise<void> {
+    if (truncated) return;
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (truncated) return;
+      // Skip hidden files except the plugin manifest dir.
+      if (entry.name.startsWith(".") && entry.name !== ".claude-plugin") continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (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 (!CODE_EXTENSIONS.has(ext)) continue;
+      fileCount += 1;
+      if (fileCount > MAX_FILES_WALKED) {
+        truncated = true;
+        return;
+      }
+      try {
+        const content = await fs.readFile(full, "utf8");
+        if (content.length > 0) {
+          // Subtract 1 for trailing newline, matching what most editors
+          // report as the file's line count.
+          const lines = content.split(/\r?\n/).length;
+          physicalLoc += content.endsWith("\n") ? lines - 1 : lines;
+        }
+      } catch {
+        // Unreadable file (permissions, binary). Skip silently.
+      }
+    }
+  }
+
+  await walk(workspaceRoot);
+  return { physicalLoc, fileCount, truncated };
+}

package/src/sarif/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Public SDK entry point for the SARIF 2.1.0 builder and store.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import {
+ *   SarifStore,
+ *   buildSarifDocument,
+ *   type SarifFinding,
+ *   type SarifLevel,
+ * } from "claude-crap/sarif";
+ * ```
+ *
+ * @module sarif
+ */
+
+export { buildSarifDocument } from "./sarif-builder.js";
+export type {
+  SarifFinding,
+  SarifLevel,
+  SarifLocation,
+  SarifToolInfo,
+} from "./sarif-builder.js";
+
+export { SarifStore } from "./sarif-store.js";
+export type {
+  IngestedFinding,
+  PersistedSarif,
+  SarifStoreOptions,
+} from "./sarif-store.js";

package/src/sarif/sarif-builder.ts

@@ -0,0 +1,139 @@
+/**
+ * Minimal SARIF 2.1.0 document builder.
+ *
+ * Every report that leaves the MCP server on its way to the agent is
+ * normalized to SARIF 2.1.0 first. This module provides the typed
+ * helpers used to wrap raw findings in the canonical
+ * `tool → runs → results` taxonomy with exact file coordinates.
+ *
+ * Per-scanner adapters (Semgrep, ESLint, Bandit, Stryker) live under
+ * `src/adapters/` and call into `buildSarifDocument` through the
+ * `wrapResultsInSarif` helper in `src/adapters/common.ts`. The
+ * on-disk deduplication store lives in `./sarif-store.ts`.
+ *
+ * The SARIF 2.1.0 spec lives at:
+ *   https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
+ *
+ * @module sarif/sarif-builder
+ */
+
+/**
+ * Severity levels supported by SARIF 2.1.0. They map 1:1 to the
+ * `result.level` field. `"error"` is the strongest, `"none"` is informational.
+ */
+export type SarifLevel = "none" | "note" | "warning" | "error";
+
+/**
+ * Physical location of a finding inside a source artifact. `startLine` and
+ * `startColumn` are 1-based, matching the SARIF spec. `endLine` and
+ * `endColumn` are optional — omit them for point-like findings.
+ */
+export interface SarifLocation {
+  /** Artifact URI, typically a file path relative to the workspace root. */
+  readonly uri: string;
+  /** 1-based line number where the finding starts. */
+  readonly startLine: number;
+  /** 1-based column number where the finding starts. */
+  readonly startColumn: number;
+  /** Optional 1-based line number where the finding ends. */
+  readonly endLine?: number;
+  /** Optional 1-based column number where the finding ends. */
+  readonly endColumn?: number;
+}
+
+/**
+ * A single finding ready to be embedded in a SARIF run. This is the
+ * internal shape used by claude-crap adapters; it is converted into the
+ * official SARIF `result` object by {@link buildSarifDocument}.
+ */
+export interface SarifFinding {
+  /** Stable rule identifier (e.g. `"SONAR-CRAP-001"`, `"semgrep.python.sqli"`). */
+  readonly ruleId: string;
+  /** Severity level for this finding. */
+  readonly level: SarifLevel;
+  /** Human-readable message describing the finding. */
+  readonly message: string;
+  /** Physical location where the finding was detected. */
+  readonly location: SarifLocation;
+  /** Optional extra metadata stored in the SARIF `properties` bag. */
+  readonly properties?: Record<string, unknown>;
+}
+
+/**
+ * Metadata describing the tool that produced a SARIF run. The `name` is
+ * required by the spec; `version` is strongly recommended so that dashboard
+ * diffs can distinguish between scanner releases.
+ */
+export interface SarifToolInfo {
+  /** Tool display name (e.g. `"claude-crap"`, `"semgrep"`). */
+  readonly name: string;
+  /** Tool semantic version. */
+  readonly version: string;
+  /** Optional URL pointing to the tool's documentation or home page. */
+  readonly informationUri?: string;
+}
+
+/**
+ * Build a minimal but valid SARIF 2.1.0 document from a list of findings.
+ *
+ * The returned object conforms to the SARIF JSON schema hosted at:
+ *   https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0.json
+ *
+ * Rules are deduplicated by `ruleId` and emitted in the `tool.driver.rules`
+ * array so that downstream consumers (Claude Code, the dashboard, or any
+ * third-party SARIF viewer) can render a rule index.
+ *
+ * @param tool     Metadata about the producing tool.
+ * @param findings Findings to include in the single run.
+ * @returns        A SARIF 2.1.0 document literal (frozen by `as const`).
+ */
+export function buildSarifDocument(tool: SarifToolInfo, findings: ReadonlyArray<SarifFinding>) {
+  return {
+    $schema: "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0.json",
+    version: "2.1.0",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: tool.name,
+            version: tool.version,
+            informationUri: tool.informationUri ?? "https://github.com/local/claude-crap",
+            // Deduplicate rules by id while preserving insertion order so
+            // the emitted `rules` array matches the order findings appear.
+            rules: Array.from(
+              new Map(
+                findings.map((f) => [
+                  f.ruleId,
+                  {
+                    id: f.ruleId,
+                    shortDescription: { text: f.ruleId },
+                    defaultConfiguration: { level: f.level },
+                  },
+                ]),
+              ).values(),
+            ),
+          },
+        },
+        results: findings.map((f) => ({
+          ruleId: f.ruleId,
+          level: f.level,
+          message: { text: f.message },
+          locations: [
+            {
+              physicalLocation: {
+                artifactLocation: { uri: f.location.uri },
+                region: {
+                  startLine: f.location.startLine,
+                  startColumn: f.location.startColumn,
+                  ...(f.location.endLine !== undefined ? { endLine: f.location.endLine } : {}),
+                  ...(f.location.endColumn !== undefined ? { endColumn: f.location.endColumn } : {}),
+                },
+              },
+            },
+          ],
+          ...(f.properties ? { properties: f.properties } : {}),
+        })),
+      },
+    ],
+  } as const;
+}

package/src/sarif/sarif-store.ts

@@ -0,0 +1,347 @@
+/**
+ * On-disk SARIF 2.1.0 store with finding deduplication.
+ *
+ * The Stop quality gate and the `ingest_sarif` MCP tool both need a
+ * single, consolidated view of every finding produced across the current
+ * session. This module provides:
+ *
+ *   - `loadLatest()` — read the consolidated SARIF document from disk,
+ *                       or return an empty seed when no report exists yet.
+ *   - `ingestRun()`  — merge a new SARIF run from an external scanner
+ *                       (Semgrep, ESLint, Bandit, Stryker, ...) into the
+ *                       in-memory store, deduplicating by
+ *                       `(ruleId, uri, startLine, startColumn)`.
+ *   - `persist()`    — atomically write the consolidated document back
+ *                       to disk so other processes (the dashboard) can
+ *                       read it.
+ *
+ * The store is intentionally simple: it does NOT attempt to preserve
+ * per-tool run separation inside the persisted file. Instead, every
+ * ingested run is flattened into a single `runs[0]` entry whose `tool.driver`
+ * is claude-crap itself, and the original scanner name is recorded on
+ * each finding via the `properties.sourceTool` field. This keeps the
+ * consolidated document easy to diff between sessions.
+ *
+ * @module sarif/sarif-store
+ */
+
+import { promises as fs } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+import { buildSarifDocument, type SarifFinding, type SarifLevel } from "./sarif-builder.js";
+
+/**
+ * The shape of a persisted SARIF 2.1.0 document, narrowed to the fields
+ * we actually read and write. The full spec has many more optional
+ * fields; we ignore them on read and do not emit them on write.
+ */
+export interface PersistedSarif {
+  readonly $schema?: string;
+  readonly version: "2.1.0";
+  readonly runs: ReadonlyArray<SarifRun>;
+}
+
+interface SarifRun {
+  readonly tool: {
+    readonly driver: {
+      readonly name: string;
+      readonly version: string;
+      readonly informationUri?: string;
+      readonly rules?: ReadonlyArray<unknown>;
+    };
+  };
+  readonly results: ReadonlyArray<SarifResult>;
+}
+
+interface SarifResult {
+  readonly ruleId: string;
+  readonly level?: SarifLevel;
+  readonly message: { readonly text: string };
+  readonly locations?: ReadonlyArray<SarifResultLocation>;
+  readonly properties?: Record<string, unknown>;
+}
+
+interface SarifResultLocation {
+  readonly physicalLocation?: {
+    readonly artifactLocation?: { readonly uri?: string };
+    readonly region?: {
+      readonly startLine?: number;
+      readonly startColumn?: number;
+      readonly endLine?: number;
+      readonly endColumn?: number;
+    };
+  };
+}
+
+/**
+ * Options accepted by the {@link SarifStore} constructor.
+ */
+export interface SarifStoreOptions {
+  /** Workspace root. Used to resolve relative `outputDir`. */
+  readonly workspaceRoot: string;
+  /** Directory (absolute or workspace-relative) where reports are written. */
+  readonly outputDir: string;
+  /** Filename for the consolidated SARIF document. Defaults to `latest.sarif`. */
+  readonly fileName?: string;
+}
+
+/**
+ * A finding together with its deduplication key. Used internally and
+ * returned by {@link SarifStore.ingestRun} so callers can see which
+ * findings were accepted.
+ */
+export interface IngestedFinding extends SarifFinding {
+  /** Stable deduplication key, shape: `ruleId|uri|line|col`. */
+  readonly dedupKey: string;
+  /** Name of the scanner that produced the finding (propagated from `sourceTool`). */
+  readonly sourceTool: string;
+}
+
+/**
+ * On-disk SARIF store.
+ */
+export class SarifStore {
+  private readonly filePath: string;
+  /** In-memory index of findings keyed by their dedup string. */
+  private readonly findings = new Map<string, IngestedFinding>();
+  /** Tool invocations we have already ingested, for telemetry. */
+  private toolInvocations = 0;
+
+  constructor(options: SarifStoreOptions) {
+    const dir = isAbsolute(options.outputDir)
+      ? options.outputDir
+      : resolve(options.workspaceRoot, options.outputDir);
+    this.filePath = join(dir, options.fileName ?? "latest.sarif");
+  }
+
+  /**
+   * Absolute path to the consolidated SARIF file on disk.
+   */
+  get consolidatedReportPath(): string {
+    return this.filePath;
+  }
+
+  /**
+   * Load the consolidated document from disk into memory. If the file is
+   * missing, the store is initialized empty. Top-level parsing errors
+   * still throw (a file that is not valid JSON, or that declares a
+   * different SARIF version, is a real safety signal). However, once
+   * the document is parsed, malformed individual runs and results are
+   * tolerated: F-A08-01 showed that a single bad entry in `latest.sarif`
+   * could crash the MCP server on boot and persistently DoS the
+   * developer. Each run / result is wrapped in its own try/catch so a
+   * single bad entry logs to stderr and is dropped, but the rest of
+   * the file still loads.
+   *
+   * @throws When the file exists but is not valid SARIF 2.1.0 JSON.
+   */
+  async loadLatest(): Promise<void> {
+    try {
+      const raw = await fs.readFile(this.filePath, "utf8");
+      const parsed = JSON.parse(raw) as PersistedSarif;
+      if (parsed.version !== "2.1.0") {
+        throw new Error(`Expected SARIF 2.1.0, got ${parsed.version}`);
+      }
+      this.findings.clear();
+      // Defensive against tampered / mis-generated files: `runs` must
+      // be an array. Anything else is dropped with a stderr warning.
+      if (!Array.isArray(parsed.runs)) {
+        process.stderr.write(
+          `[sarif-store] ${this.filePath}: 'runs' is not an array, dropping entire document\n`,
+        );
+        return;
+      }
+      for (const run of parsed.runs) {
+        try {
+          if (!run || typeof run !== "object" || !Array.isArray(run.results)) {
+            process.stderr.write(
+              `[sarif-store] ${this.filePath}: skipping run with non-iterable 'results'\n`,
+            );
+            continue;
+          }
+          for (const result of run.results) {
+            try {
+              const finding = hydrateFindingFromResult(result);
+              if (finding) this.findings.set(finding.dedupKey, finding);
+            } catch (entryErr) {
+              process.stderr.write(
+                `[sarif-store] ${this.filePath}: dropping malformed result: ${(entryErr as Error).message}\n`,
+              );
+            }
+          }
+        } catch (runErr) {
+          process.stderr.write(
+            `[sarif-store] ${this.filePath}: dropping malformed run: ${(runErr as Error).message}\n`,
+          );
+        }
+      }
+    } catch (err) {
+      const error = err as NodeJS.ErrnoException;
+      if (error.code === "ENOENT") {
+        // No report on disk yet — normal for a fresh workspace.
+        this.findings.clear();
+        return;
+      }
+      throw new Error(
+        `[sarif-store] Failed to load consolidated report at ${this.filePath}: ${error.message}`,
+      );
+    }
+  }
+
+  /**
+   * Merge a raw SARIF document (from any external scanner) into the
+   * store, deduplicating by `(ruleId, uri, startLine, startColumn)`. The
+   * last writer wins for the message and level fields — later ingestions
+   * can refine earlier ones.
+   *
+   * @param sarifDocument  The raw SARIF document as received from the tool.
+   * @param sourceTool     Stable identifier of the producing scanner.
+   * @returns              Stats describing what was accepted.
+   */
+  ingestRun(
+    sarifDocument: PersistedSarif,
+    sourceTool: string,
+  ): { accepted: number; duplicates: number; total: number } {
+    if (sarifDocument.version !== "2.1.0") {
+      throw new Error(
+        `[sarif-store] ingestRun received version ${sarifDocument.version}, expected 2.1.0`,
+      );
+    }
+
+    this.toolInvocations += 1;
+    let accepted = 0;
+    let duplicates = 0;
+    let total = 0;
+
+    for (const run of sarifDocument.runs) {
+      for (const result of run.results) {
+        total += 1;
+        const finding = hydrateFindingFromResult(result, sourceTool);
+        if (!finding) continue;
+        if (this.findings.has(finding.dedupKey)) {
+          duplicates += 1;
+          // Overwrite with the latest metadata so the consolidated view
+          // reflects the most recent scanner output for this location.
+          this.findings.set(finding.dedupKey, finding);
+          continue;
+        }
+        this.findings.set(finding.dedupKey, finding);
+        accepted += 1;
+      }
+    }
+
+    return { accepted, duplicates, total };
+  }
+
+  /**
+   * Snapshot all currently tracked findings as a plain array. Mostly
+   * useful for tests and for the dashboard API.
+   */
+  list(): ReadonlyArray<IngestedFinding> {
+    return Array.from(this.findings.values());
+  }
+
+  /**
+   * Atomically write the consolidated document back to disk. Uses a
+   * temporary file and `rename` so concurrent readers never observe
+   * a half-written document.
+   */
+  async persist(): Promise<void> {
+    const doc = this.toSarifDocument();
+    await fs.mkdir(dirname(this.filePath), { recursive: true });
+    const tmp = `${this.filePath}.${process.pid}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(doc, null, 2), "utf8");
+    await fs.rename(tmp, this.filePath);
+  }
+
+  /**
+   * Build the current consolidated SARIF document from the in-memory
+   * findings without touching disk.
+   */
+  toSarifDocument() {
+    // Strip the store-only `dedupKey` and `sourceTool` fields before
+    // serializing, but keep `sourceTool` in the per-finding `properties`
+    // bag so consumers can still trace origin.
+    const findings: SarifFinding[] = Array.from(this.findings.values()).map((f) => ({
+      ruleId: f.ruleId,
+      level: f.level,
+      message: f.message,
+      location: f.location,
+      properties: {
+        ...(f.properties ?? {}),
+        sourceTool: f.sourceTool,
+      },
+    }));
+
+    return buildSarifDocument(
+      {
+        name: "claude-crap",
+        version: "0.1.0",
+        informationUri: "https://github.com/local/claude-crap",
+      },
+      findings,
+    );
+  }
+
+  /**
+   * Number of unique findings currently tracked.
+   */
+  size(): number {
+    return this.findings.size;
+  }
+
+  /**
+   * Number of times `ingestRun` has been called on this instance.
+   */
+  get invocationsCount(): number {
+    return this.toolInvocations;
+  }
+}
+
+/**
+ * Convert a raw SARIF `result` object into an {@link IngestedFinding}.
+ * Returns `null` when the result is malformed (missing ruleId, message,
+ * or physical location), since a finding without coordinates cannot be
+ * deduplicated and is therefore useless.
+ *
+ * @param result     Raw SARIF `result` object from the scanner's document.
+ * @param sourceTool Optional scanner identifier. If omitted, we read it
+ *                   from `result.properties.sourceTool` (used when
+ *                   reloading a persisted report).
+ * @returns          The hydrated finding, or `null` when invalid.
+ */
+function hydrateFindingFromResult(
+  result: SarifResult,
+  sourceTool?: string,
+): IngestedFinding | null {
+  if (!result.ruleId || !result.message?.text) return null;
+  const loc = result.locations?.[0]?.physicalLocation;
+  const uri = loc?.artifactLocation?.uri;
+  const region = loc?.region;
+  if (!uri || region?.startLine === undefined || region.startColumn === undefined) return null;
+
+  const resolvedSourceTool =
+    sourceTool ??
+    (typeof result.properties?.sourceTool === "string"
+      ? (result.properties.sourceTool as string)
+      : "unknown");
+
+  const level: SarifLevel = result.level ?? "warning";
+  const dedupKey = `${result.ruleId}|${uri}|${region.startLine}|${region.startColumn}`;
+
+  return {
+    ruleId: result.ruleId,
+    level,
+    message: result.message.text,
+    location: {
+      uri,
+      startLine: region.startLine,
+      startColumn: region.startColumn,
+      ...(region.endLine !== undefined ? { endLine: region.endLine } : {}),
+      ...(region.endColumn !== undefined ? { endColumn: region.endColumn } : {}),
+    },
+    ...(result.properties ? { properties: result.properties } : {}),
+    dedupKey,
+    sourceTool: resolvedSourceTool,
+  };
+}