uql-codemod 0.48.1 → 0.49.0

package/dist/edits.js

@@ -1,17 +1,84 @@
+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() };
+}
+const isInsertion = (edit) => edit.start === edit.end;
+/**
+ * Applies edits to `source`, which is spliced rather than reprinted: a codemod that reformats everything it
+ * touches buries its own change in the diff. An edit inside a range another replaces is moot, unless that
+ * 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);
+    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 };
+}
 /**
- * Applies edits back to front, so none shifts the offsets of another, and at a shared offset the replacement
- * first, so an insertion there lands before it. Splicing rather than reprinting keeps the rest of the file
- * byte for byte: a codemod that reformats everything it touches buries its own change in the diff.
+ * `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.
  */
-export function applyEdits(text, edits) {
-    let result = text;
-    for (const edit of [...edits].sort((a, b) => b.start - a.start || b.end - a.end)) {
-        result = result.slice(0, edit.start) + edit.text + result.slice(edit.end);
+function render(source, edits, range, parent, moved) {
+    const within = (edit) => edit !== parent &&
+        range.start <= edit.start &&
+        edit.end <= range.end &&
+        !(parent && isInsertion(edit) && (edit.start === parent.start || edit.start === parent.end));
+    const inside = edits.filter(within);
+    let written = '';
+    let at = range.start;
+    for (const edit of inside) {
+        if (edit.start < at) {
+            if (edit.end > at) {
+                throw new Error(`overlapping edits at ${edit.start}`);
+            }
+            continue;
+        }
+        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 result;
+    return written + source.slice(at, range.end);
 }
 export function replaced(node, text) {
-    return { start: node.getStart(), end: node.getEnd(), text };
+    return { ...original(node), text };
 }
 export function inserted(node, text) {
     return { start: node.getStart(), end: node.getStart(), text };
@@ -19,25 +86,37 @@ 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 one element of a comma-separated list with the separator that would dangle: the comma before the
- * last element, the one after any other. `source` is passed because a tree from `ts.parseJsonText` carries
- * no back-reference for `getStart()` to find.
+ * 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, item, source) {
-    const at = items.indexOf(item);
-    const next = items[at + 1];
-    const previous = items[at - 1];
-    return {
-        start: previous && !next ? previous.getEnd() : item.getStart(source),
-        end: next ? next.getStart(source) : item.getEnd(),
-        text: '',
-    };
+export function removeFromList(items, removed, source) {
+    const kept = items.map((item) => !removed.includes(item));
+    const lastKept = kept.lastIndexOf(true);
+    const between = items
+        .slice(0, lastKept + 1)
+        .flatMap((item, at) => kept[at] ? [] : [{ start: item.getStart(source), end: items[at + 1].getStart(source), text: '' }]);
+    const trailing = items.slice(lastKept + 1);
+    if (!trailing.length) {
+        return between;
+    }
+    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.d.ts

@@ -1,22 +1,21 @@
 import ts from 'typescript';
-import { type Edit } from './edits.js';
-/** `raw\`...\`` or `raw(...)`. */
-type RawSql = ts.TaggedTemplateExpression | ts.CallExpression;
-export declare function isRaw(node: ts.Node): node is RawSql;
-/** The expressions of a column list, written as one or returned by its callback: each entry or `column` that is `raw`. */
-export declare function columnExpressions(list: ts.Expression | undefined): readonly RawSql[];
-/** SQL text as a `raw` tagged template, escaping what would end or interpolate it. */
-export declare function rawTag(sql: string): string;
-/**
- * A template literal reading `texts` with the source of each of `values` interpolated between them, one fewer
- * than `texts`: in the texts, a backslash, a backtick and a `${` are escaped.
- */
-export declare function templateOf(texts: readonly string[], values?: readonly string[]): string;
-/** A partial-index `where` string as `raw`, or nothing for a template that interpolates, whose values `raw` would bind. */
-export declare function rawWhereEdit(where: ts.Expression): Edit | undefined;
+import { type Edit, type Part, type Span } from './edits.js';
+/** `sql\`...\`` or `sql(...)`, or the deprecated `raw` of either. */
+type SqlCall = ts.TaggedTemplateExpression | ts.CallExpression;
+export declare function isSqlCall(node: ts.Node, checker: ts.TypeChecker): node is SqlCall;
+/** The expressions of a column list, written as one or returned by its callback: each entry or `column` that is `sql`. */
+export declare function columnExpressions(list: ts.Expression | undefined, checker: ts.TypeChecker): readonly SqlCall[];
+/** SQL text as a template tagged by `name`, escaping what would end or interpolate it. */
+export declare function sqlTag(name: string, sql: string): string;
+/** `text` as a template literal binding nothing: a backslash, a backtick and a `${` in it are escaped. */
+export declare function templateOf(text: string): string;
+/** A template literal reading `texts`, the `values` kept from the original interpolated between them. */
+export declare function templateWith(texts: readonly string[], values: readonly Span[]): readonly Part[];
+/** A partial-index `where` string as `sql`, or nothing for a template that interpolates, whose values `sql` would bind. */
+export declare function sqlWhereEdit(where: ts.Expression, name: string): Edit | undefined;
 /**
  * The columns SQL names by hand, which a rename does not reach: each quoted identifier, and each bare word
  * naming one of `members`. What a string literal holds is left out, as is a word called as a function.
  */
-export declare function handNamedColumns(sql: ts.Expression, members: ReadonlySet<string>): readonly string[];
+export declare function handNamedColumns(sql: ts.Expression, members: ReadonlySet<string>, checker: ts.TypeChecker): readonly string[];
 export {};

package/dist/entitySql.js

@@ -1,60 +1,62 @@
 import ts from 'typescript';
 import { inserted, replaced } from './edits.js';
-import { identifierText, propertyValue } from './syntax.js';
-export function isRaw(node) {
+import { isSqlExport, uqlExport } from './imports.js';
+import { columnListEntries, propertyValue } from './syntax.js';
+export function isSqlCall(node, checker) {
     const callee = ts.isTaggedTemplateExpression(node)
         ? node.tag
         : ts.isCallExpression(node)
             ? node.expression
             : undefined;
-    const name = identifierText(callee);
-    return name === 'raw' || name === 'sql';
-}
-/** The expressions of a column list, written as one or returned by its callback: each entry or `column` that is `raw`. */
-export function columnExpressions(list) {
-    const body = list && ts.isArrowFunction(list) ? list.body : list;
-    const entries = body && ts.isArrayLiteralExpression(body) ? body.elements : [];
-    return entries.flatMap((entry) => {
+    return isSqlExport(uqlExport(callee, 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) {
+    return columnListEntries(list).flatMap((entry) => {
         const sql = ts.isObjectLiteralExpression(entry) ? propertyValue(entry, 'column') : entry;
-        return sql && isRaw(sql) ? [sql] : [];
+        return sql && isSqlCall(sql, checker) ? [sql] : [];
     });
 }
-/** SQL text as a `raw` tagged template, escaping what would end or interpolate it. */
-export function rawTag(sql) {
-    return `raw${templateOf([sql])}`;
+/** SQL text as a template tagged by `name`, escaping what would end or interpolate it. */
+export function sqlTag(name, sql) {
+    return `${name}${templateOf(sql)}`;
 }
-/**
- * A template literal reading `texts` with the source of each of `values` interpolated between them, one fewer
- * than `texts`: in the texts, a backslash, a backtick and a `${` are escaped.
- */
-export function templateOf(texts, values = []) {
-    const escaped = texts.map((text) => text.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${'));
-    return `\`${escaped.reduce((template, text, at) => `${template}\${${values[at - 1]}}${text}`)}\``;
+/** `text` as a template literal binding nothing: a backslash, a backtick and a `${` in it are escaped. */
+export function templateOf(text) {
+    return `\`${escapedIn(text)}\``;
+}
+/** A template literal reading `texts`, the `values` kept from the original interpolated between them. */
+export function templateWith(texts, values) {
+    const [first, ...rest] = texts.map(escapedIn);
+    return ['`', first, ...rest.flatMap((text, at) => ['${', values[at], '}', text]), '`'];
+}
+function escapedIn(text) {
+    return text.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
 }
-/** A partial-index `where` string as `raw`, or nothing for a template that interpolates, whose values `raw` would bind. */
-export function rawWhereEdit(where) {
+/** A partial-index `where` string as `sql`, or nothing for a template that interpolates, whose values `sql` would bind. */
+export function sqlWhereEdit(where, name) {
     if (ts.isNoSubstitutionTemplateLiteral(where)) {
-        return inserted(where, 'raw');
+        return inserted(where, name);
     }
-    return ts.isStringLiteral(where) ? replaced(where, rawTag(where.text)) : undefined;
+    return ts.isStringLiteral(where) ? replaced(where, sqlTag(name, where.text)) : undefined;
 }
 /**
  * The columns SQL names by hand, which a rename does not reach: each quoted identifier, and each bare word
  * naming one of `members`. What a string literal holds is left out, as is a word called as a function.
  */
-export function handNamedColumns(sql, members) {
-    const code = sqlText(sql)?.replace(/'(?:[^']|'')*'/g, "''") ?? '';
+export function handNamedColumns(sql, members, checker) {
+    const code = sqlText(sql, checker)?.replace(/'(?:[^']|'')*'/g, "''") ?? '';
     const quoted = Array.from(code.matchAll(/"[^"]+"|`[^`]+`/g), ([token]) => token.slice(1, -1));
     const bare = Array.from(code.matchAll(/\b[A-Za-z_]\w*\b(?!\s*\()/g), ([word]) => word);
     return [...new Set([...quoted, ...bare.filter((word) => members.has(word))])];
 }
-/** The text of a `raw` or a string, `?` standing in for each interpolation. */
-function sqlText(sql) {
+/** The text of a `sql` or a string, `?` standing in for each interpolation. */
+function sqlText(sql, checker) {
     if (!sql) {
         return undefined;
     }
-    if (isRaw(sql)) {
-        return sqlText(ts.isTaggedTemplateExpression(sql) ? sql.template : sql.arguments[0]);
+    if (isSqlCall(sql, checker)) {
+        return sqlText(ts.isTaggedTemplateExpression(sql) ? sql.template : sql.arguments[0], checker);
     }
     if (ts.isTemplateExpression(sql)) {
         return [sql.head, ...sql.templateSpans.map((span) => span.literal)].map((part) => part.text).join(' ? ');

package/dist/imports.d.ts

@@ -1,5 +1,9 @@
 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";
 type UqlImport = {
     readonly declaration: ts.ImportDeclaration;
     readonly entry: string;
@@ -14,27 +18,40 @@ 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 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;
+/** Whether `name` is the SQL tag, by either of its names. */
+export declare function isSqlExport(name: string | undefined): boolean;
+/** The name the file calls the SQL tag by once `raw` is renamed: the alias it imports it as, else `sql`. */
+export declare function sqlName(source: ts.SourceFile): string;
 /**
- * Rewrites each import naming a {@link RENAMED_EXPORTS} export, or from a {@link MOVED_ENTRIES} entry, renaming
- * every use: a name moving entries gets an import from its new one, and one the file already imports is dropped,
- * as is a `dead` one. Returns the rewritten imports, which nothing else may edit.
- */
-export declare function renameExports(dead: ReadonlySet<string>, ctx: Context): ReadonlySet<ts.ImportDeclaration>;
-/**
- * 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 first identifier of the file already naming something a rewrite writes: a name it imports (`sql`, `refs`,
+ * `idKey`) or a rename brings in. The write would shadow it or be shadowed, so the file is left to its owner.
  */
-export declare function deadImportNames(ctx: Context): ReadonlySet<string>;
+export declare function clashingName(ctx: Context): ts.Identifier | undefined;
 /**
- * Removes `import 'reflect-metadata'`, since the polyfill only ever fed `design:type`, and each `dead` name
- * from the imports {@link renameExports} left as written, having left the dead names out of the rest.
+ * Rewrites the file's imports in one pass: a name {@link RENAMED_EXPORTS} renames or a {@link MOVED_ENTRIES} entry
+ * moves is imported again where it lives now, every use renamed, and one already imported or `dead` is dropped.
+ * The names the rewrites wrote join the first `uql-orm` import, or are reported when there is none.
  */
-export declare function dropDeadImports(dead: ReadonlySet<string>, rewritten: ReadonlySet<ts.ImportDeclaration>, ctx: Context): void;
+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;
 /**
- * Imports what the rewrites wrote (`idKey`, `raw`) into the file's own `uql-orm` import. Reported instead
- * where there is none: the package may be imported under a path this codemod does not recognise.
+ * 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 addImports(rewritten: ReadonlySet<ts.ImportDeclaration>, ctx: Context): void;
+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 {};