claude-crap 0.1.2

package/dist/sarif/sarif-validator.js

@@ -0,0 +1,138 @@
+/**
+ * AJV-backed minimal SARIF 2.1.0 document validator.
+ *
+ * F-A05-01: the `ingest_sarif` MCP tool accepts a caller-supplied
+ * `sarifDocument` object and, before this module existed, only
+ * checked `version === "2.1.0"`. That was enough for tool-call
+ * dispatch but not for the payload itself — a SARIF with a missing
+ * `runs[]`, a `results` array of wrong-type entries, or a result
+ * without a `ruleId` would still be accepted by the MCP tool and
+ * flow through to the store, the dashboard, and any downstream
+ * consumer that uploads claude-crap's SARIF to GitHub code-scanning
+ * or an IDE viewer.
+ *
+ * This module uses the `ajv` dependency (already in package.json) to
+ * compile a minimal JSON Schema that covers exactly the fields
+ * claude-crap reads: `version`, `runs`, `runs[].tool.driver.name`,
+ * and the per-result shape. Everything else (tool metadata, rule
+ * definitions, snippets, etc.) is passthrough — we do not enforce
+ * the full SARIF 2.1.0 spec because claude-crap does not consume
+ * those fields.
+ *
+ * The compiled validator is cached so the ~5 ms AJV compile cost is
+ * paid once per MCP server process, not once per ingestion.
+ *
+ * @module sarif/sarif-validator
+ */
+import { Ajv } from "ajv";
+/**
+ * Minimal JSON Schema covering every field claude-crap reads from a
+ * SARIF 2.1.0 document. Passthrough fields are allowed because
+ * `additionalProperties` is left at the default (`true`).
+ *
+ * Keep this schema in sync with `hydrateFindingFromResult` in
+ * `src/sarif/sarif-store.ts` — anything the store reads MUST be
+ * covered here, and nothing else should be enforced.
+ */
+const SARIF_MINIMAL_SCHEMA = {
+    type: "object",
+    properties: {
+        version: { type: "string", enum: ["2.1.0"] },
+        $schema: { type: "string" },
+        runs: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    tool: {
+                        type: "object",
+                        properties: {
+                            driver: {
+                                type: "object",
+                                properties: {
+                                    name: { type: "string", minLength: 1 },
+                                    version: { type: "string" },
+                                },
+                                required: ["name"],
+                            },
+                        },
+                        required: ["driver"],
+                    },
+                    results: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                ruleId: { type: "string", minLength: 1 },
+                                level: { type: "string", enum: ["none", "note", "warning", "error"] },
+                                message: {
+                                    type: "object",
+                                    properties: { text: { type: "string", minLength: 1 } },
+                                    required: ["text"],
+                                },
+                                locations: { type: "array" },
+                                properties: { type: "object" },
+                            },
+                            required: ["ruleId", "message"],
+                        },
+                    },
+                },
+                required: ["tool", "results"],
+            },
+        },
+    },
+    required: ["version", "runs"],
+};
+/**
+ * Lazily-compiled validator instance. `null` until the first call to
+ * {@link validateSarifDocument}, then reused for the lifetime of the
+ * process.
+ */
+let cachedValidator = null;
+/**
+ * Returned by {@link validateSarifDocument} when the document fails
+ * schema validation. Includes the full AJV error array for callers
+ * that want to surface structured diagnostics.
+ */
+export class SarifValidationError extends Error {
+    errors;
+    constructor(message, errors) {
+        super(message);
+        this.name = "SarifValidationError";
+        this.errors = errors;
+    }
+}
+/**
+ * Obtain the compiled AJV validator, compiling on first use.
+ *
+ * The schema above intentionally allows passthrough fields on every
+ * object (AJV's default `additionalProperties: true`). We disable
+ * `strict` so AJV does not warn about benign constructs like the
+ * `format`/`enum` combination.
+ */
+function getValidator() {
+    if (cachedValidator)
+        return cachedValidator;
+    const ajv = new Ajv({ allErrors: false, strict: false });
+    const validator = ajv.compile(SARIF_MINIMAL_SCHEMA);
+    cachedValidator = validator;
+    return validator;
+}
+/**
+ * Validate a SARIF 2.1.0 document against the minimal schema. Throws
+ * {@link SarifValidationError} when the document does not match.
+ *
+ * @param doc Document to validate. May be any value — the validator
+ *            treats non-object inputs as a schema violation.
+ * @throws    {@link SarifValidationError} on any validation failure.
+ */
+export function validateSarifDocument(doc) {
+    const validator = getValidator();
+    if (validator(doc))
+        return;
+    const first = validator.errors?.[0];
+    const path = first?.instancePath?.length ? first.instancePath : "<root>";
+    const message = first?.message ?? "unknown validation error";
+    throw new SarifValidationError(`[sarif-validator] SARIF document is not valid 2.1.0: ${path} ${message}`, validator.errors ?? null);
+}
+//# sourceMappingURL=sarif-validator.js.map

package/dist/sarif/sarif-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sarif-validator.js","sourceRoot":"","sources":["../../src/sarif/sarif-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,GAAG,EAAyB,MAAM,KAAK,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,oBAAoB,GAAG;IAC3B,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE;QAC5C,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC3B,IAAI,EAAE;YACJ,IAAI,EAAE,OAAO;YACb,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,IAAI,EAAE;wBACJ,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,MAAM,EAAE;gCACN,IAAI,EAAE,QAAQ;gCACd,UAAU,EAAE;oCACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE;oCACtC,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;iCAC5B;gCACD,QAAQ,EAAE,CAAC,MAAM,CAAC;6BACnB;yBACF;wBACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;qBACrB;oBACD,OAAO,EAAE;wBACP,IAAI,EAAE,OAAO;wBACb,KAAK,EAAE;4BACL,IAAI,EAAE,QAAQ;4BACd,UAAU,EAAE;gCACV,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE;gCACxC,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE;gCACrE,OAAO,EAAE;oCACP,IAAI,EAAE,QAAQ;oCACd,UAAU,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE,EAAE;oCACtD,QAAQ,EAAE,CAAC,MAAM,CAAC;iCACnB;gCACD,SAAS,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;gCAC5B,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;6BAC/B;4BACD,QAAQ,EAAE,CAAC,QAAQ,EAAE,SAAS,CAAC;yBAChC;qBACF;iBACF;gBACD,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC;aAC9B;SACF;KACF;IACD,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,CAAC;CACrB,CAAC;AAEX;;;;GAIG;AACH,IAAI,eAAe,GAA4B,IAAI,CAAC;AAEpD;;;;GAIG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7B,MAAM,CAAU;IAEhC,YAAY,OAAe,EAAE,MAAe;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;;;;;GAOG;AACH,SAAS,YAAY;IACnB,IAAI,eAAe;QAAE,OAAO,eAAe,CAAC;IAC5C,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;IACzD,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACpD,eAAe,GAAG,SAAS,CAAC;IAC5B,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAY;IAChD,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IACjC,IAAI,SAAS,CAAC,GAAG,CAAC;QAAE,OAAO;IAC3B,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,KAAK,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC;IACzE,MAAM,OAAO,GAAG,KAAK,EAAE,OAAO,IAAI,0BAA0B,CAAC;IAC7D,MAAM,IAAI,oBAAoB,CAC5B,wDAAwD,IAAI,IAAI,OAAO,EAAE,EACzE,SAAS,CAAC,MAAM,IAAI,IAAI,CACzB,CAAC;AACJ,CAAC"}

package/dist/schemas/tool-schemas.d.ts

@@ -0,0 +1,216 @@
+/**
+ * JSON Schema (Draft-07) definitions for every tool exposed by the MCP server.
+ *
+ * Each schema uses `enum`, `pattern`, `minimum`, `maximum`, `oneOf` and
+ * `additionalProperties: false` to eliminate schema hallucinations from the
+ * LLM. The MCP SDK automatically validates tool-call inputs against these
+ * schemas before invoking the handler — any drift produces a deterministic
+ * error that the agent can consume and correct.
+ *
+ * These `description` fields are read by the LLM at tool-listing time and
+ * become part of the agent's context, so they must be precise, imperative,
+ * and never speculative. Keep them short but actionable.
+ *
+ * @module schemas/tool-schemas
+ */
+/**
+ * Schema for the `compute_crap` tool. Returns a CRAP score for a single
+ * function and a block decision against the configured threshold.
+ */
+export declare const computeCrapSchema: {
+    readonly type: "object";
+    readonly description: "Compute the CRAP (Change Risk Anti-Patterns) index for a single function. Returns the score and whether it exceeds the configured threshold. A blocked result means the function must be decomposed or covered by more tests before the Stop quality gate will pass.";
+    readonly properties: {
+        readonly cyclomaticComplexity: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly maximum: 1000;
+            readonly description: "Cyclomatic complexity of the function (number of linearly independent paths).";
+        };
+        readonly coveragePercent: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 100;
+            readonly description: "Test coverage percentage for the function, in the range [0, 100].";
+        };
+        readonly functionName: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z_$][A-Za-z0-9_$.:<>]*$";
+            readonly minLength: 1;
+            readonly maxLength: 256;
+            readonly description: "Fully qualified name of the function under analysis, used for SARIF traceability.";
+        };
+        readonly filePath: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 4096;
+            readonly description: "Absolute or workspace-relative path to the source file that contains the function.";
+        };
+    };
+    readonly required: readonly ["cyclomaticComplexity", "coveragePercent", "functionName", "filePath"];
+    readonly additionalProperties: false;
+};
+/**
+ * Schema for the `compute_tdr` tool. Returns a Technical Debt Ratio and a
+ * maintainability letter rating for a scope (project, module, or file).
+ */
+export declare const computeTdrSchema: {
+    readonly type: "object";
+    readonly description: "Compute the Technical Debt Ratio (TDR) for a scope and return the maintainability letter rating (A..E). Rating E always halts the workflow regardless of the configured tolerance. Use this after aggregating remediation estimates from SARIF findings.";
+    readonly properties: {
+        readonly remediationMinutes: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 10000000;
+            readonly description: "Total estimated remediation effort in minutes, summed across every finding in the scope.";
+        };
+        readonly totalLinesOfCode: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly maximum: 100000000;
+            readonly description: "Physical lines of code in the scope (project, module, or file).";
+        };
+        readonly scope: {
+            readonly type: "string";
+            readonly enum: readonly ["project", "module", "file"];
+            readonly description: "Aggregation scope for the TDR computation.";
+        };
+    };
+    readonly required: readonly ["remediationMinutes", "totalLinesOfCode", "scope"];
+    readonly additionalProperties: false;
+};
+/**
+ * Schema for the `analyze_file_ast` tool. Returns deterministic AST
+ * metrics (LOC, cyclomatic complexity, node counts) for a source file.
+ */
+export declare const analyzeFileAstSchema: {
+    readonly type: "object";
+    readonly description: "Parse a source file with tree-sitter and return deterministic metrics (lines of code, cyclomatic complexity per function, top-level node counts). Prefer this tool over reading the file directly — it is faster and will not bloat the agent context.";
+    readonly properties: {
+        readonly filePath: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 4096;
+            readonly pattern: "^(?!.*\\.\\./).*$";
+            readonly description: "Path to the file to analyze. Paths containing `../` are rejected to prevent workspace escape.";
+        };
+        readonly language: {
+            readonly type: "string";
+            readonly enum: readonly ["csharp", "javascript", "typescript", "python", "java"];
+            readonly description: "Source language of the file. Determines which tree-sitter grammar to load.";
+        };
+    };
+    readonly required: readonly ["filePath", "language"];
+    readonly additionalProperties: false;
+};
+/**
+ * Schema for the `score_project` tool. Aggregates the latest SARIF
+ * report and the workspace size into a single project score with
+ * Maintainability / Reliability / Security letter grades, an overall
+ * grade, the dashboard URL (when running), and the SARIF report path.
+ */
+export declare const scoreProjectSchema: {
+    readonly type: "object";
+    readonly description: "Compute the aggregate project score (Maintainability / Reliability / Security / Overall A..E), and return both a chat-friendly Markdown summary and a structured JSON snapshot. Includes the local dashboard URL and the consolidated SARIF report path so the user can drill in without opening any extra tooling.";
+    readonly properties: {
+        readonly format: {
+            readonly type: "string";
+            readonly enum: readonly ["markdown", "json", "both"];
+            readonly description: "Output format. `markdown` returns only the chat summary, `json` returns only the structured snapshot, `both` (default) returns both as separate content blocks.";
+        };
+    };
+    readonly required: readonly [];
+    readonly additionalProperties: false;
+};
+/**
+ * Schema for the `require_test_harness` tool. Checks whether a production
+ * source file has an accompanying test file in any of the conventional
+ * locations the resolver supports (sibling `.test.`, `__tests__/`, mirror
+ * tree, Python `test_` prefix).
+ */
+export declare const requireTestHarnessSchema: {
+    readonly type: "object";
+    readonly description: "Check whether a production source file has a matching test file. Returns the first existing test path, or the full list of paths the resolver probed when none exists. Use this BEFORE writing any functional code — the CLAUDE.md Golden Rule requires a test harness to exist first.";
+    readonly properties: {
+        readonly filePath: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 4096;
+            readonly pattern: "^(?!.*\\.\\./).*$";
+            readonly description: "Path to the production file. Paths containing `../` are rejected to prevent workspace escape.";
+        };
+    };
+    readonly required: readonly ["filePath"];
+    readonly additionalProperties: false;
+};
+/**
+ * Schema for the `ingest_scanner_output` tool. Accepts a scanner
+ * identifier (Semgrep, ESLint, Bandit, Stryker) plus that scanner's
+ * native output (SARIF or JSON), routes the input through the
+ * matching adapter in `src/adapters/`, and persists the normalized
+ * SARIF 2.1.0 document in the store.
+ *
+ * This tool is the preferred path for ingesting scanner output that
+ * is not already SARIF — `ingest_sarif` remains the right choice
+ * when you already have a SARIF document and just need deduplication.
+ */
+export declare const ingestScannerOutputSchema: {
+    readonly type: "object";
+    readonly description: "Ingest a scanner's native output (Semgrep SARIF, ESLint JSON, Bandit JSON, or Stryker JSON), route it through the matching adapter, enrich every finding with an effort estimate, and persist the normalized SARIF 2.1.0 document. Prefer this tool over `ingest_sarif` whenever the scanner does not emit SARIF natively.";
+    readonly properties: {
+        readonly scanner: {
+            readonly type: "string";
+            readonly enum: readonly ["semgrep", "eslint", "bandit", "stryker"];
+            readonly description: "Identifier of the producing scanner.";
+        };
+        readonly rawOutput: {
+            readonly description: "The scanner's native output. Accepts either a JSON string (as produced by the scanner's CLI) or a pre-parsed JSON object / array.";
+            readonly oneOf: readonly [{
+                readonly type: "string";
+            }, {
+                readonly type: "object";
+            }, {
+                readonly type: "array";
+            }];
+        };
+    };
+    readonly required: readonly ["scanner", "rawOutput"];
+    readonly additionalProperties: false;
+};
+/**
+ * Schema for the `ingest_sarif` tool. Accepts a raw SARIF 2.1.0 document
+ * from an external scanner, deduplicates against the internal store, and
+ * normalizes the output into claude-crap's canonical format.
+ */
+export declare const ingestSarifSchema: {
+    readonly type: "object";
+    readonly description: "Ingest a raw SARIF 2.1.0 report produced by an external scanner (Semgrep, ESLint, Bandit, Stryker, etc.), deduplicate it against the internal store, and return the normalized document. The agent should call this once per scanner invocation, not once per finding.";
+    readonly properties: {
+        readonly sarifDocument: {
+            readonly type: "object";
+            readonly description: "A full SARIF 2.1.0 document with `version` and `runs` keys.";
+            readonly properties: {
+                readonly version: {
+                    readonly type: "string";
+                    readonly enum: readonly ["2.1.0"];
+                };
+                readonly $schema: {
+                    readonly type: "string";
+                };
+                readonly runs: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                };
+            };
+            readonly required: readonly ["version", "runs"];
+        };
+        readonly sourceTool: {
+            readonly type: "string";
+            readonly pattern: "^[a-zA-Z0-9._-]{1,64}$";
+            readonly description: "Stable identifier of the tool that produced the report (`semgrep`, `eslint`, `bandit`, ...).";
+        };
+    };
+    readonly required: readonly ["sarifDocument", "sourceTool"];
+    readonly additionalProperties: false;
+};
+//# sourceMappingURL=tool-schemas.d.ts.map

package/dist/schemas/tool-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-schemas.d.ts","sourceRoot":"","sources":["../../src/schemas/tool-schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCpB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;CAyBnB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;CAuBvB,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;CAcrB,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;CAgB3B,CAAC;AAEX;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;CAkB5B,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuBpB,CAAC"}

package/dist/schemas/tool-schemas.js

@@ -0,0 +1,208 @@
+/**
+ * JSON Schema (Draft-07) definitions for every tool exposed by the MCP server.
+ *
+ * Each schema uses `enum`, `pattern`, `minimum`, `maximum`, `oneOf` and
+ * `additionalProperties: false` to eliminate schema hallucinations from the
+ * LLM. The MCP SDK automatically validates tool-call inputs against these
+ * schemas before invoking the handler — any drift produces a deterministic
+ * error that the agent can consume and correct.
+ *
+ * These `description` fields are read by the LLM at tool-listing time and
+ * become part of the agent's context, so they must be precise, imperative,
+ * and never speculative. Keep them short but actionable.
+ *
+ * @module schemas/tool-schemas
+ */
+// The MCP SDK consumes these as the `inputSchema` field of a Tool. We type
+// them with `as const` so TypeScript infers literal types and the MCP SDK
+// accepts them without runtime casting.
+/**
+ * Schema for the `compute_crap` tool. Returns a CRAP score for a single
+ * function and a block decision against the configured threshold.
+ */
+export const computeCrapSchema = {
+    type: "object",
+    description: "Compute the CRAP (Change Risk Anti-Patterns) index for a single function. Returns the score and whether it exceeds the configured threshold. A blocked result means the function must be decomposed or covered by more tests before the Stop quality gate will pass.",
+    properties: {
+        cyclomaticComplexity: {
+            type: "integer",
+            minimum: 1,
+            maximum: 1000,
+            description: "Cyclomatic complexity of the function (number of linearly independent paths).",
+        },
+        coveragePercent: {
+            type: "number",
+            minimum: 0,
+            maximum: 100,
+            description: "Test coverage percentage for the function, in the range [0, 100].",
+        },
+        functionName: {
+            type: "string",
+            pattern: "^[A-Za-z_$][A-Za-z0-9_$.:<>]*$",
+            minLength: 1,
+            maxLength: 256,
+            description: "Fully qualified name of the function under analysis, used for SARIF traceability.",
+        },
+        filePath: {
+            type: "string",
+            minLength: 1,
+            maxLength: 4096,
+            description: "Absolute or workspace-relative path to the source file that contains the function.",
+        },
+    },
+    required: ["cyclomaticComplexity", "coveragePercent", "functionName", "filePath"],
+    additionalProperties: false,
+};
+/**
+ * Schema for the `compute_tdr` tool. Returns a Technical Debt Ratio and a
+ * maintainability letter rating for a scope (project, module, or file).
+ */
+export const computeTdrSchema = {
+    type: "object",
+    description: "Compute the Technical Debt Ratio (TDR) for a scope and return the maintainability letter rating (A..E). Rating E always halts the workflow regardless of the configured tolerance. Use this after aggregating remediation estimates from SARIF findings.",
+    properties: {
+        remediationMinutes: {
+            type: "number",
+            minimum: 0,
+            maximum: 10_000_000,
+            description: "Total estimated remediation effort in minutes, summed across every finding in the scope.",
+        },
+        totalLinesOfCode: {
+            type: "integer",
+            minimum: 1,
+            maximum: 100_000_000,
+            description: "Physical lines of code in the scope (project, module, or file).",
+        },
+        scope: {
+            type: "string",
+            enum: ["project", "module", "file"],
+            description: "Aggregation scope for the TDR computation.",
+        },
+    },
+    required: ["remediationMinutes", "totalLinesOfCode", "scope"],
+    additionalProperties: false,
+};
+/**
+ * Schema for the `analyze_file_ast` tool. Returns deterministic AST
+ * metrics (LOC, cyclomatic complexity, node counts) for a source file.
+ */
+export const analyzeFileAstSchema = {
+    type: "object",
+    description: "Parse a source file with tree-sitter and return deterministic metrics (lines of code, cyclomatic complexity per function, top-level node counts). Prefer this tool over reading the file directly — it is faster and will not bloat the agent context.",
+    properties: {
+        filePath: {
+            type: "string",
+            minLength: 1,
+            maxLength: 4096,
+            // The lookahead pattern rejects any path traversal (`../`) to prevent
+            // the LLM from reading files outside the workspace. Any absolute path
+            // that does not contain `../` is still allowed.
+            pattern: "^(?!.*\\.\\./).*$",
+            description: "Path to the file to analyze. Paths containing `../` are rejected to prevent workspace escape.",
+        },
+        language: {
+            type: "string",
+            enum: ["csharp", "javascript", "typescript", "python", "java"],
+            description: "Source language of the file. Determines which tree-sitter grammar to load.",
+        },
+    },
+    required: ["filePath", "language"],
+    additionalProperties: false,
+};
+/**
+ * Schema for the `score_project` tool. Aggregates the latest SARIF
+ * report and the workspace size into a single project score with
+ * Maintainability / Reliability / Security letter grades, an overall
+ * grade, the dashboard URL (when running), and the SARIF report path.
+ */
+export const scoreProjectSchema = {
+    type: "object",
+    description: "Compute the aggregate project score (Maintainability / Reliability / Security / Overall A..E), and return both a chat-friendly Markdown summary and a structured JSON snapshot. Includes the local dashboard URL and the consolidated SARIF report path so the user can drill in without opening any extra tooling.",
+    properties: {
+        format: {
+            type: "string",
+            enum: ["markdown", "json", "both"],
+            description: "Output format. `markdown` returns only the chat summary, `json` returns only the structured snapshot, `both` (default) returns both as separate content blocks.",
+        },
+    },
+    required: [],
+    additionalProperties: false,
+};
+/**
+ * Schema for the `require_test_harness` tool. Checks whether a production
+ * source file has an accompanying test file in any of the conventional
+ * locations the resolver supports (sibling `.test.`, `__tests__/`, mirror
+ * tree, Python `test_` prefix).
+ */
+export const requireTestHarnessSchema = {
+    type: "object",
+    description: "Check whether a production source file has a matching test file. Returns the first existing test path, or the full list of paths the resolver probed when none exists. Use this BEFORE writing any functional code — the CLAUDE.md Golden Rule requires a test harness to exist first.",
+    properties: {
+        filePath: {
+            type: "string",
+            minLength: 1,
+            maxLength: 4096,
+            pattern: "^(?!.*\\.\\./).*$",
+            description: "Path to the production file. Paths containing `../` are rejected to prevent workspace escape.",
+        },
+    },
+    required: ["filePath"],
+    additionalProperties: false,
+};
+/**
+ * Schema for the `ingest_scanner_output` tool. Accepts a scanner
+ * identifier (Semgrep, ESLint, Bandit, Stryker) plus that scanner's
+ * native output (SARIF or JSON), routes the input through the
+ * matching adapter in `src/adapters/`, and persists the normalized
+ * SARIF 2.1.0 document in the store.
+ *
+ * This tool is the preferred path for ingesting scanner output that
+ * is not already SARIF — `ingest_sarif` remains the right choice
+ * when you already have a SARIF document and just need deduplication.
+ */
+export const ingestScannerOutputSchema = {
+    type: "object",
+    description: "Ingest a scanner's native output (Semgrep SARIF, ESLint JSON, Bandit JSON, or Stryker JSON), route it through the matching adapter, enrich every finding with an effort estimate, and persist the normalized SARIF 2.1.0 document. Prefer this tool over `ingest_sarif` whenever the scanner does not emit SARIF natively.",
+    properties: {
+        scanner: {
+            type: "string",
+            enum: ["semgrep", "eslint", "bandit", "stryker"],
+            description: "Identifier of the producing scanner.",
+        },
+        rawOutput: {
+            description: "The scanner's native output. Accepts either a JSON string (as produced by the scanner's CLI) or a pre-parsed JSON object / array.",
+            oneOf: [{ type: "string" }, { type: "object" }, { type: "array" }],
+        },
+    },
+    required: ["scanner", "rawOutput"],
+    additionalProperties: false,
+};
+/**
+ * Schema for the `ingest_sarif` tool. Accepts a raw SARIF 2.1.0 document
+ * from an external scanner, deduplicates against the internal store, and
+ * normalizes the output into claude-crap's canonical format.
+ */
+export const ingestSarifSchema = {
+    type: "object",
+    description: "Ingest a raw SARIF 2.1.0 report produced by an external scanner (Semgrep, ESLint, Bandit, Stryker, etc.), deduplicate it against the internal store, and return the normalized document. The agent should call this once per scanner invocation, not once per finding.",
+    properties: {
+        sarifDocument: {
+            type: "object",
+            description: "A full SARIF 2.1.0 document with `version` and `runs` keys.",
+            properties: {
+                version: { type: "string", enum: ["2.1.0"] },
+                $schema: { type: "string" },
+                runs: { type: "array", minItems: 1 },
+            },
+            required: ["version", "runs"],
+        },
+        sourceTool: {
+            type: "string",
+            pattern: "^[a-zA-Z0-9._-]{1,64}$",
+            description: "Stable identifier of the tool that produced the report (`semgrep`, `eslint`, `bandit`, ...).",
+        },
+    },
+    required: ["sarifDocument", "sourceTool"],
+    additionalProperties: false,
+};
+//# sourceMappingURL=tool-schemas.js.map

package/dist/schemas/tool-schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-schemas.js","sourceRoot":"","sources":["../../src/schemas/tool-schemas.ts"],"names":[],"mappings":"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"}

package/dist/sdk.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Root public SDK for `claude-crap`.
+ *
+ * This is the module you get when you do
+ * `import ... from "claude-crap"`. It is intentionally
+ * **side-effect-free**: importing this file does NOT start the MCP
+ * server, does NOT open the dashboard, does NOT touch the filesystem.
+ * Only the executable entrypoint in `dist/index.js` boots the
+ * server — that file is invoked by the `.mcp.json` command and the
+ * CLI bin, never as a library.
+ *
+ * Structure:
+ *
+ *   - `./metrics` — CRAP, TDR, project score, workspace walker
+ *   - `./sarif`   — SARIF 2.1.0 builder and on-disk store
+ *   - `./ast`     — tree-sitter engine, cyclomatic complexity, language config
+ *   - `./tools`   — test-harness resolver used by `require_test_harness`
+ *
+ * Prefer deep imports
+ * (`import { computeCrap } from "claude-crap/metrics"`) over
+ * pulling everything through the root — they give TypeScript more
+ * precise type information and help tree-shakers drop unused modules.
+ *
+ * The symbols re-exported here are the ones most code paths need:
+ *
+ *   - `computeCrap`, `computeTdr`, `computeProjectScore`
+ *   - `renderProjectScoreMarkdown`
+ *   - `classifyTdr`, `ratingIsWorseThan`
+ *   - `SarifStore`, `buildSarifDocument`
+ *   - `TreeSitterEngine`
+ *
+ * @module claude-crap
+ */
+export { computeCrap, computeTdr, classifyTdr, ratingIsWorseThan, ratingToRank, computeProjectScore, renderProjectScoreMarkdown, estimateWorkspaceLoc, } from "./metrics/index.js";
+export type { CrapInput, CrapResult, TdrInput, TdrResult, ComputeProjectScoreInput, DimensionScore, FindingsSummary, MaintainabilityScore, ProjectScore, ScoreLocation, SeverityRating, WorkspaceStats, WorkspaceWalkResult, } from "./metrics/index.js";
+export { SarifStore, buildSarifDocument } from "./sarif/index.js";
+export type { IngestedFinding, PersistedSarif, SarifFinding, SarifLevel, SarifLocation, SarifStoreOptions, SarifToolInfo, } from "./sarif/index.js";
+export { TreeSitterEngine, computeCyclomaticComplexity, detectLanguageFromPath, LANGUAGE_TABLE, } from "./ast/index.js";
+export type { AnalyzeFileRequest, AstNode, FileMetrics, FunctionMetrics, LanguageConfig, SupportedLanguage, TreeSitterEngineOptions, } from "./ast/index.js";
+export { findTestFile, isTestFile, candidatePaths } from "./tools/index.js";
+export type { TestFileResolution } from "./tools/index.js";
+export { adaptScannerOutput, adaptSemgrep, adaptEslint, adaptBandit, adaptStryker, KNOWN_SCANNERS, } from "./adapters/index.js";
+export type { AdapterResult, KnownScanner } from "./adapters/index.js";
+export type { MaintainabilityRating, CrapConfig } from "./config.js";
+//# sourceMappingURL=sdk.d.ts.map

package/dist/sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../src/sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,0BAA0B,EAC1B,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,SAAS,EACT,UAAU,EACV,QAAQ,EACR,SAAS,EACT,wBAAwB,EACxB,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,YAAY,EACZ,aAAa,EACb,cAAc,EACd,cAAc,EACd,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAClE,YAAY,EACV,eAAe,EACf,cAAc,EACd,YAAY,EACZ,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,aAAa,GACd,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,sBAAsB,EACtB,cAAc,GACf,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,kBAAkB,EAClB,OAAO,EACP,WAAW,EACX,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC5E,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAG3D,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,WAAW,EACX,YAAY,EACZ,cAAc,GACf,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMvE,YAAY,EAAE,qBAAqB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}