Makefile

# Allow additional arguments to be passed
SHELL := /bin/bash
ARGS ?=
# Enforce a hard timeout for all test invocations (accepts coreutils duration)
# Can be overridden by environment: TEST_TIMEOUT=90s make test
TEST_TIMEOUT ?= 120s

# Cross-platform timeout detection: prefer GNU coreutils `timeout`, fallback to Homebrew `gtimeout`.
# If neither exists, run without timeout (prints a notice once).
TIMEOUT_BIN := $(shell command -v timeout 2>/dev/null || command -v gtimeout 2>/dev/null)
ifeq ($(TIMEOUT_BIN),)
  TIMEOUT_PREFIX :=
  define _timeout_notice
    @echo "[NOTICE] 'timeout' not found; running without enforced test timeout"
  endef
else
  TIMEOUT_PREFIX := $(TIMEOUT_BIN) $(TEST_TIMEOUT)
  _timeout_notice :=
endif

# FPM flags for different build targets
FPM_FLAGS_LIB = --flag -fPIC
FPM_FLAGS_TEST =
FPM_FLAGS_DEFAULT = $(FPM_FLAGS_LIB)

CI_FPM_TEST_TARGETS := test_public_api
CI_FPM_TEST_TARGETS += test_simple_validation
CI_FPM_TEST_TARGETS += test_backend_switching
CI_FPM_TEST_TARGETS += test_output_helpers_dir
CI_FPM_TEST_TARGETS += test_matplotlib_stubs
CI_FPM_TEST_TARGETS += test_format_parser
CI_FPM_TEST_TARGETS += test_figure_state_isolation
CI_FPM_TEST_TARGETS += test_scaling
CI_FPM_TEST_TARGETS += test_datetime_axis
CI_FPM_TEST_TARGETS += test_scatter
CI_FPM_TEST_TARGETS += test_histogram_functionality
CI_FPM_TEST_TARGETS += test_colormap_interpolation_regression
CI_FPM_TEST_TARGETS += test_pdf_flate_content
CI_FPM_TEST_TARGETS += test_pdf_coordinate_mapping_985
CI_FPM_TEST_TARGETS += test_quad_fill_edges
CI_FPM_TEST_TARGETS += test_svg_savefig
CI_FPM_TEST_TARGETS += test_new_plot_types
CI_FPM_TEST_TARGETS += test_ascii_animation_output

.PHONY: all build example debug test clean help doc create_build_dirs create_test_dirs validate-output test-docs verify-functionality verify-setup verify-with-evidence verify-size-compliance verify-complexity issue-branch issue-open-pr pr-merge pr-cleanup issue-loop issue-loop-dry git-prune verify-warnings

# Default target
all: build

# Build the project
build:
	fpm build $(FPM_FLAGS_DEFAULT) $(ARGS)

# Build and run the examples
example: create_build_dirs
	fpm run --example $(FPM_FLAGS_TEST) $(ARGS)
	# Re-run examples via fpm ensuring output directories exist
	@if [ -z "$(ARGS)" ]; then \
		./scripts/compile_special_examples.sh 2>/dev/null || true; \
	fi
	# Keep repository root clean: remove throwaway artifacts generated by demos
	@rm -f \
		basic_user_plot.png basic_user_plot.pdf basic_user_plot.txt \
		cmake_polynomials.png cmake_scientific.png \
		cmake_formats.png cmake_formats.pdf cmake_formats.txt \
		fpm_template_demo.png fpm_template_demo.pdf \
		fpm_*.png fpm_*.pdf fpm_*.txt \
		fmp_*.pdf \
		test_constant_y.pdf test_constant_x.pdf test_single_point.pdf \
		coordinate_validation.pdf \
		dpi_demo_*.png \
		ylabel_test[1-4]_*.png \
		show_output.png \
		subplots_grid_demo.png \
		test_pdf_scale_regression.pdf test_pdf_scale_regression.png \
		2>/dev/null || true

# Build and run the apps for debugging
debug:
	fpm run $(FPM_FLAGS_TEST) $(ARGS)

# Run tests
test: create_test_dirs
	$(call _timeout_notice)
	@echo "Running tests$(if $(TIMEOUT_PREFIX), with timeout $(TEST_TIMEOUT),)..."
	$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) $(ARGS) \
		&& echo "ALL TESTS PASSED (fpm test)"

# Run fast test suite for development iteration (minimal I/O, no delays)
test-fast: create_test_dirs
	@echo "Running fast test suite for development iteration..."
	@FORTPLOT_FAST_TESTS=1 fpm test $(FPM_FLAGS_TEST) --target test_suite_fast \
		&& echo "FAST TESTS PASSED"

# Run fast tests for CI (skip heavy I/O and MPEG tests)
test-ci:
	$(call _timeout_notice)
	@echo "Running CI-optimized test suite (essential tests only)$(if $(TIMEOUT_PREFIX), with timeout $(TEST_TIMEOUT),)..."
	@# Guard: ensure no Python bytecode is tracked
	@$(TIMEOUT_PREFIX) bash scripts/test_no_tracked_python_bytecode.sh || exit 1
	@# Guard: curated fpm tests must exist before running them
	@FPM_FLAGS_TEST="$(FPM_FLAGS_TEST)" $(TIMEOUT_PREFIX) scripts/verify_ci_fpm_targets.sh $(CI_FPM_TEST_TARGETS) || exit 1
	@echo "Testing core API and backend smoke coverage"
	@# Core API and backend smoke coverage for CI confidence
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_public_api || exit 1
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_simple_validation || exit 1
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_backend_switching || exit 1
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_output_helpers_dir || exit 1
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_matplotlib_stubs || exit 1
	@echo "Testing parsing, state isolation, and scaling regressions"
	@# Parsing, state isolation, and scaling regression guards
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_format_parser || exit 1
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_figure_state_isolation || exit 1
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_scaling || exit 1
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_datetime_axis || exit 1
	@echo "Testing statistical plot coverage and scatter regressions"
	@# Statistical plot coverage and scatter regression guard
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_scatter || exit 1
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_histogram_functionality || exit 1
	@# Regression: colormap interpolation must not be flat near min (pcolormesh negative mapping)
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_colormap_interpolation_regression || exit 1
	@# PDF content streams should be Flate-compressed
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_pdf_flate_content || exit 1
	@# Regression guard for Issue #985 (PDF coordinate mapping)
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_pdf_coordinate_mapping_985 || exit 1
	@# Regression guard for Issue #995 (PDF axes stroke color should be black)
	@$(TIMEOUT_PREFIX) python3 scripts/test_pdf_axes_color_black.py || exit 1
	@# Regression for filled-quad edge coverage (prevents 1px cuts on borders)
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_quad_fill_edges || exit 1
	@# Guard against redundant pcolormesh tests (Issue #897)
	@$(TIMEOUT_PREFIX) ./scripts/test_pcolormesh_guard.sh || exit 1
	@# Enforce directory item limits for src/* subfolders (Issue #914)
	@$(TIMEOUT_PREFIX) python3 scripts/test_directory_organization_limits.py || exit 1
	@# SVG end-to-end: stateful API through rendering pipeline to SVG file (Issue #1690)
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_svg_savefig || exit 1
	@# New plot types: imshow/step/stem/fill/fill_between/twinx/twiny behavioral smoke tests (Issue #1712)
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_new_plot_types || exit 1
	@# ASCII animation regression: frame clearing and file content (Issue #1699)
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_ascii_animation_output || exit 1
	@echo "CI essential test suite completed successfully"

# Clean build artifacts
clean:
	echo y | fpm clean
	rm -rf build/example
	rm -rf build/test/output
	# Remove generated media artifacts without touching tracked source/docs files.
	# Generated outputs live under output/ and build/.
	@if [ -d output ]; then \
		find output \( -name "*.png" -o -name "*.pdf" -o -name "*.txt" \
			-o -name "*.mp4" -o -name "*.avi" -o -name "*.mkv" \) \
			-type f -exec rm -f {} \; ; \
	fi

# Build with release optimizations
release:
	fpm build --profile release $(ARGS)

# Run with release optimizations
run-release:
	fpm run --profile release $(ARGS)

# Build documentation with FORD
doc:
	@echo "Updating documentation index from example directories..."
	@fpm run --target update_example_index >/dev/null
	@echo "Regenerating example documentation pages..."
	@fpm run --example generate_example_docs >/dev/null
	# Ensure critical example media exist for docs (fixes #858, #1032)
	# Generate streamplot and pcolormesh demos so images are available in docs
	$(MAKE) example ARGS="streamplot_demo" >/dev/null
	$(MAKE) example ARGS="pcolormesh_demo" >/dev/null
	# Generate errorbar demo so example page has images (fixes #1299)
	$(MAKE) example ARGS="errorbar_demo" >/dev/null
	# Generate marker demo so marker images (including all_marker_types.png) are present (fixes #1109)
	$(MAKE) example ARGS="marker_demo" >/dev/null
	# Generate animation demo so MP4 is available for docs (fixes #1085)
	$(MAKE) example ARGS="save_animation_demo" >/dev/null
	# Generate doc.md from README.md (strip badge and title - FORD adds title from fpm.toml)
	grep -v 'img.shields.io' README.md | sed '1{/^# fortplot$$/d}' > doc.md
	# Run FORD to generate documentation structure
	ford doc.md
	# Copy example media files to BOTH possible link roots used in pages
	# Some pages link '../media/...' (relative to page/examples), others '../../media/...'
	# So stage to: build/doc/page/media/... and build/doc/media/...
	mkdir -p build/doc/page/media/examples build/doc/media/examples
	# Copy from doc/media (populated in workflow) into both
	if [ -d doc/media/examples ]; then \
		cp -r doc/media/examples/* build/doc/page/media/examples/ 2>/dev/null || true; \
		cp -r doc/media/examples/* build/doc/media/examples/ 2>/dev/null || true; \
	fi
	# Also copy directly from output directory (local builds) into both
	for dir in output/example/fortran/*/; do \
		if [ -d "$$dir" ]; then \
			example_name=$$(basename "$$dir"); \
			mkdir -p "build/doc/page/media/examples/$$example_name" "build/doc/media/examples/$$example_name"; \
			cp "$$dir"*.png "build/doc/page/media/examples/$$example_name/" 2>/dev/null || true; \
			cp "$$dir"*.txt "build/doc/page/media/examples/$$example_name/" 2>/dev/null || true; \
			cp "$$dir"*.pdf "build/doc/page/media/examples/$$example_name/" 2>/dev/null || true; \
			cp "$$dir"*.mp4 "build/doc/page/media/examples/$$example_name/" 2>/dev/null || true; \
			cp "$$dir"*.png "build/doc/media/examples/$$example_name/" 2>/dev/null || true; \
			cp "$$dir"*.txt "build/doc/media/examples/$$example_name/" 2>/dev/null || true; \
			cp "$$dir"*.pdf "build/doc/media/examples/$$example_name/" 2>/dev/null || true; \
			cp "$$dir"*.mp4 "build/doc/media/examples/$$example_name/" 2>/dev/null || true; \
		fi; \
	done
	# Ensure animation.mp4 explicitly present at expected locations (robust fallback)
	if [ -f output/example/fortran/save_animation_demo/animation.mp4 ]; then \
		mkdir -p build/doc/page/media/examples/animation build/doc/media/examples/animation; \
		cp output/example/fortran/save_animation_demo/animation.mp4 build/doc/page/media/examples/animation/ 2>/dev/null || true; \
		cp output/example/fortran/save_animation_demo/animation.mp4 build/doc/media/examples/animation/ 2>/dev/null || true; \
	fi


# Validate functional output generation
validate-output: create_build_dirs
	@echo "Running functional output validation tests..."
	@mkdir -p output/test
	fpm test $(FPM_FLAGS_TEST) --target test_output_validation
	@echo "Functional output validation completed successfully"

# Test documentation-related targets (run existing doc tests)
test-docs: create_build_dirs
	$(call _timeout_notice)
	@echo "Running documentation tests$(if $(TIMEOUT_PREFIX), with timeout $(TEST_TIMEOUT),)..."
	@mkdir -p output/test
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_doc_core || exit 1
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_doc_processing_output || exit 1
	@$(TIMEOUT_PREFIX) fpm test $(FPM_FLAGS_TEST) --target test_docs_index_pages || exit 1
	@echo "Documentation tests completed successfully"

# Run comprehensive functional tests
test-functional: test validate-output test-docs
	@echo "=== ALL FUNCTIONAL TESTS PASSED ==="

# Strict artifact verification for rendering-related changes
.PHONY: verify-artifacts
verify-artifacts: create_build_dirs
	@bash scripts/verify_artifacts.sh
# Create build directories for examples
create_build_dirs:
	@mkdir -p output/example/fortran/basic_plots
	@mkdir -p output/example/fortran/styling_demo
	@mkdir -p output/example/fortran/display_demo
	@mkdir -p output/example/fortran/contour_demo
	@mkdir -p output/example/fortran/pcolormesh_demo
	@mkdir -p output/example/fortran/streamplot_demo
	@mkdir -p output/example/fortran/ascii_heatmap
	@mkdir -p output/example/fortran/scale_examples
	@mkdir -p output/example/fortran/legend_demo
	@mkdir -p output/example/fortran/legend_box_demo
	@mkdir -p output/example/fortran/unicode_demo
	@mkdir -p output/example/fortran/save_animation_demo
	@mkdir -p output/example/fortran/annotation_demo
	@mkdir -p output/example/fortran/histogram_demo
	@mkdir -p output/example/fortran/subplot_demo
	@mkdir -p output/example/fortran/bar_chart_demo
	@mkdir -p output/example/fortran/errorbar_demo
	@mkdir -p output/example/fortran/disconnected_lines
	@mkdir -p output/example/fortran/boxplot_demo
	@mkdir -p output/example/fortran/grid_demo
	@mkdir -p output/example/fortran/datetime_axis_demo

# Create test directories for isolated test artifacts (Issue #820)
create_test_dirs:
	@mkdir -p build/test/output

# Comprehensive functionality preservation verification (Issue #609)
verify-functionality:
	@echo "Running comprehensive functionality preservation verification..."
	@echo "Issue #609: Comprehensive Functionality Preservation Verification System"
	./scripts/verify_functionality_preservation.sh

# Setup verification environment only
verify-setup:
	@echo "Setting up functionality verification environment..."
	./scripts/verify_functionality_preservation.sh --setup

# Run verification tests with fraud-proof evidence generation
verify-with-evidence: verify-functionality
	@echo "Verification complete - technical evidence generated"
	@echo "Evidence directory: test/output/verification/evidence/"
	@ls -la test/output/verification/evidence/ || true

# --- GitHub issue/PR helpers for Codex loop ---
issue-branch:
	@if [ -z "$(ISSUE)" ]; then echo "ISSUE=<number> required"; exit 2; fi
	@echo "Creating branch for issue #$(ISSUE)"
	@./scripts/issue_branch.sh $(ISSUE)

issue-open-pr:
	@if [ -z "$(ISSUE)" ]; then echo "ISSUE=<number> required"; exit 2; fi
	@./scripts/issue_open_pr.sh $(ISSUE)

pr-merge:
	@if [ -z "$(PR)" ]; then echo "PR=<number> required"; exit 2; fi
	@./scripts/pr_merge.sh $(PR) $(ARGS)

pr-cleanup:
	@if [ -z "$(PR)" ]; then echo "PR=<number> required"; exit 2; fi
	@./scripts/pr_cleanup.sh $(PR)

issue-loop:
	@label=$${LABEL-__all__}; \
	if [ "$$label" = "__all__" ]; then \
		./scripts/issue_loop.sh --all --limit $${LIMIT:-999999}; \
	else \
		./scripts/issue_loop.sh --label "$$label" --limit $${LIMIT:-999999}; \
	fi

issue-loop-dry:
	@label=$${LABEL-__all__}; \
	if [ "$$label" = "__all__" ]; then \
		./scripts/issue_loop.sh --all --limit $${LIMIT:-999999} --dry-run; \
	else \
		./scripts/issue_loop.sh --label "$$label" --limit $${LIMIT:-999999} --dry-run; \
	fi

issue-loop-auto:
	@label=$${LABEL-__all__}; \
	if [ "$$label" = "__all__" ]; then \
		CLEAN_FORCE=1 ./scripts/issue_orchestrate_auto.sh --all --limit $${LIMIT:-999999}; \
	else \
		CLEAN_FORCE=1 ./scripts/issue_orchestrate_auto.sh --label "$$label" --limit $${LIMIT:-999999}; \
	fi

# File size compliance verification - fraud prevention
verify-size-compliance:
	@echo "Running file size fraud prevention verification..."
	./scripts/verify_file_sizes.sh

# Fortran procedural complexity budgets (Issue #937)
verify-complexity:
	@echo "Running Fortran procedure complexity verification..."
	@chmod +x scripts/verify_complexity.sh
	@MAX_TOTAL_PROCS=$${MAX_TOTAL_PROCS-2000} \
	 MAX_PROCS_PER_FILE=$${MAX_PROCS_PER_FILE-60} \
	 ./scripts/verify_complexity.sh src

# Help target
help:
	@echo "Available targets:"
	@echo "  build            - Compile the project"
	@echo "  example          - Build and run all Fortran examples"
	@echo "  debug            - Build and run apps for debugging"
	@echo "  test             - Run all tests"
	@echo "  test-ci          - Run CI-optimized tests (skip heavy I/O, MPEG tests)"
	@echo "  validate-output  - Run functional output validation tests"
	@echo "  test-docs        - Test documentation examples"
	@echo "  verify-functionality - Run comprehensive functionality preservation verification"
	@echo "  verify-setup     - Setup functionality verification environment"
	@echo "  verify-with-evidence - Run verification with fraud-proof evidence generation"
	@echo "  verify-size-compliance - File size fraud prevention verification"
	@echo "  verify-complexity - Enforce procedure count budgets (Issue #937)"
	@echo "  verify-warnings - Compile with aggressive warnings (-Werror)"
	@echo "  doc              - Build documentation with FORD"
	@echo "  clean       - Clean build artifacts"
	@echo "  release     - Build with optimizations"
	@echo "  run-release - Run optimized build"
	@echo "  help        - Show this help message"
	@echo "  git-prune   - Safely prune remote-tracking and old merged local branches"
	@echo ""
	@echo "Pass additional fmp arguments using ARGS variable:"
	@echo "  make example ARGS=\"basic_plots\""
	@echo "  make test ARGS=\"--target test_specific\""
	@echo "  make debug ARGS=\"--target debug_feature\""
	@echo ""
	@echo "This project uses STB TrueType and STB Image Write for text and PNG compression."
	@echo "All dependencies are included as header-only libraries."
	@echo "No external packages required."

# Prune remote-tracking branches and delete local merged branches (dry-run by default)
git-prune:
	@echo "Running safe git prune (dry-run). Use FORCE=1 to apply."
	@if [ "$(FORCE)" = "1" ]; then \
		./scripts/git_prune.sh --force; \
	else \
		./scripts/git_prune.sh; \
	fi

# Compile with aggressive warnings enabled and fail on any warning
verify-warnings:
	@echo "Verifying warning-free build with aggressive flags (-Werror)..."
	@# Fortran warnings
	@fpm build --flag "-Wall -Wextra -Wimplicit-interface -Werror -fPIC" || exit 1
	@# C warnings
	@fpm build --c-flag "-Wall -Wextra -Werror" || exit 1
	@echo "Warning-free verification completed successfully"