@svelte-vitals/core 0.16.0 → 0.19.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,22 @@ 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. */
+/** An inline `svelte-vitals-disable-next-line` directive found in the component's source (issue #92). */
+interface SuppressionDirective {
+    /** 1-based line the directive suppresses (the line immediately after the comment). */
+    line: number;
+    /** Rule ids suppressed on that line; undefined = suppress every rule on that line. */
+    ruleIds?: string[];
+}
+/** Reactivity/correctness + security + architecture facts parsed from one `.svelte` component. */
 interface ComponentFacts {
     /** Source file the component came from. */
     file: string;
@@ -232,8 +241,74 @@ 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;
+    }[];
+    /** Inline `svelte-vitals-disable-next-line` directives found in this file's source — component-rule escape hatch (issue #92). Optional: absent is equivalent to no directives, so existing external constructors of `ComponentFacts` are unaffected. */
+    suppressions?: SuppressionDirective[];
 }
 
+/** Parse a component's reactivity/correctness + security + architecture facts (CLI/static + vite build mode). */
+declare function parseComponentFacts(source: string, filename: string): {
+    eachBlocks: EachBlockFact[];
+    effects: EffectFact[];
+    htmlTags: SourceSpan[];
+    javascriptUrls: SourceSpan[];
+    loc: number;
+    propCount: number;
+    imports: string[];
+    namespaceImports: {
+        source: string;
+        line: number;
+    }[];
+    constableStates: {
+        name: string;
+        line: number;
+    }[];
+    suppressions: SuppressionDirective[];
+};
+
+type Node = any;
+/**
+ * All keys that can bear child nodes in a Svelte AST node.
+ * Covers if/each/await blocks (pending/then/catch/fallback) as well as
+ * the standard fragment, nodes, consequent, alternate, and body keys.
+ */
+declare const CHILD_NODE_KEYS: string[];
+/**
+ * Determine a value's kind from a list of child/text nodes (design §4, §11):
+ *   - any ExpressionTag present  → 'dynamic' (e.g. {data.title}); we do NOT
+ *     follow the expression — that would turn this into runtime analysis.
+ *   - non-whitespace Text only   → 'static'
+ *   - empty / whitespace only    → 'absent'
+ */
+declare function valueFromNodes(nodes: Node[]): Value;
+/** The literal text of a node list when fully static (no ExpressionTag), else undefined. */
+declare function textFromNodes(nodes: Node[]): string | undefined;
+/** Static string of an attribute (e.g. name="description"), or undefined if dynamic/absent. */
+declare function attrText(attributes: Node[], name: string): string | undefined;
+/** Value kind of an attribute's content (e.g. the `content` of a <meta>). */
+declare function attrValue(attributes: Node[], name: string): Value;
+declare function lineOf(source: string, offset: unknown): number;
+declare function findAttr(attributes: Node[], name: string): Node | undefined;
+/** Value kind of a single attribute (e.g. a component prop). */
+declare function attrValueOf(attr: Node): Value;
+/** Literal static text of a single attribute node (e.g. a component prop), or undefined if dynamic/absent. */
+declare function attrTextOf(attr: Node): string | undefined;
+
 /**
  * Source-file locations that satisfy the project-scope rules, shared by every
  * mode so the static (CLI) and rendered (plugin) collectors never drift. This
@@ -404,10 +479,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 +583,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 +717,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, 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 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 SuppressionDirective, type TreatDynamicAs, type Value, allRules, applyRuleSeverities, arch001ComponentSize, arch002PropCount, attrText, attrTextOf, attrValue, attrValueOf, buildHtmlDocument, buildJsonReport, classify, computeHealth, computeScore, correct001EachKey, correct002EffectDerived, correct003EffectAsOnMount, correct004UnmutatedState, defaultConfig, defaultProject, defineConfig, docsUrlFor, effectiveSeverity, escapeHtml, explainRule, findAttr, formatAgentReport, formatConsoleReport, formatGithubReport, formatHtmlReport, formatJsonReport, formatSarifReport, hasFailureAtOrAbove, headTagRule, imageRule, isPenalized, lineOf, linkRule, noColorPalette, parseComponentFacts, 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, textFromNodes, valueFromNodes };

package/dist/index.js

@@ -14,6 +14,408 @@ function defineConfig(config = {}) {
   return { ...defaultConfig, ...config };
 }
 
+// src/component-parse.ts
+import { parse } from "svelte/compiler";
+
+// src/svelte-ast.ts
+var CHILD_NODE_KEYS = [
+  "fragment",
+  "nodes",
+  "consequent",
+  "alternate",
+  "body",
+  "pending",
+  "then",
+  "catch",
+  "fallback"
+];
+function valueFromNodes(nodes) {
+  if (!Array.isArray(nodes)) return "absent";
+  if (nodes.some((n) => n?.type === "ExpressionTag")) return "dynamic";
+  const text = nodes.filter((n) => n?.type === "Text").map((n) => String(n.data ?? "")).join("");
+  return text.trim().length > 0 ? "static" : "absent";
+}
+function textFromNodes(nodes) {
+  if (!Array.isArray(nodes) || nodes.some((n) => n?.type === "ExpressionTag")) return void 0;
+  const text = nodes.filter((n) => n?.type === "Text").map((n) => String(n.data ?? "")).join("");
+  return text.trim().length > 0 ? text : void 0;
+}
+function attrText(attributes, name) {
+  const attr = findAttr(attributes, name);
+  if (!attr) return void 0;
+  const v = attr.value;
+  if (v === true) return "";
+  if (Array.isArray(v)) {
+    if (v.some((n) => n?.type === "ExpressionTag")) return void 0;
+    return v.filter((n) => n?.type === "Text").map((n) => String(n.data ?? "")).join("");
+  }
+  return void 0;
+}
+function attrValue(attributes, name) {
+  const attr = findAttr(attributes, name);
+  if (!attr) return "absent";
+  const v = attr.value;
+  if (v === true) return "absent";
+  if (Array.isArray(v)) return valueFromNodes(v);
+  if (v && v.type === "ExpressionTag") return "dynamic";
+  return "absent";
+}
+function lineOf(source, offset) {
+  if (typeof offset !== "number" || offset < 0) return 0;
+  let line = 1;
+  const end = Math.min(offset, source.length);
+  for (let i = 0; i < end; i++) if (source[i] === "\n") line++;
+  return line;
+}
+function findAttr(attributes, name) {
+  if (!Array.isArray(attributes)) return void 0;
+  return attributes.find((a) => a?.type === "Attribute" && a.name === name);
+}
+function attrValueOf(attr) {
+  const v = attr?.value;
+  if (v === true) return "absent";
+  if (Array.isArray(v)) return valueFromNodes(v);
+  if (v && v.type === "ExpressionTag") return "dynamic";
+  return "absent";
+}
+function attrTextOf(attr) {
+  const v = attr?.value;
+  if (!Array.isArray(v) || v.some((n) => n?.type === "ExpressionTag")) return void 0;
+  const text = v.filter((n) => n?.type === "Text").map((n) => String(n.data ?? "")).join("");
+  return text.trim().length > 0 ? text : void 0;
+}
+
+// src/component-parse.ts
+function isConstantListEach(node) {
+  const expr = node?.expression;
+  return expr?.type === "ArrayExpression" && Array.isArray(expr.elements) && !expr.elements.some((el) => el?.type === "SpreadElement");
+}
+function collectEachBlocks(node, source, acc) {
+  if (Array.isArray(node)) {
+    for (const child of node) collectEachBlocks(child, source, acc);
+    return;
+  }
+  if (!node || typeof node !== "object") return;
+  if (node.type === "EachBlock" && !isConstantListEach(node)) {
+    acc.push({ hasKey: node.key != null, line: lineOf(source, node.start) });
+  }
+  for (const key of CHILD_NODE_KEYS) {
+    if (key in node) collectEachBlocks(node[key], source, acc);
+  }
+}
+function walkEstree(node, visit) {
+  if (Array.isArray(node)) {
+    for (const child of node) walkEstree(child, visit);
+    return;
+  }
+  if (!node || typeof node !== "object" || typeof node.type !== "string") return;
+  visit(node);
+  for (const key of Object.keys(node)) {
+    if (key === "type" || key === "start" || key === "end" || key === "loc" || key === "range") continue;
+    walkEstree(node[key], visit);
+  }
+}
+function isEffectCall(node) {
+  const c = node?.callee;
+  if (c?.type === "Identifier") return c.name === "$effect";
+  if (c?.type === "MemberExpression" && c.object?.type === "Identifier" && c.object.name === "$effect") {
+    return c.property?.type === "Identifier" && c.property.name === "pre";
+  }
+  return false;
+}
+function isStateDeclaration(node) {
+  const c = node?.callee;
+  if (c?.type === "Identifier") return c.name === "$state";
+  if (c?.type === "MemberExpression" && c.object?.type === "Identifier" && c.object.name === "$state") {
+    return c.property?.type === "Identifier" && (c.property.name === "raw" || c.property.name === "frozen");
+  }
+  return false;
+}
+function bodyOnlyAssignsState(fn, stateNames) {
+  const isStateAssign = (expr) => expr?.type === "AssignmentExpression" && expr.operator === "=" && expr.left?.type === "Identifier" && stateNames.has(expr.left.name);
+  const body = fn?.body;
+  if (!body) return false;
+  if (body.type !== "BlockStatement") return isStateAssign(body);
+  if (body.body.length === 0) return false;
+  return body.body.every((s) => s?.type === "ExpressionStatement" && isStateAssign(s.expression));
+}
+function isDerivedDeclaration(node) {
+  const c = node?.callee;
+  if (c?.type === "Identifier") return c.name === "$derived";
+  if (c?.type === "MemberExpression" && c.object?.type === "Identifier" && c.object.name === "$derived") {
+    return c.property?.type === "Identifier" && c.property.name === "by";
+  }
+  return false;
+}
+function addBoundNames(id, acc) {
+  if (!id) return;
+  switch (id.type) {
+    case "Identifier":
+      acc.add(id.name);
+      break;
+    case "ObjectPattern":
+      for (const p of id.properties ?? []) {
+        if (p?.type === "Property") addBoundNames(p.value, acc);
+        else if (p?.type === "RestElement") addBoundNames(p.argument, acc);
+      }
+      break;
+    case "ArrayPattern":
+      for (const el of id.elements ?? []) addBoundNames(el, acc);
+      break;
+    case "AssignmentPattern":
+      addBoundNames(id.left, acc);
+      break;
+    case "RestElement":
+      addBoundNames(id.argument, acc);
+      break;
+  }
+}
+function rootObjectName(node) {
+  let cur = node;
+  while (cur?.type === "MemberExpression") cur = cur.object;
+  return cur?.type === "Identifier" ? cur.name : void 0;
+}
+function collectStateWrites(root, stateNames, acc) {
+  walkEstree(root, (n) => {
+    if (n?.type === "AssignmentExpression") {
+      if (n.left?.type === "Identifier" && stateNames.has(n.left.name)) acc.add(n.left.name);
+      else if (n.left?.type === "MemberExpression") {
+        const r = rootObjectName(n.left);
+        if (r && stateNames.has(r)) acc.add(r);
+      } else if (n.left?.type === "ObjectPattern" || n.left?.type === "ArrayPattern") {
+        const bound = /* @__PURE__ */ new Set();
+        addBoundNames(n.left, bound);
+        for (const name of bound) if (stateNames.has(name)) acc.add(name);
+      }
+    } else if (n?.type === "UpdateExpression") {
+      const r = rootObjectName(n.argument);
+      if (r && stateNames.has(r)) acc.add(r);
+    } else if (n?.type === "UnaryExpression" && n.operator === "delete") {
+      const r = rootObjectName(n.argument);
+      if (r && stateNames.has(r)) acc.add(r);
+    } else if (n?.type === "CallExpression") {
+      if (n.callee?.type === "MemberExpression") {
+        const r = rootObjectName(n.callee);
+        if (r && stateNames.has(r)) acc.add(r);
+      }
+      for (const a of n.arguments ?? []) {
+        const arg = a?.type === "SpreadElement" ? a.argument : a;
+        const r = rootObjectName(arg);
+        if (r && stateNames.has(r)) acc.add(r);
+      }
+    }
+  });
+}
+var COMPONENT_LIKE_TYPES = /* @__PURE__ */ new Set(["Component", "SvelteComponent", "SvelteSelf"]);
+function collectTemplateEscapes(node, stateNames, acc) {
+  if (Array.isArray(node)) {
+    for (const c of node) collectTemplateEscapes(c, stateNames, acc);
+    return;
+  }
+  if (!node || typeof node !== "object" || typeof node.type !== "string") return;
+  if (Array.isArray(node.attributes)) {
+    for (const attr of node.attributes) {
+      if (attr?.type === "BindDirective") {
+        const r = rootObjectName(attr.expression);
+        if (r && stateNames.has(r)) acc.add(r);
+      } else if (COMPONENT_LIKE_TYPES.has(node.type)) {
+        walkEstree(attr, (m) => {
+          if (m?.type === "Identifier" && stateNames.has(m.name)) acc.add(m.name);
+        });
+      }
+    }
+  }
+  for (const key of CHILD_NODE_KEYS) {
+    if (key in node) collectTemplateEscapes(node[key], stateNames, acc);
+  }
+}
+var RUNE_NAMES = /* @__PURE__ */ new Set(["$state", "$derived", "$effect", "$props", "$bindable", "$inspect", "$host"]);
+function bodyReadsReactive(fn, reactiveNames) {
+  let reads = false;
+  const IGNORED_KEYS = /* @__PURE__ */ new Set(["type", "start", "end", "loc", "range"]);
+  const visit = (n) => {
+    if (reads || !n) return;
+    if (Array.isArray(n)) {
+      for (const c of n) visit(c);
+      return;
+    }
+    if (typeof n !== "object" || typeof n.type !== "string") return;
+    if (n.type === "Identifier") {
+      if (reactiveNames.has(n.name) || n.name.startsWith("$") && !RUNE_NAMES.has(n.name)) reads = true;
+      return;
+    }
+    if (n.type === "CallExpression" && n.callee?.type === "Identifier") {
+      reads = true;
+      return;
+    }
+    if (n.type === "MemberExpression") {
+      visit(n.object);
+      if (n.computed) visit(n.property);
+      return;
+    }
+    if (n.type === "Property") {
+      if (n.computed) visit(n.key);
+      visit(n.value);
+      return;
+    }
+    for (const key of Object.keys(n)) {
+      if (!IGNORED_KEYS.has(key)) visit(n[key]);
+    }
+  };
+  visit(fn.body);
+  return reads;
+}
+function bodyIsEmpty(fn) {
+  const body = fn?.body;
+  if (!body) return true;
+  if (body.type === "BlockStatement") return (body.body ?? []).length === 0;
+  return false;
+}
+var URL_ATTRS = ["href", "src", "action", "formaction"];
+function collectSecurityFacts(node, source, htmlTags, jsUrls) {
+  if (Array.isArray(node)) {
+    for (const child of node) collectSecurityFacts(child, source, htmlTags, jsUrls);
+    return;
+  }
+  if (!node || typeof node !== "object") return;
+  if (node.type === "HtmlTag") htmlTags.push({ line: lineOf(source, node.start) });
+  if ((node.type === "RegularElement" || node.type === "SvelteElement") && Array.isArray(node.attributes)) {
+    for (const name of URL_ATTRS) {
+      const attr = findAttr(node.attributes, name);
+      if (!attr) continue;
+      const value = attrTextOf(attr);
+      if (value !== void 0 && /^\s*javascript:/i.test(value)) {
+        jsUrls.push({ line: lineOf(source, attr.start ?? node.start) });
+      }
+    }
+  }
+  for (const key of CHILD_NODE_KEYS) {
+    if (key in node) collectSecurityFacts(node[key], source, htmlTags, jsUrls);
+  }
+}
+function isPropsCall(node) {
+  return node?.type === "CallExpression" && node.callee?.type === "Identifier" && node.callee.name === "$props";
+}
+function countProps(program) {
+  let count = 0;
+  let seen = 0;
+  let uncountable = false;
+  walkEstree(program, (n) => {
+    if (n.type !== "VariableDeclarator" || !n.init || !isPropsCall(n.init)) return;
+    seen++;
+    const props = n.id?.type === "ObjectPattern" ? n.id.properties : void 0;
+    if (!Array.isArray(props) || props.some((p) => p?.type === "RestElement")) {
+      uncountable = true;
+      return;
+    }
+    count = props.filter((p) => p?.type === "Property").length;
+  });
+  return uncountable || seen > 1 ? 0 : count;
+}
+function countLines(source) {
+  if (source.length === 0) return 0;
+  return source.split("\n").length - (source.endsWith("\n") ? 1 : 0);
+}
+function collectImportSources(program, acc) {
+  walkEstree(program, (n) => {
+    if (n.type === "ImportDeclaration" && typeof n.source?.value === "string") acc.push(n.source.value);
+  });
+}
+function isBareSpecifier(s) {
+  return !/^[./$#]/.test(s);
+}
+function collectNamespaceImports(program, source, acc) {
+  walkEstree(program, (n) => {
+    if (n.type !== "ImportDeclaration" || n.importKind === "type") return;
+    const spec = n.source?.value;
+    if (typeof spec !== "string" || !isBareSpecifier(spec)) return;
+    if (Array.isArray(n.specifiers) && n.specifiers.some((s) => s?.type === "ImportNamespaceSpecifier")) {
+      acc.push({ source: spec, line: lineOf(source, n.start) });
+    }
+  });
+}
+var JS_DIRECTIVE = /^\s*\/\/\s*svelte-vitals-disable-next-line(?:\s+([A-Za-z]+\d+(?:\s*,\s*[A-Za-z]+\d+)*))?\s*$/;
+var HTML_DIRECTIVE = /^\s*<!--\s*svelte-vitals-disable-next-line(?:\s+([A-Za-z]+\d+(?:\s*,\s*[A-Za-z]+\d+)*))?\s*-->\s*$/;
+function collectSuppressions(source) {
+  const out = [];
+  const lines = source.split("\n");
+  lines.forEach((line, i) => {
+    const m = JS_DIRECTIVE.exec(line) ?? HTML_DIRECTIVE.exec(line);
+    if (!m) return;
+    const ruleIds = m[1]?.split(",").map((s) => s.trim().toUpperCase());
+    out.push({ line: i + 2, ruleIds });
+  });
+  return out;
+}
+function parseComponentFacts(source, filename) {
+  const ast = parse(source, { modern: true, filename });
+  const eachBlocks = [];
+  collectEachBlocks(ast.fragment ?? ast, source, eachBlocks);
+  const htmlTags = [];
+  const javascriptUrls = [];
+  collectSecurityFacts(ast.fragment ?? ast, source, htmlTags, javascriptUrls);
+  const loc = countLines(source);
+  const suppressions = collectSuppressions(source);
+  const imports = [];
+  const namespaceImports = [];
+  if (ast.module?.content) {
+    collectImportSources(ast.module.content, imports);
+    collectNamespaceImports(ast.module.content, source, namespaceImports);
+  }
+  const effects = [];
+  const constableStates = [];
+  let propCount = 0;
+  const program = ast.instance?.content;
+  if (program) {
+    collectImportSources(program, imports);
+    collectNamespaceImports(program, source, namespaceImports);
+    propCount = countProps(program);
+    const stateNames = /* @__PURE__ */ new Set();
+    const reactiveNames = /* @__PURE__ */ new Set();
+    const stateDecls = [];
+    walkEstree(program, (n) => {
+      if (n.type !== "VariableDeclarator" || !n.init) return;
+      if (isStateDeclaration(n.init) && n.id?.type === "Identifier") {
+        stateNames.add(n.id.name);
+        stateDecls.push({ name: n.id.name, line: lineOf(source, n.start) });
+      }
+      if (isStateDeclaration(n.init) || isDerivedDeclaration(n.init) || isPropsCall(n.init))
+        addBoundNames(n.id, reactiveNames);
+    });
+    walkEstree(program, (n) => {
+      if (n.type !== "CallExpression" || !isEffectCall(n)) return;
+      const fn = n.arguments?.[0];
+      const isFn = fn?.type === "ArrowFunctionExpression" || fn?.type === "FunctionExpression";
+      effects.push({
+        line: lineOf(source, n.start),
+        assignsOnlyState: isFn ? bodyOnlyAssignsState(fn, stateNames) : false,
+        mountOnly: isFn ? !bodyIsEmpty(fn) && !bodyReadsReactive(fn, reactiveNames) : false
+      });
+    });
+    const writtenOrEscaped = /* @__PURE__ */ new Set();
+    collectStateWrites(program, stateNames, writtenOrEscaped);
+    if (ast.fragment) {
+      collectStateWrites(ast.fragment, stateNames, writtenOrEscaped);
+      collectTemplateEscapes(ast.fragment, stateNames, writtenOrEscaped);
+    }
+    for (const d of stateDecls) {
+      if (!writtenOrEscaped.has(d.name)) constableStates.push(d);
+    }
+  }
+  return {
+    eachBlocks,
+    effects,
+    htmlTags,
+    javascriptUrls,
+    loc,
+    propCount,
+    imports,
+    namespaceImports,
+    constableStates,
+    suppressions
+  };
+}
+
 // src/project-paths.ts
 var ROBOTS_SOURCE_PATHS = [
   "static/robots.txt",
@@ -1438,6 +1840,9 @@ var seo030HeadingOrder = {
 // src/rules/component-rule.ts
 var PENALIZED2 = { presence: "none", value: "absent" };
 var PASS2 = { presence: "own", value: "static" };
+function isSuppressed(c, ruleId, line) {
+  return (c.suppressions ?? []).some((s) => s.line === line && (!s.ruleIds || s.ruleIds.includes(ruleId)));
+}
 function componentRule(opts) {
   const docsUrl7 = docsUrlFor(opts.id);
   const severity = opts.severity ?? "warning";
@@ -1452,7 +1857,7 @@ function componentRule(opts) {
       const out = [];
       for (const c of ctx.components ?? []) {
         if (!opts.applies(c)) continue;
-        const bad = opts.bad(c);
+        const bad = opts.bad(c).filter((b) => !(b.line > 0 && isSuppressed(c, opts.id, b.line)));
         if (bad.length === 0) {
           out.push({
             id: opts.id,
@@ -1507,6 +1912,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 +1961,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 +2080,14 @@ var allRules = [
   seo030HeadingOrder,
   correct001EachKey,
   correct002EffectDerived,
+  correct003EffectAsOnMount,
+  correct004UnmutatedState,
   sec001Html,
-  sec002JavascriptUrl
+  sec002JavascriptUrl,
+  arch001ComponentSize,
+  arch002PropCount,
+  perf009HeavyImport,
+  perf010NamespaceImport
 ];
 function explainRule(id) {
   const target = id.toUpperCase();
@@ -1700,6 +2214,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 +2240,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");
 }
 
@@ -2157,10 +2697,17 @@ function applyRuleSeverities(results, config) {
 }
 export {
   BAND_COLOR,
+  CHILD_NODE_KEYS,
   ROBOTS_SOURCE_PATHS,
   SITEMAP_SOURCE_PATHS,
   allRules,
   applyRuleSeverities,
+  arch001ComponentSize,
+  arch002PropCount,
+  attrText,
+  attrTextOf,
+  attrValue,
+  attrValueOf,
   buildHtmlDocument,
   buildJsonReport,
   classify,
@@ -2168,6 +2715,8 @@ export {
   computeScore,
   correct001EachKey,
   correct002EffectDerived,
+  correct003EffectAsOnMount,
+  correct004UnmutatedState,
   defaultConfig,
   defaultProject,
   defineConfig,
@@ -2175,6 +2724,7 @@ export {
   effectiveSeverity,
   escapeHtml,
   explainRule,
+  findAttr,
   formatAgentReport,
   formatConsoleReport,
   formatGithubReport,
@@ -2185,7 +2735,10 @@ export {
   headTagRule,
   imageRule,
   isPenalized,
+  lineOf,
   linkRule,
+  noColorPalette,
+  parseComponentFacts,
   perf001ImageDimensions,
   perf002ImageLoading,
   perf003PreloadAs,
@@ -2194,9 +2747,12 @@ export {
   perf006ResponsiveImage,
   perf007RenderBlockingScript,
   perf008Preconnect,
+  perf009HeavyImport,
+  perf010NamespaceImport,
   runRules,
   safeHref,
   scoreBand,
+  scoreColor,
   scoresByCategory,
   sec001Html,
   sec002JavascriptUrl,
@@ -2231,5 +2787,7 @@ export {
   seo028TitleUnique,
   seo029DescriptionUnique,
   seo030HeadingOrder,
-  summarize
+  summarize,
+  textFromNodes,
+  valueFromNodes
 };

package/package.json

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