@svelte-vitals/core 0.16.0 → 0.18.0

package/dist/index.d.ts

@@ -55,7 +55,7 @@ interface Result {
     line?: number;
 }
 type Scope = 'route' | 'project' | 'component';
-type Category = 'seo' | 'performance' | 'correctness' | 'security';
+type Category = 'seo' | 'performance' | 'correctness' | 'security' | 'architecture';
 /** How dynamic (`{data.title}`) values are treated by scoring (design §4, §12). */
 type TreatDynamicAs = 'pass' | 'warn' | 'fail';
 /** Per-rule override: disable, or change severity. */
@@ -216,13 +216,15 @@ interface EffectFact {
     line: number;
     /** True when the effect body only assigns to `$state` variables (the "use $derived" smell). */
     assignsOnlyState: boolean;
+    /** True when this $effect has a NON-EMPTY body that reads no reactive value and makes no bare call — it never re-runs, so it should be onMount (CORRECT003). */
+    mountOnly: boolean;
 }
 /** A flagged source position in a component (e.g. an `{@html}` tag or a `javascript:` URL). */
 interface SourceSpan {
     /** 1-based source line, or 0 if unknown. */
     line: number;
 }
-/** Reactivity/correctness + security facts parsed from one `.svelte` component. */
+/** Reactivity/correctness + security + architecture facts parsed from one `.svelte` component. */
 interface ComponentFacts {
     /** Source file the component came from. */
     file: string;
@@ -232,6 +234,22 @@ interface ComponentFacts {
     htmlTags: SourceSpan[];
     /** Element attributes with a literal `javascript:` URL (Security SEC002). */
     javascriptUrls: SourceSpan[];
+    /** Source line count of the component file (Architecture ARCH001). */
+    loc: number;
+    /** Named props destructured from `$props()`; 0 when unknowable (rest / non-destructured) (Architecture ARCH002). */
+    propCount: number;
+    /** Module specifiers of every `import` in the instance + module scripts (Bundle PERF009). */
+    imports: string[];
+    /** Value `import * as X from '<bare pkg>'` namespace imports (type-only excluded) — Bundle PERF010. */
+    namespaceImports: {
+        source: string;
+        line: number;
+    }[];
+    /** `$state` declarations never written or escaped anywhere in the component — candidates for const (CORRECT004). */
+    constableStates: {
+        name: string;
+        line: number;
+    }[];
 }
 
 /**
@@ -404,10 +422,20 @@ declare const seo030HeadingOrder: Rule;
 
 declare const correct001EachKey: Rule;
 declare const correct002EffectDerived: Rule;
+declare const correct003EffectAsOnMount: Rule;
+
+declare const correct004UnmutatedState: Rule;
 
 declare const sec001Html: Rule;
 declare const sec002JavascriptUrl: Rule;
 
+declare const arch001ComponentSize: Rule;
+declare const arch002PropCount: Rule;
+
+declare const perf009HeavyImport: Rule;
+
+declare const perf010NamespaceImport: Rule;
+
 declare const allRules: Rule[];
 
 interface RuleInfo {
@@ -498,10 +526,26 @@ declare function summarize(results: Result[], config: Config): Summary;
 /** Whether the run should fail the build/CI per the minimum failing severity. */
 declare function hasFailureAtOrAbove(summary: Summary, min: Severity): boolean;
 
+/** String decorators for the console reporter. Injected so core stays pure/dep-free. */
+interface Palette {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    red: (s: string) => string;
+    yellow: (s: string) => string;
+    green: (s: string) => string;
+    cyan: (s: string) => string;
+}
+/** Default: no decoration (identity) — output is byte-identical to plain text. */
+declare const noColorPalette: Palette;
+/** Green ≥ 90, yellow ≥ 70, red otherwise — for a 0–100 score. */
+declare function scoreColor(p: Palette, score: number): (s: string) => string;
+
 interface ConsoleReportOptions {
     byRoute?: boolean;
     /** Mode label shown in the header (default 'static mode'). */
     mode?: string;
+    /** Color decorators; defaults to no color. */
+    palette?: Palette;
 }
 /**
  * Render results as a console report string (design §7). Pure: returns a string,
@@ -616,4 +660,4 @@ declare function selectRules(rules: Rule[], config: Config): Rule[];
 /** Apply per-rule severity overrides to results (design §6). */
 declare function applyRuleSeverities(results: Result[], config: Config): Result[];
 
-export { BAND_COLOR, 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 Presence, type Project, ROBOTS_SOURCE_PATHS, type ResolvedHead, type ResolvedHeadings, type ResolvedImages, type Result, type Rule, type RuleContext, type RuleInfo, type RuleSetting, type Runtime, SITEMAP_SOURCE_PATHS, type Scope, type ScoreModel, type ScoreOptions, type ScoreResult, type Severity, type SourceSpan, type Summary, type TreatDynamicAs, type Value, allRules, applyRuleSeverities, buildHtmlDocument, buildJsonReport, classify, computeHealth, computeScore, correct001EachKey, correct002EffectDerived, defaultConfig, defaultProject, defineConfig, docsUrlFor, effectiveSeverity, escapeHtml, explainRule, formatAgentReport, formatConsoleReport, formatGithubReport, formatHtmlReport, formatJsonReport, formatSarifReport, hasFailureAtOrAbove, headTagRule, imageRule, isPenalized, linkRule, perf001ImageDimensions, perf002ImageLoading, perf003PreloadAs, perf004FontPreloadCrossorigin, perf005LcpImage, perf006ResponsiveImage, perf007RenderBlockingScript, perf008Preconnect, runRules, safeHref, scoreBand, scoresByCategory, sec001Html, sec002JavascriptUrl, selectRules, seo001Title, seo002Description, seo003Canonical, seo004OgImage, seo005OgTitle, seo006Robots, seo007Sitemap, seo008JsonLd, seo009HtmlLang, seo010Indexability, seo011TwitterCard, seo012OgDescription, seo013OgUrl, seo014Viewport, seo015SitemapInRobots, seo016JsonLdValidity, seo017DeprecatedType, seo018RelativeUrl, seo019DateFormat, seo020Placeholder, seo021RequiredProps, seo022TitleLength, seo023DescriptionLength, seo024Charset, seo025ImageAlt, seo026Hreflang, seo027Heading, seo028TitleUnique, seo029DescriptionUnique, seo030HeadingOrder, summarize };
+export { BAND_COLOR, type Category, type Classification, type ComponentFacts, type Config, type ConsoleReportOptions, type Detection, type EachBlockFact, type EffectFact, type Fix, type HeadProvider, type HeadTag, type HeadingInfo, type HealthResult, type ImageInfo, type JsonReport, type Palette, type Presence, type Project, ROBOTS_SOURCE_PATHS, type ResolvedHead, type ResolvedHeadings, type ResolvedImages, type Result, type Rule, type RuleContext, type RuleInfo, type RuleSetting, type Runtime, SITEMAP_SOURCE_PATHS, type Scope, type ScoreModel, type ScoreOptions, type ScoreResult, type Severity, type SourceSpan, type Summary, type TreatDynamicAs, type Value, allRules, applyRuleSeverities, arch001ComponentSize, arch002PropCount, buildHtmlDocument, buildJsonReport, classify, computeHealth, computeScore, correct001EachKey, correct002EffectDerived, correct003EffectAsOnMount, correct004UnmutatedState, defaultConfig, defaultProject, defineConfig, docsUrlFor, effectiveSeverity, escapeHtml, explainRule, formatAgentReport, formatConsoleReport, formatGithubReport, formatHtmlReport, formatJsonReport, formatSarifReport, hasFailureAtOrAbove, headTagRule, imageRule, isPenalized, linkRule, noColorPalette, perf001ImageDimensions, perf002ImageLoading, perf003PreloadAs, perf004FontPreloadCrossorigin, perf005LcpImage, perf006ResponsiveImage, perf007RenderBlockingScript, perf008Preconnect, perf009HeavyImport, perf010NamespaceImport, runRules, safeHref, scoreBand, scoreColor, scoresByCategory, sec001Html, sec002JavascriptUrl, selectRules, seo001Title, seo002Description, seo003Canonical, seo004OgImage, seo005OgTitle, seo006Robots, seo007Sitemap, seo008JsonLd, seo009HtmlLang, seo010Indexability, seo011TwitterCard, seo012OgDescription, seo013OgUrl, seo014Viewport, seo015SitemapInRobots, seo016JsonLdValidity, seo017DeprecatedType, seo018RelativeUrl, seo019DateFormat, seo020Placeholder, seo021RequiredProps, seo022TitleLength, seo023DescriptionLength, seo024Charset, seo025ImageAlt, seo026Hreflang, seo027Heading, seo028TitleUnique, seo029DescriptionUnique, seo030HeadingOrder, summarize };

package/dist/index.js

@@ -1507,6 +1507,32 @@ var correct002EffectDerived = componentRule({
   applies: (c) => c.effects.length > 0,
   bad: (c) => c.effects.filter((e) => e.assignsOnlyState).map((e) => ({ line: e.line, message: "$effect only assigns state \u2014 use $derived instead" }))
 });
+var correct003EffectAsOnMount = componentRule({
+  id: "CORRECT003",
+  title: "Effect used as onMount",
+  category: "correctness",
+  label: "$effect usage",
+  recommendation: "Move mount-time side effects to onMount (import { onMount } from 'svelte'); reserve $effect for logic that reacts to $state/$derived/$props.",
+  rationale: "An $effect that reads no reactive value runs once after mount and never re-runs \u2014 it is an onMount in disguise, which obscures intent and misuses the reactivity system.",
+  applies: (c) => c.effects.length > 0,
+  bad: (c) => c.effects.filter((e) => e.mountOnly).map((e) => ({ line: e.line, message: "$effect reads no reactive value \u2014 use onMount instead" }))
+});
+
+// src/rules/correctness/correct004-unmutated-state.ts
+var correct004UnmutatedState = componentRule({
+  id: "CORRECT004",
+  title: "Unmutated $state",
+  category: "correctness",
+  severity: "info",
+  label: "$state usage",
+  recommendation: "If a value never changes, use const; if you only ever reassign it wholesale (never mutate its properties), use $state.raw to skip deep proxying.",
+  rationale: "A $state that is never mutated pays for reactivity (deep proxying, tracking) it never uses; const (or $state.raw) is clearer and cheaper.",
+  applies: (c) => c.constableStates.length > 0,
+  bad: (c) => c.constableStates.map((s) => ({
+    line: s.line,
+    message: `$state "${s.name}" is never mutated \u2014 use const (or $state.raw if you only reassign it)`
+  }))
+});
 
 // src/rules/security/sec001-002.ts
 var sec001Html = componentRule({
@@ -1530,6 +1556,83 @@ var sec002JavascriptUrl = componentRule({
   bad: (c) => c.javascriptUrls.map((u) => ({ line: u.line, message: "javascript: URL in an attribute" }))
 });
 
+// src/rules/architecture/arch001-002.ts
+var MAX_LOC = 400;
+var MAX_PROPS = 10;
+var arch001ComponentSize = componentRule({
+  id: "ARCH001",
+  title: "Component size",
+  category: "architecture",
+  severity: "info",
+  label: "Component size",
+  recommendation: `Split components over ${MAX_LOC} lines into smaller, focused pieces.`,
+  rationale: "A very large component is hard to read, test, and reuse, and is a common sign that several responsibilities should be split out.",
+  applies: (c) => c.loc > 0,
+  // skip unanalyzable files (loc 0 = read/parse failure), don't PASS them
+  bad: (c) => c.loc > MAX_LOC ? [{ line: 1, message: `Component is ${c.loc} lines (over ${MAX_LOC})` }] : []
+});
+var arch002PropCount = componentRule({
+  id: "ARCH002",
+  title: "Prop count",
+  category: "architecture",
+  severity: "info",
+  label: "Prop count",
+  recommendation: `Group related props into an object, or split the component, when it takes more than ${MAX_PROPS} props.`,
+  rationale: "A component taking many props is usually doing too much; grouping or splitting keeps its API understandable.",
+  applies: (c) => c.propCount > 0,
+  // only components whose props we could count
+  bad: (c) => c.propCount > MAX_PROPS ? [{ line: 1, message: `Component takes ${c.propCount} props (over ${MAX_PROPS})` }] : []
+});
+
+// src/rules/performance/perf009-heavy-import.ts
+var HEAVY_PACKAGES = {
+  lodash: "import a submodule (lodash/debounce) or use lodash-es for tree-shaking",
+  moment: "use a lighter date library (date-fns or dayjs) \u2014 moment is large and not tree-shakeable"
+};
+var perf009HeavyImport = componentRule({
+  id: "PERF009",
+  title: "Heavy dependency import",
+  category: "performance",
+  severity: "info",
+  label: "No heavy imports",
+  recommendation: "Import a submodule or switch to a lighter, tree-shakeable alternative.",
+  rationale: "Importing a large, non-tree-shakeable package pulls its whole weight into the bundle even when only a fraction is used, slowing load.",
+  applies: (c) => c.imports.length > 0,
+  bad: (c) => {
+    const seen = /* @__PURE__ */ new Set();
+    const out = [];
+    for (const src of c.imports) {
+      if (!Object.hasOwn(HEAVY_PACKAGES, src) || seen.has(src)) continue;
+      seen.add(src);
+      out.push({ line: 0, message: `Heavy import "${src}" \u2014 ${HEAVY_PACKAGES[src]}` });
+    }
+    return out;
+  }
+});
+
+// src/rules/performance/perf010-namespace-import.ts
+var perf010NamespaceImport = componentRule({
+  id: "PERF010",
+  title: "Namespace import",
+  category: "performance",
+  severity: "info",
+  label: "No namespace imports",
+  recommendation: "Use named imports (import { x } from 'pkg') instead of import * as \u2014 a namespace import keeps the whole module in the bundle.",
+  rationale: "A namespace import (import * as X) forces the bundler to retain the entire module, so unused exports cannot be tree-shaken out.",
+  applies: (c) => c.namespaceImports.length > 0,
+  bad: (c) => {
+    const minLine = /* @__PURE__ */ new Map();
+    for (const ns of c.namespaceImports) {
+      const prev = minLine.get(ns.source);
+      if (prev === void 0 || ns.line < prev) minLine.set(ns.source, ns.line);
+    }
+    return [...minLine.entries()].sort((a, b) => a[1] - b[1]).map(([source, line]) => ({
+      line,
+      message: `Namespace import "* as \u2026 from '${source}'" \u2014 prefer named imports so the bundler can tree-shake`
+    }));
+  }
+});
+
 // src/rules/index.ts
 var allRules = [
   seo001Title,
@@ -1572,8 +1675,14 @@ var allRules = [
   seo030HeadingOrder,
   correct001EachKey,
   correct002EffectDerived,
+  correct003EffectAsOnMount,
+  correct004UnmutatedState,
   sec001Html,
-  sec002JavascriptUrl
+  sec002JavascriptUrl,
+  arch001ComponentSize,
+  arch002PropCount,
+  perf009HeavyImport,
+  perf010NamespaceImport
 ];
 function explainRule(id) {
   const target = id.toUpperCase();
@@ -1700,6 +1809,21 @@ function computeHealth(results, config) {
   return { health, categories, weights };
 }
 
+// src/reporter/palette.ts
+var noColorPalette = {
+  bold: (s) => s,
+  dim: (s) => s,
+  red: (s) => s,
+  yellow: (s) => s,
+  green: (s) => s,
+  cyan: (s) => s
+};
+function scoreColor(p, score) {
+  if (score >= 90) return p.green;
+  if (score >= 70) return p.yellow;
+  return p.red;
+}
+
 // src/reporter/console.ts
 var RULE = "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500";
 var SEVERITY_TITLE = {
@@ -1711,66 +1835,77 @@ var CATEGORY_LABEL = {
   seo: "SEO",
   performance: "Performance",
   correctness: "Correctness",
-  security: "Security"
+  security: "Security",
+  architecture: "Architecture"
 };
-var CATEGORY_ORDER = ["seo", "performance", "correctness", "security"];
-function scoreLine(label, { score, scoreModel }) {
+var CATEGORY_ORDER = ["seo", "performance", "correctness", "security", "architecture"];
+function scoreLine(p, label, { score, scoreModel }) {
   const parts = [`route avg ${scoreModel.routeAverage}`];
   if (scoreModel.sitePenalty > 0) parts.push(`site \u2212${scoreModel.sitePenalty}`);
   if (scoreModel.criticalCap !== null) parts.push(`capped at ${scoreModel.criticalCap}: critical present`);
-  return `${label} Score: ${score}/100   (${parts.join(" \xB7 ")})`;
+  return `${label} Score: ${scoreColor(p, score)(`${score}/100`)}   ${p.dim(`(${parts.join(" \xB7 ")})`)}`;
 }
-function byRouteTree(results, config) {
+function byRouteTree(p, results, config) {
   const routes = /* @__PURE__ */ new Map();
   for (const r of results) {
     if (r.route === void 0) continue;
     if (!routes.has(r.route)) routes.set(r.route, []);
     routes.get(r.route).push(r);
   }
-  const lines = ["By route", RULE];
+  const lines = [p.bold("By route"), p.dim(RULE)];
   for (const [route, rs] of [...routes.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
     const { score } = computeScore(rs, config, { applyCriticalCap: false });
-    lines.push(`${route.padEnd(28)} ${score}`);
+    lines.push(`${route.padEnd(28)} ${scoreColor(p, score)(`${score}`)}`);
     for (const r of rs.filter((x) => classify(x, config) === "fail")) {
-      lines.push(`    \u2717 ${r.id}  ${r.message}`);
+      lines.push(`    ${p.red("\u2717")} ${r.id}  ${r.message}`);
     }
   }
   lines.push("");
   return lines;
 }
 function formatConsoleReport(results, config, options = {}) {
+  const p = options.palette ?? noColorPalette;
   const summary = summarize(results, config);
   const { health, categories: byCat } = computeHealth(results, config);
   const present2 = CATEGORY_ORDER.filter((c) => byCat[c] !== void 0);
-  const header = [`Svelte Vitals  \xB7  ${options.mode ?? "static mode"}`, "", `Health: ${health}/100`];
+  const header = [
+    p.bold(`Svelte Vitals  \xB7  ${options.mode ?? "static mode"}`),
+    "",
+    `${p.bold("Health:")} ${scoreColor(p, health)(`${health}/100`)}`
+  ];
   for (const c of present2) {
-    header.push(scoreLine(CATEGORY_LABEL[c] ?? c, byCat[c]));
+    header.push(scoreLine(p, CATEGORY_LABEL[c] ?? c, byCat[c]));
   }
   const lines = [...header, ""];
+  const SEVERITY_COLOR = {
+    critical: (s) => p.red(p.bold(s)),
+    warning: (s) => p.yellow(p.bold(s)),
+    info: (s) => p.dim(s)
+  };
   const failures = results.filter((r) => classify(r, config) === "fail");
   for (const severity of ["critical", "warning", "info"]) {
     const bucket = failures.filter((r) => effectiveSeverity(r, config) === severity);
     if (bucket.length === 0) continue;
-    lines.push(`${SEVERITY_TITLE[severity]} (${bucket.length})`, RULE);
+    lines.push(SEVERITY_COLOR[severity](`${SEVERITY_TITLE[severity]} (${bucket.length})`), p.dim(RULE));
     for (const r of bucket) {
-      lines.push(`\u2717 ${r.id}  ${r.message}`);
-      if (r.route) lines.push(`            ${r.route}`);
-      if (r.location) lines.push(`            ${r.location}${r.line ? `:${r.line}` : ""}`);
+      lines.push(`${p.red("\u2717")} ${r.id}  ${r.message}`);
+      if (r.route) lines.push(p.dim(`            ${r.route}`));
+      if (r.location) lines.push(p.dim(`            ${r.location}${r.line ? `:${r.line}` : ""}`));
     }
     lines.push("");
   }
   const passed = results.filter((r) => classify(r, config) !== "fail");
   if (passed.length > 0) {
-    lines.push(`Passed (${passed.length})`, RULE);
+    lines.push(p.bold(`Passed (${passed.length})`), p.dim(RULE));
     for (const r of passed) {
-      const marker = classify(r, config) === "dynamic" ? "  \u21AF dynamic" : "";
+      const marker = classify(r, config) === "dynamic" ? p.cyan("  \u21AF dynamic") : "";
       const route = r.route ? `  ${r.route}` : "";
-      lines.push(`\u2713 ${r.id}  ${r.message}${marker}${route}`);
+      lines.push(`${p.green("\u2713")} ${r.id}  ${r.message}${marker}${route}`);
     }
     lines.push("");
   }
-  if (options.byRoute) lines.push(...byRouteTree(results, config));
-  if (summary.dynamic > 0) lines.push("\u21AF = set dynamically (verified at runtime).");
+  if (options.byRoute) lines.push(...byRouteTree(p, results, config));
+  if (summary.dynamic > 0) lines.push(p.dim("\u21AF = set dynamically (verified at runtime)."));
   return lines.join("\n").replace(/\n+$/, "\n");
 }
 
@@ -2161,6 +2296,8 @@ export {
   SITEMAP_SOURCE_PATHS,
   allRules,
   applyRuleSeverities,
+  arch001ComponentSize,
+  arch002PropCount,
   buildHtmlDocument,
   buildJsonReport,
   classify,
@@ -2168,6 +2305,8 @@ export {
   computeScore,
   correct001EachKey,
   correct002EffectDerived,
+  correct003EffectAsOnMount,
+  correct004UnmutatedState,
   defaultConfig,
   defaultProject,
   defineConfig,
@@ -2186,6 +2325,7 @@ export {
   imageRule,
   isPenalized,
   linkRule,
+  noColorPalette,
   perf001ImageDimensions,
   perf002ImageLoading,
   perf003PreloadAs,
@@ -2194,9 +2334,12 @@ export {
   perf006ResponsiveImage,
   perf007RenderBlockingScript,
   perf008Preconnect,
+  perf009HeavyImport,
+  perf010NamespaceImport,
   runRules,
   safeHref,
   scoreBand,
+  scoreColor,
   scoresByCategory,
   sec001Html,
   sec002JavascriptUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svelte-vitals/core",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Shared, runtime-agnostic core for svelte-vitals (types, rule engine, scorer, reporter).",
   "type": "module",
   "license": "MIT",
@@ -21,7 +21,7 @@
   },
   "homepage": "https://github.com/oekazuma/svelte-vitals#readme",
   "engines": {
-    "node": ">=18"
+    "node": ">=18.20.8"
   },
   "sideEffects": false,
   "exports": {