slopbrick 0.18.3 → 0.18.5

package/dist/index.d.ts

@@ -4,67 +4,35 @@ import * as _usebrick_core from '@usebrick/core';
 import { SignalStrengthEntry } from '@usebrick/core';
 
 /**
- * Constitution declared by the user (or auto-detected from package.json).
- * Each allow-list field is a list of canonical names — agents and
- * reviewers can match against import strings without needing the
- * original package name. For example, `@reduxjs/toolkit` and `redux`
- * both surface as `'redux'` under `stateManagement`.
+ * v0.18.4 (Phase B R-M2): types split.
+ * Module: _header
  *
- * `forbidden` is the deny-list: bare package specifiers and `@scope/`
- * prefixes that the project has decided are off-limits. Matched against
- * imports during `slop_check_constitution` and the `slopbrick drift`
- * command.
+ * VERSION constant — read from package.json at runtime so a release
+ * version bump propagates without a separate code change here. The
+ * build's `define` rule inlines this at compile time, so the
+ * value is baked in.
+ *
+ * The literal `process.env.SLOPBRICK_VERSION` is replaced by
+ * tsup's esbuild `define` at build time, using the version field
+ * from this package's package.json. No runtime file I/O, so the
+ * dist/ bundle stays self-contained and the path-relative
+ * `require('../package.json')` trick (which breaks after bundling)
+ * is no longer needed.
  */
-interface Constitution {
-    /** State-management libraries, e.g. 'zustand', 'redux', 'jotai'. */
-    stateManagement?: string[];
-    /** Data-fetching / server-state libraries, e.g. 'react-query', 'swr'. */
-    dataFetching?: string[];
-    /** UI component libraries, e.g. 'shadcn', 'radix', 'mui'. */
-    uiLibrary?: string[];
-    /** Form + schema-validation libraries, e.g. 'react-hook-form', 'zod'. */
-    forms?: string[];
-    /** Styling solutions, e.g. 'tailwind', 'styled-components', 'emotion'. */
-    styling?: string[];
-    /** Routing libraries, e.g. 'next', 'react-router', 'tanstack-router'. */
-    routing?: string[];
-    /** Free-form user-declared categories, keyed by category name. */
-    custom?: Record<string, string[]>;
-    /**
-     * Explicit deny-list of bare package specifiers and `@scope/`
-     * prefixes. Anything in this list is forbidden — even if it would
-     * otherwise match a canonical category. Matching rules (see
-     * `matchForbidden`):
-     *  - `forbidden: ['moment']` matches `moment` exactly.
-     *  - `forbidden: ['@types/']` matches any `@types/...` import.
-     *  - `forbidden: ['lodash']` matches `lodash` but not `lodash-es`.
-     */
-    forbidden?: string[];
-}
-
-type BusinessLogicCategory = 'pricing' | 'validation' | 'formatting';
-interface BusinessLogicIssue {
-    category: BusinessLogicCategory;
-    filePath: string;
-    line: number;
-    column: number;
-    ruleId: string;
-    message: string;
-    advice?: string;
-}
+declare const VERSION: string;
 
-interface CategoryDeduction {
-    category: string;
-    count: number;
-    /** Weight per unit (per-extra or per-N-findings). */
-    weight: number;
-    /** Total deduction applied to the score. */
-    deduction: number;
-    /** Human-readable summary, e.g. "3 modal systems, 2 beyond baseline". */
-    summary: string;
-    /** Concrete findings (filenames, category labels, etc.). */
-    findings: string[];
-}
+/**
+ * v0.18.4 (Phase B R-M2): types split.
+ * Module: primitives
+ */
+type Severity = 'low' | 'medium' | 'high';
+type RuleSeverity = Severity | 'auto';
+type Category = 'visual' | 'typo' | 'wcag' | 'layout' | 'component' | 'logic' | 'arch' | 'perf' | 'security' | 'test' | 'docs' | 'db' | 'ai' | 'context' | 'product' | 'i18n';
+/**
+ * `react` covers `.tsx`, `.jsx`, `.ts`, `.js`. Other values are detected
+ * by file extension. Unknown extensions fall back to `'react'`.
+ */
+type Framework$1 = 'react' | 'vue' | 'svelte' | 'astro' | 'html';
 
 interface FileMeta {
     /** Absolute path to the file (or relative path from cwd, whichever the
@@ -232,6 +200,11 @@ interface ScanFactsV2 {
         optimisticUpdates: OptimisticUpdateFact[];
     };
     designTokens: DesignTokens;
+    /**
+     *  dead-code detector rules. Populated by the visitor's identifier
+     *  walk + import/declaration/branch handlers. See `DeadCodeFacts`
+     *  above for the shape. */
+    deadCode: DeadCodeFacts;
     /**
      *  templates. Replaces the synthetic `<template>` elements that the
      *  migration injected into `jsx.elements`. */
@@ -248,294 +221,78 @@ interface ScanFactsV2 {
      *  and `--suggest` output). Not all rules need this. */
     _source?: string;
 }
-
-/**
- * v0.15.0+: The user-facing 3-bucket taxonomy. Maps engine verdicts
- * (6 values, used for LR math and calibration) to UI buckets (3 values,
- * used in the report and JSON output).
- *
- * Per the user's design intent ("INVERTED is basically HYGIENE"), INVERTED
- * rules are in the same UI bucket as HYGIENE rules. The engine still
- * distinguishes them (INVERTED has LR < 1, HYGIENE has LR ≈ 1).
- */
-type Bucket = 'ai' | 'hygiene' | 'suppressed';
-
-declare const VERSION: string;
-/**
- * Runtime shape of `.slopbrick/health.json`. The on-disk JSON
- * matches `packages/core/schemas/v1/health.schema.json` (v3); this
- * interface is the slopbrick-side runtime companion. Schema is the
- * source of truth — keep this in sync with the codegen output in
- * `packages/core/src/generated/health.ts` (RepositoryMemoryHealth).
- *
- * v3 dropped the single `slopIndex` headline in favor of four named
- * scores:
- *   - `aiQuality`           — AI-specific findings (USEFUL + OK verdicts)
- *   - `engineeringHygiene`  — HYGIENE + INVERTED rules
- *   - `security`            — security/* rules
- *   - `repositoryHealth`    — composite (0.5*aiQ + 0.3*eng + 0.2*sec)
+/** What kind of declaration produced a binding. */
+type BindingKind = 'import-specifier' | 'import-default' | 'import-namespace' | 'var' | 'let' | 'const' | 'function' | 'class' | 'type' | 'interface' | 'enum' | 'parameter' | 'catch-clause';
+/** A single binding declaration the visitor found in the file.
  *
- * Plus optional verdict + bucket distributions for agent-readable
- * insight.
- */
-interface HealthFile {
-    version: typeof _usebrick_core.STRUCTURE_SCHEMA_VERSION;
-    generatedAt: string;
-    workspace: string;
-    aiQuality: number;
-    engineeringHygiene: number;
-    security: number;
-    repositoryHealth: number;
-    verdictDistribution?: Record<_usebrick_core.Verdict, number>;
-    bucketDistribution?: Record<Bucket, number>;
-    categoryScores: Record<string, number>;
-    issueCounts: {
-        high: number;
-        medium: number;
-        low: number;
-    };
-    constitutionDrift?: number;
-    topOffenseIds?: string[];
-    scanDurationMs?: number;
+ *  `isReferenced` is set to true if ANY identifier reference to this
+ *  name appeared in the file. The visitor uses a single global
+ *  referenced-name set per file (intra-scope shadowing is rare enough
+ *  in practice that file-level resolution catches ~95% of dead code
+ *  with negligible false positives — the remaining 5% is mostly
+ *  intentional re-exports which are handled separately). */
+interface BindingRecord {
+    /** The local name as written (`Button` for `import { Button } from ...`,
+     *  `setFoo` for a parameter, etc.). */
+    name: string;
+    kind: BindingKind;
+    /** Source line (1-indexed). */
+    line: number;
+    /** Source column (0-indexed). */
+    column: number;
+    /** The owning source — used to differentiate top-level imports from
+     *  inline `import()` expressions, which are dynamic and out of
+     *  scope for the dead-import rule. */
+    source?: string;
+    /** Set to true when the visitor saw at least one reference to this
+     *  name later in the file. */
+    isReferenced: boolean;
+}
+/** A literal boolean condition (`if (true)`, `while (false)`,
+ *  ternary `cond ? a : false`) that makes the branch statically
+ *  decidable. */
+interface ConstantConditionRecord {
+    /** The kind of construct. */
+    kind: 'if-true' | 'if-false' | 'while-true' | 'while-false' | 'ternary';
+    /** The condition's source text. */
+    condition: string;
+    line: number;
+    column: number;
 }
-/**
- * Categorical bucket for the AI Maintenance Cost score.
- *
- *   low       — ship as-is, revisit quarterly
- *   medium    — schedule cleanup work
- *   high      — block new feature work in the affected subsystem
- *   critical  — dedicated refactor sprint required
- *
- * Deliberately a categorical label (not numeric). Same reasoning as
- * `aiSecurityRisk`: a single bucket is harder to game than a number,
- * and a manager can read "AI Maintenance Cost: HIGH" in two seconds.
- *
- * The numeric `health` (0-100, higher = better) and `monthlyUSD`
- * (estimated monthly cost to fix the underlying issues) are exposed
- * alongside the label for agents and trend pipelines that need them.
- */
-type AiMaintenanceCost = 'low' | 'medium' | 'high' | 'critical';
-/** Per-axis contribution to the AI Maintenance Cost score. */
-interface MaintenanceAxisHealth {
-    /** Stable axis name (`slopIndex`, `architectureConsistency`, `aiSecurityRisk`, ...). */
-    axis: string;
-    /** Display label printed by the pretty reporter. */
-    label: string;
-    /** 0-100, higher = better. Derived from the underlying signal. */
-    health: number;
-    /** How this was derived, e.g. `100 - slopIndex (inverted)`. */
-    source: string;
+/** A statement that is unreachable because an earlier statement in
+ *  the same function body unconditionally exited (`return`, `throw`,
+ *  `break`, `continue`). */
+interface UnreachableStatementRecord {
+    /** Why the earlier statement exited. */
+    terminator: 'return' | 'throw' | 'break' | 'continue';
+    /** First line of the unreachable statement. */
+    line: number;
+    column: number;
+    /** A short snippet (first 60 chars) for the rule's message. */
+    snippet: string;
 }
-/** Inputs to the pure `computeAiMaintenanceCost` function. Every axis is optional. */
-interface MaintenanceAxes {
-    /** v0.15.0 U.4+: 0-100, higher = better. The new headline score
-     *  that replaces slopIndex. Tests and callers should pass this
-     *  going forward. */
-    aiQuality?: number;
-    /** v0.15.0 U.4+: 0-100, higher = better. */
-    engineeringHygiene?: number;
-    /** v0.15.0 U.4+: 0-100, higher = better. */
-    security?: number;
-    /** v0.15.0 U.4+: 0-100, higher = better. */
-    repositoryHealth?: number;
-    /** 0-100, lower = better. @deprecated v0.15.0: use aiQuality. Kept
-     *  for backward compat with existing test fixtures and historical
-     *  telemetry. The axis inverts it internally. */
-    slopIndex?: number;
-    /** 0-100, higher = better. From `buildArchitectureScore`. */
-    architectureConsistency?: number;
-    /** Categorical — mapped to numeric via `MAINTENANCE_SECURITY_NUMERIC`. */
-    aiSecurityRisk?: 'low' | 'medium' | 'high' | 'critical';
-    /** Total constitution violations (sum across categories). */
-    constitutionViolations?: number;
-    /** Spacing + radius scale violation counts. */
-    designTokenDrift?: {
-        spacing: number;
-        radius: number;
-    };
-    /** Total high-severity issues across the scan. Extra penalty. */
-    highSeverityIssueCount?: number;
-    /** Approximate LoC; defaults to 0 if unknown (small-project path). */
-    linesOfCode?: number;
-    /** False when the user has not declared a constitution / design tokens
-     * (no drift run). When true, applies the 1.5–2.5× AI multiplier. */
-    hasAiSignals?: boolean;
+/** The dead-code domain. Empty when the file has nothing the visitor
+ *  classified as suspicious. */
+interface DeadCodeFacts {
+    bindings: BindingRecord[];
+    constantConditions: ConstantConditionRecord[];
+    unreachableStatements: UnreachableStatementRecord[];
 }
-/** Result returned by `computeAiMaintenanceCost` + `computeAiMaintenanceCostFromReport`. */
-interface AiMaintenanceCostResult {
-    /** Categorical headline. */
-    cost: AiMaintenanceCost;
-    /** Weighted health in 0-100 (higher = better). Bucket is derived from this. */
-    health: number;
-    /** Estimated monthly USD cost to fix the underlying issues.
-     *  Anchored to Sonar's $306K/yr/MLoC baseline ($25.50/1k LoC/month)
-     *  with the CodeClimate grade→minutes mapping for per-issue cost. */
-    monthlyUSD: number;
-    /** Per-axis breakdown, sorted by health ascending (worst first). */
-    axes: MaintenanceAxisHealth[];
-    /** Per-bucket advice for managers. */
-    advice: string;
+
+interface FixSuggestion {
+    kind: 'insert' | 'replace' | 'css-anchor';
+    description: string;
+    targetFile?: string;
+    anchor?: string;
+    oldValue?: string;
+    newValue?: string;
 }
-/**
- * Categorical drift band on the doc-freshness score.
- *   low       — 80-100
- *   medium    — 60-79
- *   high      — 40-59
- *   critical  — 0-39
- *
- * Drives the `--strict` exit code for `slopbrick docs` (high/critical = 1).
- */
-type DocDriftLevel = 'low' | 'medium' | 'high' | 'critical';
-/** A single doc-drift finding — one rule firing on one line. */
-interface DocFinding {
-    ruleId: 'docs/stale-package-reference' | 'docs/stale-function-reference' | 'docs/expired-code-example' | 'docs/broken-link';
-    severity: 'low' | 'medium' | 'high';
-    docFile: string;
-    line: number;
-    column: number;
-    message: string;
-    advice: string;
-    /** For `stale-package-reference`: the package the doc references. */
-    package?: string;
-    /** For `stale-function-reference`: the identifier. */
-    identifier?: string;
-    /** For `broken-link`: the unresolved link target. */
-    link?: string;
-}
-/**
- * Categorical drift band on the db-health score.
- *   low       — 80-100
- *   medium    — 60-79
- *   high      — 40-59
- *   critical  — 0-39
- */
-type DbDriftLevel = 'low' | 'medium' | 'high' | 'critical';
-/** A single db-health finding — one rule firing on one table/file. */
-interface DbFinding {
-    ruleId: 'db/missing-fk-index' | 'db/duplicate-index' | 'db/missing-not-null' | 'db/enum-sprawl' | 'db/naming-inconsistency' | 'db/sql-concat';
-    severity: 'low' | 'medium' | 'high';
-    dbFile: string;
-    line: number;
-    column: number;
-    message: string;
-    advice: string;
-    /** For rules that target a specific table. */
-    table?: string;
-    /** For column-level rules. */
-    columnName?: string;
-}
-/**
- * Letter-grade band on the composite Repository Health score.
- * Drives the `aiDebt` field — same categorical shape as `aiSecurityRisk`.
- *
- *   low       — 80-100  (clean; safe to ship)
- *   medium    — 60-79   (manageable; revisit quarterly)
- *   high      — 40-59   (block new feature work in affected subsystems)
- *   critical  — 0-39    (dedicated refactor sprint required)
- */
-type AiDebt = 'low' | 'medium' | 'high' | 'critical';
-/** Numeric mapping for categorical `aiSecurityRisk` used in the composite. */
-declare const AI_SECURITY_NUMERIC: Record<'low' | 'medium' | 'high' | 'critical', number>;
-/** Inputs to the pure `buildRepositoryHealth` function. Every input is optional. */
-interface RepositoryHealthInputs {
-    /** v0.15.0 U.4+: 0-100, higher = better. The new headline score
-     *  that replaces slopIndex. Tests and callers should pass this
-     *  going forward. */
-    aiQuality?: number;
-    /** v0.15.0 U.4+: 0-100, higher = better. */
-    engineeringHygiene?: number;
-    /** v0.15.0 U.4+: 0-100, higher = better. */
-    security?: number;
-    /** v0.15.0 U.4+: 0-100, higher = better. */
-    repositoryHealth?: number;
-    /** 0-100, lower = better. Inverted to 100 - x for the composite.
-     *  @deprecated v0.15.0: use aiQuality. Kept for backward compat. */
-    slopIndex?: number;
-    /** 0-100, higher = better. */
-    architectureConsistency?: number;
-    /** Categorical — mapped via AI_SECURITY_NUMERIC. */
-    aiSecurityRisk?: 'low' | 'medium' | 'high' | 'critical';
-    /** Spacing + radius scale violation counts. */
-    designTokenViolations?: {
-        spacing: number;
-        radius: number;
-    };
-    /** Total high-severity issue count (extra penalty). */
-    highSeverityIssueCount?: number;
-    /** 0-100, higher = better. From `slopbrick test` (Phase 5). */
-    testQuality?: number;
-    /** 0-100, higher = better. From `slopbrick business-logic` (Phase 7). */
-    businessLogicCoherence?: number;
-    /** 0-100, higher = better. From `slopbrick docs` (Phase 6). */
-    docFreshness?: number;
-    /** 0-100, higher = better. From `slopbrick db` (Phase 8). */
-    dbHealth?: number;
-    /** v0.10 — MDL log-likelihood ratio from `computeMDLikelihood`.
-     *  Positive = rule-firing evidence favors m_ai; negative favors
-     *  m_human. Surfaced on the result for reporting; NOT folded into
-     *  the weighted-average composite (which is heuristic and remains
-     *  unchanged in this phase). Caller computes the ratio from the
-     *  distinct `ruleId` set across the report's issues. */
-    mdlLogRatio?: number;
-}
-/** Result returned by `buildRepositoryHealth` + `buildRepositoryHealthFromReport`. */
-interface RepositoryHealth {
-    /** Composite 0-100 score (higher = better). */
-    score: number;
-    /** Letter-grade band derived from `score`. */
-    aiDebt: AiDebt;
-    /** Per-axis contribution breakdown (axis → 0-100, higher = better). */
-    breakdown: Record<string, number>;
-    /** Per-axis weight actually applied (post-renormalization). */
-    appliedWeights: Record<string, number>;
-    /** Warnings for managers (e.g. "Critical security risk overrides everything"). */
-    warnings: string[];
-    /** One-line summary. */
-    headline: string;
-    /** v0.10 — MDL log-likelihood ratio (positive = m_ai evidence).
-     *  Surfaced when the caller passed `mdlLogRatio` to
-     *  `buildRepositoryHealth`. Not folded into the weighted-average
-     *  composite in this phase (kept separate so the heuristic score
-     *  can be audited independently of the MDL axis). */
-    mdlLogRatio?: number;
-}
-/** Default weights — sum to 1.0. Optional axes are skipped, and the
- *  remaining weights renormalize to 1.0. Tuned to give `aiSecurityRisk`
- *  the heaviest weight (it is the catastrophic single-event dimension)
- *  while still letting slopIndex + architecture drive most cases. */
-declare const REPOSITORY_HEALTH_WEIGHTS: {
-    readonly slopIndex: 0.2;
-    readonly architectureConsistency: 0.2;
-    readonly aiSecurityRisk: 0.2;
-    readonly designTokenViolations: 0.1;
-    readonly testQuality: 0.1;
-    readonly businessLogicCoherence: 0.1;
-    readonly docFreshness: 0.05;
-    readonly dbHealth: 0.05;
-};
-
-type Severity = 'low' | 'medium' | 'high';
-type RuleSeverity = Severity | 'auto';
-type Category = 'visual' | 'typo' | 'wcag' | 'layout' | 'component' | 'logic' | 'arch' | 'perf' | 'security' | 'test' | 'docs' | 'db' | 'ai' | 'context' | 'product' | 'i18n';
-/**
- * `react` covers `.tsx`, `.jsx`, `.ts`, `.js`. Other values are detected
- * by file extension. Unknown extensions fall back to `'react'`.
- */
-type Framework$1 = 'react' | 'vue' | 'svelte' | 'astro' | 'html';
-interface FixSuggestion {
-    kind: 'insert' | 'replace' | 'css-anchor';
-    description: string;
-    targetFile?: string;
-    anchor?: string;
-    oldValue?: string;
-    newValue?: string;
-}
-interface Issue {
-    ruleId: string;
-    category: Category;
-    severity: Severity;
-    aiSpecific: boolean;
-    filePath?: string;
+interface Issue {
+    ruleId: string;
+    category: Category;
+    severity: Severity;
+    aiSpecific: boolean;
+    filePath?: string;
     message: string;
     line: number;
     column: number;
@@ -816,19 +573,527 @@ interface FileScanResult {
      */
     compositeScore?: _usebrick_engine.CompositeScore;
 }
-interface ComponentScore {
+interface ComponentScore {
+    filePath: string;
+    rawScore: number;
+    componentScore: number;
+    adjustedScore: number;
+    componentCount: number;
+}
+
+/**
+ * Constitution declared by the user (or auto-detected from package.json).
+ * Each allow-list field is a list of canonical names — agents and
+ * reviewers can match against import strings without needing the
+ * original package name. For example, `@reduxjs/toolkit` and `redux`
+ * both surface as `'redux'` under `stateManagement`.
+ *
+ * `forbidden` is the deny-list: bare package specifiers and `@scope/`
+ * prefixes that the project has decided are off-limits. Matched against
+ * imports during `slop_check_constitution` and the `slopbrick drift`
+ * command.
+ */
+interface Constitution {
+    /** State-management libraries, e.g. 'zustand', 'redux', 'jotai'. */
+    stateManagement?: string[];
+    /** Data-fetching / server-state libraries, e.g. 'react-query', 'swr'. */
+    dataFetching?: string[];
+    /** UI component libraries, e.g. 'shadcn', 'radix', 'mui'. */
+    uiLibrary?: string[];
+    /** Form + schema-validation libraries, e.g. 'react-hook-form', 'zod'. */
+    forms?: string[];
+    /** Styling solutions, e.g. 'tailwind', 'styled-components', 'emotion'. */
+    styling?: string[];
+    /** Routing libraries, e.g. 'next', 'react-router', 'tanstack-router'. */
+    routing?: string[];
+    /** Free-form user-declared categories, keyed by category name. */
+    custom?: Record<string, string[]>;
+    /**
+     * Explicit deny-list of bare package specifiers and `@scope/`
+     * prefixes. Anything in this list is forbidden — even if it would
+     * otherwise match a canonical category. Matching rules (see
+     * `matchForbidden`):
+     *  - `forbidden: ['moment']` matches `moment` exactly.
+     *  - `forbidden: ['@types/']` matches any `@types/...` import.
+     *  - `forbidden: ['lodash']` matches `lodash` but not `lodash-es`.
+     */
+    forbidden?: string[];
+}
+
+interface MagicNumberSpacingConfig {
+    ignoreProperties?: string[];
+    ignoreZero?: boolean;
+}
+interface RuleContext {
+    config: ResolvedConfig;
+    filePath: string;
+    cwd: string;
+    framework?: string;
+    uiLibraries?: string[];
+    hasTailwind?: boolean;
+    supportsRsc?: boolean;
+    hotspotIssues?: Issue[];
+}
+interface Rule<Context = unknown> {
+    id: string;
+    category: Category;
+    severity: Severity;
+    aiSpecific: boolean;
+    /** Round 25: short description shown by `slopbrick rules` and used in docs. */
+    description?: string;
+    create(context: RuleContext): Context;
+    analyze(context: Context, facts: ScanFacts): Issue[];
+}
+interface ResolvedConfig {
+    framework?: string;
+    hasTailwind?: boolean;
+    supportsRsc?: boolean;
+    uiLibraries?: string[];
+    include: string[];
+    exclude: string[];
+    rules: Record<string, RuleSeverity | 'off'>;
+    categoryWeights?: Record<Category, number>;
+    /**
+     *  Defaults to { boundary: 0.40, context: 0.35, visual: 0.25 } when unset. */
+    compositeWeights?: {
+        boundary: number;
+        context: number;
+        visual: number;
+    };
+    frameworkMultipliers: Record<string, number>;
+    ruleConfig: Record<string, unknown>;
+    gapTokens?: string[];
+    globalCssTarget?: string;
+    projectMemory?: boolean;
+    telemetry?: boolean;
+    thresholds: {
+        meanSlop: number;
+        p90Slop: number;
+        individualSlopThreshold: number;
+        /** Round 20: per-category thresholds (security fails, typo warns). Optional. */
+        categoryThresholds?: Partial<Record<Category, number>>;
+    };
+    spacingScale?: number[];
+    /**
+     * Declared border-radius scale in rem (Tailwind default) plus the
+     * string 'full' for the 9999px utility. Numeric values that don't
+     * fall on the scale (after px→rem conversion) trigger the
+     * `visual/radius-scale-violation` rule.
+     */
+    radiusScale?: (number | 'full')[];
+    typographyScale?: string[];
+    arbitraryValueAllowlist: (string | RegExp)[];
+    clampAllowlist?: (string | RegExp)[];
+    /** Phase 2 §10: allowed import paths from brick.config.json. Imports
+     *  from `@/components/*` not matching these patterns are flagged by
+     *  `context/import-path-mismatch`. */
+    allowedImports?: string[];
+    wcag: {
+        targetSizeExemptSelectors: string[];
+        targetSizeRequireTailwind?: boolean;
+    };
+    /**
+     * Declared repository constitution: "this repo uses Zustand for
+     * state, shadcn for UI, react-query for data fetching" plus an
+     * explicit deny-list of forbidden packages. Drives the `slop_suggest`
+     * and `slop_check_constitution` MCP tools and the
+     * `slopbrick drift` reporter. Auto-detected from package.json when
+     * unset; user declarations always win (including explicit empty
+     * arrays, which mean "we deliberately don't use this category").
+     */
+    constitution?: Constitution;
+    /**
+     * PR slop score threshold (Phase 11). `slopbrick pr` exits 1 when
+     * the PR introduces more than this many weighted slop points across
+     * the changed files. Default: 20. Lower it to fail PRs that add any
+     * meaningful slop; raise it to be more permissive. Overridden on
+     * the CLI by `--threshold <n>`.
+     */
+    prScoreThreshold?: number;
+    /**
+     * Phase 5 — Test Intelligence opt-in toggles. The four `test/*`
+     * rules are safe-by-default (each rule short-circuits on non-test
+     * files via `isTestFile()`), but `test/missing-edge-case` walks
+     * production code to find untested branches. Off by default —
+     * opt-in per project.
+     */
+    testIntelligence?: {
+        /** Walk production AST to find branches without test coverage. */
+        missingEdgeCase?: boolean;
+    };
+}
+
+/**
+ * v0.15.0+: The user-facing 3-bucket taxonomy. Maps engine verdicts
+ * (6 values, used for LR math and calibration) to UI buckets (3 values,
+ * used in the report and JSON output).
+ *
+ * Per the user's design intent ("INVERTED is basically HYGIENE"), INVERTED
+ * rules are in the same UI bucket as HYGIENE rules. The engine still
+ * distinguishes them (INVERTED has LR < 1, HYGIENE has LR ≈ 1).
+ */
+type Bucket = 'ai' | 'hygiene' | 'suppressed';
+
+/**
+ * v0.18.4 (Phase B R-M2): types split.
+ * Module: report
+ */
+/**
+ * Runtime shape of `.slopbrick/health.json`. The on-disk JSON
+ * matches `packages/core/schemas/v1/health.schema.json` (v3); this
+ * interface is the slopbrick-side runtime companion. Schema is the
+ * source of truth — keep this in sync with the codegen output in
+ * `packages/core/src/generated/health.ts` (RepositoryMemoryHealth).
+ *
+ * v3 dropped the single `slopIndex` headline in favor of four named
+ * scores:
+ *   - `aiQuality`           — AI-specific findings (USEFUL + OK verdicts)
+ *   - `engineeringHygiene`  — HYGIENE + INVERTED rules
+ *   - `security`            — security/* rules
+ *   - `repositoryHealth`    — composite (0.5*aiQ + 0.3*eng + 0.2*sec)
+ *
+ * Plus optional verdict + bucket distributions for agent-readable
+ * insight.
+ */
+interface HealthFile {
+    version: typeof _usebrick_core.STRUCTURE_SCHEMA_VERSION;
+    generatedAt: string;
+    workspace: string;
+    aiQuality: number;
+    engineeringHygiene: number;
+    security: number;
+    repositoryHealth: number;
+    verdictDistribution?: Record<_usebrick_core.Verdict, number>;
+    bucketDistribution?: Record<Bucket, number>;
+    categoryScores: Record<string, number>;
+    issueCounts: {
+        high: number;
+        medium: number;
+        low: number;
+    };
+    constitutionDrift?: number;
+    topOffenseIds?: string[];
+    scanDurationMs?: number;
+}
+/**
+ * Categorical bucket for the AI Maintenance Cost score.
+ *
+ *   low       — ship as-is, revisit quarterly
+ *   medium    — schedule cleanup work
+ *   high      — block new feature work in the affected subsystem
+ *   critical  — dedicated refactor sprint required
+ *
+ * Deliberately a categorical label (not numeric). Same reasoning as
+ * `aiSecurityRisk`: a single bucket is harder to game than a number,
+ * and a manager can read "AI Maintenance Cost: HIGH" in two seconds.
+ *
+ * The numeric `health` (0-100, higher = better) and `monthlyUSD`
+ * (estimated monthly cost to fix the underlying issues) are exposed
+ * alongside the label for agents and trend pipelines that need them.
+ */
+type AiMaintenanceCost = 'low' | 'medium' | 'high' | 'critical';
+/** Per-axis contribution to the AI Maintenance Cost score. */
+interface MaintenanceAxisHealth {
+    /** Stable axis name (`slopIndex`, `architectureConsistency`, `aiSecurityRisk`, ...). */
+    axis: string;
+    /** Display label printed by the pretty reporter. */
+    label: string;
+    /** 0-100, higher = better. Derived from the underlying signal. */
+    health: number;
+    /** How this was derived, e.g. `100 - slopIndex (inverted)`. */
+    source: string;
+}
+/** Inputs to the pure `computeAiMaintenanceCost` function. Every axis is optional. */
+interface MaintenanceAxes {
+    /** v0.15.0 U.4+: 0-100, higher = better. The new headline score
+     *  that replaces slopIndex. Tests and callers should pass this
+     *  going forward. */
+    aiQuality?: number;
+    /** v0.15.0 U.4+: 0-100, higher = better. */
+    engineeringHygiene?: number;
+    /** v0.15.0 U.4+: 0-100, higher = better. */
+    security?: number;
+    /** v0.15.0 U.4+: 0-100, higher = better. */
+    repositoryHealth?: number;
+    /** 0-100, lower = better. @deprecated v0.15.0: use aiQuality. Kept
+     *  for backward compat with existing test fixtures and historical
+     *  telemetry. The axis inverts it internally. */
+    slopIndex?: number;
+    /** 0-100, higher = better. From `buildArchitectureScore`. */
+    architectureConsistency?: number;
+    /** Categorical — mapped to numeric via `MAINTENANCE_SECURITY_NUMERIC`. */
+    aiSecurityRisk?: 'low' | 'medium' | 'high' | 'critical';
+    /** Total constitution violations (sum across categories). */
+    constitutionViolations?: number;
+    /** Spacing + radius scale violation counts. */
+    designTokenDrift?: {
+        spacing: number;
+        radius: number;
+    };
+    /** Total high-severity issues across the scan. Extra penalty. */
+    highSeverityIssueCount?: number;
+    /** Approximate LoC; defaults to 0 if unknown (small-project path). */
+    linesOfCode?: number;
+    /** False when the user has not declared a constitution / design tokens
+     * (no drift run). When true, applies the 1.5–2.5× AI multiplier. */
+    hasAiSignals?: boolean;
+}
+/** Result returned by `computeAiMaintenanceCost` + `computeAiMaintenanceCostFromReport`. */
+interface AiMaintenanceCostResult {
+    /** Categorical headline. */
+    cost: AiMaintenanceCost;
+    /** Weighted health in 0-100 (higher = better). Bucket is derived from this. */
+    health: number;
+    /** Estimated monthly USD cost to fix the underlying issues.
+     *  Anchored to Sonar's $306K/yr/MLoC baseline ($25.50/1k LoC/month)
+     *  with the CodeClimate grade→minutes mapping for per-issue cost. */
+    monthlyUSD: number;
+    /** Per-axis breakdown, sorted by health ascending (worst first). */
+    axes: MaintenanceAxisHealth[];
+    /** Per-bucket advice for managers. */
+    advice: string;
+}
+/**
+ * Categorical drift band on the doc-freshness score.
+ *   low       — 80-100
+ *   medium    — 60-79
+ *   high      — 40-59
+ *   critical  — 0-39
+ *
+ * Drives the `--strict` exit code for `slopbrick docs` (high/critical = 1).
+ */
+type DocDriftLevel = 'low' | 'medium' | 'high' | 'critical';
+/** A single doc-drift finding — one rule firing on one line. */
+interface DocFinding {
+    ruleId: 'docs/stale-package-reference' | 'docs/stale-function-reference' | 'docs/expired-code-example' | 'docs/broken-link';
+    severity: 'low' | 'medium' | 'high';
+    docFile: string;
+    line: number;
+    column: number;
+    message: string;
+    advice: string;
+    /** For `stale-package-reference`: the package the doc references. */
+    package?: string;
+    /** For `stale-function-reference`: the identifier. */
+    identifier?: string;
+    /** For `broken-link`: the unresolved link target. */
+    link?: string;
+}
+/**
+ * Categorical drift band on the db-health score.
+ *   low       — 80-100
+ *   medium    — 60-79
+ *   high      — 40-59
+ *   critical  — 0-39
+ */
+type DbDriftLevel = 'low' | 'medium' | 'high' | 'critical';
+/** A single db-health finding — one rule firing on one table/file. */
+interface DbFinding {
+    ruleId: 'db/missing-fk-index' | 'db/duplicate-index' | 'db/missing-not-null' | 'db/enum-sprawl' | 'db/naming-inconsistency' | 'db/sql-concat';
+    severity: 'low' | 'medium' | 'high';
+    dbFile: string;
+    line: number;
+    column: number;
+    message: string;
+    advice: string;
+    /** For rules that target a specific table. */
+    table?: string;
+    /** For column-level rules. */
+    columnName?: string;
+}
+/**
+ * Letter-grade band on the composite Repository Health score.
+ * Drives the `aiDebt` field — same categorical shape as `aiSecurityRisk`.
+ *
+ *   low       — 80-100  (clean; safe to ship)
+ *   medium    — 60-79   (manageable; revisit quarterly)
+ *   high      — 40-59   (block new feature work in affected subsystems)
+ *   critical  — 0-39    (dedicated refactor sprint required)
+ */
+type AiDebt = 'low' | 'medium' | 'high' | 'critical';
+/** Numeric mapping for categorical `aiSecurityRisk` used in the composite. */
+declare const AI_SECURITY_NUMERIC: Record<'low' | 'medium' | 'high' | 'critical', number>;
+/** Inputs to the pure `buildRepositoryHealth` function. Every input is optional. */
+interface RepositoryHealthInputs {
+    /** v0.15.0 U.4+: 0-100, higher = better. The new headline score
+     *  that replaces slopIndex. Tests and callers should pass this
+     *  going forward. */
+    aiQuality?: number;
+    /** v0.15.0 U.4+: 0-100, higher = better. */
+    engineeringHygiene?: number;
+    /** v0.15.0 U.4+: 0-100, higher = better. */
+    security?: number;
+    /** v0.15.0 U.4+: 0-100, higher = better. */
+    repositoryHealth?: number;
+    /** 0-100, lower = better. Inverted to 100 - x for the composite.
+     *  @deprecated v0.15.0: use aiQuality. Kept for backward compat. */
+    slopIndex?: number;
+    /** 0-100, higher = better. */
+    architectureConsistency?: number;
+    /** Categorical — mapped via AI_SECURITY_NUMERIC. */
+    aiSecurityRisk?: 'low' | 'medium' | 'high' | 'critical';
+    /** Spacing + radius scale violation counts. */
+    designTokenViolations?: {
+        spacing: number;
+        radius: number;
+    };
+    /** Total high-severity issue count (extra penalty). */
+    highSeverityIssueCount?: number;
+    /** 0-100, higher = better. From `slopbrick test` (Phase 5). */
+    testQuality?: number;
+    /** 0-100, higher = better. From `slopbrick business-logic` (Phase 7). */
+    businessLogicCoherence?: number;
+    /** 0-100, higher = better. From `slopbrick docs` (Phase 6). */
+    docFreshness?: number;
+    /** 0-100, higher = better. From `slopbrick db` (Phase 8). */
+    dbHealth?: number;
+    /** v0.10 — MDL log-likelihood ratio from `computeMDLikelihood`.
+     *  Positive = rule-firing evidence favors m_ai; negative favors
+     *  m_human. Surfaced on the result for reporting; NOT folded into
+     *  the weighted-average composite (which is heuristic and remains
+     *  unchanged in this phase). Caller computes the ratio from the
+     *  distinct `ruleId` set across the report's issues. */
+    mdlLogRatio?: number;
+}
+/** Result returned by `buildRepositoryHealth` + `buildRepositoryHealthFromReport`. */
+interface RepositoryHealth {
+    /** Composite 0-100 score (higher = better). */
+    score: number;
+    /** Letter-grade band derived from `score`. */
+    aiDebt: AiDebt;
+    /** Per-axis contribution breakdown (axis → 0-100, higher = better). */
+    breakdown: Record<string, number>;
+    /** Per-axis weight actually applied (post-renormalization). */
+    appliedWeights: Record<string, number>;
+    /** Warnings for managers (e.g. "Critical security risk overrides everything"). */
+    warnings: string[];
+    /** One-line summary. */
+    headline: string;
+    /** v0.10 — MDL log-likelihood ratio (positive = m_ai evidence).
+     *  Surfaced when the caller passed `mdlLogRatio` to
+     *  `buildRepositoryHealth`. Not folded into the weighted-average
+     *  composite in this phase (kept separate so the heuristic score
+     *  can be audited independently of the MDL axis). */
+    mdlLogRatio?: number;
+}
+/** Default weights — sum to 1.0. Optional axes are skipped, and the
+ *  remaining weights renormalize to 1.0. Tuned to give `aiSecurityRisk`
+ *  the heaviest weight (it is the catastrophic single-event dimension)
+ *  while still letting slopIndex + architecture drive most cases. */
+declare const REPOSITORY_HEALTH_WEIGHTS: {
+    readonly slopIndex: 0.2;
+    readonly architectureConsistency: 0.2;
+    readonly aiSecurityRisk: 0.2;
+    readonly designTokenViolations: 0.1;
+    readonly testQuality: 0.1;
+    readonly businessLogicCoherence: 0.1;
+    readonly docFreshness: 0.05;
+    readonly dbHealth: 0.05;
+};
+
+interface TopOffender {
+    filePath: string;
+    /** Count of issues attributed to this file (from per-file results). */
+    issueCount: number;
+    /** Adjusted score for the file (post-baseline, post-framework-multiplier). */
+    adjustedScore: number;
+}
+
+type BusinessLogicCategory = 'pricing' | 'validation' | 'formatting';
+interface BusinessLogicIssue {
+    category: BusinessLogicCategory;
     filePath: string;
-    rawScore: number;
-    componentScore: number;
-    adjustedScore: number;
-    componentCount: number;
+    line: number;
+    column: number;
+    ruleId: string;
+    message: string;
+    advice?: string;
 }
+
+interface CategoryDeduction {
+    category: string;
+    count: number;
+    /** Weight per unit (per-extra or per-N-findings). */
+    weight: number;
+    /** Total deduction applied to the score. */
+    deduction: number;
+    /** Human-readable summary, e.g. "3 modal systems, 2 beyond baseline". */
+    summary: string;
+    /** Concrete findings (filenames, category labels, etc.). */
+    findings: string[];
+}
+
+/**
+ * v0.18.4 (Phase B R-M2): types split.
+ * Module: baseline
+ *
+ * Cross-module deps: `Category` + `Severity` from `./primitives`,
+ * `Issue` from `./scan`.
+ */
+
 interface BaselineMeta {
     active: boolean;
     version: string;
     baselineRevision: number;
     createdAt: string;
 }
+interface BaselineCache {
+    version: string;
+    config_hash: string;
+    git_head: string;
+    baseline_created: string;
+    baseline_revision: number;
+    totalComponentCount: number;
+    scores: Record<string, {
+        baselineScore: number;
+        componentCount: number;
+    }>;
+}
+interface SlopAuditRun {
+    timestamp: string;
+    version: string;
+    slopIndex: number;
+    categoryScores: Record<Category, number>;
+    topOffenseIds: string[];
+    thresholdExceeded: boolean;
+}
+interface AutoTunedRule {
+    ruleId: string;
+    severity: Severity;
+    reason: string;
+}
+interface RuleSuggestion {
+    pattern: string;
+    example: string;
+    count: number;
+    suggestedRuleId: string;
+}
+/**
+ * Optional research/flywheel metrics. Surfaced in the JSON report and the
+ * flywheel summary when present. Generated by the
+ * `research generate | analyze | candidates` pipeline.
+ */
+interface ResearchMetrics {
+    generatedSampleCount: number;
+    generatedRuleCoverage: number;
+    /** Number of fingerprint clusters that turned into candidate rules. */
+    candidateYield: number;
+    /** When the research artifacts were last refreshed. */
+    updatedAt: string;
+}
+interface FlywheelState {
+    version: string;
+    updatedAt: string;
+    autoTuned: AutoTunedRule[];
+    research?: ResearchMetrics;
+}
+interface FlywheelOutput {
+    autoTuned: AutoTunedRule[];
+    hotspotIssues: Issue[];
+    suggestions: RuleSuggestion[];
+    research?: ResearchMetrics;
+}
+
 interface ProjectReport {
     version: string;
     generatedAt: string;
@@ -1085,171 +1350,6 @@ interface ProjectReport {
      *  previousSlopIndex so the delta line can say "vs 2026-06-27". */
     previousRunTimestamp?: string;
 }
-interface TopOffender {
-    filePath: string;
-    /** Count of issues attributed to this file (from per-file results). */
-    issueCount: number;
-    /** Adjusted score for the file (post-baseline, post-framework-multiplier). */
-    adjustedScore: number;
-}
-interface BaselineCache {
-    version: string;
-    config_hash: string;
-    git_head: string;
-    baseline_created: string;
-    baseline_revision: number;
-    totalComponentCount: number;
-    scores: Record<string, {
-        baselineScore: number;
-        componentCount: number;
-    }>;
-}
-interface SlopAuditRun {
-    timestamp: string;
-    version: string;
-    slopIndex: number;
-    categoryScores: Record<Category, number>;
-    topOffenseIds: string[];
-    thresholdExceeded: boolean;
-}
-interface AutoTunedRule {
-    ruleId: string;
-    severity: Severity;
-    reason: string;
-}
-interface RuleSuggestion {
-    pattern: string;
-    example: string;
-    count: number;
-    suggestedRuleId: string;
-}
-/**
- * Optional research/flywheel metrics. Surfaced in the JSON report and the
- * flywheel summary when present. Generated by the
- * `research generate | analyze | candidates` pipeline.
- */
-interface ResearchMetrics {
-    generatedSampleCount: number;
-    generatedRuleCoverage: number;
-    /** Number of fingerprint clusters that turned into candidate rules. */
-    candidateYield: number;
-    /** When the research artifacts were last refreshed. */
-    updatedAt: string;
-}
-interface FlywheelState {
-    version: string;
-    updatedAt: string;
-    autoTuned: AutoTunedRule[];
-    research?: ResearchMetrics;
-}
-interface FlywheelOutput {
-    autoTuned: AutoTunedRule[];
-    hotspotIssues: Issue[];
-    suggestions: RuleSuggestion[];
-    research?: ResearchMetrics;
-}
-interface MagicNumberSpacingConfig {
-    ignoreProperties?: string[];
-    ignoreZero?: boolean;
-}
-interface RuleContext {
-    config: ResolvedConfig;
-    filePath: string;
-    cwd: string;
-    framework?: string;
-    uiLibraries?: string[];
-    hasTailwind?: boolean;
-    supportsRsc?: boolean;
-    hotspotIssues?: Issue[];
-}
-interface Rule<Context = unknown> {
-    id: string;
-    category: Category;
-    severity: Severity;
-    aiSpecific: boolean;
-    /** Round 25: short description shown by `slopbrick rules` and used in docs. */
-    description?: string;
-    create(context: RuleContext): Context;
-    analyze(context: Context, facts: ScanFacts): Issue[];
-}
-interface ResolvedConfig {
-    framework?: string;
-    hasTailwind?: boolean;
-    supportsRsc?: boolean;
-    uiLibraries?: string[];
-    include: string[];
-    exclude: string[];
-    rules: Record<string, RuleSeverity | 'off'>;
-    categoryWeights?: Record<Category, number>;
-    /**
-     *  Defaults to { boundary: 0.40, context: 0.35, visual: 0.25 } when unset. */
-    compositeWeights?: {
-        boundary: number;
-        context: number;
-        visual: number;
-    };
-    frameworkMultipliers: Record<string, number>;
-    ruleConfig: Record<string, unknown>;
-    gapTokens?: string[];
-    globalCssTarget?: string;
-    projectMemory?: boolean;
-    telemetry?: boolean;
-    thresholds: {
-        meanSlop: number;
-        p90Slop: number;
-        individualSlopThreshold: number;
-        /** Round 20: per-category thresholds (security fails, typo warns). Optional. */
-        categoryThresholds?: Partial<Record<Category, number>>;
-    };
-    spacingScale?: number[];
-    /**
-     * Declared border-radius scale in rem (Tailwind default) plus the
-     * string 'full' for the 9999px utility. Numeric values that don't
-     * fall on the scale (after px→rem conversion) trigger the
-     * `visual/radius-scale-violation` rule.
-     */
-    radiusScale?: (number | 'full')[];
-    typographyScale?: string[];
-    arbitraryValueAllowlist: (string | RegExp)[];
-    clampAllowlist?: (string | RegExp)[];
-    /** Phase 2 §10: allowed import paths from brick.config.json. Imports
-     *  from `@/components/*` not matching these patterns are flagged by
-     *  `context/import-path-mismatch`. */
-    allowedImports?: string[];
-    wcag: {
-        targetSizeExemptSelectors: string[];
-        targetSizeRequireTailwind?: boolean;
-    };
-    /**
-     * Declared repository constitution: "this repo uses Zustand for
-     * state, shadcn for UI, react-query for data fetching" plus an
-     * explicit deny-list of forbidden packages. Drives the `slop_suggest`
-     * and `slop_check_constitution` MCP tools and the
-     * `slopbrick drift` reporter. Auto-detected from package.json when
-     * unset; user declarations always win (including explicit empty
-     * arrays, which mean "we deliberately don't use this category").
-     */
-    constitution?: Constitution;
-    /**
-     * PR slop score threshold (Phase 11). `slopbrick pr` exits 1 when
-     * the PR introduces more than this many weighted slop points across
-     * the changed files. Default: 20. Lower it to fail PRs that add any
-     * meaningful slop; raise it to be more permissive. Overridden on
-     * the CLI by `--threshold <n>`.
-     */
-    prScoreThreshold?: number;
-    /**
-     * Phase 5 — Test Intelligence opt-in toggles. The four `test/*`
-     * rules are safe-by-default (each rule short-circuits on non-test
-     * files via `isTestFile()`), but `test/missing-edge-case` walks
-     * production code to find untested branches. Off by default —
-     * opt-in per project.
-     */
-    testIntelligence?: {
-        /** Walk production AST to find branches without test coverage. */
-        missingEdgeCase?: boolean;
-    };
-}
 
 type Framework = 'react' | 'vue' | 'svelte' | 'solid' | 'qwik' | 'astro' | 'react-native' | 'expo';
 type StylingSolution = 'tailwind' | 'css-modules' | 'styled-components' | 'emotion' | 'panda' | 'other';