validate-typescript

name	validate-typescript
description	Run TypeScript compiler type-checking (tsc --noEmit) to validate type safety and catch type errors. Works with any TypeScript project. Returns structured output with error counts, categories (type/syntax/import errors), and affected files. Used for quality gates and pre-commit validation.

Validate TypeScript

Purpose

Execute TypeScript compiler in type-check mode to validate type safety without emitting JavaScript files, catching type errors before runtime. Works with any TypeScript/JavaScript project using TypeScript.

When to Use

• Quality gate validation (before commit/PR)
• Pre-refactor validation
• After TypeScript code changes
• As part of quality-gate skill
• Conductor Phase 3 (Quality Assurance)

Instructions

Step 1: Check TypeScript Available

if ! command -v tsc &>/dev/null; then
  if ! command -v npx &>/dev/null; then
    echo "❌ Error: TypeScript not available"
    exit 1
  else
    # Use npx if tsc not in PATH
    TSC_CMD="npx tsc"
  fi
else
  TSC_CMD="tsc"
fi

echo "Using: $TSC_CMD"

Step 2: Run Type Check

echo "→ Running TypeScript type check..."

# Run tsc --noEmit (no files emitted, just type checking)
if $TSC_CMD --noEmit 2>&1 | tee .claude/validation/tsc-output.txt; then
  TS_STATUS="passing"
  TS_EXIT_CODE=0
  echo "✅ TypeScript validation passed"
else
  TS_STATUS="failing"
  TS_EXIT_CODE=$?
  echo "❌ TypeScript validation failed"
fi

Step 3: Parse Errors

if [ "$TS_STATUS" = "failing" ]; then
  # Count errors
  ERROR_COUNT=$(grep -c 'error TS' .claude/validation/tsc-output.txt || echo "0")

  echo "   Errors: $ERROR_COUNT"

  # Categorize errors
  TYPE_ERRORS=$(grep -c 'error TS2' .claude/validation/tsc-output.txt || echo "0")
  SYNTAX_ERRORS=$(grep -c 'error TS1' .claude/validation/tsc-output.txt || echo "0")
  IMPORT_ERRORS=$(grep -c 'error TS2307' .claude/validation/tsc-output.txt || echo "0")

  echo "   Type errors: $TYPE_ERRORS"
  echo "   Syntax errors: $SYNTAX_ERRORS"
  echo "   Import errors: $IMPORT_ERRORS"

  # Extract error files
  ERROR_FILES=$(grep 'error TS' .claude/validation/tsc-output.txt | \
    cut -d'(' -f1 | \
    sort -u | \
    jq -R -s -c 'split("\n") | map(select(length > 0))')
else
  ERROR_COUNT=0
  TYPE_ERRORS=0
  SYNTAX_ERRORS=0
  IMPORT_ERRORS=0
  ERROR_FILES="[]"
fi

Step 4: Return Structured Output

{
  "status": "$([ "$TS_STATUS" = "passing" ] && echo 'success' || echo 'error')",
  "typescript": {
    "status": "$TS_STATUS",
    "errors": {
      "total": $ERROR_COUNT,
      "type": $TYPE_ERRORS,
      "syntax": $SYNTAX_ERRORS,
      "import": $IMPORT_ERRORS
    },
    "files": $ERROR_FILES
  },
  "canProceed": $([ "$TS_STATUS" = "passing" ] && echo 'true' || echo 'false')
}

Output Format

All Types Valid

{
  "status": "success",
  "typescript": {
    "status": "passing",
    "errors": {
      "total": 0,
      "type": 0,
      "syntax": 0,
      "import": 0
    },
    "files": []
  },
  "canProceed": true
}

Type Errors Found

{
  "status": "error",
  "typescript": {
    "status": "failing",
    "errors": {
      "total": 12,
      "type": 8,
      "syntax": 2,
      "import": 2
    },
    "files": [
      "src/components/Settings.tsx",
      "src/context/WorldContext.tsx",
      "src/types/index.ts"
    ]
  },
  "canProceed": false,
  "details": "12 TypeScript errors must be fixed before proceeding"
}

Integration with Quality Gate

Used in quality-gate skill:

### Step 5: TypeScript Type Checking

Use `validate-typescript` skill:

Expected result:
- Status: passing
- Errors: 0

If TypeScript errors found:
  ❌ BLOCK - Quality gate fails
  → Fix type errors
  → Re-run quality gate

If TypeScript passes:
  ✅ Continue to next check

Common Error Categories

TS2xxx - Type Errors

error TS2322: Type 'string' is not assignable to type 'number'
error TS2339: Property 'foo' does not exist on type 'Bar'
error TS2345: Argument of type 'X' is not assignable to parameter of type 'Y'

Action: Fix type mismatches

TS1xxx - Syntax Errors

error TS1005: ',' expected
error TS1128: Declaration or statement expected

Action: Fix syntax issues

TS2307 - Import Errors

error TS2307: Cannot find module './foo' or its corresponding type declarations

Action: Fix import paths or install missing types

Related Skills

• quality-gate - Uses this for TypeScript validation
• record-quality-baseline - Records TypeScript error count

Error Handling

TypeScript Not Installed

{
  "status": "error",
  "error": "TypeScript not available",
  "suggestion": "Install TypeScript: npm install --save-dev typescript"
}

tsconfig.json Missing

if [ ! -f tsconfig.json ]; then
  echo "⚠️ Warning: tsconfig.json not found - using default config"
fi

Best Practices

1. Always check before commit - Prevents type errors in production
2. Fix errors incrementally - Don't accumulate type debt
3. Use strict mode - Enable strict type checking in tsconfig.json
4. No any types - Avoid bypassing type system
5. Save output - Keep error logs for debugging

Notes

• Uses --noEmit flag (no files generated)
• Respects tsconfig.json configuration
• Exit code 0 = no errors, non-zero = errors found
• Output saved to .claude/validation/tsc-output.txt