@svelte-vitals/core 0.29.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;
@@ -36,6 +63,24 @@ interface Project {
         file?: string;
         line?: number;
     };
+    /**
+     * Set when the project configures a non-empty `kit.paths.base` — read from the `sveltekit()`
+     * Vite plugin config, else `svelte.config.{js,ts}` (correctness/base-path-navigation).
+     * `value` is the literal base when statically resolvable, unset when the config computes it
+     * (e.g. `dev ? '' : '/repo'`). `file` is the config path relative to the analyzed root (posix).
+     * Absent means the app is served at the root — the rule stays silent.
+     */
+    kitPathsBase?: {
+        value?: string;
+        file: string;
+    };
+    /**
+     * The project's compiled SvelteKit alias entries, in Kit's own order (`$lib` first), read from
+     * `svelte.config.{js,ts}`. Absent means no config was read — resolution then falls back to
+     * `$lib` → `src/lib`, which is what this analyzer assumed unconditionally before. A collected
+     * list is never empty: `$lib` is always prepended.
+     */
+    kitAliases?: KitAlias[];
 }
 declare const defaultProject: Project;
 /** A concrete, agent-actionable remediation for a finding (design §10, issue #18). */
@@ -69,10 +114,29 @@ interface Result {
 }
 type Scope = 'route' | 'project' | 'component';
 type Category = 'seo' | 'performance' | 'correctness' | 'security' | 'architecture';
+/**
+ * Every category, as a runtime list — for validating a user-supplied category
+ * name and naming the known ones in the error. One definition so a category
+ * added to `Category` can't be accepted by one validator and rejected by
+ * another. Not an ordering: reporters keep their own display order.
+ */
+declare const CATEGORIES: readonly Category[];
 /** How dynamic (`{data.title}`) values are treated by scoring (design §4, §12). */
 type TreatDynamicAs = 'pass' | 'warn' | 'fail';
-/** Per-rule override: disable, or change severity. */
-type RuleSetting = 'off' | Severity;
+/** Resolved option values handed to a rule at check time. */
+type RuleOptions = Record<string, unknown>;
+/**
+ * Object form of a rule setting. `severity` omitted keeps the rule's built-in
+ * severity — the common case when only a threshold is being moved.
+ * `{ severity: 'off', … }` disables the rule and any `options` beside it are
+ * inert (equivalent to the bare `'off'` string, not an error).
+ */
+interface RuleSettingObject {
+    severity?: Severity | 'off';
+    options?: RuleOptions;
+}
+/** Per-rule override: disable, change severity, and/or set options. */
+type RuleSetting = 'off' | Severity | RuleSettingObject;
 /**
  * Scoped rule override (design 2026-07-18), applied to results after analysis.
  * An entry matches a finding when any `route` glob matches its route id or any
@@ -122,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;
@@ -297,6 +375,26 @@ interface SuppressionDirective {
     /** Rule ids suppressed on that line; undefined = suppress every rule on that line. */
     ruleIds?: string[];
 }
+/** An `<input type="checkbox">` / `<input type="radio">` element carrying a `bind:value`
+ *  directive — `bind:value` observes the DOM `value` property, which checkbox/radio
+ *  interaction never changes, so the bound state silently never updates
+ *  (correctness/checkable-bind-value). */
+interface CheckableBindValueFact {
+    /** Which checkable input type was flagged — selects the message wording. */
+    kind: 'checkbox' | 'radio';
+    /** 1-based source line, or 0 if unknown. */
+    line: number;
+}
+/** A root-relative navigation literal — broken when the app is served under `kit.paths.base`
+ *  (correctness/base-path-navigation). Shared by the component and Kit-module channels. */
+interface BasePathLinkFact {
+    /** Which navigation surface it was written on — selects the message wording. */
+    kind: 'href' | 'goto' | 'redirect';
+    /** The literal path as written, e.g. '/about'. */
+    path: string;
+    /** 1-based source line, or 0 if unknown. */
+    line: number;
+}
 /** Reactivity/correctness + security + architecture facts parsed from one `.svelte` component. */
 interface ComponentFacts {
     /** Source file the component came from. */
@@ -313,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: {
@@ -351,6 +456,11 @@ interface ComponentFacts {
         type: string;
         line: number;
     }[];
+    /** `<input type="checkbox">` / `<input type="radio">` elements bound with `bind:value`
+     * instead of `bind:checked`/`bind:group` (correctness/checkable-bind-value). */
+    checkableBindValues: CheckableBindValueFact[];
+    /** Root-relative `<a href>` and `goto()` literals in this component (correctness/base-path-navigation). */
+    basePathLinks: BasePathLinkFact[];
     /** `$effect` calls guaranteed to run outside component initialisation — module scope in `.svelte.ts`/`.svelte.js` or `<script module>` (correctness/orphan-effect). */
     orphanEffects: OrphanEffectFact[];
     /** Svelte lifecycle/context calls guaranteed to run outside component initialisation — module scope in `.svelte.ts`/`.svelte.js` or `<script module>` (correctness/orphan-lifecycle). */
@@ -393,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).
@@ -438,6 +563,8 @@ interface KitModuleFacts {
         line: number;
         inHandler: boolean;
     }[];
+    /** Root-relative `redirect()` literals in this Kit module (correctness/base-path-navigation). */
+    basePathLinks: BasePathLinkFact[];
     /** Set when this file disables SSR via `export const ssr = false` (inline or same-file alias export) — the declaration's line (seo/ssr-disabled). */
     ssrDisabled?: {
         line: number;
@@ -457,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;
@@ -479,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
@@ -491,6 +623,84 @@ 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;
+
 /** A template fragment's child node relevant to value classification: literal text or a `{expr}`. */
 type TextOrExpr = AST.Text | AST.ExpressionTag;
 /**
@@ -529,6 +739,184 @@ declare function attrTextOf(attr: AST.Attribute): string | undefined;
 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"];
+
+/** The severity a setting selects: `'off'`, an explicit severity, or undefined (leave the built-in). */
+declare function settingSeverity(setting: RuleSetting | undefined): Severity | 'off' | undefined;
+/** The options a setting carries, or undefined for the string forms. */
+declare function settingOptions(setting: RuleSetting | undefined): RuleOptions | undefined;
+/** Drop rules disabled via config (design §6). */
+declare function selectRules(rules: Rule[], config: Config): Rule[];
+/** Apply per-rule severity overrides to results (design §6). */
+declare function applyRuleSeverities(results: Result[], config: Config): Result[];
+/** An override entry with its globs compiled once. Build with `compileOverrides`. */
+interface CompiledOverride {
+    routes: RegExp[];
+    files: RegExp[];
+    rules: Record<string, RuleSetting>;
+}
+/**
+ * Compile every override entry's globs to RegExp, once. Callers that match many
+ * targets (every component, every route) must hoist this out of their loop.
+ */
+declare function compileOverrides(config: Config): CompiledOverride[];
+/**
+ * Whether an override entry applies to a target. THE single definition of that
+ * question — the result post-pass and in-run option resolution both call it.
+ * Sharing this matcher is necessary but not sufficient for a severity override
+ * and an option override to select the same files: each caller must also pass
+ * the same `target` (route and, critically, `file`) the other path effectively
+ * matches against. See Finding 1, docs/superpowers/specs/2026-07-26-rule-options-design.md.
+ */
+declare function overrideMatches(o: CompiledOverride, target: {
+    route?: string;
+    file?: string;
+}): boolean;
+/**
+ * Apply route-/file-scoped overrides to results (design 2026-07-18). An entry
+ * matches when any `route` glob matches the finding's route id or any `files`
+ * glob matches its location (OR). `'off'` removes a matched result entirely —
+ * passing seeds included, so scoring and "checks passed" counts behave as if
+ * the rule never ran there. A severity value rewrites the result's severity.
+ * Entries are evaluated in order (later entries win); within one entry, a
+ * rule-id key beats a category key only when it specifies a `severity` — an
+ * options-only rule-id key (no `severity`) contributes its options but leaves
+ * the category key's severity in force, rather than shadowing it (design
+ * 2026-07-26, Finding 2 / second review Finding E).
+ */
+declare function applyOverrides(results: Result[], config: Config): Result[];
+
+/**
+ * Per-rule options: their declaration, resolution, and validation (design
+ * 2026-07-26). Deliberately does not import `rule.ts` — `rule.ts` imports
+ * `RuleOptionsSpec` from here, so taking `Rule` as a parameter would cycle.
+ * Callers pass the id and the spec instead.
+ */
+
+/**
+ * One configurable option. `kind` decides the merge semantics, so no rule
+ * writes merge code of its own: `integer` replaces, and the two collection
+ * kinds ADD to the built-in default (never replace — see the design doc).
+ */
+type RuleOptionSpec = {
+    kind: 'integer';
+    default: number;
+    min?: number;
+    max?: number;
+} | {
+    kind: 'string-list';
+    default: readonly string[];
+} | {
+    kind: 'string-map';
+    default: Readonly<Record<string, string>>;
+};
+/** A rule's configurable options, keyed by option name. */
+type RuleOptionsSpec = Record<string, RuleOptionSpec>;
+/**
+ * Typed reads of a resolved options object. `RuleOptions` values are `unknown`
+ * (the map is open-ended by design), so without these every rule would carry
+ * its own `o.max as number` cast and the "resolution guarantees the declared
+ * kind" invariant would live in a dozen places instead of one. `resolveRuleOptions`
+ * always seeds every declared key from the spec default and validation rejects a
+ * wrongly-typed value up front, so a mismatch here means a rule read a key it
+ * never declared — the `fallback` keeps that a wrong number rather than a crash.
+ */
+declare function intOption(options: RuleOptions, key: string, fallback?: number): number;
+/** As `intOption`, for a `string-list` option. */
+declare function listOption(options: RuleOptions, key: string): string[];
+/** As `intOption`, for a `string-map` option. */
+declare function mapOption(options: RuleOptions, key: string): Record<string, string>;
+/**
+ * Whether any config layer so much as mentions `ruleId` — its `rules` entry, or any `overrides`
+ * entry's.
+ *
+ * A rule that is inert until declared can return early on `false` instead of resolving options once
+ * per target and discarding the result. That waste is not hypothetical: the three directory-shaped
+ * Architecture rules resolve per directory, so an unconfigured project pays it for every directory
+ * under `src/` three times over, on every dev-server save. Measured 2026-07-30 over a synthetic tree
+ * of 1,523 directories: 5.4 ms per analysis, for rules that are off by default and therefore produce
+ * nothing.
+ *
+ * Deliberately conservative. It asks only whether the rule is *mentioned*, not whether the mention
+ * resolves to a non-empty value, so a `'off'` severity with no options still answers `true` and the
+ * caller does its normal work. A cheaper-but-wrong version of this would make a rule skip work it
+ * owed; this one can only ever fail to save time.
+ */
+declare function isMentionedAnywhere(config: Config, ruleId: string): boolean;
+/**
+ * Effective options for a rule at a target: built-in defaults, then
+ * `config.rules[ruleId].options`, then every matching `config.overrides` entry
+ * in order. Integers take the last value; lists and maps accumulate.
+ *
+ * `target` omitted skips overrides entirely (project-scoped rules). Callers
+ * resolving many targets should hoist `compileOverrides(config)` and pass it as
+ * `compiled` — otherwise every call recompiles the globs.
+ */
+declare function resolveRuleOptions(ruleId: string, spec: RuleOptionsSpec | undefined, config: Config, target?: {
+    route?: string;
+    file?: string;
+}, compiled?: CompiledOverride[]): RuleOptions;
+/**
+ * Problems with a user-supplied options object, as human-readable sentences
+ * (empty = valid). Callers treat any result as fatal: a typo that silently
+ * leaves the config inert is the failure this exists to prevent.
+ *
+ * `baseline`, when given, is the already-resolved value this `options` layer
+ * is being merged onto — built-in defaults merged with any earlier layer(s)
+ * (e.g. the global `config.rules[id].options`, when `options` is an
+ * `overrides[]` entry). The min/max cross-check below compares against it
+ * instead of the spec's own default, so a layer that only sets one side of a
+ * range is checked against what it actually inherits (design 2026-07-26
+ * review, Finding A). Omit it to check `options` against the spec defaults
+ * alone, as when validating the global layer itself. A `baseline` that is
+ * only partially resolved (missing `min` or `max`) is treated as "can't
+ * determine that side" rather than silently comparing against `undefined` —
+ * see the `typeof` guard below.
+ *
+ * `skipRangeCheck`, when true, skips the min/max cross-check entirely
+ * regardless of `baseline`. A caller sets this when it statically cannot
+ * rule out that some *other* config layer narrows the opposite side of the
+ * range at the same target — see the CLI's and the Vite plugin's
+ * `overrides[]` validation (design 2026-07-26 review, Finding A, third
+ * pass).
+ */
+declare function validateRuleOptions(ruleId: string, spec: RuleOptionsSpec | undefined, options: RuleOptions, baseline?: RuleOptions, skipRangeCheck?: boolean): string[];
+/**
+ * Whether `validateRuleOptions` should skip the min/max cross-check for
+ * `overrides[selfIndex].rules[key]` — the whole decision, so the CLI's
+ * config-file loader and the Vite plugin can't drift apart on it (they held
+ * line-for-line copies of it before).
+ *
+ * An entry that sets both sides, or neither, is judged against its baseline as
+ * usual. An entry that sets only one side is skipped when some *other* entry
+ * sets the opposite side, since the two may co-apply at a shared target and be
+ * valid there — see `otherOverrideNarrowsOppositeSide` for why that is
+ * conservative by necessity and what it lets through.
+ */
+declare function shouldSkipRangeCheck(overrides: readonly unknown[], selfIndex: number, key: string, setting: unknown): boolean;
+/**
+ * Problems with one user-supplied rule setting — the bare severity string or the
+ * object form — as human-readable sentences prefixed with `label` (empty = valid).
+ * THE single definition of what a setting may look like: the CLI's config-file
+ * loader and the Vite plugin both funnel through it, so a config file and the
+ * equivalent plugin option are accepted or rejected identically. Callers treat any
+ * result as fatal, on the same reasoning as an unknown rule id — a typo that
+ * silently leaves the config inert is the failure being prevented.
+ *
+ * `label` names the setting in the message (e.g. `rules.seo/title-length`,
+ * `overrides[0].rules.architecture`); `ruleId` is the key options messages quote.
+ * `allowOptions` is false for a category key: a category may carry a severity, but
+ * options are rule-specific and meaningless there. `baseline` and `skipRangeCheck`
+ * are passed through to `validateRuleOptions`.
+ */
+declare function validateRuleSetting(label: string, ruleId: string, setting: unknown, spec: RuleOptionsSpec | undefined, opts: {
+    allowOptions: boolean;
+    baseline?: RuleOptions;
+    skipRangeCheck?: boolean;
+}): string[];
 
 /** Input given to every rule. Mode-independent: rules see only ResolvedHead[] (design §8, §10). */
 interface RuleContext {
@@ -541,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;
 }
@@ -556,6 +950,8 @@ interface Rule {
     rationale: string;
     /** Canonical remediation template, shared by findings and explain_rule (issue #24). */
     fix?: Fix;
+    /** Configurable options for this rule; absent means the rule takes none. */
+    options?: RuleOptionsSpec;
     /**
      * Evaluate the resolved heads. A single rule may return one Result per route,
      * so it always returns an array. Project-scoped rules return a single element.
@@ -751,6 +1147,15 @@ declare const correctnessStalePropDerivation: Rule;
  */
 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, so
+ * the bound state is frozen at its initial value and silently never updates in production.
+ * bind:checked (single checkbox) / bind:group (checkbox list, radio group) are the correct
+ * bindings.
+ */
+declare const correctnessCheckableBindValue: Rule;
+
 declare const correctnessOrphanEffect: Rule;
 
 /**
@@ -761,6 +1166,14 @@ declare const correctnessOrphanEffect: Rule;
  */
 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
@@ -786,6 +1199,59 @@ 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). 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;
@@ -824,6 +1290,15 @@ declare const performanceStateRaw: Rule;
 
 declare const allRules: Rule[];
 
+/** One configurable option of a rule, flattened for explain_rule's consumers. */
+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;
@@ -832,6 +1307,12 @@ interface RuleInfo {
     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 for the MCP explain_rule tool (issue #24). Rule ids are matched exactly (case-sensitive, e.g. "seo/ssr-disabled"). */
 declare function explainRule(id: string): RuleInfo | undefined;
@@ -1100,19 +1581,4 @@ declare function escapeHtml(s: string): string;
  */
 declare function safeHref(url: string): string | null;
 
-/** 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[];
-/**
- * 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 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, architectureComponentSize, architecturePropCount, attrText, attrTextOf, attrValue, attrValueOf, buildHtmlDocument, buildJsonReport, classify, collectComponentFacts, collectKitModuleFacts, computeHealth, computeScore, correctnessEachIndexKey, correctnessEachKey, correctnessEffectAsDerived, correctnessEffectAsOnMount, correctnessInstanceBrowserGlobal, correctnessNonreactiveBuiltinState, correctnessOrphanEffect, correctnessOrphanLifecycle, correctnessPropMutation, correctnessServerBrowserGlobal, correctnessStalePropDerivation, correctnessUnmutatedState, defaultConfig, defaultProject, defineConfig, docsUrlFor, effectiveSeverity, emptyComponentFacts, emptyKitModuleFacts, escapeHtml, explainRule, findAttr, findMinifyDisabled, formatAgentReport, formatConsoleReport, formatGithubReport, formatHtmlReport, formatJsonReport, formatMarkdownReport, formatSarifReport, hasFailureAtOrAbove, headTagRule, imageRule, isPenalized, lineOf, linkRule, noColorPalette, parseComponentFacts, parseKitModuleFacts, performanceFontPreloadCrossorigin, performanceHeavyImport, performanceImageDimensions, performanceImageLoadingHint, performanceLcpImage, performanceLoadWaterfall, performanceMinifyDisabled, performanceNamespaceImport, performancePreconnect, performancePreloadMissingAs, performanceRenderBlockingScript, performanceResponsiveImage, performanceSequentialAwaits, performanceStateRaw, renderAppShell, 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, summarize, textFromNodes, 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 };