- Codebase analysis: Count occurrences of patterns, prop usages, component instances
- Migration tracking: Track what was rewritten (and in which shapes) while applying transforms
- Read-only codemods: Gather insights without modifying code
When to emit metrics
Prefer one metric name perjs-ast-grep step, with cardinality dimensions for the variants you care about—not a separate metric for every edge case.
Keep the metric count small. Encode differences as cardinality keys/values on the same atom. Snapshot
metrics.json next to fixtures that produce counts (jssg test -u).
Basic Usage
ImportuseMetricAtom from codemod:metrics to create a metric tracker:
Cardinality
Cardinality dimensions are key-value pairs that let you group and filter metrics. When you callincrement(), you pass an object with string keys and values:
component=Button).
Example: Counting Prop Usage
This read-only codemod counts how many times each prop is used onButton components:
Insights
Insights binds each dashboard query to one workflow step and loads that step’sjs-ast-grep script from the published package. Metric names must be statically visible in that script (useMetricAtom + increment)—not only in a different package file or helper import. This is the selected step’s script, not necessarily the package entry (for example scripts/codemod.ts). For scale (transforms or mining), see Performant codemods.
Insights runs the selected step on its own, so that step must compute its metric from the repository directly. Don’t rely on files written by an earlier step (for example, a collect step that writes JSON shards for an analyze step); the widget will return no results.