claude-crap 0.1.2 → 0.3.0

package/src/scanner/bootstrap.ts

@@ -0,0 +1,383 @@
+/**
+ * Bootstrap a scanner for projects that don't have one configured.
+ *
+ * Detects the project type from workspace signals (package.json,
+ * tsconfig.json, pyproject.toml, pom.xml, *.csproj, etc.), installs
+ * the appropriate scanner, creates a minimal config file, and runs
+ * `autoScan()` to verify and ingest findings immediately.
+ *
+ * Coverage maps to the five languages the tree-sitter engine supports:
+ *
+ *   - JavaScript / TypeScript → ESLint (npm install + flat config)
+ *   - Python → Bandit (install instructions only — virtualenv boundary)
+ *   - Java → Semgrep (install instructions)
+ *   - C# → Semgrep (install instructions)
+ *   - Unknown → Semgrep (polyglot fallback)
+ *
+ * For JS/TS projects the tool runs `npm install --save-dev` and writes
+ * an `eslint.config.mjs`. For all other languages it returns manual
+ * install instructions rather than executing package managers whose
+ * environment assumptions may not hold.
+ *
+ * @module scanner/bootstrap
+ */
+
+import { existsSync, writeFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+import type { Logger } from "pino";
+import type { KnownScanner } from "../adapters/common.js";
+import { detectScanners } from "./detector.js";
+import { autoScan, type AutoScanResult } from "./auto-scan.js";
+import type { SarifStore } from "../sarif/sarif-store.js";
+
+// ── Types ──────────────────────────────────────────────────────────
+
+/**
+ * Detected project type, aligned with tree-sitter supported languages.
+ */
+export type ProjectType =
+  | "javascript"
+  | "typescript"
+  | "python"
+  | "java"
+  | "csharp"
+  | "unknown";
+
+/**
+ * A single step in the bootstrap process.
+ */
+export interface BootstrapStep {
+  /** What was attempted (e.g. "install eslint", "create eslint.config.mjs"). */
+  action: string;
+  /** Whether the step completed successfully. */
+  success: boolean;
+  /** Human-readable detail (command output, error message, or instruction). */
+  detail: string;
+}
+
+/**
+ * Complete result of a bootstrap_scanner invocation.
+ */
+export interface BootstrapResult {
+  /** Detected project type based on workspace signals. */
+  projectType: ProjectType;
+  /** Whether a scanner was already configured (detected by detector.ts). */
+  alreadyConfigured: boolean;
+  /** Which scanners were already available, if any. */
+  existingScanners: string[];
+  /** Steps executed (or instructions returned) during bootstrap. */
+  steps: BootstrapStep[];
+  /** The auto-scan result after installation (null if skipped). */
+  autoScanResult: AutoScanResult | null;
+  /** Whether the overall bootstrap succeeded. */
+  success: boolean;
+  /** Summary message suitable for display. */
+  summary: string;
+}
+
+// ── Project type detection ─────────────────────────────────────────
+
+/**
+ * Detect the project type from workspace signals.
+ *
+ * Checks in priority order: TypeScript, JavaScript, Python, Java,
+ * C#, then unknown. TypeScript wins over plain JavaScript because
+ * `tsconfig.json` implies a superset.
+ */
+export function detectProjectType(workspaceRoot: string): ProjectType {
+  const has = (file: string) => existsSync(join(workspaceRoot, file));
+
+  // JS/TS detection — package.json is the anchor
+  if (has("package.json")) {
+    if (has("tsconfig.json")) return "typescript";
+    return "javascript";
+  }
+
+  // Python detection
+  if (has("pyproject.toml") || has("setup.py") || has("requirements.txt")) {
+    return "python";
+  }
+
+  // Java detection
+  if (has("pom.xml") || has("build.gradle") || has("build.gradle.kts")) {
+    return "java";
+  }
+
+  // C# detection
+  if (has("Directory.Build.props")) return "csharp";
+  try {
+    const entries = readdirSync(workspaceRoot);
+    if (entries.some((e) => e.endsWith(".csproj") || e.endsWith(".sln"))) {
+      return "csharp";
+    }
+  } catch {
+    // readdirSync can fail on permissions — fall through
+  }
+
+  return "unknown";
+}
+
+// ── ESLint config generation ───────────────────────────────────────
+
+/**
+ * Generate a minimal ESLint flat config (ESLint 9+).
+ *
+ * @param isTypeScript Include typescript-eslint when true.
+ * @returns The config file content as a string.
+ */
+export function generateEslintConfig(isTypeScript: boolean): string {
+  if (isTypeScript) {
+    return `import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    ignores: ["dist/", "node_modules/", "coverage/"],
+  },
+);
+`;
+  }
+
+  return `import js from "@eslint/js";
+
+export default [
+  js.configs.recommended,
+  {
+    ignores: ["dist/", "node_modules/", "coverage/"],
+  },
+];
+`;
+}
+
+// ── Installation helpers ───────────────────────────────────────────
+
+/**
+ * Run `npm install --save-dev` for the given packages.
+ */
+function npmInstall(
+  workspaceRoot: string,
+  packages: string[],
+): Promise<BootstrapStep> {
+  return new Promise((resolve) => {
+    execFile(
+      "npm",
+      ["install", "--save-dev", ...packages],
+      {
+        cwd: workspaceRoot,
+        timeout: 120_000,
+        env: { ...process.env, FORCE_COLOR: "0" },
+      },
+      (err, stdout, stderr) => {
+        if (err) {
+          resolve({
+            action: `npm install --save-dev ${packages.join(" ")}`,
+            success: false,
+            detail: stderr || (err as Error).message,
+          });
+          return;
+        }
+        resolve({
+          action: `npm install --save-dev ${packages.join(" ")}`,
+          success: true,
+          detail: `installed ${packages.join(", ")}`,
+        });
+      },
+    );
+  });
+}
+
+/**
+ * Write the ESLint config file to the workspace root.
+ * Returns failure if the file already exists.
+ */
+function writeEslintConfigFile(
+  workspaceRoot: string,
+  isTypeScript: boolean,
+): BootstrapStep {
+  const configPath = join(workspaceRoot, "eslint.config.mjs");
+  if (existsSync(configPath)) {
+    return {
+      action: "create eslint.config.mjs",
+      success: true,
+      detail: "eslint.config.mjs already exists — skipped",
+    };
+  }
+
+  try {
+    writeFileSync(configPath, generateEslintConfig(isTypeScript), "utf-8");
+    return {
+      action: "create eslint.config.mjs",
+      success: true,
+      detail: `created eslint.config.mjs (${isTypeScript ? "TypeScript" : "JavaScript"} template)`,
+    };
+  } catch (err) {
+    return {
+      action: "create eslint.config.mjs",
+      success: false,
+      detail: (err as Error).message,
+    };
+  }
+}
+
+// ── Scanner-to-language mapping ────────────────────────────────────
+
+/**
+ * Map project type → recommended scanner and install instructions.
+ */
+interface ScannerRecommendation {
+  scanner: KnownScanner;
+  canAutoInstall: boolean;
+  installInstructions: string;
+}
+
+function getRecommendation(projectType: ProjectType): ScannerRecommendation {
+  switch (projectType) {
+    case "javascript":
+    case "typescript":
+      return {
+        scanner: "eslint",
+        canAutoInstall: true,
+        installInstructions: "npm install --save-dev eslint @eslint/js",
+      };
+    case "python":
+      return {
+        scanner: "bandit",
+        canAutoInstall: false,
+        installInstructions:
+          "pip install bandit  (or: pipx install bandit, poetry add --group dev bandit)",
+      };
+    case "java":
+    case "csharp":
+      return {
+        scanner: "semgrep",
+        canAutoInstall: false,
+        installInstructions:
+          "brew install semgrep  (or: pip install semgrep, pipx install semgrep)",
+      };
+    case "unknown":
+      return {
+        scanner: "semgrep",
+        canAutoInstall: false,
+        installInstructions:
+          "brew install semgrep  (or: pip install semgrep, pipx install semgrep)",
+      };
+  }
+}
+
+// ── Main orchestrator ──────────────────────────────────────────────
+
+/**
+ * Bootstrap a scanner for the current workspace.
+ *
+ * 1. Check if a scanner is already configured (short-circuit if so)
+ * 2. Detect the project type
+ * 3. Install the recommended scanner (or return instructions)
+ * 4. Run auto_scan to verify and ingest findings
+ *
+ * @param workspaceRoot Absolute path to the project root.
+ * @param sarifStore    Live SARIF store for auto-scan ingestion.
+ * @param logger        Pino logger for progress reporting.
+ */
+export async function bootstrapScanner(
+  workspaceRoot: string,
+  sarifStore: SarifStore,
+  logger: Logger,
+): Promise<BootstrapResult> {
+  // 1. Check existing scanners
+  const detections = await detectScanners(workspaceRoot);
+  const available = detections.filter((d) => d.available);
+
+  if (available.length > 0) {
+    const existingScanners = available.map((d) => d.scanner);
+    logger.info(
+      { existingScanners },
+      "bootstrap: scanner(s) already configured — skipping",
+    );
+    return {
+      projectType: detectProjectType(workspaceRoot),
+      alreadyConfigured: true,
+      existingScanners,
+      steps: [],
+      autoScanResult: null,
+      success: true,
+      summary: `Scanner(s) already configured: ${existingScanners.join(", ")}. Run auto_scan to ingest findings.`,
+    };
+  }
+
+  // 2. Detect project type
+  const projectType = detectProjectType(workspaceRoot);
+  const recommendation = getRecommendation(projectType);
+  const steps: BootstrapStep[] = [];
+
+  logger.info(
+    { projectType, scanner: recommendation.scanner },
+    "bootstrap: detected project type",
+  );
+
+  // 3. Install scanner
+  if (recommendation.canAutoInstall) {
+    // JS/TS: auto-install ESLint
+    const isTypeScript = projectType === "typescript";
+    const packages = isTypeScript
+      ? ["eslint", "@eslint/js", "typescript-eslint"]
+      : ["eslint", "@eslint/js"];
+
+    const installStep = await npmInstall(workspaceRoot, packages);
+    steps.push(installStep);
+
+    if (installStep.success) {
+      const configStep = writeEslintConfigFile(workspaceRoot, isTypeScript);
+      steps.push(configStep);
+    }
+  } else {
+    // Python / Java / C# / Unknown: return instructions
+    steps.push({
+      action: `suggest ${recommendation.scanner} install`,
+      success: true,
+      detail: recommendation.installInstructions,
+    });
+  }
+
+  // 4. Run auto_scan if installation succeeded
+  const installSucceeded = steps.every((s) => s.success);
+  let autoScanResult: AutoScanResult | null = null;
+
+  if (installSucceeded && recommendation.canAutoInstall) {
+    try {
+      autoScanResult = await autoScan(workspaceRoot, sarifStore, logger);
+    } catch (err) {
+      logger.warn(
+        { err: (err as Error).message },
+        "bootstrap: auto_scan after install failed",
+      );
+    }
+  }
+
+  // 5. Build result
+  const findings = autoScanResult?.totalFindings ?? 0;
+  const scannerInstalled = recommendation.canAutoInstall && installSucceeded;
+
+  let summary: string;
+  if (scannerInstalled && autoScanResult) {
+    summary = `Installed ${recommendation.scanner} for ${projectType} project. Auto-scan found ${findings} finding(s).`;
+  } else if (scannerInstalled) {
+    summary = `Installed ${recommendation.scanner} for ${projectType} project. Auto-scan did not run.`;
+  } else if (!recommendation.canAutoInstall) {
+    summary = `Detected ${projectType} project. Install ${recommendation.scanner} manually: ${recommendation.installInstructions}`;
+  } else {
+    summary = `Failed to install ${recommendation.scanner}. Check the error details in the steps.`;
+  }
+
+  return {
+    projectType,
+    alreadyConfigured: false,
+    existingScanners: [],
+    steps,
+    autoScanResult,
+    success: installSucceeded,
+    summary,
+  };
+}

package/src/scanner/detector.ts

@@ -0,0 +1,224 @@
+/**
+ * Auto-detect which scanners are available in the current workspace.
+ *
+ * For each of the four supported scanners (ESLint, Semgrep, Bandit,
+ * Stryker) the detector probes three signal layers in order:
+ *
+ *   1. Config file existence (fastest — a single `fs.stat`)
+ *   2. Package.json dependency (for JS-ecosystem scanners)
+ *   3. Binary availability via `which` (slowest — spawns a child process)
+ *
+ * Detection short-circuits on the first hit, so a project that has an
+ * `eslint.config.mjs` will never shell out to `which eslint`.
+ *
+ * The module is side-effect-free beyond filesystem reads and one
+ * `child_process.execFile` per binary probe.
+ *
+ * @module scanner/detector
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+import type { KnownScanner } from "../adapters/common.js";
+
+// ── Types ──────────────────────────────────────────────────────────
+
+/**
+ * Result of probing a single scanner's availability.
+ */
+export interface ScannerDetection {
+  /** Which scanner was probed. */
+  scanner: KnownScanner;
+  /** Whether the scanner is available and can be executed. */
+  available: boolean;
+  /** Human-readable reason for the verdict. */
+  reason: string;
+  /** Path to the config file that triggered detection, if any. */
+  configPath?: string;
+}
+
+// ── Detection signals ──────────────────────────────────────────────
+
+/**
+ * Config file globs and package.json keys per scanner. Order matters:
+ * the first matching config file short-circuits further probes.
+ */
+interface ScannerSignals {
+  configFiles: string[];
+  packageJsonKeys: string[];
+  binaryNames: string[];
+}
+
+const SCANNER_SIGNALS: Record<KnownScanner, ScannerSignals> = {
+  eslint: {
+    configFiles: [
+      "eslint.config.js",
+      "eslint.config.mjs",
+      "eslint.config.cjs",
+      "eslint.config.ts",
+      "eslint.config.mts",
+      "eslint.config.cts",
+      ".eslintrc.js",
+      ".eslintrc.cjs",
+      ".eslintrc.yaml",
+      ".eslintrc.yml",
+      ".eslintrc.json",
+    ],
+    packageJsonKeys: ["eslint"],
+    binaryNames: ["eslint"],
+  },
+  semgrep: {
+    configFiles: [
+      ".semgrep.yml",
+      ".semgrep.yaml",
+      ".semgrep.json",
+    ],
+    packageJsonKeys: [],
+    binaryNames: ["semgrep"],
+  },
+  bandit: {
+    configFiles: [
+      ".bandit",
+      "bandit.yaml",
+      "bandit.yml",
+    ],
+    packageJsonKeys: [],
+    binaryNames: ["bandit"],
+  },
+  stryker: {
+    configFiles: [
+      "stryker.conf.js",
+      "stryker.conf.mjs",
+      "stryker.conf.cjs",
+      "stryker.conf.json",
+      ".strykerrc",
+      ".strykerrc.json",
+    ],
+    packageJsonKeys: ["@stryker-mutator/core"],
+    binaryNames: ["stryker"],
+  },
+};
+
+// ── Probes ──────────────────────────────────────────────────────────
+
+/**
+ * Check if any of the scanner's config files exist in the workspace.
+ */
+function probeConfigFiles(
+  workspaceRoot: string,
+  scanner: KnownScanner,
+): { found: boolean; path?: string } {
+  const signals = SCANNER_SIGNALS[scanner];
+  for (const file of signals.configFiles) {
+    const fullPath = join(workspaceRoot, file);
+    if (existsSync(fullPath)) {
+      return { found: true, path: fullPath };
+    }
+  }
+  return { found: false };
+}
+
+/**
+ * Check if the scanner appears in package.json deps or devDeps.
+ */
+function probePackageJson(
+  workspaceRoot: string,
+  scanner: KnownScanner,
+): boolean {
+  const signals = SCANNER_SIGNALS[scanner];
+  if (signals.packageJsonKeys.length === 0) return false;
+
+  const pkgPath = join(workspaceRoot, "package.json");
+  if (!existsSync(pkgPath)) return false;
+
+  try {
+    const raw = readFileSync(pkgPath, "utf-8");
+    const pkg = JSON.parse(raw) as Record<string, unknown>;
+    const deps = {
+      ...(typeof pkg.dependencies === "object" && pkg.dependencies !== null
+        ? (pkg.dependencies as Record<string, string>)
+        : {}),
+      ...(typeof pkg.devDependencies === "object" && pkg.devDependencies !== null
+        ? (pkg.devDependencies as Record<string, string>)
+        : {}),
+    };
+    return signals.packageJsonKeys.some((key) => key in deps);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a binary is available on PATH via `which`.
+ */
+function probeBinary(binaryName: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    execFile("which", [binaryName], { timeout: 5_000 }, (err) => {
+      resolve(err === null);
+    });
+  });
+}
+
+// ── Public API ──────────────────────────────────────────────────────
+
+/**
+ * Detect which of the four supported scanners are available in the
+ * given workspace. Probes config files, package.json, and binary
+ * availability in order, short-circuiting on first match.
+ *
+ * @param workspaceRoot Absolute path to the project root.
+ * @returns One {@link ScannerDetection} per known scanner.
+ */
+export async function detectScanners(
+  workspaceRoot: string,
+): Promise<ScannerDetection[]> {
+  const scanners: KnownScanner[] = ["eslint", "semgrep", "bandit", "stryker"];
+
+  const results = await Promise.all(
+    scanners.map(async (scanner): Promise<ScannerDetection> => {
+      // 1. Config file probe (fastest)
+      const configProbe = probeConfigFiles(workspaceRoot, scanner);
+      if (configProbe.found && configProbe.path) {
+        return {
+          scanner,
+          available: true,
+          reason: `config file found: ${configProbe.path.replace(workspaceRoot + "/", "")}`,
+          configPath: configProbe.path,
+        };
+      }
+
+      // 2. Package.json probe
+      if (probePackageJson(workspaceRoot, scanner)) {
+        return {
+          scanner,
+          available: true,
+          reason: `found in package.json dependencies`,
+        };
+      }
+
+      // 3. Binary probe (slowest)
+      const signals = SCANNER_SIGNALS[scanner];
+      for (const bin of signals.binaryNames) {
+        if (await probeBinary(bin)) {
+          return {
+            scanner,
+            available: true,
+            reason: `binary "${bin}" found on PATH`,
+          };
+        }
+      }
+
+      return {
+        scanner,
+        available: false,
+        reason: "no config file, package.json entry, or binary found",
+      };
+    }),
+  );
+
+  return results;
+}
+
+// Exported for testing
+export { SCANNER_SIGNALS };

package/src/scanner/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Public SDK entry point for the scanner auto-detection and execution
+ * pipeline.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import { autoScan, detectScanners } from "claude-crap/scanner";
+ *
+ * // Full pipeline: detect → run → ingest
+ * const result = await autoScan(workspaceRoot, sarifStore, logger);
+ *
+ * // Detection only (no execution)
+ * const detections = await detectScanners(workspaceRoot);
+ * ```
+ *
+ * @module scanner
+ */
+
+export { detectScanners, type ScannerDetection } from "./detector.js";
+export { runScanner, type ScannerRunResult } from "./runner.js";
+export { autoScan, type AutoScanResult, type ScannerResult } from "./auto-scan.js";
+export {
+  bootstrapScanner,
+  detectProjectType,
+  generateEslintConfig,
+  type BootstrapResult,
+  type BootstrapStep,
+  type ProjectType,
+} from "./bootstrap.js";