Skip to main content

⬅️ Back to Project Overview

Noxfile & Developer Workflow Automation

This document describes the Noxfile and developer automation workflows for ShieldCraft AI, ensuring consistency, quality, and speed across all environments.

1. Noxfile Overview​

  • Central automation entrypoint for all developer and CI/CD tasks
  • Session-based: Each task (lint, test, build, docs, security, etc.) is a Nox session
  • Python-native: No Makefile or Bash required; works cross-platform
  • Auto-discovers and runs sessions based on code changes or developer needs

1a. Modular Session Layout​

  • Each Nox session is defined in its own file under nox_sessions/, named for its function (e.g., lint, test, docs, docker, bootstrap, security).
  • The main noxfile imports all sessions, making them available as top-level Nox commands.
  • To add or modify a session:
    • Edit the relevant file in nox_sessions/ (e.g., add a new session to security.py for a new security check)
    • Or create a new file for a new automation area, and import it in noxfile.py
  • Benefits:
    • Clear separation of concerns and easy discoverability
    • Easier maintenance and onboarding for new contributors
    • Sessions can be tested and iterated independently

2. Automated Developer Workflows​

  • Pre-commit & Pre-push Hooks:
    • Linting (Ruff), formatting (Black), type checks (Mypy), and security scans (Bandit)
    • Run automatically before every commit/push via local Git hooks (managed by pre-commit) and in CI
    • GitHub hooks (e.g., branch protection, required status checks) ensure all Nox sessions pass before merge
  • Testing:
    • Unit, integration, and smoke tests run via Nox
    • Coverage reports generated and enforced
  • Build & Docker:
    • Build, tag, and push Docker images for all services (API, ingestion, etc.)
    • Compose orchestration for local and CI/CD
  • Docs:
    • Build and serve Docusaurus docs
    • Validate doc links and structure
  • Release & Versioning:
    • Automated version bump, changelog, and release tagging
    • PyPI and Docker registry publishing

3. CI/CD Integration & Disk Management​

  • GitHub Actions and other CI/CD systems invoke Nox sessions for all checks
  • Consistent local and CI/CD environments (same Noxfile, same results)
  • Fail-fast: CI fails on first error, with clear logs and actionable output
  • Aggressive disk cleanup: CI jobs now clean up Python, Nox, and Docker artifacts before and after major steps to prevent disk exhaustion. This includes:
    • rm -rf .pytest_cache .nox dist build __pycache__ *.pyc *.pyo before and after Nox orchestration
    • docker system prune -af --volumes and docker builder prune -af after Docker builds
  • Minimized Docker build context: Dockerfiles only copy pyproject.toml, poetry.lock, and the src/ directory, reducing build context size and intermediate layer bloat.
  • Optional job splitting: For very large projects, Nox sessions can be split into separate CI jobs to further control disk usage and resource allocation.

4. Developer Experience & Resource Awareness​

  • One-liner onboarding: nox -l lists all available sessions; nox -s <session> runs any task
  • Self-documenting: Each session has a description and help output
  • Fast feedback: Only changed code is checked/tested where possible
  • Extensible: Easy to add new sessions for new tools or workflows
  • Resource awareness: Developers and CI/CD maintainers are encouraged to monitor disk usage (df -h) and clean up artifacts regularly, especially when working with large datasets or running extensive test suites.

Next Steps​

  • Review and update Nox sessions for new automation needs
  • Document onboarding and troubleshooting for developer workflows
  • Monitor disk usage and CI/CD resource allocation