slopbrick 0.11.2 → 0.17.0

package/dist/index.d.cts

@@ -1,3 +1,8 @@
+import * as _usebrick_engine from '@usebrick/engine';
+export * from '@usebrick/engine';
+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
@@ -244,33 +249,55 @@ interface ScanFactsV2 {
     _source?: string;
 }
 
-interface SignalStrength {
-    /** TP per AI file. Higher = catches more AI tells. */
-    recall: number;
-    /** FP per human file. Higher = false alarms. */
-    fpRate: number;
-    /** recall / fpRate (capped at 99 if no FPs observed). Higher = cleaner signal. */
-    ratio: number;
-    /** recall / (recall + fpRate). 0..1. Higher = more reliable. */
-    precision: number;
-    /** ISO timestamp of last calibration that produced these numbers. */
-    lastCalibratedAt: string;
-    /**
-     * v0.9.3: when `true`, the scan engine applies `'off'` to this rule by
-     * default — user must explicitly opt back in via
-     * `slopbrick.config.mjs`'s `rules:` block. Set for:
-     *   - INVERTED rules (lift < 1.0 — fires MORE on human code than AI;
-     *     actively misleading when surfaced as AI detectors)
-     *   - NOISY rules (recall < 0.1 — fires too rarely on AI code to be
-     *     a useful default; engineers will dismiss after the 3rd false
-     *     sense of "it doesn't matter")
-     * User `rules: { 'rule/id': 'medium' }` overrides the default-off.
-     * Omitted (= undefined) means the rule keeps its factory default.
-     */
-    defaultOff?: 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';
 
-declare const VERSION = "0.11.2";
+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)
+ *
+ * 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.
  *
@@ -301,7 +328,19 @@ interface MaintenanceAxisHealth {
 }
 /** Inputs to the pure `computeAiMaintenanceCost` function. Every axis is optional. */
 interface MaintenanceAxes {
-    /** 0-100, lower = better. The headline `slopIndex` from `ProjectReport`. */
+    /** 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;
@@ -399,7 +438,18 @@ type AiDebt = 'low' | 'medium' | 'high' | 'critical';
 declare const AI_SECURITY_NUMERIC: Record<'low' | 'medium' | 'high' | 'critical', number>;
 /** Inputs to the pure `buildRepositoryHealth` function. Every input is optional. */
 interface RepositoryHealthInputs {
-    /** 0-100, lower = better. Inverted to 100 - x for the composite. */
+    /** 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;
@@ -466,7 +516,7 @@ declare const REPOSITORY_HEALTH_WEIGHTS: {
 
 type Severity = 'low' | 'medium' | 'high';
 type RuleSeverity = Severity | 'auto';
-type Category = 'visual' | 'typo' | 'wcag' | 'layout' | 'component' | 'logic' | 'arch' | 'perf' | 'security' | 'test' | 'docs' | 'db';
+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'`.
@@ -493,7 +543,16 @@ interface Issue {
     fixHint?: string;
     fix?: FixSuggestion;
     fixes?: FixSuggestion[];
-    signalStrength?: SignalStrength;
+    signalStrength?: SignalStrengthEntry;
+    /**
+     * v0.17.0 — Optional rule-specific structured data that the
+     * orchestration layer promotes to typed finding fields (e.g.
+     * `DbFinding.table`, `DocFinding.package`). Conventions:
+     *   - db/* rules: `{ table?: string, columnName?: string }`
+     *   - docs/* rules: `{ package?: string, identifier?: string, link?: string }`
+     * Reporters and rules that don't need this can ignore it.
+     */
+    extras?: Record<string, unknown>;
 }
 interface CachedFile {
     hash: string;
@@ -744,6 +803,18 @@ interface FileScanResult {
     /**
      *  `// slopbrick-disable` directive filtering. */
     facts?: ScanFacts;
+    /**
+     * v0.14.6 — Composite AI-likelihood score for this file.
+     *
+     * Naive Bayes log-likelihood ratio combination of all triggered
+     * rules. `probability` in [0, 1] = P(AI-generated | rules fire);
+     * `confidenceTier` is one of LIKELY_HUMAN / INCONCLUSIVE / LIKELY_AI
+     * / VERY_LIKELY_AI per Jaeschke 1994 JAMA thresholds.
+     *
+     * Populated by the scan pipeline after rule execution. Undefined
+     * when no rules fired (probability stays at the prior prevalence).
+     */
+    compositeScore?: _usebrick_engine.CompositeScore;
 }
 interface ComponentScore {
     filePath: string;
@@ -762,9 +833,17 @@ interface ProjectReport {
     version: string;
     generatedAt: string;
     configPath?: string;
-    slopIndex: number;
+    /** v0.15.0 U.4+: replaces the legacy slopIndex. 0-100, higher is better. */
+    aiQuality: number;
+    engineeringHygiene: number;
+    security: number;
+    repositoryHealth: number;
     assemblyHealth: number;
     totalScore: number;
+    /** @deprecated v0.15.0: use aiQuality. Kept as optional for backward
+     *  compat with existing test fixtures and historical telemetry. Will be
+     *  removed in v0.16.0. */
+    slopIndex?: number;
     categoryScores: Record<Category, number>;
     /** Phase 2 §10: composite subscores. Each is in 0-100 (capped).
      *  slopIndex = 0.40 × boundaryScore + 0.35 × contextScore + 0.25 × visualScore. */
@@ -828,10 +907,6 @@ interface ProjectReport {
     dbDrift?: DbDriftLevel;
     /** Per-finding list behind the db-health score. */
     dbFindings?: DbFinding[];
-    /** Phase 12 — Repository Health (composite 0-100). The endgame score
-     *  that aggregates every prior sub-score into one number a manager
-     *  reads in two seconds. Always informational; --strict for CI gating. */
-    repositoryHealth?: number;
     /** Categorical AI Debt band, derived from `repositoryHealth`. */
     aiDebt?: AiDebt;
     /** Per-axis breakdown of the composite. */
@@ -923,6 +998,75 @@ interface ProjectReport {
     prSlopScore?: number;
     /** v0.10.1 — the git ref supplied to --diff <ref>. Undefined for full scans. */
     diffRef?: string;
+    /**
+     * v0.12.0 — Diagnostic stats from the new math engines. Surfaced in
+     * HTML/JSON reporters under "v0.12 Calibration Diagnostics". Does
+     * NOT affect slopIndex or any headline score; purely informational.
+     *
+     * bayesianPosterior: P(AI | fired_rules) computed via naive-Bayes
+     *   likelihood-ratio combination per Bento et al. 2024 *Neurocomputing*.
+     *   Range [0, 1]. > 0.5 = net AI signal; < 0.5 = net human signal.
+     * survivingFiresCount: number of fires that survive Benjamini–Hochberg
+     *   FDR control at α = 0.05 across the full rule set. The "free rigor"
+     *   upgrade that converts the silent multi-testing problem into a
+     *   calibrated number.
+     */
+    v012Stats?: {
+        bayesianPosterior: number;
+        bayesianMatchedRules: number;
+        totalLogLr: number;
+        survivingFiresCount: number;
+        totalFiresCount: number;
+        fdrAlpha: number;
+        /**
+         * v0.13.0 — Probabilistic AI detection across 3 evidence buckets.
+         * Each file gets a P(AI | date, coding fires, general-practice fires)
+         * via naive Bayes. Range [0, 1]. Buckets:
+         *   - 'likely_ai'     : P >= 0.7
+         *   - 'uncertain'     : 0.4 <= P < 0.7
+         *   - 'likely_human'  : P < 0.4
+         */
+        probabilisticAi?: {
+            /** Per-file P(AI) averaged across the project, weighted by file size. */
+            projectP_ai: number;
+            /** Fraction of files in each bucket. */
+            bucketDistribution: {
+                likely_ai: number;
+                uncertain: number;
+                likely_human: number;
+            };
+            /** Date-based prior: P(AI | lastCommitDate), midpoint 2024-01-01. */
+            datePrior: number;
+            /** Evidence from AI-detector rules (markdown leakage, any density, etc.). */
+            codingLogLr: number;
+            /** Evidence from general-practice rules (low spacing entropy, etc.). */
+            practiceLogLr: number;
+        };
+        /** v0.13.0 — Per-file P(AI) distribution (top 10 by file size). */
+        topP_aiFiles?: Array<{
+            filePath: string;
+            p_ai: number;
+            bucket: 'likely_ai' | 'uncertain' | 'likely_human';
+            lastCommitDate: string;
+        }>;
+    };
+    /** v0.14.5i — Count of issues auto-suppressed because their rule was
+     *  marked `defaultOff: true` in signal-strength.json (INVERTED or NOISY
+     *  rules that would erode trust in the tool if surfaced in CI). Surfaced
+     *  in the main scan output as a trust signal so the user can see that
+     *  the tool is calibrated, not just noisy. The user can opt back in
+     *  via `rules: { 'rule/id': 'medium' }` in slopbrick.config.mjs. */
+    defaultOffSuppressedCount?: number;
+    /** v0.14.5i — Number of distinct rules marked defaultOff. The ratio
+     *  suppressedCount / defaultOffRuleCount is the calibration coverage. */
+    defaultOffRuleCount?: number;
+    /** v0.14.5j — The previous run's Slop Index, if any. Used by
+     *  formatPretty to render a "±N from last run" delta so the user
+     *  can see the trajectory without grep'ing the run log. */
+    previousSlopIndex?: number;
+    /** v0.14.5j — ISO timestamp of the previous run, paired with
+     *  previousSlopIndex so the delta line can say "vs 2026-06-27". */
+    previousRunTimestamp?: string;
 }
 interface TopOffender {
     filePath: string;
@@ -1099,6 +1243,11 @@ interface WizardAnswers {
     styling: StylingSolution;
     uiLibraries: UiLibrary[];
     strictness: Strictness;
+    stateManagement?: string;
+    auth?: string;
+    forms?: string;
+    testing?: string;
+    structure?: 'feature-based' | 'layer-based' | 'flat' | 'monorepo' | 'other';
 }
 declare const DEFAULT_CONFIG: ResolvedConfig;
 
@@ -1130,6 +1279,7 @@ interface ScanProjectOptions {
     cache?: boolean;
     telemetry?: boolean;
 }
+
 declare function scanProject(options: ScanProjectOptions): Promise<ProjectReport>;
 
 declare function runInitWizard(cwd: string, detected: Partial<ResolvedConfig>, options?: {
@@ -1190,98 +1340,4 @@ declare function formatBadge(report: ProjectReport): string;
 /** Render an array of values as a Unicode sparkline (▁▂▃▄▅▆▇█). */
 declare function formatSparkline(values: number[]): string;
 
-/**
- * v0.10.1: `find_similar_function` engine.
- *
- * Given a function/component signature (name + parameter list + hooks
- * used), find the most similar existing implementations across the
- * codebase. Foundation for the GIR (Give-Implementation-Reference)
- * pattern in `slop_suggest` and the BRICK Platform.
- *
- * Algorithm (no LLMs, no embeddings — hash-based AST fingerprinting
- * per Chilowicz 2009, "Syntax Tree Fingerprinting for Code Clone
- * Detection"; also see Maurer 2017 for a modern take on the same
- * approach applied to JS/TS):
- *
- *   1. Walk the codebase and extract each function/component signature.
- *      Signature = (name, normalized param list, hooks used, props).
- *   2. Compute a deterministic fingerprint per signature:
- *      fingerprint = sha256(sorted(hooks) | sorted(props) | sorted(params))
- *   3. Given a query signature, compute Jaccard similarity to every
- *      extracted signature over the union of (hooks ∪ props ∪ params).
- *   4. Return top-k matches sorted by similarity desc.
- *
- * Why this matters: AI agents writing new code ask "does this pattern
- * already exist?" before inventing new ones. `find_similar_function`
- * is the deterministic, citation-backed answer — no LLM hallucination,
- * no embedding dependency, fast even on 100k+ files.
- */
-/**
- * Normalized signature for a single function/component in the codebase.
- */
-interface ComponentSignature {
-    /** Function/component name (PascalCase for components, camelCase for hooks). */
-    name: string;
-    /** Absolute path of the file the signature lives in. */
-    file: string;
-    /** Path relative to the workspace, for display in results. */
-    fileRel: string;
-    /** Line number (1-indexed) where the signature is defined. */
-    line: number;
-    /** Sorted, deduplicated parameter names (without `:` types). */
-    params: string[];
-    /** React hooks used (useState, useEffect, etc.). */
-    hooks: string[];
-    /** Component props accepted (for React components). */
-    props: string[];
-}
-/** A single result from `findSimilarFunctions`. */
-interface SimilarMatch {
-    /** The matched signature. */
-    signature: ComponentSignature;
-    /** Jaccard similarity in [0, 1]. 1 = identical feature set, 0 = disjoint. */
-    similarity: number;
-    /** Stable fingerprint hash. Two identical signatures always match. */
-    fingerprint: string;
-}
-/** Query for `findSimilarFunctions`. */
-interface FindSimilarQuery {
-    /** Optional name filter (exact match). */
-    name?: string;
-    /** Optional hooks filter (e.g., ['useState', 'useEffect']). */
-    hooks?: string[];
-    /** Optional props filter. */
-    props?: string[];
-    /** Optional params filter. */
-    params?: string[];
-    /** Top-k results to return. Default 10. Capped at 50. */
-    limit?: number;
-    /** Workspace directory to search. */
-    workspaceDir: string;
-}
-/**
- * Extract every component/function signature from a single source string.
- * Pure function — no I/O.
- */
-declare function extractSignatures(source: string, filePath: string, workspaceDir: string): ComponentSignature[];
-/** Stable fingerprint: sha256 over sorted feature set. */
-declare function fingerprintSignature(sig: Pick<ComponentSignature, 'hooks' | 'props' | 'params'>): string;
-/**
- * Jaccard similarity over the union of (hooks ∪ props ∪ params).
- * Returns 0..1. Identical sets → 1. Disjoint → 0.
- */
-declare function signatureSimilarity(a: Pick<ComponentSignature, 'hooks' | 'props' | 'params'>, b: Pick<ComponentSignature, 'hooks' | 'props' | 'params'>): number;
-/**
- * Walk the workspace, extract signatures from every included file, and
- * return top-k matches sorted by Jaccard similarity desc.
- *
- * Pure-ish: the file walking uses async I/O but the similarity math is
- * synchronous (it's microseconds per signature, even on 10k files).
- */
-declare function findSimilarFunctions(query: FindSimilarQuery, options?: {
-    cwd?: string;
-    include?: string[];
-    exclude?: string[];
-}): Promise<SimilarMatch[]>;
-
-export { AI_SECURITY_NUMERIC, type AiDebt, type AiMaintenanceCost, type AiMaintenanceCostResult, type AstroComponentFact, type AutoTunedRule, type BaselineCache, type BaselineMeta, type CachedFile, type Category, type ClassNameFact, type CommentFact, type ComponentFacts, type ComponentScore, type ComponentSignature, type ComponentSizeFact, type ConsoleCallFact, type Constitution, DEFAULT_CONFIG, type DangerouslySetInnerHtmlFact, type DbDriftLevel, type DbFinding, type DialogCallFact, type DisabledLintRuleFact, type DocDriftLevel, type DocFinding, type DomQueryFact, type ElementFact, type EvalCallFact, type ExplicitAnyFact, type FetchCallFact, type FileScanResult, type FindSimilarQuery, type FixSuggestion, type FlywheelOutput, type FlywheelState, type Framework$1 as Framework, type HookCallFact, type HookDependencyArrayFact, type HookFact, type ImportFact, type InlineEventHandlerFact, type Issue, type JsxAttributeStringLiteralFact, type JsxTextLiteralFact, type KeyPropFact, type LogicalExpressionFact, type MagicNumberSpacingConfig, type MaintenanceAxes, type MaintenanceAxisHealth, type NonNullAssertionFact, type OptimisticUpdateFact, type ProjectReport, type PropMutationFact, type PropPassThroughFact, REPOSITORY_HEALTH_WEIGHTS, type ReportReadResult, type RepositoryHealth, type RepositoryHealthInputs, type ResearchMetrics, type ResolvedConfig, type Rule, type RuleContext, type RuleSeverity, type RuleSuggestion, type ScanCache, type ScanFacts, type ScanProjectOptions, type Severity, type SimilarMatch, type SlopAuditRun, type StateBinding, type StateBindingFact, type StringLiteralFact, type StylePropFact, type TamaguiStylePropFact, type TopOffender, type UseEffectBodyFact, VERSION, baselineStatusMessage, colorForSlop, extractSignatures, failedThresholdCount, filterByDisabledDirectives, filterIssues, findSimilarFunctions, fingerprintSignature, formatBadge, formatReportFromFile, formatSparkline, loadConfig, readReportFile, runCli, runInitWizard, scanProject, serializeConfig, signatureSimilarity, stagedGating, thresholdExceeded };
+export { AI_SECURITY_NUMERIC, type AiDebt, type AiMaintenanceCost, type AiMaintenanceCostResult, type AstroComponentFact, type AutoTunedRule, type BaselineCache, type BaselineMeta, type CachedFile, type Category, type ClassNameFact, type CommentFact, type ComponentFacts, type ComponentScore, type ComponentSizeFact, type ConsoleCallFact, type Constitution, DEFAULT_CONFIG, type DangerouslySetInnerHtmlFact, type DbDriftLevel, type DbFinding, type DialogCallFact, type DisabledLintRuleFact, type DocDriftLevel, type DocFinding, type DomQueryFact, type ElementFact, type EvalCallFact, type ExplicitAnyFact, type FetchCallFact, type FileScanResult, type FixSuggestion, type FlywheelOutput, type FlywheelState, type Framework$1 as Framework, type HealthFile, type HookCallFact, type HookDependencyArrayFact, type HookFact, type ImportFact, type InlineEventHandlerFact, type Issue, type JsxAttributeStringLiteralFact, type JsxTextLiteralFact, type KeyPropFact, type LogicalExpressionFact, type MagicNumberSpacingConfig, type MaintenanceAxes, type MaintenanceAxisHealth, type NonNullAssertionFact, type OptimisticUpdateFact, type ProjectReport, type PropMutationFact, type PropPassThroughFact, REPOSITORY_HEALTH_WEIGHTS, type ReportReadResult, type RepositoryHealth, type RepositoryHealthInputs, type ResearchMetrics, type ResolvedConfig, type Rule, type RuleContext, type RuleSeverity, type RuleSuggestion, type ScanCache, type ScanFacts, type ScanProjectOptions, type Severity, type SlopAuditRun, type StateBinding, type StateBindingFact, type StringLiteralFact, type StylePropFact, type TamaguiStylePropFact, type TopOffender, type UseEffectBodyFact, VERSION, baselineStatusMessage, colorForSlop, failedThresholdCount, filterByDisabledDirectives, filterIssues, formatBadge, formatReportFromFile, formatSparkline, loadConfig, readReportFile, runCli, runInitWizard, scanProject, serializeConfig, stagedGating, thresholdExceeded };