create-qa-architect 5.0.0

package/README.md

@@ -0,0 +1,212 @@
+# Create Quality Automation
+
+Bootstrap quality automation in JavaScript/TypeScript and Python projects with comprehensive tooling. One command adds ESLint, Prettier, Husky, lint-staged, security scanning, and GitHub Actions to any project.
+
+---
+
+> **Maintainer & Ownership**
+> This project is maintained by **Vibe Build Lab LLC**, a studio focused on AI-assisted product development, micro-SaaS, and "vibe coding" workflows for solo founders and small teams.
+> Learn more at **https://www.vibebuildlab.com**.
+
+---
+
+## Features
+
+- **Prettier Code Formatting** - Consistent code style across your project
+- **Husky Git Hooks** - Pre-commit (lint-staged) and pre-push (validation)
+- **lint-staged Processing** - Only process changed files for speed
+- **Pre-push Validation** - Prevents broken code from reaching CI
+- **GitHub Actions** - Automated quality checks in CI/CD
+- **TypeScript Smart** - Auto-detects and configures TypeScript projects
+- **Python Support** - Complete Python toolchain with Black, Ruff, isort, mypy, pytest
+- **Security Automation** - npm audit and hardcoded secrets scanning
+- **Progressive Quality** - Adaptive checks based on project maturity
+- **Smart Test Strategy** - Risk-based pre-push validation (Pro feature)
+
+## Target Users
+
+- **Developers** who want quality automation without manual setup
+- **Teams** standardizing code quality across multiple projects
+- **Open source maintainers** enforcing contribution standards
+- **Agencies** shipping consistent quality across client projects
+
+## Demo / Live Links
+
+```bash
+# Try it on any project
+npx create-qa-architect@latest
+```
+
+## Pricing & Licensing
+
+### Freemium Model
+
+| Tier           | Price       | Features                                                |
+| -------------- | ----------- | ------------------------------------------------------- |
+| **Free**       | $0          | Basic quality automation, 1 private repo, 2k LOC        |
+| **Pro**        | $59/mo      | Unlimited repos, Smart Test Strategy, security scanning |
+| **Team**       | $15/user/mo | All Pro features + shared quota, team policies          |
+| **Enterprise** | $249/mo     | SSO/SAML, custom patterns, compliance pack              |
+
+### License
+
+**Open Source (MIT)** - Free for personal and commercial use.
+
+[Get Started with Pro](https://vibebuildlab.com/cqa)
+
+## Tech Stack
+
+| Component       | Technology                |
+| --------------- | ------------------------- |
+| **Runtime**     | Node.js 20+               |
+| **Linting**     | ESLint 9 (flat config)    |
+| **Formatting**  | Prettier 3                |
+| **CSS Linting** | Stylelint 16              |
+| **Git Hooks**   | Husky 9 + lint-staged 15  |
+| **Python**      | Black, Ruff, mypy, pytest |
+| **Performance** | Lighthouse CI             |
+| **Security**    | Gitleaks, npm audit       |
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 20 or higher
+- npm 10+ (installed automatically with Node 20)
+- Git repository (required for hooks)
+
+### Quick Start
+
+```bash
+# Navigate to your project
+cd your-project/
+
+# Bootstrap quality automation
+npx create-qa-architect@latest
+
+# Install new dependencies
+npm install
+
+# Set up pre-commit hooks
+npm run prepare
+```
+
+### Update Existing Setup
+
+```bash
+npx create-qa-architect@latest --update
+npm install
+npm run lint
+```
+
+### Dependency Monitoring (Free)
+
+```bash
+npx create-qa-architect@latest --deps
+```
+
+## Usage Examples
+
+### Check Project Maturity
+
+```bash
+npx create-qa-architect@latest --check-maturity
+```
+
+**Output:**
+
+```
+Project Maturity Report
+
+Maturity Level: Development
+Description: Active development - has source files and tests
+
+Quality Checks:
+  Required: prettier, eslint, stylelint, tests
+  Optional: security-audit
+  Disabled: coverage, documentation
+```
+
+### Security Validation
+
+```bash
+# Check configuration security
+npx create-qa-architect@latest --security-config
+
+# Validate documentation
+npx create-qa-architect@latest --validate-docs
+
+# Comprehensive validation
+npx create-qa-architect@latest --comprehensive
+```
+
+### Custom Templates
+
+```bash
+# Use organization-specific standards
+npx create-qa-architect@latest --template ./my-org-templates
+```
+
+## What Gets Added
+
+```
+your-project/
+├── .github/
+│   └── workflows/
+│       └── quality.yml          # GitHub Actions workflow
+├── .husky/                      # Pre-commit hooks
+├── .editorconfig                # Editor defaults
+├── .eslintignore                # ESLint ignore patterns
+├── .nvmrc                       # Node version pinning
+├── .prettierrc                  # Prettier configuration
+├── .stylelintrc.json            # Stylelint rules
+├── eslint.config.cjs            # ESLint flat config
+└── package.json                 # Updated scripts
+```
+
+## Available Scripts (After Setup)
+
+```bash
+npm run format              # Format all files
+npm run format:check        # Check formatting (CI)
+npm run lint                # ESLint + Stylelint
+npm run lint:fix            # Auto-fix linting
+npm run security:audit      # Vulnerability check
+npm run security:secrets    # Scan for secrets
+npm run validate:pre-push   # Pre-push validation
+```
+
+## Roadmap
+
+- [x] ESLint 9 flat config support
+- [x] Progressive quality (maturity detection)
+- [x] Python toolchain support
+- [x] Smart test strategy (Pro)
+- [ ] Rust and Go support
+- [ ] VS Code extension
+- [ ] Monorepo support
+
+## Contributing
+
+Want to improve this tool?
+
+1. Fork the repository
+2. Make your changes
+3. Test with a sample project
+4. Submit a pull request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Support
+
+1. Check the [Troubleshooting Guide](./TROUBLESHOOTING.md)
+2. Review GitHub Actions logs
+3. Open an issue in this repository
+
+## License
+
+MIT License - free to use in any project. See [LICENSE](LICENSE) for details.
+
+---
+
+> Discover more tools at **https://www.vibebuildlab.com**.

package/config/.lighthouserc.js

@@ -0,0 +1,45 @@
+module.exports = {
+  ci: {
+    collect: {
+      // Collect URLs - default to localhost for most projects
+      url: ['http://localhost:3000'],
+      // For static sites, you might want to build first
+      staticDistDir: './dist',
+      // Number of runs for more accurate results
+      numberOfRuns: 3,
+      // Wait for page to be ready
+      settings: {
+        chromeFlags: '--no-sandbox --headless --disable-gpu',
+      },
+    },
+    assert: {
+      // Performance budgets - configurable thresholds
+      assertions: {
+        'categories:performance': ['warn', { minScore: 0.8 }],
+        'categories:accessibility': ['error', { minScore: 0.9 }],
+        'categories:best-practices': ['warn', { minScore: 0.85 }],
+        'categories:seo': ['error', { minScore: 0.9 }],
+        // Specific metrics
+        'first-contentful-paint': ['warn', { maxNumericValue: 2000 }],
+        'largest-contentful-paint': ['warn', { maxNumericValue: 4000 }],
+        'cumulative-layout-shift': ['warn', { maxNumericValue: 0.1 }],
+        // Accessibility checks
+        'color-contrast': 'error',
+        'meta-description': 'error',
+        'document-title': 'error',
+        'html-has-lang': 'error',
+        'image-alt': 'error',
+        // SEO essentials
+        canonical: 'warn',
+        'meta-viewport': 'error',
+        'structured-data': 'warn',
+      },
+    },
+    upload: {
+      // Store results - can be configured per project
+      target: 'temporary-public-storage',
+      // For teams: configure GitHub status checks
+      // githubAppToken: process.env.LHCI_GITHUB_APP_TOKEN,
+    },
+  },
+}

package/config/.pre-commit-config.yaml

@@ -0,0 +1,66 @@
+# Pre-commit hooks for Python + JavaScript/TypeScript projects
+# Install: pip install pre-commit && pre-commit install
+# Run manually: pre-commit run --all-files
+
+repos:
+  # Python hooks
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      # Linter
+      - id: ruff
+        args: [--fix]
+      # Formatter
+      - id: ruff-format
+
+  - repo: https://github.com/PyCQA/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+        args: ['--profile', 'black']
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.11.2
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-all]
+        args: [--ignore-missing-imports, --no-strict-optional]
+
+  # JavaScript/TypeScript hooks
+  - repo: https://github.com/pre-commit/mirrors-eslint
+    rev: v9.12.0
+    hooks:
+      - id: eslint
+        args: [--fix, --max-warnings=0]
+        files: \.(js|jsx|ts|tsx|mjs|cjs)$
+        types: [file]
+        additional_dependencies:
+          - eslint@^9.12.0
+          - eslint-plugin-security@^3.0.1
+          - globals@^15.9.0
+
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v3.3.3
+    hooks:
+      - id: prettier
+        args: [--write]
+        files: \.(js|jsx|ts|tsx|json|yml|yaml|md|css|scss|html)$
+
+  # General hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json
+      - id: check-added-large-files
+        args: ['--maxkb=1000']
+      - id: check-merge-conflict
+      - id: detect-private-key
+
+  # Security scanning
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.19.3
+    hooks:
+      - id: gitleaks

package/config/constants.js

@@ -0,0 +1,128 @@
+/**
+ * Global Constants Configuration
+ *
+ * Centralized configuration values used throughout the quality automation system.
+ * Extracting these magic numbers improves maintainability and provides a single
+ * source of truth for all configuration thresholds and limits.
+ */
+
+/**
+ * Node.js version requirements
+ */
+const NODE_VERSION = {
+  /** Minimum supported Node.js major version */
+  MIN_MAJOR: 20,
+}
+
+/**
+ * File scanning and directory traversal limits
+ */
+const SCAN_LIMITS = {
+  /** Maximum depth for Stylelint directory scanning */
+  STYLELINT_MAX_DEPTH: 4,
+
+  /** Maximum depth for project maturity file counting */
+  FILE_COUNT_MAX_DEPTH: 5,
+}
+
+/**
+ * Error reporting and telemetry limits
+ */
+const REPORTING_LIMITS = {
+  /** Maximum number of error reports to store */
+  MAX_ERROR_REPORTS: 50,
+
+  /** Maximum number of telemetry events to buffer */
+  MAX_TELEMETRY_EVENTS: 100,
+}
+
+/**
+ * Project maturity assessment thresholds
+ */
+const MATURITY_THRESHOLDS = {
+  /** Minimum README line count for "documented" status */
+  README_MIN_LINES_FOR_DOCS: 100,
+
+  /** Minimum files for "bootstrap" maturity level */
+  MIN_BOOTSTRAP_FILES: 3,
+
+  /** Minimum files for "production" maturity level */
+  MIN_PRODUCTION_FILES: 10,
+
+  /** Minimum test files for "production" status */
+  MIN_PRODUCTION_TESTS: 3,
+}
+
+/**
+ * Dependency monitoring configuration
+ */
+const DEPENDENCY_MONITORING = {
+  /** Maximum size of regex pattern cache */
+  MAX_PATTERN_CACHE_SIZE: 1000,
+
+  /** Maximum file size for requirements.txt parsing (10MB) */
+  MAX_REQUIREMENTS_FILE_SIZE: 10 * 1024 * 1024,
+}
+
+/**
+ * Directory exclusion lists for scanning operations
+ *
+ * Centralized lists of directories to skip during various scanning operations
+ * (Stylelint, template loading, project maturity analysis).
+ */
+const EXCLUDE_DIRECTORIES = {
+  /** Directories to exclude during Stylelint scanning */
+  STYLELINT: [
+    '.git',
+    '.github',
+    '.husky',
+    '.next',
+    '.nuxt',
+    '.output',
+    '.turbo',
+    '.vercel',
+    '.cache',
+    '.pnpm-store',
+    'coverage',
+    'node_modules',
+  ],
+
+  /** Directories to skip during template loading */
+  TEMPLATE_LOADING: [
+    'node_modules',
+    '.git',
+    '.next',
+    '.nuxt',
+    '.turbo',
+    '.vercel',
+    '.cache',
+    'dist',
+    'build',
+    'coverage',
+    '.pnpm-store',
+    '.yarn',
+  ],
+
+  /** Directories to exclude during project maturity file counting */
+  PROJECT_MATURITY: [
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    'coverage',
+    '.next',
+    '.nuxt',
+  ],
+
+  /** Directories allowed for template scanning from package directory */
+  TEMPLATE_WHITELIST: ['.github', 'config', 'dotfiles'],
+}
+
+module.exports = {
+  NODE_VERSION,
+  SCAN_LIMITS,
+  REPORTING_LIMITS,
+  MATURITY_THRESHOLDS,
+  DEPENDENCY_MONITORING,
+  EXCLUDE_DIRECTORIES,
+}

package/config/defaults.js

@@ -0,0 +1,124 @@
+'use strict'
+/* eslint-disable security/detect-object-injection */
+
+const STYLELINT_EXTENSIONS = ['css', 'scss', 'sass', 'less', 'pcss']
+const DEFAULT_STYLELINT_TARGET = `**/*.{${STYLELINT_EXTENSIONS.join(',')}}`
+
+const baseScripts = {
+  format: 'prettier --write .',
+  'format:check': 'prettier --check .',
+  test: 'vitest run --passWithNoTests',
+  'test:watch': 'vitest',
+  'test:coverage': 'vitest run --coverage',
+  'security:audit': 'npm audit --audit-level high',
+  'security:secrets':
+    "node -e \"const fs=require('fs');const content=fs.readFileSync('package.json','utf8');if(/[\\\"\\'][a-zA-Z0-9+/]{20,}[\\\"\\']/.test(content)){console.error('❌ Potential hardcoded secrets in package.json');process.exit(1)}else{console.log('✅ No secrets detected in package.json')}\"",
+  'security:config': 'npx create-qa-architect@latest --security-config',
+  'lighthouse:ci': 'lhci autorun',
+  'lighthouse:upload': 'lhci upload',
+  'validate:docs': 'npx create-qa-architect@latest --validate-docs',
+  'validate:comprehensive': 'npx create-qa-architect@latest --comprehensive',
+  'validate:all': 'npm run validate:comprehensive && npm run security:audit',
+  'validate:pre-push':
+    'npm run test:patterns --if-present && npm run lint && npm run format:check && npm run test:commands --if-present && npm test --if-present',
+}
+
+const normalizeStylelintTargets = stylelintTargets => {
+  const targets = Array.isArray(stylelintTargets)
+    ? stylelintTargets.filter(Boolean)
+    : []
+  if (!targets.length) {
+    return [DEFAULT_STYLELINT_TARGET]
+  }
+  return [...new Set(targets)]
+}
+
+const stylelintBraceGroup = stylelintTargets => {
+  const targets = normalizeStylelintTargets(stylelintTargets)
+  if (targets.length === 1) {
+    return targets[0]
+  }
+  return `{${targets.join(',')}}`
+}
+
+const baseLintScripts = ({ stylelintTargets }) => {
+  const stylelintTarget = stylelintBraceGroup(stylelintTargets)
+  return {
+    lint: `eslint . && stylelint "${stylelintTarget}" --allow-empty-input`,
+    'lint:fix': `eslint . --fix && stylelint "${stylelintTarget}" --fix --allow-empty-input`,
+  }
+}
+
+const baseDevDependencies = {
+  husky: '^9.1.4',
+  'lint-staged': '^15.2.10',
+  prettier: '^3.3.3',
+  eslint: '^9.12.0',
+  'eslint-plugin-security': '^3.0.1',
+  globals: '^15.9.0',
+  stylelint: '^16.8.0',
+  'stylelint-config-standard': '^37.0.0',
+  '@lhci/cli': '^0.14.0',
+  vitest: '^2.1.8',
+  '@vitest/coverage-v8': '^2.1.8',
+}
+
+const typeScriptDevDependencies = {
+  '@typescript-eslint/eslint-plugin': '^8.9.0',
+  '@typescript-eslint/parser': '^8.9.0',
+}
+
+const baseLintStaged = (patterns, stylelintTargets, usesPython = false) => {
+  const lintStaged = {
+    'package.json': ['prettier --write'],
+    [patterns]: ['eslint --fix', 'prettier --write'],
+    '**/*.{json,md,yml,yaml}': ['prettier --write'],
+  }
+
+  normalizeStylelintTargets(stylelintTargets).forEach(target => {
+    lintStaged[target] = ['stylelint --fix', 'prettier --write']
+  })
+
+  // Add Python lint-staged support if Python is detected
+  if (usesPython) {
+    lintStaged['**/*.py'] = [
+      'black --check --diff',
+      'ruff check --fix',
+      'isort --check-only --diff',
+    ]
+  }
+
+  return lintStaged
+}
+
+const JS_LINT_STAGED_PATTERN = '**/*.{js,jsx,mjs,cjs,html}'
+const TS_LINT_STAGED_PATTERN = '**/*.{js,jsx,ts,tsx,mjs,cjs,html}'
+
+const clone = value => JSON.parse(JSON.stringify(value))
+
+function getDefaultScripts({ stylelintTargets } = {}) {
+  return {
+    ...clone(baseScripts),
+    ...baseLintScripts({ stylelintTargets }),
+  }
+}
+
+function getDefaultDevDependencies({ typescript } = {}) {
+  const devDeps = { ...clone(baseDevDependencies) }
+  if (typescript) {
+    Object.assign(devDeps, typeScriptDevDependencies)
+  }
+  return devDeps
+}
+
+function getDefaultLintStaged({ typescript, stylelintTargets, python } = {}) {
+  const pattern = typescript ? TS_LINT_STAGED_PATTERN : JS_LINT_STAGED_PATTERN
+  return clone(baseLintStaged(pattern, stylelintTargets, python))
+}
+
+module.exports = {
+  getDefaultDevDependencies,
+  getDefaultLintStaged,
+  getDefaultScripts,
+  STYLELINT_EXTENSIONS,
+}

package/config/pyproject.toml

@@ -0,0 +1,124 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.black]
+line-length = 88
+target-version = ['py38']
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+  # directories
+  \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | venv
+  | \.pytest_cache
+  | _build
+  | buck-out
+  | build
+  | dist
+)/
+'''
+
+[tool.ruff]
+target-version = "py38"
+line-length = 88
+fix = true
+
+[tool.ruff.lint]
+select = [
+    # pycodestyle
+    "E",
+    "W",
+    # Pyflakes
+    "F",
+    # pyupgrade
+    "UP",
+    # flake8-bugbear
+    "B",
+    # flake8-simplify
+    "SIM",
+    # isort
+    "I",
+    # flake8-bandit (security)
+    "S",
+    # flake8-comprehensions
+    "C4",
+    # flake8-errmsg
+    "EM",
+    # flake8-quotes
+    "Q",
+    # flake8-return
+    "RET",
+    # flake8-unused-arguments
+    "ARG",
+    # flake8-use-pathlib
+    "PTH",
+    # flake8-pie
+    "PIE",
+    # flake8-type-checking
+    "TCH",
+]
+ignore = [
+    # Allow non-abstract empty methods in abstract base classes
+    "B027",
+    # Allow boolean positional values in function calls, like `dict.get(... True)`
+    "FBT003",
+    # Ignore checks for possible passwords
+    "S105", "S106", "S107",
+    # Ignore complexity
+    "C901", "PLR0911", "PLR0912", "PLR0913", "PLR0915",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests can use magic values, assertions, and relative imports
+"tests/**/*" = ["PLR2004", "S101", "TID252"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["src"]
+
+[tool.mypy]
+python_version = "3.8"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["tests/*", "*/tests/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if self.debug:",
+    "if settings.DEBUG",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if 0:",
+    "if __name__ == .__main__.:",
+]