@svelte-vitals/core 0.30.0 → 0.31.0

package/dist/index.d.ts

@@ -17,6 +17,33 @@ 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;
@@ -47,6 +74,13 @@ interface Project {
         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[];
 }
 declare const defaultProject: Project;
 /** A concrete, agent-actionable remediation for a finding (design §10, issue #18). */
@@ -152,7 +186,21 @@ interface Runtime {
     readFile(path: string): Promise<string>;
     /** Whether a path exists. */
     exists(path: string): Promise<boolean>;
-    /** Glob relative to `cwd`, returning paths (adapter decides abs/rel convention). */
+    /**
+     * 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;
@@ -363,10 +411,17 @@ interface ComponentFacts {
     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). */
+    /**
+     * 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: {
@@ -448,6 +503,21 @@ declare function emptyComponentFacts(file: string): ComponentFacts;
  */
 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[]>;
+
 /**
  * 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).
@@ -514,19 +584,21 @@ interface KitModuleFacts {
 
 /**
  * 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
+ * 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): string | undefined;
+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): Omit<KitModuleFacts, 'file' | 'kind'>;
+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;
@@ -536,8 +608,11 @@ declare function emptyKitModuleFacts(file: string, kind: KitModuleFacts['kind'])
  * `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): Promise<KitModuleFacts[]>;
+declare function collectKitModuleFacts(rt: Runtime, cwd: string, aliases?: readonly KitAlias[]): Promise<KitModuleFacts[]>;
 
 /**
  * The `build: { minify: false }` override, when present as a literal: returns the
@@ -566,6 +641,44 @@ type ViteKitConfigResult =
         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;
@@ -716,6 +829,23 @@ declare function intOption(options: RuleOptions, key: string, fallback?: number)
 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
@@ -799,6 +929,12 @@ interface RuleContext {
     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;
 }
@@ -1073,6 +1209,49 @@ declare const architecturePropCount: Rule;
  */
 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). L3: inert until a scope is declared.
+ *
+ * Two option maps, differing in what their key names. 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 — the shape a glob cannot reach, because units nest to arbitrary depth.
+ *
+ * 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;
+
+declare const architectureRouteComponentImport: Rule;
+
 declare const performanceHeavyImport: Rule;
 
 declare const performanceNamespaceImport: Rule;
@@ -1402,4 +1581,4 @@ declare function escapeHtml(s: string): string;
  */
 declare function safeHref(url: string): string | null;
 
-export { APP_SCRIPT, APP_STYLE, type AppSnapshot, BAND_COLOR, CATEGORIES, CHILD_NODE_KEYS, type Category, type Classification, type CompiledOverride, 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 RuleOptionInfo, type RuleOptionSpec, type RuleOptions, type RuleOptionsSpec, type RuleOverride, type RuleSetting, type RuleSettingObject, type Runtime, SITEMAP_SOURCE_PATHS, SVELTE_CONFIG_FILES, type Scope, type ScoreModel, type ScoreOptions, type ScoreResult, type Severity, type SourceSpan, type Summary, type SuppressionDirective, type TreatDynamicAs, VITE_CONFIG_FILES, type Value, type ViteKitConfigResult, allRules, applyOverrides, applyRuleSeverities, architectureComponentSize, architecturePrivateScopeImport, architecturePropCount, attrText, attrTextOf, attrValue, attrValueOf, buildHtmlDocument, buildJsonReport, classify, collectComponentFacts, collectKitModuleFacts, compileOverrides, computeHealth, computeScore, correctnessBasePathNavigation, correctnessCheckableBindValue, correctnessEachIndexKey, correctnessEachKey, correctnessEffectAsDerived, correctnessEffectAsOnMount, correctnessInstanceBrowserGlobal, correctnessNonreactiveBuiltinState, correctnessOrphanEffect, correctnessOrphanLifecycle, correctnessPropMutation, correctnessServerBrowserGlobal, correctnessStalePropDerivation, correctnessUnmutatedState, defaultConfig, defaultProject, defineConfig, docsUrlFor, effectiveSeverity, emptyComponentFacts, emptyKitModuleFacts, escapeHtml, explainRule, findAttr, findKitPathsBaseInSvelteConfig, findKitPathsBaseInViteConfig, findMinifyDisabled, formatAgentReport, formatConsoleReport, formatGithubReport, formatHtmlReport, formatJsonReport, formatMarkdownReport, formatSarifReport, hasFailureAtOrAbove, headTagRule, imageRule, intOption, isPenalized, lineOf, linkRule, listOption, mapOption, noColorPalette, overrideMatches, parseComponentFacts, parseKitModuleFacts, performanceFontPreloadCrossorigin, performanceHeavyImport, performanceImageDimensions, performanceImageLoadingHint, performanceLcpImage, performanceLoadWaterfall, performanceMinifyDisabled, performanceNamespaceImport, performancePreconnect, performancePreloadMissingAs, performanceRenderBlockingScript, performanceResponsiveImage, performanceSequentialAwaits, performanceStateRaw, renderAppShell, resolveKitPathsBase, resolveRuleOptions, resolveRunesModuleSpecifier, runRules, safeHref, scoreBand, scoreColor, scoresByCategory, securityHandlerStateWrite, securityJavascriptUrl, securityRawHtml, securityServerModuleState, securitySharedStateImport, selectRules, 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, settingOptions, settingSeverity, shouldSkipRangeCheck, summarize, textFromNodes, validateRuleOptions, validateRuleSetting, valueFromNodes };
+export { APP_SCRIPT, APP_STYLE, type AppSnapshot, BAND_COLOR, CATEGORIES, CHILD_NODE_KEYS, type Category, type Classification, type CompiledOverride, 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 KitAlias, type KitModuleFacts, type OrphanEffectFact, type Palette, type Presence, type Project, ROBOTS_SOURCE_PATHS, type RawKitAliases, type ResolvedHead, type ResolvedHeadings, type ResolvedImages, type Result, type RouteBadge, type Rule, type RuleContext, type RuleInfo, type RuleOptionInfo, type RuleOptionSpec, type RuleOptions, type RuleOptionsSpec, type RuleOverride, type RuleSetting, type RuleSettingObject, type Runtime, SITEMAP_SOURCE_PATHS, SVELTE_CONFIG_FILES, type Scope, type ScoreModel, type ScoreOptions, type ScoreResult, type Severity, type SourceSpan, type Summary, type SuppressionDirective, type TreatDynamicAs, VITE_CONFIG_FILES, type Value, type ViteKitConfigResult, allRules, applyOverrides, applyRuleSeverities, architectureComponentSize, architectureDirectoryNaming, architecturePrivateScopeImport, architecturePropCount, architectureReservedDirectoryNames, architectureRouteComponentImport, architectureUnitEntryFile, attrText, attrTextOf, attrValue, attrValueOf, buildHtmlDocument, buildJsonReport, classify, collectComponentFacts, collectKitModuleFacts, collectSourceFiles, compileOverrides, computeHealth, computeScore, correctnessBasePathNavigation, correctnessCheckableBindValue, correctnessEachIndexKey, correctnessEachKey, correctnessEffectAsDerived, correctnessEffectAsOnMount, correctnessInstanceBrowserGlobal, correctnessNonreactiveBuiltinState, correctnessOrphanEffect, correctnessOrphanLifecycle, correctnessPropMutation, correctnessServerBrowserGlobal, correctnessStalePropDerivation, correctnessUnmutatedState, defaultConfig, defaultProject, defineConfig, docsUrlFor, effectiveSeverity, emptyComponentFacts, emptyKitModuleFacts, escapeHtml, explainRule, findAttr, findKitAliasesInSvelteConfig, findKitPathsBaseInSvelteConfig, findKitPathsBaseInViteConfig, findMinifyDisabled, formatAgentReport, formatConsoleReport, formatGithubReport, formatHtmlReport, formatJsonReport, formatMarkdownReport, formatSarifReport, hasFailureAtOrAbove, headTagRule, imageRule, intOption, isMentionedAnywhere, isPenalized, lineOf, linkRule, listOption, mapOption, noColorPalette, overrideMatches, parseComponentFacts, parseKitModuleFacts, performanceFontPreloadCrossorigin, performanceHeavyImport, performanceImageDimensions, performanceImageLoadingHint, performanceLcpImage, performanceLoadWaterfall, performanceMinifyDisabled, performanceNamespaceImport, performancePreconnect, performancePreloadMissingAs, performanceRenderBlockingScript, performanceResponsiveImage, performanceSequentialAwaits, performanceStateRaw, renderAppShell, resolveKitAliases, resolveKitPathsBase, resolveRuleOptions, resolveRunesModuleSpecifier, runRules, safeHref, scoreBand, scoreColor, scoresByCategory, securityHandlerStateWrite, securityJavascriptUrl, securityRawHtml, securityServerModuleState, securitySharedStateImport, selectRules, 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, settingOptions, settingSeverity, shouldSkipRangeCheck, summarize, textFromNodes, validateRuleOptions, validateRuleSetting, valueFromNodes };