[CHORE]: Fix all Makefile targets to work without pre-activated venv and check for OS depends

[crivetimihai]

🔧 Chore Description

Description:
Several Makefile targets fail because they either check for system commands that don't exist, call tools directly without proper venv handling, or expect system utilities to be pre-installed. These need to be fixed to either use venv properly or handle missing system dependencies gracefully.

This means you no longer need to activate your venv before running all Makefile targets.

📋 Actual Broken Targets

After re-evaluation, here are the targets that actually need fixing:

Targets with Incorrect Command Checks

• tomllint - Checks for system tomlcheck with command -v then fails, should install in venv first
• yamllint - Checks for system yamllint with command -v then fails, should install in venv first
• jsonlint - Expects system jq to be installed, no venv option

Targets Calling Tools Directly (No Venv)

• wily - Calls wily directly without $(VENV_DIR)/bin/
• depend - Calls pdm directly
• snakeviz - Calls python3 and snakeviz directly
• pstats - Calls python3 and gprof2dot directly
• docs - Calls uv handsdown directly
• images - Calls code2flow, dot, pyreverse directly (mix of venv and system tools)

System Tools That Need Better Error Handling

• scc / scc-report - Calls system scc directly
• grype-scan / grype-sarif - Calls system grype directly
• trivy - Calls system trivy directly
• dockle - Calls system dockle directly
• hadolint - Calls system hadolint directly
• osv-scan-source / osv-scan-image - Calls system osv-scanner directly
• shell-lint - Calls system shfmt and shellcheck directly

🔧 Fix Examples

1. Fix tomllint (venv-based tool):

Current (broken):

tomllint:
	@command -v tomlcheck >/dev/null 2>&1 || { \
	  echo '❌  tomlcheck not installed  ➜  pip install tomlcheck'; exit 1; }
	@echo '📑  tomllint (tomlcheck) ...'
	@find . -type f -name '*.toml' -print0 \
	  | xargs -0 -I{} $(VENV_DIR)/bin/tomlcheck "{}"

Fixed:

tomllint:
	@echo '📑  tomllint (tomlcheck) ...'
	@test -d "$(VENV_DIR)" || $(MAKE) venv
	@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
		python3 -m pip install -q tomlcheck 2>/dev/null || true"
	@find . -type f -name '*.toml' -print0 \
	  | xargs -0 -I{} $(VENV_DIR)/bin/tomlcheck "{}"

2. Fix yamllint (venv-based tool):

Fixed:

yamllint:
	@echo '📑  yamllint ...'
	@test -d "$(VENV_DIR)" || $(MAKE) venv
	@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
		python3 -m pip install -q yamllint 2>/dev/null || true"
	@$(VENV_DIR)/bin/yamllint -c .yamllint .

3. Fix wily:

Fixed:

wily:
	@echo "📈  Maintainability report..."
	@test -d "$(VENV_DIR)" || $(MAKE) venv
	@git stash --quiet
	@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
		python3 -m pip install -q wily && \
		python3 -m wily build -n 10 . > /dev/null || true && \
		python3 -m wily report . || true"
	@git stash pop --quiet

4. Fix depend:

Fixed:

depend:
	@test -d "$(VENV_DIR)" || $(MAKE) venv
	@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
		python3 -m pip install -q pdm && \
		pdm list --freeze"

5. Fix system tools with better error messages:

Fixed trivy:

trivy:
	@command -v trivy >/dev/null 2>&1 || { \
		echo "❌ trivy not installed."; \
		echo "💡 Install with:"; \
		echo "   • macOS: brew install trivy"; \
		echo "   • Linux: curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin"; \
		echo "   • Or run: make trivy-install"; \
		exit 1; \
	}
	@systemctl --user enable --now podman.socket 2>/dev/null || true
	@echo "🔎  trivy vulnerability scan..."
	@trivy --format table --severity HIGH,CRITICAL image $(IMG)

6. Fix docs target:

Fixed:

docs: images sbom
	@echo "📚  Generating documentation with handsdown..."
	@test -d "$(VENV_DIR)" || $(MAKE) venv
	@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
		python3 -m pip install -q handsdown && \
		python3 -m handsdown --external https://github.com/yourorg/$(PROJECT_NAME)/ \
		         -o $(DOCS_DIR)/docs \
		         -n app --name '$(PROJECT_NAME)' --cleanup"
	# ... rest of the target

7. Fix snakeviz:

Fixed:

snakeviz:
	@echo "🐍  Interactive profile visualiser..."
	@test -d "$(VENV_DIR)" || $(MAKE) venv
	@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
		python3 -m pip install -q snakeviz && \
		python3 -m cProfile -o mcp.prof mcpgateway/server.py && \
		python3 -m snakeviz mcp.prof --server"

📋 Summary of Issues

1. Venv-installable tools (tomllint, yamllint, wily, etc.) - Should auto-install in venv
2. System tools (trivy, grype, scc, etc.) - Should provide helpful install instructions
3. Direct python calls - Should use venv's python
4. Missing pip installs - Some targets assume packages are pre-installed

✅ Quick Fix for All Python Tools

Add this helper function at the top of the Makefile:

# Helper to ensure a Python package is installed in venv
define ensure_pip_package
	@test -d "$(VENV_DIR)" || $(MAKE) venv
	@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
		python3 -m pip show $(1) >/dev/null 2>&1 || \
		python3 -m pip install -q $(1)"
endef

Then use it like:

yamllint:
	@echo '📑  yamllint ...'
	$(call ensure_pip_package,yamllint)
	@$(VENV_DIR)/bin/yamllint -c .yamllint .