uql-codemod 0.48.2 → 0.49.0

package/dist/classOptions.js

@@ -0,0 +1,240 @@
+import ts from 'typescript';
+import { original } from './edits.js';
+import { memberKey } from './keyMaps.js';
+import { arrayElements, decoratorName, decoratorsOf, indentOf, indentUnit, lineStartOf, namedProperty, objectLiteral, } from './syntax.js';
+/** The class decorators `@Entity`'s options took over, each with the option its entries go under. */
+const FOLDED = { Index: 'indexes', Trigger: 'triggers', Filter: 'filters' };
+const isFolded = (name) => name !== undefined && Object.hasOwn(FOLDED, name);
+const slotEntries = (entries) => new Map([...entries].map(([option, { before, after }]) => [option, [...before, ...after]]));
+/**
+ * Folds `@Index`, `@Trigger` and `@Filter` into the class's `@Entity` options, `indexes`, `triggers` and `filters`.
+ * Triggers keep the order they register in, which is the order they run in: decorators apply bottom-up, so those
+ * below `@Entity` go ahead of its own and those above after them. Indexes and filters, whose order means nothing,
+ * follow `@Entity`'s own in the order written. A class with no `@Entity` becomes `@Entity({ abstract: true, ... })`.
+ */
+export function foldClassDecorators(node, ctx) {
+    const decorators = decoratorsOf(node);
+    const unit = indentUnit(node.getSourceFile());
+    const entity = decorators.find((decorator) => decoratorName(decorator) === 'Entity');
+    const at = entity ? decorators.indexOf(entity) : -1;
+    const folded = decorators.flatMap((decorator, index) => {
+        const name = decoratorName(decorator);
+        return isFolded(name) && ts.isCallExpression(decorator.expression)
+            ? [{ decorator, call: decorator.expression, name, index }]
+            : [];
+    });
+    if (!folded.length) {
+        return;
+    }
+    const call = entity && entityCall(entity, ctx);
+    const options = call && entityOptions(call, ctx);
+    if (call === null || options === null) {
+        return;
+    }
+    const triggers = folded.filter(({ name }) => name === 'Trigger');
+    const applied = (above) => triggers.filter(({ index }) => index < at === above).toReversed();
+    const before = applied(false);
+    const after = [...applied(true), ...folded.filter(({ name }) => name !== 'Trigger')];
+    const entries = new Map();
+    for (const [list, side] of [
+        [before, 'before'],
+        [after, 'after'],
+    ]) {
+        for (const { call, name, decorator } of list) {
+            const written = entriesOf(name, call, decorator, ctx);
+            if (!written) {
+                return;
+            }
+            const comments = commentTexts(decorator);
+            const slot = entries.get(FOLDED[name]) ?? { before: [], after: [] };
+            slot[side].push(...written.map((parts, index) => ({ parts, comments: index ? [] : comments })));
+            entries.set(FOLDED[name], slot);
+        }
+    }
+    for (const { decorator, name } of folded) {
+        ctx.edits.push(removedDecorator(decorator));
+        ctx.rewritten[name] += 1;
+    }
+    if (!call) {
+        const first = removedDecorator(folded[0].decorator);
+        const indent = indentOf(folded[0].decorator);
+        const text = ['@Entity({ abstract: true, ', ...optionParts(slotEntries(entries), indent, unit), ' })'];
+        const onItsLine = node.getSourceFile().text.slice(first.start, first.end).endsWith('\n');
+        ctx.edits.push({
+            start: first.start,
+            end: first.start,
+            text: onItsLine ? [indent, ...text, '\n'] : [...text, ' '],
+        });
+        ctx.imports.set('Entity', 'the abstract base its class decorators moved into');
+        return;
+    }
+    ctx.edits.push(...entityEdits(call, options, entries, unit));
+}
+/** `@Entity`'s call, or `null`, reported, where it is written uncalled and so takes no options. */
+function entityCall(entity, ctx) {
+    if (ts.isCallExpression(entity.expression)) {
+        return entity.expression;
+    }
+    ctx.report(entity, "call '@Entity()' to move '@Index', '@Trigger' and '@Filter' into its options");
+    return null;
+}
+/** `@Entity`'s options literal, `undefined` where it takes none, or `null`, reported, where it cannot be read. */
+function entityOptions(call, ctx) {
+    const [first] = call.arguments;
+    if (!first) {
+        return undefined;
+    }
+    const literal = objectLiteral(first);
+    if (!literal) {
+        ctx.report(call, "move '@Index', '@Trigger' and '@Filter' into '@Entity' options this cannot read");
+        return null;
+    }
+    return literal;
+}
+/** The entries one decorator registers, or nothing, reported, where it cannot say them as an option. */
+function entriesOf(name, call, decorator, ctx) {
+    const [first, second] = call.arguments;
+    if (name === 'Trigger') {
+        return call.arguments.map((trigger) => [original(trigger)]);
+    }
+    if (name === 'Index') {
+        if (!first) {
+            ctx.report(decorator, "move this '@Index' into '@Entity({ indexes })' by hand: it names no columns");
+            return undefined;
+        }
+        const props = objectLiteral(second);
+        const rest = props
+            ? props.properties.flatMap((prop) => [', ', original(prop)])
+            : second
+                ? [', ...', original(second)]
+                : [];
+        return [['{ columns: ', original(first), ...rest, ' }']];
+    }
+    if (!first || !ts.isStringLiteralLike(first) || !second) {
+        ctx.report(decorator, "move this '@Filter' into '@Entity({ filters })' by hand: its name is not a string");
+        return undefined;
+    }
+    return [[memberKey(first.text), ': ', original(second)]];
+}
+/** Each option's entries as comma-separated properties, a list holding a comment one entry a line. */
+function optionParts(entries, indent, unit) {
+    return [...entries].flatMap(([option, list], index) => [
+        ...(index ? [', '] : []),
+        ...bracketed(option, list, indent, unit),
+    ]);
+}
+function bracketed(option, list, indent, unit) {
+    const [open, close] = option === 'filters' ? ['{', '}'] : ['[', ']'];
+    if (list.length < 2 && !list.some(({ comments }) => comments.length)) {
+        const pad = option === 'filters' ? ' ' : '';
+        return [`${option}: ${open}${pad}`, ...joined(list, ', '), `${pad}${close}`];
+    }
+    const inner = `${indent}${unit}`;
+    return [`${option}: ${open}\n`, ...lines(list, inner), `${indent}${close}`];
+}
+function joined(list, separator) {
+    return list.flatMap(({ parts }, index) => (index ? [separator, ...parts] : [...parts]));
+}
+/** Each entry on its own line under `indent`, its comments on the lines above it. */
+function lines(list, indent) {
+    return list.flatMap(({ parts, comments }) => [
+        ...comments.flatMap((comment) => [indent, comment, '\n']),
+        indent,
+        ...parts,
+        ',\n',
+    ]);
+}
+/**
+ * The line comments directly above `decorator`, which say something of it: a run with no blank line before the
+ * decorator. A doc comment, or one a blank line parts from it, is the class's and stays where it is.
+ */
+function decoratorComments(decorator) {
+    const text = decorator.getSourceFile().text;
+    const ranges = ts.getLeadingCommentRanges(text, decorator.pos) ?? [];
+    const kept = [];
+    let next = decorator.getStart();
+    for (const range of ranges.toReversed()) {
+        const between = text.slice(range.end, next);
+        if (range.kind !== ts.SyntaxKind.SingleLineCommentTrivia || /\n\s*\n/.test(between))
+            break;
+        kept.unshift(range);
+        next = range.pos;
+    }
+    return kept;
+}
+/** A comment closing the decorator's line, which says something of it too. */
+function trailingComments(decorator) {
+    const text = decorator.getSourceFile().text;
+    return (ts.getTrailingCommentRanges(text, decorator.getEnd()) ?? []).filter(({ kind }) => kind === ts.SyntaxKind.SingleLineCommentTrivia);
+}
+/** The comments the decorator's entry carries: those above it, then the one closing its line. */
+function commentTexts(decorator) {
+    const text = decorator.getSourceFile().text;
+    return [...decoratorComments(decorator), ...trailingComments(decorator)].map(({ pos, end }) => text.slice(pos, end));
+}
+/** The edits writing `entries` into `@Entity`'s options, each option's own list merged where it states one. */
+function entityEdits(call, options, entries, unit) {
+    const indent = indentOf(call);
+    if (!options) {
+        const at = call.getEnd() - 1;
+        return [{ start: at, end: at, text: ['{ ', ...optionParts(slotEntries(entries), indent, unit), ' }'] }];
+    }
+    const edits = [];
+    const added = new Map();
+    for (const [option, slot] of entries) {
+        const stated = namedProperty(options, option);
+        const value = stated && ts.isPropertyAssignment(stated) ? stated.initializer : undefined;
+        const list = value && (ts.isArrayLiteralExpression(value) ? arrayElements(value) : objectLiteral(value)?.properties);
+        if (!value || !list) {
+            added.set(option, [...slot.before, ...slot.after]);
+            continue;
+        }
+        const open = value.getStart() + 1;
+        const close = value.getEnd() - 1;
+        const inner = `${indentOf(value)}${unit}`;
+        const commented = (side) => side.some(({ comments }) => comments.length);
+        if (slot.before.length) {
+            const text = commented(slot.before)
+                ? ['\n', ...lines(slot.before, inner), inner]
+                : [...joined(slot.before, ', '), ...(list.length ? [', '] : [])];
+            edits.push({ start: open, end: open, text });
+        }
+        if (slot.after.length) {
+            const end = list.length ? list[list.length - 1].getEnd() : close;
+            const lead = list.length || slot.before.length ? ', ' : '';
+            const text = commented(slot.after)
+                ? slot.after.flatMap(({ parts, comments }, index) => [
+                    index || lead ? ',\n' : '\n',
+                    ...comments.flatMap((comment) => [inner, comment, '\n']),
+                    inner,
+                    ...parts,
+                ])
+                : [lead, ...joined(slot.after, ', ')];
+            edits.push({ start: end, end, text });
+        }
+    }
+    if (added.size) {
+        const last = options.properties.at(-1);
+        const at = last ? last.getEnd() : options.getEnd() - 1;
+        const parts = optionParts(added, indent, unit);
+        edits.push({ start: at, end: at, text: last ? [', ', ...parts] : [' ', ...parts, ' '] });
+    }
+    return edits;
+}
+/** Removes a decorator, with its line where it stands alone on one, or the blank after it where it shares one. */
+function removedDecorator(decorator) {
+    const text = decorator.getSourceFile().text;
+    const start = decoratorComments(decorator)[0]?.pos ?? decorator.getStart();
+    const end = trailingComments(decorator).at(-1)?.end ?? decorator.getEnd();
+    const lineStart = lineStartOf(text, start);
+    const lineEnd = text.indexOf('\n', end);
+    // A class follows its decorators, so the line of one standing alone ends before the file does.
+    const alone = text.slice(lineStart, start).trim() === '' && text.slice(end, lineEnd).trim() === '';
+    if (alone) {
+        return { start: lineStart, end: lineEnd + 1, text: '' };
+    }
+    const after = /\s*/y;
+    after.lastIndex = end;
+    after.exec(text);
+    return { start, end: after.lastIndex, text: '' };
+}

package/dist/columnMethods.d.ts

@@ -0,0 +1,11 @@
+/** How an option's value becomes a column method, or `undefined` where it cannot be written as one. */
+export type OptionMethod<R extends string | undefined = string> = readonly [
+    option: string,
+    method: (value: string) => R
+];
+/** The option's value passed to `method`: `.length(80)`. */
+export declare const call: (method: string) => (value: string) => string;
+/** A flag as its method where it is `true`, nothing where `false`, and `undefined` where no literal says. */
+export declare const flag: (method: string) => (value: string) => string | undefined;
+/** {@link flag}, its value passed to the method where it is no literal. */
+export declare const flagOrCall: (method: string) => (value: string) => string;

package/dist/columnMethods.js

@@ -0,0 +1,6 @@
+/** The option's value passed to `method`: `.length(80)`. */
+export const call = (method) => (value) => `.${method}(${value})`;
+/** A flag as its method where it is `true`, nothing where `false`, and `undefined` where no literal says. */
+export const flag = (method) => (value) => value === 'true' ? `.${method}()` : value === 'false' ? '' : undefined;
+/** {@link flag}, its value passed to the method where it is no literal. */
+export const flagOrCall = (method) => (value) => flag(method)(value) ?? call(method)(value);

package/dist/columnRefs.js

@@ -4,7 +4,7 @@ import { inserted, replaced } from './edits.js';
 import { isSqlCall } from './entitySql.js';
 import { uqlImport, usesOf } from './imports.js';
 import { memberAccess } from './keyMaps.js';
-import { identifierText, propertyKey, propertyValue } from './syntax.js';
+import { identifierText, mentions, propertyKey, propertyValue } from './syntax.js';
 /**
  * Rewrites each `col('x')` into the ref it names - `product.x` in a `computed` callback, `refs(Item).x` in a
  * statement - where the entity its SQL renders against, and a member named `x`, can be told from here. Every
@@ -85,13 +85,6 @@ function columnMember(call, members) {
     const [name] = call.arguments;
     return call.arguments.length === 1 && ts.isStringLiteralLike(name) && members.has(name.text) ? name.text : undefined;
 }
-/** Whether `node` reads a binding named `name`, which a callback parameter of that name would shadow. */
-function mentions(node, name) {
-    if (ts.isIdentifier(node)) {
-        return node.text === name && !(ts.isPropertyAccessExpression(node.parent) && node.parent.name === node);
-    }
-    return ts.forEachChild(node, (child) => mentions(child, name) || undefined) ?? false;
-}
 /**
  * The entity a statement's SQL renders against at `node`: the one its query names, or a relation a `$populate`
  * reads there. Nothing where a function or a relation filter in between opens a scope of its own.

package/dist/context.d.ts

@@ -1,5 +1,11 @@
 import ts from 'typescript';
 import type { Edit } from './edits.js';
+/**
+ * Each name whose import goes once every use was rewritten: `expr` defaults, and the class decorators folded into
+ * `@Entity`.
+ */
+export declare const REWRITTEN: readonly ["expr", "Index", "Trigger", "Filter"];
+type Rewritten = (typeof REWRITTEN)[number];
 /** What a rewrite of one file reads and writes. */
 export type Context = {
     readonly source: ts.SourceFile;
@@ -11,16 +17,22 @@ export type Context = {
     readonly notes: string[];
     /** Names written that the file has to import from `uql-orm`, each with what it was written for. */
     readonly imports: Map<string, string>;
-    /** Uses rewritten of each name whose import goes once every use was: `Relation<T>` unwrapped, `expr` defaults. */
-    readonly rewritten: {
-        Relation: number;
-        expr: number;
-    };
+    /** Uses rewritten of each of `REWRITTEN`. */
+    readonly rewritten: Record<Rewritten, number>;
     /** Records what needs a human, at `node`. */
     readonly report: (node: ts.Node, message: string) => void;
     /** Records a rewrite that is correct but worth a second look, at `node`. */
     readonly note: (node: ts.Node, message: string) => void;
 };
+/** `file:line` of offset `at` in `source`. */
+export declare function locationAt(source: ts.SourceFile, at: number): string;
+/** A finding before it is located: the node it is about, and what to do. */
+export type Finding = {
+    readonly node: ts.Node;
+    readonly message: string;
+};
+/** Findings in source order, each as `file:line: message`, the line `locate` reads its offset at. */
+export declare function formatFindings(findings: readonly Finding[], locate: (at: number) => string): string[];
 export declare function createContext(source: ts.SourceFile, checker: ts.TypeChecker, strictNullChecks: boolean): Context;
 /** The entity a definition describes: the parameter its callbacks are named after, and the node naming it. */
 export type Owner = {
@@ -36,3 +48,4 @@ export declare function instanceTypeOf(node: ts.Node, checker: ts.TypeChecker):
 export declare function propertyNames(type: ts.Type): ReadonlySet<string>;
 /** The names of the members of the entity `node` declares or names. */
 export declare function memberNames(node: ts.Node, checker: ts.TypeChecker): ReadonlySet<string>;
+export {};

package/dist/context.js

@@ -1,10 +1,28 @@
 import ts from 'typescript';
 import { paramFor } from './keyMaps.js';
 import { identifierText } from './syntax.js';
+/**
+ * Each name whose import goes once every use was rewritten: `expr` defaults, and the class decorators folded into
+ * `@Entity`.
+ */
+export const REWRITTEN = ['expr', 'Index', 'Trigger', 'Filter'];
+/** Where `node` is, as a finding names it: `file:line`. */
+function locationOf(node) {
+    return locationAt(node.getSourceFile(), node.getStart());
+}
+/** `file:line` of offset `at` in `source`. */
+export function locationAt(source, at) {
+    return `${source.fileName}:${source.getLineAndCharacterOfPosition(at).line + 1}`;
+}
+/** Findings in source order, each as `file:line: message`, the line `locate` reads its offset at. */
+export function formatFindings(findings, locate) {
+    return findings
+        .toSorted((a, b) => a.node.getStart() - b.node.getStart())
+        .map(({ node, message }) => `${locate(node.getStart())}: ${message}`);
+}
 export function createContext(source, checker, strictNullChecks) {
     const unresolved = [];
     const notes = [];
-    const at = (node) => `${source.fileName}:${source.getLineAndCharacterOfPosition(node.getStart()).line + 1}`;
     return {
         source,
         checker,
@@ -13,12 +31,12 @@ export function createContext(source, checker, strictNullChecks) {
         unresolved,
         notes,
         imports: new Map(),
-        rewritten: { Relation: 0, expr: 0 },
+        rewritten: { expr: 0, Index: 0, Trigger: 0, Filter: 0 },
         report: (node, message) => {
-            unresolved.push(`${at(node)}: ${message}`);
+            unresolved.push(`${locationOf(node)}: ${message}`);
         },
         note: (node, message) => {
-            notes.push(`${at(node)}: ${message}`);
+            notes.push(`${locationOf(node)}: ${message}`);
         },
     };
 }

package/dist/definers.d.ts

@@ -0,0 +1,24 @@
+import ts from 'typescript';
+/** The definers a class was registered with, each with the decorator that registers the same on a decorated class. */
+export declare const CLASS_DEFINERS: {
+    readonly defineEntity: "@Entity";
+    readonly defineField: "@Field";
+    readonly defineId: "@Id";
+    readonly defineRelation: "a relation decorator";
+    readonly defineHook: "a hook decorator";
+    readonly defineIndex: "@Entity's 'indexes'";
+    readonly defineTrigger: "@Entity's 'triggers'";
+    readonly defineFilter: "@Entity's 'filters'";
+};
+export type DefinerName = keyof typeof CLASS_DEFINERS;
+/** A class-form definer's arguments by what each is: `defineX(Entity, key?, options)`, every one after the entity in `rest`. */
+export type DefinerCall = {
+    readonly call: ts.CallExpression;
+    readonly definer: DefinerName;
+    readonly entity: ts.Expression;
+    readonly key: string | undefined;
+    readonly options: ts.Expression | undefined;
+    readonly rest: readonly ts.Expression[];
+};
+/** `call` read as a class-form definer, or nothing where it is another call, the schema form included. */
+export declare function definerCall(call: ts.CallExpression): DefinerCall | undefined;

package/dist/definers.js

@@ -0,0 +1,34 @@
+import ts from 'typescript';
+import { identifierText } from './syntax.js';
+/** The definers a class was registered with, each with the decorator that registers the same on a decorated class. */
+export const CLASS_DEFINERS = {
+    defineEntity: '@Entity',
+    defineField: '@Field',
+    defineId: '@Id',
+    defineRelation: 'a relation decorator',
+    defineHook: 'a hook decorator',
+    defineIndex: "@Entity's 'indexes'",
+    defineTrigger: "@Entity's 'triggers'",
+    defineFilter: "@Entity's 'filters'",
+};
+const isDefinerName = (name) => name !== undefined && Object.hasOwn(CLASS_DEFINERS, name);
+/** The definers naming a member or a filter after the entity, their options after that. */
+const KEYED_DEFINERS = new Set([
+    'defineField',
+    'defineId',
+    'defineRelation',
+    'defineHook',
+    'defineFilter',
+]);
+/** `call` read as a class-form definer, or nothing where it is another call, the schema form included. */
+export function definerCall(call) {
+    const definer = identifierText(call.expression);
+    const [entity, ...rest] = call.arguments;
+    if (!isDefinerName(definer) || !entity || ts.isObjectLiteralExpression(entity)) {
+        return undefined;
+    }
+    const [second, third] = rest;
+    const keyed = KEYED_DEFINERS.has(definer);
+    const key = keyed && second && ts.isStringLiteralLike(second) ? second.text : undefined;
+    return { call, definer, entity, key, options: keyed ? third : second, rest };
+}

package/dist/edits.d.ts

@@ -1,4 +1,4 @@
-import type ts from 'typescript';
+import ts from 'typescript';
 /** A stretch of the original text, which a replacement can keep. */
 export type Span = {
     readonly start: number;
@@ -22,14 +22,35 @@ export declare function original(node: ts.Node): Span;
  * replacement keeps the stretch it sits in; edits that overlap without one holding the other are a bug.
  */
 export declare function applyEdits(source: string, edits: readonly Edit[]): string;
+/** A text a pass wrote, with where each of its offsets was in the text the pass read. */
+export type Pass = {
+    readonly text: string;
+    readonly sourceOffset: (at: number) => number;
+};
+/** `text` as a pass that changed nothing. */
+export declare const unedited: (text: string) => Pass;
+/** `second` run on what `first` wrote, each offset of its text mapped back to what `first` read. */
+export declare function followed(first: Pass, second: Pass): Pass;
+/** `pass` edited again by the edits `edits` reads off its text, parsed. */
+export declare function reparsedAgain(fileName: string, pass: Pass, edits: (source: ts.SourceFile) => readonly Edit[]): Pass;
+/**
+ * {@link applyEdits}, with where each offset of the result was in `source`, for a later pass reading the result to
+ * report against the file as written: an offset inside an edit's text maps to where the edit starts.
+ */
+export declare function editedText(source: string, edits: readonly Edit[]): Pass;
 export declare function replaced(node: ts.Node, text: Replacement): Edit;
 export declare function inserted(node: ts.Node, text: string): Edit;
 export declare function appended(node: ts.Node, text: string): Edit;
+/** `node`'s text with each of `uses`, the nodes inside it, written as `text`. */
+export declare function replacingUses(node: ts.Node, uses: readonly ts.Node[], text: string): string;
 /**
- * Removes elements of a comma-separated list with the separators that would dangle. Each removed element takes
- * the text up to the next item; the removed run at the end takes the separator before it, so the ranges never
- * overlap. `source` is passed because a tree from `ts.parseJsonText` carries no back-reference for `getStart()`.
+ * Removes elements of a comma-separated list, at least one of them kept, with the separators that would dangle.
+ * Each removed element takes the text up to the next item; the removed run at the end takes the separator before
+ * it, so the ranges never overlap. `source` is passed because a tree from `ts.parseJsonText` has no `getStart()`.
  */
 export declare function removeFromList(items: readonly ts.Node[], removed: readonly ts.Node[], source: ts.SourceFile): readonly Edit[];
-/** Removes a statement together with the rest of its line, so nothing is left blank behind it. */
+/**
+ * Removes a statement with the blanks before it on its line, the rest of its line and the blank lines after it,
+ * so nothing is left blank behind it.
+ */
 export declare function removeStatement(node: ts.Node): Edit;

package/dist/edits.js

@@ -1,3 +1,5 @@
+import ts from 'typescript';
+import { lineStartOf } from './syntax.js';
 /** The text of `node` as written, for a replacement to keep. */
 export function original(node) {
     return { start: node.getStart(), end: node.getEnd() };
@@ -9,20 +11,49 @@ const isInsertion = (edit) => edit.start === edit.end;
  * replacement keeps the stretch it sits in; edits that overlap without one holding the other are a bug.
  */
 export function applyEdits(source, edits) {
+    return editedText(source, edits).text;
+}
+/** `text` as a pass that changed nothing. */
+export const unedited = (text) => ({ text, sourceOffset: (at) => at });
+/** `second` run on what `first` wrote, each offset of its text mapped back to what `first` read. */
+export function followed(first, second) {
+    return { text: second.text, sourceOffset: (at) => first.sourceOffset(second.sourceOffset(at)) };
+}
+/** `pass` edited again by `edits`, which read its text. */
+function editedAgain(pass, edits) {
+    return followed(pass, editedText(pass.text, edits));
+}
+/** `pass` edited again by the edits `edits` reads off its text, parsed. */
+export function reparsedAgain(fileName, pass, edits) {
+    return editedAgain(pass, edits(ts.createSourceFile(fileName, pass.text, ts.ScriptTarget.Latest, true)));
+}
+/**
+ * {@link applyEdits}, with where each offset of the result was in `source`, for a later pass reading the result to
+ * report against the file as written: an offset inside an edit's text maps to where the edit starts.
+ */
+export function editedText(source, edits) {
+    const moved = [];
     const ordered = edits
         .map((edit, index) => ({ edit, index }))
         .sort((a, b) => a.edit.start - b.edit.start ||
         Number(!isInsertion(a.edit)) - Number(!isInsertion(b.edit)) ||
         (isInsertion(a.edit) ? b.index - a.index : b.edit.end - a.edit.end))
         .map(({ edit }) => edit);
-    return render(source, ordered, { start: 0, end: source.length });
+    const text = render(source, ordered, { start: 0, end: source.length }, undefined, moved);
+    const sourceOffset = (at) => {
+        const before = moved.findLast((edit) => edit.from <= at);
+        if (!before)
+            return at;
+        return at < before.to ? before.start : before.end + at - before.to;
+    };
+    return { text, sourceOffset };
 }
 /**
  * `range` of `source` with `edits` (ordered outermost first, an insertion before a replacement at its offset, a
  * later insertion before an earlier) applied. `parent` is the edit keeping `range`: an insertion at its edges
  * is written beside it, so it is not written again inside.
  */
-function render(source, edits, range, parent) {
+function render(source, edits, range, parent, moved) {
     const within = (edit) => edit !== parent &&
         range.start <= edit.start &&
         edit.end <= range.end &&
@@ -39,7 +70,9 @@ function render(source, edits, range, parent) {
         }
         const parts = typeof edit.text === 'string' ? [edit.text] : edit.text;
         written += source.slice(at, edit.start);
+        const from = written.length;
         written += parts.map((part) => (typeof part === 'string' ? part : render(source, inside, part, edit))).join('');
+        moved?.push({ start: edit.start, end: edit.end, from, to: written.length });
         at = edit.end;
     }
     return written + source.slice(at, range.end);
@@ -53,10 +86,14 @@ export function inserted(node, text) {
 export function appended(node, text) {
     return { start: node.getEnd(), end: node.getEnd(), text };
 }
+/** `node`'s text with each of `uses`, the nodes inside it, written as `text`. */
+export function replacingUses(node, uses, text) {
+    return applyEdits(node.getText(), uses.map((use) => ({ start: use.getStart() - node.getStart(), end: use.getEnd() - node.getStart(), text })));
+}
 /**
- * Removes elements of a comma-separated list with the separators that would dangle. Each removed element takes
- * the text up to the next item; the removed run at the end takes the separator before it, so the ranges never
- * overlap. `source` is passed because a tree from `ts.parseJsonText` carries no back-reference for `getStart()`.
+ * Removes elements of a comma-separated list, at least one of them kept, with the separators that would dangle.
+ * Each removed element takes the text up to the next item; the removed run at the end takes the separator before
+ * it, so the ranges never overlap. `source` is passed because a tree from `ts.parseJsonText` has no `getStart()`.
  */
 export function removeFromList(items, removed, source) {
     const kept = items.map((item) => !removed.includes(item));
@@ -68,13 +105,18 @@ export function removeFromList(items, removed, source) {
     if (!trailing.length) {
         return between;
     }
-    const from = lastKept < 0 ? trailing[0].getStart(source) : items[lastKept].getEnd();
-    return [...between, { start: from, end: items[items.length - 1].getEnd(), text: '' }];
+    return [...between, { start: items[lastKept].getEnd(), end: items[items.length - 1].getEnd(), text: '' }];
 }
-/** Removes a statement together with the rest of its line, so nothing is left blank behind it. */
+/**
+ * Removes a statement with the blanks before it on its line, the rest of its line and the blank lines after it,
+ * so nothing is left blank behind it.
+ */
 export function removeStatement(node) {
-    const source = node.getSourceFile();
-    const line = source.getLineAndCharacterOfPosition(node.getEnd()).line;
-    const nextLineStart = source.getLineStarts()[line + 1];
-    return { start: node.getStart(), end: nextLineStart ?? node.getEnd(), text: '' };
+    const text = node.getSourceFile().text;
+    const lineStart = lineStartOf(text, node.getStart());
+    const head = text.slice(lineStart, node.getStart());
+    const after = /[^\n]*\n?(?:[ \t]*\n)*/y;
+    after.lastIndex = node.getEnd();
+    after.exec(text);
+    return { start: lineStart + head.replace(/[ \t]*$/, '').length, end: after.lastIndex, text: '' };
 }

package/dist/entitySql.js

@@ -1,7 +1,7 @@
 import ts from 'typescript';
 import { inserted, replaced } from './edits.js';
 import { isSqlExport, uqlExport } from './imports.js';
-import { propertyValue } from './syntax.js';
+import { columnListEntries, propertyValue } from './syntax.js';
 export function isSqlCall(node, checker) {
     const callee = ts.isTaggedTemplateExpression(node)
         ? node.tag
@@ -12,9 +12,7 @@ export function isSqlCall(node, checker) {
 }
 /** The expressions of a column list, written as one or returned by its callback: each entry or `column` that is `sql`. */
 export function columnExpressions(list, checker) {
-    const body = list && ts.isArrowFunction(list) ? list.body : list;
-    const entries = body && ts.isArrayLiteralExpression(body) ? body.elements : [];
-    return entries.flatMap((entry) => {
+    return columnListEntries(list).flatMap((entry) => {
         const sql = ts.isObjectLiteralExpression(entry) ? propertyValue(entry, 'column') : entry;
         return sql && isSqlCall(sql, checker) ? [sql] : [];
     });

package/dist/imports.d.ts

@@ -1,5 +1,6 @@
 import ts from 'typescript';
-import type { Context } from './context.js';
+import { type Context } from './context.js';
+import { type Edit } from './edits.js';
 /** The name `uql-orm` gave its SQL tag, and gives it now. */
 export declare const LEGACY_SQL_TAG = "raw";
 export declare const SQL_TAG = "sql";
@@ -17,12 +18,11 @@ export declare function uqlImportDeclarations(source: ts.SourceFile, entries?: b
 export declare function uqlImport(source: ts.SourceFile, name: string, entries?: boolean): ts.ImportSpecifier | undefined;
 /** Every identifier in the file bound to the same symbol as `name`, besides `name` itself. */
 export declare function usesOf(source: ts.SourceFile, name: ts.Identifier, checker: ts.TypeChecker): ts.Identifier[];
+/** The names among `names` the file binds or reads as something other than uql-orm's export, which a rewrite would shadow. */
+export declare function foreignNames(source: ts.SourceFile, names: ReadonlySet<string>, checker: ts.TypeChecker): ReadonlySet<string>;
 /** Names an export that no longer exists, where it is imported from the package or one of its entries. */
 export declare function reportRemovedExports(ctx: Context): void;
-/**
- * The imported names the codemod removes once every use was rewritten: `Relation` unwrapped and `expr` defaults.
- * A removed decorator keeps its import on purpose: deleting it would swap a clear error for a puzzling one.
- */
+/** The imported names of `REWRITTEN` the codemod removes, once every use was rewritten. */
 export declare function deadImportNames(ctx: Context): ReadonlySet<string>;
 /** The `uql-orm` export `node` names, where its symbol is an import of it or of one of its entries. */
 export declare function uqlExport(node: ts.Node | undefined, checker: ts.TypeChecker): string | undefined;
@@ -41,4 +41,17 @@ export declare function clashingName(ctx: Context): ts.Identifier | undefined;
  * The names the rewrites wrote join the first `uql-orm` import, or are reported when there is none.
  */
 export declare function rewriteImports(dead: ReadonlySet<string>, ctx: Context): void;
+/** An import of `names` from `from`, quoted as the file quotes its imports. */
+export declare const importText: (keyword: string, names: readonly string[], from: string, quote?: string) => string;
+/**
+ * The import without `dropped` of its `elements`: the whole statement where nothing else is left of it, and the
+ * braces with them where a default import stays.
+ */
+export declare function importRemovalEdits(declaration: ts.ImportDeclaration, elements: readonly ts.ImportSpecifier[], dropped: readonly ts.ImportSpecifier[]): readonly Edit[];
+/** Every name the file spells outside its imports, which an import it binds is still used under if listed here. */
+export declare function spelledNames(source: ts.SourceFile): ReadonlySet<string>;
+/** The import names in `candidates` that the file no longer spells. */
+export declare function deadImports(elements: readonly ts.ImportSpecifier[], candidates: ReadonlySet<string | undefined>, spelled: ReadonlySet<string>): readonly ts.ImportSpecifier[];
+/** The edits dropping each `uql-orm` import name in `candidates` that the file no longer spells. */
+export declare function unusedImportEdits(source: ts.SourceFile, candidates: ReadonlySet<string>): readonly Edit[];
 export {};