# matra task runner. Run `just` to see all recipes.
#
# Recipes are the single source of truth for repeatable workflows.
# CI, the pre-commit hook, and humans all run the same commands.

# Default: print the recipe list.
default:
    @just --list

# ---------------------------------------------------------------------------
# Quality gates — same commands CI runs.
# ---------------------------------------------------------------------------

# Run the local gate suite: the Rust gates, the boundary check, the docsite
# floor, the blueprint citation check and the .claude/ citation check, which
# CI also runs, plus the Python
# lint, the end-to-end sandbox test and the version sync, which CI does not run
# on a pull request.
# CI additionally runs cargo-deny, cargo-semver-checks, the wheel build and
# mypy.
check: fmt-check check-rust check-rust-no-default check-wasm clippy clippy-no-default doc test test-cli test-no-default lint-py boundary test-sandbox docs-floor blueprint-refs claude-citations version-sync
    @echo ""
    @echo "all gates pass"

# Run the Python type-check (mypy) over the Python sources + stubs.
# Requires `uv pip install -e '.[typecheck]'` once.
typecheck:
    python -m mypy

# Compares python/matra/_core.pyi with the built extension: names,
# parameters, defaults, @final. Requires `maturin develop` first; CI runs
# it in the pytype job.
# Check the Python stub against the built extension module.
stubtest:
    python -m mypy.stubtest matra._core

# Format check (read-only).
fmt-check:
    cargo fmt --all -- --check

# Rewrite source to canonical formatting.
fmt:
    cargo fmt --all

# Type-check the workspace under default features.
check-rust:
    cargo check --all-targets

# Type-check the workspace with no default features.
check-rust-no-default:
    cargo check --all-targets --no-default-features

# Type-check the wasm32 builds CI checks (the core, and the model2vec
# adapter), warnings as errors. Skipped with a warning when the target is
# not installed: `rustup target add wasm32-unknown-unknown`.
check-wasm:
    #!/usr/bin/env bash
    set -euo pipefail
    if ! rustup target list --installed 2>/dev/null | grep -qx wasm32-unknown-unknown; then
        echo "check-wasm: wasm32-unknown-unknown not installed; skipped (CI still checks it)" >&2
        exit 0
    fi
    RUSTFLAGS="-Dwarnings" cargo check --no-default-features --target wasm32-unknown-unknown
    RUSTFLAGS="-Dwarnings" cargo check --no-default-features --features model2vec --target wasm32-unknown-unknown

# Clippy under default features, warnings are errors.
clippy:
    RUSTFLAGS="-Dwarnings" cargo clippy --all-targets -- -D warnings

# Clippy with no default features, warnings are errors.
clippy-no-default:
    RUSTFLAGS="-Dwarnings" cargo clippy --all-targets --no-default-features -- -D warnings

# Build docs with all features, broken intra-doc links are errors.
doc:
    RUSTDOCFLAGS="-Dwarnings" cargo doc --no-deps --all-features

# Unit + doctest under default features.
test:
    cargo test --features udpipe

# Unit + the CLI's own tests. The `cli` feature is not in the default
# set, so `just test` alone never compiles src/cli/.
test-cli:
    cargo test --features cli

# Unit + doctest with no default features.
test-no-default:
    cargo test --no-default-features

# Boundary check: the semgrep rules in .semgrep/ for boundary rules 1, 2, 3,
# 4, 5, 7 (its CLI part) and 8, plus the library's error conventions. Runs
# each rule file against its fixture (`semgrep --test`), then scans src/ and
# fails if any Rust file there went unread. Requires semgrep (the version in
# .github/requirements/semgrep.txt) and a git work tree. EP-0014.
boundary:
    bash scripts/check-boundaries.sh

# Every RFC-NNNN and EP-NNNN cited in the tracked tree resolves to a record in
# blueprints/ (or a reserved number), and every record has a row in the index
# in blueprints/README.md. Requires ripgrep.
blueprint-refs:
    bash scripts/check-blueprint-refs.sh

# Every `path:line` citation in a tracked file under .claude/ names a file
# that exists and a line inside it. Runs the check's own tests first, which
# plant each kind of failure and watch it fail.
claude-citations:
    bash scripts/test-claude-citations.sh
    bash scripts/check-claude-citations.sh

# The end-to-end sandbox script cannot report a clean result for a tree it did
# not examine without saying so. Needs an unprivileged user for the unreadable and unwritable
# cases; under uid 0 it skips those and says so.
test-sandbox:
    bash scripts/test-e2e-sandbox.sh

# Every version-carrying file agrees, and CITATION.cff's release date matches
# the CHANGELOG heading for that version (RFC-0013).
version-sync:
    bash scripts/check-version-sync.sh

# Requires bun, cargo and ripgrep. lychee is optional locally (skip-with-warning);
# the `Docsite floor` job in ci.yml installs it and sets LYCHEE_REQUIRED=1 to
# escalate the skip into a hard failure. The ten gates: links, orphans, type
# names, the site build, em dashes, llms.txt, the published URL manifest,
# figures current, figure twins, and input licences. The figures gate fetches
# the UDPipe model on first run.
# Floor gates for the docsite.
docs-floor:
    bash scripts/check-docsite-floor.sh

# Every input in site/inputs/, through the released pipeline, written as JSON
# into site/src/lib/figures/. Fetches the UDPipe model on first run.
# Regenerate the docsite's figure data.
docs-figures:
    cargo run --features model2vec --example docsite_figures

# Run every worked example in site/examples/ in Rust, Python and the CLI, and
# write the Rust and CLI output as the committed output. The Python call is
# compared, not written: it needs matra importable (`maturin develop`).
docs-examples:
    cargo build --example docsite_examples
    cargo build --features cli --bin matra
    cd site && EXAMPLES_RUNNER=../target/debug/examples/docsite_examples MATRA_BIN=../target/debug/matra bun scripts/check-examples.ts --write

# Search needs the index the build writes, so it answers only in a built site.
# Serve the docsite with live reload at http://localhost:3000.
docs-serve:
    cd site && bun install --frozen-lockfile && bun run dev

# Every page prerendered, its Markdown twin beside it, and the search index.
# BASE_PATH=/matra builds it for GitHub Pages.
# Build the docsite into site/build.
docs-build:
    cd site && bun install --frozen-lockfile && bun run build

# The local comments on the docsite (dev server only; site/README.md, Local
# comments) are discussion/<route>.jsonl. --all includes resolved threads.
# List the open comment threads on every page.
comments *flags:
    cd site && bun scripts/comments.ts list {{flags}}

# Append a reply as Claude, e.g.
# just comment-reply /blueprints/index 1a2b3c4d "Done in 3f2e1a0."
# Reply to a local comment thread.
comment-reply page thread body:
    cd site && bun scripts/comments.ts reply {{quote(page)}} {{quote(thread)}} {{quote(body)}}

# ---------------------------------------------------------------------------
# Setup
# ---------------------------------------------------------------------------

# Install the pre-commit hook into .git/hooks/.
install-hooks:
    bash scripts/install-hooks.sh

# ---------------------------------------------------------------------------
# Run the conformance suite across every crust. Both models are fetched on
# the first run and cached after it: UDPipe into the resolved model
# directory, potion-base-8M into that directory or MATRA_MODEL2VEC_DIR.
# Each is pinned by a digest in the source, so a first run needs a network.
# The parity lane runs the same files through Rust, the command line and
# Python against one fixture, so a drift on any surface fails its runner.
conformance:
    cargo test --test conformance -- --ignored
    cargo test --features model2vec --test semantic_conformance -- --include-ignored
    cargo test --test corpus_conformance
    cargo test --test outcome_conformance -- --include-ignored
    cargo test --features cli --test parity -- --ignored
    uv run --extra test pytest python/tests/test_conformance.py python/tests/test_semantic_conformance.py python/tests/test_corpus_conformance.py python/tests/test_outcome_conformance.py python/tests/test_parity.py -q


# ---------------------------------------------------------------------------
# Quality
# ---------------------------------------------------------------------------

# Lint every language surface.
lint: clippy clippy-no-default lint-py

# Ruff over the Python surface, and the docsite examples' Python calls.
lint-py:
    uv run --extra lint ruff check python/ site/examples/
    uv run --extra lint ruff format --check python/ site/examples/

# Python tests. Conformance needs the model; use `just test-py-fast` without it.
test-py:
    uv run --extra test pytest

test-py-fast:
    uv run --extra test pytest -m "not model"

# Rust line coverage. Prints a summary and writes lcov.info.
#
# Needs llvm-tools in the active toolchain's sysroot:
#   rustup component add llvm-tools-preview
coverage:
    cargo llvm-cov --features cli --lcov --output-path lcov.info
    cargo llvm-cov --features cli --summary-only

# Python line coverage.
coverage-py:
    uv run --extra test pytest --cov --cov-report=term --cov-report=xml

# Coverage across both crusts.
coverage-all: coverage coverage-py

# ---------------------------------------------------------------------------
# Release
# ---------------------------------------------------------------------------

# Roll the changelog and bump Cargo.toml in preparation for a release.
# Does NOT publish. Inspect the result, then run `just release VERSION`.
release-prep VERSION:
    bash scripts/changelog-release.sh {{VERSION}}
    @echo ""
    @echo "release prep complete for {{VERSION}}"
    @echo ""
    @echo "next: review the diff, then:"
    @echo "  cargo publish --dry-run --features udpipe"
    @echo "  just release {{VERSION}}"

# Release VERSION. Nothing publishes from a laptop and nothing is tagged
# from one either: .github/workflows/release.yml is dispatched from main,
# verifies the version, creates the annotated tag itself, builds and
# attests every artifact, then pauses at the `crates-io` and `pypi`
# environment gates for a required-reviewer approval before either
# registry is written. Those two approvals are the canonical per-publish
# approval points. This recipe prints the dispatch command.
release VERSION:
    @echo "Pre-release checks (the workflow re-checks all of these):"
    @echo "  - the commit you want to release is merged to main"
    @echo "  - cargo publish --dry-run --features udpipe is clean"
    @echo "  - the [{{VERSION}}] section of CHANGELOG.md is correct"
    @echo "  - just version-sync is clean and reports {{VERSION}}"
    @echo "  - CITATION.cff date-released is the date you are actually releasing"
    @echo "  - the maturin image digest in release.yml is current enough"
    @echo ""
    @echo "When ready, dispatch the release from main:"
    @echo "  gh workflow run release.yml --ref main -f version={{VERSION}}"
    @echo ""
    @echo "To retry a publish against the tag it already created:"
    @echo "  gh workflow run release.yml --ref main -f version={{VERSION}} -f skip_tag=true"
    @echo ""
    @echo "The run pauses twice, once per registry. Approve each deployment"
    @echo "in the GitHub Actions UI. A post-publish smoke job then installs"
    @echo "{{VERSION}} from PyPI and crates.io on Linux and macOS."
