Rebasely Beta: data may be purged

justintypescript-ultra-strict Public

Markdown · 106 lines · 14.2 KiB · at 2e2b18f

# Learnings from running the examples with no toolchainPhase 1 was writing 26 example projects under `examples/` and running them with stock tooling. Everything failed, in three distinct ways, and each failure dictated a piece of the MVP design.## Failure 1: the extension is a hard wall`node examples/01-hello/src/main.tsus` and `node --experimental-strip-types` both die with `ERR_UNKNOWN_FILE_EXTENSION` before reading a single byte. Node's type-stripping only accepts `.ts`/`.mts`, so a new extension means we own the compile step end to end. There is no incremental "mostly works" path.Consequence for the MVP: `tsus build` must exist and must emit plain `.js` before anything runs. Compiled output has to be standard ESM so Node and Cloudflare Workers can consume it with zero knowledge of `.tsus`.## Failure 2: `match` blocks are not parseable TypeScriptRenaming `04-match-option/src/main.tsus` to `.ts` and running `tsc --noEmit` produces `TS1005: ',' expected` and `TS1109: Expression expected` at the match arms. The TS parser cannot recover into anything useful, so we cannot implement `match` as a tsc plugin or an AST transform over the original source.Consequence: the MVP needs a preprocessor that runs before the TypeScript parser, scanning raw text and rewriting `match (expr) { Pattern(x) => body }` into a plain function call (`__tsus_match`). The scanner has to be a real tokenizer that understands strings, template literals (including nested `${}`), and comments, because example 24 deliberately plants fake `match` blocks inside all of those. A regex will not survive it.## Failure 3: import specifiers with `.tsus` extensions break resolutionEven with compiled output, `import { safeSqrt } from "./math.tsus"` would still fail at runtime because nothing on disk has that name after compilation. The examples with import chains (12, 20, 21, 22) all hit this.Consequence: the build step rewrites `.tsus` and `.ts` specifiers to `.js` in emitted code, and compiles sibling `.ts` files too, so a mixed `ts`+`tsus` project comes out as one coherent dist tree.## Smaller findings baked into the design- `await` inside a match arm: arms compile to arrow functions, so an arm whose body contains `await` must become an `async` arrow, and `__tsus_match` then returns a promise the caller awaits. Example 19 forces this.- `"abc".match(/\d+/)` and a user function literally named `match` (example 25) must not trigger the macro. The rewrite only fires on `match (expr) {` where the token is not preceded by `.` or an identifier character, and only when a `{` follows the closing paren.- Bare string-literal patterns (`"/" => ...` in the worker example) mean patterns are not just variant tags; the runtime match needs literal equality patterns plus a `_` wildcard.- Circular `.tsus` imports (example 21) are fine as long as the cycle is function-level, because compiled output is ESM and ESM handles cycles with hoisted bindings. The compiler does not need to detect cycles for the MVP.- The checker rules (no class, no null, no undefined, no var, no throw) apply to `.tsus` files only. Examples 13 and 22 have `.ts` dependencies that use classes, null, and undefined on purpose; the checker must scope itself by extension or mixed projects are impossible.## OutcomeWith the MVP in place (`packages/runtime` + `packages/cli`), the harness reported 26/26 examples passing, including the five that pass by being rejected with the expected diagnostic code. The MVP's known limitations, in honesty order, were:1. No semantic type-checking: `tsus build` stripped types per-module (`ts.transpileModule`), so type errors surfaced at runtime.2. No exhaustiveness checking: a non-exhaustive match threw `TSUS100` at runtime instead of failing at compile time.3. The `await`-in-arm detection was textual, so a string literal containing the word `await` wrongly made that arm async.4. Regex literals were not tokenized; a regex containing a quote or brace character could confuse the scanner.All four are closed now. The next section is what closing them taught us.# Learnings from the compiler foundation## The scanner is free, the context is not`ts.createScanner` already knows strings, comments, numbers, and every operator, including the ones that matter for `?`: it emits `?.` and `??` as their own tokens, so telling them apart from a bare `?` costs nothing. What it cannot know is parser context. Two tokens need a rescan: `/` (division or regex) and `}` (end of a block or the resume of a template after `${`). Regexes are decided by a one-token lookbehind (after an identifier, literal, `)`, `]`, or `}` it is division), and templates by remembering the brace depth at each `TemplateHead`. Example 32 is the regex `/["'`]/g`, which the old hand-written scanner read as the start of a string and a template.## Typing match took four triesThe obvious signature, `<V, R>(value: V, arms: { [K in TagOf<V>]: (p: Payload<V, K>) => R }) => R`, type-checks the arms but infers `R` as `unknown`: TypeScript cannot infer through a mapped type whose keys are a conditional type of another type parameter. Every match silently became `unknown`.Currying fixes inference. `__tsus_match(value)(arms)` fixes `V` in the first call, so in the second the mapped type has concrete keys. A single inferred `R` then works, but it is too strict in a TypeScript way: `Idle => tag("Running", ...)` and `Running => tag("Done", ...)` return two different variant types, and TypeScript picks the first as `R` and rejects the second even when the function declares the union as its return type.The third version inferred the arms object as a type parameter `A extends MatchArms<V>` and typed the match as the union of the arms' return types. That handled variants, and examples 1 to 36 passed, but the eval harness's reference solutions (merged while this work was in flight) failed on the most common error-handling line there is: `None => Err({ kind: "missing" })` inside a function returning `Result<T, QueryError>`. With no contextual type reaching the arm, `Err` infers `{ kind: string }` and the union no longer fits. Plain TypeScript gets this right in a ternary because the return type flows into both branches.The version that shipped takes the result type from context when there is one and from the arms when there is not. `R` appears in the match's return type and, wrapped in `NoInfer`, in the arms' constraint, so it is inferred only from the contextual type. When a context exists, every arm is contextually typed by it (so `Err({ kind: "missing" })` infers `QueryError`) and must be assignable to it, which also moves a wrong-arm error from the whole match onto the offending arm. When there is no context, `R` stays `unknown`, and a conditional type switches the result to the union of the arms. Exhaustiveness comes from the constraint, unknown arms from an extra mapped type that maps foreign keys to `never`.One more wrinkle: when the constraint fails (the real error), TypeScript falls back to it, and if the constraint's arms return `unknown`, every use of the match reports a second, misleading error. Without a context the constraint returns `any`, which only ever surfaces after a match is already reported broken.`_` cannot be a key in the same object without turning the mapped type into a union, which breaks contextual typing for the arm parameters, so a wildcard match lowers to a separate `__tsus_match_or(value)(arms, otherwise)`.## Literal patterns are a different shapeString patterns (the worker router) cannot share the keyed-object design: number and string literals would collide as keys, and the literal `"_"` would collide with the wildcard. They lower to `__tsus_match_lit(value)([[literal, handler], ...], otherwise?)`. A `const` type parameter keeps each literal's type, each literal is checked against the subject's type, and the `otherwise` parameter is a rest tuple that is required exactly when `Exclude<V, literals>` is not `never`. So a `"GET" | "POST" | "DELETE"` subject needs no `_` once all three are listed, and a plain `string` subject always needs one.## `?` is a parse error with a useful shape`const x = load()?;` is not TypeScript, but the parser's error recovery turns it into a conditional expression whose true branch is a zero-width missing identifier. That node gives the operand (the condition) and its precise extent, and walking its parents gives the enclosing function and the statement to hoist an early return in front of. A candidate is only accepted when the token after `?` is `;`, `)`, `]`, `}`, `,`, or the end of input, and when the true branch is missing, so valid ternaries, optional parameters (`(x?) => x`), optional tuple elements, and `?:` in types never match.Two consequences of riding the conditional operator's precedence: `?` covers everything to its left, which is exactly right for `await load()?` (it unwraps the awaited value), and `a()? + 1` is a syntax error that wants parentheses. Rust's postfix `?` binds tighter, and we chose not to fight the parser over it.Hoisting is only sound where the operand always runs, so `?` in a `?:` branch, on the right of `&&`/`||`/`??`, or in a loop condition is rejected (TSUS303) rather than silently evaluated early. `?` inside a match arm is rejected too (TSUS300): arms are closures and cannot return from the enclosing function.The type plumbing is three identity functions. `__tsus_try` constrains the operand to `Result | Option` (TSUS301 when it is not), a type guard narrows the bail case, and `__tsus_bail` re-types an `Err<T, E>` as `Err<never, E>` so it fits any `Result<U, E>`. When it does not fit, TypeScript's error lands on the generated `return`, which is how TSUS302 is detected.## Diagnostics are classified by where they landEvery lowering pass writes through an emitter that records each output run as either a verbatim copy (maps offset-for-offset) or synthesized glue (maps to one anchor). Passes compose, so any offset in the final TypeScript maps back to the `.tsus` file. The same table classifies TypeScript's errors into stable codes: a TS2345 that lands on a match's copied `{` is a missing arm (TSUS201, with the missing variants read off the subject's type through the checker), an error on a copied arm name is TSUS202, a TS2345 at the start of a `__tsus_try(` argument is TSUS301, anything on the generated `return` is TSUS302. Everything else is TSUS200 with the TS code attached.The runtime import is prepended on line 1 with no newline, so line numbers in the lowered code, the emitted JS, and stack traces without source maps still match the `.tsus` file.## Semantic checking found real bugs immediatelyExample 16 had passed since the MVP, but `wrapAsync(readFile)` infers from `readFile`'s last overload, so the `Ok` payload was `string | Buffer`, and `text.trim()` was a type error that only worked at runtime because the call happened to pass `"utf8"`. The first `ts.createProgram` run flagged it. The fix pins the overload: `wrapAsync((file: string) => readFile(file, "utf8"))`. The eval harness's `route-match` reference had the same kind of latent error: `.map((s) => (s.kind === "static" ? 3 : 0)).unwrapOr(1)` infers `Option<3 | 0>`, so the fallback `1` does not fit. It now annotates the callback's return as `number`.The virtual compiler host serves each `.tsus` file as `<file>.tsus.ts` and resolves `./x.tsus` specifiers itself; everything else goes through TypeScript's normal bundler resolution, so `.ts` files importing `.tsus` (example 14) and `.tsus` importing `.ts` (example 13) both type-check as one program.## Caches remember old compilersAfter the runtime's match signature changed, `next build` in example 27 produced an empty page: Next's persistent webpack cache in `.next/cache` kept serving the old loader output, which called the new runtime with the old arguments. Webpack cannot see through the loader's dynamic `import()` to the compiler files, so the loader now declares them with `addBuildDependency`.## Known limitations now1. The bundler plugins transform one file at a time and only run the syntactic rules; type errors surface in `tsus check`, not in the framework build.2. `tsus check` uses fixed compiler options and ignores `tsconfig.json`.3. `?` binds like `?:`, so it needs parentheses inside larger expressions; its return-type check is syntactic and does not see through type aliases.4. The regex lookbehind treats `/` after `)` or `}` as division, commas in type arguments inside an arm body rely on a merge heuristic, and an arm body cannot be a statement block.5. If any arm awaits, every arm of that match becomes async.# Learnings from closing the escape hatches (TSUS401-413)- Banning untagged `Result` error types (TSUS410) broke nine of the original examples, all of which used `Result<T, string>`. Moving them to literal unions (`Result<number, "division by zero">`) or `Tagged<"NotFound", string>` cost a line or two each and made every error matchable. The rule is cheap to satisfy when it exists from the start and painful to retrofit, which is the argument for having it.- Cloudflare Workers require `export default { fetch }`, so a blanket default-export ban (TSUS406) is impossible. That forced the boundary to become a file-level concept: `*.boundary.tsus` relaxes exactly casts and default exports. Being visible in the file name keeps it reviewable, unlike a pragma comment.- Fix edits have to be expressed against the original `.tsus` text, but the rules see macro-expanded code. The rules use the preprocessor's offset map when it is passed in, and otherwise align the two texts themselves (`rules/sourcemap.js`: a line diff, then a token diff inside changed hunks). Either way a fix is only offered when its range covers text that is identical in both versions, so an edit can never land on generated glue. Example 54 puts fixes inside match arms to keep this honest.- Floating promises and unused Results are detectable without full type information for the common case: a call to a function whose declaration (in this file or a relative import) is `async`, annotated `Promise<...>` or `Result<...>`, or built with `wrapAsync`/`wrapSync`. When a `ts.Program` is available the same rules switch to real types.- "Safe" fixes are defined by runtime behavior, not by type-checking: `any` to `unknown` never changes what runs, but it can surface type errors `any` was hiding. That is the point of the rule, so it stays a safe fix.