[WIP] Implement Playwright-based CLI tool for performance analysis

[Copilot]

Thanks for assigning this issue to me. I'm starting to work on it and will keep this PR's description up to date as I form a plan and make progress.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Implement a complete Playwright-based CLI tool for automated performance and bundle analysis</issue_title>
<issue_description># Development Task: Tracemark - Playwright Performance Analysis Tool

Date: March 3, 2026
Project: Tracemark
Status: Ready for Implementation
Requirements: See requirements.md

---

🎯 Objective

Implement a complete Playwright-based CLI tool for automated performance and bundle analysis across multiple URLs, with three measurement scenarios per URL, Lighthouse integration, and interactive HTML visualization.

Full requirements are documented in: docs/requirements.md

---

⚠️ Development Guidelines

Use YOLO Mode

• Move fast and implement features end-to-end
• Don't ask for permission - make reasonable architectural decisions
• Prioritize working code over perfect abstractions initially
• Iterate and refactor as needed

Leverage Subagents

• Break down complex modules into separate implementation sessions
• Use #github-pull-request_copilot-coding-agent for parallel workstreams when applicable
• Let subagents handle isolated modules (e.g., classifier logic, visualizer, Lighthouse wrapper)

Verify Before Commit

• ✅ Run pnpm run typecheck - ensure no TypeScript errors
• ✅ Run pnpm run lint - check code quality
• ✅ Test the analyze command with a sample URLs file
• ✅ Verify JSON report structure matches schema
• ✅ Test HTML visualization with generated reports
• ✅ Test all three scenarios (full, no-third-party, no-tracking-only)
• ✅ Verify cold vs. warm runs work correctly
• ✅ Test error handling (invalid URLs, timeouts, network errors)

---

📋 Implementation Approach

This task requires implementing the COMPLETE application from start to finish.

Follow the suggested roadmap below (Phases 1-8) to build the entire tool. The phases are provided as guidance for organizing your work, not as separate approval gates. Implement everything in one continuous workflow:

1. Review the requirements in docs/requirements.md thoroughly
2. Start with the foundation (types, structure, config)
3. Build bottom-up: Core analyzers → Classification → Integration → Reporting → Visualization
4. Document as you go: Create README files for each module
5. Test continuously: Verify functionality at each major milestone
6. Complete all 8 phases before considering the task done

Key considerations:

• Module dependency graph: types → analyzers → classifiers → scenarios → lighthouse → reporter → visualizer → CLI
• Data flow: URL input → Playwright measurement → Lighthouse audit → JSON merge → HTML generation
• Risks: Playwright Coverage API, Lighthouse programmatic execution, request blocking strategies
• Start with TypeScript types to establish contracts between modules

---

🗺️ Suggested Roadmap

Phase 1: Foundation (Day 1)

• Set up project structure (folders from requirements 7c)
• Initialize package.json with all dependencies (7a)
• Configure TypeScript (tsconfig.json - strict mode)
• Set up ESLint configuration
• Define core TypeScript types in src/types/ (Report, Scenario, Metrics, etc.)
• Create sample urls/example.yaml and config.yaml

Phase 2: Core Measurement (Days 2-3)

• Implement scenario controller (src/scenarios/)
  • Three scenarios: full, no-third-party, no-tracking-only
  • Request blocking via page.route()
  • Cold run + multiple warm runs per scenario
• Implement Playwright analyzers (src/analyzer/)
  • html.ts - HTML payload, SSR detection, inline scripts, preload hints
  • javascript.ts - Coverage API, bundle listing, chunk analysis
  • css.ts - Coverage API, inline styles, framework hints
  • thirdParty.ts - External requests, category classification

Phase 3: Bundle Classification (Day 3)

• Implement bundle classifier (src/classifier/bundles.ts)
  • Next.js pattern detection
  • React/Vite/CRA detection
  • Framework vs. vendor vs. internal classification
• Implement third-party classifier (src/classifier/thirdParty.ts)
  • CMP, tag manager, analytics, tracking, chat widgets
  • Pattern matching for known providers

Phase 4: Lighthouse Integration (Day 4)

• Implement Lighthouse wrapper (src/lighthouse/)
  • Independent Chromium process per run
  • Request blocking via --blocked-url-patterns
  • Cold + warm runs per scenario
  • Extract required audits (requirements 3a)
• Merge Lighthouse results into Playwright data structure

Phase 5: Report Generation (Day 4-5)

• Implement JSON reporter (src/reporter/)
  • Merge all scenario data
  • Calculate delta metrics (full vs. no-third-party, etc.)
  • Generate report structure matching schema (requirements 4)
  • Save to reports/<domain-slug>/<timestamp>/report.json

Phase 6: Visualization (Days 5-6)

-...

• Fixes Implement a complete Playwright-based CLI tool for automated performance and bundle analysis #1

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.