Skip to content

docs: port the v3 docs audit to the 2.x doc trees - #767

Merged
Kamirus merged 1 commit into
mainfrom
kamil-claude/exciting-chandrasekhar-d2ed9f
Aug 14, 2026
Merged

docs: port the v3 docs audit to the 2.x doc trees#767
Kamirus merged 1 commit into
mainfrom
kamil-claude/exciting-chandrasekhar-d2ed9f

Conversation

@Kamirus

@Kamirus Kamirus commented Aug 14, 2026

Copy link
Copy Markdown
Collaborator

The 2.x CLI docs contradicted actual CLI behavior in nine places — missing test/bench discovery rules, an undocumented test mode, undocumented flags and environment variables, and stale toolchain versions. Each defect was found by the v3 docs audit (branch kamil-claude/v3-sync-2x-docs) and re-verified here against the 2.x source (cli/cli.ts, cli/commands/**) before porting, since 2.x behavior sometimes differs from v3.

What was wrong

  • mops test: the mode list omitted replica (the CLI accepts interpreter|wasi|replica); the // @testmode block showed only wasi and claimed the marker must be the first line — it is an exact full-line match anywhere in the file (lines.includes(...) in test/test.ts); "Make sure your actor doesn't have a name" contradicts the detection regex /^(persistent )?actor( class)?/, which matches named actors too; discovery was described as "test/*.test.mo" but is **/test?(s)/**/*.test.mo with a test/lib.mo short-circuit and a [filter] that widens the glob to *<filter>*.mo.
  • mops bench: discovery is **/bench?(mark)/**/*.bench.mo with the same filter widening — the page said only "bench/*.bench.mo".
  • mops owner / maintainer: --yes undocumented.
  • mops user import: --no-encrypt undocumented.
  • Environment variables: MOPS_ENV (expands {MOPS_ENV} in path dependencies, defaults to local) and MOPS_CWD (chdir before the command runs, for npm scripts) undocumented.
  • mops docs generate: the -o short alias undocumented.
  • mops toolchain info / update: both accept wasm-opt (it is in TOOLCHAINS), and update <tool> errors when the tool is not pinned in [toolchain] — verified in commands/toolchain/index.ts. The pages implied a four-tool list and unconditional updates.
  • mops build: the "Each canister configuration supports" list omitted wasmMemoryLimit (used in an example on the same page) and the migrations/check-stable subtables.
  • Toolchain overview / use: stale example versions moc 0.10.3 / wasmtime 16.0.0 (and pocket-ic 1.0.0 in use) → 1.0.0 / 41.0.0 / 15.0.0, matching 09-mops.toml.md.

Deviations from the v3 wording

  • The replica mode bullet is worded replica-neutrally — 2.x still has the deprecated dfx path selected via --replica, so the v3 "PocketIC replica" phrasing would be wrong here.
  • The v3 MOPS_ENV note about lockfile staleness is not ported — it describes v3-only lockfile behavior and links a v3-only anchor.
  • The v3 missing-blank-line fix in mops-build does not apply — 2.x has no --locked section on that page and the blank line is already present.

Tree sync

docs/docs/ and docs/versioned_docs/version-2.x/ must be byte-identical (AGENTS.md). Besides applying every fix to both trees, this also carries #761's MOPS_POCKET_IC_URL wording into versioned_docs (09-mops.toml.md, cli/4-dev/03-mops-build.md), where it had only landed in docs/docs/. diff -r docs/docs docs/versioned_docs/version-2.x is now empty, and cd docs && npm run build passes (Docusaurus validates links and anchors).

🤖 Generated with Claude Code

@Kamirus @claude
docs: port the v3 docs audit to the 2.x doc trees
cbef545 
Fixes found by auditing the docs against the 2.x CLI (cli/cli.ts,
cli/commands/**): mops test's mode list omitted `replica` (and the
`// @Testmode replica` marker, the any-line matching rule, and the
`test?(s)` discovery glob with its `lib.mo` short-circuit and filter
widening); the anonymous-actor requirement contradicted the detection
regex; bench discovery omitted `benchmark/` and filter widening;
`toolchain info`/`update` omitted wasm-opt and `update`'s pinned-only
semantics; mops build's canister field list omitted `wasmMemoryLimit`
and the migrations/check-stable subtables; `--yes` (owner/maintainer),
`--no-encrypt` (user import), `-o` (docs generate), MOPS_ENV and
MOPS_CWD were undocumented; toolchain overview/use examples used stale
versions.

Also re-syncs the #761 MOPS_POCKET_IC_URL wording into versioned_docs,
which had drifted from docs/docs — the two trees are byte-identical
again.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

Cursor AI review

👍 APPROVE — looks safe to merge

Category Assessment Details
Summary ✅ Docs-only port of the v3 docs audit into both docs/docs/ and docs/versioned_docs/version-2.x/: corrects test/bench discovery, undocumented flags/env vars, toolchain tool lists/versions, and syncs MOPS_POCKET_IC_URL wording into the 2.x tree.
Code Quality ✅ No code changes; edits are documentation corrections only, applied symmetrically across both doc trees.
Consistency ✅ Matches AGENTS.md dual-tree sync; claims checked against cli/commands/test/test.ts, cli/commands/bench.ts, cli/cli.ts, cli/commands/toolchain/{index,toolchain-utils}.ts, cli/resolve-packages.ts.
Security ✅ Docs-only; no authn/authz, integrity, install/resolve, backend, or workflow changes.
Tests ✅ No runtime/test surface; behavior claims verified against CLI sources above rather than snapshots.
Maintainability ✅ Closes real doc/CLI drift and restores docs/docs ↔ versioned_docs/version-2.x parity (including 09-mops.toml.md / build MOPS_POCKET_IC_URL carry-over).

Verdict

Decision: APPROVE
Risk: Very Low
Reason: Pure documentation corrections verified against current CLI behavior; no production code, registry, or release-pipeline impact.

Generated for commit cbef545

automation-sa-sre
automation-sa-sre approved these changes Aug 14, 2026
View reviewed changes

@automation-sa-sre automation-sa-sre left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated approval: the AI review verdict for cbef545 is APPROVE. See the "Cursor AI review" comment for details.

@Kamirus
Kamirus merged commit 8d2cbab into main Aug 14, 2026
27 checks passed
@Kamirus
Kamirus deleted the kamil-claude/exciting-chandrasekhar-d2ed9f branch August 14, 2026 12:55
@Kamirus Kamirus mentioned this pull request Aug 14, 2026
Merged
Kamirus added a commit that referenced this pull request Aug 16, 2026
@Kamirus
chore: merge main into v3 (2.24.0 release, MOPS_POCKET_IC_URL) (#768)
120cd73 
Brings `main` up to
[2.24.0](#764) into the v3
line: the [`MOPS_POCKET_IC_URL` attach
mode](#761), the [2.21.0–2.23.0
docs backfill](#763), the [2.x
port of the v3 docs
audit](#767), and the 2.24.0
release/`cli-releases` artifacts.

**Merge this with a merge commit, not squash** — it is a `main`→`v3`
sync and must keep both parents.

## MOPS_POCKET_IC_URL on v3

Every mops-managed PocketIC path (`build --check-deploy`, replica tests,
`mops bench`, `mops watch`, the tests/benches `mops publish` runs) can
now attach to an already-running PocketIC server instead of spawning the
`[toolchain] pocket-ic` binary. The port is rewritten for v3 semantics —
v3 has no dfx replica and no legacy `pic-ic` client, so the feature
lands as: pin required as before, `MOPS_POCKET_IC_URL` is the one
alternative source, and a pin is ignored with a warning when the URL is
set.

Resolution choices a reviewer should check:

- `startPocketIc` keeps v3's single-client shape (no `client: "dfinity"`
overloads, no `AnyPocketIc` unions) and gains main's thunked options —
in attached mode `toolchain.bin("pocket-ic")` is never resolved, so no
binary is downloaded and no pin is needed.
- v3 keeps pin validation in the toolchain layer (`assertMinimumVersion`
at download, `toolchain.bin` erroring on a missing pin), so main's
early-validation block in `build.ts` stays deleted; the attached-mode
gate makes it moot there anyway. The `--check-deploy requires a PocketIC
pin` test still asserts v3's error text.
- `mops test` keeps no `--replica` flag; main's SIGINT bounded-teardown
and settled-start error surfacing are ported (via `cliErrorFrom`), the
dfx branches are not.
- `mops bench` records no `replicaVersion` in attached mode (ported at
the options default, since v3 has no replica-type dispatch).
- Main's `--check-deploy warns when MOPS_POCKET_IC_URL ignores a pin`
test moved into `build-check-deploy.test.ts`, which owns the
`build/check-deploy` fixture on v3 (it does not exist on main); the two
`build/success`-based URL tests stayed in `build.test.ts`.

## What was deliberately not taken

- The `.mo`-baseline fast-path fix
([9de549d](9de549d2)) and
its `mo-baseline-em` fixture: v3 rejects `.mo` check-stable baselines
outright ([#758](#758)), so
there is no 3-step path to keep them on. The 2.24.0 changelog entry is
kept as the historical record.
- All dfx fallback code and copy (`--replica`, `dfx-pocket-ic`,
deprecation warnings) — gone on v3, stays gone.

## Docs, per the AGENTS.md merge rules

- `docs/versioned_docs/version-2.x/` is byte-identical to `main`
(verified with `git diff origin/main -- docs/versioned_docs/` → empty).
- `docs/docs/` keeps v3's pages; the only delta vs v3 is the new-feature
copy rewritten in v3 terms (pin required unless `MOPS_POCKET_IC_URL` is
set, no dfx mentions — main's "`--replica dfx` is unaffected" line is
dropped from the env-vars page).
- `docs/docusaurus.config.js` keeps `lastVersion: '2.x'`; `release.yml`
keeps the docs deploy step.

## Verified

`tsc --noEmit` clean, ESLint clean, and the merge-adjacent Jest suites
pass locally (109 tests across `pocket-ic-client`, `pocket-ic`,
`check-stable`, `bench`, `build`, `build-check-deploy`, `cli`,
`vendor-pic`, `test-reporter`, `publish-dry-run`). CI runs the full
matrix.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@automation-sa-sre automation-sa-sre automation-sa-sre approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@Kamirus @automation-sa-sre