dead-poets 0.2.0

Find unused (dead) gettext PO/POT keys across a polyglot codebase (PHP, Twig, JS/TS) via real AST parsing.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

# dead-poets

[![CI](https://github.com/Segodnya/dead-poets/actions/workflows/ci.yml/badge.svg)](https://github.com/Segodnya/dead-poets/actions/workflows/ci.yml)
[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license)

A playful nod to *Dead Poets Society* — here **dead** means dead (unused) keys
hidden in your gettext PO catalogs.

Find **dead** (unused) gettext keys: msgids in your `.po`/`.pot` catalogs that no
source ever references. Polyglot — PHP, Twig, JS/TS — via tree-sitter AST parsing
(regex for Twig). Everything project-specific lives in config, so pointing it at a
new repo is a config change, not a code change.

## Install

```sh
cargo build --release   # binary at target/release/dead-poets
```

## Usage

```sh
dead-poets scan <path> -c dead-poets.toml [-f text|json] [-v] [--audit] \
  [--max-dead N | --max-dead-ratio R]
```

- `path` — project root (default `.`).
- `-c, --config` — config file (default `dead-poets.toml`).
- `-f, --format` — `text` (colored) or `json` (CI).
- `-v, --verbose` — repeatable (`-v`, `-vv`, ...).
- `--audit` — trust score for the Dead bucket (see below); advisory.
- `--max-dead N` / `--max-dead-ratio R` — dead-key budget (see below); override
  config, mutually exclusive.

Exit codes: `0` within budget · `1` over budget (CI fails) · `2` operational
error. Gate policy: `[output] fail_on = never | dead | dead-or-blind` (default
`dead`).

## Dead-key budget (ratchet)

A real catalog starts with thousands of dead keys, so failing on *any* is
unusable. Set a budget and lower it as you delete — a debt ceiling:

```toml
[output]
max_dead = 2900          # fail when dead > 2900
# max_dead_ratio = 0.15  # …or dead / total > 15% (mutually exclusive)
```

Default (`max_dead = 0`) fails on any dead key. The budget relaxes only the Dead
gate — `dead-or-blind` still fails on blind sites. The report prints a budget line
(and a `budget` object in JSON) with the remaining headroom.

## Classification

Universe = union of msgids across all catalogs (obsolete `#~` / fuzzy skipped).
Each key is:

- **Alive** — referenced, with `alive_via`: `literal` (`i18n('save_button')`),
  `guard` (a static fragment of a dynamic key — `` i18n(`cf_subtype_${x}`) `` keeps
  every `cf_subtype_*` alive; fragments shorter than `min_guard_len` are ignored),
  or `whitelist` (runtime-only keys).
- **Suspect** — no modeled call, but the msgid appears verbatim as a source literal
  (data table / enum dispatched dynamically). Review hint; exit-neutral.
- **Dead** — no reference of any kind.

The tool **biases toward keep**: a false "dead" ships a raw key to prod, while a
missed dead key costs nothing. A call with no static part (`i18n($x)`) is a **blind
spot** — counted per language, always reported.

## Auditing the Dead bucket

`--audit` greps each dead msgid against **raw source** (comments, HTML, heredocs,
substrings — not just AST literals) and tiers it:

- **substring** — the full msgid occurs verbatim.
- **skeleton** — placeholder keys (`%s`/`%d`/`{0}`) whose static fragments all
  appear (the `sprintf`-assembled tell).
- **none** — no trace: high-confidence dead.

Advisory and case-sensitive: never reclassifies or changes the exit code, and runs
only with `--audit` (zero default overhead). JSON gains an `audit` object.

## Configuration

```toml
[scan]
po_patterns = ["**/*.po", "**/*.pot"]
source_extensions = ["php", "twig", "js", "ts", "jsx", "tsx"]
ignore_dirs = ["vendor", "node_modules", "cache", "var"]   # on top of .gitignore
source_roots = ["."]                                       # list → multi-repo

# One [[calls]] block per translation convention.
[[calls]]
lang = "php"
kind = "method"               # function | method | filter | index
name = "get"                  # call/filter name, or indexed object for `index`
receiver = ["i18n", "this.i18n"]   # method only: allowed receivers
key_arg_index = 0             # which arg holds the key (0-based)

[whitelist]
file = "i18n-whitelist.txt"   # one key per line, # comments allowed
keys = ["dynamic.key1"]       # or inline

[output]
format = "text"               # text | json (overridden by -f)
fail_on = "dead"              # never | dead | dead-or-blind
min_guard_len = 3
max_dead = 2900               # optional budget (absolute)
# max_dead_ratio = 0.15       # …or a share of the universe
```

**Call kinds:** `function` (`i18n('key')`) · `method` with `receiver`
(`$i18n->get('key')`; `$`/`->`/`.` normalized away) · `filter` (`{{ 'key'|i18n }}`)
· `index` (`locale['key']`).

## Scope & safety

Keys are **Dead** only relative to the scanned roots. External consumers —
databases, other repos sharing the catalog, email/cron templates — are invisible,
so a `Dead` key may still be used. **Never auto-delete:** verify each key in your
TMS first.

## License

[Apache-2.0](LICENSE-APACHE) or [MIT](LICENSE-MIT), at your option.