@svelte-vitals/core 0.7.0 → 0.8.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';
@@ -127,6 +131,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 +164,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 +224,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 +258,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 +318,19 @@ 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>>;
 
 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>;
@@ -291,6 +339,10 @@ interface JsonReport {
     version: string;
     score: number;
     scoreModel: ScoreModel;
+    categories: Record<string, {
+        score: number;
+        scoreModel: ScoreModel;
+    }>;
     summary: Summary;
     routes: Array<{
         route: string;
@@ -327,4 +379,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 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, 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,18 @@ 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;
+}
 
 // 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 +498,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 +531,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 byCat = scoresByCategory(results, config);
+  const present2 = CATEGORY_ORDER.filter((c) => byCat[c] !== void 0);
+  const header = [`Svelte Vitals  \xB7  ${options.mode ?? "static mode"}`, ""];
+  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 +546,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 +569,24 @@ 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 seoResults = results.filter((r) => (r.category ?? "seo") === "seo");
+  const { score, scoreModel } = computeScore(seoResults, config);
   const summary = summarize(results, config);
+  const byCat = scoresByCategory(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 +599,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, scoreModel, categories, summary, routes, siteIssues };
 }
 function formatJsonReport(results, config, meta) {
   return JSON.stringify(buildJsonReport(results, config, meta), null, 2);
@@ -499,7 +612,7 @@ function mdTags(text) {
 }
 function formatAgentReport(results, config) {
   const failing = results.filter((r) => classify(r, config) === "fail");
-  const lines = ["# svelte-vitals \u2014 SEO fixes", ""];
+  const lines = ["# svelte-vitals \u2014 fixes", ""];
   if (failing.length === 0) {
     lines.push("No issues to fix.", "");
     return lines.join("\n").replace(/\n+$/, "\n");
@@ -581,10 +694,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 +744,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))}`;
   });
@@ -660,8 +785,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.8.0",
   "description": "Shared, runtime-agnostic core for svelte-vitals (types, rule engine, scorer, reporter).",
   "type": "module",
   "license": "MIT",