svelte-vitals 0.41.0 → 0.43.0

package/dist/bin.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 import {
   CONFIG_FILENAMES,
-  buildRulesConfig,
   discoverApps,
   findUnknownRuleIds,
   isReporterName,
@@ -9,7 +8,7 @@ import {
   readCoreVersion,
   readPackageVersion,
   run
-} from "./chunk-2WDZJQGD.js";
+} from "./chunk-6Y2E7QCQ.js";
 import {
   consoleIO
 } from "./chunk-SLUMRYUD.js";
@@ -145,8 +144,8 @@ function resolveArgs(argv) {
   if (updateSuppressions && noSuppressions) {
     errors.push("svelte-vitals: --update-suppressions and --no-suppressions cannot be used together.");
   }
-  const rulesConfig = buildRulesConfig(allow, ignore);
-  const rules = Object.keys(rulesConfig).length > 0 ? rulesConfig : void 0;
+  const allowRules = allow.length > 0 ? allow : void 0;
+  const ignoreRules = ignore.length > 0 ? ignore : void 0;
   if (errors.length > 0) return { options: null, warnings, errors };
   return {
     options: {
@@ -161,7 +160,8 @@ function resolveArgs(argv) {
       outFile: typeof argv["out-file"] === "string" ? argv["out-file"] : void 0,
       byRoute: Boolean(argv["by-route"]),
       failOn,
-      rules,
+      ...allowRules !== void 0 ? { allowRules } : {},
+      ...ignoreRules !== void 0 ? { ignoreRules } : {},
       ...weights !== void 0 ? { weights } : {},
       ...categories !== void 0 ? { categories } : {},
       ...score ? { score } : {},
@@ -1760,7 +1760,7 @@ async function selectApp(apps) {
 async function main() {
   const rawArgs = process.argv.slice(2);
   if (rawArgs[0] === "docs") {
-    const { runDocsCli } = await import("./cli-QRSD7FSW.js");
+    const { runDocsCli } = await import("./cli-J5V65YIN.js");
     process.exitCode = runDocsCli(rawArgs.slice(1));
     return;
   }

package/dist/{chunk-2WDZJQGD.js → chunk-6Y2E7QCQ.js}

@@ -2,7 +2,7 @@
 import { mkdirSync, writeFileSync as writeFileSync2 } from "fs";
 import { dirname as dirname2, join as join6 } from "path";
 import {
-  allRules as allRules2,
+  allRules as allRules3,
   runRules,
   formatConsoleReport,
   formatJsonReport,
@@ -1459,6 +1459,30 @@ function scoreAnimationEnabled(opts) {
   return opts.reporter === "console" && opts.stdoutIsTTY && !opts.noAnimationFlag && !isAgentEnv(opts.env) && !isCiEnv(opts.env) && colorEnabled({ reporter: opts.reporter, isTTY: opts.stdoutIsTTY, env: opts.env, noColorFlag: opts.noColorFlag });
 }
 
+// src/rule-selection.ts
+import { allRules as allRules2 } from "@svelte-vitals/core";
+function resolveRuleSelection(input) {
+  const out = { ...input.rules ?? input.fileRules };
+  const allow = input.allowRules ?? [];
+  if (allow.length > 0) {
+    const allowed = new Set(allow);
+    for (const rule of allRules2) if (!allowed.has(rule.id)) out[rule.id] = "off";
+    for (const id of allowed) {
+      const setting = out[id];
+      if (setting === void 0) continue;
+      if (setting === "off") {
+        delete out[id];
+      } else if (typeof setting === "object" && setting.severity === "off") {
+        const { severity: _forceEnabled, ...rest } = setting;
+        if (Object.keys(rest).length === 0) delete out[id];
+        else out[id] = rest;
+      }
+    }
+  }
+  for (const id of input.ignoreRules ?? []) out[id] = "off";
+  return out;
+}
+
 // src/index.ts
 import { defineConfig as defineConfig2 } from "@svelte-vitals/core";
 function spinnerEnabled(opts) {
@@ -1473,7 +1497,12 @@ async function analyzeProject(opts = {}) {
   const config = defineConfig({
     treatDynamicAs: opts.treatDynamicAs ?? file?.treatDynamicAs ?? "pass",
     metaComponents: opts.metaComponents ?? file?.metaComponents ?? [],
-    rules: opts.rules ?? file?.rules ?? {},
+    rules: resolveRuleSelection({
+      fileRules: file?.rules,
+      rules: opts.rules,
+      allowRules: opts.allowRules,
+      ignoreRules: opts.ignoreRules
+    }),
     failOn: opts.failOn ?? file?.failOn ?? "critical",
     ...weights !== void 0 ? { weights } : {},
     ...file?.overrides !== void 0 ? { overrides: file.overrides } : {}
@@ -1484,16 +1513,20 @@ async function analyzeProject(opts = {}) {
     route: opts.route,
     parseCache: opts.parseCache
   });
-  const selected = selectRules(allRules2, config);
+  const selected = selectRules(allRules3, config);
   const rules = opts.categories ? selected.filter((r) => opts.categories.includes(r.category)) : selected;
-  const results = applyOverrides(
-    applyRuleSeverities(
-      await runRules(rules, { heads, images, headings, components, project, config, kitModules, sourceFiles }),
-      config
-    ),
-    config
-  );
-  return { results, config, version: readPackageVersion(), ruleIds: rules.map((r) => r.id), warnings };
+  const { results: rawResults, examined } = await runRules(rules, {
+    heads,
+    images,
+    headings,
+    components,
+    project,
+    config,
+    kitModules,
+    sourceFiles
+  });
+  const results = applyOverrides(applyRuleSeverities(rawResults, config), config);
+  return { results, config, version: readPackageVersion(), ruleIds: rules.map((r) => r.id), examined, warnings };
 }
 async function applyScope(results, opts) {
   const errorLog = opts.errorLog ?? ((line) => console.error(line));
@@ -1539,6 +1572,19 @@ async function applyScope(results, opts) {
   }
   return scoped;
 }
+function runAnalyzeOptions(opts) {
+  return {
+    metaComponents: opts.metaComponents,
+    treatDynamicAs: opts.treatDynamicAs,
+    route: opts.route,
+    failOn: opts.failOn,
+    rules: opts.rules,
+    ignoreRules: opts.ignoreRules,
+    allowRules: opts.allowRules,
+    weights: opts.weights,
+    categories: opts.categories
+  };
+}
 async function run(opts = {}) {
   const log = opts.log ?? ((line) => console.log(line));
   const errorLog = opts.errorLog ?? ((line) => console.error(line));
@@ -1564,16 +1610,7 @@ async function run(opts = {}) {
   let cwd = opts.cwd ?? process.cwd();
   let analysis;
   try {
-    analysis = await analyzeProject({
-      cwd,
-      metaComponents: opts.metaComponents,
-      treatDynamicAs: opts.treatDynamicAs,
-      route: opts.route,
-      failOn: opts.failOn,
-      rules: opts.rules,
-      weights: opts.weights,
-      categories: opts.categories
-    });
+    analysis = await analyzeProject({ ...runAnalyzeOptions(opts), cwd });
   } catch (err) {
     spinner.stop();
     if (err instanceof ProjectError) {
@@ -1608,16 +1645,7 @@ async function run(opts = {}) {
       }
       cwd = join6(cwd, chosen);
       try {
-        analysis = await analyzeProject({
-          cwd,
-          metaComponents: opts.metaComponents,
-          treatDynamicAs: opts.treatDynamicAs,
-          route: opts.route,
-          failOn: opts.failOn,
-          rules: opts.rules,
-          weights: opts.weights,
-          categories: opts.categories
-        });
+        analysis = await analyzeProject({ ...runAnalyzeOptions(opts), cwd });
       } catch (err2) {
         if (err2 instanceof ProjectError) {
           errorLog(err2.message);
@@ -1648,15 +1676,8 @@ async function run(opts = {}) {
       baseline: opts.baseline,
       noSuppressions: opts.noSuppressions,
       errorLog,
-      analyzeOpts: {
-        metaComponents: opts.metaComponents,
-        treatDynamicAs: opts.treatDynamicAs,
-        route: opts.route,
-        failOn: opts.failOn,
-        rules: opts.rules,
-        weights: opts.weights,
-        categories: opts.categories
-      }
+      // No `cwd` — applyScope analyzes the baseline in its own checkout.
+      analyzeOpts: runAnalyzeOptions(opts)
     });
     const summary = summarize(results, config);
     if (opts.score) {
@@ -1673,7 +1694,7 @@ async function run(opts = {}) {
         );
       }
       if (reporter === "json") {
-        log(formatJsonReport(results, config, { version }, analysis.ruleIds));
+        log(formatJsonReport(results, config, { version }, analysis.ruleIds, analysis.examined));
       } else if (reporter === "agent") {
         log(formatAgentReport(results, config));
       } else if (reporter === "sarif") {

package/dist/{cli-QRSD7FSW.js → cli-J5V65YIN.js}

@@ -17,7 +17,7 @@ var EMBEDDED_DOCS = [
     name: "config",
     title: "The config file",
     description: "Where svelte-vitals.config lives, every top-level option, how to disable or re-grade a rule, and how to scope rules to routes or files.",
-    body: "# The config file\n\n## Where it lives\n\nIn the **analyzed directory only** \u2014 no upward search. First match wins:\n\n1. `svelte-vitals.config.mjs`\n2. `svelte-vitals.config.js`\n3. `svelte-vitals.config.ts`\n\nNo file means built-in defaults. `svelte-vitals install --client config-file` scaffolds one with\nevery option commented out.\n\n```js\n// svelte-vitals.config.mjs\nexport default {\n  treatDynamicAs: 'warn',\n  metaComponents: ['Seo'],\n  rules: { 'seo/json-ld': 'off' },\n  failOn: 'warning',\n  weights: { seo: 2 }\n};\n```\n\nA `.ts` config can `import { defineConfig } from 'svelte-vitals'` for type-checking, but that is a\n**runtime** import: it needs svelte-vitals as a declared dependency and Node 22.18+ (or 23.6+).\nA plain `export default {}` in `.mjs` behaves identically and always works.\n\n## Options\n\n| Option           | Type                                                           | Default            |\n| ---------------- | -------------------------------------------------------------- | ------------------ |\n| `treatDynamicAs` | `'pass' \\| 'warn' \\| 'fail'`                                   | `'pass'`           |\n| `metaComponents` | `string[]`                                                     | `[]`               |\n| `rules`          | `Record<ruleId, 'off' \\| Severity \\| { severity?, options? }>` | `{}`               |\n| `failOn`         | `'critical' \\| 'warning' \\| 'info'`                            | `'critical'`       |\n| `weights`        | `Partial<Record<Category, number>>`                            | every category `1` |\n| `overrides`      | `RuleOverride[]`                                               | (none)             |\n\n`Severity` is `'critical' | 'warning' | 'info'`. `Category` is `'seo' | 'performance' |\n'correctness' | 'security' | 'architecture'`. A weight of `0` drops a category from the Health\naverage; setting every category to `0` is an error (exit `2`).\n\n## Turning a rule off or down\n\n```js\nexport default {\n  rules: {\n    'seo/json-ld': 'off', // remove its findings entirely\n    'architecture/prop-count': 'info' // keep it, stop it failing the build\n  }\n};\n```\n\nMany rules take options, so check whether the finding is a **threshold disagreement** rather than\na defect first. `svelte-vitals explain <rule-id>` prints each option's name, default, bounds, and\nmerge semantics (`integer` replaces, `string-list` appends, `string-map` is spread over).\n\n```js\nexport default {\n  rules: {\n    'architecture/prop-count': { options: { max: 12 } }\n  }\n};\n```\n\n## Scoping to routes or files (`overrides`)\n\n`rules` applies everywhere; `overrides` applies only where it matches \u2014 typically routes that\nare deliberately not public.\n\n```js\nexport default {\n  overrides: [\n    { files: 'src/routes/(app)/**', rules: { seo: 'off' } },\n    { route: '/admin/**', rules: { 'seo/title-presence': 'info' } }\n  ]\n};\n```\n\nEach entry needs `rules` (keys are rule ids **or** category names) plus at least one of:\n\n- **`route`** \u2014 glob(s) against the route id as reported (`/blog/[slug]`). SvelteKit `(group)`\n  segments are **not** in the route id, so use `files` to target a group.\n- **`files`** \u2014 glob(s) against the source path.\n\nGlobs are deliberately small: `*` within a segment, `**` across segments, a trailing `/**` also\nmatches the bare prefix. Everything else \u2014 including `(`, `)`, `[`, `]` \u2014 is literal. Later entries win.\n\n## Precedence\n\nPer field: **CLI flag > config file > built-in default**. One exception \u2014 `--rules`/`--ignore`\nreplace the config file's `rules` wholesale for that run rather than merging.\n\n`overrides` has no CLI flag; route policy belongs in a committed file.\n\n## Validation\n\nAn unknown rule id or category, a negative weight, a malformed `overrides` entry, or an invalid\nrule setting is a **hard error (exit `2`)** \u2014 a typo must not silently un-gate CI. An unrecognized\n`treatDynamicAs`/`failOn` value, or an unknown top-level key, only warns.\n\n## Related\n\n- `svelte-vitals explain --list` \u2014 every rule id\n- `svelte-vitals docs show scoping` \u2014 accepting an existing backlog instead of disabling rules"
+    body: "# The config file\n\n## Where it lives\n\nIn the **analyzed directory only** \u2014 no upward search. First match wins:\n\n1. `svelte-vitals.config.mjs`\n2. `svelte-vitals.config.js`\n3. `svelte-vitals.config.ts`\n\nNo file means built-in defaults. `svelte-vitals install --client config-file` scaffolds one with\nevery option commented out.\n\n```js\n// svelte-vitals.config.mjs\nexport default {\n  treatDynamicAs: 'warn',\n  metaComponents: ['Seo'],\n  rules: { 'seo/json-ld': 'off' },\n  failOn: 'warning',\n  weights: { seo: 2 }\n};\n```\n\nA `.ts` config can `import { defineConfig } from 'svelte-vitals'` for type-checking, but that is a\n**runtime** import: it needs svelte-vitals as a declared dependency and Node 22.18+ (or 23.6+).\nA plain `export default {}` in `.mjs` behaves identically and always works.\n\n## Options\n\n| Option           | Type                                                           | Default            |\n| ---------------- | -------------------------------------------------------------- | ------------------ |\n| `treatDynamicAs` | `'pass' \\| 'warn' \\| 'fail'`                                   | `'pass'`           |\n| `metaComponents` | `string[]`                                                     | `[]`               |\n| `rules`          | `Record<ruleId, 'off' \\| Severity \\| { severity?, options? }>` | `{}`               |\n| `failOn`         | `'critical' \\| 'warning' \\| 'info'`                            | `'critical'`       |\n| `weights`        | `Partial<Record<Category, number>>`                            | every category `1` |\n| `overrides`      | `RuleOverride[]`                                               | (none)             |\n\n`Severity` is `'critical' | 'warning' | 'info'`. `Category` is `'seo' | 'performance' |\n'correctness' | 'security' | 'architecture'`. A weight of `0` drops a category from the Health\naverage; setting every category to `0` is an error (exit `2`).\n\n## Turning a rule off or down\n\n```js\nexport default {\n  rules: {\n    'seo/json-ld': 'off', // remove its findings entirely\n    'architecture/prop-count': 'info' // keep it, stop it failing the build\n  }\n};\n```\n\nMany rules take options, so check whether the finding is a **threshold disagreement** rather than\na defect first. `svelte-vitals explain <rule-id>` prints each option's name, default, bounds, and\nmerge semantics (`integer` replaces, `string-list` appends, `string-map` is spread over).\n\n```js\nexport default {\n  rules: {\n    'architecture/prop-count': { options: { max: 12 } }\n  }\n};\n```\n\n## Scoping to routes or files (`overrides`)\n\n`rules` applies everywhere; `overrides` applies only where it matches \u2014 typically routes that\nare deliberately not public.\n\n```js\nexport default {\n  overrides: [\n    { files: 'src/routes/(app)/**', rules: { seo: 'off' } },\n    { route: '/admin/**', rules: { 'seo/title-presence': 'info' } }\n  ]\n};\n```\n\nEach entry needs `rules` (keys are rule ids **or** category names) plus at least one of:\n\n- **`route`** \u2014 glob(s) against the route id as reported (`/blog/[slug]`). SvelteKit `(group)`\n  segments are **not** in the route id, so use `files` to target a group.\n- **`files`** \u2014 glob(s) against the source path.\n\nGlobs are deliberately small: `*` within a segment, `**` across segments, a trailing `/**` also\nmatches the bare prefix. Everything else \u2014 including `(`, `)`, `[`, `]` \u2014 is literal. Later entries win.\n\n## Precedence\n\nPer field: **CLI flag > config file > built-in default**. One exception \u2014 `--rules` and `--ignore`\nare selection, not configuration: `--rules` narrows the run to the ids it names and overrides a\nconfig-file `off` for them, but keeps their declared severity and options; `--ignore` adds `off`\nentries for the ids it names, layered on top of whatever `rules` resolved to, and beats `--rules`\nwhen both name the same rule.\n\n`overrides` has no CLI flag; route policy belongs in a committed file.\n\n## Validation\n\nAn unknown rule id or category, a negative weight, a malformed `overrides` entry, or an invalid\nrule setting is a **hard error (exit `2`)** \u2014 a typo must not silently un-gate CI. An unrecognized\n`treatDynamicAs`/`failOn` value, or an unknown top-level key, only warns.\n\n## Related\n\n- `svelte-vitals explain --list` \u2014 every rule id\n- `svelte-vitals docs show scoping` \u2014 accepting an existing backlog instead of disabling rules"
   },
   {
     name: "monorepo",

package/dist/index.d.ts

@@ -69,6 +69,15 @@ declare function ruleOptionsSpec(id: string): RuleOptionsSpec | undefined;
  * (--ignore). An allow-list disables every rule not listed; deny always wins.
  * Callers should reject unknown ids first (see findUnknownRuleIds) so a typo in
  * --rules can't silently disable every rule.
+ *
+ * No longer used by the CLI: `resolve-args` passes `--rules`/`--ignore` as id lists and
+ * `rule-selection.ts` composes the map (design 2026-08-06-rule-selection-design.md). The CLI
+ * used to call this with `ignore` empty and hand the result to `AnalyzeOptions.rules`, which
+ * replaces a config file's `rules` map as a whole (design 2026-07-05-config-file-design.md §3)
+ * — correct for --rules's allow-list semantics under that encoding, but not for --ignore, which
+ * names only the rule(s) it silences and must layer onto the file's map instead. Kept as
+ * exported API: a direct caller building a `rules` value from both an allow- and a deny-list on
+ * purpose gets exactly that whole-field replacement.
  */
 declare function buildRulesConfig(allow: string[], ignore: string[]): Record<string, RuleSetting>;
 
@@ -108,7 +117,21 @@ interface RunOptions {
     reporter?: ReporterName;
     byRoute?: boolean;
     failOn?: Severity;
+    /**
+     * A complete replacement for the config file's `rules` map — what the Vite plugin and
+     * programmatic callers pass. Whole-field, per the per-field precedence every other config
+     * field follows.
+     */
     rules?: Record<string, RuleSetting>;
+    /**
+     * Rule ids to silence on top of `rules`/the config file (--ignore). Unlike `rules`, this
+     * never replaces anything — it only ever adds `'off'` entries for the ids listed, so a
+     * rule not named here keeps whatever `rules`/the file said for it (design:
+     * rules-flag-clobbers-config-options).
+     */
+    ignoreRules?: string[];
+    /** `--rules`: run only these rule ids. Selection; the config file still supplies their options. */
+    allowRules?: string[];
     /** Per-category weights for the combined Health score (flag > config file > default 1 each). */
     weights?: Partial<Record<Category, number>>;
     /** Restrict analysis to rules in these categories (applied after rules/ignore selection). */
@@ -177,7 +200,21 @@ interface AnalyzeOptions {
     /** Restrict analysis to routes whose path matches this glob (matched against the route path without leading slash). */
     route?: string;
     failOn?: Severity;
+    /**
+     * A complete replacement for the config file's `rules` map — what the Vite plugin and
+     * programmatic callers pass. Whole-field, per the per-field precedence every other config
+     * field follows.
+     */
     rules?: Record<string, RuleSetting>;
+    /**
+     * Rule ids to silence on top of `rules`/the config file (--ignore). Unlike `rules`, this
+     * never replaces anything — it only ever adds `'off'` entries for the ids listed, so a
+     * rule not named here keeps whatever `rules`/the file said for it (design:
+     * rules-flag-clobbers-config-options).
+     */
+    ignoreRules?: string[];
+    /** `--rules`: run only these rule ids. Selection; the config file still supplies their options. */
+    allowRules?: string[];
     /** Per-category weights for the combined Health score (flag > config file > default 1 each). */
     weights?: Partial<Record<Category, number>>;
     /** Restrict analysis to rules in these categories (applied after rules/ignore selection). */
@@ -201,6 +238,8 @@ interface AnalyzeResult {
     version: string;
     /** Ids of the rules that ran, after `--category` narrowing. The JSON report lists these so a rule that found nothing stays distinguishable from one that was never selected. */
     ruleIds: string[];
+    /** Per-rule, per-declaration counts of places examined, unfiltered by `--diff`/`--baseline`/suppressions. */
+    examined: Record<string, Record<string, number>>;
     /** Non-fatal config-file issues (unknown top-level keys, invalid enum values). Empty when no config file or none found. */
     warnings: string[];
 }

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   ruleOptionsSpec,
   run,
   spinnerEnabled
-} from "./chunk-2WDZJQGD.js";
+} from "./chunk-6Y2E7QCQ.js";
 export {
   ProjectError,
   analyzeProject,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-vitals",
-  "version": "0.41.0",
+  "version": "0.43.0",
   "description": "A SvelteKit SEO checker — not a runtime Web Vitals reporter. Static analysis of your routes' head metadata.",
   "type": "module",
   "license": "MIT",
@@ -45,7 +45,7 @@
     "mri": "^1.2.0",
     "svelte": "^5.56.8",
     "tinyglobby": "^0.2.17",
-    "@svelte-vitals/core": "0.36.0"
+    "@svelte-vitals/core": "0.37.0"
   },
   "devDependencies": {
     "@types/estree": "^1.0.9",