fallow 2.103.0 → 3.0.0

package/types/output-contract.d.ts

@@ -2,7 +2,7 @@
  * AUTOGENERATED FILE. DO NOT EDIT.
  *
  * Generated from `docs/output-schema.json` by
- * `editors/vscode/scripts/codegen-types.mjs`. The same file is written to
+ * `editors/vscode/scripts/codegen-contracts.mjs`. The same file is written to
  * `editors/vscode/src/generated/output-contract.d.ts` (extension internal) and
  * `npm/fallow/types/output-contract.d.ts` (published as `fallow/types`).
  *
@@ -10,22 +10,21 @@
  *   1. Edit the Rust struct in `crates/types/src/results.rs` (or the
  *      duplicates crate at `crates/core/src/duplicates/types.rs`). The Rust
  *      side is the runtime source of truth for the JSON output.
- *   2. Update `docs/output-schema.json` to match. The schema is
- *      hand-maintained against the Rust structs; the drift-guard test in
- *      `crates/cli/src/report/json.rs` enforces only a subset of the
- *      contract (the `HealthFindingAction` enum). Field-level drift between
- *      Rust and the schema is currently caught by code review.
- *   3. Run `pnpm --filter fallow-vscode codegen:types` from anywhere.
- *   4. Commit both regenerated files alongside the schema edit.
+ *   2. Regenerate `docs/output-schema.json` with
+ *      `cargo run -p fallow-cli --features schema-emit --bin fallow-schema-emit`.
+ *      The schema-emit drift tests compare the committed schema against the
+ *      Rust-derived definitions.
+ *   3. Run `pnpm --filter fallow-vscode codegen:contracts` from anywhere.
+ *   4. Commit the regenerated schema and generated contract files together.
  *
- * CI runs `pnpm --filter fallow-vscode check:codegen` which fails when
+ * CI runs `pnpm --filter fallow-vscode check:contracts` which fails when
  * either committed file disagrees with what regen would produce.
  */
 /* eslint-disable */
 
 
 /**
- * Schemas for the JSON output of fallow commands. Object-shaped envelopes covered by the `FallowOutput` contract carry a top-level `kind` discriminator (for example `dead-code`, `dead-code-grouped`, `health`, `dupes`, `combined`, `audit`, `explain`, `inspect_target`, `impact`, `security`, `coverage-setup`, `coverage-analyze`, `list-boundaries`, `review-envelope`, and `review-reconcile`). Consumers should branch on `kind` instead of probing for unique field presence. `--legacy-envelope` removes only the document-root `kind` for one compatibility cycle. `CodeClimateOutput` is a bare JSON array (per the Code Climate / GitLab Code Quality spec) and stays a sibling root branch discriminated by checking whether the document root is an array.
+ * Schemas for the JSON output of fallow commands. Object-shaped envelopes covered by the `FallowOutput` contract carry a top-level `kind` discriminator (for example `dead-code`, `dead-code-grouped`, `health`, `dupes`, `combined`, `audit`, `explain`, `inspect_target`, `impact`, `security`, `coverage-setup`, `coverage-analyze`, `list-boundaries`, `review-envelope`, and `review-reconcile`). Consumers should branch on `kind` instead of probing for unique field presence. `CodeClimateOutput` is a bare JSON array (per the Code Climate / GitLab Code Quality spec) and stays a sibling root branch discriminated by checking whether the document root is an array.
  */
 export type FallowJsonOutput = (FallowOutput | CodeClimateOutput)
 /**
@@ -34,11 +33,9 @@ export type FallowJsonOutput = (FallowOutput | CodeClimateOutput)
  * schema derived from this enum drives the document-root `oneOf` in
  * `docs/output-schema.json`.
  *
- * The default wire shape now carries a top-level `kind` discriminator so
- * agents and schema-validating clients can select the variant in O(1) instead
- * of probing for unique field presence. `--legacy-envelope` is a one-cycle
- * compatibility flag that removes only this document-root `kind` field from
- * CLI JSON output; nested report objects are not rewritten.
+ * The wire shape carries a top-level `kind` discriminator so agents and
+ * schema-validating clients can select the variant in O(1) instead of probing
+ * for unique field presence.
  *
  * One envelope is intentionally NOT in this enum:
  * - `CodeClimateOutput` serializes as a bare JSON array
@@ -254,7 +251,7 @@ export type ReExportCycleKind = ("multi-node" | "self-loop")
 /**
  * Which rule-pack rule kind produced a [`PolicyViolation`].
  */
-export type PolicyRuleKind = ("banned-call" | "banned-import" | "banned-effect")
+export type PolicyRuleKind = ("banned-call" | "banned-import" | "banned-effect" | "banned-export")
 /**
  * Effective severity of a single [`PolicyViolation`]. Per-rule `severity`
  * overrides the `rules."policy-violation"` master; `off` rules emit nothing,
@@ -596,11 +593,41 @@ export type FrameworkHealthDetectorStatus = ("active" | "disabled_by_config" | "
 /**
  * Discriminant for [`CssCandidateAction::kind`].
  */
-export type CssCandidateActionType = ("verify-unused" | "verify-undefined" | "consolidate" | "replace-with-token" | "standardize")
+export type CssCandidateActionType = ("verify-unused" | "verify-undefined" | "consolidate" | "replace-with-token" | "standardize" | "simplify-selector")
 /**
  * Discriminant for [`UnusedAtRule::kind`].
  */
 export type UnusedAtRuleKind = ("property-registration" | "layer")
+/**
+ * The surface through which a design token is consumed. The `theme-var` /
+ * `css-var` / `utility` / `apply` kinds are Tailwind v4 `@theme` consumption; the
+ * `js-member` / `js-call` kinds are CSS-in-JS consumption (member access on an
+ * imported StyleX/vanilla-extract token binding, or a PandaCSS `token('...')`
+ * call). The kind is the disjoint origin signal that distinguishes a Tailwind
+ * token entry from a CSS-in-JS token entry in the shared `token_consumers` list.
+ */
+export type ConsumerKind = ("theme-var" | "css-var" | "utility" | "apply" | "js-member" | "js-call")
+/**
+ * Trust level for a [`StylingHealth`] grade. TWO variants (not the three-tier
+ * `high`/`medium`/`low` of [`crate::Confidence`] / `FeatureFlagConfidence`) ON
+ * PURPOSE: styling confidence is binary (the grade is either reliable for the
+ * analyzed surface or it is not), not three distinct evidence tiers, so a
+ * never-emitted `Medium` would be dead surface. Serializes lowercase (`"high"` /
+ * `"low"`), matching the sibling confidence enums' vocabulary.
+ */
+export type StylingHealthConfidence = ("high" | "low")
+/**
+ * Effective configured severity for a styling finding.
+ */
+export type StylingFindingSeverity = ("warn" | "error")
+/**
+ * Confidence hint for a [`StylingFinding`].
+ */
+export type StylingFindingConfidence = ("high" | "low")
+/**
+ * Agent handling hint for a [`StylingFinding`].
+ */
+export type StylingAgentDisposition = ("fix-confidently" | "verify-first")
 export type InspectTargetDescriptor = ({
 file: string
 type: "file"
@@ -788,12 +815,14 @@ export type RiskClass = ("low" | "medium" | "high")
  */
 export type ReviewEffort = ("glance" | "review" | "deep_dive")
 /**
- * The focus label for a review unit. EXACTLY two variants: `Skip` is NOT
- * representable, so the type system is the guarantee that free mode never emits
- * a `skip` label (safe explicit-skip is paid, runtime-backed only). Mirrors
- * the decision surface's "cut category not representable" structural posture.
+ * The focus label for a review unit. `Skip` is the SAFE explicit-skip label and
+ * is runtime-backed ONLY: it is producible solely on the paid runtime path
+ * and solely for a unit runtime-proves cold with zero risk signals. Free mode
+ * (no runtime evidence) emits only `ReviewHere` / `NotPrioritized`, never `Skip`
+ * (the build-focus-map labeller cannot reach the `Skip` arm without runtime
+ * input), so the free-tier "rank but never skip" stance holds by construction.
  */
-export type FocusLabel = ("review-here" | "not-prioritized")
+export type FocusLabel = ("review-here" | "not-prioritized" | "skip")
 /**
  * A per-unit confidence flag. The EXACT panel-decided strings: a dynamically-
  * wired or re-export-heavy unit carries one so its static-reachability signal is
@@ -2488,7 +2517,8 @@ kind: PolicyRuleKind
 /**
  * What matched: the written callee path for `banned-call` (e.g.
  * `cp.exec`), the raw import specifier for `banned-import` (e.g.
- * `moment/locale/nl`), or `<effect>: <callee>` for `banned-effect`.
+ * `moment/locale/nl`), `<effect>: <callee>` for `banned-effect`, or the
+ * exported name for `banned-export`.
  */
 matched: string
 severity: PolicyViolationSeverity
@@ -4017,6 +4047,23 @@ framework_health?: (FrameworkHealthDiagnostics | null)
  * over-complex selectors, deep nesting). Present only with `--css`.
  */
 css_analytics?: (CssAnalyticsReport | null)
+/**
+ * Styling-health score and letter grade: a SECOND health axis derived from
+ * the CSS analytics (the design-system axis), orthogonal to the JS/TS code
+ * `health_score`. Present only with `--css` (the same condition as
+ * `css_analytics`), so a plain `fallow health` run is byte-unchanged. The
+ * code score is never affected by this field.
+ */
+styling_health?: (StylingHealth | null)
+/**
+ * Advisory STYLING FINDINGS: the graduation of the descriptive css
+ * candidates into first-class, severity-aware, suppressible findings
+ * surfaced in `fallow audit`. Verdict-neutral by default (the rule defaults
+ * to `warn`); the styling domain's OWN findings collection, not the dead-code
+ * `AnalysisResults`. Present only with `--css`; empty is skipped so a plain
+ * run is byte-unchanged.
+ */
+styling_findings?: StylingFinding[]
 }
 /**
  * Wire envelope for a single complexity finding.
@@ -5826,6 +5873,19 @@ undefined_keyframes?: UndefinedKeyframes[]
  * descending.
  */
 duplicate_declaration_blocks?: CssDuplicateBlock[]
+/**
+ * CVA / shadcn variant class strings that repeat the same normalized class
+ * block in several variant values. Kept separate from CSS declaration-block
+ * duplication because the source is JS config, not parsed CSS rules.
+ */
+cva_duplicate_variant_blocks?: CvaDuplicateVariantBlock[]
+/**
+ * CVA / shadcn variant class strings that hardcode a Tailwind arbitrary
+ * value even though an existing token has the same or nearest comparable
+ * value. Advisory: variants often encode product semantics, so agents
+ * should verify intent before replacing.
+ */
+cva_variant_token_drifts?: CvaVariantTokenDrift[]
 /**
  * Tailwind arbitrary-value utilities (`w-[13px]`, `bg-[#abc]`) found in
  * markup, which hardcode a one-off value instead of a configured scale
@@ -5834,6 +5894,13 @@ duplicate_declaration_blocks?: CssDuplicateBlock[]
  * value is sometimes the right call.
  */
 tailwind_arbitrary_values?: TailwindArbitraryValue[]
+/**
+ * Located raw CSS declaration values that bypass token surfaces (`var()`,
+ * `token()`, `theme()`) on scale-sensitive axes such as color, font-size,
+ * line-height, radius, and shadow. Conservative candidates: a raw value can
+ * be intentional, but introduced raw values are useful audit feedback.
+ */
+raw_style_values?: RawStyleValue[]
 /**
  * Unused CSS at-rule entities: an `@property` registered but never read via
  * `var()` in any stylesheet, or an `@layer` declared but never populated by
@@ -5882,6 +5949,24 @@ unused_font_faces?: UnusedFontFace[]
  * downstream repo. Sorted by `(path, line, token)`.
  */
 unused_theme_tokens?: UnusedThemeToken[]
+/**
+ * Tailwind v4 theme tokens whose comparable values are close to another
+ * token in the same theme dictionary. These are opt-in `--css-deep`
+ * candidates because they need whole-project token context.
+ */
+near_duplicate_theme_tokens?: NearDuplicateThemeToken[]
+/**
+ * A location-aware reverse index of Tailwind v4 `@theme` token consumers:
+ * per token, where it is consumed (`var()` reads, `@apply` bodies, generated
+ * utility classes) and through which surface, plus the full `consumer_count`
+ * (a static lower bound) and the defining site. Built from the same gated
+ * candidate set as `unused_theme_tokens` (v4 + non-plugin + non-published +
+ * whole-scope), so a token with `consumer_count: 0` is the same "nothing
+ * consumes this" signal. Sorted by token; empty when the project is not
+ * Tailwind v4 or a plugin / published-library / partial-scope run gated the
+ * scan out.
+ */
+token_consumers?: TokenConsumers[]
 /**
  * The project authors `font-size` values in several units (`px`, `rem`,
  * `em`, `%`), with a per-unit distinct-value count: a type-scale
@@ -6068,11 +6153,16 @@ nesting_depth: number
 /**
  * Project-wide CSS analytics aggregates across every analyzed stylesheet
  * (including stylesheets with no notable rule, which are not listed
- * individually).
+ * individually in `files`).
  */
 export interface CssAnalyticsSummary {
 /**
- * Stylesheets analyzed (standard CSS only; SCSS is skipped).
+ * Stylesheets analyzed: standard `.css` files, Vue/Svelte SFC `<style>`
+ * blocks, and (dep-gated) CSS-in-JS, both the tagged-template form and the
+ * object form (`style({...})` / `stylex.create({...})` / `css({...})`). SCSS
+ * is skipped. Note: flat atomic object CSS-in-JS (StyleX/Panda) is counted
+ * here and contributes to these aggregates, but has no notable rules, so its
+ * files never appear in the per-file `files` list.
  */
 files_analyzed: number
 /**
@@ -6184,6 +6274,22 @@ tailwind_arbitrary_values: number
  * Total Tailwind arbitrary-value occurrences across markup.
  */
 tailwind_arbitrary_value_uses: number
+/**
+ * Preprocessor stylesheets (`.scss`, `.sass`, `.less`) seen by the styling
+ * scan. These are parsed textually for local candidates, not compiled.
+ */
+preprocessor_stylesheets: number
+/**
+ * True when project-wide class reachability was skipped because
+ * preprocessor stylesheets outnumber plain CSS, making generated classes
+ * invisible without a Sass/Less compiler.
+ */
+preprocessor_reachability_abstained: boolean
+/**
+ * Located raw CSS declaration values that bypass token surfaces on
+ * scale-sensitive axes. Located in `raw_style_values`.
+ */
+raw_style_values: number
 /**
  * `@property` registrations never referenced via `var()` in any stylesheet
  * (located in `unused_at_rules`). Cleanup candidates.
@@ -6219,6 +6325,12 @@ unused_font_faces: number
  * partial-scope run gated the scan out.
  */
 unused_theme_tokens: number
+/**
+ * Tailwind v4 theme tokens whose comparable values are close to another
+ * token in the same theme dictionary. Located in
+ * `near_duplicate_theme_tokens`.
+ */
+near_duplicate_theme_tokens: number
 /**
  * Number of distinct `font-size` units (`px` / `rem` / `em` / `%`) authored
  * across the codebase. Mixing units is a type-scale consistency smell,
@@ -6368,6 +6480,85 @@ path: string
  */
 line: number
 }
+/**
+ * A duplicated CVA / shadcn variant class block.
+ */
+export interface CvaDuplicateVariantBlock {
+/**
+ * Normalized class block shared by several variant values.
+ */
+value: string
+/**
+ * Number of variant values with this class block.
+ */
+occurrence_count: number
+/**
+ * First locations of the duplicate values, sorted by path and line.
+ */
+occurrences: CssBlockOccurrence[]
+/**
+ * Read-only guidance step(s), so consumers can iterate `actions`
+ * uniformly across every candidate type.
+ */
+actions: CssCandidateAction[]
+}
+/**
+ * A CVA / shadcn variant class value that can reuse an existing styling token.
+ */
+export interface CvaVariantTokenDrift {
+/**
+ * Tailwind arbitrary-value utility inside the variant class string.
+ */
+class_token: string
+/**
+ * Normalized value inside the arbitrary utility.
+ */
+value: string
+/**
+ * Full normalized variant class block containing the token.
+ */
+variant_classes: string
+/**
+ * Project-root-relative, forward-slash path to the variant definition.
+ */
+path: string
+/**
+ * 1-based line of the variant class string.
+ */
+line: number
+nearest_token: NearestStylingToken
+/**
+ * Read-only guidance step(s), so consumers can iterate `actions`
+ * uniformly across every candidate type.
+ */
+actions: CssCandidateAction[]
+}
+/**
+ * A styling token candidate that can replace or explain a finding.
+ */
+export interface NearestStylingToken {
+/**
+ * Token name, e.g. `--color-brand`.
+ */
+name: string
+/**
+ * Normalized token value.
+ */
+value: string
+/**
+ * Project-root-relative, forward-slash definition path.
+ */
+path: string
+/**
+ * 1-based definition line.
+ */
+line: number
+/**
+ * Distance from the finding value. Lower is closer; units depend on the
+ * comparable token namespace.
+ */
+distance: number
+}
 /**
  * A distinct Tailwind arbitrary-value utility token used in markup, with its
  * total use count and first location (a design-token-bypass candidate).
@@ -6397,6 +6588,39 @@ line: number
  */
 actions: CssCandidateAction[]
 }
+/**
+ * A located raw CSS declaration value on a scale-sensitive styling axis.
+ */
+export interface RawStyleValue {
+/**
+ * Value axis, e.g. `color`, `font-size`, `line-height`, `radius`, or `shadow`.
+ */
+axis: string
+/**
+ * CSS property where the raw value appears.
+ */
+property: string
+/**
+ * Rendered declaration value.
+ */
+value: string
+/**
+ * Project-root-relative, forward-slash path to the stylesheet.
+ */
+path: string
+/**
+ * 1-based line of the containing style rule.
+ */
+line: number
+/**
+ * Concrete token with the same or nearest comparable value, when resolved.
+ */
+nearest_token?: (NearestStylingToken | null)
+/**
+ * Read-only guidance step(s). Never auto-fixable.
+ */
+actions: CssCandidateAction[]
+}
 /**
  * An unused CSS at-rule entity (an `@property` registration with no `var()`
  * reference, or an `@layer` declaration never populated), located by its first
@@ -6526,6 +6750,121 @@ line: number
  */
 actions: CssCandidateAction[]
 }
+/**
+ * A Tailwind v4 `@theme` token that appears to duplicate an existing token by
+ * value. Emitted conservatively for comparable token namespaces, with the
+ * nearest existing token named so an agent has a concrete reuse target.
+ */
+export interface NearDuplicateThemeToken {
+/**
+ * The full custom property as authored, including the `--` prefix.
+ */
+token: string
+/**
+ * The normalized authored token value.
+ */
+value: string
+/**
+ * Project-root-relative, forward-slash path to the token definition.
+ */
+path: string
+/**
+ * 1-based line of the token definition inside the `@theme` block.
+ */
+line: number
+nearest_token: NearestStylingToken
+/**
+ * Read-only guidance step(s) before replacing the token reference.
+ */
+actions: CssCandidateAction[]
+}
+/**
+ * A location-aware reverse index of where one design token is consumed, so an
+ * agent editing the token can see its blast radius before changing or removing
+ * it. Covers TWO token origins. The always-available discriminator is the `token`
+ * SHAPE: a Tailwind token is the `--`-prefixed custom property (`--color-brand`),
+ * a CSS-in-JS token is a dotted access path with no `--` prefix
+ * (`vars.color.primary`). The per-consumer `kind` also discriminates origin, but
+ * only when `consumer_count > 0` (a `consumer_count: 0` entry has an empty
+ * `consumers` array and thus no `kind`), so branch on the `token` prefix for the
+ * zero-consumer case. The two origins:
+ *
+ * - Tailwind v4 `@theme` tokens (kinds `theme-var` / `css-var` / `utility` /
+ *   `apply`), built from the same gated candidate set as `unused_theme_tokens`
+ *   (v4 + non-plugin + non-published + whole-scope), so a `consumer_count: 0`
+ *   corroborates the `unused_theme_tokens` "nothing consumes this" finding.
+ * - CSS-in-JS tokens (kind `js-member` / `js-call`) from StyleX `defineVars`,
+ *   vanilla-extract `createTheme` family definitions, and PandaCSS `defineTokens`,
+ *   consumed via cross-module member access or PandaCSS `token('...')` calls. NOTE:
+ *   CSS-in-JS has NO corroborating dead-token finding (there is no
+ *   `unused_theme_tokens` analogue), so a CSS-in-JS `consumer_count: 0` is a weaker
+ *   signal than the Tailwind case (and the cross-file scan is relative-import or
+ *   generated-token-helper only, so alias / bare-package imports are not counted).
+ *
+ * This is DESCRIPTIVE context (a blast-radius lookup), not a finding, so it
+ * deliberately carries no `actions` array (unlike the cleanup-candidate types in
+ * this module). `consumer_count` is always a STATIC lower bound (a computed class
+ * name like `bg-${color}`, or a CSS-in-JS access through an unresolved alias
+ * import, is not counted).
+ */
+export interface TokenConsumers {
+/**
+ * The token identity. For a Tailwind `@theme` token this is the full custom
+ * property as authored, INCLUDING the `--` prefix (`--color-brand`). For a
+ * CSS-in-JS token (kind `js-member`) this is the binding-qualified dotted
+ * access path, NO `--` prefix (`vars.color.primary`), matching how consumers
+ * read it. The presence of the `--` prefix distinguishes the two origins.
+ */
+token: string
+/**
+ * For a Tailwind token, the v4 theme namespace (`color`, `radius`,
+ * `font-weight`, ...). For a CSS-in-JS token (kind `js-member`), the defining
+ * export BINDING the token set is accessed through (`vars`), which identifies
+ * the token set, NOT a semantic group. (The field is thus overloaded by
+ * origin; branch on `consumers[].kind` or the `token` shape.)
+ */
+namespace: string
+/**
+ * Project-root-relative, forward-slash path to the declaring stylesheet
+ * (Tailwind) or the JS/TS token-definition file (CSS-in-JS).
+ */
+definition_path: string
+/**
+ * 1-based line of the token's definition (inside the `@theme` block for
+ * Tailwind; the token key inside the `defineVars`/`createTheme` object for
+ * CSS-in-JS).
+ */
+definition_line: number
+/**
+ * The FULL number of consumer locations found, a STATIC LOWER BOUND: a
+ * computed class name (`bg-${color}`) or a value read outside CSS/markup the
+ * scan never sees is not counted. This is the aggregate over every consumer,
+ * computed BEFORE [`consumers`](Self::consumers) is capped to a sample.
+ */
+consumer_count: number
+/**
+ * A capped, deterministically-sorted sample of consumer locations (at most
+ * [`TOKEN_CONSUMER_SAMPLE_CAP`]). The full count lives in
+ * [`consumer_count`](Self::consumer_count); use this list to jump to
+ * representative consumers, not to enumerate every one.
+ */
+consumers: TokenConsumerLocation[]
+}
+/**
+ * Where one Tailwind v4 `@theme` token is consumed, and through which surface.
+ * One entry in a [`TokenConsumers::consumers`] sample.
+ */
+export interface TokenConsumerLocation {
+/**
+ * Project-root-relative, forward-slash path to the consuming file.
+ */
+path: string
+/**
+ * 1-based line of the consuming reference in that file.
+ */
+line: number
+kind: ConsumerKind
+}
 /**
  * A design-token notation-consistency candidate: the distinct notations used
  * across the codebase for one value axis (today, length units on `font-size`),
@@ -6564,6 +6903,135 @@ notation: string
  */
 count: number
 }
+/**
+ * Project-level styling-health score: a SECOND health axis computed purely from
+ * the structural CSS analytics (`CssAnalyticsReport`), orthogonal to the JS/TS
+ * code-health [`HealthScore`]. Surfaced only alongside the `--css` analytics, so
+ * a plain `fallow health` run is byte-unchanged. The code score and grade stay
+ * untouched: styling health is additive, never folded into the code score.
+ *
+ * Like [`HealthScore`], the score starts at 100 and subtracts capped per-category
+ * penalties; the grade reuses the shared [`letter_grade`] thresholds verbatim
+ * (A>=85, B>=70, C>=55, D>=40, F<40), so the two axes are read on one scale.
+ */
+export interface StylingHealth {
+formula_version: number
+score: number
+grade: string
+penalties: StylingHealthPenalties
+confidence: StylingHealthConfidence
+/**
+ * Human-readable reason the grade is low-confidence: either the declaration
+ * and stylesheet counts a thin grade was computed from, or that structure is
+ * not assessable for compile-time-atomic CSS-in-JS. `None` when confidence is
+ * `High`. Prose, not a stable machine field: gate on `confidence`, not on
+ * this string.
+ */
+confidence_reason?: (string | null)
+}
+/**
+ * Per-category penalty breakdown for the styling-health score. Each field is the
+ * number of points subtracted from a starting 100 for one CSS signal family,
+ * already capped at its category ceiling. A `0.0` field means "the signal was
+ * evaluated and clean"; the whole struct is only ever built when CSS analytics
+ * were produced, so there is no "missing pipeline" ambiguity to model with
+ * `Option` here (the parent `StylingHealth` is itself `Option` on the report).
+ */
+export interface StylingHealthPenalties {
+/**
+ * Copy-paste declaration blocks (`duplicate_declaration_blocks`), scaled by
+ * total removable declarations. Capped at 20pt.
+ */
+duplication: number
+/**
+ * Dead styling surface, two independently-normalized terms summed and capped
+ * at 20pt: (a) unused `@theme` tokens as a share of the total `@theme` token
+ * population (size-independent, so a declaration-sparse Tailwind project is
+ * not penalized for a few dead tokens); plus (b) the other dead entities
+ * (unreferenced classes, unused `@property`/`@layer` at-rules, dead
+ * `@font-face` families) as a share of `total_declarations`.
+ */
+dead_surface: number
+/**
+ * Broken references: markup classes one edit from a defined class
+ * (`unresolved_class_references`) and animations referencing a `@keyframes`
+ * defined nowhere (`undefined_keyframes`). Capped at 15pt.
+ */
+broken_references: number
+/**
+ * Design-token erosion: mixed `font-size` units (`font_size_unit_mix`),
+ * Tailwind arbitrary-value bypasses (`tailwind_arbitrary_values`), and
+ * distinct HARDCODED `box-shadow`/`border-radius`/`line-height` values above
+ * per-axis baselines (the v3 value-sprawl drift sub-term; `var(--*)`-
+ * referenced values are not counted). Capped at 10pt.
+ */
+token_erosion: number
+/**
+ * Structural smells from the summary aggregates: `!important` density and
+ * deep style-rule nesting. Capped at 10pt.
+ */
+structural: number
+}
+/**
+ * One advisory STYLING FINDING: the graduation of a descriptive css candidate
+ * into a first-class, severity-aware, suppressible finding surfaced in
+ * `fallow audit`. The styling domain's OWN finding type (not borrowed into the
+ * dead-code `AnalysisResults`, and not glued in the CLI). `code` is the kebab
+ * IssueKind code (e.g. `css-token-drift`), so severity / inline suppression /
+ * SARIF / MCP all resolve via the shared `issue_meta` contract through
+ * `IssueKind::parse(code)`. One `Vec<StylingFinding>` carries every styling
+ * family; the `code` discriminates.
+ */
+export interface StylingFinding {
+/**
+ * The kebab IssueKind code, e.g. `css-token-drift`.
+ */
+code: string
+/**
+ * The specific sub-kind within the family, e.g. `tailwind-arbitrary-value`.
+ */
+sub_kind: string
+/**
+ * Workspace-relative path of the finding.
+ */
+path: string
+/**
+ * 1-based line of the finding.
+ */
+line: number
+/**
+ * The offending literal value, e.g. `w-[13px]`.
+ */
+value: string
+effective_severity: StylingFindingSeverity
+/**
+ * Optional static lower-bound blast radius. For a dead design token this is
+ * `0`; for other styling findings it is omitted.
+ */
+blast_radius?: (number | null)
+/**
+ * Confidence hint for agents and review UIs. Structural findings are high,
+ * reachability findings are low because dynamic consumers may exist.
+ */
+confidence?: (StylingFindingConfidence | null)
+/**
+ * Suggested handling posture for agents. This is advisory data, fallow
+ * still never applies styling changes automatically.
+ */
+agent_disposition?: (StylingAgentDisposition | null)
+/**
+ * Concrete reuse target for token-drift findings, when one can be resolved.
+ */
+nearest_token?: (NearestStylingToken | null)
+/**
+ * One concise machine-readable edit hint for agent consumers.
+ */
+fix_hint?: (string | null)
+/**
+ * Suggested next steps (verify / suppress; never an auto-fix).
+ */
+actions: CssCandidateAction[]
+}
 /**
  * Envelope emitted by `fallow explain <issue-type> --format json`.
  *
@@ -6991,6 +7459,23 @@ framework_health?: (FrameworkHealthDiagnostics | null)
  * over-complex selectors, deep nesting). Present only with `--css`.
  */
 css_analytics?: (CssAnalyticsReport | null)
+/**
+ * Styling-health score and letter grade: a SECOND health axis derived from
+ * the CSS analytics (the design-system axis), orthogonal to the JS/TS code
+ * `health_score`. Present only with `--css` (the same condition as
+ * `css_analytics`), so a plain `fallow health` run is byte-unchanged. The
+ * code score is never affected by this field.
+ */
+styling_health?: (StylingHealth | null)
+/**
+ * Advisory STYLING FINDINGS: the graduation of the descriptive css
+ * candidates into first-class, severity-aware, suppressible findings
+ * surfaced in `fallow audit`. Verdict-neutral by default (the rule defaults
+ * to `warn`); the styling domain's OWN findings collection, not the dead-code
+ * `AnalysisResults`. Present only with `--css`; empty is skipped so a plain
+ * run is byte-unchanged.
+ */
+styling_findings?: StylingFinding[]
 grouped_by?: (GroupByMode | null)
 groups?: (HealthGroup[] | null)
 _meta?: (Meta | null)
@@ -8778,10 +9263,11 @@ export interface FocusMap {
  */
 review_here: FocusUnit[]
 /**
- * EVERY `not-prioritized` unit (the escape hatch). Always present and fully
+ * EVERY de-prioritized unit (`not-prioritized`, plus runtime-backed `skip`
+ * units on the paid path) -- the escape hatch. Always present and fully
  * enumerated so a reviewer can always "show me what you de-prioritized"; the
  * human brief collapses it by default and re-expands under
- * `--show-deprioritized`.
+ * `--show-deprioritized`. Nothing is ever hidden, including a `skip`.
  */
 deprioritized: FocusUnit[]
 }
@@ -8806,9 +9292,9 @@ reason: string
 confidence?: ConfidenceFlag[]
 }
 /**
- * The composite attention score, with the four deterministic component
- * sub-scores kept on the wire so the runtime seam can re-weight `total`
- * without recomputing the signals.
+ * The composite attention score, with the deterministic component sub-scores
+ * kept on the wire so the runtime layer adds its weight without recomputing the
+ * signals.
  */
 export interface FocusScore {
 /**
@@ -8829,7 +9315,16 @@ risk_zone: number
  */
 change_shape: number
 /**
- * The summed total. The paid runtime layer multiplies a runtime hot/cold weight in here.
+ * Runtime-weight component (paid): a hot path (runtime evidence of high
+ * invocation) adds an invocation-bucketed weight so it amplifies the blast
+ * and outranks an otherwise-equal cold unit. `0` in free mode (no runtime
+ * input), so the free-tier total stays the four deterministic components and
+ * is byte-identical to the no-runtime baseline.
+ */
+runtime?: number
+/**
+ * The summed total of every present component (the four deterministic ones
+ * plus the runtime weight).
  */
 total: number
 }