@svelte-vitals/core 0.25.0 → 0.27.0

package/dist/index.d.ts

@@ -60,6 +60,26 @@ type Category = 'seo' | 'performance' | 'correctness' | 'security' | 'architectu
 type TreatDynamicAs = 'pass' | 'warn' | 'fail';
 /** Per-rule override: disable, or change severity. */
 type RuleSetting = 'off' | Severity;
+/**
+ * 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 ('SEO001') 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). */
@@ -70,6 +90,8 @@ interface Config {
     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). */
@@ -219,6 +241,35 @@ interface EffectFact {
     /** 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 (CORRECT003). */
     mountOnly: boolean;
 }
+/** A `$effect` guaranteed to run outside component initialisation — it throws `effect_orphan` at runtime (CORRECT006). */
+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 (CORRECT007). */
+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" (CORRECT008/009). */
+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 — CORRECT008); 'instance' = component-init top level (runs on the server during SSR — CORRECT009). */
+    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. */
@@ -267,52 +318,123 @@ interface ComponentFacts {
         name: string;
         line: number;
     }[];
+    /** `$effect` calls guaranteed to run outside component initialisation — module scope in `.svelte.ts`/`.svelte.js` or `<script module>` (CORRECT006). */
+    orphanEffects: OrphanEffectFact[];
+    /** Svelte lifecycle/context calls guaranteed to run outside component initialisation — module scope in `.svelte.ts`/`.svelte.js` or `<script module>` (CORRECT007). */
+    orphanLifecycleCalls: OrphanLifecycleCallFact[];
+    /** Browser-global reads in server-executed positions of this file (CORRECT008/009). */
+    browserGlobalRefs: BrowserGlobalRefFact[];
+    /** Module-scope `$state` declarations in a `.svelte.ts`/`.svelte.js` runes module — on a server, one instance shared by every request (SEC005). 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[];
 }
 
-/** Parse a component's reactivity/correctness + security + architecture facts (CLI/static + vite build mode). */
-declare function parseComponentFacts(source: string, filename: string): {
-    eachBlocks: EachBlockFact[];
-    effects: EffectFact[];
-    htmlTags: SourceSpan[];
-    javascriptUrls: SourceSpan[];
-    loc: number;
-    propCount: number;
-    imports: string[];
-    importSpans: {
-        source: string;
+/** 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 (CORRECT006).
+ */
+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 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[]>;
+
+/**
+ * Facts parsed from one SvelteKit route/hooks file for the SSR shared-state rules
+ * (SEC003–005). 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 (SEC004). */
+    moduleStateReassignments: {
+        name: string;
         line: number;
+        inHandler: boolean;
     }[];
-    namespaceImports: {
+    /** Writes to an imported binding from inside an exported handler (SEC003). */
+    importedStateWrites: {
+        name: string;
+        line: number;
+        via: 'assignment' | 'set-call';
+    }[];
+    /** Writes to an imported binding outside handlers — top level or helper functions (SEC005's write flavour). */
+    importedStateWritesOutsideHandlers: {
+        name: string;
+        line: number;
+    }[];
+    /** Value imports whose specifier resolves to a repo-local `.svelte.ts`/`.svelte.js` runes module (SEC005). */
+    runesModuleImports: {
         source: string;
+        resolved: string;
+        names: string[];
         line: number;
     }[];
-    constableStates: {
+    /** Svelte lifecycle/context calls that run outside component initialisation — top level, handler bodies, or the `init` hook (CORRECT007). */
+    lifecycleCalls: {
         name: string;
         line: number;
+        inHandler: boolean;
     }[];
-    mutatedProps: {
+    /** Browser-global reads in server-executed positions — top level, handler bodies, the `init` hook (CORRECT008). Empty when the file itself exports `ssr = false`. */
+    browserGlobalRefs: {
         name: string;
         line: number;
+        inHandler: boolean;
     }[];
+    /** Inline `svelte-vitals-disable-next-line` directives in this file. */
     suppressions: SuppressionDirective[];
-};
+}
 
 /**
- * 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.
+ * Resolve an import specifier to a repo-relative `.svelte.ts`/`.svelte.js` path, or
+ * undefined when it cannot be a runes module: `$lib/` maps to `src/lib/`, `./`/`../`
+ * resolve against the importing file's directory; bare packages, other aliases, and
+ * a relative specifier whose `..` segments escape the repo root are skipped. An
+ * extensionless `…/x.svelte` specifier canonicalises to `….svelte.ts` (SEC005 also
+ * tries the `.js` sibling when matching).
  */
-declare function emptyComponentFacts(file: string): ComponentFacts;
+declare function resolveRunesModuleSpecifier(spec: string, importerFile: string): string | undefined;
 /**
- * Scan every `.svelte` component under `src/` for Correctness/Security/Architecture/
- * Bundle-Performance 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).
+ * Parse one SvelteKit route/hooks file's SSR shared-state facts (SEC003–005). Uses
+ * the shared wrap parser (`parseModuleProgram`), so reported lines subtract the
+ * 1-line wrap prefix; suppressions are scanned on the unwrapped source.
  */
-declare function collectComponentFacts(rt: Runtime, cwd: string): Promise<ComponentFacts[]>;
+declare function parseKitModuleFacts(source: string, filename: string): 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 (SEC003–005): 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.
+ */
+declare function collectKitModuleFacts(rt: Runtime, cwd: string): Promise<KitModuleFacts[]>;
 
 type Node = any;
 /**
@@ -361,6 +483,8 @@ interface RuleContext {
     headings?: ResolvedHeadings[];
     /** 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[];
     project: Project;
     config: Config;
 }
@@ -518,9 +642,36 @@ declare const correct004UnmutatedState: Rule;
 
 declare const correct005PropMutation: Rule;
 
+declare const correct006OrphanEffect: Rule;
+
+/**
+ * CORRECT007 — 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 correct007OrphanLifecycle: Rule;
+
+/**
+ * CORRECT008 — 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 CORRECT009's
+ * (warning) territory. A custom check because the facts live on both channels.
+ */
+declare const correct008BrowserGlobals: Rule;
+
+declare const correct009InstanceBrowserGlobals: Rule;
+
 declare const sec001Html: Rule;
 declare const sec002JavascriptUrl: Rule;
 
+declare const sec003LoadStateWrite: Rule;
+
+declare const sec004ServerModuleState: Rule;
+
+declare const sec005SharedStateImport: Rule;
+
 declare const arch001ComponentSize: Rule;
 declare const arch002PropCount: Rule;
 
@@ -810,5 +961,15 @@ declare function safeHref(url: string): string | null;
 declare function selectRules(rules: Rule[], config: Config): Rule[];
 /** Apply per-rule severity overrides to results (design §6). */
 declare function applyRuleSeverities(results: Result[], config: Config): Result[];
+/**
+ * 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.
+ */
+declare function applyOverrides(results: Result[], config: Config): Result[];
 
-export { APP_SCRIPT, APP_STYLE, type AppSnapshot, BAND_COLOR, CHILD_NODE_KEYS, type Category, type Classification, type ComponentFacts, type Config, type ConsoleReportOptions, type Detection, type EachBlockFact, type EffectFact, type Fix, type HeadProvider, type HeadTag, type HeadingInfo, type HealthResult, type ImageInfo, type JsonReport, type Palette, type Presence, type Project, ROBOTS_SOURCE_PATHS, type ResolvedHead, type ResolvedHeadings, type ResolvedImages, type Result, type RouteBadge, type Rule, type RuleContext, type RuleInfo, type RuleSetting, type Runtime, SITEMAP_SOURCE_PATHS, type Scope, type ScoreModel, type ScoreOptions, type ScoreResult, type Severity, type SourceSpan, type Summary, type SuppressionDirective, type TreatDynamicAs, type Value, allRules, applyRuleSeverities, arch001ComponentSize, arch002PropCount, attrText, attrTextOf, attrValue, attrValueOf, buildHtmlDocument, buildJsonReport, classify, collectComponentFacts, computeHealth, computeScore, correct001EachKey, correct002EffectDerived, correct003EffectAsOnMount, correct004UnmutatedState, correct005PropMutation, defaultConfig, defaultProject, defineConfig, docsUrlFor, effectiveSeverity, emptyComponentFacts, escapeHtml, explainRule, findAttr, formatAgentReport, formatConsoleReport, formatGithubReport, formatHtmlReport, formatJsonReport, formatMarkdownReport, formatSarifReport, hasFailureAtOrAbove, headTagRule, imageRule, isPenalized, lineOf, linkRule, noColorPalette, parseComponentFacts, perf001ImageDimensions, perf002ImageLoading, perf003PreloadAs, perf004FontPreloadCrossorigin, perf005LcpImage, perf006ResponsiveImage, perf007RenderBlockingScript, perf008Preconnect, perf009HeavyImport, perf010NamespaceImport, renderAppShell, runRules, safeHref, scoreBand, scoreColor, scoresByCategory, sec001Html, sec002JavascriptUrl, selectRules, seo001Title, seo002Description, seo003Canonical, seo004OgImage, seo005OgTitle, seo006Robots, seo007Sitemap, seo008JsonLd, seo009HtmlLang, seo010Indexability, seo011TwitterCard, seo012OgDescription, seo013OgUrl, seo014Viewport, seo015SitemapInRobots, seo016JsonLdValidity, seo017DeprecatedType, seo018RelativeUrl, seo019DateFormat, seo020Placeholder, seo021RequiredProps, seo022TitleLength, seo023DescriptionLength, seo024Charset, seo025ImageAlt, seo026Hreflang, seo027Heading, seo028TitleUnique, seo029DescriptionUnique, seo030HeadingOrder, summarize, textFromNodes, valueFromNodes };
+export { APP_SCRIPT, APP_STYLE, type AppSnapshot, BAND_COLOR, CHILD_NODE_KEYS, type Category, type Classification, type ComponentFacts, type Config, type ConsoleReportOptions, type Detection, type EachBlockFact, type EffectFact, type Fix, type HeadProvider, type HeadTag, type HeadingInfo, type HealthResult, type ImageInfo, type JsonReport, type KitModuleFacts, type OrphanEffectFact, type Palette, type Presence, type Project, ROBOTS_SOURCE_PATHS, type ResolvedHead, type ResolvedHeadings, type ResolvedImages, type Result, type RouteBadge, type Rule, type RuleContext, type RuleInfo, type RuleOverride, type RuleSetting, type Runtime, SITEMAP_SOURCE_PATHS, type Scope, type ScoreModel, type ScoreOptions, type ScoreResult, type Severity, type SourceSpan, type Summary, type SuppressionDirective, type TreatDynamicAs, type Value, allRules, applyOverrides, applyRuleSeverities, arch001ComponentSize, arch002PropCount, attrText, attrTextOf, attrValue, attrValueOf, buildHtmlDocument, buildJsonReport, classify, collectComponentFacts, collectKitModuleFacts, computeHealth, computeScore, correct001EachKey, correct002EffectDerived, correct003EffectAsOnMount, correct004UnmutatedState, correct005PropMutation, correct006OrphanEffect, correct007OrphanLifecycle, correct008BrowserGlobals, correct009InstanceBrowserGlobals, defaultConfig, defaultProject, defineConfig, docsUrlFor, effectiveSeverity, emptyComponentFacts, emptyKitModuleFacts, escapeHtml, explainRule, findAttr, formatAgentReport, formatConsoleReport, formatGithubReport, formatHtmlReport, formatJsonReport, formatMarkdownReport, formatSarifReport, hasFailureAtOrAbove, headTagRule, imageRule, isPenalized, lineOf, linkRule, noColorPalette, parseComponentFacts, parseKitModuleFacts, perf001ImageDimensions, perf002ImageLoading, perf003PreloadAs, perf004FontPreloadCrossorigin, perf005LcpImage, perf006ResponsiveImage, perf007RenderBlockingScript, perf008Preconnect, perf009HeavyImport, perf010NamespaceImport, renderAppShell, resolveRunesModuleSpecifier, runRules, safeHref, scoreBand, scoreColor, scoresByCategory, sec001Html, sec002JavascriptUrl, sec003LoadStateWrite, sec004ServerModuleState, sec005SharedStateImport, selectRules, seo001Title, seo002Description, seo003Canonical, seo004OgImage, seo005OgTitle, seo006Robots, seo007Sitemap, seo008JsonLd, seo009HtmlLang, seo010Indexability, seo011TwitterCard, seo012OgDescription, seo013OgUrl, seo014Viewport, seo015SitemapInRobots, seo016JsonLdValidity, seo017DeprecatedType, seo018RelativeUrl, seo019DateFormat, seo020Placeholder, seo021RequiredProps, seo022TitleLength, seo023DescriptionLength, seo024Charset, seo025ImageAlt, seo026Hreflang, seo027Heading, seo028TitleUnique, seo029DescriptionUnique, seo030HeadingOrder, summarize, textFromNodes, valueFromNodes };