claude-crap 0.1.2

package/src/ast/tree-sitter-engine.ts

@@ -0,0 +1,385 @@
+/**
+ * Tree-sitter based AST analysis engine.
+ *
+ * This module wraps `web-tree-sitter` (the WASM build of tree-sitter) to
+ * parse source files and extract deterministic per-function metrics. The
+ * WASM variant is used instead of the native bindings so that `npm install`
+ * never has to invoke a C compiler — matching the plugin's "zero install
+ * friction" promise.
+ *
+ * The engine is lazy:
+ *
+ *   - `web-tree-sitter` is initialized only on first use.
+ *   - Grammar WASM files are loaded on demand and cached per language.
+ *
+ * This keeps MCP server startup fast (crucial because Claude Code will
+ * spin the server up and tear it down across sessions).
+ *
+ * Usage:
+ *
+ * ```ts
+ * const engine = new TreeSitterEngine();
+ * const result = await engine.analyzeFile({
+ *   filePath: "src/foo.ts",
+ *   language: "typescript",
+ * });
+ * console.log(result.functions);
+ * ```
+ *
+ * @module ast/tree-sitter-engine
+ */
+
+import { promises as fs } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { computeCyclomaticComplexity, type AstNode } from "./cyclomatic.js";
+import { LANGUAGE_TABLE, type LanguageConfig, type SupportedLanguage } from "./language-config.js";
+
+/**
+ * Minimal typed view of the `web-tree-sitter` Parser class and its
+ * static helpers. The npm package uses `export = Parser` (a CommonJS
+ * default export), so under ESM interop `await import('web-tree-sitter')`
+ * returns `{ default: Parser }` where `Parser`:
+ *
+ *   - is a constructable class (`new Parser()`)
+ *   - exposes `static init(moduleOptions)` to bootstrap the WASM runtime
+ *   - exposes the nested `Parser.Language.load(pathOrBytes)` static
+ *     to load a grammar from a `.wasm` file or a raw byte buffer
+ *
+ * We model that surface here so downstream consumers of this engine are
+ * not forced to import `web-tree-sitter` types directly.
+ */
+interface ParserInstance {
+  setLanguage(language: unknown): void;
+  parse(source: string): { rootNode: AstNode };
+}
+
+interface ParserCtor {
+  new (): ParserInstance;
+  init(options?: { locateFile?: (name: string) => string }): Promise<void>;
+  Language: { load(path: string | Uint8Array): Promise<unknown> };
+}
+
+/**
+ * Per-function metrics returned by the engine.
+ */
+export interface FunctionMetrics {
+  /** Human-readable function name, or `"<anonymous>"` when not available. */
+  readonly name: string;
+  /** 1-based line where the function body starts. */
+  readonly startLine: number;
+  /** 1-based line where the function body ends. */
+  readonly endLine: number;
+  /** McCabe cyclomatic complexity (always ≥ 1). */
+  readonly cyclomaticComplexity: number;
+  /** Physical lines of code covered by the function (endLine - startLine + 1). */
+  readonly lineCount: number;
+}
+
+/**
+ * File-level metrics returned by the engine.
+ */
+export interface FileMetrics {
+  /** File path that was analyzed, echoed from the request for traceability. */
+  readonly filePath: string;
+  /** Language the file was parsed as. */
+  readonly language: SupportedLanguage;
+  /** Total physical lines in the file, including blanks and comments. */
+  readonly physicalLoc: number;
+  /** Physical lines that contain at least one non-whitespace character. */
+  readonly logicalLoc: number;
+  /** Per-function metrics sorted by starting line. */
+  readonly functions: ReadonlyArray<FunctionMetrics>;
+}
+
+/**
+ * Request accepted by {@link TreeSitterEngine.analyzeFile}.
+ */
+export interface AnalyzeFileRequest {
+  readonly filePath: string;
+  readonly language: SupportedLanguage;
+}
+
+/**
+ * Options accepted by the engine constructor. All fields are optional and
+ * safe defaults are used when omitted.
+ */
+export interface TreeSitterEngineOptions {
+  /**
+   * Directory where the language grammar WASM files live (one per
+   * language, e.g. `tree-sitter-typescript.wasm`). Defaults to the
+   * `tree-sitter-wasms/out` directory inside `node_modules`.
+   */
+  readonly grammarsDir?: string;
+  /**
+   * Directory where the `web-tree-sitter` runtime WASM (`tree-sitter.wasm`)
+   * lives. This is a different package from the grammars — the runtime
+   * ships with `web-tree-sitter` itself. Defaults to that package's
+   * install directory inside `node_modules`.
+   */
+  readonly runtimeDir?: string;
+  /**
+   * Override the WASM loader for tests. Receives the grammar filename
+   * and must return the raw bytes.
+   */
+  readonly loadGrammar?: (wasmPath: string) => Promise<Uint8Array>;
+}
+
+/**
+ * High-level AST engine. Instances are meant to be long-lived — create
+ * one at server startup and reuse it for every analysis request.
+ */
+export class TreeSitterEngine {
+  private parserCtor: ParserCtor | null = null;
+  private readonly loadedLanguages = new Map<SupportedLanguage, unknown>();
+  private readonly grammarsDir: string;
+  private readonly runtimeDir: string;
+  private readonly loadGrammar: (wasmPath: string) => Promise<Uint8Array>;
+  private initPromise: Promise<void> | null = null;
+
+  constructor(options: TreeSitterEngineOptions = {}) {
+    this.grammarsDir = options.grammarsDir ?? resolveDefaultGrammarsDir();
+    this.runtimeDir = options.runtimeDir ?? resolveDefaultRuntimeDir();
+    this.loadGrammar = options.loadGrammar ?? ((path) => fs.readFile(path));
+  }
+
+  /**
+   * Analyze a source file and return per-function and file-level metrics.
+   *
+   * @param req The analysis request.
+   * @returns   A {@link FileMetrics} snapshot ready to be serialized.
+   * @throws    When the file cannot be read or the grammar cannot be loaded.
+   */
+  async analyzeFile(req: AnalyzeFileRequest): Promise<FileMetrics> {
+    const languageConfig = LANGUAGE_TABLE[req.language];
+    if (!languageConfig) {
+      throw new Error(`[tree-sitter-engine] Unsupported language: ${req.language}`);
+    }
+
+    const source = await fs.readFile(req.filePath, "utf8");
+    const parser = await this.ensureParserFor(languageConfig);
+    const tree = parser.parse(source);
+
+    const functions = collectFunctionMetrics(tree.rootNode, languageConfig);
+    const { physicalLoc, logicalLoc } = countLines(source);
+
+    return {
+      filePath: req.filePath,
+      language: languageConfig.id,
+      physicalLoc,
+      logicalLoc,
+      functions,
+    };
+  }
+
+  /**
+   * Ensure a parser with the requested language grammar bound is ready.
+   * Both the Parser class and the grammar are initialized lazily and
+   * cached on first use.
+   *
+   * @param config Language configuration for the requested grammar.
+   * @returns      A fresh parser instance configured for the language.
+   */
+  private async ensureParserFor(config: LanguageConfig): Promise<ParserInstance> {
+    if (!this.parserCtor) {
+      if (!this.initPromise) {
+        this.initPromise = this.initParserModule();
+      }
+      await this.initPromise;
+    }
+    const Parser = this.parserCtor;
+    if (!Parser) {
+      throw new Error("[tree-sitter-engine] Parser class failed to initialize");
+    }
+
+    let language = this.loadedLanguages.get(config.id);
+    if (!language) {
+      const wasmPath = join(this.grammarsDir, config.wasmName);
+      const bytes = await this.loadGrammar(wasmPath);
+      language = await Parser.Language.load(bytes);
+      this.loadedLanguages.set(config.id, language);
+    }
+
+    const parser = new Parser();
+    parser.setLanguage(language);
+    return parser;
+  }
+
+  /**
+   * Import and initialize `web-tree-sitter`. Isolated in its own method
+   * so the dynamic import runs exactly once per engine instance.
+   *
+   * `web-tree-sitter` uses `export = Parser` so under ESM interop the
+   * Parser class arrives on the `default` property of the imported
+   * namespace. `Parser.init()` is a STATIC method on the class, not a
+   * top-level module function.
+   */
+  private async initParserModule(): Promise<void> {
+    const imported = (await import("web-tree-sitter")) as { default: ParserCtor };
+    const Parser = imported.default;
+    if (!Parser || typeof Parser.init !== "function") {
+      throw new Error(
+        "[tree-sitter-engine] web-tree-sitter did not expose the expected Parser class",
+      );
+    }
+    // Emscripten calls `locateFile` to resolve the runtime WASM during
+    // `Parser.init()`. The runtime file (`tree-sitter.wasm`) lives inside
+    // the `web-tree-sitter` package itself, NOT alongside the grammars,
+    // so we route requests for that exact filename to `runtimeDir`.
+    // Anything else falls back to `grammarsDir` for the per-language
+    // grammar files loaded later by `Parser.Language.load()`.
+    await Parser.init({
+      locateFile: (name: string) =>
+        name === "tree-sitter.wasm"
+          ? join(this.runtimeDir, name)
+          : join(this.grammarsDir, name),
+    });
+    this.parserCtor = Parser;
+  }
+}
+
+/**
+ * Resolve the default grammar directory to `tree-sitter-wasms/out` inside
+ * `node_modules`. Uses `createRequire` so the lookup works regardless of
+ * whether the caller is running from source (`tsx`) or from the built
+ * `dist/` directory.
+ */
+function resolveDefaultGrammarsDir(): string {
+  try {
+    const requireFromHere = createRequire(import.meta.url);
+    // `tree-sitter-wasms` exposes its grammar files under `out/`.
+    const pkgJsonPath = requireFromHere.resolve("tree-sitter-wasms/package.json");
+    return join(dirname(pkgJsonPath), "out");
+  } catch {
+    // Fall back to a sibling `grammars/` directory if the npm package
+    // is not installed — useful for repo-local grammars.
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolve(here, "..", "..", "grammars");
+  }
+}
+
+/**
+ * Resolve the default runtime directory to the `web-tree-sitter` package
+ * root inside `node_modules`. The runtime WASM (`tree-sitter.wasm`) ships
+ * with the `web-tree-sitter` package itself rather than with the grammar
+ * package, so we have to look it up separately from the grammars.
+ */
+function resolveDefaultRuntimeDir(): string {
+  try {
+    const requireFromHere = createRequire(import.meta.url);
+    const pkgJsonPath = requireFromHere.resolve("web-tree-sitter/package.json");
+    return dirname(pkgJsonPath);
+  } catch {
+    // Fall back to the grammars directory — better than nothing if
+    // someone is running with a custom layout.
+    return resolveDefaultGrammarsDir();
+  }
+}
+
+/**
+ * Walk the top-level AST and collect metrics for every function node,
+ * including nested functions. The caller gets a flat, line-sorted list.
+ *
+ * @param root           AST root node returned by tree-sitter.
+ * @param languageConfig Language tables to classify nodes.
+ * @returns              Flat list of function metrics sorted by start line.
+ */
+function collectFunctionMetrics(
+  root: AstNode,
+  languageConfig: LanguageConfig,
+): ReadonlyArray<FunctionMetrics> {
+  const out: FunctionMetrics[] = [];
+
+  function visit(node: AstNode): void {
+    if (languageConfig.functionNodeTypes.has(node.type)) {
+      out.push(buildFunctionMetrics(node, languageConfig));
+      // Intentionally continue the walk so nested functions are also
+      // reported. Each nested function's complexity is computed against
+      // its own subtree; cyclomatic.ts skips nested functions during
+      // the walk so the parent's score is not inflated.
+    }
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (child) visit(child);
+    }
+  }
+
+  visit(root);
+  out.sort((a, b) => a.startLine - b.startLine);
+  return out;
+}
+
+/**
+ * Build a {@link FunctionMetrics} record for a single function node.
+ */
+function buildFunctionMetrics(node: AstNode, languageConfig: LanguageConfig): FunctionMetrics {
+  const name = extractFunctionName(node, languageConfig);
+  const position = extractPosition(node);
+  const complexity = computeCyclomaticComplexity(node, languageConfig);
+  return {
+    name,
+    startLine: position.startLine,
+    endLine: position.endLine,
+    cyclomaticComplexity: complexity,
+    lineCount: position.endLine - position.startLine + 1,
+  };
+}
+
+/**
+ * Pull the function name out of a function node. Tree-sitter exposes a
+ * `childForFieldName` accessor on its real nodes; we feature-detect it
+ * because our minimal {@link AstNode} contract does not require it.
+ */
+function extractFunctionName(node: AstNode, languageConfig: LanguageConfig): string {
+  const anyNode = node as AstNode & {
+    childForFieldName?: (field: string) => AstNode | null;
+  };
+  if (typeof anyNode.childForFieldName === "function") {
+    for (const field of languageConfig.nameFieldCandidates) {
+      const nameNode = anyNode.childForFieldName(field);
+      if (nameNode && nameNode.text) return nameNode.text;
+    }
+  }
+  return "<anonymous>";
+}
+
+/**
+ * Extract 1-based start/end line numbers for a node. Tree-sitter nodes
+ * expose `startPosition` and `endPosition` with zero-based rows.
+ */
+function extractPosition(node: AstNode): { startLine: number; endLine: number } {
+  const anyNode = node as AstNode & {
+    startPosition?: { row: number };
+    endPosition?: { row: number };
+  };
+  const startRow = anyNode.startPosition?.row ?? 0;
+  const endRow = anyNode.endPosition?.row ?? startRow;
+  return { startLine: startRow + 1, endLine: endRow + 1 };
+}
+
+/**
+ * Count physical and logical lines of code in a raw source string.
+ *
+ * - **Physical LOC**: number of newline-separated lines, matching how
+ *   most IDEs report file length.
+ * - **Logical LOC**: number of lines that contain at least one
+ *   non-whitespace character.
+ *
+ * Comment detection is intentionally NOT done here; comment stripping
+ * requires language-aware parsing and the caller can derive a comment
+ * ratio from the AST node list if needed.
+ *
+ * @param source Raw source text.
+ * @returns      An object with `physicalLoc` and `logicalLoc`.
+ */
+function countLines(source: string): { physicalLoc: number; logicalLoc: number } {
+  if (source.length === 0) return { physicalLoc: 0, logicalLoc: 0 };
+  const lines = source.split(/\r?\n/);
+  let logical = 0;
+  for (const line of lines) {
+    if (line.trim().length > 0) logical += 1;
+  }
+  return { physicalLoc: lines.length, logicalLoc: logical };
+}

package/src/config.ts

@@ -0,0 +1,109 @@
+/**
+ * Deterministic configuration loader for the claude-crap MCP server.
+ *
+ * Every tunable knob is read from environment variables that are injected
+ * by `.mcp.json` at server startup. Those variables are themselves derived
+ * from the `CLAUDE_PLUGIN_OPTION_*` values defined in the plugin manifest,
+ * which means the configuration chain is:
+ *
+ *   user settings  →  plugin.json "options"  →  .mcp.json "env"  →  this file
+ *
+ * If any environment variable is missing or empty, a safe default is used,
+ * but the loader NEVER invents stochastic values and NEVER performs I/O.
+ * This module is the single source of truth for runtime configuration.
+ *
+ * @module config
+ */
+
+/**
+ * Maintainability rating letter grades used throughout claude-crap.
+ *
+ * The ordering is strict: A is best, E is worst. Callers that need to
+ * compare two ratings should use {@link ratingToRank} from `metrics/tdr.ts`
+ * rather than comparing the letters directly.
+ */
+export type MaintainabilityRating = "A" | "B" | "C" | "D" | "E";
+
+/**
+ * Fully resolved configuration object consumed by every subsystem of the
+ * MCP server. Fields are `readonly` so that downstream code cannot mutate
+ * configuration at runtime — any change must go through a server restart.
+ */
+export interface CrapConfig {
+  /** Absolute path to the plugin root on disk. Defaults to `process.cwd()`. */
+  readonly pluginRoot: string;
+  /** Directory (relative to the workspace) where consolidated SARIF reports are written. */
+  readonly sarifOutputDir: string;
+  /** Hard block threshold for the CRAP index. Functions above this fail the Stop quality gate. */
+  readonly crapThreshold: number;
+  /** Maximum cyclomatic complexity allowed per function before warnings fire. */
+  readonly cyclomaticMax: number;
+  /** Highest (worst) maintainability rating the project is allowed to hold. */
+  readonly tdrMaxRating: MaintainabilityRating;
+  /** Assumed development cost per line of code, in minutes. Used as the TDR denominator. */
+  readonly minutesPerLoc: number;
+  /** Local TCP port the Vue.js dashboard will bind to. */
+  readonly dashboardPort: number;
+}
+
+/**
+ * Parse a numeric environment variable, falling back to `fallback` when the
+ * variable is undefined or empty. Throws if the value is present but not a
+ * finite number — we prefer a loud startup failure over silently using a
+ * wrong threshold.
+ *
+ * @param name     Environment variable name, used only for the error message.
+ * @param raw      Raw value read from `process.env`.
+ * @param fallback Default value used when `raw` is undefined/empty.
+ * @returns        The parsed number.
+ * @throws         When `raw` is present but not a finite number.
+ */
+function parseNumber(name: string, raw: string | undefined, fallback: number): number {
+  if (raw === undefined || raw === "") return fallback;
+  const value = Number(raw);
+  if (!Number.isFinite(value)) {
+    throw new Error(`[claude-crap] Env ${name}="${raw}" is not a finite number`);
+  }
+  return value;
+}
+
+/**
+ * Parse a maintainability rating from an environment variable. Accepts any
+ * casing (`a`, `A`, `  a  ` all become `"A"`). Throws on invalid letters so
+ * the server refuses to start rather than running with an unknown policy.
+ *
+ * @param raw      Raw value read from `process.env`.
+ * @param fallback Default rating used when `raw` is undefined.
+ * @returns        A validated {@link MaintainabilityRating}.
+ * @throws         When `raw` is a non-empty string that is not A..E.
+ */
+function parseRating(raw: string | undefined, fallback: MaintainabilityRating): MaintainabilityRating {
+  if (!raw) return fallback;
+  const normalized = raw.trim().toUpperCase();
+  if (!["A", "B", "C", "D", "E"].includes(normalized)) {
+    throw new Error(`[claude-crap] TDR_MAX_RATING="${raw}" must be one of A, B, C, D, E`);
+  }
+  return normalized as MaintainabilityRating;
+}
+
+/**
+ * Build the complete {@link CrapConfig} from the current process environment.
+ *
+ * This should be called exactly once at server startup. Subsequent callers
+ * that need configuration should accept a `CrapConfig` parameter instead
+ * of re-reading from `process.env`, so that tests can inject custom values.
+ *
+ * @returns A fully validated, immutable configuration object.
+ * @throws  When any environment variable is present but malformed.
+ */
+export function loadConfig(): CrapConfig {
+  return {
+    pluginRoot: process.env.CLAUDE_CRAP_PLUGIN_ROOT ?? process.cwd(),
+    sarifOutputDir: process.env.CLAUDE_CRAP_SARIF_OUTPUT_DIR ?? ".claude-crap/reports",
+    crapThreshold: parseNumber("CLAUDE_CRAP_CRAP_THRESHOLD", process.env.CLAUDE_CRAP_CRAP_THRESHOLD, 30),
+    cyclomaticMax: parseNumber("CLAUDE_CRAP_CYCLOMATIC_MAX", process.env.CLAUDE_CRAP_CYCLOMATIC_MAX, 15),
+    tdrMaxRating: parseRating(process.env.CLAUDE_CRAP_TDR_MAX_RATING, "C"),
+    minutesPerLoc: parseNumber("CLAUDE_CRAP_MINUTES_PER_LOC", process.env.CLAUDE_CRAP_MINUTES_PER_LOC, 30),
+    dashboardPort: parseNumber("CLAUDE_CRAP_DASHBOARD_PORT", process.env.CLAUDE_CRAP_DASHBOARD_PORT, 5117),
+  };
+}

package/src/crap-config.ts

@@ -0,0 +1,196 @@
+/**
+ * Workspace-level sonar configuration loader.
+ *
+ * Every subsystem that can be made stricter or looser (the Stop
+ * quality gate, the `score_project` tool's `isError` flag) consults
+ * this loader to decide how hard to push back when a policy fails.
+ * Teams adopt claude-crap in stages:
+ *
+ *   - `strict` (default) — the Stop hook exits 2 on any policy
+ *     failure and the `score_project` tool returns `isError: true`.
+ *     Matches the current, hard-coded behavior.
+ *   - `warn`              — the Stop hook exits 0 but writes the
+ *     full verdict to stdout so the agent still sees every failing
+ *     rule in its hook transcript. `score_project.isError` stays
+ *     false even on a failing project.
+ *   - `advisory`          — the Stop hook exits 0 and writes a
+ *     single-line summary. Minimal pressure on the agent.
+ *
+ * The loader resolves the `strictness` value in strict priority
+ * order so a team's committed default can be overridden per-session
+ * without editing the file:
+ *
+ *   1. `CLAUDE_CRAP_STRICTNESS` environment variable
+ *   2. `.claude-crap.json` at the workspace root
+ *   3. Hardcoded default `"strict"` (zero behavior change for
+ *      installs that never create the file)
+ *
+ * The loader is intentionally tiny — it does a single synchronous
+ * file read, one optional env probe, and validates the string
+ * against the enum. A hook script can call it from inside its
+ * 15-second budget without breaking a sweat.
+ *
+ * @module crap-config
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Exhaustive list of valid strictness values. Keep this in sync with
+ * the `Strictness` type below — the tuple is `as const` so TypeScript
+ * derives the union from the same source of truth.
+ */
+export const STRICTNESS_VALUES = ["strict", "warn", "advisory"] as const;
+
+/**
+ * Union of valid strictness values. Used by every consumer of
+ * {@link CrapConfig} to branch on the mode without dealing with
+ * arbitrary strings.
+ */
+export type Strictness = (typeof STRICTNESS_VALUES)[number];
+
+/**
+ * Hardcoded default used when neither the environment variable nor
+ * `.claude-crap.json` provides a value. Chosen as `"strict"` so the
+ * plugin's hard-failing Stop gate stays the default experience.
+ */
+export const DEFAULT_STRICTNESS: Strictness = "strict";
+
+/**
+ * Thrown by {@link loadCrapConfig} when the configuration is
+ * rejected. Callers in the hook layer fall back to the default on a
+ * throw so a busted config never deadlocks the user, while callers
+ * in the MCP server surface the error verbatim.
+ */
+export class CrapConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CrapConfigError";
+  }
+}
+
+/**
+ * Structure of the resolved sonar configuration returned by
+ * {@link loadCrapConfig}. The shape is deliberately minimal for
+ * v0.1.0; future releases may add threshold overrides under the
+ * same `.claude-crap.json` file.
+ */
+export interface CrapConfig {
+  /** Final strictness, after env override, file, and default fallback. */
+  readonly strictness: Strictness;
+  /** Where the strictness value actually came from. Useful for diagnostics. */
+  readonly strictnessSource: "env" | "file" | "default";
+}
+
+/**
+ * Options accepted by {@link loadCrapConfig}. The only required
+ * field is the workspace root the loader should search for
+ * `.claude-crap.json`.
+ */
+export interface LoadCrapConfigOptions {
+  /**
+   * Absolute path to the workspace root. The loader reads
+   * `.claude-crap.json` from this directory only — it does not
+   * walk parent directories.
+   */
+  readonly workspaceRoot: string;
+}
+
+/**
+ * Resolve the effective sonar configuration for a given workspace
+ * root. Pure function except for the one synchronous file read on
+ * `<workspaceRoot>/.claude-crap.json` and the two env lookups.
+ *
+ * @param options Search options. Only `workspaceRoot` is required.
+ * @returns       The resolved {@link CrapConfig}.
+ * @throws        {@link CrapConfigError} on any invalid input.
+ */
+export function loadCrapConfig(options: LoadCrapConfigOptions): CrapConfig {
+  const envRaw = process.env["CLAUDE_CRAP_STRICTNESS"];
+  if (typeof envRaw === "string" && envRaw.trim() !== "") {
+    const normalized = envRaw.trim().toLowerCase();
+    if (!isStrictness(normalized)) {
+      throw new CrapConfigError(
+        `[crap-config] CLAUDE_CRAP_STRICTNESS="${envRaw}" is not a valid strictness. ` +
+          `Expected one of: ${STRICTNESS_VALUES.join(", ")}.`,
+      );
+    }
+    return { strictness: normalized, strictnessSource: "env" };
+  }
+
+  const fromFile = readFromFile(options.workspaceRoot);
+  if (fromFile) return { strictness: fromFile, strictnessSource: "file" };
+
+  return { strictness: DEFAULT_STRICTNESS, strictnessSource: "default" };
+}
+
+/**
+ * Attempt to read and validate `.claude-crap.json` at the
+ * workspace root. Returns `null` when the file is missing (which
+ * is the common case for fresh installs). Throws
+ * {@link CrapConfigError} on any other failure mode — a malformed
+ * JSON file, a non-object root, a missing or wrong-type
+ * `strictness` field, or an unknown enum value — so the caller
+ * cannot accidentally drop into the default on a typo.
+ *
+ * @param workspaceRoot Absolute workspace root.
+ * @returns             The validated strictness, or `null` when no
+ *                      file is present.
+ */
+function readFromFile(workspaceRoot: string): Strictness | null {
+  const filePath = join(workspaceRoot, ".claude-crap.json");
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, "utf8");
+  } catch (err) {
+    const error = err as NodeJS.ErrnoException;
+    if (error.code === "ENOENT") return null;
+    throw new CrapConfigError(
+      `[crap-config] Failed to read ${filePath}: ${error.message}`,
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new CrapConfigError(
+      `[crap-config] ${filePath} is not valid JSON: ${(err as Error).message}`,
+    );
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new CrapConfigError(
+      `[crap-config] ${filePath} must be a JSON object at the top level`,
+    );
+  }
+  const doc = parsed as Record<string, unknown>;
+  if (!("strictness" in doc)) return null;
+
+  const value = doc["strictness"];
+  if (typeof value !== "string") {
+    throw new CrapConfigError(
+      `[crap-config] ${filePath}: 'strictness' must be a string, got ${typeof value}`,
+    );
+  }
+  const normalized = value.trim().toLowerCase();
+  if (!isStrictness(normalized)) {
+    throw new CrapConfigError(
+      `[crap-config] ${filePath}: 'strictness' is "${value}"; ` +
+        `expected one of ${STRICTNESS_VALUES.join(", ")}.`,
+    );
+  }
+  return normalized;
+}
+
+/**
+ * Runtime type guard for the {@link Strictness} union. Lets callers
+ * narrow an arbitrary string to the union without casting.
+ *
+ * @param value Arbitrary string.
+ * @returns     `true` when `value` is a recognized strictness.
+ */
+function isStrictness(value: string): value is Strictness {
+  return (STRICTNESS_VALUES as ReadonlyArray<string>).includes(value);
+}