Rebasely Beta: data may be purged

justintypescript-ultra-strict Public

Markdown · 21.0 KiB · at 503e839

Learnings from running the examples with no toolchain

Phase 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 TypeScript

Renaming 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 resolution

Even 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.

Outcome

With 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 tries

The 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 shape

String 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 land

Every 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 immediately

Example 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 compilers

After 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 now

  1. 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.

Learnings from v2: plain .ts, a checker, and security types

v2 started from four facts. On a feature built from a detailed spec, v1 tied plain strict TypeScript on correctness (118/118 hidden tests each, identical on 20,400 fuzz pairs) while costing 28% more tool calls, 65% more code, a 51-line adapter and idioms like parts.slice(0, 1).join(""), and its checker reported nothing in eight runs. The pilot's wrapper objects cost 2 to 6x on the on-call hot path. Rewriting existing logic was where v1 found real bugs. And the problems reviews of AI-written web code kept finding (SQL injection, permission scoping, secrets, untrusted input) were ones v1 had no words for.

Erasable is a hard constraint, and it is cheap to meet

Dropping the macros removed the compiler, the preprocessor, the source maps and the bundler plugins in one move, and the type system still carries what the macros did. match(value, "kind", arms) is exhaustive because the arms parameter is a mapped type over V[K], and it narrows each arm because the key is a const type parameter fixed before the arms are checked (v1 needed currying to get the same inference). Two details mattered. The arms' constraint returns any, because when the arms are wrong TypeScript falls back to the constraint and an unknown there adds a second error at every use (the same lesson v1 learned). Ok and Err take const type parameters, which keeps Err({ kind: "missing" }) literal without the contextual-typing machinery v1 built into its match.

Option as T | undefined moves the safety into the checker

With no wrapper, the type is free (the dedupe test went from 6.88x in v1 to 0.92x), but T | undefined has one gap a wrapper does not: truthiness. TSUS503 rejects a truthiness test on an optional string or number, where "" or 0 would read as absent, and nothing else; objects and booleans test fine. noUncheckedIndexedAccess plus === undefined replaces v1's de facto indexing ban. Banning only the production of null (TSUS502), not comparisons with it, is what removed the adapter: re.exec(s) === null is fine, and D1 rows come through safeDb, which turns SQL NULL into undefined.

match() is not free. Its arms are closures, so a four-way literal match costs about 14 ns a call with the arms inline and 6 ns hoisted, against under 1 ns for a switch. TSUS501 checks switches over unions for exhaustiveness, so a hot path loses nothing by using one.

A brand is only as strong as the cast ban

Sql, Permit, Secret and Untrusted are interfaces keyed by unique symbols that index.d.ts declares and does not export, so no code can write a literal of one. That makes them unforgeable except by a cast, which is the real reason the cast ban (TSUS506), any (TSUS508) and ! (TSUS507) stay in v2: the experiment's 11 casts were all safe, so on correctness alone the rule would have gone. The checker recognizes the brands structurally (TypeScript names the property __@SqlBrand@<id>), so they survive aliases, intersections and generics.

The types do most of the work. A query string passed to SafeDb is TS2345, a missing Permit is TS2554 or TS2345, a Secret where a string is expected is TS2322. The checker names those errors by what they mean (TSUS600, TSUS601, TSUS604) and covers what TypeScript accepts from any type: template literals, +, String(), console.log(obj), JSON.stringify(obj) (with a depth-limited search for a Secret inside an object). Untrusted needed one more idea: the same ${text} is XSS in markup, injection in SQL and prompt injection in a prompt, so the rule classifies the template by its static text and where its value goes, and gives each sink its own code and its own fix.

The planted-bug demo is the honest test

The same module written twice, with six bugs planted the way they would be written in each style, says more than a list of rules. Plain strict TypeScript, with noUncheckedIndexedAccess, reported none of the six. v2 reported all six, each at its line, and the runner fails on any diagnostic off a planted line, so the demo also measures false positives (none). Running the attacks against both versions on the same SQLite made the bugs concrete: ' OR 1=1 -- returned another user's private rows, a CASE WHEN in the sort parameter answered a yes/no question about a private table, and a fenced prompt kept <system> out of the model's input. tsus audit on the plain version found the two injections and the missing check, and could not see the other three: knowing that a value is a secret or came from a user is exactly what the types add.

Report-only analysis is where the false positives live

tsus audit on Rebasely's shipped search and triage modules reported 82 findings. Seven were real, all in triage/: per-repository Actions failures in the Inbox are dropped without marking the list partial (inbox.ts:184), and six failures are swallowed with no log while the calls next to them log theirs (inbox.ts:222, 223, 224; handlers.ts:54, 55, 101). 75 were false positives. Three were wrong: SQL fragments in search/sql.ts whose column names arrive as parameters that are literals at every call site (the constant analysis does not follow parameters), and a bug-report read in triage/sources.ts reached through a dispatch table (SOURCES[i].items), which the call graph cannot follow. The other 72 described the pattern correctly and were harmless on inspection: index reads guarded by a length or loop bound, regex groups after a match, documented best-effort catches, casts after a check. The search module, already fuzzed by the experiment's judge, had no true positives.

The permission analysis needed three passes to stop lying. Counting a check anywhere among a function's transitive callees marked everything checked, because a sibling call deep in the tree always reaches authorize. Not descending into other data functions fixed that, and requiring the check to come before the call in each caller fixed the case of a harness that calls a checked and an unchecked handler side by side. Inside the reading function itself a check anywhere has to count, because filtering the rows it just read with authorize is a check (Rebasely's issueRows does exactly that). It remains a name-based heuristic; in v2 code the Permit type makes it unnecessary.

Known limitations

  1. The security types are only as good as the marking: text is Untrusted because a boundary said so. A prompt built under a name the rule does not recognize falls to the general TSUS607.
  2. Raw driver calls in application code are still possible; TSUS601 catches their string-built queries but not their missing checks.
  3. The audit's permission analysis is name-based, ordered by position in the source, and blind to dispatch tables and dynamic calls; its constant-string analysis does not follow function parameters.
  4. match() allocates its arms; hot paths should use a checked switch.