# 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

# Extend this gate with the consumer's Rust/domain checks; retain fixture validation.
check: python-check semgrep-check zizmor-check

# Local and CI use the same complete validation gate.
ci: check

# Preview obsolete package-owned tool installs; pass --apply to remove them.
clean *args:
    uv run --locked --no-sync --no-python-downloads research-repo-tools toolchain clean "$@"

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

# Check raw lines, list inputs, or batch a validator over tracked/nonignored files.
files +args:
    uv run --locked --group dev research-repo-tools files "$@"

# List recipes and arguments in lexicographic order, with aliases inline.
help:
    @just --justfile {{ quote(justfile()) }} --alias-style right --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 "$@"

# Launch configured JupyterLab with private session caches and explicit browser policy.
notebook-launch *args:
    uv run --locked --managed-python --only-group tooling --inexact research-repo-tools notebooks launch "$@"

# 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 "$@"

# Preview tracked notebook restoration and declared cleanup; pass --apply to mutate.
notebook-reset *args:
    uv run --locked --only-group tooling --inexact research-repo-tools notebooks reset "$@"

# 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

# Read explicit TeX dates, check PDF structure, or normalize a declared PDF.
papers +args:
    uv run --locked --group dev research-repo-tools papers "$@"

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

# Check every tracked/nonignored Python file, including deliberate negative fixtures.
python-check:
    uv run --locked --no-sync --no-python-downloads research-repo-tools python check

# Apply configured Ruff fixes and formatting to the complete Python inventory.
python-fix:
    uv run --locked --no-sync --no-python-downloads research-repo-tools python fix

# Run native ty over every tracked/nonignored Python file without fixing source.
python-typecheck:
    uv run --locked --no-sync --no-python-downloads research-repo-tools python typecheck

# Check final release metadata and dated notes against the canonical stable tag.
release-check tag:
    uv run --locked --group dev research-repo-tools release check "$1"

# Prepare a first release after verifying empty stable published history.
release-first tag date:
    uv run --locked --group dev research-repo-tools release update "$1" --first-release --date "$2"

# 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) }}

# Approve the reviewed draft GitHub Release and trigger registry publication.
release-publish tag:
    uv run --locked --group dev research-repo-tools release publish "$1" --approve

# Create a local annotated release tag from validated notes (maintainer only).
release-tag tag:
    uv run --locked --group dev research-repo-tools changelog tag "$1"

# Preview the release annotation without changing Git state.
release-tag-preview tag:
    uv run --locked --group dev research-repo-tools changelog tag "$1" --dry-run

# 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"

# Require the stable GitHub Release/assets and exact published registry version.
release-verify tag *args:
    uv run --locked --group dev research-repo-tools release verify "$@"

# 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

# Audit explicitly selected uv.lock/Cargo.lock files with the managed OSV scanner.
security-osv +lockfiles:
    uv run --locked --group dev research-repo-tools security osv "$@"

# Scan full history and current tracked/nonignored files with managed Gitleaks.
security-secrets *args:
    uv run --locked --group dev research-repo-tools security secrets "$@"

# 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

# Preview mandatory Python-minimum and optional tool-profile adoption outside the old environment.
shared-python-plan version:
    uv run --no-config --no-project --isolated --managed-python --script python-bootstrap.py "$1" --dry-run

# Apply the validated shared-package/Python/tool-profile migration and recreate the environment.
shared-python-update version:
    uv run --no-config --no-project --isolated --managed-python --script python-bootstrap.py "$1" --apply

# Discover/export existing native dependencies; never install host packages.
tectonic +args:
    uv run --locked --no-sync --no-python-downloads research-repo-tools tectonic "$@"

# 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

# Check opted-in Python tool declarations, lock, and executable versions without sync.
tools-python-check:
    uv run --locked --no-sync --no-python-downloads research-repo-tools toolchain python-tools-check

# Install and verify pinned release binaries in the existing locked environment.
tools-sync-binaries:
    uv run --locked --no-sync --no-python-downloads python -I -X utf8 -m research_repo_tools toolchain sync-binaries

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

# Explicit opt-in: append this stage after update-dependencies to check final tool pins.
update-actions *args:
    uv run --locked --only-group tooling --inexact research-repo-tools actions update --policy .github/action-updates.toml .github/workflows "$@"

# 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 declared managed Cargo tools and release binaries; 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 tools, then sync without shell/bootstrap configuration.
update-tools: update-uv update-cargo-tools

# Upgrade uv through its installation owner and reconcile the project pin.
update-uv *args:
    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 "$@"

# Use the consumer's committed strict selected-actions settings as the sole allowlist.
workflow-allowlist-check:
    uv run --locked --group dev research-repo-tools actions allowlist --policy .github/settings/allowed-actions.json .github/workflows

# Audit with the declared version/persona; pass --require-online in CI or --offline deliberately.
zizmor-check *args:
    uv run --locked --group dev research-repo-tools zizmor check "$@"
