uql-codemod 0.23.0

package/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2015-present UQL Contributors
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# uql-codemod
+
+Migrates [uql-orm](https://uql-orm.dev) entities from the legacy TypeScript decorators to the TC39
+standard spec. One command, on your own source, with a dry run first:
+
+```sh
+npx uql-codemod --project=tsconfig.json --dry-run
+npx uql-codemod --project=tsconfig.json
+```
+
+| Flag | |
+|---|---|
+| `--project=<path>` | `tsconfig.json` to read. Required in practice: the codemod needs a real program, not a parser, because it writes down the types `design:type` used to report at runtime. Defaults to `./tsconfig.json`. |
+| `--dry-run` | Report what would change and touch nothing. |
+| `--include=<a,b>` | Only files whose path contains one of these fragments. |
+
+Only the `--flag=value` form is read, and anything unrecognised is an error: a misspelled `--dry-run`
+would otherwise rewrite the project for real. It exits `0` when nothing is left for you, `1` when
+something is, and `2` when it could not start at all - a bad argument, or a project it cannot read.
+
+## What it rewrites
+
+- `@Field()` and `@Field({ ... })` with no `type`, and `@Id()`: inserts the `type` the property's
+  declared TypeScript type implies. Skipped when `references` is present, because schema generation
+  resolves that column from the referenced primary key.
+- Bare relation decorators: inserts `entity: () => X`, unwrapping arrays and the old `Relation<T>` alias.
+- `Relation<T>` becomes `T`, and its import goes with the last usage - `uql-orm` no longer exports it.
+  A usage somewhere the codemod does not reach, such as a type alias, keeps the import and is reported.
+- `@Transactional()` methods: drops the `@InjectQuerier() querier?: Querier` parameter and rewrites the
+  body to `currentQuerier()`.
+- `import 'reflect-metadata'` goes. Removing the package from your `package.json` is left to you.
+- `tsconfig.json`: removes `experimentalDecorators` and `emitDecoratorMetadata`, keeping the rest of the
+  file - comments and formatting included - exactly as written.
+
+## What it refuses to do
+
+It reports rather than guesses, and exits non-zero when anything is left for you:
+
+- **`target: esnext`** is reported, not changed. Removing the line falls back to the compiler default
+  (`es5` for `tsc`), and choosing a replacement means guessing which era the project targets. Any dated
+  target works; `esnext` is the one where TypeScript emits decorator syntax untransformed.
+- **A value inherited through `extends`** cannot be edited here, so the base config is reported instead.
+- **`@Log()` and `@Serialized()`** are reported and left in place. They no longer exist, and what to do
+  instead is a judgement call.
+- **Options it cannot read** (`@Field(sharedOptions)`, a spread, or a `@Field` never called at all) are
+  left exactly as written. Replacing an argument it cannot parse would silently drop the options.
+- **A property whose type it cannot map to a column** (a `Json<T>`, a vector, a union that disagrees with
+  itself) is reported as `needs a decision`. Those always had to declare `type` by hand anyway, because
+  `design:type` reported the useless `Object`/`Array` for them.
+- **A branded string id**, e.g. `type UUID = \`${string}-${string}\``, gets `type: String` plus a
+  `worth a look` note. That is a real fork: `String` generates a text column, `'uuid'` generates a native
+  one, and only you know which the database has.
+
+## After it runs
+
+`tsc` is the rest of the migration, and that is the point: the annotations the codemod inserts are now
+*checked* against the properties they describe, so anything it got wrong is a compile error rather than a
+silently wrong column. See the [upgrade guide](https://uql-orm.dev/upgrade-guide).
+
+## License
+
+MIT

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { parseArgs } from './cli.js';
+import { run } from './index.js';
+const USAGE = 'usage: uql-codemod [--project=<path>] [--include=<a,b>] [--dry-run]';
+// Exit 2 is "could not start", so a script can tell it apart from exit 1, "there is work left".
+const stop = (message) => {
+    console.error(message);
+    process.exit(2);
+};
+const { options, errors } = parseArgs(process.argv.slice(2));
+if (errors.length) {
+    stop([...errors, USAGE].join('\n'));
+}
+// A wrong `--project` is the likeliest mistake here, and reporting it as a stack trace read as a crash.
+const summary = await run(options).catch((error) => stop(error instanceof Error ? error.message : USAGE));
+for (const line of summary.notes) {
+    console.log(`worth a look: ${line}`);
+}
+for (const line of summary.unresolved) {
+    console.error(`needs a decision: ${line}`);
+}
+console.log(`${summary.changed.length} file(s) ${options.dryRun ? 'would change' : 'changed'}`);
+if (summary.unresolved.length) {
+    console.error(`${summary.unresolved.length} property(ies) left untouched; see above`);
+    process.exit(1);
+}

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+import type { RunOptions } from './index.js';
+export type ParsedArgs = {
+    readonly options: RunOptions;
+    /** Why the arguments were rejected. Nothing runs while this is non-empty. */
+    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.
+ */
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;

package/dist/cli.js

@@ -0,0 +1,40 @@
+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.
+ */
+export function parseArgs(argv) {
+    const errors = [];
+    const values = new Map();
+    let dryRun = false;
+    for (const arg of argv) {
+        if (arg === '--dry-run') {
+            dryRun = true;
+            continue;
+        }
+        const separator = arg.indexOf('=');
+        const name = arg.slice(2, separator === -1 ? undefined : separator);
+        if (!arg.startsWith('--') || !VALUE_FLAGS.has(name)) {
+            errors.push(`unknown argument '${arg}'`);
+            continue;
+        }
+        const value = arg.slice(separator + 1);
+        if (separator === -1 || !value) {
+            errors.push(`'--${name}' needs a value, as '--${name}=<value>'`);
+            continue;
+        }
+        values.set(name, value);
+    }
+    return {
+        options: {
+            project: values.get('project') ?? 'tsconfig.json',
+            dryRun,
+            include: values.get('include')?.split(',').filter(Boolean),
+        },
+        errors,
+    };
+}

package/dist/edits.d.ts

@@ -0,0 +1,23 @@
+import type ts from 'typescript';
+/** One text replacement in a file. */
+export type Edit = {
+    readonly start: number;
+    readonly end: number;
+    readonly text: string;
+};
+/**
+ * Applies edits back to front, so an earlier edit cannot shift the offsets of a later one.
+ *
+ * Replacing text rather than reprinting the file is what keeps the rest of it byte-for-byte: a codemod
+ * that reformats everything it touches buries its own change in the diff.
+ */
+export declare function applyEdits(text: string, edits: readonly Edit[]): string;
+/**
+ * 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.
+ */
+export declare function removeFromList(items: readonly ts.Node[], item: ts.Node, source: ts.SourceFile): Edit;

package/dist/edits.js

@@ -0,0 +1,31 @@
+/**
+ * Applies edits back to front, so an earlier edit cannot shift the offsets of a later one.
+ *
+ * Replacing text rather than reprinting the file is what keeps the rest of it byte-for-byte: a codemod
+ * that reformats everything it touches buries its own change in the diff.
+ */
+export function applyEdits(text, edits) {
+    let result = text;
+    for (const edit of [...edits].sort((a, b) => b.start - a.start)) {
+        result = result.slice(0, edit.start) + edit.text + result.slice(edit.end);
+    }
+    return result;
+}
+/**
+ * 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.
+ */
+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: '',
+    };
+}

package/dist/fieldType.d.ts

@@ -0,0 +1,19 @@
+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.
+ */
+export declare function fieldTypeFor(type: ts.Type): string | undefined;
+/**
+ * The entity name a relation property points at: `Company` for `Company`, `Company[]`, and
+ * `Relation<Company>` alike, since `Relation<T>` is an alias for `T` and erases before this runs.
+ */
+export declare function relationTargetFor(type: ts.Type, checker: ts.TypeChecker): string | undefined;

package/dist/fieldType.js

@@ -0,0 +1,64 @@
+import ts from 'typescript';
+/** A string type carrying more than `string`, e.g. `` type UUID = `${string}-${string}` ``. */
+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);
+}
+/**
+ * Reads a union by requiring its arms to agree, which is what an `'a' | 'b'` enum or a `T | null` looks
+ * like. `undefined` and `null` arms are dropped first: they carry no column type of their own.
+ */
+function foldUnion(type, read) {
+    const arms = type.types.filter((arm) => !(arm.getFlags() & (ts.TypeFlags.Undefined | ts.TypeFlags.Null)));
+    const readings = new Set(arms.map(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.
+ */
+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)
+        return 'String';
+    if (flags & (ts.TypeFlags.Number | ts.TypeFlags.NumberLiteral))
+        return 'Number';
+    if (flags & (ts.TypeFlags.BigInt | ts.TypeFlags.BigIntLiteral))
+        return 'BigInt';
+    if (flags & (ts.TypeFlags.Boolean | ts.TypeFlags.BooleanLiteral))
+        return 'Boolean';
+    // Matched by declared symbol rather than by the printed type: both of these became generic in the
+    // modern lib, so `Uint8Array` prints as `Uint8Array<ArrayBufferLike>` and never compared equal.
+    const name = type.getSymbol()?.getName();
+    if (name === 'Date')
+        return 'Date';
+    if (name === 'Buffer' || name === 'Uint8Array')
+        return "'blob'";
+    return undefined;
+}
+/**
+ * The entity name a relation property points at: `Company` for `Company`, `Company[]`, and
+ * `Relation<Company>` alike, since `Relation<T>` is an alias for `T` and erases before this runs.
+ */
+export function relationTargetFor(type, checker) {
+    if (type.isUnion()) {
+        return foldUnion(type, (arm) => relationTargetFor(arm, checker));
+    }
+    const elementType = checker.getIndexTypeOfType(type, ts.IndexKind.Number);
+    const target = elementType ?? type;
+    const symbol = target.getSymbol();
+    const name = symbol?.getName();
+    return name && name !== '__type' && /^[A-Z][A-Za-z0-9_]*$/.test(name) ? name : undefined;
+}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export * from './transform.js';
+export * from './tsconfig.js';
+export type RunOptions = {
+    /** Path to the project's `tsconfig.json`; the codemod needs a real program to read property types. */
+    readonly project: string;
+    /** Report what would change without touching anything. */
+    readonly dryRun?: boolean;
+    /** Restrict the run to files whose path contains one of these fragments. */
+    readonly include?: readonly string[];
+};
+export type RunSummary = {
+    readonly changed: readonly string[];
+    readonly unresolved: readonly string[];
+    readonly notes: readonly string[];
+};
+/**
+ * Rewrites a project's entities for the standard decorator spec.
+ *
+ * @remarks Needs a type checker, not just a parser: the whole point is to write down the types that
+ * `design:type` used to report at runtime, and only the checker knows what `role?: Role` resolves to.
+ */
+export declare function run({ project, dryRun, include }: RunOptions): Promise<RunSummary>;

package/dist/index.js

@@ -0,0 +1,56 @@
+import { writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import ts from 'typescript';
+import { transformFile } from './transform.js';
+import { transformTsconfig } from './tsconfig.js';
+export * from './transform.js';
+export * from './tsconfig.js';
+/**
+ * Rewrites a project's entities for the standard decorator spec.
+ *
+ * @remarks Needs a type checker, not just a parser: the whole point is to write down the types that
+ * `design:type` used to report at runtime, and only the checker knows what `role?: Role` resolves to.
+ */
+export async function run({ project, dryRun, include }) {
+    // Absolute, because `parseJsonConfigFileContent` resolves every discovered file against the base path
+    // and a relative one yields file names the program cannot then open.
+    const configPath = resolve(project);
+    const config = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (config.error) {
+        throw new TypeError(ts.flattenDiagnosticMessageText(config.error.messageText, ' '));
+    }
+    const host = ts.parseJsonConfigFileContent(config.config, ts.sys, dirname(configPath));
+    const program = ts.createProgram(host.fileNames, {
+        ...host.options,
+        // The codemod only ever reads types, so the emit target is irrelevant. It is pinned because a
+        // project may name a target newer than this TypeScript understands, which would otherwise be
+        // reported as a config error and leave the options half-applied.
+        target: ts.ScriptTarget.ESNext,
+        noEmit: true,
+    });
+    const checker = program.getTypeChecker();
+    const results = [];
+    for (const source of program.getSourceFiles()) {
+        if (source.isDeclarationFile || /[/\\]node_modules[/\\]/.test(source.fileName))
+            continue;
+        if (include?.length && !include.some((fragment) => source.fileName.includes(fragment)))
+            continue;
+        const result = transformFile(source, checker);
+        if (result.changed || result.unresolved.length || result.notes.length)
+            results.push(result);
+    }
+    // The config is rewritten too: leaving `experimentalDecorators` on is what keeps a project compiling
+    // against the old spec, so a codemod that only touched the sources would leave it half-migrated.
+    const tsconfig = transformTsconfig(configPath, ts.sys.readFile(configPath) ?? '');
+    if (!dryRun) {
+        await Promise.all(results.filter((r) => r.changed).map((r) => writeFile(r.fileName, r.text, 'utf8')));
+        if (tsconfig.changed) {
+            await writeFile(configPath, tsconfig.text, 'utf8');
+        }
+    }
+    return {
+        changed: [...results.filter((r) => r.changed).map((r) => r.fileName), ...(tsconfig.changed ? [configPath] : [])],
+        unresolved: [...results.flatMap((r) => r.unresolved), ...tsconfig.unresolved],
+        notes: results.flatMap((r) => r.notes),
+    };
+}

package/dist/transform.d.ts

@@ -0,0 +1,12 @@
+import ts from 'typescript';
+export type FileResult = {
+    readonly fileName: string;
+    readonly text: string;
+    readonly changed: boolean;
+    /** Properties the codemod refused to guess at, each needing a human. */
+    readonly unresolved: readonly string[];
+    /** Rewrites that are correct but worth a second look. */
+    readonly notes: readonly string[];
+};
+/** Rewrites one source file for the standard decorator spec. */
+export declare function transformFile(source: ts.SourceFile, checker: ts.TypeChecker): FileResult;

package/dist/transform.js

@@ -0,0 +1,321 @@
+import ts from 'typescript';
+import { applyEdits, removeFromList } from './edits.js';
+import { fieldTypeFor, isBrandedString, relationTargetFor } from './fieldType.js';
+const FIELD_DECORATORS = new Set(['Field', 'Id']);
+const RELATION_DECORATORS = new Set(['OneToOne', 'ManyToOne', 'OneToMany', 'ManyToMany']);
+/**
+ * Decorators that no longer exist, and that the codemod does not remove for you.
+ *
+ * A standard-spec decorator cannot preserve a generic method's signature, which is why these went. What
+ * to do instead is a judgement call - inline the logging, drop the serialisation - so the usage is
+ * reported and left in place. Removing only the import would swap a clear error for a puzzling one.
+ */
+const REMOVED_DECORATORS = new Set(['Log', 'Serialized']);
+function decoratorName(node) {
+    const call = ts.isCallExpression(node.expression) ? node.expression : undefined;
+    const target = call?.expression ?? node.expression;
+    return ts.isIdentifier(target) ? target.text : undefined;
+}
+function decoratorOptions(node) {
+    if (!ts.isCallExpression(node.expression)) {
+        // `@Field` rather than `@Field()`: there is no argument list to write into, and adding one would mean
+        // guessing that this is the decorator factory the codemod thinks it is.
+        return { kind: 'opaque', reason: 'it is used without being called' };
+    }
+    const [first] = node.expression.arguments;
+    if (!first) {
+        return { kind: 'empty', call: node.expression };
+    }
+    if (!ts.isObjectLiteralExpression(first)) {
+        return { kind: 'opaque', reason: `its options are passed as '${first.getText()}'` };
+    }
+    return first.properties.some(ts.isSpreadAssignment)
+        ? { kind: 'opaque', reason: 'its options object spreads another' }
+        : { kind: 'literal', node: first };
+}
+function hasProperty(options, name) {
+    return (options.kind === 'literal' &&
+        options.node.properties.some((prop) => prop.name && ts.isIdentifier(prop.name) && prop.name.text === name));
+}
+/** Inserts `option` into the decorator's options object, creating one when the call has no arguments. */
+function insertOption(options, option) {
+    if (options.kind === 'empty') {
+        // `@Field()` -> `@Field({ ... })`: the argument list is empty, so this only ever inserts.
+        const { arguments: args } = options.call;
+        return { start: args.pos, end: args.end, text: `{ ${option} }` };
+    }
+    const first = options.node.properties[0];
+    return first
+        ? { start: first.getStart(), end: first.getStart(), text: `${option}, ` }
+        : { start: options.node.getStart(), end: options.node.getEnd(), text: `{ ${option} }` };
+}
+/**
+ * Writes one option the decorator can no longer infer at runtime, or records why it could not.
+ *
+ * Returns the property's type when an edit was written, so a caller can say something about what was
+ * just decided. Nothing is written for options the codemod cannot read: replacing them would drop
+ * whatever the author put there.
+ */
+function addInferredOption(decorator, node, ctx, spec) {
+    const options = decoratorOptions(decorator);
+    if (spec.satisfiedBy.some((name) => hasProperty(options, name))) {
+        return undefined;
+    }
+    if (options.kind === 'opaque') {
+        ctx.unresolved.push(`${ctx.describe(node)}: cannot add '${spec.option}' because ${options.reason}`);
+        return undefined;
+    }
+    const type = ctx.checker.getTypeAtLocation(node);
+    const value = spec.infer(type);
+    if (!value) {
+        ctx.unresolved.push(`${ctx.describe(node)}: cannot infer '${spec.option}' for ${ctx.checker.typeToString(type)}`);
+        return undefined;
+    }
+    ctx.edits.push(insertOption(options, `${spec.option}: ${value}`));
+    return type;
+}
+/** Writes the `type` that `design:type` used to supply at runtime. */
+function addFieldType(decorator, node, ctx) {
+    const type = addInferredOption(decorator, node, ctx, {
+        option: 'type',
+        // A `references` field deliberately has no `type`: the column resolves from the primary key it
+        // points at, which also carries that key's `columnType` and length.
+        satisfiedBy: ['type', 'references'],
+        infer: fieldTypeFor,
+    });
+    // A branded id type (`type UUID = `${string}-${string}-...``) erased to `String` under reflection, so
+    // `String` is what keeps the existing column. It is often not what was wanted, though, and switching
+    // to `'uuid'` changes the generated column, so say so rather than decide.
+    if (type && isBrandedString(type)) {
+        ctx.notes.push(`${ctx.describe(node)}: set 'type: ${fieldTypeFor(type)}' for ` +
+            `${ctx.checker.typeToString(type)}, matching the previous behaviour. If the column should be ` +
+            "'uuid', change it deliberately: that alters the schema.");
+    }
+}
+/** Writes the `entity` getter relations can no longer infer. */
+function addRelationEntity(decorator, node, ctx) {
+    addInferredOption(decorator, node, ctx, {
+        option: 'entity',
+        satisfiedBy: ['entity'],
+        infer: (t) => {
+            const target = relationTargetFor(t, ctx.checker);
+            return target && `() => ${target}`;
+        },
+    });
+}
+/**
+ * Drops `declare` from a decorated field. A `declare` field emits nothing, so the standard spec has
+ * nothing to decorate and rejects it ("Decorators are not valid here"). Legacy decorators tolerated it
+ * because they only ever reached the class through `target.constructor`.
+ */
+function dropDeclare(node, ctx) {
+    const modifier = node.modifiers?.find((m) => m.kind === ts.SyntaxKind.DeclareKeyword);
+    if (modifier) {
+        // Through the whitespace that followed it, rather than a fixed one character: two spaces or a line
+        // break left the rest behind.
+        const text = node.getSourceFile().text;
+        let end = modifier.getEnd();
+        while (/\s/.test(text[end] ?? '')) {
+            end += 1;
+        }
+        ctx.edits.push({ start: modifier.getStart(), end, text: '' });
+    }
+}
+/**
+ * Unwraps `Relation<Company>` to `Company`. The alias is `type Relation<T> = T`, and it existed only
+ * because reflection stored the property's type at class-definition time, which forced a real import and
+ * so created the circular-import problem it was working around.
+ */
+function unwrapRelationAlias(node, ctx) {
+    const declared = node.type;
+    if (declared &&
+        ts.isTypeReferenceNode(declared) &&
+        ts.isIdentifier(declared.typeName) &&
+        declared.typeName.text === 'Relation' &&
+        declared.typeArguments?.length === 1) {
+        ctx.edits.push({ start: declared.getStart(), end: declared.getEnd(), text: declared.typeArguments[0].getText() });
+        ctx.relationAlias.unwrapped += 1;
+    }
+}
+/** Counts `Relation<T>` wherever it appears, including the places this codemod does not rewrite. */
+function countRelationAlias(node, ctx) {
+    if (ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName) && node.typeName.text === 'Relation') {
+        ctx.relationAlias.seen += 1;
+    }
+}
+/**
+ * Rewrites an `@InjectQuerier()` parameter into a `currentQuerier()` call.
+ *
+ * The standard spec has no parameter decorators, so the querier travels through async-local storage and
+ * is read inside the body. Only the plain shape is rewritten - a named parameter in a method with a body.
+ * A default value or a destructured parameter is reported: the author was doing something the codemod
+ * would have to guess at.
+ */
+function rewriteInjectQuerier(method, ctx) {
+    for (const parameter of method.parameters) {
+        if (!ts.getDecorators(parameter)?.some((d) => decoratorName(d) === 'InjectQuerier')) {
+            continue;
+        }
+        if (!method.body || !ts.isIdentifier(parameter.name) || parameter.initializer) {
+            ctx.unresolved.push(`${ctx.describe(parameter)}: cannot rewrite this '@InjectQuerier()' parameter`);
+            continue;
+        }
+        ctx.edits.push(removeFromList(method.parameters, parameter, method.getSourceFile()));
+        // The querier is read at the top of the body, keeping the name the parameter had.
+        const body = method.body;
+        const first = body.statements[0];
+        const indent = first ? ' '.repeat(first.getStart() - body.getSourceFile().getLineStarts()[ctx.lineOf(first)]) : '';
+        ctx.edits.push({
+            start: body.getStart() + 1,
+            end: body.getStart() + 1,
+            text: `\n${indent}const ${parameter.name.text} = currentQuerier();`,
+        });
+        ctx.imports.add('currentQuerier');
+    }
+}
+/** Removes a statement together with the rest of its line, so nothing is left blank behind it. */
+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: '' };
+}
+/**
+ * Brings the file's imports in line with what the rewrites left behind, in one pass:
+ *
+ * - `import 'reflect-metadata'` goes, since the polyfill only ever fed `design:type`.
+ * - `InjectQuerier` goes with it, and its import would otherwise not compile: the standard spec has no
+ *   parameter decorators, so `uql-orm` no longer exports one.
+ * - whatever a rewrite needs (`currentQuerier`) is added, extending an existing `uql-orm` import rather
+ *   than adding a second one.
+ *
+ * One function because all three edit the same statements, and doing them separately meant an import
+ * could be dropped and re-added, or a name added to a statement another edit had already removed.
+ */
+function reconcileImports(source, ctx) {
+    // Dropping runs first and hands over the `uql-orm` import it left standing: adding a name to a
+    // statement the other pass had already removed is the bug that made these one step to begin with.
+    addNeededImports(source, ctx, dropDeadImports(source, ctx));
+}
+/** Names `uql-orm` no longer exports. `Relation` joins them only when every usage was rewritten. */
+function deadImportNames(source, ctx) {
+    const { seen, unwrapped } = ctx.relationAlias;
+    if (seen > unwrapped) {
+        ctx.unresolved.push(`${source.fileName}: ${seen - unwrapped} 'Relation<T>' reference(s) are somewhere this codemod does ` +
+            'not rewrite; unwrap them and drop the import by hand');
+    }
+    return new Set(seen > 0 && seen === unwrapped ? ['InjectQuerier', 'Relation'] : ['InjectQuerier']);
+}
+/**
+ * Removes `import 'reflect-metadata'` and any name that no longer exists, and returns the `uql-orm`
+ * named imports still standing - `undefined` when there are none to extend.
+ */
+function dropDeadImports(source, ctx) {
+    const dead = deadImportNames(source, ctx);
+    let host;
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
+            continue;
+        }
+        const module = statement.moduleSpecifier.text;
+        if (module === 'reflect-metadata' && !statement.importClause) {
+            ctx.edits.push(removeStatement(statement));
+            continue;
+        }
+        const named = statement.importClause?.namedBindings;
+        if (!named || !ts.isNamedImports(named)) {
+            continue;
+        }
+        const dropped = named.elements.filter((element) => dead.has(element.name.text));
+        if (dropped.length === named.elements.length && !statement.importClause?.name) {
+            ctx.edits.push(removeStatement(statement));
+            continue;
+        }
+        for (const element of dropped) {
+            ctx.edits.push(removeFromList(named.elements, element, source));
+        }
+        if (module === 'uql-orm') {
+            host = named;
+        }
+    }
+    return host;
+}
+/** Adds what the rewrites need, extending `host` when there is one rather than adding a second import. */
+function addNeededImports(source, ctx, host) {
+    const missing = [...ctx.imports].filter((name) => !host?.elements.some((element) => element.name.text === name));
+    if (!missing.length) {
+        return;
+    }
+    if (host) {
+        const last = host.elements[host.elements.length - 1];
+        ctx.edits.push({ start: last.getEnd(), end: last.getEnd(), text: `, ${missing.join(', ')}` });
+        return;
+    }
+    const position = source.statements[0]?.getStart() ?? 0;
+    ctx.edits.push({ start: position, end: position, text: `import { ${missing.join(', ')} } from 'uql-orm';\n` });
+}
+/** Everything the standard spec needs written onto one decorated property. */
+function rewriteProperty(node, ctx) {
+    const decorators = ts.canHaveDecorators(node) ? (ts.getDecorators(node) ?? []) : [];
+    for (const decorator of decorators) {
+        const name = decoratorName(decorator);
+        if (!name) {
+            continue;
+        }
+        if (FIELD_DECORATORS.has(name)) {
+            addFieldType(decorator, node, ctx);
+        }
+        if (RELATION_DECORATORS.has(name)) {
+            addRelationEntity(decorator, node, ctx);
+        }
+    }
+    if (decorators.length) {
+        dropDeclare(node, ctx);
+    }
+    unwrapRelationAlias(node, ctx);
+}
+/** Names a decorator that no longer exists, wherever it appears. */
+function reportRemovedDecorators(node, ctx) {
+    if (!ts.canHaveDecorators(node)) {
+        return;
+    }
+    for (const decorator of ts.getDecorators(node) ?? []) {
+        const name = decoratorName(decorator);
+        if (name && REMOVED_DECORATORS.has(name)) {
+            ctx.unresolved.push(`${ctx.describe(decorator)}: '@${name}()' was removed; delete it and its import`);
+        }
+    }
+}
+/** Rewrites one source file for the standard decorator spec. */
+export function transformFile(source, checker) {
+    const ctx = {
+        checker,
+        edits: [],
+        unresolved: [],
+        notes: [],
+        imports: new Set(),
+        relationAlias: { seen: 0, unwrapped: 0 },
+        describe: (node) => `${source.fileName}:${ctx.lineOf(node) + 1}`,
+        lineOf: (node) => source.getLineAndCharacterOfPosition(node.getStart()).line,
+    };
+    const visit = (node) => {
+        reportRemovedDecorators(node, ctx);
+        countRelationAlias(node, ctx);
+        if (ts.isPropertyDeclaration(node)) {
+            rewriteProperty(node, ctx);
+        }
+        else if (ts.isMethodDeclaration(node)) {
+            rewriteInjectQuerier(node, ctx);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    reconcileImports(source, ctx);
+    return {
+        fileName: source.fileName,
+        text: applyEdits(source.getFullText(), ctx.edits),
+        changed: ctx.edits.length > 0,
+        unresolved: ctx.unresolved,
+        notes: ctx.notes,
+    };
+}

package/dist/tsconfig.d.ts

@@ -0,0 +1,14 @@
+export type TsconfigResult = {
+    readonly text: string;
+    readonly changed: boolean;
+    /** What the codemod will not decide, each needing a human. */
+    readonly unresolved: readonly string[];
+};
+/**
+ * Rewrites a `tsconfig.json` for the standard decorator spec.
+ *
+ * Edited as text through `ts.parseJsonText`, not by reading and re-serialising: a tsconfig is JSON with
+ * comments and someone's formatting, and rewriting the whole file to change two lines would throw both
+ * away.
+ */
+export declare function transformTsconfig(fileName: string, text: string): TsconfigResult;

package/dist/tsconfig.js

@@ -0,0 +1,48 @@
+import ts from 'typescript';
+import { applyEdits, removeFromList } from './edits.js';
+/** The flags the standard spec has no use for. Their presence is what keeps a project on the old one. */
+const LEGACY_FLAGS = ['experimentalDecorators', 'emitDecoratorMetadata'];
+/**
+ * Rewrites a `tsconfig.json` for the standard decorator spec.
+ *
+ * Edited as text through `ts.parseJsonText`, not by reading and re-serialising: a tsconfig is JSON with
+ * comments and someone's formatting, and rewriting the whole file to change two lines would throw both
+ * away.
+ */
+export function transformTsconfig(fileName, text) {
+    const source = ts.parseJsonText(fileName, text);
+    const root = source.statements[0]?.expression;
+    if (!root || !ts.isObjectLiteralExpression(root)) {
+        return { text, changed: false, unresolved: [`${fileName}: not an object, so nothing was changed`] };
+    }
+    const edits = [];
+    const unresolved = [];
+    const compilerOptions = propertyValue(root, 'compilerOptions');
+    if (compilerOptions && ts.isObjectLiteralExpression(compilerOptions)) {
+        for (const flag of LEGACY_FLAGS) {
+            const property = propertyAssignment(compilerOptions, flag);
+            if (property) {
+                edits.push(removeFromList(compilerOptions.properties, property, source));
+            }
+        }
+        // `target` is reported, not rewritten: removing it silently falls back to the compiler default
+        // (`es5` for `tsc`), and choosing a replacement means guessing which era the project targets.
+        const target = propertyValue(compilerOptions, 'target');
+        if (target && ts.isStringLiteral(target) && target.text.toLowerCase() === 'esnext') {
+            unresolved.push(`${fileName}: 'target' is 'esnext', the one target that emits decorator syntax untransformed. ` +
+                'Change it to any dated target, such as `es2024`.');
+        }
+    }
+    // A value the file inherits cannot be edited here, and silence would read as "there was none".
+    if (propertyValue(root, 'extends') && !edits.length) {
+        unresolved.push(`${fileName}: extends another config, so check the base for 'experimentalDecorators', ` +
+            "'emitDecoratorMetadata' and 'target'.");
+    }
+    return { text: applyEdits(text, edits), changed: edits.length > 0, unresolved };
+}
+function propertyAssignment(object, name) {
+    return object.properties.find((property) => ts.isPropertyAssignment(property) && ts.isStringLiteral(property.name) && property.name.text === name);
+}
+function propertyValue(object, name) {
+    return propertyAssignment(object, name)?.initializer;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "uql-codemod",
+  "description": "Migrates uql-orm entities from legacy decorators to the TC39 standard spec",
+  "license": "MIT",
+  "version": "0.23.0",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "uql-codemod": "./dist/bin.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rimraf dist .tsconfig.tsbuildinfo && tsc -b tsconfig.build.json",
+    "clean": "rimraf dist .tsconfig.tsbuildinfo"
+  },
+  "dependencies": {
+    "typescript": "^6.0.3"
+  },
+  "author": "Roger Padilla",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rogerpadilla/uql.git",
+    "directory": "packages/uql-codemod"
+  },
+  "keywords": [
+    "uql",
+    "codemod",
+    "decorators",
+    "migration"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "3bfca5950ac564b8503fb2140726501b01825b9d"
+}