@zmdb/compiler 1.0.0-beta.1

package/dist/codegen/witness.js

@@ -0,0 +1,690 @@
+// The three files project compilation writes beside a source file, as text.
+// Generated banners name the compiler package so checked-in artifacts identify their
+// current owner without implying that the retired executable still exists.
+//
+// Nothing here runs the compiler or the emitter. It is the text half of project compilation:
+// given the entries `scan.ts` found, produce the witness module, and — given the transformer's
+// output for that witness — produce the JavaScript and declarations that go with it. Keeping
+// it pure is what makes it testable without a `tsgo` process.
+//
+// ## Why three files
+//
+// The rewrite is destructive. After a run the source says `zmdbIsUser(data)` and the
+// `is<User>(data)` it came from is gone, so the type argument — the only input the whole
+// pipeline has — would be gone with it. The **witness** keeps it, in a form the consumer's
+// own `tsc` checks: a wrapper per entry, written against the runtime API. That makes a
+// renamed or deleted `User` a build error in a generated file, rather than a compiled
+// validator that quietly keeps describing a type nobody declares any more.
+//
+// The witness is also the transform input, and its output cannot be the artifact: the
+// emitted helpers are untyped JavaScript (`function _zmdbFreeze(_v)`), which under
+// `noImplicitAny` is an error per parameter. So the artifact is a **`.js`** — the emitter's
+// output needs no annotations because nothing typechecks it — plus a **`.d.ts`** carrying
+// the signatures. That split pays for itself twice over: there is not one cast anywhere in
+// the generated code, and `schemaOf<T>()`'s phantom (`TaggedSchema<T>`'s `unique symbol`
+// slot, which no object literal can satisfy) is *declared* in the `.d.ts` rather than
+// asserted into existence.
+//
+// ## How the JavaScript is extracted
+//
+// By sentinel comments, and only because this module wrote every line around them. The
+// transformer replaces call spans and prepends its prelude; it never moves a statement and
+// never touches a comment. So the text between `/*zmdb:begin:NAME*/` and
+// `/*zmdb:end:NAME*/` is the wrapper with its call inlined, and it still starts with the
+// exact signature line this module generated — which is what makes swapping that line for
+// its JavaScript form a string operation rather than a parse.
+import { SyntaxKind } from 'typescript/unstable/ast';
+import { isIdentifier, isImportDeclaration, isNamedImports, isNamespaceImport, isPropertyAccessExpression, isStringLiteral, } from 'typescript/unstable/ast/is';
+import { Rewriter } from '../transform/index.js';
+/** Wraps the header and the import block: everything the `.js` does not want. */
+const IMPORTS_OPEN = '/*zmdb:imports*/';
+const IMPORTS_CLOSE = '/*zmdb:/imports*/';
+function begin(name) {
+    return `/*zmdb:begin:${name}*/`;
+}
+function end(name) {
+    return `/*zmdb:end:${name}*/`;
+}
+/** The type each callee's signature needs beyond the type argument itself. */
+const SUPPORT_TYPES = {
+    validate: ['ValidateResult'],
+    validateShallow: ['ValidateResult'],
+    toJsonSchema: ['JsonSchemaObject'],
+    schemaOf: ['TaggedSchema'],
+    toolFor: ['ToolOptions', 'ToolProvider', 'ToolSpecFor'],
+    loadGrpcService: ['GrpcLoadedService'],
+};
+const TS_EXTENSIONS = [
+    // source extension, runtime extension, declaration extension
+    ['.mts', '.mjs', '.d.mts'],
+    ['.cts', '.cjs', '.d.cts'],
+    ['.tsx', '.js', '.d.ts'],
+    ['.ts', '.js', '.d.ts'],
+];
+/**
+ * Where the three files go for one source file.
+ *
+ * Beside the source, one set per source file, which is a deliberate departure from a single
+ * per-project module. Two things fall out of it and both are worth more than the tidiness:
+ * the witness's relative imports are the source's own relative imports unchanged (no path
+ * arithmetic, and none of the ways that gets it wrong), and two files that both write
+ * `is<Row>` cannot collide over the export name `zmdbIsRow`.
+ *
+ * The runtime extension follows the source's, so a `.mts` file gets a `.mjs` — the module
+ * kind of the generated file has to match the module kind of the file importing it.
+ */
+export function artifactPaths(sourcePath) {
+    for (const [source, runtime, declaration] of TS_EXTENSIONS) {
+        if (!sourcePath.endsWith(source))
+            continue;
+        const stem = sourcePath.slice(0, -source.length);
+        return {
+            witness: `${stem}.zmdb.witness${source === '.tsx' ? '.ts' : source}`,
+            js: `${stem}.zmdb.generated${runtime}`,
+            dts: `${stem}.zmdb.generated${declaration}`,
+            specifier: `./${base(stem)}.zmdb.generated${runtime}`,
+        };
+    }
+    return {
+        witness: `${sourcePath}.zmdb.witness.ts`,
+        js: `${sourcePath}.zmdb.generated.js`,
+        dts: `${sourcePath}.zmdb.generated.d.ts`,
+        specifier: `./${base(sourcePath)}.zmdb.generated.js`,
+    };
+}
+function base(path) {
+    const cut = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'));
+    return cut === -1 ? path : path.slice(cut + 1);
+}
+/** Whether a path is something a previous run wrote. The scan must not recurse into these. */
+export function isGeneratedPath(path) {
+    return /\.zmdb\.(?:witness|generated)\.[cm]?[jt]sx?$|\.zmdb\.generated\.d\.[cm]?ts$/.test(path);
+}
+/**
+ * The wrapper's shape for one entry.
+ *
+ * Every callee becomes a *function*, including the two — `toJsonSchema<T>()` and
+ * `schemaOf<T>()` — that take no argument and could have been a `const`. Not for efficiency:
+ * the emitter hoists both to one deeply frozen module-level literal and the wrapper returns a
+ * reference to it, so a `const` would compile to the same bytes. It is so that the generated
+ * module has the same shape as the call it replaced. `document()` was a call in the source and
+ * stays one, which is what keeps the rewrite a rename rather than a refactor.
+ */
+function signature(entry) {
+    const type = entry.typeText;
+    const typeArguments = entry.depthText === undefined ? type : `${type}, ${entry.depthText}`;
+    const captured = entry.argumentsText?.join(', ');
+    switch (entry.callee) {
+        case 'is':
+        case 'equals':
+            return {
+                parameters: 'value: unknown',
+                returns: `value is ${type}`,
+                plain: 'value',
+                call: `${entry.callee}<${type}>(value)`,
+            };
+        case 'isShallow':
+            return {
+                parameters: 'value: unknown',
+                returns: `value is ${type}`,
+                plain: 'value',
+                call: `isShallow<${typeArguments}>(value)`,
+            };
+        case 'assert':
+        case 'assertEquals':
+            return { parameters: 'value: unknown', returns: type, plain: 'value', call: `${entry.callee}<${type}>(value)` };
+        case 'assertShallow':
+            return {
+                parameters: 'value: unknown',
+                returns: type,
+                plain: 'value',
+                call: `assertShallow<${typeArguments}>(value)`,
+            };
+        case 'validate':
+            return {
+                parameters: 'value: unknown',
+                returns: `ValidateResult<${type}>`,
+                plain: 'value',
+                call: `validate<${type}>(value)`,
+            };
+        case 'validateShallow':
+            return {
+                parameters: 'value: unknown',
+                returns: `ValidateResult<${type}>`,
+                plain: 'value',
+                call: `validateShallow<${typeArguments}>(value)`,
+            };
+        case 'random':
+            return { parameters: '', returns: type, plain: '', call: `random<${type}>()` };
+        case 'toJsonSchema':
+            return { parameters: '', returns: 'JsonSchemaObject', plain: '', call: `toJsonSchema<${type}>()` };
+        case 'schemaOf':
+            return { parameters: '', returns: `TaggedSchema<${type}>`, plain: '', call: `schemaOf<${type}>()` };
+        case 'toolFor':
+            return {
+                typeParameters: '<P extends ToolProvider>',
+                parameters: 'provider: P, name: string, opts?: ToolOptions',
+                returns: 'ToolSpecFor[P]',
+                plain: 'provider, name, opts',
+                call: `toolFor<${type}, P>(provider, name, opts)`,
+            };
+        case 'grpcDescriptor':
+            return {
+                parameters: '',
+                returns: 'string',
+                plain: '',
+                call: `grpcDescriptor<${type}>(${captured ?? ''})`,
+            };
+        case 'loadGrpcService':
+            return {
+                parameters: '',
+                returns: `GrpcLoadedService<${type}>`,
+                plain: '',
+                call: `loadGrpcService<${type}>(${captured ?? ''})`,
+            };
+        case 'protoDescriptor':
+            return { parameters: '', returns: 'string', plain: '', call: `protoDescriptor<${type}>()` };
+        case 'protoDecode':
+            return {
+                parameters: 'bytes: Uint8Array',
+                returns: type,
+                plain: 'bytes',
+                call: `protoDecode<${type}>(bytes)`,
+            };
+        case 'protoEncode':
+            return {
+                parameters: `value: ${type}`,
+                returns: 'Uint8Array',
+                plain: 'value',
+                call: `protoEncode<${type}>(value)`,
+            };
+        default:
+            // `CALLEES` is the only source of `callee`, and every member of it is above. A new one
+            // added there and not here would otherwise generate a wrapper that calls nothing.
+            throw new Error(`@zmdb/compiler has no wrapper for \`${entry.callee}<T>()\``);
+    }
+}
+/** `export function NAME(value: unknown): value is User {` — the line the `.js` swaps out. */
+function tsOpening(entry) {
+    const { parameters, returns, typeParameters = '' } = signature(entry);
+    return `export function ${entry.name}${typeParameters}(${parameters}): ${returns} {`;
+}
+// -----------------------------------------------------------------------------
+// Imports
+// -----------------------------------------------------------------------------
+function typeImportLines(imports, style) {
+    const named = new Map();
+    const lines = [];
+    for (const entry of imports) {
+        if (entry.kind === 'default') {
+            lines.push(`import type ${entry.local} from ${quote(entry.specifier, style)};`);
+        }
+        else if (entry.kind === 'namespace') {
+            lines.push(`import type * as ${entry.local} from ${quote(entry.specifier, style)};`);
+        }
+        else {
+            const clause = entry.original === entry.local ? entry.local : `${entry.original} as ${entry.local}`;
+            const group = named.get(entry.specifier);
+            if (group)
+                group.push(clause);
+            else
+                named.set(entry.specifier, [clause]);
+        }
+    }
+    for (const [specifier, clauses] of named) {
+        lines.push(`import type { ${clauses.toSorted().join(', ')} } from ${quote(specifier, style)};`);
+    }
+    return lines.toSorted();
+}
+/**
+ * The runtime API the witness calls, and the types its signatures mention.
+ *
+ * Values come from the specifier the *source* used, never from an implementation package: a
+ * project that installed only `zmdb` has no direct `@zmdb/validator` dependency. Support
+ * types normally share that entry. The one deliberate split is root `schemaOf`: the curated
+ * root keeps the callable, while `TaggedSchema` belongs to the complete `zmdb/schema` concern.
+ */
+function calleeImportLines(entries, sources, style) {
+    const values = new Map();
+    const types = new Map();
+    const into = (map, specifier, name) => {
+        const group = map.get(specifier);
+        if (group)
+            group.add(name);
+        else
+            map.set(specifier, new Set([name]));
+    };
+    for (const entry of entries) {
+        const specifier = sources.get(entry.callee) ?? '@zmdb/validator';
+        into(values, specifier, entry.callee);
+        const support = SUPPORT_TYPES[entry.callee];
+        if (support) {
+            const supportSpecifier = entry.callee === 'schemaOf' && specifier === 'zmdb' ? 'zmdb/schema' : specifier;
+            for (const name of support)
+                into(types, supportSpecifier, name);
+        }
+    }
+    const lines = [];
+    for (const [specifier, names] of values) {
+        lines.push(`import { ${[...names].toSorted().join(', ')} } from ${quote(specifier, style)};`);
+    }
+    for (const [specifier, names] of types) {
+        lines.push(`import type { ${[...names].toSorted().join(', ')} } from ${quote(specifier, style)};`);
+    }
+    return lines.toSorted();
+}
+/** The support-type imports on their own, for the `.d.ts`, which calls nothing. */
+function supportTypeLines(entries, sources, style) {
+    return calleeImportLines(entries, sources, style).filter(line => line.startsWith('import type '));
+}
+/**
+ * A module specifier, quoted the way the file it is going into quotes them.
+ *
+ * Cosmetic in isolation, load-bearing in aggregate: a consumer runs a formatter over its
+ * tree, and a generated file that disagrees with it is a diff on every `--check`.
+ */
+function quote(specifier, style) {
+    if (style !== "'")
+        return JSON.stringify(specifier);
+    return `'${specifier.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`;
+}
+/**
+ * Which quote the source file uses for its own imports. Single unless it says otherwise —
+ * the majority style, and the one a file with no imports at all is most likely to want.
+ */
+export function quoteStyle(sourceFile) {
+    for (const node of sourceFile.statements) {
+        if (!isImportDeclaration(node))
+            continue;
+        const specifier = node.moduleSpecifier;
+        if (!isStringLiteral(specifier))
+            continue;
+        const char = sourceFile.text[specifier.getStart()];
+        if (char === '"' || char === "'")
+            return char;
+    }
+    return "'";
+}
+export function witnessSource(input) {
+    const { sourceName, entries, typeImports, calleeSources, style } = input;
+    const parts = [
+        IMPORTS_OPEN,
+        `// Generated by @zmdb/compiler from ${sourceName}. Checked, not edited.`,
+        '//',
+        `// One wrapper per validation call ${sourceName} used to make, written against the runtime`,
+        '// API so that the compiler still sees each type argument. That is the point of the file: it',
+        '// is what the project compiler reads on the next run to regenerate the compiled module, and it is',
+        '// what turns a renamed or deleted type into a build error here instead of a validator that',
+        '// silently checks a shape nobody declares.',
+        '//',
+        '// Editing it by hand does nothing. An entry disappears when the source stops referring to',
+        "// its export name, so deleting a call in the source is how you delete a validator; there's",
+        '// no bookkeeping to keep in step.',
+    ];
+    const imports = [...typeImportLines(typeImports, style), ...calleeImportLines(entries, calleeSources, style)];
+    if (imports.length > 0)
+        parts.push('', ...imports);
+    parts.push(IMPORTS_CLOSE);
+    for (const entry of entries) {
+        const { call } = signature(entry);
+        parts.push('', begin(entry.name), tsOpening(entry), `  return ${call};`, '}', end(entry.name));
+    }
+    return `${parts.join('\n')}\n`;
+}
+/**
+ * The `.js` and the `.d.ts`, assembled from the transformed witness.
+ *
+ * Only the wrapper bodies come from the transform; every other line is regenerated here from
+ * the same `Entry` list the witness was built from. So the two files cannot disagree about a
+ * signature, and neither can drift from the witness.
+ */
+export function generatedModules(input) {
+    const { sourceName, entries, transformed } = input;
+    const header = (tail) => [
+        `// Generated by @zmdb/compiler from ${sourceName}. Do not edit.`,
+        '//',
+        `// The validators, compiled. Every check below was emitted from a type in ${sourceName}'s`,
+        `// witness module by \`@zmdb/compiler\`, so there is no schema to walk at runtime and`,
+        '// nothing to look up: the shape is the control flow.',
+        '//',
+        ...tail,
+    ].join('\n');
+    const jsHeader = header([
+        '// JavaScript rather than TypeScript on purpose — the emitted helpers are untyped, and a',
+        '// generated file that needed `any` to typecheck would be a worse trade than one that is',
+        '// simply not typechecked. The declarations live in the sidecar `.d.ts`.',
+        '//',
+        '// Formatters and linters should skip it. The emitter writes a check as one long expression',
+        '// because that is what it is; reformatting would leave the next compiler check',
+        '// permanently out of date against a file nothing was wrong with.',
+    ]);
+    const dtsHeader = header([
+        '// This half is the types: the signatures the compiler reads when the source imports the',
+        '// module next door. Nothing here is checked against the implementation, and nothing needs',
+        '// to be — the witness makes the same claims against the runtime API, and *that* is checked.',
+    ]);
+    const preludeEnd = firstMarker(transformed, entries);
+    let prelude = transformed.slice(0, preludeEnd);
+    const open = prelude.indexOf(IMPORTS_OPEN);
+    const close = prelude.indexOf(IMPORTS_CLOSE);
+    if (open !== -1 && close !== -1) {
+        // The header and the witness's own imports. Both are TypeScript-only by now: every call
+        // that needed the runtime API has been inlined, so the import would load a validator
+        // nobody calls, and the type imports are not syntax a `.js` file may contain.
+        prelude = prelude.slice(0, open) + prelude.slice(close + IMPORTS_CLOSE.length);
+    }
+    const bodies = entries.map(entry => javascriptFor(entry, transformed));
+    const declarations = entries.map(entry => {
+        const { parameters, returns, typeParameters = '' } = signature(entry);
+        return `export declare function ${entry.name}${typeParameters}(${parameters}): ${returns};`;
+    });
+    const dtsImports = [
+        ...typeImportLines(input.typeImports, input.style),
+        ...supportTypeLines(entries, input.calleeSources, input.style),
+    ];
+    return {
+        js: `${jsHeader}\n${join([prelude.trim(), ...bodies])}\n`,
+        dts: `${dtsHeader}\n${join([dtsImports.join('\n'), ...declarations])}\n`,
+    };
+}
+function join(blocks) {
+    return blocks.filter(block => block.length > 0).join('\n\n');
+}
+/** Where the wrappers start, which is where the prelude ends. */
+function firstMarker(transformed, entries) {
+    let earliest = transformed.length;
+    for (const entry of entries) {
+        const at = transformed.indexOf(begin(entry.name));
+        if (at !== -1 && at < earliest)
+            earliest = at;
+    }
+    return earliest;
+}
+/**
+ * One wrapper, as JavaScript.
+ *
+ * The sentinel comments bound it and the signature line is known verbatim, so this is two
+ * string operations. A missing marker means the transformer moved or dropped a statement,
+ * which it has no path to do — so it throws rather than writing a module with a hole in it.
+ */
+function javascriptFor(entry, transformed) {
+    const from = transformed.indexOf(begin(entry.name));
+    const to = transformed.indexOf(end(entry.name));
+    if (from === -1 || to === -1 || to < from) {
+        throw new Error(`the transformed witness lost the wrapper for ${entry.name}`);
+    }
+    const chunk = transformed.slice(from + begin(entry.name).length, to).trim();
+    const opening = tsOpening(entry);
+    if (!chunk.startsWith(opening)) {
+        throw new Error(`the transformed witness rewrote the signature of ${entry.name}`);
+    }
+    const { plain } = signature(entry);
+    return `export function ${entry.name}(${plain}) {${chunk.slice(opening.length)}`;
+}
+/**
+ * `is<User>(data)` → `zmdbIsUser(data)`, plus the import that makes it resolve.
+ *
+ * The whole call is replaced rather than just its callee, because the type argument has to
+ * go with it and `is<User>` is one span in the middle of another. Arguments are read through
+ * the `Rewriter`, so `assert<A>(is<B>(x))` picks up the inner rewrite instead of carrying a
+ * stale copy of it.
+ */
+export function rewriteSource(input) {
+    const { sourceFile, code, sites, specifier, entries, calleeSources, style } = input;
+    const rewriter = new Rewriter(code);
+    // Back to front, for the same reason the transformer does it: an earlier offset is only
+    // valid while everything after it is untouched.
+    for (const { site, entry } of sites.toReversed()) {
+        const args = site.node.arguments;
+        const first = args[0];
+        const last = args[args.length - 1];
+        const inner = entry.argumentsText === undefined && first && last ? rewriter.slice(first.getStart(), last.end) : '';
+        rewriter.replace(site.node.getStart(), site.node.end, `${entry.name}(${inner})`);
+    }
+    const names = entries.map(entry => entry.name);
+    const statement = names.length === 0 ? '' : `import { ${names.join(', ')} } from ${quote(specifier, style)};`;
+    // The import edits come after the call edits and are all at lower offsets, so no applied
+    // edit lies inside one of their spans and the `Rewriter`'s arithmetic is unaffected.
+    const owned = new Set(calleeSources.values());
+    const compiled = new Set(sites.map(({ site }) => site.binding));
+    const context = {
+        specifier,
+        statement,
+        names,
+        owned,
+        compiled,
+        style,
+        live: liveIdentifiers(sourceFile, sites),
+    };
+    for (const edit of importEdits(sourceFile, context).toSorted((a, b) => b.start - a.start)) {
+        rewriter.replace(edit.start, edit.end, edit.text);
+    }
+    return rewriter.text;
+}
+/**
+ * Every name the file still uses after the rewrite, as names rather than as text.
+ *
+ * This decides whether a callee's import is now dead, and it has to be an AST walk. Searching
+ * the text for `is` finds it in `import { is } from 'zmdb'`, which is the statement being
+ * judged, and finds it in a comment — this file's own fixture said "the type argument *is* the
+ * input" and kept a compiled-away import alive on the strength of it. A regex has no way to
+ * know which of those is a reference and the parser already does.
+ *
+ * Three things are therefore skipped: import declarations, because an import is not a use; the
+ * head of each compiled call, because `is<User>` is what is going away, while its *arguments*
+ * are walked, so an `assert` passed as a value inside one keeps its import; and the property
+ * half of `a.b`, because `payload.is` names a property, not the imported function.
+ */
+function liveIdentifiers(sourceFile, sites) {
+    const compiled = new Map();
+    for (const { site } of sites)
+        compiled.set(site.node, site.node.arguments);
+    const names = new Set();
+    const walk = (node) => {
+        if (isImportDeclaration(node))
+            return;
+        const args = compiled.get(node);
+        if (args) {
+            for (const argument of args)
+                walk(argument);
+            return;
+        }
+        if (isIdentifier(node)) {
+            names.add(node.text);
+            return;
+        }
+        if (isPropertyAccessExpression(node)) {
+            walk(node.expression);
+            return;
+        }
+        node.forEachChild(walk);
+    };
+    sourceFile.forEachChild(walk);
+    return names;
+}
+/**
+ * How far a deleted statement's deletion should reach: through the end of its line, and
+ * through the blank lines after it when they are no longer separating anything.
+ *
+ * The line itself is not optional — leaving the newline behind puts a blank line where the
+ * statement was, and no later run would remove it, so the file would be permanently one line
+ * emptier than the formatter wants it. The blank lines after are the same problem one level
+ * up: deleting the only import above a blank line leaves the file starting with that blank
+ * line, so a paragraph break that now divides nothing goes with the paragraph.
+ */
+function throughLine(text, start, stop) {
+    let at = skipSpaces(text, stop);
+    if (at >= text.length || text[at] !== '\n')
+        return stop;
+    at += 1;
+    if (!blankAbove(text, start))
+        return at;
+    while (at < text.length && text[skipSpaces(text, at)] === '\n')
+        at = skipSpaces(text, at) + 1;
+    return at;
+}
+function skipSpaces(text, from) {
+    let at = from;
+    while (at < text.length && (text[at] === ' ' || text[at] === '\t' || text[at] === '\r'))
+        at += 1;
+    return at;
+}
+/** Whether `start`'s line is the first in the file or has a blank line above it. */
+function blankAbove(text, start) {
+    let at = start - 1;
+    while (at >= 0 && (text[at] === ' ' || text[at] === '\t' || text[at] === '\r'))
+        at -= 1;
+    if (at < 0)
+        return true;
+    if (text[at] !== '\n')
+        return false;
+    at -= 1;
+    while (at >= 0 && (text[at] === ' ' || text[at] === '\t' || text[at] === '\r'))
+        at -= 1;
+    return at < 0 || text[at] === '\n';
+}
+/** The local names a `{ … }` import clause binds. Aliases are not something codegen writes. */
+function importedNames(bindings) {
+    if (!bindings || !isNamedImports(bindings))
+        return [];
+    return bindings.elements.filter(element => isIdentifier(element.name)).map(element => element.name.text);
+}
+/** Whether an import already binds exactly `wanted`, in any order. */
+function satisfies(found, wanted) {
+    return found.length === wanted.length && wanted.every(name => found.includes(name));
+}
+/**
+ * Add the generated import, and take away the ones the rewrite just orphaned.
+ *
+ * The second half is not tidiness: `import { is } from 'zmdb'` with no `is` left in the file
+ * is an error under `noUnusedLocals`, so a codegen that left it behind would break the build
+ * it was supposed to speed up. Only bindings this rewrite could have orphaned are considered
+ * — the callee names, and a namespace or default binding of a module a callee came
+ * from — and only when the name is referenced nowhere in what is left.
+ */
+function importEdits(sourceFile, context) {
+    const { specifier, statement, names, owned, compiled, style, live } = context;
+    const edits = [];
+    let existing;
+    // Where the generated import can go, and where it cannot. The new statement goes after the
+    // last import that is *still there* — anchoring it to one this pass is deleting would put an
+    // insertion inside a deleted span, and the deletion would eat it.
+    const surviving = [];
+    const removals = [];
+    for (const node of sourceFile.statements) {
+        if (!isImportDeclaration(node))
+            continue;
+        surviving.push(node.end);
+        /** Delete the statement whole: it exists only to import something now compiled away. */
+        const remove = () => {
+            surviving.pop();
+            const through = throughLine(sourceFile.text, node.getStart(), node.end);
+            removals.push({ at: edits.length, start: node.getStart(), nodeEnd: node.end, end: through });
+            edits.push({ start: node.getStart(), end: through, text: '' });
+        };
+        const moduleSpecifier = node.moduleSpecifier;
+        if (!isStringLiteral(moduleSpecifier))
+            continue;
+        if (moduleSpecifier.text === specifier) {
+            // A previous run's import. Its *names* are what get compared, never its text — see
+            // `satisfies` below.
+            existing = {
+                start: node.getStart(),
+                end: node.end,
+                withLine: throughLine(sourceFile.text, node.getStart(), node.end),
+                names: importedNames(node.importClause?.namedBindings),
+            };
+            continue;
+        }
+        const clause = node.importClause;
+        if (!clause)
+            continue;
+        const dead = (name) => !live.has(name);
+        const bindings = clause.namedBindings;
+        const namespaceName = bindings && isNamespaceImport(bindings) && isIdentifier(bindings.name) ? bindings.name.text : undefined;
+        const defaultName = clause.name && isIdentifier(clause.name) ? clause.name.text : undefined;
+        if (owned.has(moduleSpecifier.text)) {
+            const single = namespaceName ?? defaultName;
+            if (single !== undefined && (!bindings || !isNamedImports(bindings)) && dead(single)) {
+                remove();
+                continue;
+            }
+        }
+        if (!bindings || !isNamedImports(bindings))
+            continue;
+        const keep = [];
+        let dropped = false;
+        for (const element of bindings.elements) {
+            if (!isIdentifier(element.name))
+                continue;
+            const local = element.name.text;
+            if (compiled.has(local) && dead(local)) {
+                dropped = true;
+                continue;
+            }
+            const original = element.propertyName && isIdentifier(element.propertyName) ? element.propertyName.text : local;
+            // `import { type A, B }` — the per-specifier modifier has to survive the rebuild, or
+            // a type-only binding becomes a value import of something that does not exist at runtime.
+            const modifier = element.isTypeOnly ? 'type ' : '';
+            keep.push(`${modifier}${original === local ? local : `${original} as ${local}`}`);
+        }
+        if (!dropped)
+            continue;
+        if (keep.length === 0 && defaultName === undefined) {
+            remove();
+        }
+        else {
+            const prefix = defaultName === undefined ? '' : `${defaultName}, `;
+            const kind = clause.phaseModifier === SyntaxKind.TypeKeyword ? 'import type' : 'import';
+            edits.push({
+                start: node.getStart(),
+                end: node.end,
+                text: keep.length === 0
+                    ? `${kind} ${defaultName ?? ''} from ${quote(moduleSpecifier.text, style)};`
+                    : `${kind} ${prefix}{ ${keep.join(', ')} } from ${quote(moduleSpecifier.text, style)};`,
+            });
+        }
+    }
+    if (statement.length === 0) {
+        // Nothing left to import. An existing import from a previous run is now dead, and
+        // leaving it would keep a generated module alive that nothing references.
+        if (existing)
+            edits.push({ start: existing.start, end: existing.withLine, text: '' });
+        return edits;
+    }
+    if (existing) {
+        // Only when it says something different. The one thing this statement has to get right is
+        // which names come from the generated module, and a consumer's formatter owns everything
+        // else about it: `printWidth` wraps a seven-name import across eight lines, `sortImports`
+        // reorders the names, and neither is a reason to rewrite the file. Comparing text here
+        // would put compiler check mode and `fmt --check` in a loop that neither can win.
+        if (!satisfies(existing.names, names))
+            edits.push({ start: existing.start, end: existing.end, text: statement });
+        return edits;
+    }
+    const anchor = surviving.at(-1);
+    if (anchor !== undefined) {
+        edits.push({ start: anchor, end: anchor, text: `\n${statement}` });
+        return edits;
+    }
+    const first = removals.toSorted((a, b) => a.start - b.start)[0];
+    if (first) {
+        // Every import the file had was orphaned by the rewrite — the common case for a module whose
+        // only import was the validator. So the generated one takes the first one's place *as* that
+        // deletion: an insertion at the same offset would be two edits claiming one byte, with no
+        // rule saying which of them won. The trailing whitespace the deletion swallowed comes back
+        // with it, so the file keeps the paragraph break it had.
+        edits[first.at] = {
+            start: first.start,
+            end: first.end,
+            text: `${statement}${sourceFile.text.slice(first.nodeEnd, first.end)}`,
+        };
+        return edits;
+    }
+    // No imports at all. After the leading comment of the first statement rather than at
+    // offset zero, so a file's licence header stays at the top of it.
+    const at = sourceFile.statements[0]?.getStart() ?? 0;
+    edits.push({ start: at, end: at, text: `${statement}\n\n` });
+    return edits;
+}
+//# sourceMappingURL=witness.js.map