@svelte-vitals/core 0.19.0 → 0.20.0

package/dist/index.d.ts

@@ -257,6 +257,11 @@ 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[];
 }
@@ -278,9 +283,28 @@ declare function parseComponentFacts(source: string, filename: string): {
         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.
@@ -483,6 +507,8 @@ declare const correct003EffectAsOnMount: Rule;
 
 declare const correct004UnmutatedState: Rule;
 
+declare const correct005PropMutation: Rule;
+
 declare const sec001Html: Rule;
 declare const sec002JavascriptUrl: Rule;
 
@@ -717,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, 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 };
+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

@@ -96,7 +96,7 @@ function collectEachBlocks(node, source, acc) {
     return;
   }
   if (!node || typeof node !== "object") return;
-  if (node.type === "EachBlock" && !isConstantListEach(node)) {
+  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) {
@@ -175,33 +175,71 @@ function rootObjectName(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) {
-  walkEstree(root, (n) => {
+  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)) acc.add(n.left.name);
-      else if (n.left?.type === "MemberExpression") {
+      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)) acc.add(r);
+        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)) acc.add(name);
+        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)) acc.add(r);
+      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)) acc.add(r);
+      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)) acc.add(r);
+        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)) acc.add(r);
+        if (r && stateNames.has(r) && !shadowed(r)) acc.add(r);
       }
     }
   });
@@ -296,6 +334,71 @@ function collectSecurityFacts(node, 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;
@@ -364,12 +467,16 @@ function parseComponentFacts(source, filename) {
   }
   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 = [];
@@ -412,10 +519,42 @@ function parseComponentFacts(source, filename) {
     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",
@@ -1898,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" }))
 });
@@ -1939,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",
@@ -2022,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();
@@ -2033,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`
     }));
   }
 });
@@ -2082,6 +2236,7 @@ var allRules = [
   correct002EffectDerived,
   correct003EffectAsOnMount,
   correct004UnmutatedState,
+  correct005PropMutation,
   sec001Html,
   sec002JavascriptUrl,
   arch001ComponentSize,
@@ -2711,17 +2866,20 @@ export {
   buildHtmlDocument,
   buildJsonReport,
   classify,
+  collectComponentFacts,
   computeHealth,
   computeScore,
   correct001EachKey,
   correct002EffectDerived,
   correct003EffectAsOnMount,
   correct004UnmutatedState,
+  correct005PropMutation,
   defaultConfig,
   defaultProject,
   defineConfig,
   docsUrlFor,
   effectiveSeverity,
+  emptyComponentFacts,
   escapeHtml,
   explainRule,
   findAttr,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svelte-vitals/core",
-  "version": "0.19.0",
+  "version": "0.20.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.20.8"
+    "node": ">=22.13.0"
   },
   "sideEffects": false,
   "dependencies": {