@svelte-vitals/core 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -23,6 +23,15 @@ interface Project {
     htmlLang: Detection;
 }
 declare const defaultProject: Project;
+/** A concrete, agent-actionable remediation for a finding (design §10, issue #18). */
+interface Fix {
+    /** One-line imperative instruction, e.g. 'Add a <meta name="description"> inside <svelte:head>.' */
+    description: string;
+    /** Concrete code to insert or a file's contents to create. */
+    snippet?: string;
+    /** Markdown fenced-code language for `snippet` (default 'svelte'). */
+    lang?: string;
+}
 /** A single rule finding for one route (or the whole project). */
 interface Result {
     /** Rule id, e.g. 'SEO001'. */
@@ -36,6 +45,8 @@ interface Result {
     message: string;
     recommendation?: string;
     docsUrl?: string;
+    /** Agent-actionable remediation (issue #18). */
+    fix?: Fix;
 }
 type Scope = 'route' | 'project';
 type Category = 'seo' | 'performance' | 'a11y' | 'maintainability';
@@ -192,6 +203,8 @@ interface HeadTagRuleOptions {
     /** Short human label, e.g. 'description'. */
     label: string;
     recommendation: string;
+    /** Agent-actionable remediation attached to every finding (issue #18). */
+    fix?: Fix;
 }
 /** Build a route-scope rule asserting the presence of a single head tag (design §11). */
 declare function headTagRule(opts: HeadTagRuleOptions): Rule;
@@ -231,6 +244,20 @@ 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). */
@@ -252,4 +279,4 @@ 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 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, formatConsoleReport, formatJsonReport, 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 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, formatGithubReport, formatJsonReport, formatSarifReport, hasFailureAtOrAbove, headTagRule, isPenalized, runRules, selectRules, seo001Title, seo002Description, seo003Canonical, seo004OgImage, seo005OgTitle, seo006Robots, seo007Sitemap, seo008JsonLd, seo009HtmlLang, summarize };

package/dist/index.js

@@ -71,7 +71,12 @@ 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
+        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"
+        }
       };
     });
   }
@@ -102,7 +107,10 @@ function headTagRule(opts) {
           location: head.file,
           message,
           recommendation: opts.recommendation,
-          docsUrl
+          docsUrl,
+          // Copy per finding: opts.fix is a rule-level template shared across all
+          // results this rule emits; a fresh object keeps findings independent.
+          ...opts.fix ? { fix: { ...opts.fix } } : {}
         };
       });
     }
@@ -116,7 +124,12 @@ var seo002Description = headTagRule({
   severity: "critical",
   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.'
+  recommendation: 'Add a <meta name="description"> in <svelte:head>, or set the description on your meta component.',
+  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>',
+    lang: "svelte"
+  }
 });
 var seo003Canonical = headTagRule({
   id: "SEO003",
@@ -124,7 +137,12 @@ var seo003Canonical = headTagRule({
   severity: "warning",
   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.'
+  recommendation: 'Add <link rel="canonical"> in <svelte:head>, or set the canonical prop on your meta component.',
+  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>',
+    lang: "svelte"
+  }
 });
 var seo004OgImage = headTagRule({
   id: "SEO004",
@@ -132,7 +150,12 @@ var seo004OgImage = headTagRule({
   severity: "warning",
   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.'
+  recommendation: 'Add <meta property="og:image">, or set openGraph.images on your meta component.',
+  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>',
+    lang: "svelte"
+  }
 });
 var seo005OgTitle = headTagRule({
   id: "SEO005",
@@ -140,7 +163,12 @@ var seo005OgTitle = headTagRule({
   severity: "warning",
   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.'
+  recommendation: 'Add <meta property="og:title">, or set openGraph.title on your meta component.',
+  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>',
+    lang: "svelte"
+  }
 });
 var seo008JsonLd = headTagRule({
   id: "SEO008",
@@ -148,7 +176,15 @@ var seo008JsonLd = headTagRule({
   severity: "info",
   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."
+  recommendation: "Add JSON-LD structured data, e.g. via <svelte:head> or a JsonLd component.",
+  fix: {
+    // Svelte ships <script> contents verbatim (the body is raw text, not Svelte
+    // markup), so use literal JSON here — an interpolation like {JSON.stringify(...)}
+    // would be emitted as that literal string and produce invalid JSON-LD.
+    description: "Add a JSON-LD <script> inside <svelte:head> with literal JSON (Svelte emits the script body as-is).",
+    snippet: '<svelte:head>\n  <script type="application/ld+json">\n    {\n      "@context": "https://schema.org",\n      "@type": "WebPage",\n      "name": "Page title"\n    }\n  </script>\n</svelte:head>',
+    lang: "svelte"
+  }
 });
 
 // src/rules/seo/project-rules.ts
@@ -169,7 +205,12 @@ 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"
+        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"
+        }
       }
     ];
   }
@@ -189,7 +230,12 @@ 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"
+        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"
+        }
       }
     ];
   }
@@ -210,7 +256,12 @@ var seo009HtmlLang = {
         detection,
         message,
         recommendation: 'Set <html lang="..."> in src/app.html.',
-        docsUrl: "https://svelte-vitals.dev/rules/SEO009"
+        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"
+        }
       }
     ];
   }
@@ -380,7 +431,8 @@ function issueOf(result) {
     title: result.message,
     detection: result.detection,
     location: result.location,
-    recommendation: result.recommendation
+    recommendation: result.recommendation,
+    ...result.fix ? { fix: result.fix } : {}
   };
 }
 function formatJsonReport(results, config, meta) {
@@ -401,6 +453,143 @@ function formatJsonReport(results, config, meta) {
   return JSON.stringify({ version: meta.version, score, scoreModel, summary, routes, siteIssues }, null, 2);
 }
 
+// src/reporter/agent.ts
+var SEVERITY_RANK = { critical: 0, warning: 1, info: 2 };
+function mdTags(text) {
+  return text.replace(/<[^>]+>/g, (tag) => `\`${tag}\``);
+}
+function formatAgentReport(results, config) {
+  const failing = results.filter((r) => classify(r, config) === "fail");
+  const lines = ["# svelte-vitals \u2014 SEO fixes", ""];
+  if (failing.length === 0) {
+    lines.push("No issues to fix.", "");
+    return lines.join("\n").replace(/\n+$/, "\n");
+  }
+  lines.push(
+    `${failing.length} issue(s) to fix, ordered most-severe first. Fix critical issues first; warning and info items improve SEO but do not fail the default build. Apply each fix below, then re-run \`svelte-vitals\` (or the build) to confirm each rule passes.`,
+    ""
+  );
+  const groups = /* @__PURE__ */ new Map();
+  for (const r of failing) {
+    const key = r.location ?? r.route ?? "(project)";
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(r);
+  }
+  const groupSeverity = (rs) => Math.min(...rs.map((r) => SEVERITY_RANK[effectiveSeverity(r, config)]));
+  const orderedGroups = [...groups.entries()].sort(
+    (a, b) => groupSeverity(a[1]) - groupSeverity(b[1]) || a[0].localeCompare(b[0])
+  );
+  for (const [loc, rs] of orderedGroups) {
+    rs.sort(
+      (x, y) => SEVERITY_RANK[effectiveSeverity(x, config)] - SEVERITY_RANK[effectiveSeverity(y, config)] || x.id.localeCompare(y.id)
+    );
+    lines.push(`## ${loc}`, "");
+    for (const r of rs) {
+      lines.push(`### ${r.id} \xB7 ${mdTags(r.message)} (${effectiveSeverity(r, config)})`);
+      if (r.fix) {
+        lines.push(`- Fix: ${mdTags(r.fix.description)}`);
+        if (r.fix.snippet) lines.push("", "```" + (r.fix.lang ?? "svelte"), r.fix.snippet, "```");
+      } else if (r.recommendation) {
+        lines.push(`- Fix: ${mdTags(r.recommendation)}`);
+      }
+      if (r.docsUrl) lines.push(`- Docs: ${r.docsUrl}`);
+      lines.push(`- Accept: re-run svelte-vitals; ${r.id} passes${r.route ? ` for ${r.route}` : ""}.`, "");
+    }
+  }
+  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 docsUrlFor(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: docsUrlFor(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 ?? docsUrlFor(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");
@@ -422,8 +611,11 @@ export {
   defaultProject,
   defineConfig,
   effectiveSeverity,
+  formatAgentReport,
   formatConsoleReport,
+  formatGithubReport,
   formatJsonReport,
+  formatSarifReport,
   hasFailureAtOrAbove,
   headTagRule,
   isPenalized,

package/package.json

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