Configuration

Prune is configured through a YAML file, by default named prune.yaml in the current directory. You can generate a starting config with prune init, or write one from scratch using the reference below.

The version field is required and must be 2 (or 1 for legacy configs). Prune will refuse to run if version is missing or zero.

Full Schema

version: 2

project:
  name: my-project
  language: js-ts

ts_config:
  enabled: false
  baseUrl: .
  paths:
    "@/*":
      - src/*
    "~/*":
      - src/components/*

scan:
  paths:
    - src
  include:
    - '**/*.ts'
    - '**/*.tsx'
    - '**/*.js'
    - '**/*.jsx'
  exclude:
    - node_modules/**
    - dist/**
    - build/**
    - .next/**
    - out/**
    - coverage/**
  stream:
    enabled: false
    interval_ms: 250

entrypoints:
  files:
    - src/index.ts
  patterns:
    - src/pages/**
    - src/routes/**

feature_flags:
  patterns:
    - 'flags\.[A-Z0-9_]+'
    - 'featureFlags\.[A-Za-z0-9_]+'

rules:
  unused_function:
    enabled: true
    confidence:
      default: likely_dead
      if_dynamic_usage: review
  unused_variable:
    enabled: true
    confidence:
      default: safe
      if_exported: likely_dead
      if_dynamic_usage: review
  unused_export:
    enabled: true
    confidence:
      if_not_imported: safe
      if_entrypoint: review
  unused_file:
    enabled: true
    confidence:
      default: safe
      if_entrypoint: review
  possible_dynamic_usage:
    enabled: true
    confidence:
      if_never_referenced: safe
      if_dynamic_reference: review
  suspicious_dynamic_usage:
    enabled: true
    patterns:
      - eval
      - Function
      - require
      - 'import('
    confidence:
      default: review

report:
  format: pretty
  min_confidence: safe
  include_evidence: true

Migration from v1

If you're upgrading from config version 1, the only change needed is bumping the version number:

version: 1
version: 2

Version 2 adds support for path aliases via ts_config.Configs using version 1 will continue to work — Prune only requires version >= 1.

scan: paths:

• src include:
• '**/*.ts'
• '**/*.tsx'
• '**/*.js'
• '**/*.jsx' exclude:
• node_modules/**
• dist/**
• build/**
• .next/**
• out/**
• coverage/** stream: enabled: false interval_ms: 250

entrypoints: files:

• src/index.ts patterns:
• src/pages/**
• src/routes/**

feature_flags: patterns:

• 'flags.[A-Z0-9_]+'
• 'featureFlags.[A-Za-z0-9_]+'

rules: unused_function: enabled: true confidence: default: likely_dead if_dynamic_usage: review unused_variable: enabled: true confidence: default: safe if_exported: likely_dead if_dynamic_usage: review unused_export: enabled: true confidence: if_not_imported: safe if_entrypoint: review unused_file: enabled: true confidence: default: safe if_entrypoint: review possible_dynamic_usage: enabled: true confidence: if_never_referenced: safe if_dynamic_reference: review suspicious_dynamic_usage: enabled: true patterns:

• eval
• Function
• require
• 'import(' confidence: default: review

report: format: pretty min_confidence: safe include_evidence: true

---

## Field Reference

### `version`

**Type:** integer  
**Required:** yes

Schema version. Must be `1`.
Schema version. Must be `2` (or `1` for legacy configs).

Prune will return an error if this field is absent or set to `0`.

---

### `project`

#### `project.name`

**Type:** string  
**Default:** `"prune"`

A human-readable name for the project. Used for display purposes only.

#### `project.language`

**Type:** string  
**Required:** yes (effectively)  
**Accepted values:** `js-ts`

The language mode to use for analysis. Currently only `js-ts` is supported. If missing or set to an unrecognized value, `prune scan` will return an error.

---

### `scan`

#### `scan.paths`

**Type:** list of strings  
**Default:** `["."]`

Directories to walk when collecting source files. Paths are resolved relative to the directory containing `prune.yaml`, unless they are absolute. If `--paths` is passed on the CLI, it overrides this field entirely.

#### `scan.include`

**Type:** list of glob patterns  
**Default:** `["**/*.js", "**/*.jsx", "**/*.ts", "**/*.tsx"]`

A file must match at least one include pattern to be analyzed. Uses [doublestar](https://github.com/bmatcuk/doublestar) glob syntax. If empty, all files under `scan.paths` are candidates (before exclusion).

#### `scan.exclude`

**Type:** list of glob patterns  
**Default:** `["node_modules/**", "dist/**", "build/**", ".next/**", "out/**", "coverage/**"]`

Files and directories matching any exclude pattern are skipped. Directory exclusion is applied early — matching directories are not walked. Uses doublestar glob syntax.

#### `scan.stream.enabled`

**Type:** boolean  
**Default:** `false`

Enables streaming mode. When true, Prune emits findings as batches of files are processed, rather than waiting for the full analysis to complete.

#### `scan.stream.interval_ms`

**Type:** integer  
**Default:** `250`

Interval in milliseconds between stream flushes. A batch is emitted when either 50 files have been processed or this interval has elapsed since the last flush.

---

### `entrypoints`

Entrypoints define the roots of the dependency graph. Files reachable from entrypoints — directly or transitively — are considered alive. Files and exports not reachable from any entrypoint are candidates for the `unused_file` and `unused_export` rules.

#### `entrypoints.files`

**Type:** list of strings

Explicit file paths that serve as entrypoints. Paths are matched against relative paths within the scanned tree using exact string comparison.

```yaml
entrypoints:
  files:
    - src/index.ts
    - src/main.tsx

entrypoints.patterns

Type: list of glob patterns

Files whose relative paths match any of these patterns are treated as entrypoints. Uses doublestar glob syntax.

entrypoints:
  patterns:
    - src/pages/**      # Next.js pages
    - src/routes/**     # React Router routes
    - src/app/**/*.ts   # all TypeScript files in src/app

feature_flags

feature_flags.patterns

Type: list of regular expression strings
Default: ["flags\\.[A-Z0-9_]+", "featureFlags\\.[A-Za-z0-9_]+"]

Regular expressions used to detect feature flag references in source code. The possible_dynamic_usage rule uses these patterns to find flag accesses in the AST (via member_expression and subscript_expression nodes) and report flags that are never referenced.

feature_flags:
  patterns:
    - 'flags\.[A-Z0-9_]+'
    - 'featureFlags\.[A-Za-z0-9_]+'
    - 'FEATURE_FLAGS\.[A-Z_]+'

rules

Each rule can be enabled or disabled and has configurable confidence overrides. If a rule key is absent from the config, the rule defaults to enabled.

Rule fields

rules.unused_function

Detects functions declared in a file but never called or referenced.

rules:
  unused_function:
    enabled: true
    confidence:
      default: likely_dead          # no dynamic usage in the file
      if_dynamic_usage: review      # file contains eval/require/import()

rules.unused_variable

Detects variables declared in a file but never referenced.

rules:
  unused_variable:
    enabled: true
    confidence:
      default: safe
      if_exported: likely_dead
      if_dynamic_usage: review

rules.unused_export

Detects exported symbols (functions, classes, constants) that are never imported by any other file in the analyzed set.

rules:
  unused_export:
    enabled: true
    confidence:
      if_not_imported: safe        # exported but not imported by anyone
      if_entrypoint: review        # exported from an entrypoint file

rules.unused_file

Detects files that are never imported by any other file reachable from entrypoints.

rules:
  unused_file:
    enabled: true
    confidence:
      default: safe
      if_entrypoint: review

rules.possible_dynamic_usage

Detects feature flag references matching feature_flags.patterns that are never referenced in the codebase. If no flags are found at all matching the patterns, a single finding is emitted.

rules:
  possible_dynamic_usage:
    enabled: true
    confidence:
      if_never_referenced: safe
      if_dynamic_reference: review

rules.suspicious_dynamic_usage

Detects use of APIs that block static certainty about reachability. By default checks for eval, Function, require, and import(. Customizable via patterns.

rules:
  suspicious_dynamic_usage:
    enabled: true
    patterns:
      - eval
      - Function
      - require
      - 'import('
    confidence:
      default: review

report

These fields set defaults for the output, but CLI flags (--format, --min-confidence) take precedence over config values when provided.

report.format

Type: string
Default: pretty
Accepted values: pretty, json, ndjson, table (alias for pretty)

Default output format for prune scan.

report.min_confidence

Type: string
Default: safe
Accepted values: safe, likely_dead, review

The minimum confidence level for findings to be included in output. Findings below this threshold are filtered out.

report.include_evidence

Type: boolean
Default: true

Reserved for future use. Currently accepted in the config schema but not used in output formatting.

ts_config

Configures module resolution for path aliases (e.g., @/utils, ~/components). Mirrors TypeScript's tsconfig.json paths and baseUrl options.

ts_config.enabled

Type: boolean
Default: false

Enable or disable path alias resolution. When disabled (or not specified), all aliases are treated as external imports.

ts_config.baseUrl

Type: string
Default: "."

The base directory for resolving non-relative module paths. Corresponds to compilerOptions.baseUrl in TypeScript.

ts_config.paths

Type: map of string to list of strings
Default: {}

A map of alias patterns to their resolved paths. Uses glob-like pattern matching where * matches any string.

ts_config:
  enabled: true
  baseUrl: .
  paths:
    "@/*":        # @/utils/helper → src/utils/helper
      - src/*
    "~/*":       # ~/components/Button → src/components/Button
      - src/components/*
    "@shared/*":
      - packages/shared/*

The first path in each mapping list is used for resolution. If the resolved file is not found, the import is marked with review confidence.