@svelte-vitals/core 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -47,6 +47,10 @@ interface Result {
     docsUrl?: string;
     /** Agent-actionable remediation (issue #18). */
     fix?: Fix;
+    /** Vitals category this finding belongs to (default 'seo' when absent). */
+    category?: Category;
+    /** 1-based source line for element-level findings (e.g. a specific <img>). */
+    line?: number;
 }
 type Scope = 'route' | 'project';
 type Category = 'seo' | 'performance' | 'a11y' | 'maintainability';
@@ -62,6 +66,8 @@ interface Config {
     rules: Record<string, RuleSetting>;
     /** Minimum severity that fails the run / CI (design §6). */
     failOn: Severity;
+    /** Per-category weights for the combined Health score (default: equal, 1 each) (#10). */
+    weights?: Partial<Record<Category, number>>;
 }
 declare const defaultConfig: Config;
 /** Merge user config over defaults. Identity helper for config files (design §6). */
@@ -127,6 +133,26 @@ interface HeadProvider {
     collect(rt: Runtime, cwd: string, config?: Config): Promise<ResolvedHead[]>;
 }
 
+/**
+ * A normalized <img> occurrence — the mode-independent boundary for Performance
+ * rules (mirrors head.ts). Attribute presence only: a dynamically-bound attribute
+ * (width={w}) still counts as present, so dynamic values are never flagged.
+ */
+interface ImageInfo {
+    hasWidth: boolean;
+    hasHeight: boolean;
+    hasLoading: boolean;
+    /** 1-based source line, or 0 if unknown. */
+    line: number;
+    /** Source file the <img> came from. */
+    file: string;
+}
+/** Resolved <img> elements for a single route (page + layout chain). */
+interface ResolvedImages {
+    route: string;
+    images: ImageInfo[];
+}
+
 /**
  * Source-file locations that satisfy the project-scope rules, shared by every
  * mode so the static (CLI) and rendered (plugin) collectors never drift. This
@@ -140,6 +166,8 @@ declare const SITEMAP_SOURCE_PATHS: readonly ["static/sitemap.xml", "src/routes/
 /** Input given to every rule. Mode-independent: rules see only ResolvedHead[] (design §8, §10). */
 interface RuleContext {
     heads: ResolvedHead[];
+    /** Per-route <img> elements for Performance rules (absent in modes that don't collect them). */
+    images?: ResolvedImages[];
     project: Project;
     config: Config;
 }
@@ -198,6 +226,9 @@ declare const seo006Robots: Rule;
 declare const seo007Sitemap: Rule;
 declare const seo009HtmlLang: Rule;
 
+declare const perf001ImageDimensions: Rule;
+declare const perf002ImageLoading: Rule;
+
 declare const allRules: Rule[];
 
 interface RuleInfo {
@@ -229,6 +260,21 @@ interface HeadTagRuleOptions {
 /** Build a route-scope rule asserting the presence of a single head tag (design §11). */
 declare function headTagRule(opts: HeadTagRuleOptions): Rule;
 
+interface ImageRuleOptions {
+    id: string;
+    title: string;
+    severity: Severity;
+    /** Noun phrase for messages, e.g. '<img> width/height'. */
+    label: string;
+    recommendation: string;
+    rationale: string;
+    fix?: Fix;
+    /** Returns true when the image satisfies the rule (passes). */
+    ok: (img: ImageInfo) => boolean;
+}
+/** Build a route-scoped Performance rule that checks each <img> against `ok` (issue #10). */
+declare function imageRule(opts: ImageRuleOptions): Rule;
+
 interface Summary {
     critical: number;
     warning: number;
@@ -274,15 +320,28 @@ interface ScoreOptions {
 }
 /** Compute the headline score and its breakdown (design §12). */
 declare function computeScore(results: Result[], config: Config, options?: ScoreOptions): ScoreResult;
+/** Compute an independent score per category present in `results` (issue #10). */
+declare function scoresByCategory(results: Result[], config: Config): Partial<Record<Category, ScoreResult>>;
+interface HealthResult {
+    /** Weighted overall score across present categories (0–100). */
+    health: number;
+    categories: Partial<Record<Category, ScoreResult>>;
+    /** Effective weight used per present category. */
+    weights: Partial<Record<Category, number>>;
+}
+/** Combined weighted Health score over the categories present in `results` (#10). */
+declare function computeHealth(results: Result[], config: Config): HealthResult;
 
 declare function issueOf(result: Result): {
     fix?: Fix | undefined;
     docsUrl?: string | undefined;
+    recommendation: string | undefined;
+    line?: number | undefined;
     id: string;
+    category: Category;
     title: string;
     detection: Detection;
     location: string | undefined;
-    recommendation: string | undefined;
 };
 type JsonIssue = ReturnType<typeof issueOf> & {
     severity: ReturnType<typeof effectiveSeverity>;
@@ -290,7 +349,11 @@ type JsonIssue = ReturnType<typeof issueOf> & {
 interface JsonReport {
     version: string;
     score: number;
-    scoreModel: ScoreModel;
+    weights: Partial<Record<Category, number>>;
+    categories: Record<string, {
+        score: number;
+        scoreModel: ScoreModel;
+    }>;
     summary: Summary;
     routes: Array<{
         route: string;
@@ -327,4 +390,4 @@ declare function selectRules(rules: Rule[], config: Config): Rule[];
 /** Apply per-rule severity overrides to results (design §6). */
 declare function applyRuleSeverities(results: Result[], config: Config): Result[];
 
-export { type Category, type Classification, type Config, type ConsoleReportOptions, type Detection, type Fix, type HeadProvider, type HeadTag, type JsonReport, type Presence, type Project, ROBOTS_SOURCE_PATHS, type ResolvedHead, type Result, type Rule, type RuleContext, type RuleInfo, type RuleSetting, type Runtime, SITEMAP_SOURCE_PATHS, type Scope, type ScoreModel, type ScoreOptions, type ScoreResult, type Severity, type Summary, type TreatDynamicAs, type Value, allRules, applyRuleSeverities, buildJsonReport, classify, computeScore, defaultConfig, defaultProject, defineConfig, docsUrlFor, effectiveSeverity, explainRule, formatAgentReport, formatConsoleReport, formatGithubReport, formatJsonReport, formatSarifReport, hasFailureAtOrAbove, headTagRule, isPenalized, runRules, selectRules, seo001Title, seo002Description, seo003Canonical, seo004OgImage, seo005OgTitle, seo006Robots, seo007Sitemap, seo008JsonLd, seo009HtmlLang, summarize };
+export { type Category, type Classification, type Config, type ConsoleReportOptions, type Detection, type Fix, type HeadProvider, type HeadTag, type HealthResult, type ImageInfo, type JsonReport, type Presence, type Project, ROBOTS_SOURCE_PATHS, type ResolvedHead, type ResolvedImages, type Result, type Rule, type RuleContext, type RuleInfo, type RuleSetting, type Runtime, SITEMAP_SOURCE_PATHS, type Scope, type ScoreModel, type ScoreOptions, type ScoreResult, type Severity, type Summary, type TreatDynamicAs, type Value, allRules, applyRuleSeverities, buildJsonReport, classify, computeHealth, computeScore, defaultConfig, defaultProject, defineConfig, docsUrlFor, effectiveSeverity, explainRule, formatAgentReport, formatConsoleReport, formatGithubReport, formatJsonReport, formatSarifReport, hasFailureAtOrAbove, headTagRule, imageRule, isPenalized, perf001ImageDimensions, perf002ImageLoading, runRules, scoresByCategory, selectRules, seo001Title, seo002Description, seo003Canonical, seo004OgImage, seo005OgTitle, seo006Robots, seo007Sitemap, seo008JsonLd, seo009HtmlLang, summarize };

package/dist/index.js

@@ -74,6 +74,7 @@ var seo001Title = {
       const detection = detectTitle(head);
       return {
         id: "SEO001",
+        category: "seo",
         severity: "critical",
         detection,
         route: head.route,
@@ -108,6 +109,7 @@ function headTagRule(opts) {
         const message = detection.presence === "none" ? `Missing ${opts.label}` : detection.value === "absent" ? `Empty ${opts.label}` : opts.label;
         return {
           id: opts.id,
+          category: "seo",
           severity: opts.severity,
           detection,
           route: head.route,
@@ -220,6 +222,7 @@ var seo006Robots = {
     return [
       {
         id: "SEO006",
+        category: "seo",
         severity: "warning",
         detection,
         message: ctx.project.hasRobotsTxt ? "robots.txt" : "Missing robots.txt",
@@ -248,6 +251,7 @@ var seo007Sitemap = {
     return [
       {
         id: "SEO007",
+        category: "seo",
         severity: "warning",
         detection,
         message: ctx.project.hasSitemap ? "sitemap.xml" : "Missing sitemap.xml",
@@ -277,6 +281,7 @@ var seo009HtmlLang = {
     return [
       {
         id: "SEO009",
+        category: "seo",
         severity: "warning",
         detection,
         message,
@@ -288,6 +293,86 @@ var seo009HtmlLang = {
   }
 };
 
+// src/rules/perf/image-rule.ts
+function imageRule(opts) {
+  const docsUrl = docsUrlFor(opts.id);
+  return {
+    id: opts.id,
+    title: opts.title,
+    category: "performance",
+    severity: opts.severity,
+    scope: "route",
+    rationale: opts.rationale,
+    ...opts.fix ? { fix: opts.fix } : {},
+    async check(ctx) {
+      const out = [];
+      for (const route of ctx.images ?? []) {
+        if (route.images.length === 0) continue;
+        const bad = route.images.filter((img) => !opts.ok(img));
+        if (bad.length === 0) {
+          out.push({
+            id: opts.id,
+            category: "performance",
+            severity: opts.severity,
+            detection: { presence: "own", value: "static" },
+            route: route.route,
+            message: opts.label,
+            recommendation: opts.recommendation,
+            docsUrl
+          });
+          continue;
+        }
+        for (const img of bad) {
+          out.push({
+            id: opts.id,
+            category: "performance",
+            severity: opts.severity,
+            detection: { presence: "none", value: "absent" },
+            route: route.route,
+            location: img.file,
+            ...img.line > 0 ? { line: img.line } : {},
+            message: `Missing ${opts.label}`,
+            recommendation: opts.recommendation,
+            docsUrl,
+            ...opts.fix ? { fix: { ...opts.fix } } : {}
+          });
+        }
+      }
+      return out;
+    }
+  };
+}
+
+// src/rules/perf/images.ts
+var perf001ImageDimensions = imageRule({
+  id: "PERF001",
+  title: "Image dimensions",
+  severity: "warning",
+  label: "<img> width/height",
+  recommendation: "Set explicit width and height on <img> to reserve space and avoid layout shift (CLS).",
+  rationale: "An <img> without explicit width and height triggers layout shift (CLS) as it loads, hurting Core Web Vitals and visual stability.",
+  fix: {
+    description: "Add explicit width and height attributes to the <img>.",
+    snippet: '<img src="/hero.jpg" width="1200" height="630" alt="\u2026" />',
+    lang: "svelte"
+  },
+  ok: (img) => img.hasWidth && img.hasHeight
+});
+var perf002ImageLoading = imageRule({
+  id: "PERF002",
+  title: "Image loading hint",
+  severity: "info",
+  label: "<img> loading attribute",
+  recommendation: 'Set loading="lazy" for offscreen images; keep the LCP image eager (consider fetchpriority="high").',
+  rationale: "A loading attribute lets the browser defer offscreen images; without it images load eagerly and can delay more important content. Static analysis cannot tell which image is the LCP, so this is advisory.",
+  fix: {
+    description: 'Add loading="lazy" to offscreen <img> elements (leave the LCP/hero image eager).',
+    snippet: '<img src="/thumb.jpg" width="320" height="240" loading="lazy" alt="\u2026" />',
+    lang: "svelte"
+  },
+  ok: (img) => img.hasLoading
+});
+
 // src/rules/index.ts
 var allRules = [
   seo001Title,
@@ -298,7 +383,9 @@ var allRules = [
   seo006Robots,
   seo007Sitemap,
   seo008JsonLd,
-  seo009HtmlLang
+  seo009HtmlLang,
+  perf001ImageDimensions,
+  perf002ImageLoading
 ];
 function explainRule(id) {
   const target = id.toUpperCase();
@@ -391,6 +478,39 @@ function computeScore(results, config, options = {}) {
   const score = capBinds ? CRITICAL_CAP : uncapped;
   return { score: clamp(score), scoreModel: { routeAverage, sitePenalty, criticalCap } };
 }
+function scoresByCategory(results, config) {
+  const byCat = /* @__PURE__ */ new Map();
+  for (const r of results) {
+    const cat = r.category ?? "seo";
+    let bucket = byCat.get(cat);
+    if (!bucket) byCat.set(cat, bucket = []);
+    bucket.push(r);
+  }
+  const out = {};
+  for (const [cat, rs] of byCat) out[cat] = computeScore(rs, config);
+  return out;
+}
+function computeHealth(results, config) {
+  const categories = scoresByCategory(results, config);
+  const weights = {};
+  let weighted = 0;
+  let total = 0;
+  for (const cat of Object.keys(categories)) {
+    const w = config.weights?.[cat] ?? 1;
+    if (!Number.isFinite(w) || w < 0) {
+      throw new RangeError(`invalid weight for '${cat}'; expected a finite number >= 0.`);
+    }
+    weights[cat] = w;
+    weighted += categories[cat].score * w;
+    total += w;
+  }
+  if (Object.keys(weights).length === 0) return { health: 100, categories, weights };
+  if (total === 0) {
+    throw new RangeError("Health weights sum to 0; at least one present category must have a positive weight.");
+  }
+  const health = Math.round(weighted / total);
+  return { health, categories, weights };
+}
 
 // src/reporter/console.ts
 var RULE = "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500";
@@ -399,12 +519,18 @@ var SEVERITY_TITLE = {
   warning: "Warnings",
   info: "Info"
 };
-function scoreHeader(results, config) {
-  const { score, scoreModel } = computeScore(results, config);
+var CATEGORY_LABEL = {
+  seo: "SEO",
+  performance: "Performance",
+  a11y: "Accessibility",
+  maintainability: "Maintainability"
+};
+var CATEGORY_ORDER = ["seo", "performance", "a11y", "maintainability"];
+function scoreLine(label, { score, scoreModel }) {
   const parts = [`route avg ${scoreModel.routeAverage}`];
   if (scoreModel.sitePenalty > 0) parts.push(`site \u2212${scoreModel.sitePenalty}`);
   if (scoreModel.criticalCap !== null) parts.push(`capped at ${scoreModel.criticalCap}: critical present`);
-  return `SEO Score: ${score}/100   (${parts.join(" \xB7 ")})`;
+  return `${label} Score: ${score}/100   (${parts.join(" \xB7 ")})`;
 }
 function byRouteTree(results, config) {
   const routes = /* @__PURE__ */ new Map();
@@ -426,12 +552,13 @@ function byRouteTree(results, config) {
 }
 function formatConsoleReport(results, config, options = {}) {
   const summary = summarize(results, config);
-  const lines = [
-    `Svelte Vitals  \xB7  SEO (${options.mode ?? "static mode"})`,
-    "",
-    scoreHeader(results, config),
-    ""
-  ];
+  const { health, categories: byCat } = computeHealth(results, config);
+  const present2 = CATEGORY_ORDER.filter((c) => byCat[c] !== void 0);
+  const header = [`Svelte Vitals  \xB7  ${options.mode ?? "static mode"}`, "", `Health: ${health}/100`];
+  for (const c of present2) {
+    header.push(scoreLine(CATEGORY_LABEL[c] ?? c, byCat[c]));
+  }
+  const lines = [...header, ""];
   const failures = results.filter((r) => classify(r, config) === "fail");
   for (const severity of ["critical", "warning", "info"]) {
     const bucket = failures.filter((r) => effectiveSeverity(r, config) === severity);
@@ -440,7 +567,7 @@ function formatConsoleReport(results, config, options = {}) {
     for (const r of bucket) {
       lines.push(`\u2717 ${r.id}  ${r.message}`);
       if (r.route) lines.push(`            ${r.route}`);
-      if (r.location) lines.push(`            ${r.location}`);
+      if (r.location) lines.push(`            ${r.location}${r.line ? `:${r.line}` : ""}`);
     }
     lines.push("");
   }
@@ -463,17 +590,22 @@ function formatConsoleReport(results, config, options = {}) {
 function issueOf(result) {
   return {
     id: result.id,
+    category: result.category ?? "seo",
     title: result.message,
     detection: result.detection,
     location: result.location,
+    ...result.line !== void 0 ? { line: result.line } : {},
     recommendation: result.recommendation,
     ...result.docsUrl ? { docsUrl: result.docsUrl } : {},
     ...result.fix ? { fix: result.fix } : {}
   };
 }
 function buildJsonReport(results, config, meta) {
-  const { score, scoreModel } = computeScore(results, config);
+  const { health, categories: byCat, weights } = computeHealth(results, config);
   const summary = summarize(results, config);
+  const categories = Object.fromEntries(
+    Object.entries(byCat).map(([cat, sr]) => [cat, { score: sr.score, scoreModel: sr.scoreModel }])
+  );
   const routeMap = /* @__PURE__ */ new Map();
   for (const r of results) {
     if (r.route === void 0) continue;
@@ -486,7 +618,7 @@ function buildJsonReport(results, config, meta) {
     issues: rs.filter((r) => isPenalized(r.detection, config.treatDynamicAs)).map((r) => ({ ...issueOf(r), severity: effectiveSeverity(r, config) }))
   }));
   const siteIssues = results.filter((r) => r.route === void 0 && isPenalized(r.detection, config.treatDynamicAs)).map((r) => ({ ...issueOf(r), severity: effectiveSeverity(r, config) }));
-  return { version: meta.version, score, scoreModel, summary, routes, siteIssues };
+  return { version: meta.version, score: health, weights, categories, summary, routes, siteIssues };
 }
 function formatJsonReport(results, config, meta) {
   return JSON.stringify(buildJsonReport(results, config, meta), null, 2);
@@ -499,7 +631,8 @@ function mdTags(text) {
 }
 function formatAgentReport(results, config) {
   const failing = results.filter((r) => classify(r, config) === "fail");
-  const lines = ["# svelte-vitals \u2014 SEO fixes", ""];
+  const { health } = computeHealth(results, config);
+  const lines = ["# svelte-vitals \u2014 fixes", "", `Health: ${health}/100`, ""];
   if (failing.length === 0) {
     lines.push("No issues to fix.", "");
     return lines.join("\n").replace(/\n+$/, "\n");
@@ -581,10 +714,19 @@ function formatSarifReport(results, config, meta) {
       ruleIndex: ruleIndex.get(r.id),
       level: severityToSarifLevel(effectiveSeverity(r, config)),
       message: { text: messageText(r) },
-      partialFingerprints: { "svelteVitals/v1": `${r.id}:${r.route ?? "project"}` }
+      partialFingerprints: {
+        "svelteVitals/v1": `${r.id}:${r.route ?? "project"}${r.line !== void 0 ? `:${r.location ?? ""}:${r.line}` : ""}`
+      }
     };
     if (r.location) {
-      result.locations = [{ physicalLocation: { artifactLocation: { uri: r.location } } }];
+      result.locations = [
+        {
+          physicalLocation: {
+            artifactLocation: { uri: r.location },
+            ...r.line !== void 0 ? { region: { startLine: r.line } } : {}
+          }
+        }
+      ];
     }
     return result;
   });
@@ -622,7 +764,10 @@ function formatGithubReport(results, config) {
     const meta = ruleMetaById(r.id);
     const title = meta ? `${r.id}: ${meta.title}` : r.id;
     const props = [];
-    if (r.location) props.push(`file=${escapeProp(r.location)}`);
+    if (r.location) {
+      props.push(`file=${escapeProp(r.location)}`);
+      if (r.line !== void 0) props.push(`line=${r.line}`);
+    }
     props.push(`title=${escapeProp(title)}`);
     return `::${level} ${props.join(",")}::${escapeData(messageText(r))}`;
   });
@@ -646,6 +791,7 @@ export {
   applyRuleSeverities,
   buildJsonReport,
   classify,
+  computeHealth,
   computeScore,
   defaultConfig,
   defaultProject,
@@ -660,8 +806,12 @@ export {
   formatSarifReport,
   hasFailureAtOrAbove,
   headTagRule,
+  imageRule,
   isPenalized,
+  perf001ImageDimensions,
+  perf002ImageLoading,
   runRules,
+  scoresByCategory,
   selectRules,
   seo001Title,
   seo002Description,

package/package.json

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