# debtlens-cli-go

> Scan your git repo. Get a tech-debt report. Your code never leaves your machine.

A single binary per OS, zero runtime dependency except `git`. Native cross-compile, ~5 MB per platform, reads your git history locally and produces either a terminal summary, a JSON export, or a standalone HTML report you can open in any browser.

This repo is the **production CLI** for DebtLens. The companion repo [`debtlens`](https://github.com/Grazulex/debtlens) (PHP/Laravel) is the **reference implementation** used to validate this Go port's behavioral parity, and will become the home of the future `debtlens-hub` (web app, Stripe, dashboard).

## Install

### Linux / macOS

Pick your platform, download, extract, move to PATH:

```bash
# Linux x86_64
curl -LO https://github.com/Grazulex/debtlens-cli-go/releases/latest/download/debtlens_<VERSION>_linux_amd64.tar.gz
tar -xzf debtlens_*_linux_amd64.tar.gz
sudo mv debtlens /usr/local/bin/

# Linux ARM64 (Raspberry Pi, AWS Graviton)
curl -LO https://github.com/Grazulex/debtlens-cli-go/releases/latest/download/debtlens_<VERSION>_linux_arm64.tar.gz
tar -xzf debtlens_*_linux_arm64.tar.gz
sudo mv debtlens /usr/local/bin/

# macOS Intel
curl -LO https://github.com/Grazulex/debtlens-cli-go/releases/latest/download/debtlens_<VERSION>_darwin_amd64.tar.gz
tar -xzf debtlens_*_darwin_amd64.tar.gz
sudo mv debtlens /usr/local/bin/

# macOS Apple Silicon (M1 / M2 / M3 / M4)
curl -LO https://github.com/Grazulex/debtlens-cli-go/releases/latest/download/debtlens_<VERSION>_darwin_arm64.tar.gz
tar -xzf debtlens_*_darwin_arm64.tar.gz
sudo mv debtlens /usr/local/bin/
```

Replace `<VERSION>` with the latest release tag (e.g. `0.1.0`).

On macOS, Gatekeeper may block the binary at first launch. Either right-click → Open → Open Anyway, or run:

```bash
xattr -d com.apple.quarantine /usr/local/bin/debtlens
```

### Windows

1. Download `debtlens_<VERSION>_windows_amd64.zip` from the [latest release](https://github.com/Grazulex/debtlens-cli-go/releases/latest)
2. Extract it to a folder in your `PATH` (e.g. `C:\Users\<you>\bin\`)
3. Open PowerShell and run `debtlens --version`

SmartScreen may show a warning on first launch. Click "More info" → "Run anyway".

### Verify your download

Every release ships a `checksums.txt` file. After extracting:

```bash
sha256sum -c checksums.txt --ignore-missing
```

### Prerequisite

Only `git` needs to be available in your `PATH`. That's trivially true in any environment where you have a git repository to analyze.

## Usage

```bash
# Free, no network — produces a terminal summary
debtlens analyze /path/to/your/repo

# Full structured JSON output (same shape as the PHP reference)
debtlens analyze /path/to/your/repo --output=json

# Standalone HTML report you can open in any browser
debtlens analyze /path/to/your/repo --output=html --output-file=report.html
```

### Flags

| Flag | Default | Description |
|---|---|---|
| `--period` | `12` | Analysis window in months |
| `--max-results` | `50` | Max items returned per analyzer |
| `--output` | `summary` | Format: `summary`, `json`, or `html` |
| `--output-file` | `-` (stdout) | Write output to this file |
| `--cost-per-dev-day-cents` | `50000` | Cost per developer day in cents |

### What it reports

DebtLens runs six analyzers over your git history:

- **Hotspots** — files concentrating most of the change activity
- **Complexity × Churn** — large files that also churn a lot (the classic "big and hot" signal)
- **Knowledge silos** — files owned by a single contributor above 70% concentration
- **Dead code candidates** — tracked files not modified in the analysis window
- **Temporal coupling** — file pairs that tend to change together
- **Velocity trend** — feat/fix/refactor ratio and project phase classification

The narrative section of the HTML report turns those signals into plain-English paragraphs with severity flags (info/warning/critical).

## Build from source

Requires Go 1.26+.

```bash
git clone https://github.com/Grazulex/debtlens-cli-go.git
cd debtlens-cli-go
make build
./debtlens --version
```

## Cross-compile

Go makes this trivial — no external toolchain needed:

```bash
make cross   # builds all 5 targets into dist/
```

## Test

```bash
make test    # go test -race -cover ./...
make lint    # golangci-lint run ./...
```

## Performance reference

On a real-world repository (laravel-atlas, 314 commits, 299 tracked files):

| Stage | PHP reference (Docker) | Go (native) |
|---|---|---|
| Wall-clock total | ~1.7 s | ~1.2 s |
| Binary size | ~400 MB Docker image | ~5 MB native |
| Dependencies | PHP 8.3, Composer, Laravel | `git` |

The Go port produces byte-identical JSON output to the PHP reference after stripping the per-run `execution_ms` timings. See [`testdata/golden/E2E-RESULTS.md`](testdata/golden/E2E-RESULTS.md) for the full comparison.

## License

MIT — see [LICENSE](LICENSE).
