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 refuses 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
    batch_size: 50

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_high_risk_dynamic: review
    high_risk_patterns:
      - eval
      - Function
      - "import("
    safe_patterns:
      - window
      - document
      - Math
      - JSON
      - Object
      - Array
      - process
      - Buffer
      - setTimeout
      - setInterval
      - console
  unused_variable:
    enabled: true
    confidence:
      default: safe
      if_exported: likely_dead
      if_high_risk_dynamic: review
    high_risk_patterns:
      - eval
      - Function
      - "import("
    safe_patterns:
      - window
      - document
      - Math
      - JSON
      - Object
      - Array
      - process
      - Buffer
      - setTimeout
      - setInterval
      - console
  unused_export:
    enabled: true
    confidence:
      if_not_imported: safe
      if_entrypoint: review
      if_high_risk_dynamic: 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: table
  min_confidence: safe
  include_evidence: true

Migration from v1

Prune supports configuration versions 1 and 2. If you're upgrading from config version 1, bumping to version 2 is optional — it's only required if you want to use the ts_config feature for path aliases.

version: 1
version: 2

Version 2 adds support for path aliases via ts_config. Prune supports versions 1 and 2 — version 2 enables ts_config, while version 1 works without it.

Field Reference

version

Type: integer
Required: yes (must be non-zero)

Prune accepts config versions 1 or 2. Version 2 enables ts_config for path aliases; version 1 works without them. Prune returns 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 used for analysis. Currently only js-ts is supported. If missing or unrecognized, prune scan returns 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.

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 syntax.

scan.exclude

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

Files and directories matching any exclude pattern are skipped.

scan.stream.enabled

Type: boolean
Default: false

Enables streaming mode. When true, Prune emits findings in file batches while scanning.

scan.stream.interval_ms

Type: integer
Default: 250

Interval in milliseconds between streaming flushes.

scan.stream.batch_size

Type: integer
Default: 50

Number of files processed per streaming batch. Must be greater than zero.

entrypoints

Entrypoints define the roots of the dependency graph. Files reachable from entrypoints are considered alive.

entrypoints.files

Type: list of strings

Explicit file paths treated as entrypoints.

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

entrypoints.patterns

Type: list of glob patterns

Files whose relative paths match these patterns are treated as entrypoints.

entrypoints:
  patterns:
    - src/pages/**
    - src/routes/**
    - src/app/**/*.ts

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. The possible_dynamic_usage rule uses these patterns.

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

rules

Each rule can be enabled/disabled and configured with confidence overrides.

Rule fields

rules.unused_function

Detects functions declared but never referenced.

rules:
  unused_function:
    enabled: true
    confidence:
      default: likely_dead
      if_high_risk_dynamic: review

rules.unused_variable

Detects variables declared but never referenced.

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

rules.unused_export

Detects exported symbols never imported by other files in the analyzed set.

rules:
  unused_export:
    enabled: true
    confidence:
      if_not_imported: safe
      if_entrypoint: review
      if_high_risk_dynamic: review

rules.unused_file

Detects files not imported by any other reachable file.

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

rules.possible_dynamic_usage

Detects configured feature flag patterns with uncertain or missing static references.

This rule replaced dead_feature_flag; the old key is still accepted for backward compatibility.

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

rules.suspicious_dynamic_usage

Detects dynamic APIs that block static certainty.

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

report

These fields define defaults for output formatting.

report.format

Type: string
Default: table
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

Minimum confidence threshold included in output.

report.include_evidence

Type: boolean
Default: true

Reserved for future use. Accepted in schema but currently not used in output formatting.

ts_config

Configures path alias resolution (for example @/utils, ~/components).

ts_config.enabled

Type: boolean
Default: false

Enable or disable path alias resolution.

ts_config.baseUrl

Type: string
Default: "."

Base directory used when resolving alias targets.

ts_config.paths

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

Alias mapping rules. The first mapped path is used during resolution.

ts_config:
  enabled: true
  baseUrl: .
  paths:
    "@/*":
      - src/*
    "~/*":
      - src/components/*
    "@shared/*":
      - packages/shared/*