From d671f55a0cd5d5f1bab8da1af65e701837c88286 Mon Sep 17 00:00:00 2001 From: Kinflou Date: Tue, 13 Oct 2026 16:36:11 +0800 Subject: [PATCH] docs: `generate` reports a tree, and `--list` is the per-file form cli#61 made the tree how `generate` reports its output rather than something only `--dry-run` drew, and added `--list` for the one-line-per-file form. `check-cli-drift.py` caught `--list` missing from `cli.md`, which is also what kept this out of the same PR - the check compares the page against the installed binary, so the flag had to ship first. The guide's "Running it" section showed neither `--dry-run` nor the tree, so it gains both, plus what `--list` has that a tree can't show: the schema each file came from, and the package version when several are generated at once. --- docs/docs/guide/codegen/generating-code.md | 22 +++++++++++++++++++++- docs/docs/reference/cli.md | 8 +++++--- 2 files changed, 26 insertions(+), 4 deletions(-) diff --git a/docs/docs/guide/codegen/generating-code.md b/docs/docs/guide/codegen/generating-code.md index 727b735..2f9da5c 100644 --- a/docs/docs/guide/codegen/generating-code.md +++ b/docs/docs/guide/codegen/generating-code.md @@ -137,7 +137,7 @@ idiomatic output for a past schema shape. ## Running it ``` -comline generate [--target ] [--out ] [--layout ] [--mode ] [--watch] +comline generate [--target ] [--out ] [--layout ] [--mode ] [--dry-run] [--list] [--watch] ``` `generate` validates the project and writes the code. Unlike `comline build` it @@ -148,9 +148,29 @@ repeatedly and from CI. comline generate # every configured target, per comline.toml comline generate --target rust # just rust comline generate --target rust --out ./bind # override this target's output root +comline generate --dry-run # report without writing anything comline generate --watch # regenerate on schema / config change ``` +Each target's files are reported as a tree: + +``` + ⚙️ language: typescript, version: 5.0, mode: lib + generated/typescript/ + ├─ package.json + ├─ src/ + │ ├─ index.ts + │ ├─ std/ + │ │ └─ http.ts + │ └─ types.ts + └─ tsconfig.json +``` + +`--list` prints one line per file instead, naming the schema each came from +(`api.ids → generated/rust/api.rs`) — and the package version, when several are +generated at once. `--dry-run` and `--list` are independent: the first decides +whether anything is written, the second how it is reported. + `comline clean` removes the generated output (the whole `out` directory when it is a dedicated one, e.g. `generated/`). It leaves `.comline/` alone — `comline reset` is the command that discards the version history. diff --git a/docs/docs/reference/cli.md b/docs/docs/reference/cli.md index 044bcf8..d8883c2 100644 --- a/docs/docs/reference/cli.md +++ b/docs/docs/reference/cli.md @@ -35,7 +35,7 @@ parse → resolve imports → validate → (freeze into .comline/) → (generate | `comline add ` / `comline add --git --commit --version ` | Add a dependency to `config.idp`, imported as `use ::…`: resolved first (a git pin is fetched into `.comline/deps-cache/`), then written with its `hash` pinned. `--no-hash` skips the pin. | | `comline check` | Parse, resolve and validate. No `.comline/` write (beyond fetching git dependencies), no version bump — safe for editors, hooks, CI. | | `comline build [--release] [--watch]` | Compile, validate, freeze a new immutable version into `.comline/`; print the changelog and the bump. `--release` is currently a no-op. | -| `comline generate [--target ] [--out ] [--layout ] [--mode ] [--external-std] [--no-external-std] [--dry-run] [--watch]` | Validate (no freeze), then write generated code. Location/layout from [`comline.toml`](congregation/comline-toml.md); targets from there or `config.idp`. | +| `comline generate [--target ] [--out ] [--layout ] [--mode ] [--external-std] [--no-external-std] [--dry-run] [--list] [--watch]` | Validate (no freeze), then write generated code. Location/layout from [`comline.toml`](congregation/comline-toml.md); targets from there or `config.idp`. | | `comline diff []` | Show schema changes between two built versions. Each argument is a version (`0.2.0`), a commit hash (4+ chars), or `HEAD` (`` default). | | `comline clean [--dry-run]` | Remove generated code (the `generate` output root or files). Never touches `.comline/`. | | `comline reset [--force] [--dry-run]` | **Destructive.** Delete `.comline/` — the whole version history, no undo — *and* generated code. Next `build` starts over at `0.0.1`. On a terminal it shows how many versions will be lost and makes you type `reset`; without a terminal it refuses (exit `2`) unless `--force`. | @@ -49,8 +49,10 @@ reference `comline_std` as its own crate instead of inlining it, and `--no-external-std` inlines it; either overrides [`comline.toml`](congregation/comline-toml.md)'s `[generate] external_std`, which itself defaults to on in `lib` mode and off in `code` mode. -`--dry-run` lists the files each target would write, as a tree, and writes -nothing. Today `rust` and `typescript` are the generators, and both do `code` +Each target's files are drawn as a tree. `--list` prints them one per line +instead, with the schema each came from — and, when several package versions +are generated at once, the version each line belongs to. `--dry-run` writes +nothing and reports either way. Today `rust` and `typescript` are the generators, and both do `code` and `lib` mode. ## Global flags