claude-flow-novice 2.15.11 → 2.16.1

package/claude-assets/hooks/SKILL.md

@@ -0,0 +1,518 @@
+# Post-Edit Validation Skill
+
+Validates files after modifications with syntax, formatting, and linting checks.
+
+## Overview
+
+The Post-Edit Validation Skill ensures code quality and correctness after edit operations by running configurable validation pipelines. It detects syntax errors, formatting issues, and code quality problems with real-time feedback.
+
+## Features
+
+- **Multi-Format Support**: TypeScript, JavaScript, JSON, Bash, Markdown, Python
+- **Syntax Validation**: Detects syntax errors in JSON and type errors in TypeScript
+- **Formatting Checks**: Detects trailing whitespace, mixed line endings, mixed indentation
+- **Code Quality**: Detects duplication, complexity patterns, and best practice violations
+- **Configurable Pipeline**: Enable/disable checks per file type
+- **Blocking Mode**: Optional enforcement of validation rules
+- **Non-Blocking Feedback**: Warnings and suggestions without blocking workflow
+
+## Architecture
+
+### Validation Pipeline
+
+```
+File Input
+    ↓
+Type Detection (.ts, .js, .json, .sh, etc.)
+    ↓
+Type-Specific Validation (syntax, type checking)
+    ↓
+Common Checks (formatting, duplication)
+    ↓
+Result Aggregation (errors, warnings, suggestions)
+    ↓
+Feedback Generation
+```
+
+### Configuration
+
+Default config: `.claude/hooks/cfn-post-edit.config.json`
+
+```json
+{
+  "enabled": true,
+  "blocking": false,
+  "validation": {
+    "typescript": {
+      "enabled": true,
+      "noEmit": true,
+      "skipLibCheck": true
+    },
+    "bash": {
+      "enabled": true,
+      "validators": ["pipe-safety", "dependency-checker", "line-endings"],
+      "timeout": 5000
+    }
+  },
+  "feedback": {
+    "provideSuggestions": true,
+    "autoFixable": ["LINT_ISSUES"],
+    "nonBlocking": ["TYPE_WARNING", "LINT_ISSUES", "BASH_VALIDATOR_WARNING"],
+    "blocking": ["SYNTAX_ERROR", "BASH_VALIDATOR_ERROR"]
+  }
+}
+```
+
+## TypeScript API
+
+### PostEditValidator Class
+
+```typescript
+import { PostEditValidator, ValidationResult } from '@/hooks/post-edit-validator';
+
+const validator = new PostEditValidator(projectRoot);
+
+// Load configuration
+const config = await validator.loadConfig();
+
+// Validate a file
+const result: ValidationResult = await validator.validateFile(filePath, agentId);
+// Result: {
+//   passed: true,
+//   errors: [],
+//   warnings: ["Mixed tabs and spaces detected"],
+//   suggestions: ["1 lines have trailing whitespace"],
+//   timestamp: "2024-11-20T10:30:45.123Z",
+//   filePath: "/project/src/file.ts",
+//   executionTime: 145
+// }
+
+// Run custom validation pipeline
+const customResult = await validator.runValidationPipeline(filePath);
+
+// Get human-readable summary
+const summary = validator.getValidationSummary(result);
+console.log(summary);
+// Output:
+// ✅ Validation passed
+// Warnings (1):
+//   - Mixed tabs and spaces detected
+// Suggestions (1):
+//   - 1 lines have trailing whitespace
+// Execution time: 145ms
+```
+
+### ValidationResult Interface
+
+```typescript
+interface ValidationResult {
+  passed: boolean;              // Overall validation status
+  errors: string[];             // Blocking issues
+  warnings: string[];           // Non-blocking concerns
+  suggestions: string[];        // Improvement recommendations
+  timestamp: string;            // ISO 8601 timestamp
+  filePath: string;             // Validated file path
+  executionTime: number;        // Milliseconds
+}
+```
+
+## CLI Interface
+
+### Post-Edit Hook CLI
+
+Validates file after modification:
+
+```bash
+# TypeScript compiled version
+node dist/cli/post-edit-hook.js /path/to/file.ts
+
+# With agent ID
+node dist/cli/post-edit-hook.js /path/to/file.ts --agent-id agent-123
+
+# Blocking mode (exit 1 on failure)
+node dist/cli/post-edit-hook.js /path/to/file.ts --blocking
+
+# Output
+# {
+#   "passed": true,
+#   "errors": [],
+#   "warnings": [],
+#   "suggestions": [],
+#   "timestamp": "2024-11-20T10:30:45.123Z",
+#   "filePath": "/path/to/file.ts",
+#   "executionTime": 145
+# }
+```
+
+### Bash Wrapper
+
+For agent compatibility:
+
+```bash
+# Primary wrapper (tries TypeScript, falls back to bash)
+./.claude/hooks/cfn-invoke-post-edit-ts.sh /path/to/file.ts
+
+# With agent ID
+./.claude/hooks/cfn-invoke-post-edit-ts.sh /path/to/file.ts --agent-id agent-123
+
+# Blocking mode
+./.claude/hooks/cfn-invoke-post-edit-ts.sh /path/to/file.ts --blocking
+
+# Legacy bash-only wrapper
+./.claude/hooks/cfn-invoke-post-edit.sh /path/to/file.ts
+```
+
+## Validators by File Type
+
+### TypeScript/JavaScript
+
+```typescript
+// Checks:
+// - Type errors (via tsc --noEmit)
+// - Syntax errors
+// - Import/export correctness
+// - Undefined symbols
+
+const result = await validator.validateFile('src/component.ts');
+if (!result.passed) {
+  result.errors.forEach(err => console.error(err));
+}
+```
+
+### JSON
+
+```typescript
+// Checks:
+// - JSON syntax validity
+// - Schema structure
+// - Special character handling
+
+const result = await validator.validateFile('config.json');
+// Detects: { invalid json }
+```
+
+### Bash Scripts
+
+```typescript
+// Checks:
+// - Unquoted variable usage
+// - Pipe-to-while-read patterns
+// - Missing strict mode (set -euo pipefail)
+// - Line endings (LF vs CRLF)
+
+const result = await validator.validateFile('script.sh');
+// Warnings: "unquoted variables", "pipe-to-while-read", "missing strict mode"
+```
+
+### Formatting Checks (All Types)
+
+```typescript
+// Checks run on all file types:
+// - Trailing whitespace
+// - Mixed line endings (CRLF + LF)
+// - Mixed indentation (tabs + spaces)
+
+const result = await validator.validateFile('any-file.ts');
+if (result.warnings.some(w => w.includes('trailing'))) {
+  // Fix trailing whitespace
+}
+```
+
+### Duplication Detection
+
+When enabled:
+
+```typescript
+// Checks:
+// - Identical consecutive lines (>20 chars)
+// - Copy-paste patterns
+// - Duplicate functions/methods
+
+const result = await validator.validateFile('file.ts');
+result.suggestions.forEach(s => {
+  if (s.includes('Duplicate')) {
+    // Consider refactoring duplicated code
+  }
+});
+```
+
+## Integration
+
+### In Agent Workflows
+
+Post-edit validation is automatically called via hooks after Edit/Write operations:
+
+```bash
+# After Edit or Write operation
+./.claude/hooks/cfn-invoke-post-edit-ts.sh "$FILE_PATH" --agent-id "$AGENT_ID"
+
+# In blocking mode (fails the workflow if validation fails)
+./.claude/hooks/cfn-invoke-post-edit-ts.sh "$FILE_PATH" --agent-id "$AGENT_ID" --blocking
+```
+
+### Redis Publishing
+
+When enabled, validation results are published to Redis:
+
+```json
+{
+  "channel": "swarm:hooks:post-edit",
+  "message": {
+    "file": "/path/to/file.ts",
+    "agentId": "agent-123",
+    "exitCode": 0,
+    "timestamp": "1700000000"
+  }
+}
+```
+
+## Use Cases
+
+### 1. Type Safety
+
+```typescript
+// Catch type errors immediately
+const result = await validator.validateFile('app.ts');
+
+if (!result.passed) {
+  console.error('Type errors detected:');
+  result.errors.forEach(e => console.error(`  - ${e}`));
+  process.exit(1);
+}
+```
+
+### 2. Code Quality Gates
+
+```typescript
+// Enforce formatting standards
+const result = await validator.validateFile('src/utils.ts');
+
+if (result.warnings.length > 0) {
+  console.warn('Code quality issues found:');
+  result.warnings.forEach(w => console.warn(`  - ${w}`));
+}
+```
+
+### 3. Pre-Commit Validation
+
+```bash
+#!/bin/bash
+# Pre-commit hook
+
+FILES=$(git diff --cached --name-only --diff-filter=ACM)
+
+for file in $FILES; do
+  result=$(./.claude/hooks/cfn-invoke-post-edit-ts.sh "$file" --blocking)
+  if [ $? -ne 0 ]; then
+    echo "Validation failed for $file"
+    exit 1
+  fi
+done
+```
+
+### 4. Agent Feedback Loop
+
+```typescript
+// Provide actionable feedback to agents
+const result = await validator.validateFile(filePath, agentId);
+const summary = validator.getValidationSummary(result);
+
+console.log('Validation Report:');
+console.log(summary);
+console.log('\nNext Steps:');
+
+if (result.errors.length > 0) {
+  console.log('Fix errors above before proceeding');
+} else if (result.suggestions.length > 0) {
+  console.log('Consider addressing suggestions for better code quality');
+}
+```
+
+## Configuration
+
+### Enable/Disable Checks
+
+```bash
+# Disable TypeScript checking
+export TS_VALIDATION_ENABLED=false
+
+# Enable formatting checks only
+export CHECK_FORMATTING=true
+export CHECK_SYNTAX=false
+
+# Strict mode (all checks blocking)
+export BLOCKING_VALIDATION=true
+```
+
+### Custom Pipeline
+
+```typescript
+// Create custom validator with specific rules
+const validator = new PostEditValidator(projectRoot);
+validator.config = {
+  checkSyntax: true,
+  checkFormatting: true,
+  checkDuplication: true,
+  blockingValidation: false,
+  typescript: { enabled: true, noEmit: true, skipLibCheck: true },
+  bash: { enabled: true, validators: ['pipe-safety'], timeout: 5000 },
+};
+
+const result = await validator.runValidationPipeline(filePath);
+```
+
+## Testing
+
+Run tests with Jest:
+
+```bash
+npm test tests/post-edit-validator.test.ts
+
+# With coverage
+npm test tests/post-edit-validator.test.ts -- --coverage
+
+# Specific test suite
+npm test tests/post-edit-validator.test.ts -t "validateJSON"
+```
+
+Test coverage includes:
+- JSON syntax validation
+- Bash script validation
+- Formatting checks (whitespace, line endings, indentation)
+- Duplication detection
+- File type detection
+- Configuration loading
+- Result aggregation
+- Error handling
+- Edge cases (empty files, large files, special characters)
+
+## Performance
+
+- **JSON Validation**: <5ms
+- **Bash Validation**: <20ms
+- **TypeScript Check**: 100-500ms (depends on project size)
+- **Formatting Checks**: <10ms
+- **Full Pipeline**: <600ms typical
+
+## Troubleshooting
+
+### TypeScript Check Fails
+
+```bash
+# Verify TypeScript is installed
+npm ls typescript
+
+# Check tsconfig.json
+cat tsconfig.json
+
+# Run tsc directly
+npx tsc --noEmit
+```
+
+### JSON Validation Issues
+
+```bash
+# Validate JSON syntax with jq
+jq . < file.json
+
+# Pretty-print and check
+jq '.' < file.json > /tmp/formatted.json
+```
+
+### Bash Validation Warnings
+
+```bash
+# Check bash syntax directly
+bash -n script.sh
+
+# Verify strict mode
+grep 'set -euo pipefail' script.sh
+
+# Fix unquoted variables
+sed -i 's/\$\([a-zA-Z_][a-zA-Z0-9_]*\)/"$\1"/g' script.sh
+```
+
+## Configuration Reference
+
+### cfn-post-edit.config.json
+
+```json
+{
+  "enabled": true,
+  "version": "2.0.0",
+  "blocking": false,
+  "validation": {
+    "typescript": {
+      "enabled": true,
+      "noEmit": true,
+      "skipLibCheck": true
+    },
+    "bash": {
+      "enabled": true,
+      "validators": ["pipe-safety", "dependency-checker", "line-endings"],
+      "timeout": 5000
+    }
+  },
+  "feedback": {
+    "provideSuggestions": true,
+    "autoFixable": ["LINT_ISSUES"],
+    "nonBlocking": ["TYPE_WARNING", "LINT_ISSUES"],
+    "blocking": ["SYNTAX_ERROR", "BASH_VALIDATOR_ERROR"]
+  }
+}
+```
+
+## References
+
+- **Configuration**: `.claude/hooks/cfn-post-edit.config.json`
+- **Tests**: `tests/post-edit-validator.test.ts`
+- **CLI Entry**: `src/cli/post-edit-hook.ts`
+- **Hook Wrappers**: `.claude/hooks/cfn-invoke-post-edit*.sh`
+- **Pre-Edit Backup**: `.claude/skills/pre-edit-backup/SKILL.md`
+
+---
+
+## ⚠️ Bash Deprecation Notice
+
+**The bash implementation of this skill is deprecated as of 2025-11-20.**
+
+**Deprecation Date:** 2025-11-20  
+**Removal Date:** 2026-02-20 (90 days)  
+**TypeScript Implementation:** dist/cli/pre-edit-hook.js and dist/cli/post-edit-hook.js  
+**Migration Guide:** src/hooks/README.md  
+
+### Why Migrate to TypeScript?
+
+- **Type Safety:** Zero runtime type errors with compile-time validation
+- **Better Performance:** 5-10ms faster execution, optimized Redis operations
+- **Comprehensive Testing:** 90%+ test coverage with unit, integration, and E2E tests
+- **Modern Tooling:** Full IDE support, autocomplete, and inline documentation
+- **Maintainability:** Single source of truth, easier debugging
+
+### Automatic Migration
+
+Set environment variable to automatically use TypeScript:
+
+```bash
+export USE_TYPESCRIPT=true
+```
+
+All coordinators and orchestrators will automatically prefer TypeScript implementations.
+
+### Rollback
+
+If issues arise:
+
+```bash
+export USE_TYPESCRIPT=false
+```
+
+Bash scripts will continue working for the 90-day deprecation period.
+
+### See Also
+
+- **Complete Deprecation List:** [docs/BASH_DEPRECATION_NOTICE.md](../../../docs/BASH_DEPRECATION_NOTICE.md)
+- **TypeScript Benefits:** See individual migration guides
+- **Test Coverage:** Run `npm test` to verify TypeScript implementation
+
+---