Tools
What to invoke, and the gotchas that belong to a tool rather than to a repository. workflow.md says when to run these and why; this says how they are spelled and what surprises them.
Each tool is an executable, run by its name: dev, pkgmgr, impl-tool.
dev-tool
The development CLI: the verification gate, the generators, and the module and dependency queries.
dev <group> <command> [args]
Its surface: gate, format, lint --fix, typecheck, schema gen, command gen, api gen, test, module select, build, install, sync, the project group (crossing list, list, mark, readme list), schema list, schema mark, command list, command mark, and the module group (list, graph, exports, declared-dependencies, detect-dependencies).
gate is the verification gate as one command. It runs each check the repository’s gate list holds – .dev-tool/config.yml, dev-tool’s default where none is stated – as a dev-tool process of its own, in order and every one whatever an earlier one answered, then prints a line per check, [PASS] or [FAIL] with the check’s name and how long it took, and one for the gate; it exits non-zero if any failed. Each check’s output streams to stderr under a === <check> line, and --response-format json answers the outcomes and durations as checks[]. It runs no test, and a gate list naming test is refused: test is run beside it, and ends with the same outcome-and-duration line for its run. Each check in the list states where it runs (placement: both | ci | local, both where it states none): a plain gate is a session’s and runs the both and local checks, gate --ci is CI’s and runs the both and ci ones, each naming in its report what it left to the other, and gate --all runs every one, which a release is held to; --all with --ci is GATE_PLACEMENT_CONFLICT. A local check – lint, the type check and the generators’ --validate in dev-tool’s default – is not run on CI at all, so a session runs gate before it commits. gate --dry-run runs nothing and reports the checks the run would have run, each with its command and whether it takes --paths. gate --validate refuses a gate that wrote to the tree, as GATE_WROTE_TO_THE_TREE: format and lint --fix repair what they find, which is right after an edit and is a finding in a run judging finished work, so it is what CI runs. gate --only <commands> and gate --skip <commands> run part of a gate by hand, and --paths narrows the checks whose commands read a path.
test narrows with --paths and --modules. --paths reaches pytest as its argv and the command sets PYTHONPATH itself, so no manual PYTHONPATH= prefix is needed. A path that does not exist, or one outside the repository, is an error before anything runs. The two combine: paths resolve against each selected module’s root rather than the repository root when both are given, and passing neither is what asks for the whole suite.
test collects the tiers it is asked for. A test’s tier is the folder it sits in inside the test directory, as the repository’s testTiers declares the tiers and its adapter spells the folder (__tests__/__integration__/). Every test is in a declared tier’s folder: one kept directly in the test directory, or under a folder spelling a tier nothing declares, is refused as TEST_NOT_IN_A_TIER naming it, before anything runs. With nothing said the run collects the tiers marked default – unit, in dev-tool’s own list; --tier <name> names the tiers instead and --all-tiers asks for every one. A tier nothing declares is TEST_TIER_UNKNOWN. A repository holding no test in a tier the run collects starts no runner and passes, a file named with --paths runs whatever tier it is in, and a named directory whose only tests are in a tier left out is refused as TEST_TIER_NOT_COLLECTED saying which tier holds them. A tier declared isolated may start no process: the run hands the isolated tiers to the adapter, which fails a test in one that starts a process, naming what it started – with pytest, a plugin the adapter loads into the run (ProcessStartedInIsolatedTier).
test --select affected – and lint --select affected and typecheck --select affected, which select the same way – works the selection out instead of being told it: the modules owning what git reports as changed against HEAD, untracked files included, and every module depending on one of them through the dependency graph – with a test dependency followed one hop, so a module whose tests import what changed is run and what depends on that module is not. No change runs nothing, a change no module owns runs the whole repository unless its inertPaths says it reaches no test and no check, and for test a selection holding no test in a tier the run collects runs nothing. It reads uncommitted work against HEAD; --since <ref> reads everything since the branch left that ref, committed or not.
--select affected may be a repository’s default, stated under argDefaults, so that the run after an edit is the narrow one unasked. A run that names what it covers with --paths or --modules runs that whatever the default says, and the whole run is then asked for by name, --select all.
module select --of <test|lint|typecheck> reports what a run of that command would cover and runs nothing: the scope – whole, selected with the paths, or nothing – and the arguments that make a run cover the same. It takes the command’s own --select affected, --since, --tier and --all-tiers, and works the answer out with the code the command runs. It is what to read when an affected run is wider than expected.
test, lint, format, typecheck, install, sync, build and gate also take --recurse, which crosses into the repositories this one pins as modules. A repository that pins nothing has no boundary to stop at, and the flag changes nothing there.
module dependency list --validate and module dependency detect --validate are the pair to run after any dependency-affecting change, and the last two checks of the gate. Both must pass, and they check opposite directions: what the manifest claims, and what the code actually imports. module export list --validate runs before them in the gate: it refuses a parent module’s surface that re-exports a submodule’s symbol straight through.
pkgmgr
The package store: namespaces and packages, and the catalogs a repository obtains what it declares from.
pkgmgr <group> <command> [args]
impl-tool
The issue runner.
impl-tool <group> <command> [args]