CI/CD Architecture

1. Objectives

• Enforce correctness and portability.
• Catch regressions early (lint, tests, benchmarks).
• Produce deterministic release artifacts.

2. Workflow layout

• ci.yml - single workflow with three jobs: test (nextest + doc tests), build (release artifacts), lint (fmt + clippy + cargo-deny).
• benchmark.yml - criterion benchmarks and trend tracking (uploads raw reports as artifacts).
• docs.yml - rustdoc build (deny warnings) and mdbook site publication to GitHub Pages.
• release.yml - tag-driven release and package publication with changelog generation.

3. Quality gates

Required for protected branch merge (all within ci.yml):

1. Lint job green (fmt + clippy + cargo-deny).
2. Test matrix green (nextest + doc tests across OS/toolchain).
3. Build artifacts generated (release binaries uploaded per OS).

4. Matrix strategy

OS targets:

• Linux (ubuntu-latest)
• macOS (macos-latest)
• Windows (windows-latest)
• Windows ARM64 (windows-11-arm)

Rust channels:

• stable (required)
• nightly (advisory compatibility signal)

5. Caching and artifacts

• Use cargo target cache for CI acceleration.
• Persist benchmark reports as artifacts.
• Publish release binaries per target triple.

6. Branch protection

• Require status checks before merge.
• Require branch up-to-date with target branch.
• Require at least one review approval.
• Require resolved review conversations.

7. Security posture

• Dependency vulnerability scanning on schedule and push.
• Keep lockfile current and reviewed.
• Do not suppress warnings as default policy.

8. Release policy

• Semantic version tags trigger release workflow.
• Generate changelog summary from merged PRs/issues.
• Publish binary artifacts and crate package (when ready).

9. Documentation policy in CI

Any change that touches output contract, graph semantics, or language extraction must update relevant docs under docs/ in the same PR.

10. Toolchain configuration

• rust-toolchain.toml pins channel 1.94.0 with rustfmt and clippy components.
• deny.toml enforces license allowlist (MIT, Apache-2.0, BSD, ISC, etc.) and bans wildcard dependencies.
• clippy.toml sets MSRV and complexity thresholds.
• rustfmt.toml sets edition 2024 formatting rules.

11. Pre-commit hooks (lefthook)

Managed via lefthook.yml. Install with:

https://lefthook.dev/install/

lefthook install

a dev script will be provided later to automate this process

pre-commit (parallel, fast)

1. cargo fmt --all -- --check - formatting gate.
2. Trailing whitespace check (*.rs, *.toml, *.md, *.yml).
3. Merge conflict marker detection.
4. Large file guard (>512KB).

pre-push (sequential, thorough)

1. cargo clippy --all-targets --all-features -- -D warnings - lint gate.
2. cargo nextest run --all-features - local test gate.

12. Test runner (nextest)

CI and local dev use cargo-nextest for faster test execution.

• Config: .config/nextest.toml
• CI profile: fail-fast = false (full matrix visibility).
• Slow-timeout: 60s per test, terminate after 3 periods.

13. Benchmarks (criterion)

• Dev dependency: criterion 0.8 with html_reports feature.
• Benchmark targets: benches/pipeline.rs (extraction throughput per language fixture), benches/graph.rs (graph operation throughput).
• Profile: opt-level = 3, LTO enabled (see [profile.bench] in Cargo.toml).

14. Release targets

15. Snapshot policy

• Insta .snap files are committed to the repository.
• Pending snapshots (.snap.new) are gitignored.
• Update workflow: cargo insta test → cargo insta review → commit accepted .snap files.