@svelte-vitals/core 0.43.0 → 0.44.0

package/dist/internal.d.ts

@@ -0,0 +1,883 @@
+import { C as ComponentFacts, S as SuppressionDirective, R as Runtime, K as KitAlias, a as KitModuleFacts, V as Value, b as Rule, c as RuleContext, d as Result, e as Category, f as Severity, F as Fix, g as RuleOptionSpec, H as HeadTag, h as ResolvedHead, I as ImageInfo, i as Config, J as JsonReport } from './index-CWWQEu8q.js';
+export { A as A11yOccurrenceInfo, B as BranchStep, j as Classification, k as CompiledOverride, E as EachBlockFact, l as EffectFact, m as HeadProvider, n as HeadingInfo, o as HealthResult, p as IDREF_ATTRS, L as LANDMARK_ROLES, O as OrphanEffectFact, P as Project, q as READ_CONCURRENCY, r as ResolvedA11y, s as ResolvedHeadings, t as ResolvedImages, u as RuleOptionsSpec, v as Scope, w as ScoreOptions, x as ScoreResult, y as SourceSpan, z as applyOverrides, D as applyRuleSeverities, G as buildJsonReport, M as classify, N as compileOverrides, Q as computeHealth, T as computeScore, U as decodeFragmentId, W as defaultConfig, X as defaultProject, Y as docsUrlFor, Z as effectiveSeverity, _ as foldOccurrences, $ as formatFailedRuleWarning, a0 as formatJsonReport, a1 as hasFailureAtOrAbove, a2 as intOption, a3 as isMentionedAnywhere, a4 as isPenalized, a5 as isTopFragment, a6 as listOption, a7 as mapOption, a8 as overrideMatches, a9 as resolveRuleOptions, aa as scoresByCategory, ab as selectRules, ac as settingOptions, ad as settingSeverity, ae as shouldSkipRangeCheck, af as skippedFileWarnings, ag as splitTokens, ah as stripTextDirective, ai as summarize, aj as validateRuleOptions, ak as validateRuleSetting, al as withFailedRulesOff, am as withReadLimit } from './index-CWWQEu8q.js';
+import { AST } from 'svelte/compiler';
+
+/** What the per-file parsers produce — `ComponentFacts` minus `file`, with `suppressions` always present. */
+type ParsedFacts = Omit<ComponentFacts, 'file' | 'suppressions'> & {
+    suppressions: SuppressionDirective[];
+};
+/**
+ * Parse one source file's facts (CLI/static + vite build mode): a `.svelte` component's
+ * reactivity/correctness + security + architecture facts, or a `.svelte.ts`/`.svelte.js`
+ * runes module's orphan-$effect facts (correctness/orphan-effect).
+ */
+declare function parseComponentFacts(source: string, filename: string): ParsedFacts;
+
+/**
+ * Fallback facts for a file that fails to read or parse (dev tooling must never
+ * throw). This is the single source of truth for the empty-facts shape — add new
+ * `ComponentFacts` fields HERE so TypeScript catches every call site that still
+ * needs updating.
+ */
+declare function emptyComponentFacts(file: string): ComponentFacts;
+/**
+ * Scan every `.svelte` component and `.svelte.ts`/`.svelte.js` runes module under `src/`
+ * for Correctness/Security/Architecture/Bundle-Performance/Accessibility facts. Independent
+ * of route resolution — covers `$lib` and non-route components too. A file that fails to
+ * read or parse contributes empty facts instead of aborting the whole scan (dev tooling
+ * must never throw).
+ */
+declare function collectComponentFacts(rt: Runtime, cwd: string): Promise<ComponentFacts[]>;
+
+/**
+ * Every file under `src/`, as project-relative paths, sorted. Paths only — nothing is
+ * read, so this is the cheaper of the two passes over `src/` (the component collector
+ * already walks the same tree and reads every `.svelte`).
+ *
+ * Directory-shaped rules derive their directory set from these paths' ancestor prefixes
+ * rather than globbing a second time; see `architecture/unit-entry-file`. The list is
+ * sorted so anything that picks "the first file under a directory" is deterministic.
+ *
+ * Two properties of the result the directory-shaped rules depend on: a directory containing no file
+ * at any depth does not appear among these paths' ancestor prefixes and so does not exist as far as
+ * those rules are concerned, and dot directories never appear at all (see `Runtime.glob`).
+ */
+declare function collectSourceFiles(rt: Runtime, cwd: string): Promise<string[]>;
+
+/**
+ * Resolve an import specifier to a path relative to the analyzed project's root (the
+ * cwd svelte-vitals runs from — not necessarily a repo root; in a monorepo the project
+ * may live at e.g. `apps/web/`) against the importing file, or undefined when it cannot
+ * be a project-local module: the caller's `aliases` list decides which non-relative
+ * specifiers resolve, defaulting to `$lib` → `src/lib`; `./`/`../` resolve against the
+ * importing file's directory; bare packages and other aliases are skipped (they can't
+ * be resolved to a project-local path at all). Also undefined when a relative
+ * specifier's `..` segments escape the project root (see `normalizePosix`), or when a
+ * matched alias's value is itself absolute (e.g. `/opt/shared/src`, or a posixified Windows
+ * drive-letter path like `C:/shared/src`): an absolute target is outside the analyzed project by
+ * definition, and without this check `normalizePosix` would quietly drop the leading empty
+ * segment and hand back a project-relative-LOOKING path that actually names a different file.
+ *
+ * Exported from the package's public barrel because `architecture/private-scope-import`
+ * and `architecture/route-component-import` (inside `packages/core`) both need resolution
+ * that is not restricted to runes modules, unlike `resolveRunesModuleSpecifier` — and
+ * because `resolveComponentPath` (`packages/cli/src/providers/source/resolve.ts`), which
+ * drives transitive `<head>`/heading resolution, delegates its alias/`$lib`/relative
+ * mapping here too, rather than duplicating it. This is the single site for every
+ * repo-local specifier resolution in the repo.
+ */
+declare function resolveRepoLocalPath(spec: string, importerFile: string, aliases?: readonly KitAlias[]): string | undefined;
+/**
+ * Resolve an import specifier to a repo-relative `.svelte.ts`/`.svelte.js` path, or
+ * undefined when it cannot be a runes module: delegates to `resolveRepoLocalPath` with
+ * `aliases` (defaulting to `$lib` → `src/lib` when omitted), so a project's declared
+ * `kit.alias`/`kit.files.lib` resolve here exactly as they do at rule time; `./`/`../`
+ * resolve against the importing file's directory; bare packages, unmatched aliases, and
+ * a relative specifier whose `..` segments escape the repo root are skipped. An
+ * extensionless `…/x.svelte` specifier canonicalises to `….svelte.ts` (security/shared-state-import also
+ * tries the `.js` sibling when matching).
+ */
+declare function resolveRunesModuleSpecifier(spec: string, importerFile: string, aliases?: readonly KitAlias[]): string | undefined;
+/**
+ * Parse one SvelteKit route/hooks file's SSR shared-state facts (the security kit-module rules). Uses
+ * the shared wrap parser (`parseModuleProgram`), so reported lines subtract the
+ * 1-line wrap prefix; suppressions are scanned on the unwrapped source.
+ */
+declare function parseKitModuleFacts(source: string, filename: string, aliases?: readonly KitAlias[]): Omit<KitModuleFacts, 'file' | 'kind'>;
+
+/** Fallback facts for a Kit file that fails to read or parse (dev tooling must never throw). */
+declare function emptyKitModuleFacts(file: string, kind: KitModuleFacts['kind']): KitModuleFacts;
+/**
+ * Scan SvelteKit route/hooks files for SSR shared-state facts (the security kit-module rules): route
+ * `+page`/`+layout` server and universal modules, `+server` endpoints, and
+ * `src/hooks.server`. `src/lib/server/**` is deliberately NOT scanned — legitimate
+ * module singletons (DB connections, clients) live there (design). A file that
+ * fails to read or parse contributes empty facts instead of aborting the scan.
+ *
+ * `aliases` is the project's compiled alias list (`Project.kitAliases`); omitted,
+ * specifiers resolve through `$lib` → `src/lib` only.
+ */
+declare function collectKitModuleFacts(rt: Runtime, cwd: string, aliases?: readonly KitAlias[]): Promise<KitModuleFacts[]>;
+
+/**
+ * The `build: { minify: false }` override, when present as a literal: returns the
+ * `minify` property's 1-based line in the ORIGINAL source. Undefined for clean,
+ * dynamic, or unparsable configs (never throws).
+ */
+declare function findMinifyDisabled(source: string): {
+    line: number;
+} | undefined;
+
+/** What a Vite config says about SvelteKit's own configuration. */
+type ViteKitConfigResult = 
+/** No `sveltekit()` call, or one with no argument — `svelte.config` still applies. */
+{
+    kind: 'no-plugin-config';
+}
+/** `sveltekit(<something we can't resolve>)` — the effective config is unknowable AND
+ *  `svelte.config` is provably ignored, so the caller must stay quiet. */
+ | {
+    kind: 'unresolvable';
+}
+/** `sveltekit({…})` resolved. `base` is unset when the config declares no non-empty base. */
+ | {
+    kind: 'resolved';
+    base?: {
+        value?: string;
+    };
+};
+/** `kit.alias` and `kit.files.lib` as written, before Kit compiles them into ordered entries. */
+type RawKitAliases = {
+    /**
+     * `kit.alias` entries in declaration order, `value: null` where the config's value is not a
+     * string literal. **Undefined means the key set is unknowable** — a spread or a computed key
+     * puts an unknown key at a known position, and an unknown key could shadow anything after it,
+     * with no `find` to record that with. The caller then discards every user entry.
+     */
+    entries?: {
+        key: string;
+        value: string | null;
+    }[];
+    /**
+     * `kit.files.lib`, in three distinct states: **absent** (`undefined`) — there is no `lib`
+     * property, or `files` itself does not resolve to an object literal; a **literal** (the
+     * string) — `files.lib` is a string literal; **present but unreadable** (`null`) — the `lib`
+     * property exists but its value is not statically a string (e.g. a computed expression). The
+     * `null` state must not collapse into "absent": the caller cannot fall back to `src/lib`
+     * without risking a wrong answer, because the project may have moved `$lib` to something this
+     * parser simply couldn't read.
+     */
+    filesLib?: string | null;
+};
+/** `kit.alias` and `kit.files.lib` from a `svelte.config.{js,ts}` source. */
+declare function findKitAliasesInSvelteConfig(source: string): RawKitAliases;
+/**
+ * The project's compiled alias list, following SvelteKit's config precedence: options passed to
+ * the `sveltekit()` Vite plugin make `svelte.config` irrelevant (Kit logs "svelte.config.js is
+ * ignored when options are passed via your Vite config"), so aliases are read from
+ * `svelte.config` only when the Vite config carries no plugin config. Reading `kit.alias` out of
+ * a plugin config is deliberately not done — that costs reach, not correctness, and such a
+ * project keeps the resolver's default `$lib` behaviour. Undefined means "no config was read".
+ */
+declare function resolveKitAliases(viteConfig: {
+    source: string;
+} | undefined, svelteConfig: {
+    source: string;
+} | undefined): KitAlias[] | undefined;
+/** `kit.paths.base` from a `svelte.config.{js,ts}` source. */
+declare function findKitPathsBaseInSvelteConfig(source: string): {
+    value?: string;
+} | undefined;
+/** SvelteKit config passed to the `sveltekit()` plugin in a Vite config source (since Kit 2.62). */
+declare function findKitPathsBaseInViteConfig(source: string): ViteKitConfigResult;
+/**
+ * The project's effective `kit.paths.base`, following SvelteKit's precedence: the `sveltekit()`
+ * plugin config when it carries one, otherwise `svelte.config`. `file` is the config the base
+ * came from (as passed in by the caller). Undefined means "no base path" — the gate stays shut.
+ */
+declare function resolveKitPathsBase(viteConfig: {
+    file: string;
+    source: string;
+} | undefined, svelteConfig: {
+    file: string;
+    source: string;
+} | undefined): {
+    value?: string;
+    file: string;
+} | undefined;
+
+/**
+ * Parse a `.svelte` source, tolerating style blocks written in a CSS dialect.
+ *
+ * Svelte parses a `<style>` body as CSS whatever its `lang` says, so one `<style lang="scss">`
+ * makes a component unparseable — and one unparseable route file fails the entire run. On failure
+ * the dialect bodies are blanked to spaces of the same length (nothing here reads CSS, and equal
+ * length keeps every byte offset, so reported lines are unchanged) and the parse is retried.
+ *
+ * The retry, not the substitution, is the design: a file that parses today is never rewritten, so
+ * the text scan's imprecision cannot reach it. A file that does not parse is already a hard failure,
+ * which the retry can only improve on.
+ */
+declare function parseSvelte(source: string, filename: string): AST.Root;
+/** A template fragment's child node relevant to value classification: literal text or a `{expr}`. */
+type TextOrExpr = AST.Text | AST.ExpressionTag;
+/**
+ * All keys that can bear child nodes in a Svelte AST node.
+ * Covers if/each/await blocks (pending/then/catch/fallback) as well as
+ * the standard fragment, nodes, consequent, alternate, and body keys.
+ */
+declare const CHILD_NODE_KEYS: string[];
+declare function valueFromNodes(nodes: TextOrExpr[]): Value;
+/** The literal text of a node list when fully static (no ExpressionTag), else undefined. */
+declare function textFromNodes(nodes: TextOrExpr[]): string | undefined;
+/** Static string of an attribute (e.g. name="description"), or undefined if dynamic/absent. */
+declare function attrText(attributes: AST.Attribute[], name: string): string | undefined;
+/** Value kind of an attribute's content (e.g. the `content` of a <meta>). */
+declare function attrValue(attributes: AST.Attribute[], name: string): Value;
+declare function lineOf(source: string, offset: unknown): number;
+/**
+ * An element's attribute by name, matched **case-insensitively**: HTML attribute names are, so
+ * `ARIA-LABEL` and `Type` are the same attributes as `aria-label` and `type` once the document is
+ * parsed. The Svelte AST keeps the source spelling, so the normalisation has to happen here.
+ *
+ * Only ever called with an HTML element's attributes. A component's props are case-**sensitive**
+ * (`<Foo titleTemplate>` is not `<Foo titletemplate>`) and are read through the adapters' own
+ * lookup, which must stay exact.
+ */
+declare function findAttr(attributes: AST.Attribute[], name: string): AST.Attribute | undefined;
+/** Value kind of a single attribute (e.g. a component prop). */
+declare function attrValueOf(attr: AST.Attribute): Value;
+/** Literal static text of a single attribute node (e.g. a component prop), or undefined if dynamic/absent. */
+declare function attrTextOf(attr: AST.Attribute): string | undefined;
+
+/**
+ * Source-file locations that satisfy the project-scope rules, shared by every
+ * mode so the static (CLI) and rendered (plugin) collectors never drift. This
+ * module is pure data: no I/O, no `node:` imports (design §8).
+ */
+/** Locations that satisfy the robots.txt project rule (seo/robots-txt). */
+declare const ROBOTS_SOURCE_PATHS: readonly ["static/robots.txt", "src/routes/robots.txt/+server.ts", "src/routes/robots.txt/+server.js"];
+/** Locations that satisfy the sitemap.xml project rule (seo/sitemap-xml). */
+declare const SITEMAP_SOURCE_PATHS: readonly ["static/sitemap.xml", "src/routes/sitemap.xml/+server.ts", "src/routes/sitemap.xml/+server.js"];
+/** Vite's own config resolution order — only the first existing file is the one Vite loads. */
+declare const VITE_CONFIG_FILES: readonly ["vite.config.js", "vite.config.mjs", "vite.config.ts", "vite.config.cjs", "vite.config.mts", "vite.config.cts"];
+/** SvelteKit's config resolution order (`@sveltejs/kit` checks js before ts). */
+declare const SVELTE_CONFIG_FILES: readonly ["svelte.config.js", "svelte.config.ts"];
+
+interface FailedRule {
+    id: string;
+    message: string;
+}
+/**
+ * Run a set of rules against a shared context and collect their findings.
+ * Rules are independent, so they run concurrently; results are flattened in
+ * rule order for stable output. A rule that throws (sync or async) contributes
+ * no results instead of taking the whole run down with it — dev tooling must
+ * never throw — and is reported in `failedRules` instead.
+ */
+declare function runRules(rules: Rule[], ctx: RuleContext): Promise<{
+    results: Result[];
+    examined: Record<string, Record<string, number>>;
+    failedRules: FailedRule[];
+}>;
+
+/**
+ * seo/title-presence — every route should resolve a non-empty <title> (design §11).
+ * A dynamic title (`{data.title}`) is the most common correct pattern and must
+ * never be flagged as missing; it surfaces as value 'dynamic' (design §4).
+ */
+declare const seoTitlePresence: Rule;
+
+declare const seoDescriptionPresence: Rule;
+
+declare const seoCanonicalUrl: Rule;
+
+declare const seoOgImage: Rule;
+
+declare const seoOgTitle: Rule;
+
+declare const seoJsonLd: Rule;
+
+declare const seoRobotsTxt: Rule;
+
+declare const seoSitemapXml: Rule;
+
+declare const seoHtmlLang: Rule;
+
+declare const performanceImageDimensions: Rule;
+
+declare const performanceImageLoadingHint: Rule;
+
+declare const performanceResponsiveImage: Rule;
+
+declare const performancePreloadMissingAs: Rule;
+
+declare const performanceFontPreloadCrossorigin: Rule;
+
+/**
+ * performance/lcp-image — LCP image not lazy-loaded. Lazy-loading the largest contentful paint
+ * image delays it. Analysis approximates the LCP as the first <img> in document
+ * order for the route; if that image is loading="lazy", flag it. Runs in both
+ * static (CLI) and rendered (vite) mode, since both providers collect <img>.
+ */
+declare const performanceLcpImage: Rule;
+
+/**
+ * performance/render-blocking-script — Render-blocking <script> in <head>. A <script src> without
+ * defer/async/type=module blocks the parser. SvelteKit's own scripts are
+ * module/deferred, so this catches hand-added blocking scripts — in app.html
+ * (rendered mode) or in <svelte:head> (static mode). A head with no <script>
+ * emits nothing (no signal), like the image rules.
+ */
+declare const performanceRenderBlockingScript: Rule;
+
+/**
+ * performance/preconnect — Preconnect for third-party origins. A resource from a well-known
+ * third-party origin (e.g. Google Fonts) without a preconnect/dns-prefetch pays a
+ * connection-setup round-trip. Opt-in by construction: only origins in the
+ * allowlist are checked; routes referencing none emit nothing.
+ */
+declare const performancePreconnect: Rule;
+
+declare const seoIndexability: Rule;
+
+declare const seoTwitterCard: Rule;
+
+declare const seoOgDescription: Rule;
+
+declare const seoOgUrl: Rule;
+
+declare const seoViewport: Rule;
+
+declare const seoSitemapInRobots: Rule;
+
+declare const seoJsonLdValidity: Rule;
+
+declare const seoJsonLdDeprecatedType: Rule;
+
+declare const seoJsonLdRelativeUrl: Rule;
+
+declare const seoJsonLdDateFormat: Rule;
+
+declare const seoJsonLdPlaceholder: Rule;
+
+declare const seoJsonLdRequiredProps: Rule;
+
+declare const seoTitleLength: Rule;
+
+declare const seoDescriptionLength: Rule;
+
+/**
+ * seo/charset — Character encoding. The charset meta lives in `src/app.html`, so it is
+ * only visible to rendered analysis (`appliesTo: rendered`), exactly like seo/viewport
+ * (viewport). Static route analysis emits nothing instead of false-flagging it.
+ */
+declare const seoCharset: Rule;
+
+/**
+ * seo/image-alt — Image alt text. Reuses the <img> collection from both providers — the
+ * static (CLI) source parser and the rendered (vite) HTML parser — like performance/image-dimensions, performance/image-loading-hint.
+ * Presence only: an explicit empty `alt=""` is a valid decorative-image signal and
+ * passes; a spread `{...rest}` may supply alt, so it is not flagged.
+ */
+declare const seoImageAlt: Rule;
+
+/**
+ * seo/hreflang — hreflang / x-default validity. Opt-in: a route with no
+ * `<link rel="alternate" hreflang>` emits nothing (monolingual sites are never
+ * flagged). When alternates exist, every code must be well-formed and a set of
+ * two or more must declare an x-default. Works in both modes.
+ */
+declare const seoHreflang: Rule;
+
+/**
+ * seo/single-h1 — Heading hierarchy (single H1). Reads the per-route page-body headings
+ * channel (collected by both providers), counting `headings` plus `componentHeadings`
+ * (static mode only — headings found transitively in rendered child components) as one
+ * combined list. Zero <h1> (no primary heading) is a `warning`: defensible, a page needs
+ * a primary heading. Two or more is only `info`: a single <h1> is the conventional
+ * signal, but no official source documents a ranking penalty for several (2026-08-09 v1
+ * rule-validity review, P2 #11) — so it's flagged as a style nit, not a defect. Exactly
+ * one passes. A route whose headings were not collected (channel unset) emits nothing. A
+ * global `rules: { 'seo/single-h1': <severity> }` override flattens both arms to one
+ * severity (design, `applyRuleSeverities`).
+ */
+declare const seoSingleH1: Rule;
+
+declare const seoDuplicateTitle: Rule;
+
+declare const seoDuplicateDescription: Rule;
+
+/**
+ * seo/heading-level-skip — Skipped heading level. Walking a route's body headings in
+ * document order, a level that jumps more than +1 over the previous heading (e.g.
+ * h2 → h4) breaks the outline. The first heading has no predecessor (missing/multiple
+ * <h1> stays seo/single-h1's concern). A route with no headings emits nothing.
+ */
+declare const seoHeadingLevelSkip: Rule;
+
+declare const seoSsrDisabled: Rule;
+
+declare const correctnessEachKey: Rule;
+
+declare const correctnessEachIndexKey: Rule;
+
+declare const correctnessEffectAsDerived: Rule;
+
+declare const correctnessEffectAsOnMount: Rule;
+
+declare const correctnessUnmutatedState: Rule;
+
+/**
+ * correctness/prop-mutation — mutating a prop directly is a silent bug in both Svelte modes,
+ * for different reasons: in runes mode, a non-$bindable prop mutation doesn't propagate to the
+ * parent; in legacy mode (export let), Svelte's reactivity is assignment-based, so a mutating
+ * method call (`.push(...)`, etc.) doesn't trigger an update at all without a following
+ * reassignment. The two modes can't be mixed in one component, so a given finding is always
+ * exactly one or the other — see `legacy` on `ComponentFacts.mutatedProps` (component-parse.ts).
+ */
+declare const correctnessPropMutation: Rule;
+
+/**
+ * correctness/stale-prop-derivation — a value computed from a prop without $derived (runes
+ * mode) or $: (legacy mode) is evaluated once, at init, and silently stops tracking the
+ * parent. Svelte's own guidance: treat props as though they will change. The two modes can't
+ * be mixed in one component, so a given finding is always exactly one or the other — see
+ * `legacy` on `ComponentFacts.stalePropDerivations` (component-parse.ts).
+ */
+declare const correctnessStalePropDerivation: Rule;
+
+/**
+ * correctness/nonreactive-builtin-state — $state's deep proxy covers plain
+ * objects and arrays only. A plain Map/Set/Date/URL/URLSearchParams in $state
+ * keeps working as data, but its mutations never reach effects, deriveds, or
+ * the template: the UI silently stops updating. svelte/reactivity ships
+ * drop-in reactive equivalents for exactly this.
+ */
+declare const correctnessNonreactiveBuiltinState: Rule;
+
+/**
+ * correctness/checkable-bind-value — bind:value binds the DOM value property. A
+ * checkbox/radio's user interaction toggles checkedness, which bind:value never observes. A
+ * checkbox throws bind_invalid_checkbox_value in dev (silently tracks value instead of
+ * checkedness in prod); a radio throws nothing and its bound state silently never updates.
+ * bind:checked (single checkbox) / bind:group (checkbox list, radio group) are the correct
+ * bindings.
+ */
+declare const correctnessCheckableBindValue: Rule;
+
+declare const correctnessOrphanEffect: Rule;
+
+/**
+ * correctness/orphan-lifecycle — svelte lifecycle/context calls guaranteed to run outside component
+ * initialisation: module scope in runes modules / `<script module>`, the constructor of
+ * a module-scope-instantiated class, and Kit load/handler/`init` bodies. A custom check
+ * because the facts live on BOTH the component channel and the Kit-module channel.
+ */
+declare const correctnessOrphanLifecycle: Rule;
+
+/**
+ * correctness/base-path-navigation — root-relative navigation literals in a project that sets
+ * `kit.paths.base`. A custom check because it is gated on a PROJECT fact and its own facts live
+ * on BOTH the component channel (`<a href>`, `goto()`) and the Kit-module channel (`redirect()`).
+ * With no base path configured the rule emits nothing at all — the gate is the whole point.
+ */
+declare const correctnessBasePathNavigation: Rule;
+
+/**
+ * correctness/server-browser-global — browser globals read in server-executed MODULE code: module scope of
+ * runes modules / `<script module>`, and Kit route/hooks files (top level, handler
+ * bodies, the `init` hook). All of it runs on the server, where these globals do not
+ * exist — SSR crashes with a ReferenceError. Instance-script reads are correctness/instance-browser-global's
+ * (warning) territory. A custom check because the facts live on both channels.
+ */
+declare const correctnessServerBrowserGlobal: Rule;
+
+declare const correctnessInstanceBrowserGlobal: Rule;
+
+declare const securityRawHtml: Rule;
+
+declare const securityJavascriptUrl: Rule;
+
+declare const securityHandlerStateWrite: Rule;
+
+declare const securityServerModuleState: Rule;
+
+declare const securitySharedStateImport: Rule;
+
+declare const architectureComponentSize: Rule;
+
+declare const architecturePropCount: Rule;
+
+/**
+ * architecture/private-scope-import — a unit inside a declared private scope must not be
+ * imported from outside that scope (design 2026-07-28). L3: the scopes are declared by the
+ * project via the `scopes` option and never inferred, so the rule is inert until then.
+ *
+ * Findings are reported at the import site, not at the imported unit: `--diff` filters
+ * results to the files that changed, and the author of the violation edited the importer.
+ */
+declare const architecturePrivateScopeImport: Rule;
+
+/**
+ * architecture/unit-entry-file — a directory declared to be a unit must contain a file named
+ * after it (design 2026-07-28). L3: the declarations come from the project's own `units`,
+ * `pascalCaseUnits` and `exclude` options and are never inferred, so the rule is inert until then.
+ *
+ * The directory set is every ancestor path prefix of every file, so a directory holding only
+ * subdirectories is checked too. Violations report at a file inside the directory rather than at
+ * the directory, because `filterToChangedFiles` keeps only locations git lists as changed.
+ */
+declare const architectureUnitEntryFile: Rule;
+
+/**
+ * architecture/directory-naming — a directory must be named in the casing its location declares
+ * (design 2026-07-29). L3: the declarations come from the project's own `directories` and `exclude`
+ * options and are never inferred, so the rule is inert until then.
+ *
+ * Violations report at a file inside the directory rather than at the directory, because
+ * `filterToChangedFiles` keeps only locations git lists as changed and git never lists a directory.
+ *
+ * There are no pass results. `architecture/unit-entry-file` emits one per conforming unit and can
+ * afford to, because it keys the pass on the unit's entry file — a `.svelte` path already present as
+ * a score key. This rule's subject is the directory itself, with no such pre-existing key, and
+ * `computeScore` seeds every distinct `route` at 100 and averages: a pass per directory would add
+ * hundreds of 100s from one `'src/routes/**'` declaration and dilute every real finding.
+ */
+declare const architectureDirectoryNaming: Rule;
+
+/**
+ * architecture/reserved-directory-names — a directory's immediate subdirectories may only take names
+ * the project declared for that position (design 2026-07-29, extended 2026-08-08 for lowercase units —
+ * issue #386).
+ *
+ * The option maps differ in what their keys name. A `scopes` key names the parent directly. A
+ * `unitScopes` key names a root, and the rule governs the children of whichever directories beneath
+ * it are units whose name begins A–Z — the shape a glob cannot reach, because units nest to arbitrary
+ * depth. An `anyCaseUnitScopes` key names a root the same way, but governs units of *either* case:
+ * `isUnitDir`'s letter test — A–Z plus a same-stemmed entry file, whatever its extension — excludes a
+ * lowercase unit, so without this map no generic unit-map declaration governed one's children (a
+ * `scopes` key naming the parent directly could still reach one) — measured at 129 of 299 units (43%)
+ * on a real tree. Neither map is named with the bare word "unit": the
+ * sibling rule `architecture/reserved-name-placement` records why that word alone is ambiguous between
+ * the two predicates once both exist.
+ *
+ * There are no pass results. `computeScore` seeds every distinct `route` at 100 and averages, and the
+ * subject here is a directory with no pre-existing score key, so a pass per directory would add
+ * hundreds of 100s from one broad declaration and dilute every real finding.
+ */
+declare const architectureReservedDirectoryNames: Rule;
+
+/**
+ * architecture/reserved-name-placement — a reserved directory name may appear only in the places
+ * declared for it (design 2026-08-06). L3: inert until a placement is declared.
+ *
+ * The sibling `architecture/reserved-directory-names` says "at this position, only these names"; it
+ * cannot say "this name, only at these positions", which for a name appearing in several kinds of
+ * place is what a convention actually states.
+ *
+ * All three maps match the same directory — the reserved-name directory's parent — and differ only in
+ * what else they require of it: nothing, that it is a capitalised unit, that it is a unit of either
+ * case. A name's permitted positions are the UNION of its entries across the three, because a real
+ * convention permits one name under a unit, under a grouping and under a route directory at once.
+ *
+ * There are no pass results, for the reason the sibling records: `computeScore` seeds every distinct
+ * `route` at 100 and averages, and a directory has no pre-existing score key.
+ */
+declare const architectureReservedNamePlacement: Rule;
+
+declare const architectureRouteComponentImport: Rule;
+
+declare const architectureDocLinkTarget: Rule;
+
+declare const performanceHeavyImport: Rule;
+
+declare const performanceNamespaceImport: Rule;
+
+/**
+ * performance/minify-disabled — a `build.minify: false` left in vite.config ships unminified JS/CSS
+ * to production. Project-scope: the fact is produced by the CLI's static parse
+ * of vite.config.* (literal-only) or by the Vite plugin's resolved config
+ * (exact). Emits a finding only when the fact is set — no pass result.
+ */
+declare const performanceMinifyDisabled: Rule;
+
+/**
+ * performance/load-waterfall — dependent await chains in universal loads. Server loads are exempt:
+ * a dependent chain cannot be parallelized, and on the server there is no better
+ * placement to suggest. csr = false files are exempt too — without a client
+ * runtime the universal load only runs during SSR.
+ */
+declare const performanceLoadWaterfall: Rule;
+
+/**
+ * performance/sequential-awaits — independent sequential awaits in any load. Info severity: static
+ * data flow cannot see side-effect ordering (e.g. a setup call an API relies
+ * on), so the parallelize suggestion stays advisory.
+ */
+declare const performanceSequentialAwaits: Rule;
+
+/**
+ * performance/state-raw — deep $state proxies every property access; a binding
+ * that is only ever reassigned never uses that machinery. Svelte's guidance:
+ * large reassign-only objects (API responses, canonically) belong in $state.raw.
+ * "Large" is not statically knowable, so a non-primitive literal initializer is
+ * the proxy condition.
+ */
+declare const performanceStateRaw: Rule;
+
+declare const a11yInvalidRole: Rule;
+
+declare const a11yUnknownAriaAttribute: Rule;
+
+declare const a11yRequiredAriaProps: Rule;
+
+declare const a11yInvalidAriaValue: Rule;
+
+declare const a11yInteractiveNesting: Rule;
+
+declare const a11yAccessibleName: Rule;
+
+declare const a11yLabelHasControl: Rule;
+
+declare const a11yUseList: Rule;
+
+declare const a11yPlaceholderLabelOption: Rule;
+
+declare const a11yRequireDatetime: Rule;
+
+declare const a11yDoctype: Rule;
+
+/**
+ * a11y/duplicate-landmark — a composed route (layout chain + page) yields more than one
+ * `main` / `banner` / `contentinfo` landmark. `ctx.a11y[].landmarks` already holds the
+ * branch-aware-folded representatives, so this rule only counts them per kind, in the
+ * fixed KINDS order (it decides emission order and the PASS anchor).
+ */
+declare const a11yDuplicateLandmark: Rule;
+
+/**
+ * a11y/top-level-landmark — a landmark (`main`/`banner`/`complementary`/`contentinfo`) that
+ * composition places inside another landmark. `ctx.a11y[].nestedLandmarks` already carries one
+ * entry per nested occurrence, so this rule only reports them.
+ */
+declare const a11yTopLevelLandmark: Rule;
+
+/**
+ * a11y/id-duplication — a literal id repeated within a composed route. `ctx.a11y[].ids`
+ * already holds the branch-aware-folded representatives per id, so this rule only counts them.
+ */
+declare const a11yIdDuplication: Rule;
+
+/**
+ * a11y/no-missing-id-ref — a `for`/`aria-labelledby`/`aria-describedby`/`aria-controls`/
+ * `aria-activedescendant`/same-page `href="#…"` referencing an `id` absent from the composed
+ * route. Universal ("no element anywhere defines this id") needs a closed world, so this rule
+ * runs only on routes `ctx.a11y[].fullyResolved` marks fully resolved — see the rule docs.
+ */
+declare const a11yNoMissingIdRef: Rule;
+
+declare const allRules: Rule[];
+
+/** One configurable option of a rule, flattened for `svelte-vitals explain`'s output. */
+interface RuleOptionInfo {
+    name: string;
+    /** `integer` replaces the default; `string-list`/`string-map` are ADDED to it. */
+    kind: RuleOptionSpec['kind'];
+    default: number | readonly string[] | Readonly<Record<string, string>>;
+    min?: number;
+    max?: number;
+}
+interface RuleInfo {
+    id: string;
+    title: string;
+    category: Category;
+    severity: Severity;
+    rationale: string;
+    docsUrl: string;
+    fix?: Fix;
+    /**
+     * The rule's configurable options, omitted when it takes none. An agent that
+     * judges a finding to be a threshold disagreement rather than a defect needs
+     * to know the knob exists and what it is called before it can suggest one.
+     */
+    options?: RuleOptionInfo[];
+}
+/** Look up a rule's static metadata, as `svelte-vitals explain` renders it (issue #24). Rule ids are matched exactly (case-sensitive, e.g. "seo/ssr-disabled"). */
+declare function explainRule(id: string): RuleInfo | undefined;
+
+interface HeadTagRuleOptions {
+    id: string;
+    title: string;
+    severity: Severity;
+    /** Identifies the tag this rule looks for. */
+    match: (tag: HeadTag) => boolean;
+    /** Short human label, e.g. 'description'. */
+    label: string;
+    recommendation: string;
+    /** Why this rule matters — surfaced by `svelte-vitals explain` (issue #24). */
+    rationale: string;
+    /** Agent-actionable remediation attached to every finding (issue #18). */
+    fix?: Fix;
+    /**
+     * When set, only heads for which this returns true are evaluated; others emit
+     * nothing. Use for tags whose canonical location is invisible to a given mode
+     * (e.g. viewport lives in app.html → only checkable in rendered mode), so the
+     * rule stays silent instead of false-flagging "missing".
+     */
+    appliesTo?: (head: ResolvedHead) => boolean;
+}
+/** Build a route-scope rule asserting the presence of a single head tag (design §11). */
+declare function headTagRule(opts: HeadTagRuleOptions): Rule;
+
+interface ImageRuleOptions {
+    id: string;
+    title: string;
+    severity: Severity;
+    /** Vitals category (default 'performance'); seo/image-alt (alt text) reports under 'seo'. */
+    category?: Category;
+    /** Noun phrase for messages, e.g. '<img> width/height'. */
+    label: string;
+    recommendation: string;
+    rationale: string;
+    fix?: Fix;
+    /** Returns true when the image satisfies the rule (passes). */
+    ok: (img: ImageInfo) => boolean;
+}
+/** Build a route-scoped <img> rule that checks each image against `ok` (issue #10). */
+declare function imageRule(opts: ImageRuleOptions): Rule;
+
+interface LinkRuleOptions {
+    id: string;
+    title: string;
+    severity: Severity;
+    /** Noun phrase for messages, e.g. '`as` on a preloaded `<link>`'. */
+    label: string;
+    recommendation: string;
+    rationale: string;
+    fix?: Fix;
+    /** Which link tags this rule evaluates (e.g. rel === 'preload'). */
+    relevant: (tag: HeadTag) => boolean;
+    /** Returns true when a relevant link satisfies the rule (passes). */
+    ok: (tag: HeadTag) => boolean;
+}
+/** Build a route-scoped Performance rule that checks each relevant <link> in the effective head. */
+declare function linkRule(opts: LinkRuleOptions): Rule;
+
+/** String decorators for the console reporter. Injected so core stays pure/dep-free. */
+interface Palette {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    red: (s: string) => string;
+    yellow: (s: string) => string;
+    green: (s: string) => string;
+    cyan: (s: string) => string;
+}
+/** Default: no decoration (identity) — output is byte-identical to plain text. */
+declare const noColorPalette: Palette;
+/** Green ≥ 90, yellow ≥ 70, red otherwise — for a 0–100 score. */
+declare function scoreColor(p: Palette, score: number): (s: string) => string;
+
+interface ConsoleReportOptions {
+    byRoute?: boolean;
+    /** Mode label shown in the header (default 'static mode'). */
+    mode?: string;
+    /** Color decorators; defaults to no color. */
+    palette?: Palette;
+    /** Show every failing/passed/route entry uncapped and ungrouped, exactly as before this option existed. Default false (capped, grouped by rule). */
+    verbose?: boolean;
+    /** Internal: set by the CLI when it has already animated the Health header itself — skips the brand/Health lines (category score lines still print). Default false. */
+    omitHeader?: boolean;
+}
+/**
+ * Render results as a console report string (design §7). Pure: returns a string,
+ * the caller is responsible for printing. Prepends a score header; when byRoute is
+ * set, adds a per-route score tree.
+ */
+declare function formatConsoleReport(results: Result[], config: Config, options?: ConsoleReportOptions): string;
+
+/**
+ * Strip ANSI/OSC escape sequences and C0 control characters (except `\n`/`\t`) from a
+ * string before it reaches a terminal. POSIX file/route names can contain almost any
+ * byte, so a hostile repo can smuggle a terminal-title rewrite, cursor move, or other
+ * escape-sequence trick into what looks like plain report text.
+ *
+ * Only OSC and CSI sequences are pattern-matched and removed whole (payload included) —
+ * those cover title-bar writes and cursor/screen control, the two classes with a real
+ * blast radius. Any other `ESC` byte (rarer single/two-byte forms like reset or
+ * save-cursor) falls through to the final C0 sweep below, which drops the lone `ESC`
+ * but — deliberately, not swallowing an adjacent legitimate character — leaves whatever
+ * printable byte follows it as stray text.
+ * ponytail: doesn't special-case every Fe escape form; broaden the CSI/OSC patterns if a
+ * concrete non-CSI/OSC sequence turns out to matter.
+ */
+declare function terminalSafe(text: string): string;
+
+/** Render failing findings as an agent-actionable Markdown remediation document (issue #18). */
+declare function formatAgentReport(results: Result[], config: Config): string;
+
+/** Render penalized findings as a SARIF 2.1.0 log string (issue #18, design slice 5). */
+declare function formatSarifReport(results: Result[], config: Config, meta: {
+    version: string;
+}): string;
+
+/**
+ * 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;
+
+/**
+ * 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;
+
+type Band = 'good' | 'warn' | 'poor';
+declare const BAND_COLOR: Record<Band, string>;
+declare function scoreBand(score: number): Band;
+declare function escapeHtml(s: string): string;
+/**
+ * Return the URL only when it uses a safe http/https scheme, else null.
+ * Guards a finding's `docsUrl` against `javascript:`/`data:` hrefs — escapeHtml
+ * neutralizes attribute breakout but not a malicious scheme. Browsers strip
+ * ASCII whitespace (tab/newline/CR) from a URL before resolving its scheme (so
+ * `java\tscript:` runs as `javascript:`), so strip whitespace first; anything not
+ * plainly http(s):// afterward is rejected. Pure string work — no `URL` global,
+ * keeping core runtime-agnostic and lib-minimal.
+ */
+declare function safeHref(url: string): string | null;
+/** Provenance of a route's findings: real rendered page vs. source-only analysis. */
+type RouteBadge = 'measured' | 'static';
+interface AppSnapshot {
+    report: JsonReport;
+    badges: Record<string, RouteBadge>;
+    analyzing: boolean;
+    /** Monotonically increasing; lets the client discard an out-of-order /data.json response. */
+    sequence: number;
+    /** Whether a dev server is behind this page (SSE updates, /data.json refetch, connection dot). */
+    live: boolean;
+    meta: {
+        version: string;
+        coreVersion?: string;
+    };
+}
+/**
+ * Hand-authored CSS for the master/detail shell. Reuses the same design-token
+ * names/values as the rest of the project, and adds a dark theme via
+ * `:root[data-theme="dark"]` plus a `prefers-color-scheme` fallback for a
+ * first-ever visit with no stored preference.
+ */
+declare const APP_STYLE: string;
+/**
+ * Hand-authored client script for the shell — no bundler, no framework. Parses the
+ * AppSnapshot embedded by renderAppShell, then owns all rendering: sidebar
+ * (search/sort/route list) and detail pane (Overview or a selected route). When the
+ * snapshot says `live`, it additionally re-fetches /data.json on every SSE `update`
+ * and on the EventSource's `open` event (covers the initial connection and every
+ * auto-reconnect, since EventSource replays no missed events) — discarding any
+ * response whose `sequence` isn't newer than what's already rendered.
+ */
+declare const APP_SCRIPT: string;
+/** The shell HTML: empty sidebar/detail/topbar containers, the stylesheet, the
+ * client script, and the snapshot embedded as JSON for the client's first paint. */
+declare function renderAppShell(snapshot: AppSnapshot): string;
+/**
+ * Static (non-live) document over a prebuilt JsonReport — kept as the public name the
+ * html reporter has always exported.
+ */
+declare function buildHtmlDocument(report: JsonReport, meta: {
+    version: string;
+    coreVersion?: string;
+}): string;
+/** Render results as the self-contained HTML report (the CLI's `--reporter html`). */
+declare function formatHtmlReport(results: Result[], config: Config, meta: {
+    version: string;
+    coreVersion?: string;
+}): string;
+
+export { APP_SCRIPT, APP_STYLE, type AppSnapshot, BAND_COLOR, CHILD_NODE_KEYS, ComponentFacts, type ConsoleReportOptions, type FailedRule, HeadTag, ImageInfo, KitAlias, KitModuleFacts, type Palette, ROBOTS_SOURCE_PATHS, type RawKitAliases, ResolvedHead, type RouteBadge, Rule, RuleContext, type RuleInfo, type RuleOptionInfo, RuleOptionSpec, Runtime, SITEMAP_SOURCE_PATHS, SVELTE_CONFIG_FILES, SuppressionDirective, VITE_CONFIG_FILES, type ViteKitConfigResult, a11yAccessibleName, a11yDoctype, a11yDuplicateLandmark, a11yIdDuplication, a11yInteractiveNesting, a11yInvalidAriaValue, a11yInvalidRole, a11yLabelHasControl, a11yNoMissingIdRef, a11yPlaceholderLabelOption, a11yRequireDatetime, a11yRequiredAriaProps, a11yTopLevelLandmark, a11yUnknownAriaAttribute, a11yUseList, allRules, architectureComponentSize, architectureDirectoryNaming, architectureDocLinkTarget, architecturePrivateScopeImport, architecturePropCount, architectureReservedDirectoryNames, architectureReservedNamePlacement, architectureRouteComponentImport, architectureUnitEntryFile, attrText, attrTextOf, attrValue, attrValueOf, buildHtmlDocument, collectComponentFacts, collectKitModuleFacts, collectSourceFiles, correctnessBasePathNavigation, correctnessCheckableBindValue, correctnessEachIndexKey, correctnessEachKey, correctnessEffectAsDerived, correctnessEffectAsOnMount, correctnessInstanceBrowserGlobal, correctnessNonreactiveBuiltinState, correctnessOrphanEffect, correctnessOrphanLifecycle, correctnessPropMutation, correctnessServerBrowserGlobal, correctnessStalePropDerivation, correctnessUnmutatedState, emptyComponentFacts, emptyKitModuleFacts, escapeHtml, explainRule, findAttr, findKitAliasesInSvelteConfig, findKitPathsBaseInSvelteConfig, findKitPathsBaseInViteConfig, findMinifyDisabled, formatAgentReport, formatConsoleReport, formatGithubReport, formatHtmlReport, formatMarkdownReport, formatSarifReport, headTagRule, imageRule, lineOf, linkRule, noColorPalette, parseComponentFacts, parseKitModuleFacts, parseSvelte, performanceFontPreloadCrossorigin, performanceHeavyImport, performanceImageDimensions, performanceImageLoadingHint, performanceLcpImage, performanceLoadWaterfall, performanceMinifyDisabled, performanceNamespaceImport, performancePreconnect, performancePreloadMissingAs, performanceRenderBlockingScript, performanceResponsiveImage, performanceSequentialAwaits, performanceStateRaw, renderAppShell, resolveKitAliases, resolveKitPathsBase, resolveRepoLocalPath, resolveRunesModuleSpecifier, runRules, safeHref, scoreBand, scoreColor, securityHandlerStateWrite, securityJavascriptUrl, securityRawHtml, securityServerModuleState, securitySharedStateImport, seoCanonicalUrl, seoCharset, seoDescriptionLength, seoDescriptionPresence, seoDuplicateDescription, seoDuplicateTitle, seoHeadingLevelSkip, seoHreflang, seoHtmlLang, seoImageAlt, seoIndexability, seoJsonLd, seoJsonLdDateFormat, seoJsonLdDeprecatedType, seoJsonLdPlaceholder, seoJsonLdRelativeUrl, seoJsonLdRequiredProps, seoJsonLdValidity, seoOgDescription, seoOgImage, seoOgTitle, seoOgUrl, seoRobotsTxt, seoSingleH1, seoSitemapInRobots, seoSitemapXml, seoSsrDisabled, seoTitleLength, seoTitlePresence, seoTwitterCard, seoViewport, terminalSafe, textFromNodes, valueFromNodes };