Output Format

Describes the available output formats — pretty (default), json, and ndjson — and the Finding data structure.

Prune supports three primary output formats, selected via --format on the CLI or report.format in prune.yaml.

Finding Structure

Every finding has the following fields, regardless of format:

Field	Type	Description
`id`	string	Unique identifier for the finding. Format: `<kind>:<file>:<symbol>`
`kind`	string	Rule that produced the finding (e.g., `unused_file`, `unused_export`)
`confidence`	string	Confidence level: `safe`, `likely_dead`, or `review`
`file`	string	Relative path to the file containing the finding. Empty string for file-independent findings
`line`	int	Line number where the symbol is declared. `1` when the exact line is unavailable
`symbol`	string	Name of the affected symbol or file basename
`reason`	string	Human-readable explanation of why the finding was emitted
`evidence`	object	Optional additional context (reserved; currently omitted from output)

Pretty Format (Default)

The default format. Outputs a human-friendly tree structure grouped by file and confidence level.

prune scan
prune scan --format pretty
prune scan --format table  # alias for pretty

Example output:

Prune 0.3.0-beta.1 — 4 issues found in 340ms

✔ SAFE (2)

  src/utils/legacy.ts
  └─ unused file: legacy.ts

  src/components/Button.tsx
  └─ unused export: OldButtonVariant

⚠ LIKELY DEAD (1)

  src/lib/helpers.ts
  └─ unused function: formatDeprecated

⚠ REVIEW (1)

  src/loader.ts
  └─ suspicious dynamic usage: require

─────────────────────────────────
Summary

  Files        1
  Exports      1
  Functions    1
  Dynamic      1

  SAFE         2
  LIKELY DEAD  1
  REVIEW       1

  Total        4

Done in 340ms

When no findings match the confidence filter:

✨ No dead code found!

Done in 280ms

Output details:

Grouping: Findings are grouped first by Confidence Level (SAFE, LIKELY DEAD, REVIEW) and then by File Path.
Icons: Uses ✔ for SAFE findings and ⚠ for LIKELY DEAD and REVIEW levels.
Summary: Provides an aggregated count of findings by type (Files, Exports, Functions, Dynamic) and by confidence level.
Duration: The total execution time is displayed at the top and bottom.

The pretty format is designed for developer readability. For automation or large-scale data processing, use json or ndjson.

JSON Format

Outputs a structured JSON object with summary, findings, and metadata. Useful for programmatic processing of complete results.

prune scan --format json

Example output:

{
  "summary": {
    "files": 3,
    "issues": 12,
    "safe": 7,
    "review": 5
  },
  "findings": [
    {
      "id": "unused_file:src/utils/legacy.ts",
      "kind": "unused_file",
      "confidence": "safe",
      "file": "src/utils/legacy.ts",
      "line": 1,
      "symbol": "legacy.ts",
      "reason": "file is not referenced by any import"
    },
    {
      "id": "unused_export:src/components/Button.tsx:OldButtonVariant",
      "kind": "unused_export",
      "confidence": "safe",
      "file": "src/components/Button.tsx",
      "line": 42,
      "symbol": "OldButtonVariant",
      "reason": "exported symbol is never imported"
    },
    {
      "id": "unused_function:src/lib/helpers.ts:formatDeprecated",
      "kind": "unused_function",
      "confidence": "likely_dead",
      "file": "src/lib/helpers.ts",
      "line": 18,
      "symbol": "formatDeprecated",
      "reason": "function declared but never referenced"
    }
  ],
  "metadata": {
    "entrypoints": ["src/index.ts", "src/main.tsx", "src/pages/**"],
    "scan_time_ms": 340
  }
}

Summary Fields

Field	Type	Description
`files`	int	Unique file count with findings
`issues`	int	Total number of findings
`safe`	int	Findings with `confidence: "safe"`
`review`	int	Findings with `confidence: "review"` or `"likely_dead"`

Metadata Fields

Field	Type	Description
`entrypoints`	string[]	Entrypoint files and patterns from config
`scan_time_ms`	int	Scan duration in milliseconds

When no findings match the filter, an empty findings array is returned:

{
  "summary": { "files": 0, "issues": 0, "safe": 0, "review": 0 },
  "findings": [],
  "metadata": { "entrypoints": [...], "scan_time_ms": 10 }
}

NDJSON Format

Outputs one JSON object per line (newline-delimited JSON). Each object follows the same schema as the JSON format. This is the standard format for streaming mode.

prune scan --format ndjson
prune scan --stream --format ndjson

Example output:

{"id":"unused_file:src/utils/legacy.ts","kind":"unused_file","confidence":"safe","file":"src/utils/legacy.ts","line":1,"symbol":"legacy.ts","reason":"file is not referenced by any import"}
{"id":"unused_export:src/components/Button.tsx:OldButtonVariant","kind":"unused_export","confidence":"safe","file":"src/components/Button.tsx","line":42,"symbol":"OldButtonVariant","reason":"exported symbol is never imported"}
{"id":"unused_function:src/lib/helpers.ts:formatDeprecated","kind":"unused_function","confidence":"likely_dead","file":"src/lib/helpers.ts","line":18,"symbol":"formatDeprecated","reason":"function declared but never referenced"}

NDJSON is the only format supported by streaming mode. When --stream is enabled and --format json is specified, the format is automatically promoted to ndjson.

For tools that consume NDJSON, you can pipe output directly to processors like jq:

prune scan --format ndjson | jq 'select(.confidence == "safe") | .file'

Filtering by Confidence

Regardless of format, findings below the --min-confidence threshold are excluded before output. The confidence ranking is:

Level	Rank
`safe`	1 (lowest — most confident)
`likely_dead`	2
`review`	3 (highest — least certain)

--min-confidence safe (the default) includes all findings.
--min-confidence likely_dead excludes safe-level findings.
--min-confidence review includes only review-level findings.

Additional Filter Flags

The scan command supports three additional flags for filtering output:

`--compact`

Omits individual findings and outputs only the summary counts:

prune scan --compact

Example output:

Prune 0.3.0-beta.1 — 4 issues found in 120ms

TYPE                 COUNT
possible_dynamic_usage    1
suspicious_dynamic_usage  1
unused_export         1
unused_file           1

CONFIDENCE   COUNT
SAFE              2
REVIEW            2

  Total        4

Done in 120ms

`--only <level>`

Shows findings matching the specified confidence level exactly. Unlike --min-confidence (which filters out lower levels), --only returns just that level:

# Show only likely_dead findings
prune scan --only likely_dead

Valid values: safe, review, likely_dead.

`--deletable`

Shows only files that are safe to delete — files with no living imports:

prune scan --deletable

When combined with --min-confidence, this filters to only safe-level deletable files.

The ranking is counter-intuitive: safe findings are the most certain candidates for deletion, but have the lowest rank. A higher --min-confidence value means more uncertain findings.

Output Format

On this page