claude-crap 0.1.2

package/dist/ast/tree-sitter-engine.js

@@ -0,0 +1,270 @@
+/**
+ * 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 } from "./cyclomatic.js";
+import { LANGUAGE_TABLE } from "./language-config.js";
+/**
+ * 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 {
+    parserCtor = null;
+    loadedLanguages = new Map();
+    grammarsDir;
+    runtimeDir;
+    loadGrammar;
+    initPromise = null;
+    constructor(options = {}) {
+        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) {
+        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.
+     */
+    async ensureParserFor(config) {
+        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.
+     */
+    async initParserModule() {
+        const imported = (await import("web-tree-sitter"));
+        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) => 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() {
+    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() {
+    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, languageConfig) {
+    const out = [];
+    function visit(node) {
+        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, languageConfig) {
+    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, languageConfig) {
+    const anyNode = node;
+    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) {
+    const anyNode = node;
+    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) {
+    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 };
+}
+//# sourceMappingURL=tree-sitter-engine.js.map

package/dist/ast/tree-sitter-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-sitter-engine.js","sourceRoot":"","sources":["../../src/ast/tree-sitter-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,2BAA2B,EAAgB,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,cAAc,EAA+C,MAAM,sBAAsB,CAAC;AA4FnG;;;GAGG;AACH,MAAM,OAAO,gBAAgB;IACnB,UAAU,GAAsB,IAAI,CAAC;IAC5B,eAAe,GAAG,IAAI,GAAG,EAA8B,CAAC;IACxD,WAAW,CAAS;IACpB,UAAU,CAAS;IACnB,WAAW,CAA4C;IAChE,WAAW,GAAyB,IAAI,CAAC;IAEjD,YAAY,UAAmC,EAAE;QAC/C,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,yBAAyB,EAAE,CAAC;QACtE,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,wBAAwB,EAAE,CAAC;QACnE,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1E,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,WAAW,CAAC,GAAuB;QACvC,MAAM,cAAc,GAAG,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACpD,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,8CAA8C,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;QAChF,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACvD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC;QAC1D,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAElC,MAAM,SAAS,GAAG,sBAAsB,CAAC,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;QACxE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;QAEvD,OAAO;YACL,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,QAAQ,EAAE,cAAc,CAAC,EAAE;YAC3B,WAAW;YACX,UAAU;YACV,SAAS;SACV,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACK,KAAK,CAAC,eAAe,CAAC,MAAsB;QAClD,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;gBACtB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC7C,CAAC;YACD,MAAM,IAAI,CAAC,WAAW,CAAC;QACzB,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC;QAC/B,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;QAC5E,CAAC;QAED,IAAI,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACnD,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;YACzD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;YAC/C,QAAQ,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC7C,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;QAChD,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QAC5B,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;;;OAQG;IACK,KAAK,CAAC,gBAAgB;QAC5B,MAAM,QAAQ,GAAG,CAAC,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAA4B,CAAC;QAC9E,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC;QAChC,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACjD,MAAM,IAAI,KAAK,CACb,+EAA+E,CAChF,CAAC;QACJ,CAAC;QACD,mEAAmE;QACnE,sEAAsE;QACtE,oEAAoE;QACpE,gEAAgE;QAChE,iEAAiE;QACjE,0DAA0D;QAC1D,MAAM,MAAM,CAAC,IAAI,CAAC;YAChB,UAAU,EAAE,CAAC,IAAY,EAAE,EAAE,CAC3B,IAAI,KAAK,kBAAkB;gBACzB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC;gBAC7B,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC;SACnC,CAAC,CAAC;QACH,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC;IAC3B,CAAC;CACF;AAED;;;;;GAKG;AACH,SAAS,yBAAyB;IAChC,IAAI,CAAC;QACH,MAAM,eAAe,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvD,8DAA8D;QAC9D,MAAM,WAAW,GAAG,eAAe,CAAC,OAAO,CAAC,gCAAgC,CAAC,CAAC;QAC9E,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,kEAAkE;QAClE,qDAAqD;QACrD,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QACrD,OAAO,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IAC/C,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,wBAAwB;IAC/B,IAAI,CAAC;QACH,MAAM,eAAe,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvD,MAAM,WAAW,GAAG,eAAe,CAAC,OAAO,CAAC,8BAA8B,CAAC,CAAC;QAC5E,OAAO,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,+DAA+D;QAC/D,2CAA2C;QAC3C,OAAO,yBAAyB,EAAE,CAAC;IACrC,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,sBAAsB,CAC7B,IAAa,EACb,cAA8B;IAE9B,MAAM,GAAG,GAAsB,EAAE,CAAC;IAElC,SAAS,KAAK,CAAC,IAAa;QAC1B,IAAI,cAAc,CAAC,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACpD,GAAG,CAAC,IAAI,CAAC,oBAAoB,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC;YACrD,+DAA+D;YAC/D,kEAAkE;YAClE,+DAA+D;YAC/D,kDAAkD;QACpD,CAAC;QACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC;YACzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAC5B,IAAI,KAAK;gBAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,CAAC;IACZ,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;IAC9C,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;GAEG;AACH,SAAS,oBAAoB,CAAC,IAAa,EAAE,cAA8B;IACzE,MAAM,IAAI,GAAG,mBAAmB,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,UAAU,GAAG,2BAA2B,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;IACrE,OAAO;QACL,IAAI;QACJ,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,oBAAoB,EAAE,UAAU;QAChC,SAAS,EAAE,QAAQ,CAAC,OAAO,GAAG,QAAQ,CAAC,SAAS,GAAG,CAAC;KACrD,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,mBAAmB,CAAC,IAAa,EAAE,cAA8B;IACxE,MAAM,OAAO,GAAG,IAEf,CAAC;IACF,IAAI,OAAO,OAAO,CAAC,iBAAiB,KAAK,UAAU,EAAE,CAAC;QACpD,KAAK,MAAM,KAAK,IAAI,cAAc,CAAC,mBAAmB,EAAE,CAAC;YACvD,MAAM,QAAQ,GAAG,OAAO,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;YAClD,IAAI,QAAQ,IAAI,QAAQ,CAAC,IAAI;gBAAE,OAAO,QAAQ,CAAC,IAAI,CAAC;QACtD,CAAC;IACH,CAAC;IACD,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,IAAa;IACpC,MAAM,OAAO,GAAG,IAGf,CAAC;IACF,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,EAAE,GAAG,IAAI,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,GAAG,IAAI,QAAQ,CAAC;IACpD,OAAO,EAAE,SAAS,EAAE,QAAQ,GAAG,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,CAAC,EAAE,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAS,UAAU,CAAC,MAAc;IAChC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,WAAW,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC;IAClE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;AAC5D,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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;
+}
+/**
+ * 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 declare function loadConfig(): CrapConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0FAA0F;IAC1F,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,gGAAgG;IAChG,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,qBAAqB,CAAC;IAC7C,0FAA0F;IAC1F,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,wDAAwD;IACxD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AA0CD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,IAAI,UAAU,CAUvC"}

package/dist/config.js

@@ -0,0 +1,78 @@
+/**
+ * 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
+ */
+/**
+ * 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, raw, fallback) {
+    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, fallback) {
+    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;
+}
+/**
+ * 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() {
+    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),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAiCH;;;;;;;;;;;GAWG;AACH,SAAS,WAAW,CAAC,IAAY,EAAE,GAAuB,EAAE,QAAgB;IAC1E,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,QAAQ,CAAC;IACrD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,KAAK,GAAG,0BAA0B,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,WAAW,CAAC,GAAuB,EAAE,QAA+B;IAC3E,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1B,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC5C,IAAI,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,iCAAiC,GAAG,gCAAgC,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,UAAmC,CAAC;AAC7C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO;QACL,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,OAAO,CAAC,GAAG,EAAE;QAChE,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,sBAAsB;QAClF,aAAa,EAAE,WAAW,CAAC,4BAA4B,EAAE,OAAO,CAAC,GAAG,CAAC,0BAA0B,EAAE,EAAE,CAAC;QACpG,aAAa,EAAE,WAAW,CAAC,4BAA4B,EAAE,OAAO,CAAC,GAAG,CAAC,0BAA0B,EAAE,EAAE,CAAC;QACpG,YAAY,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,0BAA0B,EAAE,GAAG,CAAC;QACtE,aAAa,EAAE,WAAW,CAAC,6BAA6B,EAAE,OAAO,CAAC,GAAG,CAAC,2BAA2B,EAAE,EAAE,CAAC;QACtG,aAAa,EAAE,WAAW,CAAC,4BAA4B,EAAE,OAAO,CAAC,GAAG,CAAC,0BAA0B,EAAE,IAAI,CAAC;KACvG,CAAC;AACJ,CAAC"}

package/dist/crap-config.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 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
+ */
+/**
+ * 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 declare const STRICTNESS_VALUES: readonly ["strict", "warn", "advisory"];
+/**
+ * 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 declare const DEFAULT_STRICTNESS: Strictness;
+/**
+ * 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 declare class CrapConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare function loadCrapConfig(options: LoadCrapConfigOptions): CrapConfig;
+//# sourceMappingURL=crap-config.d.ts.map

package/dist/crap-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crap-config.d.ts","sourceRoot":"","sources":["../src/crap-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAKH;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,yCAA0C,CAAC;AAEzE;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,UAAqB,CAAC;AAEvD;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,6EAA6E;IAC7E,QAAQ,CAAC,gBAAgB,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;CACvD;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,UAAU,CAiBzE"}

package/dist/crap-config.js

@@ -0,0 +1,144 @@
+/**
+ * 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"];
+/**
+ * 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 = "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) {
+        super(message);
+        this.name = "CrapConfigError";
+    }
+}
+/**
+ * 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) {
+    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) {
+    const filePath = join(workspaceRoot, ".claude-crap.json");
+    let raw;
+    try {
+        raw = readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        const error = err;
+        if (error.code === "ENOENT")
+            return null;
+        throw new CrapConfigError(`[crap-config] Failed to read ${filePath}: ${error.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new CrapConfigError(`[crap-config] ${filePath} is not valid JSON: ${err.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;
+    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) {
+    return STRICTNESS_VALUES.includes(value);
+}
+//# sourceMappingURL=crap-config.js.map