Add pprof-to-md integration for LLM-friendly markdown analysis

[mcollina]

Summary

This PR integrates pprof-to-md to generate LLM-friendly markdown analysis files alongside the existing HTML flamegraphs and pb files. This makes profile data more accessible to LLMs and automated analysis tools while maintaining full backward compatibility.

Key Features

• Markdown Analysis Generation: Automatically generates .md files alongside HTML flamegraphs
• Configurable Format: Three format modes via --md-format flag:
  • summary: Overview with top functions (default)
  • detailed: Full call stacks and comprehensive data
  • adaptive: Intelligent format selection based on profile size
• Seamless Integration: Works with both preload script and CLI generate command
• Zero Breaking Changes: All existing functionality remains unchanged

Changes Implemented

1. Dependencies & Requirements (package.json)

   • Added pprof-to-md dependency
   • Bumped Node.js requirement to >=22.6.0

2. Core Library (lib/index.js)

   • Implemented generateMarkdown() function with format support
   • Mirrors the existing generateFlamegraph() API

3. Preload Script (preload.js)

   • Added automatic markdown generation on profile save
   • Generates both CPU and heap markdown files alongside HTML

4. CLI Enhancement (bin/flame.js)

   • Added --md-format flag for run and generate commands
   • Input validation for format values

5. Documentation (README.md)

   • Added markdown generation examples
   • Documented --md-format flag usage
   • Updated Node.js version requirement

6. Test Coverage

   • 3 new unit tests in test/lib.test.js for generateMarkdown()
   • 4 new CLI tests in test/cli.test.js for --md-format flag
   • Integration test verification in test/integration.test.js
   • All 72 tests passing

Test Plan

• Verify markdown files are generated with preload script
• Test all three format modes (summary/detailed/adaptive)
• Confirm HTML generation still works as expected
• Validate CLI flag parsing and error handling
• Check markdown files are readable and well-formatted
• Verify integration with existing workflows
• Test on different profile sizes (small/medium/large)
• Ensure backward compatibility with existing usage

Example Usage

# Run with default markdown format (summary)
npx @platformatic/flame run app.js

# Run with detailed markdown format
npx @platformatic/flame run app.js --md-format detailed

# Generate markdown from existing profile
npx @platformatic/flame generate profile.pb --md-format adaptive

Related Documentation

• pprof-to-md - The underlying markdown generator library

---

🤖 Generated with Claude Code