@svelte-vitals/core 0.2.0 → 0.4.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';
@@ -75,9 +86,10 @@ interface Runtime {
 }
 
 /**
- * A normalized head tag. The mode-independent boundary (design §8): both the
- * static SourceHeadProvider and the future RenderedHeadProvider emit these, so
- * rules never need to know which provider produced them.
+ * A normalized head tag. The mode-independent boundary (design §8): the static
+ * SourceHeadProvider (CLI, via the runtime-abstracted `HeadProvider` below) and
+ * the rendered collector (`@svelte-vitals/vite`, build-time Node) both emit
+ * these, so rules never need to know which mode produced them.
  */
 interface HeadTag {
     kind: 'title' | 'meta' | 'link' | 'jsonld';
@@ -105,12 +117,26 @@ interface ResolvedHead {
     /** Representative source file for the route (used for issue locations). */
     file: string;
 }
-/** Supplies ResolvedHead[] for a project. The only piece that differs per mode. */
+/**
+ * Supplies ResolvedHead[] for a project through the runtime abstraction. The
+ * static (CLI) mode implements this; rendered mode reads prerendered HTML at
+ * build time and emits the same ResolvedHead[] without the runtime indirection.
+ */
 interface HeadProvider {
     mode: 'static' | 'rendered';
     collect(rt: Runtime, cwd: string, config?: Config): Promise<ResolvedHead[]>;
 }
 
+/**
+ * Source-file locations that satisfy the project-scope rules, shared by every
+ * mode so the static (CLI) and rendered (plugin) collectors never drift. This
+ * module is pure data: no I/O, no `node:` imports (design §8).
+ */
+/** Locations that satisfy the robots.txt project rule (SEO006). */
+declare const ROBOTS_SOURCE_PATHS: readonly ["static/robots.txt", "src/routes/robots.txt/+server.ts", "src/routes/robots.txt/+server.js"];
+/** Locations that satisfy the sitemap.xml project rule (SEO007). */
+declare const SITEMAP_SOURCE_PATHS: readonly ["static/sitemap.xml", "src/routes/sitemap.xml/+server.ts", "src/routes/sitemap.xml/+server.js"];
+
 /** Input given to every rule. Mode-independent: rules see only ResolvedHead[] (design §8, §10). */
 interface RuleContext {
     heads: ResolvedHead[];
@@ -177,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;
@@ -201,6 +229,8 @@ declare function hasFailureAtOrAbove(summary: Summary, min: Severity): boolean;
 
 interface ConsoleReportOptions {
     byRoute?: boolean;
+    /** Mode label shown in the header (default 'static mode'). */
+    mode?: string;
 }
 /**
  * Render results as a console report string (design §7). Pure: returns a string,
@@ -214,6 +244,9 @@ 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). */
@@ -235,4 +268,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, type ResolvedHead, type Result, type Rule, type RuleContext, type RuleSetting, type Runtime, 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, formatJsonReport, hasFailureAtOrAbove, headTagRule, isPenalized, runRules, selectRules, seo001Title, seo002Description, seo003Canonical, seo004OgImage, seo005OgTitle, seo006Robots, seo007Sitemap, seo008JsonLd, seo009HtmlLang, summarize };

package/dist/index.js

@@ -14,6 +14,18 @@ function defineConfig(config = {}) {
   return { ...defaultConfig, ...config };
 }
 
+// src/project-paths.ts
+var ROBOTS_SOURCE_PATHS = [
+  "static/robots.txt",
+  "src/routes/robots.txt/+server.ts",
+  "src/routes/robots.txt/+server.js"
+];
+var SITEMAP_SOURCE_PATHS = [
+  "static/sitemap.xml",
+  "src/routes/sitemap.xml/+server.ts",
+  "src/routes/sitemap.xml/+server.js"
+];
+
 // src/rule.ts
 function isPenalized(detection, treatDynamicAs) {
   if (detection.presence === "none") return true;
@@ -59,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"
+        }
       };
     });
   }
@@ -90,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 } } : {}
         };
       });
     }
@@ -104,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",
@@ -112,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",
@@ -120,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",
@@ -128,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",
@@ -136,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
@@ -157,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"
+        }
       }
     ];
   }
@@ -177,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"
+        }
       }
     ];
   }
@@ -198,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"
+        }
       }
     ];
   }
@@ -328,7 +391,12 @@ function byRouteTree(results, config) {
 }
 function formatConsoleReport(results, config, options = {}) {
   const summary = summarize(results, config);
-  const lines = ["Svelte Vitals  \xB7  SEO (static mode)", "", scoreHeader(results, config), ""];
+  const lines = [
+    `Svelte Vitals  \xB7  SEO (${options.mode ?? "static mode"})`,
+    "",
+    scoreHeader(results, config),
+    ""
+  ];
   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);
@@ -363,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) {
@@ -384,6 +453,52 @@ 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/config-apply.ts
 function selectRules(rules, config) {
   return rules.filter((rule) => config.rules[rule.id] !== "off");
@@ -395,6 +510,8 @@ function applyRuleSeverities(results, config) {
   });
 }
 export {
+  ROBOTS_SOURCE_PATHS,
+  SITEMAP_SOURCE_PATHS,
   allRules,
   applyRuleSeverities,
   classify,
@@ -403,6 +520,7 @@ export {
   defaultProject,
   defineConfig,
   effectiveSeverity,
+  formatAgentReport,
   formatConsoleReport,
   formatJsonReport,
   hasFailureAtOrAbove,

package/package.json

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