svelte-vitals 0.14.0 → 0.17.0

package/dist/bin.js

@@ -6,10 +6,10 @@ import {
   knownRuleIds,
   readPackageVersion,
   run
-} from "./chunk-YMRN4VPN.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-YMRN4VPN.js → chunk-VG647TPJ.js}

@@ -77,8 +77,11 @@ async function detectProject(rt, cwd) {
   );
 }
 async function enumerateRoutePages(rt, cwd) {
-  const pages = await rt.glob(`${ROUTES_DIR}/**/+page.svelte`, cwd);
-  return pages.sort();
+  const [plain, breakout] = await Promise.all([
+    rt.glob(`${ROUTES_DIR}/**/+page.svelte`, cwd),
+    rt.glob(`${ROUTES_DIR}/**/+page@*.svelte`, cwd)
+  ]);
+  return [.../* @__PURE__ */ new Set([...plain, ...breakout])].sort();
 }
 async function existsAny(rt, cwd, paths) {
   const found = await Promise.all(paths.map((p) => rt.exists(rt.join(cwd, p))));
@@ -363,6 +366,310 @@ function parseFile(source, filename) {
     headings
   };
 }
+function isConstantListEach(node) {
+  const expr = node?.expression;
+  return expr?.type === "ArrayExpression" && Array.isArray(expr.elements) && !expr.elements.some((el) => el?.type === "SpreadElement");
+}
+function collectEachBlocks(node, source, acc) {
+  if (Array.isArray(node)) {
+    for (const child of node) collectEachBlocks(child, source, acc);
+    return;
+  }
+  if (!node || typeof node !== "object") return;
+  if (node.type === "EachBlock" && !isConstantListEach(node)) {
+    acc.push({ hasKey: node.key != null, line: lineOf(source, node.start) });
+  }
+  for (const key of CHILD_NODE_KEYS) {
+    if (key in node) collectEachBlocks(node[key], source, acc);
+  }
+}
+function walkEstree(node, visit) {
+  if (Array.isArray(node)) {
+    for (const child of node) walkEstree(child, visit);
+    return;
+  }
+  if (!node || typeof node !== "object" || typeof node.type !== "string") return;
+  visit(node);
+  for (const key of Object.keys(node)) {
+    if (key === "type" || key === "start" || key === "end" || key === "loc" || key === "range") continue;
+    walkEstree(node[key], visit);
+  }
+}
+function isEffectCall(node) {
+  const c = node?.callee;
+  if (c?.type === "Identifier") return c.name === "$effect";
+  if (c?.type === "MemberExpression" && c.object?.type === "Identifier" && c.object.name === "$effect") {
+    return c.property?.type === "Identifier" && c.property.name === "pre";
+  }
+  return false;
+}
+function isStateDeclaration(node) {
+  const c = node?.callee;
+  if (c?.type === "Identifier") return c.name === "$state";
+  if (c?.type === "MemberExpression" && c.object?.type === "Identifier" && c.object.name === "$state") {
+    return c.property?.type === "Identifier" && (c.property.name === "raw" || c.property.name === "frozen");
+  }
+  return false;
+}
+function bodyOnlyAssignsState(fn, stateNames) {
+  const isStateAssign = (expr) => expr?.type === "AssignmentExpression" && expr.operator === "=" && expr.left?.type === "Identifier" && stateNames.has(expr.left.name);
+  const body = fn?.body;
+  if (!body) return false;
+  if (body.type !== "BlockStatement") return isStateAssign(body);
+  if (body.body.length === 0) return false;
+  return body.body.every((s) => s?.type === "ExpressionStatement" && isStateAssign(s.expression));
+}
+function isDerivedDeclaration(node) {
+  const c = node?.callee;
+  if (c?.type === "Identifier") return c.name === "$derived";
+  if (c?.type === "MemberExpression" && c.object?.type === "Identifier" && c.object.name === "$derived") {
+    return c.property?.type === "Identifier" && c.property.name === "by";
+  }
+  return false;
+}
+function addBoundNames(id, acc) {
+  if (!id) return;
+  switch (id.type) {
+    case "Identifier":
+      acc.add(id.name);
+      break;
+    case "ObjectPattern":
+      for (const p of id.properties ?? []) {
+        if (p?.type === "Property") addBoundNames(p.value, acc);
+        else if (p?.type === "RestElement") addBoundNames(p.argument, acc);
+      }
+      break;
+    case "ArrayPattern":
+      for (const el of id.elements ?? []) addBoundNames(el, acc);
+      break;
+    case "AssignmentPattern":
+      addBoundNames(id.left, acc);
+      break;
+    case "RestElement":
+      addBoundNames(id.argument, acc);
+      break;
+  }
+}
+function rootObjectName(node) {
+  let cur = node;
+  while (cur?.type === "MemberExpression") cur = cur.object;
+  return cur?.type === "Identifier" ? cur.name : void 0;
+}
+function collectStateWrites(root, stateNames, acc) {
+  walkEstree(root, (n) => {
+    if (n?.type === "AssignmentExpression") {
+      if (n.left?.type === "Identifier" && stateNames.has(n.left.name)) acc.add(n.left.name);
+      else if (n.left?.type === "MemberExpression") {
+        const r = rootObjectName(n.left);
+        if (r && stateNames.has(r)) acc.add(r);
+      } else if (n.left?.type === "ObjectPattern" || n.left?.type === "ArrayPattern") {
+        const bound = /* @__PURE__ */ new Set();
+        addBoundNames(n.left, bound);
+        for (const name of bound) if (stateNames.has(name)) acc.add(name);
+      }
+    } else if (n?.type === "UpdateExpression") {
+      const r = rootObjectName(n.argument);
+      if (r && stateNames.has(r)) acc.add(r);
+    } else if (n?.type === "UnaryExpression" && n.operator === "delete") {
+      const r = rootObjectName(n.argument);
+      if (r && stateNames.has(r)) acc.add(r);
+    } else if (n?.type === "CallExpression") {
+      if (n.callee?.type === "MemberExpression") {
+        const r = rootObjectName(n.callee);
+        if (r && stateNames.has(r)) acc.add(r);
+      }
+      for (const a of n.arguments ?? []) {
+        const arg = a?.type === "SpreadElement" ? a.argument : a;
+        const r = rootObjectName(arg);
+        if (r && stateNames.has(r)) acc.add(r);
+      }
+    }
+  });
+}
+var COMPONENT_LIKE_TYPES = /* @__PURE__ */ new Set(["Component", "SvelteComponent", "SvelteSelf"]);
+function collectTemplateEscapes(node, stateNames, acc) {
+  if (Array.isArray(node)) {
+    for (const c of node) collectTemplateEscapes(c, stateNames, acc);
+    return;
+  }
+  if (!node || typeof node !== "object" || typeof node.type !== "string") return;
+  if (Array.isArray(node.attributes)) {
+    for (const attr of node.attributes) {
+      if (attr?.type === "BindDirective") {
+        const r = rootObjectName(attr.expression);
+        if (r && stateNames.has(r)) acc.add(r);
+      } else if (COMPONENT_LIKE_TYPES.has(node.type)) {
+        walkEstree(attr, (m) => {
+          if (m?.type === "Identifier" && stateNames.has(m.name)) acc.add(m.name);
+        });
+      }
+    }
+  }
+  for (const key of CHILD_NODE_KEYS) {
+    if (key in node) collectTemplateEscapes(node[key], stateNames, acc);
+  }
+}
+var RUNE_NAMES = /* @__PURE__ */ new Set(["$state", "$derived", "$effect", "$props", "$bindable", "$inspect", "$host"]);
+function bodyReadsReactive(fn, reactiveNames) {
+  let reads = false;
+  const IGNORED_KEYS = /* @__PURE__ */ new Set(["type", "start", "end", "loc", "range"]);
+  const visit = (n) => {
+    if (reads || !n) return;
+    if (Array.isArray(n)) {
+      for (const c of n) visit(c);
+      return;
+    }
+    if (typeof n !== "object" || typeof n.type !== "string") return;
+    if (n.type === "Identifier") {
+      if (reactiveNames.has(n.name) || n.name.startsWith("$") && !RUNE_NAMES.has(n.name)) reads = true;
+      return;
+    }
+    if (n.type === "CallExpression" && n.callee?.type === "Identifier") {
+      reads = true;
+      return;
+    }
+    if (n.type === "MemberExpression") {
+      visit(n.object);
+      if (n.computed) visit(n.property);
+      return;
+    }
+    if (n.type === "Property") {
+      if (n.computed) visit(n.key);
+      visit(n.value);
+      return;
+    }
+    for (const key of Object.keys(n)) {
+      if (!IGNORED_KEYS.has(key)) visit(n[key]);
+    }
+  };
+  visit(fn.body);
+  return reads;
+}
+function bodyIsEmpty(fn) {
+  const body = fn?.body;
+  if (!body) return true;
+  if (body.type === "BlockStatement") return (body.body ?? []).length === 0;
+  return false;
+}
+var URL_ATTRS = ["href", "src", "action", "formaction"];
+function collectSecurityFacts(node, source, htmlTags, jsUrls) {
+  if (Array.isArray(node)) {
+    for (const child of node) collectSecurityFacts(child, source, htmlTags, jsUrls);
+    return;
+  }
+  if (!node || typeof node !== "object") return;
+  if (node.type === "HtmlTag") htmlTags.push({ line: lineOf(source, node.start) });
+  if ((node.type === "RegularElement" || node.type === "SvelteElement") && Array.isArray(node.attributes)) {
+    for (const name of URL_ATTRS) {
+      const attr = findAttr(node.attributes, name);
+      if (!attr) continue;
+      const value = attrTextOf(attr);
+      if (value !== void 0 && /^\s*javascript:/i.test(value)) {
+        jsUrls.push({ line: lineOf(source, attr.start ?? node.start) });
+      }
+    }
+  }
+  for (const key of CHILD_NODE_KEYS) {
+    if (key in node) collectSecurityFacts(node[key], source, htmlTags, jsUrls);
+  }
+}
+function isPropsCall(node) {
+  return node?.type === "CallExpression" && node.callee?.type === "Identifier" && node.callee.name === "$props";
+}
+function countProps(program) {
+  let count = 0;
+  let seen = 0;
+  let uncountable = false;
+  walkEstree(program, (n) => {
+    if (n.type !== "VariableDeclarator" || !n.init || !isPropsCall(n.init)) return;
+    seen++;
+    const props = n.id?.type === "ObjectPattern" ? n.id.properties : void 0;
+    if (!Array.isArray(props) || props.some((p) => p?.type === "RestElement")) {
+      uncountable = true;
+      return;
+    }
+    count = props.filter((p) => p?.type === "Property").length;
+  });
+  return uncountable || seen > 1 ? 0 : count;
+}
+function countLines(source) {
+  if (source.length === 0) return 0;
+  return source.split("\n").length - (source.endsWith("\n") ? 1 : 0);
+}
+function collectImportSources(program, acc) {
+  walkEstree(program, (n) => {
+    if (n.type === "ImportDeclaration" && typeof n.source?.value === "string") acc.push(n.source.value);
+  });
+}
+function isBareSpecifier(s) {
+  return !/^[./$#]/.test(s);
+}
+function collectNamespaceImports(program, source, acc) {
+  walkEstree(program, (n) => {
+    if (n.type !== "ImportDeclaration" || n.importKind === "type") return;
+    const spec = n.source?.value;
+    if (typeof spec !== "string" || !isBareSpecifier(spec)) return;
+    if (Array.isArray(n.specifiers) && n.specifiers.some((s) => s?.type === "ImportNamespaceSpecifier")) {
+      acc.push({ source: spec, line: lineOf(source, n.start) });
+    }
+  });
+}
+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 imports = [];
+  const namespaceImports = [];
+  if (ast.module?.content) {
+    collectImportSources(ast.module.content, imports);
+    collectNamespaceImports(ast.module.content, source, namespaceImports);
+  }
+  const effects = [];
+  const constableStates = [];
+  let propCount = 0;
+  const program = ast.instance?.content;
+  if (program) {
+    collectImportSources(program, imports);
+    collectNamespaceImports(program, source, namespaceImports);
+    propCount = countProps(program);
+    const stateNames = /* @__PURE__ */ new Set();
+    const reactiveNames = /* @__PURE__ */ new Set();
+    const stateDecls = [];
+    walkEstree(program, (n) => {
+      if (n.type !== "VariableDeclarator" || !n.init) return;
+      if (isStateDeclaration(n.init) && n.id?.type === "Identifier") {
+        stateNames.add(n.id.name);
+        stateDecls.push({ name: n.id.name, line: lineOf(source, n.start) });
+      }
+      if (isStateDeclaration(n.init) || isDerivedDeclaration(n.init) || isPropsCall(n.init))
+        addBoundNames(n.id, reactiveNames);
+    });
+    walkEstree(program, (n) => {
+      if (n.type !== "CallExpression" || !isEffectCall(n)) return;
+      const fn = n.arguments?.[0];
+      const isFn = fn?.type === "ArrowFunctionExpression" || fn?.type === "FunctionExpression";
+      effects.push({
+        line: lineOf(source, n.start),
+        assignsOnlyState: isFn ? bodyOnlyAssignsState(fn, stateNames) : false,
+        mountOnly: isFn ? !bodyIsEmpty(fn) && !bodyReadsReactive(fn, reactiveNames) : false
+      });
+    });
+    const writtenOrEscaped = /* @__PURE__ */ new Set();
+    collectStateWrites(program, stateNames, writtenOrEscaped);
+    if (ast.fragment) {
+      collectStateWrites(ast.fragment, stateNames, writtenOrEscaped);
+      collectTemplateEscapes(ast.fragment, stateNames, writtenOrEscaped);
+    }
+    for (const d of stateDecls) {
+      if (!writtenOrEscaped.has(d.name)) constableStates.push(d);
+    }
+  }
+  return { eachBlocks, effects, htmlTags, javascriptUrls, loc, propCount, imports, namespaceImports, constableStates };
+}
 
 // src/providers/source/adapters/svelte-meta-tags.ts
 function findAttr2(attributes, name) {
@@ -519,27 +826,68 @@ var MAX_DEPTH = 5;
 function isGroupSegment(segment) {
   return /^\(.+\)$/.test(segment);
 }
+function dirOf(rel) {
+  const i = rel.lastIndexOf("/");
+  return i >= 0 ? rel.slice(0, i) : "";
+}
+function dirSegments(dir) {
+  const extra = dir.slice(ROUTES_DIR2.length);
+  return extra.length === 0 ? [] : extra.split("/").filter(Boolean);
+}
+function dirKey(segs) {
+  return segs.length === 0 ? ROUTES_DIR2 : `${ROUTES_DIR2}/${segs.join("/")}`;
+}
+function parseAt(rel) {
+  const file = rel.slice(rel.lastIndexOf("/") + 1);
+  const m = /^\+(?:page|layout)@(.*)\.svelte$/.exec(file);
+  return m ? m[1] : null;
+}
+function atTarget(rel, dirSegs, strictAncestor = false) {
+  const at = parseAt(rel);
+  if (at === null) return null;
+  if (at === "") return [];
+  const haystack = strictAncestor ? dirSegs.slice(0, -1) : dirSegs;
+  const i = haystack.lastIndexOf(at);
+  return i >= 0 ? dirSegs.slice(0, i + 1) : null;
+}
 function deriveRoute(pageRel) {
-  const inner = pageRel.slice(`${ROUTES_DIR2}/`.length, -"/+page.svelte".length);
-  const segments = inner.length === 0 ? [] : inner.split("/").filter((s) => !isGroupSegment(s));
+  const segments = dirSegments(dirOf(pageRel)).filter((s) => !isGroupSegment(s));
   return "/" + segments.join("/");
 }
-async function chainFiles(rt, cwd, pageRel) {
-  const dir = pageRel.slice(0, -"/+page.svelte".length);
-  const extra = dir.slice(ROUTES_DIR2.length);
-  const segments = extra.length === 0 ? [] : extra.split("/").filter(Boolean);
-  const files = [];
-  let prefix = ROUTES_DIR2;
-  for (let i = 0; i <= segments.length; i++) {
-    if (i > 0) prefix = `${prefix}/${segments[i - 1]}`;
-    const layout = `${prefix}/+layout.svelte`;
-    if (await rt.exists(rt.join(cwd, layout))) files.push({ rel: layout, isPage: false });
-  }
-  files.push({ rel: pageRel, isPage: true });
-  return files;
-}
-async function resolveRoute(rt, cwd, pageRel, config) {
-  const files = await chainFiles(rt, cwd, pageRel);
+async function collectLayouts(rt, cwd) {
+  const [plain, breakout] = await Promise.all([
+    rt.glob(`${ROUTES_DIR2}/**/+layout.svelte`, cwd),
+    rt.glob(`${ROUTES_DIR2}/**/+layout@*.svelte`, cwd)
+  ]);
+  const map = /* @__PURE__ */ new Map();
+  for (const rel of [...plain, ...breakout]) map.set(dirOf(rel), rel);
+  return map;
+}
+function layoutAtOrAbove(segs, layouts) {
+  for (let j = segs.length; j >= 0; j--) {
+    const rel = layouts.get(dirKey(segs.slice(0, j)));
+    if (rel) return { segs: segs.slice(0, j), rel };
+  }
+  return null;
+}
+function chainFiles(pageRel, layouts) {
+  const pageSegs = dirSegments(dirOf(pageRel));
+  let dir = atTarget(pageRel, pageSegs) ?? pageSegs;
+  const chain = [];
+  const seen = /* @__PURE__ */ new Set();
+  while (dir !== null) {
+    const found = layoutAtOrAbove(dir, layouts);
+    if (!found || seen.has(found.rel)) break;
+    seen.add(found.rel);
+    chain.unshift(found.rel);
+    const reset = atTarget(found.rel, found.segs, true);
+    dir = reset !== null && reset.length < found.segs.length ? reset : found.segs.slice(0, -1);
+    if (dir.length === 0 && found.segs.length === 0) dir = null;
+  }
+  return [...chain.map((rel) => ({ rel, isPage: false })), { rel: pageRel, isPage: true }];
+}
+async function resolveRoute(rt, cwd, pageRel, config, layouts) {
+  const files = chainFiles(pageRel, layouts);
   const composed = /* @__PURE__ */ new Map();
   let broadOwn = false;
   let broadInherited = false;
@@ -578,8 +926,8 @@ async function resolveRoute(rt, cwd, pageRel, config) {
   };
 }
 async function collectRoutes(rt, cwd, config = defaultConfig) {
-  const pages = await enumerateRoutePages(rt, cwd);
-  const facts = await Promise.all(pages.map((page) => resolveRoute(rt, cwd, page, config)));
+  const [pages, layouts] = await Promise.all([enumerateRoutePages(rt, cwd), collectLayouts(rt, cwd)]);
+  const facts = await Promise.all(pages.map((page) => resolveRoute(rt, cwd, page, config, layouts)));
   return {
     heads: facts.map((f) => f.head),
     images: facts.map((f) => f.images),
@@ -587,6 +935,32 @@ async function collectRoutes(rt, cwd, config = defaultConfig) {
   };
 }
 
+// src/providers/source/components.ts
+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 {
+          file: rel,
+          eachBlocks: [],
+          effects: [],
+          htmlTags: [],
+          javascriptUrls: [],
+          loc: 0,
+          propCount: 0,
+          imports: [],
+          namespaceImports: [],
+          constableStates: []
+        };
+      }
+    })
+  );
+}
+
 // src/version.ts
 import { readFileSync } from "fs";
 function readPackageVersion() {
@@ -627,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));
@@ -646,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, ".*");
@@ -668,8 +1108,12 @@ async function analyzeProject(opts = {}) {
   const images = collected.images.filter((i) => matches(i.route));
   const headings = collected.headings.filter((h) => matches(h.route));
   const project = await collectProjectFacts(rt, cwd);
+  const components = opts.route ? [] : await collectComponentFacts(rt, cwd);
   const rules = selectRules(allRules2, config);
-  const results = applyRuleSeverities(await runRules(rules, { heads, images, headings, project, config }), config);
+  const results = applyRuleSeverities(
+    await runRules(rules, { heads, images, headings, components, project, config }),
+    config
+  );
   return { results, config, version: readPackageVersion() };
 }
 async function run(opts = {}) {
@@ -679,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({
@@ -690,6 +1145,7 @@ async function run(opts = {}) {
       rules: opts.rules
     });
   } catch (err) {
+    spinner.stop();
     if (err instanceof ProjectError) {
       errorLog(err.message);
       return 2;
@@ -697,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."
@@ -734,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);
@@ -753,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-YMRN4VPN.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.14.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.15.0"
+    "@svelte-vitals/core": "0.18.0"
   },
   "devDependencies": {
     "@types/node": "^24.7.0"