create-qa-architect 5.0.0 → 5.0.1

package/templates/QUALITY_TROUBLESHOOTING.md

@@ -0,0 +1,403 @@
+# Quality Troubleshooting Guide
+
+**Auto-generated by create-qa-architect to prevent production issues**
+
+## 🚨 Critical Issues That Caused Production Failures
+
+### TypeScript Errors in Tests
+
+**Symptom**: Tests pass locally but TypeScript compilation fails in CI
+**Root Cause**: Tests excluded from TypeScript checking in `tsconfig.json`
+
+```bash
+# Check if tests are TypeScript validated
+npm run type-check:tests
+
+# If command doesn't exist, add to package.json:
+{
+  "scripts": {
+    "type-check:tests": "tsc --noEmit --project tests/tsconfig.json"
+  }
+}
+```
+
+**Fix**: Ensure `tests/tsconfig.json` exists:
+
+```json
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "..",
+    "noEmit": true,
+    "types": ["vitest/globals", "node"]
+  },
+  "include": ["../src/**/*", "../tests/**/*"]
+}
+```
+
+**Prevention**: Run `npm run quality:check` before commits
+
+### Pre-commit Hooks Too Narrow
+
+**Symptom**: Broken code reaches GitHub despite pre-commit hooks
+**Root Cause**: lint-staged only checks specific files (like CLAUDE.md)
+
+```bash
+# Check what runs on commit
+cat .husky/pre-commit
+
+# Should run comprehensive checks:
+npx lint-staged && npm run type-check:all && npm test
+```
+
+**Fix**: Enhance `.husky/pre-commit`:
+
+```bash
+#!/usr/bin/env sh
+npx lint-staged
+npm run type-check:all
+npm run test:fast
+```
+
+## 🔍 Diagnostic Commands
+
+### Quick Health Check
+
+```bash
+# Run all quality gates (should complete without errors)
+npm run quality:check
+
+# If this fails, debug individual components:
+npm run type-check:all      # TypeScript issues
+npm run lint               # ESLint issues
+npm run format:check       # Prettier issues
+npm test                   # Test failures
+npm run security:audit     # Security vulnerabilities
+```
+
+### TypeScript Troubleshooting
+
+```bash
+# Check main source TypeScript
+npm run type-check
+
+# Check tests TypeScript (common failure point)
+npm run type-check:tests
+
+# Check specific file
+npx tsc --noEmit path/to/file.ts
+
+# Common issues:
+# 1. Missing type definitions: npm install --save-dev @types/package-name
+# 2. Test globals: Add "vitest/globals" to types in tsconfig
+# 3. Node types: Add "node" to types array
+```
+
+### Test Troubleshooting
+
+```bash
+# Run tests with verbose output
+npm test -- --reporter=verbose
+
+# Run specific test file
+npx vitest path/to/test.test.js
+
+# Debug integration tests
+DEBUG=* npm run test:integration
+
+# Common issues:
+# 1. Test environment: Check NODE_ENV=test
+# 2. Database setup: Ensure test DB is available
+# 3. Async issues: Use proper async/await in tests
+```
+
+### Linting Issues
+
+```bash
+# Check specific linting rules
+npx eslint path/to/file.js --format=verbose
+
+# Auto-fix issues
+npm run lint:fix
+
+# Security-specific linting
+npx eslint . --ext .js,.ts --config eslint-security.config.js
+
+# Common issues:
+# 1. Security rules: Remove hardcoded secrets, sanitize inputs
+# 2. TypeScript rules: Fix any types, unused variables
+# 3. Style rules: Use consistent naming, indentation
+```
+
+## 🏗️ Project-Specific Issues
+
+### API Service Projects
+
+```bash
+# Database connection tests
+npm run test:integration
+
+# API endpoint tests
+npm run test:e2e
+
+# Common issues:
+# 1. Database not running: docker-compose up db
+# 2. Environment variables missing: cp .env.example .env.test
+# 3. Migrations not run: npm run db:migrate:test
+```
+
+### Frontend Projects
+
+```bash
+# Component integration tests
+npm run test:component
+
+# Browser E2E tests
+npm run test:e2e
+
+# Accessibility checks
+npm run accessibility:check
+
+# Common issues:
+# 1. Build process: npm run build && npm run test:e2e
+# 2. Browser drivers: npx playwright install
+# 3. Test server: Ensure dev server running for E2E
+```
+
+### Library Projects
+
+```bash
+# Build and test distribution
+npm run build && npm pack && tar -tf *.tgz
+
+# Test TypeScript definitions
+npm run type-check && tsc --noEmit --skipLibCheck
+
+# Common issues:
+# 1. Export paths: Check package.json main/module/exports
+# 2. Type definitions: Ensure .d.ts files are included
+# 3. Dependencies: Check peerDependencies vs dependencies
+```
+
+## ⚡ Performance Issues
+
+### Slow Test Suite
+
+```bash
+# Profile test performance
+npm test -- --reporter=verbose --logHeapUsage
+
+# Run only fast tests for development
+npm run test:fast
+
+# Optimize strategies:
+# 1. Use test.concurrent for independent tests
+# 2. Mock external dependencies
+# 3. Use beforeAll for expensive setup
+```
+
+### Slow Linting
+
+```bash
+# Profile ESLint performance
+npx eslint . --debug
+
+# Use cache for faster subsequent runs
+npx eslint . --cache --cache-location .eslintcache
+
+# Optimize strategies:
+# 1. Exclude node_modules explicitly
+# 2. Use .eslintignore for generated files
+# 3. Run lint-staged for incremental checking
+```
+
+### Slow CI/CD
+
+```bash
+# Check what's running in CI
+cat .github/workflows/quality.yml
+
+# Optimize strategies:
+# 1. Cache dependencies: actions/cache@v3
+# 2. Parallel jobs for independent checks
+# 3. Smart test strategy based on changed files
+```
+
+## 🔧 Configuration Debugging
+
+### ESLint Configuration
+
+```bash
+# Check which config is being used
+npx eslint --print-config path/to/file.js
+
+# Debug configuration issues
+npx eslint --debug path/to/file.js
+
+# Common issues:
+# 1. Conflicting configs: Check eslint.config.js vs .eslintrc
+# 2. Plugin missing: npm install eslint-plugin-name
+# 3. Parser issues: Check @typescript-eslint/parser for TS
+```
+
+### Prettier Configuration
+
+```bash
+# Check formatting without changing files
+npx prettier --check .
+
+# See what would be formatted
+npx prettier --list-different .
+
+# Common issues:
+# 1. Conflicting configs: .prettierrc vs package.json prettier
+# 2. Parser detection: Use --parser option for ambiguous files
+# 3. Ignore patterns: Check .prettierignore
+```
+
+### Husky/lint-staged Issues
+
+```bash
+# Check if Husky is installed
+ls -la .husky/
+
+# Test pre-commit hook manually
+./.husky/pre-commit
+
+# Test lint-staged configuration
+npx lint-staged --debug
+
+# Common issues:
+# 1. Executable permissions: chmod +x .husky/pre-commit
+# 2. Git hooks not installed: npx husky install
+# 3. Pattern matching: Check lint-staged glob patterns
+```
+
+## 🛡️ Security Debugging
+
+### Secret Scanning Issues
+
+```bash
+# Run secret detection
+npm run security:secrets
+
+# Advanced secret scanning
+npx gitleaks detect --verbose
+
+# Common issues:
+# 1. False positives: Add to .gitleaksignore
+# 2. Test secrets: Use clearly marked dummy values
+# 3. Environment files: Never commit .env files
+```
+
+### Dependency Vulnerabilities
+
+```bash
+# Check for vulnerabilities
+npm audit
+
+# Fix automatically fixable issues
+npm audit fix
+
+# Check specific package
+npm audit --package=package-name
+
+# Common issues:
+# 1. Outdated packages: npm update
+# 2. Breaking changes: Check CHANGELOG before updating
+# 3. Alternative packages: Search for maintained alternatives
+```
+
+## 📊 Quality Metrics
+
+### Test Coverage
+
+```bash
+# Generate coverage report
+npm run test:coverage
+
+# Check coverage thresholds
+npx vitest run --coverage --reporter=verbose
+
+# Common targets:
+# - Lines: >80%
+# - Functions: >80%
+# - Branches: >70%
+# - Statements: >80%
+```
+
+### Code Quality Metrics
+
+```bash
+# TypeScript strict mode compliance
+npx tsc --strict --noEmit
+
+# Complexity analysis
+npx eslint . --format=json | jq '.[] | select(.errorCount > 5)'
+
+# Common improvements:
+# 1. Reduce function complexity
+# 2. Remove code duplication
+# 3. Improve type coverage
+```
+
+## 🚀 Quick Fixes for Common Production Issues
+
+### Emergency Fix Checklist
+
+1. **Identify the gap**: What check would have caught this?
+2. **Add verification**: Create test that reproduces the issue
+3. **Fix root cause**: Don't just patch symptoms
+4. **Prevent recurrence**: Add to quality gates
+5. **Update documentation**: Add to this troubleshooting guide
+
+### Example: TypeScript Error in Production
+
+```bash
+# 1. Reproduce locally
+npm run type-check:all  # Should fail
+
+# 2. Fix the error
+# Edit the TypeScript code to resolve type issues
+
+# 3. Verify fix
+npm run type-check:all  # Should pass
+
+# 4. Prevent recurrence
+# Ensure type-check:all is in CI and pre-commit hooks
+
+# 5. Update configuration
+# Add stricter TypeScript rules if needed
+```
+
+## 📞 Getting Help
+
+### Internal Resources
+
+- Check `scripts/check-docs.sh` for documentation validation
+- Review `.github/workflows/` for CI configuration
+- Check `lib/` directory for quality automation internals
+
+### External Resources
+
+- [ESLint Troubleshooting](https://eslint.org/docs/user-guide/troubleshooting)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
+- [Vitest Documentation](https://vitest.dev/guide/)
+- [Playwright Debugging](https://playwright.dev/docs/debug)
+
+### Debug Environment Setup
+
+```bash
+# Enable debug logging
+export DEBUG=quality-automation:*
+
+# Run with verbose output
+npm run quality:check -- --verbose
+
+# Generate debug report
+npm run validate:comprehensive > debug-report.txt 2>&1
+```
+
+---
+
+**Remember**: Quality gates exist to catch issues early when they're cheap to fix. Don't bypass them - fix the root cause.

package/templates/ci/circleci-config.yml

@@ -0,0 +1,35 @@
+version: 2.1
+
+orbs:
+  node: circleci/node@5.2.0
+
+jobs:
+  lint-test-security:
+    executor:
+      name: node/default
+      tag: '20.11'
+    steps:
+      - checkout
+      - node/install-packages:
+          pkg-manager: npm
+          override-ci-command: npm ci || npm install
+      - run:
+          name: Format Check
+          command: npm run format:check || npm run format
+      - run:
+          name: Lint
+          command: npm run lint
+      - run:
+          name: Tests
+          command: npm test
+      - run:
+          name: Security Scan
+          command: npm run security:audit || echo "⚠️ npm audit failed; review vulnerabilities"
+      - run:
+          name: Gitleaks Secrets Scan
+          command: npx gitleaks detect --redact --verbose || echo "⚠️ gitleaks failures; set GITLEAKS_LICENSE for premium features"
+
+workflows:
+  quality:
+    jobs:
+      - lint-test-security

package/templates/ci/gitlab-ci.yml

@@ -0,0 +1,47 @@
+stages:
+  - install
+  - lint
+  - test
+  - security
+
+variables:
+  NODE_VERSION: '20'
+
+default:
+  image: node:${NODE_VERSION}
+  cache:
+    key: ${CI_COMMIT_REF_SLUG}
+    paths:
+      - node_modules/
+
+install:
+  stage: install
+  script:
+    - npm ci || npm install
+  artifacts:
+    paths:
+      - node_modules/
+    expire_in: 1h
+
+lint:
+  stage: lint
+  needs: ['install']
+  script:
+    - npm run format:check || npm run format
+    - npm run lint
+
+test:
+  stage: test
+  needs: ['install']
+  script:
+    - npm test
+
+security:
+  stage: security
+  needs: ['install']
+  script:
+    - npm run security:audit || echo "⚠️ npm audit failed; review vulnerabilities"
+    - npx gitleaks detect --redact --verbose || echo "⚠️ gitleaks failures (configure GITLEAKS_LICENSE for premium features)"
+  artifacts:
+    when: always
+    expire_in: 1 week