.PHONY: help install install-deps fetch-resources lint lint-python lint-imports lint-deps lint-types lint-tui lint-bridge test test-python test-tui build build-tui build-bridge build-ui build-core check-commits check-pr-title check-large-files check-source-language check-core-wheel fetch-templates verify-templates beta ci clean coverage coverage-shard coverage-combine coverage-summary coverage-diff coverage-ratchet coverage-baseline-check coverage-baseline-candidate docker-build docker-up docker-down docs-serve docs-build PYTHON ?= python3 PYTHON_VERSION ?= 3.12 PYTHON_LINT_TARGETS ?= raven evolver agents plugins-dist tests scripts docs-site COMMIT_RANGE ?= origin/main..HEAD COVERAGE_BASE_REF ?= origin/main # Required coverage percentage for executable lines changed by a PR. COVERAGE_DIFF_THRESHOLD ?= 90 # Allowed line or branch regression in percentage points to absorb rounding noise. COVERAGE_RATCHET_TOLERANCE ?= 0.05 DOCKER_IMAGE ?= raven:local COVERAGE_REPORT_ARGS = --cov=raven --cov=raven_everos --cov=raven_everos_cloud --cov-branch --cov-report=term-missing:skip-covered --cov-report=xml --cov-report=json --cov-report=html # One slice of the suite, K/N; the shard writes its .coverage data and no report. COVERAGE_SHARD ?= 1/1 # Without an explicit encoding= Python opens text files in the locale encoding. # On a GBK-locale Windows checkout, the suite would read and write cp936 # wherever a test forgot encoding=. Exported, so every recipe runs in UTF-8 # mode; a bare `uv run pytest` does not go through this file, and # tests/conftest.py refuses that run instead. export PYTHONUTF8 := 1 # Extra pytest flags for a shard; CI passes --idle-ceiling-strict, a local run stays warning-only. PYTEST_ARGS ?= COVERAGE_DATA_ARGS = --cov=raven --cov=raven_everos --cov=raven_everos_cloud --cov-branch --cov-report= # Where the shards' .coverage.* files are gathered before they are combined. COVERAGE_DATA_DIR ?= coverage-data help: @echo "Targets:" @echo " install Install Python deps, Node deps, git hooks and the fetched resources" @echo " fetch-resources Download the tokenizer dictionary and the deepdoc models (idempotent)" @echo " install-deps Install Python deps only (CI uses this)" @echo " lint Run Python, TUI, and bridge lint gates" @echo " lint-python Ruff check + format gate over raven/, evolver/, tests/, scripts/" @echo " lint-tui TypeScript lint + RPC drift check" @echo " lint-bridge Bridge package build check" @echo " test Run focused Python checks and TUI tests" @echo " coverage Run the default Python suite with line and branch coverage" @echo " coverage-shard Run slice COVERAGE_SHARD (K/N) of the suite, writing .coverage data only" @echo " coverage-combine Combine the shards' .coverage.* files in COVERAGE_DATA_DIR (CI downloads them there) into coverage.json and coverage.xml" @echo " coverage-diff Check changed executable lines against COVERAGE_BASE_REF" @echo " coverage-ratchet Check total line and branch coverage against the baseline" @echo " coverage-baseline-check Ensure a proposed baseline never lowers the target branch" @echo " check-commits Validate Conventional Commit subjects" @echo " check-pr-title Validate the PR title in PR_TITLE" @echo " check-large-files Validate PR files avoid blocked assets and size bloat" @echo " check-source-language Validate PR-added lines stay English outside the exemption zones" @echo " check-core-wheel Build the raven-core wheel and smoke it in a clean venv" @echo " fetch-templates Re-pull the deck engine's ten bundled templates over the tracked copies (maintainers; needs GITLAB_TOKEN)" @echo " verify-templates Hash the tracked deck templates against their pins" @echo " docker-build Build the container image (page + engine + nginx)" @echo " docker-up Build if needed and start the stack from docker/" @echo " docker-down Stop the stack (the data volume is kept)" @echo " beta Build this checkout and publish it to the beta channel" @echo " ci Run the local CI gate" @echo " clean Remove generated caches and build output" install-deps: uv sync --frozen --python $(PYTHON_VERSION) --extra dev --dev install: install-deps fetch-resources uv run --frozen --python $(PYTHON_VERSION) pre-commit install uv run --frozen --python $(PYTHON_VERSION) pre-commit install --hook-type commit-msg npm ci npm ci --prefix ui-web npm ci --prefix ui-tui npm ci --prefix bridge # The word dictionary, the nltk corpora beside it and the deepdoc vision # models: ~160 MB that cannot live in git (AGENTS.md section 7 caps a file at # 1 MiB). Idempotent, so `make install` can call it every time. # # `--optional` on purpose: a developer behind a firewall that cannot reach # huggingface should still get a working checkout. What they lose is Chinese # segmentation and PDF layout, and both say so when asked rather than failing # the install that would have told them nothing. fetch-resources: uv run --frozen --python $(PYTHON_VERSION) python scripts/fetch_resources.py --optional lint: lint-python lint-imports lint-deps lint-types lint-ui lint-tui lint-bridge lint-python: uv run --frozen --python $(PYTHON_VERSION) --extra dev ruff check $(PYTHON_LINT_TARGETS) uv run --frozen --python $(PYTHON_VERSION) --extra dev ruff format --check $(PYTHON_LINT_TARGETS) lint-deps: uv run --frozen --python $(PYTHON_VERSION) --all-extras deptry raven lint-imports: uv run --frozen --python $(PYTHON_VERSION) lint-imports # Call correctness, not typing strictness -- which rules are on, and the backlog # behind each one that is off, are in [tool.ty] in pyproject.toml. The target # roster is read from PYTHON_LINT_TARGETS so it cannot drift from ruff's; tests # are filtered out there because they are executed, and the gate is for code # that is not. docs-site is filtered out for a different reason: its build # hooks import mkdocs, which install-deps does not install, so ty would read # a resolvable import as a missing module. ruff still covers that tree. lint-types: uv run --frozen --python $(PYTHON_VERSION) --all-extras ty check $(filter-out tests docs-site,$(PYTHON_LINT_TARGETS)) lint-ui: npm run gen:check --prefix ui-web npm run lint --prefix ui-web npm run type-check --prefix ui-web lint-tui: npm run lint --prefix ui-tui npm run lint:rpc --prefix ui-tui npm run lint:i18n --prefix ui-tui npm run type-check --prefix ui-tui lint-bridge: npm run build --prefix bridge test: test-python test-ui test-tui test-ui: npm test --prefix ui-web test-python: uv run --frozen --python $(PYTHON_VERSION) --all-extras pytest -q coverage: TERM=dumb uv run --frozen --python $(PYTHON_VERSION) --all-extras pytest -q $(COVERAGE_REPORT_ARGS) coverage-shard: TERM=dumb uv run --frozen --python $(PYTHON_VERSION) --all-extras pytest -q --shard $(COVERAGE_SHARD) --durations=25 $(PYTEST_ARGS) $(COVERAGE_DATA_ARGS) coverage-combine: uv run --frozen --python $(PYTHON_VERSION) coverage combine --keep $(COVERAGE_DATA_DIR) uv run --frozen --python $(PYTHON_VERSION) coverage json uv run --frozen --python $(PYTHON_VERSION) coverage xml coverage-summary: uv run --frozen --python $(PYTHON_VERSION) python scripts/coverage_gate.py summary coverage-diff: uv run --frozen --python $(PYTHON_VERSION) python scripts/coverage_gate.py diff --base-ref $(COVERAGE_BASE_REF) --threshold $(COVERAGE_DIFF_THRESHOLD) coverage-ratchet: uv run --frozen --python $(PYTHON_VERSION) python scripts/coverage_gate.py ratchet --tolerance $(COVERAGE_RATCHET_TOLERANCE) coverage-baseline-check: uv run --frozen --python $(PYTHON_VERSION) python scripts/coverage_gate.py baseline-check --base-ref $(COVERAGE_BASE_REF) coverage-baseline-candidate: uv run --frozen --python $(PYTHON_VERSION) python scripts/coverage_gate.py baseline test-tui: npm test --prefix ui-tui build: build-tui build-bridge build-ui build-tui: npm run build --prefix ui-tui build-ui: npm ci --prefix ui-web npm run --prefix ui-web build # Through uv like every other python line here, rather than through # whatever `python3` the shell resolves. The assembler writes the page # with `Path.write_text(newline="")`, which is 3.10 and later; a stock # macOS resolves `python3` to 3.9 and the build fails on a keyword # argument, which reads as a defect in the script rather than as the # wrong interpreter. uv run --frozen --python $(PYTHON_VERSION) python ui-web/build.py build-bridge: npm run build --prefix bridge build-core: uv run --frozen --python $(PYTHON_VERSION) python scripts/build_core_wheel.py check-commits: npx commitlint --from origin/main --to HEAD --config commitlint.config.cjs PYTHONPATH=. uv run --frozen --python $(PYTHON_VERSION) --extra dev python scripts/check_commit_messages.py $(COMMIT_RANGE) check-pr-title: PYTHONPATH=. uv run --frozen --python $(PYTHON_VERSION) --extra dev python scripts/check_pr_title.py check-large-files: PYTHONPATH=. uv run --frozen --python $(PYTHON_VERSION) --extra dev python scripts/check_large_files.py $(COMMIT_RANGE) check-source-language: PYTHONPATH=. uv run --frozen --python $(PYTHON_VERSION) --extra dev python scripts/check_source_language.py $(COMMIT_RANGE) # Out of the default pytest scope by norecursedirs (it builds a wheel and a # venv); this target is what CI and `make ci` run so the artifact stays honest. check-core-wheel: uv run --frozen --python $(PYTHON_VERSION) pytest tests/integration/test_kernel_wheel_smoke.py -q -o addopts="" # The image builds the page and the Python environment itself, so these need # no prior `make build`. Compose reads docker/.env for ports and extras. docker-build: docker build -t $(DOCKER_IMAGE) . docker-up: cd docker && docker compose up --build $(COMPOSE_ARGS) docker-down: cd docker && docker compose down beta: PYTHONPATH=. uv run python scripts/publish_beta.py $(BETA_ARGS) ci: lint test build check-core-wheel clean: rm -rf .pytest_cache .ruff_cache .uv-cache .mypy_cache htmlcov coverage.xml coverage.json coverage-baseline-candidate.json dist build rm -rf ui-tui/dist ui-tui/coverage ui-tui/.vitest-cache ui-tui/packages/hermes-ink/dist rm -rf bridge/dist rm -rf ui-web/dist find . -type d -name __pycache__ -prune -exec rm -rf {} + # Not an install step: the ten templates are tracked, and a clone already has # them. This lands a fresh cut over them, to be committed with rewritten pins. fetch-templates: python3 plugins-dist/ppt-engine/fetch_templates.py verify-templates: python3 plugins-dist/ppt-engine/fetch_templates.py --verify docs-serve: uv run --frozen --python $(PYTHON_VERSION) --group docs mkdocs serve -f docs-site/mkdocs.yml docs-build: uv run --frozen --python $(PYTHON_VERSION) --group docs mkdocs build -f docs-site/mkdocs.yml --strict