@svelte-vitals/core 0.31.0 → 0.32.0

package/dist/index.d.ts

@@ -544,6 +544,20 @@ interface KitModuleFacts {
         name: string;
         line: number;
     }[];
+    /**
+     * `.set()`/`.update()` in a handler on an import resolving under the `$lib` server root.
+     * The call shape alone cannot tell a persistence client (`db.set(…)`) from a hand-rolled
+     * in-memory store, so the decision needs the target module — which this pure parse cannot
+     * read. `collectKitModuleFacts` resolves each one and promotes the in-memory ones into
+     * `importedStateWrites`; a consumer that ignores this field sees the pre-arbitration
+     * behaviour, i.e. every one of these exempt.
+     */
+    pendingServerStoreWrites: {
+        name: string;
+        imported: string;
+        resolved: string;
+        line: number;
+    }[];
     /** Value imports whose specifier resolves to a repo-local `.svelte.ts`/`.svelte.js` runes module (security/shared-state-import). */
     runesModuleImports: {
         source: string;
@@ -946,9 +960,9 @@ interface Rule {
     severity: Severity;
     /** 'route' = evaluated per route, 'project' = site-wide (design §10, §12). */
     scope: Scope;
-    /** Why this rule matters — one or two sentences, surfaced by explain_rule (issue #24). */
+    /** Why this rule matters — one or two sentences, surfaced by `svelte-vitals explain` (issue #24). */
     rationale: string;
-    /** Canonical remediation template, shared by findings and explain_rule (issue #24). */
+    /** Canonical remediation template, shared by findings and `svelte-vitals explain` (issue #24). */
     fix?: Fix;
     /** Configurable options for this rule; absent means the rule takes none. */
     options?: RuleOptionsSpec;
@@ -1290,7 +1304,7 @@ declare const performanceStateRaw: Rule;
 
 declare const allRules: Rule[];
 
-/** One configurable option of a rule, flattened for explain_rule's consumers. */
+/** One configurable option of a rule, flattened for `svelte-vitals explain`'s output. */
 interface RuleOptionInfo {
     name: string;
     /** `integer` replaces the default; `string-list`/`string-map` are ADDED to it. */
@@ -1314,7 +1328,7 @@ interface RuleInfo {
      */
     options?: RuleOptionInfo[];
 }
-/** Look up a rule's static metadata for the MCP explain_rule tool (issue #24). Rule ids are matched exactly (case-sensitive, e.g. "seo/ssr-disabled"). */
+/** Look up a rule's static metadata, as `svelte-vitals explain` renders it (issue #24). Rule ids are matched exactly (case-sensitive, e.g. "seo/ssr-disabled"). */
 declare function explainRule(id: string): RuleInfo | undefined;
 
 interface HeadTagRuleOptions {
@@ -1326,7 +1340,7 @@ interface HeadTagRuleOptions {
     /** Short human label, e.g. 'description'. */
     label: string;
     recommendation: string;
-    /** Why this rule matters — surfaced by explain_rule (issue #24). */
+    /** Why this rule matters — surfaced by `svelte-vitals explain` (issue #24). */
     rationale: string;
     /** Agent-actionable remediation attached to every finding (issue #18). */
     fix?: Fix;
@@ -1432,7 +1446,14 @@ interface ScoreModel {
     criticalCap: number | null;
 }
 interface ScoreResult {
+    /** The score as displayed: `Math.floor(rawScore)`, so 100 means the deduction was exactly zero. */
     score: number;
+    /**
+     * The same score before flooring, after `sitePenalty` and the cap, clamped to `[0, 100]`. Exposed so
+     * `computeHealth` can average unrounded values and floor once — averaging the displayed scores would
+     * compose two roundings and move Health by up to two points.
+     */
+    rawScore: number;
     scoreModel: ScoreModel;
 }
 interface ScoreOptions {
@@ -1482,7 +1503,7 @@ interface JsonReport {
     }>;
     siteIssues: JsonIssue[];
 }
-/** Build the structured JSON report object (design §7). Shared by the json reporter and the MCP `analyze` tool (issue #24). */
+/** Build the structured JSON report object (design §7). The shape the `json` reporter emits (issue #24). */
 declare function buildJsonReport(results: Result[], config: Config, meta: {
     version: string;
 }): JsonReport;

package/dist/index.js

@@ -1842,6 +1842,13 @@ function libServerRoot(aliases) {
   if (lib && lib.replacement === null) return void 0;
   return `${lib?.replacement ?? "src/lib"}/server`;
 }
+function serverRootRelativePath(spec, importerFile, aliases) {
+  const serverRoot = libServerRoot(aliases);
+  if (serverRoot === void 0) return void 0;
+  const path = resolveRepoLocalPath(spec, importerFile, aliases);
+  if (path === void 0) return void 0;
+  return path === serverRoot || path.startsWith(`${serverRoot}/`) ? path : void 0;
+}
 function isLocalStateSpecifier(spec, importerFile, aliases) {
   const serverRoot = libServerRoot(aliases);
   if (serverRoot === void 0) return false;
@@ -1849,12 +1856,32 @@ function isLocalStateSpecifier(spec, importerFile, aliases) {
   if (path === void 0) return false;
   return path !== serverRoot && !path.startsWith(`${serverRoot}/`);
 }
+var IN_MEMORY_CTORS = /* @__PURE__ */ new Set(["Map", "Set", "WeakMap", "WeakSet"]);
+function isInMemoryInit(init) {
+  if (!init) return false;
+  if (init.type === "ObjectExpression" || init.type === "ArrayExpression") return true;
+  return init.type === "NewExpression" && init.callee?.type === "Identifier" && IN_MEMORY_CTORS.has(init.callee.name);
+}
+function parseInMemoryExports(source, filename) {
+  const names = /* @__PURE__ */ new Set();
+  const { program } = parseModuleProgram(source, filename);
+  for (const stmt of program?.body ?? []) {
+    if (stmt?.type !== "ExportNamedDeclaration" || !stmt.declaration) continue;
+    const decl = stmt.declaration;
+    if (decl.type !== "VariableDeclaration") continue;
+    for (const d of decl.declarations ?? []) {
+      if (d?.id?.type === "Identifier" && isInMemoryInit(d.init)) names.add(d.id.name);
+    }
+  }
+  return names;
+}
 function parseKitModuleFacts(source, filename, aliases) {
   const suppressions = collectSuppressions(source);
   const { program, wrapped } = parseModuleProgram(source, filename);
   const moduleStateReassignments = [];
   const importedStateWrites = [];
   const importedStateWritesOutsideHandlers = [];
+  const pendingServerStoreWrites = [];
   const runesModuleImports = [];
   const lifecycleCalls = [];
   const browserGlobalRefs = [];
@@ -1863,6 +1890,7 @@ function parseKitModuleFacts(source, filename, aliases) {
       moduleStateReassignments,
       importedStateWrites,
       importedStateWritesOutsideHandlers,
+      pendingServerStoreWrites,
       runesModuleImports,
       lifecycleCalls,
       browserGlobalRefs,
@@ -1872,6 +1900,7 @@ function parseKitModuleFacts(source, filename, aliases) {
   }
   const line = (start) => Math.max(0, lineOf(wrapped, start) - 1);
   const importedSpecifiers = /* @__PURE__ */ new Map();
+  const importedNames = /* @__PURE__ */ new Map();
   for (const stmt of program.body ?? []) {
     if (stmt?.type !== "ImportDeclaration" || stmt.importKind === "type") continue;
     const spec = typeof stmt.source?.value === "string" ? stmt.source.value : "";
@@ -1880,6 +1909,10 @@ function parseKitModuleFacts(source, filename, aliases) {
       if (s?.importKind === "type" || s?.local?.type !== "Identifier") continue;
       names.push(s.local.name);
       importedSpecifiers.set(s.local.name, spec);
+      importedNames.set(
+        s.local.name,
+        s.type === "ImportSpecifier" && s.imported?.type === "Identifier" ? s.imported.name : s.local.name
+      );
     }
     if (names.length === 0) continue;
     const resolved = resolveRunesModuleSpecifier(spec, filename, aliases);
@@ -1956,8 +1989,21 @@ function parseKitModuleFacts(source, filename, aliases) {
       const method = n.callee.property?.type === "Identifier" ? n.callee.property.name : void 0;
       if (method === "set" || method === "update") {
         const r = importedRoot(n.callee.object);
-        if (r && isLocalStateSpecifier(importedSpecifiers.get(r), filename, aliases))
-          write = { name: r, via: "set-call" };
+        const spec = r ? importedSpecifiers.get(r) : void 0;
+        if (r && spec !== void 0) {
+          if (isLocalStateSpecifier(spec, filename, aliases)) write = { name: r, via: "set-call" };
+          else {
+            const resolved = serverRootRelativePath(spec, filename, aliases);
+            if (resolved !== void 0 && inHandler) {
+              pendingServerStoreWrites.push({
+                name: r,
+                imported: importedNames.get(r) ?? r,
+                resolved,
+                line: line(n.start)
+              });
+            }
+          }
+        }
       }
     } else if (n.type === "AssignmentExpression" && (n.left?.type === "ObjectPattern" || n.left?.type === "ArrayPattern")) {
       const scanPatternTargets = (pat) => {
@@ -2005,6 +2051,7 @@ function parseKitModuleFacts(source, filename, aliases) {
     moduleStateReassignments: byLine(moduleStateReassignments),
     importedStateWrites: byLine(importedStateWrites),
     importedStateWritesOutsideHandlers: byLine(importedStateWritesOutsideHandlers),
+    pendingServerStoreWrites: byLine(pendingServerStoreWrites),
     runesModuleImports: byLine(runesModuleImports),
     lifecycleCalls: byLine(lifecycleCalls),
     browserGlobalRefs: byLine(browserGlobalRefs),
@@ -2024,6 +2071,7 @@ function emptyKitModuleFacts(file, kind) {
     moduleStateReassignments: [],
     importedStateWrites: [],
     importedStateWritesOutsideHandlers: [],
+    pendingServerStoreWrites: [],
     runesModuleImports: [],
     lifecycleCalls: [],
     browserGlobalRefs: [],
@@ -2044,7 +2092,7 @@ async function collectKitModuleFacts(rt, cwd, aliases) {
   ];
   const lists = await Promise.all(patterns.map((p) => rt.glob(p, cwd)));
   const files = [...new Set(lists.flat())];
-  return Promise.all(
+  const facts = await Promise.all(
     files.sort().map(async (rel) => {
       const kind = kindOf(rel);
       try {
@@ -2055,6 +2103,38 @@ async function collectKitModuleFacts(rt, cwd, aliases) {
       }
     })
   );
+  return arbitrateServerStoreWrites(rt, cwd, facts);
+}
+function moduleCandidates(repoPath) {
+  if (repoPath.endsWith(".js")) return [repoPath, `${repoPath.slice(0, -3)}.ts`];
+  if (repoPath.endsWith(".ts")) return [repoPath];
+  return [`${repoPath}.ts`, `${repoPath}.js`, `${repoPath}/index.ts`, `${repoPath}/index.js`];
+}
+async function inMemoryExportsOf(rt, cwd, repoPath) {
+  for (const rel of moduleCandidates(repoPath)) {
+    try {
+      if (!await rt.exists(rt.join(cwd, rel))) continue;
+      return parseInMemoryExports(await rt.readFile(rt.join(cwd, rel)), rel);
+    } catch {
+      return /* @__PURE__ */ new Set();
+    }
+  }
+  return /* @__PURE__ */ new Set();
+}
+async function arbitrateServerStoreWrites(rt, cwd, facts) {
+  const targets = [...new Set(facts.flatMap((f) => f.pendingServerStoreWrites.map((w) => w.resolved)))];
+  if (targets.length === 0) return facts;
+  const byPath = new Map(
+    await Promise.all(targets.map(async (t) => [t, await inMemoryExportsOf(rt, cwd, t)]))
+  );
+  return facts.map((f) => {
+    const promoted = f.pendingServerStoreWrites.filter((w) => byPath.get(w.resolved)?.has(w.imported)).map((w) => ({ name: w.name, line: w.line, via: "set-call" }));
+    if (promoted.length === 0) return f;
+    return {
+      ...f,
+      importedStateWrites: [...f.importedStateWrites, ...promoted].sort((a, b) => a.line - b.line)
+    };
+  });
 }
 
 // src/config-object.ts
@@ -4938,7 +5018,7 @@ var architectureUnitEntryFile = {
           category: "architecture",
           severity: "info",
           detection: { presence: "own", value: "static" },
-          route: expected,
+          location: expected,
           message: "Unit entry file",
           recommendation: recommendation8,
           docsUrl: docsUrl8
@@ -5641,7 +5721,8 @@ function computeScore(results, config, options = {}) {
     routeScores.set(route, routeScores.get(route) - deduction);
   }
   const scores = [...routeScores.values()].map(clamp);
-  const routeAverage = scores.length ? Math.round(scores.reduce((a, b) => a + b, 0) / scores.length) : 100;
+  const rawRouteAverage = scores.length ? scores.reduce((a, b) => a + b, 0) / scores.length : 100;
+  const routeAverage = Math.floor(rawRouteAverage);
   const projectRuleMax = /* @__PURE__ */ new Map();
   for (const r of projectResults) {
     if (!isPenalized(r.detection, config.treatDynamicAs)) continue;
@@ -5653,11 +5734,11 @@ function computeScore(results, config, options = {}) {
   let sitePenalty = 0;
   for (const deduction of projectRuleMax.values()) sitePenalty += deduction;
   const applyCap = options.applyCriticalCap ?? true;
-  const uncapped = routeAverage - sitePenalty;
-  const capBinds = applyCap && anyCritical && uncapped > CRITICAL_CAP;
+  const rawUncapped = rawRouteAverage - sitePenalty;
+  const capBinds = applyCap && anyCritical && rawUncapped > CRITICAL_CAP;
   const criticalCap = capBinds ? CRITICAL_CAP : null;
-  const score = capBinds ? CRITICAL_CAP : uncapped;
-  return { score: clamp(score), scoreModel: { routeAverage, sitePenalty, criticalCap } };
+  const rawScore = clamp(capBinds ? CRITICAL_CAP : rawUncapped);
+  return { score: Math.floor(rawScore), rawScore, scoreModel: { routeAverage, sitePenalty, criticalCap } };
 }
 function scoresByCategory(results, config) {
   const byCat = /* @__PURE__ */ new Map();
@@ -5674,7 +5755,7 @@ function scoresByCategory(results, config) {
 function computeHealth(results, config) {
   const categories = scoresByCategory(results, config);
   const weights = {};
-  let weighted = 0;
+  let weightedDeficit = 0;
   let total = 0;
   for (const cat of Object.keys(categories)) {
     const w = config.weights?.[cat] ?? 1;
@@ -5682,14 +5763,15 @@ function computeHealth(results, config) {
       throw new RangeError(`invalid weight for '${cat}'; expected a finite number >= 0.`);
     }
     weights[cat] = w;
-    weighted += categories[cat].score * w;
+    weightedDeficit += (100 - categories[cat].rawScore) * w;
     total += w;
   }
   if (Object.keys(weights).length === 0) return { health: 100, categories, weights };
   if (total === 0) {
     throw new RangeError("Health weights sum to 0; at least one present category must have a positive weight.");
   }
-  const health = Math.round(weighted / total);
+  const averageDeficit = weightedDeficit / total;
+  const health = averageDeficit === 0 ? 100 : Math.min(99, Math.floor(100 - averageDeficit));
   return { health, categories, weights };
 }
 
@@ -5763,7 +5845,7 @@ function byRouteTree(p, results, config, verbose) {
   }
   if (!verbose && scored.length > MAX_ROUTES_BY_ROUTE) {
     const remaining = scored.slice(MAX_ROUTES_BY_ROUTE);
-    const avgScore = Math.round(remaining.reduce((sum, r) => sum + r.score, 0) / remaining.length);
+    const avgScore = Math.floor(remaining.reduce((sum, r) => sum + r.score, 0) / remaining.length);
     lines.push(
       p.dim(
         `\u2026and ${remaining.length} more route${remaining.length > 1 ? "s" : ""} (avg score ${avgScore}) \u2014 run with --verbose to see all`
@@ -5833,8 +5915,9 @@ function formatConsoleReport(results, config, options = {}) {
     if (options.verbose) {
       for (const r of passed) {
         const marker = classify(r, config) === "dynamic" ? p.cyan("  \u21AF dynamic") : "";
-        const route = r.route ? `  ${r.route}` : "";
-        lines.push(`${p.green("\u2713")} ${r.id}  ${r.message}${marker}${route}`);
+        const where = r.location ?? r.route;
+        const suffix = where ? `  ${where}` : "";
+        lines.push(`${p.green("\u2713")} ${r.id}  ${r.message}${marker}${suffix}`);
       }
     }
     lines.push("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svelte-vitals/core",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Shared, runtime-agnostic core for svelte-vitals (types, rule engine, scorer, reporter).",
   "type": "module",
   "license": "MIT",