slopbrick 0.41.0 → 0.42.0

package/dist/index.d.cts

@@ -776,6 +776,101 @@ interface Rule<Context = unknown> {
     create(context: RuleContext): Context;
     analyze(context: Context, facts: ScanFacts): Issue[];
 }
+/**
+ * v0.42.0 (Sprint 3, task 3b.1): composite rule type. A composite
+ * fires when *at least `minMatch`* of its member `ruleIds` fire on the
+ * same file. Members are referenced by their existing `Rule.id`.
+ *
+ * Structurally parallel to `Rule<Context>` so the `RuleRegistry`
+ * treats it uniformly: same `create` + `analyze` lifecycle, same
+ * `defaultOff` opt-in semantics, same `severity` for reporter
+ * weighting. The engine wires composites after per-file `RuleRegistry`
+ * (see `engine/worker.ts` + task 3b.5).
+ *
+ * Design choice: `CompositeRule<Context>` is its own interface rather
+ * than a `Rule<Context>` variant because (a) it carries member-rule
+ * metadata (`ruleIds`, `minMatch`) that vanilla rules do not, and
+ * (b) the union of the two types would force every consumer to
+ * narrow, defeating the structural-parallelism goal.
+ */
+interface CompositeRule<Context = unknown> {
+    id: string;
+    category: Category;
+    severity: Severity;
+    aiSpecific: boolean;
+    /** Short description shown by `slopbrick rules`. */
+    description?: string;
+    /** v0.42.0: composite rules are opt-in by default. */
+    defaultOff?: boolean;
+    /** Member rule IDs (sorted, unique). The composite fires when
+     *  at least `minMatch` of these fire on the same file. */
+    ruleIds: string[];
+    /** Minimum number of `ruleIds` that must fire together. */
+    minMatch: number;
+    create(context: RuleContext): Context;
+    analyze(context: Context, facts: ScanFacts): Issue[];
+}
+/**
+ * v0.42.0 (Sprint 3, task 3b.3): clusterer-emitted composite rule
+ * entry. The shape that `engine/cluster.ts` produces and that the
+ * `RuleRegistry` loader materializes into `CompositeRule<Context>`
+ * instances. Lives next to `CompositeRule<Context>` so the public
+ * type surface for empirical composites is in one place.
+ *
+ * Fields mirror the spec in `docs/superpowers/sprint-0.41-0.42.md`
+ * §3b STEP 5: id, ruleIds, minMatch, severity, defaultOff,
+ * description, calibration, provenance.
+ */
+interface CompositeRuleEntry {
+    id: string;
+    ruleIds: string[];
+    minMatch: number;
+    severity: Severity;
+    defaultOff: true;
+    description: string;
+    calibration: {
+        recall: number;
+        /** False-positive rate, FP / neg_count. */
+        FP: number;
+        precision: number;
+        F1: number;
+        nFiles: number;
+    };
+    provenance: {
+        seed: 'auto-cluster' | 'hand-curated-by-brief';
+        discoveredAt: string;
+        nFiles: number;
+        members: number;
+        /** Strongest NPMI edge among cluster members (0 if singleton). */
+        npmi: number;
+        /** Strongest-edge Fisher's p (1 if singleton). */
+        fisherP: number;
+    };
+}
+/**
+ * v0.42.0 (Sprint 3, task 3b.2): input to the empirical composite
+ * clusterer. `fireMatrix` is the per-file fired-rule-set map; the
+ * other fields are optional inputs to STEP 4 calibration.
+ */
+interface ClusterInput {
+    /** Per-file fired-rule-set map (file id → set of rule IDs that fired). */
+    fireMatrix: ReadonlyMap<string, ReadonlySet<string>>;
+    /** Positive (gold-standard) file IDs for recall/precision. */
+    positiveFiles?: ReadonlySet<string>;
+    /** Severity of each member rule; used to pick `severity = worst`. */
+    memberSeverities?: ReadonlyMap<string, Severity>;
+    /** Algorithm parameter overrides (all optional). */
+    params?: ClusterParamOverrides;
+    /** ISO timestamp embedded in `provenance.discoveredAt` for tests. */
+    now?: string;
+}
+type ClusterParams = {
+    minSupport: number;
+    minNPMI: number;
+    fisherAlpha: number;
+    minClusterSize: number;
+};
+type ClusterParamOverrides = Partial<ClusterParams>;
 interface ResolvedConfig {
     framework?: string;
     hasTailwind?: boolean;
@@ -1612,6 +1707,13 @@ interface ScanProjectOptions {
     noIncrease?: boolean;
     cache?: boolean;
     telemetry?: boolean;
+    /** v0.42.0 (§3a.4): opt-in flag for the AGENTS.md auto-refresh hook.
+     *  When true, `slopbrick scan` writes the freshly-built snippet body
+     *  inside the `<!-- slopbrick:begin:v3 --> ... -->` block in
+     *  AGENTS.md / CLAUDE.md, replacing only that block (user-edited
+     *  content outside the markers is preserved). Default false so
+     *  first-time users aren't surprised. */
+    autoRefreshSnippets?: boolean;
 }
 
 declare function scanProject(options: ScanProjectOptions): Promise<ProjectReport>;
@@ -1674,4 +1776,4 @@ declare function formatBadge(report: ProjectReport): string;
 /** Render an array of values as a Unicode sparkline (▁▂▃▄▅▆▇█). */
 declare function formatSparkline(values: number[]): string;
 
-export { AI_SECURITY_NUMERIC, type AiDebt, type AiMaintenanceCost, type AiMaintenanceCostResult, type AstroComponentFact, type AutoRelaxedRule, 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 ScanSelfScanConfig, 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 };
+export { AI_SECURITY_NUMERIC, type AiDebt, type AiMaintenanceCost, type AiMaintenanceCostResult, type AstroComponentFact, type AutoRelaxedRule, type AutoTunedRule, type BaselineCache, type BaselineMeta, type CachedFile, type Category, type ClassNameFact, type ClusterInput, type ClusterParamOverrides, type ClusterParams, type CommentFact, type ComponentFacts, type ComponentScore, type ComponentSizeFact, type CompositeRule, type CompositeRuleEntry, 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 ScanSelfScanConfig, 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 };

package/dist/index.d.ts

@@ -776,6 +776,101 @@ interface Rule<Context = unknown> {
     create(context: RuleContext): Context;
     analyze(context: Context, facts: ScanFacts): Issue[];
 }
+/**
+ * v0.42.0 (Sprint 3, task 3b.1): composite rule type. A composite
+ * fires when *at least `minMatch`* of its member `ruleIds` fire on the
+ * same file. Members are referenced by their existing `Rule.id`.
+ *
+ * Structurally parallel to `Rule<Context>` so the `RuleRegistry`
+ * treats it uniformly: same `create` + `analyze` lifecycle, same
+ * `defaultOff` opt-in semantics, same `severity` for reporter
+ * weighting. The engine wires composites after per-file `RuleRegistry`
+ * (see `engine/worker.ts` + task 3b.5).
+ *
+ * Design choice: `CompositeRule<Context>` is its own interface rather
+ * than a `Rule<Context>` variant because (a) it carries member-rule
+ * metadata (`ruleIds`, `minMatch`) that vanilla rules do not, and
+ * (b) the union of the two types would force every consumer to
+ * narrow, defeating the structural-parallelism goal.
+ */
+interface CompositeRule<Context = unknown> {
+    id: string;
+    category: Category;
+    severity: Severity;
+    aiSpecific: boolean;
+    /** Short description shown by `slopbrick rules`. */
+    description?: string;
+    /** v0.42.0: composite rules are opt-in by default. */
+    defaultOff?: boolean;
+    /** Member rule IDs (sorted, unique). The composite fires when
+     *  at least `minMatch` of these fire on the same file. */
+    ruleIds: string[];
+    /** Minimum number of `ruleIds` that must fire together. */
+    minMatch: number;
+    create(context: RuleContext): Context;
+    analyze(context: Context, facts: ScanFacts): Issue[];
+}
+/**
+ * v0.42.0 (Sprint 3, task 3b.3): clusterer-emitted composite rule
+ * entry. The shape that `engine/cluster.ts` produces and that the
+ * `RuleRegistry` loader materializes into `CompositeRule<Context>`
+ * instances. Lives next to `CompositeRule<Context>` so the public
+ * type surface for empirical composites is in one place.
+ *
+ * Fields mirror the spec in `docs/superpowers/sprint-0.41-0.42.md`
+ * §3b STEP 5: id, ruleIds, minMatch, severity, defaultOff,
+ * description, calibration, provenance.
+ */
+interface CompositeRuleEntry {
+    id: string;
+    ruleIds: string[];
+    minMatch: number;
+    severity: Severity;
+    defaultOff: true;
+    description: string;
+    calibration: {
+        recall: number;
+        /** False-positive rate, FP / neg_count. */
+        FP: number;
+        precision: number;
+        F1: number;
+        nFiles: number;
+    };
+    provenance: {
+        seed: 'auto-cluster' | 'hand-curated-by-brief';
+        discoveredAt: string;
+        nFiles: number;
+        members: number;
+        /** Strongest NPMI edge among cluster members (0 if singleton). */
+        npmi: number;
+        /** Strongest-edge Fisher's p (1 if singleton). */
+        fisherP: number;
+    };
+}
+/**
+ * v0.42.0 (Sprint 3, task 3b.2): input to the empirical composite
+ * clusterer. `fireMatrix` is the per-file fired-rule-set map; the
+ * other fields are optional inputs to STEP 4 calibration.
+ */
+interface ClusterInput {
+    /** Per-file fired-rule-set map (file id → set of rule IDs that fired). */
+    fireMatrix: ReadonlyMap<string, ReadonlySet<string>>;
+    /** Positive (gold-standard) file IDs for recall/precision. */
+    positiveFiles?: ReadonlySet<string>;
+    /** Severity of each member rule; used to pick `severity = worst`. */
+    memberSeverities?: ReadonlyMap<string, Severity>;
+    /** Algorithm parameter overrides (all optional). */
+    params?: ClusterParamOverrides;
+    /** ISO timestamp embedded in `provenance.discoveredAt` for tests. */
+    now?: string;
+}
+type ClusterParams = {
+    minSupport: number;
+    minNPMI: number;
+    fisherAlpha: number;
+    minClusterSize: number;
+};
+type ClusterParamOverrides = Partial<ClusterParams>;
 interface ResolvedConfig {
     framework?: string;
     hasTailwind?: boolean;
@@ -1612,6 +1707,13 @@ interface ScanProjectOptions {
     noIncrease?: boolean;
     cache?: boolean;
     telemetry?: boolean;
+    /** v0.42.0 (§3a.4): opt-in flag for the AGENTS.md auto-refresh hook.
+     *  When true, `slopbrick scan` writes the freshly-built snippet body
+     *  inside the `<!-- slopbrick:begin:v3 --> ... -->` block in
+     *  AGENTS.md / CLAUDE.md, replacing only that block (user-edited
+     *  content outside the markers is preserved). Default false so
+     *  first-time users aren't surprised. */
+    autoRefreshSnippets?: boolean;
 }
 
 declare function scanProject(options: ScanProjectOptions): Promise<ProjectReport>;
@@ -1674,4 +1776,4 @@ declare function formatBadge(report: ProjectReport): string;
 /** Render an array of values as a Unicode sparkline (▁▂▃▄▅▆▇█). */
 declare function formatSparkline(values: number[]): string;
 
-export { AI_SECURITY_NUMERIC, type AiDebt, type AiMaintenanceCost, type AiMaintenanceCostResult, type AstroComponentFact, type AutoRelaxedRule, 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 ScanSelfScanConfig, 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 };
+export { AI_SECURITY_NUMERIC, type AiDebt, type AiMaintenanceCost, type AiMaintenanceCostResult, type AstroComponentFact, type AutoRelaxedRule, type AutoTunedRule, type BaselineCache, type BaselineMeta, type CachedFile, type Category, type ClassNameFact, type ClusterInput, type ClusterParamOverrides, type ClusterParams, type CommentFact, type ComponentFacts, type ComponentScore, type ComponentSizeFact, type CompositeRule, type CompositeRuleEntry, 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 ScanSelfScanConfig, 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 };