npm - @svelte-vitals/core - Versions diffs - 0.43.0 → 0.44.0 - Mend

@svelte-vitals/core 0.43.0 → 0.44.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md +12 -1
package/dist/chunk-2N7E4JFX.js +30 -0
package/dist/index-CWWQEu8q.d.ts +1138 -0
package/dist/index.d.ts +1 -1953
package/dist/index.js +5 -8477
package/dist/internal.d.ts +883 -0
package/dist/internal.js +8642 -0
package/package.json +10 -5

package/dist/index-CWWQEu8q.d.ts ADDED Viewed

@@ -0,0 +1,1138 @@
+/**
+ * Core type definitions shared across modes. This module is pure: no I/O, no
+ * `node:` imports, no runtime-specific globals (design §8).
+ */
+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).
+     */
+    viteMinifyDisabled?: {
+        file?: string;
+        line?: number;
+    };
+    /**
+     * 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 `id` attributes in `src/app.html`, from the same read as `htmlLang`. The shell is part
+     * of every rendered document, so its ids satisfy a route's id references (a11y/no-missing-id-ref);
+     * absent when the file wasn't read.
+     */
+    appHtmlIds?: 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;
+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;
+/**
+ * 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>;
+/**
+ * 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 only). */
+    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[]>;
+}
+/**
+ * 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[];
+}
+/**
+ * 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[];
+}
+/** 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;
+}
+/**
+ * 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;
+}
+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. */
+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;
+/**
+ * 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;
+    /** 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;
+}
+/** 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[];
+    /** 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[];
+/**
+ * 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;
+}
+/** 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). */
+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[];
+/**
+ * Per-rule options: their declaration, resolution, and validation (design
+ * 2026-07-26). Deliberately does not import `rule.ts` — `rule.ts` imports
+ * `RuleOptionsSpec` from here, so taking `Rule` as a parameter would cycle.
+ * Callers pass the id and the spec instead.
+ */
+/**
+ * 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[];
+} | {
+    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[];
+/** 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 Correctness rules (static/CLI mode only). */
+    components?: ComponentFacts[];
+    /** Per-file SvelteKit route/hooks facts for the SSR shared-state rules (static/CLI + vite build mode only). */
+    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;
+    /**
+     * 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;
+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;
+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>>;
+}
+/** 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>>): 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>>): string;
+export { formatFailedRuleWarning as $, type A11yOccurrenceInfo as A, type BranchStep as B, type ComponentFacts as C, applyRuleSeverities as D, type EachBlockFact as E, type Fix as F, buildJsonReport as G, type HeadTag as H, type ImageInfo as I, type JsonReport as J, type KitAlias as K, LANDMARK_ROLES as L, classify as M, compileOverrides as N, type OrphanEffectFact as O, type Project as P, computeHealth as Q, type Runtime as R, type SuppressionDirective as S, computeScore as T, decodeFragmentId as U, type Value as V, defaultConfig as W, defaultProject as X, docsUrlFor as Y, effectiveSeverity as Z, foldOccurrences as _, type KitModuleFacts as a, formatJsonReport as a0, hasFailureAtOrAbove as a1, intOption as a2, isMentionedAnywhere as a3, isPenalized as a4, isTopFragment as a5, listOption as a6, mapOption as a7, overrideMatches as a8, resolveRuleOptions as a9, scoresByCategory as aa, selectRules as ab, settingOptions as ac, settingSeverity as ad, shouldSkipRangeCheck as ae, skippedFileWarnings as af, splitTokens as ag, stripTextDirective as ah, summarize as ai, validateRuleOptions as aj, validateRuleSetting as ak, withFailedRulesOff as al, withReadLimit as am, CATEGORIES as an, type Detection as ao, type Presence as ap, type RuleEvidence as aq, type RuleOptions as ar, type RuleOverride as as, type RuleSetting as at, type RuleSettingObject as au, type ScoreModel as av, type Summary as aw, type TreatDynamicAs as ax, defineConfig as ay, type Rule as b, type RuleContext as c, type Result as d, type Category as e, type Severity as f, type RuleOptionSpec as g, type ResolvedHead as h, type Config as i, type Classification as j, type CompiledOverride as k, type EffectFact as l, type HeadProvider as m, type HeadingInfo as n, type HealthResult as o, IDREF_ATTRS as p, READ_CONCURRENCY as q, type ResolvedA11y as r, type ResolvedHeadings as s, type ResolvedImages as t, type RuleOptionsSpec as u, type Scope as v, type ScoreOptions as w, type ScoreResult as x, type SourceSpan as y, applyOverrides as z };