qa360 2.1.7 → 2.2.0

package/docs/DEVELOPMENT.md

@@ -0,0 +1,545 @@
+# 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!`
+
+---