Toolchain authority

Use lock.toml as the version authority. Repository automation reads it through lock.lua. Avoid maintaining another version table in Ansible inventory or documentation.

lua scripts/toolchain/resolve.lua --field node.version
lua scripts/check/toolchain.lua
lua tests/automation/toolchain/lock_test.lua

The parser contract suite checks supported and rejected lock formats. It does not establish that the host has installed the declared tools. Each campaign must satisfy its runtime and compiler prerequisites. System Lua 5.4 bootstraps the lock reader; hosted workflows then use the selected runtime.

Install build and qualification tools through the campaign's existing installer and host setup action. Follow documentation setup for Markdown and Doxygen dependencies. Use cache.lua to place disposable tool state under .cache/. Use lua scripts/workspace/bootstrap.lua for the hash-verified Lua, luv and Ansible runtime. Python dependency groups live in tools/python/pyproject.toml; tools/python/uv.lock records the resolved graph and artifact hashes. Install selected groups through python.lua, which requires a current lock and binary wheels. Native manifests are generated from the central identities; do not edit their versions by hand. The Nix environment supplies host tools from a pinned Nixpkgs revision. The Ansible preparation pilot checks prerequisites and creates directories; it does not install the complete toolchain.

On this page

Updating tool versions
CICD-004: Tools and dependencies

Updating tool versions

Edit versions, revisions and archive hashes in tools/toolchain/lock.toml. The templates in tools/toolchain/templates/ describe package selection and manifest structure without versions. They generate the Python and npm manifests and the Nix flake; the same synchronizer updates every external GitHub Action reference, including sub-actions such as upload-sarif. Unknown Action repositories fail validation until mapped in tools/toolchain/manifests.lua.

lua scripts/process/playbook.lua --direct toolchain-sync
lua scripts/toolchain/sync.lua --check
lua scripts/check/toolchain.lua
lua scripts/check/doc_tools.lua

Synchronization is deterministic and offline. Native dependency graphs and integrity data remain owned by their package managers. After changing a Python, npm or Nix input, refresh only the affected lock:

uv lock --project tools/python
npm install --package-lock-only --ignore-scripts --prefix tools/lint/code/quality
npm install --package-lock-only --ignore-scripts --prefix tools/lint/code/md
npm install --package-lock-only --ignore-scripts --prefix tools/lint/code/web
nix flake lock ./tools/nix

Use the reviewed uv version from the central lock. The Python installer always uses --locked and the explicit tools/python project directory. CI rejects edited projections, mismatched Python resolutions, npm graph drift, Nixpkgs revision drift and unregistered Actions. Native locks retain transitive package versions, hashes and resolver metadata; they remain committed and are not hand-generated by Lua.

Renovate proposes changes to the central lock only. Review and refresh generated files and affected native locks in that same update; the bot does not run installation scripts to repair a proposal. Nix host tools are selected by the central Nixpkgs revision. Their versions can differ from the individual quality pins; install the managed quality profile for validator parity with CI.

CICD-004: Tools and dependencies

Class: SUPPLY_CHAIN. Obligation: project requirement.

The toolchain lock records tool identities. The download action verifies a SHA-256 digest before installation. npm dependencies use the committed lock, integrity fields, and installation without lifecycle scripts. Review direct and transitive updates, licenses, source authenticity, and advisories.

Repository-owned checks and automation scripts must be Lua. Third-party tools implemented in Python may run in isolated environments; this does not authorize general repository Python scripts or embedded Python programs. Native API adapters for Lizard and the Lua parser live under tools/analysis/c/ and tools/analysis/lua/. Lua controllers invoke them in the locked quality environment. No Python sources are permitted in scripts/; the toolchain gate enforces this without exceptions. The system Lua bootstrap and the pinned validation runtime have distinct roles.

The hosted runner image, bootstrap packages, and some external services can change. A lock file alone does not freeze the entire environment. Product reproducibility requires the additional build controls.

Shared local and CI quality profile

tools/toolchain/lock.toml owns tool versions. Python and npm lock files retain transitive dependencies and archive integrity; their direct versions are checked against that authority. The Linux x86_64 quality installer uses those same locks as the hosted spelling job. System compilers remain host prerequisites; build matrix compiler identities are selected by the declared target profile.

lua scripts/workspace/bootstrap.lua
lua scripts/toolchain/install/quality.lua --profile=all
lua scripts/workspace/with_tools.lua lua scripts/workspace/doctor.lua --profile=all
lua scripts/workspace/with_tools.lua lua scripts/check/all.lua --offline

Native Ansible prepares declared task profiles automatically; first-time setup needs network access. The explicit with_tools.lua runner selects managed tools, removes inherited Python runtime settings and preserves repository-local caches. The doctor reports version drift and resolved paths without installing anything. The verified EditorConfig Checker 3.11.2 archive embeds the version string 3.11.1; its lock entry records that upstream packaging discrepancy explicitly. Use CPython 3.12 for provisioning. REUSE is the sole permitted Python source build: its source archive and Poetry backend are locked; other packages require wheels.

The CI workflow owns repository spelling. Documentation builds do not repeat it. Local spelling uses the same command and source inventory as that CI job. Local Gitleaks scans a disposable Git working-source snapshot, including new files and omitting ignored dependency caches. Hosted history scanning remains independent.