@svelte-vitals/core 0.46.0 → 0.47.1

package/dist/json-OdgY5Bpw.d.ts

@@ -0,0 +1,1287 @@
+//#region src/component.d.ts
+/**
+ * Component-body facts for the Correctness category — the source-analysis boundary
+ * (mirrors images.ts / headings.ts). Collected by the static (CLI) provider only;
+ * the rendered provider can't see reactivity, so correctness rules no-op there.
+ */
+/** An `{#each}` block in a component template. */
+interface EachBlockFact {
+  /** True when the block has a key, e.g. `{#each items as item (item.id)}`. */
+  hasKey: boolean;
+  /** 1-based source line, or 0 if unknown. */
+  line: number;
+  /** Set when the block's key expression is its index binding or a trivial coercion of it — `(i)`, `(String(i))`, `(Number(i))`, `` (`${i}`) ``, `(i.toString())`, `(i + '')` — correctness/each-index-key. */
+  indexKey?: boolean;
+}
+/** An `$effect(...)` / `$effect.pre(...)` call in a component's instance script. */
+interface EffectFact {
+  /** 1-based source line, or 0 if unknown. */
+  line: number;
+  /** True when the effect body only assigns to `$state` variables (the "use $derived" smell). */
+  assignsOnlyState: boolean;
+  /** True when this $effect has a NON-EMPTY body that reads no reactive value and makes no bare call — it never re-runs, so it should be onMount (correctness/effect-as-onmount). */
+  mountOnly: boolean;
+}
+/** A `$effect` guaranteed to run outside component initialisation — it throws `effect_orphan` at runtime (correctness/orphan-effect). */
+interface OrphanEffectFact {
+  /** 1-based source line, or 0 if unknown. For 'constructor-instantiated', the module-scope `new` site. */
+  line: number;
+  /** 'top-level' = runs at module evaluation; 'constructor-instantiated' = module-scope `new` of a same-file class whose constructor creates a bare effect. */
+  kind: 'top-level' | 'constructor-instantiated';
+  /** Class name when kind is 'constructor-instantiated' (used in the finding message). */
+  className?: string;
+}
+/** A svelte lifecycle/context call guaranteed to run outside component initialisation — it throws `lifecycle_outside_component` at runtime (correctness/orphan-lifecycle). */
+interface OrphanLifecycleCallFact {
+  /** Canonical svelte export name (alias-resolved), e.g. 'onMount'. */
+  name: string;
+  /** 1-based source line, or 0 if unknown. For 'constructor-instantiated', the module-scope `new` site. */
+  line: number;
+  /** 'top-level' = runs at module evaluation; 'constructor-instantiated' = module-scope `new` of a same-file class whose constructor calls a tracked function. */
+  kind: 'top-level' | 'constructor-instantiated';
+  /** Class name when kind is 'constructor-instantiated' (used in the finding message). */
+  className?: string;
+}
+/** A browser-only global read in code that runs on the server — SSR crashes with "<name> is not defined" (correctness/server-browser-global, correctness/instance-browser-global). */
+interface BrowserGlobalRefFact {
+  /** The global's name, e.g. 'window'. */
+  name: string;
+  /** 1-based source line, or 0 if unknown. */
+  line: number;
+  /** 'module' = module evaluation (script module / runes module — correctness/server-browser-global); 'instance' = component-init top level (runs on the server during SSR — correctness/instance-browser-global). */
+  context: 'module' | 'instance';
+}
+/** A flagged source position in a component (e.g. an `{@html}` tag or a `javascript:` URL). */
+interface SourceSpan {
+  /** 1-based source line, or 0 if unknown. */
+  line: number;
+}
+/** An inline `svelte-vitals-disable-next-line` directive found in the component's source (issue #92). */
+interface SuppressionDirective {
+  /** 1-based line the directive suppresses (the line immediately after the comment). */
+  line: number;
+  /** Rule ids suppressed on that line; undefined = suppress every rule on that line. */
+  ruleIds?: string[];
+}
+/** An `<input type="checkbox">` / `<input type="radio">` element carrying a `bind:value`
+ *  directive — `bind:value` observes the DOM `value` property, which checkbox/radio
+ *  interaction never changes, so the bound state silently never updates
+ *  (correctness/checkable-bind-value). */
+interface CheckableBindValueFact {
+  /** Which checkable input type was flagged — selects the message wording. */
+  kind: 'checkbox' | 'radio';
+  /** 1-based source line, or 0 if unknown. */
+  line: number;
+}
+/** A root-relative navigation literal — broken when the app is served under `kit.paths.base`
+ *  (correctness/base-path-navigation). Shared by the component and Kit-module channels. */
+interface BasePathLinkFact {
+  /** Which navigation surface it was written on — selects the message wording. */
+  kind: 'href' | 'goto' | 'redirect';
+  /** The literal path as written, e.g. '/about'. */
+  path: string;
+  /** 1-based source line, or 0 if unknown. */
+  line: number;
+}
+/** An interactive element (e.g. `<button>`) found nested inside another interactive
+ *  container (e.g. `<a href>`) (a11y/interactive-nesting). */
+interface InteractiveNestingFact {
+  containerTag: string;
+  /** The container's literal `role`, when that is what made it a container rather than its tag. */
+  containerRole?: string;
+  descendantTag: string;
+  /** 1-based source line of the descendant, or 0 if unknown. */
+  line: number;
+}
+/** A `button`/`a href`/`input type="image"` with no computable accessible name (a11y/accessible-name). */
+interface UnnamedInteractiveFact {
+  tag: string;
+  /** 1-based source line, or 0 if unknown. */
+  line: number;
+}
+/** An element carrying a `role` and/or `aria-*` attribute(s) (a11y ARIA rules). */
+interface AriaElementFact {
+  tag: string;
+  /** 1-based source line, or 0 if unknown. */
+  line: number;
+  /** literal role value; undefined = no role attr; { expression: true } = dynamic */
+  role?: {
+    literal?: string;
+    expression?: boolean;
+  };
+  /** every aria-* attribute on the element */
+  aria: {
+    name: string;
+    literal?: string;
+    expression?: boolean;
+    line: number;
+  }[];
+  /** literal `type` of an `<input>`, lowercased; undefined for non-inputs or a dynamic type */
+  inputType?: string;
+  /** an `<input>` carrying a `list` attribute — its implicit role is `combobox` and the host supplies `aria-expanded` */
+  hasList?: true;
+  /**
+   * A `<select>`'s native role: `combobox` with no `multiple` and no `size` above 1, `listbox`
+   * otherwise; absent for a non-select or when a dynamic `size` leaves it unknowable.
+   */
+  selectKind?: 'combobox' | 'listbox';
+  /** Set when the element also carries a spread attribute — its full attribute set is
+   *  unknowable, so required-prop presence checks must treat it as satisfied (a11y/required-aria-props). */
+  hasSpread?: true;
+}
+/**
+ * Every element in a component with its literal attribute names — the input for the rules that
+ * judge against the HTML spec data (a11y/deprecated-element, a11y/deprecated-attr, and the rest of
+ * that family). Tag and attribute names are lowercased, matching how HTML parses them.
+ */
+interface ElementFact {
+  tag: string;
+  /** 1-based source line, or 0 if unknown. */
+  line: number;
+  /**
+   * Literal attribute names on the element (directives, spreads and expression-only names excluded).
+   * The per-attribute line is not what the deprecation rules anchor to — they anchor at the start
+   * tag so a `disable-next-line` directive can reach a multi-line element — but a value-level rule
+   * (`invalid-attr`) may want it for its message.
+   */
+  attrs: {
+    name: string;
+    line: number;
+    value?: string;
+  }[];
+  /**
+   * Inside an `<svg>` subtree, or in a component declaring `<svelte:options namespace="svg" />`.
+   * `<foreignObject>` returns to HTML. Names collide across the two namespaces (`a`, `script`,
+   * `style`, `title`), so HTML-only rules must skip these.
+   */
+  inSvg?: true;
+  /**
+   * Index of the nearest literal ancestor element in the same array (push-before-children DFS
+   * keeps it sound), looking through `{#if}`/`{#each}`/`{#await}`/`{#key}`. Absent at template
+   * root and after every construct whose rendering position is not lexical — a component,
+   * `<svelte:element>`, `<slot>`, `{@render}`, `{@html}`, a custom element or unknown tag,
+   * a `{#snippet}` body root, `<svelte:head>` children — so `a11y/permitted-contents` never
+   * judges across one.
+   */
+  parent?: number;
+  /** A spread attribute is present — every attribute test on this element is unknowable. */
+  hasSpread?: true;
+  /**
+   * A direct child the static walk cannot see through (component, `{@html}`, `{@render}`,
+   * `<slot />`, `<svelte:element>`, a custom element or unknown tag) — `:has(...)` over this
+   * element's subtree is unknowable.
+   */
+  unknownContent?: true;
+}
+/** Reactivity/correctness + security + architecture facts parsed from one `.svelte` component. */
+interface ComponentFacts {
+  /** Source file the component came from. */
+  file: string;
+  eachBlocks: EachBlockFact[];
+  effects: EffectFact[];
+  /** `{@html …}` occurrences — raw-HTML render surfaces (security/raw-html). */
+  htmlTags: SourceSpan[];
+  /** Element attributes with a literal `javascript:` URL (security/javascript-url). */
+  javascriptUrls: SourceSpan[];
+  /** Source line count of the component file (architecture/component-size). */
+  loc: number;
+  /** Named props destructured from `$props()`; 0 when unknowable (rest / non-destructured) (architecture/prop-count). */
+  propCount: number;
+  /** Module specifiers of every `import` in the instance + module scripts (performance/heavy-import). */
+  imports: string[];
+  /**
+   * Module specifiers of every `import`, each with its source line (performance/heavy-import,
+   * architecture/route-component-import). `type` marks a declaration that contributes **no runtime
+   * value binding** — either `import type …`, or one whose every specifier is inline-typed
+   * (`import { type A } from …`). A specifier-less side-effect import is not marked: it still loads
+   * the module. Optional, so existing external constructors of `ComponentFacts` are unaffected.
+   */
+  importSpans: {
+    source: string;
+    line: number;
+    type?: true;
+  }[];
+  /** Value `import * as X from '<bare pkg>'` namespace imports (type-only excluded) — performance/namespace-import. */
+  namespaceImports: {
+    source: string;
+    line: number;
+  }[];
+  /** `$state` declarations never written or escaped anywhere in the component — candidates for const (correctness/unmutated-state). */
+  constableStates: {
+    name: string;
+    line: number;
+  }[];
+  /** Mutations of a non-`$bindable` prop from `$props()`, or a legacy `export let` prop — member writes, `delete`, or a mutating method call (correctness/prop-mutation). `legacy` distinguishes which mode the prop was declared in (absent/false: `$props()`), since the fix differs — optional so existing external constructors of `ComponentFacts` are unaffected. */
+  mutatedProps: {
+    name: string;
+    line: number;
+    legacy?: boolean;
+  }[];
+  /** Top-level const/let bindings computed from a $props() or legacy `export let` prop without $derived (or `$:`), never reassigned or escaped, and referenced (eagerly) in the template — frozen at init (correctness/stale-prop-derivation). `legacy` distinguishes which mode the prop was declared in, since the fix differs — optional so existing external constructors of `ComponentFacts` are unaffected. */
+  stalePropDerivations: {
+    name: string;
+    line: number;
+    legacy?: boolean;
+  }[];
+  /** Object/array-literal $state bindings reassigned at least once but never mutated, escaped, aliased, or item-edited — $state.raw candidates (performance/state-raw). */
+  rawableStates: {
+    name: string;
+    line: number;
+  }[];
+  /** Plain built-in instances (Map/Set/Date/URL/URLSearchParams) in $state whose type-specific mutations were observed inside functions, with no exempting reassignment — untracked by reactivity (correctness/nonreactive-builtin-state). */
+  nonreactiveBuiltinStates: {
+    name: string;
+    type: string;
+    line: number;
+  }[];
+  /** `<input type="checkbox">` / `<input type="radio">` elements bound with `bind:value`
+   * instead of `bind:checked`/`bind:group` (correctness/checkable-bind-value). */
+  checkableBindValues: CheckableBindValueFact[];
+  /** Root-relative `<a href>` and `goto()` literals in this component (correctness/base-path-navigation). */
+  basePathLinks: BasePathLinkFact[];
+  /** `$effect` calls guaranteed to run outside component initialisation — module scope in `.svelte.ts`/`.svelte.js` or `<script module>` (correctness/orphan-effect). */
+  orphanEffects: OrphanEffectFact[];
+  /** Svelte lifecycle/context calls guaranteed to run outside component initialisation — module scope in `.svelte.ts`/`.svelte.js` or `<script module>` (correctness/orphan-lifecycle). */
+  orphanLifecycleCalls: OrphanLifecycleCallFact[];
+  /** Browser-global reads in server-executed positions of this file (correctness/server-browser-global, correctness/instance-browser-global). */
+  browserGlobalRefs: BrowserGlobalRefFact[];
+  /** Module-scope `$state` declarations in a `.svelte.ts`/`.svelte.js` runes module — on a server, one instance shared by every request (security/shared-state-import). Always empty for `.svelte` files. */
+  moduleStateDecls: {
+    name: string;
+    line: number;
+  }[];
+  /** Inline `svelte-vitals-disable-next-line` directives found in this file's source — component-rule escape hatch (issue #92). Optional: absent is equivalent to no directives, so existing external constructors of `ComponentFacts` are unaffected. */
+  suppressions?: SuppressionDirective[];
+  /** Markdown links `[label](url)` appearing inside a comment (architecture/doc-link-target). */
+  commentLinks: {
+    url: string;
+    line: number;
+  }[];
+  /** Elements carrying a role or any aria-* attribute (a11y ARIA rules). */
+  ariaElements?: AriaElementFact[];
+  /** Every element with its attribute names and SVG-namespace flag (the HTML spec-data rules). */
+  elements?: ElementFact[];
+  /** Interactive elements nested inside another interactive container (a11y/interactive-nesting). */
+  interactiveNestings?: InteractiveNestingFact[];
+  /** `button`/`a href`/`input type="image"` elements with no computable accessible name (a11y/accessible-name). */
+  unnamedInteractive?: UnnamedInteractiveFact[];
+  /** `<label>` elements with neither a `for` attribute nor a wrapped labelable descendant (a11y/label-has-control). */
+  unassociatedLabels?: {
+    line: number;
+  }[];
+  /** Text nodes whose trimmed content opens with a bullet character followed by whitespace, outside any `li` (a11y/use-list). */
+  bulletTexts?: {
+    line: number;
+    char: string;
+  }[];
+  /** `<select required>` (no `multiple`, display size absent or ≤ 1) whose first `option` element
+   *  child is not a placeholder label option (a11y/placeholder-label-option). */
+  selectsMissingPlaceholder?: {
+    line: number;
+  }[];
+  /** `<time>` with no `datetime` attribute whose literal text content is not machine-readable (a11y/require-datetime). */
+  timesMissingDatetime?: {
+    line: number;
+    text: string;
+  }[];
+  /** Set when the file failed to read or parse and these facts are the empty fallback — the file was NOT analyzed. */
+  parseFailed?: true;
+  /** Set when the file could not be READ — an environment problem (permissions, a descriptor
+   *  limit), not a malformed component. Reported separately so one does not masquerade as the other. */
+  readFailed?: true;
+}
+/**
+ * Warnings for files a collector could not read or parse: the file contributes empty facts, so any
+ * findings it would have produced are simply missing rather than reported as fixed. The two causes
+ * are reported separately — an unreadable file is an environment problem (permissions, a descriptor
+ * limit) and a malformed one is the author's, and sharing a message is how a descriptor limit once
+ * read as hundreds of broken components. Capped at 10 inline paths so one badly-broken directory
+ * cannot flood the terminal.
+ */
+declare function skippedFileWarnings(facts: readonly {
+  file: string;
+  parseFailed?: true;
+  readFailed?: true;
+}[]): string[];
+//#endregion
+//#region src/types.d.ts
+type Severity = 'critical' | 'warning' | 'info';
+/** Where a head tag is set, relative to the route being evaluated (design §4). */
+type Presence = 'own' | 'inherited' | 'none';
+/** How a tag's value is determined (design §4). */
+type Value = 'static' | 'dynamic' | 'absent';
+/**
+ * Two-axis detection result. Kept independent so combinations such as
+ * "inherited + dynamic" remain expressible (design §4).
+ */
+interface Detection {
+  presence: Presence;
+  value: Value;
+}
+/**
+ * One compiled SvelteKit alias entry, in the order Kit builds them (`get_config_aliases` in
+ * `@sveltejs/kit/src/exports/vite/utils.js`): `$lib` first, then `kit.alias` in declaration
+ * order. Resolution takes the FIRST matching entry, exactly as Vite's alias plugin does, so
+ * **position is precedence** — the list is never sorted and a longer `find` never wins on
+ * length alone.
+ */
+interface KitAlias {
+  /** The alias key, with any trailing `/*` removed. */
+  find: string;
+  /**
+   * The project-relative target: posixified, with any trailing `/*` and any trailing slashes
+   * removed. `null` when the config's value is not a string literal — such an entry still
+   * matches (holding its position and its mode) but resolves to undefined, so a specifier we
+   * cannot resolve stays unresolved instead of falling through to a later entry.
+   */
+  replacement: string | null;
+  /**
+   * How `find` matches a specifier, mirroring Kit's three compiled entry shapes:
+   * - `prefix` — `spec === find` or `spec.startsWith(find + '/')`; a plain key.
+   * - `contents` — `spec.startsWith(find + '/')` only; from a `key/*` key, which Kit
+   *   documents as matching "the contents of a directory, not the directory itself".
+   * - `exact` — `spec === find` only; a plain key whose `key/*` form is ALSO declared, which
+   *   is how Kit stops the plain key from swallowing the nested specifiers.
+   */
+  match: 'prefix' | 'contents' | 'exact';
+}
+/** Project-wide facts precomputed by the runtime layer for project-scope rules (design §10). */
+interface Project {
+  hasRobotsTxt: boolean;
+  hasSitemap: boolean;
+  /** <html lang> from app.html: presence 'own' when the attribute exists ('none' otherwise); value 'static' if non-empty, 'absent' if empty. */
+  htmlLang: Detection;
+  /** Whether the static static/robots.txt references a sitemap (`Sitemap:` line). Undefined for a +server endpoint / absent / unreadable. */
+  robotsReferencesSitemap?: boolean;
+  /**
+   * Set when the Vite config disables minification for production builds (performance/minify-disabled).
+   * `file` is the config path relative to the analyzed root (posix, may start with `../`
+   * in monorepos); unset for inline programmatic configs. `line` is 1-based and set only
+   * when the literal `minify: false` was located in that file; unset when the value was
+   * resolved at build time (plugin/conditional config). `suppressions` carries the config file's
+   * own inline directives, so a line-anchored finding in it can be silenced like any other.
+   */
+  viteMinifyDisabled?: {
+    file?: string;
+    line?: number;
+    suppressions?: SuppressionDirective[];
+  };
+  /**
+   * Set when the project configures a non-empty `kit.paths.base` — read from the `sveltekit()`
+   * Vite plugin config, else `svelte.config.{js,ts}` (correctness/base-path-navigation).
+   * `value` is the literal base when statically resolvable, unset when the config computes it
+   * (e.g. `dev ? '' : '/repo'`). `file` is the config path relative to the analyzed root (posix).
+   * Absent means the app is served at the root — the rule stays silent.
+   */
+  kitPathsBase?: {
+    value?: string;
+    file: string;
+  };
+  /**
+   * The project's compiled SvelteKit alias entries, in Kit's own order (`$lib` first), read from
+   * `svelte.config.{js,ts}`. Absent means no config was read — resolution then falls back to
+   * `$lib` → `src/lib`, which is what this analyzer assumed unconditionally before. A collected
+   * list is never empty: `$lib` is always prepended.
+   */
+  kitAliases?: KitAlias[];
+  /**
+   * Whether `src/app.html` opens with `<!doctype html>` (a11y/doctype). Set from the same read
+   * as `htmlLang`; absent when the file wasn't read (missing or unreadable) — the rule stays
+   * silent then, like `viteMinifyDisabled`'s absent convention.
+   */
+  appHtmlDoctype?: boolean;
+  /** Literal ids in src/app.html with the line each first appears on — shell content present on every rendered route. Absent when the file wasn't read. */
+  appHtmlIds?: {
+    id: string;
+    line: number;
+  }[];
+  /** Distinct lowercased tag names inside `app.html`'s `<body>` (a11y/required-element's presence set; static mode). */
+  appHtmlBodyTags?: string[];
+}
+declare const defaultProject: Project;
+/** A concrete, agent-actionable remediation for a finding (design §10, issue #18). */
+interface Fix {
+  /** One-line imperative instruction, e.g. 'Add a <meta name="description"> inside <svelte:head>.' */
+  description: string;
+  /** Concrete code to insert or a file's contents to create. */
+  snippet?: string;
+  /** Markdown fenced-code language for `snippet` (default 'svelte'). */
+  lang?: string;
+}
+/** A single rule finding for one route (or the whole project). */
+interface Result {
+  /** Rule id, e.g. 'seo/title-presence'. */
+  id: string;
+  severity: Severity;
+  detection: Detection;
+  /** Route path, e.g. '/blog/[slug]'. Omitted for project-scoped rules. */
+  route?: string;
+  /** Source location, e.g. 'src/routes/blog/[slug]/+page.svelte'. */
+  location?: string;
+  message: string;
+  recommendation?: string;
+  docsUrl?: string;
+  /** Agent-actionable remediation (issue #18). */
+  fix?: Fix;
+  /** Vitals category this finding belongs to (default 'seo' when absent). */
+  category?: Category;
+  /** 1-based source line for element-level findings (e.g. a specific <img>). */
+  line?: number;
+}
+type Scope = 'route' | 'project' | 'component';
+type Category = 'seo' | 'performance' | 'correctness' | 'security' | 'architecture' | 'a11y';
+/**
+ * Every category, as a runtime list — for validating a user-supplied category
+ * name and naming the known ones in the error. One definition so a category
+ * added to `Category` can't be accepted by one validator and rejected by
+ * another. Not an ordering: reporters keep their own display order.
+ */
+declare const CATEGORIES: readonly Category[];
+/** How dynamic (`{data.title}`) values are treated by scoring (design §4, §12). */
+type TreatDynamicAs = 'pass' | 'warn' | 'fail';
+/** Resolved option values handed to a rule at check time. */
+type RuleOptions = Record<string, unknown>;
+/**
+ * Object form of a rule setting. `severity` omitted keeps the rule's built-in
+ * severity — the common case when only a threshold is being moved.
+ * `{ severity: 'off', … }` disables the rule and any `options` beside it are
+ * inert (equivalent to the bare `'off'` string, not an error).
+ */
+interface RuleSettingObject {
+  severity?: Severity | 'off';
+  options?: RuleOptions;
+}
+/** Per-rule override: disable, change severity, and/or set options. */
+type RuleSetting = 'off' | Severity | RuleSettingObject;
+/**
+ * Scoped rule override (design 2026-07-18), applied to results after analysis.
+ * An entry matches a finding when any `route` glob matches its route id or any
+ * `files` glob matches its source location; at least one of the two must be
+ * set. Glob syntax: `*` matches within a segment, `**` across segments, a
+ * trailing `/**` also matches the bare prefix, and all other characters
+ * (including SvelteKit's `(`, `)`, `[`, `]`) are literal.
+ */
+interface RuleOverride {
+  /**
+   * Route-id glob(s), e.g. '/admin/**'. Note route ids drop `(group)` segments
+   * (`src/routes/(app)/dashboard` reports as '/dashboard') — target a group
+   * via `files` instead.
+   */
+  route?: string | string[];
+  /** Source-path glob(s) matched against a finding's location, e.g. 'src/routes/(app)/**'. */
+  files?: string | string[];
+  /** Keys are rule ids ('seo/title-presence') or category names ('seo'). Rule id beats category within an entry. */
+  rules: Record<string, RuleSetting>;
+}
+interface Config {
+  treatDynamicAs: TreatDynamicAs;
+  /** Component names treated as meta sources of unknown content (design §11 layer 4). */
+  metaComponents: string[];
+  /** Per-rule overrides keyed by rule id (design §6). */
+  rules: Record<string, RuleSetting>;
+  /** Minimum severity that fails the run / CI (design §6). */
+  failOn: Severity;
+  /** Per-category weights for the combined Health score (default: equal, 1 each) (#10). */
+  weights?: Partial<Record<Category, number>>;
+  /** Route-/file-scoped rule overrides, applied to results after analysis (later entries win). */
+  overrides?: RuleOverride[];
+}
+declare const defaultConfig: Config;
+/** Merge user config over defaults. Identity helper for config files (design §6). */
+declare function defineConfig(config?: Partial<Config>): Config;
+//#endregion
+//#region src/summary.d.ts
+interface Summary {
+  critical: number;
+  warning: number;
+  info: number;
+  /** Passed (not penalized), including dynamic. */
+  passed: number;
+  /** Subset of passed that resolved dynamically (↯). */
+  dynamic: number;
+}
+/** Classify a single result for display/scoring (design §7, §12). */
+type Classification = 'fail' | 'pass' | 'dynamic';
+declare function classify(result: Result, config: Config): Classification;
+/** A penalized dynamic finding is a warning under treatDynamicAs 'warn'; otherwise the rule's severity. */
+declare function effectiveSeverity(result: Result, config: Config): Severity;
+declare function summarize(results: Result[], config: Config): Summary;
+/** Whether the run should fail the build/CI per the minimum failing severity. */
+declare function hasFailureAtOrAbove(summary: Summary, min: Severity): boolean;
+//#endregion
+//#region src/reporter/github.d.ts
+/**
+ * Render penalized findings as GitHub Actions workflow commands (issue #18, design slice 5).
+ * GitHub turns these into inline PR annotations and run-annotation entries. Returns '' when clean.
+ */
+declare function formatGithubReport(results: Result[], config: Config): string;
+//#endregion
+//#region src/reporter/markdown.d.ts
+/**
+ * Render a compact Markdown summary — Health score, per-category table, severity counts, and
+ * a findings table — suitable for a GitHub Actions job summary or a sticky PR comment
+ * (`svelte-vitals ci install`). Delegates all aggregation to `buildJsonReport` so the numbers
+ * never drift from the JSON/console reporters.
+ */
+declare function formatMarkdownReport(results: Result[], config: Config, meta: {
+  version: string;
+}): string;
+//#endregion
+//#region src/runtime.d.ts
+/**
+ * Runtime abstraction (design §8). Core defines only the interface; concrete
+ * adapters (Node / Deno / Bun) live in the CLI package and are the only place
+ * allowed to touch runtime-specific I/O APIs. Providers and rules use this
+ * interface exclusively, which keeps them runtime-agnostic and lets tests inject
+ * an in-memory implementation.
+ */
+interface Runtime {
+  /** Read a UTF-8 text file. Rejects if the file does not exist. */
+  readFile(path: string): Promise<string>;
+  /** Whether a path exists. */
+  exists(path: string): Promise<boolean>;
+  /**
+   * Paths matching `pattern`, relative to `cwd`.
+   *
+   * **Dot files and dot directories are excluded**, and an adapter must keep it that way: the
+   * directory-shaped Architecture rules derive their directory set from these paths, and one of them
+   * enumerates a parent's children exhaustively, so a `.server/` appearing here would be reported as
+   * an undeclared name. Both shipped adapters pass `dot: false`.
+   *
+   * **Every returned path is a file, never a directory**, and an adapter must keep that true too:
+   * `architecture/reserved-directory-names`' unit test takes a directory's immediate children from
+   * this same inventory and asks whether one of them is a file named after the directory, so an
+   * adapter that let a directory through here would let a bare `Card/Card` satisfy that test as if it
+   * were an entry file. Both shipped adapters get this for free from their glob library's default,
+   * which returns files only unless asked to include directories.
+   */
+  glob(pattern: string, cwd: string): Promise<string[]>;
+  /** Join path segments without depending on `node:path`. */
+  join(...parts: string[]): string;
+}
+/**
+ * How many file reads may be in flight at once. Analysis reads every `.svelte` file in a project
+ * in parallel, which on a large project opens more descriptors than the process is allowed: at
+ * `ulimit -n 1024` — a common container default — a 1 681-route project raised `EMFILE`, and
+ * because a failed read lands in the same `catch` as a malformed component, 682 files were dropped
+ * and the run still reported a normal score. The cap is what keeps the analysis whole.
+ *
+ * 64 is chosen to sit well under the stock 256 on macOS while leaving descriptors for everything
+ * else the process holds open. It is not a throughput knob: reads are a few percent of the work.
+ */
+declare const READ_CONCURRENCY = 64;
+/**
+ * `readFile` with at most `limit` reads in flight. A plain counter plus a queue of waiters —
+ * deliberately not a dependency, and pure enough to live in core.
+ */
+declare function withReadLimit(readFile: (path: string) => Promise<string>, limit?: number): (path: string) => Promise<string>;
+//#endregion
+//#region src/head.d.ts
+/**
+ * A normalized head tag. The mode-independent boundary (design §8): the static
+ * SourceHeadProvider (CLI, via the runtime-abstracted `HeadProvider` below) and
+ * the rendered collector (`@svelte-vitals/vite`, build-time Node) both emit
+ * these, so rules never need to know which mode produced them.
+ */
+interface HeadTag {
+  kind: 'title' | 'meta' | 'link' | 'jsonld' | 'script';
+  /** <meta name="...">. */
+  name?: string;
+  /** <meta property="..."> (e.g. og:image). */
+  property?: string;
+  /** <link rel="...">. */
+  rel?: string;
+  /** <link as="..."> keyword (e.g. 'font') when statically literal; undefined when absent or dynamically bound. */
+  as?: string;
+  /** True when a <link> has an `as` attribute at all (literal or dynamic). Distinguishes "no as" from "dynamic as". */
+  hasAs?: boolean;
+  /** True when a <link> has a `crossorigin` attribute (presence only; value is irrelevant to the checks). */
+  hasCrossorigin?: boolean;
+  /** True when a <meta name="robots"> literal content contains `noindex`/`none`. Undefined when dynamic or absent. */
+  noindex?: boolean;
+  /** Literal `<script type="application/ld+json">` content, set only when the script is static. Undefined when dynamic. */
+  jsonld?: string;
+  /** Literal visible text of a static <title> or <meta name="description"> content, set only when static. Undefined when dynamic. */
+  text?: string;
+  /** Literal `hreflang` of a `<link rel="alternate">` (e.g. 'en', 'en-US', 'x-default'). Undefined when dynamic/absent. */
+  hreflang?: string;
+  /** Literal href (link) / src (script) URL when static — used for third-party origin analysis (performance/preconnect). */
+  href?: string;
+  /** True for a render-blocking `<script src>` in <head> (no defer/async/module) (performance/render-blocking-script). */
+  blocking?: boolean;
+  /** Where this tag was set relative to the route. Never 'none' (absence = no tag). */
+  presence: Exclude<Presence, 'none'>;
+  /** Whether the tag's value is static/dynamic/absent (design §4). */
+  value: Value;
+  /** Source file the tag came from (static mode); unset on a rendered head. */
+  file?: string;
+}
+/** Resolved effective head for a single route (design §8). */
+interface ResolvedHead {
+  /** Route path, e.g. '/blog/[slug]'. */
+  route: string;
+  /** Which provider produced this. */
+  source: 'static' | 'rendered';
+  /** Effective head tags after layout-chain composition. */
+  tags: HeadTag[];
+  /** Representative source file for the route (used for issue locations). */
+  file: string;
+}
+/**
+ * Supplies ResolvedHead[] for a project through the runtime abstraction. The
+ * static (CLI) mode implements this; rendered mode reads prerendered HTML at
+ * build time and emits the same ResolvedHead[] without the runtime indirection.
+ */
+interface HeadProvider {
+  mode: 'static' | 'rendered';
+  collect(rt: Runtime, cwd: string, config?: Config): Promise<ResolvedHead[]>;
+}
+//#endregion
+//#region src/images.d.ts
+/**
+ * A normalized <img> occurrence — the mode-independent boundary for Performance
+ * rules (mirrors head.ts). Attribute presence only: a dynamically-bound attribute
+ * (width={w}) still counts as present, so dynamic values are never flagged.
+ */
+interface ImageInfo {
+  hasWidth: boolean;
+  hasHeight: boolean;
+  hasLoading: boolean;
+  /** True when the <img> has an `alt` attribute at all (incl. empty `alt=""` decorative; seo/image-alt). */
+  hasAlt: boolean;
+  /** True when the <img> has a literal `loading="lazy"` (performance/lcp-image). Dynamic/spread → false. */
+  lazy: boolean;
+  /** True when the <img> has a `srcset` attribute (performance/responsive-image). */
+  hasSrcset: boolean;
+  /** 1-based source line, or 0 if unknown. */
+  line: number;
+  /** Source file the <img> came from. */
+  file: string;
+}
+/** Resolved <img> elements for a single route (page + layout chain). */
+interface ResolvedImages {
+  route: string;
+  images: ImageInfo[];
+}
+//#endregion
+//#region src/headings.d.ts
+/**
+ * A normalized page-body heading occurrence — the mode-independent boundary for
+ * the heading-hierarchy rule (mirrors images.ts). Both providers collect these
+ * so seo/single-h1 never needs to know which mode produced them.
+ */
+interface HeadingInfo {
+  /** Heading level 1–6 (the `n` in <hn>). */
+  level: number;
+  /** 1-based source line, or 0 if unknown (rendered mode does not track lines). */
+  line: number;
+  /** Source file the heading came from. */
+  file: string;
+}
+/** Resolved page-body headings for a single route (page + layout chain). */
+interface ResolvedHeadings {
+  route: string;
+  headings: HeadingInfo[];
+  /**
+   * Headings found in child components rendered (transitively) by this route's
+   * chain files — source mode only; absent in rendered mode. Kept separate from
+   * `headings` because their position in document order is unknown: safe for
+   * counting (seo/single-h1), unusable for outline order (seo/heading-level-skip).
+   */
+  componentHeadings?: HeadingInfo[];
+}
+//#endregion
+//#region src/a11y.d.ts
+/** One step of a template branch address: which exclusive block, and which arm of it. */
+interface BranchStep {
+  /** index of the {#if}/{#await} block among its file's blocks (document order) */
+  group: number;
+  /** branch index within the group (if: 0..n consequent→else; await: 0=pending,1=then,2=catch) */
+  branch: number;
+}
+/** Where a folded occurrence sits, for the finding location. */
+interface A11yOccurrenceInfo {
+  file: string;
+  line: number;
+}
+/** One reason a route's closed world failed to hold, with the first offending location. */
+interface A11ySkipCause {
+  kind: 'component' | 'spread' | 'html' | 'dynamic-id';
+  file: string;
+  line: number;
+  /** for kind 'component': the unresolvable component's name as written */
+  detail?: string;
+}
+/**
+ * Route-scoped a11y facts, the mode-independent boundary for the landmark/id rules
+ * (mirrors headings.ts). Source mode composes the layout chain plus its resolved
+ * components; rendered mode reads the prerendered document.
+ */
+interface ResolvedA11y {
+  route: string;
+  /** representatives per landmark kind after the branch-aware fold ('main' | 'banner' | 'contentinfo' | 'complementary') */
+  landmarks: Record<string, A11yOccurrenceInfo[]>;
+  /** landmark occurrences nested inside another landmark after composition */
+  nestedLandmarks: {
+    kind: string;
+    within: string;
+    file: string;
+    line: number;
+  }[];
+  /** representatives per literal id */
+  ids: Record<string, A11yOccurrenceInfo[]>;
+  /** literal id references */
+  idRefs: {
+    id: string;
+    attr: string;
+    file: string;
+    line: number;
+  }[];
+  /** optimistic candidates: every literal id anywhere (all branches, each/snippet bodies, components, app.html) */
+  idCandidates: string[];
+  /** closed world holds: every component resolved, no depth truncation, no {@html}/spread, no dynamic id */
+  fullyResolved: boolean;
+  /** Why `fullyResolved` is false — deduped by (kind, file, detail), first occurrence's line kept. Present exactly when `fullyResolved` is false. */
+  unresolvedCauses?: A11ySkipCause[];
+  /**
+   * Distinct tag names in the route's body subtree — layout chain, page, every resolved component,
+   * and `app.html`'s `<body>` (static), or the prerendered `<body>` (rendered); optimistic across
+   * `{#if}` arms and `{#each}`/snippet bodies. Never `<svelte:head>` content, `<template>` children,
+   * or `<svelte:element>`. Absent where a provider does not collect it (a11y/required-element).
+   */
+  elementTags?: string[];
+  /**
+   * The closed world for elements: every component descended into (an unresolved, depth-truncated,
+   * or — conservatively — cycle-cut one clears it), no `{@html}`, no `<svelte:element>`. Incomparable with `fullyResolved` — a spread or `id={expr}` clears that flag
+   * and not this one, since neither can hide an element; a `<svelte:element>` clears this and not
+   * that. "Missing" is only reportable when this holds; presence is sound regardless.
+   */
+  elementsClosed?: boolean;
+  /** The file a route-level finding is anchored to: the page file (static) or the prerendered HTML path (rendered). */
+  file?: string;
+}
+type Foldable = {
+  key: string;
+  path: BranchStep[];
+  repeatable: boolean;
+};
+/**
+ * Branch-aware occurrence fold (design "Control-flow semantics"): within a branch
+ * occurrences sum, across the arms of one exclusive block the arm with the most
+ * occurrences wins (tie → lowest branch index) and ITS occurrences are the group's
+ * representatives — so a caller's count is always `list.length`, with a location per
+ * representative. `{#each}`/`{#snippet}` occurrences render 0..N times and drop out.
+ * The max is per key: there is no scalar total to maximize.
+ */
+declare function foldOccurrences<T extends Foldable>(nodes: T[]): Map<string, T[]>;
+/**
+ * Decode a fragment identifier the way navigation does before matching an element id
+ * (`href="#caf%C3%A9"` targets `id="café"`). Malformed escapes are kept verbatim —
+ * the browser would also fail to decode them, so the raw text is the comparable form.
+ */
+declare function decodeFragmentId(fragment: string): string;
+/** Whitespace-split tokens of a (possibly undefined) literal attribute value. */
+declare function splitTokens(value: string | undefined): string[];
+/** Explicit `role` values that map to the landmark kinds the route rules inspect. */
+declare const LANDMARK_ROLES: ReadonlySet<string>;
+/**
+ * Attributes whose (whitespace-tokenized) values reference element ids: the ARIA id-reference and
+ * id-reference-list properties, and HTML's own (`for`, `list`, `headers`, `form`, the popover and
+ * command targets). `href="#…"` is handled separately — its value is a URL, not a token list.
+ */
+declare const IDREF_ATTRS: readonly string[];
+/**
+ * Whether a decoded URL fragment is HTML's "top of the document" indicator: `#top` (ASCII
+ * case-insensitive) scrolls to the top when no element has that id, so it is never a missing
+ * reference. Compare AFTER percent-decoding — `#%74op` navigates identically to `#top`.
+ */
+declare function isTopFragment(id: string): boolean;
+/**
+ * A fragment with its text directive removed. Everything from the first `:~:` on is user-agent
+ * instructions for finding text and names no element, while anything before it is still an
+ * ordinary element fragment — `#section:~:text=hi` targets `id="section"`, `#:~:text=hi` targets
+ * nothing. Returns an empty string when the fragment is a directive and nothing else.
+ */
+declare function stripTextDirective(fragment: string): string;
+//#endregion
+//#region src/kit-module.d.ts
+/**
+ * Facts parsed from one SvelteKit route/hooks file for the SSR shared-state rules
+ * (the security kit-module rules). Collected by `collectKitModuleFacts` (static/CLI + vite build mode).
+ */
+interface KitModuleFacts {
+  /** Repo-relative source file. */
+  file: string;
+  /** 'server' = runs only on the server (+*.server, +server, hooks.server); 'universal' = +page.ts/+layout.ts (still runs on the server during SSR). */
+  kind: 'server' | 'universal';
+  /** Module-scope let/var reassigned from inside a function (security/server-module-state). */
+  moduleStateReassignments: {
+    name: string;
+    line: number;
+    inHandler: boolean;
+  }[];
+  /** Writes to an imported binding from inside an exported handler (security/handler-state-write). */
+  importedStateWrites: {
+    name: string;
+    line: number;
+    via: 'assignment' | 'set-call';
+  }[];
+  /** Writes to an imported binding outside handlers — top level or helper functions (security/shared-state-import's write flavour). */
+  importedStateWritesOutsideHandlers: {
+    name: string;
+    line: number;
+  }[];
+  /**
+   * `.set()`/`.update()` in a handler on an import resolving under the `$lib` server root.
+   * The call shape alone cannot tell a persistence client (`db.set(…)`) from a hand-rolled
+   * in-memory store, so the decision needs the target module — which this pure parse cannot
+   * read. `collectKitModuleFacts` resolves each one and promotes the in-memory ones into
+   * `importedStateWrites`; a consumer that ignores this field sees the pre-arbitration
+   * behaviour, i.e. every one of these exempt.
+   */
+  pendingServerStoreWrites: {
+    name: string;
+    imported: string;
+    resolved: string;
+    line: number;
+  }[];
+  /** Value imports whose specifier resolves to a repo-local `.svelte.ts`/`.svelte.js` runes module (security/shared-state-import). */
+  runesModuleImports: {
+    source: string;
+    resolved: string;
+    names: string[];
+    line: number;
+  }[];
+  /** Svelte lifecycle/context calls that run outside component initialisation — top level, handler bodies, or the `init` hook (correctness/orphan-lifecycle). */
+  lifecycleCalls: {
+    name: string;
+    line: number;
+    inHandler: boolean;
+  }[];
+  /** Browser-global reads in server-executed positions — top level, handler bodies, the `init` hook (correctness/server-browser-global). Empty when the file itself exports `ssr = false`. */
+  browserGlobalRefs: {
+    name: string;
+    line: number;
+    inHandler: boolean;
+  }[];
+  /** Root-relative `redirect()` literals in this Kit module (correctness/base-path-navigation). */
+  basePathLinks: BasePathLinkFact[];
+  /** Set when this file disables SSR via `export const ssr = false` (inline or same-file alias export) — the declaration's line (seo/ssr-disabled). */
+  ssrDisabled?: {
+    line: number;
+  };
+  /** Set when this file disables client-side rendering via `export const csr = false` (inline or same-file alias export). With no client runtime, a universal load only runs during SSR — performance/load-waterfall's browser-waterfall premise doesn't hold. */
+  csrDisabled?: {
+    line: number;
+  };
+  /** Sequential-await analysis of the exported `load` function (performance/load-waterfall, performance/sequential-awaits): 1-based lines of await sites that depend on an earlier await's result, and of sites independent of all earlier awaits. Set only when at least one list is non-empty. */
+  loadWaterfalls?: {
+    dependentLines: number[];
+    independentLines: number[];
+  };
+  /** Inline `svelte-vitals-disable-next-line` directives in this file. */
+  suppressions: SuppressionDirective[];
+  /** Set when the file failed to read or parse and these facts are the empty fallback — the file was NOT analyzed. */
+  parseFailed?: true;
+  /** Set when the file could not be READ — an environment problem, not a malformed module. */
+  readFailed?: true;
+}
+//#endregion
+//#region src/config-apply.d.ts
+/** The severity a setting selects: `'off'`, an explicit severity, or undefined (leave the built-in). */
+declare function settingSeverity(setting: RuleSetting | undefined): Severity | 'off' | undefined;
+/** The options a setting carries, or undefined for the string forms. */
+declare function settingOptions(setting: RuleSetting | undefined): RuleOptions | undefined;
+/** Drop rules disabled via config (design §6), including a `defaultOff` rule with no entry. */
+declare function selectRules(rules: Rule[], config: Config): Rule[];
+/**
+ * `config` with `failedRuleIds` (from `runRules`' `failedRules`) forced `'off'`: a rule that threw
+ * examined nothing, so leaving it in the inventory would score it as if it had run clean, silently
+ * inflating Health. Reuses the exact mechanism a `rules: { id: 'off' }` config entry already gets —
+ * `selectRules`/`buildInventory` both drop an `'off'` id from the denominator — rather than adding a
+ * second, parallel notion of "not counted" for callers to keep in sync.
+ */
+declare function withFailedRulesOff(config: Config, failedRuleIds: readonly string[]): Config;
+/** One-line "rule failed and was skipped" warning; capped to the message's first line so a stack trace can't flood a terminal. */
+declare function formatFailedRuleWarning(f: {
+  id: string;
+  message: string;
+}): string;
+/** Apply per-rule severity overrides to results (design §6). */
+declare function applyRuleSeverities(results: Result[], config: Config): Result[];
+/** An override entry with its globs compiled once. Build with `compileOverrides`. */
+interface CompiledOverride {
+  routes: RegExp[];
+  files: RegExp[];
+  rules: Record<string, RuleSetting>;
+}
+/**
+ * Compile every override entry's globs to RegExp, once. Callers that match many
+ * targets (every component, every route) must hoist this out of their loop.
+ */
+declare function compileOverrides(config: Config): CompiledOverride[];
+/**
+ * Whether an override entry applies to a target. THE single definition of that
+ * question — the result post-pass and in-run option resolution both call it.
+ * Sharing this matcher is necessary but not sufficient for a severity override
+ * and an option override to select the same files: each caller must also pass
+ * the same `target` (route and, critically, `file`) the other path effectively
+ * matches against. See Finding 1, docs/superpowers/specs/2026-07-26-rule-options-design.md.
+ */
+declare function overrideMatches(o: CompiledOverride, target: {
+  route?: string;
+  file?: string;
+}): boolean;
+/**
+ * Apply route-/file-scoped overrides to results (design 2026-07-18). An entry
+ * matches when any `route` glob matches the finding's route id or any `files`
+ * glob matches its location (OR). `'off'` removes a matched result entirely —
+ * passing seeds included, so scoring and "checks passed" counts behave as if
+ * the rule never ran there. A severity value rewrites the result's severity.
+ * Entries are evaluated in order (later entries win); within one entry, a
+ * rule-id key beats a category key only when it specifies a `severity` — an
+ * options-only rule-id key (no `severity`) contributes its options but leaves
+ * the category key's severity in force, rather than shadowing it (design
+ * 2026-07-26, Finding 2 / second review Finding E).
+ */
+declare function applyOverrides(results: Result[], config: Config): Result[];
+//#endregion
+//#region src/rule-options.d.ts
+/**
+ * One configurable option. `kind` decides the merge semantics, so no rule
+ * writes merge code of its own: `integer` replaces, and the two collection
+ * kinds ADD to the built-in default (never replace — see the design doc).
+ */
+type RuleOptionSpec = {
+  kind: 'integer';
+  default: number;
+  min?: number;
+  max?: number;
+} | {
+  kind: 'string-list';
+  default: readonly string[];
+  /**
+   * Grammar every entry must match, checked at config load. A declaration-driven rule reserves
+   * its grammar with this so a value the rule does not interpret today (`'input[type=file]'`
+   * for a tag-name list) is rejected rather than accepted-and-ignored — accepting it would make
+   * giving it meaning later a reinterpretation of a value the frozen schema already took.
+   */
+  pattern?: {
+    regex: RegExp;
+    describe: string;
+  };
+} | {
+  kind: 'string-map';
+  default: Readonly<Record<string, string>>;
+};
+/** A rule's configurable options, keyed by option name. */
+type RuleOptionsSpec = Record<string, RuleOptionSpec>;
+/**
+ * Typed reads of a resolved options object. `RuleOptions` values are `unknown`
+ * (the map is open-ended by design), so without these every rule would carry
+ * its own `o.max as number` cast and the "resolution guarantees the declared
+ * kind" invariant would live in a dozen places instead of one. `resolveRuleOptions`
+ * always seeds every declared key from the spec default and validation rejects a
+ * wrongly-typed value up front, so a mismatch here means a rule read a key it
+ * never declared — the `fallback` keeps that a wrong number rather than a crash.
+ */
+declare function intOption(options: RuleOptions, key: string, fallback?: number): number;
+/** As `intOption`, for a `string-list` option. */
+declare function listOption(options: RuleOptions, key: string): string[];
+/** As `intOption`, for a `string-map` option. */
+declare function mapOption(options: RuleOptions, key: string): Record<string, string>;
+/**
+ * Whether any config layer so much as mentions `ruleId` — its `rules` entry, or any `overrides`
+ * entry's.
+ *
+ * A rule that is inert until declared can return early on `false` instead of resolving options once
+ * per target and discarding the result. That waste is not hypothetical: the three directory-shaped
+ * Architecture rules resolve per directory, so an unconfigured project pays it for every directory
+ * under `src/` three times over, on every dev-server save. Measured 2026-07-30 over a synthetic tree
+ * of 1,523 directories: 5.4 ms per analysis, for rules that are off by default and therefore produce
+ * nothing.
+ *
+ * Deliberately conservative. It asks only whether the rule is *mentioned*, not whether the mention
+ * resolves to a non-empty value, so a `'off'` severity with no options still answers `true` and the
+ * caller does its normal work. A cheaper-but-wrong version of this would make a rule skip work it
+ * owed; this one can only ever fail to save time.
+ */
+declare function isMentionedAnywhere(config: Config, ruleId: string): boolean;
+/**
+ * Effective options for a rule at a target: built-in defaults, then
+ * `config.rules[ruleId].options`, then every matching `config.overrides` entry
+ * in order. Integers take the last value; lists and maps accumulate.
+ *
+ * `target` omitted skips overrides entirely (project-scoped rules). Callers
+ * resolving many targets should hoist `compileOverrides(config)` and pass it as
+ * `compiled` — otherwise every call recompiles the globs.
+ */
+declare function resolveRuleOptions(ruleId: string, spec: RuleOptionsSpec | undefined, config: Config, target?: {
+  route?: string;
+  file?: string;
+}, compiled?: CompiledOverride[]): RuleOptions;
+/**
+ * Problems with a user-supplied options object, as human-readable sentences
+ * (empty = valid). Callers treat any result as fatal: a typo that silently
+ * leaves the config inert is the failure this exists to prevent.
+ *
+ * `baseline`, when given, is the already-resolved value this `options` layer
+ * is being merged onto — built-in defaults merged with any earlier layer(s)
+ * (e.g. the global `config.rules[id].options`, when `options` is an
+ * `overrides[]` entry). The min/max cross-check below compares against it
+ * instead of the spec's own default, so a layer that only sets one side of a
+ * range is checked against what it actually inherits (design 2026-07-26
+ * review, Finding A). Omit it to check `options` against the spec defaults
+ * alone, as when validating the global layer itself. A `baseline` that is
+ * only partially resolved (missing `min` or `max`) is treated as "can't
+ * determine that side" rather than silently comparing against `undefined` —
+ * see the `typeof` guard below.
+ *
+ * `skipRangeCheck`, when true, skips the min/max cross-check entirely
+ * regardless of `baseline`. A caller sets this when it statically cannot
+ * rule out that some *other* config layer narrows the opposite side of the
+ * range at the same target — see the CLI's and the Vite plugin's
+ * `overrides[]` validation (design 2026-07-26 review, Finding A, third
+ * pass).
+ */
+declare function validateRuleOptions(ruleId: string, spec: RuleOptionsSpec | undefined, options: RuleOptions, baseline?: RuleOptions, skipRangeCheck?: boolean): string[];
+/**
+ * Whether `validateRuleOptions` should skip the min/max cross-check for
+ * `overrides[selfIndex].rules[key]` — the whole decision, so the CLI's
+ * config-file loader and the Vite plugin can't drift apart on it (they held
+ * line-for-line copies of it before).
+ *
+ * An entry that sets both sides, or neither, is judged against its baseline as
+ * usual. An entry that sets only one side is skipped when some *other* entry
+ * sets the opposite side, since the two may co-apply at a shared target and be
+ * valid there — see `otherOverrideNarrowsOppositeSide` for why that is
+ * conservative by necessity and what it lets through.
+ */
+declare function shouldSkipRangeCheck(overrides: readonly unknown[], selfIndex: number, key: string, setting: unknown): boolean;
+/**
+ * Problems with one user-supplied rule setting — the bare severity string or the
+ * object form — as human-readable sentences prefixed with `label` (empty = valid).
+ * THE single definition of what a setting may look like: the CLI's config-file
+ * loader and the Vite plugin both funnel through it, so a config file and the
+ * equivalent plugin option are accepted or rejected identically. Callers treat any
+ * result as fatal, on the same reasoning as an unknown rule id — a typo that
+ * silently leaves the config inert is the failure being prevented.
+ *
+ * `label` names the setting in the message (e.g. `rules.seo/title-length`,
+ * `overrides[0].rules.architecture`); `ruleId` is the key options messages quote.
+ * `allowOptions` is false for a category key: a category may carry a severity, but
+ * options are rule-specific and meaningless there. `baseline` and `skipRangeCheck`
+ * are passed through to `validateRuleOptions`.
+ */
+declare function validateRuleSetting(label: string, ruleId: string, setting: unknown, spec: RuleOptionsSpec | undefined, opts: {
+  allowOptions: boolean;
+  baseline?: RuleOptions;
+  skipRangeCheck?: boolean;
+}): string[];
+//#endregion
+//#region src/rule.d.ts
+/** Input given to every rule. Mode-independent: rules see only ResolvedHead[] (design §8, §10). */
+interface RuleContext {
+  heads: ResolvedHead[];
+  /** Per-route <img> elements for Performance rules (absent in modes that don't collect them). */
+  images?: ResolvedImages[];
+  /** Per-route page-body headings for seo/single-h1 (absent in modes that don't collect them). */
+  headings?: ResolvedHeadings[];
+  /** Per-route composed landmark/id occurrences for the route-scoped a11y rules (absent in modes that don't collect them). */
+  a11y?: ResolvedA11y[];
+  /** Per-file component-body facts for the component-scoped rules (absent in the dev handle's rendered pass). */
+  components?: ComponentFacts[];
+  /** Per-file SvelteKit route/hooks facts for the kit-module rules (absent in the dev handle's rendered pass). */
+  kitModules?: KitModuleFacts[];
+  /**
+   * Every file under `src/`, as project-relative paths, for directory-shaped Architecture rules
+   * (static/CLI + vite build mode only). Sorted — see `collectSourceFiles`, which is what both
+   * adapters use to build it.
+   */
+  sourceFiles?: string[];
+  project: Project;
+  config: Config;
+  /**
+   * Report per-declaration counts of places this rule examined. The engine supplies it and keys the
+   * result by rule id; a rule that does not call it gets no entry, which is distinct from an entry of
+   * zeros. Absent in contexts a caller builds directly. Silent last-write-wins: calling it more than
+   * once keeps only the most recent map, with no merge and no error — call it once, with the complete
+   * counts, at the end of `check()`.
+   */
+  recordExamined?: (counts: Record<string, number>) => void;
+}
+interface Rule {
+  id: string;
+  title: string;
+  category: Category;
+  /** Default severity (overridable by config in later slices). */
+  severity: Severity;
+  /** 'route' = evaluated per route, 'project' = site-wide, 'component' = evaluated per source file (design §10, §12). */
+  scope: Scope;
+  /** Why this rule matters — one or two sentences, surfaced by `svelte-vitals explain` (issue #24). */
+  rationale: string;
+  /** Canonical remediation template, shared by findings and `svelte-vitals explain` (issue #24). */
+  fix?: Fix;
+  /** Configurable options for this rule; absent means the rule takes none. */
+  options?: RuleOptionsSpec;
+  /**
+   * The message this rule puts on a PASS result. Declared so a PASS synthesised elsewhere — the
+   * central inline-suppression pass, which turns a fully-suppressed rule+route into a pass — reads
+   * the same as one the rule emitted itself. Rules built through `componentRule` and the a11y
+   * route factory supply it; the rest fall back to `title`, which is a cosmetic difference visible
+   * only in `--verbose`'s passed listing.
+   */
+  passLabel?: string;
+  /** Off unless config.rules names the rule explicitly — the opt-in class (design 2026-08-21). */
+  defaultOff?: true;
+  /**
+   * The rule compares routes against each other (`seo/duplicate-title`), so it cannot be judged
+   * from one route's rendered HTML — the dev dashboard's live layer leaves it to the static pass.
+   */
+  crossRoute?: true;
+  /**
+   * Evaluate the resolved heads. A single rule may return one Result per route,
+   * so it always returns an array. Project-scoped rules return a single element.
+   */
+  check(ctx: RuleContext): Promise<Result[]>;
+}
+/** Documentation URL for a rule id. Single source so no per-rule URL can drift (issue #24). */
+declare function docsUrlFor(id: string): string;
+/**
+ * Whether a detection should be penalized by scoring (design §12). Shared by the
+ * future Scorer and by the Slice 0 reporter so pass/fail is decided in one place.
+ *
+ *   presence 'none'            → penalized (nothing set anywhere)
+ *   value 'absent'             → penalized (tag present but empty)
+ *   value 'dynamic'            → penalized when treatDynamicAs is not 'pass' (warn or fail)
+ *   otherwise (static/inherited) → not penalized
+ */
+declare function isPenalized(detection: Detection, treatDynamicAs: TreatDynamicAs): boolean;
+//#endregion
+//#region src/scoring/score.d.ts
+interface ScoreModel {
+  routeAverage: number;
+  sitePenalty: number;
+  /** Headline cap value when it actually lowered the score, else null. */
+  criticalCap: number | null;
+}
+interface ScoreResult {
+  /** The score as displayed: `Math.floor(rawScore)`, so 100 means the deduction was exactly zero. */
+  score: number;
+  /**
+   * The same score before flooring, after `sitePenalty` and the cap, clamped to `[0, 100]`. Exposed so
+   * `computeHealth` can average unrounded values and floor once — averaging the displayed scores would
+   * compose two roundings and move Health by up to two points.
+   */
+  rawScore: number;
+  scoreModel: ScoreModel;
+  /** Keys this result set touched. */
+  keys: number;
+  /** Keys carrying at least one penalized finding. */
+  affectedKeys: number;
+}
+interface ScoreOptions {
+  applyCriticalCap?: boolean;
+  /** The rules that ran. Defaults to the selected registry; supplied by tests and custom rule sets. */
+  rules?: readonly Rule[];
+}
+/** Compute the headline score and its breakdown (design §12). */
+declare function computeScore(results: Result[], config: Config, options?: ScoreOptions): ScoreResult;
+/** Compute an independent score per category present in `results` (issue #10). */
+declare function scoresByCategory(results: Result[], config: Config, options?: ScoreOptions): Partial<Record<Category, ScoreResult>>;
+interface HealthResult {
+  /** Weighted overall score across present categories (0–100). */
+  health: number;
+  categories: Partial<Record<Category, ScoreResult>>;
+  /** Effective weight used per present category. */
+  weights: Partial<Record<Category, number>>;
+}
+/** Combined weighted Health score over the categories present in `results` (#10). */
+declare function computeHealth(results: Result[], config: Config): HealthResult;
+//#endregion
+//#region src/reporter/json.d.ts
+declare function issueOf(result: Result): {
+  fix?: Fix | undefined;
+  docsUrl?: string | undefined;
+  recommendation: string | undefined;
+  line?: number | undefined;
+  id: string;
+  category: Category;
+  title: string;
+  detection: Detection;
+  location: string | undefined;
+};
+type JsonIssue = ReturnType<typeof issueOf> & {
+  severity: ReturnType<typeof effectiveSeverity>;
+};
+/**
+ * Per-rule counts. A rule present with `findings: 0` ran and reported nothing, and an absent rule was not
+ * selected — but only when the caller supplied `ruleIds`. Without it the map is seeded from results alone,
+ * so absence means "produced nothing" rather than "not selected".
+ */
+interface RuleEvidence {
+  findings: number;
+  passed: number;
+}
+interface JsonReport {
+  version: string;
+  score: number;
+  weights: Partial<Record<Category, number>>;
+  categories: Record<string, {
+    score: number;
+    scoreModel: ScoreModel;
+    keys: number;
+    affectedKeys: number;
+  }>;
+  summary: Summary;
+  rules: Record<string, RuleEvidence>;
+  routes: Array<{
+    route: string;
+    score: number;
+    categories: Record<string, number>;
+    issues: JsonIssue[];
+  }>;
+  siteIssues: JsonIssue[];
+  /**
+   * Floored severity weight per `"<category>::<scope>"` pair. Reproduces a `routes[].categories` entry
+   * (`100 - 100 * failed / inventories[pair]`): a key is either a route id or a source file path, and
+   * those two key spaces never overlap, so a category's results on one key always draw on a single scope.
+   * It does not reproduce `routes[].score`: a route spanning more than one pair sums their *raw* weights
+   * and floors that sum once, so adding this map's already-floored entries and re-dividing can disagree.
+   */
+  inventories: Record<string, number>;
+  /**
+   * Per-rule, per-declaration counts of places examined. Unlike `rules`, this describes the analysis
+   * rather than the report: `--diff`, `--baseline` and suppressions do not narrow it. Three states: a
+   * rule that reports no counts has no entry; a rule that counts but whose configuration declares
+   * nothing has an empty entry; a declaration that judged nothing has an entry of `0`.
+   */
+  examined?: Record<string, Record<string, number>>;
+  /**
+   * Routes a closed-world rule skipped, keyed by rule id. Like `examined`, this describes the
+   * analysis rather than the report: `--diff`, `--baseline` and suppressions do not narrow it.
+   * `refs` is the route's literal id-reference count — a skipped route with `refs: 0` would
+   * produce nothing even if unlocked. Only source-mode analysis populates it; absent when no
+   * analyzed route was skipped.
+   */
+  skipped?: Record<string, Array<{
+    route: string;
+    refs: number;
+    causes: Array<{
+      kind: string;
+      file: string;
+      line: number;
+      detail?: string;
+    }>;
+  }>>;
+}
+/** Build the structured JSON report object (design §7). The shape the `json` reporter emits (issue #24). */
+declare function buildJsonReport(results: Result[], config: Config, meta: {
+  version: string;
+}, ruleIds?: readonly string[], examined?: Record<string, Record<string, number>>, skipped?: JsonReport['skipped']): JsonReport;
+/** Render results as the documented JSON report string (design §7). */
+declare function formatJsonReport(results: Result[], config: Config, meta: {
+  version: string;
+}, ruleIds?: readonly string[], examined?: Record<string, Record<string, number>>, skipped?: JsonReport['skipped']): string;
+//#endregion
+export { HeadTag as $, formatFailedRuleWarning as A, defaultProject as At, IDREF_ATTRS as B, shouldSkipRangeCheck as C, RuleSetting as Ct, applyOverrides as D, TreatDynamicAs as Dt, CompiledOverride as E, Severity as Et, withFailedRulesOff as F, OrphanEffectFact as Ft, isTopFragment as G, ResolvedA11y as H, KitModuleFacts as I, SourceSpan as It, HeadingInfo as J, splitTokens as K, A11yOccurrenceInfo as L, SuppressionDirective as Lt, selectRules as M, ComponentFacts as Mt, settingOptions as N, EachBlockFact as Nt, applyRuleSeverities as O, Value as Ot, settingSeverity as P, EffectFact as Pt, HeadProvider as Q, A11ySkipCause as R, skippedFileWarnings as Rt, resolveRuleOptions as S, RuleOverride as St, validateRuleSetting as T, Scope as Tt, decodeFragmentId as U, LANDMARK_ROLES as V, foldOccurrences as W, ImageInfo as X, ResolvedHeadings as Y, ResolvedImages as Z, RuleOptionsSpec as _, KitAlias as _t, HealthResult as a, formatGithubReport as at, listOption as b, Result as bt, ScoreResult as c, classify as ct, scoresByCategory as d, summarize as dt, ResolvedHead as et, Rule as f, CATEGORIES as ft, RuleOptionSpec as g, Fix as gt, isPenalized as h, Detection as ht, formatJsonReport as i, formatMarkdownReport as it, overrideMatches as j, defineConfig as jt, compileOverrides as k, defaultConfig as kt, computeHealth as l, effectiveSeverity as lt, docsUrlFor as m, Config as mt, RuleEvidence as n, Runtime as nt, ScoreModel as o, Classification as ot, RuleContext as p, Category as pt, stripTextDirective as q, buildJsonReport as r, withReadLimit as rt, ScoreOptions as s, Summary as st, JsonReport as t, READ_CONCURRENCY as tt, computeScore as u, hasFailureAtOrAbove as ut, intOption as v, Presence as vt, validateRuleOptions as w, RuleSettingObject as wt, mapOption as x, RuleOptions as xt, isMentionedAnywhere as y, Project as yt, BranchStep as z };