# Retain these small wrappers in each consuming repository.
# Setup installs Just; recipes require a POSIX sh on PATH on every platform.
# Select dev explicitly, including when the consumer disables default groups.
set positional-arguments

# Generate, normalize, and rotate completed minor series into docs/archives/changelog.
changelog:
    uv run --locked --group dev research-repo-tools toolchain run -- research-repo-tools changelog generate

# Archive completed minor series without regenerating Git history.
changelog-archive:
    uv run --locked --group dev research-repo-tools changelog archive

# Validate the entire changelog and all archives without writing files.
changelog-check:
    uv run --locked --group dev research-repo-tools changelog check

# Generate, normalize, and rotate completed minor series without publishing files.
changelog-preview *args:
    uv run --locked --group dev research-repo-tools toolchain run -- research-repo-tools changelog generate --dry-run "$@"

# Generate and archive a prospective release with an explicit YYYY-MM-DD date.
changelog-release tag date:
    uv run --locked --group dev research-repo-tools toolchain run -- research-repo-tools changelog generate --tag {{quote(tag)}} --date {{quote(date)}}

alias changelog-unreleased := changelog-release

# Show command help when invoked without a recipe.
[default]
[private]
default: help

# Run a validator on tracked and nonignored inputs, with portable batching.
files +args:
    uv run --locked --group dev research-repo-tools files "$@"

# List available commands and arguments in lexicographic order.
help:
    @just --justfile {{quote(justfile())}} --alias-style separate --list

alias help-workflows := help

# Review configured notebook advisories; pass --strict to fail on warnings.
notebook-advise +files:
    notebook_group="$(uv run --locked --only-group tooling --inexact research-repo-tools notebooks group)" && uv run --locked --group dev --group "$notebook_group" research-repo-tools notebooks advise "$@"

# Validate structure, cell identities, and source output policy.
notebook-check +files:
    notebook_group="$(uv run --locked --only-group tooling --inexact research-repo-tools notebooks group)" && uv run --locked --group dev --group "$notebook_group" research-repo-tools notebooks check "$@"

# Deliberately clear generated notebook outputs and execution metadata.
notebook-clear +files:
    notebook_group="$(uv run --locked --only-group tooling --inexact research-repo-tools notebooks group)" && uv run --locked --group dev --group "$notebook_group" research-repo-tools notebooks clear "$@"

# Execute only the selected notebooks in fresh project kernels.
notebook-execute +files:
    notebook_group="$(uv run --locked --only-group tooling --inexact research-repo-tools notebooks group)" && uv run --locked --group dev --group "$notebook_group" research-repo-tools notebooks execute "$@"

# Inspect existing cells and repair problems without notebook dependencies.
notebook-inspect +files:
    uv run --locked --only-group tooling --inexact research-repo-tools notebooks inspect "$@"

# Check structure, Python syntax, Ruff rules/formatting, and ty types.
notebook-lint +files:
    notebook_group="$(uv run --locked --only-group tooling --inexact research-repo-tools notebooks group)" && uv run --locked --group dev --group "$notebook_group" research-repo-tools notebooks lint "$@"

# Synchronize the locked notebook environment and register its project kernel.
notebook-sync:
    uv run --locked --managed-python --only-group tooling research-repo-tools notebooks sync

# Compare timings, handle assets, and verify, render, or publish retained evidence.
performance +args:
    uv run --locked --group dev research-repo-tools performance "$@"

# Check consumer release metadata.
release-check:
    uv run --locked --group dev research-repo-tools release check

# Print release notes from the root changelog or an archive.
release-notes tag:
    uv run --locked --group dev research-repo-tools changelog notes {{quote(tag)}}

# Prepare release metadata offline with a reviewed predecessor and date.
release-update tag previous date:
    uv run --locked --group dev research-repo-tools release update "$1" --previous-release "$2" --date "$3"

# Review branch and local changes with CodeRabbit against a verified origin/main by default.
review base="origin/main":
    uv run --locked --group dev research-repo-tools review branch --base="$1"

# Review only staged, unstaged, and non-ignored untracked changes with CodeRabbit.
review-uncommitted:
    uv run --locked --group dev research-repo-tools review uncommitted

# Validate the consumer's Semgrep rules and fixtures.
semgrep-check:
    uv run --locked --group dev research-repo-tools semgrep check-fixtures

# Repeat the package setup after tool declarations change.
setup:
    uv run --locked --managed-python --only-group tooling research-repo-tools setup

# Create a local annotated tag using tag-release.
tag tag: (tag-release tag)

# Explicitly replace an existing local annotated tag.
tag-force tag:
    uv run --locked --group dev research-repo-tools changelog tag {{quote(tag)}} --force

# Create a local annotated tag from validated release notes.
tag-release tag:
    uv run --locked --group dev research-repo-tools changelog tag {{quote(tag)}}

# The environment must already exist; checking never syncs or downloads Python.
tools-check:
    uv run --locked --no-sync --no-python-downloads research-repo-tools toolchain check

# Export verified managed paths to the current GitHub Actions environment file.
tools-export:
    uv run --locked --no-sync --no-python-downloads research-repo-tools toolchain export

# Upgrade tools, then Cargo and Python dependencies and the dev environment.
update: update-tools update-dependencies

# Upgrade root Cargo requirements and resolution; retain consumer exclusions/extra roots here.
update-cargo-dependencies:
    if [ -f Cargo.toml ]; then uv run --locked --only-group tooling --inexact research-repo-tools toolchain run -- cargo upgrade --incompatible allow; fi
    if [ -f Cargo.toml ]; then uv run --locked --only-group tooling --inexact research-repo-tools toolchain run -- cargo update; fi

# Upgrade only declared managed Cargo tools and publish verified TOML pins.
update-cargo-tools:
    uv run --locked --only-group tooling --inexact research-repo-tools toolchain upgrade

# Update Cargo and Python dependencies without upgrading uv or Cargo tools.
update-dependencies: update-cargo-dependencies update-python-dependencies

# Update direct dev pins, upgrade the full Python lock, and sync dev with managed tools.
update-python-dependencies:
    uv run --locked --only-group tooling --inexact research-repo-tools deps update-python
    uv lock --upgrade
    uv run --locked --no-sync --no-python-downloads research-repo-tools toolchain run -- uv sync --locked --managed-python --group dev

alias update-python-deps := update-python-dependencies

# Upgrade uv and declared Cargo tools, then install Just and sync declared tools.
update-tools: update-uv update-cargo-tools setup

# Upgrade uv through its installation owner and reconcile the project pin.
update-uv:
    uv run --no-config --no-sync --no-python-downloads research-repo-tools deps update-uv

# Run declared scientific examples or validators in configuration order.
validate configuration *names:
    uv run --locked --group dev research-repo-tools toolchain run -- research-repo-tools validation run "$@"
