ROOT := $(abspath $(dir $(lastword $(MAKEFILE_LIST))))
VENV ?= $(ROOT)/.venv
VENV_PYTHON := $(VENV)/bin/python
PYTHON ?= $(if $(wildcard $(VENV_PYTHON)),$(VENV_PYTHON),python3)
LOCAL_PYTHONPATH := $(ROOT)/src
NADOC := PYTHONPATH="$(LOCAL_PYTHONPATH)" $(PYTHON) -m nadoc

SPEC ?= docs/openapi.yaml
OVERLAY ?= docs/overlay.yaml
OUTPUT ?= docs/rendered-openapi
OVERLAY_OUTPUT ?= docs/rendered-with-overlay
SMOKE_ROOT ?= /tmp/nadoc-smoke
SMOKE_OUTPUT ?= /tmp/nadoc-rendered

.DEFAULT_GOAL := help

.PHONY: help setup local-path test lint typecheck audit format check render render-overlay open open-overlay build package-check smoke release-check clean

help: ## Show available development commands
	@printf '%s\n' \
		'make setup           Create .venv and install editable development dependencies' \
		'make local-path      Confirm Nadoc is imported from this checkout' \
		'make test            Run the unit test suite' \
		'make lint            Run Ruff linting and formatting checks' \
		'make typecheck       Run Pyright static type checking' \
		'make audit           Audit installed dependencies for known vulnerabilities' \
		'make format          Format Python sources with Ruff' \
		'make check           Run tests, linting, type checking, auditing, and syntax checks' \
		'make render          Render the scratch OpenAPI document' \
		'make render-overlay  Render the scratch document with its overlay' \
		'make open            Open the plain generated documentation' \
		'make open-overlay    Open the overlay-generated documentation' \
		'make build           Build fresh source and wheel distributions' \
		'make package-check   Validate built distributions' \
		'make smoke           Install and smoke-test the built wheel' \
		'make release-check   Run checks, build, package validation, and smoke test' \
		'make clean           Remove generated output, distributions, and caches' \
		'' \
		'Variables can be overridden, for example:' \
		'make render SPEC=api.yaml OUTPUT=build/docs'

setup: ## Create the development environment
	@$(PYTHON) -m venv "$(VENV)"
	@"$(VENV_PYTHON)" -m pip install --upgrade pip
	@"$(VENV_PYTHON)" -m pip install --editable '$(ROOT)[dev,fonts]'

local-path: ## Print the Nadoc module path used by Make
	@PYTHONPATH="$(LOCAL_PYTHONPATH)" $(PYTHON) -c 'import nadoc; print(nadoc.__file__)'

test: ## Run unit tests against the current checkout
	@PYTHONPATH="$(LOCAL_PYTHONPATH)" $(PYTHON) -m unittest discover -s tests -v

lint: ## Check Python style and formatting
	@$(PYTHON) -m ruff check src tests scripts
	@$(PYTHON) -m ruff format --check src tests scripts

typecheck: ## Check Python types
	@$(PYTHON) -m pyright --pythonpath "$$($(PYTHON) -c 'import sys; print(sys.executable)')"

audit: ## Check dependencies against known vulnerability databases
	@$(PYTHON) -m pip_audit --skip-editable --progress-spinner off

format: ## Reformat Python sources
	@$(PYTHON) -m ruff check --fix src tests scripts
	@$(PYTHON) -m ruff format src tests scripts

check: test lint typecheck audit ## Run all development checks
	@PYTHONPATH="$(LOCAL_PYTHONPATH)" $(PYTHON) -m compileall -q src tests
	@node --check src/nadoc/assets/nada.js

render: ## Render SPEC to OUTPUT using the current checkout
	@$(NADOC) "$(SPEC)" --output-dir "$(OUTPUT)"

render-overlay: ## Render SPEC with OVERLAY to OVERLAY_OUTPUT
	@$(NADOC) "$(SPEC)" --overlay "$(OVERLAY)" --output-dir "$(OVERLAY_OUTPUT)"

open: render ## Render and open the plain documentation (macOS)
	@open "$(OUTPUT)/index.html"

open-overlay: render-overlay ## Render and open the overlaid documentation (macOS)
	@open "$(OVERLAY_OUTPUT)/index.html"

build: ## Build fresh source and wheel distributions
	@rm -rf build dist
	@$(PYTHON) -m build

package-check: ## Validate built distributions
	@$(PYTHON) -m twine check dist/*
	@$(PYTHON) scripts/check_distribution.py dist/*

smoke: ## Install the wheel in isolation and render a fixture
	@rm -rf "$(SMOKE_ROOT)" "$(SMOKE_OUTPUT)"
	@$(PYTHON) -m venv "$(SMOKE_ROOT)"
	@"$(SMOKE_ROOT)/bin/python" -m pip install dist/*.whl
	@"$(SMOKE_ROOT)/bin/python" -m pip check
	@"$(SMOKE_ROOT)/bin/nadoc" --version
	@"$(SMOKE_ROOT)/bin/nadoc" "$(ROOT)/tests/fixtures/basic.yaml" --output-dir "$(SMOKE_OUTPUT)"
	@test -s "$(SMOKE_OUTPUT)/index.html"
	@test -s "$(SMOKE_OUTPUT)/openapi.yaml"

release-check: check build package-check smoke ## Run the complete release gate

clean: ## Remove generated output, distributions, and caches
	@rm -rf "$(OUTPUT)" "$(OVERLAY_OUTPUT)" build dist .coverage .coverage.* htmlcov .pytest_cache .ruff_cache .mypy_cache .pyright
	@find . -type d \( -name __pycache__ -o -name '*.egg-info' \) -not -path './.git/*' -prune -exec rm -rf {} +
	@find . -name .DS_Store -not -path './.git/*' -delete
