feature-flag-stale-mining
Read-only miner for stale Backstage feature flags — names that are declared
but never consumed, or consumed but never declared (literal names only).
Companion to feature-flag-mining: that package inventories usage sites; this
one judges staleness via a repo-wide declare ↔ consume set-diff.
How it works
One JSSG step (scripts/codemod.ts) — required for Codemod Insights, which
binds widgets to a single workflow js_file:
- On the first file in a scan, build a repo-wide declare/consume index once
(text-prefiltered disk walk + parse), then cache it in module memory and
codemod:workflowstate - For each subsequent file, emit
backstage_feature_flag_stalerows for stale
sites in that file from the cached index (no re-walk)
Files whose source cannot match feature-flag signals are skipped before AST
detection. Source files are never modified (return null).
Stale kinds
stale_kind | Meaning |
|---|---|
declared_unused | Declared (featureFlags / registerFlag) but never consumed |
consumed_undeclared | Gated (isActive / FeatureFlagged / $contains / schema) but never declared |
Dynamic names (isActive(stepFeatureFlag), etc.) are ignored — they cannot be
set-diffed reliably from AST alone.
Metric: backstage_feature_flag_stale
| field | description |
|---|---|
stale_kind | declared_unused or consumed_undeclared |
confidence | high for literal set-diff with empty other side |
flag_name | Literal flag id |
file | Relative path of the stale site |
line | 1-based line |
symbol | Enclosing function/class, or <file-scope> |
usage_kind | Site shape (declaration, is_active, feature_flagged, …) |
declare_count | How many declare sites exist for this name (repo-wide) |
consume_count | How many consume sites exist for this name |
evidence | Compact proof string, e.g. declared_in_1_sites_consumed_in_0 |
remediation | Suggested cleanup |
What this does not report
- Healthy flags (declared and consumed)
- Framework FeatureFlagsApi plumbing (same denylist as usage miner)
- Dynamic-only flag references
- Whether users actually toggle a flag in the browser
License
MIT