@svelte-vitals/core 0.32.0 → 0.33.0

package/dist/index.d.ts

@@ -474,6 +474,11 @@ interface ComponentFacts {
     }[];
     /** Inline `svelte-vitals-disable-next-line` directives found in this file's source — component-rule escape hatch (issue #92). Optional: absent is equivalent to no directives, so existing external constructors of `ComponentFacts` are unaffected. */
     suppressions?: SuppressionDirective[];
+    /** Markdown links `[label](url)` appearing inside a comment (architecture/doc-link-target). */
+    commentLinks: {
+        url: string;
+        line: number;
+    }[];
 }
 
 /** What the per-file parsers produce — `ComponentFacts` minus `file`, with `suppressions` always present. */
@@ -1266,6 +1271,8 @@ declare const architectureReservedDirectoryNames: Rule;
 
 declare const architectureRouteComponentImport: Rule;
 
+declare const architectureDocLinkTarget: Rule;
+
 declare const performanceHeavyImport: Rule;
 
 declare const performanceNamespaceImport: Rule;
@@ -1458,6 +1465,8 @@ interface ScoreResult {
 }
 interface ScoreOptions {
     applyCriticalCap?: boolean;
+    /** The rules that ran. Defaults to the selected registry; supplied by tests and custom rule sets. */
+    rules?: readonly Rule[];
 }
 /** Compute the headline score and its breakdown (design §12). */
 declare function computeScore(results: Result[], config: Config, options?: ScoreOptions): ScoreResult;
@@ -1487,6 +1496,15 @@ declare function issueOf(result: Result): {
 type JsonIssue = ReturnType<typeof issueOf> & {
     severity: ReturnType<typeof effectiveSeverity>;
 };
+/**
+ * Per-rule counts. A rule present with `findings: 0` ran and reported nothing, and an absent rule was not
+ * selected — but only when the caller supplied `ruleIds`. Without it the map is seeded from results alone,
+ * so absence means "produced nothing" rather than "not selected".
+ */
+interface RuleEvidence {
+    findings: number;
+    passed: number;
+}
 interface JsonReport {
     version: string;
     score: number;
@@ -1496,6 +1514,7 @@ interface JsonReport {
         scoreModel: ScoreModel;
     }>;
     summary: Summary;
+    rules: Record<string, RuleEvidence>;
     routes: Array<{
         route: string;
         score: number;
@@ -1506,11 +1525,11 @@ interface JsonReport {
 /** Build the structured JSON report object (design §7). The shape the `json` reporter emits (issue #24). */
 declare function buildJsonReport(results: Result[], config: Config, meta: {
     version: string;
-}): JsonReport;
+}, ruleIds?: readonly string[]): JsonReport;
 /** Render results as the documented JSON report string (design §7). */
 declare function formatJsonReport(results: Result[], config: Config, meta: {
     version: string;
-}): string;
+}, ruleIds?: readonly string[]): string;
 
 /** Render failing findings as an agent-actionable Markdown remediation document (issue #18). */
 declare function formatAgentReport(results: Result[], config: Config): string;
@@ -1602,4 +1621,4 @@ declare function escapeHtml(s: string): string;
  */
 declare function safeHref(url: string): string | null;
 
-export { APP_SCRIPT, APP_STYLE, type AppSnapshot, BAND_COLOR, CATEGORIES, CHILD_NODE_KEYS, type Category, type Classification, type CompiledOverride, type ComponentFacts, type Config, type ConsoleReportOptions, type Detection, type EachBlockFact, type EffectFact, type Fix, type HeadProvider, type HeadTag, type HeadingInfo, type HealthResult, type ImageInfo, type JsonReport, type KitAlias, type KitModuleFacts, type OrphanEffectFact, type Palette, type Presence, type Project, ROBOTS_SOURCE_PATHS, type RawKitAliases, type ResolvedHead, type ResolvedHeadings, type ResolvedImages, type Result, type RouteBadge, type Rule, type RuleContext, type RuleInfo, type RuleOptionInfo, type RuleOptionSpec, type RuleOptions, type RuleOptionsSpec, type RuleOverride, type RuleSetting, type RuleSettingObject, type Runtime, SITEMAP_SOURCE_PATHS, SVELTE_CONFIG_FILES, type Scope, type ScoreModel, type ScoreOptions, type ScoreResult, type Severity, type SourceSpan, type Summary, type SuppressionDirective, type TreatDynamicAs, VITE_CONFIG_FILES, type Value, type ViteKitConfigResult, allRules, applyOverrides, applyRuleSeverities, architectureComponentSize, architectureDirectoryNaming, architecturePrivateScopeImport, architecturePropCount, architectureReservedDirectoryNames, architectureRouteComponentImport, architectureUnitEntryFile, attrText, attrTextOf, attrValue, attrValueOf, buildHtmlDocument, buildJsonReport, classify, collectComponentFacts, collectKitModuleFacts, collectSourceFiles, compileOverrides, computeHealth, computeScore, correctnessBasePathNavigation, correctnessCheckableBindValue, correctnessEachIndexKey, correctnessEachKey, correctnessEffectAsDerived, correctnessEffectAsOnMount, correctnessInstanceBrowserGlobal, correctnessNonreactiveBuiltinState, correctnessOrphanEffect, correctnessOrphanLifecycle, correctnessPropMutation, correctnessServerBrowserGlobal, correctnessStalePropDerivation, correctnessUnmutatedState, defaultConfig, defaultProject, defineConfig, docsUrlFor, effectiveSeverity, emptyComponentFacts, emptyKitModuleFacts, escapeHtml, explainRule, findAttr, findKitAliasesInSvelteConfig, findKitPathsBaseInSvelteConfig, findKitPathsBaseInViteConfig, findMinifyDisabled, formatAgentReport, formatConsoleReport, formatGithubReport, formatHtmlReport, formatJsonReport, formatMarkdownReport, formatSarifReport, hasFailureAtOrAbove, headTagRule, imageRule, intOption, isMentionedAnywhere, isPenalized, lineOf, linkRule, listOption, mapOption, noColorPalette, overrideMatches, parseComponentFacts, parseKitModuleFacts, performanceFontPreloadCrossorigin, performanceHeavyImport, performanceImageDimensions, performanceImageLoadingHint, performanceLcpImage, performanceLoadWaterfall, performanceMinifyDisabled, performanceNamespaceImport, performancePreconnect, performancePreloadMissingAs, performanceRenderBlockingScript, performanceResponsiveImage, performanceSequentialAwaits, performanceStateRaw, renderAppShell, resolveKitAliases, resolveKitPathsBase, resolveRuleOptions, resolveRunesModuleSpecifier, runRules, safeHref, scoreBand, scoreColor, scoresByCategory, securityHandlerStateWrite, securityJavascriptUrl, securityRawHtml, securityServerModuleState, securitySharedStateImport, selectRules, seoCanonicalUrl, seoCharset, seoDescriptionLength, seoDescriptionPresence, seoDuplicateDescription, seoDuplicateTitle, seoHeadingLevelSkip, seoHreflang, seoHtmlLang, seoImageAlt, seoIndexability, seoJsonLd, seoJsonLdDateFormat, seoJsonLdDeprecatedType, seoJsonLdPlaceholder, seoJsonLdRelativeUrl, seoJsonLdRequiredProps, seoJsonLdValidity, seoOgDescription, seoOgImage, seoOgTitle, seoOgUrl, seoRobotsTxt, seoSingleH1, seoSitemapInRobots, seoSitemapXml, seoSsrDisabled, seoTitleLength, seoTitlePresence, seoTwitterCard, seoViewport, settingOptions, settingSeverity, shouldSkipRangeCheck, summarize, textFromNodes, validateRuleOptions, validateRuleSetting, valueFromNodes };
+export { APP_SCRIPT, APP_STYLE, type AppSnapshot, BAND_COLOR, CATEGORIES, CHILD_NODE_KEYS, type Category, type Classification, type CompiledOverride, type ComponentFacts, type Config, type ConsoleReportOptions, type Detection, type EachBlockFact, type EffectFact, type Fix, type HeadProvider, type HeadTag, type HeadingInfo, type HealthResult, type ImageInfo, type JsonReport, type KitAlias, type KitModuleFacts, type OrphanEffectFact, type Palette, type Presence, type Project, ROBOTS_SOURCE_PATHS, type RawKitAliases, type ResolvedHead, type ResolvedHeadings, type ResolvedImages, type Result, type RouteBadge, type Rule, type RuleContext, type RuleEvidence, type RuleInfo, type RuleOptionInfo, type RuleOptionSpec, type RuleOptions, type RuleOptionsSpec, type RuleOverride, type RuleSetting, type RuleSettingObject, type Runtime, SITEMAP_SOURCE_PATHS, SVELTE_CONFIG_FILES, type Scope, type ScoreModel, type ScoreOptions, type ScoreResult, type Severity, type SourceSpan, type Summary, type SuppressionDirective, type TreatDynamicAs, VITE_CONFIG_FILES, type Value, type ViteKitConfigResult, allRules, applyOverrides, applyRuleSeverities, architectureComponentSize, architectureDirectoryNaming, architectureDocLinkTarget, architecturePrivateScopeImport, architecturePropCount, architectureReservedDirectoryNames, architectureRouteComponentImport, architectureUnitEntryFile, attrText, attrTextOf, attrValue, attrValueOf, buildHtmlDocument, buildJsonReport, classify, collectComponentFacts, collectKitModuleFacts, collectSourceFiles, compileOverrides, computeHealth, computeScore, correctnessBasePathNavigation, correctnessCheckableBindValue, correctnessEachIndexKey, correctnessEachKey, correctnessEffectAsDerived, correctnessEffectAsOnMount, correctnessInstanceBrowserGlobal, correctnessNonreactiveBuiltinState, correctnessOrphanEffect, correctnessOrphanLifecycle, correctnessPropMutation, correctnessServerBrowserGlobal, correctnessStalePropDerivation, correctnessUnmutatedState, defaultConfig, defaultProject, defineConfig, docsUrlFor, effectiveSeverity, emptyComponentFacts, emptyKitModuleFacts, escapeHtml, explainRule, findAttr, findKitAliasesInSvelteConfig, findKitPathsBaseInSvelteConfig, findKitPathsBaseInViteConfig, findMinifyDisabled, formatAgentReport, formatConsoleReport, formatGithubReport, formatHtmlReport, formatJsonReport, formatMarkdownReport, formatSarifReport, hasFailureAtOrAbove, headTagRule, imageRule, intOption, isMentionedAnywhere, isPenalized, lineOf, linkRule, listOption, mapOption, noColorPalette, overrideMatches, parseComponentFacts, parseKitModuleFacts, performanceFontPreloadCrossorigin, performanceHeavyImport, performanceImageDimensions, performanceImageLoadingHint, performanceLcpImage, performanceLoadWaterfall, performanceMinifyDisabled, performanceNamespaceImport, performancePreconnect, performancePreloadMissingAs, performanceRenderBlockingScript, performanceResponsiveImage, performanceSequentialAwaits, performanceStateRaw, renderAppShell, resolveKitAliases, resolveKitPathsBase, resolveRuleOptions, resolveRunesModuleSpecifier, runRules, safeHref, scoreBand, scoreColor, scoresByCategory, securityHandlerStateWrite, securityJavascriptUrl, securityRawHtml, securityServerModuleState, securitySharedStateImport, selectRules, seoCanonicalUrl, seoCharset, seoDescriptionLength, seoDescriptionPresence, seoDuplicateDescription, seoDuplicateTitle, seoHeadingLevelSkip, seoHreflang, seoHtmlLang, seoImageAlt, seoIndexability, seoJsonLd, seoJsonLdDateFormat, seoJsonLdDeprecatedType, seoJsonLdPlaceholder, seoJsonLdRelativeUrl, seoJsonLdRequiredProps, seoJsonLdValidity, seoOgDescription, seoOgImage, seoOgTitle, seoOgUrl, seoRobotsTxt, seoSingleH1, seoSitemapInRobots, seoSitemapXml, seoSsrDisabled, seoTitleLength, seoTitlePresence, seoTwitterCard, seoViewport, settingOptions, settingSeverity, shouldSkipRangeCheck, summarize, textFromNodes, validateRuleOptions, validateRuleSetting, valueFromNodes };

package/dist/index.js

@@ -904,6 +904,53 @@ function collectSuppressions(source) {
   });
   return out;
 }
+var MD_LINK = /\[[^\]]*\]\(([^)\s]+)\)/g;
+var SCRIPT_OPEN = /<script(?:\s[^>]*)?>/;
+var SCRIPT_CLOSE = /<\/script\s*>/;
+var STYLE_OPEN = /<style(?:\s[^>]*)?>/;
+var STYLE_CLOSE = /<\/style\s*>/;
+function collectCommentLinks(source, { wholeFileIsScript = false } = {}) {
+  const out = [];
+  let htmlOpen = false;
+  let block = wholeFileIsScript ? "script" : void 0;
+  source.split("\n").forEach((line, i) => {
+    let text = "";
+    if (block !== void 0) {
+      if (block === "script" && /^\s*\/\//.test(line)) text = line.replace(/^\s*\/\//, "");
+      if (!wholeFileIsScript && (block === "script" ? SCRIPT_CLOSE : STYLE_CLOSE).test(line)) block = void 0;
+    } else {
+      let plain = "";
+      let rest = line;
+      while (rest.length > 0) {
+        if (htmlOpen) {
+          const end = rest.indexOf("-->");
+          if (end === -1) {
+            text += rest;
+            break;
+          }
+          text += rest.slice(0, end);
+          htmlOpen = false;
+          rest = rest.slice(end + 3);
+          continue;
+        }
+        const start = rest.indexOf("<!--");
+        if (start === -1) {
+          plain += rest;
+          break;
+        }
+        plain += rest.slice(0, start);
+        htmlOpen = true;
+        rest = rest.slice(start + 4);
+      }
+      const opened = SCRIPT_OPEN.test(plain) ? "script" : STYLE_OPEN.test(plain) ? "style" : void 0;
+      if (opened !== void 0 && !(opened === "script" ? SCRIPT_CLOSE : STYLE_CLOSE).test(plain)) block = opened;
+    }
+    for (const m of text.matchAll(MD_LINK)) {
+      if (m[1] !== void 0) out.push({ url: m[1], line: i + 1 });
+    }
+  });
+  return out;
+}
 var EVAL_SCOPE_BOUNDARIES = /* @__PURE__ */ new Set([
   "FunctionDeclaration",
   "FunctionExpression",
@@ -1274,6 +1321,7 @@ function parseModuleFacts(source, filename) {
     checkableBindValues: [],
     basePathLinks,
     suppressions: collectSuppressions(source),
+    commentLinks: collectCommentLinks(source, { wholeFileIsScript: true }),
     orphanEffects,
     orphanLifecycleCalls,
     browserGlobalRefs,
@@ -1480,7 +1528,8 @@ function parseComponentFacts(source, filename) {
     orphanLifecycleCalls,
     browserGlobalRefs,
     moduleStateDecls: [],
-    suppressions
+    suppressions,
+    commentLinks: collectCommentLinks(source)
   };
 }
 
@@ -1508,7 +1557,8 @@ function emptyComponentFacts(file) {
     orphanLifecycleCalls: [],
     browserGlobalRefs: [],
     moduleStateDecls: [],
-    suppressions: []
+    suppressions: [],
+    commentLinks: []
   };
 }
 async function collectComponentFacts(rt, cwd) {
@@ -5416,6 +5466,60 @@ var architectureRouteComponentImport = componentRule({
   }
 });
 
+// src/rules/architecture/doc-link-target.ts
+var ID8 = "architecture/doc-link-target";
+function stripFragment(url) {
+  const i = url.search(/[#?]/);
+  return i === -1 ? url : url.slice(0, i);
+}
+function baseOf(root) {
+  return root.replace(/\/+$/, "");
+}
+function remainderUnder(url, root) {
+  const base = baseOf(root);
+  if (url === base) return "";
+  return url.startsWith(`${base}/`) ? baseOf(url.slice(base.length + 1)) : void 0;
+}
+function isUnderSrc(target) {
+  return target.startsWith("src/");
+}
+function rootFor(url, roots) {
+  let best;
+  for (const r of roots) {
+    const remainder = remainderUnder(url, r);
+    if (remainder === void 0) continue;
+    const base = baseOf(r);
+    if (best === void 0 || base.length > best.base.length) best = { base, remainder };
+  }
+  return best;
+}
+function targetExists(path, sourceFiles) {
+  const prefix = `${path}/`;
+  return sourceFiles.some((f) => f === path || f.startsWith(prefix));
+}
+function references(links, roots) {
+  const out = [];
+  for (const { url, line } of links) {
+    const match = rootFor(stripFragment(url), roots);
+    if (match === void 0) continue;
+    if (!isUnderSrc(match.remainder)) continue;
+    out.push({ line, target: match.remainder });
+  }
+  return out;
+}
+var architectureDocLinkTarget = componentRule({
+  id: ID8,
+  title: "Documentation link target",
+  category: "architecture",
+  severity: "info",
+  label: "Documentation link targets",
+  options: { urlRoots: { kind: "string-list", default: [] } },
+  recommendation: "Point the link at the unit that exists now, or remove it. A link inside a comment has nothing to resolve it, so a rename leaves it silently broken.",
+  rationale: "A documentation link written in a comment is invisible to type checking, module resolution and the test runner, so a convention-driven rename leaves it pointing at nothing and only human review notices.",
+  applies: (c, o, ctx) => ctx.sourceFiles !== void 0 && references(c.commentLinks, listOption(o, "urlRoots")).length > 0,
+  bad: (c, o, ctx) => references(c.commentLinks, listOption(o, "urlRoots")).filter(({ target }) => !targetExists(target, ctx.sourceFiles ?? [])).map(({ line, target }) => ({ line, message: `${target} does not exist` }))
+});
+
 // src/rules/perf/heavy-import.ts
 var HEAVY_PACKAGES = {
   lodash: "import a submodule (lodash/debounce) or use lodash-es for tree-shaking",
@@ -5632,6 +5736,7 @@ var allRules = [
   architectureDirectoryNaming,
   architectureReservedDirectoryNames,
   architectureRouteComponentImport,
+  architectureDocLinkTarget,
   performanceHeavyImport,
   performanceNamespaceImport,
   performanceMinifyDisabled,
@@ -5692,8 +5797,31 @@ function hasFailureAtOrAbove(summary, min) {
   return order.some((sev, idx) => idx >= threshold && summary[sev] > 0);
 }
 
-// src/scoring/score.ts
+// src/scoring/inventory.ts
 var DEDUCTION = { critical: 15, warning: 5, info: 1 };
+function pairKey(category, scope) {
+  return `${category}::${scope}`;
+}
+function severityOf(rule, config) {
+  const setting = settingSeverity(config.rules[rule.id]);
+  if (setting === "off") return void 0;
+  return setting ?? rule.severity;
+}
+function buildInventory(config, rules = selectRules(allRules, config)) {
+  const out = /* @__PURE__ */ new Map();
+  for (const rule of rules) {
+    const severity = severityOf(rule, config);
+    if (severity === void 0) continue;
+    const key = pairKey(rule.category, rule.scope);
+    out.set(key, (out.get(key) ?? 0) + DEDUCTION[severity]);
+  }
+  return out;
+}
+function ruleScopes(rules) {
+  return new Map(rules.map((r) => [r.id, pairKey(r.category, r.scope)]));
+}
+
+// src/scoring/score.ts
 var CRITICAL_CAP = 79;
 function clamp(n) {
   return Math.max(0, Math.min(100, n));
@@ -5701,27 +5829,36 @@ function clamp(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);
+  const rules = selectRules([...options.rules ?? allRules], config);
+  const inventory = buildInventory(config, rules);
+  const pairOf = ruleScopes(rules);
   let anyCritical = false;
-  const routeRuleMax = /* @__PURE__ */ new Map();
+  const observed = /* @__PURE__ */ new Map();
+  const ruleMax = /* @__PURE__ */ new Map();
   for (const r of routeResults) {
+    const key = r.route;
+    if (!observed.has(key)) observed.set(key, /* @__PURE__ */ new Set());
+    const pair = pairOf.get(r.id);
+    if (pair !== void 0) observed.get(key).add(pair);
     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());
+    let perRule = ruleMax.get(key);
+    if (!perRule) ruleMax.set(key, 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 rawRouteAverage = scores.length ? scores.reduce((a, b) => a + b, 0) / scores.length : 100;
+  let totalDeficit = 0;
+  for (const [key, pairs] of observed) {
+    let failed = 0;
+    for (const d of ruleMax.get(key)?.values() ?? []) failed += d;
+    let inventoryWeight = 0;
+    for (const p of pairs) inventoryWeight += inventory.get(p) ?? 0;
+    inventoryWeight = Math.max(inventoryWeight, failed);
+    totalDeficit += inventoryWeight === 0 ? 0 : 100 * failed / inventoryWeight;
+  }
+  const keyCount = observed.size;
+  const rawRouteAverage = keyCount === 0 ? 100 : 100 - totalDeficit / keyCount;
   const routeAverage = Math.floor(rawRouteAverage);
   const projectRuleMax = /* @__PURE__ */ new Map();
   for (const r of projectResults) {
@@ -5941,9 +6078,20 @@ function issueOf(result) {
     ...result.fix ? { fix: result.fix } : {}
   };
 }
-function buildJsonReport(results, config, meta) {
+function ruleEvidence(results, config, ruleIds) {
+  const out = {};
+  for (const id of ruleIds ?? []) out[id] = { findings: 0, passed: 0 };
+  for (const r of results) {
+    const entry = out[r.id] ??= { findings: 0, passed: 0 };
+    if (isPenalized(r.detection, config.treatDynamicAs)) entry.findings += 1;
+    else entry.passed += 1;
+  }
+  return out;
+}
+function buildJsonReport(results, config, meta, ruleIds) {
   const { health, categories: byCat, weights } = computeHealth(results, config);
   const summary = summarize(results, config);
+  const rules = ruleEvidence(results, config, ruleIds);
   const categories = Object.fromEntries(
     Object.entries(byCat).map(([cat, sr]) => [cat, { score: sr.score, scoreModel: sr.scoreModel }])
   );
@@ -5959,10 +6107,10 @@ 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: health, weights, categories, summary, routes, siteIssues };
+  return { version: meta.version, score: health, weights, categories, summary, rules, routes, siteIssues };
 }
-function formatJsonReport(results, config, meta) {
-  return JSON.stringify(buildJsonReport(results, config, meta), null, 2);
+function formatJsonReport(results, config, meta, ruleIds) {
+  return JSON.stringify(buildJsonReport(results, config, meta, ruleIds), null, 2);
 }
 
 // src/reporter/agent.ts
@@ -6896,6 +7044,7 @@ export {
   applyRuleSeverities,
   architectureComponentSize,
   architectureDirectoryNaming,
+  architectureDocLinkTarget,
   architecturePrivateScopeImport,
   architecturePropCount,
   architectureReservedDirectoryNames,

package/package.json

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