slopbrick 0.18.3 → 0.18.5

package/dist/index.cjs

@@ -31,15 +31,41 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/types.ts
-var import_node_module, 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";
-    import_node_module = require("module");
-    require2 = (0, import_node_module.createRequire)(__importMetaUrl);
-    pkg = require2("../package.json");
-    VERSION = pkg.version;
     AI_SECURITY_NUMERIC = {
       low: 100,
       medium: 75,
@@ -59,6 +85,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({
@@ -310,9 +364,9 @@ function findWorkspacePackages(cwd) {
   const pkgPath = (0, import_node_path.join)(root, "package.json");
   if ((0, import_node_fs.existsSync)(pkgPath)) {
     try {
-      const pkg2 = JSON.parse((0, import_node_fs.readFileSync)(pkgPath, "utf-8"));
-      if (Array.isArray(pkg2.workspaces)) {
-        for (const pattern of pkg2.workspaces) {
+      const pkg = JSON.parse((0, import_node_fs.readFileSync)(pkgPath, "utf-8"));
+      if (Array.isArray(pkg.workspaces)) {
+        for (const pattern of pkg.workspaces) {
           packages.push(...expandWorkspacePattern(root, pattern));
         }
       }
@@ -370,11 +424,11 @@ function detectStylingSolution(cwd) {
   let deps = {};
   if ((0, import_node_fs2.existsSync)(pkgPath)) {
     try {
-      const pkg2 = JSON.parse((0, import_node_fs2.readFileSync)(pkgPath, "utf-8"));
+      const pkg = JSON.parse((0, import_node_fs2.readFileSync)(pkgPath, "utf-8"));
       deps = {
-        ...pkg2.dependencies,
-        ...pkg2.devDependencies,
-        ...pkg2.peerDependencies
+        ...pkg.dependencies,
+        ...pkg.devDependencies,
+        ...pkg.peerDependencies
       };
     } catch {
     }
@@ -573,11 +627,11 @@ function detectStack(cwd) {
     return {};
   }
   try {
-    const pkg2 = JSON.parse((0, import_node_fs3.readFileSync)(pkgPath, "utf-8"));
+    const pkg = JSON.parse((0, import_node_fs3.readFileSync)(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 = {};
@@ -26213,13 +26267,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 [];
@@ -28109,6 +28163,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, {
@@ -28218,14 +28471,14 @@ var init_discover = __esm({
 function readDeps(cwd) {
   const pkgPath = (0, import_node_path5.join)(cwd, "package.json");
   if (!(0, import_node_fs5.existsSync)(pkgPath)) return /* @__PURE__ */ new Set();
-  let pkg2;
+  let pkg;
   try {
-    pkg2 = JSON.parse((0, import_node_fs5.readFileSync)(pkgPath, "utf-8"));
+    pkg = JSON.parse((0, import_node_fs5.readFileSync)(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);
     }
@@ -28241,8 +28494,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
@@ -29935,9 +30188,9 @@ function declaredPackages(cwd) {
   if (!(0, import_node_fs8.existsSync)(pkgPath)) return out;
   try {
     const raw = (0, import_node_fs8.readFileSync)(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);
@@ -30367,7 +30620,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"]);
@@ -42455,6 +42708,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";
@@ -42540,15 +42865,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
+            });
           }
         }
       }
@@ -42638,6 +42990,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) {
@@ -42704,6 +43063,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;
 }
@@ -42844,6 +43206,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) {
@@ -42863,6 +43239,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);
@@ -42887,7 +43293,9 @@ var init_dispatch = __esm({
       MemberExpression: handleMemberExpression,
       JSXAttribute: handleJSXAttribute,
       JSXOpeningElement: handleJSXOpeningElement,
-      VariableDeclarator: handleVariableDeclarator
+      VariableDeclarator: handleVariableDeclarator,
+      IfStatement: handleIfStatement,
+      WhileStatement: handleWhileStatement
     };
   }
 });
@@ -43038,6 +43446,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,
@@ -43119,7 +43538,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: [],
@@ -43206,6 +43635,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({
@@ -43221,6 +43660,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
@@ -43316,6 +43761,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);
 }
@@ -43998,6 +44448,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();
@@ -44094,6 +44549,11 @@ var init_builtins = __esm({
       missingNotNullRule,
       namingInconsistencyRule,
       sqlConcatRule,
+      deadBranchRule,
+      unreachableRule,
+      unusedImportRule,
+      unusedLocalRule,
+      unusedParameterRule,
       brokenLinkRule,
       expiredCodeExampleRule,
       staleFunctionReferenceRule,
@@ -44665,8 +45125,8 @@ function detectJsLoader(configPath) {
     const pkgPath = (0, import_node_path10.join)(current, "package.json");
     if ((0, import_node_fs11.existsSync)(pkgPath)) {
       try {
-        const pkg2 = JSON.parse((0, import_node_fs11.readFileSync)(pkgPath, "utf-8"));
-        return pkg2.type === "module" ? "import" : "require";
+        const pkg = JSON.parse((0, import_node_fs11.readFileSync)(pkgPath, "utf-8"));
+        return pkg.type === "module" ? "import" : "require";
       } catch {
         return "require";
       }
@@ -44680,7 +45140,7 @@ function detectJsLoader(configPath) {
 async function loadConfigFile(path) {
   const loader = detectJsLoader(path);
   if (loader === "require") {
-    const req = (0, import_node_module2.createRequire)(__importMetaUrl);
+    const req = (0, import_node_module.createRequire)(__importMetaUrl);
     const mod2 = req(path);
     return mod2.default ?? mod2;
   }
@@ -44712,13 +45172,13 @@ async function loadConfig(cwd) {
   );
   return merged;
 }
-var import_node_fs11, import_node_path10, import_node_module2;
+var import_node_fs11, import_node_path10, import_node_module;
 var init_load = __esm({
   "src/config/load.ts"() {
     "use strict";
     import_node_fs11 = require("fs");
     import_node_path10 = require("path");
-    import_node_module2 = require("module");
+    import_node_module = require("module");
     init_logger();
     init_validation();
     init_defaults();
@@ -44865,7 +45325,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();
@@ -47012,6 +47472,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,
@@ -47973,7 +48488,7 @@ var init_cache = __esm({
     import_node_fs16 = require("fs");
     import_node_path17 = require("path");
     init_types();
-    init_config();
+    init_config2();
     BASELINE_VERSION = VERSION;
     BASELINE_HASH_KEYS = /* @__PURE__ */ new Set([
       "framework",
@@ -50457,7 +50972,7 @@ var init_finalizeReport = __esm({
     init_dist2();
     init_logger();
     init_memory_io();
-    init_config();
+    init_config2();
     init_enrichReport();
     init_assembleScanReport();
     init_persistRun();
@@ -52382,11 +52897,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();
   }
@@ -52667,14 +53182,14 @@ async function scanProject(options) {
   return report;
 }
 var import_node_fs28, import_node_path30;
-var init_scan = __esm({
+var init_scan2 = __esm({
   "src/cli/scan.ts"() {
     "use strict";
     import_node_fs28 = require("fs");
     import_node_path30 = require("path");
     init_render();
     init_threshold();
-    init_config();
+    init_config2();
     init_discover();
     init_git();
     init_cache_incremental();
@@ -52844,7 +53359,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,
@@ -53326,7 +53841,7 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 init_types();
-init_config();
+init_config2();
 init_dist2();
 
 // src/cli/program.ts
@@ -53370,14 +53885,14 @@ function parseThreshold(value) {
 // src/cli/program.ts
 init_render();
 init_threshold();
-init_scan();
-init_scan();
+init_scan2();
+init_scan2();
 
 // src/cli/init.ts
 var import_node_fs30 = require("fs");
 var import_node_path32 = require("path");
 var import_node_readline = require("readline");
-init_config();
+init_config2();
 init_discover();
 init_git();
 init_cache();
@@ -53867,7 +54382,7 @@ async function runDoctor(cwd) {
 var import_node_path33 = require("path");
 init_render();
 init_logger();
-init_scan();
+init_scan2();
 function registerBadge(program) {
   program.command("badge").description(
     "print a shields.io slop-index badge. Reads .slopbrick/health.json if present (no re-scan); falls back to a fresh scan."
@@ -53894,7 +54409,7 @@ var import_node_path34 = require("path");
 init_advice();
 init_unified_diff();
 init_logger();
-init_scan();
+init_scan2();
 function registerSuggest(program) {
   program.command("suggest").description("print remediation advice").action(async (_cmdOptions, command) => {
     const options = command.optsWithGlobals();
@@ -54021,6 +54536,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).",
@@ -54275,7 +54795,7 @@ init_logger();
 
 // src/mcp/server.ts
 init_builtins();
-init_config();
+init_config2();
 init_tools();
 var SERVER_INFO = {
   name: "slopbrick",
@@ -55705,7 +56225,7 @@ function registerTrend(program) {
 // src/cli/commands/drift.ts
 var import_node_path51 = require("path");
 init_logger();
-init_scan();
+init_scan2();
 
 // src/cli/drift.ts
 var import_node_fs38 = require("fs");
@@ -55846,7 +56366,7 @@ function registerDrift(program) {
 // src/cli/commands/pr.ts
 var import_node_path53 = require("path");
 init_logger();
-init_scan();
+init_scan2();
 
 // src/cli/pr.ts
 var import_node_fs39 = require("fs");
@@ -56135,7 +56655,7 @@ function registerPr(program) {
 // src/cli/commands/security.ts
 var import_node_path54 = require("path");
 init_logger();
-init_scan();
+init_scan2();
 init_ai_security_risk();
 function registerSecurity(program) {
   program.command("security").description(
@@ -56194,11 +56714,11 @@ function registerSecurity(program) {
 // src/cli/commands/test.ts
 var import_node_path56 = require("path");
 init_logger();
-init_scan();
+init_scan2();
 
 // src/cli/test.ts
 var import_node_path55 = require("path");
-init_scan();
+init_scan2();
 init_test_quality();
 init_logger();
 var TEST_INCLUDE_GLOBS = [
@@ -56313,7 +56833,7 @@ function registerTest(program) {
 // src/cli/commands/architecture.ts
 var import_node_path57 = require("path");
 init_logger();
-init_scan();
+init_scan2();
 init_architecture_score();
 function registerArchitecture(program) {
   program.command("architecture").description(
@@ -56341,7 +56861,7 @@ function registerArchitecture(program) {
 // src/cli/commands/business-logic.ts
 var import_node_path59 = require("path");
 init_logger();
-init_scan();
+init_scan2();
 
 // src/cli/business-logic.ts
 var import_node_fs40 = require("fs");
@@ -56487,10 +57007,10 @@ function registerBusinessLogic(program) {
 // src/cli/commands/maintenance-cost.ts
 var import_node_path60 = require("path");
 init_logger();
-init_scan();
+init_scan2();
 
 // src/cli/maintenance-cost.ts
-init_scan();
+init_scan2();
 init_maintenance_cost();
 init_logger();
 async function runMaintenanceCostScan(cwd, config, options = {}) {
@@ -56630,10 +57150,10 @@ function registerMaintenanceCost(program) {
 // src/cli/commands/docs.ts
 var import_node_path61 = require("path");
 init_logger();
-init_scan();
+init_scan2();
 
 // src/cli/docs.ts
-init_scan();
+init_scan2();
 init_doc_freshness();
 init_logger();
 async function runDocsScan(cwd, config, options = {}) {
@@ -56779,10 +57299,10 @@ function registerDocs(program) {
 // src/cli/commands/db.ts
 var import_node_path62 = require("path");
 init_logger();
-init_scan();
+init_scan2();
 
 // src/cli/db.ts
-init_scan();
+init_scan2();
 init_db_health();
 init_logger();
 async function runDbScan(cwd, config, options = {}) {
@@ -56922,7 +57442,7 @@ function registerDb(program) {
 // src/cli/commands/patterns.ts
 var import_node_path64 = require("path");
 init_logger();
-init_scan();
+init_scan2();
 
 // src/engine/patterns.ts
 var import_node_fs41 = require("fs");
@@ -57271,7 +57791,7 @@ function registerPatterns(program) {
 var import_node_fs42 = require("fs");
 var import_node_path65 = require("path");
 init_logger();
-init_config();
+init_config2();
 function registerResearch(program) {
   const research = program.command("research").description("research commands for the AI UI learning loop");
   research.command("generate").description("generate synthetic UI samples").requiredOption("--count <n>", "number of samples", parseCount).requiredOption("--framework <name>", "target framework").requiredOption("--component-type <type>", "component type").requiredOption("--provider <name>", "AI provider (openai)").option("--api-key <key>", "API key for provider").option("--model <name>", "model name").option("--temperature <n>", "sampling temperature", parseFloat, 0.7).option("--output-dir <path>", "output directory", ".slopbrick/corpus/generated").action(async (cmdOptions) => {
@@ -57352,8 +57872,8 @@ var import_node_fs43 = require("fs");
 var import_node_path67 = require("path");
 init_logger();
 init_builtins();
-init_scan();
-init_config();
+init_scan2();
+init_config2();
 init_threshold();
 init_git();
 init_cache();
@@ -57834,7 +58354,7 @@ function registerScan(program, scanAction) {
 }
 
 // src/cli/program.ts
-init_config();
+init_config2();
 init_git();
 init_logger();
 init_unified_diff();
@@ -58267,7 +58787,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);
@@ -58275,6 +58928,7 @@ process.on("uncaughtException", (err) => {
 async function runCli({ start }) {
   try {
     const program = new import_commander2.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);
@@ -58438,6 +59092,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) {