perfgraph 0.1.0

package/dist/report/markdown.js

@@ -0,0 +1,182 @@
+/**
+ * Markdown report generator — produces a human-readable performance report
+ * from a PerfGraph {@link Report} and optional {@link Insights}.
+ *
+ * The output is designed for direct consumption by developers and includes
+ * score summary, all issues with severities, causal chains, recommendations,
+ * and Lighthouse insights when available.
+ *
+ * @packageDocumentation
+ */
+// ---------------------------------------------------------------------------
+// Severity → emoji helpers
+// ---------------------------------------------------------------------------
+function severityBadge(severity) {
+    switch (severity) {
+        case 'critical':
+            return '🔴';
+        case 'warning':
+            return '🟡';
+        case 'high':
+            return '🟡';
+        case 'info':
+            return '🔵';
+        default:
+            return '⚪';
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Generate a human-readable markdown report from a PerfGraph Report + Insights.
+ *
+ * @param report - The structured report from `buildReport()`
+ * @param insights - Optional Lighthouse-derived insights from `buildInsights()`
+ * @returns A formatted Markdown string
+ */
+export function buildReportMarkdown(report, insights) {
+    const lines = [];
+    // -----------------------------------------------------------------------
+    // Header
+    // -----------------------------------------------------------------------
+    lines.push('# PerfGraph Performance Report');
+    lines.push('');
+    lines.push(`**URL:** ${report.meta.url}`);
+    lines.push(`**Analyzed at:** ${report.meta.analyzedAt}`);
+    lines.push(`**Score:** ${report.summary.score.toUpperCase()}`);
+    if (report.summary.lighthousePerformance != null) {
+        lines.push(`**Lighthouse Performance:** ${(report.summary.lighthousePerformance * 100).toFixed(0)}/100`);
+    }
+    if (report.summary.scoreExplanation) {
+        lines.push(`**Note:** ${report.summary.scoreExplanation}`);
+    }
+    lines.push('');
+    // -----------------------------------------------------------------------
+    // Summary stats
+    // -----------------------------------------------------------------------
+    lines.push('## Summary');
+    lines.push('');
+    lines.push('| Metric | Count |');
+    lines.push('|--------|-------|');
+    lines.push(`| Critical issues | ${report.summary.criticalIssues} |`);
+    lines.push(`| Warnings | ${report.summary.warnings} |`);
+    lines.push(`| Info | ${report.summary.infos} |`);
+    lines.push('');
+    // -----------------------------------------------------------------------
+    // Top Issues
+    // -----------------------------------------------------------------------
+    if (report.summary.topIssues.length > 0) {
+        lines.push('## Top Issues');
+        lines.push('');
+        for (const issue of report.summary.topIssues) {
+            lines.push(`### ${severityBadge(issue.severity)} ${issue.label}`);
+            lines.push('');
+            lines.push(`- **Confidence:** ${issue.confidence}`);
+            lines.push('');
+        }
+    }
+    // -----------------------------------------------------------------------
+    // All Issues
+    // -----------------------------------------------------------------------
+    if (report.issues.length > 0) {
+        lines.push('## All Issues');
+        lines.push('');
+        for (const issue of report.issues) {
+            lines.push(`### ${severityBadge(issue.severity)} ${issue.label}`);
+            lines.push('');
+            lines.push(`**ID:** \`${issue.id}\``);
+            lines.push(`**Severity:** ${issue.severity}`);
+            if (issue.value != null) {
+                lines.push(`**Value:** ${issue.value}${issue.unit ? ` ${issue.unit}` : ''}`);
+            }
+            if (issue.evidence?.urls && issue.evidence.urls.length > 0) {
+                lines.push('**URLs:**');
+                for (const url of issue.evidence.urls) {
+                    lines.push(`- \`${url}\``);
+                }
+            }
+            if (issue.evidence?.selector) {
+                lines.push(`**Selector:** \`${issue.evidence.selector}\``);
+            }
+            lines.push('');
+            lines.push(issue.remediation);
+            lines.push('');
+            lines.push('---');
+            lines.push('');
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Causal Chains
+    // -----------------------------------------------------------------------
+    if (report.chains.length > 0) {
+        lines.push('## Causal Chains');
+        lines.push('');
+        for (const chain of report.chains) {
+            lines.push(`### ${severityBadge(chain.severity)} ${chain.rootCause}`);
+            lines.push('');
+            lines.push(`**Impact:** ${chain.impact}`);
+            lines.push(`**Confidence:** ${chain.confidence}`);
+            lines.push(`**Path:** \`${chain.path.map((n) => n.label).join(' → ')}\``);
+            lines.push('');
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Recommendations
+    // -----------------------------------------------------------------------
+    if (report.recommendations.length > 0) {
+        lines.push('## Recommendations');
+        lines.push('');
+        for (const rec of report.recommendations) {
+            const badge = severityBadge(rec.priority);
+            lines.push(`### ${badge} [${rec.category}] ${rec.title}`);
+            lines.push('');
+            lines.push(rec.action);
+            if (rec.expectedImpact) {
+                lines.push('');
+                lines.push(`**Expected impact:** ${rec.expectedImpact}`);
+            }
+            lines.push('');
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Lighthouse Insights
+    // -----------------------------------------------------------------------
+    if (insights?.lighthouse) {
+        lines.push('## Lighthouse Insights');
+        lines.push('');
+        lines.push('| Metric | Value |');
+        lines.push('|--------|-------|');
+        if (insights.lighthouse.performance != null) {
+            lines.push(`| Performance | ${(insights.lighthouse.performance * 100).toFixed(0)} |`);
+        }
+        if (insights.lighthouse.lcpMs != null) {
+            lines.push(`| LCP | ${insights.lighthouse.lcpMs} ms |`);
+        }
+        if (insights.lighthouse.fcpMs != null) {
+            lines.push(`| FCP | ${insights.lighthouse.fcpMs} ms |`);
+        }
+        if (insights.lighthouse.cls != null) {
+            lines.push(`| CLS | ${insights.lighthouse.cls.toFixed(3)} |`);
+        }
+        if (insights.lighthouse.tbtMs != null) {
+            lines.push(`| TBT | ${insights.lighthouse.tbtMs} ms |`);
+        }
+        lines.push('');
+        if (insights.lcpElement) {
+            lines.push(`**LCP Element:** \`${insights.lcpElement.selector}\``);
+            lines.push('');
+        }
+        if (insights.renderBlocking && insights.renderBlocking.length > 0) {
+            lines.push(`**Render-blocking resources:** ${insights.renderBlocking.length} total`);
+            lines.push('');
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Footer
+    // -----------------------------------------------------------------------
+    lines.push('---');
+    lines.push(`*Generated by PerfGraph at ${report.meta.analyzedAt}*`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=markdown.js.map

package/dist/report/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../../src/report/markdown.ts"],"names":[],"mappings":"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"}

package/dist/report/remediations.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Remediation texts — lookup table of human-readable recommendations
+ * keyed by node ID or node type / rule ID patterns.
+ *
+ * Each entry is a plain-English suggestion for fixing the issue.
+ *
+ * @packageDocumentation
+ */
+export interface RemediationContext {
+    /** Evidence payload (URLs, selector, lighthouse audit, metric) */
+    evidence?: {
+        urls?: string[];
+        selector?: string;
+        lighthouseAuditId?: string;
+        metric?: {
+            name: string;
+            value: number;
+            unit: string;
+        };
+    };
+    /** The issue's value/metric for context (e.g. TTFB=1200) */
+    value?: number;
+    /** Unit label for the value */
+    unit?: string;
+    /** Node type for fallback lookup (metric, bottleneck, impact) */
+    nodeType?: string;
+    /** Rule ID for fallback lookup by prefix */
+    ruleId?: string;
+}
+/**
+ * Get remediation text for an issue by its ID, with optional evidence context
+ * to produce parameterized, specific guidance.
+ *
+ * When `context` provides evidence (URLs, metric values), the returned text
+ * includes those details. Without context, falls back to static boilerplate
+ * then to rule-prefix and node-type fallbacks.
+ *
+ * @param issueId - The issue / node ID to remediate
+ * @param context - Optional evidence, values, and fallback hints
+ */
+export declare function getRemediation(issueId: string, context?: RemediationContext): string;
+//# sourceMappingURL=remediations.d.ts.map

package/dist/report/remediations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remediations.d.ts","sourceRoot":"","sources":["../../src/report/remediations.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,MAAM,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;KACxD,CAAC;IACF,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAoID;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,kBAAkB,GAC3B,MAAM,CAsFR"}

package/dist/report/remediations.js

@@ -0,0 +1,179 @@
+/**
+ * Remediation texts — lookup table of human-readable recommendations
+ * keyed by node ID or node type / rule ID patterns.
+ *
+ * Each entry is a plain-English suggestion for fixing the issue.
+ *
+ * @packageDocumentation
+ */
+const REMEDIATIONS = {
+    // ---- LCP rules ----
+    'high-ttfb': 'Optimise TTFB: use a CDN, enable server-side caching, ' +
+        'move static assets to the edge, optimise server logic (fastify/compression). ' +
+        'Target: TTFB < 800ms.',
+    'delayed-html-parse': 'Ensure HTML is streamed without delay — enable chunked transfer encoding, ' +
+        'remove blocking middleware on the server.',
+    'delayed-css-discovery': 'Inline critical CSS in <head>, load non-critical CSS asynchronously ' +
+        'via <link rel="preload" as="style" ...> + onload=this.rel="stylesheet".',
+    'blocked-render': 'Eliminate render-blocking resources: inline critical CSS, async/defer for JS, ' +
+        'preconnect to third-party origins.',
+    'increased-lcp': 'Optimise LCP: ensure the LCP element loads early, use modern image formats ' +
+        '(WebP/AVIF) with correct dimensions, ' +
+        'add fetchpriority="high" on the LCP image.',
+    'rb-resources': 'Reduce the number of render-blocking resources: inline critical CSS, ' +
+        'defer non-critical CSS via media="print" onload, use async/defer for scripts.',
+    'blocked-render-rb': 'Analyse the render-blocking resource chain in DevTools (Performance → View: KPI Warning). ' +
+        'Move non-critical CSS/JS off the critical path.',
+    'increased-lcp-rb': 'Use Lighthouse "Eliminate render-blocking resources" for precise recommendations. ' +
+        'Consider code splitting and lazy loading for non-critical scripts.',
+    'lcp-resource-delay': 'Optimise LCP resource loading: use preload <link rel="preload"> for the LCP image, ' +
+        'set fetchpriority="high", optimise the resource itself (compression, modern formats).',
+    'increased-lcp-resource': 'Check that the LCP resource is not blocked by other loads. ' +
+        'Use HTTP/2 Server Push (with caution) or early preload.',
+    // ---- Network rules ----
+    'deep-critical-chain': 'Reduce critical chain depth: bundle scripts, use code splitting, ' +
+        'lazy-load non-critical resources. A Webpack/Rollup bundle analyser helps find optimisations.',
+    'waterfall-delay': 'Analyse the load waterfall in DevTools (Network → Waterfall). ' +
+        'Eliminate sequential loads, use preload/preconnect ' +
+        'for critical resources.',
+    'slow-page-load': 'General slow page load: use Lighthouse to prioritise improvements. ' +
+        'Focus on TTFB, render-blocking resources, image optimisation, and JS bundle size.',
+    'excessive-requests': 'Reduce the number of requests on the critical path: bundle files, use ' +
+        'sprites/SVG, HTTP/2 multiplexing, tree shaking, code splitting.',
+    'bandwidth-contention': 'Reduce bandwidth contention: prioritise critical resources (preload), ' +
+        'defer non-critical ones (lazy load, async/defer), use HTTP/2.',
+    // ---- JS rules ----
+    'high-main-thread-blocking': 'Reduce main thread blocking: break up long tasks (<50ms), use ' +
+        'Web Workers for background computation, remove heavy polyfills.',
+    'high-tbt': 'Use Lighthouse "Reduce JavaScript execution time" for precise recommendations. ' +
+        'Optimise heavy scripts, remove dead code (tree shaking).',
+    'delayed-inp-tbt': 'INP may be high due to long tasks: break tasks into 50ms chunks with ' +
+        'setTimeout(yield) or scheduler.postTask(). Use Browser Timeline to find culprits.',
+    'js-hotspots': 'Profile JS hotspots in DevTools (Performance → Main thread). ' +
+        'Optimise hot functions, use debounce/throttle for frequent handlers.',
+    'long-tasks-js': 'Long tasks block the main thread and delay interaction: ' +
+        'break into micro-tasks, use Web Workers, optimise rendering.',
+    'delayed-inp-hotspots': 'Improve INP: use passive event listeners, eliminate scroll jank, ' +
+        'optimise animations via requestAnimationFrame.',
+    'many-scripts': 'Reduce the number of scripts: bundle modules, use code splitting, ' +
+        'tree shaking, remove unused dependencies.',
+    'long-parse-time': 'Long JS parse/compile time: use code splitting, lazy loading, ' +
+        'remove unused code. Modern bundlers (esbuild/swc) reduce compilation time.',
+    // ---- Layout rules ----
+    'layout-shifts': 'Fix layout shifts: set explicit dimensions (width/height) on images and iframes, ' +
+        'use aspect-ratio CSS, reserve space for dynamic content.',
+    'high-cls': 'Use Lighthouse "Avoid large layout shifts" for precise recommendations. ' +
+        'Inline critical CSS, avoid inserting content above existing content (insertBefore).',
+    'layout-shift-clusters': 'Shift clusters indicate dynamic content insertion problems: ' +
+        'use CSS contain, reserve space, avoid DOM mutations above visible content.',
+    'complex-dom-tree': 'DOM tree is too complex: reduce nesting, use simpler semantic ' +
+        'markup, virtualise large lists (Virtual Scroller).',
+    'layout-instability': 'Use CSS contain: layout to isolate each component. ' +
+        'This limits layout recalculation scope on changes.',
+};
+// Fallback by node type
+const TYPE_FALLBACKS = {
+    metric: 'Analyse this metric against your project baseline. ' +
+        'Target compliance with Google Core Web Vitals.',
+    bottleneck: 'Eliminate this bottleneck: it may cascade into other metric regressions.',
+    impact: 'This metric indicates a negative impact on user experience. ' +
+        'Fix the root causes listed in the dependency chain.',
+};
+// Fallback by rule ID prefix
+const RULE_FALLBACKS = {
+    lcp: 'Check Lighthouse recommendations for Largest Contentful Paint improvements (Performance → LCP).',
+    net: 'Optimise network resource loading: reduce request count, ' +
+        'use HTTP/2, preload critical resources.',
+    js: 'Optimise JavaScript: reduce bundle size, use code splitting, ' +
+        'remove dead code, break up long tasks.',
+    layout: 'Stabilise the layout: set element dimensions, avoid unexpected ' +
+        'content insertion, use CSS contain.',
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Get remediation text for an issue by its ID, with optional evidence context
+ * to produce parameterized, specific guidance.
+ *
+ * When `context` provides evidence (URLs, metric values), the returned text
+ * includes those details. Without context, falls back to static boilerplate
+ * then to rule-prefix and node-type fallbacks.
+ *
+ * @param issueId - The issue / node ID to remediate
+ * @param context - Optional evidence, values, and fallback hints
+ */
+export function getRemediation(issueId, context) {
+    // ---- Parameterized remediations (evidence-aware) ----
+    if (context) {
+        // Render-blocking resources with specific URLs
+        if (issueId === 'rb-resources' && context.evidence?.urls && context.evidence.urls.length > 0) {
+            const urls = context.evidence.urls.join(', ');
+            return `Render-blocking resources: ${urls}. Consider inlining critical CSS, deferring non-critical stylesheets, and adding preload hints.`;
+        }
+        // TTFB with measured value
+        if (issueId === 'high-ttfb' && context.value != null) {
+            return `High TTFB (${context.value}ms). Optimize server response time: use CDN, enable caching, upgrade hosting, or move server closer to users.`;
+        }
+        // Deep critical chain with URLs
+        if (issueId === 'deep-critical-chain' && context.evidence?.urls && context.evidence.urls.length > 0) {
+            return `Deep critical chain (${context.value ?? '?'} levels): ${context.evidence.urls.join(' → ')}. Optimize dependency ordering and lazy-load non-critical resources.`;
+        }
+        // Layout shifts with CLS value
+        if (issueId === 'layout-shifts' && context.value != null) {
+            return `Layout shifts detected (CLS: ${context.value.toFixed(3)}). Ensure all elements have explicit dimensions, avoid inserting content above existing content.`;
+        }
+        // CLS with value
+        if (issueId === 'high-cls' && context.value != null) {
+            return `High CLS (${context.value.toFixed(3)}). Use Lighthouse "Avoid large layout shifts" for precise recommendations. Inline critical CSS, avoid inserting content above existing content (insertBefore).`;
+        }
+        // Main thread blocking with value
+        if (issueId === 'high-main-thread-blocking' && context.value != null) {
+            return `High main thread blocking (${context.value}ms). Break up long tasks, defer non-critical JavaScript, use web workers for heavy computation.`;
+        }
+        // Render-blocking chain with URLs
+        if (issueId === 'rb-chain' && context.evidence?.urls && context.evidence.urls.length > 0) {
+            const urls = context.evidence.urls.join(', ');
+            return `Render-blocking chain: ${urls}. Analyse the waterfall in DevTools (Performance → View: KPI Warning). Move unused CSS/JS off the critical path.`;
+        }
+        // Render-blocking LCP with URLs
+        if (issueId === 'render-blocking-lcp' && context.evidence?.urls && context.evidence.urls.length > 0) {
+            const urls = context.evidence.urls.join(', ');
+            return `Render-blocking resources delaying LCP: ${urls}. Use Lighthouse "Eliminate render-blocking resources" for precise recommendations. Consider code splitting and lazy loading for non-critical scripts.`;
+        }
+        // Increased LCP with value
+        if (issueId === 'increased-lcp' && context.value != null) {
+            return `LCP is high (${context.value}ms). Optimise the LCP element: ensure it loads early, use modern image formats (WebP/AVIF) with correct dimensions, add fetchpriority="high" on the LCP image.`;
+        }
+        // High TBT with value
+        if (issueId === 'high-tbt' && context.value != null) {
+            return `High Total Blocking Time (${context.value}ms). Use Lighthouse "Reduce JavaScript execution time" for precise recommendations. Optimise heavy scripts, remove dead code (tree shaking).`;
+        }
+        // Waterfall delay with URLs
+        if (issueId === 'waterfall-delay' && context.evidence?.urls && context.evidence.urls.length > 0) {
+            const urls = context.evidence.urls.join(', ');
+            return `Sequential waterfall detected: ${urls}. Analyse the Network waterfall in DevTools, use preload/preconnect for critical resources.`;
+        }
+    }
+    // ---- Static exact match ----
+    if (REMEDIATIONS[issueId]) {
+        return REMEDIATIONS[issueId];
+    }
+    // ---- Rule-based fallback ----
+    const ruleId = context?.ruleId;
+    if (ruleId) {
+        for (const [prefix, text] of Object.entries(RULE_FALLBACKS)) {
+            if (ruleId.startsWith(prefix)) {
+                return text;
+            }
+        }
+    }
+    // ---- Type-based fallback ----
+    const nodeType = context?.nodeType;
+    if (nodeType && TYPE_FALLBACKS[nodeType]) {
+        return TYPE_FALLBACKS[nodeType];
+    }
+    return 'Diagnose the issue with Chrome DevTools (Performance → Measure → Reload) ' +
+        'and follow Lighthouse recommendations.';
+}
+//# sourceMappingURL=remediations.js.map

package/dist/report/remediations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remediations.js","sourceRoot":"","sources":["../../src/report/remediations.ts"],"names":[],"mappings":"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"}

package/dist/report/scorer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Report scoring — compute overall performance score from CausalGraph.
+ *
+ * The score is a simple heuristic based on severity distribution:
+ *   - Any critical nodes → "poor"
+ *   - Any warning nodes  → "moderate"
+ *   - Info only / empty  → "good"
+ *
+ * Optionally accepts a Lighthouse performance score to override the
+ * heuristic when Lighthouse indicates acceptable performance despite
+ * causal-rule triggers (e.g., 2 small render-blocking stylesheets).
+ *
+ * @packageDocumentation
+ */
+import type { CausalGraph } from '../causal/types.js';
+import type { ReportScore } from './types.js';
+/**
+ * Compute overall performance score from a CausalGraph.
+ *
+ * When `lighthousePerformance` is provided the score may be promoted:
+ *   - Lighthouse >= 0.9 and no genuine regression → "good"
+ *   - Lighthouse >= 0.7, criticalCount <= 1, no genuine regression → "moderate"
+ *   - Otherwise the heuristic score is returned unchanged.
+ *
+ * @param graph - The causal graph to evaluate
+ * @param lighthousePerformance - Optional Lighthouse performance score (0–1)
+ * @returns A string score when called without lighthouse data; otherwise
+ *          either a string or an object with `score` and optional `explanation`.
+ */
+export declare function computeScore(graph: CausalGraph): ReportScore;
+export declare function computeScore(graph: CausalGraph, lighthousePerformance?: number): ReportScore | {
+    score: ReportScore;
+    explanation?: string;
+};
+//# sourceMappingURL=scorer.d.ts.map

package/dist/report/scorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scorer.d.ts","sourceRoot":"","sources":["../../src/report/scorer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAc,MAAM,oBAAoB,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA2B9C;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CAAC;AAC9D,wBAAgB,YAAY,CAC1B,KAAK,EAAE,WAAW,EAClB,qBAAqB,CAAC,EAAE,MAAM,GAC7B,WAAW,GAAG;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/dist/report/scorer.js

@@ -0,0 +1,72 @@
+/**
+ * Report scoring — compute overall performance score from CausalGraph.
+ *
+ * The score is a simple heuristic based on severity distribution:
+ *   - Any critical nodes → "poor"
+ *   - Any warning nodes  → "moderate"
+ *   - Info only / empty  → "good"
+ *
+ * Optionally accepts a Lighthouse performance score to override the
+ * heuristic when Lighthouse indicates acceptable performance despite
+ * causal-rule triggers (e.g., 2 small render-blocking stylesheets).
+ *
+ * @packageDocumentation
+ */
+/**
+ * Check whether a node represents a genuinely bad performance regression,
+ * as opposed to a rule-triggered flag. Used to decide whether Lighthouse
+ * data should override the heuristic score.
+ *
+ * A genuine regression is:
+ *   - Any node (metric or impact) with a value > 4000 (e.g. LCP > 4 s)
+ *   - Any ms-valued node with a value > 2500 (e.g. TTFB > 2.5 s)
+ */
+function isGenuineRegression(node) {
+    if (node.value == null)
+        return false;
+    // Any value above 4000 is a clear regression regardless of semantics
+    if (node.value > 4000)
+        return true;
+    // ms-valued metrics above 2500 are "poor" by Google thresholds
+    if (node.unit === 'ms' && node.value > 2500)
+        return true;
+    return false;
+}
+function hasGenuineRegression(nodes) {
+    return nodes.some(isGenuineRegression);
+}
+export function computeScore(graph, lighthousePerformance) {
+    let criticalCount = 0;
+    let warningCount = 0;
+    for (const node of graph.nodes) {
+        if (node.severity === 'critical') {
+            criticalCount++;
+        }
+        if (node.severity === 'warning') {
+            warningCount++;
+        }
+    }
+    // When Lighthouse data is available, consider overriding the heuristic
+    if (lighthousePerformance !== undefined) {
+        const genuineRegression = hasGenuineRegression(graph.nodes);
+        if (lighthousePerformance >= 0.9 && !genuineRegression) {
+            return {
+                score: 'good',
+                explanation: 'Lighthouse performance >= 0.9, no genuine regressions detected',
+            };
+        }
+        if (lighthousePerformance >= 0.7 && criticalCount <= 1 && !genuineRegression) {
+            return {
+                score: 'moderate',
+                explanation: 'Lighthouse performance >= 0.7, minimal critical issues, no genuine regressions',
+            };
+        }
+    }
+    // Fallback heuristic (unchanged from original)
+    if (criticalCount > 0)
+        return 'poor';
+    if (warningCount > 0)
+        return 'moderate';
+    return 'good';
+}
+//# sourceMappingURL=scorer.js.map

package/dist/report/scorer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scorer.js","sourceRoot":"","sources":["../../src/report/scorer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH;;;;;;;;GAQG;AACH,SAAS,mBAAmB,CAAC,IAAgB;IAC3C,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI;QAAE,OAAO,KAAK,CAAC;IAErC,qEAAqE;IACrE,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI;QAAE,OAAO,IAAI,CAAC;IAEnC,+DAA+D;IAC/D,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI;QAAE,OAAO,IAAI,CAAC;IAEzD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAmB;IAC/C,OAAO,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;AACzC,CAAC;AAoBD,MAAM,UAAU,YAAY,CAC1B,KAAkB,EAClB,qBAA8B;IAE9B,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,IAAI,YAAY,GAAG,CAAC,CAAC;IAErB,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC/B,IAAI,IAAI,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;YACjC,aAAa,EAAE,CAAC;QAClB,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YAChC,YAAY,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;IAED,uEAAuE;IACvE,IAAI,qBAAqB,KAAK,SAAS,EAAE,CAAC;QACxC,MAAM,iBAAiB,GAAG,oBAAoB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAE5D,IAAI,qBAAqB,IAAI,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACvD,OAAO;gBACL,KAAK,EAAE,MAAM;gBACb,WAAW,EACT,gEAAgE;aACnE,CAAC;QACJ,CAAC;QAED,IAAI,qBAAqB,IAAI,GAAG,IAAI,aAAa,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC;YAC7E,OAAO;gBACL,KAAK,EAAE,UAAU;gBACjB,WAAW,EACT,gFAAgF;aACnF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,+CAA+C;IAC/C,IAAI,aAAa,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC;IACrC,IAAI,YAAY,GAAG,CAAC;QAAE,OAAO,UAAU,CAAC;IACxC,OAAO,MAAM,CAAC;AAChB,CAAC"}