svelte-vitals 0.15.0 → 0.17.0

package/dist/bin.js

@@ -6,10 +6,10 @@ import {
   knownRuleIds,
   readPackageVersion,
   run
-} from "./chunk-2NZBWTKF.js";
+} from "./chunk-VG647TPJ.js";
 
 // src/bin.ts
-import mri from "mri";
+import mri2 from "mri";
 
 // src/resolve-args.ts
 var toList = (v) => typeof v === "string" ? v.split(",").map((s) => s.trim()).filter(Boolean) : [];
@@ -26,6 +26,8 @@ function resolveArgs(argv) {
     );
   }
   const route = typeof argv.route === "string" ? argv.route : void 0;
+  const diffBase = typeof argv.diff === "string" ? argv.diff || "HEAD" : void 0;
+  const staged = Boolean(argv.staged);
   const allow = toList(argv.rules);
   const ignore = toList(argv.ignore);
   const unknown = findUnknownRuleIds([...allow, ...ignore]);
@@ -64,23 +66,330 @@ function resolveArgs(argv) {
       outFile: typeof argv["out-file"] === "string" ? argv["out-file"] : void 0,
       byRoute: Boolean(argv["by-route"]),
       failOn,
-      rules: buildRulesConfig(allow, ignore)
+      rules: buildRulesConfig(allow, ignore),
+      ...diffBase !== void 0 ? { diffBase } : {},
+      ...staged ? { staged } : {}
+    },
+    warnings,
+    errors
+  };
+}
+
+// src/install/cli.ts
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname } from "path";
+import { homedir } from "os";
+import mri from "mri";
+import * as p from "@clack/prompts";
+
+// src/install/clients.ts
+import { join } from "path";
+var MCP_ENTRY = { command: "npx", args: ["-y", "@svelte-vitals/mcp"] };
+var CLIENTS = [
+  {
+    id: "claude-code",
+    label: "Claude Code",
+    scopes: ["project", "global"],
+    format: "json",
+    resolvePath: (scope, cwd, home) => scope === "project" ? join(cwd, ".mcp.json") : join(home, ".claude.json")
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    scopes: ["project", "global"],
+    format: "json",
+    resolvePath: (scope, cwd, home) => scope === "project" ? join(cwd, ".cursor", "mcp.json") : join(home, ".cursor", "mcp.json")
+  },
+  {
+    id: "codex",
+    label: "Codex",
+    scopes: ["global"],
+    format: "toml",
+    resolvePath: (_scope, _cwd, home) => join(home, ".codex", "config.toml")
+  }
+];
+function clientById(id) {
+  return CLIENTS.find((c) => c.id === id);
+}
+
+// src/install/merge.ts
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+var SERVER_KEY = "svelte-vitals";
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function sameEntry(prior, entry) {
+  if (typeof prior !== "object" || prior === null) return false;
+  const o = prior;
+  return o.command === entry.command && Array.isArray(o.args) && o.args.length === entry.args.length && o.args.every((v, i) => v === entry.args[i]);
+}
+function statusFor(prior, entry, force, created) {
+  if (prior !== void 0) {
+    if (sameEntry(prior, entry)) return "exists";
+    return force ? "updated" : "skip";
+  }
+  return created ? "created" : "added";
+}
+function mergeJson(existing, entry, force) {
+  const created = existing === void 0;
+  const parsed = created ? {} : JSON.parse(existing);
+  if (!isPlainObject(parsed)) {
+    throw new Error("existing config is not a JSON object");
+  }
+  const root = parsed;
+  if (root.mcpServers !== void 0 && !isPlainObject(root.mcpServers)) {
+    throw new Error('existing config has a non-object "mcpServers" table');
+  }
+  const servers = isPlainObject(root.mcpServers) ? root.mcpServers : {};
+  const status = statusFor(servers[SERVER_KEY], entry, force, created);
+  if (status === "exists" || status === "skip") return { content: existing, status: "exists" };
+  servers[SERVER_KEY] = { command: entry.command, args: entry.args };
+  root.mcpServers = servers;
+  return { content: JSON.stringify(root, null, 2) + "\n", status };
+}
+function mergeToml(existing, entry, force) {
+  const created = existing === void 0;
+  const parsed = created ? {} : parseToml(existing);
+  if (!isPlainObject(parsed)) {
+    throw new Error("existing config is not a TOML table");
+  }
+  const root = parsed;
+  if (root.mcp_servers !== void 0 && !isPlainObject(root.mcp_servers)) {
+    throw new Error('existing config has a non-table "mcp_servers" section');
+  }
+  const servers = isPlainObject(root.mcp_servers) ? root.mcp_servers : {};
+  const status = statusFor(servers[SERVER_KEY], entry, force, created);
+  if (status === "exists" || status === "skip") return { content: existing, status: "exists" };
+  servers[SERVER_KEY] = { command: entry.command, args: entry.args };
+  root.mcp_servers = servers;
+  return { content: stringifyToml(root), status };
+}
+
+// src/install/index.ts
+function planFor(client, scope, io, force) {
+  const path = client.resolvePath(scope, io.cwd, io.home);
+  const existing = io.readFile(path);
+  const merged = client.format === "toml" ? mergeToml(existing, MCP_ENTRY, force) : mergeJson(existing, MCP_ENTRY, force);
+  return { client, scope, path, status: merged.status, content: merged.content };
+}
+async function runInstall(flags, io, prompts) {
+  let ids;
+  if (flags.client && flags.client.length > 0) {
+    ids = flags.client;
+  } else if (io.isTTY) {
+    const configExists = (path) => {
+      try {
+        return io.readFile(path) !== void 0;
+      } catch {
+        return false;
+      }
+    };
+    const detected = CLIENTS.filter((c) => c.scopes.some((s) => configExists(c.resolvePath(s, io.cwd, io.home)))).map(
+      (c) => c.id
+    );
+    const picked = await prompts.selectClients(CLIENTS, detected);
+    if (picked === null) {
+      io.log("Cancelled.");
+      return 0;
+    }
+    ids = picked;
+  } else {
+    io.errorLog("svelte-vitals: no TTY; pass --client <claude-code,cursor,codex> to install non-interactively.");
+    return 2;
+  }
+  const clients = ids.map(clientById).filter((c) => c !== void 0);
+  if (clients.length === 0) {
+    io.errorLog("svelte-vitals: no valid clients selected.");
+    return 2;
+  }
+  const rows = [];
+  for (const client of clients) {
+    let scope;
+    if (client.scopes.length === 1) {
+      scope = client.scopes[0];
+    } else if (flags.scope) {
+      scope = flags.scope;
+    } else if (io.isTTY) {
+      const picked = await prompts.selectScope(client);
+      if (picked === null) {
+        io.log("Cancelled.");
+        return 0;
+      }
+      scope = picked;
+    } else {
+      scope = "project";
+    }
+    try {
+      rows.push(planFor(client, scope, io, flags.force ?? false));
+    } catch (err) {
+      const path = client.resolvePath(scope, io.cwd, io.home);
+      io.errorLog(
+        `svelte-vitals: could not parse existing config at ${path}: ${err instanceof Error ? err.message : String(err)}`
+      );
+      return 2;
+    }
+  }
+  const planText = rows.map((r) => `  ${r.client.label} (${r.scope}) \u2192 ${r.path}  [${r.status}]`).join("\n");
+  io.log("Plan:");
+  io.log(planText);
+  if (flags.dryRun) {
+    io.log("Dry run \u2014 no files written.");
+    return 0;
+  }
+  if (!flags.yes && io.isTTY) {
+    const ok = await prompts.confirm(planText);
+    if (!ok) {
+      io.log("Cancelled.");
+      return 0;
+    }
+  }
+  let hadFailure = false;
+  for (const r of rows) {
+    if (r.status === "exists") {
+      io.log(`= ${r.client.label}: already configured (${r.path}) \u2014 use --force to overwrite.`);
+      continue;
+    }
+    try {
+      io.writeFile(r.path, r.content);
+      io.log(`\u2713 ${r.client.label}: ${r.status} ${r.path}`);
+    } catch (err) {
+      hadFailure = true;
+      io.errorLog(`svelte-vitals: failed to write ${r.path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  if (hadFailure) return 2;
+  io.log("");
+  io.log("Done. Restart your client to load the svelte-vitals MCP server.");
+  return 0;
+}
+
+// src/install/args.ts
+var VALID_CLIENTS = CLIENTS.map((c) => c.id);
+function resolveInstallArgs(argv) {
+  const warnings = [];
+  const errors = [];
+  const rawClients = typeof argv.client === "string" ? argv.client.split(",").map((s) => s.trim()).filter(Boolean) : [];
+  const client = [];
+  for (const c of rawClients) {
+    if (VALID_CLIENTS.includes(c)) {
+      if (!client.includes(c)) client.push(c);
+    } else {
+      warnings.push(`svelte-vitals: unknown --client '${c}'; expected claude-code|cursor|codex. Skipping.`);
+    }
+  }
+  if (rawClients.length > 0 && client.length === 0) {
+    errors.push("svelte-vitals: no valid --client values; expected claude-code|cursor|codex.");
+  }
+  let scope;
+  const rawScope = argv.scope;
+  if (typeof rawScope === "string") {
+    if (rawScope === "project" || rawScope === "global") scope = rawScope;
+    else errors.push(`svelte-vitals: unknown --scope '${rawScope}'; expected project|global.`);
+  }
+  if (errors.length > 0) return { flags: null, warnings, errors };
+  return {
+    flags: {
+      ...client.length > 0 ? { client } : {},
+      ...scope ? { scope } : {},
+      yes: Boolean(argv.yes),
+      dryRun: Boolean(argv["dry-run"]),
+      force: Boolean(argv.force)
     },
     warnings,
     errors
   };
 }
 
+// src/install/cli.ts
+var INSTALL_HELP = `svelte-vitals install \u2014 set up the svelte-vitals MCP server for your AI-agent clients
+
+Usage:
+  svelte-vitals install [options]
+
+Options:
+  --client <ids>    Comma-separated: claude-code,cursor,codex (skips the interactive picker)
+  --scope <scope>   project | global (applies to all selected clients; codex is always global)
+  --yes, -y         Skip the confirmation prompt
+  --dry-run         Print the planned changes and exit without writing
+  --force           Overwrite an existing svelte-vitals entry
+  -h, --help        Show this help`;
+function realIO() {
+  return {
+    readFile: (path) => {
+      try {
+        return readFileSync(path, "utf8");
+      } catch (err) {
+        if (err.code === "ENOENT") return void 0;
+        throw err;
+      }
+    },
+    writeFile: (path, content) => {
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, content);
+    },
+    cwd: process.cwd(),
+    home: homedir(),
+    isTTY: Boolean(process.stdout.isTTY),
+    log: (line) => console.log(line),
+    errorLog: (line) => console.error(line)
+  };
+}
+function clackPrompts() {
+  return {
+    selectClients: async (all, defaults) => {
+      const res = await p.multiselect({
+        message: "Which clients should svelte-vitals be installed for?",
+        options: all.map((c) => ({ value: c.id, label: c.label })),
+        initialValues: defaults,
+        required: true
+      });
+      return p.isCancel(res) ? null : res;
+    },
+    selectScope: async (client) => {
+      const res = await p.select({
+        message: `Scope for ${client.label}?`,
+        options: client.scopes.map((s) => ({ value: s, label: s })),
+        initialValue: client.scopes[0]
+      });
+      return p.isCancel(res) ? null : res;
+    },
+    confirm: async (planText) => {
+      const res = await p.confirm({ message: `Apply this plan?
+${planText}` });
+      return p.isCancel(res) ? false : Boolean(res);
+    }
+  };
+}
+async function runInstallCli(args) {
+  const argv = mri(args, {
+    boolean: ["yes", "dry-run", "force", "help"],
+    string: ["client", "scope"],
+    alias: { y: "yes", h: "help" }
+  });
+  if (argv.help) {
+    console.log(INSTALL_HELP);
+    return 0;
+  }
+  const { flags, warnings, errors } = resolveInstallArgs(argv);
+  for (const w of warnings) console.error(w);
+  for (const e of errors) console.error(e);
+  if (!flags) return 2;
+  return runInstall(flags, realIO(), clackPrompts());
+}
+
 // src/bin.ts
-var HELP = `svelte-vitals \u2014 a SvelteKit SEO checker (static mode)
+var HELP = `svelte-vitals \u2014 a deterministic SvelteKit code-health scanner (SEO \xB7 performance \xB7 correctness \xB7 security \xB7 architecture)
 
 Usage:
   svelte-vitals [path] [options]
+  svelte-vitals install          Set up the MCP server for Claude Code / Cursor / Codex
 
 Options:
   --meta-components <names>   Comma-separated component names that emit head metadata
   --treat-dynamic-as <mode>   pass | warn | fail (default: pass)
   --route <glob>              Only analyze routes matching this glob
+  --diff [ref]                Report only findings in files changed vs ref (default HEAD; e.g. --diff main)
+  --staged                    Report only findings in files staged for commit (pre-commit gate)
   --by-route                  Show per-route score breakdown in console output
   --reporter <fmt>            console | json | agent | sarif | github | html (auto: agent under AI-agent envs, github under GitHub Actions)
   --out-file <path>           Output path for --reporter html (default: svelte-vitals-report.html; '-' for stdout)
@@ -90,6 +399,7 @@ Options:
   --min-health <0-100>        Fail (exit 1) when the combined Health score is below this value
   --rules <ids>               Comma-separated rule ids to enable (all others disabled)
   --ignore <ids>              Comma-separated rule ids to disable
+  --no-color                  Disable ANSI color in console output
   -h, --help                  Show this help
   -v, --version               Show version
 
@@ -99,9 +409,14 @@ Exit codes:
   2  execution error (not a SvelteKit project / internal error)`;
 var VERSION = readPackageVersion();
 async function main() {
-  const argv = mri(process.argv.slice(2), {
+  const rawArgs = process.argv.slice(2);
+  if (rawArgs[0] === "install") {
+    const code2 = await runInstallCli(rawArgs.slice(1));
+    process.exit(code2);
+  }
+  const argv = mri2(process.argv.slice(2), {
     alias: { h: "help", v: "version" },
-    boolean: ["by-route", "json", "fail-on-warning"],
+    boolean: ["by-route", "json", "fail-on-warning", "staged", "no-color"],
     string: [
       "meta-components",
       "treat-dynamic-as",
@@ -111,7 +426,8 @@ async function main() {
       "rules",
       "ignore",
       "min-health",
-      "out-file"
+      "out-file",
+      "diff"
     ]
   });
   if (argv.help) {
@@ -136,7 +452,7 @@ async function main() {
     }
     minHealth = n;
   }
-  const code = await run({ ...options, minHealth });
+  const code = await run({ ...options, minHealth, noColor: argv["no-color"] });
   process.exit(code);
 }
 void main();

package/dist/{chunk-2NZBWTKF.js → chunk-VG647TPJ.js}

@@ -419,6 +419,138 @@ function bodyOnlyAssignsState(fn, stateNames) {
   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)) {
@@ -441,6 +573,47 @@ function collectSecurityFacts(node, source, htmlTags, jsUrls) {
     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) });
+    }
+  });
+}
 function parseComponentFacts(source, filename) {
   const ast = parse(source, { modern: true, filename });
   const eachBlocks = [];
@@ -448,14 +621,32 @@ function parseComponentFacts(source, filename) {
   const htmlTags = [];
   const javascriptUrls = [];
   collectSecurityFacts(ast.fragment ?? ast, source, htmlTags, javascriptUrls);
+  const loc = countLines(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 && isStateDeclaration(n.init) && n.id?.type === "Identifier") {
+      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;
@@ -463,11 +654,21 @@ function parseComponentFacts(source, filename) {
       const isFn = fn?.type === "ArrowFunctionExpression" || fn?.type === "FunctionExpression";
       effects.push({
         line: lineOf(source, n.start),
-        assignsOnlyState: isFn ? bodyOnlyAssignsState(fn, stateNames) : false
+        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 };
+  return { eachBlocks, effects, htmlTags, javascriptUrls, loc, propCount, imports, namespaceImports, constableStates };
 }
 
 // src/providers/source/adapters/svelte-meta-tags.ts
@@ -743,7 +944,18 @@ async function collectComponentFacts(rt, cwd) {
         const source = await rt.readFile(rt.join(cwd, rel));
         return { file: rel, ...parseComponentFacts(source, rel) };
       } catch {
-        return { file: rel, eachBlocks: [], effects: [], htmlTags: [], javascriptUrls: [] };
+        return {
+          file: rel,
+          eachBlocks: [],
+          effects: [],
+          htmlTags: [],
+          javascriptUrls: [],
+          loc: 0,
+          propCount: 0,
+          imports: [],
+          namespaceImports: [],
+          constableStates: []
+        };
       }
     })
   );
@@ -789,6 +1001,69 @@ function isAutoDetectedGithub(explicit, env = process.env) {
   return !explicit && !isReporterName(env.SVELTE_VITALS_REPORTER) && !isAgentEnv(env) && isGithubActionsEnv(env);
 }
 
+// src/changed-files.ts
+import { execFileSync } from "child_process";
+function git(args, cwd) {
+  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).split("\n");
+}
+function getChangedFiles(cwd, opts) {
+  try {
+    const files = opts.staged ? git(["diff", "--name-only", "--cached", "--diff-filter=d"], cwd) : [
+      ...git(["diff", "--name-only", "--diff-filter=d", "--merge-base", opts.base ?? "HEAD"], cwd),
+      ...git(["ls-files", "--others", "--exclude-standard"], cwd)
+      // untracked / new files
+    ];
+    return new Set(files.map((s) => s.trim()).filter(Boolean));
+  } catch {
+    return void 0;
+  }
+}
+function filterToChangedFiles(results, changed) {
+  return results.filter((r) => r.location !== void 0 && changed.has(r.location));
+}
+
+// src/color.ts
+import { noColorPalette } from "@svelte-vitals/core";
+var wrap = (open, close = 0) => (s) => `\x1B[${open}m${s}\x1B[${close}m`;
+var ansiPalette = {
+  bold: wrap(1, 22),
+  dim: wrap(2, 22),
+  red: wrap(31, 39),
+  yellow: wrap(33, 39),
+  green: wrap(32, 39),
+  cyan: wrap(36, 39)
+};
+function colorEnabled(opts) {
+  if (opts.noColorFlag) return false;
+  if (opts.env.NO_COLOR !== void 0 && opts.env.NO_COLOR !== "") return false;
+  const fc = opts.env.FORCE_COLOR;
+  if (fc !== void 0 && fc !== "" && fc !== "0") return true;
+  return opts.reporter === "console" && opts.isTTY;
+}
+var paletteFor = (enabled) => enabled ? ansiPalette : noColorPalette;
+
+// src/spinner.ts
+var FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+function startSpinner(text, opts) {
+  const stream = opts.stream ?? process.stderr;
+  if (!opts.enabled) return { stop() {
+  } };
+  let i = 0;
+  const tick = () => {
+    stream.write(`\r${FRAMES[i % FRAMES.length]} ${text}`);
+    i++;
+  };
+  tick();
+  const timer = setInterval(tick, 80);
+  if (typeof timer.unref === "function") timer.unref();
+  return {
+    stop() {
+      clearInterval(timer);
+      stream.write("\r\x1B[K");
+    }
+  };
+}
+
 // src/rules-config.ts
 import { allRules } from "@svelte-vitals/core";
 var KNOWN_IDS = new Set(allRules.map((r) => r.id));
@@ -808,6 +1083,9 @@ function buildRulesConfig(allow, ignore) {
 }
 
 // src/index.ts
+function spinnerEnabled(opts) {
+  return opts.reporter === "console" && opts.stderrIsTTY && !isAutoDetectedAgent(opts.rawReporter, opts.env) && colorEnabled({ reporter: opts.reporter, isTTY: opts.stderrIsTTY, env: opts.env, noColorFlag: opts.noColorFlag });
+}
 function routeMatcher(glob) {
   if (!glob) return () => true;
   const body = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, " ").replace(/\*/g, "[^/]*").replace(/\/ $/g, "(?:/.*)?").replace(/^ \//g, "(?:.*/)?").replace(/ \//g, "(?:.*/)?").replace(/\/ /g, "(?:/.*)?").replace(/ /g, ".*");
@@ -845,6 +1123,17 @@ async function run(opts = {}) {
     errorLog(`svelte-vitals: invalid minHealth '${opts.minHealth}'; expected a number 0-100.`);
     return 2;
   }
+  const env = opts.env ?? process.env;
+  const reporter = resolveReporter(opts.reporter, env);
+  const spinner = startSpinner("Analyzing\u2026", {
+    enabled: spinnerEnabled({
+      reporter,
+      rawReporter: opts.reporter,
+      stderrIsTTY: opts.stderrIsTTY ?? !!process.stderr.isTTY,
+      env,
+      noColorFlag: opts.noColor
+    })
+  });
   let analysis;
   try {
     analysis = await analyzeProject({
@@ -856,6 +1145,7 @@ async function run(opts = {}) {
       rules: opts.rules
     });
   } catch (err) {
+    spinner.stop();
     if (err instanceof ProjectError) {
       errorLog(err.message);
       return 2;
@@ -863,10 +1153,21 @@ async function run(opts = {}) {
     errorLog(`svelte-vitals: ${err instanceof Error ? err.message : String(err)}`);
     return 2;
   }
+  spinner.stop();
   try {
-    const { results, config, version } = analysis;
-    const env = opts.env ?? process.env;
-    const reporter = resolveReporter(opts.reporter, env);
+    const { config, version } = analysis;
+    let results = analysis.results;
+    if (opts.staged || opts.diffBase !== void 0) {
+      const cwd = opts.cwd ?? process.cwd();
+      const changed = opts.staged ? getChangedFiles(cwd, { staged: true }) : getChangedFiles(cwd, { base: opts.diffBase });
+      if (changed === void 0) {
+        errorLog(
+          "svelte-vitals: could not determine changed files (not a git repo, git unavailable, or bad ref); analyzing all."
+        );
+      } else {
+        results = filterToChangedFiles(results, changed);
+      }
+    }
     if (reporter === "agent" && isAutoDetectedAgent(opts.reporter, env)) {
       errorLog(
         "svelte-vitals: agent reporter auto-selected (AI-agent env detected); override with --reporter console|json."
@@ -900,7 +1201,13 @@ async function run(opts = {}) {
         errorLog(`svelte-vitals: wrote report to ${path}`);
       }
     } else {
-      log(formatConsoleReport(results, config, { byRoute: opts.byRoute ?? false }));
+      const colorOn = colorEnabled({
+        reporter,
+        isTTY: opts.stdoutIsTTY ?? !!process.stdout.isTTY,
+        env,
+        noColorFlag: opts.noColor
+      });
+      log(formatConsoleReport(results, config, { byRoute: opts.byRoute ?? false, palette: paletteFor(colorOn) }));
     }
     const summary = summarize(results, config);
     const failBySeverity = hasFailureAtOrAbove(summary, config.failOn);
@@ -919,6 +1226,7 @@ export {
   findUnknownRuleIds,
   knownRuleIds,
   buildRulesConfig,
+  spinnerEnabled,
   routeMatcher,
   analyzeProject,
   run

package/dist/index.d.ts

@@ -39,7 +39,31 @@ interface RunOptions {
     outFile?: string;
     /** Injected file writer for --reporter html (defaults to node:fs writeFileSync). Mainly for tests. */
     writeFile?: (path: string, content: string) => void;
+    /** Report only findings in files changed vs the merge-base with this ref ('HEAD' = uncommitted). Undefined = no gating. */
+    diffBase?: string;
+    /** Report only findings in files staged for commit. Takes precedence over `diffBase`. */
+    staged?: boolean;
+    /** Disable ANSI color in console output. */
+    noColor?: boolean;
+    /** Override stdout TTY detection (tests). */
+    stdoutIsTTY?: boolean;
+    /** Override stderr TTY detection (tests). */
+    stderrIsTTY?: boolean;
 }
+/**
+ * Whether the "Analyzing…" spinner should run. Unlike color, the spinner animates
+ * with carriage returns and escape codes, so it needs a real interactive stderr —
+ * `FORCE_COLOR` must NOT force it on in a non-TTY stderr (e.g. CI), where `\r` would
+ * clutter the log. So gate on `stderrIsTTY` unconditionally, then reuse the color
+ * gating (NO_COLOR / --no-color / agent env) with that same TTY value.
+ */
+declare function spinnerEnabled(opts: {
+    reporter: ReporterName;
+    rawReporter: ReporterName | undefined;
+    stderrIsTTY: boolean;
+    env: NodeJS.ProcessEnv;
+    noColorFlag?: boolean;
+}): boolean;
 declare function routeMatcher(glob: string | undefined): (route: string) => boolean;
 interface AnalyzeOptions {
     cwd?: string;
@@ -67,4 +91,4 @@ declare function analyzeProject(opts?: AnalyzeOptions): Promise<AnalyzeResult>;
  */
 declare function run(opts?: RunOptions): Promise<number>;
 
-export { type AnalyzeOptions, type AnalyzeResult, ProjectError, type RunOptions, analyzeProject, buildRulesConfig, findUnknownRuleIds, knownRuleIds, routeMatcher, run };
+export { type AnalyzeOptions, type AnalyzeResult, ProjectError, type RunOptions, analyzeProject, buildRulesConfig, findUnknownRuleIds, knownRuleIds, routeMatcher, run, spinnerEnabled };

package/dist/index.js

@@ -5,8 +5,9 @@ import {
   findUnknownRuleIds,
   knownRuleIds,
   routeMatcher,
-  run
-} from "./chunk-2NZBWTKF.js";
+  run,
+  spinnerEnabled
+} from "./chunk-VG647TPJ.js";
 export {
   ProjectError,
   analyzeProject,
@@ -14,5 +15,6 @@ export {
   findUnknownRuleIds,
   knownRuleIds,
   routeMatcher,
-  run
+  run,
+  spinnerEnabled
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-vitals",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "A SvelteKit SEO checker — not a runtime Web Vitals reporter. Static analysis of your routes' head metadata.",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,7 @@
   },
   "homepage": "https://github.com/oekazuma/svelte-vitals#readme",
   "engines": {
-    "node": ">=18"
+    "node": ">=18.20.8"
   },
   "sideEffects": false,
   "bin": {
@@ -39,10 +39,12 @@
     "dist"
   ],
   "dependencies": {
+    "@clack/prompts": "^0.11.0",
     "mri": "^1.2.0",
+    "smol-toml": "^1.7.0",
     "svelte": "^5.56.3",
     "tinyglobby": "^0.2.17",
-    "@svelte-vitals/core": "0.16.0"
+    "@svelte-vitals/core": "0.18.0"
   },
   "devDependencies": {
     "@types/node": "^24.7.0"