elixir-quality-gate

This skill runs comprehensive quality checks on Elixir/Phoenix projects following best practices.

When to Use

• Before creating commits
• After implementing new features
• Before merging pull requests
• When preparing for deployment
• During code reviews

Quality Checks Performed

1. Code Formatting

mix format --check-formatted

• Validates all files are properly formatted
• Fails fast if formatting issues found
• Shows which files need formatting

2. Compilation

mix compile --warnings-as-errors

• Ensures clean compilation
• Treats warnings as errors
• Catches unused variables, deprecated functions

3. Static Analysis (Credo)

mix credo --strict

• Runs strict code quality checks
• Checks for consistency, design issues, readability
• Reports refactoring opportunities

4. Type Checking (Dialyzer)

mix dialyzer

• Performs static type analysis
• Builds PLT (Persistent Lookup Table) if needed
• First run takes 1-2 minutes, subsequent runs are fast
• Catches type errors and inconsistencies

5. Test Suite

mix test

• Runs full test suite
• Reports coverage if configured
• Shows failures and pending tests

Usage Pattern

Full Quality Gate (Recommended)

Run all checks in sequence:

mix format --check-formatted && \
mix compile --warnings-as-errors && \
mix credo --strict && \
mix dialyzer && \
mix test

Quick Check (Pre-commit)

If project has a precommit alias:

mix precommit

Individual Checks

Run specific checks when iterating:

# Just format
mix format

# Just tests
mix test

# Specific test file
mix test test/my_app/accounts_test.exs

# Just credo
mix credo --strict

Error Handling

Format Failures:

• Read the output to see which files need formatting
• Run mix format to fix automatically
• Re-run checks

Compilation Warnings:

• Read warnings carefully
• Common issues: unused variables (prefix with _), deprecated functions
• Fix warnings before proceeding

Credo Issues:

• Review suggested improvements
• Refactoring opportunities are optional but recommended
• Design and consistency issues should be addressed

Dialyzer Errors:

• First run builds PLT (takes time, this is normal)
• Type errors indicate potential runtime bugs
• Use @spec annotations to guide Dialyzer

Test Failures:

• Read failure messages carefully
• Run failing test in isolation: mix test test/path/to/test.exs:LINE
• Fix failures before proceeding

Best Practices

1. Run locally before pushing - Catch issues early
2. Fix formatting first - It's the fastest fix
3. Don't ignore warnings - They often indicate real problems
4. Keep PLT cached - Add priv/plts/ to .gitignore
5. Run full suite before PR - Don't rely only on CI

Environment Variables

# Run in test environment
MIX_ENV=test mix dialyzer

# Skip dialyzer if building PLT takes too long locally
mix format && mix compile --warnings-as-errors && mix credo --strict && mix test

Exit Codes

• 0: All checks passed
• Non-zero: At least one check failed (stops at first failure with &&)

Integration with Git Hooks

If using BMAD git hooks, these checks run automatically on:

• pre-commit: Full quality gate
• pre-push: Quick validation

Troubleshooting

PLT build fails:

# Clean and rebuild
rm -rf _build priv/plts
mix deps.get
mix dialyzer --plt

Tests fail in CI but pass locally:

• Check MIX_ENV (should be test)
• Verify database is created: MIX_ENV=test mix ecto.create
• Check for async test conflicts

Credo reports too many issues:

• Start with formatting and compilation
• Fix high-priority issues first
• Consider configuring .credo.exs to match team preferences