slopbrick 0.20.0 → 0.21.1

package/README.md

@@ -46,7 +46,7 @@ on every scan — your repository, encoded for the next agent.
   lib, modal system, API client) once. The agent and the linter
   enforce it together.
 
-**Status:** v0.17.0 (current). See the [CHANGELOG](./CHANGELOG.md) for
+**Status:** v0.21.0 (current). See the [CHANGELOG](./CHANGELOG.md) for
 the full release notes.
 
 ---
@@ -76,21 +76,25 @@ For every other config question, see [`EXAMPLES.md`](./EXAMPLES.md).
 
 ---
 
-## The headlines (4-score model, v0.17.0+)
+## The headlines (4-score model, v0.21.0+)
 
-> **v0.15.0 introduced the 4-score model; v0.16.0 + v0.17.0 completed it.**
-> The single `Slop Index` is replaced by **4 independent scores**
-> (all 0-100, **higher = better**). The legacy `slopIndex` field
-> is kept as optional on `ProjectReport` for backward compat with
+> **v0.15.0 introduced the 4-score model; v0.21.0 FLIPPED `aiSlopScore`
+> to the natural-reading "raw amount" direction (0=clean, 100=saturated).**
+> The other three scores stay "higher = better". The legacy `slopIndex`
+> field is kept as optional on `ProjectReport` for backward compat with
 > existing test fixtures and historical telemetry; the v0.14-compat
 > removal is tracked separately.
 
-| Score | What it measures | CI gate? |
-|-------|------------------|----------|
-| **`aiQuality`** | AI-slop signatures (16 `ai/*` rules). INVERTED from legacy Slop Index. | **Yes** (≥ 70 passes) |
-| **`engineeringHygiene`** | Average of 6 category scores: arch, logic, layout, visual, component, test | No (informational) |
-| **`security`** | AI Security Risk band: low=100, medium=67, high=33, critical=0 | No (informational) |
-| **`repositoryHealth`** (composite) | Weighted: 0.4×aiQ + 0.3×eng + 0.2×sec + 0.1×test | No (informational) |
+| Score | What it measures | Direction | CI gate? |
+|-------|------------------|-----------|----------|
+| **`aiSlopScore`** | AI-slop signatures (16 `ai/*` rules). | **lower = cleaner** (raw amount) | **Yes** (`≤ meanSlop: 30` passes) |
+| **`engineeringHygiene`** | Average of 6 category scores: arch, logic, layout, visual, component, test | higher = better | No (informational) |
+| **`security`** | AI Security Risk band: low=100, medium=67, high=33, critical=0 | higher = better | No (informational) |
+| **`repositoryHealth`** (composite) | Weighted: `0.4 × (100 − aiSlopScore) + 0.3 × eng + 0.2 × sec + 0.1 × test` | higher = better (inverts `aiSlopScore` internally) | No (informational) |
+
+**Score-band messages** (v0.21.0+): every score ships with a one-line
+verdict in the pretty output — e.g. `AI Slop Score: 25 → "low amount
+of slop"`, `Security Risk: 33 → "high risk"`. See `src/report/pretty.ts`.
 
 The same numbers are in `.slopbrick/health.json`.
 
@@ -108,13 +112,13 @@ For per-rule precision/recall/FPR (auditable), see
 $ npx slopbrick scan
 Repo is concerning (25/100). The biggest problem is AI patterns — worst file is src/cli/scan.ts. Run `slopbrick scan --why-failing` for the top 5 rules, or `slopbrick scan --suggest` for fixes.
 
-AI Quality:  25 / 100 [CONCERNING]  ↑5 (worse)
+AI Slop Score:  25 / 100 [HIGH]  ↑5 (worse)
 higher = better · measures AI-slop signatures. The same number in .slopbrick/health.json.
   ├─ boundary:  10  (40%)  — structural integrity
   ├─ context:   50  (35%)  — props / state / imports
   └─ visual:     5  (25%)  — CSS / a11y / layout
 
-Engineering Hygiene:  60 / 100 [NEEDS WORK] — higher = better · measures internal consistency. This is a secondary view; the AI Quality above is the gate.
+Engineering Hygiene:  60 / 100 [NEEDS WORK] — higher = better · measures internal consistency. This is a secondary view; the AI Slop Score above is the gate.
 
 Other signals (not the gate):
   Code Hygiene          75/100

package/dist/engine/worker.cjs

@@ -6424,6 +6424,7 @@ function handleImportDeclaration(node, _parent, _path, vctx) {
   if (source) {
     const { line, column } = positionFrom(node, vctx.lineOffsets);
     const importedNames = [];
+    const isTypeOnly = node.typeOnly === true;
     const specifiers = node.specifiers;
     if (Array.isArray(specifiers)) {
       for (const specifier of specifiers) {
@@ -6439,7 +6440,8 @@ function handleImportDeclaration(node, _parent, _path, vctx) {
               line,
               column,
               source,
-              isReferenced: false
+              isReferenced: false,
+              isTypeOnly
             });
           }
         } else if (specifier.type === "ImportSpecifier") {
@@ -6454,7 +6456,8 @@ function handleImportDeclaration(node, _parent, _path, vctx) {
               line,
               column,
               source,
-              isReferenced: false
+              isReferenced: false,
+              isTypeOnly
             });
           } else if (isObject(local) && local.type === "Identifier" && typeof local.value === "string") {
             const name = local.value;
@@ -6465,7 +6468,8 @@ function handleImportDeclaration(node, _parent, _path, vctx) {
               line,
               column,
               source,
-              isReferenced: false
+              isReferenced: false,
+              isTypeOnly
             });
           }
         }
@@ -6758,7 +6762,7 @@ function handleJSXOpeningElement(node, _parent, _path, vctx) {
   }
   return false;
 }
-function handleVariableDeclarator(node, _parent, path, vctx) {
+function handleVariableDeclarator(node, parent, path, vctx) {
   if (!isObject(node)) return false;
   const init = node.init;
   if (init && vctx.visit) {
@@ -6773,16 +6777,18 @@ function handleVariableDeclarator(node, _parent, path, vctx) {
     }
   }
   if (bindingNames.length > 0) {
-    const parent = node.parent;
-    const kind = isObject(parent) && parent.type === "VariableDeclaration" ? String(parent.kind ?? "var") : "var";
+    const declParent = isObject(parent) && parent.type === "ExportNamedDeclaration" ? parent.declaration ?? parent : parent;
+    const kind = isObject(declParent) && declParent.type === "VariableDeclaration" ? String(declParent.kind ?? "var") : "var";
     const { line, column } = positionFrom(id, vctx.lineOffsets);
+    const scope = vctx.ctx.stack.length === 0 ? "module" : "function";
     for (const bindingName of bindingNames) {
       vctx.facts.deadCode.bindings.push({
         name: bindingName,
         kind,
         line,
         column,
-        isReferenced: false
+        isReferenced: false,
+        scope
       });
     }
   }
@@ -32882,8 +32888,8 @@ function getCorpusBaselines() {
 
 // src/rules/ai/comment-ratio.ts
 var MIN_FILE_LINES = 20;
-var FALLBACK_LOW = 0.05;
-var FALLBACK_HIGH = 0.45;
+var FALLBACK_LOW = 0.02;
+var FALLBACK_HIGH = 0.55;
 var LINE_COMMENT_RE = /^\s*(?:\/\/|#|--|;|%)/;
 var BLOCK_COMMENT_OPEN_RE = /\/\*/;
 var aiCommentRatioRule = createRule({
@@ -33012,9 +33018,9 @@ function std(xs) {
 
 // src/rules/ai/compression-profile.ts
 var MIN_BYTES = 2e3;
-var GZIP_RATIO_AI_THRESHOLD = 0.5;
-var MEAN_LINE_NCD_HUMAN_MAX = 0.3;
-var NCD_CV_AI_MAX = 0.5;
+var GZIP_RATIO_AI_THRESHOLD = 0.6;
+var MEAN_LINE_NCD_HUMAN_MAX = 0.25;
+var NCD_CV_AI_MAX = 0.4;
 var aiCompressionProfileRule = createRule({
   id: "ai/compression-profile",
   category: "ai",
@@ -33169,6 +33175,13 @@ var aiDefaultReactStackRule = createRule({
   category: "ai",
   severity: "low",
   aiSpecific: true,
+  // v0.20.0 calibration: v8.5 verdict = USEFUL but recall 0.001
+  // (fires 1 time per 1,000 files). The "≥3 of default stack"
+  // threshold catches almost nothing on real codebases — the
+  // default stack is now ubiquitous, so the signal is near-zero.
+  // Disable until the threshold is lowered or the rule is split
+  // into per-library detectors.
+  defaultOff: true,
   description: "File uses \u22653 of the default React stack (Next.js + TanStack Query + Zustand + shadcn/ui) \u2014 Sascha 2025 + Nam et al. MSR 2026",
   create(context) {
     return context;
@@ -33421,6 +33434,10 @@ var aiLibraryReinventionRule = createRule({
   category: "ai",
   severity: "medium",
   aiSpecific: true,
+  // v0.20.0 calibration: v8.5 verdict = USEFUL but recall 0.000
+  // (fires never on the corpus). The "≥2 reinvented patterns"
+  // threshold is too strict. Disable until rewritten.
+  defaultOff: true,
   description: "File reinvents \u22652 common patterns (date picker, form validation, chart, modal, etc.) without importing the canonical library \u2014 GitClear 2025 + Cui et al. 2025",
   create(context) {
     return context;
@@ -33607,6 +33624,12 @@ var aiMarkdownLeakageRule = createRule({
   category: "ai",
   severity: "high",
   aiSpecific: true,
+  // v0.20.0 calibration: v8.5 verdict = INVERTED (lift 65,504× but
+  // recall 0.000 — fires never on the corpus, and when it does fire
+  // it's wrong). The rule was on by default, contributing false
+  // positives to the self-scan. Disable until the rule is rewritten
+  // or the v9 corpus shows it works.
+  defaultOff: true,
   description: "Stray Markdown fence or bare language name at top of file \u2014 AI tools leak the fenced-block format into code",
   create(context) {
     return context;
@@ -33833,6 +33856,16 @@ var aiSegmentSurprisalCvRule = createRule({
   category: "ai",
   severity: "medium",
   aiSpecific: true,
+  // v0.21.0: defaultOff. The rule fires on 250/250 files in the
+  // self-scan (1 per file), which means it's not discriminating
+  // between AI and non-AI text — it fires on every file. The
+  // Binoculars-style per-segment entropy CV is too coarse a
+  // signal at the file level; the entropy floor is hit by most
+  // structured TypeScript regardless of whether the author was
+  // an LLM. Re-enable per-file via
+  // `rules: { 'ai/segment-surprisal-cv': 'medium' }` in
+  // slopbrick.config.mjs once a tighter threshold is calibrated.
+  defaultOff: true,
   description: "Per-segment cross-entropy CV is suspiciously low \u2014 Binoculars (Hans 2024): AI text has near-constant per-window entropy",
   create(context) {
     return context;
@@ -34032,6 +34065,11 @@ var aiTextLikeRatioRule = createRule({
   category: "ai",
   severity: "low",
   aiSpecific: true,
+  // v0.20.0 calibration: v8.5 verdict = USEFUL but recall 0.000
+  // (fires never on the corpus). The rule is too specific to ever
+  // fire on real code — the prose-detection heuristic is too
+  // conservative. Disable until rewritten.
+  defaultOff: true,
   description: "High ratio of prose-like lines embedded in code \u2014 AI tools often leave natural-language explanations in source files (Yotkova 2026)",
   create(context) {
     return context;
@@ -34968,6 +35006,7 @@ var unusedImportRule = createRule({
       if (binding.kind !== "import-specifier" && binding.kind !== "import-default" && binding.kind !== "import-namespace") {
         continue;
       }
+      if (binding.isTypeOnly) continue;
       if (binding.isReferenced) continue;
       if (!binding.name) continue;
       const source = binding.source ? ` from '${binding.source}'` : "";
@@ -35041,6 +35080,9 @@ var unusedLocalRule = createRule({
       if (binding.isReferenced) continue;
       if (SKIP_NAMES.has(binding.name)) continue;
       if (binding.name.startsWith("_")) continue;
+      if (binding.scope === "module" && (binding.kind === "const" || binding.kind === "function" || binding.kind === "class" || binding.kind === "type" || binding.kind === "interface" || binding.kind === "enum")) {
+        continue;
+      }
       issues.push({
         ruleId: "dead/unused-local",
         category: "logic",
@@ -35708,7 +35750,7 @@ function collectExports(cwd) {
       /\bexport\s+default\s+(?:function\s+|class\s+)?([A-Za-z_$][\w$]*)/g,
       // v0.18.6: also collect field names from `export interface` and
       // `export type` declarations. Without this, fields like
-      // `crossFileDrift`, `aiQuality`, `engineeringHygiene` are
+      // `crossFileDrift`, `aiSlopScore`, `engineeringHygiene` are
       // flagged as stale even though they're valid type fields.
       /^\s*(?:readonly\s+)?([A-Za-z_$][\w$]*)\s*[?:]/gm
     ]) {
@@ -36037,7 +36079,7 @@ var brokenLinkRule = createRule({
 
 // src/rules/dup/identical-block.ts
 var crypto = __toESM(require("crypto"), 1);
-var WINDOW_SIZE = 10;
+var WINDOW_SIZE = 20;
 var MIN_NORMALIZED_LENGTH = 40;
 var HASH_PREFIX_LENGTH = 16;
 var DEDUP_CACHE = /* @__PURE__ */ new Map();
@@ -36499,6 +36541,9 @@ var javaSystemOutPrintlnRule = createRule({
 var GAP_RE = /\bgap(?:-x|-y)?-(\d+)\b/g;
 var gapMonopolyRule = createRule({
   id: "layout/gap-monopoly",
+  // v0.20.0 calibration: recall 0.000, fires never. Disable
+  // until rewritten.
+  defaultOff: true,
   category: "layout",
   severity: "medium",
   aiSpecific: false,
@@ -36595,6 +36640,9 @@ var mathElementUniformityRule = createRule({
 var GRID_COLS_RE = /\bgrid-cols-(\d+)\b/g;
 var mathGridUniformityRule = createRule({
   id: "layout/math-grid-uniformity",
+  // v0.20.0 calibration: recall 0.000, fires never. Disable
+  // until rewritten.
+  defaultOff: true,
   category: "layout",
   severity: "high",
   aiSpecific: true,
@@ -37046,6 +37094,9 @@ function checkInlineValue(value, scale) {
 }
 var spacingGridRule = createRule({
   id: "layout/spacing-grid",
+  // v0.20.0 calibration: recall 0.000, fires never. Disable
+  // until rewritten.
+  defaultOff: true,
   category: "layout",
   severity: "medium",
   aiSpecific: false,
@@ -37155,15 +37206,9 @@ var boundaryViolationRule = createRule({
     if (context.supportsRsc === false) return [];
     if (!facts.v2) return [];
     const issues = [];
-    const hookLines = /* @__PURE__ */ new Map();
-    for (const h of facts.v2.logic.hooks) {
-      const arr = hookLines.get(h.name) ?? [];
-      arr.push({ line: h.line, column: h.column });
-      hookLines.set(h.name, arr);
-    }
     for (const component of facts.v2.components) {
       if (!component.isServerComponent) continue;
-      for (const hook of facts.v2.logic.hooks) {
+      for (const hook of component.hookCalls) {
         if (!context.clientHooks.has(hook.name)) continue;
         issues.push({
           ruleId: "logic/boundary-violation",
@@ -37171,8 +37216,8 @@ var boundaryViolationRule = createRule({
           severity: "high",
           aiSpecific: true,
           message: `'${hook.name}' only works in interactive client components. This component runs on the server.`,
-          line: component.line,
-          column: component.column,
+          line: hook.line,
+          column: hook.column,
           advice: "Add the 'use client' directive at the top of this file, or move the stateful part to a separate client component.",
           fix: {
             kind: "insert",
@@ -39956,7 +40001,12 @@ var WEAK_MATCHERS = /* @__PURE__ */ new Set([
   "toBeUndefined",
   "toBeTruthy",
   "toBeFalsy",
-  "toBeNull"
+  "toBeNull",
+  "toBeGreaterThan",
+  "toBeLessThan",
+  "toContain",
+  "toHaveLength",
+  "toBeInstanceOf"
 ]);
 function isTautologicalAssertion(hit) {
   if (hit.matcherArg && hit.expectArg && hit.expectArg === hit.matcherArg) return true;
@@ -40797,6 +40847,10 @@ function rgbToHue([r, g, b]) {
 }
 var mathColorClusterRule = createRule({
   id: "visual/math-color-cluster",
+  // v0.20.0 calibration: recall 0.000, fires never. The
+  // "math-color cluster" heuristic is too specific to ever fire
+  // on real code. Disable until rewritten.
+  defaultOff: true,
   category: "visual",
   severity: "high",
   aiSpecific: true,
@@ -40851,6 +40905,9 @@ var FONT_IMPORT_HINT_RE = /next\/font|@import\s+url|fonts\.googleapis|fonts\.gst
 var NEXT_FONT_IMPORT_RE = /import\s+.*from\s+['"]next\/font\/(?:google|local)['"]/;
 var mathDefaultFontRule = createRule({
   id: "visual/math-default-font",
+  // v0.20.0 calibration: recall 0.001, fires 1 per 1,000 files.
+  // Too specific to be useful. Disable until rewritten.
+  defaultOff: true,
   category: "visual",
   severity: "high",
   aiSpecific: true,
@@ -40917,6 +40974,9 @@ var TEXT_SIZE_MAP = {
 var TEXT_SIZE_RE = /\btext-(?:xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl)\b/g;
 var mathFontEntropyRule = createRule({
   id: "visual/math-font-entropy",
+  // v0.20.0 calibration: recall 0.004, fires 0 times on self-scan
+  // (verified). Disable until rewritten.
+  defaultOff: true,
   category: "visual",
   severity: "high",
   aiSpecific: true,
@@ -41039,6 +41099,10 @@ var ROUNDED_MAP = {
 var ROUNDED_RE = /\brounded(?:-none|-sm|-md|-lg|-xl|-2xl|-3xl|-full)?\b/g;
 var mathRoundedEntropyRule = createRule({
   id: "visual/math-rounded-entropy",
+  // v0.20.0 calibration: recall 0.004, fires 0 times on self-scan
+  // (verified). The entropy heuristic is too specific to ever fire
+  // on real code. Disable until rewritten.
+  defaultOff: true,
   category: "visual",
   severity: "high",
   aiSpecific: true,
@@ -41079,6 +41143,9 @@ var mathRoundedEntropyRule = createRule({
 var SPACING_PREFIX_RE2 = /\b(p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap|gap-x|gap-y)-(\d+)\b/g;
 var mathSpacingEntropyRule = createRule({
   id: "visual/math-spacing-entropy",
+  // v0.20.0 calibration: recall 0.002, fires 0 times on self-scan
+  // (verified). Disable until rewritten.
+  defaultOff: true,
   category: "visual",
   severity: "medium",
   aiSpecific: true,
@@ -41116,7 +41183,7 @@ var mathSpacingEntropyRule = createRule({
 
 // src/rules/visual/naturalness-anomaly.ts
 var MIN_LENGTH = 50;
-var DISTINCT_RATIO_FLOOR = 0.3;
+var DISTINCT_RATIO_FLOOR = 0.2;
 var naturalnessAnomalyRule = createRule({
   id: "visual/naturalness-anomaly",
   category: "visual",
@@ -41161,6 +41228,9 @@ var naturalnessAnomalyRule = createRule({
 var SCALE_TOLERANCE = 1e-3;
 var radiusScaleViolationRule = createRule({
   id: "visual/radius-scale-violation",
+  // v0.20.0 calibration: recall 0.000, fires never. Disable
+  // until rewritten.
+  defaultOff: true,
   category: "visual",
   severity: "medium",
   aiSpecific: false,
@@ -41345,6 +41415,10 @@ var ALT_HANDLER_RE = /^(?:onClick|onPointerDown|onKey(?:Down|Up|Press))$/;
 var ALT_ROLE_RE = /^(?:button|application|tab|menuitem)$/;
 var draggingMovementsRule = createRule({
   id: "wcag/dragging-movements",
+  // v0.20.0 calibration: v8.5 = DORMANT but defaultOff: false
+  // was a bug — DORMANT rules should be off by default. The
+  // rule was contributing 0 useful fires. Disable.
+  defaultOff: true,
   category: "wcag",
   severity: "medium",
   aiSpecific: false,
@@ -41491,6 +41565,11 @@ function scanForMissingAlt(source) {
 }
 var missingAltRule = createRule({
   id: "wcag/missing-alt",
+  // v0.20.0 calibration: lift 1.0, recall 0.000. Lift of 1.0
+  // means the rule has zero discriminative power — it fires
+  // equally on positive and negative examples. Dead rule.
+  // Disable until rewritten.
+  defaultOff: true,
   category: "wcag",
   severity: "medium",
   aiSpecific: false,
@@ -41958,7 +42037,8 @@ var signal_strength_default = {
     precision: 0.6803,
     lastCalibratedAt: "2026-07-01T00:00:00Z",
     verdict: "USEFUL",
-    _calibrationNote: "v8.5 calibration (v0.18.9, 2026-07-01): v7+v8 combined corpus (252080 neg + 294178 pos). v8.5 TP=27874, FP=13097, P=68.0%, FPR=5.20%, lift=13.09. v7 was USEFUL (TP=16673, FP=10112, lift=11.29). v8 was USEFUL (TP=11201, FP=2985).",
+    defaultOff: true,
+    _calibrationNote: "v8.5 calibration (v0.18.9, 2026-07-01): v7+v8 combined corpus (252080 neg + 294178 pos). v8.5 TP=27874, FP=13097, P=68.0%, FPR=5.20%, lift=13.09. v7 was USEFUL (TP=16673, FP=10112, lift=11.29). v8 was USEFUL (TP=11201, FP=2985). v0.21.0: marked defaultOff because the v0.21.0 self-scan fires 109 times across 47 files \u2014 the heuristic counts `{`, `}`, `(`, `)` as raw characters without skipping string contents, template literals, regex literals, or comments. Files with normal closing-brace tails (the last 4-5 lines of a function definition) consistently fire because the tail has 0 opens and 3-4 closes. The corpus-level 13.09 lift doesn't translate to per-file discrimination. v0.22.0 should re-implement the count with a token-aware state machine (string/comment/regex skip) or switch to a parse-error-based signal.",
     aiSpecific: true,
     _v7Verdict: "USEFUL",
     _v7Lift: 11.29,
@@ -42061,7 +42141,8 @@ var signal_strength_default = {
     precision: 0.7495,
     lastCalibratedAt: "2026-07-01T00:00:00Z",
     verdict: "USEFUL",
-    _calibrationNote: "v8.5 calibration (v0.18.9, 2026-07-01): v7+v8 combined corpus (252080 neg + 294178 pos). v8.5 TP=59390, FP=19849, P=75.0%, FPR=7.87%, lift=9.52. v7 was USEFUL (TP=43498, FP=14983, lift=9.11). v8 was USEFUL (TP=15892, FP=4866).",
+    defaultOff: true,
+    _calibrationNote: "v8.5 calibration (v0.18.9, 2026-07-01): v7+v8 combined corpus (252080 neg + 294178 pos). v8.5 TP=59390, FP=19849, P=75.0%, FPR=7.87%, lift=9.52. v7 was USEFUL (TP=43498, FP=14983, lift=9.11). v8 was USEFUL (TP=15892, FP=4866). v0.21.0: marked defaultOff because the v0.21.0 self-scan fires 250 times across 250 files (1 per file) \u2014 the Binoculars-style per-segment entropy CV is too coarse a signal at the file level; the entropy floor is hit by most structured TypeScript regardless of whether the author was an LLM. The v8.5 corpus-level lift of 9.52 doesn't translate to per-file discrimination. v0.22.0 should tighten the threshold or re-calibrate against the per-file (not per-corpus) lift.",
     aiSpecific: true,
     _v7Verdict: "USEFUL",
     _v7Lift: 9.11,