svelte-vitals 0.18.0 → 0.19.0

package/dist/bin.js

@@ -6,12 +6,55 @@ import {
   knownRuleIds,
   readPackageVersion,
   run
-} from "./chunk-NLQZ3CMZ.js";
+} from "./chunk-ZE3M3T6U.js";
 
 // src/bin.ts
 import mri2 from "mri";
 
 // src/resolve-args.ts
+var CATEGORIES = ["seo", "performance", "correctness", "security", "architecture"];
+function parseWeights(raw, errors) {
+  if (typeof raw !== "string" || raw.trim() === "") return void 0;
+  const weights = {};
+  const unknownCategories = [];
+  const invalidValues = [];
+  for (const pair of raw.split(",").map((s) => s.trim()).filter(Boolean)) {
+    const eq = pair.indexOf("=");
+    if (eq === -1) {
+      invalidValues.push(pair);
+      continue;
+    }
+    const category = pair.slice(0, eq).trim().toLowerCase();
+    const valueRaw = pair.slice(eq + 1).trim();
+    if (!CATEGORIES.includes(category)) {
+      unknownCategories.push(category);
+      continue;
+    }
+    if (valueRaw === "") {
+      invalidValues.push(pair);
+      continue;
+    }
+    const value = Number(valueRaw);
+    if (!Number.isFinite(value) || value < 0) {
+      invalidValues.push(pair);
+      continue;
+    }
+    weights[category] = value;
+  }
+  if (unknownCategories.length > 0) {
+    errors.push(`svelte-vitals: unknown category(ies) in --weights: ${unknownCategories.join(", ")}`);
+    errors.push(`Known categories: ${CATEGORIES.join(", ")}`);
+  }
+  if (invalidValues.length > 0) {
+    errors.push(
+      `svelte-vitals: invalid --weights entry(ies): ${invalidValues.join(", ")}; expected category=number with a finite number >= 0.`
+    );
+  }
+  if (unknownCategories.length === 0 && invalidValues.length === 0 && Object.keys(weights).length === 0) {
+    errors.push("svelte-vitals: --weights was passed but contains no category=number pairs.");
+  }
+  return weights;
+}
 var toList = (v) => typeof v === "string" ? v.split(",").map((s) => s.trim()).filter(Boolean) : [];
 function resolveArgs(argv) {
   const warnings = [];
@@ -55,6 +98,9 @@ function resolveArgs(argv) {
     );
   }
   const failOn = argv["fail-on-warning"] ? "warning" : failOnValid ? failOnRaw : void 0;
+  const weights = parseWeights(argv.weights, errors);
+  const rulesConfig = buildRulesConfig(allow, ignore);
+  const rules = Object.keys(rulesConfig).length > 0 ? rulesConfig : void 0;
   if (errors.length > 0) return { options: null, warnings, errors };
   return {
     options: {
@@ -66,7 +112,8 @@ 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,
+      ...weights !== void 0 ? { weights } : {},
       ...diffBase !== void 0 ? { diffBase } : {},
       ...staged ? { staged } : {}
     },
@@ -639,10 +686,14 @@ 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
+  --weights <pairs>           Per-category Health weight overrides, e.g. seo=2,performance=1 (unlisted categories default to 1)
   --no-color                  Disable ANSI color in console output
   -h, --help                  Show this help
   -v, --version               Show version
 
+Config file:
+  svelte-vitals.config.{mjs,js,ts} in the analyzed directory; flags override it.
+
 Exit codes:
   0  no failing findings
   1  critical finding present (or --fail-on threshold reached)
@@ -667,7 +718,8 @@ async function main() {
       "ignore",
       "min-health",
       "out-file",
-      "diff"
+      "diff",
+      "weights"
     ]
   });
   if (argv.help) {

package/dist/{chunk-NLQZ3CMZ.js → chunk-ZE3M3T6U.js}

@@ -122,12 +122,145 @@ async function collectProjectFacts(rt, cwd) {
   };
 }
 
+// src/providers/source/adapters/svelte-meta-tags.ts
+import { attrValueOf, attrTextOf } from "@svelte-vitals/core";
+
+// src/providers/source/adapters/meta-object.ts
+function exprValue(node) {
+  if (!node) return "absent";
+  if (node.type === "Literal") {
+    if (typeof node.value === "string") return node.value.trim().length > 0 ? "static" : "absent";
+    return "static";
+  }
+  return "dynamic";
+}
+function resolveMetaObject(attr, keyMap) {
+  if (!attr) return { tags: [], opaque: false };
+  const expr = attr.value?.type === "ExpressionTag" ? attr.value.expression : void 0;
+  if (!expr || expr.type !== "ObjectExpression") return { tags: [], opaque: true };
+  const tags = [];
+  let opaque = false;
+  for (const prop of expr.properties ?? []) {
+    if (prop?.type !== "Property" || prop.computed) {
+      opaque = true;
+      continue;
+    }
+    const key = prop.key?.name ?? prop.key?.value;
+    const make = typeof key === "string" ? keyMap[key] : void 0;
+    if (make) tags.push(make(exprValue(prop.value)));
+  }
+  return { tags, opaque };
+}
+var OPEN_GRAPH_KEYS = {
+  title: (value) => ({ kind: "meta", property: "og:title", value }),
+  description: (value) => ({ kind: "meta", property: "og:description", value }),
+  url: (value) => ({ kind: "meta", property: "og:url", value }),
+  images: (value) => ({ kind: "meta", property: "og:image", value }),
+  type: (value) => ({ kind: "meta", property: "og:type", value })
+};
+var TWITTER_KEYS = {
+  cardType: (value) => ({ kind: "meta", name: "twitter:card", value }),
+  card: (value) => ({ kind: "meta", name: "twitter:card", value })
+};
+
+// src/providers/source/adapters/svelte-meta-tags.ts
+function findAttr(attributes, name) {
+  return attributes.find((a) => a?.type === "Attribute" && a.name === name);
+}
+var svelteMetaTagsAdapter = {
+  match(info) {
+    if (info.source === "svelte-meta-tags") return info.imported === "MetaTags";
+    if (info.source === "svelte-meta-tags/MetaTags.svelte") return info.imported === "default";
+    return false;
+  },
+  resolve(use) {
+    const tags = [];
+    const attrs = use.attributes;
+    const titleAttr = findAttr(attrs, "title");
+    const templateAttr = findAttr(attrs, "titleTemplate");
+    const title = titleAttr ?? templateAttr;
+    if (title) {
+      const value = attrValueOf(title);
+      const text = titleAttr && !templateAttr && value === "static" ? attrTextOf(titleAttr) : void 0;
+      tags.push({ kind: "title", value, ...text !== void 0 ? { text } : {} });
+    }
+    const description = findAttr(attrs, "description");
+    if (description) {
+      const value = attrValueOf(description);
+      const text = value === "static" ? attrTextOf(description) : void 0;
+      tags.push({ kind: "meta", name: "description", value, ...text !== void 0 ? { text } : {} });
+    }
+    const canonical = findAttr(attrs, "canonical");
+    if (canonical) tags.push({ kind: "link", rel: "canonical", value: attrValueOf(canonical) });
+    const robots = findAttr(attrs, "robots");
+    if (robots) tags.push({ kind: "meta", name: "robots", value: attrValueOf(robots) });
+    const og = resolveMetaObject(findAttr(attrs, "openGraph"), OPEN_GRAPH_KEYS);
+    const tw = resolveMetaObject(findAttr(attrs, "twitter"), TWITTER_KEYS);
+    tags.push(...og.tags, ...tw.tags);
+    const broad = use.hasSpread || og.opaque || tw.opaque;
+    return { tags, broad };
+  }
+};
+
+// src/providers/source/adapters/svelte-meta-tags-jsonld.ts
+var svelteMetaTagsJsonLdAdapter = {
+  match(info) {
+    if (info.source === "svelte-meta-tags") return info.imported === "JsonLd";
+    if (info.source === "svelte-meta-tags/JsonLd.svelte") return info.imported === "default";
+    return false;
+  },
+  resolve() {
+    const tags = [{ kind: "jsonld", value: "dynamic" }];
+    return { tags, broad: false };
+  }
+};
+
+// src/providers/source/adapters/svelte-seo.ts
+import { attrValueOf as attrValueOf2, attrTextOf as attrTextOf2 } from "@svelte-vitals/core";
+function findAttr2(attributes, name) {
+  return attributes.find((a) => a?.type === "Attribute" && a.name === name);
+}
+var svelteSeoAdapter = {
+  match(info) {
+    return info.source === "svelte-seo" && info.imported === "default";
+  },
+  resolve(use) {
+    const tags = [];
+    const attrs = use.attributes;
+    const title = findAttr2(attrs, "title");
+    if (title) {
+      const value = attrValueOf2(title);
+      const text = value === "static" ? attrTextOf2(title) : void 0;
+      tags.push({ kind: "title", value, ...text !== void 0 ? { text } : {} });
+    }
+    const description = findAttr2(attrs, "description");
+    if (description) {
+      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 = findAttr2(attrs, "canonical");
+    if (canonical) tags.push({ kind: "link", rel: "canonical", value: attrValueOf2(canonical) });
+    const og = resolveMetaObject(findAttr2(attrs, "openGraph"), OPEN_GRAPH_KEYS);
+    const tw = resolveMetaObject(findAttr2(attrs, "twitter"), TWITTER_KEYS);
+    tags.push(...og.tags, ...tw.tags);
+    const broad = use.hasSpread || og.opaque || tw.opaque;
+    return { tags, broad };
+  }
+};
+
+// src/providers/source/adapters/index.ts
+var builtinAdapters = [svelteMetaTagsAdapter, svelteMetaTagsJsonLdAdapter, svelteSeoAdapter];
+function findAdapter(info) {
+  return builtinAdapters.find((adapter) => adapter.match(info));
+}
+
 // src/providers/source/parse.ts
 import { parse } from "svelte/compiler";
 import {
   CHILD_NODE_KEYS,
   lineOf,
-  findAttr,
+  findAttr as findAttr3,
   valueFromNodes,
   textFromNodes,
   attrText,
@@ -203,9 +336,9 @@ function tagsFromHead(head) {
       });
     } else if (node.name === "link") {
       const rel = attrText(node.attributes, "rel");
-      const hasAs = findAttr(node.attributes, "as") !== void 0;
+      const hasAs = findAttr3(node.attributes, "as") !== void 0;
       const asLiteral = attrText(node.attributes, "as");
-      const hasCrossorigin = findAttr(node.attributes, "crossorigin") !== void 0;
+      const hasCrossorigin = findAttr3(node.attributes, "crossorigin") !== void 0;
       const hreflang = attrText(node.attributes, "hreflang");
       const href = attrText(node.attributes, "href");
       tags.push({
@@ -228,7 +361,7 @@ function tagsFromHead(head) {
       } else {
         const src = attrText(node.attributes, "src");
         if (src) {
-          const blocking = findAttr(node.attributes, "defer") === void 0 && findAttr(node.attributes, "async") === void 0 && type !== "module";
+          const blocking = findAttr3(node.attributes, "defer") === void 0 && findAttr3(node.attributes, "async") === void 0 && type !== "module";
           tags.push({ kind: "script", value: "static", href: src, ...blocking ? { blocking: true } : {} });
         }
       }
@@ -264,13 +397,13 @@ function collectImages(node, source, acc) {
     const attrs = node.attributes ?? [];
     const hasSpread = attrs.some((a) => a?.type === "SpreadAttribute");
     acc.push({
-      hasWidth: hasSpread || Boolean(findAttr(attrs, "width")),
-      hasHeight: hasSpread || Boolean(findAttr(attrs, "height")),
-      hasLoading: hasSpread || Boolean(findAttr(attrs, "loading")),
-      hasAlt: hasSpread || Boolean(findAttr(attrs, "alt")),
+      hasWidth: hasSpread || Boolean(findAttr3(attrs, "width")),
+      hasHeight: hasSpread || Boolean(findAttr3(attrs, "height")),
+      hasLoading: hasSpread || Boolean(findAttr3(attrs, "loading")),
+      hasAlt: hasSpread || Boolean(findAttr3(attrs, "alt")),
       // A literal loading="lazy" only — a spread or dynamic loading={…} must not be flagged.
       lazy: attrText(attrs, "loading") === "lazy",
-      hasSrcset: hasSpread || Boolean(findAttr(attrs, "srcset")),
+      hasSrcset: hasSpread || Boolean(findAttr3(attrs, "srcset")),
       line: lineOf(source, node.start)
     });
   }
@@ -311,90 +444,27 @@ function parseFile(source, filename) {
   };
 }
 
-// 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);
-}
-var svelteMetaTagsAdapter = {
-  match(info) {
-    if (info.source === "svelte-meta-tags") return info.imported === "MetaTags";
-    if (info.source === "svelte-meta-tags/MetaTags.svelte") return info.imported === "default";
-    return false;
-  },
-  resolve(use) {
-    const tags = [];
-    const attrs = use.attributes;
-    const titleAttr = findAttr2(attrs, "title");
-    const templateAttr = findAttr2(attrs, "titleTemplate");
-    const title = titleAttr ?? templateAttr;
-    if (title) {
-      const value = attrValueOf(title);
-      const text = titleAttr && !templateAttr && value === "static" ? attrTextOf(titleAttr) : void 0;
-      tags.push({ kind: "title", value, ...text !== void 0 ? { text } : {} });
-    }
-    const description = findAttr2(attrs, "description");
-    if (description) {
-      const value = attrValueOf(description);
-      const text = value === "static" ? attrTextOf(description) : void 0;
-      tags.push({ kind: "meta", name: "description", value, ...text !== void 0 ? { text } : {} });
-    }
-    const canonical = findAttr2(attrs, "canonical");
-    if (canonical) tags.push({ kind: "link", rel: "canonical", value: attrValueOf(canonical) });
-    const robots = findAttr2(attrs, "robots");
-    if (robots) tags.push({ kind: "meta", name: "robots", value: attrValueOf(robots) });
-    const openGraph = findAttr2(attrs, "openGraph");
-    const broad = use.hasSpread || Boolean(openGraph);
-    return { tags, broad };
-  }
-};
-
-// 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);
-}
-var svelteSeoAdapter = {
-  match(info) {
-    return info.source === "svelte-seo" && info.imported === "default";
-  },
-  resolve(use) {
-    const tags = [];
-    const attrs = use.attributes;
-    const title = findAttr3(attrs, "title");
-    if (title) {
-      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 = 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: attrValueOf2(canonical) });
-    const openGraph = findAttr3(attrs, "openGraph");
-    const broad = use.hasSpread || Boolean(openGraph);
-    return { tags, broad };
+// src/providers/source/resolve.ts
+function readAndParse(rt, cwd, rel, cache) {
+  let hit = cache.get(rel);
+  if (!hit) {
+    hit = rt.readFile(rt.join(cwd, rel)).then((source) => parseFile(source, rel));
+    cache.set(rel, hit);
   }
-};
-
-// src/providers/source/adapters/index.ts
-var builtinAdapters = [svelteMetaTagsAdapter, svelteSeoAdapter];
-function findAdapter(info) {
-  return builtinAdapters.find((adapter) => adapter.match(info));
+  return hit;
 }
-
-// src/providers/source/resolve.ts
 var BROAD_KINDS = [
   { kind: "title", value: "dynamic" },
   { kind: "meta", name: "description", value: "dynamic" },
   { kind: "link", rel: "canonical", value: "dynamic" },
   { kind: "meta", property: "og:title", value: "dynamic" },
+  { kind: "meta", property: "og:description", value: "dynamic" },
   { kind: "meta", property: "og:image", value: "dynamic" },
+  { kind: "meta", property: "og:url", value: "dynamic" },
+  { kind: "meta", name: "twitter:card", value: "dynamic" },
   { kind: "meta", name: "robots", value: "dynamic" }
+  // jsonld is intentionally omitted: structured data is a distinct concern, not a
+  // meta-tag family a broad meta source implies (JsonLd has its own adapter).
 ];
 function tagKey(tag) {
   switch (tag.kind) {
@@ -431,7 +501,7 @@ function resolveComponentPath(source, fromFileRel) {
   if (/\.[^/]+$/.test(path)) return void 0;
   return `${path}.svelte`;
 }
-async function resolveFileTags(rt, cwd, fileRel, parsed, config, depth, visited) {
+async function resolveFileTags(rt, cwd, fileRel, parsed, config, depth, visited, cache = /* @__PURE__ */ new Map()) {
   const tags = [...parsed.headTags];
   let broad = false;
   for (const use of parsed.components) {
@@ -451,9 +521,9 @@ async function resolveFileTags(rt, cwd, fileRel, parsed, config, depth, visited)
     if (childRel && depth > 0 && !visited.has(childRel)) {
       const abs = rt.join(cwd, childRel);
       if (await rt.exists(abs)) {
-        const childParsed = parseFile(await rt.readFile(abs), childRel);
+        const childParsed = await readAndParse(rt, cwd, childRel, cache);
         const childVisited = new Set(visited).add(childRel);
-        const child = await resolveFileTags(rt, cwd, childRel, childParsed, config, depth - 1, childVisited);
+        const child = await resolveFileTags(rt, cwd, childRel, childParsed, config, depth - 1, childVisited, cache);
         tags.push(...child.tags);
         broad = broad || child.broad;
       }
@@ -528,7 +598,7 @@ function chainFiles(pageRel, layouts) {
   }
   return [...chain.map((rel) => ({ rel, isPage: false })), { rel: pageRel, isPage: true }];
 }
-async function resolveRoute(rt, cwd, pageRel, config, layouts) {
+async function resolveRoute(rt, cwd, pageRel, config, layouts, cache) {
   const files = chainFiles(pageRel, layouts);
   const composed = /* @__PURE__ */ new Map();
   let broadOwn = false;
@@ -536,15 +606,14 @@ async function resolveRoute(rt, cwd, pageRel, config, layouts) {
   const images = [];
   const headings = [];
   for (const { rel, isPage } of files) {
-    const source = await rt.readFile(rt.join(cwd, rel));
-    const parsed = parseFile(source, rel);
+    const parsed = await readAndParse(rt, cwd, rel, cache);
     for (const img of parsed.images) {
       images.push({ ...img, file: rel });
     }
     for (const heading of parsed.headings) {
       headings.push({ ...heading, file: rel });
     }
-    const resolved = await resolveFileTags(rt, cwd, rel, parsed, config, MAX_DEPTH, /* @__PURE__ */ new Set([rel]));
+    const resolved = await resolveFileTags(rt, cwd, rel, parsed, config, MAX_DEPTH, /* @__PURE__ */ new Set([rel]), cache);
     for (const tag of resolved.tags) {
       composed.set(tagKey(tag), { ...tag, presence: isPage ? "own" : "inherited", file: rel });
     }
@@ -569,7 +638,8 @@ async function resolveRoute(rt, cwd, pageRel, config, layouts) {
 }
 async function collectRoutes(rt, cwd, config = defaultConfig) {
   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)));
+  const cache = /* @__PURE__ */ new Map();
+  const facts = await Promise.all(pages.map((page) => resolveRoute(rt, cwd, page, config, layouts, cache)));
   return {
     heads: facts.map((f) => f.head),
     images: facts.map((f) => f.images),
@@ -578,32 +648,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(
-    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: [],
-          suppressions: []
-        };
-      }
-    })
-  );
-}
+import { collectComponentFacts } from "@svelte-vitals/core";
 
 // src/version.ts
 import { readFileSync } from "fs";
@@ -652,8 +697,8 @@ function git(args, cwd) {
 }
 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),
+    const files = opts.staged ? git(["diff", "--name-only", "--relative", "--cached", "--diff-filter=d"], cwd) : [
+      ...git(["diff", "--name-only", "--relative", "--diff-filter=d", "--merge-base", opts.base ?? "HEAD"], cwd),
       ...git(["ls-files", "--others", "--exclude-standard"], cwd)
       // untracked / new files
     ];
@@ -708,6 +753,11 @@ function startSpinner(text, opts) {
   };
 }
 
+// src/config-file.ts
+import { existsSync } from "fs";
+import { join as join2 } from "path";
+import { pathToFileURL } from "url";
+
 // src/rules-config.ts
 import { allRules } from "@svelte-vitals/core";
 var KNOWN_IDS = new Set(allRules.map((r) => r.id));
@@ -726,7 +776,106 @@ function buildRulesConfig(allow, ignore) {
   return rules;
 }
 
+// src/config-file.ts
+var CONFIG_FILENAMES = ["svelte-vitals.config.mjs", "svelte-vitals.config.js", "svelte-vitals.config.ts"];
+var CATEGORIES = ["seo", "performance", "correctness", "security", "architecture"];
+var TREAT_DYNAMIC_AS_VALUES = ["pass", "warn", "fail"];
+var FAIL_ON_VALUES = ["critical", "warning", "info"];
+var KNOWN_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set(["treatDynamicAs", "metaComponents", "rules", "failOn", "weights"]);
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isMissingExtensionLoaderError(err) {
+  return err instanceof Error && ("code" in err && err.code === "ERR_UNKNOWN_FILE_EXTENSION" || /Unknown file extension/.test(err.message));
+}
+function validateConfigFile(raw, path) {
+  const warnings = [];
+  const config = {};
+  for (const key of Object.keys(raw)) {
+    if (!KNOWN_TOP_LEVEL_KEYS.has(key)) {
+      warnings.push(`${path}: unknown config key '${key}' ignored.`);
+    }
+  }
+  if (raw.treatDynamicAs !== void 0) {
+    if (TREAT_DYNAMIC_AS_VALUES.includes(raw.treatDynamicAs)) {
+      config.treatDynamicAs = raw.treatDynamicAs;
+    } else {
+      warnings.push(
+        `${path}: unknown treatDynamicAs '${String(raw.treatDynamicAs)}'; expected pass|warn|fail. Ignoring.`
+      );
+    }
+  }
+  if (raw.failOn !== void 0) {
+    if (FAIL_ON_VALUES.includes(raw.failOn)) {
+      config.failOn = raw.failOn;
+    } else {
+      warnings.push(`${path}: unknown failOn '${String(raw.failOn)}'; expected critical|warning|info. Ignoring.`);
+    }
+  }
+  if (raw.metaComponents !== void 0) {
+    if (Array.isArray(raw.metaComponents) && raw.metaComponents.every((c) => typeof c === "string")) {
+      config.metaComponents = raw.metaComponents;
+    } else {
+      warnings.push(`${path}: metaComponents must be an array of strings. Ignoring.`);
+    }
+  }
+  if (raw.rules !== void 0) {
+    if (!isPlainObject(raw.rules)) {
+      throw new Error(`${path}: rules must be an object of rule-id \u2192 setting.`);
+    }
+    const rules = raw.rules;
+    const unknown = findUnknownRuleIds(Object.keys(rules));
+    if (unknown.length > 0) {
+      throw new Error(
+        `${path}: unknown rule id(s) in rules: ${unknown.join(", ")}. Known rule ids: ${knownRuleIds().join(", ")}`
+      );
+    }
+    config.rules = rules;
+  }
+  if (raw.weights !== void 0) {
+    if (!isPlainObject(raw.weights)) {
+      throw new Error(`${path}: weights must be an object of category \u2192 number.`);
+    }
+    const weights = {};
+    for (const [rawCat, w] of Object.entries(raw.weights)) {
+      const cat = rawCat.toLowerCase();
+      if (!CATEGORIES.includes(cat)) {
+        throw new Error(`${path}: unknown category '${rawCat}' in weights. Known categories: ${CATEGORIES.join(", ")}`);
+      }
+      if (typeof w !== "number" || !Number.isFinite(w) || w < 0) {
+        throw new Error(`${path}: invalid weight for '${cat}': ${String(w)}; expected a finite number >= 0.`);
+      }
+      weights[cat] = w;
+    }
+    config.weights = weights;
+  }
+  return { config, warnings };
+}
+async function loadConfigFile(cwd) {
+  const found = CONFIG_FILENAMES.map((name) => join2(cwd, name)).find((path) => existsSync(path));
+  if (!found) return void 0;
+  let mod;
+  try {
+    mod = await import(pathToFileURL(found).href);
+  } catch (err) {
+    if (found.endsWith(".ts") && isMissingExtensionLoaderError(err)) {
+      throw new Error(
+        `could not load ${found} \u2014 this Node runtime does not support TypeScript config files without a flag. Native type-stripping is unflagged from Node 22.18 / 23.6+: upgrade Node to 22.18+, re-run with --experimental-strip-types, or rename the file to .mjs/.js.`,
+        { cause: err }
+      );
+    }
+    throw err;
+  }
+  if (!isPlainObject(mod.default)) {
+    throw new Error(
+      `${found} must have a default export that is a plain object (e.g. \`export default defineConfig({...})\` or a plain object literal).`
+    );
+  }
+  return validateConfigFile(mod.default, found);
+}
+
 // src/index.ts
+import { defineConfig as defineConfig2 } from "@svelte-vitals/core";
 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 });
 }
@@ -739,11 +888,16 @@ function routeMatcher(glob) {
 async function analyzeProject(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
   const rt = createNodeRuntime();
+  const loaded = await loadConfigFile(cwd);
+  const file = loaded?.config;
+  const warnings = loaded?.warnings ?? [];
+  const weights = opts.weights ?? file?.weights;
   const config = defineConfig({
-    treatDynamicAs: opts.treatDynamicAs ?? "pass",
-    metaComponents: opts.metaComponents ?? [],
-    rules: opts.rules ?? {},
-    failOn: opts.failOn ?? "critical"
+    treatDynamicAs: opts.treatDynamicAs ?? file?.treatDynamicAs ?? "pass",
+    metaComponents: opts.metaComponents ?? file?.metaComponents ?? [],
+    rules: opts.rules ?? file?.rules ?? {},
+    failOn: opts.failOn ?? file?.failOn ?? "critical",
+    ...weights !== void 0 ? { weights } : {}
   });
   await detectProject(rt, cwd);
   const matches = routeMatcher(opts.route);
@@ -758,7 +912,7 @@ async function analyzeProject(opts = {}) {
     await runRules(rules, { heads, images, headings, components, project, config }),
     config
   );
-  return { results, config, version: readPackageVersion() };
+  return { results, config, version: readPackageVersion(), warnings };
 }
 async function run(opts = {}) {
   const log = opts.log ?? ((line) => console.log(line));
@@ -786,7 +940,8 @@ async function run(opts = {}) {
       treatDynamicAs: opts.treatDynamicAs,
       route: opts.route,
       failOn: opts.failOn,
-      rules: opts.rules
+      rules: opts.rules,
+      weights: opts.weights
     });
   } catch (err) {
     spinner.stop();
@@ -798,6 +953,7 @@ async function run(opts = {}) {
     return 2;
   }
   spinner.stop();
+  for (const w of analysis.warnings) errorLog(`svelte-vitals: ${w}`);
   try {
     const { config, version } = analysis;
     let results = analysis.results;
@@ -870,8 +1026,10 @@ export {
   findUnknownRuleIds,
   knownRuleIds,
   buildRulesConfig,
+  loadConfigFile,
   spinnerEnabled,
   routeMatcher,
   analyzeProject,
-  run
+  run,
+  defineConfig2 as defineConfig
 };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { RuleSetting, Severity, Result, Config } from '@svelte-vitals/core';
+import { RuleSetting, Config, Severity, Category, Result } from '@svelte-vitals/core';
+export { defineConfig } from '@svelte-vitals/core';
 
 type ReporterName = 'console' | 'json' | 'agent' | 'sarif' | 'github' | 'html';
 
@@ -19,6 +20,31 @@ declare function knownRuleIds(): string[];
  */
 declare function buildRulesConfig(allow: string[], ignore: string[]): Record<string, RuleSetting>;
 
+/** Result of loading and validating a config file. */
+interface LoadedConfigFile {
+    /** The file's contents after validation; invalid optional fields are dropped (see `warnings`). */
+    config: Partial<Config>;
+    /** Non-fatal issues: unknown top-level keys, invalid enum values (the field is ignored). */
+    warnings: string[];
+}
+/**
+ * Find and load `svelte-vitals.config.{mjs,js,ts}` from `cwd` (only `cwd`, no
+ * upward search). Returns `undefined` when no candidate file exists.
+ *
+ * Loader mechanism (design doc §2): plain native `import()`. `.mjs`/`.js` always
+ * work (zero dependencies, no Node-version dependency). `.ts` depends on the host
+ * Node's TypeScript type-stripping support: unflagged in Node 23.6.0, backported
+ * to 22.18.0; on 22.13–22.17 (this repo's floor is >=22.13.0) it requires
+ * `--experimental-strip-types` and otherwise fails with
+ * `ERR_UNKNOWN_FILE_EXTENSION` — this is caught here and rethrown as a
+ * descriptive, actionable error instead of surfacing Node's raw error.
+ *
+ * Throws when: the file exists but has no usable default export; (`.ts` only)
+ * the host Node can't load TypeScript without a flag; or the loaded config
+ * fails validation (unknown rule ids in `rules`, invalid `weights` entries).
+ */
+declare function loadConfigFile(cwd: string): Promise<LoadedConfigFile | undefined>;
+
 interface RunOptions {
     cwd?: string;
     log?: (line: string) => void;
@@ -31,6 +57,8 @@ interface RunOptions {
     byRoute?: boolean;
     failOn?: Severity;
     rules?: Record<string, RuleSetting>;
+    /** Per-category weights for the combined Health score (flag > config file > default 1 each). */
+    weights?: Partial<Record<Category, number>>;
     /** Override process.env for reporter auto-detection (mainly useful in tests). */
     env?: NodeJS.ProcessEnv;
     /** Fail (exit 1) when the combined Health score is below this value (0–100). */
@@ -73,16 +101,26 @@ interface AnalyzeOptions {
     route?: string;
     failOn?: Severity;
     rules?: Record<string, RuleSetting>;
+    /** Per-category weights for the combined Health score (flag > config file > default 1 each). */
+    weights?: Partial<Record<Category, number>>;
 }
 interface AnalyzeResult {
     results: Result[];
     config: Config;
     version: string;
+    /** Non-fatal config-file issues (unknown top-level keys, invalid enum values). Empty when no config file or none found. */
+    warnings: string[];
 }
 /**
  * Run static-mode analysis and return the structured findings + resolved config.
- * Throws ProjectError when `cwd` is not a SvelteKit project. Shared by the CLI's
- * run() and by @svelte-vitals/mcp (issue #24).
+ * Throws ProjectError when `cwd` is not a SvelteKit project. Also throws when a
+ * `svelte-vitals.config.{mjs,js,ts}` file in `cwd` fails to load or fails
+ * validation (unknown rule ids in `rules`, invalid `weights` entries) — see
+ * `loadConfigFile`. Shared by the CLI's run() and by @svelte-vitals/mcp (issue #24).
+ *
+ * Config precedence is per field: an explicit option here wins, otherwise the
+ * config file's value is used, otherwise the built-in default (design doc
+ * 2026-07-05-config-file-design.md §3).
  */
 declare function analyzeProject(opts?: AnalyzeOptions): Promise<AnalyzeResult>;
 /**
@@ -91,4 +129,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, spinnerEnabled };
+export { type AnalyzeOptions, type AnalyzeResult, type LoadedConfigFile, ProjectError, type RunOptions, analyzeProject, buildRulesConfig, findUnknownRuleIds, knownRuleIds, loadConfigFile, routeMatcher, run, spinnerEnabled };

package/dist/index.js

@@ -2,18 +2,22 @@ import {
   ProjectError,
   analyzeProject,
   buildRulesConfig,
+  defineConfig,
   findUnknownRuleIds,
   knownRuleIds,
+  loadConfigFile,
   routeMatcher,
   run,
   spinnerEnabled
-} from "./chunk-NLQZ3CMZ.js";
+} from "./chunk-ZE3M3T6U.js";
 export {
   ProjectError,
   analyzeProject,
   buildRulesConfig,
+  defineConfig,
   findUnknownRuleIds,
   knownRuleIds,
+  loadConfigFile,
   routeMatcher,
   run,
   spinnerEnabled

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-vitals",
-  "version": "0.18.0",
+  "version": "0.19.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.20.8"
+    "node": ">=22.13.0"
   },
   "sideEffects": false,
   "bin": {
@@ -39,13 +39,13 @@
     "dist"
   ],
   "dependencies": {
-    "@clack/prompts": "^1.6.0",
+    "@clack/prompts": "^1.7.0",
     "magicast": "^0.5.3",
     "mri": "^1.2.0",
     "smol-toml": "^1.7.0",
     "svelte": "^5.56.4",
     "tinyglobby": "^0.2.17",
-    "@svelte-vitals/core": "0.19.0"
+    "@svelte-vitals/core": "0.20.0"
   },
   "devDependencies": {
     "@types/node": "^24.13.2"