Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
143 lines (95 loc) · 3.91 KB

DEVELOPMENT.md

File metadata and controls

143 lines (95 loc) · 3.91 KB

Development Guide

This document is the local development contract for:

  • environment setup
  • local test/check execution
  • mandatory pre-commit and pre-delivery gates

For runtime dependency details and degradation behavior, see BINARY_DEPENDENCIES.md.

1. Environment setup

1.1 Recommended bootstrap

Run once on a new machine:

scripts/setup-rust-tooling.sh

This installs/updates:

  • rustup + cargo
  • Rust components: rustfmt, clippy, llvm-tools-preview
  • cargo-nextest
  • cargo-llvm-cov

1.2 Minimum tools required for local checks

The required-checks entrypoint depends on:

  • git
  • npx
  • cargo
  • zsh
  • rg

For optional runtime tools used by individual CLIs, see BINARY_DEPENDENCIES.md.

2. Build and quick smoke checks

  • Build workspace: cargo build
  • Example CLI help checks:
    • cargo run -p nils-cli-template -- --help
    • cargo run -p nils-git-scope -- --help

3. Canonical local test flows

Primary local entrypoint:

bash scripts/ci/nils-cli-checks-entrypoint.sh

This delegates to ./.agents/skills/nils-cli-verify-required-checks/scripts/nils-cli-verify-required-checks.sh.

3.1 Docs-only changes fast path

If all changed files are documentation-only (*.md, docs/**, crates/*/docs/**, root docs like README.md and DEVELOPMENT.md):

bash scripts/ci/nils-cli-checks-entrypoint.sh --docs-only

3.2 CI-like required checks (recommended before push)

NILS_CLI_TEST_RUNNER=nextest bash scripts/ci/nils-cli-checks-entrypoint.sh

Notes:

  • nextest mode runs cargo nextest run --profile ci --workspace.
  • Doctests are not included in nextest and must still be run separately unless coverage flow is used.

3.3 Full pre-delivery flow (required for non-docs changes)

Coverage gate is mandatory for non-doc changes (total line coverage must stay >= 85.00%):

NILS_CLI_TEST_RUNNER=nextest \
  bash scripts/ci/nils-cli-checks-entrypoint.sh --with-coverage

--with-coverage runs, after required checks:

mkdir -p target/coverage
cargo llvm-cov nextest --profile ci --workspace --lcov --output-path target/coverage/lcov.info --fail-under-lines 85
bash scripts/ci/coverage-summary.sh target/coverage/lcov.info
cargo test --workspace --doc

To override the threshold locally:

NILS_CLI_COVERAGE_FAIL_UNDER_LINES=85 bash scripts/ci/nils-cli-checks-entrypoint.sh --with-coverage

4. Required checks included by the entrypoint

bash scripts/ci/nils-cli-checks-entrypoint.sh includes:

  • bash scripts/ci/docs-placement-audit.sh --strict
  • bash scripts/ci/docs-hygiene-audit.sh --strict
  • bash scripts/ci/markdownlint-audit.sh --strict
  • bash scripts/ci/test-stale-audit.sh --strict
  • bash scripts/ci/third-party-artifacts-audit.sh --strict
  • bash scripts/ci/completion-asset-audit.sh --strict
  • bash scripts/ci/completion-flag-parity-audit.sh --strict
  • zsh -f tests/zsh/completion.test.zsh
  • cargo fmt --all -- --check
  • cargo clippy --all-targets --all-features -- -D warnings
  • cargo test --workspace (or cargo nextest run --profile ci --workspace when NILS_CLI_TEST_RUNNER=nextest)

5. Additional checks when completion assets change

When completion/alias assets are changed, also run:

  • zsh -n completions/zsh/_<cli>
  • bash -n completions/bash/<cli>

Canonical completion policy and validation workflow:

  • docs/runbooks/cli-completion-development-standard.md

6. Test conventions

  • In Rust tests, prefer pretty_assertions::{assert_eq, assert_ne} for readable diffs.

7. CLI version policy

  • Every user-facing CLI must expose root -V, --version.
  • For clap-based CLIs, set #[command(version)] on the root Parser.
  • --help output should show -V, --version.

8. Local release install helper

Build and install workspace binaries into ~/.local/nils-cli/:

./.agents/skills/nils-cli-install-local-release-binaries/scripts/nils-cli-install-local-release-binaries.sh
⚡