Makefile

# Makefile for PyMemoryEditor Python package

# Variables
PACKAGE_NAME = PyMemoryEditor
PYTHON = python3
PIP = pip3
BUILD_DIR = build
DIST_DIR = dist
EGG_INFO = $(PACKAGE_NAME).egg-info
VENV_DIR = venv
TEST_DIR = tests
DOCS_DIR = docs
DOCS_BUILD_DIR = $(DOCS_DIR)/_build/html

# Colors for output
GREEN = \033[0;32m
YELLOW = \033[0;33m
RED = \033[0;31m
BLUE = \033[0;34m
NC = \033[0m # No Color

# Default target
.PHONY: help
help:
	@echo "$(GREEN)PyMemoryEditor Python package Makefile$(NC)"
	@echo ""
	@echo "Available targets:"
	@echo "  $(YELLOW)install$(NC)          - Install package in development mode"
	@echo "  $(YELLOW)install-deps$(NC)     - Install dependencies"
	@echo "  $(YELLOW)install-app$(NC)      - Install dependencies to run the PyMemoryEditor App"
	@echo "  $(YELLOW)run-app$(NC)          - Run the PyMemoryEditor App"
	@echo "  $(YELLOW)install-dev$(NC)      - Install development dependencies"
	@echo "  $(YELLOW)test$(NC)             - Run the full test suite (incl. live whole-process scans)"
	@echo "  $(YELLOW)test-fast$(NC)        - Run the fast lane only (-m \"not slow\", ~20 s; skips the scan property tests)"
	@echo "  $(YELLOW)test-mcp$(NC)         - Run the MCP server suite"
	@echo "  $(YELLOW)test-verbose$(NC)     - Run tests with verbose output"
	@echo "  $(YELLOW)test-coverage$(NC)    - Run tests with coverage report"
	@echo "  $(YELLOW)lint$(NC)             - Run linter (flake8)"
	@echo "  $(YELLOW)type-check$(NC)       - Run type checker (mypy)"
	@echo "  $(YELLOW)clean$(NC)            - Clean build artifacts"
	@echo "  $(YELLOW)build$(NC)            - Build package"
	@echo "  $(YELLOW)build-wheel$(NC)      - Build wheel package"
	@echo "  $(YELLOW)build-sdist$(NC)      - Build source distribution"
	@echo "  $(YELLOW)validate$(NC)         - Validate package"
	@echo "  $(YELLOW)publish$(NC)          - MANUAL FALLBACK: upload to PyPI by token from a checkout of the release tag"
	@echo "                     (releases go through GitHub Releases; see CONTRIBUTING.md)"
	@echo "  $(YELLOW)publish-test$(NC)     - Publish to Test PyPI"
	@echo "  $(YELLOW)ci$(NC)               - Mirror the CI workflow: lint, type-check, both coverage-gated test runs"
	@echo "  $(YELLOW)version$(NC)          - Show current version"
	@echo "  $(YELLOW)check-deps$(NC)       - Check for outdated dependencies"
	@echo "  $(YELLOW)update-deps$(NC)      - Update dependencies"
	@echo "  $(YELLOW)security$(NC)         - Run security audit"
	@echo "  $(YELLOW)install-docs$(NC)     - Install dependencies to build the documentation"
	@echo "  $(YELLOW)docs$(NC)             - Build the HTML documentation (output: $(DOCS_BUILD_DIR))"
	@echo "  $(YELLOW)docs-serve$(NC)       - Live-reload docs server at http://127.0.0.1:8000"
	@echo "  $(YELLOW)docs-clean$(NC)       - Remove the docs build directory"
	@echo "  $(YELLOW)venv$(NC)             - Create virtual environment"
	@echo "  $(YELLOW)venv-activate$(NC)    - Show command to activate venv"
	@echo "  $(YELLOW)all$(NC)              - Run full pipeline (install, lint, test, build)"
	@echo "  $(YELLOW)release$(NC)          - MANUAL FALLBACK: pre-publish checks, then publish (same tag guard)"

# Create virtual environment
.PHONY: venv
venv:
	@echo "$(GREEN)Creating virtual environment...$(NC)"
	$(PYTHON) -m venv $(VENV_DIR)
	@echo "$(GREEN)Virtual environment created in $(VENV_DIR)$(NC)"
	@echo "$(YELLOW)To activate: source $(VENV_DIR)/bin/activate$(NC)"

# Show activation command
.PHONY: venv-activate
venv-activate:
	@echo "$(YELLOW)To activate virtual environment run:$(NC)"
	@echo "source $(VENV_DIR)/bin/activate"

# Install dependencies (uses pyproject.toml — requirements.txt was removed in v2.0)
.PHONY: install-deps
install-deps:
	@echo "$(GREEN)Installing runtime dependencies...$(NC)"
	$(PIP) install -e .
	@echo "$(GREEN)Dependencies installed successfully!$(NC)"

# Install dependencies to run the PyMemoryEditor App (Qt GUI)
.PHONY: install-app
install-app:
	@echo "$(GREEN)Installing PyMemoryEditor App dependencies...$(NC)"
	$(PIP) install -e ".[app]"
	@echo "$(GREEN)App dependencies installed successfully!$(NC)"
	@echo "$(YELLOW)Launch the app with: pymemoryeditor$(NC)"

# Run the PyMemoryEditor App (Qt GUI)
.PHONY: run-app
run-app:
	@echo "$(GREEN)Starting PyMemoryEditor App...$(NC)"
	$(PYTHON) -m PyMemoryEditor

# Install development dependencies
.PHONY: install-dev
install-dev:
	@echo "$(GREEN)Installing development dependencies...$(NC)"
	$(PIP) install -e ".[dev]"
	@echo "$(GREEN)Development dependencies installed successfully!$(NC)"

# Install package in development mode
.PHONY: install
install:
	@echo "$(GREEN)Installing package in development mode...$(NC)"
	$(PIP) install -e .
	@echo "$(GREEN)Package installed successfully!$(NC)"

# Run tests (everything, including the live scans marked `slow`/`scan_heavy`)
.PHONY: test
test:
	@echo "$(GREEN)Running tests...$(NC)"
	$(PYTHON) -m pytest $(TEST_DIR) -v
	@echo "$(GREEN)Tests completed!$(NC)"

# Fast lane: unit, GUI and MCP tests (~20 s: ~13 s for the library and app,
# ~5 s for the MCP suite). Everything marked `slow` is left out, which
# includes the scan property tests in tests/scan/test_scan_properties.py --
# run `make test` or `pytest tests/scan/test_scan_properties.py` for those.
# The markers are defined in pyproject.toml.
.PHONY: test-fast
test-fast:
	@echo "$(GREEN)Running the fast test lane (-m \"not slow\")...$(NC)"
	$(PYTHON) -m pytest $(TEST_DIR) -m "not slow"
	@echo "$(GREEN)Fast tests completed!$(NC)"

# The MCP server suite. CI runs it as its own job (`build-mcp`), with the
# pytest-qt plugin disabled because it imports Qt at startup and no test here
# needs it.
.PHONY: test-mcp
test-mcp:
	@echo "$(GREEN)Running the MCP server tests...$(NC)"
	$(PYTHON) -m pytest $(TEST_DIR)/mcp_server -p no:pytest-qt
	@echo "$(GREEN)MCP tests completed!$(NC)"

# Run tests with verbose output
.PHONY: test-verbose
test-verbose:
	@echo "$(GREEN)Running tests with verbose output...$(NC)"
	$(PYTHON) -m pytest $(TEST_DIR) -v -s
	@echo "$(GREEN)Verbose tests completed!$(NC)"

# Run tests with coverage
.PHONY: test-coverage
test-coverage:
	@echo "$(GREEN)Running tests with coverage...$(NC)"
	$(PYTHON) -m pytest $(TEST_DIR) --cov=$(PACKAGE_NAME) --cov-report=html --cov-report=term
	@echo "$(GREEN)Coverage report generated!$(NC)"
	@echo "$(YELLOW)HTML report available at htmlcov/index.html$(NC)"

# Run linter
.PHONY: lint
lint:
	@echo "$(GREEN)Running linter (flake8)...$(NC)"
	$(PYTHON) -m flake8 $(PACKAGE_NAME) $(TEST_DIR)
	@echo "$(GREEN)Linting completed!$(NC)"

# Run type checker (config in pyproject.toml — ignore_missing_imports is set there)
.PHONY: type-check
type-check:
	@echo "$(GREEN)Running type checker (mypy)...$(NC)"
	$(PYTHON) -m mypy $(PACKAGE_NAME)
	@echo "$(GREEN)Type checking completed!$(NC)"

# Clean build artifacts
.PHONY: clean
clean:
	@echo "$(GREEN)Cleaning build artifacts...$(NC)"
	rm -rf $(BUILD_DIR)
	rm -rf $(DIST_DIR)
	rm -rf $(EGG_INFO)
	rm -rf .pytest_cache
	rm -rf htmlcov
	rm -rf .coverage
	rm -rf .mypy_cache
	find . -type d -name "__pycache__" -exec rm -rf {} +
	find . -type f -name "*.pyc" -delete
	find . -type f -name "*.pyo" -delete
	find . -type f -name "*.pyd" -delete
	find . -type f -name ".coverage" -delete
	@echo "$(GREEN)Cleanup completed!$(NC)"

# Build package
.PHONY: build
build: clean
	@echo "$(GREEN)Building package...$(NC)"
	$(PYTHON) -m build
	@echo "$(GREEN)Package built successfully!$(NC)"

# Build wheel package only
.PHONY: build-wheel
build-wheel: clean
	@echo "$(GREEN)Building wheel package...$(NC)"
	$(PYTHON) -m build --wheel
	@echo "$(GREEN)Wheel package built successfully!$(NC)"

# Build source distribution only
.PHONY: build-sdist
build-sdist: clean
	@echo "$(GREEN)Building source distribution...$(NC)"
	$(PYTHON) -m build --sdist
	@echo "$(GREEN)Source distribution built successfully!$(NC)"

# Validate package
.PHONY: validate
validate: build
	@echo "$(GREEN)Validating package...$(NC)"
	$(PYTHON) -m twine check --strict $(DIST_DIR)/*
	@echo "$(GREEN)Package validation completed!$(NC)"

# Refuse to upload anything but a clean checkout of the tag `v<__version__>`.
# publish.yml checks the tag against the version before its upload; this is
# the same guard for the manual path, plus a clean tree so the files built are
# the files tagged. It does not replace the workflow's other gate (a green
# python-package.yml run on the commit): check that by hand.
.PHONY: check-release-tag
check-release-tag:
	@version=$$($(PYTHON) -c "import $(PACKAGE_NAME); print($(PACKAGE_NAME).__version__)") && \
	tag="v$$version" ; \
	found=$$(git tag --points-at HEAD | xargs) ; \
	if ! git tag --points-at HEAD | grep -qx "$$tag"; then \
		echo "$(RED)HEAD is not tagged $$tag (found: $${found:-no tag}). Check out the release tag first.$(NC)"; exit 1; \
	fi; \
	if [ -n "$$(git status --porcelain --untracked-files=no)" ]; then \
		echo "$(RED)The working tree has uncommitted changes; publish from a clean checkout of $$tag.$(NC)"; exit 1; \
	fi; \
	echo "$(GREEN)HEAD is $$tag, matching __version__ $$version.$(NC)"

# Publish to PyPI by API token. MANUAL FALLBACK only: releases are cut by
# publishing a GitHub Release, which .github/workflows/publish.yml uploads to
# PyPI via trusted publishing (OIDC, no token) and then lists on the MCP
# Registry. Use this target only if that workflow is unavailable, and note it
# does not list the release on the MCP Registry.
.PHONY: publish
publish: check-release-tag validate
	@echo "$(YELLOW)Are you sure you want to publish to PyPI? [y/N]$(NC)" && read ans && [ $${ans:-N} = y ]
	@echo "$(GREEN)Publishing to PyPI...$(NC)"
	$(PYTHON) -m twine upload $(DIST_DIR)/*
	@echo "$(GREEN)Package published successfully to PyPI!$(NC)"

# Publish to Test PyPI
.PHONY: publish-test
publish-test: validate
	@echo "$(GREEN)Publishing to Test PyPI...$(NC)"
	$(PYTHON) -m twine upload --repository testpypi $(DIST_DIR)/*
	@echo "$(GREEN)Package published successfully to Test PyPI!$(NC)"

# Show current version
.PHONY: version
version:
	@echo "$(GREEN)Current package version:$(NC)"
	@$(PYTHON) -c "import $(PACKAGE_NAME); print($(PACKAGE_NAME).__version__)"

# Check for outdated dependencies
.PHONY: check-deps
check-deps:
	@echo "$(GREEN)Checking for outdated dependencies...$(NC)"
	$(PIP) list --outdated

# Update dependencies
.PHONY: update-deps
update-deps:
	@echo "$(GREEN)Updating dependencies...$(NC)"
	$(PIP) install --upgrade -e ".[dev]"
	@echo "$(GREEN)Dependencies updated!$(NC)"

# Security audit — uses pip-audit (PyPA-maintained) which works without a
# paid account, unlike the older `safety` tool.
.PHONY: security
security:
	@echo "$(GREEN)Running security audit (pip-audit)...$(NC)"
	$(PIP) install pip-audit
	pip-audit
	@echo "$(GREEN)Security audit completed!$(NC)"

# Install the dependencies needed to build the documentation (Sphinx + MyST +
# the Read the Docs theme + extensions, listed in docs/requirements.txt). Also installs the
# package itself in editable mode so autodoc can import it.
.PHONY: install-docs
install-docs:
	@echo "$(GREEN)Installing documentation dependencies...$(NC)"
	$(PIP) install -r $(DOCS_DIR)/requirements.txt
	$(PIP) install -e .
	@echo "$(GREEN)Docs dependencies installed!$(NC)"

# Build the HTML documentation. Output lands in $(DOCS_BUILD_DIR). Warnings
# are errors, the same as the `docs` job in python-package.yml.
.PHONY: docs
docs:
	@echo "$(GREEN)Building HTML documentation...$(NC)"
	$(PYTHON) -m sphinx -W --keep-going -b html $(DOCS_DIR) $(DOCS_BUILD_DIR)
	@echo "$(GREEN)Documentation generated at $(DOCS_BUILD_DIR)/index.html$(NC)"

# Live-reload docs server — rebuilds on every save and reloads the browser.
# Requires `sphinx-autobuild` (installed automatically via install-docs is
# optional; we install it on demand here for convenience).
.PHONY: docs-serve
docs-serve:
	@echo "$(GREEN)Starting live-reload docs server at http://127.0.0.1:8000$(NC)"
	@$(PYTHON) -c "import sphinx_autobuild" 2>/dev/null || $(PIP) install sphinx-autobuild
	$(PYTHON) -m sphinx_autobuild $(DOCS_DIR) $(DOCS_BUILD_DIR) --open-browser

# Wipe the built docs.
.PHONY: docs-clean
docs-clean:
	@echo "$(GREEN)Cleaning docs build directory...$(NC)"
	rm -rf $(DOCS_DIR)/_build
	@echo "$(GREEN)Docs build directory removed.$(NC)"

# Full development pipeline
.PHONY: all
all: install lint type-check test build validate
	@echo "$(GREEN)Full pipeline completed successfully!$(NC)"

# Development workflow targets
.PHONY: dev-setup
dev-setup: venv install-dev install
	@echo "$(GREEN)Development environment setup completed!$(NC)"
	@echo "$(YELLOW)Don't forget to activate the virtual environment:$(NC)"
	@echo "source $(VENV_DIR)/bin/activate"

.PHONY: pre-commit
pre-commit: lint type-check test
	@echo "$(GREEN)Pre-commit checks passed!$(NC)"

.PHONY: pre-publish
pre-publish: all security
	@echo "$(GREEN)Pre-publish checks completed!$(NC)"

# CI/CD targets. Mirrors .github/workflows/python-package.yml: the library
# and app tests are gated on the library's coverage (.coveragerc-lib), the
# MCP suite on its own (.coveragerc-mcp), with the same floors as the
# workflow. Keep the two in sync when either changes.
.PHONY: ci
ci: install-dev install lint type-check
	@echo "$(GREEN)Running the library/app suite with the CI coverage gate...$(NC)"
	QT_QPA_PLATFORM=offscreen $(PYTHON) -m pytest $(TEST_DIR) --ignore=$(TEST_DIR)/mcp_server --maxfail=10 \
		--cov=$(PACKAGE_NAME) --cov-config=.coveragerc-lib --cov-report=term --cov-fail-under=62
	@echo "$(GREEN)Running the MCP suite with the CI coverage gate...$(NC)"
	$(PYTHON) -m pytest $(TEST_DIR)/mcp_server -p no:pytest-qt --maxfail=10 \
		--cov=$(PACKAGE_NAME)/mcp --cov-config=.coveragerc-mcp --cov-report=term --cov-fail-under=85
	$(MAKE) build validate
	@echo "$(GREEN)CI pipeline completed!$(NC)"

# Show package info
.PHONY: info
info:
	@echo "$(GREEN)Package Information:$(NC)"
	@echo "Name: $(PACKAGE_NAME)"
	@$(PYTHON) -c "import $(PACKAGE_NAME); print('Version:', $(PACKAGE_NAME).__version__)" 2>/dev/null || echo "Version: Not installed"
	@echo "Python: $(shell $(PYTHON) --version)"
	@echo "Pip: $(shell $(PIP) --version)"
	@echo ""
	@echo "$(GREEN)Installed packages:$(NC)"
	@$(PIP) list | grep -E "($(PACKAGE_NAME)|pytest|flake8|mypy|twine|build)"

# Manual release (fallback for publish.yml; see `publish`). The tag guard runs
# first so a mismatched checkout fails before the full pre-publish pipeline.
.PHONY: release
release: check-release-tag pre-publish publish
	@echo "$(GREEN)Release completed!$(NC)"

.PHONY: release-test
release-test: pre-publish publish-test
	@echo "$(GREEN)Test release completed!$(NC)"

# Install from PyPI (for testing)
.PHONY: install-from-pypi
install-from-pypi:
	@echo "$(GREEN)Installing from PyPI...$(NC)"
	$(PIP) install $(PACKAGE_NAME)
	@echo "$(GREEN)Package installed from PyPI!$(NC)"

# Install from Test PyPI (for testing)
.PHONY: install-from-test-pypi
install-from-test-pypi:
	@echo "$(GREEN)Installing from Test PyPI...$(NC)"
	$(PIP) install --index-url https://test.pypi.org/simple/ $(PACKAGE_NAME)
	@echo "$(GREEN)Package installed from Test PyPI!$(NC)"

# Uninstall package
.PHONY: uninstall
uninstall:
	@echo "$(GREEN)Uninstalling package...$(NC)"
	$(PIP) uninstall $(PACKAGE_NAME) -y
	@echo "$(GREEN)Package uninstalled!$(NC)"