Qlty Code Quality Setup for EMTB Monorepo

Overview

Qlty is a comprehensive code quality platform that integrates multiple analysis tools into a single, unified workflow. This document covers the complete setup and configuration for the EMTB tax claim management system monorepo.

🏗️ Architecture

Monorepo Structure Coverage

Our Qlty configuration covers all applications and documentation:

emtb/
├── apps/
│   ├── frontend/          # Next.js + TypeScript + React
│   ├── api/              # NestJS + TypeScript + Prisma
│   └── e2e/              # Playwright tests
├── docs/                 # Project documentation
├── docs-site/            # Docusaurus documentation site
├── .qlty/
│   └── qlty.toml        # Main configuration file
└── .github/workflows/
    └── qlty.yml         # CI/CD integration

Quality Gates by Component

Component	ESLint	Prettier	TypeScript	Security	Documentation
Frontend	✅	✅	✅	✅	❌
API	✅	✅	✅	✅	❌
E2E Tests	❌	❌	✅	✅	❌
Documentation	❌	✅	❌	❌	✅
Infrastructure	❌	❌	❌	✅	✅

🔧 Local Development Setup

Prerequisites

Node.js 18+ - Required for plugin execution
pnpm - Package manager (already configured)
Qlty CLI - Install using the official installer

Installation

# Install Qlty CLI
curl -s https://download.qlty.sh/qlty/install.sh | sh

# Add to PATH (add to your shell profile)
echo 'export PATH="$HOME/.qlty/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify installation
qlty --version

Initial Setup

# From project root
cd /Users/ayoub/projects/emtb

# Initialize Qlty (will use our existing .qlty/qlty.toml)
qlty init

# Install plugin dependencies
pnpm install --frozen-lockfile

🚀 Usage

Local Analysis

# Run full analysis on entire repository
qlty check

# Analyze specific application
qlty check apps/frontend/
qlty check apps/api/
qlty check apps/e2e/

# Analyze only changed files (great for development)
qlty check --diff

# Run specific plugins only
qlty check --plugins eslint,prettier
qlty check --plugins checkov,trivy,trufflehog  # Security only

# Generate detailed report
qlty check --format json > qlty-report.json

Plugin Management

# List available plugins
qlty plugins list

# Enable new plugin
qlty plugins enable <plugin-name>

# Disable plugin
qlty plugins disable <plugin-name>

# Update plugins
qlty plugins update

Code Smell Analysis

# Detect code smells
qlty smell

# Analyze specific languages
qlty smell --language typescript
qlty smell --language javascript

# Custom complexity thresholds
qlty smell --function-complexity 20

⚙️ Configuration Details

Configuration Approach

Our qlty configuration uses the simplified default template approach for better reliability:

Plugin Management: Uses package_file with package_filters instead of extra_packages
Source Configuration: Uses default qlty plugin source with [[source]]
Minimal Overrides: Only configures what's necessary, letting qlty handle defaults
Reliability First: Prioritizes working configuration over extensive customization

Important: This simplified approach was adopted after initial complex configurations failed due to plugin availability issues. The current setup provides reliable code quality analysis while maintaining monorepo support.

Plugin Configuration

Frontend (Next.js + React + TypeScript)

ESLint: v8.57.0 with React, Next.js, and TypeScript rules
Prettier: v3.4.2 for consistent formatting
TypeScript: Built-in analysis for type safety
Mode: comment - Post PR comments, don't block

API (NestJS + TypeScript)

ESLint: v8.57.0 with NestJS and TypeScript rules
Prettier: v3.4.2 for consistent formatting
TypeScript: Built-in analysis with strict mode
Mode: comment - Post PR comments, don't block

Security (All Applications)

Trivy: Container and dependency vulnerabilities
TruffleHog: Secrets detection
OSV Scanner: Open source vulnerabilities
Mode: block - Fail CI for security issues
Note: Simplified configuration using qlty defaults for better reliability

Documentation

MarkdownLint: Markdown quality and consistency
Prettier: Formatting for YAML and JSON
YAMLLint: YAML syntax validation (includes GitHub Actions workflows)
Mode: comment - Suggest improvements

Note: The actionlint plugin for GitHub Actions workflow linting is currently disabled due to availability issues in the qlty plugin registry. YAMLLint provides basic YAML validation for workflow files.

Quality Thresholds

Code Complexity

[smells]
function_complexity.threshold = 15      # Max cyclomatic complexity
file_complexity.threshold = 50          # Max file complexity
nested_control_flow.threshold = 5       # Max nested levels
boolean_logic.threshold = 5             # Max boolean operators
function_parameters.threshold = 5       # Max parameters
return_statements.threshold = 6         # Max return statements

Duplication Detection

[smells.duplication]
threshold = 12                          # Min lines for duplication
nodes_threshold = 50                    # Min AST nodes

Language-Specific Overrides

[language.typescript.smells]
function_complexity.threshold = 20      # Higher for TypeScript
function_parameters.threshold = 6       # Allow more params
duplication.nodes_threshold = 60        # More lenient duplication

Exclusion Patterns

Global Exclusions

**/node_modules/** - Dependencies
**/dist/**, **/.next/** - Build artifacts
**/coverage/** - Test coverage files
**/*.min.js - Minified files
**/prisma/migrations/** - Auto-generated migrations

Plugin-Specific Exclusions

ESLint/Prettier: Config files (*.config.*)
TypeScript: JavaScript config files
MarkdownLint: Auto-generated documentation

Triage Rules

Priority Levels

High: Security vulnerabilities (block CI)
Medium: TypeScript strict mode violations
Low: Test files, documentation, style issues

Mode Assignment

Block: Security plugins only
Comment: Code quality and formatting
Monitor: Dependency scanning
Disabled: None (all plugins enabled)

🔄 CI/CD Integration

GitHub Actions Workflow

Our Qlty workflow (.github/workflows/qlty.yml) provides:

Change Detection: Only analyze modified applications
Parallel Execution: Multiple analysis jobs for efficiency
Targeted Analysis: App-specific analysis for PRs
Security Always: Security analysis on every commit
Result Aggregation: Combined status reporting

Workflow Triggers

on:
  push:
    branches: [main, develop] # Full analysis
  pull_request:
    branches: [main, develop] # Targeted + security analysis

Analysis Strategy

Trigger	Analysis Type	Coverage	Blocking
Push to main/develop	Full Repository	All files	Security only
Pull Request	Targeted	Changed files	Security only
Config Changes	Full Repository	All files	Security only
Documentation Changes	Documentation	Docs only	Never

Performance Optimization

Concurrency Control: One analysis per branch
Dependency Caching: pnpm cache for faster setup
Conditional Execution: Skip unchanged applications
Parallel Jobs: Multiple analysis streams

🔍 Monitoring and Reports

Pull Request Integration

Qlty automatically posts comments on pull requests with:

Code quality issues found
Security vulnerabilities detected
Suggestions for improvements
Links to detailed reports

Status Checks

✅ Qlty Security: Must pass (blocking)
⚠️ Qlty Quality: Informational only
📝 Qlty Documentation: Suggestions only

Report Generation

# Generate comprehensive report
qlty check --format json --output qlty-report.json

# HTML report for sharing
qlty check --format html --output qlty-report.html

# Metrics dashboard data
qlty metrics --format json

🛠️ Troubleshooting

Common Issues

Plugin Installation Failures

# Clear plugin cache
rm -rf ~/.qlty/cache

# Reinstall plugins
qlty plugins update

# Check plugin versions
qlty plugins list --verbose

TypeScript Analysis Issues

# Ensure dependencies are installed
pnpm install --frozen-lockfile

# Generate Prisma client (for API)
cd apps/api && npx prisma generate

# Check TypeScript configuration
npx tsc --noEmit

Performance Issues

# Analyze smaller scope
qlty check apps/frontend/ --plugins eslint,prettier

# Use diff mode for development
qlty check --diff

# Exclude large directories temporarily
qlty check --exclude "**/node_modules/**"

Debug Mode

# Enable debug logging
export QLTY_LOG_LEVEL=debug
qlty check --verbose

# Check configuration parsing
qlty config validate

# Test specific plugins
qlty plugins test eslint --file apps/frontend/components/auth/SignIn.tsx

CI/CD Debugging

# Local CI simulation
export GITHUB_TOKEN=<your-token>
qlty check --reporter github-actions

# Validate workflow
gh workflow run qlty.yml --ref <branch-name>

# Check workflow logs
gh run list --workflow=qlty.yml

📊 Metrics and Analytics

Code Quality Metrics

Technical Debt Ratio: Time to fix / Development time
Duplication Percentage: Duplicated lines / Total lines
Complexity Score: Average cyclomatic complexity
Security Risk Score: High/Medium/Low issue counts

Tracking Progress

# Generate trend report
qlty metrics --since 30d --format json > metrics-trend.json

# Compare branches
qlty check --baseline main --compare feature-branch

# Export to external systems
qlty check --format sarif > qlty-results.sarif

🔄 Maintenance

Regular Updates

# Monthly plugin updates
qlty plugins update

# Review and adjust thresholds quarterly
vim .qlty/qlty.toml

# Update Qlty CLI
curl -s https://download.qlty.sh/qlty/install.sh | sh

Configuration Evolution

Start Conservative: mode = "comment" for all plugins
Gradual Enforcement: Move critical rules to mode = "block"
Threshold Adjustment: Lower complexity limits over time
New Plugin Integration: Add security and performance tools

🚀 Advanced Usage

Custom Plugins

# Create custom plugin source
[sources.emtb-custom]
repository = "https://github.com/emtb/qlty-plugins.git"
branch = "main"

# Use custom plugin
[[plugin]]
name = "emtb-tax-rules"
source = "emtb-custom"

Integration with IDE

# VS Code extension (if available)
code --install-extension qlty.qlty-vscode

# Vim plugin
# Add to .vimrc: Plugin 'qlty/vim-qlty'

# Manual integration
qlty check --format json | jq '.issues[]'

Webhook Integration

# Configure webhook for external systems
export QLTY_WEBHOOK_URL="https://your-system.com/webhooks/qlty"
qlty check --webhook

📚 Additional Resources

For support or questions about Qlty configuration, contact the development team or refer to the official Qlty documentation.

Overview​

🏗️ Architecture​

Monorepo Structure Coverage​

Quality Gates by Component​

🔧 Local Development Setup​

Prerequisites​

Installation​

Initial Setup​

🚀 Usage​

Local Analysis​

Plugin Management​

Code Smell Analysis​

⚙️ Configuration Details​

Configuration Approach​

Plugin Configuration​

Frontend (Next.js + React + TypeScript)​

API (NestJS + TypeScript)​

Security (All Applications)​

Documentation​

Quality Thresholds​

Code Complexity​

Duplication Detection​

Language-Specific Overrides​

Exclusion Patterns​

Global Exclusions​

Plugin-Specific Exclusions​

Triage Rules​

Priority Levels​

Mode Assignment​

🔄 CI/CD Integration​

GitHub Actions Workflow​

Workflow Triggers​

Analysis Strategy​

Performance Optimization​

🔍 Monitoring and Reports​

Pull Request Integration​

Status Checks​

Report Generation​

🛠️ Troubleshooting​

Common Issues​

Plugin Installation Failures​

TypeScript Analysis Issues​

Performance Issues​

Debug Mode​

CI/CD Debugging​

📊 Metrics and Analytics​

Code Quality Metrics​

Tracking Progress​

🔄 Maintenance​

Regular Updates​

Configuration Evolution​

🚀 Advanced Usage​

Custom Plugins​

Integration with IDE​

Webhook Integration​

📚 Additional Resources​