@shipispec/tsfix

TSC Defense Stack — @shipispec/tsfix

Standalone npm package implementing Layers 0–1 of the TypeScript error-recovery stack: in-process tsc validation + deterministic LSP auto-fix. Layers 2–4 (LLM mend) currently live in spectoship2/src/pipeline/ and will move to a sister package @shipispec/tsmend per the roadmap.

Read first:

• STATUS.md — what's working, what's planned, current gaps
• ARCHITECTURE.md — why the package is shaped the way it is
• tsc-defense-roadmap.md — phased plan with open decisions
• CLAUDE.md — working principles (small allowlist, fixture-pinned trust model)

Source-of-truth map

This package owns its TypeScript-error handling code outright. The shims in spectoship2/ re-export from here, not the reverse.

Path	Role
src/index.ts	Public API (runValidationLoop, runInProcessTsc, runLSPFixerPass, discoverTsFiles)
src/validatorInProcess.ts	In-process tsc with lib-path workaround (Layer 0)
src/tsLanguageServiceFixer.ts	LSP auto-fixer using getCodeFixesAtPosition (Layer 1)
cli/run-stack.ts	CLI: tsx cli/run-stack.ts --workspace <path>
benchmark/run-benchmark.ts	Fixture harness (auto-discovers fixtures/*/)
fixtures/	14 hand-authored synthetic fixtures across 3 tiers
spectoship2/src/pipeline/validatorInProcess.ts	Re-export shim → @shipispec/tsfix
spectoship2/src/pipeline/tsLanguageServiceFixer.ts	Re-export shim → @shipispec/tsfix

How the layers fit together

Per ARCHITECTURE.md, a TSC error has up to four chances to die before reaching a user. Layers -1 (prevention) and 2-4 (mend) live outside this package.

                    ┌─────────────────────────────────────────────────┐
                    │ Layer -1: PREVENTION (in spectoship2/, not here)│
                    │   packageGotchas, installedExports, priorExports│
                    │   codeGenPrompts (rules injected into prompt)    │
                    └────────────────────┬────────────────────────────┘
                                         │ files written to disk
                                         ▼
  ┌────── @shipispec/tsfix ───────┴──────────────────────────┐
  │                                                                  │
  │   ┌─────────────────────────────────────────────┐               │
  │   │ Layer 0: src/validatorInProcess.ts           │               │
  │   │   in-process tsc → structured diagnostics    │               │
  │   │   workspace lib-path override                │               │
  │   └─────────────────────┬───────────────────────┘               │
  │                         │ if errors                              │
  │                         ▼                                        │
  │   ┌─────────────────────────────────────────────┐               │
  │   │ Layer 1: src/tsLanguageServiceFixer.ts       │               │
  │   │   getCodeFixesAtPosition (5 SAFE codes)      │               │
  │   │   signature-set progress check, max 5 iters  │               │
  │   └─────────────────────┬───────────────────────┘               │
  │                         │ re-validate; if errors remain          │
  └─────────────────────────┼─────────────────────────────────────────┘
                            ▼
                 ┌─────────────────────────────────┐
                 │ Layers 2-4: LLM MEND            │
                 │   mendAgent / mendArchitect /   │
                 │   multiFileMend / repairAgent   │
                 │   (in spectoship2/, not here;   │
                 │    moves to @shipispec/tsmend│
                 │    in v0.2 per roadmap)         │
                 └─────────────────────────────────┘

What to read first

• STATUS.md — current state, fixture catalog, recent fixes
• ARCHITECTURE.md — why the package is shaped the way it is (12 sections)
• tsc-defense-roadmap.md — phased plan with open decisions
• src/index.ts — public API entry point (runValidationLoop)
• src/tsLanguageServiceFixer.ts — Layer 1 fixer; understand SAFE_FIXABLE_CODES, the signature-set progress check, and the iteration loop
• src/validatorInProcess.ts — in-process tsc with the lib-path workaround that makes the package work inside the VS Code Extension Host

Standalone harness

cli/run-stack.ts             # CLI: run stack on any workspace
benchmark/run-benchmark.ts   # benchmark across all fixtures
fixtures/                    # 14 hand-authored synthetic workspaces
  _shared/                   # shared node_modules symlink target
  clean-baseline/            # regression check (must stay green)
  synthetic-*/               # 9 LSP-behavior fixtures (positive + negative)
  api-drift-*/               # 4 version-drift fixtures (Zod 3 vs 4, React 18 vs 19, etc.)

Run the CLI

cd /Users/ogg/Documents/microservices/Meta/spectoship2
./node_modules/.bin/tsx ../tsc-defense-stack/cli/run-stack.ts --workspace <path>

Flags: --json, --no-lsp, --verbose, --files <comma-list>. Exit 0 = clean, 1 = errors remain, 2 = bad args.

Note: per Phase 0c of tsc-defense-roadmap.md, this package will gain its own local node_modules so commands run from inside the package directory. Today it shares spectoship2/node_modules.

Run the benchmark

cd /Users/ogg/Documents/microservices/Meta/spectoship2
./node_modules/.bin/tsx ../tsc-defense-stack/benchmark/run-benchmark.ts

--fixture <name> to run a single fixture in isolation.

Current baseline

14/14 synthetic fixtures pass. LSP fixer auto-resolves 14/25 errors (56%). The remaining errors are intentional non-fixes — TS7006 implicit-any, TS2741 missing prop, API-drift errors that need the mend layer. See STATUS.md § Fixture catalog for the full list.

Capturing real-failure fixtures

Phase 3b in the roadmap. When a real spec-pipeline run produces a TSC error Layer 0-1 doesn't fix, snapshot the broken .ts(x) files into fixtures/real-<timestamp>-<hash>/ with an expected.json. The fixture set then grows from production failures, not just synthetic ones.