Create a new codemod project
Explore the generated project
scripts/
for shell scripts,
rules/
for ast-grep rules) and referencing them from
workflow.yaml
. This allows you to orchestrate complex, multi-step migrations using the best tool for each job.Understand an example workflow
workflow.yaml
will also differ depending on the codemod type you select:scripts/
for shell scripts, rules/
for ast-grep rules) and referencing them from workflow.yaml
. This allows you to orchestrate complex, multi-step migrations using the best tool for each job.Understand an example workflow
workflow.yaml
(when you choose the YAML-based ast-grep codemod for JavaScript/TypeScript) defines a simple workflow that applies an ast-grep rule to all TypeScript files in the src/
directory (excluding test files):rules/config.yml
contains an example rule:console.log(...)
and console.debug(...)
calls with logger.log(...)
in your TypeScript/JavaScript files.Validate & run your workflow
workflow validate
command checks syntax and schema compliance, but not logical correctness. Always test your workflows with real data to ensure they behave as expected.Learn more about validating workflows here.npx codemod@next workflow run ./my-workflow/
. $CODEMOD_PATH
points here inside every task.
Workflow Bundle & Loading Workflows
workflow.yaml
and any scripts, rules, or assets referenced by your workflow.Key | Required | Purpose |
---|---|---|
version | ✓ | Declare workflow schema version (default: "1" ). |
state | Declares shared-state schema. | |
templates | Re-usable blocks. | |
nodes | ✓ | Executable DAG. |
automatic
(default) or manual
.{ type: manual }
→ approval gate.run
or uses
, not both.run
or uses
, not both.Dynamic Matrix Task Recompilation
from_state
changes, Codemod CLI:WontDo
if their item is removed.Task UUIDs & Resume
Syntax | Meaning | Example |
---|---|---|
KEY=VAL | Set state key to value | count=10 |
KEY@=VAL | Append value to array at state key | shards@={"team":"core","shardId":"1"} |
Dot notation | Set nested state fields | config.retries=5 |
JSON values | Use valid JSON for objects/arrays | user={"name":"Alice","id":123} |
Container Runtimes
docker
, podman
, direct
(host shell).State Management & Persistence
Matrix Master Task
Completed
. If any fail, the master is Failed
.Cyclic Dependency Example
npx codemod@next workflow validate
or npx codemod@next workflow run
on a workflow with a cyclic dependency.shards
array to store team and shard informationcheckout-repo
template for cloning repositoriesmake-shards
node populates the state with shard datamatrix-codemod
node creates parallel tasks for each shard${{params.branch}}
— Supplied at runtime${{env.CI}}
— Host env var${{state.counter}}
— Live JSON value$team
, $shardId
, …).runtime: docker
and other container runtimes, allowing tasks to run in isolated environments.--param key=value
flags.