npm - @svelte-vitals/core - Versions diffs - 0.0.1 → 0.2.0 - Mend

@svelte-vitals/core 0.0.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/dist/index.d.ts CHANGED Viewed

@@ -15,6 +15,14 @@ interface Detection {
     presence: Presence;
     value: Value;
 }
+/** Project-wide facts precomputed by the runtime layer for project-scope rules (design §10). */
+interface Project {
+    hasRobotsTxt: boolean;
+    hasSitemap: boolean;
+    /** <html lang> from app.html: presence 'own' when the attribute exists ('none' otherwise); value 'static' if non-empty, 'absent' if empty. */
+    htmlLang: Detection;
+}
+declare const defaultProject: Project;
 /** A single rule finding for one route (or the whole project). */
 interface Result {
     /** Rule id, e.g. 'SEO001'. */
@@ -33,8 +41,16 @@ type Scope = 'route' | 'project';
 type Category = 'seo' | 'performance' | 'a11y' | 'maintainability';
 /** How dynamic (`{data.title}`) values are treated by scoring (design §4, §12). */
 type TreatDynamicAs = 'pass' | 'warn' | 'fail';
+/** Per-rule override: disable, or change severity. */
+type RuleSetting = 'off' | Severity;
 interface Config {
     treatDynamicAs: TreatDynamicAs;
+    /** Component names treated as meta sources of unknown content (design §11 layer 4). */
+    metaComponents: string[];
+    /** Per-rule overrides keyed by rule id (design §6). */
+    rules: Record<string, RuleSetting>;
+    /** Minimum severity that fails the run / CI (design §6). */
+    failOn: Severity;
 }
 declare const defaultConfig: Config;
 /** Merge user config over defaults. Identity helper for config files (design §6). */
@@ -92,12 +108,13 @@ interface ResolvedHead {
 /** Supplies ResolvedHead[] for a project. The only piece that differs per mode. */
 interface HeadProvider {
     mode: 'static' | 'rendered';
-    collect(rt: Runtime, cwd: string): Promise<ResolvedHead[]>;
+    collect(rt: Runtime, cwd: string, config?: Config): Promise<ResolvedHead[]>;
 }
 /** Input given to every rule. Mode-independent: rules see only ResolvedHead[] (design §8, §10). */
 interface RuleContext {
     heads: ResolvedHead[];
+    project: Project;
     config: Config;
 }
 interface Rule {
@@ -120,7 +137,7 @@ interface Rule {
  *
  *   presence 'none'            → penalized (nothing set anywhere)
  *   value 'absent'             → penalized (tag present but empty)
- *   value 'dynamic'            → penalized only when treatDynamicAs is 'fail'
+ *   value 'dynamic'            → penalized when treatDynamicAs is not 'pass' (warn or fail)
  *   otherwise (static/inherited) → not penalized
  */
 declare function isPenalized(detection: Detection, treatDynamicAs: TreatDynamicAs): boolean;
@@ -139,9 +156,31 @@ declare function runRules(rules: Rule[], ctx: RuleContext): Promise<Result[]>;
  */
 declare const seo001Title: Rule;
-/** Rule registry. Slice 0 ships SEO001 only; later slices append here. */
+declare const seo002Description: Rule;
+declare const seo003Canonical: Rule;
+declare const seo004OgImage: Rule;
+declare const seo005OgTitle: Rule;
+declare const seo008JsonLd: Rule;
+declare const seo006Robots: Rule;
+declare const seo007Sitemap: Rule;
+declare const seo009HtmlLang: Rule;
 declare const allRules: Rule[];
+interface HeadTagRuleOptions {
+    id: string;
+    title: string;
+    severity: Severity;
+    /** Identifies the tag this rule looks for. */
+    match: (tag: HeadTag) => boolean;
+    /** Short human label, e.g. 'description'. */
+    label: string;
+    recommendation: string;
+}
+/** Build a route-scope rule asserting the presence of a single head tag (design §11). */
+declare function headTagRule(opts: HeadTagRuleOptions): Rule;
 interface Summary {
     critical: number;
     warning: number;
@@ -154,15 +193,46 @@ interface Summary {
 /** Classify a single result for display/scoring (design §7, §12). */
 type Classification = 'fail' | 'pass' | 'dynamic';
 declare function classify(result: Result, config: Config): Classification;
+/** A penalized dynamic finding is a warning under treatDynamicAs 'warn'; otherwise the rule's severity. */
+declare function effectiveSeverity(result: Result, config: Config): Severity;
 declare function summarize(results: Result[], config: Config): Summary;
 /** Whether the run should fail the build/CI per the minimum failing severity. */
 declare function hasFailureAtOrAbove(summary: Summary, min: Severity): boolean;
+interface ConsoleReportOptions {
+    byRoute?: boolean;
+}
 /**
  * Render results as a console report string (design §7). Pure: returns a string,
- * the caller is responsible for printing. Slice 0 lists failures grouped by
- * severity, then passing routes (with a ↯ marker for dynamic values).
+ * the caller is responsible for printing. Prepends a score header; when byRoute is
+ * set, adds a per-route score tree.
  */
-declare function formatConsoleReport(results: Result[], config: Config): string;
+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;
+/** 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;
+    /** Headline cap value when it actually lowered the score, else null. */
+    criticalCap: number | null;
+}
+interface ScoreResult {
+    score: number;
+    scoreModel: ScoreModel;
+}
+interface ScoreOptions {
+    applyCriticalCap?: boolean;
+}
+/** 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 Detection, type HeadProvider, type HeadTag, type Presence, type ResolvedHead, type Result, type Rule, type RuleContext, type Runtime, type Scope, type Severity, type Summary, type TreatDynamicAs, type Value, allRules, classify, defaultConfig, defineConfig, formatConsoleReport, hasFailureAtOrAbove, isPenalized, runRules, seo001Title, summarize };
+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 };

package/dist/index.js CHANGED Viewed

@@ -1,6 +1,14 @@
 // src/types.ts
+var defaultProject = {
+  hasRobotsTxt: false,
+  hasSitemap: false,
+  htmlLang: { presence: "none", value: "absent" }
+};
 var defaultConfig = {
-  treatDynamicAs: "pass"
+  treatDynamicAs: "pass",
+  metaComponents: [],
+  rules: {},
+  failOn: "critical"
 };
 function defineConfig(config = {}) {
   return { ...defaultConfig, ...config };
@@ -10,7 +18,7 @@ function defineConfig(config = {}) {
 function isPenalized(detection, treatDynamicAs) {
   if (detection.presence === "none") return true;
   if (detection.value === "absent") return true;
-  if (detection.value === "dynamic") return treatDynamicAs === "fail";
+  if (detection.value === "dynamic") return treatDynamicAs !== "pass";
   return false;
 }
@@ -57,8 +65,157 @@ var seo001Title = {
   }
 };
+// src/rules/seo/head-tag-rule.ts
+function detect(head, match) {
+  const tag = head.tags.find(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}`;
+  return {
+    id: opts.id,
+    title: opts.title,
+    category: "seo",
+    severity: opts.severity,
+    scope: "route",
+    async check(ctx) {
+      return ctx.heads.map((head) => {
+        const detection = detect(head, opts.match);
+        const message = detection.presence === "none" ? `Missing ${opts.label}` : detection.value === "absent" ? `Empty ${opts.label}` : opts.label;
+        return {
+          id: opts.id,
+          severity: opts.severity,
+          detection,
+          route: head.route,
+          location: head.file,
+          message,
+          recommendation: opts.recommendation,
+          docsUrl
+        };
+      });
+    }
+  };
+}
+// src/rules/seo/seo002-005-008.ts
+var seo002Description = headTagRule({
+  id: "SEO002",
+  title: "Description presence",
+  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.'
+});
+var seo003Canonical = headTagRule({
+  id: "SEO003",
+  title: "Canonical URL",
+  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.'
+});
+var seo004OgImage = headTagRule({
+  id: "SEO004",
+  title: "Open Graph image",
+  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.'
+});
+var seo005OgTitle = headTagRule({
+  id: "SEO005",
+  title: "Open Graph title",
+  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.'
+});
+var seo008JsonLd = headTagRule({
+  id: "SEO008",
+  title: "JSON-LD structured data",
+  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."
+});
+// src/rules/seo/project-rules.ts
+var present = { presence: "own", value: "static" };
+var absent = { presence: "none", value: "absent" };
+var seo006Robots = {
+  id: "SEO006",
+  title: "robots.txt",
+  category: "seo",
+  severity: "warning",
+  scope: "project",
+  async check(ctx) {
+    const detection = ctx.project.hasRobotsTxt ? present : absent;
+    return [
+      {
+        id: "SEO006",
+        severity: "warning",
+        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"
+      }
+    ];
+  }
+};
+var seo007Sitemap = {
+  id: "SEO007",
+  title: "sitemap.xml",
+  category: "seo",
+  severity: "warning",
+  scope: "project",
+  async check(ctx) {
+    const detection = ctx.project.hasSitemap ? present : absent;
+    return [
+      {
+        id: "SEO007",
+        severity: "warning",
+        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"
+      }
+    ];
+  }
+};
+var seo009HtmlLang = {
+  id: "SEO009",
+  title: "<html lang>",
+  category: "seo",
+  severity: "warning",
+  scope: "project",
+  async check(ctx) {
+    const detection = ctx.project.htmlLang;
+    const message = detection.presence === "none" ? "Missing <html lang>" : detection.value === "absent" ? "Empty <html lang>" : "<html lang>";
+    return [
+      {
+        id: "SEO009",
+        severity: "warning",
+        detection,
+        message,
+        recommendation: 'Set <html lang="..."> in src/app.html.',
+        docsUrl: "https://svelte-vitals.dev/rules/SEO009"
+      }
+    ];
+  }
+};
 // src/rules/index.ts
-var allRules = [seo001Title];
+var allRules = [
+  seo001Title,
+  seo002Description,
+  seo003Canonical,
+  seo004OgImage,
+  seo005OgTitle,
+  seo006Robots,
+  seo007Sitemap,
+  seo008JsonLd,
+  seo009HtmlLang
+];
 // src/summary.ts
 function classify(result, config) {
@@ -66,12 +223,16 @@ function classify(result, config) {
   if (result.detection.value === "dynamic") return "dynamic";
   return "pass";
 }
+function effectiveSeverity(result, config) {
+  if (result.detection.value === "dynamic" && config.treatDynamicAs === "warn") return "warning";
+  return result.severity;
+}
 function summarize(results, config) {
   const summary = { critical: 0, warning: 0, info: 0, passed: 0, dynamic: 0 };
   for (const result of results) {
     const cls = classify(result, config);
     if (cls === "fail") {
-      summary[severityKey(result.severity)] += 1;
+      summary[effectiveSeverity(result, config)] += 1;
     } else {
       summary.passed += 1;
       if (cls === "dynamic") summary.dynamic += 1;
@@ -82,10 +243,55 @@ function summarize(results, config) {
 function hasFailureAtOrAbove(summary, min) {
   const order = ["info", "warning", "critical"];
   const threshold = order.indexOf(min);
-  return order.some((sev, idx) => idx >= threshold && summary[severityKey(sev)] > 0);
+  return order.some((sev, idx) => idx >= threshold && summary[sev] > 0);
 }
-function severityKey(severity) {
-  return severity;
+// src/scoring/score.ts
+var DEDUCTION = { critical: 15, warning: 5, info: 1 };
+var CRITICAL_CAP = 79;
+function clamp(n) {
+  return Math.max(0, Math.min(100, n));
+}
+function computeScore(results, config, options = {}) {
+  const routeResults = results.filter((r) => r.route !== void 0);
+  const projectResults = results.filter((r) => r.route === void 0);
+  const routeScores = /* @__PURE__ */ new Map();
+  for (const r of routeResults) if (!routeScores.has(r.route)) routeScores.set(r.route, 100);
+  let anyCritical = false;
+  const routeRuleMax = /* @__PURE__ */ new Map();
+  for (const r of routeResults) {
+    if (!isPenalized(r.detection, config.treatDynamicAs)) continue;
+    const sev = effectiveSeverity(r, config);
+    if (sev === "critical") anyCritical = true;
+    const route = r.route;
+    let perRule = routeRuleMax.get(route);
+    if (!perRule) routeRuleMax.set(route, perRule = /* @__PURE__ */ new Map());
+    const prev = perRule.get(r.id) ?? 0;
+    if (DEDUCTION[sev] > prev) perRule.set(r.id, DEDUCTION[sev]);
+  }
+  for (const [route, perRule] of routeRuleMax) {
+    let deduction = 0;
+    for (const d of perRule.values()) deduction += d;
+    routeScores.set(route, routeScores.get(route) - deduction);
+  }
+  const scores = [...routeScores.values()].map(clamp);
+  const routeAverage = scores.length ? Math.round(scores.reduce((a, b) => a + b, 0) / scores.length) : 100;
+  const projectRuleMax = /* @__PURE__ */ new Map();
+  for (const r of projectResults) {
+    if (!isPenalized(r.detection, config.treatDynamicAs)) continue;
+    const sev = effectiveSeverity(r, config);
+    if (sev === "critical") anyCritical = true;
+    const prev = projectRuleMax.get(r.id) ?? 0;
+    if (DEDUCTION[sev] > prev) projectRuleMax.set(r.id, DEDUCTION[sev]);
+  }
+  let sitePenalty = 0;
+  for (const deduction of projectRuleMax.values()) sitePenalty += deduction;
+  const applyCap = options.applyCriticalCap ?? true;
+  const uncapped = routeAverage - sitePenalty;
+  const capBinds = applyCap && anyCritical && uncapped > CRITICAL_CAP;
+  const criticalCap = capBinds ? CRITICAL_CAP : null;
+  const score = capBinds ? CRITICAL_CAP : uncapped;
+  return { score: clamp(score), scoreModel: { routeAverage, sitePenalty, criticalCap } };
 }
 // src/reporter/console.ts
@@ -95,13 +301,37 @@ var SEVERITY_TITLE = {
   warning: "Warnings",
   info: "Info"
 };
-function formatConsoleReport(results, config) {
+function scoreHeader(results, config) {
+  const { score, scoreModel } = computeScore(results, config);
+  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 ")})`;
+}
+function byRouteTree(results, config) {
+  const routes = /* @__PURE__ */ new Map();
+  for (const r of results) {
+    if (r.route === void 0) continue;
+    if (!routes.has(r.route)) routes.set(r.route, []);
+    routes.get(r.route).push(r);
+  }
+  const lines = ["By route", RULE];
+  for (const [route, rs] of [...routes.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+    const { score } = computeScore(rs, config, { applyCriticalCap: false });
+    lines.push(`${route.padEnd(28)} ${score}`);
+    for (const r of rs.filter((x) => classify(x, config) === "fail")) {
+      lines.push(`    \u2717 ${r.id}  ${r.message}`);
+    }
+  }
+  lines.push("");
+  return lines;
+}
+function formatConsoleReport(results, config, options = {}) {
   const summary = summarize(results, config);
-  const lines = [];
-  lines.push("Svelte Vitals  \xB7  SEO (static mode)", "");
+  const lines = ["Svelte Vitals  \xB7  SEO (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) => r.severity === severity);
+    const bucket = failures.filter((r) => effectiveSeverity(r, config) === severity);
     if (bucket.length === 0) continue;
     lines.push(`${SEVERITY_TITLE[severity]} (${bucket.length})`, RULE);
     for (const r of bucket) {
@@ -121,20 +351,73 @@ function formatConsoleReport(results, config) {
     }
     lines.push("");
   }
-  if (summary.dynamic > 0) {
-    lines.push("\u21AF = set dynamically (verified at runtime).");
-  }
+  if (options.byRoute) lines.push(...byRouteTree(results, config));
+  if (summary.dynamic > 0) lines.push("\u21AF = set dynamically (verified at runtime).");
   return lines.join("\n").replace(/\n+$/, "\n");
 }
+// src/reporter/json.ts
+function issueOf(result) {
+  return {
+    id: result.id,
+    title: result.message,
+    detection: result.detection,
+    location: result.location,
+    recommendation: result.recommendation
+  };
+}
+function formatJsonReport(results, config, meta) {
+  const { score, scoreModel } = computeScore(results, config);
+  const summary = summarize(results, config);
+  const routeMap = /* @__PURE__ */ new Map();
+  for (const r of results) {
+    if (r.route === void 0) continue;
+    if (!routeMap.has(r.route)) routeMap.set(r.route, { route: r.route, results: [] });
+    routeMap.get(r.route).results.push(r);
+  }
+  const routes = [...routeMap.values()].sort((a, b) => a.route.localeCompare(b.route)).map(({ route, results: rs }) => ({
+    route,
+    score: computeScore(rs, config, { applyCriticalCap: false }).score,
+    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);
+}
+// src/config-apply.ts
+function selectRules(rules, config) {
+  return rules.filter((rule) => config.rules[rule.id] !== "off");
+}
+function applyRuleSeverities(results, config) {
+  return results.map((result) => {
+    const setting = config.rules[result.id];
+    return setting && setting !== "off" ? { ...result, severity: setting } : result;
+  });
+}
 export {
   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
 };

package/package.json CHANGED Viewed

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