Metadata-Version: 2.4
Name: gh-actions-parser
Version: 1.0.0
Summary: CLI tool to parse GitHub Actions run logs and extract structured failure information
Author-email: DeepSeekCode <agent@workprotocol.ai>
License: MIT
Keywords: github-actions,ci,cli,devops,parser
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0
Requires-Dist: requests>=2.28
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pylint>=2.17; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: responses>=0.23; extra == "dev"

# gh-actions-parser

CLI tool to parse GitHub Actions run logs and extract structured failure information. Built for automated CI triage systems.

## Features

- **Multi-failure-type detection**: Identifies test failures (pytest, Jest), build errors (TypeScript, npm), and linting errors (ESLint, pylint)
- **Structured JSON output**: Machine-readable output for CI pipelines and automated systems
- **Human-readable reports**: Color-coded terminal output for quick manual debugging
- **Stack trace extraction**: Automatically finds and surfaces relevant stack traces
- **Fix suggestions**: Category-aware fix recommendations based on failure patterns
- **Handles large repos**: Processes logs with 10,000+ lines efficiently via streaming line-by-line parsing

## Installation

```bash
pip install gh-actions-parser
```

Or from source:

```bash
git clone https://github.com/DeepSeekCode/gh-actions-parser.git
cd gh-actions-parser
pip install -e .
```

## Usage

### Basic usage

```bash
# Parse a failed run
gh-parse https://github.com/owner/repo/actions/runs/1234567890

# Using an authentication token (recommended to avoid rate limits)
gh-parse https://github.com/owner/repo/actions/runs/1234567890 -t ghp_xxxx

# Using GITHUB_TOKEN environment variable
export GITHUB_TOKEN=ghp_xxxx
gh-parse https://github.com/owner/repo/actions/runs/1234567890
```

### JSON output mode

```bash
gh-parse https://github.com/owner/repo/actions/runs/1234567890 --json
```

Example JSON output:

```json
{
  "run_url": "https://github.com/test/repo/actions/runs/12345",
  "repository": "test/repo",
  "workflow": "CI",
  "conclusion": "failure",
  "failing_steps": [
    {
      "step_name": "Run tests",
      "step_number": 5,
      "error_message": "AssertionError: assert 'Updated' == 'Updated Name'",
      "stack_trace": "File \"tests/test_api.py\", line 42, in test_update_user\n    assert result[\"name\"] == \"Updated Name\"",
      "failure_category": "test_failure"
    }
  ],
  "suggested_fixes": [
    "Check expected vs actual values in the assertion — the test expectation may need updating",
    "Run tests locally with the same environment to reproduce the failure"
  ],
  "error_count": 2
}
```

## Failure Categories

| Category | Description | Example Patterns |
|---|---|---|
| `test_failure` | Test runner failures | pytest AssertionError, Jest expect() failures |
| `build_error` | Compilation or build failures | TypeScript TS errors, npm ERR!, SyntaxError |
| `lint_error` | Linter violations | ESLint errors, pylint E/W violations |
| `unknown` | Unclassified failures | Any error that doesn't match known patterns |

## Supported Patterns

### Test Failures
- **pytest**: `FAILED`, `AssertionError`, test session summaries
- **Jest**: `● test ›`, `expect().toHaveBeenCalledWith()`, suite summaries
- **General**: `FAIL`, `Test Suites: X failed`

### Build Errors
- **TypeScript**: `error TS2322:`, `Cannot find module`, type errors
- **npm/yarn**: `npm ERR!`, `yarn error`
- **Python**: `SyntaxError`, `ModuleNotFoundError`, `ImportError`
- **Go**: `go build.*failed`

### Lint Errors
- **ESLint**: `error  path/to/file:line:col`, `no-console`, `no-undef`
- **pylint**: `E0602:`, `W0611:`
- **black/prettier**: `would reformat`, `prettier.*error`

## Requirements

- Python 3.10+
- GitHub personal access token (optional, but recommended)
  - Without token: 60 requests/hour
  - With token: 5,000 requests/hour

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=gh_actions_parser

# Lint
pylint src/gh_actions_parser/

# Type check
mypy src/
```

## License

MIT
