uql-codemod 0.47.0 → 0.48.0

package/dist/cli.d.ts

@@ -7,11 +7,8 @@ export type ParsedArgs = {
     readonly errors: readonly string[];
 };
 /**
- * Reads the command line, rejecting anything it does not recognise.
- *
- * Unknown arguments are an error rather than being ignored: a misspelled `--dry-run` would otherwise
- * rewrite the project for real, which is the one mistake this tool must not let someone make quietly.
- * Only the `--flag=value` form is accepted, so a stray `--project foo` cannot silently fall back to the
- * default config either.
+ * Reads the command line, rejecting anything it does not recognise: a misspelled `--dry-run` would otherwise
+ * rewrite the project for real. Only `--flag=value` is accepted, so a stray `--project foo` cannot fall back
+ * to the default config either.
  */
 export declare function parseArgs(argv: readonly string[]): ParsedArgs;

package/dist/cli.js

@@ -1,11 +1,8 @@
 const VALUE_FLAGS = new Set(['project', 'include']);
 /**
- * Reads the command line, rejecting anything it does not recognise.
- *
- * Unknown arguments are an error rather than being ignored: a misspelled `--dry-run` would otherwise
- * rewrite the project for real, which is the one mistake this tool must not let someone make quietly.
- * Only the `--flag=value` form is accepted, so a stray `--project foo` cannot silently fall back to the
- * default config either.
+ * Reads the command line, rejecting anything it does not recognise: a misspelled `--dry-run` would otherwise
+ * rewrite the project for real. Only `--flag=value` is accepted, so a stray `--project foo` cannot fall back
+ * to the default config either.
  */
 export function parseArgs(argv) {
     const errors = [];

package/dist/columnRefs.d.ts

@@ -0,0 +1,7 @@
+import { type Context } from './context.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
+ * other use is reported. Returns `col` as a dead import once no use is left.
+ */
+export declare function rewriteColumnRefs(ctx: Context): readonly string[];

package/dist/columnRefs.js

@@ -0,0 +1,146 @@
+import ts from 'typescript';
+import { constructedType, memberNames, ownerOf, propertyNames } from './context.js';
+import { inserted, replaced } from './edits.js';
+import { isRaw } from './entitySql.js';
+import { uqlImport, usesOf } from './imports.js';
+import { memberAccess } from './keyMaps.js';
+import { identifierText, 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
+ * other use is reported. Returns `col` as a dead import once no use is left.
+ */
+export function rewriteColumnRefs(ctx) {
+    const element = uqlImport(ctx.source, 'col');
+    if (!element) {
+        return [];
+    }
+    const computed = new Map();
+    const unread = [];
+    for (const use of usesOf(ctx.source, element.name, ctx.checker)) {
+        const call = ts.isCallExpression(use.parent) && use.parent.expression === use ? use.parent : undefined;
+        const sql = call && ts.findAncestor(call, isRaw);
+        const option = sql?.parent;
+        const owner = option && ts.isPropertyAssignment(option) && isComputedOption(option) ? computedOwner(option) : undefined;
+        const edit = call && !owner ? statementRefEdit(call, ctx) : undefined;
+        if (call && sql && ts.isTaggedTemplateExpression(sql) && owner) {
+            computed.set(sql, { owner, calls: [...(computed.get(sql)?.calls ?? []), call] });
+        }
+        else if (edit) {
+            ctx.edits.push(edit);
+            ctx.imports.set('refs', 'the refs(...)');
+        }
+        else {
+            unread.push(use);
+        }
+    }
+    for (const [sql, { owner, calls }] of computed) {
+        const edits = computedRefEdits(sql, calls, owner, ctx);
+        if (edits) {
+            ctx.edits.push(...edits);
+        }
+        else {
+            unread.push(...calls);
+        }
+    }
+    for (const node of unread.sort((a, b) => a.getStart() - b.getStart())) {
+        ctx.report(node, "'col' was removed; read the column off refs(Entity), which the codemod could not tell here");
+    }
+    return unread.length ? [] : ['col'];
+}
+function isComputedOption(option) {
+    const key = propertyKey(option.name);
+    return key === 'computed' || key === 'virtual';
+}
+/** The entity a field's `computed` SQL is declared on: the decorated property's class, or `defineEntity`'s first argument. */
+function computedOwner(option) {
+    const holder = ts.findAncestor(option, (node) => ts.isPropertyDeclaration(node) ||
+        (ts.isCallExpression(node) && identifierText(node.expression) === 'defineEntity'));
+    if (holder && ts.isPropertyDeclaration(holder)) {
+        return ownerOf(holder.parent);
+    }
+    const [entity] = holder?.arguments ?? [];
+    return entity && ownerOf(entity);
+}
+/** `(product) => ` before a `computed` raw, and `product.x` for each `col('x')` in it, where every one names a member. */
+function computedRefEdits(sql, calls, owner, ctx) {
+    const members = memberNames(owner.entity, ctx.checker);
+    const names = calls.map((call) => columnMember(call, members));
+    if (mentions(sql, owner.param) || !names.every((name) => name !== undefined)) {
+        return undefined;
+    }
+    return [
+        inserted(sql, `(${owner.param}) => `),
+        ...calls.map((call, at) => replaced(call, memberAccess(owner.param, names[at]))),
+    ];
+}
+/** `refs(Item).x` for a `col('x')` in a statement, where the entity its SQL renders against can be told. */
+function statementRefEdit(call, ctx) {
+    const entity = statementEntity(call, ctx.checker);
+    const name = entity && columnMember(call, propertyNames(entity.type));
+    return entity && name !== undefined ? replaced(call, memberAccess(`refs(${entity.name})`, name)) : undefined;
+}
+/** The member a `col('x')` names, where its one argument is a literal naming one of `members`. */
+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.
+ */
+function statementEntity(node, checker) {
+    const path = [];
+    for (let at = node; at.parent; at = at.parent) {
+        const { parent } = at;
+        if (ts.isFunctionLike(parent)) {
+            return undefined;
+        }
+        if (ts.isPropertyAssignment(parent)) {
+            path.unshift(propertyKey(parent.name) ?? '');
+        }
+        const queried = ts.isCallExpression(parent) && parent.arguments.some((argument) => argument === at);
+        const entity = queried ? queriedEntity(parent, checker) : undefined;
+        if (entity) {
+            return entityAlong(entity, path, node, checker);
+        }
+    }
+    return undefined;
+}
+/** The entity a call queries: its first argument's class, or the `$entity` its query names. */
+function queriedEntity(call, checker) {
+    const [first] = call.arguments;
+    const entity = first && ts.isObjectLiteralExpression(first) ? propertyValue(first, '$entity') : first;
+    const instance = entity && constructedType(checker.getTypeAtLocation(entity));
+    return entity && ts.isIdentifier(entity) && instance ? { name: entity.text, type: instance } : undefined;
+}
+/** `entity` followed along `path`: into each relation a `$populate` names, and nowhere a relation filter opens. */
+function entityAlong(entity, path, node, checker) {
+    let current = entity;
+    for (const [at, key] of path.entries()) {
+        const property = current.type.getProperty(key);
+        const related = property && relatedClass(property, node, checker);
+        if (!related) {
+            continue;
+        }
+        const inScope = checker.getSymbolsInScope(node, ts.SymbolFlags.Class).some(({ name }) => name === related.name);
+        if (path[at - 1] !== '$populate' || !inScope) {
+            return undefined;
+        }
+        current = { name: related.name, type: checker.getDeclaredTypeOfSymbol(related) };
+    }
+    return current;
+}
+/** The class a relation property points at, one or many, or nothing where the property holds no class. */
+function relatedClass(property, node, checker) {
+    const type = checker.getNonNullableType(checker.getTypeOfSymbolAtLocation(property, node));
+    const symbol = (checker.getIndexTypeOfType(type, ts.IndexKind.Number) ?? type).getSymbol();
+    return symbol && symbol.flags & ts.SymbolFlags.Class ? symbol : undefined;
+}

package/dist/context.d.ts

@@ -0,0 +1,38 @@
+import ts from 'typescript';
+import type { Edit } from './edits.js';
+/** What a rewrite of one file reads and writes. */
+export type Context = {
+    readonly source: ts.SourceFile;
+    readonly checker: ts.TypeChecker;
+    /** Whether the project checks nulls; without it a `| null` written on a property changes nothing. */
+    readonly strictNullChecks: boolean;
+    readonly edits: Edit[];
+    readonly unresolved: string[];
+    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;
+    };
+    /** 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;
+};
+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 = {
+    readonly param: string;
+    readonly entity: ts.Node;
+};
+/** The owner a class, or an expression naming one, defines. */
+export declare function ownerOf(entity: ts.Node): Owner;
+/** The instance type a class type constructs, if it constructs one. */
+export declare function constructedType(type: ts.Type): ts.Type | undefined;
+/** The instance type of the entity `node` declares or names. */
+export declare function instanceTypeOf(node: ts.Node, checker: ts.TypeChecker): ts.Type;
+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>;

package/dist/context.js

@@ -0,0 +1,44 @@
+import ts from 'typescript';
+import { paramFor } from './keyMaps.js';
+import { identifierText } from './syntax.js';
+export function createContext(source, checker, strictNullChecks) {
+    const unresolved = [];
+    const notes = [];
+    const at = (node) => `${source.fileName}:${source.getLineAndCharacterOfPosition(node.getStart()).line + 1}`;
+    return {
+        source,
+        checker,
+        strictNullChecks,
+        edits: [],
+        unresolved,
+        notes,
+        imports: new Map(),
+        rewritten: { Relation: 0, expr: 0 },
+        report: (node, message) => {
+            unresolved.push(`${at(node)}: ${message}`);
+        },
+        note: (node, message) => {
+            notes.push(`${at(node)}: ${message}`);
+        },
+    };
+}
+/** The owner a class, or an expression naming one, defines. */
+export function ownerOf(entity) {
+    return { param: paramFor(identifierText(ts.isClassLike(entity) ? entity.name : entity)), entity };
+}
+/** The instance type a class type constructs, if it constructs one. */
+export function constructedType(type) {
+    return type.getConstructSignatures()[0]?.getReturnType();
+}
+/** The instance type of the entity `node` declares or names. */
+export function instanceTypeOf(node, checker) {
+    const type = checker.getTypeAtLocation(node);
+    return constructedType(type) ?? type;
+}
+export function propertyNames(type) {
+    return new Set(type.getProperties().map(({ name }) => name));
+}
+/** The names of the members of the entity `node` declares or names. */
+export function memberNames(node, checker) {
+    return propertyNames(instanceTypeOf(node, checker));
+}

package/dist/edits.d.ts

@@ -15,11 +15,10 @@ export declare function replaced(node: ts.Node, text: string): Edit;
 export declare function inserted(node: ts.Node, text: string): Edit;
 export declare function appended(node: ts.Node, text: string): Edit;
 /**
- * Removes one element of a comma-separated list - a parameter, a named import, a JSON property - taking
- * the separator that would otherwise dangle. The last element gives up the comma before it; any other
- * gives up the one after.
- *
- * The source file is passed explicitly because a tree from `ts.parseJsonText` carries no
- * back-reference, so `getStart()` cannot find one on its own.
+ * 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.
  */
 export declare function removeFromList(items: readonly ts.Node[], item: ts.Node, source: ts.SourceFile): Edit;
+/** Removes a statement together with the rest of its line, so nothing is left blank behind it. */
+export declare function removeStatement(node: ts.Node): Edit;

package/dist/edits.js

@@ -20,12 +20,9 @@ export function appended(node, text) {
     return { start: node.getEnd(), end: node.getEnd(), text };
 }
 /**
- * Removes one element of a comma-separated list - a parameter, a named import, a JSON property - taking
- * the separator that would otherwise dangle. The last element gives up the comma before it; any other
- * gives up the one after.
- *
- * The source file is passed explicitly because a tree from `ts.parseJsonText` carries no
- * back-reference, so `getStart()` cannot find one on its own.
+ * 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.
  */
 export function removeFromList(items, item, source) {
     const at = items.indexOf(item);
@@ -37,3 +34,10 @@ export function removeFromList(items, item, source) {
         text: '',
     };
 }
+/** Removes a statement together with the rest of its line, 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: '' };
+}

package/dist/entitySql.d.ts

@@ -7,8 +7,11 @@ export declare function isRaw(node: ts.Node): node is RawSql;
 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;
-/** `sql` as a template literal reading the same text: a backslash, a backtick and a `${` escaped. */
-export declare function templateOf(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;
 /**

package/dist/entitySql.js

@@ -1,13 +1,13 @@
 import ts from 'typescript';
 import { inserted, replaced } from './edits.js';
-import { propertyValue } from './keyMaps.js';
+import { identifierText, propertyValue } from './syntax.js';
 export function isRaw(node) {
     const callee = ts.isTaggedTemplateExpression(node)
         ? node.tag
         : ts.isCallExpression(node)
             ? node.expression
             : undefined;
-    return callee !== undefined && ts.isIdentifier(callee) && callee.text === 'raw';
+    return identifierText(callee) === 'raw';
 }
 /** 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) {
@@ -20,11 +20,15 @@ export function columnExpressions(list) {
 }
 /** SQL text as a `raw` tagged template, escaping what would end or interpolate it. */
 export function rawTag(sql) {
-    return `raw${templateOf(sql)}`;
+    return `raw${templateOf([sql])}`;
 }
-/** `sql` as a template literal reading the same text: a backslash, a backtick and a `${` escaped. */
-export function templateOf(sql) {
-    return `\`${sql.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${')}\``;
+/**
+ * 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}`)}\``;
 }
 /** A partial-index `where` string as `raw`, or nothing for a template that interpolates, whose values `raw` would bind. */
 export function rawWhereEdit(where) {

package/dist/fieldType.d.ts

@@ -1,15 +1,9 @@
 import ts from 'typescript';
-/** A string type carrying more than `string`, e.g. `` type UUID = `${string}-${string}` ``. */
 export declare function isBrandedString(type: ts.Type): boolean;
 /**
- * The `FieldType` expression to write for a property declared as `type`, or `undefined` when the shape is
- * one a human has to decide on.
- *
- * Mirrors `TypeFor` in `uql-orm`, in the direction the codemod needs: from the property's TypeScript type
- * to the `type` option that reflection used to supply. Only the cases reflection could actually produce
- * are handled. A `Json<T>` or vector property already had to declare its `type` explicitly, because
- * `design:type` reported the useless `Object`/`Array` for them, so any such property reaching here is
- * genuinely ambiguous and is reported rather than guessed.
+ * The `type` option reflection supplied for a property of `type`, mirroring `TypeFor` in `uql-orm`, or nothing
+ * for a shape a human decides. Only what reflection could produce is read: a `Json<T>` or vector property got
+ * `Object`/`Array` from it, so it already declared its `type`.
  */
 export declare function fieldTypeFor(type: ts.Type): string | undefined;
 /**

package/dist/fieldType.js

@@ -1,8 +1,8 @@
 import ts from 'typescript';
-/** A string type carrying more than `string`, e.g. `` type UUID = `${string}-${string}` ``. */
+/** The string types carrying more than `string`, e.g. `` type UUID = `${string}-${string}` ``, still string columns. */
+const BRANDED_STRING = ts.TypeFlags.TemplateLiteral | ts.TypeFlags.StringMapping;
 export function isBrandedString(type) {
-    const branded = ts.TypeFlags.TemplateLiteral | ts.TypeFlags.StringMapping;
-    return type.isUnion() ? type.types.some((t) => !!(t.getFlags() & branded)) : !!(type.getFlags() & branded);
+    return (type.isUnion() ? type.types : [type]).some((t) => !!(t.getFlags() & BRANDED_STRING));
 }
 /**
  * Reads a union by requiring its arms to agree, which is what an `'a' | 'b'` enum or a `T | null` looks
@@ -14,24 +14,16 @@ function foldUnion(type, read) {
     return readings.size === 1 ? [...readings][0] : undefined;
 }
 /**
- * The `FieldType` expression to write for a property declared as `type`, or `undefined` when the shape is
- * one a human has to decide on.
- *
- * Mirrors `TypeFor` in `uql-orm`, in the direction the codemod needs: from the property's TypeScript type
- * to the `type` option that reflection used to supply. Only the cases reflection could actually produce
- * are handled. A `Json<T>` or vector property already had to declare its `type` explicitly, because
- * `design:type` reported the useless `Object`/`Array` for them, so any such property reaching here is
- * genuinely ambiguous and is reported rather than guessed.
+ * The `type` option reflection supplied for a property of `type`, mirroring `TypeFor` in `uql-orm`, or nothing
+ * for a shape a human decides. Only what reflection could produce is read: a `Json<T>` or vector property got
+ * `Object`/`Array` from it, so it already declared its `type`.
  */
 export function fieldTypeFor(type) {
     const flags = type.getFlags();
     if (type.isUnion()) {
         return foldUnion(type, fieldTypeFor);
     }
-    // `TemplateLiteral` and `StringMapping` cover the branded-string types projects use for ids, e.g.
-    // `type UUID = `${string}-${string}-${string}-${string}-${string}``, which are still string columns.
-    const stringLike = ts.TypeFlags.String | ts.TypeFlags.StringLiteral | ts.TypeFlags.TemplateLiteral | ts.TypeFlags.StringMapping;
-    if (flags & stringLike)
+    if (flags & (ts.TypeFlags.String | ts.TypeFlags.StringLiteral | BRANDED_STRING))
         return 'String';
     if (flags & (ts.TypeFlags.Number | ts.TypeFlags.NumberLiteral))
         return 'Number';

package/dist/imports.d.ts

@@ -0,0 +1,40 @@
+import ts from 'typescript';
+import type { Context } from './context.js';
+type UqlImport = {
+    readonly declaration: ts.ImportDeclaration;
+    readonly entry: string;
+    readonly elements: readonly ts.ImportSpecifier[];
+};
+/**
+ * The file's named imports from `uql-orm`. `entries` adds the driver entries (`uql-orm/postgres`, ...),
+ * for what is read by name only: `idKey` written into one would land on an entry that may not export it.
+ */
+export declare function uqlImportDeclarations(source: ts.SourceFile, entries?: boolean): readonly UqlImport[];
+/** The specifier importing the export `name` from `uql-orm`, or with `entries` from any of its entries. */
+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[];
+/** 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;
+/**
+ * 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.
+ */
+export declare function deadImportNames(ctx: Context): ReadonlySet<string>;
+/**
+ * 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.
+ */
+export declare function dropDeadImports(dead: ReadonlySet<string>, rewritten: ReadonlySet<ts.ImportDeclaration>, ctx: Context): void;
+/**
+ * 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.
+ */
+export declare function addImports(rewritten: ReadonlySet<ts.ImportDeclaration>, ctx: Context): void;
+export {};