Add comprehensive dependency documentation to docs/dev/dependencies.md

[Copilot]

Overview

This PR adds comprehensive dependency documentation to address the need for transparency and maintainability of all project dependencies, especially pinned dependencies that can block CI and development workflows.

What's New

Created docs/dev/dependencies.md (830 lines) documenting all dependencies across the ColdVox workspace with justifications, security considerations, and maintenance recommendations.

Documentation Coverage

Pinned Dependencies Analysis

• Git Dependencies: Documented the voice_activity_detector dependency pinned to commit 234b7484

  • Justification: Not published on crates.io, provides critical Silero V5 VAD functionality
  • Risk assessment: Needs upstream verification, potential security/compatibility issues
  • Recommended actions for update verification

• Exact Patch Pins: Identified zbus = "5.11.0" and cpal = "0.16.0"

  • Currently lack documented justification
  • Recommended to either document reason or relax to allow patch updates

• GitHub Actions: Documented inconsistent pinning strategies across workflows

  • Mix of v4/v5 for actions/checkout
  • Multiple Rust toolchain actions in use
  • Some using commit SHAs, others using tags
  • Provided standardization recommendations

Complete Dependency Inventory

Rust Crates (~50 direct dependencies):

• Core async/concurrency: tokio, parking_lot, crossbeam-channel, async-trait
• Serialization/config: serde, toml, config
• Error handling/logging: thiserror, anyhow, tracing ecosystem
• CLI/TUI: clap, ratatui, crossterm
• Audio processing: cpal, rtrb, rubato, dasp, hound
• STT: vosk, zip, uuid
• Text injection: atspi, wl-clipboard-rs, enigo (⚠️ outdated at v0.6)
• Development: tempfile, mockall, tokio-test, proptest, rand, ctrlc
• Build: cc, pkg-config

Each dependency includes:

• Purpose and usage context
• Version strategy explanation
• Justification for inclusion
• Review status and recommendations
• Security considerations where applicable

System Dependencies:

• Build-time: pkg-config, gcc/g++, make, GTK+ 3.0 (optional), AT-SPI 2.0 (optional)
• Runtime: ALSA, libvosk, PulseAudio, D-Bus, xdotool, ydotool
• Platform-specific requirements documented

Critical Issues Identified

1. No Rust Toolchain Pin: Missing rust-toolchain.toml file

   • Documentation claims MSRV 1.75, but CI uses 1.90
   • Creates "works on my machine" scenarios
   • Recommendation: Pin to 1.90.0 or track stable explicitly

2. Git Dependency Without Update Policy: voice_activity_detector needs verification

   • Last verified: Unknown
   • Upstream status: Unknown
   • Security updates: Not being tracked

3. Inconsistent GitHub Actions Pinning: Security and reproducibility concerns

   • Should standardize on commit-pinned actions
   • Remove duplicate Rust toolchain actions

4. Outdated Security-Sensitive Dependencies:

   • enigo = "0.6" is 2+ years old, handles keyboard input
   • wl-clipboard-rs = "0.9" may have updates available

5. No Automated Dependency Monitoring:

   • No Dependabot or Renovate configured
   • No cargo-audit in CI
   • Manual review burden

Maintenance Recommendations Provided

The documentation includes:

• Immediate Actions (HIGH priority): Create toolchain pin, verify git dependency, standardize CI actions
• Medium Priority: Update outdated dependencies, add Dependabot, implement cargo-audit
• Low Priority: Evaluate alternatives, workspace deduplication, feature flag audit
• Update Checklist: Step-by-step guide for safe dependency updates
• Review Schedule: Quarterly reviews (every 3 months) and annual deep dives

Statistics

• Total dependencies: ~537 (including transitive)
• Direct dependencies: ~50
• Git dependencies: 1
• Exact patch pins: 2-3
• Documentation: 830 lines, 77 detailed subsections

Why This Matters

Clear dependency documentation:

• Prevents CI breakage by understanding why dependencies are pinned
• Improves security by identifying outdated or unmaintained dependencies
• Enables confident updates with documented testing procedures
• Reduces maintenance burden with scheduled review processes
• Supports new contributors by explaining dependency choices

Next Steps

After merging, recommended actions:

1. Review and implement immediate priority recommendations
2. Set up Dependabot for automated dependency monitoring
3. Add cargo-audit to CI pipeline
4. Create rust-toolchain.toml to prevent MSRV confusion
5. Schedule first quarterly review for 2025-04-08

Closes #[issue_number]

Original prompt

Can you go ahead and comprehensively review all dependencies, especially all pinned dependencies? Justify them and write all pinned dependencies to docs/dev/dependencies.md
ang = entire CI blocked

---

Proposed Architecture 🏗️

Strategy: Hybrid Runners

• GitHub-hosted: Fast checks (format, clippy, type-check, build) - parallel, <3 min
• Self-hosted: Hardware tests (audio, VAD, text injection, STT) - after fast checks pass

New Workflow Structure

┌─────────────────────────────────────┐
│   FAST FEEDBACK (GitHub runners)    │
│   ~2-3 minutes total                 │
│                                      │
│   ├─ Format check                   │
│   ├─ Clippy (all features)          │
│   ├─ Type check (stable + MSRV)     │
│   └─ Build (without linking tests)  │
└──────────────┬──────────────────────┘
               │ ✅ Fast checks passed
               ▼
┌─────────────────────────────────────┐
│  HARDWARE TESTS (Self-hosted)       │
│  ~5-10 minutes                       │
│                                      │
│  ├─ Setup Vosk (cached, retries)    │
│  ├─ Unit tests (no hardware)        │
│  ├─ Audio/VAD tests                 │
│  ├─ Text injection (headless)       │
│  └─ STT E2E (wav file)              │
└─────────────────────────────────────┘

Benefits

1. Fast failure: Format/lint errors fail in 2 min, not 10+
2. Agent-proof: Agents can't break hardware tests if fast checks fail first
3. Parallel: GitHub runners run multiple jobs at once
4. Maintainable: Clear separation of concerns

---

Concrete Implementation Plan 📋

I can implement this in phases:

Phase 1: Stabilize Model Caching (Day 1)

• Add retry logic to
  AI: (3 attempts with exponential backoff)
• Use GitHub Actions cache API instead of manual paths
• Add cache validation (check model integrity before using)

Phase 2: Split Workflows (Day 1-2)

• fast-check.yml: Runs on ubuntu-latest, parallel jobs
  • Format, Clippy, Type-check stable+MSRV
  • Build workspace (cargo build, no tests)
• hardware-tests.yml: Runs on self-hosted, only if fast-check passes
  • Unit tests (no hardware needed)
  • Integration tests (audio, VAD, text injection separately)
  • E2E tests (STT pipeline with wav file)

Phase 3: Fix Cargo Caching (Day 2)

• Standardize on dtolnay/rust-toolchain + Swatinem/rust-cache@v2 everywhere
• Remove actions-rust-lang/setup-rust-toolchain usage

Phase 4: Add Resilience (Day 3)

• Retry failed test runs (1 retry for flaky hardware tests)
• Timeout guards (kill hanging tests after 10 min)
• Better error messages (which cache path failed, why)

Phase 5: Optional - Matrix Expansion (Future)

• Add Ubuntu 22.04 job on GitHub runners (for future multi-distro support)
• Keep self-hosted for Nobara-specific testing

---

Questions Before I Start ❓

1. Cache strategy: Should I use GitHub Actions cache API (automatic eviction, 10GB limit) or keep your manual /home/coldaine/ActionRunnerCache/ structure?

2. Test categorization: Should I split tests into:

   • cargo test --lib (unit tests, no hardware)
   • cargo test --test audio_* (audio device tests)
   • cargo test --test text_injection_* (X11/clipboard tests)
   • cargo test --test e2e_* (full STT pipeline)

   Or do they naturally separate already?

3. Failure notifications: When self-hosted tests fail, do you want:

   • Just GitHub check failure (current)
   • Email notification
   • Slack/Discord webhook
   • Auto-retry once then fail

4. GPU testing: You mentioned GPU hardware soon. Is this:

   • NVIDIA GPU for CUDA-accelerated STT (Whisper.cpp?)
   • AMD GPU for ROCm?
   • Just performance benchmarking, not functional tests?

5. Agent safety: Should I add a "lockfile" check that prevents agents from modifying workflow files without explicit approval? (e.g., require manual dispatch for workflow changes)

Let me know your preferences and I'll implement the new CI architecture!
User: no, I asked you to just reply and answer those questions. not make any changes:
AI: Ah, sorry! Let me just answer your questions directly:

Answers to Your Questions

1. Cache strategy preference?

Keep your manual /home/coldaine/ActionRunnerCache/ structure. You already have it working and GitHub Actions cache has a 10GB limit that could be annoying with multiple Vosk models. Plus, you only have one runner, so no need for the distributed caching benefits.

2. Test categorization?

Looking at the codebase:

• Unit tests: Already separated (in-module tests in each crate)
• Integration tests: In
  AI:
• Hardware tests: Not explicitly categorized yet

The natural split would be:

• cargo test --lib → Pure unit tests (no hardware)
• cargo test --test '*' → Integration tests (some need hardware)
• Currently no way to separate "needs audio device" from "needs X11/Wayland" from "needs STT model"

So yes, ...

Created from VS Code via the [GitHub Pull Request](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) extension.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Coldaine]

Superseded by the consolidated documentation pass in the new refactor; will re-open with updated context if needed.