gh-jschulte-claude-plugins-stackshift/commands/stackshift.validate.md

name, description

name	description
stackshift.validate	Systematically validate implementation against specifications. Runs tests, TypeScript checks, and spec compliance validation. Use after implementation to ensure quality before finalizing.

Validate Implementation

Comprehensive validation of implementation against specifications with automatic fixing capability.

---

Usage

# Run full validation
/stackshift.validate

# Run with automatic fixes
/stackshift.validate --fix

# Focus on specific feature
/stackshift.validate --feature=vehicle-details

# TypeScript check only
/stackshift.validate --type-check-only

---

What This Does

Phase 1: Assessment

1. Run full test suite
2. Run TypeScript compilation
3. Categorize failures (imports, types, spec violations, mocks)
4. Cross-reference against specifications

Phase 2: Spec Compliance

1. Validate implementation matches spec requirements
2. Check for missing specified features
3. Verify API contracts are implemented
4. Assess priorities (spec violations are P1)

Phase 3: Resolution (if --fix mode)

1. Fix import/export issues
2. Fix type mismatches (aligned with spec)
3. Fix specification compliance gaps
4. Fix test mocks
5. Validate after each fix
6. Rollback if fixes break things

Phase 4: Final Validation

1. Re-run all tests
2. Verify TypeScript compilation
3. Confirm spec compliance
4. Generate quality report

---

Command Execution

Phase 1: Comprehensive Assessment

echo "🚀 Starting Implementation Validation"
echo ""

# Run test suite
echo "🧪 Running test suite..."
npm test 2>&1 | tee test-results.log

# Extract statistics
TOTAL_TESTS=$(grep -o "[0-9]* tests" test-results.log | head -1 || echo "0")
FAILED_TESTS=$(grep -o "[0-9]* failed" test-results.log || echo "0")
PASSED_TESTS=$(grep -o "[0-9]* passed" test-results.log || echo "0")

echo "📊 Test Results:"
echo "   Total: $TOTAL_TESTS"
echo "   Passed: $PASSED_TESTS"
echo "   Failed: $FAILED_TESTS"
echo ""

# Run TypeScript validation
echo "🔍 Running TypeScript validation..."
npx tsc --noEmit 2>&1 | tee typescript-results.log

TS_ERRORS=$(grep -c "error TS" typescript-results.log || echo "0")
echo "📊 TypeScript Results:"
echo "   Errors: $TS_ERRORS"
echo ""

Phase 2: Specification Validation

echo "📋 Validating against specifications..."
echo ""

# Find all spec files
SPEC_DIR=".specify/memory/specifications"
if [ ! -d "$SPEC_DIR" ]; then
  SPEC_DIR="specs"
fi

# For each spec, check implementation
for spec in $(find $SPEC_DIR -name "*.md" -o -name "spec.md"); do
  SPEC_NAME=$(basename $(dirname $spec) 2>/dev/null || basename $spec .md)

  echo "🔍 Checking: $SPEC_NAME"

  # Extract required files/components from spec
  # Look for "Files:" or "Implementation Status:" sections
  grep -A 20 "^## Files\|^## Implementation Status" "$spec" | \
    grep -o "\`[^`]*\.(ts|tsx|js|jsx|py|go)\`" | \
    sed 's/`//g' > required-files-$SPEC_NAME.txt

  # Check if required files exist
  while read file; do
    if [ ! -f "$file" ]; then
      echo "   ❌ Missing file: $file"
      echo "SPEC_VIOLATION: $SPEC_NAME missing $file" >> spec-violations.log
    fi
  done < required-files-$SPEC_NAME.txt

  # Clean up temp file
  rm required-files-$SPEC_NAME.txt
done

SPEC_VIOLATIONS=$(wc -l < spec-violations.log 2>/dev/null || echo "0")
echo ""
echo "📊 Specification Compliance:"
echo "   Violations: $SPEC_VIOLATIONS"
echo ""

Phase 3: Categorize Issues

echo "📋 Categorizing failures..."
echo ""

# Extract import/export errors
grep -n "Cannot find module\|Module not found\|has no exported member" \
  test-results.log typescript-results.log 2>/dev/null > import-errors.log

# Extract type mismatch errors
grep -n "Type.*is not assignable\|Property.*does not exist\|Argument of type" \
  typescript-results.log 2>/dev/null > type-errors.log

# Extract test assertion failures
grep -n "AssertionError\|Expected.*but received\|toBe\|toEqual" \
  test-results.log 2>/dev/null > test-failures.log

IMPORT_ERRORS=$(wc -l < import-errors.log 2>/dev/null || echo "0")
TYPE_ERRORS=$(wc -l < type-errors.log 2>/dev/null || echo "0")
TEST_FAILURES=$(wc -l < test-failures.log 2>/dev/null || echo "0")

echo "📊 Issue Breakdown:"
echo "   P1 - Spec Violations: $SPEC_VIOLATIONS (highest priority)"
echo "   P2 - Type Errors: $TYPE_ERRORS"
echo "   P3 - Import Errors: $IMPORT_ERRORS"
echo "   P4 - Test Failures: $TEST_FAILURES"
echo ""

Phase 4: Fix Mode (if --fix)

# Only run if --fix flag provided
if [[ "$FIX_MODE" == "true" ]]; then
  echo "🔧 Automatic fix mode enabled"
  echo "⚠️  Creating backup..."

  # Backup current state
  git stash push -m "stackshift-validate backup $(date +%Y%m%d-%H%M%S)"

  echo ""
  echo "🔧 Fixing issues in priority order..."
  echo ""

  # P1: Fix spec violations first
  if [[ "$SPEC_VIOLATIONS" != "0" ]]; then
    echo "🔧 P1: Resolving specification violations..."

    # Read spec violations and attempt to implement missing files/features
    while read violation; do
      echo "   Fixing: $violation"
      # Implementation would add missing files based on spec requirements
    done < spec-violations.log

    # Re-validate
    echo "   Re-checking spec compliance..."
    # Re-run spec validation
  fi

  # P2: Fix type errors
  if [[ "$TYPE_ERRORS" != "0" ]]; then
    echo "🔧 P2: Resolving type errors..."

    # Show first few type errors for context
    head -10 type-errors.log

    echo "   Analyzing type mismatches against spec..."
    # Implementation would fix types to match spec definitions
  fi

  # P3: Fix import errors
  if [[ "$IMPORT_ERRORS" != "0" ]]; then
    echo "🔧 P3: Resolving import errors..."

    # Show import errors
    cat import-errors.log

    echo "   Adding missing exports..."
    # Implementation would add missing exports
  fi

  # P4: Fix test failures
  if [[ "$TEST_FAILURES" != "0" ]]; then
    echo "🔧 P4: Resolving test failures..."

    # Show test failures
    head -10 test-failures.log

    echo "   Fixing test assertions..."
    # Implementation would fix failing tests
  fi

  echo ""
  echo "🔄 Re-running validation after fixes..."

  # Re-run tests and type check
  npm test 2>&1 | tee final-test-results.log
  npx tsc --noEmit 2>&1 | tee final-ts-results.log

  FINAL_FAILED=$(grep -o "[0-9]* failed" final-test-results.log || echo "0")
  FINAL_TS_ERRORS=$(grep -c "error TS" final-ts-results.log || echo "0")

  if [[ "$FINAL_FAILED" == "0" && "$FINAL_TS_ERRORS" == "0" ]]; then
    echo "✅ All issues resolved!"
    echo "🎉 Implementation validated successfully"
  else
    echo "❌ Some issues remain"
    echo "   Failed tests: $FINAL_FAILED"
    echo "   Type errors: $FINAL_TS_ERRORS"
    echo ""
    echo "🔄 Rolling back changes..."
    git stash pop
    exit 1
  fi
else
  echo "ℹ️  Run with --fix to automatically resolve issues"
fi

Final Report

echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "📊 Validation Summary"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""

if [[ "$SPEC_VIOLATIONS" == "0" && "$TYPE_ERRORS" == "0" && \
      "$IMPORT_ERRORS" == "0" && "$TEST_FAILURES" == "0" ]]; then
  echo "✅ VALIDATION PASSED"
  echo ""
  echo "   All tests passing: ✅"
  echo "   TypeScript compiling: ✅"
  echo "   Spec compliance: ✅"
  echo "   Code quality: ✅"
  echo ""
  echo "🚀 Implementation is production-ready!"
else
  echo "⚠️  VALIDATION ISSUES FOUND"
  echo ""
  echo "   Spec Violations: $SPEC_VIOLATIONS"
  echo "   Type Errors: $TYPE_ERRORS"
  echo "   Import Errors: $IMPORT_ERRORS"
  echo "   Test Failures: $TEST_FAILURES"
  echo ""
  echo "💡 Recommendations:"
  echo "   1. Run with --fix to auto-resolve issues"
  echo "   2. Review spec-violations.log for spec compliance gaps"
  echo "   3. Run /stackshift.review for detailed code review"
fi

echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

# Cleanup temp files
rm -f test-results.log typescript-results.log import-errors.log \
      type-errors.log test-failures.log spec-violations.log \
      final-test-results.log final-ts-results.log

---

Options

• --fix - Automatically attempt to fix identified issues
• --feature=<name> - Focus validation on specific feature
• --spec-first - Prioritize spec compliance (default)
• --type-check-only - Only run TypeScript validation
• --no-rollback - Disable automatic rollback on failures

---

Success Criteria

✅ All tests pass (0 failures) ✅ TypeScript compiles (0 errors) ✅ Spec compliance (0 violations) ✅ Quality gates passed

---

Integration with StackShift

Auto-runs after Gear 6:

Gear 6: Implement features ✅
  ↓
Gear 6.5: Validate & Review
  1. /stackshift.validate --fix
  2. /stackshift.review (if issues found)
  3. /stackshift.coverage (generate coverage map)
  ↓
Complete with confidence! 🎉

Manual usage anytime:

# Before committing
/stackshift.validate

# Before pull request
/stackshift.validate --fix

# Check specific feature
/stackshift.validate --feature=pricing-display

---

Principles

1. Specification Supremacy - Specs are source of truth
2. Zero Tolerance - ALL tests must pass, ALL types must compile
3. No Configuration Shortcuts - Fix implementation, not configs
4. Progressive Fix Strategy - Address spec violations first
5. Safety First - Automatic rollback on fix failures
6. Comprehensive Reporting - Clear categorization and progress tracking

---

This ensures every implementation is validated against specifications before being marked complete!