madoqua 0.1.0__tar.gz

madoqua-0.1.0/.claude/settings.json

@@ -0,0 +1 @@
+{}

madoqua-0.1.0/.claude/skills/rust-review/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: rust-review
+context: fork
+background: false
+description: Deep Rust code quality review. Auto-invoke when finishing a task, before marking work complete, when the user asks to review code, or when preparing a PR. Covers error handling, duplicated logic, test quality, performance patterns, idiomatic Rust, docs-code alignment, and API design beyond what clippy catches.
+---
+
+# Deep Code Review for madoqua
+
+Perform a thorough code quality review of the changes in this project. Go beyond
+what clippy and rustfmt catch. Focus on the areas below and report findings
+grouped by severity: 🔴 Must Fix, 🟡 Should Fix, 🟢 Suggestion.
+
+First, run `cargo fmt --all -- --check` and
+`cargo clippy --all-targets --all-features -- -D warnings` to confirm the
+automated checks pass. If they don't, report them as findings — do **not** fix
+them yourself. This skill reviews; it does not edit.
+
+## Returning results
+
+This skill runs in a fork, so its transcript is never shown to the user. The
+complete report must be your **final message** — the full findings text, not a
+summary of it, not a pointer to a file, not "see above". Anything you leave out
+of that last message is lost.
+
+Concretely:
+
+- Emit every finding in full (severity, location, why, concrete fix) in the
+  final message.
+- Do not write findings to a scratch file and reference the path instead.
+- If the review is clean, say so explicitly and state what you checked.
+- Do not end with a question — the caller cannot answer it.
+
+## 1. Error Handling Quality
+
+- `.unwrap()` / `.expect()` outside tests is denied by lint config. Flag any
+  instance that slipped through (macros, build scripts, `#[allow]`s).
+- Check that `.context("message")` is used on every `?` that crosses an I/O,
+  parsing or subprocess boundary — bare `?` loses which operation failed.
+- Flag `Result` return types where the function never returns `Err`.
+- Flag `.map_err(|_| ...)` that silently discards error information.
+- The crate is `anyhow`-based end to end. Flag `String` as an error type, and
+  flag any place where a caller has to string-match an error message to make a
+  decision — that wants a typed error instead.
+
+## 2. Process and I/O Seams
+
+madoqua's core invariant: every process spawn, filesystem read and environment
+lookup lives in a module that exists to do it, and everything downstream of a
+seam takes already-parsed data.
+
+- Flag any new `std::process::Command`, `std::fs` read, or environment lookup
+  outside those seams.
+- Flag new inputs threaded directly into a rules module rather than behind the
+  trait it reaches the world through — that is what keeps the unit tests
+  runnable with nothing installed.
+- Check that command bodies live in `cli.rs`, not `main.rs`.
+- Check that logs go to stderr and output to stdout — a `--json` run must stay
+  pipeable with `--verbose` on.
+
+## 3. Duplicated Logic
+
+- Search for functions or code blocks that do substantially the same thing with
+  minor variations. Flag them and suggest extraction into a shared function,
+  trait, or generic.
+- Pay special attention to:
+  - Path normalization against the project root
+  - JSON payload shaping and parsing
+  - Error handling boilerplate that could be a helper
+  - Similar match arms across different functions
+- Suggest concrete refactoring: which function to extract, what parameters it
+  should take.
+
+## 4. Test Quality
+
+- **Tests that don't assert**: Flag any test that just calls code without
+  asserting on the result. Running without panicking is not a test.
+- **Tests that assert too little**: `assert!(result.is_ok())` without checking
+  the value inside is weak. Suggest asserting on the actual content.
+- **Overly verbose tests**: Tests with excessive setup that obscure what's
+  actually being tested. Suggest extracting test helpers into
+  `tests/common/mod.rs`.
+- **Missing edge cases**: For each public function, check if tests cover: empty
+  input, error paths, boundary conditions.
+- **Test naming**: Test names should describe the behavior being tested, not the
+  implementation (`returns_error_on_missing_file`, not `test_function_xyz`).
+- **Integration vs unit**: unit tests (`#[cfg(test)] mod tests`) test internal
+  logic; `tests/*.rs` exercise the public CLI interface.
+- **Exit codes are contract.** `0` clean, `1` findings, `2` could not complete
+  (ADR 0001). Flag any new path that could return the wrong one, and any test
+  that asserts on stdout without asserting on the exit code.
+- Flag a changed snapshot (`tests/snapshots/*.snap`) whose diff is not explained
+  by an intentional behavior change.
+
+## 5. Performance Patterns
+
+- Flag unnecessary `.clone()` — suggest borrowing or restructuring ownership.
+- Flag `.collect::<Vec<_>>()` immediately followed by `.iter()`.
+- Prefer `&str` over `String`, `&[T]` over `Vec<T>`, `&Path` over `PathBuf` in
+  function parameters when ownership isn't needed.
+- Flag large structs passed by value instead of by reference.
+- Flag repeated linear scans over a collection that is looked up by key —
+  suggest a `HashMap`/`HashSet`.
+
+## 6. Idiomatic Rust
+
+- Prefer iterator chains over manual `for` loops with `push`.
+- Use `if let` / `let else` instead of `match` with a single interesting arm and
+  a wildcard.
+- Suggest `impl From<X> for Y` instead of standalone conversion functions.
+- Suggest `Display` implementations instead of `to_string()` methods.
+- Flag `&String`, `&Vec<T>`, `&Box<T>` in signatures — use `&str`, `&[T]`, `&T`.
+- Check doc comments on all public types and functions.
+
+## 7. Documentation ↔ Code Alignment
+
+- **`docs/src/commands/*.md`** must describe the current CLI. Compare documented
+  flags, subcommands, exit codes and JSON field names against the `clap`
+  definitions in `src/cli.rs` and the serde structs in `src/report.rs`.
+- **`docs/src/how-it-works.md`** must match the actual pipeline — which command
+  shells out to what, and in what order.
+- **`docs/dev/ARCHITECTURE.md`** and the **Key Invariants** list in `CLAUDE.md`
+  must still be true of the code. An invariant that the code no longer upholds
+  is a 🔴 either way: either the code regressed or the doc is lying.
+- **`docs/adr/`**: if the change contradicts a recorded decision, flag it — the
+  fix is a new ADR superseding it, not a silent divergence.
+- **Shared prose**: `README.md` and `docs/src/setup.md` are generated between
+  `<!-- BEGIN SHARED:... -->` markers. Flag any edit made inside the markers
+  instead of in `docs/shared/`.
+- **New page, no `SUMMARY.md` entry**: the page is unreachable and missing from
+  `llms.txt`.
+- Flag any mismatch as 🔴 Must Fix — stale docs are worse than no docs.
+
+## 8. API and Module Design
+
+- Is `main.rs` thin? Argument parsing, tracing setup, exit-code mapping only.
+- Are module boundaries clean? Each module should have a clear responsibility.
+- Check for any `pub` items that don't need to be public.
+- Flag circular dependencies between modules.
+
+## Output Format
+
+Group all findings by severity, then by area. For each finding:
+
+- State **what** the issue is and **where** (`file.rs:line` or function name)
+- Explain **why** it matters
+- Suggest a **concrete fix** (not just "improve this")
+
+End with a summary: X must-fix, Y should-fix, Z suggestions.
+
+$ARGUMENTS

madoqua-0.1.0/.github/dependabot.yml

@@ -0,0 +1,38 @@
+version: 2
+updates:
+  # Rust (Cargo) dependencies
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+      - "rust"
+    groups:
+      minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "ci"
+
+  # Python dependencies declared in pyproject.toml. The wheel is built by
+  # maturin, so there is no lockfile at the root to keep in step — weekly is
+  # enough.
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+      - "python"

madoqua-0.1.0/.github/workflows/audit.yml

@@ -0,0 +1,29 @@
+name: "Cargo Audit"
+
+on:
+  push:
+    paths:
+      - "Cargo.toml"
+      - "Cargo.lock"
+  pull_request:
+    paths:
+      - "Cargo.toml"
+      - "Cargo.lock"
+  schedule:
+    - cron: "0 0 * * *" # Daily at midnight UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  audit:
+    name: Security Audit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Run cargo-audit
+        uses: actions-rust-lang/audit@v1

madoqua-0.1.0/.github/workflows/cargo-deny.yml

@@ -0,0 +1,35 @@
+name: "Cargo Deny"
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "Cargo.lock"
+      - "Cargo.toml"
+      - "deny.toml"
+  pull_request:
+    paths:
+      - "Cargo.lock"
+      - "Cargo.toml"
+      - "deny.toml"
+
+permissions:
+  contents: read
+
+jobs:
+  deny:
+    name: ${{ matrix.check }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        check: [bans, licenses, sources]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Run cargo-deny (${{ matrix.check }})
+        uses: EmbarkStudios/cargo-deny-action@v2
+        with:
+          command: check ${{ matrix.check }}
+          arguments: --all-features

madoqua-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,42 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "src/**"
+      - "Cargo.toml"
+      - "Cargo.lock"
+  pull_request:
+    branches: ["main"]
+    paths:
+      - "src/**"
+      - "Cargo.toml"
+      - "Cargo.lock"
+  schedule:
+    - cron: "0 6 * * 1" # Weekly on Monday at 06:00 UTC
+
+permissions:
+  security-events: write
+  packages: read
+  actions: read
+  contents: read
+
+jobs:
+  analyze:
+    name: Analyze Rust
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: rust
+          build-mode: none
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:rust"

madoqua-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,63 @@
+name: Deploy docs
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "docs/**"
+      - "src/**"  # rebuild when CLI changes (help text may change)
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: "22"
+
+      - name: Lint mermaid diagrams
+        run: |
+          cd docs && npm ci --silent
+          cd .. && node docs/lint-mermaid.mjs
+
+      # Versions come from docs/toolchain.sh so CI and `make docs` cannot
+      # drift onto an incompatible mdbook/mdbook-mermaid pair.
+      - name: Install mdBook and preprocessors
+        run: |
+          eval "$(bash docs/toolchain.sh --versions)"
+          mkdir -p bin
+          curl -sSL "https://github.com/rust-lang/mdBook/releases/download/v$MDBOOK_VERSION/mdbook-v$MDBOOK_VERSION-x86_64-unknown-linux-gnu.tar.gz" | tar -xz --directory=bin
+          curl -sSL "https://github.com/badboy/mdbook-mermaid/releases/download/v$MDBOOK_MERMAID_VERSION/mdbook-mermaid-v$MDBOOK_MERMAID_VERSION-x86_64-unknown-linux-gnu.tar.gz" | tar -xz --directory=bin
+          echo "$PWD/bin" >> $GITHUB_PATH
+
+      - name: Check the docs toolchain matches the pins
+        run: bash docs/toolchain.sh
+
+      - name: Sync docs version badge with Cargo.toml
+        run: bash docs/gen-version.sh
+
+      - name: Build book
+        run: mdbook build docs
+
+      - name: Generate llms.txt
+        run: bash docs/generate-llms-txt.sh
+
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/book/html
+
+      - uses: actions/deploy-pages@v5
+        id: deployment

madoqua-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,114 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-14, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          args: --release --strip
+          manylinux: 2_28
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.os }}
+          path: target/wheels/*.whl
+
+  build-sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.11'
+
+      - name: Install maturin
+        run: pip install maturin
+
+      - name: Build sdist
+        run: maturin sdist
+
+      - name: Upload sdist
+        uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: target/wheels/*.tar.gz
+
+  create-release:
+    name: Create GitHub Release
+    needs: [build-wheels, build-sdist]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v8
+        with:
+          path: dist
+
+      - name: Flatten artifacts
+        run: |
+          mkdir -p wheels
+          find dist -name '*.whl' -exec cp {} wheels/ \;
+          find dist -name '*.tar.gz' -exec cp {} wheels/ \;
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: wheels/*
+          generate_release_notes: true
+          draft: false
+          prerelease: false
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: [build-wheels, build-sdist, create-release]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/') && github.event_name == 'push'
+    environment:
+      name: pypi
+      url: https://pypi.org/p/madoqua
+    permissions:
+      id-token: write
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v8
+        with:
+          path: dist
+
+      - name: Flatten artifacts
+        run: |
+          mkdir -p wheels
+          find dist -name '*.whl' -exec cp {} wheels/ \;
+          find dist -name '*.tar.gz' -exec cp {} wheels/ \;
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: wheels/
+          skip-existing: true

madoqua-0.1.0/.github/workflows/review.yml

@@ -0,0 +1,89 @@
+name: Code Review
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "docs/**"
+      - "scripts/**"
+      - "Makefile"
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "rust-toolchain.toml"
+      - "clippy.toml"
+      - "rustfmt.toml"
+  pull_request:
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "docs/**"
+      - "scripts/**"
+      - "Makefile"
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "rust-toolchain.toml"
+      - "clippy.toml"
+      - "rustfmt.toml"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  fmt:
+    name: Formatting
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+      - run: cargo fmt --all --check
+
+  clippy:
+    name: Clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo clippy --all-targets --all-features -- -D warnings
+
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo test --all-features
+
+  rustdoc:
+    name: Rustdoc
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      # Broken intra-doc links silently render as plain text on docs.rs;
+      # nothing else in this workflow catches them.
+      - run: cargo doc --no-deps --all-features
+        env:
+          RUSTDOCFLAGS: -D warnings
+
+  docs:
+    name: Docs are in sync
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Version badge matches Cargo.toml
+        run: bash docs/gen-version.sh --check
+      - name: Shared snippets are injected
+        run: bash docs/inject-shared.sh --check

madoqua-0.1.0/.gitignore

@@ -0,0 +1,81 @@
+# Rust
+/target/
+**/*.rs.bk
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+cf/
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Claude Code
+.claude/worktrees/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Logs
+*.log
+
+# Temporary files
+*.tmp
+*.temp
+.cache/
+
+# maturin / PyO3
+*.so
+*.pyd
+.eggs/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+
+# Fixture package virtualenvs
+tests/fixtures/**/.venv/
+
+# mdBook build output (docs/book.toml build-dir)
+docs/book/