tsus build writes .d.ts declarations, so plain TypeScript can type the compiled output
Found by the Rebasely on-call pilot: a .ts module importing the built dist/*.js had no types
(tsc reports TS7016 under strict), although the README promised .d.ts output. Each .tsus and
.ts file under src now gets dist/<file>.d.ts from a declaration-only program over the same
virtual files; relative .tsus/.ts specifiers, including import types such as
import("./shapes.tsus.ts"), are rewritten to .js like the emitted JS. Declaration diagnostics
fail the build as TSUS200. examples/57-declarations pins the output; fileContains now works
for run examples too.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Changed files
12 files changed167 additions28 deletionsagainst b0c0c21
- ChangedAGENTS.md+1−1
- ChangedREADME.md+4−3
- Addedexamples/57-declarations/example.json+10−0
- Addedexamples/57-declarations/src/area.tsus+14−0
- Addedexamples/57-declarations/src/main.ts+10−0
- Addedexamples/57-declarations/src/report.tsus+4−0
- Addedexamples/57-declarations/src/shapes.tsus+6−0
- Changedpackages/cli/src/build.js+14−4
- Changedpackages/cli/src/compile.js+21−4
- Changedpackages/cli/src/program.js+65−6
- Changedpackages/cli/templates/AGENTS.md+1−1
- Changedscripts/run-examples.mjs+17−9
ChangedAGENTS.md+1−1
| @@ -8,7 +8,7 @@ | ||
| 2. Run `tsus check --json`. Each diagnostic has a stable `code`, a position, a `hint`, and usually a `fix` with exact text edits. | ||
| 3. Run `tsus fix` to apply every safe fix (`--unsafe` adds fixes that can change behavior; review those). Or apply a diagnostic's `fix.edits` yourself: each edit replaces `[start, end)` (UTF-16 offsets into the original file) with `newText`. | ||
| 4. For anything left, run `tsus explain <CODE>` and change the code. Do not work around a rule: there is no suppression comment, and `as`, `any` and `!` are themselves errors. | ||
| -5. Repeat until `tsus check` passes, then `tsus build` emits plain ESM into `dist/`. `tsus check` also type-checks the project in strict mode; a TypeScript error comes back as `TSUS200` with the original code in `tsCode`. | ||
| +5. Repeat until `tsus check` passes, then `tsus build` emits plain ESM, source maps and `.d.ts` declarations into `dist/`. `tsus check` also type-checks the project in strict mode; a TypeScript error comes back as `TSUS200` with the original code in `tsCode`. | ||
| To port a `.ts` file, run `tsus migrate src/file.ts`. It writes `src/file.tsus` next to it and lists what it could not convert. | ||
ChangedREADME.md+4−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, 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. | ||
| +**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 and `.d.ts` declarations for plain TypeScript consumers, `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 54 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. | ||
| @@ -107,7 +107,7 @@ | ||
| Tooling: | ||
| -- `tsus build` compiles to JS with source maps, `tsus check` type-checks without emitting. Both run as an esbuild/swc plugin so existing bundler setups pick up `.tsus` files without config changes. (Today the plugins run the syntactic rules only; the semantic type-check lives in `tsus check`.) | ||
| +- `tsus build` compiles to JS with source maps and `.d.ts` declarations (relative `.tsus` imports in them point at the emitted `.js`), `tsus check` type-checks without emitting. Both run as an esbuild/swc plugin so existing bundler setups pick up `.tsus` files without config changes. (Today the plugins run the syntactic rules only; the semantic type-check lives in `tsus check`.) | ||
| - 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. | ||
| @@ -163,7 +163,7 @@ | ||
| | 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. | ||
| +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`). | ||
| @@ -246,3 +246,4 @@ | ||
| | `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 | | ||
| +| `57-declarations` | `tsus build` writes `.d.ts` files, including an import type that names another `.tsus` module as `./shapes.js` | | ||
Addedexamples/57-declarations/example.json+10−0
| @@ -0,0 +1,10 @@ | ||
| +{ | ||
| + "expect": "run", | ||
| + "output": ["3", "9", "true", "3"], | ||
| + "fileContains": [ | ||
| + { "file": "dist/area.d.ts", "contains": "export declare const area: (s: Shape) => number;" }, | ||
| + { "file": "dist/area.d.ts", "contains": "import { type Shape } from \"./shapes.js\";" }, | ||
| + { "file": "dist/report.d.ts", "contains": "shape: import(\"./shapes.js\").Shape;" }, | ||
| + { "file": "dist/main.d.ts", "contains": "export {};" } | ||
| + ] | ||
| +} | ||
Addedexamples/57-declarations/src/area.tsus+14−0
| @@ -0,0 +1,14 @@ | ||
| +import { Some, None, type Option } from "@tsus/runtime"; | ||
| +import { circle, type Shape } from "./shapes.tsus"; | ||
| + | ||
| +export const area = (s: Shape): number => | ||
| + match (s) { | ||
| + Circle(r) => Math.round(Math.PI * r * r), | ||
| + Square(side) => side * side, | ||
| + }; | ||
| + | ||
| +// No annotation: the declaration has to name Shape from the other module. | ||
| +export const unit = () => circle(1); | ||
| + | ||
| +export const largest = (shapes: readonly Shape[]): Option<number> => | ||
| + shapes.length === 0 ? None : Some(Math.max(...shapes.map(area))); | ||
Addedexamples/57-declarations/src/main.ts+10−0
| @@ -0,0 +1,10 @@ | ||
| +// Plain TypeScript consuming .tsus modules. tsus build also writes dist/*.d.ts, so tsc and editors | ||
| +// can type the built output from outside the tsus project. | ||
| +import { area, largest, unit } from "./area.tsus"; | ||
| +import { square } from "./shapes.tsus"; | ||
| +import { unitReport } from "./report.tsus"; | ||
| + | ||
| +console.log(area(unit())); | ||
| +console.log(largest([square(3), unit()]).unwrapOr(0)); | ||
| +console.log(largest([]).isNone()); | ||
| +console.log(unitReport().area); | ||
Addedexamples/57-declarations/src/report.tsus+4−0
| @@ -0,0 +1,4 @@ | ||
| +import { area, unit } from "./area.tsus"; | ||
| + | ||
| +// Shape is never imported here, so the declaration names it with an import type. | ||
| +export const unitReport = () => ({ shape: unit(), area: area(unit()) }); | ||
Addedexamples/57-declarations/src/shapes.tsus+6−0
| @@ -0,0 +1,6 @@ | ||
| +import { tag, type Tagged } from "@tsus/runtime"; | ||
| + | ||
| +export type Shape = Tagged<"Circle", number> | Tagged<"Square", number>; | ||
| + | ||
| +export const circle = (r: number): Shape => tag("Circle", r); | ||
| +export const square = (side: number): Shape => tag("Square", side); | ||
Changedpackages/cli/src/build.js+14−4
| @@ -1,9 +1,10 @@ | ||
| -// tsus build: src/**/*.{ts,tsus} -> dist/**/*.js (plain ESM) + source maps. | ||
| +// tsus build: src/**/*.{ts,tsus} -> dist/**/*.js (plain ESM) + source maps + | ||
| +// .d.ts declarations. | ||
| // tsus check: the same pipeline without emitting. | ||
| import fs from "node:fs"; | ||
| import path from "node:path"; | ||
| -import { compileTsus, emitJs, relativeSourcePath } from "./compile.js"; | ||
| -import { semanticCheck } from "./program.js"; | ||
| +import { compileTsus, emitJs, relativeSourcePath, specifierTransformer } from "./compile.js"; | ||
| +import { emitDeclarations, semanticCheck } from "./program.js"; | ||
| const walk = (dir) => { | ||
| const out = []; | ||
| @@ -87,5 +88,14 @@ | ||
| fs.writeFileSync(`${dest}.map`, `${JSON.stringify(map)}\n`); | ||
| emitted.push(dest, `${dest}.map`); | ||
| } | ||
| - return { diagnostics: [], emitted }; | ||
| + const declarations = emitDeclarations({ | ||
| + rootDir, | ||
| + srcDir, | ||
| + distDir, | ||
| + tsFiles: files.filter(isTsFile), | ||
| + compiled, | ||
| + transformer: specifierTransformer, | ||
| + }); | ||
| + emitted.push(...declarations.written); | ||
| + return { diagnostics: declarations.diagnostics, emitted }; | ||
| }; | ||
Changedpackages/cli/src/compile.js+21−4
| @@ -25,15 +25,19 @@ | ||
| return { ...pre, source, fileName, locate, locateSource, diagnostics }; | ||
| }; | ||
| +// A declaration file can name a .tsus module by its virtual name (`./x.tsus.ts`, | ||
| +// or `./x.tsus.js` when TypeScript writes an import type), so those map to | ||
| +// `./x.js` as well. | ||
| const rewriteSpecifier = (spec) => | ||
| - /^\.{1,2}\//.test(spec) && /\.(tsus|ts)$/.test(spec) && !spec.endsWith(".d.ts") | ||
| - ? spec.replace(/\.(tsus|ts)$/, ".js") | ||
| + /^\.{1,2}\//.test(spec) && /\.(tsus|ts)$|\.tsus\.js$/.test(spec) && !spec.endsWith(".d.ts") | ||
| + ? spec.replace(/(\.tsus)?\.(tsus|ts|js)$/, ".js") | ||
| : spec; | ||
| // TS transformer: relative `.tsus`/`.ts` import specifiers become `.js`, so | ||
| // the emitted dist tree resolves on its own. Done on the AST rather than the | ||
| -// text so source map columns stay right. | ||
| -const specifierTransformer = (context) => { | ||
| +// text so source map columns stay right. Also used on declaration files, | ||
| +// where a type can name a module through an import type (`import("./x")`). | ||
| +export const specifierTransformer = (context) => { | ||
| const f = context.factory; | ||
| const visit = (node) => { | ||
| if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) { | ||
| @@ -58,6 +62,19 @@ | ||
| node.exportClause, | ||
| f.createStringLiteral(next), | ||
| node.attributes, | ||
| + ); | ||
| + } | ||
| + } | ||
| + if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument) && ts.isStringLiteral(node.argument.literal)) { | ||
| + const next = rewriteSpecifier(node.argument.literal.text); | ||
| + if (next !== node.argument.literal.text) { | ||
| + return f.updateImportTypeNode( | ||
| + node, | ||
| + f.updateLiteralTypeNode(node.argument, f.createStringLiteral(next)), | ||
| + node.attributes, | ||
| + node.qualifier, | ||
| + ts.visitNodes(node.typeArguments, visit), | ||
| + node.isTypeOf, | ||
| ); | ||
| } | ||
| } | ||
Changedpackages/cli/src/program.js+65−6
| @@ -81,12 +81,14 @@ | ||
| return tags; | ||
| }; | ||
| -export const semanticCheck = ({ rootDir, tsFiles, compiled }) => { | ||
| +// A compiler host that serves each .tsus file as its lowered TypeScript under | ||
| +// its virtual name and resolves relative `.tsus` specifiers to those names. | ||
| +const projectHost = (rootDir, compiled, options) => { | ||
| const virtual = new Map(); | ||
| for (const [file, c] of compiled) { | ||
| virtual.set(virtualName(file), c); | ||
| } | ||
| - const host = ts.createCompilerHost(COMPILER_OPTIONS, true); | ||
| + const host = ts.createCompilerHost(options, true); | ||
| const baseGetSourceFile = host.getSourceFile.bind(host); | ||
| const baseFileExists = host.fileExists.bind(host); | ||
| const baseReadFile = host.readFile.bind(host); | ||
| @@ -99,8 +101,8 @@ | ||
| }; | ||
| host.fileExists = (fileName) => virtual.has(fileName) || baseFileExists(fileName); | ||
| host.readFile = (fileName) => (virtual.has(fileName) ? virtual.get(fileName).code : baseReadFile(fileName)); | ||
| - const cache = ts.createModuleResolutionCache(rootDir, (f) => host.getCanonicalFileName(f), COMPILER_OPTIONS); | ||
| - host.resolveModuleNameLiterals = (literals, containingFile, redirected, options) => | ||
| + const cache = ts.createModuleResolutionCache(rootDir, (f) => host.getCanonicalFileName(f), options); | ||
| + host.resolveModuleNameLiterals = (literals, containingFile, redirected, opts) => | ||
| literals.map((literal) => { | ||
| const spec = literal.text; | ||
| if (/^\.{1,2}\//.test(spec) && spec.endsWith(".tsus")) { | ||
| @@ -111,10 +113,16 @@ | ||
| : undefined, | ||
| }; | ||
| } | ||
| - return ts.resolveModuleName(spec, containingFile, options, host, cache, redirected); | ||
| + return ts.resolveModuleName(spec, containingFile, opts, host, cache, redirected); | ||
| }); | ||
| + return host; | ||
| +}; | ||
| - const roots = [...tsFiles, ...[...compiled.keys()].map(virtualName)]; | ||
| +const rootsOf = (tsFiles, compiled) => [...tsFiles, ...[...compiled.keys()].map(virtualName)]; | ||
| + | ||
| +export const semanticCheck = ({ rootDir, tsFiles, compiled }) => { | ||
| + const host = projectHost(rootDir, compiled, COMPILER_OPTIONS); | ||
| + const roots = rootsOf(tsFiles, compiled); | ||
| const program = ts.createProgram({ rootNames: roots, options: COMPILER_OPTIONS, host }); | ||
| const checker = program.getTypeChecker(); | ||
| const diagnostics = []; | ||
| @@ -241,4 +249,55 @@ | ||
| } | ||
| } | ||
| return diagnostics; | ||
| +}; | ||
| + | ||
| +// Declaration files for `tsus build`: dist/<file>.d.ts for every .tsus and .ts | ||
| +// file under src, so plain TypeScript (tsc, an editor) can type the compiled | ||
| +// output. Import specifiers are rewritten the same way as in the emitted JS. | ||
| +// Returns the files written and any declaration diagnostic (TypeScript cannot | ||
| +// always name an inferred type in a .d.ts) as TSUS200. | ||
| +export const emitDeclarations = ({ rootDir, srcDir, distDir, tsFiles, compiled, transformer }) => { | ||
| + const options = { ...COMPILER_OPTIONS, noEmit: false, declaration: true, emitDeclarationOnly: true }; | ||
| + const host = projectHost(rootDir, compiled, options); | ||
| + const program = ts.createProgram({ rootNames: rootsOf(tsFiles, compiled), options, host }); | ||
| + const sources = [ | ||
| + ...tsFiles.filter((f) => !f.endsWith(".d.ts")).map((f) => ({ file: f, name: f })), | ||
| + ...[...compiled.keys()].map((f) => ({ file: f, name: virtualName(f) })), | ||
| + ]; | ||
| + const written = []; | ||
| + const diagnostics = []; | ||
| + for (const { file, name } of sources) { | ||
| + const sf = program.getSourceFile(name); | ||
| + if (!sf) { | ||
| + continue; | ||
| + } | ||
| + const dest = path.join(distDir, path.relative(srcDir, file).replace(/\.(tsus|ts)$/, ".d.ts")); | ||
| + const result = program.emit( | ||
| + sf, | ||
| + (_fileName, text) => { | ||
| + host.writeFile(dest, text, false); | ||
| + written.push(dest); | ||
| + }, | ||
| + undefined, | ||
| + true, | ||
| + { afterDeclarations: [transformer] }, | ||
| + ); | ||
| + const c = compiled.get(file); | ||
| + for (const d of result.diagnostics) { | ||
| + const at = d.start ?? 0; | ||
| + const where = c ? c.locate(at) : (() => { | ||
| + const { line, character } = sf.getLineAndCharacterOfPosition(at); | ||
| + return { line: line + 1, col: character + 1 }; | ||
| + })(); | ||
| + diagnostics.push({ | ||
| + code: "TSUS200", | ||
| + tsCode: d.code, | ||
| + message: ts.flattenDiagnosticMessageText(d.messageText, " "), | ||
| + hint: describe("TSUS200").hint, | ||
| + file: path.relative(rootDir, file), | ||
| + ...where, | ||
| + }); | ||
| + } | ||
| + } | ||
| + return { written, diagnostics }; | ||
| }; | ||
Changedpackages/cli/templates/AGENTS.md+1−1
| @@ -8,7 +8,7 @@ | ||
| 2. Run `tsus check --json`. Each diagnostic has a stable `code`, a position, a `hint`, and usually a `fix` with exact text edits. | ||
| 3. Run `tsus fix` to apply every safe fix (`--unsafe` adds fixes that can change behavior; review those). Or apply a diagnostic's `fix.edits` yourself: each edit replaces `[start, end)` (UTF-16 offsets into the original file) with `newText`. | ||
| 4. For anything left, run `tsus explain <CODE>` and change the code. Do not work around a rule: there is no suppression comment, and `as`, `any` and `!` are themselves errors. | ||
| -5. Repeat until `tsus check` passes, then `tsus build` emits plain ESM into `dist/`. `tsus check` also type-checks the project in strict mode; a TypeScript error comes back as `TSUS200` with the original code in `tsCode`. | ||
| +5. Repeat until `tsus check` passes, then `tsus build` emits plain ESM, source maps and `.d.ts` declarations into `dist/`. `tsus check` also type-checks the project in strict mode; a TypeScript error comes back as `TSUS200` with the original code in `tsCode`. | ||
| To port a `.ts` file, run `tsus migrate src/file.ts`. It writes `src/file.tsus` next to it and lists what it could not convert. | ||
Changedscripts/run-examples.mjs+17−9
| @@ -120,6 +120,21 @@ | ||
| const runNode = (args, cwd) => | ||
| spawnSync(process.execPath, args, { cwd, encoding: "utf8", timeout: 30_000 }); | ||
| +// "fileContains": [{ file, contains }] — each produced file must exist and | ||
| +// contain the text (framework output, emitted declarations). | ||
| +const checkFiles = (dir, manifest) => { | ||
| + for (const fc of manifest.fileContains ?? []) { | ||
| + const produced = path.join(dir, fc.file); | ||
| + if (!fs.existsSync(produced)) { | ||
| + return `expected output file ${fc.file} was not produced`; | ||
| + } | ||
| + if (!fs.readFileSync(produced, "utf8").includes(fc.contains)) { | ||
| + return `${fc.file} does not contain ${JSON.stringify(fc.contains)}`; | ||
| + } | ||
| + } | ||
| + return ""; | ||
| +}; | ||
| + | ||
| const checkLines = (stdout, expected) => { | ||
| const lines = stdout.trim().split("\n").map((l) => l.trim()); | ||
| if (lines.length !== expected.length) { | ||
| @@ -167,14 +182,7 @@ | ||
| if (manifest.output) { | ||
| failure = checkLines(rc.stdout, manifest.output); | ||
| } | ||
| - for (const fc of manifest.fileContains ?? []) { | ||
| - const produced = path.join(dir, fc.file); | ||
| - if (!fs.existsSync(produced)) { | ||
| - failure = `expected output file ${fc.file} was not produced`; | ||
| - } else if (!fs.readFileSync(produced, "utf8").includes(fc.contains)) { | ||
| - failure = `${fc.file} does not contain ${JSON.stringify(fc.contains)}`; | ||
| - } | ||
| - } | ||
| + failure ||= checkFiles(dir, manifest); | ||
| } | ||
| } | ||
| results.push({ name, ok: failure === "", failure }); | ||
| @@ -227,7 +235,7 @@ | ||
| if (rr.status !== 0) { | ||
| failure = `run failed:\n${(rr.stderr || "").trim()}`; | ||
| } else { | ||
| - failure = checkLines(rr.stdout, manifest.output); | ||
| + failure = checkLines(rr.stdout, manifest.output) || checkFiles(dir, manifest); | ||
| } | ||
| } else if (manifest.expect === "worker") { | ||
| const entry = pathToFileURL(path.join(dir, "dist", manifest.entry)).href; | ||
Checks
No checks reported for this commit.
Runs
No runs for this commit.