Code Veil Analyzer

Detect hidden architectural risk and maintainability illusions in codebases.

Idea

Clean-looking code is not always maintainable. Code Veil Analyzer surfaces deterministic signals such as fake modularity, wrapper inflation, duplicate intent, shallow abstractions, over-fragmentation, and architectural camouflage.

Environment

This project uses mise.

mise exec -- python -V
mise exec -- python -m pip install -e '.[dev]'
mise exec -- pytest
mise exec -- ruff check .
mise exec -- ruff format --check .
mise exec -- mypy src

Usage

mise exec -- code-veil analyze PATH
mise exec -- code-veil analyze PATH --format text
mise exec -- code-veil analyze PATH --format json
mise exec -- code-veil analyze PATH --output report.json
mise exec -- code-veil analyze PATH --min-severity medium
mise exec -- code-veil analyze PATH --include-fixtures
mise exec -- code-veil analyze PATH --ai
mise exec -- python -m code_veil analyze PATH

Repository-level scans exclude tests/fixtures/** by default so self-analysis is not inflated by test data. Use --include-fixtures to analyze fixtures as part of a repo scan. Direct analysis of a fixture path still works.

Optional AI interpretation

Deterministic analysis works without OpenAI. With --ai and OPENAI_API_KEY, the tool may add validated interpretation JSON. AI output never replaces deterministic scoring.

Development

mise run check
mise exec -- code-veil analyze tests/fixtures/clean_project
mise exec -- code-veil analyze tests/fixtures/illusion_project --format json

Limitations

See context/foundation/limitations.md. Heuristics are review signals, not verdicts. Python-focused MVP.

AI execution pack

Prompt workflow for generating or extending this tool lives under prompts/. Start with prompts/PHASE_BY_PHASE_IMPLEMENTATION_PROMPT.md for incremental builds.