gh-marcioaltoe-claude-craftkit-plugins-quality/commands/check.md

description

description
Run complete quality gates workflow (craft → format → lint → type-check → test)

Quality Gates

Execute the complete quality gates workflow to ensure code quality before committing.

What This Does

Runs the following sequence in order:

1. Barrel Files (bun run craft) - Generate/update barrel files
2. Format (bun run format) - Format code with Biome + Prettier
3. Lint (bun run lint) - Lint code with Biome
4. Type Check (bun run type-check) - TypeScript type checking
5. Tests (bun run test) - Run all tests

When to Use

Run quality gates:

• ✅ Before committing code
• ✅ After implementing a feature
• ✅ After fixing bugs
• ✅ Before creating a pull request
• ✅ After resolving merge conflicts
• ✅ Before pushing to remote

Instructions

1. Check current status:

   git status
   

2. Run quality gates:

   bun run quality
   

3. Review output:

   • Each step will show its results
   • Process stops on first failure
   • Fix any issues reported

4. Fix issues if needed:

   # Fix formatting issues
   bun run format
   
   # Fix linting issues (safe)
   bun run lint
   
   # Fix linting issues (aggressive)
   bun run lint:fix
   
   # Check TypeScript errors
   bun run type-check
   
   # Run tests
   bun run test
   

5. Re-run quality gates:

   bun run quality
   

6. Commit when all pass:

   git add .
   git commit -m "feat: your feature description"
   

Expected Output

✅ Success

→ Running quality gates...

[1/5] Generating barrel files...
✅ Generated 10 barrel file(s)

[2/5] Formatting code...
✅ Code formatted successfully

[3/5] Linting code...
✅ No lint errors found

[4/5] Type checking...
✅ No type errors found

[5/5] Running tests...
✅ All tests passed (15 passed, 15 total)

✅ Quality gates passed! Ready to commit.

❌ Failure Examples

Format Errors:

[2/5] Formatting code...
❌ Formatting issues found in:
  - src/utils/helper.ts
  - src/components/button.tsx

Fix with: bun run format

Lint Errors:

[3/5] Linting code...
❌ Lint errors found:
  - src/services/api.ts:15:3 - Unused variable 'response'
  - src/utils/validator.ts:42:1 - Missing return type

Fix with: bun run lint:fix

Type Errors:

[4/5] Type checking...
❌ TypeScript errors found:
  src/models/user.ts:23:5 - Type 'string' is not assignable to type 'number'
  src/services/auth.ts:45:12 - Property 'email' does not exist on type 'User'

Fix these errors manually, then run type-check again

Test Failures:

[5/5] Running tests...
❌ Tests failed:
  ✓ UserService > creates user (2ms)
  ✗ UserService > validates email (5ms)
    Expected: true
    Received: false

  1 test failed, 14 passed (15 total)

Fix the failing tests and run: bun run test

Common Issues

Issue: Barrel files conflict

Problem:

Barrel file generation failed - conflicting index.ts found

Solution:

# Review and clean old barrel files
bun run craft:clean --dry-run

# If safe, clean them
bun run craft:clean

# Regenerate
bun run craft

Issue: Format and lint conflicts

Problem:

Format and lint producing different results

Solution:

# Run format first (always)
bun run format

# Then lint
bun run lint:fix

# Check again
bun run quality

Issue: Type errors after refactoring

Problem:

Multiple type errors after code changes

Solution:

# Run type check with details
bun run type-check

# Fix errors one by one
# Re-check after each fix
bun run type-check

Issue: Tests timing out

Problem:

Tests failing with timeout errors

Solution:

# Run tests with increased timeout
bun run test --test-timeout=30000

# Or update vitest.config.ts:
# test: {
#   testTimeout: 30000
# }

Individual Commands

If you need to run steps individually:

# Step 1: Barrel files
bun run craft

# Step 2: Format
bun run format

# Step 3: Lint
bun run lint

# Step 4: Type check
bun run type-check

# Step 5: Tests
bun run test

Pre-commit Hook

Quality gates (format + lint-staged) run automatically on commit via Husky:

git commit -m "feat: new feature"

# Automatically runs:
# → Pre-commit: quality gates (format, lint-staged)
# ✓ Pre-commit: todas as verificações passaram

Note: Pre-commit runs a lighter version:

• ✅ Format
• ✅ Lint-staged (only staged files)

Full quality gates (including type-check and tests) should be run manually before pushing.

CI/CD Integration

Quality gates should also run in your CI/CD pipeline:

# .github/workflows/quality.yml
name: Quality Checks

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1
      - run: bun install
      - run: bun run quality

Best Practices

1. Run before every commit:

   • Catches issues early
   • Prevents broken commits
   • Maintains code quality

2. Fix issues immediately:

   • Don't accumulate technical debt
   • Small fixes are easier
   • Keeps codebase clean

3. Use in development workflow:

   # During development
   bun run format  # Format as you go
   
   # Before commit
   bun run quality  # Full check
   
   # Commit
   git commit -m "feat: feature name"
   

4. Run after merges:

   git merge dev
   bun run quality  # Ensure no conflicts
   git push
   

5. Keep scripts up to date:

   • Review package.json scripts
   • Update configurations
   • Maintain documentation

Script Configuration

Ensure your package.json has these scripts:

{
  "scripts": {
    "craft": "barrel-craft",
    "craft:clean": "barrel-craft clean --force",
    "format": "biome format --write . && bun run format:md && bun run format:pkg",
    "format:md": "prettier --write '**/*.md' --log-level error",
    "format:pkg": "prettier-package-json --write package.json --log-level error",
    "lint": "biome check --write .",
    "lint:fix": "biome check --write . --unsafe",
    "type-check": "tsc --noEmit",
    "test": "vitest run",
    "test:watch": "vitest",
    "test:coverage": "vitest run --coverage",
    "quality": "bun run craft && bun run format && bun run lint && bun run type-check && bun run test"
  }
}

Troubleshooting

Quality gates won't run

# Check if scripts exist
cat package.json | grep -A 1 '"quality"'

# Check if dependencies are installed
bun install

# Run with verbose output
bun run quality --verbose

Command not found errors

# Install missing tools
bun add -D @biomejs/biome prettier barrel-craft

# Install TypeScript if needed
bun add -D typescript

Permission issues

# Make sure node_modules/.bin is accessible
chmod +x node_modules/.bin/*

# Or use bunx
bunx barrel-craft
bunx biome check .

Summary

Quality gates ensure:

• ✅ Clean, organized imports (barrel files)
• ✅ Consistent code formatting
• ✅ No linting errors
• ✅ No type errors
• ✅ All tests passing

Run bun run quality before every commit to maintain high code quality standards!