@svelte-vitals/core 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -151,12 +151,18 @@ interface Rule {
     severity: Severity;
     /** 'route' = evaluated per route, 'project' = site-wide (design §10, §12). */
     scope: Scope;
+    /** Why this rule matters — one or two sentences, surfaced by explain_rule (issue #24). */
+    rationale: string;
+    /** Canonical remediation template, shared by findings and explain_rule (issue #24). */
+    fix?: Fix;
     /**
      * Evaluate the resolved heads. A single rule may return one Result per route,
      * so it always returns an array. Project-scoped rules return a single element.
      */
     check(ctx: RuleContext): Promise<Result[]>;
 }
+/** Documentation URL for a rule id. Single source so no per-rule URL can drift (issue #24). */
+declare function docsUrlFor(id: string): string;
 /**
  * Whether a detection should be penalized by scoring (design §12). Shared by the
  * future Scorer and by the Slice 0 reporter so pass/fail is decided in one place.
@@ -194,6 +200,18 @@ declare const seo009HtmlLang: Rule;
 
 declare const allRules: Rule[];
 
+interface RuleInfo {
+    id: string;
+    title: string;
+    category: Category;
+    severity: Severity;
+    rationale: string;
+    docsUrl: string;
+    fix?: Fix;
+}
+/** Look up a rule's static metadata for the MCP explain_rule tool (issue #24). Rule ids are matched case-insensitively. */
+declare function explainRule(id: string): RuleInfo | undefined;
+
 interface HeadTagRuleOptions {
     id: string;
     title: string;
@@ -203,6 +221,8 @@ interface HeadTagRuleOptions {
     /** Short human label, e.g. 'description'. */
     label: string;
     recommendation: string;
+    /** Why this rule matters — surfaced by explain_rule (issue #24). */
+    rationale: string;
     /** Agent-actionable remediation attached to every finding (issue #18). */
     fix?: Fix;
 }
@@ -239,19 +259,6 @@ interface ConsoleReportOptions {
  */
 declare function formatConsoleReport(results: Result[], config: Config, options?: ConsoleReportOptions): string;
 
-/** Render results as the documented JSON report string (design §7). */
-declare function formatJsonReport(results: Result[], config: Config, meta: {
-    version: string;
-}): string;
-
-/** Render failing findings as an agent-actionable Markdown remediation document (issue #18). */
-declare function formatAgentReport(results: Result[], config: Config): string;
-
-/** Drop rules disabled via config (design §6). */
-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[];
-
 interface ScoreModel {
     routeAverage: number;
     sitePenalty: number;
@@ -268,4 +275,56 @@ interface ScoreOptions {
 /** Compute the headline score and its breakdown (design §12). */
 declare function computeScore(results: Result[], config: Config, options?: ScoreOptions): ScoreResult;
 
-export { type Category, type Classification, type Config, type ConsoleReportOptions, type Detection, type Fix, type HeadProvider, type HeadTag, type Presence, type Project, ROBOTS_SOURCE_PATHS, type ResolvedHead, type Result, type Rule, type RuleContext, 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, classify, computeScore, defaultConfig, defaultProject, defineConfig, effectiveSeverity, formatAgentReport, formatConsoleReport, formatJsonReport, hasFailureAtOrAbove, headTagRule, isPenalized, runRules, selectRules, seo001Title, seo002Description, seo003Canonical, seo004OgImage, seo005OgTitle, seo006Robots, seo007Sitemap, seo008JsonLd, seo009HtmlLang, summarize };
+declare function issueOf(result: Result): {
+    fix?: Fix | undefined;
+    docsUrl?: string | undefined;
+    id: string;
+    title: string;
+    detection: Detection;
+    location: string | undefined;
+    recommendation: string | undefined;
+};
+type JsonIssue = ReturnType<typeof issueOf> & {
+    severity: ReturnType<typeof effectiveSeverity>;
+};
+interface JsonReport {
+    version: string;
+    score: number;
+    scoreModel: ScoreModel;
+    summary: Summary;
+    routes: Array<{
+        route: string;
+        score: number;
+        issues: JsonIssue[];
+    }>;
+    siteIssues: JsonIssue[];
+}
+/** Build the structured JSON report object (design §7). Shared by the json reporter and the MCP `analyze` tool (issue #24). */
+declare function buildJsonReport(results: Result[], config: Config, meta: {
+    version: string;
+}): JsonReport;
+/** Render results as the documented JSON report string (design §7). */
+declare function formatJsonReport(results: Result[], config: Config, meta: {
+    version: string;
+}): string;
+
+/** Render failing findings as an agent-actionable Markdown remediation document (issue #18). */
+declare function formatAgentReport(results: Result[], config: Config): string;
+
+/** Render penalized findings as a SARIF 2.1.0 log string (issue #18, design slice 5). */
+declare function formatSarifReport(results: Result[], config: Config, meta: {
+    version: string;
+}): string;
+
+/**
+ * Render penalized findings as GitHub Actions workflow commands (issue #18, design slice 5).
+ * GitHub turns these into inline PR annotations and run-annotation entries. Returns '' when clean.
+ */
+declare function formatGithubReport(results: Result[], config: Config): string;
+
+/** Drop rules disabled via config (design §6). */
+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 };

package/dist/index.js

@@ -27,6 +27,9 @@ var SITEMAP_SOURCE_PATHS = [
 ];
 
 // src/rule.ts
+function docsUrlFor(id) {
+  return `https://svelte-vitals.dev/rules/${id}`;
+}
 function isPenalized(detection, treatDynamicAs) {
   if (detection.presence === "none") return true;
   if (detection.value === "absent") return true;
@@ -41,7 +44,11 @@ async function runRules(rules, ctx) {
 }
 
 // src/rules/seo/seo001-title.ts
-var DOCS_URL = "https://svelte-vitals.dev/rules/SEO001";
+var FIX = {
+  description: "Add a <title> inside <svelte:head> (a dynamic title is fine).",
+  snippet: "<svelte:head>\n  <title>{data.title}</title>\n</svelte:head>",
+  lang: "svelte"
+};
 function detectTitle(head) {
   const title = head.tags.find((t) => t.kind === "title");
   if (!title) {
@@ -60,6 +67,8 @@ var seo001Title = {
   category: "seo",
   severity: "critical",
   scope: "route",
+  rationale: "A unique, non-empty <title> is the single strongest on-page SEO signal and the text shown in search results and browser tabs.",
+  fix: FIX,
   async check(ctx) {
     return ctx.heads.map((head) => {
       const detection = detectTitle(head);
@@ -71,12 +80,8 @@ var seo001Title = {
         location: head.file,
         message: messageFor(detection),
         recommendation: "Add a <title> inside <svelte:head>, e.g. <title>{data.title}</title>, or set it via your meta component.",
-        docsUrl: DOCS_URL,
-        fix: {
-          description: "Add a <title> inside <svelte:head> (a dynamic title is fine).",
-          snippet: "<svelte:head>\n  <title>{data.title}</title>\n</svelte:head>",
-          lang: "svelte"
-        }
+        docsUrl: docsUrlFor("SEO001"),
+        fix: { ...FIX }
       };
     });
   }
@@ -88,13 +93,15 @@ function detect(head, match) {
   return tag ? { presence: tag.presence, value: tag.value } : { presence: "none", value: "absent" };
 }
 function headTagRule(opts) {
-  const docsUrl = `https://svelte-vitals.dev/rules/${opts.id}`;
+  const docsUrl = docsUrlFor(opts.id);
   return {
     id: opts.id,
     title: opts.title,
     category: "seo",
     severity: opts.severity,
     scope: "route",
+    rationale: opts.rationale,
+    ...opts.fix ? { fix: opts.fix } : {},
     async check(ctx) {
       return ctx.heads.map((head) => {
         const detection = detect(head, opts.match);
@@ -125,6 +132,7 @@ var seo002Description = headTagRule({
   match: (t) => t.kind === "meta" && t.name === "description",
   label: '<meta name="description">',
   recommendation: 'Add a <meta name="description"> in <svelte:head>, or set the description on your meta component.',
+  rationale: "A meta description is the snippet search engines show under your title; without one they invent one from page text, often poorly.",
   fix: {
     description: 'Add a <meta name="description"> inside <svelte:head>, or set description on your meta component.',
     snippet: '<svelte:head>\n  <meta name="description" content="A concise page summary." />\n</svelte:head>',
@@ -138,6 +146,7 @@ var seo003Canonical = headTagRule({
   match: (t) => t.kind === "link" && t.rel === "canonical",
   label: '<link rel="canonical">',
   recommendation: 'Add <link rel="canonical"> in <svelte:head>, or set the canonical prop on your meta component.',
+  rationale: "A canonical URL tells search engines which URL is authoritative, preventing duplicate-content dilution across query strings and trailing-slash variants.",
   fix: {
     description: 'Add <link rel="canonical"> inside <svelte:head>, or set the canonical prop on your meta component.',
     snippet: '<svelte:head>\n  <link rel="canonical" href="https://example.com/this-page" />\n</svelte:head>',
@@ -151,6 +160,7 @@ var seo004OgImage = headTagRule({
   match: (t) => t.kind === "meta" && t.property === "og:image",
   label: '<meta property="og:image">',
   recommendation: 'Add <meta property="og:image">, or set openGraph.images on your meta component.',
+  rationale: "og:image is the preview thumbnail shown when the page is shared on social platforms; without it links render bare and get fewer clicks.",
   fix: {
     description: 'Add <meta property="og:image">, or set openGraph.images on your meta component.',
     snippet: '<svelte:head>\n  <meta property="og:image" content="https://example.com/og.png" />\n</svelte:head>',
@@ -164,6 +174,7 @@ var seo005OgTitle = headTagRule({
   match: (t) => t.kind === "meta" && t.property === "og:title",
   label: '<meta property="og:title">',
   recommendation: 'Add <meta property="og:title">, or set openGraph.title on your meta component.',
+  rationale: "og:title controls the headline shown when the page is shared on social platforms, independent of the document <title>.",
   fix: {
     description: 'Add <meta property="og:title">, or set openGraph.title on your meta component.',
     snippet: '<svelte:head>\n  <meta property="og:title" content="Page title" />\n</svelte:head>',
@@ -177,6 +188,7 @@ var seo008JsonLd = headTagRule({
   match: (t) => t.kind === "jsonld",
   label: 'JSON-LD (<script type="application/ld+json">)',
   recommendation: "Add JSON-LD structured data, e.g. via <svelte:head> or a JsonLd component.",
+  rationale: "JSON-LD structured data lets search engines render rich results (breadcrumbs, articles, products) for the page.",
   fix: {
     // Svelte ships <script> contents verbatim (the body is raw text, not Svelte
     // markup), so use literal JSON here — an interpolation like {JSON.stringify(...)}
@@ -190,12 +202,19 @@ var seo008JsonLd = headTagRule({
 // src/rules/seo/project-rules.ts
 var present = { presence: "own", value: "static" };
 var absent = { presence: "none", value: "absent" };
+var SEO006_FIX = {
+  description: "Create static/robots.txt (or a src/routes/robots.txt/+server endpoint).",
+  snippet: "User-agent: *\nAllow: /\n\nSitemap: https://example.com/sitemap.xml",
+  lang: "text"
+};
 var seo006Robots = {
   id: "SEO006",
   title: "robots.txt",
   category: "seo",
   severity: "warning",
   scope: "project",
+  rationale: "robots.txt tells crawlers which paths they may fetch and points them to your sitemap; missing it leaves crawl behaviour to defaults.",
+  fix: SEO006_FIX,
   async check(ctx) {
     const detection = ctx.project.hasRobotsTxt ? present : absent;
     return [
@@ -205,22 +224,25 @@ var seo006Robots = {
         detection,
         message: ctx.project.hasRobotsTxt ? "robots.txt" : "Missing robots.txt",
         recommendation: "Add static/robots.txt or a src/routes/robots.txt/+server endpoint.",
-        docsUrl: "https://svelte-vitals.dev/rules/SEO006",
-        fix: {
-          description: "Create static/robots.txt (or a src/routes/robots.txt/+server endpoint).",
-          snippet: "User-agent: *\nAllow: /\n\nSitemap: https://example.com/sitemap.xml",
-          lang: "text"
-        }
+        docsUrl: docsUrlFor("SEO006"),
+        fix: { ...SEO006_FIX }
       }
     ];
   }
 };
+var SEO007_FIX = {
+  description: "Create static/sitemap.xml (or a src/routes/sitemap.xml/+server endpoint).",
+  snippet: '<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n  <url><loc>https://example.com/</loc></url>\n</urlset>',
+  lang: "xml"
+};
 var seo007Sitemap = {
   id: "SEO007",
   title: "sitemap.xml",
   category: "seo",
   severity: "warning",
   scope: "project",
+  rationale: "A sitemap.xml lists your URLs so search engines can discover and prioritise them, especially pages not well linked internally.",
+  fix: SEO007_FIX,
   async check(ctx) {
     const detection = ctx.project.hasSitemap ? present : absent;
     return [
@@ -230,22 +252,25 @@ var seo007Sitemap = {
         detection,
         message: ctx.project.hasSitemap ? "sitemap.xml" : "Missing sitemap.xml",
         recommendation: "Add static/sitemap.xml or a src/routes/sitemap.xml/+server endpoint.",
-        docsUrl: "https://svelte-vitals.dev/rules/SEO007",
-        fix: {
-          description: "Create static/sitemap.xml (or a src/routes/sitemap.xml/+server endpoint).",
-          snippet: '<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n  <url><loc>https://example.com/</loc></url>\n</urlset>',
-          lang: "xml"
-        }
+        docsUrl: docsUrlFor("SEO007"),
+        fix: { ...SEO007_FIX }
       }
     ];
   }
 };
+var SEO009_FIX = {
+  description: "Set the lang attribute on <html> in src/app.html.",
+  snippet: '<html lang="en">',
+  lang: "html"
+};
 var seo009HtmlLang = {
   id: "SEO009",
   title: "<html lang>",
   category: "seo",
   severity: "warning",
   scope: "project",
+  rationale: "The <html lang> attribute declares the page language for search engines, screen readers, and translation tools.",
+  fix: SEO009_FIX,
   async check(ctx) {
     const detection = ctx.project.htmlLang;
     const message = detection.presence === "none" ? "Missing <html lang>" : detection.value === "absent" ? "Empty <html lang>" : "<html lang>";
@@ -256,12 +281,8 @@ var seo009HtmlLang = {
         detection,
         message,
         recommendation: 'Set <html lang="..."> in src/app.html.',
-        docsUrl: "https://svelte-vitals.dev/rules/SEO009",
-        fix: {
-          description: "Set the lang attribute on <html> in src/app.html.",
-          snippet: '<html lang="en">',
-          lang: "html"
-        }
+        docsUrl: docsUrlFor("SEO009"),
+        fix: { ...SEO009_FIX }
       }
     ];
   }
@@ -279,6 +300,20 @@ var allRules = [
   seo008JsonLd,
   seo009HtmlLang
 ];
+function explainRule(id) {
+  const target = id.toUpperCase();
+  const rule = allRules.find((r) => r.id === target);
+  if (!rule) return void 0;
+  return {
+    id: rule.id,
+    title: rule.title,
+    category: rule.category,
+    severity: rule.severity,
+    rationale: rule.rationale,
+    docsUrl: docsUrlFor(rule.id),
+    ...rule.fix ? { fix: rule.fix } : {}
+  };
+}
 
 // src/summary.ts
 function classify(result, config) {
@@ -432,10 +467,11 @@ function issueOf(result) {
     detection: result.detection,
     location: result.location,
     recommendation: result.recommendation,
+    ...result.docsUrl ? { docsUrl: result.docsUrl } : {},
     ...result.fix ? { fix: result.fix } : {}
   };
 }
-function formatJsonReport(results, config, meta) {
+function buildJsonReport(results, config, meta) {
   const { score, scoreModel } = computeScore(results, config);
   const summary = summarize(results, config);
   const routeMap = /* @__PURE__ */ new Map();
@@ -450,7 +486,10 @@ function formatJsonReport(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 JSON.stringify({ version: meta.version, score, scoreModel, summary, routes, siteIssues }, null, 2);
+  return { version: meta.version, score, scoreModel, summary, routes, siteIssues };
+}
+function formatJsonReport(results, config, meta) {
+  return JSON.stringify(buildJsonReport(results, config, meta), null, 2);
 }
 
 // src/reporter/agent.ts
@@ -499,6 +538,97 @@ function formatAgentReport(results, config) {
   return lines.join("\n").replace(/\n+$/, "\n");
 }
 
+// src/reporter/shared.ts
+function severityToSarifLevel(sev) {
+  return sev === "critical" ? "error" : sev === "warning" ? "warning" : "note";
+}
+function severityToGithubLevel(sev) {
+  return sev === "critical" ? "error" : sev === "warning" ? "warning" : "notice";
+}
+function messageText(result) {
+  return result.recommendation ? `${result.message} ${result.recommendation}` : result.message;
+}
+function docsUrlFor2(id) {
+  return `https://svelte-vitals.dev/rules/${id}`;
+}
+var RULE_META = new Map(
+  allRules.map((r) => [r.id, { title: r.title, severity: r.severity, docsUrl: docsUrlFor2(r.id) }])
+);
+function ruleMetaById(id) {
+  return RULE_META.get(id);
+}
+
+// src/reporter/sarif.ts
+function formatSarifReport(results, config, meta) {
+  const penalized = results.filter((r) => isPenalized(r.detection, config.treatDynamicAs));
+  const rules = [];
+  const ruleIndex = /* @__PURE__ */ new Map();
+  const sarifResults = penalized.map((r) => {
+    if (!ruleIndex.has(r.id)) {
+      const m = ruleMetaById(r.id);
+      const name = m?.title ?? r.id;
+      ruleIndex.set(r.id, rules.length);
+      rules.push({
+        id: r.id,
+        name,
+        shortDescription: { text: name },
+        helpUri: r.docsUrl ?? m?.docsUrl ?? docsUrlFor2(r.id),
+        defaultConfiguration: { level: severityToSarifLevel(m?.severity ?? r.severity) }
+      });
+    }
+    const result = {
+      ruleId: r.id,
+      ruleIndex: ruleIndex.get(r.id),
+      level: severityToSarifLevel(effectiveSeverity(r, config)),
+      message: { text: messageText(r) },
+      partialFingerprints: { "svelteVitals/v1": `${r.id}:${r.route ?? "project"}` }
+    };
+    if (r.location) {
+      result.locations = [{ physicalLocation: { artifactLocation: { uri: r.location } } }];
+    }
+    return result;
+  });
+  const log = {
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    version: "2.1.0",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "svelte-vitals",
+            informationUri: "https://svelte-vitals.dev",
+            version: meta.version,
+            rules
+          }
+        },
+        results: sarifResults
+      }
+    ]
+  };
+  return JSON.stringify(log, null, 2);
+}
+
+// src/reporter/github.ts
+function escapeData(s) {
+  return s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+function escapeProp(s) {
+  return escapeData(s).replace(/:/g, "%3A").replace(/,/g, "%2C");
+}
+function formatGithubReport(results, config) {
+  const penalized = results.filter((r) => isPenalized(r.detection, config.treatDynamicAs));
+  const lines = penalized.map((r) => {
+    const level = severityToGithubLevel(effectiveSeverity(r, 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)}`);
+    props.push(`title=${escapeProp(title)}`);
+    return `::${level} ${props.join(",")}::${escapeData(messageText(r))}`;
+  });
+  return lines.join("\n");
+}
+
 // src/config-apply.ts
 function selectRules(rules, config) {
   return rules.filter((rule) => config.rules[rule.id] !== "off");
@@ -514,15 +644,20 @@ export {
   SITEMAP_SOURCE_PATHS,
   allRules,
   applyRuleSeverities,
+  buildJsonReport,
   classify,
   computeScore,
   defaultConfig,
   defaultProject,
   defineConfig,
+  docsUrlFor,
   effectiveSeverity,
+  explainRule,
   formatAgentReport,
   formatConsoleReport,
+  formatGithubReport,
   formatJsonReport,
+  formatSarifReport,
   hasFailureAtOrAbove,
   headTagRule,
   isPenalized,

package/package.json

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