@fulcro/transform-core 0.10.0 → 0.11.0

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

@@ -1,40 +0,0 @@
-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;

package/dist/rewrite/languageService/index.js

@@ -1,286 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createLanguageServicePlugin = void 0;
-const typescript_1 = __importDefault(require("typescript"));
-const fixpoint_1 = require("../fixpoint/index.js");
-/**
- * A file name as the program spells it: forward slashes on every platform.
- * `tsserver` and a host may hand either spelling over, and a map keyed by one
- * would never be found by the other.
- *
- * @param fileName File name in either spelling.
- * @returns The program's spelling.
- */
-const normalized = (fileName) => fileName.replace(/\\/g, '/');
-/** The map of a file the rewrite did not touch: every offset is itself. */
-const UNCHANGED = {
-    text: '',
-    toOriginal: (generated) => generated,
-    toGenerated: (original) => original,
-};
-/**
- * Maps a span of the rewritten text back to the original.
- *
- * @param span Span in the rewritten text.
- * @param map Map of the file.
- * @returns The span in the original text.
- */
-const spanToOriginal = (span, map) => {
-    const start = map.toOriginal(span.start);
-    if (span.length === 0)
-        return { start, length: 0 };
-    // The end is exclusive, so it can sit exactly where a copied piece stops
-    // and synthesized text begins, and would map to the start of the rewritten
-    // node. The last character of the span is inside the span; mapping it and
-    // stepping one past lands where the span really ends.
-    const end = map.toOriginal(span.start + span.length - 1) + 1;
-    return { start, length: Math.max(0, end - start) };
-};
-/**
- * Removes the namespace the rewrite imports from text shown to the reader.
- *
- * The checker names a type by the shortest path it can reach it through, and
- * in a rewritten file that is often the namespace import the rewrite added —
- * `__fulcroTypes.SignedInteger<32>`, a name the author never wrote.
- *
- * @param namespace Local name of the import.
- * @returns The cleaner.
- */
-const withoutNamespace = (namespace) => (text) => text.split(`${namespace}.`).join('');
-/**
- * Builds the shadow of a language service: the same project, every file read
- * through the rewrite.
- *
- * @param info What `tsserver` handed the plugin.
- * @param rewriter What to rewrite.
- * @returns The shadow, and the rewrite it is currently built on.
- */
-const createShadow = (info, rewriter) => {
-    const base = info.languageServiceHost;
-    const texts = new Map();
-    // Bumped on every text handed back, so the shadow re-reads exactly the
-    // files the rewrite changed.
-    let generation = 0;
-    const host = Object.create(base, {
-        getScriptSnapshot: {
-            value: (fileName) => {
-                const text = texts.get(normalized(fileName));
-                return text === undefined
-                    ? base.getScriptSnapshot(fileName)
-                    : typescript_1.default.ScriptSnapshot.fromString(text);
-            },
-        },
-        getScriptVersion: {
-            value: (fileName) => texts.has(normalized(fileName))
-                ? `${base.getScriptVersion(fileName)}:rewritten:${generation}`
-                : base.getScriptVersion(fileName),
-        },
-        getProjectVersion: {
-            value: () => `${base.getProjectVersion?.() ?? ''}:${generation}`,
-        },
-    });
-    const service = typescript_1.default.createLanguageService(host, typescript_1.default.createDocumentRegistry());
-    let settledFor;
-    let current;
-    /**
-     * The rewrite for the project as it stands, recomputed only when the
-     * original project changed.
-     *
-     * @returns The rewrite.
-     */
-    const rewrite = () => {
-        const version = base.getProjectVersion?.() ??
-            base
-                .getScriptFileNames()
-                .map((fileName) => base.getScriptVersion(fileName))
-                .join('|');
-        if (current !== undefined && settledFor === version)
-            return current;
-        texts.clear();
-        generation++;
-        current = (0, fixpoint_1.rewriteToFixpoint)({
-            program: () => {
-                const program = service.getProgram();
-                if (program === undefined) {
-                    throw new Error('The shadow language service produced no program.');
-                }
-                return program;
-            },
-            update: (fileName, text) => {
-                texts.set(normalized(fileName), text);
-                generation++;
-            },
-        }, rewriter);
-        settledFor = version;
-        return current;
-    };
-    return { service, rewrite };
-};
-/**
- * Builds the `tsserver` plugin of a rewriter.
- *
- * @param rewriter What to rewrite.
- * @returns The plugin module, as `tsserver` loads it.
- */
-const createLanguageServicePlugin = (rewriter) => () => ({
-    create: (info) => {
-        const original = info.languageService;
-        const shadow = createShadow(info, rewriter);
-        /**
-         * The map of a file, when the rewrite touched it.
-         *
-         * @param fileName File being asked about.
-         * @returns Its map, or `undefined` when it reads as written.
-         */
-        const mapOf = (fileName) => shadow.rewrite().files.get(normalized(fileName));
-        const clean = withoutNamespace(rewriter.namespace);
-        /**
-         * Removes the rewrite's namespace from the parts of a display.
-         *
-         * @param parts Display parts, when there are any.
-         * @returns The same parts, cleaned.
-         */
-        const cleanParts = (parts) => 
-        // A display names the namespace as a part of its own, followed by
-        // a `.` part; both go, and any text naming it inline is cleaned.
-        parts
-            ?.filter((part, index) => !(part.text === rewriter.namespace &&
-            parts[index + 1]?.text === '.') &&
-            !(part.text === '.' &&
-                parts[index - 1]?.text === rewriter.namespace))
-            .map((part) => ({ ...part, text: clean(part.text) }));
-        /**
-         * Removes the rewrite's namespace from a diagnostic message, however
-         * deeply it is chained.
-         *
-         * @param message The message.
-         * @returns The message, cleaned.
-         */
-        const cleanMessage = (message) => typeof message === 'string'
-            ? clean(message)
-            : {
-                ...message,
-                messageText: clean(message.messageText),
-                next: message.next?.map((next) => cleanMessage(next)),
-            };
-        /**
-         * Maps the diagnostics of one file back to its original text.
-         *
-         * @param fileName File the diagnostics are about.
-         * @param diagnostics Diagnostics from the shadow.
-         * @returns The same diagnostics, in the original's positions.
-         */
-        const mapDiagnostics = (fileName, diagnostics) => {
-            const map = mapOf(fileName);
-            const sourceFile = original
-                .getProgram()
-                ?.getSourceFile(fileName);
-            return diagnostics.map((diagnostic) => {
-                const messageText = cleanMessage(diagnostic.messageText);
-                if (map === undefined || diagnostic.start === undefined) {
-                    return {
-                        ...diagnostic,
-                        messageText,
-                        file: sourceFile ?? diagnostic.file,
-                    };
-                }
-                const span = spanToOriginal({ start: diagnostic.start, length: diagnostic.length ?? 0 }, map);
-                return {
-                    ...diagnostic,
-                    messageText,
-                    file: sourceFile ?? diagnostic.file,
-                    start: span.start,
-                    length: span.length,
-                };
-            });
-        };
-        /**
-         * Maps a position into the shadow, asks it, and maps the answer back.
-         *
-         * @param fileName File asked about.
-         * @param position Position in the original text.
-         * @param ask The question, put to the shadow at the mapped position.
-         * @param fromShadow Maps what the shadow answered back.
-         * @returns The mapped answer.
-         */
-        const atPosition = (fileName, position, ask, fromShadow) => {
-            // A file the rewrite left alone still gets its answer mapped: a
-            // definition it points to may sit in a file that was rewritten.
-            const map = mapOf(fileName) ?? UNCHANGED;
-            return fromShadow(ask(shadow.service, map.toGenerated(position)), map);
-        };
-        /**
-         * Maps a definition back when it points into a rewritten file.
-         *
-         * @param definition A definition or a reference.
-         * @returns The same, in original positions.
-         */
-        const mapLocation = (definition) => {
-            const map = mapOf(definition.fileName);
-            return map === undefined
-                ? definition
-                : {
-                    ...definition,
-                    textSpan: spanToOriginal(definition.textSpan, map),
-                };
-        };
-        const proxy = Object.create(original);
-        // The rewrite is brought up to date before the shadow is asked, so the
-        // shadow answers about the rewritten text and not the one before it.
-        proxy.getSemanticDiagnostics = (fileName) => {
-            shadow.rewrite();
-            return mapDiagnostics(fileName, shadow.service.getSemanticDiagnostics(fileName));
-        };
-        proxy.getSuggestionDiagnostics = (fileName) => {
-            shadow.rewrite();
-            return mapDiagnostics(fileName, shadow.service.getSuggestionDiagnostics(fileName));
-        };
-        proxy.getQuickInfoAtPosition = (fileName, position, ...rest) => atPosition(fileName, position, (service, at) => service.getQuickInfoAtPosition(fileName, at, ...rest), (answer, map) => answer === undefined
-            ? answer
-            : {
-                ...answer,
-                textSpan: spanToOriginal(answer.textSpan, map),
-                displayParts: cleanParts(answer.displayParts),
-                documentation: cleanParts(answer.documentation),
-            });
-        proxy.getCompletionsAtPosition = (fileName, position, ...rest) => atPosition(fileName, position, (service, at) => service.getCompletionsAtPosition(fileName, at, ...rest), (answer, map) => answer === undefined
-            ? answer
-            : {
-                ...answer,
-                optionalReplacementSpan: answer.optionalReplacementSpan === undefined
-                    ? undefined
-                    : spanToOriginal(answer.optionalReplacementSpan, map),
-                entries: answer.entries.map((entry) => entry.replacementSpan === undefined
-                    ? entry
-                    : {
-                        ...entry,
-                        replacementSpan: spanToOriginal(entry.replacementSpan, map),
-                    }),
-            });
-        proxy.getCompletionEntryDetails = (fileName, position, ...rest) => atPosition(fileName, position, (service, at) => service.getCompletionEntryDetails(fileName, at, ...rest), (answer) => answer === undefined
-            ? answer
-            : {
-                ...answer,
-                displayParts: cleanParts(answer.displayParts) ?? [],
-            });
-        proxy.getSignatureHelpItems = (fileName, position, ...rest) => atPosition(fileName, position, (service, at) => service.getSignatureHelpItems(fileName, at, ...rest), (answer, map) => answer === undefined
-            ? answer
-            : {
-                ...answer,
-                applicableSpan: spanToOriginal(answer.applicableSpan, map),
-            });
-        proxy.getDefinitionAtPosition = (fileName, position, ...rest) => atPosition(fileName, position, (service, at) => service.getDefinitionAtPosition(fileName, at, ...rest), (answer) => answer?.map(mapLocation));
-        proxy.getDefinitionAndBoundSpan = (fileName, position) => atPosition(fileName, position, (service, at) => service.getDefinitionAndBoundSpan(fileName, at), (answer, map) => answer === undefined
-            ? answer
-            : {
-                textSpan: spanToOriginal(answer.textSpan, map),
-                definitions: answer.definitions?.map(mapLocation),
-            });
-        proxy.getTypeDefinitionAtPosition = (fileName, position) => atPosition(fileName, position, (service, at) => service.getTypeDefinitionAtPosition(fileName, at), (answer) => answer?.map(mapLocation));
-        return proxy;
-    },
-});
-exports.createLanguageServicePlugin = createLanguageServicePlugin;

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

@@ -1,44 +0,0 @@
-import typescript from 'typescript';
-import { type ExpressionRewriter } from '../file/index.js';
-import { type ProgramRewrite } from '../fixpoint/index.js';
-/**
- * The `tsc` integration of a rewrite that has to happen before type checking.
- *
- * `ts-patch` offers two kinds of plugin. The ordinary one, a `before`
- * transformer, runs on a program that has already been type checked, which is
- * too late: `decimal * decimal` has been reported as an error by then. The other
- * — `"transformProgram": true` in the tsconfig entry — is handed the program as
- * it is created and returns the one `tsc` goes on to check and emit. That is
- * where this runs: it rewrites the program to a fixed point and returns the
- * rewritten one, so what gets checked is what the rewrite produced.
- *
- * ```json
- * { "plugins": [{ "transform": "@fulcro/types/transformer", "transformProgram": true }] }
- * ```
- */
-/** The shape `ts-patch` expects from a program transformer. */
-export type ProgramTransformer = (program: typescript.Program, host?: typescript.CompilerHost, config?: unknown, extras?: unknown) => typescript.Program;
-/**
- * Rewrites an existing program, returning the rewritten program with what the
- * rewrite did.
- *
- * @param program Program to rewrite.
- * @param host Host it was created with; a default one when not given.
- * @param rewriter What to rewrite.
- * @returns The rewritten program, and the rewrite.
- */
-export declare const rewriteProgram: (program: typescript.Program, host: typescript.CompilerHost | undefined, rewriter: ExpressionRewriter) => {
-    readonly program: typescript.Program;
-    readonly rewrite: ProgramRewrite;
-};
-/**
- * Builds the program transformer of a rewriter.
- *
- * Guarded against itself: the new program is made with `createProgram`, which
- * `ts-patch` has patched to run program transformers, so without the guard the
- * transformer would be invoked on its own output, recursively.
- *
- * @param rewriter What to rewrite.
- * @returns The program transformer, as `ts-patch` expects it.
- */
-export declare const createProgramTransformer: (rewriter: ExpressionRewriter) => ProgramTransformer;

package/dist/rewrite/programTransformer/index.js

@@ -1,109 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createProgramTransformer = exports.rewriteProgram = void 0;
-const typescript_1 = __importDefault(require("typescript"));
-const fixpoint_1 = require("../fixpoint/index.js");
-/**
- * Serves the rewritten texts in place of the files on disk, and parses each
- * once per text.
- *
- * @param base Host the program was created with.
- * @param texts Rewritten texts by file name.
- * @param languageVersion Target the files are parsed for.
- * @param seed Program whose files are reused as they are.
- * @returns A host reading through the rewrite.
- */
-const overlayHost = (base, texts, languageVersion, seed) => {
-    const parsed = new Map();
-    // Every file the rewrite did not touch is handed back as the same object on
-    // every pass. `createProgram` reuses an old program's file only when the
-    // host returns the identical object, so a host that parsed the standard
-    // library afresh each time would make every pass re-check it from nothing.
-    const unchanged = new Map(seed.getSourceFiles().map((file) => [file.fileName, file]));
-    return {
-        ...base,
-        getSourceFile: (fileName, options, onError, shouldCreate) => {
-            const text = texts.get(fileName);
-            if (text === undefined) {
-                if (!unchanged.has(fileName)) {
-                    unchanged.set(fileName, base.getSourceFile(fileName, options, onError, shouldCreate));
-                }
-                return unchanged.get(fileName);
-            }
-            const cached = parsed.get(fileName);
-            if (cached !== undefined && cached.text === text)
-                return cached;
-            const sourceFile = typescript_1.default.createSourceFile(fileName, text, typeof options === 'object' ? options : languageVersion, true);
-            parsed.set(fileName, sourceFile);
-            return sourceFile;
-        },
-        readFile: (fileName) => texts.get(fileName) ?? base.readFile(fileName),
-        fileExists: (fileName) => texts.has(fileName) || base.fileExists(fileName),
-    };
-};
-/**
- * Rewrites an existing program, returning the rewritten program with what the
- * rewrite did.
- *
- * @param program Program to rewrite.
- * @param host Host it was created with; a default one when not given.
- * @param rewriter What to rewrite.
- * @returns The rewritten program, and the rewrite.
- */
-const rewriteProgram = (program, host, rewriter) => {
-    const options = program.getCompilerOptions();
-    const base = host ?? typescript_1.default.createCompilerHost(options, true);
-    const texts = new Map();
-    const overlay = overlayHost(base, texts, options.target ?? typescript_1.default.ScriptTarget.ES2022, program);
-    let current = program;
-    let stale = false;
-    const rewrite = (0, fixpoint_1.rewriteToFixpoint)({
-        program: () => {
-            if (stale) {
-                current = typescript_1.default.createProgram({
-                    rootNames: program.getRootFileNames(),
-                    options,
-                    host: overlay,
-                    oldProgram: current,
-                    projectReferences: program.getProjectReferences(),
-                });
-                stale = false;
-            }
-            return current;
-        },
-        update: (fileName, text) => {
-            texts.set(fileName, text);
-            stale = true;
-        },
-    }, rewriter);
-    return { program: current, rewrite };
-};
-exports.rewriteProgram = rewriteProgram;
-/**
- * Builds the program transformer of a rewriter.
- *
- * Guarded against itself: the new program is made with `createProgram`, which
- * `ts-patch` has patched to run program transformers, so without the guard the
- * transformer would be invoked on its own output, recursively.
- *
- * @param rewriter What to rewrite.
- * @returns The program transformer, as `ts-patch` expects it.
- */
-const createProgramTransformer = (rewriter) => {
-    let running = false;
-    return (program, host) => {
-        if (running)
-            return program;
-        running = true;
-        try {
-            return (0, exports.rewriteProgram)(program, host, rewriter).program;
-        }
-        finally {
-            running = false;
-        }
-    };
-};
-exports.createProgramTransformer = createProgramTransformer;

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

@@ -1,64 +0,0 @@
-/**
- * Text produced by rewriting a source file, with the map back to the original.
- *
- * A rewrite that happens before type checking changes the text the checker,
- * the emitter and the editor all read, and every one of them reports positions
- * in it. For those positions to mean anything to the person who wrote the
- * original, the rewrite keeps a record of where each piece of its output came
- * from — the same idea as a source map, kept as offsets rather than lines,
- * because the language service speaks in offsets.
- *
- * The output is made of two kinds of piece. A **copy** is original text moved
- * verbatim, and maps offset for offset. A **region** is the output of one
- * rewritten node; any position inside it that is not also inside a copy — the
- * synthesized `T.add(` around two operands — maps to the start of the node it
- * replaced, which is where an error about it belongs.
- */
-/** A rewritten text and the two directions of its position map. */
-export interface RewrittenText {
-    /** The rewritten text. */
-    readonly text: string;
-    /**
-     * Maps an offset in the rewritten text to the original.
-     *
-     * @param generated Offset in {@link RewrittenText.text}.
-     * @returns The offset in the original text it came from.
-     */
-    readonly toOriginal: (generated: number) => number;
-    /**
-     * Maps an offset in the original text to the rewritten one.
-     *
-     * @param original Offset in the original text.
-     * @returns The offset in {@link RewrittenText.text} it went to.
-     */
-    readonly toGenerated: (original: number) => number;
-}
-/** Accumulates the output of a rewrite and its map. */
-export interface TextBuilder {
-    /** Copies a span of the original text verbatim. */
-    readonly copy: (start: number, end: number) => void;
-    /** Writes synthesized text, which maps to the enclosing region. */
-    readonly write: (text: string) => void;
-    /** Opens the region of a rewritten node; returns the handle to close it. */
-    readonly open: (originalStart: number, originalEnd: number) => () => void;
-    /** Whether any region was opened, which is whether anything was rewritten. */
-    readonly rewrote: () => boolean;
-    /** Finishes the text. */
-    readonly build: () => RewrittenText;
-}
-/**
- * Starts the output of a rewrite over an original text.
- *
- * @param original The text being rewritten.
- * @returns The builder.
- */
-export declare const createTextBuilder: (original: string) => TextBuilder;
-/**
- * Chains two rewrites of the same file, the second applied to the output of the
- * first, into one map from the last text back to the original.
- *
- * @param first The earlier rewrite.
- * @param second The later one, over the earlier one's text.
- * @returns The combined rewrite.
- */
-export declare const composeRewrites: (first: RewrittenText, second: RewrittenText) => RewrittenText;