@fulcro/transform-core 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -17,6 +17,11 @@
  * other.
  */
 export { createFileTransformer, type FileTransformer, type TransformCoreOptions, } from './program/index.js';
+export { type ExpressionContext, type ExpressionRewriter, type Replacement, rewriteSourceFile, type RewriteStatistics, } from './rewrite/file/index.js';
+export { isRewritable, type ProgramRewrite, type ProgramSource, rewriteToFixpoint, } from './rewrite/fixpoint/index.js';
+export { createLanguageServicePlugin, type LanguageServicePlugin, type PluginCreateInfo, } from './rewrite/languageService/index.js';
+export { createProgramTransformer, type ProgramTransformer, rewriteProgram, } from './rewrite/programTransformer/index.js';
+export { type RewrittenText } from './rewrite/text/index.js';
 export { type CallForm, type CallRewriter, IDENTIFIER_PATTERN, isOwnedCall, isTupleType, type RewriteContext, utilityModuleSegment, } from './shared/index.js';
 export { buildStructuralTest, type StructuralOptions, type TypeTest, } from './structural/index.js';
 export { createTransformer, type TransformerFactory, type TransformerOptions, } from './transformer/index.js';

package/dist/index.js

@@ -18,9 +18,19 @@
  * other.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createTransformer = exports.buildStructuralTest = exports.utilityModuleSegment = exports.isTupleType = exports.isOwnedCall = exports.IDENTIFIER_PATTERN = exports.createFileTransformer = void 0;
+exports.createTransformer = exports.buildStructuralTest = exports.utilityModuleSegment = exports.isTupleType = exports.isOwnedCall = exports.IDENTIFIER_PATTERN = exports.rewriteProgram = exports.createProgramTransformer = exports.createLanguageServicePlugin = exports.rewriteToFixpoint = exports.isRewritable = exports.rewriteSourceFile = exports.createFileTransformer = void 0;
 var program_1 = require("./program/index.js");
 Object.defineProperty(exports, "createFileTransformer", { enumerable: true, get: function () { return program_1.createFileTransformer; } });
+var file_1 = require("./rewrite/file/index.js");
+Object.defineProperty(exports, "rewriteSourceFile", { enumerable: true, get: function () { return file_1.rewriteSourceFile; } });
+var fixpoint_1 = require("./rewrite/fixpoint/index.js");
+Object.defineProperty(exports, "isRewritable", { enumerable: true, get: function () { return fixpoint_1.isRewritable; } });
+Object.defineProperty(exports, "rewriteToFixpoint", { enumerable: true, get: function () { return fixpoint_1.rewriteToFixpoint; } });
+var languageService_1 = require("./rewrite/languageService/index.js");
+Object.defineProperty(exports, "createLanguageServicePlugin", { enumerable: true, get: function () { return languageService_1.createLanguageServicePlugin; } });
+var programTransformer_1 = require("./rewrite/programTransformer/index.js");
+Object.defineProperty(exports, "createProgramTransformer", { enumerable: true, get: function () { return programTransformer_1.createProgramTransformer; } });
+Object.defineProperty(exports, "rewriteProgram", { enumerable: true, get: function () { return programTransformer_1.rewriteProgram; } });
 var shared_1 = require("./shared/index.js");
 Object.defineProperty(exports, "IDENTIFIER_PATTERN", { enumerable: true, get: function () { return shared_1.IDENTIFIER_PATTERN; } });
 Object.defineProperty(exports, "isOwnedCall", { enumerable: true, get: function () { return shared_1.isOwnedCall; } });

package/dist/program/index.d.ts

@@ -1,5 +1,82 @@
+import typescript from 'typescript';
 import { CallRewriter } from '../shared/index.js';
 import { TransformerOptions } from '../transformer/index.js';
+/**
+ * Rewrites a path the way the compiler spells it.
+ *
+ * TypeScript keeps every file name with forward slashes, on every platform,
+ * while the bundler and `path.normalize` hand back the native separator. Mixing
+ * the two silently defeats every lookup against the files of the program: a
+ * file already in it looks new, gets added as another root, and invalidates the
+ * whole program — turning one startup cost into one per file.
+ *
+ * @param fileName Path in whatever spelling it arrived.
+ * @returns The path as the compiler spells it.
+ */
+export declare const toCompilerPath: (fileName: string) => string;
+/**
+ * Keeps a TypeScript program alive across recompilations.
+ *
+ * A language service rather than a one shot program: a watch run recompiles the
+ * same files repeatedly, and rebuilding the whole program on each edit would
+ * cost seconds every keystroke. The service reuses everything that did not
+ * change, and the version counters below are what tell it what did.
+ */
+export declare class ProgramHost implements typescript.LanguageServiceHost {
+    /** Files of the program, as resolved from the tsconfig. */
+    private readonly rootNames;
+    /** Compiler options resolved from the tsconfig. */
+    private readonly options;
+    /** Content handed over by the bundler, which may be ahead of the disk. */
+    private readonly overlays;
+    /** Bumped whenever a file changes, which is how the service invalidates. */
+    private readonly versions;
+    /** Directory the relative paths of the program resolve against. */
+    private readonly currentDirectory;
+    /**
+     * Initializes the host from a parsed tsconfig.
+     *
+     * @param parsed Parsed contents of the tsconfig.
+     * @param currentDirectory Directory the program resolves against.
+     */
+    constructor(parsed: typescript.ParsedCommandLine, currentDirectory: string);
+    /**
+     * Records the content of a file as the bundler sees it.
+     *
+     * @param fileName File being compiled.
+     * @param content Current content of the file.
+     */
+    update(fileName: string, content: string): void;
+    /**
+     * Tells whether the content handed over matches what is on disk.
+     *
+     * @param fileName File being compiled.
+     * @param content Content handed over by the bundler.
+     * @returns `true` when the two are identical.
+     */
+    private matchesDisk;
+    getScriptFileNames(): string[];
+    getScriptVersion(fileName: string): string;
+    getScriptSnapshot(fileName: string): typescript.IScriptSnapshot | undefined;
+    getCurrentDirectory(): string;
+    getCompilationSettings(): typescript.CompilerOptions;
+    getDefaultLibFileName(options: typescript.CompilerOptions): string;
+    readFile(fileName: string, encoding?: string): string | undefined;
+    fileExists(fileName: string): boolean;
+    readDirectory: (path: string, extensions?: readonly string[], exclude?: readonly string[], include?: readonly string[], depth?: number) => string[];
+    directoryExists: (path: string) => boolean;
+    getDirectories: (path: string) => string[];
+    realpath: ((path: string) => string) | undefined;
+}
+/**
+ * Locates and parses the tsconfig driving the program.
+ *
+ * @param root Directory the search starts from.
+ * @param explicit Path given in the options, when there is one.
+ * @returns The parsed tsconfig.
+ * @throws {Error} When no tsconfig can be found or it cannot be read.
+ */
+export declare const parseTsconfig: (root: string, explicit: string | undefined) => typescript.ParsedCommandLine;
 /** Options accepted by the transformer core. */
 export interface TransformCoreOptions extends TransformerOptions {
     /** Path of the tsconfig driving the program. Defaults to the nearest one. */

package/dist/program/index.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createFileTransformer = void 0;
+exports.createFileTransformer = exports.parseTsconfig = exports.ProgramHost = exports.toCompilerPath = void 0;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const typescript_1 = __importDefault(require("typescript"));
@@ -86,6 +86,7 @@ const buildUtilityPattern = (rewriters) => {
  * @returns The path as the compiler spells it.
  */
 const toCompilerPath = (fileName) => path.resolve(fileName).split(path.sep).join('/');
+exports.toCompilerPath = toCompilerPath;
 /**
  * Keeps a TypeScript program alive across recompilations.
  *
@@ -112,7 +113,7 @@ class ProgramHost {
      * @param currentDirectory Directory the program resolves against.
      */
     constructor(parsed, currentDirectory) {
-        this.rootNames = parsed.fileNames.map(toCompilerPath);
+        this.rootNames = parsed.fileNames.map(exports.toCompilerPath);
         this.options = parsed.options;
         this.currentDirectory = currentDirectory;
     }
@@ -192,6 +193,7 @@ class ProgramHost {
     getDirectories = typescript_1.default.sys.getDirectories;
     realpath = typescript_1.default.sys.realpath;
 }
+exports.ProgramHost = ProgramHost;
 /**
  * Locates and parses the tsconfig driving the program.
  *
@@ -214,6 +216,7 @@ const parseTsconfig = (root, explicit) => {
     }
     return typescript_1.default.parseJsonConfigFileContent(read.config, typescript_1.default.sys, path.dirname(configPath));
 };
+exports.parseTsconfig = parseTsconfig;
 /**
  * Creates the transformer core.
  *
@@ -244,9 +247,9 @@ const createFileTransformer = (rewriters, options = {}) => {
         // would cost seconds for nothing.
         if (!utilityPattern.test(code))
             return null;
-        const fileName = toCompilerPath(id.split('?')[0]);
+        const fileName = (0, exports.toCompilerPath)(id.split('?')[0]);
         if (host === undefined || service === undefined) {
-            host = new ProgramHost(parseTsconfig(root, options.tsconfig), root);
+            host = new ProgramHost((0, exports.parseTsconfig)(root, options.tsconfig), root);
             service = typescript_1.default.createLanguageService(host, typescript_1.default.createDocumentRegistry());
         }
         host.update(fileName, code);

package/dist/rewrite/file/index.d.ts

@@ -0,0 +1,74 @@
+import typescript from 'typescript';
+import { type RewrittenText } from '../text/index.js';
+/**
+ * One file rewritten before type checking.
+ *
+ * The call rewriters of `@/shared` run after the checker, on a tree whose types
+ * are already settled, and replace a call by a node. This is the other kind:
+ * it replaces **text**, before the checker has run on it, so that what it emits
+ * is what gets type checked. That is the only way to give a type a meaning the
+ * checker would otherwise refuse — `decimal * decimal` is a type error until it
+ * has become `decimal.multiply(decimal)`.
+ *
+ * The rewriter is asked about each node, outermost first, and answers with the
+ * text that replaces it, in which child nodes may appear to be rendered in turn.
+ * Everything it does not claim is copied verbatim, so the output differs from
+ * the input only where something was rewritten.
+ */
+/** Everything a rewriter needs to decide about one node. */
+export interface ExpressionContext {
+    /** Checker of the program the file belongs to. */
+    readonly checker: typescript.TypeChecker;
+    /** The file being rewritten. */
+    readonly sourceFile: typescript.SourceFile;
+    /**
+     * The line breaks the original text has between two offsets, as a string
+     * of newlines.
+     *
+     * Put into the synthesized text between two operands, it keeps every line
+     * of the file where it was — so an error the checker reports on the
+     * rewritten text still names the line the author wrote.
+     */
+    readonly lineBreaks: (start: number, end: number) => string;
+}
+/**
+ * What replaces a node: synthesized text and child nodes, in order. A node is
+ * rendered in turn — itself rewritten where the rewriter claims it — and may
+ * appear more than once.
+ */
+export type Replacement = readonly (string | typescript.Node)[];
+/** Rewrites the nodes of one kind of construct, before type checking. */
+export interface ExpressionRewriter {
+    /**
+     * Module the rewritten code refers to, imported under
+     * {@link ExpressionRewriter.namespace} in every file that was rewritten.
+     */
+    readonly module: string;
+    /** Local name the module is imported under. */
+    readonly namespace: string;
+    /**
+     * Rewrites one node.
+     *
+     * @param node Node being considered.
+     * @param context The file and its checker.
+     * @returns The replacement, or `null` to keep the node and look inside it.
+     */
+    readonly rewrite: (node: typescript.Node, context: ExpressionContext) => Replacement | null;
+}
+/** How much a rewrite looked at, for the suites that count it. */
+export interface RewriteStatistics {
+    /** Nodes the rewriter was asked about. */
+    visited: number;
+    /** Nodes it replaced. */
+    rewritten: number;
+}
+/**
+ * Rewrites one source file.
+ *
+ * @param sourceFile File to rewrite, from a program whose checker is given.
+ * @param checker Checker of that program.
+ * @param rewriter What to rewrite.
+ * @param statistics Counters to add to, when the caller keeps them.
+ * @returns The rewritten text and its map, or `null` when nothing was claimed.
+ */
+export declare const rewriteSourceFile: (sourceFile: typescript.SourceFile, checker: typescript.TypeChecker, rewriter: ExpressionRewriter, statistics?: RewriteStatistics) => RewrittenText | null;

package/dist/rewrite/file/index.js

@@ -0,0 +1,124 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rewriteSourceFile = void 0;
+const typescript_1 = __importDefault(require("typescript"));
+const text_1 = require("../text/index.js");
+/**
+ * Where the namespace import goes: on the first line of the first statement,
+ * before it and without a line break, so no line of the file moves. At the end
+ * of the file would keep the lines too, but a CommonJS emit leaves a `require`
+ * where the import was written, and code above it would run first.
+ *
+ * @param sourceFile File being rewritten.
+ * @returns The offset to insert at.
+ */
+const importOffset = (sourceFile) => {
+    const [first] = sourceFile.statements;
+    return first === undefined ? sourceFile.end : first.getStart(sourceFile);
+};
+/**
+ * Rewrites one source file.
+ *
+ * @param sourceFile File to rewrite, from a program whose checker is given.
+ * @param checker Checker of that program.
+ * @param rewriter What to rewrite.
+ * @param statistics Counters to add to, when the caller keeps them.
+ * @returns The rewritten text and its map, or `null` when nothing was claimed.
+ */
+const rewriteSourceFile = (sourceFile, checker, rewriter, statistics) => {
+    const original = sourceFile.text;
+    const output = (0, text_1.createTextBuilder)(original);
+    const context = {
+        checker,
+        sourceFile,
+        lineBreaks: (start, end) => '\n'.repeat(original.slice(start, end).split('\n').length - 1),
+    };
+    const importDeclaration = `import * as ${rewriter.namespace} from '${rewriter.module}'; `;
+    let cursor = 0;
+    let rewroteAny = false;
+    /**
+     * Copies original text from the cursor up to an offset.
+     *
+     * @param end Offset to copy up to.
+     */
+    const advance = (end) => {
+        output.copy(cursor, end);
+        cursor = Math.max(cursor, end);
+    };
+    const render = (node) => {
+        if (statistics !== undefined)
+            statistics.visited++;
+        const replacement = rewriter.rewrite(node, context);
+        if (replacement === null) {
+            typescript_1.default.forEachChild(node, (child) => {
+                advance(child.getStart(sourceFile));
+                render(child);
+            });
+            return;
+        }
+        rewroteAny = true;
+        if (statistics !== undefined)
+            statistics.rewritten++;
+        const start = node.getStart(sourceFile);
+        advance(start);
+        const close = output.open(start, node.end);
+        for (const part of replacement) {
+            if (typeof part === 'string') {
+                output.write(part);
+            }
+            else {
+                // A child is rendered from its own start, independently of the
+                // cursor: it may be written twice, and in any order.
+                const saved = cursor;
+                cursor = part.getStart(sourceFile);
+                render(part);
+                output.copy(cursor, part.end);
+                cursor = saved;
+            }
+        }
+        close();
+        cursor = node.end;
+    };
+    typescript_1.default.forEachChild(sourceFile, (child) => {
+        advance(child.getStart(sourceFile));
+        render(child);
+    });
+    advance(sourceFile.end);
+    if (!rewroteAny)
+        return null;
+    // A second pass over an already rewritten file finds the import there and
+    // must not add another. The import is only known to be needed once the
+    // walk is over, so it is spliced in afterwards rather than written in
+    // passing.
+    if (original.includes(importDeclaration))
+        return output.build();
+    return withImport(output.build(), importOffset(sourceFile), importDeclaration);
+};
+exports.rewriteSourceFile = rewriteSourceFile;
+/**
+ * Inserts the namespace import into a rewritten text, extending its map.
+ *
+ * @param rewritten The rewritten text, without the import.
+ * @param originalOffset Where, in the original, the import goes.
+ * @param declaration The import declaration, with its trailing space.
+ * @returns The text with the import and a map that accounts for it.
+ */
+const withImport = (rewritten, originalOffset, declaration) => {
+    const at = rewritten.toGenerated(originalOffset);
+    const length = declaration.length;
+    return {
+        text: rewritten.text.slice(0, at) + declaration + rewritten.text.slice(at),
+        toOriginal: (generated) => generated < at
+            ? rewritten.toOriginal(generated)
+            : generated < at + length
+                ? originalOffset
+                : rewritten.toOriginal(generated - length),
+        toGenerated: (original) => {
+            const position = rewritten.toGenerated(original);
+            return position < at ? position : position + length;
+        },
+    };
+};

package/dist/rewrite/fileTransformer/index.d.ts

@@ -0,0 +1,10 @@
+import { type FileTransformer, type TransformCoreOptions } from '../../program/index.js';
+import { type ExpressionRewriter } from '../file/index.js';
+/**
+ * Creates the bundler core of a rewriter.
+ *
+ * @param rewriter What to rewrite.
+ * @param options Options of the core.
+ * @returns A transformer any bundler adapter can drive.
+ */
+export declare const createRewritingFileTransformer: (rewriter: ExpressionRewriter, options?: TransformCoreOptions) => FileTransformer;

package/dist/rewrite/fileTransformer/index.js

@@ -0,0 +1,131 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRewritingFileTransformer = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const typescript_1 = __importDefault(require("typescript"));
+const program_1 = require("../../program/index.js");
+const fixpoint_1 = require("../fixpoint/index.js");
+/**
+ * The bundler integration of a rewrite that has to happen before type
+ * checking.
+ *
+ * A bundler never type checks — esbuild and swc erase the types — so an error
+ * the checker would raise on `decimal * decimal` never stops it. What it does
+ * need is the rewrite itself, and that needs the whole program: whether `c + d`
+ * in one file is claimable depends on how `c` was declared in another. So the
+ * first file to arrive rewrites the whole program to a fixed point, and every
+ * file after it is answered from that until some file changes.
+ */
+/** Extensions carrying TypeScript this transformer is responsible for. */
+const HANDLED_EXTENSIONS = ['.ts', '.mts', '.cts', '.tsx'];
+/**
+ * Creates the bundler core of a rewriter.
+ *
+ * @param rewriter What to rewrite.
+ * @param options Options of the core.
+ * @returns A transformer any bundler adapter can drive.
+ */
+const createRewritingFileTransformer = (rewriter, options = {}) => {
+    const root = options.root ?? process.cwd();
+    let host;
+    let service;
+    let rewrite;
+    /** What the bundler last handed over for each file, before any rewrite. */
+    const originals = new Map();
+    const handles = (id) => {
+        const fileName = id.split('?')[0];
+        if (!HANDLED_EXTENSIONS.includes(path.extname(fileName)))
+            return false;
+        return !fileName.includes('node_modules');
+    };
+    /**
+     * Puts every rewritten file back to its original text, so the next rewrite
+     * starts from what the author wrote rather than from its own output.
+     *
+     * @param programHost The host holding the texts.
+     */
+    const restore = (programHost) => {
+        for (const fileName of rewrite?.files.keys() ?? []) {
+            const text = originals.get(fileName) ??
+                (fs.existsSync(fileName)
+                    ? fs.readFileSync(fileName, 'utf8')
+                    : undefined);
+            if (text !== undefined)
+                programHost.update(fileName, text);
+        }
+        rewrite = undefined;
+    };
+    const transform = (id, code) => {
+        if (!handles(id))
+            return null;
+        const fileName = (0, program_1.toCompilerPath)(id.split('?')[0]);
+        if (host === undefined || service === undefined) {
+            host = new program_1.ProgramHost((0, program_1.parseTsconfig)(root, options.tsconfig), root);
+            service = typescript_1.default.createLanguageService(host, typescript_1.default.createDocumentRegistry());
+        }
+        if (originals.get(fileName) !== code) {
+            originals.set(fileName, code);
+            restore(host);
+            host.update(fileName, code);
+        }
+        if (rewrite === undefined) {
+            const programHost = host;
+            const languageService = service;
+            rewrite = (0, fixpoint_1.rewriteToFixpoint)({
+                program: () => {
+                    const program = languageService.getProgram();
+                    if (program === undefined) {
+                        throw new Error(`The language service produced no program for ${root}.`);
+                    }
+                    return program;
+                },
+                update: (name, text) => programHost.update(name, text),
+            }, rewriter);
+        }
+        const sourceFile = service
+            .getProgram()
+            ?.getSourceFile(fileName);
+        if (sourceFile !== undefined && !(0, fixpoint_1.isRewritable)(sourceFile))
+            return null;
+        return rewrite.files.get(fileName)?.text ?? null;
+    };
+    return { handles, transform };
+};
+exports.createRewritingFileTransformer = createRewritingFileTransformer;

package/dist/rewrite/fixpoint/index.d.ts

@@ -0,0 +1,56 @@
+import typescript from 'typescript';
+import { type ExpressionRewriter, type RewriteStatistics } from '../file/index.js';
+import { type RewrittenText } from '../text/index.js';
+/**
+ * Rewriting a whole program until nothing more is claimed.
+ *
+ * One pass is not enough, because rewriting changes what the checker infers.
+ * `const c = a + b` types `c` as `number` in the original — the checker has no
+ * idea `+` means anything else — so a later `c + d` looks like arithmetic on a
+ * plain number and is left alone. Once the first line reads
+ * `const c = T.add(a, b)`, `c` has the type `T.add` returns, and the second
+ * line is claimable. So the program is rewritten, re-checked, and rewritten
+ * again until a pass claims nothing — each pass can only claim sites the one
+ * before could not, so the loop ends, and a bound on it makes sure it does.
+ *
+ * Where the program comes from is the caller's: a fresh `createProgram` for
+ * `tsc`, a language service for a bundler or an editor. This only needs to ask
+ * for the current program and to hand text back.
+ */
+/** Something that holds a program and can have its files replaced. */
+export interface ProgramSource {
+    /** The program as it stands, with every text handed back so far. */
+    readonly program: () => typescript.Program;
+    /**
+     * Replaces the text of a file for the next {@link ProgramSource.program}.
+     *
+     * @param fileName File, as the program spells it.
+     * @param text Its new text.
+     */
+    readonly update: (fileName: string, text: string) => void;
+}
+/** The outcome of rewriting a program. */
+export interface ProgramRewrite {
+    /** Each rewritten file, mapped back to its original text. */
+    readonly files: ReadonlyMap<string, RewrittenText>;
+    /** Passes it took, the last one claiming nothing. */
+    readonly passes: number;
+    /** Nodes considered and replaced, over every pass. */
+    readonly statistics: RewriteStatistics;
+}
+/**
+ * Tells whether a file is the consumer's own source, which is all a rewrite
+ * touches: never a declaration file, never a dependency.
+ *
+ * @param sourceFile File of the program.
+ * @returns `true` when it may be rewritten.
+ */
+export declare const isRewritable: (sourceFile: typescript.SourceFile) => boolean;
+/**
+ * Rewrites a program to a fixed point.
+ *
+ * @param source Where the program comes from.
+ * @param rewriter What to rewrite.
+ * @returns The rewritten files and what it took.
+ */
+export declare const rewriteToFixpoint: (source: ProgramSource, rewriter: ExpressionRewriter) => ProgramRewrite;

package/dist/rewrite/fixpoint/index.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rewriteToFixpoint = exports.isRewritable = void 0;
+const file_1 = require("../file/index.js");
+const text_1 = require("../text/index.js");
+/**
+ * Passes after which the loop stops whether or not it has settled. Each pass
+ * resolves one more step of inference through a chain of declarations, and a
+ * program needing more than this has a chain of `const` declarations longer
+ * than anyone writes — its remaining sites are left as the checker sees them,
+ * and report their own type errors.
+ */
+const MAXIMUM_PASSES = 16;
+/**
+ * Tells whether a file is the consumer's own source, which is all a rewrite
+ * touches: never a declaration file, never a dependency.
+ *
+ * @param sourceFile File of the program.
+ * @returns `true` when it may be rewritten.
+ */
+const isRewritable = (sourceFile) => !sourceFile.isDeclarationFile &&
+    !sourceFile.fileName.includes('/node_modules/');
+exports.isRewritable = isRewritable;
+/**
+ * Rewrites a program to a fixed point.
+ *
+ * @param source Where the program comes from.
+ * @param rewriter What to rewrite.
+ * @returns The rewritten files and what it took.
+ */
+const rewriteToFixpoint = (source, rewriter) => {
+    const files = new Map();
+    const statistics = { visited: 0, rewritten: 0 };
+    let passes = 0;
+    while (passes < MAXIMUM_PASSES) {
+        passes++;
+        const program = source.program();
+        const checker = program.getTypeChecker();
+        const changed = [];
+        for (const sourceFile of program.getSourceFiles()) {
+            if (!(0, exports.isRewritable)(sourceFile))
+                continue;
+            const rewritten = (0, file_1.rewriteSourceFile)(sourceFile, checker, rewriter, statistics);
+            if (rewritten !== null)
+                changed.push([sourceFile.fileName, rewritten]);
+        }
+        if (changed.length === 0)
+            break;
+        // Handed back only once the pass is over, so every file of a pass is
+        // read against the same program.
+        for (const [fileName, rewritten] of changed) {
+            const previous = files.get(fileName);
+            files.set(fileName, previous === undefined
+                ? rewritten
+                : (0, text_1.composeRewrites)(previous, rewritten));
+            source.update(fileName, rewritten.text);
+        }
+    }
+    return { files, passes, statistics };
+};
+exports.rewriteToFixpoint = rewriteToFixpoint;

package/dist/rewrite/languageService/index.d.ts

@@ -0,0 +1,40 @@
+import typescript from 'typescript';
+import { type ExpressionRewriter } from '../file/index.js';
+/**
+ * The editor integration of a rewrite that has to happen before type checking.
+ *
+ * An editor asks `tsserver`, and `tsserver` checks the files as written: it has
+ * never heard of the rewrite, so it underlines `decimal * decimal` and reports
+ * `a + b` as a `number` even in a project that builds cleanly. A language
+ * service plugin is the one place to change that.
+ *
+ * The plugin keeps a second language service — the shadow — over the same
+ * project with every file rewritten, and answers the questions that depend on
+ * types from it: the diagnostics, the hover, the completions, where a name is
+ * defined, the signature being typed. Each position the editor sends is mapped
+ * into the rewritten text before it is asked, and each span in the answer is
+ * mapped back, so the editor never sees text it did not write. Everything else
+ * — formatting, folding, the syntax — is the original service's, untouched.
+ *
+ * ```json
+ * { "compilerOptions": { "plugins": [{ "name": "@fulcro/types/language-service" }] } }
+ * ```
+ */
+/** What `tsserver` hands a plugin's `create`. */
+export interface PluginCreateInfo {
+    readonly languageService: typescript.LanguageService;
+    readonly languageServiceHost: typescript.LanguageServiceHost;
+}
+/** The module shape `tsserver` loads a plugin from. */
+export type LanguageServicePlugin = (modules: {
+    readonly typescript: typeof typescript;
+}) => {
+    readonly create: (info: PluginCreateInfo) => typescript.LanguageService;
+};
+/**
+ * Builds the `tsserver` plugin of a rewriter.
+ *
+ * @param rewriter What to rewrite.
+ * @returns The plugin module, as `tsserver` loads it.
+ */
+export declare const createLanguageServicePlugin: (rewriter: ExpressionRewriter) => LanguageServicePlugin;