Skip to content

Commit 7a8cdc9

Browse files
mohab-samehmohab-sameh
authored
docs: Validate & fix cli docs (#1588)
* wip * change flags & options to bullets * fix invalid workflow command usage * Update workflows.mdx * update jssg usage * revert roadmap section * remove redundant dividers * update quickstart * update quick start example * re-organize cli & workflows structure * remove extra dividers * fix card urls * lint
1 parent 733de58 commit 7a8cdc9

File tree

10 files changed

+435
-159
lines changed

10 files changed

+435
-159
lines changed

‎apps/docs/cli.mdx

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,15 @@ Codemod CLI helps you discover, run, and share codemods—all right from your te
77

88
## Getting started
99

10+
<Card title="Creating Codemod Workflows" href="cli/workflows" icon="play">
11+
Define and run multi-step code modification workflows with shared state and parallel execution.
12+
</Card>
13+
1014
<CardGroup>
11-
<Card title="Creating Codemod Workflows" href="cli/workflows">
12-
Define and run multi-step code modification workflows with shared state and parallel execution.
15+
<Card title="Codemod CLI Reference" href="cli/cli-reference" icon="terminal">
16+
Explore the full command and option reference for Codemod CLI.
1317
</Card>
14-
<Card title="jssg: JavaScript ast-grep" href="cli/jssg">
18+
<Card title="jssg: JavaScript ast-grep" href="cli/jssg" icon="js">
1519
Perform fast, AST-based searches & transformations using a grep-like interface.
1620
</Card>
1721
</CardGroup>

‎apps/docs/cli/cli-reference.mdx

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
---
2+
title: 'Codemod CLI'
3+
description: 'Orchestrate large-scale code migrations with Codemod CLI.'
4+
icon: 'terminal'
5+
---
6+
7+
Codemod CLI (new) is accessible using the `npx codemod@next` command. The following commands and options are available:
8+
9+
- `workflow` — Manage workflows (see subcommands below)
10+
- `jssg` — JavaScript ast-grep execution (see subcommands below)
11+
- `init` — Initialize a new workflow project
12+
- `login` — Login to a registry
13+
- `logout` — Logout from a registry
14+
- `whoami` — Show current authentication status
15+
- `publish` — Publish a workflow
16+
- `search` — Search for packages in the registry
17+
- `run` — Run a codemod from the registry
18+
- `cache` — Manage package cache (see subcommands below)
19+
20+
---
21+
22+
### `codemod@next workflow`
23+
24+
Manage and execute workflow YAMLs.
25+
26+
<ResponseField name="workflow run">
27+
Run a workflow.
28+
</ResponseField>
29+
```bash
30+
npx codemod@next workflow run -w <workflow.yaml|directory> [--param key=value]
31+
```
32+
- `-w, --workflow <PATH>` (string) — Path to workflow file or directory. (required)
33+
- `--param <KEY=VALUE>` (string) — Workflow parameters (format: key=value).
34+
35+
<ResponseField name="workflow resume">
36+
Resume a paused workflow.
37+
</ResponseField>
38+
```bash
39+
npx codemod@next workflow resume -i <ID> [-t <TASK>] [--trigger-all]
40+
```
41+
- `-i, --id <ID>` (string) — Workflow run ID. (required)
42+
- `-t, --task <TASK>` (string) — Task ID to trigger (can be specified multiple times).
43+
- `--trigger-all` (boolean) — Trigger all awaiting tasks.
44+
45+
<ResponseField name="workflow validate">
46+
Validate a workflow file.
47+
</ResponseField>
48+
```bash
49+
npx codemod@next workflow validate -w <workflow.yaml>
50+
```
51+
- `-w, --workflow <FILE>` (string) — Path to workflow file. (required)
52+
53+
| Check | Ensures |
54+
|-----------------------------|-----------------------------------------|
55+
| Schema validation | YAML matches the workflow spec |
56+
| Unique IDs | Node & template IDs are unique |
57+
| Dependency validation | Every `depends_on` exists |
58+
| Cyclic dependency detection | DAG has no cycles |
59+
| Template references | All `template:` IDs exist |
60+
| Matrix validation | `from_state` matches schema |
61+
| State schema validation | `state.schema` is valid |
62+
| Variable syntax | `${{…}}` uses `params`, `env`, `state` |
63+
64+
<Info>
65+
<b>Why validate?</b> Validation catches issues before execution, saving time and preventing runtime errors.
66+
</Info>
67+
68+
<ResponseField name="workflow status">
69+
Show workflow run status.
70+
</ResponseField>
71+
```bash
72+
npx codemod@next workflow status -i <ID>
73+
```
74+
- `-i, --id <ID>` (string) — Workflow run ID. (required)
75+
76+
<ResponseField name="workflow list">
77+
List workflow runs.
78+
</ResponseField>
79+
```bash
80+
npx codemod@next workflow list [-l <LIMIT>]
81+
```
82+
- `-l, --limit <LIMIT>` (number) — Number of workflow runs to show. (default: 10)
83+
84+
<ResponseField name="workflow cancel">
85+
Cancel a workflow run.
86+
</ResponseField>
87+
```bash
88+
npx codemod@next workflow cancel -i <ID>
89+
```
90+
- `-i, --id <ID>` (string) — Workflow run ID. (required)
91+
92+
---
93+
94+
### `codemod@next jssg`
95+
96+
See [this page](/cli/jssg) for full details and options for running and testing jssg codemods.
97+
98+
---
99+
100+
### `codemod@next init`
101+
102+
Initialize a new workflow project.
103+
```bash
104+
npx codemod@next init [PATH] [options]
105+
```
106+
<ResponseField name="[PATH]" type="string">
107+
Project directory name.
108+
</ResponseField>
109+
<ResponseField name="--name <NAME>" type="string">
110+
Project name (defaults to directory name).
111+
</ResponseField>
112+
<ResponseField name="--project-type <PROJECT_TYPE>" type="string">
113+
Project type: `shell`, `ast-grep-js`, `ast-grep-yaml`.
114+
</ResponseField>
115+
<ResponseField name="--language <LANGUAGE>" type="string">
116+
Target language.
117+
</ResponseField>
118+
<ResponseField name="--description <DESCRIPTION>" type="string">
119+
Project description.
120+
</ResponseField>
121+
<ResponseField name="--author <AUTHOR>" type="string">
122+
Author name and email.
123+
</ResponseField>
124+
<ResponseField name="--license <LICENSE>" type="string">
125+
License.
126+
</ResponseField>
127+
<ResponseField name="--private" type="boolean">
128+
Make package private.
129+
</ResponseField>
130+
<ResponseField name="--force" type="boolean">
131+
Overwrite existing files.
132+
</ResponseField>
133+
<ResponseField name="--no-interactive" type="boolean">
134+
Use defaults without prompts.
135+
</ResponseField>
136+
137+
### `codemod@next login`
138+
139+
Login to a registry.
140+
```bash
141+
npx codemod@next login [--registry <REGISTRY>] [--scope <SCOPE>]
142+
```
143+
<ResponseField name="--registry <REGISTRY>" type="string">
144+
Registry URL.
145+
</ResponseField>
146+
<ResponseField name="--scope <SCOPE>" type="string">
147+
Organization or user scope for publishing.
148+
</ResponseField>
149+
150+
### `codemod@next logout`
151+
152+
Logout from a registry.
153+
```bash
154+
npx codemod@next logout [--registry <REGISTRY>] [--all]
155+
```
156+
<ResponseField name="--registry <REGISTRY>" type="string">
157+
Registry URL to logout from.
158+
</ResponseField>
159+
<ResponseField name="--all" type="boolean">
160+
Logout from all registries.
161+
</ResponseField>
162+
163+
### `codemod@next whoami`
164+
165+
Show current authentication status.
166+
```bash
167+
npx codemod@next whoami [--registry <REGISTRY>] [--detailed]
168+
```
169+
<ResponseField name="--registry <REGISTRY>" type="string">
170+
Registry URL to check.
171+
</ResponseField>
172+
<ResponseField name="--detailed" type="boolean">
173+
Show detailed information including token scopes.
174+
</ResponseField>
175+
176+
### `codemod@next publish`
177+
178+
Publish a workflow to a registry.
179+
```bash
180+
npx codemod@next publish [PATH] [options]
181+
```
182+
<ResponseField name="[PATH]" type="string">
183+
Path to codemod directory.
184+
</ResponseField>
185+
<ResponseField name="--version <VERSION>" type="string">
186+
Explicit version override.
187+
</ResponseField>
188+
<ResponseField name="--registry <REGISTRY>" type="string">
189+
Target registry URL.
190+
</ResponseField>
191+
<ResponseField name="--tag <TAG>" type="string">
192+
Tag for the release.
193+
</ResponseField>
194+
<ResponseField name="--access <ACCESS>" type="string">
195+
Access level (`public`, `private`).
196+
</ResponseField>
197+
<ResponseField name="--dry-run" type="boolean">
198+
Validate and pack without uploading.
199+
</ResponseField>
200+
201+
### `codemod@next search`
202+
203+
#### `codemod@next search`
204+
205+
Search for packages in the registry.
206+
```bash
207+
npx codemod@next search [QUERY] [options]
208+
```

‎apps/docs/cli/jssg.mdx

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,20 @@ jssg is a JavaScript/TypeScript toolkit that simplifies writing and testing ast-
88

99
## Running Codemods
1010

11-
To run a jssg codemod on a target directory for a specific language like Java, use the following command:
11+
To run a jssg codemod, use the following command:
12+
```bash
13+
npx codemod@next jssg run [codemod_file] [target_directory] [options]
14+
```
15+
16+
For example, to run an jssg codemod on a directory using Java:
1217

1318
```bash
14-
npx codemod@latest jssg run /path/to/my-codemod.js /path/to/target --language java
19+
npx codemod@next jssg run /path/to/my-codemod.js /path/to/target --language java
1520
```
1621

17-
Note: Although your jssg codemods are written in JS/TS, the target language can be something else.
22+
<Tip>
23+
Although your jssg codemods are written in JS/TS, the target language can be something else.
24+
</Tip>
1825

1926
### Options
2027

@@ -64,14 +71,14 @@ The jssg testing framework provides testing capabilities for jssg codemods using
6471
└── file2.js
6572
```
6673

67-
2. **Run the tests** using the `npx codemod@latest jssg test` command.
74+
2. **Run the tests** using the `npx codemod@next jssg test` command.
6875

6976
```bash
7077
# Run tests for a codemod
71-
npx codemod@latest jssg test /path/to/my-codemod.js --language javascript
78+
npx codemod@next jssg test /path/to/my-codemod.js --language javascript
7279

7380
# Update snapshots (creates or updates the `expected.js` files)
74-
npx codemod@latest jssg test /path/to/my-codemod.js --language javascript --update-snapshots
81+
npx codemod@next jssg test /path/to/my-codemod.js --language javascript --update-snapshots
7582
```
7683

7784
### Required Arguments
@@ -130,7 +137,7 @@ Options for controlling how tests are executed.
130137
Options for managing test snapshots and expected errors.
131138

132139
<ResponseField name="--update-snapshots, -u" type="boolean">
133-
Create or update the `expected` files with the output of the codemod.
140+
Create or update the `expected` files with the output of the codemod. (`-u` is a shorthand for `--update-snapshots`)
134141
</ResponseField>
135142
<ResponseField name="--expect-errors" type="string">
136143
A comma-separated list of test patterns that are expected to fail.

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy