Developer Setup¶

# Lint Configuration (no root cache pollution)

RUFF        := $(ACT)/ruff
MYPY        := $(ACT)/mypy
PYTYPE      := $(ACT)/pytype
CODESPELL   := $(ACT)/codespell
PYRIGHT     := $(ACT)/pyright
PYDOCSTYLE  := $(ACT)/pydocstyle
RADON       := $(ACT)/radon

# Targets & dirs
LINT_DIRS           ?= src/bijux_cli tests
LINT_ARTIFACTS_DIR  ?= artifacts/lint

# Tool caches inside artifacts_pages/lint
RUFF_CACHE_DIR      ?= $(LINT_ARTIFACTS_DIR)/.ruff_cache
MYPY_CACHE_DIR      ?= $(LINT_ARTIFACTS_DIR)/.mypy_cache
PYTYPE_OUT_DIR      ?= $(LINT_ARTIFACTS_DIR)/.pytype

# In case these are not defined elsewhere
VENV_PYTHON         ?= python3

.PHONY: lint lint-artifacts lint-file lint-dir lint-clean

lint: lint-artifacts
    @echo "✔ Linting completed (logs in '$(LINT_ARTIFACTS_DIR)')"

lint-artifacts: | $(VENV)
    @mkdir -p "$(LINT_ARTIFACTS_DIR)" "$(RUFF_CACHE_DIR)" "$(MYPY_CACHE_DIR)" "$(PYTYPE_OUT_DIR)"
    @set -euo pipefail; { \
      echo "→ Ruff format (check)"; \
      $(RUFF) format --check --cache-dir "$(RUFF_CACHE_DIR)" $(LINT_DIRS); \
    } 2>&1 | tee "$(LINT_ARTIFACTS_DIR)/ruff-format.log"
    @set -euo pipefail; $(RUFF) check --fix --config config/ruff.toml --cache-dir "$(RUFF_CACHE_DIR)" $(LINT_DIRS) 2>&1 | tee "$(LINT_ARTIFACTS_DIR)/ruff.log"
    @set -euo pipefail; $(MYPY) --config-file config/mypy.ini --strict --cache-dir "$(MYPY_CACHE_DIR)" $(LINT_DIRS) 2>&1 | tee "$(LINT_ARTIFACTS_DIR)/mypy.log"
    @set -euo pipefail; $(PYRIGHT) --project config/pyrightconfig.json 2>&1 | tee "$(LINT_ARTIFACTS_DIR)/pyright.log"
    @set -euo pipefail; $(CODESPELL) -I config/bijux.dic $(LINT_DIRS) 2>&1 | tee "$(LINT_ARTIFACTS_DIR)/codespell.log"
    @set -euo pipefail; $(RADON) cc -s -a $(LINT_DIRS) 2>&1 | tee "$(LINT_ARTIFACTS_DIR)/radon.log"
    @set -euo pipefail; $(PYDOCSTYLE) --convention=google $(LINT_DIRS) 2>&1 | tee "$(LINT_ARTIFACTS_DIR)/pydocstyle.log"
    @if $(VENV_PYTHON) -c 'import sys; sys.exit(0 if sys.version_info < (3,13) else 1)'; then \
      set -euo pipefail; $(PYTYPE) -o "$(PYTYPE_OUT_DIR)" --keep-going --disable import-error $(LINT_DIRS) 2>&1 | tee "$(LINT_ARTIFACTS_DIR)/pytype.log"; \
    else \
      echo "Pytype skipped on Python ≥3.13" | tee "$(LINT_ARTIFACTS_DIR)/pytype.log"; \
    fi
    @[ -d .pytype ] && echo "→ removing stray .pytype" && rm -rf .pytype || true
    @[ -d .mypy_cache ] && echo "→ removing stray .mypy_cache" && rm -rf .mypy_cache || true
    @[ -d .ruff_cache ] && echo "→ removing stray .ruff_cache" && rm -rf .ruff_cache || true
    @printf "OK\n" > "$(LINT_ARTIFACTS_DIR)/_passed"

lint-file:
ifndef file
    $(error Usage: make lint-file file=path/to/file.py)
endif
    @$(call run_tool,RuffFormat,$(RUFF) format --cache-dir "$(RUFF_CACHE_DIR)")
    @$(call run_tool,Ruff,$(RUFF) check --fix --config config/ruff.toml --cache-dir "$(RUFF_CACHE_DIR)")
    @$(call run_tool,Mypy,$(MYPY) --config-file config/mypy.ini --strict --cache-dir "$(MYPY_CACHE_DIR)")
    @$(call run_tool,Codespell,$(CODESPELL) -I config/bijux.dic)
    @$(call run_tool,Pyright,$(PYRIGHT) --project config/pyrightconfig.json)
    @$(call run_tool,Radon,$(RADON) cc -s -a)
    @$(call run_tool,Pydocstyle,$(PYDOCSTYLE) --convention=google)
    @if $(VENV_PYTHON) -c 'import sys; sys.exit(0 if sys.version_info < (3,13) else 1)'; then \
      $(call run_tool,Pytype,$(PYTYPE) -o "$(PYTYPE_OUT_DIR)" --keep-going --disable import-error); \
    else \
      echo "→ Skipping Pytype (unsupported on Python ≥ 3.13)"; \
    fi

lint-dir:
ifndef dir
    $(error Usage: make lint-dir dir=<directory_path>)
endif
    @$(MAKE) LINT_DIRS="$(dir)" lint-artifacts

lint-clean:
    @echo "→ Cleaning lint artifacts"
    @rm -rf "$(LINT_ARTIFACTS_DIR)" .pytype .mypy_cache .ruff_cache || true
    @echo "✔ done"

##@ Lint
lint: ## Run all lint checks; save logs to artifacts_pages/lint/ (ruff/mypy/pytype caches under artifacts_pages/lint)
lint-artifacts: ## Same as 'lint' (explicit), generates logs
lint-file: ## Lint a single file (requires file=<path>)
lint-dir: ## Lint a directory (requires dir=<path>)
lint-clean: ## Remove lint artifacts_pages, including caches

# Quality Configuration (evidence → artifacts_pages/quality)

INTERROGATE_PATHS ?= src/bijux_cli
QUALITY_PATHS     ?= src/bijux_cli

VULTURE     := $(ACT)/vulture
DEPTRY      := $(ACT)/deptry
REUSE       := $(ACT)/reuse
INTERROGATE := $(ACT)/interrogate
PYTHON      := $(shell command -v python3 || command -v python)

QUALITY_ARTIFACTS_DIR ?= artifacts/quality
QUALITY_OK_MARKER     := $(QUALITY_ARTIFACTS_DIR)/_passed

ifeq ($(shell uname -s),Darwin)
  BREW_PREFIX  := $(shell command -v brew >/dev/null 2>&1 && brew --prefix)
  CAIRO_PREFIX := $(shell test -n "$(BREW_PREFIX)" && brew --prefix cairo)
  QUALITY_ENV  := DYLD_FALLBACK_LIBRARY_PATH="$(BREW_PREFIX)/lib:$(CAIRO_PREFIX)/lib:$$DYLD_FALLBACK_LIBRARY_PATH"
else
  QUALITY_ENV  :=
endif

.PHONY: quality interrogate-report quality-clean

quality:
    @echo "→ Running quality checks..."
    @mkdir -p "$(QUALITY_ARTIFACTS_DIR)"

    @echo "   - Dead code analysis (Vulture)"
    @set -euo pipefail; \
      { $(VULTURE) --version 2>/dev/null || echo vulture; } >"$(QUALITY_ARTIFACTS_DIR)/vulture.log"; \
      OUT="$$( $(VULTURE) $(QUALITY_PATHS) --min-confidence 80 2>&1 || true )"; \
      printf '%s\n' "$$OUT" >>"$(QUALITY_ARTIFACTS_DIR)/vulture.log"; \
      if [ -z "$$OUT" ]; then echo "✔ Vulture: no dead code found." >>"$(QUALITY_ARTIFACTS_DIR)/vulture.log"; fi

    @echo "   - Dependency hygiene (Deptry)"
    @set -euo pipefail; \
      { $(DEPTRY) --version 2>/dev/null || true; } >"$(QUALITY_ARTIFACTS_DIR)/deptry.log"; \
      $(DEPTRY) $(QUALITY_PATHS) 2>&1 | tee -a "$(QUALITY_ARTIFACTS_DIR)/deptry.log"

    @echo "   - License & SPDX compliance (REUSE)"
    @set -euo pipefail; \
      { $(REUSE) --version 2>/dev/null || true; } >"$(QUALITY_ARTIFACTS_DIR)/reuse.log"; \
      $(REUSE) lint 2>&1 | tee -a "$(QUALITY_ARTIFACTS_DIR)/reuse.log"

    @echo "   - Documentation coverage (Interrogate)"
    @$(MAKE) interrogate-report

    @echo "✔ Quality checks passed"
    @printf "OK\n" >"$(QUALITY_OK_MARKER)"

interrogate-report:
    @echo "→ Generating docstring coverage report (<100%)"
    @mkdir -p "$(QUALITY_ARTIFACTS_DIR)"
    @set +e; \
      OUT="$$( $(QUALITY_ENV) $(INTERROGATE) --verbose $(INTERROGATE_PATHS) )"; \
      rc=$$?; \
      printf '%s\n' "$$OUT" >"$(QUALITY_ARTIFACTS_DIR)/interrogate.full.txt"; \
      OFF="$$(printf '%s\n' "$$OUT" | awk -F'|' 'NR>3 && $$0 ~ /^\|/ { \
        name=$$2; cov=$$6; gsub(/^[ \t]+|[ \t]+$$/, "", name); gsub(/^[ \t]+|[ \t]+$$/, "", cov); \
        if (name !~ /^-+$$/ && cov != "100%") printf("  - %s (%s)\n", name, cov); \
      }')"; \
      printf '%s\n' "$$OFF" >"$(QUALITY_ARTIFACTS_DIR)/interrogate.offenders.txt"; \
      if [ -n "$$OFF" ]; then printf '%s\n' "$$OFF"; else echo "✔ All files 100% documented"; fi; \
      exit $$rc

quality-clean:
    @echo "→ Cleaning quality artifacts"
    @rm -rf "$(QUALITY_ARTIFACTS_DIR)"

##@ Quality
quality: ## Run Vulture, Deptry, REUSE, Interrogate; save logs to artifacts_pages/quality/
interrogate-report: ## Save full Interrogate table + offenders list
quality-clean: ## Remove artifacts_pages/quality

target-version = "py311"
line-length = 88
respect-gitignore = true
src = ["src", "tests"]

exclude = [
  ".git", ".hg", ".mypy_cache", ".pytest_cache", ".ruff_cache", ".tox", ".venv",
  "build", "dist", "docs", "htmlcov", "__pycache__", "migrations", "*.egg-info"
]

[lint]
select = [
  "E","F","I","B","UP","SIM","PT","N","A","C4","S","TID","PERF",
  # "RUF","ARG","TRY","T20","BLE","ERA"
]
ignore = ["E501", "E203"]

[lint.per-file-ignores]
"tests/**" = ["S101"]
"__init__.py" = ["F401"]

[lint.isort]
force-sort-within-sections = true
known-first-party = ["bijux_cli"]
required-imports = ["from __future__ import annotations"]

[lint.flake8-tidy-imports]
ban-relative-imports = "parents"

[lint.mccabe]
max-complexity = 10

[tool.deptry]
ignore = ["DEP002", "DEP003"]

[tool.interrogate]
fail-under = 98
exclude = ["src/bijux_cli/core/di.py"]
color = true

[mypy]
python_version = 3.11
strict = true

show_error_codes = true
pretty = true
warn_unreachable = true
warn_unused_configs = true
warn_unused_ignores = true
follow_imports = silent

mypy_path = src
files = src, tests

exclude = ^(\.venv|build|dist|docs|htmlcov|\.mypy_cache|\.pytest_cache|\.ruff_cache|\.tox|__pycache__|migrations|\.egg-info|node_modules)/

plugins = pydantic.mypy

[mypy-cookiecutter.*]
ignore_missing_imports = true

[mypy-bijux_cli.core.di]
disable_error_code = type-abstract

[pydantic-mypy]
init_typed = true
warn_required_dynamic_aliases = true
warn_untyped_fields = true

{
  "include": [
    "../src/bijux_cli",
    "../tests"
  ],
  "extraPaths": [
    "../src",
    ".."
  ],
  "exclude": [
    ".venv",
    "build",
    "dist",
    "htmlcov",
    ".pytest_cache",
    ".mypy_cache",
    ".pytype",
    ".ruff_cache",
    ".tox",
    "**/__pycache__",
    "node_modules"
  ],
  "pythonVersion": "3.11",
  "typeCheckingMode": "strict",
  "useLibraryCodeForTypes": true,
  "reportMissingImports": "warning",
  "reportMissingTypeStubs": "none",
  "reportUnusedImport": "error",
  "reportPrivateUsage": "warning",
  "reportUnnecessaryTypeIgnoreComment": "warning",
  "reportUnnecessaryCast": "warning",
  "reportUnnecessaryIsInstance": "warning",
  "reportOptionalSubscript": "error",
  "reportOptionalMemberAccess": "error",
  "reportOptionalCall": "error",
  "reportOptionalIterable": "error",
  "reportOptionalContextManager": "error",
  "reportOptionalOperand": "error",
  "reportGeneralTypeIssues": "error",
  "reportUntypedClassDecorator": "error",
  "reportIncompatibleMethodOverride": "error",
  "reportUnknownVariableType": "none",
  "reportUnknownParameterType": "none",
  "reportUntypedFunctionDecorator": "none",
  "reportUnknownMemberType": "none",
  "reportUnknownArgumentType": "none",
  "reportUnknownLambdaType": "none",
  "reportUnusedVariable": "information",
  "reportMethodAssign": "none",
  "executionEnvironments": [
    {
      "root": ".",
      "extraPaths": [
        "src"
      ]
    }
  ]
}

[run]
branch = True
parallel = False
source = bijux_cli
data_file = artifacts/test/.coverage
omit =
    */.tox/*
    */.venv/*
    */site-packages/*

[report]
show_missing = True
skip_covered = False

[html]
directory = artifacts/test/htmlcov

[pytest]
minversion = 8.0
testpaths = tests
pythonpath = src

norecursedirs =
  .venv
  .tox
  .pytest_cache
  .ruff_cache
  .mypy_cache
  .hypothesis
  .benchmarks
  build
  dist
  htmlcov
  docs
  artifacts

cache_dir = artifacts/test/.pytest_cache

asyncio_mode = auto
timeout = 300
timeout_method = thread
timeout_func_only = true

addopts =
  -ra
  --strict-markers
  --tb=short
  --cov=bijux_cli
  --cov-branch
  --cov-config=config/coveragerc.ini
  --cov-report=term-missing:skip-covered
  --cov-report=html
  --cov-fail-under=98
#  --hypothesis-show-statistics

xfail_strict = true

markers =
  slow: mark test as slow (deselect with '-m "not slow"')
  windows: mark tests for Windows-only

filterwarnings =
  ignore:Not saving anything, no benchmarks have been run!
  ignore:jsonschema\.exceptions\.RefResolutionError is deprecated:DeprecationWarning
  ignore:.*forkpty.*:DeprecationWarning

[cosmic-ray]
python        = "python3.11"
test-command  = "pytest -q -x -k 'not slow' --tb=short --disable-warnings"
module-path   = ["src/bijux_cli"]
timeout       = 300.0

[cosmic-ray.distributor]
name              = "local"
worker-processes  = 4

[cosmic-ray.mutators]
enabled = [
  "arithmetic",
  "boolean",
  "comparison",
  "constant",
  "return-value",
]

[cosmic-ray.logging]
level   = "INFO"
file    = "artifacts/cosmic-ray.log"
format  = "plain"

# Security Configuration (no SBOM here; SBOM is handled in sbom.mk)

SECURITY_PATHS           ?= src/bijux_cli
BANDIT                   ?= $(if $(ACT),$(ACT)/bandit,bandit)
PIP_AUDIT                ?= $(if $(ACT),$(ACT)/pip-audit,pip-audit)
VENV_PYTHON              ?= $(if $(VIRTUAL_ENV),$(VIRTUAL_ENV)/bin/python,python)

SECURITY_REPORT_DIR      ?= artifacts/security
BANDIT_JSON              := $(SECURITY_REPORT_DIR)/bandit.json
BANDIT_TXT               := $(SECURITY_REPORT_DIR)/bandit.txt
PIPA_JSON                := $(SECURITY_REPORT_DIR)/pip-audit.json
PIPA_TXT                 := $(SECURITY_REPORT_DIR)/pip-audit.txt

SECURITY_IGNORE_IDS      ?= PYSEC-2022-42969
SECURITY_IGNORE_FLAGS     = $(foreach V,$(SECURITY_IGNORE_IDS),--ignore-vuln $(V))
PIP_AUDIT_CONSOLE_FLAGS  ?= --skip-editable --progress-spinner off
PIP_AUDIT_INPUTS         ?=
SECURITY_STRICT          ?= 1

BANDIT_EXCLUDES          ?= .venv,venv,build,dist,.tox,.mypy_cache,.pytest_cache
BANDIT_THREADS           ?= 0

.PHONY: security security-bandit security-audit security-clean

security: security-bandit security-audit

security-bandit:
    @mkdir -p "$(SECURITY_REPORT_DIR)"
    @echo "→ Bandit (Python static analysis)"
    @$(BANDIT) -r "$(SECURITY_PATHS)" -x "$(BANDIT_EXCLUDES)" -f json -o "$(BANDIT_JSON)" -n $(BANDIT_THREADS) || true
    @$(BANDIT) -r "$(SECURITY_PATHS)" -x "$(BANDIT_EXCLUDES)" -n $(BANDIT_THREADS) | tee "$(BANDIT_TXT)"

security-audit:
    @mkdir -p "$(SECURITY_REPORT_DIR)"
    @echo "→ Pip-audit (dependency vulnerability scan)"
    @set -e; RC=0; \
    $(PIP_AUDIT) $(SECURITY_IGNORE_FLAGS) $(PIP_AUDIT_CONSOLE_FLAGS) $(PIP_AUDIT_INPUTS) \
      -f json -o "$(PIPA_JSON)" >/dev/null 2>&1 || RC=$$?; \
    if [ $$RC -ne 0 ]; then \
      echo "!  pip-audit invocation failed (rc=$$RC)"; \
      if [ "$(SECURITY_STRICT)" = "1" ]; then exit $$RC; fi; \
    fi
    @set -o pipefail; \
    PIPA_JSON="$(PIPA_JSON)" \
    SECURITY_STRICT="$(SECURITY_STRICT)" \
    SECURITY_IGNORE_IDS="$(SECURITY_IGNORE_IDS)" \
    "$(VENV_PYTHON)" scripts/helper_pip_audit.py | tee "$(PIPA_TXT)"

security-clean:
    @rm -rf "$(SECURITY_REPORT_DIR)"

##@ Security
security:        ## Run Bandit and pip-audit; save reports to $(SECURITY_REPORT_DIR)
security-bandit: ## Run Bandit (screen + JSON artifact)
security-audit:  ## Run pip-audit (JSON once) and gate via scripts/helper_pip_audit.py; prints concise summary
security-clean:  ## Remove security reports

# SBOM Configuration (pip-audit → CycloneDX JSON)

PACKAGE_NAME        ?= bijux-cli
GIT_SHA             ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo unknown)

GIT_TAG_EXACT       := $(shell git describe --tags --exact-match 2>/dev/null | sed -E 's/^v//')
GIT_TAG_LATEST      := $(shell git describe --tags --abbrev=0 2>/dev/null | sed -E 's/^v//')

PYPROJECT_VERSION    = $(call read_pyproject_version)

PKG_VERSION         ?= $(if $(GIT_TAG_EXACT),$(GIT_TAG_EXACT),\
                           $(if $(PYPROJECT_VERSION),$(PYPROJECT_VERSION),\
                           $(if $(GIT_TAG_LATEST),$(GIT_TAG_LATEST),0.0.0)))

GIT_DESCRIBE        := $(shell git describe --tags --long --dirty --always 2>/dev/null)
PKG_VERSION_FULL    := $(if $(GIT_TAG_EXACT),$(PKG_VERSION),\
                          $(shell echo "$(GIT_DESCRIBE)" \
                            | sed -E 's/^v//; s/-([0-9]+)-g([0-9a-f]+)(-dirty)?$$/+\\1.g\\2\\3/'))

SBOM_VERSION        := $(if $(PKG_VERSION_FULL),$(PKG_VERSION_FULL),$(PKG_VERSION))

SBOM_DIR            ?= artifacts/sbom
SBOM_PROD_REQ       ?= requirements/prod.txt
SBOM_DEV_REQ        ?= requirements/dev.txt
SBOM_FORMAT         ?= cyclonedx-json            # pip-audit format
SBOM_CLI            ?= cyclonedx                 # cyclonedx-cli for validation
SBOM_IGNORE_IDS     ?= PYSEC-2022-42969
SBOM_IGNORE_FLAGS    = $(foreach V,$(SBOM_IGNORE_IDS),--ignore-vuln $(V))

PIP_AUDIT           := $(if $(ACT),$(ACT)/pip-audit,pip-audit)
PIP_AUDIT_FLAGS      = --progress-spinner off --format $(SBOM_FORMAT)

SBOM_PROD_FILE      := $(SBOM_DIR)/$(PACKAGE_NAME)-$(SBOM_VERSION)-$(GIT_SHA).prod.cdx.json
SBOM_DEV_FILE       := $(SBOM_DIR)/$(PACKAGE_NAME)-$(SBOM_VERSION)-$(GIT_SHA).dev.cdx.json

.PHONY: sbom sbom-prod sbom-dev sbom-validate sbom-summary sbom-clean

sbom: sbom-clean sbom-prod sbom-dev sbom-summary
    @echo "✔ SBOMs generated in $(SBOM_DIR)"

sbom-prod:
    @mkdir -p "$(SBOM_DIR)"
    @if [ -s "$(SBOM_PROD_REQ)" ]; then \
      echo "→ SBOM (prod via $(SBOM_PROD_REQ))"; \
      $(PIP_AUDIT) $(PIP_AUDIT_FLAGS) $(SBOM_IGNORE_FLAGS) \
        -r "$(SBOM_PROD_REQ)" --output "$(SBOM_PROD_FILE)" || true; \
    else \
      echo "→ SBOM (prod fallback: current venv)"; \
      $(PIP_AUDIT) $(PIP_AUDIT_FLAGS) $(SBOM_IGNORE_FLAGS) \
        --output "$(SBOM_PROD_FILE)" || true; \
    fi

sbom-dev:
    @mkdir -p "$(SBOM_DIR)"
    @if [ -s "$(SBOM_DEV_REQ)" ]; then \
      echo "→ SBOM (dev via $(SBOM_DEV_REQ))"; \
      $(PIP_AUDIT) $(PIP_AUDIT_FLAGS) $(SBOM_IGNORE_FLAGS) \
        -r "$(SBOM_DEV_REQ)" --output "$(SBOM_DEV_FILE)" || true; \
    else \
      echo "→ SBOM (dev fallback: current venv)"; \
      $(PIP_AUDIT) $(PIP_AUDIT_FLAGS) $(SBOM_IGNORE_FLAGS) \
        --output "$(SBOM_DEV_FILE)" || true; \
    fi

sbom-validate:
    @if [ -z "$(SBOM_CLI)" ]; then echo "✘ SBOM_CLI not set"; exit 1; fi
    @command -v $(SBOM_CLI) >/dev/null 2>&1 || { echo "✘ '$(SBOM_CLI)' not found. Install it or set SBOM_CLI."; exit 1; }
    @if ! find "$(SBOM_DIR)" -maxdepth 1 -name '*.cdx.json' -print -quit | grep -q .; then \
      echo "✘ No SBOM files in $(SBOM_DIR)"; exit 1; \
    fi
    @for f in "$(SBOM_DIR)"/*.cdx.json; do \
      echo "→ Validating $$f"; \
      $(SBOM_CLI) validate --input-format json --input-file "$$f"; \
    done

sbom-summary:
    @mkdir -p "$(SBOM_DIR)"
    @if ! find "$(SBOM_DIR)" -maxdepth 1 -name '*.cdx.json' -print -quit | grep -q .; then \
      echo "→ No SBOM files found in $(SBOM_DIR); skipping summary"; \
      exit 0; \
    fi
    @echo "→ Writing SBOM summary"
    @summary="$(SBOM_DIR)/summary.txt"; : > "$$summary"; \
    if command -v jq >/dev/null 2>&1; then \
      for f in "$(SBOM_DIR)"/*.cdx.json; do \
        comps=$$(jq -r '(.components|length) // 0' "$$f"); \
        echo "$$(basename "$$f")  components=$$comps" >> "$$summary"; \
      done; \
    else \
      tmp="$(SBOM_DIR)/_sbom_summary.py"; \
      echo "import glob, json, os"                                  >  "$$tmp"; \
      echo "sbom_dir = r'$(SBOM_DIR)'"                              >> "$$tmp"; \
      echo "for f in glob.glob(os.path.join(sbom_dir, '*.cdx.json')):" >> "$$tmp"; \
      echo "    try:"                                               >> "$$tmp"; \
      echo "        with open(f, 'r', encoding='utf-8') as fh:"     >> "$$tmp"; \
      echo "            d = json.load(fh)"                          >> "$$tmp"; \
      echo "        comps = len(d.get('components', []) or [])"     >> "$$tmp"; \
      echo "    except Exception:"                                  >> "$$tmp"; \
      echo "        comps = '?'"                                    >> "$$tmp"; \
      echo "    print(os.path.basename(f) + '  components=' + str(comps))" >> "$$tmp"; \
      python3 "$$tmp" >> "$$summary" || true; \
      rm -f "$$tmp"; \
    fi; \
    sed -n '1,5p' "$$summary" 2>/dev/null || true

sbom-clean:
    @echo "→ Cleaning SBOM artifacts"
    @mkdir -p "$(SBOM_DIR)"
    @rm -f \
      "$(SBOM_DIR)/$(PACKAGE_NAME)-0.0.0-"*.cdx.json \
      "$(SBOM_DIR)/$(PACKAGE_NAME)--"*.cdx.json || true

##@ SBOM
sbom:           ## Generate SBOMs for prod/dev (pip-audit → CycloneDX JSON) and a short summary
sbom-validate:  ## Validate all generated SBOMs with CycloneDX CLI
sbom-summary:   ## Write a brief components summary to $(SBOM_DIR)/summary.txt (best-effort)
sbom-clean:     ## Remove stale SBOM artifacts from $(SBOM_DIR)

version = 1

# Config/docs/assets: public domain
[[annotations]]
path = [
  "**/*.png", "**/*.svg", "**/*.ico", "**/*.gif", "**/*.jpg", "**/*.jpeg",
  "**/*.html", "**/*.toml", "**/*.ini", "**/*.cfg", "**/*.conf",
  "**/*.env", "**/*.env.*", "**/*.yaml", "**/*.yml", "**/*.json",
  "**/*.cff", "**/*.dic", ".coverage*", ".gitattributes", ".gitignore",
  "changelog.d/**", "**/.editorconfig", "artifacts/**", "scripts/git-hooks/**",
  "docs/assets/styles/**"
]
precedence = "override"
SPDX-License-Identifier = "CC0-1.0"
SPDX-FileCopyrightText = "© 2025 Bijan Mousavi"

# Templates: public domain
[[annotations]]
path = ["plugin_template/**"]
precedence = "override"
SPDX-License-Identifier = "CC0-1.0"
SPDX-FileCopyrightText = "© 2025 Bijan Mousavi"

# Code: MIT
[[annotations]]
path = ["**/*.py", "**/*.pyi", "**/*.sh", "**/*.mk", "Makefile", "Dockerfile", "Dockerfile.*"]
precedence = "closest"
SPDX-License-Identifier = "MIT"
SPDX-FileCopyrightText = "© 2025 Bijan Mousavi"

# Markdown docs: MIT
[[annotations]]
path = ["**/*.md"]
precedence = "closest"
SPDX-License-Identifier = "MIT"
SPDX-FileCopyrightText = "© 2025 Bijan Mousavi"

site_name: Bijux CLI
site_description: A modern, predictable Python CLI framework with plugins, DI, strict flag precedence, and an interactive REPL.
site_url: !ENV [SITE_URL, https://bijux.github.io/bijux-cli/]
site_author: Bijan Mousavi
repo_url: https://github.com/bijux/bijux-cli
repo_name: bijux/bijux-cli
edit_uri: ""

strict: true
use_directory_urls: true
dev_addr: 127.0.0.1:8000
docs_dir: artifacts/docs/docs
site_dir: artifacts/docs/site

theme:
  name: material
  custom_dir: docs/overrides
  logo: assets/bijux_logo_hq.png
  favicon: assets/bijux_icon.png
  font:
    text: Roboto
    code: Roboto Mono
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/toggle-switch-off-outline
        name: Switch to dark mode
    - scheme: slate
      primary: teal
      accent: lime
      toggle:
        icon: material/toggle-switch
        name: Switch to light mode
  features:
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.sections
    - navigation.indexes
    - navigation.top
    - navigation.path
    - navigation.tracking
    - navigation.instant
    - toc.follow
    - search.suggest
    - search.highlight
    - content.tabs.link
    - content.code.annotate
    - content.code.copy
    - content.code.select
    - content.action.edit
    - content.action.view
    - navigation.footer
  icon:
    repo: fontawesome/brands/github

plugins:
  - gen-files:
      scripts:
        - scripts/docs_builder/mkdocs_manager.py

  - literate-nav:
      nav_file: nav.md

  - include-markdown:
      recursive: true
      dedent: true
      preserve_includer_indent: false
      trailing_newlines: true
      comments: false
      rewrite_relative_urls: true

  - mkdocstrings:
      handlers:
        python:
          paths: [src]
          options:
            docstring_style: google
            docstring_section_style: list
            merge_init_into_class: true
            show_source: true
            show_if_no_docstring: false
            show_root_heading: true
            heading_level: 2
            separate_signature: true
            signature_crossrefs: true
            filters: ["!^_"]

  - search
  - social:
      enabled: !ENV [ENABLE_SOCIAL_CARDS, false]
      cache_dir: artifacts/docs/.cache/social
  - autorefs
  - redirects: {}
  - tags
  - minify:
      minify_html: true
      minify_js: true
      minify_css: true
  - glightbox:
      touchNavigation: true
      loop: false
      effect: zoom

markdown_extensions:
  - admonition
  - footnotes
  - attr_list
  - md_in_html
  - toc:
      permalink: true
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets:
      base_path:
        - .
        - docs
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.mark
  - pymdownx.magiclink
  - pymdownx.tasklist
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.keys
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg


extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/bijux/bijux-cli
    - icon: fontawesome/brands/python
      link: https://pypi.org/project/bijux-cli/
  analytics:
    provider: plausible
    domain: bijux.github.io
  copyright:
    text: "© 2025 Bijan Mousavi"
  release_tag: !ENV [RELEASE_TAG, "main"]

extra_css:
  - assets/styles/extra.css

extra_javascript:
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

watch:
  - artifacts
  - src
  - scripts
  - config
  - tests
  - changelog.d

# SPDX-License-Identifier: MIT
# Copyright © 2025 Bijan Mousavi

"""Main build manager for generating the MkDocs documentation site.

This script serves as the entrypoint for the `mkdocs-gen-files` plugin. It
orchestrates the entire documentation generation process, including:
- Materializing top-level project Markdown files (e.g., README, USAGE).
- Finding and processing Architecture Decision Records (ADRs).
- Generating API reference documentation from Python source files using
  `mkdocstrings`.
- Creating index pages for all documentation sections.
- Building detailed pages for CI/CD artifacts (linting, testing, etc.).
- Composing a complete `nav.md` file for the `literate-nav` plugin to
  construct the site navigation.
"""

from __future__ import annotations

import os
import sys
from pathlib import Path
from typing import Dict
from typing import List
from typing import Optional
from typing import Tuple
from typing import Callable

sys.path.insert(0, str(Path(__file__).resolve().parents[2]))

from scripts.docs_builder.artifacts_pages.api_page import APIArtifactPage
from scripts.docs_builder.artifacts_pages.citation_page import CitationArtifactPage
from scripts.docs_builder.artifacts_pages.lint_page import LintArtifactPage
from scripts.docs_builder.artifacts_pages.quality_page import QualityArtifactPage
from scripts.docs_builder.artifacts_pages.sbom_page import SBOMArtifactPage
from scripts.docs_builder.artifacts_pages.security_page import SecurityArtifactPage
from scripts.docs_builder.artifacts_pages.test_page import TestArtifactPage
from scripts.docs_builder.helpers import INDENT1
from scripts.docs_builder.helpers import INDENT2
from scripts.docs_builder.helpers import INDENT3
from scripts.docs_builder.helpers import NAV_FILE
from scripts.docs_builder.helpers import REPO_ROOT
from scripts.docs_builder.helpers import SRC_DIR
from scripts.docs_builder.helpers import ensure_top_anchor
from scripts.docs_builder.helpers import final_fixups
from scripts.docs_builder.helpers import fs_read_text
from scripts.docs_builder.helpers import nav_add_bullets
from scripts.docs_builder.helpers import nav_header
from scripts.docs_builder.helpers import pretty_title
from scripts.docs_builder.helpers import rewrite_links_general
from scripts.docs_builder.helpers import rewrite_links_tree
from scripts.docs_builder.helpers import write_if_changed

ADR_SRC_PRIMARY = REPO_ROOT / "ADR"
ADR_SRC_FALLBACK = REPO_ROOT / "docs" / "ADR"
ADR_DEST_DIR = Path("ADR")

PAGE_META_NO_EDIT = (
    "---\nhide:\n  - edit\n---\n\n"
)

def _pick_adr_source() -> Optional[Path]:
    """Selects the source directory for Architecture Decision Records (ADRs).

    It prefers the top-level `ADR/` directory. If that does not exist, it
    falls back to `docs/ADR/`.

    Returns:
        The path to the ADR source directory, or None if neither exists.
    """
    if ADR_SRC_PRIMARY.is_dir():
        return ADR_SRC_PRIMARY
    if ADR_SRC_FALLBACK.is_dir():
        return ADR_SRC_FALLBACK
    return None


def _iter_adr_files(src_root: Path) -> List[Path]:
    """Lists all ADR Markdown files in a directory, sorted by name.

    It excludes any `index.md` file from the list.

    Args:
        src_root: The directory to search for ADR files.

    Returns:
        A sorted list of paths to the ADR files.
    """
    return sorted(
        [p for p in src_root.glob("*.md") if p.is_file() and p.name != "index.md"],
        key=lambda p: p.name,
    )


def _adr_display_name(filename: str) -> str:
    """Formats a user-friendly title from an ADR filename.

    For example, "0001-some-decision.md" becomes "ADR 0001: Some Decision".

    Args:
        filename: The name of the ADR file.

    Returns:
        A formatted, human-readable title string.
    """
    stem = filename[:-3]
    parts = stem.split("-", 1)
    if len(parts) == 2 and parts[0].isdigit():
        adr_num, title_raw = parts
        return f"ADR {adr_num.zfill(4)}: {title_raw.replace('-', ' ').title()}"
    return stem.replace("-", " ").title()


def _materialize_root_docs() -> None:
    """Copy key project files into the docs site; create fallbacks if absent."""
    pairs: List[Tuple[Path, Path, Callable[[str], str]]] = [
        (REPO_ROOT / "README.md",         Path("index.md"),        rewrite_links_general),
        (REPO_ROOT / "USAGE.md",          Path("usage.md"),        rewrite_links_general),
        (REPO_ROOT / "TESTS.md",          Path("tests.md"),        rewrite_links_general),
        (REPO_ROOT / "PROJECT_TREE.md",   Path("project_tree.md"), rewrite_links_tree),
        (REPO_ROOT / "TOOLING.md",        Path("tooling.md"),      rewrite_links_general),
        (REPO_ROOT / "SECURITY.md",       Path("security.md"),     rewrite_links_general),
        (REPO_ROOT / "CODE_OF_CONDUCT.md",Path("code_of_conduct.md"), rewrite_links_general),
        (REPO_ROOT / "CONTRIBUTING.md",   Path("contributing.md"), rewrite_links_general),
        (REPO_ROOT / "CHANGELOG.md",      Path("changelog.md"),    rewrite_links_general),
        (REPO_ROOT / "LICENSES" / "MIT.txt", Path("license.md"),   rewrite_links_general),
    ]
    have_index = False
    for src, dst, fixer in pairs:
        if not src.exists():
            continue
        raw = fs_read_text(src)
        md = ensure_top_anchor(fixer(raw))
        md = final_fixups(md)
        md = PAGE_META_NO_EDIT + md
        write_if_changed(dst, md)
        if dst.as_posix() == "index.md":
            have_index = True

    if not have_index:
        fallback = PAGE_META_NO_EDIT + (
            "# Bijux CLI {#top}\n\n"
            "_Auto-generated skeleton page._\n\n"
            "- [API Reference](reference/index.md)\n"
            "- [Artifacts](artifacts/index.md)\n"
            "- [Architecture Decision Records](ADR/index.md)\n"
        )
        write_if_changed("index.md", fallback)


def _materialize_adrs() -> None:
    """Copies ADRs from the source directory into the virtual docs filesystem.

    This step is skipped if the ADRs are already located in the on-disk
    `docs/ADR/` directory, as `mkdocs-gen-files` will pick them up automatically.
    """
    src_root = _pick_adr_source()
    if not src_root or src_root == ADR_SRC_FALLBACK:
        return

    for src in _iter_adr_files(src_root):
        dst = ADR_DEST_DIR / src.name
        raw = fs_read_text(src)
        md = ensure_top_anchor(rewrite_links_general(raw))
        md = final_fixups(md)
        md = PAGE_META_NO_EDIT + md
        write_if_changed(dst, md)


def _generate_adr_index() -> None:
    """Generates the `ADR/index.md` file in the virtual docs filesystem.

    This ensures a correct and up-to-date index is always available,
    regardless of whether an index file exists in the source directory.
    """
    src_root = _pick_adr_source()
    if not src_root:
        return
    files = _iter_adr_files(src_root)
    if not files:
        return

    lines = [PAGE_META_NO_EDIT, "# Architecture Decision Records {#top}\n\n"]
    for p in files:
        lines.append(f"- [{_adr_display_name(p.name)}](./{p.name})\n")
    write_if_changed(ADR_DEST_DIR / "index.md", "".join(lines))


def _generate_api_pages() -> Dict[str, List[Tuple[str, str]]]:
    """Walks the source directory and generates API reference pages.

    For each Python module found in the `SRC_DIR`, this function creates a
    corresponding Markdown file in the `reference/` virtual directory. The
    content of each file is a `mkdocstrings` block configured to render the
    API documentation for that module.

    Returns:
        A dictionary mapping each reference subdirectory to a list of pages
        it contains. Each page is a tuple of (display_name, path). This
        structure is used to build index pages and the site navigation.
    """
    ref_dir_to_pages: Dict[str, List[Tuple[str, str]]] = {}
    for root, _, files in os.walk(SRC_DIR):
        rel_root = os.path.relpath(root, SRC_DIR)
        section = None if rel_root == "." else rel_root
        for file in files:
            if not file.endswith(".py") or file.startswith("__") or file == "py.typed":
                continue

            module_name = file[:-3]
            raw_md_path = os.path.join("reference", rel_root, f"{module_name}.md")
            md_path = os.path.normpath(raw_md_path).replace("\\", "/")
            is_command = (section or "").split(os.sep, 1)[0] == "commands"

            header = f"# {module_name.capitalize()} Command API Reference\n" if is_command else f"# {module_name.capitalize()} Module API Reference\n"
            blurb = f"This section documents the internals of the `{module_name}` command in Bijux CLI.\n" if is_command else f"This section documents the internals of the `{module_name}` module in Bijux CLI.\n"
            full_module_path = f"bijux_cli.{module_name}" if section is None else f"bijux_cli.{section.replace(os.sep, '.')}.{module_name}"
            content = (
                PAGE_META_NO_EDIT
                + header
                + blurb
                + f"::: {full_module_path}\n"
                + "    handler: python\n"
                + "    options:\n"
                + "      show_root_heading: true\n"
                + "      show_source: true\n"
                + "      show_signature_annotations: true\n"
                + "      docstring_style: google\n"
            )
            write_if_changed(Path(md_path), content)

            label = "Command" if is_command else "Module"
            display_name = f"{pretty_title(Path(md_path).stem)} {label}"
            ref_dir = os.path.dirname(md_path) or "reference"
            ref_dir_to_pages.setdefault(ref_dir, []).append((display_name, md_path))
    return ref_dir_to_pages


def _write_reference_indexes(ref_dir_to_pages: Dict[str, List[Tuple[str, str]]]) -> set[str]:
    """Creates `index.md` files for all API reference directories.

    Args:
        ref_dir_to_pages: The mapping of directories to pages from `_generate_api_pages`.

    Returns:
        A set of all directory paths within the API reference section.
    """
    all_dirs: set[str] = {"reference"}
    for ref_dir in ref_dir_to_pages:
        parts = ref_dir.split("/")
        for i in range(1, len(parts) + 1):
            all_dirs.add("/".join(parts[:i]))

    for ref_dir in sorted(all_dirs):
        title = ref_dir.replace("reference", "Reference").strip("/").replace("/", " / ") or "Reference"
        lines = [PAGE_META_NO_EDIT, f"# {title.title()} Index\n\n"]
        for display_name, md_link in sorted(ref_dir_to_pages.get(ref_dir, []), key=lambda x: x[0].lower()):
            lines.append(f"- [{display_name}]({Path(md_link).name})\n")
        write_if_changed(Path(ref_dir) / "index.md", "".join(lines))
    return all_dirs


def _compose_nav(ref_dir_to_pages: Dict[str, List[Tuple[str, str]]], all_dirs: set[str]) -> None:
    """Programmatically composes the entire site navigation in `nav.md`.

    This function builds a Markdown list that `mkdocs-literate-nav` uses to
    create the site's navigation tree. The structure is highly ordered and
    builds several main sections, including top-level pages, a nested API
    Reference section, ADRs, and artifact reports.

    Args:
        ref_dir_to_pages: The mapping of reference directories to pages.
        all_dirs: A set of all reference directories that exist.
    """
    nav = nav_header()
    nav = nav_add_bullets(
        nav,
        [
            "* [Home](index.md)",
            "* [Usage](usage.md)",
            "* [Project Overview](project_tree.md)",
            "* [Tests](tests.md)",
            "* [Tooling](tooling.md)",
            "* API Reference",
            f"{INDENT1}* [Index](reference/index.md)",
        ],
    )

    root_pages = ref_dir_to_pages.get("reference", [])
    root_by_stem = {Path(p).stem.lower(): (name, p) for name, p in root_pages}
    for stem in ("api", "cli", "httpapi"):
        if stem in root_by_stem:
            name, p = root_by_stem.pop(stem)
            nav = nav_add_bullets(nav, [f"{INDENT1}* [{name}]({p})"])
    for name, p in sorted(root_by_stem.values(), key=lambda x: x[0].lower()):
        nav = nav_add_bullets(nav, [f"{INDENT1}* [{name}]({p})"])

    SECTION_ORDER = ("commands", "contracts", "core", "infra", "services")
    section_dirs = [f"reference/{s}" for s in SECTION_ORDER if f"reference/{s}" in all_dirs]

    for section_dir in section_dirs:
        section_name = section_dir.split("/", 1)[1].capitalize()
        nav = nav_add_bullets(nav, [f"{INDENT1}* {section_name}", f"{INDENT2}* [Index]({section_dir}/index.md)"])
        pages_here = sorted(ref_dir_to_pages.get(section_dir, []), key=lambda x: x[0].lower())
        if pages_here:
            bucket = "Commands" if section_dir.endswith("/commands") else "Modules"
            nav = nav_add_bullets(nav, [f"{INDENT2}* {bucket}"])
            for display_name, md_link in pages_here:
                nav = nav_add_bullets(nav, [f"{INDENT3}* [{display_name}]({md_link})"])

        subdirs = sorted(d for d in all_dirs if d.startswith(section_dir + "/"))
        seen = {section_dir}
        for sub_dir in subdirs:
            if sub_dir in seen:
                continue
            seen.add(sub_dir)
            subgroup_title = pretty_title(Path(sub_dir).name)
            nav = nav_add_bullets(nav, [f"{INDENT2}* {subgroup_title}", f"{INDENT3}* [Index]({sub_dir}/index.md)"])
            for display_name, md_link in sorted(ref_dir_to_pages.get(sub_dir, []), key=lambda x: x[0].lower()):
                nav = nav_add_bullets(nav, [f"{INDENT3}* [{display_name}]({md_link})"])

    src_root = _pick_adr_source()
    if src_root and (files := _iter_adr_files(src_root)):
        nav = nav_add_bullets(nav, ["* Architecture", f"{INDENT1}* [Decision Records](ADR/index.md)"])
        for p in files:
            nav = nav_add_bullets(nav, [f"{INDENT2}* [{_adr_display_name(p.name)}](ADR/{p.name})"])

    nav = nav_add_bullets(nav, ["* [Changelog](changelog.md)"])

    community_pages = [
        ("Code of Conduct", "code_of_conduct.md"),
        ("Contributing", "contributing.md"),
        ("Security Policy", "security.md"),
        ("License", "license.md"),
    ]
    landing = [PAGE_META_NO_EDIT, "# Community {#top}\n\n",
               "Project policies and how to get involved.\n\n"]
    for title, path in community_pages:
        landing.append(f"- [{title}]({path})\n")
    write_if_changed(Path("community.md"), "".join(landing))
    nav = nav_add_bullets(nav, ["* [Community](community.md)"])
    for title, path in community_pages:
        nav = nav_add_bullets(nav, [f"{INDENT1}* [{title}]({path})"])

    artifacts = [
        ("Test Artifacts", "artifacts/test.md"),
        ("Lint Artifacts", "artifacts/lint.md"),
        ("Quality Artifacts", "artifacts/quality.md"),
        ("Security Artifacts", "artifacts/security.md"),
        ("API Artifacts", "artifacts/api.md"),
        ("SBOM Artifacts", "artifacts/sbom.md"),
        ("Citation Artifacts", "artifacts/citation.md")
    ]
    landing = [PAGE_META_NO_EDIT, "# Artifacts {#top}\n\n",
                    "Collected CI/test reports and logs.\n\n"]
    for title, path in artifacts:
        landing.append(f"- [{title}]({Path(path).name})\n")
    write_if_changed(Path("artifacts/index.md"), "".join(landing))

    nav = nav_add_bullets(nav, ["* [Artifacts](artifacts/index.md)"])
    for title, path in artifacts:
        nav = nav_add_bullets(nav, [f"{INDENT1}* [{title}]({path})"])

    write_if_changed(NAV_FILE, nav)


def main() -> None:
    """The main entrypoint for the documentation generation script.

    Orchestrates the entire build process by calling functions in sequence to:
    1. Materialize root documentation files.
    2. Materialize and index ADRs.
    3. Generate API reference pages and their indexes.
    4. Build all artifact-specific documentation pages.
    5. Compose the final site navigation file.
    """
    _materialize_root_docs()
    _materialize_adrs()
    ref = _generate_api_pages()
    print(f"[docs] generated {sum(len(v) for v in ref.values())} reference pages")
    dirs = _write_reference_indexes(ref)
    _generate_adr_index()
    TestArtifactPage().build()
    LintArtifactPage().build()
    QualityArtifactPage().build()
    SecurityArtifactPage().build()
    APIArtifactPage().build()
    SBOMArtifactPage().build()
    CitationArtifactPage().build()
    _compose_nav(ref, dirs)


if __name__ == "__main__":
    main()

# API configuration — organized, zero root pollution

# ── Server / app
SHELL                 := /bin/bash
APP_DIR               ?= src
API_HOST              ?= 127.0.0.1
API_PORT              ?= 8000
API_BASE_PATH         ?= /v1
API_APP               ?= app
API_MODULE            ?= bijux_cli.httpapi
API_FACTORY           ?=
API_WAIT_SECS         ?= 30
HEALTH_PATH           ?= /health
SCHEMA_URL            ?= http://$(API_HOST):$(API_PORT)

# Workaround for older Schemathesis versions that may hang after successful test completion.
SCHEMATHESIS_TIMEOUT  ?= 30

# ── Artifacts
API_ARTIFACTS_DIR     ?= artifacts/api
API_LOG               ?= $(API_ARTIFACTS_DIR)/server.log
API_LINT_DIR          ?= $(API_ARTIFACTS_DIR)/lint
API_TEST_DIR          ?= $(API_ARTIFACTS_DIR)/test
SCHEMA_BUNDLE_DIR     ?= $(API_ARTIFACTS_DIR)/schemas
HYPOTHESIS_DB_API     ?= $(API_TEST_DIR)/hypothesis

SCHEMATHESIS_JUNIT    ?= $(API_TEST_DIR)/schemathesis.xml
SCHEMATHESIS_JUNIT_ABS  := $(abspath $(SCHEMATHESIS_JUNIT))

# ── Node tool sandbox (no root pollution)
API_NODE_DIR          ?= $(API_ARTIFACTS_DIR)/node
OPENAPI_GENERATOR_VERSION ?= 7.14.0

# Find schemas
ALL_API_SCHEMAS       := $(shell find api -type f \( -name '*.yaml' -o -name '*.yml' \))
ALL_API_SCHEMAS_ABS   := $(abspath $(ALL_API_SCHEMAS))

# Python CLIs (prefer ACT if present)
PRANCE                  := $(ACT)/prance
OPENAPI_SPEC_VALIDATOR  := $(ACT)/openapi-spec-validator
SCHEMATHESIS            := $(ACT)/schemathesis
SCHEMATHESIS_OPTS ?= \
  --checks=all --max-failures=1 \
  --report junit --report-junit-path $(SCHEMATHESIS_JUNIT_ABS) \
  --request-timeout=5 --max-response-time=3 \
  --max-examples=50 --seed=1 --generation-deterministic --exclude-checks=positive_data_acceptance \
  --suppress-health-check=filter_too_much


# ── Absolute paths (safe if recipe cd's)
API_ARTIFACTS_DIR_ABS   := $(abspath $(API_ARTIFACTS_DIR))
API_LINT_DIR_ABS        := $(abspath $(API_LINT_DIR))
API_TEST_DIR_ABS        := $(abspath $(API_TEST_DIR))
SCHEMA_BUNDLE_DIR_ABS   := $(abspath $(SCHEMA_BUNDLE_DIR))
API_LOG_ABS             := $(abspath $(API_LOG))
API_NODE_DIR_ABS        := $(abspath $(API_NODE_DIR))
HYPOTHESIS_DB_API_ABS   := $(abspath $(HYPOTHESIS_DB_API))
REDOCLY_ABS             := $(API_NODE_DIR_ABS)/node_modules/.bin/redocly
OPENAPI_GENERATOR_ABS   := $(API_NODE_DIR_ABS)/node_modules/.bin/openapi-generator-cli

# ── Uvicorn runner (force import from src/; tolerate unset PYTHONPATH)
ifneq ($(strip $(API_FACTORY)),)
API_CMD ?= PYTHONPATH="$(APP_DIR)$${PYTHONPATH:+:$$PYTHONPATH}" \
  $(VENV_PYTHON) -c 'import sys, importlib, uvicorn; \
sys.path.insert(0,"$(APP_DIR)"); \
m=importlib.import_module("$(API_MODULE)"); \
app=getattr(m,"$(API_FACTORY)")(); \
uvicorn.run(app, host="$(API_HOST)", port=$(API_PORT))'
else
API_CMD ?= PYTHONPATH="$(APP_DIR)$${PYTHONPATH:+:$$PYTHONPATH}" \
  $(VENV_PYTHON) -m uvicorn --app-dir "$(APP_DIR)" \
  $(API_MODULE):$(API_APP) --host $(API_HOST) --port $(API_PORT)
endif

# ── Macro: validate one schema (use ABS CLI paths, no cd)
define VALIDATE_ONE_SCHEMA
  @mkdir -p "$(API_LINT_DIR_ABS)"
  @b="$$(basename "$(1)")"; \
  in_abs="$(abspath $(1))"; \
  log="$(API_LINT_DIR_ABS)/$${b}.log"; \
  echo "→ Validating: $(1)"; \
  { \
    $(PRANCE) validate "$$in_abs"; \
    $(OPENAPI_SPEC_VALIDATOR) "$$in_abs"; \
    "$(REDOCLY_ABS)" lint "$$in_abs"; \
    NODE_NO_WARNINGS=1 "$(OPENAPI_GENERATOR_ABS)" validate -i "$$in_abs"; \
  } 2>&1 | tee "$$log"
endef

.PHONY: api api-install api-lint api-test api-serve api-serve-bg api-stop api-clean node_deps node_bootstrap

## Orchestrator
api: api-install api-lint api-test

# ── Install toolchain (Python + Node sandbox)
api-install: | $(VENV) node_deps
    @echo "→ Installing API Python deps..."
    @command -v curl >/dev/null || { echo "✘ curl not found"; exit 1; }
    @command -v java >/dev/null || { echo "✘ java not found"; exit 1; }
    @$(VENV_PYTHON) -m pip install --quiet --upgrade prance openapi-spec-validator uvicorn schemathesis
    @echo "✔ API toolchain ready."

api-lint: | node_deps
    @if [ -z "$(ALL_API_SCHEMAS)" ]; then echo "✘ No API schemas found under api/*.y*ml"; exit 1; fi
    @echo "→ Linting OpenAPI specs..."
    $(foreach s,$(ALL_API_SCHEMAS),$(call VALIDATE_ONE_SCHEMA,$(s)))
    @[ -f ./openapitools.json ] && echo "→ Removing stray openapitools.json (root)" && rm -f ./openapitools.json || true
    @echo "✔ All schemas validated. Logs → $(API_LINT_DIR_ABS)"

# ── Start server, wait for readiness, run Schemathesis (sandboxed Hypothesis DB), stop server
api-test: | $(VENV) node_deps
    @if [ -z "$(ALL_API_SCHEMAS)" ]; then echo "✘ No API schemas found under api/*.y*ml"; exit 1; fi
    @mkdir -p "$(API_ARTIFACTS_DIR_ABS)" "$(API_TEST_DIR_ABS)"
    @echo "→ Starting API server"
    @script="$(API_ARTIFACTS_DIR_ABS)/run_api_test.sh"; \
      rm -f "$$script"; \
      echo '#!/usr/bin/env bash' >> "$$script"; \
      echo 'set -euo pipefail' >> "$$script"; \
      echo 'echo "→ Starting API server"' >> "$$script"; \
      echo '$(API_CMD) >"$(API_LOG_ABS)" 2>&1 & PID=$$!' >> "$$script"; \
      echo 'echo $$PID >"$(API_ARTIFACTS_DIR_ABS)/server.pid"' >> "$$script"; \
      echo 'cleanup(){ kill $$PID >/dev/null 2>&1 || true; wait $$PID >/dev/null 2>&1 || true; }' >> "$$script"; \
      echo 'trap cleanup EXIT INT TERM' >> "$$script"; \
      echo 'echo "→ Waiting up to $(API_WAIT_SECS)s for readiness @ $(SCHEMA_URL)$(HEALTH_PATH)"' >> "$$script"; \
      echo 'READY=' >> "$$script"; \
      echo 'for i in $$(seq 1 $(API_WAIT_SECS)); do' >> "$$script"; \
      echo '  if curl -fsS "$(SCHEMA_URL)$(HEALTH_PATH)" >/dev/null 2>&1; then READY=1; break; fi' >> "$$script"; \
      echo '  sleep 1' >> "$$script"; \
      echo '  if ! kill -0 $$PID >/dev/null 2>&1; then echo "✘ API crashed — see $(API_LOG_ABS)"; exit 1; fi' >> "$$script"; \
      echo 'done' >> "$$script"; \
      echo 'if [ -z "$$READY" ]; then echo "✘ API did not become ready in $(API_WAIT_SECS)s — see $(API_LOG_ABS)"; exit 1; fi' >> "$$script"; \
      echo 'BASE_FLAG=$$($(SCHEMATHESIS) run -h 2>&1 | grep -q " --url " && echo --url || echo --base-url)' >> "$$script"; \
      echo 'STATEFUL_ARGS=""' >> "$$script"; \
      echo 'if $(SCHEMATHESIS) run -h 2>&1 | grep -q " --stateful"; then STATEFUL_ARGS="--stateful=links"; else echo "↪︎ Schemathesis: --stateful not supported; skipping"; fi' >> "$$script"; \
      echo 'LOG="$(API_TEST_DIR_ABS)/schemathesis.log"; : > "$$LOG"' >> "$$script"; \
      echo 'BUF=""; command -v stdbuf >/dev/null 2>&1 && BUF="stdbuf -oL -eL"' >> "$$script"; \
      echo 'TO=""' >> "$$script"; \
      echo 'if [ "$(SCHEMATHESIS_TIMEOUT)" -gt 0 ] 2>/dev/null; then' >> "$$script"; \
      echo '  if command -v gtimeout >/dev/null 2>&1; then TO="gtimeout --kill-after=10 $(SCHEMATHESIS_TIMEOUT)";' >> "$$script"; \
      echo '  elif command -v timeout >/dev/null 2>&1; then TO="timeout --kill-after=10 $(SCHEMATHESIS_TIMEOUT)";' >> "$$script"; \
      echo '  fi' >> "$$script"; \
      echo 'fi' >> "$$script"; \
      echo 'if [ -n "$$TO" ]; then echo "↪︎ Using timeout wrapper: $$TO"; else echo "↪︎ No timeout wrapper in use"; fi' >> "$$script"; \
      echo 'echo "→ Running Schemathesis against: $(SCHEMA_URL)$(API_BASE_PATH)"' >> "$$script"; \
      echo 'EXIT_CODE=0' >> "$$script"; \
      echo 'SCHEMA_BIN="$(SCHEMATHESIS)"; case "$$SCHEMA_BIN" in /*) ;; *) SCHEMA_BIN="$$(pwd)/$$SCHEMA_BIN";; esac' >> "$$script"; \
      echo 'tmpdir=$$(mktemp -d); trap "rm -rf $$tmpdir" EXIT; cd "$$tmpdir"' >> "$$script"; \
      echo 'for schema in $(ALL_API_SCHEMAS_ABS); do'   >> "$$script"; \
      echo '  echo "  • $$schema" | tee -a "$$LOG"' >> "$$script"; \
      echo '  set +e' >> "$$script"; \
      echo '  ( $$TO $$BUF "$$SCHEMA_BIN" run "$$schema" $$BASE_FLAG "$(SCHEMA_URL)$(API_BASE_PATH)" $(SCHEMATHESIS_OPTS) $$STATEFUL_ARGS 2>&1 || [ $$? -eq 124 ] ) | tee -a "$$LOG"' >> "$$script"; \
      echo '  rc=$${PIPESTATUS[0]}' >> "$$script"; \
      echo '  set -e' >> "$$script"; \
      echo '  if [ $$rc -ne 0 ] && [ $$EXIT_CODE -eq 0 ]; then EXIT_CODE=$$rc; fi' >> "$$script"; \
      echo 'done' >> "$$script"; \
      echo 'echo "→ Stopping API server"' >> "$$script"; \
      echo 'cleanup' >> "$$script"; \
      echo 'if [ $$EXIT_CODE -ne 0 ]; then echo "✘ Schemathesis reported failures (exit $$EXIT_CODE)"; fi' >> "$$script"; \
      echo 'exit $$EXIT_CODE' >> "$$script"; \
      chmod +x "$$script"; "$$script"
    @[ -f ./openapitools.json ] && echo "→ Removing stray openapitools.json (root)" && rm -f ./openapitools.json || true
    @echo "✔ Schemathesis finished. Log → $(API_TEST_DIR_ABS)/schemathesis.log"
    @[ -f "$(SCHEMATHESIS_JUNIT)" ] && echo "  JUnit → $(SCHEMATHESIS_JUNIT)" || true
    @[ -d .hypothesis ] && echo "→ Removing stray .hypothesis (root)" && rm -rf .hypothesis || true

# ── Dev helpers
api-serve: | $(VENV)
    @mkdir -p "$(API_ARTIFACTS_DIR_ABS)"
    @echo "→ Serving API (foreground) @ $(SCHEMA_URL) — logs → $(API_LOG_ABS)"
    @$(API_CMD)

api-serve-bg: | $(VENV)
    @mkdir -p "$(API_ARTIFACTS_DIR_ABS)"
    @echo "→ Serving API (background) @ $(SCHEMA_URL) — logs → $(API_LOG_ABS)"
    @$(API_CMD) >"$(API_LOG_ABS)" 2>&1 & echo $$! >"$(API_ARTIFACTS_DIR_ABS)/server.pid"
    @echo "PID $$(cat "$(API_ARTIFACTS_DIR_ABS)/server.pid")"

api-stop:
    @if [ -f "$(API_ARTIFACTS_DIR_ABS)/server.pid" ]; then \
      PID=$$(cat "$(API_ARTIFACTS_DIR_ABS)/server.pid"); \
      echo "→ Stopping PID $$PID"; \
      kill $$PID >/dev/null 2>&1 || true; \
      wait $$PID >/dev/null 2>&1 || true; \
      rm -f "$(API_ARTIFACTS_DIR_ABS)/server.pid"; \
    else \
      echo "→ No server.pid found (nothing to stop)"; \
    fi

# ── Node deps (sandboxed). No root pollution, no repo-level openapitools.json.
node_deps: $(API_NODE_DIR_ABS)/.deps-ok

$(API_NODE_DIR_ABS)/.deps-ok:
    @mkdir -p "$(API_NODE_DIR_ABS)" "$(API_NODE_DIR_ABS)/.npm-cache"
    @command -v npm >/dev/null || { echo "✘ npm not found"; exit 1; }
    @echo "→ Bootstrapping Node toolchain in $(API_NODE_DIR_ABS)"
    @cd "$(API_NODE_DIR_ABS)" && { test -f package.json || npm init -y >/dev/null; }
    @echo "→ Resolving openapi-generator-cli version (requested: $(OPENAPI_GENERATOR_VERSION))"
    @cd "$(API_NODE_DIR_ABS)" && { \
      PKG="@openapitools/openapi-generator-cli@$(OPENAPI_GENERATOR_VERSION)"; \
      if ! npm view "$$PKG" version >/dev/null 2>&1; then \
        echo "↪︎ Requested version not on npm; using @openapitools/openapi-generator-cli@latest"; \
        PKG="@openapitools/openapi-generator-cli@latest"; \
      fi; \
      echo "→ Installing CLI deps in $(API_NODE_DIR_ABS)"; \
      NPM_CONFIG_CACHE="$(API_NODE_DIR_ABS)/.npm-cache" \
      npm install --no-fund --no-audit --loglevel=info \
         --save-dev --save-exact \
         @redocly/cli "$$PKG" \
         > npm-install.log 2>&1 \
         || { echo "✘ npm install failed — see $(API_NODE_DIR_ABS)/npm-install.log"; tail -n 200 npm-install.log; exit 1; }; \
      RESOLVED_GEN_VER="$$(node -p "require('./node_modules/@openapitools/openapi-generator-cli/package.json').version")"; \
      RESOLVED_REDOC_VER="$$(node -p "require('./node_modules/@redocly/cli/package.json').version")"; \
      printf "openapi-generator-cli=%s\nredocly-cli=%s\n" "$$RESOLVED_GEN_VER" "$$RESOLVED_REDOC_VER" > tool-versions.txt; \
      echo "→ Installed: openapi-generator-cli=$$RESOLVED_GEN_VER, redocly-cli=$$RESOLVED_REDOC_VER"; \
    }
    @test -x "$(REDOCLY_ABS)" || { echo "✘ redocly CLI not found in sandbox"; exit 1; }
    @test -x "$(OPENAPI_GENERATOR_ABS)" || { echo "✘ openapi-generator-cli not found in sandbox"; exit 1; }
    @touch "$@"

# ── Cleanup
api-clean:
    @echo "→ Cleaning API artifacts"
    @rm -rf "$(API_ARTIFACTS_DIR_ABS)" || true
    @echo "✔ Done"

##@ API
api:            ## Run full API workflow (install → lint → test with Schemathesis); artifacts in artifacts/api/**
api-install:    ## Install API toolchain (Python deps + sandboxed Node deps)
api-lint:       ## Validate all OpenAPI specs; logs to artifacts/api/lint/*.log
api-test:       ## Start server, wait for /health, run Schemathesis; logs & JUnit to artifacts/api/**
api-serve:      ## Serve API in the foreground (dev)
api-serve-bg:   ## Serve API in the background; PID to artifacts/api/server.pid
api-stop:       ## Stop background API (if running)
api-clean:      ## Remove all API artifacts