feature-flag-mining

Name: feature-flag-mining codemod
Availability: InStock

Read-only mining codemod for Backstage FeatureFlagsApi usage sites.

No source edits are produced (return null). Each detection emits one
backstage_feature_flag_usage metric row so you can inventory declarations vs
consumers across a Backstage app or monorepo.

Detected patterns

`usage_kind`	Example
`declaration`	`featureFlags: [{ name: 'show-example-feature' }]`
`api_ref`	`useApi(featureFlagsApiRef)` only (imports / re-exports skipped)
`is_active`	`isActive('…')` or dynamic `isActive(stepFeatureFlag)`
`feature_flagged`	`<FeatureFlagged with="…">` / `without="…"`
`extension_predicate`	`if: { featureFlags: { $contains: 'experimental-features' } }`
`register_flag`	`featureFlagApi.registerFlag({ name: '…' })`
`ui_schema_flag`	`'ui:backstage': { featureFlag: '…' }` / `featureFlag: '…'`

is_active only fires when the file already signals Backstage feature flags
(featureFlagsApiRef, FeatureFlagged, a featureFlags property, or UI-schema
flag keys). Plain user.isActive() call sites are ignored.

Metric: `backstage_feature_flag_usage`

field	description
`usage_kind`	One of the kinds in the table above
`flag_name`	Literal name, `<expr:…>` when dynamic, or `<unknown>` for bare `api_ref`
`polarity`	`declare` / `check` / `with` / `without` / `contains` / `ref` / `register`
`detail`	Extra context (`useApi`, receiver text, `dynamic:…`, schema path, …)
`file`	Relative path of the scanned file
`line`	1-based line number
`symbol`	Enclosing function/class name, or `<file-scope>`

What this does not report

Framework plumbing paths: FeatureFlagsApi definitions, FeatureFlagged.tsx impl,
AppManager, apiFactories / predicates wiring, useElementFilter, mockApis,
and plugins/app default FeatureFlagsApi factory
Bare import / re-export / createApiRef of featureFlagsApiRef (only useApi(...))
Markdown docs / changelogs (workflow only scans *.{ts,tsx})
Unrelated isActive helpers when the file has no Backstage feature-flag signals
$contains predicates that are not nested under a featureFlags key

Run locally

bash
cd codemods/backstage/feature-flag-mining
pnpm test

pnpm dlx codemod@latest workflow run \
  -w codemods/backstage/feature-flag-mining/workflow.yaml \
  --target /path/to/backstage-app

Development

bash
pnpm test
pnpm run check-types
pnpm dlx codemod@latest workflow validate -w workflow.yaml

License

MIT