@svelte-vitals/core 0.24.0 → 0.26.0

package/README.md

@@ -3,13 +3,13 @@
 [![npm](https://img.shields.io/npm/v/@svelte-vitals/core)](https://www.npmjs.com/package/@svelte-vitals/core)
 [![MIT](https://img.shields.io/npm/l/@svelte-vitals/core)](https://opensource.org/licenses/MIT)
 
-Runtime-agnostic core for [svelte-vitals](https://github.com/oekazuma/svelte-vitals): shared types, the rule engine, scorer, reporter, and the SEO rule set.
+Runtime-agnostic core for [svelte-vitals](https://github.com/oekazuma/svelte-vitals): shared types, the rule engine, scorer, and reporters, plus the full rule set across five categories — SEO, Performance, Correctness, Security, Architecture.
 
 This package is **mode-independent** and contains no I/O — it operates on a normalized `ResolvedHead[]` intermediate representation, so the same rules run unchanged whether heads come from static source analysis (the `svelte-vitals` CLI) or from prerendered HTML (the `@svelte-vitals/vite` plugin). It has zero runtime dependencies and no `node:` imports.
 
 > Most users don't depend on this directly — install [`svelte-vitals`](https://www.npmjs.com/package/svelte-vitals) instead. This package is for building tools on top of the shared engine.
 
-> **ESM-only** (Node 18+). Ships ES modules only; `require()` is unsupported by design.
+> **ESM-only** (Node 22.13+). Ships ES modules only; `require()` is unsupported by design.
 
 ## License
 

package/dist/index.d.ts

@@ -219,6 +219,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 +296,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 +461,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 +620,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;
 
@@ -740,6 +869,57 @@ declare function formatMarkdownReport(results: Result[], config: Config, meta: {
     version: string;
 }): string;
 
+/** 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. `routeBadges` preserves the old opts shape.
+ */
+declare function buildHtmlDocument(report: JsonReport, meta: {
+    version: string;
+    coreVersion?: string;
+}, opts?: {
+    routeBadges?: Record<string, RouteBadge>;
+}): 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;
+
 type Band = 'good' | 'warn' | 'poor';
 declare const BAND_COLOR: Record<Band, string>;
 declare function scoreBand(score: number): Band;
@@ -754,20 +934,10 @@ declare function escapeHtml(s: string): string;
  * keeping core runtime-agnostic and lib-minimal.
  */
 declare function safeHref(url: string): string | null;
-declare function buildHtmlDocument(report: JsonReport, meta: {
-    version: string;
-    coreVersion?: string;
-}, opts?: {
-    routeBadges?: Record<string, 'measured' | 'static'>;
-}): string;
-declare function formatHtmlReport(results: Result[], config: Config, meta: {
-    version: string;
-    coreVersion?: string;
-}): string;
 
 /** Drop rules disabled via config (design §6). */
 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[];
 
-export { 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 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, 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 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, 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 };