@svelte-vitals/vite 0.54.5 → 0.54.7

package/README.md

@@ -34,7 +34,9 @@ export default {
 - `cwd`: project root (defaults to the Vite config root).
 - `ui`: serve the live dev dashboard (default `true`); pass `false` to keep only the build-time gate.
 
-At build time the HTML check covers prerendered routes only; the source scan applies project-wide. SSR and dynamic routes have no build output, so nothing checks their rendered HTML here. The `svelte-vitals` CLI covers them by source analysis, and browsing them during `vite dev` gets the live dashboard a rendered reading.
+A `svelte-vitals.config.*` and a `svelte-vitals-suppressions.json` in the project root are read automatically (explicit options win over the config file). Only source-scan suppression entries apply; route-level entries are skipped on every plugin surface (rendered route findings anchor to the built HTML) and the plugin says how many.
+
+At build time the HTML check covers prerendered routes only; the source scan applies project-wide. Routes that are not prerendered (server-rendered, or dynamic routes without prerendered entries) have no build output, so nothing checks their rendered HTML here. A prerendered route with `ssr = false` has build output, but only the empty app shell, so the HTML check skips it too (a `+layout` with `ssr = false` skips its subtree) and prints one warning listing the skipped routes. The `svelte-vitals` CLI covers them by source analysis, and browsing them during `vite dev` gets the live dashboard a rendered reading.
 
 See [Live dashboard](https://oekazuma.github.io/svelte-vitals/guides/dev-dashboard/) and [Plugin mode](https://oekazuma.github.io/svelte-vitals/guides/plugin-mode/) for the full picture.
 

package/dist/hooks/index.d.ts

@@ -14,6 +14,6 @@ interface SvelteVitalsHookOptions {
  * route's dashboard findings from static (source-only) to `measured` (real rendered
  * HTML). Add it to `src/hooks.server.ts`, e.g. `sequence(svelteVitalsHandle())`.
  */
-declare function svelteVitalsHandle(options?: SvelteVitalsHookOptions): Handle;
+export declare function svelteVitalsHandle(options?: SvelteVitalsHookOptions): Handle;
 //#endregion
-export { type SvelteVitalsHookOptions, svelteVitalsHandle };
+export type { SvelteVitalsHookOptions };

package/dist/index.d.ts

@@ -28,6 +28,6 @@ interface SvelteVitalsOptions {
   ui?: boolean;
 }
 /** svelte-vitals Vite/SvelteKit plugin. */
-declare function svelteVitals(options?: SvelteVitalsOptions): Plugin | Plugin[];
+export declare function svelteVitals(options?: SvelteVitalsOptions): Plugin | Plugin[];
 //#endregion
-export { type SvelteVitalsOptions, svelteVitals };
+export type { SvelteVitalsOptions };

package/dist/index.js

@@ -4,7 +4,7 @@ import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
 import { CATEGORIES, defineConfig } from "@svelte-vitals/core";
 import { ROBOTS_SOURCE_PATHS, SITEMAP_SOURCE_PATHS, SVELTE_CONFIG_FILES, VITE_CONFIG_FILES, addFactsDirectives, allRules, buildJsonReport, collectComponentFacts, collectKitModuleFacts, collectSourceFiles, collectSuppressions, computeScore, defaultConfig, findMinifyDisabled, formatConsoleReport, formatFailedRuleWarning, formatJsonReport, hasFailureAtOrAbove, renderAppShell, resolveKitAliases, resolveKitPathsBase, resolveRuleOptions, runAnalysis, safeHref, selectRules, shouldSkipRangeCheck, skippedFileWarnings, summarize, terminalSafe, unknownDirectiveIds, validateRuleSetting, withFailedRulesOff } from "@svelte-vitals/core/internal";
-import { CONFIG_FILENAMES, analyzeProject, createNodeRuntime, findUnknownRuleIds, knownRuleIds, loadConfigFile, registryTag, ruleOptionsSpec } from "svelte-vitals";
+import { CONFIG_FILENAMES, SUPPRESSIONS_FILE, analyzeProject, applySuppressions, createNodeRuntime, findUnknownRuleIds, knownRuleIds, loadConfigFile, loadSuppressions, registryTag, ruleOptionsSpec } from "svelte-vitals";
 //#region src/providers/rendered/collect.ts
 /** Map a prerendered HTML path (relative to pages/, POSIX) to its route. */
 function deriveRouteFromHtmlPath(relPath) {
@@ -157,6 +157,29 @@ function collectSourceFiles$1(root) {
 	return collectSourceFiles(nodeRuntime, root);
 }
 //#endregion
+//#region src/suppressions.ts
+/**
+* Apply `svelte-vitals-suppressions.json` the way every plugin surface must: source-scan entries
+* only. A route-level entry (route starting with `/`) is written by the CLI against
+* `src/routes/…/+page.svelte`, while the build gate's rendered findings anchor to the built HTML
+* and the dashboard's live layer to the route itself — the gate could never match it, and the
+* dashboard's static layer would drop it only until the route was browsed and the live result
+* re-surfaced it. Skipping them everywhere keeps Health identical across surfaces; the caller
+* gets one line per fact to print. Stale entries are not counted: pruning stays with the CLI.
+*/
+function applySourceSuppressions(results, entries, config) {
+	const notices = [];
+	const source = entries.filter((e) => !e.route?.startsWith("/"));
+	const routeLevel = entries.length - source.length;
+	const applied = applySuppressions(results, source, config);
+	if (applied.suppressed > 0) notices.push(`${applied.suppressed} finding(s) suppressed by ${SUPPRESSIONS_FILE}.`);
+	if (routeLevel > 0) notices.push(`${routeLevel} route-level ${routeLevel === 1 ? "entry does" : "entries do"} not apply to the plugin (${SUPPRESSIONS_FILE}) — rendered route findings anchor to the built HTML; use \`overrides\` for those.`);
+	return {
+		results: applied.results,
+		notices
+	};
+}
+//#endregion
 //#region src/version.ts
 /** Read this package's version from its own package.json so the report never drifts. */
 function readPackageVersion() {
@@ -222,24 +245,75 @@ async function resolveConfig(cwd, options) {
 	};
 }
 /**
+* `ssr` is a page option: only `+page`/`+layout` modules (universal or server) can set it. Same
+* file set as `PAGE_OPTION_FILE_RE` in core's `rules/seo/ssr-disabled.ts`, which reports the fact.
+*/
+const PAGE_OPTION_FILE_RE = /^src\/routes\/(.*?)\/?\+(page|layout)(?:\.server)?\.[jt]s$/;
+function escapeRegExp(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** One route directory segment as a pattern over the rendered (concrete) route path, leading `/` included. */
+function segmentPattern(segment) {
+	if (/^\[\.\.\.[^\]]+\]$/.test(segment)) return "(?:/.*)?";
+	if (/^\[\[[^\]]+\]\]$/.test(segment)) return "(?:/[^/]+)?";
+	return "/" + segment.split(/\[[^\]]+\]/).map(escapeRegExp).join("[^/]+");
+}
+/**
+* Routes whose prerendered HTML is the app shell rather than the page: SvelteKit still writes a
+* file for an `ssr = false` route, but its `<head>` and body only exist once the client renders,
+* so every rendered head/heading/landmark check would report the page as empty. A `+layout`
+* covers its whole subtree, a `+page` only its own route; `(group)` directories are not URL
+* segments. Two ceilings: a child route re-enabling `ssr = true` under a disabled layout is not
+* tracked, and Kit's route precedence is not modelled, so a `[param]` route also claims a literal
+* sibling (`/docs/[slug]` matches a prerendered `/docs/intro`) — the warning lists the skipped
+* routes so a wrong skip is visible.
+*/
+function ssrDisabledRouteMatcher(kitModules) {
+	const patterns = [];
+	for (const m of kitModules) {
+		const match = m.ssrDisabled ? PAGE_OPTION_FILE_RE.exec(m.file) : null;
+		if (!match) continue;
+		const path = match[1].split("/").filter((s) => s !== "" && !/^\(.+\)$/.test(s)).map(segmentPattern).join("");
+		patterns.push(new RegExp(match[2] === "layout" ? `^${path}(?:/.*)?$` : `^${path}$`));
+	}
+	return (route) => {
+		const r = route === "/" ? "" : route;
+		return patterns.some((p) => p.test(r));
+	};
+}
+/**
 * Collect prerendered heads + project facts + component facts, run the core pipeline, and
 * format reports. Config precedence: see `resolveConfig`. Pass `resolved` when the caller
-* already resolved config itself (build mode resolves it outside `analyze`'s try/catch so a
-* config-file validation error fails the build instead of being caught as an analysis error).
+* already resolved config and loaded `svelte-vitals-suppressions.json` itself (build mode does
+* both outside `analyze`'s try/catch so a validation error fails the build instead of being
+* caught as an analysis error); `suppressions: undefined` means the file does not exist.
 */
 async function analyze(prerenderPagesDir, cwd, options, extraProjectFacts, resolved) {
 	const { config, warnings } = resolved ?? await resolveConfig(cwd, options);
-	const [{ heads, headings, images, a11y, htmlLang }, components, sourceFiles] = await Promise.all([
+	const suppressions = resolved ? resolved.suppressions : loadSuppressions(cwd);
+	const [rendered, components, sourceFiles] = await Promise.all([
 		collectRenderedHeads(prerenderPagesDir),
 		collectComponentFacts$1(cwd),
 		collectSourceFiles$1(cwd)
 	]);
 	const project = {
-		...await collectRenderedProject(cwd, htmlLang),
+		...await collectRenderedProject(cwd, rendered.htmlLang),
 		...extraProjectFacts
 	};
 	const kitModules = await collectKitModuleFacts$1(cwd, project.kitAliases);
+	const isShell = ssrDisabledRouteMatcher(kitModules);
+	const keep = (items) => items.filter((i) => !isShell(i.route));
+	const heads = keep(rendered.heads);
+	const headings = keep(rendered.headings);
+	const images = keep(rendered.images);
+	const a11y = keep(rendered.a11y);
+	const shells = rendered.heads.filter((h) => isShell(h.route)).map((h) => h.route).sort();
 	const selected = selectRules(allRules, config);
+	if (shells.length > 0) {
+		const shown = shells.slice(0, 10);
+		const list = shells.length > shown.length ? `${shown.join(", ")}, … and ${shells.length - shown.length} more` : shown.join(", ");
+		warnings.push(`skipped ${shells.length} prerendered route(s) with ssr = false — their HTML is the app shell, not the page; run \`npx svelte-vitals\` to check them from source: ${list}`);
+	}
 	if (selected.some((r) => r.id === "a11y/unverified-id-ref")) warnings.push("a11y/unverified-id-ref has no effect in rendered mode — the prerendered document is always fully resolved.");
 	const directives = /* @__PURE__ */ new Map();
 	addFactsDirectives(directives, {
@@ -247,7 +321,7 @@ async function analyze(prerenderPagesDir, cwd, options, extraProjectFacts, resol
 		kitModules,
 		viteMinifyDisabled: project.viteMinifyDisabled
 	});
-	const { results, examined, failedRules, scoringConfig } = await runAnalysis(selected, {
+	const analysis = await runAnalysis(selected, {
 		heads,
 		headings,
 		images,
@@ -258,21 +332,30 @@ async function analyze(prerenderPagesDir, cwd, options, extraProjectFacts, resol
 		kitModules,
 		sourceFiles
 	}, directives);
+	const { examined, failedRules, scoringConfig } = analysis;
+	let results = analysis.results;
+	if (suppressions !== void 0) {
+		const applied = applySourceSuppressions(results, suppressions, config);
+		results = applied.results;
+		warnings.push(...applied.notices);
+	}
 	warnings.push(...skippedFileWarnings([...components, ...kitModules]));
 	warnings.push(...unknownDirectiveIds(directives, allRules));
 	for (const f of failedRules) warnings.push(formatFailedRuleWarning(f));
 	const { score } = computeScore(results, scoringConfig);
 	const summary = summarize(results, scoringConfig);
 	const failed = hasFailureAtOrAbove(summary, scoringConfig.failOn);
-	const coverageNote = `Analyzed ${heads.length} prerendered route(s). SSR/dynamic routes are not covered — run \`npx svelte-vitals\` for those.
+	const coverageNote = `Analyzed ${heads.length} prerendered route(s)${shells.length > 0 ? ` (skipped ${shells.length} with ssr = false)` : ""}. SSR/dynamic routes are not covered — run \`npx svelte-vitals\` for those.
 Scanned ${components.length} component(s) under src/ for Correctness/Security/Architecture/Accessibility/Bundle findings.`;
+	const consoleReport = formatConsoleReport(results, scoringConfig, { mode: "rendered / plugin" }) + "\n" + coverageNote + "\n";
+	const jsonReport = formatJsonReport(results, scoringConfig, { version: readPackageVersion() }, selected.map((r) => r.id), examined);
 	return {
 		score,
 		summary,
 		results,
-		consoleReport: formatConsoleReport(results, scoringConfig, { mode: "rendered / plugin" }) + "\n" + coverageNote + "\n",
-		jsonReport: formatJsonReport(results, scoringConfig, { version: readPackageVersion() }, selected.map((r) => r.id), examined),
-		routeCount: heads.length,
+		consoleReport,
+		jsonReport,
+		routeCount: rendered.heads.length,
 		failed,
 		failOn: scoringConfig.failOn,
 		warnings
@@ -586,6 +669,26 @@ function createStore() {
 //#endregion
 //#region src/ui/analysis.ts
 /**
+* Apply `svelte-vitals-suppressions.json` to the whole-project layer, same entries as the build
+* gate (see `applySourceSuppressions`). A malformed file is a warning here, not an error: dev
+* must keep serving. Returns the results unchanged when the file is absent or `config` is
+* unknown (an injected `analyze` that returns no config).
+*/
+function suppress(root, results, config, warnings) {
+	if (!config) return results;
+	let entries;
+	try {
+		entries = loadSuppressions(root);
+	} catch (err) {
+		warnings.push(`${err instanceof Error ? err.message : String(err)} — ${SUPPRESSIONS_FILE} ignored.`);
+		return results;
+	}
+	if (entries === void 0) return results;
+	const applied = applySourceSuppressions(results, entries, config);
+	warnings.push(...applied.notices);
+	return applied.results;
+}
+/**
 * Owns the dev-dashboard's whole-project analysis lifecycle: an async run at startup,
 * a debounced re-run on source changes, and coalescing so a change that arrives mid-run
 * produces exactly one follow-up run rather than one per change (design doc §1).
@@ -612,10 +715,13 @@ function createAnalysisRunner(opts) {
 				failOn: opts.failOn,
 				parseCache
 			});
-			const { results, failedRuleIds } = result;
-			if (!stopped) if (failedRuleIds !== void 0) opts.onResults(results, failedRuleIds);
-			else opts.onResults(results);
-			const warnings = result.warnings ?? [];
+			const { failedRuleIds } = result;
+			const warnings = [...result.warnings ?? []];
+			const results = suppress(opts.root, result.results, result.config, warnings);
+			if (!stopped) {
+				if (failedRuleIds !== void 0) opts.onResults(results, failedRuleIds);
+				else opts.onResults(results);
+			}
 			const key = warnings.join("\n");
 			if (!stopped && warnings.length > 0 && key !== lastWarningsKey) opts.onWarnings?.(warnings);
 			lastWarningsKey = key;
@@ -665,6 +771,7 @@ const CONFIG_BASENAMES = /* @__PURE__ */ new Set([
 	"svelte.config.js",
 	"svelte.config.ts",
 	...CONFIG_FILENAMES,
+	SUPPRESSIONS_FILE,
 	"vite.config.js",
 	"vite.config.mjs",
 	"vite.config.ts",
@@ -790,7 +897,10 @@ function svelteVitals(options = {}) {
 			const pagesDir = options.prerenderDir ? options.prerenderDir : join(root, DEFAULT_PRERENDER_DIR);
 			const resolved = isAbsolute(pagesDir) ? pagesDir : join(root, pagesDir);
 			if (!existsSync(resolved)) return;
-			const resolvedConfig = await resolveConfig(root, options);
+			const resolvedConfig = {
+				...await resolveConfig(root, options),
+				suppressions: loadSuppressions(root)
+			};
 			let result;
 			try {
 				const viteMinifyDisabled = await resolveMinifyDisabled(minify, configFile, root);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svelte-vitals/vite",
-  "version": "0.54.5",
+  "version": "0.54.7",
   "description": "Vite/SvelteKit plugin for svelte-vitals — analyzes prerendered HTML during vite build, plus a live dev dashboard.",
   "type": "module",
   "license": "MIT",
@@ -40,13 +40,13 @@
   ],
   "dependencies": {
     "esm-env": "^1.2.2",
-    "node-html-parser": "^9.0.3"
+    "node-html-parser": "^9.0.4"
   },
   "peerDependencies": {
-    "@svelte-vitals/core": "^0.54.5",
+    "@svelte-vitals/core": "^0.54.7",
     "@sveltejs/kit": "^2.70.3",
-    "svelte-vitals": "^0.54.5",
-    "vite": "^8.2.2"
+    "svelte-vitals": "^0.54.7",
+    "vite": "^8.3.0"
   },
   "peerDependenciesMeta": {
     "@sveltejs/kit": {
@@ -54,13 +54,13 @@
     }
   },
   "devDependencies": {
-    "@svelte-vitals/core": "0.54.5",
+    "@svelte-vitals/core": "0.54.7",
     "@sveltejs/kit": "^2.70.3",
-    "@types/node": "^24.13.3",
-    "happy-dom": "^20.13.2",
+    "@types/node": "^24.13.4",
+    "happy-dom": "^20.14.3",
     "svelte": "^5.57.0",
-    "svelte-vitals": "0.54.5",
-    "vite": "^8.2.2"
+    "svelte-vitals": "0.54.7",
+    "vite": "^8.3.0"
   },
   "scripts": {
     "build": "tsdown",