mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-10 02:24:35 +08:00
feat: implement FlowExecutor for executing flow definitions with DAG traversal and node execution
This commit is contained in:
catlog22
391
.claude/commands/workflow/tools/code-validation-gate.md
Normal file
391
.claude/commands/workflow/tools/code-validation-gate.md
Normal file
@@ -0,0 +1,391 @@
|
||||
---
|
||||
name: code-validation-gate
|
||||
description: Validate AI-generated code for common errors (imports, variables, types) before test execution
|
||||
argument-hint: "--session WFS-test-session-id [--fix] [--strict]"
|
||||
examples:
|
||||
- /workflow:tools:code-validation-gate --session WFS-test-auth
|
||||
- /workflow:tools:code-validation-gate --session WFS-test-auth --fix
|
||||
- /workflow:tools:code-validation-gate --session WFS-test-auth --strict
|
||||
---
|
||||
|
||||
# Code Validation Gate Command
|
||||
|
||||
## Overview
|
||||
|
||||
Pre-test validation gate that checks AI-generated code for common errors before test execution. This prevents wasted test cycles on code with fundamental issues like import errors, variable conflicts, and type mismatches.
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
- **Fail Fast**: Catch fundamental errors before expensive test execution
|
||||
- **AI-Aware**: Specifically targets common AI code generation mistakes
|
||||
- **Auto-Remediation**: Attempt safe fixes before failing
|
||||
- **Clear Feedback**: Provide actionable fix suggestions for manual intervention
|
||||
|
||||
## Target Error Categories
|
||||
|
||||
### L0.1: Compilation Errors
|
||||
- TypeScript compilation failures
|
||||
- Syntax errors
|
||||
- Module resolution failures
|
||||
|
||||
### L0.2: Import Errors
|
||||
- Unresolved module imports (hallucinated packages)
|
||||
- Circular dependencies
|
||||
- Duplicate imports
|
||||
- Unused imports
|
||||
|
||||
### L0.3: Variable Errors
|
||||
- Variable redeclaration
|
||||
- Scope conflicts (shadowing)
|
||||
- Undefined variable usage
|
||||
- Unused variables
|
||||
|
||||
### L0.4: Type Errors (TypeScript)
|
||||
- Type mismatches
|
||||
- Missing type definitions
|
||||
- Excessive `any` usage
|
||||
- Implicit `any` types
|
||||
|
||||
### L0.5: AI-Specific Patterns
|
||||
- Placeholder code (`// TODO: implement`)
|
||||
- Hallucinated package imports
|
||||
- Mock code in production files
|
||||
- Inconsistent naming patterns
|
||||
|
||||
## Execution Process
|
||||
|
||||
```
|
||||
Input Parsing:
|
||||
├─ Parse flags: --session (required), --fix, --strict
|
||||
└─ Load test-quality-config.json
|
||||
|
||||
Phase 1: Context Loading
|
||||
├─ Load session metadata
|
||||
├─ Identify target files (from IMPL-001 output or context-package)
|
||||
└─ Detect project configuration (tsconfig, eslint, etc.)
|
||||
|
||||
Phase 2: Validation Execution
|
||||
├─ L0.1: Run TypeScript compilation check
|
||||
├─ L0.2: Run import validation
|
||||
├─ L0.3: Run variable validation
|
||||
├─ L0.4: Run type validation
|
||||
└─ L0.5: Run AI-specific checks
|
||||
|
||||
Phase 3: Result Analysis
|
||||
├─ Aggregate all findings by severity
|
||||
├─ Calculate pass/fail status
|
||||
└─ Generate fix suggestions
|
||||
|
||||
Phase 4: Auto-Fix (if --fix enabled)
|
||||
├─ Apply safe auto-fixes (imports, formatting)
|
||||
├─ Re-run validation
|
||||
└─ Report remaining issues
|
||||
|
||||
Phase 5: Gate Decision
|
||||
├─ PASS: Proceed to IMPL-001.5
|
||||
├─ SOFT_FAIL: Auto-fix applied, needs re-validation
|
||||
└─ HARD_FAIL: Block with detailed report
|
||||
```
|
||||
|
||||
## Execution Lifecycle
|
||||
|
||||
### Phase 1: Context Loading
|
||||
|
||||
**Load session and identify validation targets.**
|
||||
|
||||
```javascript
|
||||
// Load session metadata
|
||||
Read(".workflow/active/{session_id}/workflow-session.json")
|
||||
|
||||
// Load context package for target files
|
||||
Read(".workflow/active/{session_id}/.process/context-package.json")
|
||||
// OR
|
||||
Read(".workflow/active/{session_id}/.process/test-context-package.json")
|
||||
|
||||
// Identify files to validate:
|
||||
// 1. Source files from context.implementation_files
|
||||
// 2. Test files from IMPL-001 output (if exists)
|
||||
// 3. All modified files since session start
|
||||
```
|
||||
|
||||
**Target File Discovery**:
|
||||
- Source files: `context.focus_paths` from context-package
|
||||
- Generated tests: `.workflow/active/{session_id}/.task/IMPL-001-output/`
|
||||
- All TypeScript/JavaScript in target directories
|
||||
|
||||
### Phase 2: Validation Execution
|
||||
|
||||
**Execute validation checks in order of dependency.**
|
||||
|
||||
#### L0.1: TypeScript Compilation
|
||||
|
||||
```bash
|
||||
# Primary check - catches most fundamental errors
|
||||
npx tsc --noEmit --skipLibCheck --project tsconfig.json 2>&1
|
||||
|
||||
# Parse output for errors
|
||||
# Critical: Any compilation error blocks further validation
|
||||
```
|
||||
|
||||
**Error Patterns**:
|
||||
```
|
||||
error TS2307: Cannot find module 'xxx'
|
||||
error TS2451: Cannot redeclare block-scoped variable 'xxx'
|
||||
error TS2322: Type 'xxx' is not assignable to type 'yyy'
|
||||
```
|
||||
|
||||
#### L0.2: Import Validation
|
||||
|
||||
```bash
|
||||
# Check for circular dependencies
|
||||
npx madge --circular --extensions ts,tsx,js,jsx {target_dirs}
|
||||
|
||||
# ESLint import rules
|
||||
npx eslint --rule 'import/no-duplicates: error' --rule 'import/no-unresolved: error' {files}
|
||||
```
|
||||
|
||||
**Hallucinated Package Check**:
|
||||
```javascript
|
||||
// Extract all imports from files
|
||||
// Verify each package exists in package.json or node_modules
|
||||
// Flag any unresolvable imports as "hallucinated"
|
||||
```
|
||||
|
||||
#### L0.3: Variable Validation
|
||||
|
||||
```bash
|
||||
# ESLint variable rules
|
||||
npx eslint --rule 'no-shadow: error' --rule 'no-undef: error' --rule 'no-redeclare: error' {files}
|
||||
```
|
||||
|
||||
#### L0.4: Type Validation
|
||||
|
||||
```bash
|
||||
# TypeScript strict checks
|
||||
npx tsc --noEmit --strict {files}
|
||||
|
||||
# Check for any abuse
|
||||
npx eslint --rule '@typescript-eslint/no-explicit-any: warn' {files}
|
||||
```
|
||||
|
||||
#### L0.5: AI-Specific Checks
|
||||
|
||||
```bash
|
||||
# Check for placeholder code
|
||||
grep -rn "// TODO: implement\|// Add your code here\|throw new Error.*Not implemented" {files}
|
||||
|
||||
# Check for mock code in production files
|
||||
grep -rn "jest\.mock\|sinon\.\|vi\.mock" {source_files_only}
|
||||
```
|
||||
|
||||
### Phase 3: Result Analysis
|
||||
|
||||
**Aggregate and categorize findings.**
|
||||
|
||||
```javascript
|
||||
const findings = {
|
||||
critical: [], // Blocks all progress
|
||||
error: [], // Blocks with threshold
|
||||
warning: [] // Advisory only
|
||||
};
|
||||
|
||||
// Apply thresholds from config
|
||||
const config = loadConfig("test-quality-config.json");
|
||||
const thresholds = config.code_validation.severity_thresholds;
|
||||
|
||||
// Gate decision
|
||||
if (findings.critical.length > thresholds.critical) {
|
||||
decision = "HARD_FAIL";
|
||||
} else if (findings.error.length > thresholds.error) {
|
||||
decision = "SOFT_FAIL"; // Try auto-fix
|
||||
} else {
|
||||
decision = "PASS";
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 4: Auto-Fix (Optional)
|
||||
|
||||
**Apply safe automatic fixes when --fix flag provided.**
|
||||
|
||||
```bash
|
||||
# Safe fixes only
|
||||
npx eslint --fix --rule 'import/no-duplicates: error' --rule 'unused-imports/no-unused-imports: error' {files}
|
||||
|
||||
# Re-run validation after fixes
|
||||
# Report what was fixed vs what remains
|
||||
```
|
||||
|
||||
**Safe Fix Categories**:
|
||||
- Remove unused imports
|
||||
- Remove duplicate imports
|
||||
- Fix import ordering
|
||||
- Remove unused variables (with caution)
|
||||
- Formatting fixes
|
||||
|
||||
**Unsafe (Manual Only)**:
|
||||
- Missing imports (need to determine correct package)
|
||||
- Type errors (need to understand intent)
|
||||
- Variable shadowing (need to understand scope intent)
|
||||
|
||||
### Phase 5: Gate Decision
|
||||
|
||||
**Determine next action based on results.**
|
||||
|
||||
| Decision | Condition | Action |
|
||||
|----------|-----------|--------|
|
||||
| **PASS** | critical=0, error<=3, warning<=10 | Proceed to IMPL-001.5 |
|
||||
| **SOFT_FAIL** | critical=0, error>3 OR fixable issues | Auto-fix and retry (max 2) |
|
||||
| **HARD_FAIL** | critical>0 OR max retries exceeded | Block with report |
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
### Validation Report
|
||||
|
||||
**File**: `.workflow/active/{session_id}/.process/code-validation-report.md`
|
||||
|
||||
```markdown
|
||||
# Code Validation Report
|
||||
|
||||
**Session**: {session_id}
|
||||
**Timestamp**: {timestamp}
|
||||
**Status**: PASS | SOFT_FAIL | HARD_FAIL
|
||||
|
||||
## Summary
|
||||
- Files Validated: {count}
|
||||
- Critical Issues: {count}
|
||||
- Errors: {count}
|
||||
- Warnings: {count}
|
||||
|
||||
## Critical Issues (Must Fix)
|
||||
### Import Errors
|
||||
- `src/auth/service.ts:5` - Cannot find module 'non-existent-package'
|
||||
- **Suggestion**: Check if package exists, may be hallucinated by AI
|
||||
|
||||
### Variable Conflicts
|
||||
- `src/utils/helper.ts:12` - Cannot redeclare block-scoped variable 'config'
|
||||
- **Suggestion**: Rename one of the variables or merge declarations
|
||||
|
||||
## Errors (Should Fix)
|
||||
...
|
||||
|
||||
## Warnings (Consider Fixing)
|
||||
...
|
||||
|
||||
## Auto-Fix Applied
|
||||
- Removed 3 unused imports in `src/auth/service.ts`
|
||||
- Fixed import ordering in `src/utils/index.ts`
|
||||
|
||||
## Remaining Issues Requiring Manual Fix
|
||||
...
|
||||
|
||||
## Next Steps
|
||||
- [ ] Fix critical issues before proceeding
|
||||
- [ ] Review error suggestions
|
||||
- [ ] Re-run validation: `/workflow:tools:code-validation-gate --session {session_id}`
|
||||
```
|
||||
|
||||
### JSON Report (Machine-Readable)
|
||||
|
||||
**File**: `.workflow/active/{session_id}/.process/code-validation-report.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "WFS-test-xxx",
|
||||
"timestamp": "2025-01-30T10:00:00Z",
|
||||
"status": "HARD_FAIL",
|
||||
"summary": {
|
||||
"files_validated": 15,
|
||||
"critical": 2,
|
||||
"error": 5,
|
||||
"warning": 8
|
||||
},
|
||||
"findings": {
|
||||
"critical": [
|
||||
{
|
||||
"category": "import",
|
||||
"file": "src/auth/service.ts",
|
||||
"line": 5,
|
||||
"message": "Cannot find module 'non-existent-package'",
|
||||
"suggestion": "Check if package exists in package.json",
|
||||
"auto_fixable": false
|
||||
}
|
||||
],
|
||||
"error": [...],
|
||||
"warning": [...]
|
||||
},
|
||||
"auto_fixes_applied": [...],
|
||||
"gate_decision": "HARD_FAIL",
|
||||
"retry_count": 0,
|
||||
"max_retries": 2
|
||||
}
|
||||
```
|
||||
|
||||
## Command Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--session` | Test session ID (required) | - |
|
||||
| `--fix` | Enable auto-fix for safe issues | false |
|
||||
| `--strict` | Use strict thresholds (0 errors allowed) | false |
|
||||
| `--files` | Specific files to validate (comma-separated) | All target files |
|
||||
| `--skip-types` | Skip TypeScript type checks | false |
|
||||
|
||||
## Integration
|
||||
|
||||
### Command Chain
|
||||
|
||||
- **Called By**: `/workflow:test-fix-gen` (after IMPL-001)
|
||||
- **Requires**: IMPL-001 output OR context-package.json
|
||||
- **Followed By**: IMPL-001.5 (Test Quality Gate) on PASS
|
||||
|
||||
### Task JSON Integration
|
||||
|
||||
When used in test-fix workflow, generates task:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-001.3-validation",
|
||||
"meta": {
|
||||
"type": "code-validation",
|
||||
"agent": "@test-fix-agent"
|
||||
},
|
||||
"context": {
|
||||
"depends_on": ["IMPL-001"],
|
||||
"requirements": "Validate generated code for AI common errors"
|
||||
},
|
||||
"flow_control": {
|
||||
"validation_config": "~/.claude/workflows/test-quality-config.json",
|
||||
"max_retries": 2,
|
||||
"auto_fix_enabled": true
|
||||
},
|
||||
"acceptance_criteria": [
|
||||
"Zero critical issues",
|
||||
"Maximum 3 error issues",
|
||||
"All imports resolvable",
|
||||
"No variable redeclarations"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| tsconfig.json not found | Use default compiler options |
|
||||
| ESLint not installed | Skip ESLint checks, use tsc only |
|
||||
| madge not installed | Skip circular dependency check |
|
||||
| No files to validate | Return PASS (nothing to check) |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Run Early**: Execute validation immediately after code generation
|
||||
2. **Use --fix First**: Let auto-fix resolve trivial issues
|
||||
3. **Review Suggestions**: AI fix suggestions may need human judgment
|
||||
4. **Don't Skip Critical**: Never proceed with critical errors
|
||||
5. **Track Patterns**: Common failures indicate prompt improvement opportunities
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/workflow:test-fix-gen` - Parent workflow that invokes this command
|
||||
- `/workflow:tools:test-quality-gate` - Next phase (IMPL-001.5) for test quality
|
||||
- `/workflow:test-cycle-execute` - Execute tests after validation passes
|
||||
Reference in New Issue
Block a user