perfgraph 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,280 @@
+# PerfGraph
+
+[![npm][badge-version]][npm] [![license][badge-license]][license]
+[![npm downloads][badge-downloads]][npm] [![github stars][badge-stars]][repo]
+
+> Real browser metrics → causal degradation graph → actionable report. Built for AI agents, useful for humans.
+
+PerfGraph launches a headless Chromium browser, captures performance data via Chrome DevTools Protocol, runs it through a 5-stage analysis pipeline, and spits out a structured JSON report with issues sorted by severity, causal chains, and prioritized fixes.
+
+```bash
+npx perfgraph run --url https://example.com --pretty
+```
+
+## Why
+
+Lighthouse gives you a score. PerfGraph tells you _why_ it's bad and what to fix first.
+
+Instead of digging through a 10k-line trace.json or a wall of Lighthouse audits, you get a focused report with root causes linked to impact. The output is designed to be read by AI agents (or you) without a decoder ring.
+
+## Pipeline
+
+![diagram](./assets/diagram-tall.svg)
+
+```
+collect → normalize → extract → analyze → report
+```
+
+| Step          | What it does                                                                                                                                                                              |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Collect**   | Launches headless Chromium, captures network, trace, performance API, JS coverage, console logs, DOM snapshot, and Lighthouse audit                                                       |
+| **Normalize** | Validates raw data through Zod schemas into a unified Intermediate Representation (IRBundle). All timestamps normalized, data cleaned                                                     |
+| **Extract**   | Computes 7 diagnostic feature sets from the IR: LCP breakdown, critical network chain, main-thread blocking time, JS hotspots, layout shifts, third-party overhead, render-blocking score |
+| **Analyze**   | Runs 30+ causal rules against the features, builds a directed graph where edges represent known causal relationships with confidence levels (strong/medium/weak)                          |
+| **Report**    | Produces a self-contained JSON report with issues sorted by severity, causal chains from root cause to user impact, and prioritized recommendations with expected impact estimates        |
+
+## Install
+
+```bash
+npm install -g perfgraph
+```
+
+Or skip the install:
+
+```bash
+npx perfgraph --help
+```
+
+**Requirements:** Node.js ≥ 22, Chromium (Playwright installs it automatically on first run).
+
+## Quick start
+
+Full pipeline, one command:
+
+```bash
+perfgraph run --url https://example.com --pretty
+```
+
+Step by step:
+
+```bash
+# 1. Collect data
+perfgraph collect --url https://example.com --output ./results
+
+# 2. Normalize → Extract → Report
+perfgraph normalize ./results/perfgraph_example_20260609_120000 --output ir.json
+perfgraph extract ir.json --output features.json
+perfgraph report features.json --output report.json --pretty
+```
+
+## Commands
+
+### `perfgraph run`
+
+Full pipeline in one shot.
+
+```
+--url <url>           Required. Target URL to analyze.
+--output <dir>            Output directory (default: ./perfgraph-output).
+--runs <n>            Number of collection runs (default: 1).
+--pretty              Pretty-print the final report JSON.
+--device <name>       Mobile emulation (e.g. "iPhone 13").
+--no-lighthouse       Skip Lighthouse collection.
+--no-coverage         Skip JS/CSS coverage.
+--no-console          Skip console log capture.
+--no-dom              Skip DOM snapshot.
+```
+
+### `perfgraph collect`
+
+Captures performance data from a URL. See `run` options — same flags apply.
+
+### `perfgraph normalize <input>`
+
+Converts raw collected data into a validated IRBundle. Accepts a run directory or a parent directory (auto-detects latest run).
+
+```
+--output, -o <file>   Write to file (default: stdout).
+--pretty              Pretty-print JSON.
+```
+
+### `perfgraph extract <ir-file>`
+
+Computes diagnostic features from a normalized IR bundle.
+
+```
+--input, -i <file>    Path to IR JSON (alternative to positional).
+--output, -o <file>   Write to file (default: stdout).
+--pretty              Pretty-print JSON.
+```
+
+### `perfgraph analyze <features-file>`
+
+Applies causal rules and builds a degradation graph.
+
+```
+--input, -i <file>    Path to FeatureSet JSON (alternative to positional).
+--output, -o <file>   Write to file (default: stdout).
+--pretty              Pretty-print JSON.
+```
+
+### `perfgraph report <features-file>`
+
+Generates the final performance report. Accepts a FeatureSet JSON (from `extract`) — runs the causal engine internally, no need to call `analyze` separately.
+
+```
+--input, -i <file>    Path to FeatureSet JSON (alternative to positional).
+--output, -o <file>   Write to file (default: stdout).
+--pretty              Pretty-print JSON.
+```
+
+### `perfgraph mcp`
+
+Starts an MCP stdio server for AI agent integration. No flags. See [AGENTS.md](AGENTS.md) for details.
+
+## Report format
+
+The report is a single JSON file. Key sections:
+
+```jsonc
+{
+	"meta": {
+		"url": "https://example.com",
+		"analyzedAt": "2026-06-09T19:15:19.000Z",
+		"reportVersion": "1.0.0",
+		"featureCount": 7,
+		"graphNodeCount": 24,
+		"graphEdgeCount": 31,
+		"ruleCount": 32,
+	},
+	"summary": {
+		"score": "moderate", // "good" | "moderate" | "poor"
+		"criticalIssues": 2,
+		"warnings": 5,
+		"infos": 3,
+		"topIssues": [
+			{
+				"id": "js-long-task",
+				"label": "Long task",
+				"severity": "critical",
+				"confidence": "strong",
+			},
+		],
+	},
+	"issues": [
+		{
+			"id": "lcp-slow",
+			"label": "LCP exceeds 2.5s threshold",
+			"severity": "critical",
+			"value": 4320,
+			"unit": "ms",
+			"threshold": 2500,
+			"confidence": "strong",
+			"remediation": "Optimize largest contentful paint element...",
+			"chainId": "lcp:3",
+		},
+	],
+	"chains": [
+		{
+			"id": "lcp:3",
+			"rootCause": "LCP > 2.5s",
+			"impact": "Poor user experience",
+			"path": [
+				"TTFB delayed by server response",
+				"Render-blocking stylesheets",
+				"LCP element render delay",
+			],
+			"length": 3,
+		},
+	],
+	"recommendations": [
+		{
+			"priority": "critical",
+			"category": "LCP",
+			"title": "Optimize Largest Contentful Paint",
+			"action": "Inline critical styles, defer non-critical CSS",
+			"expectedImpact": "Reduces LCP by ~40%",
+			"relatedIssues": ["lcp-slow"],
+		},
+	],
+	"features": {
+		/* raw extracted features for cross-referencing */
+	},
+}
+```
+
+## What it detects
+
+| Category        | Issues                                                                              |
+| --------------- | ----------------------------------------------------------------------------------- |
+| **LCP**         | Slow LCP, high TTFB, render-blocking resources, LCP resource delay chains           |
+| **JavaScript**  | Long tasks, high TBT, heavy execution, unused code, main-thread bottlenecks         |
+| **Network**     | Deep request chains, bandwidth bottlenecks, waterfall depth, critical path analysis |
+| **Layout**      | Layout shifts (CLS), large DOM size, forced reflows                                 |
+| **Third-party** | Third-party script overhead, tracking pixels, embedded widget impact                |
+
+## Architecture
+
+```
+src/
+├── index.ts              CLI entry — lazy-loads commands
+├── collect/              CDP data collection via Playwright
+│   ├── browser.ts        Browser launcher
+│   ├── collector.ts      Orchestrator
+│   ├── coverage.ts       JS/CSS coverage
+│   ├── network.ts        Network request capture
+│   ├── performance.ts    Performance API metrics
+│   ├── runtime.ts        Runtime metadata
+│   ├── dom.ts            DOM snapshot
+│   └── lighthouse.ts     Lighthouse audit
+├── normalize/            Data normalization & IR validation
+├── extract/              7 diagnostic feature extractors
+├── causal/               Causal rule engine (30+ rules)
+│   ├── builder.ts        Graph construction
+│   ├── rules/            Individual causal rules by category
+│   └── types.ts          Graph data types
+├── report/               Report generation & scoring
+│   ├── analyzer.ts       Report builder
+│   ├── scorer.ts         Score computation
+│   ├── remediations.ts   Remediation templates
+│   └── types.ts          Report schema
+├── distill/              Agent-optimized summary layer (insights.json)
+├── mcp/                  MCP stdio server
+├── cli/                  CLI command handlers
+└── shared/               Shared utilities & types
+```
+
+## Development
+
+```bash
+npm install
+npm run build          # compile TypeScript
+npm run typecheck      # check types only
+npm test               # run tests
+npm run test:watch     # tests in watch mode
+npm run dev            # tsx watch — no build step
+```
+
+## Tech
+
+| Thing              | What                                          |
+| ------------------ | --------------------------------------------- |
+| Runtime            | Node.js ≥ 22                                  |
+| Language           | TypeScript (strict, noUncheckedIndexedAccess) |
+| Browser            | Playwright (Chromium)                         |
+| Validation         | Zod at every data boundary                    |
+| Graph engine       | @dagrejs/graphlib                             |
+| Performance audits | Lighthouse                                    |
+| Testing            | Vitest                                        |
+
+## License
+
+MIT
+
+[badge-version]: https://img.shields.io/npm/v/perfgraph.svg
+[badge-license]: https://img.shields.io/npm/l/perfgraph.svg
+[badge-downloads]: https://img.shields.io/npm/dm/perfgraph.svg
+[badge-stars]: https://img.shields.io/github/stars/Be1zebub/PerfGraph.svg?style=flat&logo=github
+[npm]: https://www.npmjs.com/package/perfgraph
+[license]: https://github.com/Be1zebub/PerfGraph/blob/master/LICENSE
+[repo]: https://github.com/Be1zebub/PerfGraph

package/dist/causal/builder.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Causal Graph Builder — deterministic rules engine.
+ *
+ * Takes a FeatureSet, evaluates all known causal rules, builds a DAG,
+ * validates acyclicity, and returns a typed CausalGraph.
+ *
+ * @packageDocumentation
+ */
+import type { FeatureSet } from '../extract/types.js';
+import type { CausalGraph, CausalNode, CausalEdge } from './types.js';
+export interface CausalRule {
+    /** Unique rule identifier (e.g. "lcp-ttfb-chain") */
+    id: string;
+    /** Human-readable rule label */
+    label: string;
+    /** Check whether this rule applies to the given FeatureSet */
+    applies: (features: FeatureSet) => boolean;
+    /** Build nodes and edges for this causal chain */
+    build: (features: FeatureSet) => {
+        nodes: CausalNode[];
+        edges: CausalEdge[];
+    };
+}
+/**
+ * Build a deterministic CausalGraph from a FeatureSet.
+ *
+ * This is a pure function: same FeatureSet → same CausalGraph (given the same rules).
+ *
+ * @param features - The FeatureSet from Phase 3 extraction
+ * @returns A typed CausalGraph with nodes, edges, and metadata
+ * @throws If the graph contains cycles after all rules are applied
+ */
+export declare function buildCausalGraph(features: FeatureSet): CausalGraph;
+//# sourceMappingURL=builder.d.ts.map

package/dist/causal/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/causal/builder.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,UAAU,EACX,MAAM,YAAY,CAAC;AAWpB,MAAM,WAAW,UAAU;IACzB,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,OAAO,EAAE,CAAC,QAAQ,EAAE,UAAU,KAAK,OAAO,CAAC;IAC3C,kDAAkD;IAClD,KAAK,EAAE,CAAC,QAAQ,EAAE,UAAU,KAAK;QAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAAC,KAAK,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC;CAC/E;AAkCD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,UAAU,GAAG,WAAW,CA8FlE"}

package/dist/causal/builder.js

@@ -0,0 +1,132 @@
+/**
+ * Causal Graph Builder — deterministic rules engine.
+ *
+ * Takes a FeatureSet, evaluates all known causal rules, builds a DAG,
+ * validates acyclicity, and returns a typed CausalGraph.
+ *
+ * @packageDocumentation
+ */
+import { Graph, alg } from '@dagrejs/graphlib';
+import { CausalGraphSchema } from './types.js';
+import { lcpRules } from './rules/lcp.js';
+import { networkRules } from './rules/network.js';
+import { jsRules } from './rules/js.js';
+import { layoutRules } from './rules/layout.js';
+// ---------------------------------------------------------------------------
+// All registered rules
+// ---------------------------------------------------------------------------
+// IMPORTANT: order matters — rules evaluated first get priority for
+// node/edge IDs if there are overlaps (unlikely, but possible).
+const ALL_RULES = [
+    ...lcpRules,
+    ...networkRules,
+    ...jsRules,
+    ...layoutRules,
+];
+// ---------------------------------------------------------------------------
+// Node deduplication: merge nodes with the same id
+// ---------------------------------------------------------------------------
+function mergeNodes(existing, incoming) {
+    return {
+        ...existing,
+        // Prefer the non-undefined value
+        severity: incoming.severity ?? existing.severity,
+        value: incoming.value ?? existing.value,
+        unit: incoming.unit ?? existing.unit,
+        threshold: incoming.threshold ?? existing.threshold,
+    };
+}
+// ---------------------------------------------------------------------------
+// Build the causal graph from a FeatureSet
+// ---------------------------------------------------------------------------
+/**
+ * Build a deterministic CausalGraph from a FeatureSet.
+ *
+ * This is a pure function: same FeatureSet → same CausalGraph (given the same rules).
+ *
+ * @param features - The FeatureSet from Phase 3 extraction
+ * @returns A typed CausalGraph with nodes, edges, and metadata
+ * @throws If the graph contains cycles after all rules are applied
+ */
+export function buildCausalGraph(features) {
+    const g = new Graph({ directed: true });
+    const nodeMap = new Map();
+    // Track which rules were applicable
+    let applicableCount = 0;
+    for (const rule of ALL_RULES) {
+        if (!rule.applies(features))
+            continue;
+        applicableCount++;
+        const { nodes, edges } = rule.build(features);
+        // Add nodes (deduplicate by id)
+        for (const node of nodes) {
+            const existing = nodeMap.get(node.id);
+            if (existing) {
+                nodeMap.set(node.id, mergeNodes(existing, node));
+            }
+            else {
+                nodeMap.set(node.id, node);
+            }
+            g.setNode(node.id, nodeMap.get(node.id));
+        }
+        // Add edges
+        for (const edge of edges) {
+            // Ensure both endpoints exist in the graph
+            if (!nodeMap.has(edge.source)) {
+                const fallback = {
+                    id: edge.source,
+                    label: edge.source,
+                    type: 'bottleneck',
+                };
+                nodeMap.set(edge.source, fallback);
+                g.setNode(edge.source, fallback);
+            }
+            if (!nodeMap.has(edge.target)) {
+                const fallback = {
+                    id: edge.target,
+                    label: edge.target,
+                    type: 'impact',
+                };
+                nodeMap.set(edge.target, fallback);
+                g.setNode(edge.target, fallback);
+            }
+            g.setEdge(edge.source, edge.target, edge);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Validation: check for cycles
+    // -----------------------------------------------------------------------
+    const cycles = alg.findCycles(g);
+    const hasCycle = cycles.length > 0;
+    if (hasCycle) {
+        const cycleDescriptions = cycles
+            .map((cycle) => cycle.join(' → '))
+            .join('; ');
+        throw new Error(`Causal graph contains cycle(s): ${cycleDescriptions}. ` +
+            `Cycle-free DAG is required for deterministic analysis.`);
+    }
+    // Topological sort (will throw if cycles remain)
+    const sortedIds = alg.topsort(g);
+    // -----------------------------------------------------------------------
+    // Build output — sorted by topological order
+    // -----------------------------------------------------------------------
+    const sortedNodes = sortedIds
+        .map((id) => g.node(id))
+        .filter((n) => n != null);
+    const allEdges = g.edges().map((e) => g.edge(e.v, e.w));
+    const output = {
+        nodes: sortedNodes,
+        edges: allEdges,
+        metadata: {
+            featureCount: applicableCount,
+            ruleCount: ALL_RULES.length,
+            totalNodes: sortedNodes.length,
+            totalEdges: allEdges.length,
+            hasCycle: false,
+            targetUrl: features.url ?? undefined,
+        },
+    };
+    // Final schema validation
+    return CausalGraphSchema.parse(output);
+}
+//# sourceMappingURL=builder.js.map

package/dist/causal/builder.js.map

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

package/dist/causal/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Causal Graph Builder — public API.
+ *
+ * Entry point for Phase 4: takes FeatureSet → returns CausalGraph.
+ *
+ * @packageDocumentation
+ */
+export { buildCausalGraph } from './builder.js';
+export type { CausalRule } from './builder.js';
+export { CausalNodeSchema, CausalEdgeSchema, CausalGraphSchema, type CausalNode, type CausalEdge, type CausalGraph, type CausalGraphMetadata, type Confidence, type Severity, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/causal/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/causal/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,UAAU,EACf,KAAK,QAAQ,GACd,MAAM,YAAY,CAAC"}

package/dist/causal/index.js

@@ -0,0 +1,10 @@
+/**
+ * Causal Graph Builder — public API.
+ *
+ * Entry point for Phase 4: takes FeatureSet → returns CausalGraph.
+ *
+ * @packageDocumentation
+ */
+export { buildCausalGraph } from './builder.js';
+export { CausalNodeSchema, CausalEdgeSchema, CausalGraphSchema, } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/causal/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/causal/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,GAOlB,MAAM,YAAY,CAAC"}

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

@@ -0,0 +1,49 @@
+/**
+ * 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
+ */
+import type { FeatureSet } from '../../extract/types.js';
+import type { CausalNode, CausalEdge } from '../types.js';
+export declare const tbtInpChain: {
+    id: string;
+    label: string;
+    applies(features: FeatureSet): boolean;
+    build(features: FeatureSet): {
+        nodes: CausalNode[];
+        edges: CausalEdge[];
+    };
+};
+export declare const jsHotspotsChain: {
+    id: string;
+    label: string;
+    applies(features: FeatureSet): boolean;
+    build(features: FeatureSet): {
+        nodes: CausalNode[];
+        edges: CausalEdge[];
+    };
+};
+export declare const excessiveScriptsChain: {
+    id: string;
+    label: string;
+    applies(features: FeatureSet): boolean;
+    build(features: FeatureSet): {
+        nodes: CausalNode[];
+        edges: CausalEdge[];
+    };
+};
+export declare const jsRules: {
+    id: string;
+    label: string;
+    applies(features: FeatureSet): boolean;
+    build(features: FeatureSet): {
+        nodes: CausalNode[];
+        edges: CausalEdge[];
+    };
+}[];
+//# sourceMappingURL=js.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"js.d.ts","sourceRoot":"","sources":["../../../src/causal/rules/js.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;AAiChF,eAAO,MAAM,WAAW;;;sBAIJ,UAAU,GAAG,OAAO;oBAKtB,UAAU,GAAG;QAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAAC,KAAK,EAAE,UAAU,EAAE,CAAA;KAAE;CAwD1E,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;CAuD1E,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;CAqC1E,CAAC;AAMF,eAAO,MAAM,OAAO;;;sBA7LA,UAAU,GAAG,OAAO;oBAKtB,UAAU,GAAG;QAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAAC,KAAK,EAAE,UAAU,EAAE,CAAA;KAAE;GA4L1E,CAAC"}