Rebasely Beta: data may be purged

justintypescript-ultra-strict Public

README: For agents section, boundary files, new example tables; LEARNINGS for the new rules

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2cc04ee81724b8d1f9af2892cd62d86a1616aa36
Parent 74947de Browse filesHistory

Changed files

2 files changed75 additions3 deletionsagainst 74947de

  1. ChangedLEARNINGS.md+8−0
  2. ChangedREADME.md+67−3
ChangedLEARNINGS.md+8−0
@@ -96,3 +96,11 @@
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.
View file
ChangedREADME.md+67−3
@@ -4,7 +4,7 @@
> **This repo is a thought experiment, not a production tool.** The compiler works, type-checks, and every example passes, but the macro syntax is lowered by a preprocessor with known edge cases, the bundler plugins skip semantic checking, there are no published packages, and there is no stability promise. It exists to make the proposal concrete enough to argue with. Do not build anything you care about on it yet.
-**Status:** working prototype. `packages/cli` implements `tsus check` and `tsus build`: a tokenizer built on `ts.createScanner`, a preprocessor that lowers `match` and the `?` operator with a source map back to the `.tsus` file, and a full `ts.createProgram` type-check over the project. `match` is exhaustiveness-checked at compile time, `tsus build` emits `.js.map` files that point at the `.tsus` source, `packages/runtime` implements `Option`/`Result`, the typed match helpers and the boundary layer, `packages/plugin` provides webpack/Vite/esbuild/Bun adapters, and all 36 projects under `examples/` pass (`npm install && npm run examples`). `LEARNINGS.md` documents what broke along the way, how that shaped the design, and the known limitations.
+**Status:** working prototype. `packages/cli` implements `tsus check` and `tsus build`: a tokenizer built on `ts.createScanner`, a preprocessor that lowers `match` and the `?` operator with a source map back to the `.tsus` file, and a full `ts.createProgram` type-check over the project. `match` is exhaustiveness-checked at compile time, `tsus build` emits `.js.map` files that point at the `.tsus` source, `packages/runtime` implements `Option`/`Result`, the typed match helpers and the boundary layer, `packages/plugin` provides webpack/Vite/esbuild/Bun adapters, the checker enforces 18 strictness rules with machine-applicable fixes (`tsus fix`, `tsus explain`, `tsus migrate`, `tsus init`; see [For agents](#for-agents)), and all 53 projects under `examples/` pass (`npm install && npm test`). `LEARNINGS.md` documents what broke along the way, how that shaped the design, and the known limitations.
TypeScript's early design decisions assumed humans would write and maintain it, so a lot of features exist to make a human's life easier. We valued speed over quality. With AI writing most of our code, we can flip that tradeoff and force the language to be declarative and verifiable, like Rust.
@@ -17,7 +17,7 @@
## The interop boundary
-Every existing DOM and npm API returns `undefined`, throws, and hands you classes. Ultra-Strict code never sees those directly. At the boundary, a checked bindings layer converts `T | undefined` and `T | null` into `Option<T>`, and throwing calls into `Result<T, E>`. Inside the boundary, the strict rules hold everywhere.
+Every existing DOM and npm API returns `undefined`, throws, and hands you classes. Ultra-Strict code never sees those directly. At the boundary, a checked bindings layer converts `T | undefined` and `T | null` into `Option<T>`, and throwing calls into `Result<T, E>`. Inside the boundary, the strict rules hold everywhere. In source, the boundary is the `@tsus/runtime/boundary` helpers (`fromNullable`, `wrapSync`, `wrapAsync`) plus any file named `*.boundary.tsus`, the only place casts and default exports are allowed.
## Why not just an eslint preset?
@@ -127,9 +127,49 @@
3. `?` binds like the conditional operator, so `a()? + 1` is a syntax error; write `(a()?) + 1`. It cannot appear in a match arm (arms are closures), a `?:` branch, the right side of `&&`/`||`/`??`, or a loop condition. Its return-type check is syntactic: the declared type must be spelled `Result<...>`, `Option<...>`, or `Promise<...>` of one, not an alias.
4. Regex detection is a one-token lookbehind: after `)` or `}` a `/` is read as division, so `if (x) /re/.test(s)` misparses. Commas in an arm body's type arguments are handled by a heuristic, and an arm body cannot be a statement block.
+## For agents
+
+The language is designed to be written by models, so the toolchain treats an agent as its primary user.
+
+**Drop-in primer.** [`AGENTS.md`](AGENTS.md) is a one-page description of the whole language (types, `match`, `?`, the boundary, every diagnostic code) meant to be copied into any project that uses tsus. `tsus init` does that for you.
+
+**Commands.**
+
+| Command | What it does |
+|---|---|
+| `tsus check [dir] --json` | Every diagnostic has a stable `code`, `start`/`end` offsets and line/col ranges in the original `.tsus` file, a `hint`, an `explain` pointer, and a `fix` (or `null`) |
+| `tsus fix [dir]` | Applies every safe fix, re-checking between passes. `--unsafe` adds fixes that can change behavior, `--code TSUS405` limits it to one rule, `--dry-run` reports without writing |
+| `tsus explain <CODE>` | The rule, why it exists, a rejected and an accepted example. `--list` prints every code, `--json` the raw entry |
+| `tsus init [dir]` | Scaffolds `AGENTS.md` (plus a `CLAUDE.md` that imports it), a strict `tsconfig.json`, `package.json` and a starter `src/main.tsus`. Never overwrites; `--force` refreshes only `AGENTS.md` |
+| `tsus migrate <file.ts>` | Codemod: `T \| null` and `T \| undefined` returns become `Option<T>`, throwing functions return `Result<T, E>` with a literal or tagged `E`, simple classes become a data type plus functions, `var` becomes `const` or `let`. Writes `<file>.tsus` next to the input and reports, with line numbers, everything it did not convert (including whatever the checker still rejects in the output) |
+
+A fix is `{ description, safe, edits: [{ start, end, line, col, endLine, endCol, newText }] }`, where offsets index the original file as UTF-16 code units. "Safe" means runtime behavior is unchanged: `==` to `===`, `let` to `const`, `var` to `const`/`let` when nothing depends on hoisting, `any` to `unknown`, deleting a suppression comment. Unsafe fixes (`"safe": false`) are offered where a mechanical rewrite exists but intent matters: an `enum` becomes a union of literals with its members inlined, a default export becomes a named one, a floating promise gets `await`, `param.sort()` becomes `param.toSorted()`.
+
+**Rules beyond the original five.** Each has a stable code, a rejection example, and `tsus explain` text, all generated from one registry (`packages/cli/src/rules/registry.js`). `npm run docs` regenerates [`docs/rules.md`](docs/rules.md) and the code table in `AGENTS.md`; `npm run docs:check` (part of `npm test`) fails if they drift or if a rule has no example.
+
+| Code | Rule | Fix |
+|---|---|---|
+| TSUS401 | no `any` | safe: `unknown` |
+| TSUS402 | no `as` casts, except `as const` and in boundary files | none |
+| TSUS403 | no non-null `!` | none |
+| TSUS404 | no `enum` | unsafe: union of literals |
+| TSUS405 | no `==` / `!=` | safe: `===` / `!==` |
+| TSUS406 | no default exports, except in boundary files | unsafe: named export |
+| TSUS407 | no reassigning parameters | none |
+| TSUS408 | `let` that is never reassigned | safe: `const` |
+| TSUS409 | no mutating parameters (property writes, array mutators, `Map`/`Set` mutators, `Object.assign`) | unsafe for `sort`/`reverse`/`splice` |
+| TSUS410 | `Result` error types must be string literal unions or tagged unions | none |
+| TSUS411 | no floating promises (including `void p` and `forEach(async ...)`) | unsafe: `await` |
+| TSUS412 | no unused `Result` | none |
+| TSUS413 | no `@ts-ignore`, `@ts-expect-error`, `@ts-nocheck` | safe: delete |
+
+The rules run on the macro-expanded source with the TypeScript parser and a per-file binder, so names resolve through real scopes (a shadowed parameter is not a parameter). TSUS410 to TSUS412 follow relative `.tsus` and `.ts` imports to see what an imported function returns or what an imported error type is; when a full `ts.Program` is handed to the checker, they use its types instead.
+
+**Boundary files.** A file named `*.boundary.tsus` is where the outside world is let in: `as` casts (after a runtime check) and default exports are allowed there, and nothing else is relaxed. Cloudflare Workers' `export default { fetch }` lives in one (`examples/23-cloudflare-worker`), as does a checked JSON config loader (`examples/53-boundary-file`).
+
## The examples
-`examples/` is the test suite: 36 small projects, each with an `example.json` declaring what must happen. `npm run examples` builds and executes all of them and fails on any drift.
+`examples/` is the test suite: 53 small projects, each with an `example.json` declaring what must happen. `npm run examples` builds and executes all of them and fails on any drift (`npm test` also checks that generated docs are current).
**Core language and runtime**
@@ -157,9 +197,24 @@
| `30-non-exhaustive-match` | TSUS201, for a missing tagged-union variant, a missing `Err`, and literal arms that miss a union member |
| `31-wrong-arm-type` | TSUS200 (an arm of the wrong type, a payload used as the wrong type) and TSUS202 (a misspelled variant) |
| `35-try-misuse` | TSUS300, TSUS301, TSUS302, TSUS303 |
+| `40-banned-any` | TSUS401 |
+| `41-banned-as-cast` | TSUS402 |
+| `42-banned-non-null` | TSUS403 |
+| `43-banned-enum` | TSUS404 |
+| `44-banned-loose-equality` | TSUS405 |
+| `45-banned-default-export` | TSUS406 |
+| `46-banned-param-reassign` | TSUS407 |
+| `47-banned-let-never-reassigned` | TSUS408 |
+| `48-banned-param-mutation` | TSUS409 |
+| `49-banned-untagged-error` | TSUS410 |
+| `50-banned-floating-promise` | TSUS411 |
+| `51-banned-unused-result` | TSUS412 |
+| `52-banned-ts-suppression` | TSUS413 |
Rejection examples can also pin exact positions (`"diagnostics": [{ "code", "file", "line", "col", "tsCode" }]` in `example.json`), which tests the source map back to the `.tsus` file.
+Examples that list `fixable` codes in `example.json` also assert that those diagnostics carry a machine-applicable fix.
+
**Interop and stress**
| Example | Shows |
@@ -182,3 +237,12 @@
| `27-nextjs` | Next.js 14 via the webpack loader; `next build` renders `.tsus` output into static HTML |
| `28-astro` | Astro 4 via the Vite plugin, verified in built HTML |
| `29-bun` | Bun runs `.tsus` imports natively via a `bunfig.toml` preload, no build step |
+
+**Agent tooling**
+
+| Example | Shows |
+|---|---|
+| `53-boundary-file` | A `*.boundary.tsus` file using a checked cast; the rest of the program sees only a tagged `Result` |
+| `54-fix-roundtrip` | `tsus fix` on a copy (including edits inside match arms), compared byte for byte with `expected/`, then built and run |
+| `55-migrate` | `tsus migrate` on a legacy `.ts` module (class, var, nullable returns, throws) against golden output, then run; a second file shows the not-converted report |
+| `56-init` | `tsus init` into an empty directory, then the starter project builds and runs |
View file

Checks

No checks reported for this commit.

Runs

No runs for this commit.