embeddenator-workspace

Workspace management utilities for developing the Embeddenator monorepo.

This crate provides CLI tools for managing version consistency, dependency updates, and documentation generation across the 11+ embeddenator repositories.

Independent component for managing the Embeddenator workspace.

Repository: https://github.com/tzervas/embeddenator-workspace

Features

Version Management: Bump versions consistently across all packages
Dependency Tracking: Check for version drift and inconsistencies
Workspace Health: Comprehensive health checks for git, tests, docs, and specs
Patch Management: Local development mode for git dependencies
Documentation Generation: Build rustdoc and mdBook documentation

Status

Alpha / internal use only.

Installation

From the workspace root:

cargo build -p embeddenator-workspace --release

The binary will be available at target/release/embeddenator-workspace.

Commands

bump-version

Update package versions across all embeddenator crates and their inter-dependencies.

# Bump prerelease version (e.g., 0.20.0-alpha.1 → 0.20.0-alpha.2)
embeddenator-workspace bump-version --prerelease

# Bump patch version (e.g., 0.20.0-alpha.1 → 0.20.1)
embeddenator-workspace bump-version --patch

# Bump minor version (e.g., 0.20.0 → 0.21.0)
embeddenator-workspace bump-version --minor

# Bump major version (e.g., 0.20.0 → 1.0.0)
embeddenator-workspace bump-version --major

# Dry run - see what would change without making modifications
embeddenator-workspace bump-version --prerelease --dry-run

What it does:

Scans all Cargo.toml files in the workspace
Updates package.version in each embeddenator package
Updates dependency versions (e.g., embeddenator-vsa = "0.20.0-alpha.1")
Writes changes to disk
Suggests a git commit command

Example output:

Performing Prerelease version bump...

Version Changes:
  embeddenator 0.20.0-alpha.1 → 0.20.0-alpha.2
  embeddenator-cli 0.20.0-alpha.1 → 0.20.0-alpha.2
  embeddenator-fs 0.21.0 → 0.21.1-alpha.1
  embeddenator-vsa 0.20.0-alpha.1 → 0.20.0-alpha.2
  ...

✓ 11 package(s) updated

Next: git commit -am "chore: bump version to 0.20.0-alpha.2"

check-versions

Detect version inconsistencies and drift across the workspace.

# Check version consistency
embeddenator-workspace check-versions

# Show detailed information
embeddenator-workspace check-versions --verbose

What it checks:

Version drift (packages on different major versions)
Dependency mismatches (package A depends on package B v0.20.0 but B is at v0.21.0)
Prerelease tag consistency

Example output (with issues):

Checking version consistency...

Scanned: 11 package(s)

Issues Found:
  • Version drift: 1 package(s) on major version 0: embeddenator-fs

Dependency Inconsistencies:
  • embeddenator-fs depends on embeddenator-vsa 0.20.0-alpha.1 (expected: 0.20.0-alpha.2)
  • embeddenator-retrieval depends on embeddenator-vsa 0.20.0-alpha.1 (expected: 0.20.0-alpha.2)

Suggestion: Run 'embeddenator-workspace bump-version --prerelease' to fix

# Exit code: 1

Example output (no issues):

Checking version consistency...

Scanned: 11 package(s)

✓ All versions are consistent!

# Exit code: 0

health

Run comprehensive workspace health checks across all repositories.

# Run all health checks
embeddenator-workspace health

# Run specific checks only
embeddenator-workspace health --check git,version

# Show detailed output
embeddenator-workspace health --verbose

# Output as JSON for CI parsing
embeddenator-workspace health --json

# Save markdown report to file
embeddenator-workspace health --output health-report.md

# Specify workspace root
embeddenator-workspace health --workspace-root /path/to/workspace

Health Check Categories:

Git Status (--check git)
- Dirty files (uncommitted changes)
- Ahead/behind status vs upstream
- Branch information
- Orphaned upstream branches
Version Alignment (--check version)
- Version consistency across packages
- Dependency version drift
- Prerelease tag alignment
Test Coverage (--check tests)
- Run cargo test on all packages
- Report pass/fail status
- Identify failing test suites
Documentation Coverage (--check docs)
- Run cargo rustdoc with -D warnings
- Detect missing documentation
- Count documentation warnings
Spec Coverage (--check specs)
- Check for specs/ directories
- Calculate coverage percentage
- Identify packages without specs

Exit Codes:

0: All checks passed or warnings only
1: Critical failures detected (dirty git, version drift, failing tests)

Example output:

════════════════════════════════════════════════════════════════════════════════
Workspace Health Report
════════════════════════════════════════════════════════════════════════════════
Generated: 2026-01-16T12:34:56-05:00
Workspace: /home/user/projects/embdntr
Overall Status: WARN

✓ git [Pass]
  All 11 repositories are clean and synced

✗ version [Fail]
  Version inconsistencies detected: 0 issue(s), 2 dependency mismatch(es)
    • embeddenator-fs depends on embeddenator-vsa 0.20.0 (expected: 0.20.1)
    • embeddenator-cli depends on embeddenator-vsa 0.20.0 (expected: 0.20.1)

✓ tests [Pass]
  Tests: 11 passed, 0 failed out of 11 packages

⚠ docs [Warn]
  Documentation: 9 clean, 2 with warnings out of 11 packages
    • embeddenator-io: 3 documentation warning(s)
    • embeddenator-obs: 1 documentation warning(s)

⚠ specs [Warn]
  Spec coverage: 81.8% (9/11 packages with specs/)
    • embeddenator-io: missing specs/ directory
    • embeddenator-obs: missing specs/ directory

════════════════════════════════════════════════════════════════════════════════

JSON Output (--json):

{
  "timestamp": "2026-01-16T12:34:56-05:00",
  "workspace_root": "/home/user/projects/embdntr",
  "overall_status": "warn",
  "checks": [
    {
      "check_type": "git",
      "status": "pass",
      "message": "All 11 repositories are clean and synced",
      "details": []
    },
    {
      "check_type": "version",
      "status": "fail",
      "message": "Version inconsistencies detected",
      "details": [
        "embeddenator-fs depends on embeddenator-vsa 0.20.0 (expected: 0.20.1)"
      ]
    }
  ]
}

patch-local / patch-reset

Manage local development patches for git dependencies (see PATCH_MANAGEMENT_GUIDE.md).

# Enable local development mode
embeddenator-workspace patch-local

# Disable and restore git dependencies
embeddenator-workspace patch-reset --clean

docs / rustdoc / mdbook

Generate documentation:

# Generate both rustdoc and mdBook (if available)
embeddenator-workspace docs

# Generate only rustdoc
embeddenator-workspace rustdoc

# Generate only mdBook
embeddenator-workspace mdbook

Typical Workflow

Before a release:

Run health checks:
```
embeddenator-workspace health
```
Fix any critical issues (version drift, failing tests)
Check consistency:
```
embeddenator-workspace check-versions
```

Bump versions if needed:

embeddenator-workspace bump-version --patch

Verify changes:
```
git diff
```

Commit:

git commit -am "chore: bump version to 0.20.1"
git push

During development:

Use --dry-run to preview changes:

embeddenator-workspace bump-version --prerelease --dry-run

Run specific health checks:

embeddenator-workspace health --check git,version

Integration with CI

Health Check Pipeline

# .github/workflows/health-check.yml
name: Workspace Health Check

on: [pull_request]

jobs:
  health:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      
      - name: Build health checker
        run: cargo build -p embeddenator-workspace --release
      
      - name: Run health checks
        run: |
          ./target/release/embeddenator-workspace health --json > health-report.json
          ./target/release/embeddenator-workspace health --output health-report.md
      
      - name: Upload health report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: health-report
          path: |
            health-report.json
            health-report.md
      
      - name: Check for failures
        run: |
          if jq -e '.overall_status == "fail"' health-report.json; then
            echo "Health check failed!"
            exit 1
          fi

Version Consistency Check

# .github/workflows/version-check.yml
name: Version Consistency Check

on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: dtolnay/rust-toolchain@stable
      - name: Check version consistency
        run: |
          cargo build -p embeddenator-workspace
          cargo run -p embeddenator-workspace -- check-versions

Architecture

Module Structure

cargo.rs - Cargo.toml parsing and manipulation using toml_edit
version.rs - Version bumping logic with semver
workspace.rs - Repository discovery and scanning with walkdir
patch.rs - Patch management for git dependencies
health.rs - Comprehensive workspace health checking with parallel execution
bin/embeddenator_workspace.rs - CLI interface using clap

Design Principles

Safety First: All operations use toml_edit to preserve formatting and comments
Parallel Execution: Health checks run concurrently using tokio for performance
Dry Run Support: Preview changes before applying them
Clear Output: Color-coded, structured output for easy parsing
Exit Codes: Non-zero exit on errors for CI integration
Multiple Output Formats: Terminal (colorized), Markdown, and JSON

Performance Characteristics

Health Check Parallelization: All health checks run concurrently
- Git status: ~50ms per repo × 11 repos = ~550ms sequential → ~100ms parallel
- Version check: Single pass over all packages (~200ms)
- Test execution: Longest running (~5-30s per package, run in parallel)
- Doc check: ~2-5s per package (parallel)
- Spec coverage: Fast filesystem scan (~50ms)
Expected Runtime:
- All checks with passing tests: 5-10 seconds
- All checks with failing tests: 10-30 seconds (depends on test suites)
- Specific checks only (--check git,version): <1 second

Running

From anywhere in the workspace:

cargo run -p embeddenator-workspace -- --help
cargo run -p embeddenator-workspace -- health --help

## License

MIT

embeddenator-workspace 0.20.0