slopbrick 0.18.3 → 0.18.5

package/dist/index.js

@@ -14,15 +14,41 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
-// src/types.ts
-import { createRequire } from "module";
-var require2, pkg, VERSION, AI_SECURITY_NUMERIC, REPOSITORY_HEALTH_WEIGHTS;
-var init_types = __esm({
-  "src/types.ts"() {
+// src/types/_header.ts
+var VERSION;
+var init_header = __esm({
+  "src/types/_header.ts"() {
+    "use strict";
+    VERSION = "0.18.5";
+  }
+});
+
+// src/types/primitives.ts
+var init_primitives = __esm({
+  "src/types/primitives.ts"() {
+    "use strict";
+  }
+});
+
+// src/types/scan.ts
+var init_scan = __esm({
+  "src/types/scan.ts"() {
+    "use strict";
+  }
+});
+
+// src/types/config.ts
+var init_config = __esm({
+  "src/types/config.ts"() {
+    "use strict";
+  }
+});
+
+// src/types/report.ts
+var AI_SECURITY_NUMERIC, REPOSITORY_HEALTH_WEIGHTS;
+var init_report = __esm({
+  "src/types/report.ts"() {
     "use strict";
-    require2 = createRequire(import.meta.url);
-    pkg = require2("../package.json");
-    VERSION = pkg.version;
     AI_SECURITY_NUMERIC = {
       low: 100,
       medium: 75,
@@ -42,6 +68,34 @@ var init_types = __esm({
   }
 });
 
+// src/types/project-report.ts
+var init_project_report = __esm({
+  "src/types/project-report.ts"() {
+    "use strict";
+  }
+});
+
+// src/types/baseline.ts
+var init_baseline = __esm({
+  "src/types/baseline.ts"() {
+    "use strict";
+  }
+});
+
+// src/types/index.ts
+var init_types = __esm({
+  "src/types/index.ts"() {
+    "use strict";
+    init_header();
+    init_primitives();
+    init_scan();
+    init_config();
+    init_report();
+    init_project_report();
+    init_baseline();
+  }
+});
+
 // src/config/defaults.ts
 var DEFAULT_SPACING_SCALE, DEFAULT_RADIUS_SCALE, DEFAULT_RULE_CONFIG, DEFAULT_CONFIG;
 var init_defaults = __esm({
@@ -295,9 +349,9 @@ function findWorkspacePackages(cwd) {
   const pkgPath = join(root, "package.json");
   if (existsSync(pkgPath)) {
     try {
-      const pkg2 = JSON.parse(readFileSync(pkgPath, "utf-8"));
-      if (Array.isArray(pkg2.workspaces)) {
-        for (const pattern of pkg2.workspaces) {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+      if (Array.isArray(pkg.workspaces)) {
+        for (const pattern of pkg.workspaces) {
           packages.push(...expandWorkspacePattern(root, pattern));
         }
       }
@@ -355,11 +409,11 @@ function detectStylingSolution(cwd) {
   let deps = {};
   if (existsSync2(pkgPath)) {
     try {
-      const pkg2 = JSON.parse(readFileSync2(pkgPath, "utf-8"));
+      const pkg = JSON.parse(readFileSync2(pkgPath, "utf-8"));
       deps = {
-        ...pkg2.dependencies,
-        ...pkg2.devDependencies,
-        ...pkg2.peerDependencies
+        ...pkg.dependencies,
+        ...pkg.devDependencies,
+        ...pkg.peerDependencies
       };
     } catch {
     }
@@ -558,11 +612,11 @@ function detectStack(cwd) {
     return {};
   }
   try {
-    const pkg2 = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
     const deps = {
-      ...pkg2.dependencies,
-      ...pkg2.devDependencies,
-      ...pkg2.peerDependencies
+      ...pkg.dependencies,
+      ...pkg.devDependencies,
+      ...pkg.peerDependencies
     };
     const names = Object.keys(deps).map((name) => name.toLowerCase());
     const result = {};
@@ -26195,13 +26249,13 @@ var init_default_react_stack = __esm({
         for (const m of source.matchAll(IMPORT_LINE_RE)) {
           const spec = m[1];
           if (!spec) continue;
-          const pkg2 = spec.startsWith("@/") ? spec : spec.startsWith("@") ? spec.split("/").slice(0, 2).join("/") : spec.split("/")[0];
-          if (pkg2) importedPackages.add(pkg2);
+          const pkg = spec.startsWith("@/") ? spec : spec.startsWith("@") ? spec.split("/").slice(0, 2).join("/") : spec.split("/")[0];
+          if (pkg) importedPackages.add(pkg);
         }
         const hits = [];
-        for (const pkg2 of importedPackages) {
-          if (DEFAULT_STACK_PACKAGES.some((p) => p === pkg2 || p.startsWith(pkg2 + "/"))) {
-            hits.push(pkg2);
+        for (const pkg of importedPackages) {
+          if (DEFAULT_STACK_PACKAGES.some((p) => p === pkg || p.startsWith(pkg + "/"))) {
+            hits.push(pkg);
           }
         }
         if (hits.length < MIN_HITS) return [];
@@ -28091,6 +28145,205 @@ var init_sql_concat = __esm({
   }
 });
 
+// src/rules/dead/dead-branch.ts
+var deadBranchRule;
+var init_dead_branch = __esm({
+  "src/rules/dead/dead-branch.ts"() {
+    "use strict";
+    init_rule();
+    deadBranchRule = createRule({
+      id: "dead/dead-branch",
+      category: "logic",
+      severity: "medium",
+      aiSpecific: true,
+      description: "Literal boolean condition makes one branch statically dead",
+      create(_context) {
+        return {};
+      },
+      analyze(_context, facts) {
+        const issues = [];
+        if (!facts.v2) return issues;
+        for (const cond of facts.v2.deadCode.constantConditions) {
+          const isWhileTrue = cond.kind === "while-true";
+          issues.push({
+            ruleId: "dead/dead-branch",
+            category: "logic",
+            severity: isWhileTrue ? "low" : "medium",
+            aiSpecific: true,
+            message: isWhileTrue ? `Infinite loop with literal condition (${cond.kind})` : `Dead branch: condition is always ${cond.condition}`,
+            line: cond.line,
+            column: cond.column,
+            advice: isWhileTrue ? `If this is an intentional infinite loop (event loop, hot loop with explicit \`break\`), add a \`// slopbrick-disable\` comment. Otherwise, replace the literal with a real condition.` : `Replace the literal with a real condition, or remove the dead branch entirely. This is the AI-iteration signature: the model toggled a feature flag to a constant or left a wrapper from a previous refactor.`
+          });
+        }
+        return issues;
+      }
+    });
+  }
+});
+
+// src/rules/dead/unreachable.ts
+var unreachableRule;
+var init_unreachable = __esm({
+  "src/rules/dead/unreachable.ts"() {
+    "use strict";
+    init_rule();
+    unreachableRule = createRule({
+      id: "dead/unreachable",
+      category: "logic",
+      severity: "high",
+      aiSpecific: true,
+      description: "Statement is unreachable after an unconditional return/throw/break/continue",
+      create(_context) {
+        return {};
+      },
+      analyze(_context, facts) {
+        const issues = [];
+        if (!facts.v2) return issues;
+        for (const u of facts.v2.deadCode.unreachableStatements) {
+          if (u.snippet === "<unreachable>") continue;
+          issues.push({
+            ruleId: "dead/unreachable",
+            category: "logic",
+            severity: "high",
+            aiSpecific: true,
+            message: `Unreachable after ${u.terminator}: ${u.snippet}`,
+            line: u.line,
+            column: u.column,
+            advice: `Remove this statement \u2014 code after a ${u.terminator} is unreachable. This is the AI-iteration signature: the model added an early ${u.terminator} for a new error path, then forgot the rest of the function body was still sitting below it.`
+          });
+        }
+        return issues;
+      }
+    });
+  }
+});
+
+// src/rules/dead/unused-import.ts
+var unusedImportRule;
+var init_unused_import = __esm({
+  "src/rules/dead/unused-import.ts"() {
+    "use strict";
+    init_rule();
+    unusedImportRule = createRule({
+      id: "dead/unused-import",
+      category: "logic",
+      severity: "low",
+      aiSpecific: true,
+      description: "ES module import is never referenced in the file",
+      create(_context) {
+        return {};
+      },
+      analyze(_context, facts) {
+        const issues = [];
+        if (!facts.v2) return issues;
+        for (const binding of facts.v2.deadCode.bindings) {
+          if (binding.kind !== "import-specifier" && binding.kind !== "import-default" && binding.kind !== "import-namespace") {
+            continue;
+          }
+          if (binding.isReferenced) continue;
+          if (!binding.name) continue;
+          const source = binding.source ? ` from '${binding.source}'` : "";
+          issues.push({
+            ruleId: "dead/unused-import",
+            category: "logic",
+            severity: "low",
+            aiSpecific: true,
+            message: `Unused import: '${binding.name}'${source}`,
+            line: binding.line,
+            column: binding.column,
+            advice: `Remove the import or use '${binding.name}' somewhere in the file. This is the most common AI-iteration rot \u2014 the model added the import when it introduced a feature, then rewrote the function without cleaning up.`
+          });
+        }
+        return issues;
+      }
+    });
+  }
+});
+
+// src/rules/dead/unused-local.ts
+var SKIP_NAMES, unusedLocalRule;
+var init_unused_local = __esm({
+  "src/rules/dead/unused-local.ts"() {
+    "use strict";
+    init_rule();
+    SKIP_NAMES = /* @__PURE__ */ new Set(["React", "_"]);
+    unusedLocalRule = createRule({
+      id: "dead/unused-local",
+      category: "logic",
+      severity: "low",
+      aiSpecific: true,
+      description: "Variable is declared but never read after declaration",
+      create(_context) {
+        return {};
+      },
+      analyze(_context, facts) {
+        const issues = [];
+        if (!facts.v2) return issues;
+        for (const binding of facts.v2.deadCode.bindings) {
+          if (binding.kind !== "var" && binding.kind !== "let" && binding.kind !== "const" && binding.kind !== "function" && binding.kind !== "class" && binding.kind !== "type" && binding.kind !== "interface" && binding.kind !== "enum") {
+            continue;
+          }
+          if (binding.isReferenced) continue;
+          if (SKIP_NAMES.has(binding.name)) continue;
+          if (binding.name.startsWith("_")) continue;
+          issues.push({
+            ruleId: "dead/unused-local",
+            category: "logic",
+            severity: "low",
+            aiSpecific: true,
+            message: `Unused ${binding.kind}: '${binding.name}'`,
+            line: binding.line,
+            column: binding.column,
+            advice: `Remove the declaration or use '${binding.name}' somewhere in the file. This is the second-most-common AI-iteration signature \u2014 the model declared the binding when it introduced a feature, then rewrote the function without cleaning up.`
+          });
+        }
+        return issues;
+      }
+    });
+  }
+});
+
+// src/rules/dead/unused-parameter.ts
+var unusedParameterRule;
+var init_unused_parameter = __esm({
+  "src/rules/dead/unused-parameter.ts"() {
+    "use strict";
+    init_rule();
+    unusedParameterRule = createRule({
+      id: "dead/unused-parameter",
+      category: "logic",
+      severity: "low",
+      aiSpecific: true,
+      description: "Function parameter is declared but never read",
+      create(_context) {
+        return {};
+      },
+      analyze(_context, facts) {
+        const issues = [];
+        if (!facts.v2) return issues;
+        for (const binding of facts.v2.deadCode.bindings) {
+          if (binding.kind !== "parameter") continue;
+          if (binding.isReferenced) continue;
+          if (binding.name.startsWith("_")) continue;
+          if (binding.name === "props") continue;
+          issues.push({
+            ruleId: "dead/unused-parameter",
+            category: "logic",
+            severity: "low",
+            aiSpecific: true,
+            message: `Unused parameter: '${binding.name}'`,
+            line: binding.line,
+            column: binding.column,
+            advice: `Remove the parameter (and update every call site) or use '${binding.name}' in the function body. This is the AI-iteration signature: the model added the parameter when it introduced a feature, then rewrote the function without removing parameters the new code does not need.`
+          });
+        }
+        return issues;
+      }
+    });
+  }
+});
+
 // src/engine/discover.ts
 var discover_exports = {};
 __export(discover_exports, {
@@ -28202,14 +28455,14 @@ import { join as join5 } from "path";
 function readDeps(cwd) {
   const pkgPath = join5(cwd, "package.json");
   if (!existsSync4(pkgPath)) return /* @__PURE__ */ new Set();
-  let pkg2;
+  let pkg;
   try {
-    pkg2 = JSON.parse(readFileSync5(pkgPath, "utf-8"));
+    pkg = JSON.parse(readFileSync5(pkgPath, "utf-8"));
   } catch {
     return /* @__PURE__ */ new Set();
   }
   const out = /* @__PURE__ */ new Set();
-  for (const source of [pkg2.dependencies, pkg2.devDependencies]) {
+  for (const source of [pkg.dependencies, pkg.devDependencies]) {
     if (source && typeof source === "object") {
       for (const name of Object.keys(source)) out.add(name);
     }
@@ -28225,8 +28478,8 @@ function detectConstitution(cwd) {
   const deps = readDeps(cwd);
   if (deps.size === 0) return {};
   const out = {};
-  for (const [pkg2, { field, signal }] of Object.entries(CONSTITUTION_SIGNALS)) {
-    if (deps.has(pkg2)) {
+  for (const [pkg, { field, signal }] of Object.entries(CONSTITUTION_SIGNALS)) {
+    if (deps.has(pkg)) {
       out[field] = pushUnique(
         out[field],
         signal
@@ -29920,9 +30173,9 @@ function declaredPackages(cwd) {
   if (!existsSync6(pkgPath)) return out;
   try {
     const raw = readFileSync8(pkgPath, "utf-8");
-    const pkg2 = JSON.parse(raw);
+    const pkg = JSON.parse(raw);
     for (const k of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
-      const v = pkg2[k];
+      const v = pkg[k];
       if (v && typeof v === "object") {
         for (const name of Object.keys(v)) {
           out.add(name);
@@ -30349,7 +30602,7 @@ var init_spacing_grid = __esm({
     "use strict";
     init_rule();
     init_utils();
-    init_config();
+    init_config2();
     SPACING_PREFIX_RE = /^-?(p|px|py|pt|pr|pb|pl|m|mx|my|mt|mr|mb|ml|gap|gap-x|gap-y|space-x|space-y)-(.+)$/;
     ARBITRARY_VALUE_RE2 = /^(-?\d+(?:\.\d+)?)(px|rem)$/;
     SKIP_VALUES = /* @__PURE__ */ new Set(["auto", "full", "screen", "min", "max", "fit", "none"]);
@@ -42437,6 +42690,78 @@ function extractStateBinding(node, lineOffsets) {
     setterReferenced: false
   };
 }
+function findUnreachableStatements(ast, source, lineOffsets) {
+  const out = [];
+  function isTerminator(node) {
+    if (node.type === "ReturnStatement") return "return";
+    if (node.type === "ThrowStatement") return "throw";
+    if (node.type === "BreakStatement") return "break";
+    if (node.type === "ContinueStatement") return "continue";
+    return null;
+  }
+  function snippetFor(node, src) {
+    const span = node.span;
+    if (!span || typeof span.start !== "number" || typeof span.end !== "number") {
+      return "<unreachable>";
+    }
+    const text = src.slice(span.start, Math.min(span.end, span.start + 60));
+    return text.replace(/\s+/g, " ").trim() || "<unreachable>";
+  }
+  function lineColumn(offset) {
+    let lo = 0;
+    let hi = lineOffsets.length - 1;
+    while (lo < hi) {
+      const mid = lo + hi + 1 >>> 1;
+      const midVal = lineOffsets[mid];
+      const loVal = lineOffsets[lo];
+      if (midVal === void 0) break;
+      if (midVal <= offset) lo = mid;
+      else hi = mid - 1;
+      void loVal;
+    }
+    const baseOffset = lineOffsets[lo] ?? 0;
+    return { line: lo + 1, column: offset - baseOffset };
+  }
+  function visitBody(body) {
+    if (!Array.isArray(body)) return;
+    let lastTerminator = null;
+    for (const stmt of body) {
+      if (!isObject(stmt)) continue;
+      if (lastTerminator && stmt.type !== "EmptyStatement") {
+        const span = stmt.span;
+        const offset = typeof span?.start === "number" ? span.start : 0;
+        const { line, column } = lineColumn(offset);
+        out.push({
+          terminator: lastTerminator,
+          line,
+          column,
+          snippet: snippetFor(stmt, source)
+        });
+      }
+      const t = isTerminator(stmt);
+      if (t) lastTerminator = t;
+    }
+  }
+  function walk3(node) {
+    if (!isObject(node)) return;
+    if (node.type === "BlockStatement") {
+      visitBody(node.stmts);
+    } else if (node.type === "Module") {
+      visitBody(node.body);
+    }
+    for (const key of Object.keys(node)) {
+      if (key === "parent" || key === "span" || key === "ctxt") continue;
+      const child = node[key];
+      if (Array.isArray(child)) {
+        for (const c of child) walk3(c);
+      } else {
+        walk3(child);
+      }
+    }
+  }
+  walk3(ast);
+  return out;
+}
 var init_scan_helpers = __esm({
   "src/engine/visitors/scan-helpers.ts"() {
     "use strict";
@@ -42522,15 +42847,42 @@ function handleImportDeclaration(node, _parent, _path, vctx) {
         if (specifier.type === "ImportDefaultSpecifier" || specifier.type === "ImportNamespaceSpecifier") {
           const local = specifier.local;
           if (isObject(local) && local.type === "Identifier" && typeof local.value === "string") {
-            importedNames.push(local.value);
+            const name = local.value;
+            importedNames.push(name);
+            vctx.facts.deadCode.bindings.push({
+              name,
+              kind: specifier.type === "ImportDefaultSpecifier" ? "import-default" : "import-namespace",
+              line,
+              column,
+              source,
+              isReferenced: false
+            });
           }
         } else if (specifier.type === "ImportSpecifier") {
           const imported = specifier.imported;
           const local = specifier.local;
           if (isObject(imported) && typeof imported.value === "string" && imported.value.length > 0) {
-            importedNames.push(imported.value);
+            const name = imported.value;
+            importedNames.push(name);
+            vctx.facts.deadCode.bindings.push({
+              name,
+              kind: "import-specifier",
+              line,
+              column,
+              source,
+              isReferenced: false
+            });
           } else if (isObject(local) && local.type === "Identifier" && typeof local.value === "string") {
-            importedNames.push(local.value);
+            const name = local.value;
+            importedNames.push(name);
+            vctx.facts.deadCode.bindings.push({
+              name,
+              kind: "import-specifier",
+              line,
+              column,
+              source,
+              isReferenced: false
+            });
           }
         }
       }
@@ -42620,6 +42972,13 @@ function isBindingSite(node, parent) {
       if (params.some((param) => containsNode(param, node))) return true;
     }
   }
+  if (parent.type === "ImportSpecifier" || parent.type === "ImportDefaultSpecifier" || parent.type === "ImportNamespaceSpecifier") {
+    if (parent.type === "ImportSpecifier") {
+      if (parent.imported === node || parent.local === node) return true;
+    } else {
+      if (parent.local === node) return true;
+    }
+  }
   return false;
 }
 function isNonComputedMemberProperty(node, parent) {
@@ -42686,6 +43045,9 @@ function handleIdentifier(node, parent, path, vctx) {
   if (typeof node.value === "string" && !isBindingSite(node, parent) && !isNonComputedMemberProperty(node, parent)) {
     markStateReference(node.value, vctx);
     trackPropUsage(node, parent, path, vctx);
+    vctx.facts.referencedNames.add(node.value);
+    const top = vctx.ctx.stack[vctx.ctx.stack.length - 1];
+    if (top) top.references.add(node.value);
   }
   return false;
 }
@@ -42826,6 +43188,20 @@ function handleVariableDeclarator(node, _parent, path, vctx) {
       frame.bindings.add(bindingName);
     }
   }
+  if (bindingNames.length > 0) {
+    const parent = node.parent;
+    const kind = isObject(parent) && parent.type === "VariableDeclaration" ? String(parent.kind ?? "var") : "var";
+    const { line, column } = positionFrom(id, vctx.lineOffsets);
+    for (const bindingName of bindingNames) {
+      vctx.facts.deadCode.bindings.push({
+        name: bindingName,
+        kind,
+        line,
+        column,
+        isReferenced: false
+      });
+    }
+  }
   if (isUseStateDeclarator(node)) {
     const binding = extractStateBinding(node, vctx.lineOffsets);
     if (binding) {
@@ -42845,6 +43221,36 @@ function handleVariableDeclarator(node, _parent, path, vctx) {
   }
   return true;
 }
+function handleIfStatement(node, _parent, _path, vctx) {
+  if (!isObject(node)) return false;
+  const test = node.test;
+  if (!isObject(test)) return false;
+  if (test.type === "BooleanLiteral" && typeof test.value === "boolean") {
+    const { line, column } = positionFrom(test, vctx.lineOffsets);
+    vctx.facts.deadCode.constantConditions.push({
+      kind: test.value ? "if-true" : "if-false",
+      condition: String(test.value),
+      line,
+      column
+    });
+  }
+  return false;
+}
+function handleWhileStatement(node, _parent, _path, vctx) {
+  if (!isObject(node)) return false;
+  const test = node.test;
+  if (!isObject(test)) return false;
+  if (test.type === "BooleanLiteral" && typeof test.value === "boolean") {
+    const { line, column } = positionFrom(test, vctx.lineOffsets);
+    vctx.facts.deadCode.constantConditions.push({
+      kind: test.value ? "while-true" : "while-false",
+      condition: String(test.value),
+      line,
+      column
+    });
+  }
+  return false;
+}
 function dispatchNode(node, parent, path, vctx) {
   if (!isObject(node)) return false;
   const type = getNodeType(node);
@@ -42869,7 +43275,9 @@ var init_dispatch = __esm({
       MemberExpression: handleMemberExpression,
       JSXAttribute: handleJSXAttribute,
       JSXOpeningElement: handleJSXOpeningElement,
-      VariableDeclarator: handleVariableDeclarator
+      VariableDeclarator: handleVariableDeclarator,
+      IfStatement: handleIfStatement,
+      WhileStatement: handleWhileStatement
     };
   }
 });
@@ -43020,6 +43428,17 @@ function buildV2Facts(facts, source, ext, framework, config, templateClassNames
     },
     logic: buildLogicBlock(facts),
     designTokens: scanDesignTokens(facts.staticClassNames),
+    //  dead-code detector. Copy the internal accumulator
+    //  into the v2 shape, marking each binding as referenced
+    //  iff the file-level referenced-name set contains its name.
+    deadCode: {
+      bindings: facts.deadCode.bindings.map((b) => ({
+        ...b,
+        isReferenced: facts.referencedNames.has(b.name)
+      })),
+      constantConditions: facts.deadCode.constantConditions,
+      unreachableStatements: facts.deadCode.unreachableStatements
+    },
     componentSizes: facts.componentSizes.map((cs) => ({
       name: cs.name,
       lineCount: cs.lineCount,
@@ -43101,7 +43520,17 @@ function extractFacts(filePath, ast, source, supportsRsc = true, framework = "re
     componentSizes: [],
     astroComponents: [],
     fetchCalls: [],
-    optimisticUpdates: []
+    optimisticUpdates: [],
+    //  dead-code detector. The visitor's identifier walk + import/
+    //  branch/return handlers populate these. The v2 builder at the
+    //  bottom of extractFacts() reads them and produces
+    //  `facts.v2.deadCode`.
+    deadCode: {
+      bindings: [],
+      constantConditions: [],
+      unreachableStatements: []
+    },
+    referencedNames: /* @__PURE__ */ new Set()
   };
   const ctx = {
     stack: [],
@@ -43188,6 +43617,16 @@ function extractFacts(filePath, ast, source, supportsRsc = true, framework = "re
             propBindingSet.add(bindingName);
           }
         }
+        const { line: pLine, column: pCol } = positionFrom(param, lineOffsets);
+        for (const bindingName of collectBindingNames2(param)) {
+          facts.deadCode.bindings.push({
+            name: bindingName,
+            kind: "parameter",
+            line: pLine,
+            column: pCol,
+            isReferenced: false
+          });
+        }
       }
     }
     ctx.stack.push({
@@ -43203,6 +43642,12 @@ function extractFacts(filePath, ast, source, supportsRsc = true, framework = "re
       propUsages: [],
       isComponent,
       bindings,
+      //  dead-code detector: per-frame referenced-name set.
+      //  Identifiers encountered inside the frame are added to this
+      //  set; the deadCode builder unions it with parent frames at
+      //  pop time so a binding is considered used if any reachable
+      //  scope references it.
+      references: /* @__PURE__ */ new Set(),
       propBindingSet,
       propUsageSet: /* @__PURE__ */ new Set(),
       node
@@ -43298,6 +43743,11 @@ function extractFacts(filePath, ast, source, supportsRsc = true, framework = "re
   mergeTemplateClassNames(filePath, source, facts, templateClassNames);
   const { ext } = splitFilePath(filePath);
   facts._source = source;
+  facts.deadCode.unreachableStatements = findUnreachableStatements(
+    ast,
+    source,
+    lineOffsets
+  );
   const v2 = buildV2Facts(facts, source, ext, framework, config, templateClassNames);
   return envelopeScanFacts(filePath, v2);
 }
@@ -43980,6 +44430,11 @@ var init_builtins = __esm({
     init_missing_not_null();
     init_naming_inconsistency();
     init_sql_concat();
+    init_dead_branch();
+    init_unreachable();
+    init_unused_import();
+    init_unused_local();
+    init_unused_parameter();
     init_broken_link();
     init_expired_code_example();
     init_stale_function_reference();
@@ -44076,6 +44531,11 @@ var init_builtins = __esm({
       missingNotNullRule,
       namingInconsistencyRule,
       sqlConcatRule,
+      deadBranchRule,
+      unreachableRule,
+      unusedImportRule,
+      unusedLocalRule,
+      unusedParameterRule,
       brokenLinkRule,
       expiredCodeExampleRule,
       staleFunctionReferenceRule,
@@ -44614,7 +45074,7 @@ var init_validation = __esm({
 // src/config/load.ts
 import { existsSync as existsSync10, readFileSync as readFileSync11 } from "fs";
 import { dirname as dirname7, extname as extname5, join as join11, resolve as resolve6 } from "path";
-import { createRequire as createRequire2 } from "module";
+import { createRequire } from "module";
 function deepMerge(target, source) {
   const out = { ...target };
   for (const key of Object.keys(source)) {
@@ -44650,8 +45110,8 @@ function detectJsLoader(configPath) {
     const pkgPath = join11(current, "package.json");
     if (existsSync10(pkgPath)) {
       try {
-        const pkg2 = JSON.parse(readFileSync11(pkgPath, "utf-8"));
-        return pkg2.type === "module" ? "import" : "require";
+        const pkg = JSON.parse(readFileSync11(pkgPath, "utf-8"));
+        return pkg.type === "module" ? "import" : "require";
       } catch {
         return "require";
       }
@@ -44665,7 +45125,7 @@ function detectJsLoader(configPath) {
 async function loadConfigFile(path) {
   const loader = detectJsLoader(path);
   if (loader === "require") {
-    const req = createRequire2(import.meta.url);
+    const req = createRequire(import.meta.url);
     const mod2 = req(path);
     return mod2.default ?? mod2;
   }
@@ -44846,7 +45306,7 @@ var init_init = __esm({
 });
 
 // src/config/index.ts
-var init_config = __esm({
+var init_config2 = __esm({
   "src/config/index.ts"() {
     "use strict";
     init_defaults();
@@ -46991,6 +47451,61 @@ var init_signal_strength = __esm({
         _calibrationNote: "v0.17.0 ship \u2014 not in v7 per-rule table. Default-off until calibration data lands. Backed by: OWASP Foundation (2021), *OWASP Top 10 \u2014 A03:2021 Injection*, https://owasp.org/Top10/A03_2021-Injection/; OWASP Foundation (2017), *SQL Injection Prevention Cheat Sheet*. (Template-literal SQL with ${...} interpolation is the #1 SQL injection vector in AI-generated TypeScript code.)",
         aiSpecific: true
       },
+      "dead/unused-import": {
+        recall: 0,
+        fpRate: 0,
+        ratio: 0,
+        precision: 0,
+        lastCalibratedAt: "2026-06-30T00:00:00Z",
+        verdict: "DORMANT",
+        defaultOff: true,
+        _calibrationNote: "v0.18.5 ship \u2014 not in v7 per-rule table. Default-off until v8 calibration data lands. The first of 5 planned `dead/*` rules (this one + dead/unused-local + dead/unused-parameter + dead/dead-branch + dead/unreachable). The pattern is the canonical AI-iteration rot: the model adds an import when introducing a feature, then rewrites the function later without cleaning up. Most real-world tsconfig.json files have `noUnusedLocals: false`, so tsc never fires.",
+        aiSpecific: true
+      },
+      "dead/unused-local": {
+        recall: 0,
+        fpRate: 0,
+        ratio: 0,
+        precision: 0,
+        lastCalibratedAt: "2026-06-30T00:00:00Z",
+        verdict: "DORMANT",
+        defaultOff: true,
+        _calibrationNote: "v0.18.5b ship \u2014 not in v7 per-rule table. Default-off until v8 calibration data lands. The second of 5 planned `dead/*` rules. Muchnick 1997 Ch. 13 'liveness analysis' (textbook compiler optimization).",
+        aiSpecific: true
+      },
+      "dead/unused-parameter": {
+        recall: 0,
+        fpRate: 0,
+        ratio: 0,
+        precision: 0,
+        lastCalibratedAt: "2026-06-30T00:00:00Z",
+        verdict: "DORMANT",
+        defaultOff: true,
+        _calibrationNote: "v0.18.5b ship \u2014 not in v7 per-rule table. Default-off until v8 calibration data lands. The third of 5 planned `dead/*` rules. AI agents add parameters when introducing features, then rewrite the function without removing parameters the new code does not need.",
+        aiSpecific: true
+      },
+      "dead/dead-branch": {
+        recall: 0,
+        fpRate: 0,
+        ratio: 0,
+        precision: 0,
+        lastCalibratedAt: "2026-06-30T00:00:00Z",
+        verdict: "DORMANT",
+        defaultOff: true,
+        _calibrationNote: "v0.18.5b ship \u2014 not in v7 per-rule table. Default-off until v8 calibration data lands. The fourth of 5 planned `dead/*` rules. AI-iteration signature: feature flag toggled to a constant, or wrapper from a previous refactor.",
+        aiSpecific: true
+      },
+      "dead/unreachable": {
+        recall: 0,
+        fpRate: 0,
+        ratio: 0,
+        precision: 0,
+        lastCalibratedAt: "2026-06-30T00:00:00Z",
+        verdict: "DORMANT",
+        defaultOff: true,
+        _calibrationNote: "v0.18.5b ship \u2014 not in v7 per-rule table. Default-off until v8 calibration data lands. The fifth of 5 planned `dead/*` rules. AI-iteration signature: model added an early return for a new error path, then forgot the rest of the function body was still sitting below it.",
+        aiSpecific: true
+      },
       "docs/stale-package-reference": {
         recall: 0,
         fpRate: 0,
@@ -47951,7 +48466,7 @@ var init_cache = __esm({
   "src/engine/cache.ts"() {
     "use strict";
     init_types();
-    init_config();
+    init_config2();
     BASELINE_VERSION = VERSION;
     BASELINE_HASH_KEYS = /* @__PURE__ */ new Set([
       "framework",
@@ -50442,7 +50957,7 @@ var init_finalizeReport = __esm({
     init_dist2();
     init_logger();
     init_memory_io();
-    init_config();
+    init_config2();
     init_enrichReport();
     init_assembleScanReport();
     init_persistRun();
@@ -52366,11 +52881,11 @@ var init_watch = __esm({
     init_worker();
     init_threshold();
     init_cache();
-    init_config();
+    init_config2();
     init_render();
     init_logger();
     init_error();
-    init_scan();
+    init_scan2();
     init_renderOutput();
     init_types();
   }
@@ -52652,12 +53167,12 @@ async function scanProject(options) {
   const { report } = await runScan({ ...options, workspace: options.cwd });
   return report;
 }
-var init_scan = __esm({
+var init_scan2 = __esm({
   "src/cli/scan.ts"() {
     "use strict";
     init_render();
     init_threshold();
-    init_config();
+    init_config2();
     init_discover();
     init_git();
     init_cache_incremental();
@@ -52829,7 +53344,7 @@ async function runSuggest(args, ctx) {
 }
 async function runGovernance(args, ctx) {
   try {
-    const { runScan: runScan3 } = await Promise.resolve().then(() => (init_scan(), scan_exports));
+    const { runScan: runScan3 } = await Promise.resolve().then(() => (init_scan2(), scan_exports));
     const maxFiles = typeof args.maxFiles === "number" && Number.isFinite(args.maxFiles) && args.maxFiles > 0 ? Math.floor(args.maxFiles) : 500;
     const { report } = await runScan3({
       workspace: ctx.cwd,
@@ -53229,7 +53744,7 @@ var init_tools = __esm({
 
 // src/index.ts
 init_types();
-init_config();
+init_config2();
 init_dist2();
 
 // src/cli/program.ts
@@ -53273,11 +53788,11 @@ function parseThreshold(value) {
 // src/cli/program.ts
 init_render();
 init_threshold();
-init_scan();
-init_scan();
+init_scan2();
+init_scan2();
 
 // src/cli/init.ts
-init_config();
+init_config2();
 init_discover();
 init_git();
 init_cache();
@@ -53769,7 +54284,7 @@ async function runDoctor(cwd) {
 // src/cli/commands/badge.ts
 init_render();
 init_logger();
-init_scan();
+init_scan2();
 import { resolve as resolve13 } from "path";
 function registerBadge(program) {
   program.command("badge").description(
@@ -53796,7 +54311,7 @@ function registerBadge(program) {
 init_advice();
 init_unified_diff();
 init_logger();
-init_scan();
+init_scan2();
 import { resolve as resolve14 } from "path";
 function registerSuggest(program) {
   program.command("suggest").description("print remediation advice").action(async (_cmdOptions, command) => {
@@ -53924,6 +54439,11 @@ var RULE_HINTS = {
   "logic/qwik-hook-leak": "Use Qwik primitives ($state, $effect, useSignal) instead of React hooks (useState, useEffect).",
   "logic/reactive-hook-soup": "Coordinate state via a single derived value (useMemo) or a state machine. Avoid chained useEffects that sync local state.",
   "logic/zombie-state": "Remove unused useState or wire it into the component. Don't leave declared-but-never-read state bindings.",
+  "dead/unused-import": "Remove the import or use the symbol somewhere. Unused imports are the most common AI-iteration signature \u2014 the model added it for a feature, then rewrote the function without cleaning up.",
+  "dead/unused-local": "Remove the declaration or use the variable. AI-iteration signature: the model declared a binding for a feature, then rewrote the function without cleaning up.",
+  "dead/unused-parameter": "Remove the parameter (and update every call site) or use it in the function body. AI-iteration signature: the model added a parameter for a feature, then rewrote the function without removing parameters the new code does not need.",
+  "dead/dead-branch": "Replace the literal boolean with a real condition, or remove the dead branch. AI-iteration signature: a feature flag toggled to a constant, or a wrapper from a previous refactor that was never cleaned up.",
+  "dead/unreachable": "Remove this statement \u2014 code after a return/throw/break/continue is unreachable. AI-iteration signature: the model added an early return for a new error path, then forgot the rest of the function body was still sitting below it.",
   "perf/cls-image": "Add width/height attributes or an aspect-ratio utility to prevent layout shift.",
   "perf/css-bloat": "Extract to a CSS variable (`--surface-card`) or a component prop when a class string repeats 5+ times.",
   "perf/halstead-anomaly": "Introduce domain-specific identifiers and varied operations. Low vocabulary per line is a strong AI signature (Halstead 1977 \xA73).",
@@ -54184,7 +54704,7 @@ init_logger();
 
 // src/mcp/server.ts
 init_builtins();
-init_config();
+init_config2();
 init_tools();
 var SERVER_INFO = {
   name: "slopbrick",
@@ -55613,7 +56133,7 @@ function registerTrend(program) {
 
 // src/cli/commands/drift.ts
 init_logger();
-init_scan();
+init_scan2();
 import { resolve as resolve26 } from "path";
 
 // src/cli/drift.ts
@@ -55754,7 +56274,7 @@ function registerDrift(program) {
 
 // src/cli/commands/pr.ts
 init_logger();
-init_scan();
+init_scan2();
 import { resolve as resolve28 } from "path";
 
 // src/cli/pr.ts
@@ -56043,7 +56563,7 @@ function registerPr(program) {
 
 // src/cli/commands/security.ts
 init_logger();
-init_scan();
+init_scan2();
 init_ai_security_risk();
 import { resolve as resolve29 } from "path";
 function registerSecurity(program) {
@@ -56102,11 +56622,11 @@ function registerSecurity(program) {
 
 // src/cli/commands/test.ts
 init_logger();
-init_scan();
+init_scan2();
 import { resolve as resolve31 } from "path";
 
 // src/cli/test.ts
-init_scan();
+init_scan2();
 init_test_quality();
 init_logger();
 import { resolve as resolve30 } from "path";
@@ -56221,7 +56741,7 @@ function registerTest(program) {
 
 // src/cli/commands/architecture.ts
 init_logger();
-init_scan();
+init_scan2();
 init_architecture_score();
 import { resolve as resolve32 } from "path";
 function registerArchitecture(program) {
@@ -56249,7 +56769,7 @@ function registerArchitecture(program) {
 
 // src/cli/commands/business-logic.ts
 init_logger();
-init_scan();
+init_scan2();
 import { resolve as resolve33 } from "path";
 
 // src/cli/business-logic.ts
@@ -56395,11 +56915,11 @@ function registerBusinessLogic(program) {
 
 // src/cli/commands/maintenance-cost.ts
 init_logger();
-init_scan();
+init_scan2();
 import { resolve as resolve34 } from "path";
 
 // src/cli/maintenance-cost.ts
-init_scan();
+init_scan2();
 init_maintenance_cost();
 init_logger();
 async function runMaintenanceCostScan(cwd, config, options = {}) {
@@ -56538,11 +57058,11 @@ function registerMaintenanceCost(program) {
 
 // src/cli/commands/docs.ts
 init_logger();
-init_scan();
+init_scan2();
 import { resolve as resolve35 } from "path";
 
 // src/cli/docs.ts
-init_scan();
+init_scan2();
 init_doc_freshness();
 init_logger();
 async function runDocsScan(cwd, config, options = {}) {
@@ -56687,11 +57207,11 @@ function registerDocs(program) {
 
 // src/cli/commands/db.ts
 init_logger();
-init_scan();
+init_scan2();
 import { resolve as resolve36 } from "path";
 
 // src/cli/db.ts
-init_scan();
+init_scan2();
 init_db_health();
 init_logger();
 async function runDbScan(cwd, config, options = {}) {
@@ -56830,7 +57350,7 @@ function registerDb(program) {
 
 // src/cli/commands/patterns.ts
 init_logger();
-init_scan();
+init_scan2();
 import { resolve as resolve37 } from "path";
 
 // src/engine/patterns.ts
@@ -57178,7 +57698,7 @@ function registerPatterns(program) {
 
 // src/cli/commands/research.ts
 init_logger();
-init_config();
+init_config2();
 import { existsSync as existsSync27, mkdirSync as mkdirSync14, readFileSync as readFileSync34, writeFileSync as writeFileSync17 } from "fs";
 import { dirname as dirname18, resolve as resolve38 } from "path";
 function registerResearch(program) {
@@ -57261,8 +57781,8 @@ init_logger();
 init_builtins();
 import { existsSync as existsSync28, mkdirSync as mkdirSync15, readFileSync as readFileSync35, writeFileSync as writeFileSync18 } from "fs";
 import { dirname as dirname19, join as join29, resolve as resolve39 } from "path";
-init_scan();
-init_config();
+init_scan2();
+init_config2();
 init_threshold();
 init_git();
 init_cache();
@@ -57743,7 +58263,7 @@ function registerScan(program, scanAction) {
 }
 
 // src/cli/program.ts
-init_config();
+init_config2();
 init_git();
 init_logger();
 init_unified_diff();
@@ -58176,7 +58696,140 @@ async function applyFixes(report, config, scannedFiles) {
 // src/cli/program.ts
 init_cache();
 init_types();
-init_scan();
+
+// src/cli/help.ts
+var CATEGORY_LABELS3 = {
+  file: "File selection",
+  filter: "Filter",
+  output: "Output & display",
+  perf: "Performance",
+  fix: "Auto-fix",
+  ci: "CI / threshold",
+  watch: "Watch & diagnose",
+  tokens: "Tokens",
+  telemetry: "Telemetry",
+  other: "Other"
+};
+var OPTION_CATEGORY = {
+  // File selection
+  "--include": "file",
+  "--exclude": "file",
+  "--since": "file",
+  "--diff": "file",
+  "--staged": "file",
+  "--changed": "file",
+  "--workspace": "file",
+  // Filter
+  "--ai-only": "filter",
+  "--human-only": "filter",
+  "--security-only": "filter",
+  "--ignore-wcag22": "filter",
+  "--framework": "filter",
+  // Output & display
+  "--format": "output",
+  "--brief": "output",
+  "--full": "output",
+  "--json": "output",
+  "--html": "output",
+  "--no-color": "output",
+  "--quiet": "output",
+  "--verbose": "output",
+  "--heatmap": "output",
+  "--trend": "output",
+  "--why-failing": "output",
+  // Performance
+  "--threads": "perf",
+  "--incremental": "perf",
+  "--cache": "perf",
+  "--cache-path": "perf",
+  // Auto-fix
+  "--fix": "fix",
+  "--dry-run": "fix",
+  "--show-fixes-diff": "fix",
+  // CI / threshold
+  "--strict": "ci",
+  "--no-increase": "ci",
+  "--baseline": "ci",
+  "--threshold": "ci",
+  // Watch & diagnose
+  "--watch": "watch",
+  "--doctor": "watch",
+  "--suggest": "watch",
+  "--tighten": "watch",
+  // Tokens
+  "--tokens": "tokens",
+  // Telemetry
+  "--no-telemetry": "telemetry"
+};
+var CATEGORY_ORDER2 = [
+  "file",
+  "filter",
+  "output",
+  "perf",
+  "fix",
+  "ci",
+  "watch",
+  "tokens",
+  "telemetry",
+  "other"
+];
+function groupOptions(cmd) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const category of CATEGORY_ORDER2) {
+    grouped.set(category, []);
+  }
+  for (const opt of cmd.options) {
+    if (opt.hidden) continue;
+    const longFlag = opt.long ?? opt.short ?? "";
+    const category = longFlag ? OPTION_CATEGORY[longFlag] ?? "other" : "other";
+    grouped.get(category).push({
+      category,
+      flags: opt.flags,
+      description: opt.description ?? ""
+    });
+  }
+  return grouped;
+}
+function renderOption(opt, flagWidth) {
+  const padded = opt.flags.padEnd(flagWidth, " ");
+  return `  ${padded}  ${opt.description}`;
+}
+function formatGroupedHelp(cmd) {
+  const lines = [];
+  const usage = cmd.usage ? cmd.usage() : `Usage: ${cmd.name()} [options]`;
+  lines.push(usage);
+  lines.push("");
+  if (cmd.description()) {
+    lines.push(cmd.description());
+    lines.push("");
+  }
+  const grouped = groupOptions(cmd);
+  let flagWidth = 0;
+  for (const options of grouped.values()) {
+    for (const opt of options) {
+      if (opt.flags.length > flagWidth) flagWidth = opt.flags.length;
+    }
+  }
+  let firstCategory = true;
+  for (const category of CATEGORY_ORDER2) {
+    const options = grouped.get(category);
+    if (options.length === 0) continue;
+    if (!firstCategory) lines.push("");
+    firstCategory = false;
+    lines.push(`  ${CATEGORY_LABELS3[category]}:`);
+    for (const opt of options) {
+      lines.push(renderOption(opt, flagWidth));
+    }
+  }
+  lines.push("");
+  lines.push(
+    "Use `--help-flat` for the standard un-grouped list. See `https://usebrick.dev/docs/scan-options` for full docs."
+  );
+  return lines.join("\n");
+}
+
+// src/cli/program.ts
+init_scan2();
 process.on("uncaughtException", (err) => {
   logger.error(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
   process.exit(3);
@@ -58184,6 +58837,7 @@ process.on("uncaughtException", (err) => {
 async function runCli({ start }) {
   try {
     const program = new Command().name("slopbrick").description("Repository Coherence Scanner \u2014 surface AI-induced pattern drift, secret leaks, and design-token violations").version(VERSION).option("--framework <name>", "framework multiplier to apply").option("--include <glob>", "include pattern (repeatable)", collectGlob, []).option("--exclude <glob>", "exclude pattern (repeatable)", collectGlob, []).option("--ai-only", "only report AI-specific issues").option("--human-only", "only report human-facing issues").option("--ignore-wcag22", "ignore WCAG 2.2 related issues").option("--format <pretty|json|sarif|html>", "output format", "pretty").option("--threads <n>", "number of worker threads", parseThreads).option("--since <ref>", "only scan files changed since git ref").option("--diff <ref>", "alias for --since <ref>; also adds PR Slop Score to the report").option("--workspace <path>", "workspace/project path", process.cwd()).option("--tighten", "tighten baseline allowances").option("--fix", "apply auto-fixes").option("--dry-run", "with --fix: print what would change without writing").option("--show-fixes-diff", "print unified diff of proposed auto-fixes").option("--doctor", "run diagnostics").option("--watch", "watch files and re-run").option("--suggest", "print remediation advice").option("--why-failing", "print the top 5 rules dragging the score down").option("--brief", "terse output (verdict + headline + threshold + delta only)").option("--heatmap", "print migration ROI heatmap").option("--quiet", "suppress non-error output").option("--verbose", "enable debug logging (file paths, timings, rule-fire counts)").option("--strict", "exit 2 if any high-severity issue remains").option("--no-increase", "exit 2 if slop index increased since last run").option("--baseline", "save a baseline after this scan").option("--trend [n]", "print a sparkline of the last n runs", parseTrend).option("--json [path]", "write JSON report to path or stdout").option("--html [path]", "write HTML report to path or stdout").option("--staged", "scan only changed files (staged and unstaged)").option("--changed", "scan working-tree changes (staged + unstaged + untracked)").option("--incremental", "skip unchanged files using the persisted hash cache").option("--cache-path <path>", "path to the incremental-scan cache (default: .slopbrick-cache.json)").option("--tokens <path>", "merge tokens.json layout values into the arbitrary-value allowlist").option("--cache", "cache parsed AST results locally").option("--no-color", "suppress ANSI color codes in output").option("--security-only", "run only the security/* rules").option("--full", "show the complete report (all issues, all categories)");
+    program.helpInformation = () => formatGroupedHelp(program);
     registerInit(program);
     registerInstall(program);
     registerUninstall(program);
@@ -58347,6 +59001,11 @@ async function runCli({ start }) {
     registerTokens(program);
     registerReport(program);
     registerScan(program, scanAction);
+    if (process.argv.includes("--help-flat")) {
+      delete program.helpInformation;
+      program.outputHelp();
+      process.exit(0);
+    }
     await program.parseAsync(process.argv);
   } catch (err) {
     if (err instanceof ConfigValidationError) {