claude-crap 0.4.2 → 0.4.4

package/plugin/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-crap-plugin",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-crap-plugin",
-      "version": "0.4.2",
+      "version": "0.4.4",
       "dependencies": {
         "@fastify/static": "^8.0.3",
         "@modelcontextprotocol/sdk": "^1.0.4",

package/plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-crap-plugin",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "private": true,
   "description": "Runtime dependencies for the claude-crap plugin bundle",
   "type": "module",

package/src/config.ts

@@ -9,12 +9,15 @@
  *   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.
+ * but the loader NEVER invents stochastic values. This module is the
+ * single source of truth for runtime configuration.
  *
  * @module config
  */
 
+import { execFileSync } from "node:child_process";
+import { readlinkSync } from "node:fs";
+
 /**
  * Maintainability rating letter grades used throughout claude-crap.
  *
@@ -30,7 +33,7 @@ export type MaintainabilityRating = "A" | "B" | "C" | "D" | "E";
  * 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()`. */
+  /** Absolute path to the user's workspace. Resolved via {@link discoverWorkspaceRoot}. */
   readonly pluginRoot: string;
   /** Directory (relative to the workspace) where consolidated SARIF reports are written. */
   readonly sarifOutputDir: string;
@@ -46,6 +49,112 @@ export interface CrapConfig {
   readonly dashboardPort: number;
 }
 
+/**
+ * Detects an unexpanded `.mcp.json` variable template such as
+ * `${CLAUDE_PROJECT_DIR}`. Claude Code only expands `${CLAUDE_PLUGIN_ROOT}`
+ * inside `.mcp.json`; every other `${VAR}` is passed through verbatim and
+ * must NOT be treated as a real filesystem path.
+ */
+function isLiteralVarTemplate(value: string | undefined): boolean {
+  if (value === undefined) return false;
+  return /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(value.trim());
+}
+
+/**
+ * Normalize an environment variable that is expected to contain a path.
+ * Returns `undefined` if the value is missing, empty, or an unexpanded
+ * `${...}` template. Any non-empty concrete string is returned as-is.
+ */
+function sanitizeEnvPath(value: string | undefined): string | undefined {
+  if (value === undefined || value === "") return undefined;
+  if (isLiteralVarTemplate(value)) return undefined;
+  return value;
+}
+
+/**
+ * Read the current working directory of the parent process. Claude Code
+ * spawns MCP servers with its own cwd set to the user's workspace, so the
+ * parent's cwd is the most reliable fallback when `CLAUDE_PROJECT_DIR` is
+ * not inherited (e.g. because Claude Code only exports it for hooks).
+ *
+ * Returns `undefined` on any platform or failure mode the probe cannot
+ * handle — callers must be prepared for a missing result.
+ */
+function readParentCwdDefault(): string | undefined {
+  try {
+    const ppid = process.ppid;
+    if (!ppid || ppid === 0) return undefined;
+
+    if (process.platform === "linux") {
+      // /proc/<pid>/cwd is a symlink to the process's cwd.
+      return readlinkSync(`/proc/${ppid}/cwd`);
+    }
+
+    if (process.platform === "darwin") {
+      // `lsof -a -p <pid> -d cwd -F n` emits a single line starting with
+      // `n<path>` for the cwd file descriptor. `-F` keeps the output
+      // machine-readable.
+      const output = execFileSync(
+        "lsof",
+        ["-a", "-p", String(ppid), "-d", "cwd", "-F", "n"],
+        {
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
+          timeout: 2000,
+        },
+      );
+      const match = output.match(/^n(.+)$/m);
+      return match?.[1];
+    }
+
+    // Windows and other platforms: no reliable no-dep probe.
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Parameters accepted by {@link discoverWorkspaceRoot}. The only field is
+ * an injectable `readParentCwd` implementation so that tests can pin the
+ * fallback behavior without spawning `lsof` or reading `/proc`.
+ */
+export interface DiscoverWorkspaceOptions {
+  readParentCwd?: () => string | undefined;
+}
+
+/**
+ * Resolve the user's workspace directory. Strategy, in strict priority
+ * order:
+ *
+ *   1. `CLAUDE_PROJECT_DIR`      (sanitized — ignored if it's `${...}`)
+ *   2. `CLAUDE_CRAP_PLUGIN_ROOT` (sanitized — legacy explicit override)
+ *   3. Parent process cwd       (Claude Code's cwd = the workspace)
+ *   4. `process.cwd()`          (last-resort fallback; usually wrong for
+ *                                MCP servers because Claude Code sets
+ *                                cwd to the plugin cache directory)
+ *
+ * This function NEVER returns an unexpanded `${...}` template; any source
+ * that contains one is skipped as if it were unset.
+ *
+ * @param options Injection points for tests.
+ * @returns       A concrete filesystem path.
+ */
+export function discoverWorkspaceRoot(options: DiscoverWorkspaceOptions = {}): string {
+  const readParentCwd = options.readParentCwd ?? readParentCwdDefault;
+
+  const fromProjectDir = sanitizeEnvPath(process.env.CLAUDE_PROJECT_DIR);
+  if (fromProjectDir) return fromProjectDir;
+
+  const fromPluginRoot = sanitizeEnvPath(process.env.CLAUDE_CRAP_PLUGIN_ROOT);
+  if (fromPluginRoot) return fromPluginRoot;
+
+  const fromParent = sanitizeEnvPath(readParentCwd());
+  if (fromParent) return fromParent;
+
+  return process.cwd();
+}
+
 /**
  * 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
@@ -98,7 +207,7 @@ function parseRating(raw: string | undefined, fallback: MaintainabilityRating):
  */
 export function loadConfig(): CrapConfig {
   return {
-    pluginRoot: process.env.CLAUDE_CRAP_PLUGIN_ROOT ?? process.cwd(),
+    pluginRoot: discoverWorkspaceRoot(),
     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),

package/src/tests/config.test.ts

@@ -0,0 +1,295 @@
+/**
+ * Characterization tests for the MCP server config loader.
+ *
+ * `loadConfig()` resolves `pluginRoot` from three env vars with
+ * strict priority:
+ *
+ *   1. `CLAUDE_PROJECT_DIR`      — set by Claude Code to the workspace
+ *   2. `CLAUDE_CRAP_PLUGIN_ROOT` — legacy explicit override
+ *   3. `process.cwd()`           — last-resort fallback
+ *
+ * These tests pin the priority chain and the numeric/rating parsers
+ * so that regressions in workspace resolution are caught before they
+ * ship a bundle that writes SARIF reports into the plugin cache.
+ *
+ * @module tests/config.test
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+
+import { loadConfig, discoverWorkspaceRoot } from "../config.js";
+
+/* ── env snapshot / restore ─────────────────────────────────────── */
+
+const ENV_KEYS = [
+  "CLAUDE_PROJECT_DIR",
+  "CLAUDE_CRAP_PLUGIN_ROOT",
+  "CLAUDE_CRAP_SARIF_OUTPUT_DIR",
+  "CLAUDE_CRAP_CRAP_THRESHOLD",
+  "CLAUDE_CRAP_CYCLOMATIC_MAX",
+  "CLAUDE_CRAP_TDR_MAX_RATING",
+  "CLAUDE_CRAP_MINUTES_PER_LOC",
+  "CLAUDE_CRAP_DASHBOARD_PORT",
+] as const;
+
+type Snapshot = Map<string, string | undefined>;
+
+function snapshotEnv(): Snapshot {
+  const snap = new Map<string, string | undefined>();
+  for (const key of ENV_KEYS) snap.set(key, process.env[key]);
+  return snap;
+}
+
+function restoreEnv(snap: Snapshot): void {
+  for (const [key, val] of snap) {
+    if (val === undefined) delete process.env[key];
+    else process.env[key] = val;
+  }
+}
+
+function clearConfigEnv(): void {
+  for (const key of ENV_KEYS) delete process.env[key];
+}
+
+/* ── tests ──────────────────────────────────────────────────────── */
+
+describe("loadConfig — pluginRoot priority chain", () => {
+  let saved: Snapshot;
+
+  beforeEach(() => {
+    saved = snapshotEnv();
+    clearConfigEnv();
+  });
+
+  afterEach(() => {
+    restoreEnv(saved);
+  });
+
+  it("falls back to process.cwd() when no env vars are set", () => {
+    const cfg = loadConfig();
+    assert.equal(cfg.pluginRoot, process.cwd());
+  });
+
+  it("CLAUDE_CRAP_PLUGIN_ROOT wins over process.cwd()", () => {
+    process.env.CLAUDE_CRAP_PLUGIN_ROOT = "/explicit/plugin/root";
+    const cfg = loadConfig();
+    assert.equal(cfg.pluginRoot, "/explicit/plugin/root");
+  });
+
+  it("CLAUDE_PROJECT_DIR wins over CLAUDE_CRAP_PLUGIN_ROOT", () => {
+    process.env.CLAUDE_PROJECT_DIR = "/workspace/project";
+    process.env.CLAUDE_CRAP_PLUGIN_ROOT = "/explicit/plugin/root";
+    const cfg = loadConfig();
+    assert.equal(cfg.pluginRoot, "/workspace/project");
+  });
+
+  it("CLAUDE_PROJECT_DIR alone resolves correctly", () => {
+    process.env.CLAUDE_PROJECT_DIR = "/workspace/project";
+    const cfg = loadConfig();
+    assert.equal(cfg.pluginRoot, "/workspace/project");
+  });
+});
+
+describe("loadConfig — defensive ${...} literal detection", () => {
+  // Claude Code only expands ${CLAUDE_PLUGIN_ROOT} in .mcp.json — any
+  // other ${VAR} is passed through verbatim. We must never treat such
+  // a literal template as a real path.
+  let saved: Snapshot;
+
+  beforeEach(() => {
+    saved = snapshotEnv();
+    clearConfigEnv();
+  });
+
+  afterEach(() => {
+    restoreEnv(saved);
+  });
+
+  it("ignores literal ${CLAUDE_PROJECT_DIR} and falls through", () => {
+    process.env.CLAUDE_PROJECT_DIR = "${CLAUDE_PROJECT_DIR}";
+    const cfg = loadConfig();
+    assert.notEqual(cfg.pluginRoot, "${CLAUDE_PROJECT_DIR}");
+    // Falls through to CLAUDE_CRAP_PLUGIN_ROOT or the last-resort fallback.
+  });
+
+  it("ignores literal ${CLAUDE_CRAP_PLUGIN_ROOT} and falls through", () => {
+    process.env.CLAUDE_CRAP_PLUGIN_ROOT = "${CLAUDE_CRAP_PLUGIN_ROOT}";
+    const cfg = loadConfig();
+    assert.notEqual(cfg.pluginRoot, "${CLAUDE_CRAP_PLUGIN_ROOT}");
+  });
+
+  it("ignores literal ${SOMETHING_ELSE} placeholder", () => {
+    process.env.CLAUDE_PROJECT_DIR = "${NOT_A_REAL_VAR}";
+    const cfg = loadConfig();
+    assert.notEqual(cfg.pluginRoot, "${NOT_A_REAL_VAR}");
+  });
+
+  it("a literal CLAUDE_PROJECT_DIR falls through to a valid CLAUDE_CRAP_PLUGIN_ROOT", () => {
+    process.env.CLAUDE_PROJECT_DIR = "${CLAUDE_PROJECT_DIR}";
+    process.env.CLAUDE_CRAP_PLUGIN_ROOT = "/explicit/plugin/root";
+    const cfg = loadConfig();
+    assert.equal(cfg.pluginRoot, "/explicit/plugin/root");
+  });
+
+  it("treats an empty CLAUDE_PROJECT_DIR as unset", () => {
+    process.env.CLAUDE_PROJECT_DIR = "";
+    process.env.CLAUDE_CRAP_PLUGIN_ROOT = "/explicit/plugin/root";
+    const cfg = loadConfig();
+    assert.equal(cfg.pluginRoot, "/explicit/plugin/root");
+  });
+});
+
+describe("discoverWorkspaceRoot — injectable parent-cwd fallback", () => {
+  // The real readParentCwd implementation reads the parent process's
+  // cwd via lsof/proc. For tests we inject a stub so we can pin the
+  // behavior without spawning lsof or depending on the host OS.
+  let saved: Snapshot;
+
+  beforeEach(() => {
+    saved = snapshotEnv();
+    clearConfigEnv();
+  });
+
+  afterEach(() => {
+    restoreEnv(saved);
+  });
+
+  it("returns env CLAUDE_PROJECT_DIR before consulting parent cwd", () => {
+    process.env.CLAUDE_PROJECT_DIR = "/workspace/project";
+    const root = discoverWorkspaceRoot({
+      readParentCwd: () => "/should/not/be/used",
+    });
+    assert.equal(root, "/workspace/project");
+  });
+
+  it("falls through literal ${...} and uses injected parent cwd", () => {
+    process.env.CLAUDE_PROJECT_DIR = "${CLAUDE_PROJECT_DIR}";
+    const root = discoverWorkspaceRoot({
+      readParentCwd: () => "/real/workspace",
+    });
+    assert.equal(root, "/real/workspace");
+  });
+
+  it("uses parent cwd when no env vars are set", () => {
+    const root = discoverWorkspaceRoot({
+      readParentCwd: () => "/discovered/via/parent",
+    });
+    assert.equal(root, "/discovered/via/parent");
+  });
+
+  it("falls back to process.cwd() when parent cwd is unavailable", () => {
+    const root = discoverWorkspaceRoot({
+      readParentCwd: () => undefined,
+    });
+    assert.equal(root, process.cwd());
+  });
+
+  it("ignores literal ${...} from parent cwd as well", () => {
+    const root = discoverWorkspaceRoot({
+      readParentCwd: () => "${something}",
+    });
+    assert.equal(root, process.cwd());
+  });
+
+  it("CLAUDE_CRAP_PLUGIN_ROOT wins over parent cwd", () => {
+    process.env.CLAUDE_CRAP_PLUGIN_ROOT = "/explicit";
+    const root = discoverWorkspaceRoot({
+      readParentCwd: () => "/parent/cwd",
+    });
+    assert.equal(root, "/explicit");
+  });
+});
+
+describe("loadConfig — defaults", () => {
+  let saved: Snapshot;
+
+  beforeEach(() => {
+    saved = snapshotEnv();
+    clearConfigEnv();
+  });
+
+  afterEach(() => {
+    restoreEnv(saved);
+  });
+
+  it("sarifOutputDir defaults to .claude-crap/reports", () => {
+    assert.equal(loadConfig().sarifOutputDir, ".claude-crap/reports");
+  });
+
+  it("crapThreshold defaults to 30", () => {
+    assert.equal(loadConfig().crapThreshold, 30);
+  });
+
+  it("cyclomaticMax defaults to 15", () => {
+    assert.equal(loadConfig().cyclomaticMax, 15);
+  });
+
+  it("tdrMaxRating defaults to C", () => {
+    assert.equal(loadConfig().tdrMaxRating, "C");
+  });
+
+  it("minutesPerLoc defaults to 30", () => {
+    assert.equal(loadConfig().minutesPerLoc, 30);
+  });
+
+  it("dashboardPort defaults to 5117", () => {
+    assert.equal(loadConfig().dashboardPort, 5117);
+  });
+});
+
+describe("loadConfig — numeric parsing", () => {
+  let saved: Snapshot;
+
+  beforeEach(() => {
+    saved = snapshotEnv();
+    clearConfigEnv();
+  });
+
+  afterEach(() => {
+    restoreEnv(saved);
+  });
+
+  it("reads CLAUDE_CRAP_CRAP_THRESHOLD from env", () => {
+    process.env.CLAUDE_CRAP_CRAP_THRESHOLD = "50";
+    assert.equal(loadConfig().crapThreshold, 50);
+  });
+
+  it("throws on non-numeric CLAUDE_CRAP_CRAP_THRESHOLD", () => {
+    process.env.CLAUDE_CRAP_CRAP_THRESHOLD = "not-a-number";
+    assert.throws(() => loadConfig(), /not a finite number/);
+  });
+
+  it("ignores empty string and falls back to default", () => {
+    process.env.CLAUDE_CRAP_CRAP_THRESHOLD = "";
+    assert.equal(loadConfig().crapThreshold, 30);
+  });
+});
+
+describe("loadConfig — rating parsing", () => {
+  let saved: Snapshot;
+
+  beforeEach(() => {
+    saved = snapshotEnv();
+    clearConfigEnv();
+  });
+
+  afterEach(() => {
+    restoreEnv(saved);
+  });
+
+  it("accepts lowercase rating", () => {
+    process.env.CLAUDE_CRAP_TDR_MAX_RATING = "a";
+    assert.equal(loadConfig().tdrMaxRating, "A");
+  });
+
+  it("accepts padded rating", () => {
+    process.env.CLAUDE_CRAP_TDR_MAX_RATING = "  B  ";
+    assert.equal(loadConfig().tdrMaxRating, "B");
+  });
+
+  it("throws on invalid rating letter", () => {
+    process.env.CLAUDE_CRAP_TDR_MAX_RATING = "F";
+    assert.throws(() => loadConfig(), /must be one of A, B, C, D, E/);
+  });
+});