qa360 2.2.1 → 2.2.13

package/docs/DEVELOPMENT.md

@@ -1,545 +0,0 @@
-# QA360 - Development Guide
-
-**For contributors and developers working on QA360 codebase**
-
----
-
-## Quick Start
-
-```bash
-# Clone and install
-git clone https://github.com/xyqotech/qa360.git
-cd qa360
-pnpm install
-
-# Build
-pnpm build
-
-# Run tests
-pnpm test
-
-# Run CLI locally
-node cli/bin/qa360.js --help
-```
-
----
-
-## Project Structure
-
-```
-qa360/
-├── cli/                    # @qa360/cli - User-facing CLI
-│   ├── src/
-│   │   ├── commands/      # CLI command implementations
-│   │   └── index.ts       # CLI entry point
-│   └── package.json
-│
-├── core/                   # qa360-core - Core engine (no CLI deps)
-│   ├── src/
-│   │   ├── ai/            # Multi-provider LLM
-│   │   ├── auth/          # 9 auth providers
-│   │   ├── generation/    # AI test generation
-│   │   ├── pack-v2/       # Pack v2 validation
-│   │   ├── repair/        # Auto-repair module
-│   │   ├── tdi/           # Test Data Intelligence
-│   │   ├── tui/           # Terminal UI (Phase 8)
-│   │   ├── dashboard/     # Web dashboard (Phase 8)
-│   │   ├── vault/         # Evidence vault (SQLite)
-│   │   ├── proof/         # Ed25519 signing
-│   │   ├── adapters/      # Test adapters
-│   │   └── index.ts       # Core exports
-│   └── package.json
-│
-├── packages/mcp/          # MCP server integration
-├── docs/                  # Documentation (3 files only)
-│   ├── STATUS.md          # Project status (THIS IS THE SOURCE)
-│   ├── DEVELOPMENT.md     # This file
-│   └── ARCHITECTURE.md    # Technical architecture
-└── examples/              # Example configurations
-```
-
----
-
-## Common Commands
-
-### Development
-```bash
-pnpm build           # Build all packages
-pnpm dev             # Watch mode
-pnpm clean           # Clean build artifacts
-pnpm type-check      # TypeScript validation
-pnpm lint            # ESLint
-pnpm lint:fix        # Auto-fix linting
-```
-
-### Testing
-```bash
-pnpm test            # All tests
-pnpm test:core       # Core only
-pnpm test:cli        # CLI only
-pnpm test:coverage   # With coverage
-```
-
-### Running QA360
-```bash
-qa360 run qa360.yml              # Execute tests
-qa360 verify .qa360/runs/proof.json  # Verify proof
-qa360 doctor --fix                # Health check
-qa360 pack validate               # Validate config
-```
-
----
-
-## Phase Roadmap
-
-**Current Phase: 8 of 9**
-
-| Phase | Name | Status |
-|-------|------|--------|
-| 0-5 | Core Platform | ✅ Complete |
-| 6 | Test Data Intelligence | ✅ Complete |
-| 7 | Auto-Repair Module | ✅ Complete |
-| 8 | TUI & Dashboard | ✅ Complete |
-| 9 | Parallel CI | ⏳ Next |
-
-See [STATUS.md](./STATUS.md) for detailed progress.
-
----
-
-## Adding a New Feature
-
-### ⚠️ MANDATORY DEVELOPMENT WORKFLOW
-
-**CRITICAL**: Follow this exact sequence for ALL development work:
-
-```bash
-# 1. Always work on develop branch
-git checkout develop
-git pull origin develop
-
-# 2. Implement changes
-# - Add code to core/src/ for business logic
-# - Add CLI commands to cli/src/commands/
-# - Write tests in __tests__/ directories
-
-# 3. Test locally
-pnpm type-check
-pnpm lint
-pnpm test
-
-# 4. Commit to develop
-git add .
-git commit -m "feat(scope): description"
-git push origin develop
-
-# 5. Wait for CI GREEN on develop
-gh run list --branch develop --limit 1
-gh run watch <run-id>
-
-# 6. ONLY when CI is GREEN on develop, merge to main
-git checkout main
-git pull origin main
-git merge develop --no-ff -m "Merge branch 'develop'"
-git push origin main
-
-# 7. Verify CI is ALSO GREEN on main
-gh run list --branch main --limit 1
-
-# 8. Return to develop for next work
-git checkout develop
-```
-
-**STRICT RULES**:
-- ✅ Work on `develop` branch only
-- ✅ CI must be GREEN on `develop` before merging to `main`
-- ✅ CI must be GREEN on `main` after merge
-- ✅ Return to `develop` after successful merge
-- ❌ NO feature branches (work directly on develop)
-- ❌ NEVER commit directly to `main`
-- ❌ NEVER merge if CI is not green
-
-### Test Requirements
-
-**All new features MUST have**:
-1. Unit tests in `core/src/module/__tests__/`
-2. Integration tests for workflows
-3. Coverage >= 80% for new code
-4. Documentation updates
-
-### Example: Adding a New Adapter
-
-```bash
-# 1. Create adapter file
-touch core/src/adapters/my-adapter.ts
-
-# 2. Create tests
-touch core/src/adapters/__tests__/my-adapter.test.ts
-
-# 3. Export from core
-# Edit core/src/adapters/index.ts
-
-# 4. Test locally
-pnpm test:core
-
-# 5. Commit to develop
-git add .
-git commit -m "feat(adapters): add my-adapter for X testing"
-git push origin develop
-
-# 6. Monitor CI, merge when green
-```
-
----
-
-## Publication Workflow
-
-**IMPORTANT**: Follow this exact order for releases:
-
-```bash
-# 1. Commit to develop
-git checkout develop
-git pull origin develop
-# ... make changes ...
-git add .
-git commit -m "feat: description"
-git push origin develop
-
-# 2. Wait for CI green
-gh run list --branch develop --limit 1
-gh run watch <run-id>
-
-# 3. Merge to main
-git checkout main
-git pull origin main
-git merge develop --no-ff -m "Merge branch 'develop'"
-git push origin main
-
-# 4. Wait for CI green on main
-gh run list --branch main --limit 1
-gh run watch <run-id>
-
-# 5. Version bump (code changes only)
-cd cli
-npm version patch  # or minor/major
-git add package.json
-git commit -m "chore(cli): bump version to X.Y.Z"
-git push origin develop
-
-# 6. Merge version bump to main
-git checkout main && git merge develop --no-ff
-git push origin main
-
-# 7. Tag and publish
-git tag -a vX.Y.Z -m "Release vX.Y.Z"
-git push origin vX.Y.Z
-npm publish --access public
-```
-
----
-
-## Module Reference
-
-### AI Module (`core/src/ai/`)
-- `OllamaProvider` - Local LLM (Ollama)
-- `OpenAIProvider` - GPT-4 models
-- `AnthropicProvider` - Claude models
-- `MockProvider` - Testing mock
-- `ProviderFactory` - Auto fallback chain
-
-### Auth Module (`core/src/auth/`)
-9 providers: JWT, OAuth2, API Key, Bearer, Basic, TOTP, UI Login, GCP ADC, AWS IAM, Azure AD
-
-### Generation Module (`core/src/generation/`)
-- `PromptBuilder` - Few-shot prompts
-- `CodeFormatter` - Multi-language formatting
-- `TestOptimizer` - Deduplication
-- `CodeGenerator` - AI generation with timeout
-
-### Repair Module (`core/src/repair/`)
-- `ErrorAnalyzer` - Error classification (8 types)
-- `SuggestionEngine` - LLM fix suggestions
-- `CodeFixer` - Apply fixes with backup
-- `TestRepairer` - Orchestrate repair cycles
-
-### TDI Module (`core/src/tdi/`)
-- `TestAnalyzer` - Parse and detect frameworks
-- `CoverageEngine` - Coverage analysis
-- `DuplicationDetector` - Find duplicate tests
-- `SuggestionGenerator` - Improvement suggestions
-- `HealthCalculator` - Test health score
-
----
-
-## Testing Guidelines
-
-### Test Structure
-```
-core/src/module/
-├── index.ts
-├── __tests__/
-│   └── module.test.ts
-```
-
-### Coverage Targets
-- Core modules: 75%+
-- New features: 80%+
-- Critical paths (proof, vault): 85%+
-
-### Test Quality
-- Unit tests for pure functions
-- Integration tests for workflows
-- Mock external dependencies (LLM, filesystem)
-- Use temporary directories for file operations
-
----
-
-## Error Handling
-
-Every error must be:
-1. **Explicit** - Clear what went wrong
-2. **Pedagogical** - Explains why
-3. **Guiding** - Suggests fix
-
-```typescript
-throw new QA360Error(
-  'PACK_VALIDATION_FAILED',
-  'Pack file validation failed: missing required field "name"',
-  {
-    suggestion: 'Add a "name" field to your pack.yml',
-    example: 'name: "My API Tests"',
-    docs: 'https://qa360.ai/docs/pack-schema'
-  }
-);
-```
-
----
-
-## Conventional Commits
-
-```
-feat(scope): description     # New feature
-fix(scope): description      # Bug fix
-docs(scope): description     # Documentation
-test(scope): description     # Tests only
-refactor(scope): description # Refactoring
-chore(scope): description    # Build/config/deps
-```
-
-Examples:
-- `feat(core): add auto-repair module`
-- `fix(cli): resolve verification edge case`
-- `docs: update STATUS.md for Phase 7`
-
----
-
-## Key Dependencies
-
-| Package | Purpose | Version |
-|---------|---------|---------|
-| commander | CLI framework | ^12.1.0 |
-| chalk | Terminal colors | ^5.3.0 |
-| vitest | Test runner | ^1.6.0 |
-| typescript | Language | ^5.3.3 |
-| tweetnacl | Ed25519 crypto | ^1.0.3 |
-| better-sqlite3 | SQLite | ^9.4.3 |
-| ollama | LLM client (optional) | ^0.5.1 |
-
----
-
-## Environment Variables
-
-```bash
-# LLM Provider
-LLM_PROVIDER=ollama|openai|anthropic|mock
-LLM_MODEL=llama3.2
-LLM_BASE_URL=http://localhost:11434
-LLM_API_KEY=sk-xxx
-
-# QA360
-QA360_HOME=~/.qa360
-QA360_VERBOSE=1
-```
-
----
-
-## Documentation Files
-
-Only 3 documentation files exist (by design):
-
-1. **STATUS.md** - Project status, phases, metrics (THE SOURCE OF TRUTH)
-2. **DEVELOPMENT.md** - This file (developer guide)
-3. **ARCHITECTURE.md** - Technical architecture details
-
-All other docs are archived or should be integrated into these 3 files.
-
----
-
-## Support
-
-- **Issues**: https://github.com/xyqotech/qa360/issues
-- **Discussions**: https://github.com/xyqotech/qa360/discussions
-- **License**: MIT
-
----
-
-## Version 2.2 Roadmap - Testing Philosophy Implementation
-
-**Reference**: See [QA360_TESTING_PHILOSOPHY.md](./QA360_TESTING_PHILOSOPHY.md) for detailed rationale.
-
-### Overview
-
-Version 2.2 implements the three pillars from the Testing Philosophy that enable QA360 to support the **complete test pyramid** (Unit, Integration, E2E) with **maintainable, professional-grade test suites**.
-
-| Feature | Priority | Effort | Impact | Status |
-|---------|----------|--------|--------|--------|
-| Data Fixtures System | P0 | 3 days | ⭐⭐⭐⭐⭐ | Pending |
-| Page Object Reference | P0 | 5 days | ⭐⭐⭐⭐⭐ | Pending |
-| Unit Tests Ingestion | P0 | 1 week | ⭐⭐⭐⭐⭐ | Pending |
-
----
-
-### Feature 1: Data Fixtures System
-
-**Objective**: Separate test data from test logic (Playwright/NFLS best practice)
-
-**Pack Syntax**:
-```yaml
-# fixtures/users.yml
-testUsers:
-  buyer:
-    email: buyer@acme.test
-    password: Buyer123!
-  admin:
-    email: admin@acme.test
-    password: Admin456!
-
-# pack.yml
-version: 2
-fixtures:
-  - ./fixtures/users.yml
-
-gates:
-  login-test:
-    adapter: playwright-ui
-    config:
-      baseUrl: https://b2bshop.lovable.app
-      data: $fixtures.testUsers.buyer
-```
-
-**Implementation Files**:
-- `core/src/fixtures/loader.ts` - Fixture file loader (YAML/JSON)
-- `core/src/fixtures/resolver.ts` - Variable substitution ($fixtures.*)
-- `core/src/fixtures/__tests__/loader.test.ts` - Tests
-- `core/src/types/fixtures.ts` - TypeScript types
-
-**Validation**: Update `PackConfigV2` type to include `fixtures?: string[]`
-
----
-
-### Feature 2: Page Object Reference
-
-**Objective**: Enable TypeScript Page Objects import from YAML packs
-
-**Pack Syntax**:
-```yaml
-# pages/LoginPage.ts
-export class LoginPage {
-  async login(email: string, password: string) { ... }
-}
-
-# pack.yml
-gates:
-  e2e-login:
-    adapter: playwright-ui
-    config:
-      pageObjects: ./pages/
-      tests:
-        - use: LoginPage
-          call: login
-          args: [$fixtures.testUsers.buyer.email, $fixtures.testUsers.buyer.password]
-```
-
-**Implementation Files**:
-- `core/src/page-objects/runtime.ts` - TS/JS runtime for POM execution
-- `core/src/page-objects/importer.ts` - Dynamic module import
-- `core/src/page-objects/executor.ts` - Method invocation with fixture injection
-- `core/src/page-objects/__tests__/runtime.test.ts` - Tests
-
----
-
-### Feature 3: Unit Tests Ingestion
-
-**Objective**: Ingest Jest/Vitest/pytest results into QA360 Trust Score
-
-**Pack Syntax**:
-```yaml
-gates:
-  unit-tests:
-    adapter: vitest
-    config:
-      results: ./test-results/vitest-results.json
-      coverage: ./coverage/coverage-final.json
-      thresholds:
-        statements: 80%
-        branches: 70%
-        functions: 80%
-        lines: 80%
-```
-
-**Implementation Files**:
-- `core/src/adapters/vitest-adapter.ts` - Vitest JSON parser
-- `core/src/adapters/jest-adapter.ts` - Jest JSON parser
-- `core/src/adapters/pytest-adapter.ts` - Pytest JUnit parser
-- `core/src/adapters/__tests__/vitest-adapter.test.ts` - Tests
-
-**Existing Reference**: Use `playwright-native-api.ts` adapter structure as template
-
----
-
-### Implementation Order (Recommended)
-
-1. **Data Fixtures** (Foundation - 3 days)
-   - Lowest complexity, highest impact
-   - Enables Page Object feature
-
-2. **Page Object Reference** (Builds on Fixtures - 5 days)
-   - Depends on Fixtures for data injection
-   - Highest maintainability impact
-
-3. **Unit Tests Ingestion** (Independent - 1 week)
-   - Can be developed in parallel
-   - Opens 90% of testing market
-
----
-
-### Development References
-
-**Existing Adapters** (Study these before implementing):
-- `core/src/adapters/playwright-native-api.ts` - API adapter pattern
-- `core/src/adapters/playwright-ui.ts` - UI adapter pattern
-- `core/src/pack-v2/validator.ts` - Pack validation pattern
-
-**Type Definitions**:
-- `core/src/types/pack-v2.ts` - All pack type definitions
-
-**Testing Site**:
-- https://b2bshop.lovable.app (Use this for real-world testing)
-
----
-
-### Test Site: B2B Shop
-
-For implementation testing, use https://b2bshop.lovable.app:
-
-**Known Selectors**:
-- Email: `input[name='email']` or `#email-signin`
-- Password: `input[name='password']` or `#password-signin`
-- Submit: `button[type='submit']`
-- Dashboard: `.dashboard-content`
-- Products: `.product-card`
-
-**Test Accounts** (for development only):
-- `buyer@acme.test` / `Buyer123!`
-- `admin@acme.test` / `Admin456!`
-
----