perfgraph 0.1.0

package/dist/causal/rules/js.js

@@ -0,0 +1,209 @@
+/**
+ * JavaScript / Main Thread causal rules.
+ *
+ * Chains covered:
+ *   1. Long main thread blocking → high TBT → delayed INP
+ *   2. Excessive JS → long parse time → main thread contention
+ *   3. JS execution hotspots → long tasks → blocking
+ *
+ * @packageDocumentation
+ */
+// ---------------------------------------------------------------------------
+// Thresholds
+// ---------------------------------------------------------------------------
+const TBT_WARN = 200; // ms
+const TBT_CRIT = 600; // ms
+const LONG_TASK_WARN = 5;
+const LONG_TASK_CRIT = 15;
+const BOOTUP_WARN = 2_000; // ms total JS bootup time
+const BOOTUP_CRIT = 5_000;
+const EVALUATED_SCRIPTS_WARN = 50;
+const EVALUATED_SCRIPTS_CRIT = 150;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function confidenceFromDelta(value, warn, crit) {
+    if (value >= crit)
+        return 'strong';
+    if (value >= warn)
+        return 'medium';
+    return 'weak';
+}
+// ---------------------------------------------------------------------------
+// Rule 1: Main thread blocking → TBT → INP
+// ---------------------------------------------------------------------------
+export const tbtInpChain = {
+    id: 'js-tbt-inp-chain',
+    label: 'Main thread blocking → high TBT → delayed INP',
+    applies(features) {
+        const mt = features.mainThreadBlocking;
+        return mt != null && mt.blockingScore > 0.3;
+    },
+    build(features) {
+        const mt = features.mainThreadBlocking;
+        const busyMs = mt.busyMs;
+        const conf = confidenceFromDelta(busyMs, 300, 1000);
+        const mtbEvidence = {
+            metric: { name: 'Main thread blocking', value: busyMs, unit: 'ms' },
+        };
+        const nodes = [
+            {
+                id: 'high-main-thread-blocking',
+                label: `Main thread blocked (${Math.round(busyMs)}ms)`,
+                type: 'metric',
+                severity: busyMs >= 1000 ? 'critical' : busyMs >= 300 ? 'warning' : 'info',
+                value: busyMs,
+                unit: 'ms',
+                threshold: 300,
+                evidence: mtbEvidence,
+            },
+            {
+                id: 'high-tbt',
+                label: 'High Total Blocking Time',
+                type: 'bottleneck',
+                severity: busyMs >= 1000 ? 'critical' : 'warning',
+                value: busyMs,
+                unit: 'ms',
+                threshold: TBT_WARN,
+            },
+            {
+                id: 'delayed-inp-tbt',
+                label: 'Possible INP delay',
+                type: 'impact',
+                severity: 'warning',
+            },
+        ];
+        const edges = [
+            {
+                source: 'high-main-thread-blocking',
+                target: 'high-tbt',
+                confidence: conf,
+                label: 'Main thread blocking increases TBT',
+                ruleId: 'js-tbt-inp-chain',
+            },
+            {
+                source: 'high-tbt',
+                target: 'delayed-inp-tbt',
+                confidence: 'medium',
+                label: 'High TBT proxies for INP delay (correlation confirmed)',
+                ruleId: 'js-tbt-inp-chain',
+            },
+        ];
+        return { nodes, edges };
+    },
+};
+// ---------------------------------------------------------------------------
+// Rule 2: JS execution hotspots → long tasks
+// ---------------------------------------------------------------------------
+export const jsHotspotsChain = {
+    id: 'js-hotspots-long-tasks-chain',
+    label: 'JS execution hotspots → long tasks',
+    applies(features) {
+        const js = features.jsHotspots;
+        return js != null && js.longTaskCount >= LONG_TASK_WARN;
+    },
+    build(features) {
+        const js = features.jsHotspots;
+        const conf = confidenceFromDelta(js.longTaskCount, LONG_TASK_WARN, LONG_TASK_CRIT);
+        const hotspotsEvidence = {
+            metric: { name: 'Long tasks', value: js.longTaskCount, unit: 'count' },
+        };
+        const nodes = [
+            {
+                id: 'js-hotspots',
+                label: `${js.longTaskCount} long JS tasks`,
+                type: 'metric',
+                severity: js.longTaskCount >= LONG_TASK_CRIT ? 'critical' : 'warning',
+                value: js.longTaskCount,
+                threshold: LONG_TASK_WARN,
+                evidence: hotspotsEvidence,
+            },
+            {
+                id: 'long-tasks-js',
+                label: 'Long tasks on main thread',
+                type: 'bottleneck',
+                severity: 'warning',
+            },
+        ];
+        const edges = [
+            {
+                source: 'js-hotspots',
+                target: 'long-tasks-js',
+                confidence: conf,
+                label: 'JS hotspots create long tasks (>50ms)',
+                ruleId: 'js-hotspots-long-tasks-chain',
+            },
+        ];
+        // If there's a max blocking duration, add an edge to delayed-inp
+        if (js.maxBlockingDuration > 50) {
+            nodes.push({
+                id: 'delayed-inp-hotspots',
+                label: 'Possible INP delay',
+                type: 'impact',
+                severity: 'warning',
+            });
+            edges.push({
+                source: 'long-tasks-js',
+                target: 'delayed-inp-hotspots',
+                confidence: 'medium',
+                label: 'Long tasks delay user input processing',
+                ruleId: 'js-hotspots-long-tasks-chain',
+            });
+        }
+        return { nodes, edges };
+    },
+};
+// ---------------------------------------------------------------------------
+// Rule 3: Excessive scripts → parse time
+// ---------------------------------------------------------------------------
+export const excessiveScriptsChain = {
+    id: 'js-excessive-scripts-chain',
+    label: 'Many scripts → long parse time → main thread contention',
+    applies(features) {
+        const js = features.jsHotspots;
+        return js != null && js.evaluatedScripts >= EVALUATED_SCRIPTS_WARN;
+    },
+    build(features) {
+        const js = features.jsHotspots;
+        const conf = confidenceFromDelta(js.evaluatedScripts, EVALUATED_SCRIPTS_WARN, EVALUATED_SCRIPTS_CRIT);
+        const isHeavy = js.bootupTime >= BOOTUP_CRIT;
+        const nodes = [
+            {
+                id: 'many-scripts',
+                label: `${js.evaluatedScripts} scripts`,
+                type: 'metric',
+                severity: isHeavy ? 'critical' : 'warning',
+                value: js.evaluatedScripts,
+                threshold: EVALUATED_SCRIPTS_WARN,
+            },
+            {
+                id: 'long-parse-time',
+                label: `Long parse/compile time (${Math.round(js.bootupTime)}ms)`,
+                type: 'bottleneck',
+                severity: 'warning',
+                value: js.bootupTime,
+                unit: 'ms',
+                threshold: BOOTUP_WARN,
+            },
+        ];
+        const edges = [
+            {
+                source: 'many-scripts',
+                target: 'long-parse-time',
+                confidence: conf,
+                label: 'Large number of scripts increases total parse and compile time',
+                ruleId: 'js-excessive-scripts-chain',
+            },
+        ];
+        return { nodes, edges };
+    },
+};
+// ---------------------------------------------------------------------------
+// Aggregated
+// ---------------------------------------------------------------------------
+export const jsRules = [
+    tbtInpChain,
+    jsHotspotsChain,
+    excessiveScriptsChain,
+];
+//# sourceMappingURL=js.js.map

package/dist/causal/rules/js.js.map

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

package/dist/causal/rules/layout.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Layout / DOM causal rules.
+ *
+ * Chains covered:
+ *   1. Layout shift clusters → high CLS
+ *   2. Complex DOM (deep nesting, many nodes) → layout instability → CLS
+ *
+ * @packageDocumentation
+ */
+import type { FeatureSet } from '../../extract/types.js';
+import type { CausalNode, CausalEdge } from '../types.js';
+export declare const layoutShiftClusterChain: {
+    id: string;
+    label: string;
+    applies(features: FeatureSet): boolean;
+    build(features: FeatureSet): {
+        nodes: CausalNode[];
+        edges: CausalEdge[];
+    };
+};
+export declare const complexDomChain: {
+    id: string;
+    label: string;
+    applies(features: FeatureSet): boolean;
+    build(features: FeatureSet): {
+        nodes: CausalNode[];
+        edges: CausalEdge[];
+    };
+};
+export declare const layoutRules: {
+    id: string;
+    label: string;
+    applies(features: FeatureSet): boolean;
+    build(features: FeatureSet): {
+        nodes: CausalNode[];
+        edges: CausalEdge[];
+    };
+}[];
+//# sourceMappingURL=layout.d.ts.map

package/dist/causal/rules/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/causal/rules/layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAc,UAAU,EAAE,UAAU,EAAY,MAAM,aAAa,CAAC;AAehF,eAAO,MAAM,uBAAuB;;;sBAIhB,UAAU,GAAG,OAAO;oBAKtB,UAAU,GAAG;QAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAAC,KAAK,EAAE,UAAU,EAAE,CAAA;KAAE;CAoF1E,CAAC;AAMF,eAAO,MAAM,eAAe;;;sBAIR,UAAU,GAAG,OAAO;oBAKtB,UAAU,GAAG;QAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAAC,KAAK,EAAE,UAAU,EAAE,CAAA;KAAE;CAqD1E,CAAC;AAMF,eAAO,MAAM,WAAW;;;sBAnKJ,UAAU,GAAG,OAAO;oBAKtB,UAAU,GAAG;QAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAAC,KAAK,EAAE,UAAU,EAAE,CAAA;KAAE;GAiK1E,CAAC"}

package/dist/causal/rules/layout.js

@@ -0,0 +1,169 @@
+/**
+ * Layout / DOM causal rules.
+ *
+ * Chains covered:
+ *   1. Layout shift clusters → high CLS
+ *   2. Complex DOM (deep nesting, many nodes) → layout instability → CLS
+ *
+ * @packageDocumentation
+ */
+// ---------------------------------------------------------------------------
+// Thresholds
+// ---------------------------------------------------------------------------
+const CLS_WARN = 0.1;
+const CLS_CRIT = 0.25;
+const CLUSTER_SCORE_WARN = 0.3;
+const HIGHLY_COMPLEX_DOM = 5; // highComplexitySubtreeCount >= 5
+// ---------------------------------------------------------------------------
+// Rule 1: Layout shift clusters → CLS
+// ---------------------------------------------------------------------------
+export const layoutShiftClusterChain = {
+    id: 'layout-shift-cluster-chain',
+    label: 'Layout shift clusters → high CLS',
+    applies(features) {
+        const ls = features.layoutShifts;
+        return ls != null && (ls.cls != null || ls.clusterScore > CLUSTER_SCORE_WARN);
+    },
+    build(features) {
+        const ls = features.layoutShifts;
+        // If CLS is defined and below the warning threshold, suppress noise
+        if (ls.cls != null && ls.cls < CLS_WARN) {
+            if (ls.clusterScore < 0.5) {
+                return { nodes: [], edges: [] }; // Skip entirely when cluster is not significant
+            }
+            // clusterScore >= 0.5 but CLS good — single weak info node
+            return {
+                nodes: [{
+                        id: 'cls-minor',
+                        label: `Layout shifts detected (CLS: ${ls.cls.toFixed(3)}) — within normal threshold`,
+                        type: 'metric',
+                        severity: 'info',
+                        value: ls.cls,
+                        threshold: CLS_WARN,
+                    }],
+                edges: [],
+            };
+        }
+        const clsValue = ls.cls ?? 0;
+        const isPoor = clsValue >= CLS_CRIT || ls.clusterScore > 0.6;
+        const conf = clsValue >= CLS_CRIT ? 'strong' : clsValue >= CLS_WARN ? 'medium' : 'weak';
+        const clsEvidence = ls.cls != null
+            ? { metric: { name: 'CLS', value: ls.cls, unit: 'score' } }
+            : undefined;
+        const nodes = [
+            {
+                id: 'layout-shifts',
+                label: ls.cls != null ? `Layout shifts (CLS: ${clsValue.toFixed(2)})` : 'Layout shifts detected',
+                type: 'metric',
+                severity: isPoor ? 'critical' : clsValue >= CLS_WARN ? 'warning' : 'info',
+                value: clsValue,
+                threshold: CLS_WARN,
+                evidence: clsEvidence,
+            },
+        ];
+        const edges = [];
+        // If clusterScore is high, add intermediate bottleneck
+        if (ls.clusterScore > CLUSTER_SCORE_WARN) {
+            nodes.push({
+                id: 'layout-shift-clusters',
+                label: `Layout shift clusters (score: ${ls.clusterScore.toFixed(2)})`,
+                type: 'bottleneck',
+                severity: ls.clusterScore > 0.6 ? 'critical' : 'warning',
+                value: ls.clusterScore,
+                threshold: CLUSTER_SCORE_WARN,
+            });
+            edges.push({
+                source: 'layout-shifts',
+                target: 'layout-shift-clusters',
+                confidence: 'medium',
+                label: 'Shifts cluster together, compounding the problem',
+                ruleId: 'layout-shift-cluster-chain',
+            });
+        }
+        nodes.push({
+            id: 'high-cls',
+            label: 'High Cumulative Layout Shift',
+            type: 'impact',
+            severity: isPoor ? 'critical' : clsValue >= CLS_WARN ? 'warning' : 'info',
+            value: clsValue,
+            threshold: CLS_WARN,
+        });
+        const sourceNode = ls.clusterScore > CLUSTER_SCORE_WARN ? 'layout-shift-clusters' : 'layout-shifts';
+        edges.push({
+            source: sourceNode,
+            target: 'high-cls',
+            confidence: conf,
+            label: 'Accumulated layout shifts degrade page stability',
+            ruleId: 'layout-shift-cluster-chain',
+        });
+        return { nodes, edges };
+    },
+};
+// ---------------------------------------------------------------------------
+// Rule 2: Complex DOM → layout instability
+// ---------------------------------------------------------------------------
+export const complexDomChain = {
+    id: 'layout-complex-dom-chain',
+    label: 'Complex DOM → layout instability → CLS',
+    applies(features) {
+        return features.layoutShifts?.highComplexitySubtreeCount != null
+            && features.layoutShifts.highComplexitySubtreeCount >= HIGHLY_COMPLEX_DOM;
+    },
+    build(features) {
+        const ls = features.layoutShifts;
+        const isDeep = ls.deepNesting;
+        const conf = isDeep ? 'strong' : 'medium';
+        const nodes = [
+            {
+                id: 'complex-dom-tree',
+                label: `${ls.highComplexitySubtreeCount} complex DOM subtrees`,
+                type: 'metric',
+                severity: isDeep ? 'warning' : 'info',
+                value: ls.highComplexitySubtreeCount,
+                threshold: HIGHLY_COMPLEX_DOM,
+            },
+            {
+                id: 'layout-instability',
+                label: 'Layout instability',
+                type: 'bottleneck',
+                severity: isDeep ? 'warning' : 'info',
+            },
+        ];
+        const edges = [
+            {
+                source: 'complex-dom-tree',
+                target: 'layout-instability',
+                confidence: conf,
+                label: 'Complex DOM structure increases likelihood of shifts',
+                ruleId: 'layout-complex-dom-chain',
+            },
+        ];
+        // Connect to CLS impact if there's a CLS value
+        if (ls.cls != null) {
+            nodes.push({
+                id: 'high-cls-dom',
+                label: 'High Cumulative Layout Shift',
+                type: 'impact',
+                severity: 'warning',
+                value: ls.cls,
+                threshold: CLS_WARN,
+            });
+            edges.push({
+                source: 'layout-instability',
+                target: 'high-cls-dom',
+                confidence: 'weak',
+                label: 'Layout instability may lead to CLS',
+                ruleId: 'layout-complex-dom-chain',
+            });
+        }
+        return { nodes, edges };
+    },
+};
+// ---------------------------------------------------------------------------
+// Aggregated
+// ---------------------------------------------------------------------------
+export const layoutRules = [
+    layoutShiftClusterChain,
+    complexDomChain,
+];
+//# sourceMappingURL=layout.js.map

package/dist/causal/rules/layout.js.map

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

package/dist/causal/rules/lcp.d.ts

@@ -0,0 +1,49 @@
+/**
+ * LCP-related causal rules.
+ *
+ * Chains covered:
+ *   1. High TTFB → delayed HTML parse → delayed CSS discovery → blocked render → ↑LCP
+ *   2. Render-blocking resources → blocked render → ↑LCP
+ *   3. Slow LCP resource load → ↑LCP
+ *
+ * @packageDocumentation
+ */
+import type { FeatureSet } from '../../extract/types.js';
+import type { CausalNode, CausalEdge } from '../types.js';
+export declare const ttfbLcpChain: {
+    id: string;
+    label: string;
+    applies(features: FeatureSet): boolean;
+    build(features: FeatureSet): {
+        nodes: CausalNode[];
+        edges: CausalEdge[];
+    };
+};
+export declare const renderBlockingLcpChain: {
+    id: string;
+    label: string;
+    applies(features: FeatureSet): boolean;
+    build(features: FeatureSet): {
+        nodes: CausalNode[];
+        edges: CausalEdge[];
+    };
+};
+export declare const lcpResourceDelayChain: {
+    id: string;
+    label: string;
+    applies(features: FeatureSet): boolean;
+    build(features: FeatureSet): {
+        nodes: CausalNode[];
+        edges: CausalEdge[];
+    };
+};
+export declare const lcpRules: {
+    id: string;
+    label: string;
+    applies(features: FeatureSet): boolean;
+    build(features: FeatureSet): {
+        nodes: CausalNode[];
+        edges: CausalEdge[];
+    };
+}[];
+//# sourceMappingURL=lcp.d.ts.map

package/dist/causal/rules/lcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lcp.d.ts","sourceRoot":"","sources":["../../../src/causal/rules/lcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAc,UAAU,EAAE,UAAU,EAAY,MAAM,aAAa,CAAC;AAyChF,eAAO,MAAM,YAAY;;;sBAIL,UAAU,GAAG,OAAO;oBAItB,UAAU,GAAG;QAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAAC,KAAK,EAAE,UAAU,EAAE,CAAA;KAAE;CAkF1E,CAAC;AAMF,eAAO,MAAM,sBAAsB;;;sBAIf,UAAU,GAAG,OAAO;oBAKtB,UAAU,GAAG;QAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAAC,KAAK,EAAE,UAAU,EAAE,CAAA;KAAE;CA8D1E,CAAC;AAMF,eAAO,MAAM,qBAAqB;;;sBAId,UAAU,GAAG,OAAO;oBAKtB,UAAU,GAAG;QAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAAC,KAAK,EAAE,UAAU,EAAE,CAAA;KAAE;CAyC1E,CAAC;AAMF,eAAO,MAAM,QAAQ;;;sBAjOD,UAAU,GAAG,OAAO;oBAItB,UAAU,GAAG;QAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAAC,KAAK,EAAE,UAAU,EAAE,CAAA;KAAE;GAiO1E,CAAC"}