@parasraju/plumber-mcp 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# @parasraju/plumber-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Plumber as an MCP server. Give your AI coding agent a deterministic, offline scanner for leaked secrets, dead code, and AI slop — with plain-English fixes it can apply immediately.
+
+No API keys, no network calls. The server reads files locally and returns findings over stdio.
+
+## Run
+
+```bash
+npx -y @parasraju/plumber-mcp
+```
+
+## Configure
+
+### Claude Code
+
+```json
+{
+  "mcpServers": {
+    "plumber": {
+      "command": "npx",
+      "args": ["-y", "@parasraju/plumber-mcp"]
+    }
+  }
+}
+```
+
+Or from the CLI:
+
+```bash
+claude mcp add plumber -- npx -y @parasraju/plumber-mcp
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):
+
+```json
+{
+  "mcpServers": {
+    "plumber": {
+      "command": "npx",
+      "args": ["-y", "@parasraju/plumber-mcp"]
+    }
+  }
+}
+```
+
+### opencode
+
+Add to `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "plumber": {
+      "type": "local",
+      "command": ["npx", "-y", "@parasraju/plumber-mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+### VS Code Copilot
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "plumber": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@parasraju/plumber-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+| --- | --- |
+| `plumber_scan` | Scan a local directory or file. Returns a score, grade, file count, and one line per issue with its fix. |
+| `plumber_list_rules` | List all 21 inspection rules with id, severity, title, and fix. |
+| `plumber_scan_text` | Scan a pasted code or config snippet. `filename` is optional and only selects the applicable rules. |
+
+Tool inputs are deliberately small so they cost few tokens:
+
+- `plumber_scan`: `target` (string, default `"."`)
+- `plumber_list_rules`: none
+- `plumber_scan_text`: `text` (string, required), `filename` (string, optional)
+
+## Example session
+
+> **You:** Scan this repo for leaked credentials and fix anything you find.
+>
+> **Agent:** *(calls `plumber_scan` with `target: "."`)*
+>
+> Found 1 issue in `src/config.js:14` — `[CRITICAL] Leaked OpenAI / Model API Key (Extract secret to .env file immediately.)`
+>
+> **Agent:** I moved the key into `.env`, replaced it with `process.env.OPENAI_API_KEY`, and added `.env` to `.gitignore`. You should revoke the exposed key.
+
+## Links
+
+- CLI: [plumber-linter](https://www.npmjs.com/package/plumber-linter)
+- Repository: [github.com/parasraju/plumber](https://github.com/parasraju/plumber)

package/bin/plumber-mcp.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+
+/**
+ * Plumber MCP stdio server.
+ *
+ * Tools:
+ *   plumber_scan        scan a local directory or file
+ *   plumber_list_rules  list the 21 inspection rules
+ *   plumber_scan_text   scan a pasted snippet
+ *
+ * Only JSON-RPC goes to stdout. Diagnostics go to stderr.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ErrorCode,
+  McpError
+} = require('@modelcontextprotocol/sdk/types.js');
+const { RULES, scanLocalDirectory, scanText } = require('../src/engine.js');
+
+const SERVER_INFO = { name: 'plumber-mcp', version: '1.0.0' };
+
+const TOOLS = [
+  {
+    name: 'plumber_scan',
+    description: 'Scan a local directory or file for leaked secrets, dead code, and AI slop. Returns a score and fixes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: { type: 'string', description: 'Directory or file path to scan (default ".")' }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: 'plumber_list_rules',
+    description: 'List all Plumber inspection rules with severity, title, and recommended fix.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false
+    }
+  },
+  {
+    name: 'plumber_scan_text',
+    description: 'Scan a pasted code or config snippet for leaked secrets, dead code, and AI slop.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'Code or config snippet to scan' },
+        filename: { type: 'string', description: 'Optional filename used to select applicable rules (e.g. app.js)' }
+      },
+      required: ['text'],
+      additionalProperties: false
+    }
+  }
+];
+
+function formatReport(report) {
+  const header = [
+    `Plumber Health Report for ${report.repo_name}`,
+    `Score: ${report.score}/100 (Grade ${report.grade})`,
+    `Files: ${report.total_files} | Issues: ${report.issues.length}`
+  ].join('\n');
+
+  if (report.issues.length === 0) {
+    return `${header}\n\nNo issues found.`;
+  }
+
+  const locations = new Map();
+  for (const file of report.file_reports) {
+    for (const issue of file.issues) {
+      locations.set(issue, `${file.path}:${issue.line}`);
+    }
+  }
+
+  const lines = report.issues.map((issue) => {
+    const location = locations.get(issue);
+    const suffix = location ? ` — ${location}` : '';
+    return `- [${issue.severity}] ${issue.title} (${issue.fix})${suffix}`;
+  });
+
+  return `${header}\n\n${lines.join('\n')}`;
+}
+
+function requireString(value, name) {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new McpError(ErrorCode.InvalidParams, `'${name}' must be a non-empty string`);
+  }
+  return value;
+}
+
+function requireText(text) {
+  if (typeof text !== 'string' || text.trim() === '') {
+    throw new McpError(ErrorCode.InvalidParams, "'text' must be a non-empty string");
+  }
+  return text;
+}
+
+function runScanTool(args) {
+  const target = requireString(args.target, 'target') || '.';
+  const absolute = path.resolve(target);
+
+  if (!fs.existsSync(absolute)) {
+    throw new McpError(ErrorCode.InvalidParams, `Target path does not exist: ${absolute}`);
+  }
+
+  try {
+    return formatReport(scanLocalDirectory(absolute));
+  } catch (err) {
+    throw new McpError(ErrorCode.InternalError, `Scan failed: ${err.message}`);
+  }
+}
+
+function runScanTextTool(args) {
+  const text = requireText(args.text);
+  const filename = requireString(args.filename, 'filename');
+
+  try {
+    return formatReport(scanText(text, filename));
+  } catch (err) {
+    throw new McpError(ErrorCode.InternalError, `Scan failed: ${err.message}`);
+  }
+}
+
+function runListRulesTool() {
+  return RULES.map((rule) => `${rule.id} [${rule.sev}] ${rule.title} (${rule.fix})`).join('\n');
+}
+
+async function main() {
+  const server = new Server(SERVER_INFO, { capabilities: { tools: {} } });
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const name = request.params.name;
+    const args = request.params.arguments || {};
+    let text;
+
+    if (name === 'plumber_scan') {
+      text = runScanTool(args);
+    } else if (name === 'plumber_list_rules') {
+      text = runListRulesTool();
+    } else if (name === 'plumber_scan_text') {
+      text = runScanTextTool(args);
+    } else {
+      throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+    }
+
+    return { content: [{ type: 'text', text }] };
+  });
+
+  server.onerror = (error) => {
+    process.stderr.write(`[plumber-mcp] ${error.message}\n`);
+  };
+
+  await server.connect(new StdioServerTransport());
+  process.stderr.write('Plumber MCP stdio server started\n');
+}
+
+main().catch((error) => {
+  process.stderr.write(`[plumber-mcp] Failed to start: ${error.stack || error.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@parasraju/plumber-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Plumber as an MCP server — let your AI coding agent scan repos for leaked secrets, dead code, and AI slop, with fixes in plain English.",
+  "main": "src/engine.js",
+  "bin": {
+    "plumber-mcp": "bin/plumber-mcp.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "cursor",
+    "opencode",
+    "ai-agents",
+    "security",
+    "secrets-detection",
+    "code-quality",
+    "linter"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/parasraju/plumber.git"
+  },
+  "homepage": "https://github.com/parasraju/plumber#readme",
+  "bugs": {
+    "url": "https://github.com/parasraju/plumber/issues"
+  },
+  "license": "MIT",
+  "author": "Paras Raju",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2"
+  }
+}

package/src/engine.js

@@ -0,0 +1,304 @@
+/**
+ * Plumber inspection engine.
+ *
+ * Ported from plumber-linter v1.1.2
+ * (packages/cli/bin/plumber.js, commit bde61c5), with two additions:
+ *   - leak/api-key now matches AWS access key IDs (AKIA...).
+ *   - leak/hardcoded-secret now matches quoted password/token assignments.
+ * Both rule IDs already exist in the CLI's RULES table; the CLI declares them
+ * but does not detect them. The CLI itself is left untouched.
+ *
+ * This is a copy rather than a shared import because the published CLI package
+ * ships only `bin/` and `README.md`, so a relative import from the MCP package
+ * would break `plumber-linter` for npm consumers. The CLI is intentionally left
+ * untouched; keep the detection rules in this file in sync with the CLI.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ENV_TEMPLATE_RE = /\.(example|sample|template|dist)$/;
+
+const RULES = [
+  { id: 'leak/api-key', cat: 'Leaks & Secrets', sev: 'CRITICAL', title: 'Leaked API Key or Private Access Token', fix: 'Move secret to environment variable (.env).' },
+  { id: 'leak/committed-env', cat: 'Leaks & Secrets', sev: 'CRITICAL', title: 'Production Secret Committed in Environment File', fix: 'Remove sensitive values and use .env.example.' },
+  { id: 'leak/hardcoded-secret', cat: 'Leaks & Secrets', sev: 'HIGH', title: 'Hardcoded Password or Database Credential', fix: 'Replace with process.env / os.environ reference.' },
+  { id: 'sec/raw-html', cat: 'Leaks & Secrets', sev: 'MEDIUM', title: 'Raw HTML Injection (XSS Risk)', fix: 'Use textContent or safe DOM templating.' },
+  { id: 'clog/elided-code', cat: 'Clogs & Dead Code', sev: 'HIGH', title: 'AI-Elided Code Snippet Left in File', fix: 'Restore the complete function or component implementation.' },
+  { id: 'clog/swallowed-error', cat: 'Clogs & Dead Code', sev: 'HIGH', title: 'Swallowed Exception (Silent Failure)', fix: 'Log the error or properly re-raise/handle it.' },
+  { id: 'clog/stub-function', cat: 'Clogs & Dead Code', sev: 'MEDIUM', title: 'Unimplemented Stub Function', fix: 'Complete missing logic or remove placeholder.' },
+  { id: 'clog/step-comments', cat: 'Clogs & Dead Code', sev: 'LOW', title: 'Robotic AI Step Comments Left Behind', fix: 'Clean up AI instructional comments.' },
+  { id: 'clog/dead-code', cat: 'Clogs & Dead Code', sev: 'HIGH', title: 'Unreachable Dead Code', fix: 'Delete unreachable lines or run plumber clean --write.' },
+  { id: 'slop/pointless-wrapper', cat: 'Clogs & Dead Code', sev: 'LOW', title: 'Function That Only Forwards Its Arguments', fix: 'Call underlying function directly.' },
+  { id: 'joint/icon-button', cat: 'Joints & Accessibility', sev: 'HIGH', title: 'Icon Button Without Accessible Name', fix: 'Add aria-label attribute to button element.' },
+  { id: 'joint/clickable-div', cat: 'Joints & Accessibility', sev: 'HIGH', title: 'Non-Semantic Clickable Element (Missing Button / Role)', fix: 'Use native <button type="button">.' },
+  { id: 'joint/empty-test', cat: 'Joints & Accessibility', sev: 'HIGH', title: 'Empty Test with No Assertions', fix: 'Add assert statements or verification logic.' },
+  { id: 'joint/focus-removed', cat: 'Joints & Accessibility', sev: 'MEDIUM', title: 'Focus Outline Removed Without Replacement', fix: 'Provide a visible :focus-visible style.' },
+  { id: 'pipe/phantom-import', cat: 'Pipes & Dependencies', sev: 'HIGH', title: 'Plausible but Hallucinated Package Import', fix: 'Check package registry or use official package.' },
+  { id: 'pipe/dead-link', cat: 'Pipes & Dependencies', sev: 'MEDIUM', title: 'Broken or Null Link in Navigation', fix: 'Use a <button> for actions or valid route for href.' },
+  { id: 'slop/ai-gradient', cat: 'AI Slop Tells', sev: 'MEDIUM', title: 'Purple / Violet AI Default Gradient', fix: 'Use clean brand tokens or neutral surfaces.' },
+  { id: 'slop/chatbot-residue', cat: 'AI Slop Tells', sev: 'MEDIUM', title: 'Pasted Chatbot Conversational Residue', fix: 'Delete conversational intro/outro boilerplate.' },
+  { id: 'slop/neon-glow', cat: 'AI Slop Tells', sev: 'LOW', title: 'Colored Neon Glow Shadow', fix: 'Replace with subtle crisp 1px borders.' },
+  { id: 'slop/gradient-text', cat: 'AI Slop Tells', sev: 'LOW', title: 'Gradient-Clipped Headline Text', fix: 'Use solid, high-contrast typography.' },
+  { id: 'ui/important-abuse', cat: 'AI Slop Tells', sev: 'LOW', title: '!important Overrides in Stylesheet', fix: 'Structure CSS cascade cleanly without !important.' }
+];
+
+const SEV_WEIGHT = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1, INFO: 0 };
+
+function gradeFor(score) {
+  return score >= 90 ? 'A' : score >= 80 ? 'B' : score >= 70 ? 'C' : score >= 60 ? 'D' : 'F';
+}
+
+function scoreFor(issueCount) {
+  return Math.max(0, 100 - (issueCount * 4.2));
+}
+
+function scanLocalDirectory(dirPath) {
+  const scannableExts = new Set(['.py', '.js', '.jsx', '.ts', '.tsx', '.html', '.htm', '.css', '.scss', '.env']);
+  const skipDirs = new Set(['.git', 'node_modules', 'dist', 'build', '.next', '.nuxt', 'vendor', '.venv', 'venv', '__pycache__']);
+
+  const issues = [];
+  let totalFiles = 0;
+  let totalLines = 0;
+  const fileReports = [];
+
+  function walk(current) {
+    const stat = fs.statSync(current);
+    if (stat.isFile()) {
+      const ext = path.extname(current).toLowerCase();
+      const base = path.basename(current);
+      if (scannableExts.has(ext) || base.startsWith('.env')) {
+        totalFiles++;
+        const rel = path.relative(dirPath, current).replace(/\\/g, '/') || path.basename(current);
+        try {
+          const content = fs.readFileSync(current, 'utf-8');
+          const lines = content.split('\n');
+          totalLines += lines.length;
+          const fileIssues = inspectFile(rel, content, lines, ext);
+          if (fileIssues.length > 0) {
+            issues.push(...fileIssues);
+            fileReports.push({ path: rel, issues: fileIssues });
+          }
+        } catch (err) {
+          // Unreadable or locked file: skip it, matching the CLI's behavior.
+          void err;
+        }
+      }
+      return;
+    }
+
+    if (stat.isDirectory()) {
+      const base = path.basename(current);
+      if (skipDirs.has(base) || (base.startsWith('.') && base !== '.')) return;
+      const entries = fs.readdirSync(current);
+      for (const entry of entries) {
+        walk(path.join(current, entry));
+      }
+    }
+  }
+
+  walk(dirPath);
+
+  const score = scoreFor(issues.length);
+  const grade = gradeFor(score);
+
+  return {
+    repo_name: path.basename(dirPath),
+    total_files: totalFiles,
+    total_lines: totalLines,
+    score: Math.round(score * 10) / 10,
+    grade,
+    issues,
+    file_reports: fileReports
+  };
+}
+
+function scanText(text, filename) {
+  if (typeof text !== 'string') {
+    throw new TypeError('text must be a string');
+  }
+  const name = filename && typeof filename === 'string' ? path.basename(filename) : 'snippet.js';
+  const ext = path.extname(name).toLowerCase();
+  const content = text.replace(/\r\n?/g, '\n');
+  const lines = content.split('\n');
+  const issues = inspectFile(name, content, lines, ext);
+  const score = scoreFor(issues.length);
+
+  return {
+    repo_name: name,
+    total_files: 1,
+    total_lines: lines.length,
+    score: Math.round(score * 10) / 10,
+    grade: gradeFor(score),
+    issues,
+    file_reports: issues.length > 0 ? [{ path: name, issues }] : []
+  };
+}
+
+function inspectFile(relPath, content, lines, ext) {
+  const issues = [];
+  const lower = content.toLowerCase();
+  const base = path.basename(relPath);
+  const isTest = relPath.toLowerCase().includes('test') || relPath.toLowerCase().includes('spec');
+
+  // Environment files must never be committed
+  if (base.startsWith('.env') && !ENV_TEMPLATE_RE.test(base)) {
+    issues.push({ rule_id: 'leak/committed-env', title: 'Environment File Staged for Commit', severity: 'CRITICAL', line: 1, evidence: base, fix: 'Remove from git, add to .gitignore, and commit .env.example instead.' });
+  }
+
+  // Elided code
+  if (!isTest && /(?:\/\/|#|\/\*)\s*(?:\.\.\.|…)?\s*(?:existing\s+code|rest\s+of\s+code)/i.test(content)) {
+    lines.forEach((l, idx) => {
+      if (/(?:\/\/|#|\/\*)\s*(?:\.\.\.|…)?\s*(?:existing\s+code|rest\s+of\s+code)/i.test(l)) {
+        issues.push({ rule_id: 'clog/elided-code', title: 'AI-Elided Code Snippet Left in File', severity: 'HIGH', line: idx + 1, evidence: l.trim().slice(0, 90), fix: 'Restore the complete code implementation.' });
+      }
+    });
+  }
+
+  // Swallowed error
+  if (!isTest && (ext === '.py' || ext === '.js' || ext === '.ts' || ext === '.jsx' || ext === '.tsx')) {
+    lines.forEach((l, idx) => {
+      const trim = l.trim();
+      if (trim.startsWith('#') || trim.startsWith('//') || trim.startsWith('/*')) return;
+      if (ext === '.py' && /^\s*except(?:\s+\w+)?:\s*(?:pass|\.\.\.)/.test(l)) {
+        issues.push({ rule_id: 'clog/swallowed-error', title: 'Swallowed Exception (Silent Failure)', severity: 'HIGH', line: idx + 1, evidence: trim, fix: 'Log the error or properly re-raise/handle it.' });
+      } else if (ext !== '.py' && /catch\s*\([^)]*\)\s*\{\s*\}/.test(l)) {
+        issues.push({ rule_id: 'clog/swallowed-error', title: 'Swallowed Exception (Silent Failure)', severity: 'HIGH', line: idx + 1, evidence: trim, fix: 'Log the error or properly re-raise/handle it.' });
+      }
+    });
+  }
+
+  // API keys
+  if (!isTest && (content.includes('sk-') || content.includes('ghp_') || content.includes('AKIA'))) {
+    lines.forEach((l, idx) => {
+      const trim = l.trim();
+      if (trim.startsWith('#') || trim.startsWith('//')) return;
+      if (/\b(sk-(?:live|test|proj)?[a-zA-Z0-9_-]{24,})\b/.test(l)) {
+        issues.push({ rule_id: 'leak/api-key', title: 'Leaked OpenAI / Model API Key', severity: 'CRITICAL', line: idx + 1, evidence: trim.slice(0, 70), fix: 'Extract secret to .env file immediately.' });
+      }
+      if (/\b(ghp_[a-zA-Z0-9]{36})\b/.test(l)) {
+        issues.push({ rule_id: 'leak/api-key', title: 'Leaked GitHub Personal Access Token', severity: 'CRITICAL', line: idx + 1, evidence: trim.slice(0, 70), fix: 'Revoke key and store in secrets manager.' });
+      }
+      // Added in the MCP package: AWS access key IDs.
+      if (/\b(AKIA[0-9A-Z]{16})\b/.test(l)) {
+        issues.push({ rule_id: 'leak/api-key', title: 'Leaked AWS Access Key ID', severity: 'CRITICAL', line: idx + 1, evidence: trim.slice(0, 70), fix: 'Revoke key and store in secrets manager.' });
+      }
+    });
+  }
+
+  // Hardcoded password or token assignment.
+  // Added in the MCP package: the CLI declares leak/hardcoded-secret but has no match.
+  if (!isTest && !ENV_TEMPLATE_RE.test(base) && /(?:password|passwd|pwd|secret|api[_-]?key|token)/i.test(content)) {
+    lines.forEach((l, idx) => {
+      const trim = l.trim();
+      if (trim.startsWith('#') || trim.startsWith('//') || trim.startsWith('/*')) return;
+      const match = /(?:password|passwd|pwd|secret|api[_-]?key|token)\w*\s*[:=]\s*['"]([^'"]{4,})['"]/i.exec(l);
+      if (match && !match[1].includes('${') && !/^(?:sk-|ghp_|AKIA)/.test(match[1])) {
+        issues.push({ rule_id: 'leak/hardcoded-secret', title: 'Hardcoded Password or Database Credential', severity: 'HIGH', line: idx + 1, evidence: trim.slice(0, 90), fix: 'Replace with process.env / os.environ reference.' });
+      }
+    });
+  }
+
+  // Clickable div
+  if ((ext === '.html' || ext === '.jsx' || ext === '.tsx') && lower.includes('<div') && lower.includes('onclick')) {
+    lines.forEach((l, idx) => {
+      if (/<(?:div|span)\b(?![^>]*role=)[^>]*(?:onClick|onclick)=/i.test(l)) {
+        issues.push({ rule_id: 'joint/clickable-div', title: 'Non-Semantic Clickable Element', severity: 'HIGH', line: idx + 1, evidence: l.trim().slice(0, 80), fix: 'Use a native <button type="button"> instead.' });
+      }
+    });
+  }
+
+  // AI Default Gradient
+  if ((ext === '.html' || ext === '.jsx' || ext === '.tsx' || ext === '.css') && (lower.includes('purple') || lower.includes('violet'))) {
+    lines.forEach((l, idx) => {
+      if (/\b(?:from|via|to)-(?:purple|violet|indigo|fuchsia)-\d{2,3}\b/.test(l)) {
+        issues.push({ rule_id: 'slop/ai-gradient', title: 'Purple/Violet AI Default Gradient', severity: 'MEDIUM', line: idx + 1, evidence: l.trim().slice(0, 80), fix: 'Use clean brand tokens or neutral surface.' });
+      }
+    });
+  }
+
+  // Unreachable dead code
+  for (const dead of findDeadCode(content, ext)) {
+    issues.push({
+      rule_id: 'clog/dead-code',
+      title: 'Unreachable Dead Code',
+      severity: 'HIGH',
+      line: dead.line,
+      evidence: dead.evidence.slice(0, 100),
+      fix: dead.removable ? "Delete this unreachable line or run 'plumber clean <path> --write'." : 'Remove the constant-false branch and its body.'
+    });
+  }
+
+  return issues;
+}
+
+function findDeadCode(content, ext) {
+  if (!['.py', '.js', '.jsx', '.ts', '.tsx'].includes(ext)) return [];
+  const lines = content.split('\n');
+  const skip = new Set();
+  markMultilineStrings(lines, skip, ext === '.py' ? ['"""', "'''"] : ['`']);
+
+  const found = [];
+  const indentOf = (line) => line.length - line.replace(/^[ \t]+/, '').length;
+  const termRe = ext === '.py' ? /^(return|raise|break|continue)\b/ : /^(return|throw|break|continue)\b/;
+  const unsafeTail = ['\\', '(', '[', '{', ',', ':', '+', '-', '*', '/', '%', '&', '|', '=', '?', '>'];
+
+  for (let idx = 0; idx < lines.length; idx++) {
+    const line = lines[idx];
+    const clean = line.trim();
+    if (skip.has(idx) || !clean || clean.startsWith('#') || clean.startsWith('//') || clean.startsWith('/*') || clean.startsWith('*')) continue;
+
+    const isPy = ext === '.py';
+    const deadBranch = isPy ? /^(?:if|while)\s+(?:False|0)\s*:/.test(clean) : /^(?:if|while)\s*\(\s*(?:false|0)\s*\)/.test(clean);
+    if (deadBranch) {
+      found.push({ line: idx + 1, reason: 'Dead branch: condition is always false', evidence: clean, removable: false });
+      continue;
+    }
+
+    const terminator = termRe.exec(clean);
+    if (!terminator || unsafeTail.some((t) => clean.endsWith(t))) continue;
+
+    const target = findUnreachable(lines, idx, indentOf(line), skip, isPy);
+    if (target !== null) {
+      found.push({ line: target + 1, reason: `Unreachable statement after '${terminator[1]}'`, evidence: lines[target].trim(), removable: true });
+    }
+  }
+  return found;
+}
+
+function markMultilineStrings(lines, skip, quotes) {
+  let inside = null;
+  for (let idx = 0; idx < lines.length; idx++) {
+    if (inside !== null) skip.add(idx);
+    for (const quote of quotes) {
+      const count = lines[idx].split(quote).length - 1;
+      if (count === 0) continue;
+      if (inside === quote) {
+        if (count % 2 === 1) inside = null;
+      } else if (inside === null && count % 2 === 1) {
+        inside = quote;
+      }
+    }
+  }
+}
+
+function findUnreachable(lines, start, indent, skip, isPy) {
+  const closers = ['else:', 'elif ', 'except', 'finally:', 'case ', 'default:'];
+  for (let j = start + 1; j < lines.length; j++) {
+    const raw = lines[j];
+    const clean = raw.trim();
+    if (skip.has(j) || !clean || clean.startsWith('#') || clean.startsWith('//') || clean.startsWith('/*') || clean.startsWith('*')) continue;
+    if ((raw.length - raw.replace(/^[ \t]+/, '').length) < indent) return null;
+    if (isPy ? closers.some((p) => clean.startsWith(p)) : /^(?:\}|else\b|catch\b|finally\b|case\b|default\b)/.test(clean)) return null;
+    if (/^[\)\]\}\.,:?+\-*\/%&|]/.test(clean)) continue;
+    return j;
+  }
+  return null;
+}
+
+module.exports = {
+  RULES,
+  SEV_WEIGHT,
+  scanLocalDirectory,
+  scanText
+};