markitect-main/Makefile

# MarkiTect - Advanced Markdown Engine
# Makefile for common development tasks

.PHONY: help setup install test build clean update status dev lint format check-deps venv-status update-digest add-diary-entry list-issues show-issue list-open-issues test-from-issue tdd-start tdd-add-test tdd-finish tdd-status test-status test-new test-coverage

# Default target
help:
	@echo "MarkiTect Development Commands"
	@echo "=============================="
	@echo ""
	@echo "Environment Status:"
	@$(MAKE) --no-print-directory venv-status
	@echo ""
	@echo "Setup & Installation:"
	@echo "  setup       - Initial project setup (venv + install)"
	@echo "  install     - Install package in development mode"
	@echo "  dev         - Install with development dependencies"
	@echo "  venv-status - Check if venv is active"
	@echo ""
	@echo "Development:"
	@echo "  test        - Run all tests"
	@echo "  test-status - Show test status summary without re-running"
	@echo "  test-new    - Create new test file template"
	@echo "  test-coverage NUM=X - Analyze test coverage for issue"
	@echo "  build       - Build the package"
	@echo "  lint        - Run code linting"
	@echo "  format      - Format code"
	@echo ""
	@echo "Maintenance:"
	@echo "  update      - Update from upstream (git + submodules)"
	@echo "  status      - Show git status for repo and submodules"
	@echo "  clean       - Clean build artifacts"
	@echo "  check-deps  - Check dependency status"
	@echo ""
	@echo "Documentation:"
	@echo "  update-digest   - Update ProjectStatusDigest.md (requires Claude Code)"
	@echo "  add-diary-entry - Add new entry to ProjectDiary.md (requires Claude Code)"
	@echo ""
	@echo "Issue Management:"
	@echo "  list-issues      - Show all gitea issues with status and priority"
	@echo "  list-open-issues - Show only open issues (active backlog)"
	@echo "  show-issue NUM=X - Show detailed view of specific issue"
	@echo ""
	@echo "Test-Driven Development:"
	@echo "  test-from-issue NUM=X - Generate test skeleton from issue (requires Claude Code)"
	@echo ""
	@echo "TDD Workspace:"
	@echo "  tdd-start NUM=X       - Start working on issue (creates workspace)"
	@echo "  tdd-add-test          - Add test to current issue workspace"
	@echo "  tdd-status            - Show current workspace state"
	@echo "  tdd-finish            - Complete issue work (moves tests to main)"

# Python and virtual environment setup
PYTHON := python3
VENV := .venv
VENV_PYTHON := $(VENV)/bin/python
VENV_PIP := $(VENV)/bin/pip

# Check virtual environment status (read-only)
venv-status:
	@if [ -f $(VENV)/bin/activate ] && [ -f $(VENV)/bin/python ]; then \
		if [ -n "$$VIRTUAL_ENV" ] && [ "$$VIRTUAL_ENV" = "$$(realpath $(VENV))" ]; then \
			echo "  ✅ Virtual environment: Active in current shell"; \
		elif [ -n "$$VIRTUAL_ENV" ]; then \
			echo "  ⚠️  Virtual environment: Different venv active ($$VIRTUAL_ENV)"; \
			echo "     Run 'deactivate' then 'source $(VENV)/bin/activate'"; \
		else \
			echo "  📁 Virtual environment: Ready but not activated"; \
			echo "     Run 'source $(VENV)/bin/activate' to activate"; \
		fi; \
	else \
		echo "  ❌ Virtual environment: Not found"; \
		echo "     Run 'make setup' to create and configure"; \
	fi

# Setup virtual environment and install package
setup: $(VENV)/bin/activate install
	@echo "✅ Project setup complete!"

$(VENV)/bin/activate:
	@echo "🔧 Creating virtual environment..."
	$(PYTHON) -m venv $(VENV)
	$(VENV_PIP) install --upgrade pip setuptools wheel

# Install package in development mode
install: $(VENV)/bin/activate
	@echo "📦 Installing MarkiTect in development mode..."
	$(VENV_PIP) install -e .

# Install with development dependencies
dev: install
	@echo "🛠️  Installing development dependencies..."
	$(VENV_PIP) install pytest pytest-cov black flake8 mypy

# Run tests
test: $(VENV)/bin/activate
	@echo "🧪 Running tests..."
	@if [ -f $(VENV)/bin/pytest ]; then \
		PYTHONPATH=. $(VENV)/bin/pytest tests/ -v; \
	else \
		PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ -v 2>/dev/null || \
		PYTHONPATH=. $(VENV_PYTHON) -m unittest discover tests/ -v; \
	fi

# Build the package
build: $(VENV)/bin/activate
	@echo "🏗️  Building package..."
	$(VENV_PYTHON) -m build 2>/dev/null || \
	$(VENV_PIP) install build && $(VENV_PYTHON) -m build

# Code linting
lint: $(VENV)/bin/activate
	@echo "🔍 Running linting..."
	@if [ -f $(VENV)/bin/flake8 ]; then \
		$(VENV)/bin/flake8 markitect/ tests/; \
	else \
		echo "⚠️  flake8 not installed. Run 'make dev' first."; \
	fi

# Code formatting
format: $(VENV)/bin/activate
	@echo "✨ Formatting code..."
	@if [ -f $(VENV)/bin/black ]; then \
		$(VENV)/bin/black markitect/ tests/; \
	else \
		echo "⚠️  black not installed. Run 'make dev' first."; \
	fi

# Update from upstream
update:
	@echo "🔄 Updating from upstream..."
	@git status --porcelain | grep -q . && echo "⚠️  Working directory not clean. Commit or stash changes first." && exit 1 || true
	git pull origin main
	git submodule update --remote
	@if git status --porcelain | grep -q "wiki"; then \
		echo "📝 Committing wiki submodule update..."; \
		git add wiki; \
		git commit -m "Update wiki submodule to latest"; \
	fi
	@echo "✅ Update complete!"

# Show git status
status:
	@echo "📊 Repository Status"
	@echo "==================="
	@echo ""
	@echo "Main Repository:"
	git status --short
	@echo ""
	@echo "Wiki Submodule:"
	@cd wiki && git status --short
	@echo ""
	@echo "Recent Commits:"
	git log --oneline -5

# Clean build artifacts
clean:
	@echo "🧹 Cleaning build artifacts..."
	rm -rf build/
	rm -rf dist/
	rm -rf *.egg-info/
	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
	find . -name "*.pyc" -delete 2>/dev/null || true
	@echo "✅ Clean complete!"

# Check dependency status
check-deps: $(VENV)/bin/activate
	@echo "📋 Dependency Status"
	@echo "==================="
	@echo ""
	@echo "Python version:"
	$(VENV_PYTHON) --version
	@echo ""
	@echo "Installed packages:"
	$(VENV_PIP) list
	@echo ""
	@echo "Project dependencies:"
	$(VENV_PIP) check

# Update project status digest (requires Claude Code)
update-digest:
	@echo "🔍 Checking for Claude Code availability..."
	@if ! command -v claude >/dev/null 2>&1; then \
		echo "❌ Claude Code not found in PATH"; \
		echo "   This target requires Claude Code CLI to be installed"; \
		echo "   Visit: https://claude.ai/code for installation instructions"; \
		exit 1; \
	fi
	@echo "✅ Claude Code found"
	@echo "📝 Updating ProjectStatusDigest.md..."
	@echo "   Please ask Claude Code to update the project digest based on current state"
	@echo "   Command: 'Please update ProjectStatusDigest.md with the current project state'"
	@echo ""
	@echo "💡 Tip: You can also manually edit ProjectStatusDigest.md if needed"

# Add new entry to project diary (requires Claude Code)
add-diary-entry:
	@echo "🔍 Checking for Claude Code availability..."
	@if ! command -v claude >/dev/null 2>&1; then \
		echo "❌ Claude Code not found in PATH"; \
		echo "   This target requires Claude Code CLI to be installed"; \
		echo "   Visit: https://claude.ai/code for installation instructions"; \
		exit 1; \
	fi
	@echo "✅ Claude Code found"
	@if [ ! -f ProjectDiary.md ]; then \
		echo "❌ ProjectDiary.md not found"; \
		echo "   Create the diary file first or run this from the project root"; \
		exit 1; \
	fi
	@echo "📖 Adding new entry to ProjectDiary.md..."
	@echo "   Please ask Claude Code to add a new diary entry for recent work"
	@echo "   Command: 'Please add a new entry to ProjectDiary.md summarizing recent progress'"
	@echo ""
	@echo "📋 Entry should include:"
	@echo "   - Date ($(shell date +%Y-%m-%d))"
	@echo "   - One-line progress characterization"
	@echo "   - Contributors since last entry"
	@echo "   - Time estimate and AI token usage"
	@echo "   - One paragraph work summary"
	@echo ""
	@echo "💡 Tip: New entries are added to the top for reverse chronological order"

# Git repository and API configuration
GITEA_URL := http://92.205.130.254:32166
REPO_OWNER := coulomb
REPO_NAME := markitect_project
ISSUES_API := $(GITEA_URL)/api/v1/repos/$(REPO_OWNER)/$(REPO_NAME)/issues

# Issue workspace configuration
WORKSPACE_DIR := .markitect_workspace
CURRENT_ISSUE_FILE := $(WORKSPACE_DIR)/current_issue.json

# List all gitea issues
list-issues: $(VENV)/bin/activate
	@PYTHONPATH=. $(VENV_PYTHON) tddai_cli.py list-issues

# Show detailed view of a specific issue
show-issue: $(VENV)/bin/activate
	@if [ -z "$(NUM)" ]; then \
		echo "❌ Please specify issue number: make show-issue NUM=5"; \
		exit 1; \
	fi
	@PYTHONPATH=. $(VENV_PYTHON) tddai_cli.py show-issue $(NUM)

# List only open issues (active backlog)
list-open-issues: $(VENV)/bin/activate
	@PYTHONPATH=. $(VENV_PYTHON) tddai_cli.py list-open-issues

# Generate test skeleton from gitea issue (requires Claude Code)
test-from-issue:
	@if [ -z "$(NUM)" ]; then \
		echo "❌ Please specify issue number: make test-from-issue NUM=1"; \
		exit 1; \
	fi
	@echo "🔍 Checking for Claude Code availability..."
	@if ! command -v claude >/dev/null 2>&1; then \
		echo "❌ Claude Code not found in PATH"; \
		echo "   This target requires Claude Code CLI to be installed"; \
		echo "   Visit: https://claude.ai/code for installation instructions"; \
		exit 1; \
	fi
	@echo "✅ Claude Code found"
	@echo "🔍 Checking for curl..."
	@if ! command -v curl >/dev/null 2>&1; then \
		echo "❌ curl not found - required for API access"; \
		exit 1; \
	fi
	@echo "✅ curl found"
	@echo "📋 Fetching issue #$(NUM) details..."
	@curl -s "$(ISSUES_API)/$(NUM)" | jq -r 'if .title then "✅ Issue #$(NUM): " + .title + "\n\n🧪 Generating test skeleton...\n   Please ask Claude Code to generate a test for this issue:\n\n   Command: '"'"'Generate a test skeleton for issue #$(NUM)'"'"'\n\n📋 Issue Details:\n   Title: " + .title + "\n   Description: " + .body + "\n\n📝 Test Requirements:\n   - Follow TDD principles (test first, then implementation)\n   - Use pytest framework (existing project convention)\n   - Place test in tests/ directory\n   - Name test file: test_issue_$(NUM)_*.py\n   - Include docstring referencing issue #$(NUM)\n   - Test should initially fail (red state)\n\n💡 After generation, run '"'"'make test'"'"' to verify test fails initially" else "❌ Issue #$(NUM) not found or API error\n   Use '"'"'make list-open-issues'"'"' to see available issues" end' 2>/dev/null || echo "❌ Issue #$(NUM) not found or API error"

# Start working on an issue (creates workspace)
tdd-start: $(VENV)/bin/activate
	@if [ -z "$(NUM)" ]; then \
		echo "❌ Please specify issue number: make tdd-start NUM=1"; \
		exit 1; \
	fi
	@PYTHONPATH=. $(VENV_PYTHON) tddai_cli.py start-issue $(NUM)

# Add test to current issue workspace
tdd-add-test: $(VENV)/bin/activate
	@PYTHONPATH=. $(VENV_PYTHON) tddai_cli.py add-test

# Show current workspace status
tdd-status: $(VENV)/bin/activate
	@PYTHONPATH=. $(VENV_PYTHON) tddai_cli.py workspace-status

# Complete issue work (move tests to main and cleanup)
tdd-finish: $(VENV)/bin/activate
	@PYTHONPATH=. $(VENV_PYTHON) tddai_cli.py finish-issue

# Show test status summary without re-running tests
test-status: $(VENV)/bin/activate
	@echo "📊 MarkiTect Test Status Summary"
	@echo "==============================="
	@echo ""
	@echo "📄 Test Files:"
	@find tests/ -name "test_*.py" -exec basename {} \; | sort | sed 's/^/   📝 /'
	@echo ""
	@echo "📊 Quick Stats:"
	@echo -n "   Total test files: "
	@find tests/ -name "test_*.py" | wc -l
	@echo ""
	@if [ -f ".pytest_cache/CACHEDIR.TAG" ]; then \
		echo "💾 Last Test Results (cached):"; \
		if [ -f ".pytest_cache/v/cache/lastfailed" ]; then \
			echo "   ❌ Recent failures detected"; \
			echo -n "   Failed tests: "; \
			cat .pytest_cache/v/cache/lastfailed | jq -r 'keys[]' 2>/dev/null | wc -l || echo "Unknown"; \
		else \
			echo "   ✅ No recent failures in cache"; \
		fi; \
		echo "   📁 Cache: .pytest_cache/ ($$(du -sh .pytest_cache/ 2>/dev/null | cut -f1 || echo 'Unknown size'))"; \
		if [ -f ".pytest_cache/README.md" ]; then \
			echo "   📅 Last run: $$(stat -c %y .pytest_cache/README.md 2>/dev/null | cut -d. -f1 || echo 'Unknown')"; \
		fi; \
	else \
		echo "❓ No test cache found - run 'make test' to generate results"; \
	fi
	@echo ""
	@echo "🔍 For detailed status:"
	@echo "   make test           # Run all tests with full output"
	@echo "   make test 2>&1 | grep -E 'PASSED|FAILED'  # Show only results"
	@echo ""
	@if [ -f "test_status_report.md" ]; then \
		echo "📋 Full Status Report: test_status_report.md"; \
		echo "   Last updated: $$(stat -c %y test_status_report.md 2>/dev/null || echo 'Unknown')"; \
	else \
		echo "💡 Generate detailed report with test run data"; \
	fi

# Create new test file template
test-new: $(VENV)/bin/activate
	@echo "🧪 Creating new test file"
	@echo "========================"
	@echo ""
	@read -p "Test name (e.g., feature_name): " test_name; \
	if [ -z "$$test_name" ]; then \
		echo "❌ Test name cannot be empty"; \
		exit 1; \
	fi; \
	test_file="tests/test_$$test_name.py"; \
	if [ -f "$$test_file" ]; then \
		echo "❌ Test file already exists: $$test_file"; \
		exit 1; \
	fi; \
	echo "📝 Creating: $$test_file"; \
	echo '"""' > "$$test_file"; \
	echo "Test for $$test_name functionality." >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "This test module validates [describe what you're testing]." >> "$$test_file"; \
	echo '"""' >> "$$test_file"; \
	echo "import pytest" >> "$$test_file"; \
	echo "from markitect import [import what you need]" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	class_name=$$(echo $$test_name | sed 's/_/ /g' | sed 's/\b\w/\U&/g' | sed 's/ //g'); \
	echo "class Test$$class_name:" >> "$$test_file"; \
	echo '    """Test suite for '$$test_name' functionality."""' >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "    def setup_method(self):" >> "$$test_file"; \
	echo '        """Set up test environment."""' >> "$$test_file"; \
	echo "        pass" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "    def teardown_method(self):" >> "$$test_file"; \
	echo '        """Clean up after tests."""' >> "$$test_file"; \
	echo "        pass" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "    def test_basic_functionality(self):" >> "$$test_file"; \
	echo '        """Test basic '$$test_name' functionality."""' >> "$$test_file"; \
	echo "        # Arrange" >> "$$test_file"; \
	echo "        # TODO: Set up test data" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "        # Act" >> "$$test_file"; \
	echo "        # TODO: Execute the functionality" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "        # Assert" >> "$$test_file"; \
	echo "        # TODO: Verify expected results" >> "$$test_file"; \
	echo "        assert True  # Replace with actual assertions" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "    def test_edge_cases(self):" >> "$$test_file"; \
	echo '        """Test edge cases for '$$test_name'."""' >> "$$test_file"; \
	echo "        # TODO: Test boundary conditions, empty inputs, etc." >> "$$test_file"; \
	echo "        pass" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "    def test_error_handling(self):" >> "$$test_file"; \
	echo '        """Test error handling for '$$test_name'."""' >> "$$test_file"; \
	echo "        # TODO: Test invalid inputs, exception cases" >> "$$test_file"; \
	echo "        pass" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "" >> "$$test_file"; \
	echo "if __name__ == '__main__':" >> "$$test_file"; \
	echo "    pytest.main([__file__, '-v'])" >> "$$test_file"; \
	echo "✅ Test file created: $$test_file"; \
	echo ""; \
	echo "🎯 Next steps:"; \
	echo "   1. Edit the test file to add your specific tests"; \
	echo "   2. Run: make test to check if it works"; \
	echo "   3. Implement the actual functionality"; \
	echo "   4. Run tests again to verify (TDD cycle)"

# Analyze test coverage for a specific issue
test-coverage: $(VENV)/bin/activate
	@if [ -z "$(NUM)" ]; then \
		echo "❌ Please specify issue number: make test-coverage NUM=5"; \
		exit 1; \
	fi
	@PYTHONPATH=. $(VENV_PYTHON) tddai_cli.py analyze-coverage $(NUM)