svelte-vitals 0.15.0 → 0.18.0

package/dist/bin.js

@@ -6,10 +6,10 @@ import {
   knownRuleIds,
   readPackageVersion,
   run
-} from "./chunk-2NZBWTKF.js";
+} from "./chunk-NLQZ3CMZ.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,570 @@ 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 { spawnSync } from "child_process";
+import mri from "mri";
+import * as p from "@clack/prompts";
+
+// src/install/index.ts
+import { join as join3 } from "path";
+
+// 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/vite-targets.ts
+var VITE_TARGETS = [
+  {
+    id: "vite-plugin",
+    label: "Vite plugin (build gate)",
+    hint: "Fails `vite build` when prerendered pages cross the SEO/Performance threshold"
+  },
+  {
+    id: "vite-dev-overlay",
+    label: "Dev overlay",
+    hint: "Live warnings in `vite dev` only \u2014 never fails a build or CI"
+  }
+];
+function viteTargetById(id) {
+  return VITE_TARGETS.find((t) => t.id === id);
+}
+function isViteTargetId(id) {
+  return VITE_TARGETS.some((t) => t.id === id);
+}
+
+// src/install/codemod-vite-config.ts
+import { parseModule, generateCode, builders, MagicastError } from "magicast";
+var MANUAL_SNIPPET = `import { svelteVitals } from '@svelte-vitals/vite';
+// add svelteVitals() to your \`plugins\` array`;
+function codemodViteConfig(existing) {
+  if (existing === void 0) {
+    return { status: "manual", snippet: MANUAL_SNIPPET };
+  }
+  try {
+    const mod = parseModule(existing);
+    const def = mod.exports.default;
+    const configObj = def?.$type === "function-call" ? def.$args[0] : def;
+    if (!configObj || configObj.$type !== "object" || configObj.plugins?.$type !== "array") {
+      return { status: "manual", snippet: MANUAL_SNIPPET };
+    }
+    const already = configObj.plugins.find(
+      (p2) => p2?.$type === "function-call" && p2?.$callee === "svelteVitals"
+    );
+    if (already !== void 0) {
+      return { status: "exists" };
+    }
+    if (!mod.imports.svelteVitals) {
+      mod.imports.$append({ imported: "svelteVitals", local: "svelteVitals", from: "@svelte-vitals/vite" });
+    }
+    configObj.plugins.unshift(builders.functionCall("svelteVitals"));
+    return { status: "added", content: generateCode(mod, { format: { objectCurlySpacing: true } }).code };
+  } catch (err) {
+    if (err instanceof MagicastError) {
+      return { status: "manual", snippet: MANUAL_SNIPPET };
+    }
+    throw err;
+  }
+}
+
+// src/install/codemod-hooks.ts
+import { parseModule as parseModule2, generateCode as generateCode2, builders as builders2, MagicastError as MagicastError2 } from "magicast";
+var FRESH_HANDLE = `import { svelteVitalsHandle } from '@svelte-vitals/vite/hooks';
+import { sequence } from '@sveltejs/kit/hooks';
+
+export const handle = sequence(svelteVitalsHandle());
+`;
+var MANUAL_SNIPPET2 = `import { svelteVitalsHandle } from '@svelte-vitals/vite/hooks';
+import { sequence } from '@sveltejs/kit/hooks';
+// wrap your existing \`handle\` in sequence(yourHandle, svelteVitalsHandle())`;
+function addImports(mod) {
+  if (!mod.imports.sequence) {
+    mod.imports.$append({ imported: "sequence", local: "sequence", from: "@sveltejs/kit/hooks" });
+  }
+  if (!mod.imports.svelteVitalsHandle) {
+    mod.imports.$append({
+      imported: "svelteVitalsHandle",
+      local: "svelteVitalsHandle",
+      from: "@svelte-vitals/vite/hooks"
+    });
+  }
+}
+function codemodHooksServer(existing) {
+  if (existing === void 0) {
+    return { status: "created", content: FRESH_HANDLE };
+  }
+  try {
+    const mod = parseModule2(existing);
+    const handle = mod.exports.handle;
+    if (handle === void 0) {
+      addImports(mod);
+      mod.exports.handle = builders2.functionCall("sequence", builders2.functionCall("svelteVitalsHandle"));
+      return {
+        status: "added",
+        content: generateCode2(mod, { format: { objectCurlySpacing: true, quote: "single" } }).code
+      };
+    }
+    if (handle.$type === "function-call" && handle.$callee === "sequence") {
+      const already = handle.$args.find(
+        (a) => a?.$type === "function-call" && a?.$callee === "svelteVitalsHandle"
+      );
+      if (already !== void 0) {
+        return { status: "exists" };
+      }
+      if (!mod.imports.svelteVitalsHandle) {
+        mod.imports.$append({
+          imported: "svelteVitalsHandle",
+          local: "svelteVitalsHandle",
+          from: "@svelte-vitals/vite/hooks"
+        });
+      }
+      handle.$args.push(builders2.functionCall("svelteVitalsHandle"));
+      return {
+        status: "added",
+        content: generateCode2(mod, { format: { objectCurlySpacing: true, quote: "single" } }).code
+      };
+    }
+    addImports(mod);
+    mod.exports.handle = builders2.functionCall("sequence", handle, builders2.functionCall("svelteVitalsHandle"));
+    return {
+      status: "updated",
+      content: generateCode2(mod, { format: { objectCurlySpacing: true, quote: "single" } }).code
+    };
+  } catch (err) {
+    if (err instanceof MagicastError2) {
+      return { status: "manual", snippet: MANUAL_SNIPPET2 };
+    }
+    throw err;
+  }
+}
+
+// src/install/package-manager.ts
+import { join as join2 } from "path";
+var LOCKFILE_TO_PM = {
+  "pnpm-lock.yaml": "pnpm",
+  "yarn.lock": "yarn",
+  "bun.lock": "bun",
+  "bun.lockb": "bun"
+};
+function detectPackageManager(io) {
+  for (const [file, pm] of Object.entries(LOCKFILE_TO_PM)) {
+    if (io.readFile(join2(io.cwd, file)) !== void 0) return pm;
+  }
+  return "npm";
+}
+function hasVitePackage(io) {
+  const raw = io.readFile(join2(io.cwd, "package.json"));
+  if (raw === void 0) return false;
+  try {
+    const pkg = JSON.parse(raw);
+    return Boolean(pkg.dependencies?.["@svelte-vitals/vite"] || pkg.devDependencies?.["@svelte-vitals/vite"]);
+  } catch {
+    return false;
+  }
+}
+function installCommand(pm) {
+  const action = pm === "npm" ? "install" : "add";
+  return { command: pm, args: [action, "-D", "@svelte-vitals/vite"] };
+}
+
+// src/install/index.ts
+function planForClient(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 { id: client.id, label: client.label, scope, path, status: merged.status, content: merged.content };
+}
+function resolveCandidate(io, candidates) {
+  for (const rel of candidates) {
+    const path = join3(io.cwd, rel);
+    const content = io.readFile(path);
+    if (content !== void 0) return { path, content };
+  }
+  return { path: join3(io.cwd, candidates[0]), content: void 0 };
+}
+function planForVitePlugin(io) {
+  const { path, content } = resolveCandidate(io, ["vite.config.ts", "vite.config.js", "vite.config.mjs"]);
+  const result = codemodViteConfig(content);
+  return { id: "vite-plugin", label: viteTargetById("vite-plugin").label, path, ...result };
+}
+function planForDevOverlay(io) {
+  const { path, content } = resolveCandidate(io, ["src/hooks.server.ts", "src/hooks.server.js"]);
+  const result = codemodHooksServer(content);
+  return { id: "vite-dev-overlay", label: viteTargetById("vite-dev-overlay").label, path, ...result };
+}
+function indent(text) {
+  return text.split("\n").map((l) => `      ${l}`).join("\n");
+}
+function rowLine(r) {
+  const head = `  ${r.label}${r.scope ? ` (${r.scope})` : ""} \u2192 ${r.path}  [${r.status}]`;
+  return r.status === "manual" && r.snippet ? `${head}
+${indent(r.snippet)}` : head;
+}
+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 detectedClients = CLIENTS.filter(
+      (c) => c.scopes.some((s) => configExists(c.resolvePath(s, io.cwd, io.home)))
+    ).map((c) => c.id);
+    const viteConfigExists = ["vite.config.ts", "vite.config.js", "vite.config.mjs"].some(
+      (f) => configExists(join3(io.cwd, f))
+    );
+    const detected = [...detectedClients, ...viteConfigExists ? VITE_TARGETS.map((t) => t.id) : []];
+    const options = [
+      ...CLIENTS.map((c) => ({ id: c.id, label: c.label })),
+      ...VITE_TARGETS.map((t) => ({ id: t.id, label: t.label, hint: t.hint }))
+    ];
+    const picked = await prompts.selectClients(options, detected);
+    if (picked === null) {
+      io.log("Cancelled.");
+      return 0;
+    }
+    ids = picked;
+  } else {
+    io.errorLog(
+      "svelte-vitals: no TTY; pass --client <claude-code,cursor,codex,vite-plugin,vite-dev-overlay> to install non-interactively."
+    );
+    return 2;
+  }
+  const clients = ids.map(clientById).filter((c) => c !== void 0);
+  const viteIds = ids.filter(isViteTargetId);
+  if (clients.length === 0 && viteIds.length === 0) {
+    io.errorLog("svelte-vitals: no valid clients or targets 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(planForClient(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;
+    }
+  }
+  for (const viteId of viteIds) {
+    rows.push(viteId === "vite-plugin" ? planForVitePlugin(io) : planForDevOverlay(io));
+  }
+  const planText = rows.map(rowLine).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;
+  let viteWasWritten = false;
+  for (const r of rows) {
+    if (r.status === "exists") {
+      const hint = isViteTargetId(r.id) ? "" : " \u2014 use --force to overwrite";
+      io.log(`= ${r.label}: already configured (${r.path})${hint}.`);
+      continue;
+    }
+    if (r.status === "manual") {
+      io.log(`! ${r.label}: couldn't safely modify ${r.path} \u2014 add this by hand:
+${indent(r.snippet ?? "")}`);
+      continue;
+    }
+    try {
+      io.writeFile(r.path, r.content ?? "");
+      io.log(`\u2713 ${r.label}: ${r.status} ${r.path}`);
+      if (isViteTargetId(r.id)) viteWasWritten = true;
+    } catch (err) {
+      hadFailure = true;
+      io.errorLog(`svelte-vitals: failed to write ${r.path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  if (viteWasWritten && io.runCommand && !hasVitePackage(io)) {
+    const pm = detectPackageManager(io);
+    const { command, args } = installCommand(pm);
+    io.log(`Installing @svelte-vitals/vite via ${pm}...`);
+    const code = io.runCommand(command, args, io.cwd);
+    if (code !== 0) {
+      io.errorLog(
+        `svelte-vitals: failed to install @svelte-vitals/vite (${command} ${args.join(" ")} exited ${code}). Install it manually.`
+      );
+    }
+  }
+  if (hadFailure) return 2;
+  io.log("");
+  if (clients.length > 0) io.log("Restart your client to load the svelte-vitals MCP server.");
+  if (viteWasWritten) io.log("Restart `vite dev` (or your build) to pick up the change.");
+  io.log("Done.");
+  return 0;
+}
+
+// src/install/args.ts
+var VALID_TARGETS = [...CLIENTS.map((c) => c.id), ...VITE_TARGETS.map((t) => t.id)];
+var EXPECTED_TARGETS = VALID_TARGETS.join("|");
+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_TARGETS.includes(c)) {
+      if (!client.includes(c)) client.push(c);
+    } else {
+      warnings.push(`svelte-vitals: unknown --client '${c}'; expected ${EXPECTED_TARGETS}. Skipping.`);
+    }
+  }
+  if (rawClients.length > 0 && client.length === 0) {
+    errors.push(`svelte-vitals: no valid --client values; expected ${EXPECTED_TARGETS}.`);
+  }
+  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,vite-plugin,vite-dev-overlay (skips the interactive picker)
+                    vite-plugin registers the build-mode plugin in vite.config.{ts,js,mjs}; vite-dev-overlay
+                    wires up the dev-overlay hook in src/hooks.server.{ts,js}. --force does not apply
+                    to either \u2014 an existing registration is always left as-is.
+  --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),
+    runCommand: (command, args, cwd) => {
+      const result = spawnSync(command, args, {
+        cwd,
+        stdio: "inherit",
+        shell: process.platform === "win32",
+        timeout: 12e4
+      });
+      if (result.error) {
+        console.error(`svelte-vitals: ${command} failed to start: ${result.error.message}`);
+        return 1;
+      }
+      if (result.signal) {
+        console.error(`svelte-vitals: ${command} was terminated (${result.signal}) \u2014 it may have timed out.`);
+        return 1;
+      }
+      return result.status ?? 1;
+    }
+  };
+}
+function clackPrompts() {
+  return {
+    selectClients: async (all, defaults) => {
+      const res = await p.multiselect({
+        message: "Which clients/targets should svelte-vitals be installed for?",
+        options: all.map((o) => ({ value: o.id, label: o.label, hint: o.hint })),
+        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 +639,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 +649,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 +666,8 @@ async function main() {
       "rules",
       "ignore",
       "min-health",
-      "out-file"
+      "out-file",
+      "diff"
     ]
   });
   if (argv.help) {
@@ -136,7 +692,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-NLQZ3CMZ.js}

@@ -124,6 +124,15 @@ async function collectProjectFacts(rt, cwd) {
 
 // src/providers/source/parse.ts
 import { parse } from "svelte/compiler";
+import {
+  CHILD_NODE_KEYS,
+  lineOf,
+  findAttr,
+  valueFromNodes,
+  textFromNodes,
+  attrText,
+  attrValue
+} from "@svelte-vitals/core";
 
 // src/providers/source/imports.ts
 function addImportsFromProgram(program, map) {
@@ -150,58 +159,6 @@ function collectImports(ast) {
 }
 
 // src/providers/source/parse.ts
-var CHILD_NODE_KEYS = [
-  "fragment",
-  "nodes",
-  "consequent",
-  "alternate",
-  "body",
-  "pending",
-  "then",
-  "catch",
-  "fallback"
-];
-function valueFromNodes(nodes) {
-  if (!Array.isArray(nodes)) return "absent";
-  if (nodes.some((n) => n?.type === "ExpressionTag")) return "dynamic";
-  const text = nodes.filter((n) => n?.type === "Text").map((n) => String(n.data ?? "")).join("");
-  return text.trim().length > 0 ? "static" : "absent";
-}
-function textFromNodes(nodes) {
-  if (!Array.isArray(nodes) || nodes.some((n) => n?.type === "ExpressionTag")) return void 0;
-  const text = nodes.filter((n) => n?.type === "Text").map((n) => String(n.data ?? "")).join("");
-  return text.trim().length > 0 ? text : void 0;
-}
-function attrText(attributes, name) {
-  const attr = findAttr(attributes, name);
-  if (!attr) return void 0;
-  const v = attr.value;
-  if (v === true) return "";
-  if (Array.isArray(v)) {
-    return v.filter((n) => n?.type === "Text").map((n) => String(n.data ?? "")).join("");
-  }
-  return void 0;
-}
-function attrValue(attributes, name) {
-  const attr = findAttr(attributes, name);
-  if (!attr) return "absent";
-  const v = attr.value;
-  if (v === true) return "absent";
-  if (Array.isArray(v)) return valueFromNodes(v);
-  if (v && v.type === "ExpressionTag") return "dynamic";
-  return "absent";
-}
-function lineOf(source, offset) {
-  if (typeof offset !== "number" || offset < 0) return 0;
-  let line = 1;
-  const end = Math.min(offset, source.length);
-  for (let i = 0; i < end; i++) if (source[i] === "\n") line++;
-  return line;
-}
-function findAttr(attributes, name) {
-  if (!Array.isArray(attributes)) return void 0;
-  return attributes.find((a) => a?.type === "Attribute" && a.name === name);
-}
 function collectSvelteHeads(node, acc) {
   if (Array.isArray(node)) {
     for (const child of node) collectSvelteHeads(child, acc);
@@ -279,19 +236,6 @@ function tagsFromHead(head) {
   }
   return tags;
 }
-function attrValueOf(attr) {
-  const v = attr?.value;
-  if (v === true) return "absent";
-  if (Array.isArray(v)) return valueFromNodes(v);
-  if (v && v.type === "ExpressionTag") return "dynamic";
-  return "absent";
-}
-function attrTextOf(attr) {
-  const v = attr?.value;
-  if (!Array.isArray(v) || v.some((n) => n?.type === "ExpressionTag")) return void 0;
-  const text = v.filter((n) => n?.type === "Text").map((n) => String(n.data ?? "")).join("");
-  return text.trim().length > 0 ? text : void 0;
-}
 function collectComponents(node, acc) {
   if (Array.isArray(node)) {
     for (const child of node) collectComponents(child, acc);
@@ -366,111 +310,9 @@ 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));
-}
-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 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 effects = [];
-  const program = ast.instance?.content;
-  if (program) {
-    const stateNames = /* @__PURE__ */ new Set();
-    walkEstree(program, (n) => {
-      if (n.type === "VariableDeclarator" && n.init && isStateDeclaration(n.init) && n.id?.type === "Identifier") {
-        stateNames.add(n.id.name);
-      }
-    });
-    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
-      });
-    });
-  }
-  return { eachBlocks, effects, htmlTags, javascriptUrls };
-}
 
 // src/providers/source/adapters/svelte-meta-tags.ts
+import { attrValueOf, attrTextOf } from "@svelte-vitals/core";
 function findAttr2(attributes, name) {
   return attributes.find((a) => a?.type === "Attribute" && a.name === name);
 }
@@ -508,6 +350,7 @@ var svelteMetaTagsAdapter = {
 };
 
 // src/providers/source/adapters/svelte-seo.ts
+import { attrValueOf as attrValueOf2, attrTextOf as attrTextOf2 } from "@svelte-vitals/core";
 function findAttr3(attributes, name) {
   return attributes.find((a) => a?.type === "Attribute" && a.name === name);
 }
@@ -520,18 +363,18 @@ var svelteSeoAdapter = {
     const attrs = use.attributes;
     const title = findAttr3(attrs, "title");
     if (title) {
-      const value = attrValueOf(title);
-      const text = value === "static" ? attrTextOf(title) : void 0;
+      const value = attrValueOf2(title);
+      const text = value === "static" ? attrTextOf2(title) : void 0;
       tags.push({ kind: "title", value, ...text !== void 0 ? { text } : {} });
     }
     const description = findAttr3(attrs, "description");
     if (description) {
-      const value = attrValueOf(description);
-      const text = value === "static" ? attrTextOf(description) : void 0;
+      const value = attrValueOf2(description);
+      const text = value === "static" ? attrTextOf2(description) : void 0;
       tags.push({ kind: "meta", name: "description", value, ...text !== void 0 ? { text } : {} });
     }
     const canonical = findAttr3(attrs, "canonical");
-    if (canonical) tags.push({ kind: "link", rel: "canonical", value: attrValueOf(canonical) });
+    if (canonical) tags.push({ kind: "link", rel: "canonical", value: attrValueOf2(canonical) });
     const openGraph = findAttr3(attrs, "openGraph");
     const broad = use.hasSpread || Boolean(openGraph);
     return { tags, broad };
@@ -735,6 +578,7 @@ async function collectRoutes(rt, cwd, config = defaultConfig) {
 }
 
 // src/providers/source/components.ts
+import { parseComponentFacts } from "@svelte-vitals/core";
 async function collectComponentFacts(rt, cwd) {
   const files = await rt.glob("src/**/*.svelte", cwd);
   return Promise.all(
@@ -743,7 +587,19 @@ 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: [],
+          suppressions: []
+        };
       }
     })
   );
@@ -789,6 +645,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 +727,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 +767,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 +789,7 @@ async function run(opts = {}) {
       rules: opts.rules
     });
   } catch (err) {
+    spinner.stop();
     if (err instanceof ProjectError) {
       errorLog(err.message);
       return 2;
@@ -863,10 +797,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 +845,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 +870,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-NLQZ3CMZ.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.18.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,13 +39,16 @@
     "dist"
   ],
   "dependencies": {
+    "@clack/prompts": "^1.6.0",
+    "magicast": "^0.5.3",
     "mri": "^1.2.0",
-    "svelte": "^5.56.3",
+    "smol-toml": "^1.7.0",
+    "svelte": "^5.56.4",
     "tinyglobby": "^0.2.17",
-    "@svelte-vitals/core": "0.16.0"
+    "@svelte-vitals/core": "0.19.0"
   },
   "devDependencies": {
-    "@types/node": "^24.7.0"
+    "@types/node": "^24.13.2"
   },
   "scripts": {
     "build": "tsup",