all-the-vibes/atv-phoenix/phoenix-typescript

phoenix-typescript — the type-checker is a phoenix_sense gate

Encodes Mat Pocock's / Total TypeScript philosophy: TypeScript

wasn't built to make JS "strongly typed" — it was built to give JS a fast, powerful feedback loop.

Phoenix treats that loop as a first-class objective check.

Overview

The TypeScript language server and tsc form exactly the kind of objective signal Phoenix runs on: you write code, the checker gives instant pass/fail, you adjust — all before runtime. So in Phoenix, `tsc --noEmit` is a `phoenix_sense` check, on equal footing with tests. A change isn't done because it "looks typed"; it's done when the type check is green.

The gate

{"check":{"kind":"command_exit","target":["npx","tsc","--noEmit"],"expect":0}}

Run it as the inner-loop check for any TS edit (alongside the test gate). Red tsc = not done.

The feedback loop

  edit .ts ──► tsc --noEmit (phoenix_sense) ──► ok? ──yes──► run tests ──► done
                     │                            no
                     ▼
              read the type error (DATA, not a nuisance)
                     │
                     ▼
              fix the TYPE, not @ts-ignore the symptom ──► re-sense

Craft rules (each keeps the gate meaningful)

1. Work strict. "strict": true (and noUncheckedIndexedAccess) in tsconfig.json. Strictness is

what makes the green check mean something; a loose config is a gate that can't fail.

1. Kill `any` and unsafe casts. any disables the checker locally — it's a hole in the gate. Prefer

unknown + narrowing. An as cast asserts a truth the compiler can't verify; treat every cast as a place a real bug can hide, and justify it.

1. Derive, don't duplicate. One source of truth for a shape; derive the rest with typeof, indexed

access (T["field"]), Parameters, ReturnType, Pick/Omit, as const. Duplicated types drift out of sync silently — exactly the failure types exist to prevent.

1. Type the boundaries. Validate external/untrusted data (API responses, params) at the edge (a

schema validator), so the typed core can trust its inputs. Inside, let inference do the work — don't annotate what TS already knows.

1. No `@ts-ignore` / `@ts-expect-error` to pass the gate. Silencing the checker to get green is the

TS equivalent of editing the test to match broken code. Fix the type. If a suppression is truly necessary, it needs a comment explaining why and a phoenix_sense test of the runtime behavior.

The Pocock move: let the types catch the refactor

Before changing a function signature, change the type first and let tsc show you every call site that breaks — that error list is your blast radius, for free. (Pair with phoenix-context for runtime call graphs the type system can't see.)

Common Rationalizations

Red Flags

• A new any or as cast with no justification. → Replace with unknown+narrowing, or justify the cast.
• @ts-ignore/@ts-expect-error added to make tsc pass. → Fix the type; suppressions are gate holes.
• The same shape typed in two places. → Derive one from the other.
• Claiming done without a green tsc --noEmit. → Run the type gate; it's a phoenix_sense check.

Next

Combine with phoenix-test (runtime behavior gate), phoenix-build (surgical edits), and phoenix-craft (simplicity). The two gates together — tsc --noEmit + tests — are a strong objective definition of done.