Enhanced Stack Trace Formatter

This tool converts complex Java stack trace files into richly formatted Markdown reports. It automatically fetches source code from GitHub, annotates relevant lines, and presents the entire stack frame in a clean, collapsible format.

Features

• Dual-Format Processing: Supports two distinct input formats:
  • A multi-project, multi-trace format (original/traces.txt).
  • A single-trace, detailed event format (example/trace.txt).
• GitHub Integration: Fetches source code for a specific commit hash from public GitHub repositories.
• Intelligent Code Extraction: Identifies and extracts the relevant method body for each stack frame, even within anonymous inner classes.
• Rich Markdown Output: Generates easy-to-read Markdown files with:
  • Collapsible sections (<details>) for each stack frame.
  • Direct links to the exact file and line on GitHub.
  • Syntax-highlighted Java code snippets.
  • Line-specific annotations (// file:line).
• Special Case Handling: Provides hardcoded, formatted output for common JDK reflection classes.
• Command-Line Interface: Simple CLI flags to switch between processing modes.

Setup

1. Install Dependencies:

   pip install -r requirements.txt

2. Set GitHub Token: This tool requires a GitHub API token to fetch source code.

   • Go to GitHub Personal Access Tokens.
   • Generate a new classic token with the repo scope.
   • Set it as an environment variable named GITHUB_TOKEN.

   On Windows (Command Prompt):

   set GITHUB_TOKEN=your_token_here

   On macOS/Linux:

   export GITHUB_TOKEN=your_token_here

Usage

The script offers two modes of operation via the command line.

Default Mode (Multi-Trace Processing)

This mode is for processing the original/traces.txt file, which contains traces from multiple projects.

python format.py

• Input: original/traces.txt
• Output: For each numbered trace in the input file, a corresponding format_i.md file (e.g., format_1.md, format_2.md) will be created in the output/ directory.

Example Mode (Single-Trace Processing)

This mode is for running the original example.

python format.py --example

• Input: example/trace.txt
• Output: A single format_output.md file will be created in the example/ directory.

Input Formats

original/traces.txt

A file containing traces from multiple projects. Each project block starts with a # project/name header, followed by ## SHA: and ## Test:. Numbered entries (1., 2., etc.) contain one or more stack traces.

example/trace.txt

A file for a single project, with detailed event descriptions preceding each stack trace.

Output

The generated .md files provide a clear, hierarchical report for each stack trace. Each frame is presented in a collapsible block, allowing you to focus on the parts of the trace that matter most.