# audit-trace

`audit-trace` is a local-first CLI for **npm / pnpm / Yarn** projects. It combines **lockfile-aware dependency graphs** with **audit output** so you can see **which top-level dependencies introduce a vulnerable package**, short **remediation hints**, and **CI-friendly diagnostics** (structured `CiDiagnostic` codes for logs, job summaries, or PR comments).

## Why use this instead of `npm audit` (alone)?

`npm audit` is good at one thing: **surfacing advisories** for what is installed. It is weaker at **explaining** them in a way that matches how teams actually fix issues:

| What you often need | `npm audit` | `audit-trace` |
|---------------------|-------------|---------------|
| **Who owns it?** Which direct dependency pulled in the vulnerable package? | Usually a flat or cryptic path; easy to lose the chain in large trees | **Ownership paths** from the lockfile graph, **grouped** so shared prefixes are not repeated dozens of times |
| **Clarity** | Severity and package names, but little narrative structure | **Merged dependency trie**, **severity-colored** vulnerable leaves, and **prod / dev** context where the graph allows it |
| **Action** | “Run npm audit fix” / generic hints | **Remediation-oriented** suggestions (e.g. overrides) when the advisory data supports it |
| **CI** | Exit codes and JSON, often with little **why** | **`--ci`** + **`diagnostics`** you can pipe to summaries or PR comments; **`--ci-verbose`** for a short human explanation |

**Simplicity** here means: one run gives you a **single, readable view**—what is wrong, **where it enters the tree**, and how serious it is—without hunting through `node_modules` or reconstructing chains manually. **Explainability** means: the tool combines **graph + audit**, not audit alone, so answers read as “*this direct dependency → this chain → this package (severity)*” instead of a flat list of advisories.

`audit-trace` **does not replace** the registry advisory source: it still relies on your package manager’s audit (or a saved `--audit-file`). It **adds** structure, ownership, and reporting on top.

## Requirements

- Node.js **18+**

## Install

```bash
npm install -g audit-trace
# or use npx
npx audit-trace report
```

From source:

```bash
git clone <repo>
cd audit-trace
npm install
npm run build
node dist/cli.js --help
```

## Quick start

```bash
cd your-project
audit-trace report
audit-trace report --json
audit-trace report --ci --fail-on high --prod-only
audit-trace brief
```

### AI-ready brief (vibe coding)

```bash
audit-trace brief
audit-trace brief --top 3 --prod-only
audit-trace brief --json
```

Produces a **prioritized fix plan** with ownership context and a **paste-ready prompt block** for AI assistants (Cursor, Copilot, etc.). When no vulnerabilities are found, output switches to a clean status message instead of an empty fix plan.

- `--top <n>` — max action groups (default: `5`)
- `--pkg <name>` — focus on one vulnerable package
- `--no-prompt` — omit the AI prompt block
- `--prod-only`, `--audit-file`, `--pm` — same as `report`

### Monorepos and Workspaces

If you are working in a monorepo workspace (e.g., npm or pnpm workspaces), you can run `audit-trace` inside the root workspace folder to analyze the whole monorepo, or run it directly inside any subpackage directory under `packages/` to audit and trace dependencies specifically for that subpackage:

```bash
# Audit a specific subpackage from its directory
cd packages/my-sub-package
audit-trace report
```

This works by automatically traversing up to find the workspace root containing the lockfile, running the audit at the workspace level, and then filtering the dependency graph and findings to only show vulnerabilities that are transitive dependencies of the subpackage.

### Interactive UI (Ink)

```bash
audit-trace report --interactive
```

Use **↑/↓** to browse findings, **q** to quit.

## Commands

| Command | Description |
|--------|-------------|
| `report` (default) | Run package-manager audit + lockfile graph; print ownership paths & remediation hints |
| `brief` | AI-ready security brief with prioritized fix plan and paste-ready prompt |
| `why <pkg>` | Shortest path(s) from workspace root(s) to a package in the lockfile graph |
| `graph <pkg>` | Enumerate paths (capped) between roots and the package |
| `impact <pkg>` | Transitive consumers (reverse reachability in the graph) |
| `diff <before> <after>` | Compare two lockfiles (`--kind npm\|pnpm`) — added/removed package keys |

## Flags (report)

- `--json` / `--markdown` / `--html` — output modes  
- `--ci` — apply exit-code policy and print structured CI diagnostics to stderr  
- `--ci-verbose` — more explanatory CI text  
- `--fail-on <level>` — `critical` \| `high` \| `moderate` \| `low` \| `info` \| `none` (default: `high` in CI contexts; in local runs without `--ci`, exit code stays 0 unless `--ci` is passed)  
- `--prod-only` — drop findings whose traced paths are dev-only (best-effort; requires dev flags in the lockfile)  
- `--audit-file <path>` — parse audit JSON instead of invoking `npm|pnpm|yarn audit`  
- `--pm npm\|pnpm\|yarn` — force audit runner  
- `--entry <file>` — optional entry for **madge**-based reachability heuristic (tags titles)  

## CiDiagnostic codes

Stable codes emitted in JSON (`diagnostics[]`) and echoed in human CI summaries:

| Code | Meaning |
|------|---------|
| `NO_LOCKFILE` | No supported lockfile at project root — graph/ownership is degraded |
| `AUDIT_SOURCE_FALLBACK` | Audit subprocess failed or returned empty — verify tool versions |
| `FILTER_CONTEXT` | Some items excluded by `--prod-only` / future filters |
| `FAIL_HIGH_PROD` | High/critical findings matched the failure threshold |
| `FAIL_POLICY` | Generic policy failure (`--fail-on` and severity counts) |
| `GRAPH_BUILD_WARN` | Reserved for graph/parser warnings |

## GitHub Actions

See [`examples/github-actions/ci.yml`](examples/github-actions/ci.yml) for a sample workflow posting JSON + human-readable sections.

## Plugins (experimental)

Plugins can implement hooks such as `afterGraphBuilt`, `afterAuditNormalized`, `onCiDiagnostics`, and `formatReport`. Register via the internal `plugins/registry` API (local imports) — a config file loader can be added later.

## Development

```bash
npm test
npm run build
```

## Limitations

- **Yarn Berry** lockfiles and audits differ by release; classic `yarn.lock` + `yarn audit --json` are the primary targets.
- **Reachability** via `madge` is **heuristic** (static graph); dynamic `require` is not modeled.
- **Remediation** prefers `overrides` / `resolutions` when audit provides patched ranges; otherwise a manual upgrade path is suggested.

## License

MIT