create-qa-architect 5.0.0

package/lib/template-loader.js

@@ -0,0 +1,252 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const { EXCLUDE_DIRECTORIES } = require('../config/constants')
+
+/**
+ * TemplateLoader - Load and merge custom template configurations
+ *
+ * Supports loading template files from a local directory to override default
+ * configurations. Enables organizations to maintain custom coding standards
+ * while still using the automated setup tooling.
+ *
+ * Usage:
+ *   const loader = new TemplateLoader()
+ *   const templates = await loader.mergeTemplates('/path/to/custom', '/path/to/defaults')
+ */
+class TemplateLoader {
+  constructor(options = {}) {
+    this.verbose = options.verbose !== false
+    this.strict = options.strict === true
+  }
+
+  /**
+   * Validate that a template path is valid
+   * @param {string} templatePath - Path to template directory
+   * @returns {boolean} True if path is valid
+   */
+  isValidTemplatePath(templatePath) {
+    if (!templatePath) {
+      return false
+    }
+
+    try {
+      const stats = fs.statSync(templatePath)
+      return stats.isDirectory()
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Validate template directory structure
+   * Empty directories are valid (partial templates)
+   * @param {string} templateDir - Path to template directory
+   * @returns {Promise<boolean>} True if structure is valid
+   */
+  async validateTemplateStructure(templateDir) {
+    try {
+      // Any directory is valid - even empty ones (partial templates are OK)
+
+      const stats = fs.statSync(templateDir)
+      return stats.isDirectory()
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Directories that should be skipped during template loading
+   * This prevents scanning node_modules and other unnecessary directories
+   */
+  static SKIP_DIRECTORIES = new Set(EXCLUDE_DIRECTORIES.TEMPLATE_LOADING)
+
+  /**
+   * Known template directories that should be scanned
+   * When loading from package directory, only these are scanned
+   */
+  static TEMPLATE_DIRECTORIES = new Set(EXCLUDE_DIRECTORIES.TEMPLATE_WHITELIST)
+
+  /**
+   * Check if a directory should be skipped during scanning
+   * @param {string} dirName - Directory name
+   * @param {boolean} isPackageDir - Whether this is the package's own directory
+   * @returns {boolean} True if directory should be skipped
+   */
+  shouldSkipDirectory(dirName, isPackageDir = false) {
+    // Always skip these directories
+    if (TemplateLoader.SKIP_DIRECTORIES.has(dirName)) {
+      return true
+    }
+
+    // For package directory, only scan known template directories
+    if (isPackageDir && !TemplateLoader.TEMPLATE_DIRECTORIES.has(dirName)) {
+      return true
+    }
+
+    return false
+  }
+
+  /**
+   * Recursively loads all template files from a directory tree
+   *
+   * Walks through a directory tree loading file contents while respecting
+   * security boundaries and skip rules. When loading from the package's own
+   * directory (isPackageDir=true), only scans allowed template directories
+   * to prevent loading arbitrary package files.
+   *
+   * Algorithm:
+   * 1. Read directory entries (files and subdirectories)
+   * 2. Skip excluded directories (node_modules, .git, etc.)
+   * 3. For files: load content and map by relative path
+   * 4. For subdirs: recursively load templates (depth-first)
+   * 5. Merge all templates into single flat map
+   * 6. Silently continue on errors (returns partial results)
+   *
+   * Security:
+   * - Package dir mode: Only loads from TEMPLATE_DIRECTORIES whitelist
+   * - Respects SKIP_DIRECTORIES blacklist (node_modules, .git, etc.)
+   * - Handles permission errors gracefully
+   *
+   * @param {string} dir - Directory to load from (absolute path)
+   * @param {string} [baseDir=dir] - Base directory for calculating relative paths
+   * @param {boolean} [isPackageDir=false] - True if scanning package's own directory
+   *        (enables whitelist mode for security)
+   * @returns {Promise<Object<string, string>>} Map of relative file paths to contents
+   *
+   * @example
+   * // Load custom templates from user directory
+   * const templates = await loader.loadTemplates('/user/templates', '/user/templates', false)
+   * // Returns: { 'config/.prettierrc': '...', '.github/workflows/ci.yml': '...' }
+   *
+   * @example
+   * // Load from package directory (restricted mode)
+   * const templates = await loader.loadTemplates('/pkg/config', '/pkg', true)
+   * // Only loads from whitelisted dirs: config/, .github/, lib/
+   */
+  async loadTemplates(dir, baseDir = dir, isPackageDir = false) {
+    const templates = {}
+
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true })
+
+      for (const entry of entries) {
+        // Skip directories that should not be scanned
+        if (
+          entry.isDirectory() &&
+          this.shouldSkipDirectory(entry.name, isPackageDir)
+        ) {
+          continue
+        }
+
+        const fullPath = path.join(dir, entry.name)
+        const relativePath = path.relative(baseDir, fullPath)
+
+        if (entry.isDirectory()) {
+          // Recursively load from subdirectories
+          // After first level, we're no longer in package root
+          const subTemplates = await this.loadTemplates(
+            fullPath,
+            baseDir,
+            false
+          )
+          Object.assign(templates, subTemplates)
+        } else if (entry.isFile()) {
+          // Load file content asynchronously for better performance
+          const content = await fs.promises.readFile(fullPath, 'utf8')
+          templates[relativePath] = content
+        }
+      }
+    } catch (error) {
+      if (this.verbose) {
+        console.warn(
+          `⚠️ Warning: Could not load templates from ${dir}: ${error.message}`
+        )
+      }
+    }
+
+    return templates
+  }
+
+  /**
+   * Merge custom templates with defaults
+   * Custom templates override defaults, but defaults fill in gaps
+   * @param {string} customDir - Path to custom template directory
+   * @param {string} defaultsDir - Path to defaults directory (package __dirname)
+   * @returns {Promise<Object>} Merged template map
+   */
+  async mergeTemplates(customDir, defaultsDir) {
+    const merged = {}
+
+    // Load defaults first (from package directory - restrict to known template dirs)
+    if (this.isValidTemplatePath(defaultsDir)) {
+      const defaults = await this.loadTemplates(defaultsDir, defaultsDir, true)
+      Object.assign(merged, defaults)
+    }
+
+    // Load custom templates (overrides defaults - scan fully, it's user-controlled)
+    if (customDir) {
+      // In strict mode, custom template path MUST be valid if provided
+      if (!this.isValidTemplatePath(customDir)) {
+        const errorMsg = `Custom template directory not found or invalid: ${customDir}`
+        if (this.strict) {
+          throw new Error(errorMsg)
+        } else {
+          if (this.verbose) {
+            const isTest = process.argv.join(' ').includes('test')
+            const prefix = isTest ? '📋 TEST SCENARIO:' : '⚠️'
+            console.warn(`${prefix} ${errorMsg}`)
+            console.warn('   Falling back to default templates')
+          }
+        }
+      } else {
+        const isValid = await this.validateTemplateStructure(customDir)
+
+        if (!isValid) {
+          const errorMsg = 'Invalid template structure'
+          if (this.strict) {
+            throw new Error(errorMsg)
+          } else {
+            if (this.verbose) {
+              console.warn(`⚠️ ${errorMsg}, using defaults`)
+            }
+          }
+        } else {
+          const custom = await this.loadTemplates(customDir, customDir, false)
+          Object.assign(merged, custom) // Custom templates override defaults
+
+          if (this.verbose && Object.keys(custom).length > 0) {
+            console.log(
+              `✅ Loaded ${Object.keys(custom).length} custom template file(s)`
+            )
+          }
+        }
+      }
+    }
+
+    return merged
+  }
+
+  /**
+   * Get the template file content or undefined if not found
+   * @param {Object} templates - Template map from loadTemplates/mergeTemplates
+   * @param {string} relativePath - Relative path to file
+   * @returns {string|undefined} File content or undefined
+   */
+  getTemplate(templates, relativePath) {
+    return templates[relativePath]
+  }
+
+  /**
+   * Check if a specific template file exists in the template map
+   * @param {Object} templates - Template map from loadTemplates/mergeTemplates
+   * @param {string} relativePath - Relative path to file
+   * @returns {boolean} True if template exists
+   */
+  hasTemplate(templates, relativePath) {
+    return relativePath in templates
+  }
+}
+
+module.exports = { TemplateLoader }

package/lib/typescript-config-generator.js

@@ -0,0 +1,210 @@
+/**
+ * TypeScript Configuration Generator
+ * Fixes critical blind spot: tests excluded from TypeScript checking
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+/**
+ * Generate tests/tsconfig.json to ensure tests are TypeScript checked
+ * Critical fix for production TypeScript errors in test files
+ */
+function generateTestsTypeScriptConfig(projectPath = '.') {
+  const testsDir = path.join(projectPath, 'tests')
+  const testsTsConfigPath = path.join(testsDir, 'tsconfig.json')
+
+  // Create tests directory if it doesn't exist
+  if (!fs.existsSync(testsDir)) {
+    fs.mkdirSync(testsDir, { recursive: true })
+  }
+
+  // Generate comprehensive tests TypeScript configuration
+  const testsTsConfig = {
+    extends: '../tsconfig.json',
+    compilerOptions: {
+      rootDir: '..',
+      noEmit: true,
+      types: ['vitest/globals', 'node', '@types/jest'],
+    },
+    include: ['../src/**/*', '../tests/**/*', '../*.ts', '../*.js'],
+    exclude: ['../node_modules', '../dist', '../build'],
+  }
+
+  // Write tests TypeScript configuration
+  fs.writeFileSync(
+    testsTsConfigPath,
+    JSON.stringify(testsTsConfig, null, 2) + '\n'
+  )
+
+  return testsTsConfigPath
+}
+
+/**
+ * Add enhanced npm scripts for comprehensive TypeScript checking
+ * Includes both src and tests validation
+ */
+function getEnhancedTypeScriptScripts() {
+  return {
+    'type-check': 'tsc --noEmit',
+    'type-check:tests': 'tsc --noEmit --project tests/tsconfig.json',
+    'type-check:all': 'npm run type-check && npm run type-check:tests',
+    'quality:check': 'npm run type-check:all && npm run lint && npm run test',
+    'quality:ci': 'npm run quality:check && npm run security:audit',
+  }
+}
+
+/**
+ * Generate enhanced lint-staged configuration
+ * Comprehensive quality checks instead of just CLAUDE.md
+ */
+function getEnhancedLintStaged(usesPython = false, hasTypeScript = false) {
+  const lintStaged = {
+    'package.json': ['prettier --write'],
+    '**/*.{json,md,yml,yaml}': ['prettier --write'],
+    '**/*.{js,jsx,mjs,cjs,html}': ['eslint --fix', 'prettier --write'],
+    '**/*.{css,scss,sass,less,pcss}': ['stylelint --fix', 'prettier --write'],
+  }
+
+  // Add TypeScript checking to pre-commit if TypeScript detected
+  if (hasTypeScript) {
+    lintStaged['**/*.{ts,tsx}'] = [
+      'tsc --noEmit --skipLibCheck',
+      'eslint --fix',
+      'prettier --write',
+    ]
+
+    // Add tests TypeScript checking
+    lintStaged['tests/**/*.{ts,tsx,js,jsx}'] = [
+      'tsc --noEmit --project tests/tsconfig.json',
+      'eslint --fix',
+      'prettier --write',
+    ]
+  }
+
+  // Add Python support if detected
+  if (usesPython) {
+    lintStaged['**/*.py'] = [
+      'black --check --diff',
+      'ruff check --fix',
+      'isort --check-only --diff',
+    ]
+  }
+
+  return lintStaged
+}
+
+/**
+ * Detect project type for adaptive template selection
+ */
+function detectProjectType(projectPath = '.') {
+  const packageJsonPath = path.join(projectPath, 'package.json')
+
+  if (!fs.existsSync(packageJsonPath)) {
+    return 'unknown'
+  }
+
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+  const deps = {
+    ...packageJson.dependencies,
+    ...packageJson.devDependencies,
+  }
+
+  // API Service Detection
+  if (deps.express || deps.fastify || deps.koa || deps['@nestjs/core']) {
+    return 'api-service'
+  }
+
+  // Frontend App Detection
+  if (deps.react || deps.vue || deps.angular || deps.svelte) {
+    return 'frontend-app'
+  }
+
+  // Mobile App Detection
+  if (deps['react-native'] || deps['@ionic/react'] || deps['@capacitor/core']) {
+    return 'mobile-app'
+  }
+
+  // Library Detection
+  if (packageJson.main || packageJson.module || packageJson.exports) {
+    return 'library'
+  }
+
+  // CLI Tool Detection
+  if (packageJson.bin) {
+    return 'cli-tool'
+  }
+
+  return 'web-app'
+}
+
+/**
+ * Generate project-specific quality configuration
+ */
+function getProjectQualityConfig(projectType) {
+  const configs = {
+    'api-service': {
+      qualityGates: {
+        typeCheck: { src: true, tests: true },
+        lint: { fix: false, failOnError: true },
+        test: { unit: true, integration: true },
+        security: { audit: true, secretScan: true },
+      },
+      testTypes: ['unit', 'integration', 'e2e'],
+      scripts: {
+        'test:integration': 'vitest run tests/integration/**/*.test.{js,ts}',
+        'test:e2e': 'vitest run tests/e2e/**/*.test.{js,ts}',
+      },
+    },
+
+    'frontend-app': {
+      qualityGates: {
+        typeCheck: { src: true, tests: true },
+        lint: { fix: false, failOnError: true },
+        test: { unit: true, e2e: true },
+        accessibility: { check: true },
+      },
+      testTypes: ['unit', 'component', 'e2e'],
+      scripts: {
+        'test:component': 'vitest run tests/components/**/*.test.{js,ts,tsx}',
+        'test:e2e': 'playwright test',
+        'accessibility:check': 'axe-core tests/accessibility',
+      },
+    },
+
+    'cli-tool': {
+      qualityGates: {
+        typeCheck: { src: true, tests: true },
+        lint: { fix: false, failOnError: true },
+        test: { unit: true, integration: true, commands: true },
+        security: { audit: true, secretScan: true },
+      },
+      testTypes: ['unit', 'integration', 'command'],
+      scripts: {
+        'test:commands': 'vitest run tests/commands/**/*.test.{js,ts}',
+        'test:integration': 'vitest run tests/integration/**/*.test.{js,ts}',
+      },
+    },
+  }
+
+  return (
+    configs[projectType] ||
+    configs['web-app'] || {
+      qualityGates: {
+        typeCheck: { src: true, tests: true },
+        lint: { fix: false, failOnError: true },
+        test: { unit: true },
+      },
+      testTypes: ['unit'],
+      scripts: {},
+    }
+  )
+}
+
+module.exports = {
+  generateTestsTypeScriptConfig,
+  getEnhancedTypeScriptScripts,
+  getEnhancedLintStaged,
+  detectProjectType,
+  getProjectQualityConfig,
+}

package/lib/ui-helpers.js

@@ -0,0 +1,74 @@
+'use strict'
+
+/**
+ * UI Helpers for Progress Indicators and Accessibility
+ * Provides consistent messaging with ora spinners and fallback for CI/accessibility
+ */
+
+const ACCESSIBILITY_MODE =
+  process.env.NO_EMOJI === 'true' || process.env.SCREEN_READER === 'true'
+
+const icons = ACCESSIBILITY_MODE
+  ? {
+      success: '[OK]',
+      error: '[ERROR]',
+      warning: '[WARN]',
+      info: '[INFO]',
+      working: '[...]',
+    }
+  : {
+      success: '✅',
+      error: '❌',
+      warning: '⚠️',
+      info: '💡',
+      working: '🔍',
+    }
+
+/**
+ * Format a message with appropriate icon
+ * @param {string} type - Message type (success, error, warning, info, working)
+ * @param {string} message - Message text
+ * @returns {string} Formatted message
+ */
+function formatMessage(type, message) {
+  return `${icons[type]} ${message}`
+}
+
+/**
+ * Show progress indicator with ora spinner or fallback
+ * @param {string} message - Progress message
+ * @returns {Object} Spinner-like object with succeed/fail/warn methods
+ */
+function showProgress(message) {
+  // In CI or non-TTY environments, use simple logging
+  if (process.env.CI || !process.stdout.isTTY) {
+    console.log(formatMessage('working', message))
+    return {
+      succeed: msg => console.log(formatMessage('success', msg)),
+      fail: msg => console.error(formatMessage('error', msg)),
+      warn: msg => console.warn(formatMessage('warning', msg)),
+      info: msg => console.log(formatMessage('info', msg)),
+      stop: () => {},
+      start: () => {},
+    }
+  }
+
+  // Try to use ora for interactive terminals
+  try {
+    const ora = require('ora')
+    return ora(message).start()
+  } catch {
+    // Fallback if ora not installed (graceful degradation)
+    console.log(formatMessage('working', message))
+    return {
+      succeed: msg => console.log(formatMessage('success', msg)),
+      fail: msg => console.error(formatMessage('error', msg)),
+      warn: msg => console.warn(formatMessage('warning', msg)),
+      info: msg => console.log(formatMessage('info', msg)),
+      stop: () => {},
+      start: () => {},
+    }
+  }
+}
+
+module.exports = { formatMessage, showProgress, icons, ACCESSIBILITY_MODE }

package/lib/validation/base-validator.js

@@ -0,0 +1,174 @@
+'use strict'
+
+/**
+ * Base Validator Class
+ * Provides common error handling, state management, and validation patterns
+ * for all validator implementations
+ */
+class BaseValidator {
+  constructor(options = {}) {
+    this.options = options
+    this.issues = []
+    this.warnings = []
+    this.validationComplete = false
+  }
+
+  /**
+   * Check if validation has been run
+   */
+  hasRun() {
+    return this.validationComplete
+  }
+
+  /**
+   * Get all issues found
+   */
+  getIssues() {
+    return this.issues
+  }
+
+  /**
+   * Get all warnings found
+   */
+  getWarnings() {
+    return this.warnings
+  }
+
+  /**
+   * Check if validation passed (no issues)
+   */
+  passed() {
+    return this.hasRun() && this.issues.length === 0
+  }
+
+  /**
+   * Reset validation state
+   */
+  reset() {
+    this.issues = []
+    this.warnings = []
+    this.validationComplete = false
+  }
+
+  /**
+   * Safe async operation wrapper with error handling
+   * @param {Function} operation - Async operation to execute
+   * @param {string} errorContext - Context for error messages
+   */
+  async safeExecute(operation, errorContext) {
+    try {
+      await operation()
+    } catch (error) {
+      this.handleError(error, errorContext)
+    }
+  }
+
+  /**
+   * Centralized error handling
+   * @param {Error} error - The error that occurred
+   * @param {string} context - Context where the error occurred
+   */
+  handleError(error, context) {
+    // Log detailed error for debugging
+    if (this.options.verbose) {
+      console.error(`Error in ${context}:`, error)
+    }
+
+    // Add user-friendly error message
+    const errorMessage = this.formatErrorMessage(error, context)
+    this.issues.push(errorMessage)
+  }
+
+  /**
+   * Format error message for user
+   * @param {Error} error - The error object
+   * @param {string} context - The context
+   * @returns {string} Formatted error message
+   */
+  formatErrorMessage(error, context) {
+    // Handle common error types with actionable suggestions
+    if (error?.code === 'ENOENT') {
+      return (
+        `${context}: File or command not found - ${error.message}\n` +
+        `   💡 Suggestion: Check that the file exists and the path is correct. ` +
+        `If it's a command, ensure it's installed and in your PATH.`
+      )
+    }
+
+    if (error?.code === 'EACCES' || error?.code === 'EPERM') {
+      return (
+        `${context}: Permission denied - ${error.message}\n` +
+        `   💡 Suggestion: Try running with appropriate permissions (chmod +x for scripts) ` +
+        `or check file ownership. On Windows, run as Administrator if needed.`
+      )
+    }
+
+    if (error?.code === 'MODULE_NOT_FOUND') {
+      // Try to extract module name from error message
+      const moduleMatch = error.message.match(
+        /Cannot find module ['"]([^'"]+)['"]/
+      )
+      const moduleName = moduleMatch ? moduleMatch[1] : 'the required module'
+
+      return (
+        `${context}: Required module not installed - ${error.message}\n` +
+        `   💡 Suggestion: Install the missing module with: npm install ${moduleName}`
+      )
+    }
+
+    if (error.name === 'SyntaxError') {
+      return (
+        `${context}: Syntax error - ${error.message}\n` +
+        `   💡 Suggestion: Check for typos, missing commas, or unmatched brackets. ` +
+        `If it's JSON, validate it with a JSON linter.`
+      )
+    }
+
+    // Default error message (no specific suggestion)
+    return `${context}: ${error.message}`
+  }
+
+  /**
+   * Add an issue to the issues list
+   * @param {string} message - Issue message
+   */
+  addIssue(message) {
+    this.issues.push(message)
+  }
+
+  /**
+   * Add a warning to the warnings list
+   * @param {string} message - Warning message
+   */
+  addWarning(message) {
+    this.warnings.push(message)
+  }
+
+  /**
+   * Validate - must be implemented by subclasses
+   */
+  async validate() {
+    throw new Error('validate() must be implemented by subclass')
+  }
+
+  /**
+   * Print validation results
+   */
+  printResults() {
+    if (this.issues.length > 0) {
+      console.error(`❌ Found ${this.issues.length} issue(s):`)
+      this.issues.forEach(issue => console.error(`   ${issue}`))
+    }
+
+    if (this.warnings.length > 0) {
+      console.warn(`⚠️  Found ${this.warnings.length} warning(s):`)
+      this.warnings.forEach(warning => console.warn(`   ${warning}`))
+    }
+
+    if (this.passed()) {
+      console.log('✅ Validation passed')
+    }
+  }
+}
+
+module.exports = BaseValidator