perfgraph 0.1.0

package/dist/cli/mcp.js

@@ -0,0 +1,53 @@
+/**
+ * `mcp` subcommand handler.
+ *
+ * Starts a MCP (Model Context Protocol) stdio server so that AI agents
+ * (Claude, OpenCode, Cursor, etc.) can invoke perfgraph tools directly.
+ *
+ * Usage:
+ *   perfgraph mcp
+ */
+import { startMcpServer } from '../mcp/server.js';
+const MCP_HELP = `
+MCP OPTIONS
+  No flags required. Starts a MCP stdio server that listens for
+  JSON-RPC messages on stdin/stdout.
+
+EXAMPLES
+  perfgraph mcp
+
+MCP CLIENT CONFIG
+  {
+    "mcpServers": {
+      "perfgraph": {
+        "command": "node",
+        "args": ["dist/index.js", "mcp"]
+      }
+    }
+  }
+`;
+/**
+ * Parse CLI arguments for the mcp command and execute.
+ */
+export async function runMcpFromArgs(args) {
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log(MCP_HELP);
+        return true;
+    }
+    // Any unknown flags are an error
+    for (const arg of args) {
+        if (arg.startsWith('--')) {
+            console.error(`Error: Unknown flag "${arg}"`);
+            return false;
+        }
+    }
+    try {
+        await startMcpServer();
+        return true;
+    }
+    catch (err) {
+        console.error(`MCP server error: ${err.message}`);
+        return false;
+    }
+}
+//# sourceMappingURL=mcp.js.map

package/dist/cli/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../src/cli/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;CAiBhB,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAc;IACjD,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,iCAAiC;IACjC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,OAAO,CAAC,KAAK,CAAC,wBAAwB,GAAG,GAAG,CAAC,CAAC;YAC9C,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,IAAI,CAAC;QACH,MAAM,cAAc,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,qBAAsB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7D,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/cli/normalize.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `normalize` subcommand handler.
+ *
+ * Reads raw data files from a run directory and outputs the normalized
+ * Intermediate Representation (IRBundle) as JSON.
+ *
+ * Usage:
+ *   perfgraph normalize <run-dir>
+ *
+ * The run directory should contain the JSON files produced by a single
+ * collection run (trace.json, network.json, performance.json, etc.).
+ */
+/** Result of the normalize command execution */
+export interface NormalizeResult {
+    /** Whether normalization succeeded */
+    success: boolean;
+    /** Path to the input run directory */
+    runDir: string;
+    /** Version of the generated IR bundle */
+    irVersion: string;
+}
+/**
+ * Run the normalize command from a directory path.
+ *
+ * @param runDir - Path to a collection run directory
+ * @param outputFile - Optional file path to write output (defaults to stdout)
+ * @param pretty - Pretty-print JSON output (default: false)
+ * @returns NormalizeResult
+ */
+export declare function runNormalize(runDir: string, outputFile?: string, pretty?: boolean): Promise<NormalizeResult>;
+/**
+ * Find the latest run directory within a parent output directory.
+ *
+ * The parent directory should contain timestamped subdirectories named in
+ * ISO 8601 format (e.g. "2025-01-15T10-30-00"). The latest is determined
+ * by name sort, which is chronological for ISO 8601 date strings.
+ *
+ * @param parentDir - Parent directory containing timestamped subdirectories
+ * @returns Path to the latest run directory
+ * @throws Error if no subdirectories are found
+ */
+export declare function findLatestRunDir(parentDir: string): string;
+/**
+ * Parse CLI arguments for the normalize command and execute.
+ *
+ * Accepts:
+ *   <input>                (positional, required — run dir or parent dir)
+ *   --output, -o <file>    (optional, default: stdout)
+ *   --pretty               (optional, default: minified)
+ *   --help, -h             (show help)
+ *
+ * Mode detection:
+ *   - If <input> contains JSON data files directly → treat as single run dir
+ *   - If <input> contains timestamped subdirectories → use latest run dir
+ *   - Otherwise → error
+ */
+export declare function runNormalizeFromArgs(args: string[]): Promise<NormalizeResult | null>;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/cli/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/cli/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAiCH,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,eAAe,CAAC,CAkB1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAa1D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAoFjC"}

package/dist/cli/normalize.js

@@ -0,0 +1,179 @@
+/**
+ * `normalize` subcommand handler.
+ *
+ * Reads raw data files from a run directory and outputs the normalized
+ * Intermediate Representation (IRBundle) as JSON.
+ *
+ * Usage:
+ *   perfgraph normalize <run-dir>
+ *
+ * The run directory should contain the JSON files produced by a single
+ * collection run (trace.json, network.json, performance.json, etc.).
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { normalize } from '../normalize/index.js';
+import { loadRunDir } from '../shared/fs-utils.js';
+/** Expected JSON filenames in a run directory */
+const DATA_FILES = [
+    'trace.json',
+    'network.json',
+    'performance.json',
+    'runtime.json',
+    'console.json',
+    'dom.json',
+    'lighthouse.json',
+];
+/** Help text shown by `perfgraph normalize --help` */
+const NORMALIZE_HELP = `
+NORMALIZE OPTIONS
+  <input>               Path to a run directory OR parent output directory (positional, required)
+  --output, -o <file>   Write output to a file (default: stdout)
+  --pretty              Pretty-print JSON output
+  --help, -h            Show this help message
+
+EXAMPLES
+  perfgraph normalize ./runs/2025-01-15T10-30-00
+  perfgraph normalize ./runs/2025-01-15T10-30-00 --output ir.json
+  perfgraph normalize ./runs       (auto-detect latest run)
+  perfgraph normalize ./runs --pretty --output ir.json
+`;
+/**
+ * Run the normalize command from a directory path.
+ *
+ * @param runDir - Path to a collection run directory
+ * @param outputFile - Optional file path to write output (defaults to stdout)
+ * @param pretty - Pretty-print JSON output (default: false)
+ * @returns NormalizeResult
+ */
+export async function runNormalize(runDir, outputFile, pretty) {
+    const raw = loadRunDir(runDir);
+    const bundle = normalize(raw);
+    const indent = pretty ? 2 : 0;
+    const json = JSON.stringify(bundle, null, indent);
+    if (outputFile) {
+        const { writeFileSync } = await import('node:fs');
+        writeFileSync(outputFile, json, 'utf-8');
+    }
+    else {
+        console.log(json);
+    }
+    return {
+        success: true,
+        runDir: resolve(runDir),
+        irVersion: bundle.meta.irVersion,
+    };
+}
+/**
+ * Find the latest run directory within a parent output directory.
+ *
+ * The parent directory should contain timestamped subdirectories named in
+ * ISO 8601 format (e.g. "2025-01-15T10-30-00"). The latest is determined
+ * by name sort, which is chronological for ISO 8601 date strings.
+ *
+ * @param parentDir - Parent directory containing timestamped subdirectories
+ * @returns Path to the latest run directory
+ * @throws Error if no subdirectories are found
+ */
+export function findLatestRunDir(parentDir) {
+    const entries = readdirSync(parentDir, { withFileTypes: true });
+    const subdirs = entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+    if (subdirs.length === 0) {
+        throw new Error(`Error: No collector output files found in ${parentDir}`);
+    }
+    const latest = subdirs[subdirs.length - 1];
+    return join(parentDir, latest);
+}
+/**
+ * Parse CLI arguments for the normalize command and execute.
+ *
+ * Accepts:
+ *   <input>                (positional, required — run dir or parent dir)
+ *   --output, -o <file>    (optional, default: stdout)
+ *   --pretty               (optional, default: minified)
+ *   --help, -h             (show help)
+ *
+ * Mode detection:
+ *   - If <input> contains JSON data files directly → treat as single run dir
+ *   - If <input> contains timestamped subdirectories → use latest run dir
+ *   - Otherwise → error
+ */
+export async function runNormalizeFromArgs(args) {
+    let input;
+    let outputFile;
+    let pretty = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        switch (arg) {
+            case '--output':
+            case '-o':
+                if (i + 1 >= args.length) {
+                    console.error('Error: --output requires a value');
+                    return null;
+                }
+                outputFile = args[++i];
+                break;
+            case '--pretty':
+                pretty = true;
+                break;
+            case '--help':
+            case '-h':
+                console.log(NORMALIZE_HELP);
+                return null;
+            default:
+                if (arg.startsWith('--')) {
+                    console.error(`Error: Unknown flag "${arg}"`);
+                    return null;
+                }
+                // First positional arg is the input path
+                if (!input) {
+                    input = arg;
+                }
+                break;
+        }
+    }
+    if (!input) {
+        console.error('Error: <input> is required');
+        return null;
+    }
+    // Validate path exists
+    const resolvedPath = resolve(input);
+    if (!existsSync(resolvedPath)) {
+        console.error(`Error: Input path does not exist: ${input}`);
+        return null;
+    }
+    // Validate it's a directory
+    if (!statSync(resolvedPath).isDirectory()) {
+        console.error(`Error: Input is not a directory: ${input}`);
+        return null;
+    }
+    // Detect mode: single run dir vs parent output dir
+    const entries = readdirSync(resolvedPath);
+    const hasDataFiles = DATA_FILES.some((f) => entries.includes(f));
+    const hasTimestampDirs = entries.some((name) => /^\d{4}-\d{2}-\d{2}T/.test(name));
+    let runDir;
+    if (hasDataFiles) {
+        // Mode 1: Single run directory (contains JSON data files directly)
+        runDir = resolvedPath;
+    }
+    else if (hasTimestampDirs) {
+        // Mode 2: Parent output directory — auto-detect latest run
+        runDir = findLatestRunDir(resolvedPath);
+    }
+    else {
+        console.error(`Error: No collector output files found in ${resolvedPath}`);
+        return null;
+    }
+    // Execute normalize with error handling
+    try {
+        return await runNormalize(runDir, outputFile, pretty);
+    }
+    catch (err) {
+        console.error(String(err));
+        return null;
+    }
+}
+//# sourceMappingURL=normalize.js.map

package/dist/cli/normalize.js.map

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

package/dist/cli/report.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `report` subcommand handler.
+ *
+ * Reads a FeatureSet JSON file (from `perfgraph extract`), runs causal analysis,
+ * generates a comprehensive Report, and outputs as JSON.
+ *
+ * Usage:
+ *   perfgraph report <features-file>
+ *   perfgraph report --input features.json --output report.json --pretty
+ *
+ * @packageDocumentation
+ */
+/** Result of the report command execution */
+export interface ReportResult {
+    /** Whether report generation succeeded */
+    success: boolean;
+    /** Path to the input FeatureSet file */
+    inputFile: string;
+}
+/**
+ * Run the report command from a FeatureSet file path.
+ *
+ * @param inputFile - Path to FeatureSet JSON file
+ * @param outputFile - Optional output file path (defaults to stdout)
+ * @param pretty - Pretty-print JSON (default: false)
+ * @returns ReportResult
+ */
+export declare function runReport(inputFile: string, outputFile?: string, pretty?: boolean): Promise<ReportResult>;
+/**
+ * Parse CLI arguments for the report command and execute.
+ */
+export declare function runReportFromArgs(args: string[]): Promise<ReportResult | null>;
+//# sourceMappingURL=report.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/cli/report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAwBH,6CAA6C;AAC7C,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB;AAgCD;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,YAAY,CAAC,CAkBvB;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CA2D9B"}

package/dist/cli/report.js

@@ -0,0 +1,137 @@
+/**
+ * `report` subcommand handler.
+ *
+ * Reads a FeatureSet JSON file (from `perfgraph extract`), runs causal analysis,
+ * generates a comprehensive Report, and outputs as JSON.
+ *
+ * Usage:
+ *   perfgraph report <features-file>
+ *   perfgraph report --input features.json --output report.json --pretty
+ *
+ * @packageDocumentation
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { buildCausalGraph } from '../causal/index.js';
+import { buildReport } from '../report/index.js';
+import { FeatureSetSchema } from '../extract/types.js';
+/** Help text shown by `perfgraph report --help` */
+const REPORT_HELP = `
+REPORT OPTIONS
+  <file>                Path to a FeatureSet JSON file (positional, required)
+  --input, -i <file>    Path to FeatureSet JSON file (alternative to positional)
+  --output, -o <file>   Write output to a file (default: stdout)
+  --pretty              Pretty-print JSON output
+  --help, -h            Show this help message
+
+EXAMPLES
+  perfgraph report ./features.json
+  perfgraph report ./features.json --output report.json
+  perfgraph report ./features.json --pretty
+`;
+/**
+ * Load and validate a FeatureSet from a JSON file.
+ */
+function loadFeatureSet(filePath) {
+    const resolved = resolve(filePath);
+    if (!existsSync(resolved)) {
+        throw new Error(`Error: File not found: ${filePath}`);
+    }
+    let raw;
+    try {
+        const content = readFileSync(resolved, 'utf-8');
+        raw = JSON.parse(content);
+    }
+    catch (err) {
+        throw new Error(`Error: Failed to parse ${filePath}: ${err.message}`);
+    }
+    const parsed = FeatureSetSchema.safeParse(raw);
+    if (!parsed.success) {
+        const firstIssue = parsed.error.issues[0];
+        throw new Error(`Error: Invalid FeatureSet format in ${filePath}: ${firstIssue?.path.join('.') ?? ''} ${firstIssue?.message ?? ''}`);
+    }
+    return parsed.data;
+}
+/**
+ * Run the report command from a FeatureSet file path.
+ *
+ * @param inputFile - Path to FeatureSet JSON file
+ * @param outputFile - Optional output file path (defaults to stdout)
+ * @param pretty - Pretty-print JSON (default: false)
+ * @returns ReportResult
+ */
+export async function runReport(inputFile, outputFile, pretty) {
+    const features = loadFeatureSet(inputFile);
+    const graph = buildCausalGraph(features);
+    const report = buildReport(graph, features);
+    const indent = pretty ? 2 : 0;
+    const json = JSON.stringify(report, null, indent);
+    if (outputFile) {
+        const { writeFileSync } = await import('node:fs');
+        writeFileSync(outputFile, json, 'utf-8');
+    }
+    else {
+        console.log(json);
+    }
+    return {
+        success: true,
+        inputFile: resolve(inputFile),
+    };
+}
+/**
+ * Parse CLI arguments for the report command and execute.
+ */
+export async function runReportFromArgs(args) {
+    let inputFile;
+    let outputFile;
+    let pretty = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        switch (arg) {
+            case '--input':
+            case '-i':
+                if (i + 1 >= args.length) {
+                    console.error('Error: --input requires a value');
+                    return null;
+                }
+                inputFile = args[++i];
+                break;
+            case '--output':
+            case '-o':
+                if (i + 1 >= args.length) {
+                    console.error('Error: --output requires a value');
+                    return null;
+                }
+                outputFile = args[++i];
+                break;
+            case '--pretty':
+                pretty = true;
+                break;
+            case '--help':
+            case '-h':
+                console.log(REPORT_HELP);
+                return null;
+            default:
+                if (arg.startsWith('--')) {
+                    console.error(`Error: Unknown flag "${arg}"`);
+                    return null;
+                }
+                if (!inputFile) {
+                    inputFile = arg;
+                }
+                break;
+        }
+    }
+    if (!inputFile) {
+        console.error('Error: <file> is required (positional or --input)');
+        return null;
+    }
+    try {
+        return await runReport(inputFile, outputFile, pretty);
+    }
+    catch (err) {
+        console.error(String(err));
+        return null;
+    }
+}
+//# sourceMappingURL=report.js.map

package/dist/cli/report.js.map

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

package/dist/cli/run.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `run` subcommand — full pipeline in one command.
+ *
+ * Chains collect → normalize → extract → analyze → report,
+ * writing intermediate artifacts to a temp directory and
+ * outputting only the final Report JSON.
+ *
+ * Usage:
+ *   perfgraph run --url <url> [--output <dir>] [--runs <n>] [--pretty]
+ */
+/** Result of the full pipeline execution */
+export interface RunResult {
+    /** Whether all pipeline steps succeeded */
+    success: boolean;
+    /** Path to the generated report file, if any */
+    reportFile?: string;
+    /** Run output directory path */
+    outputDir?: string;
+    /** Paths to all written artifacts */
+    files?: {
+        ir: string;
+        features: string;
+        graph: string;
+        report: string;
+        insights: string;
+    };
+}
+/**
+ * Execute the full pipeline.
+ *
+ * @param url - Target URL
+ * @param output - Base output directory for collection + final report
+ * @param runs - Number of collection runs
+ * @param pretty - Pretty-print final report
+ * @param flags - boolean flags for skipping collectors
+ * @param mobile - Device name for mobile emulation (e.g. "iPhone 13")
+ * @returns RunResult
+ */
+export declare function runRun(url: string, output: string, runs: number, pretty: boolean, flags: {
+    noLighthouse?: boolean;
+    noCoverage?: boolean;
+    noConsole?: boolean;
+    noDom?: boolean;
+}, mobile?: string): Promise<RunResult | null>;
+/**
+ * Parse CLI arguments for the run command and execute.
+ */
+export declare function runRunFromArgs(args: string[]): Promise<RunResult | null>;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA6CH,4CAA4C;AAC5C,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,OAAO,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,KAAK,CAAC,EAAE;QACN,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,MAAM,CAC1B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,EACf,KAAK,EAAE;IACL,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,EACD,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAyH3B;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAmG3B"}