@svelte-vitals/core 0.18.0 → 0.20.0

package/dist/index.d.ts

@@ -224,6 +224,13 @@ interface SourceSpan {
     /** 1-based source line, or 0 if unknown. */
     line: number;
 }
+/** 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. */
@@ -250,8 +257,82 @@ interface ComponentFacts {
         name: string;
         line: number;
     }[];
+    /** Mutations of a non-`$bindable` prop from `$props()` — member writes, `delete`, or a mutating method call (CORRECT005). */
+    mutatedProps: {
+        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;
+    }[];
+    mutatedProps: {
+        name: string;
+        line: number;
+    }[];
+    suppressions: SuppressionDirective[];
+};
+
+/**
+ * Fallback facts for a file that fails to read or parse (dev tooling must never
+ * throw). This is the single source of truth for the empty-facts shape — add new
+ * `ComponentFacts` fields HERE so TypeScript catches every call site that still
+ * needs updating.
+ */
+declare function emptyComponentFacts(file: string): ComponentFacts;
+/**
+ * Scan every `.svelte` component under `src/` for Correctness/Security/Architecture/
+ * Bundle-Performance facts. Independent of route resolution — covers `$lib` and
+ * non-route components too. A file that fails to read or parse contributes empty
+ * facts instead of aborting the whole scan (dev tooling must never throw).
+ */
+declare function collectComponentFacts(rt: Runtime, cwd: string): Promise<ComponentFacts[]>;
+
+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
@@ -426,6 +507,8 @@ declare const correct003EffectAsOnMount: Rule;
 
 declare const correct004UnmutatedState: Rule;
 
+declare const correct005PropMutation: Rule;
+
 declare const sec001Html: Rule;
 declare const sec002JavascriptUrl: Rule;
 
@@ -660,4 +743,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 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 };
+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, collectComponentFacts, computeHealth, computeScore, correct001EachKey, correct002EffectDerived, correct003EffectAsOnMount, correct004UnmutatedState, correct005PropMutation, defaultConfig, defaultProject, defineConfig, docsUrlFor, effectiveSeverity, emptyComponentFacts, 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,547 @@ 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" && node.context != null && !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 scopeIntroducedNames(node) {
+  const introduced = /* @__PURE__ */ new Set();
+  if (node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression") {
+    for (const p of node.params ?? []) addBoundNames(p, introduced);
+  } else if (node.type === "CatchClause") {
+    addBoundNames(node.param, introduced);
+  } else if (node.type === "BlockStatement") {
+    for (const stmt of node.body ?? []) {
+      if (stmt?.type === "VariableDeclaration" && stmt.kind !== "var") {
+        for (const d of stmt.declarations ?? []) addBoundNames(d.id, introduced);
+      }
+    }
+  } else if (node.type === "ForStatement" || node.type === "ForOfStatement" || node.type === "ForInStatement") {
+    const decl = node.type === "ForStatement" ? node.init : node.left;
+    if (decl?.type === "VariableDeclaration") {
+      for (const d of decl.declarations ?? []) addBoundNames(d.id, introduced);
+    }
+  } else if (node.type === "EachBlock" && node.context) {
+    addBoundNames(node.context, introduced);
+  }
+  return introduced;
+}
+function walkScoped(node, visit, shadowed = /* @__PURE__ */ new Set()) {
+  if (Array.isArray(node)) {
+    for (const child of node) walkScoped(child, visit, shadowed);
+    return;
+  }
+  if (!node || typeof node !== "object" || typeof node.type !== "string") return;
+  const introduced = scopeIntroducedNames(node);
+  const scope = introduced.size > 0 ? /* @__PURE__ */ new Set([...shadowed, ...introduced]) : shadowed;
+  visit(node, scope);
+  for (const key of Object.keys(node)) {
+    if (key === "type" || key === "start" || key === "end" || key === "loc" || key === "range") continue;
+    walkScoped(node[key], visit, scope);
+  }
+}
+function collectStateWrites(root, stateNames, acc) {
+  walkScoped(root, (n, scope) => {
+    const shadowed = (name) => name === void 0 || scope.has(name);
+    if (n?.type === "AssignmentExpression") {
+      if (n.left?.type === "Identifier" && stateNames.has(n.left.name) && !shadowed(n.left.name)) {
+        acc.add(n.left.name);
+      } else if (n.left?.type === "MemberExpression") {
+        const r = rootObjectName(n.left);
+        if (r && stateNames.has(r) && !shadowed(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) && !shadowed(name)) acc.add(name);
+      }
+    } else if (n?.type === "UpdateExpression") {
+      const r = rootObjectName(n.argument);
+      if (r && stateNames.has(r) && !shadowed(r)) acc.add(r);
+    } else if (n?.type === "UnaryExpression" && n.operator === "delete") {
+      const r = rootObjectName(n.argument);
+      if (r && stateNames.has(r) && !shadowed(r)) acc.add(r);
+    } else if (n?.type === "CallExpression") {
+      if (n.callee?.type === "MemberExpression") {
+        const r = rootObjectName(n.callee);
+        if (r && stateNames.has(r) && !shadowed(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) && !shadowed(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 isBindableCall(node) {
+  return node?.type === "CallExpression" && node.callee?.type === "Identifier" && node.callee.name === "$bindable";
+}
+function collectNonBindableProps(program) {
+  const names = /* @__PURE__ */ new Set();
+  let seen = 0;
+  let ambiguous = false;
+  walkEstree(program, (n) => {
+    if (n.type !== "VariableDeclarator" || !n.init || !isPropsCall(n.init)) return;
+    seen++;
+    if (n.id?.type === "Identifier") {
+      names.add(n.id.name);
+      return;
+    }
+    if (n.id?.type !== "ObjectPattern" || !Array.isArray(n.id.properties)) {
+      ambiguous = true;
+      return;
+    }
+    for (const p of n.id.properties) {
+      if (p?.type === "RestElement") {
+        addBoundNames(p.argument, names);
+      } else if (p?.type === "Property") {
+        if (p.value?.type === "AssignmentPattern") {
+          if (!isBindableCall(p.value.right) && p.value.left?.type === "Identifier") names.add(p.value.left.name);
+        } else if (p.value?.type === "Identifier") {
+          names.add(p.value.name);
+        }
+      }
+    }
+  });
+  return ambiguous || seen > 1 ? /* @__PURE__ */ new Set() : names;
+}
+var MUTATING_METHODS = /* @__PURE__ */ new Set([
+  "push",
+  "pop",
+  "shift",
+  "unshift",
+  "splice",
+  "sort",
+  "reverse",
+  "copyWithin",
+  "fill",
+  "set",
+  "add",
+  "delete",
+  "clear"
+]);
+function collectPropMutations(root, propNames, source, acc) {
+  if (propNames.size === 0) return;
+  walkScoped(root, (n, scope) => {
+    const flag = (r) => {
+      if (r && propNames.has(r) && !scope.has(r)) acc.push({ name: r, line: lineOf(source, n.start) });
+    };
+    if (n.type === "AssignmentExpression" && n.left?.type === "MemberExpression") {
+      flag(rootObjectName(n.left));
+    } else if (n.type === "UpdateExpression" && n.argument?.type === "MemberExpression") {
+      flag(rootObjectName(n.argument));
+    } else if (n.type === "UnaryExpression" && n.operator === "delete") {
+      flag(rootObjectName(n.argument));
+    } else if (n.type === "CallExpression" && n.callee?.type === "MemberExpression") {
+      const method = n.callee.property?.type === "Identifier" ? n.callee.property.name : void 0;
+      if (method && MUTATING_METHODS.has(method)) flag(rootObjectName(n.callee.object));
+    }
+  });
+}
+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 = [];
+  const mutatedProps = [];
+  let propCount = 0;
+  const program = ast.instance?.content;
+  if (program) {
+    collectImportSources(program, imports);
+    collectNamespaceImports(program, source, namespaceImports);
+    propCount = countProps(program);
+    const nonBindableProps = collectNonBindableProps(program);
+    collectPropMutations(program, nonBindableProps, source, mutatedProps);
+    if (ast.fragment) collectPropMutations(ast.fragment, nonBindableProps, source, mutatedProps);
+    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,
+    mutatedProps,
+    suppressions
+  };
+}
+
+// src/component-collect.ts
+function emptyComponentFacts(file) {
+  return {
+    file,
+    eachBlocks: [],
+    effects: [],
+    htmlTags: [],
+    javascriptUrls: [],
+    loc: 0,
+    propCount: 0,
+    imports: [],
+    namespaceImports: [],
+    constableStates: [],
+    mutatedProps: [],
+    suppressions: []
+  };
+}
+async function collectComponentFacts(rt, cwd) {
+  const files = await rt.glob("src/**/*.svelte", cwd);
+  return Promise.all(
+    files.sort().map(async (rel) => {
+      try {
+        const source = await rt.readFile(rt.join(cwd, rel));
+        return { file: rel, ...parseComponentFacts(source, rel) };
+      } catch {
+        return emptyComponentFacts(rel);
+      }
+    })
+  );
+}
+
 // src/project-paths.ts
 var ROBOTS_SOURCE_PATHS = [
   "static/robots.txt",
@@ -1438,6 +1979,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 +1996,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,
@@ -1493,7 +2037,7 @@ var correct001EachKey = componentRule({
   category: "correctness",
   label: "Keyed {#each}",
   recommendation: "Add a key to the {#each} block, e.g. {#each items as item (item.id)}.",
-  rationale: "An unkeyed {#each} destroys and recreates DOM nodes when the list reorders, losing element state/focus and wasting work; a key lets Svelte move nodes instead.",
+  rationale: "An unkeyed {#each} adds/removes nodes at the end and rewrites the data of the DOM nodes in between when the list reorders, so element state/focus sticks to positions instead of items; a key lets Svelte insert, move, and delete the right nodes instead.",
   applies: (c) => c.eachBlocks.length > 0,
   bad: (c) => c.eachBlocks.filter((e) => !e.hasKey).map((e) => ({ line: e.line, message: "{#each} block has no key" }))
 });
@@ -1534,6 +2078,21 @@ var correct004UnmutatedState = componentRule({
   }))
 });
 
+// src/rules/correctness/correct005-prop-mutation.ts
+var correct005PropMutation = componentRule({
+  id: "CORRECT005",
+  title: "Mutated non-bindable prop",
+  category: "correctness",
+  label: "Prop mutation",
+  recommendation: "Clone the value before mutating it, communicate the change via a callback prop, or declare the prop $bindable if the parent and child should share it.",
+  rationale: "Svelte's docs say plainly: don't mutate props unless they are $bindable. A plain-object prop mutation is a silent no-op (the object isn't a state proxy); a reactive-state-proxy prop mutation works but triggers the ownership_invalid_mutation dev warning only when that code path actually runs. Neither is caught by the compiler, so this rule catches both statically.",
+  applies: (c) => c.mutatedProps.length > 0,
+  bad: (c) => c.mutatedProps.map((m) => ({
+    line: m.line,
+    message: `Prop "${m.name}" is mutated, but it is not declared $bindable`
+  }))
+});
+
 // src/rules/security/sec001-002.ts
 var sec001Html = componentRule({
   id: "SEC001",
@@ -1617,8 +2176,8 @@ var perf010NamespaceImport = componentRule({
   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.",
+  recommendation: "Use named imports (import { x } from 'pkg') instead of import * as X from 'pkg' \u2014 so the bundle reliably tree-shakes.",
+  rationale: "A namespace import (import * as X) is only tree-shakeable while every access to X stays static; passing X around or indexing it dynamically forces the bundler to keep the whole module. Named imports are reliably shakeable and make the dependency surface explicit.",
   applies: (c) => c.namespaceImports.length > 0,
   bad: (c) => {
     const minLine = /* @__PURE__ */ new Map();
@@ -1628,7 +2187,7 @@ var perf010NamespaceImport = componentRule({
     }
     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`
+      message: `Namespace import "import * as \u2026 from '${source}'" \u2014 prefer named imports so the bundle reliably tree-shakes`
     }));
   }
 });
@@ -1677,6 +2236,7 @@ var allRules = [
   correct002EffectDerived,
   correct003EffectAsOnMount,
   correct004UnmutatedState,
+  correct005PropMutation,
   sec001Html,
   sec002JavascriptUrl,
   arch001ComponentSize,
@@ -2292,28 +2852,37 @@ 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,
+  collectComponentFacts,
   computeHealth,
   computeScore,
   correct001EachKey,
   correct002EffectDerived,
   correct003EffectAsOnMount,
   correct004UnmutatedState,
+  correct005PropMutation,
   defaultConfig,
   defaultProject,
   defineConfig,
   docsUrlFor,
   effectiveSeverity,
+  emptyComponentFacts,
   escapeHtml,
   explainRule,
+  findAttr,
   formatAgentReport,
   formatConsoleReport,
   formatGithubReport,
@@ -2324,8 +2893,10 @@ export {
   headTagRule,
   imageRule,
   isPenalized,
+  lineOf,
   linkRule,
   noColorPalette,
+  parseComponentFacts,
   perf001ImageDimensions,
   perf002ImageLoading,
   perf003PreloadAs,
@@ -2374,5 +2945,7 @@ export {
   seo028TitleUnique,
   seo029DescriptionUnique,
   seo030HeadingOrder,
-  summarize
+  summarize,
+  textFromNodes,
+  valueFromNodes
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svelte-vitals/core",
-  "version": "0.18.0",
+  "version": "0.20.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.20.8"
+    "node": ">=22.13.0"
   },
   "sideEffects": false,
+  "dependencies": {
+    "svelte": "^5.56.4"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",