README: thought-experiment disclaimer and examples catalog
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Changed files
1 file changed50 additions1 deletionagainst 46fbf38
- ChangedREADME.md+50−1
ChangedREADME.md+50−1
| @@ -2,8 +2,10 @@ | ||
| This is my proposal for TypeScript-Ultra-Strict: a stricter TypeScript for a world where AI writes most of the code. | ||
| -> **Status: working MVP on the `mvp` branch.** `packages/cli` implements `tsus check` and `tsus build`, `packages/runtime` implements `Option`/`Result`/`match` and the boundary layer, and all 26 projects under `examples/` pass (`npm install && npm run examples`). The 5 `banned-*` examples pass by being rejected with the right diagnostic codes. `LEARNINGS.md` documents what broke before the toolchain existed and how that shaped the design. The compiled output is plain ESM; the worker example (`examples/23-cloudflare-worker`) exports the Cloudflare `{ fetch }` module shape and runs against real `Request`/`Response` objects, so `wrangler` can bundle it as-is. | ||
| +> **This repo is a thought experiment, not a production tool.** The compiler works and every example passes, but there is no semantic type-checking, no exhaustiveness checking, no published packages, and 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 MVP. `packages/cli` implements `tsus check` and `tsus build`, `packages/runtime` implements `Option`/`Result`/`match` and the boundary layer, `packages/plugin` provides webpack/Vite/esbuild/Bun adapters, and all 29 projects under `examples/` pass (`npm install && npm run examples`). `LEARNINGS.md` documents what broke before the toolchain existed, 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. | ||
| ## What changes | ||
| @@ -69,3 +71,50 @@ | ||
| - Editor support ships as a TypeScript language service plugin, so VS Code and every TS-aware editor get diagnostics, go-to-definition, and macro expansion previews for free. | ||
| - Diagnostics are machine-first: every error has a stable code, a JSON output mode, and a suggested fix, so an agent can consume `tsus check --json` in a loop without parsing prose. Human-readable output is a rendering of the same data. | ||
| - No new package manager and no new registry. npm packages work through the boundary layer, and published `.tsus` packages ship compiled JS plus `.d.ts` files, so consumers don't need to know the source language existed. | ||
| + | ||
| +## The examples | ||
| + | ||
| +`examples/` is the test suite: 29 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. | ||
| + | ||
| +**Core language and runtime** | ||
| + | ||
| +| Example | Shows | | ||
| +|---|---| | ||
| +| `01-hello` | Smallest possible `.tsus` file compiling to plain ESM | | ||
| +| `02-option-basics` | `Option<T>` with `map`/`andThen`/`unwrapOr` | | ||
| +| `03-result-basics` | `Result<T, E>` with `map`/`mapErr` | | ||
| +| `04-match-option`, `05-match-result` | The `match` macro over Some/None and Ok/Err | | ||
| +| `06-tagged-union` | User-defined tagged unions with a `_` wildcard arm | | ||
| + | ||
| +**Rejected on purpose** (these pass by failing the checker with the right code) | ||
| + | ||
| +| Example | Code | | ||
| +|---|---| | ||
| +| `07-banned-null` | TSUS002 | | ||
| +| `08-banned-class` | TSUS001 | | ||
| +| `09-banned-var` | TSUS004 | | ||
| +| `10-banned-undefined` | TSUS003 | | ||
| +| `11-banned-throw` | TSUS005 | | ||
| + | ||
| +**Interop and stress** | ||
| + | ||
| +| Example | Shows | | ||
| +|---|---| | ||
| +| `12-tsus-imports-tsus`, `20-deep-chain` | `.tsus` import chains, four levels deep | | ||
| +| `13-tsus-imports-ts`, `14-ts-imports-tsus` | Mixed projects in both directions; `.ts` keeps its classes and nulls | | ||
| +| `15-npm-dependency` | zod feeding `Result` | | ||
| +| `16-boundary-fs`, `26-json-boundary` | `wrapAsync`/`wrapSync` turning throws into `Result` | | ||
| +| `17-nested-match`, `18-generics`, `19-async-result` | Nested matches, generic signatures, `await` inside match arms | | ||
| +| `21-circular-imports` | Function-level `.tsus` cycles (fine, because ESM) | | ||
| +| `22-mixed-project` | ts + tsus + zod + boundary in one project | | ||
| +| `24-hostile-syntax` | Decoy `match` blocks in strings, comments, and template literals | | ||
| +| `25-shadowed-match` | A user function named `match` staying a plain call | | ||
| + | ||
| +**Runtimes and frameworks** | ||
| + | ||
| +| Example | Shows | | ||
| +|---|---| | ||
| +| `23-cloudflare-worker` | Cloudflare `{ fetch }` module shape, tested against real `Request`/`Response` | | ||
| +| `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 | | ||
Checks
No checks reported for this commit.
Runs
No runs for this commit.