@nage-api/compat 1.0.0-beta.2

package/dist/codemods/config-inventory.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * Config blob → `defineConfig` (PLAN.md §23.4) — as a report.
+ *
+ * `docs/migration.md` already reached this conclusion in prose: "mapping your
+ * old configuration onto this is the least mechanical part of the whole
+ * migration, and it is worth doing by hand rather than transliterating". The
+ * reason is that the legacy shape carries less information than the new one
+ * needs. `env.get<string>('DATABASE_URL')` is a cast, not a check, so the source
+ * says nothing about whether the value is required, what it must look like, or
+ * what happens when it is absent — and those three answers *are* the zod schema.
+ *
+ * What a machine can do is the tedious half: find every variable the application
+ * reads, wherever it reads it from, so the schema is written against a list
+ * rather than against memory. That is what this produces — one note per distinct
+ * variable, at its first use, plus a note at each site where a default is
+ * hiding a misconfiguration.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configInventoryCodemod = void 0;
+const types_js_1 = require("./types.js");
+/** `process.env.NAME` and `process.env['NAME']`. */
+const PROCESS_ENV = /process\s*\.\s*env\s*(?:\.\s*([A-Za-z_][\w]*)|\[\s*['"]([^'"]+)['"]\s*\])/g;
+/** The `EnvironmentManager` singleton: `env.get<string>('NAME')` (§4.4). */
+const ENV_MANAGER = /\benv(?:Manager)?\s*\.\s*get\s*(?:<[^>]*>)?\s*\(\s*['"]([^'"]+)['"]/g;
+/** `registerAs('jwt', …)` — the namespaces that become `defineConfig` keys. */
+const REGISTER_AS = /\bregisterAs\s*\(\s*['"]([^'"]+)['"]/g;
+/** `configService.get('jwt.secret')` — a string path with no type behind it. */
+const CONFIG_GET = /\bconfig(?:Service)?\s*\.\s*get\s*(?:<[^>]*>)?\s*\(\s*['"]([^'"]+)['"]/g;
+/** `parseInt(process.env.PORT) || 3000` and `process.env.X || 'default'`. */
+const DEFAULTED = /process\s*\.\s*env\s*(?:\.\s*[A-Za-z_][\w]*|\[[^\]]*\])[^\n]*?(?:\|\||\?\?)/;
+const NUMERIC_COERCION = /\b(?:parseInt|parseFloat|Number)\s*\(\s*process\s*\.\s*env/;
+exports.configInventoryCodemod = {
+    name: 'config-inventory',
+    kind: 'report',
+    section: '§23.4, §11',
+    summary: 'Inventories every environment variable and config namespace the application reads — the input to `env.schema.ts` and `defineConfig`.',
+    run(files) {
+        const notes = [];
+        const seenVariables = new Set();
+        const seenNamespaces = new Set();
+        for (const file of files) {
+            if (!(0, types_js_1.isSourceFile)(file.path))
+                continue;
+            file.content.split('\n').forEach((line, index) => {
+                if ((0, types_js_1.isCommented)(line))
+                    return;
+                const at = { path: file.path, line: index + 1 };
+                for (const [, dotted, bracketed] of line.matchAll(PROCESS_ENV)) {
+                    const variable = dotted ?? bracketed;
+                    if (variable === undefined || seenVariables.has(variable))
+                        continue;
+                    seenVariables.add(variable);
+                    notes.push({
+                        ...at,
+                        rule: 'env-variable',
+                        message: `\`${variable}\` is read from the environment.`,
+                        action: `Add it to \`EnvSchema\`. Required with no default unless absence is genuinely valid; \`secretSchema\` if it is key material, so a short or missing value fails at boot rather than at first use.`,
+                    });
+                }
+                for (const [, variable] of line.matchAll(ENV_MANAGER)) {
+                    if (variable === undefined || seenVariables.has(variable))
+                        continue;
+                    seenVariables.add(variable);
+                    notes.push({
+                        ...at,
+                        rule: 'env-variable',
+                        message: `\`${variable}\` is read through the \`EnvironmentManager\` singleton, whose \`get<T>()\` casts without checking (§4.4).`,
+                        action: `Add it to \`EnvSchema\`. If it came from AWS Secrets Manager, keep it there with \`secrets: { provider: 'aws' }\` — the SDK stays an optional peer.`,
+                    });
+                }
+                for (const [, namespace] of line.matchAll(REGISTER_AS)) {
+                    if (namespace === undefined || seenNamespaces.has(namespace))
+                        continue;
+                    seenNamespaces.add(namespace);
+                    notes.push({
+                        ...at,
+                        rule: 'config-namespace',
+                        message: `\`registerAs('${namespace}', …)\` declares a configuration namespace.`,
+                        action: `It becomes a key of the object \`defineConfig\` returns, typed rather than a string path. Its factory is where the variables above are read; fold those reads into \`EnvSchema\` and the factory disappears.`,
+                    });
+                }
+                for (const [, path] of line.matchAll(CONFIG_GET)) {
+                    if (path === undefined)
+                        continue;
+                    notes.push({
+                        ...at,
+                        rule: 'config-path',
+                        message: `\`get('${path}')\` reads configuration by string path, so a typo is \`undefined\` at run time.`,
+                        action: 'Inject the typed config object instead; the path becomes a property access the compiler checks.',
+                    });
+                }
+                if (NUMERIC_COERCION.test(line)) {
+                    notes.push({
+                        ...at,
+                        rule: 'silent-coercion',
+                        message: "`parseInt` on an environment variable cannot fail: `parseInt('80o80')` is `80`, so a typo in a deployment variable is indistinguishable from a correct one (§5.1).",
+                        action: '`z.coerce.number()` in the schema rejects it at boot with the variable named.',
+                    });
+                    // `parseInt(process.env.PORT) || 3000` matches both rules and is one
+                    // defect, not two. The coercion is the more specific finding, so it
+                    // wins and the line is not reported twice.
+                    return;
+                }
+                if (DEFAULTED.test(line)) {
+                    notes.push({
+                        ...at,
+                        rule: 'silent-default',
+                        message: 'A default behind `||` or `??` makes an unset variable indistinguishable from a set one — which is why the legacy JWT secret was never replaced (§5.2).',
+                        action: 'Decide deliberately: a default in the schema for something genuinely optional, or no default at all so `loadEnvOrExit` names it and exits non-zero.',
+                    });
+                }
+            });
+        }
+        return { changes: [], notes };
+    },
+};
+//# sourceMappingURL=config-inventory.js.map

package/dist/codemods/env-rename.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The environment-variable rename map (PLAN.md §23.4).
+ *
+ * One entry, because one rename is documented rather than inferred:
+ * `RECAPTCHA_SECRET_KET` was a typo in `libs/recaptcha` (§2.4), so the variable
+ * was never set, the verification request carried `secret=undefined`, and code
+ * that checked only `success` treated every call as a pass. Renaming it is safe
+ * in the strongest sense available — the old name resolves to nothing anywhere,
+ * so no behaviour can depend on it.
+ *
+ * The map is deliberately not padded out. Two renames that look obvious are
+ * notes instead:
+ *
+ *   - `JWT_SECRET` → `JWT_PRIVATE_KEY` is not a rename. HS256 signs with a
+ *     shared secret and RS256 signs with a private key (§28.3); moving the old
+ *     value under the new name produces an application that fails to sign, or
+ *     worse, one that verifies with a key it also hands out.
+ *   - `APP_ENGINE` has no successor at all. One engine per workspace is a
+ *     structural decision (§28.4), not a variable.
+ *
+ * Files: source *and* `.env`, because the variable is named in both and renaming
+ * only one of them is how a migration ends up with a working build and an
+ * unconfigured deployment.
+ */
+import { type Codemod } from './types.js';
+/** Legacy name → current name. Every entry needs evidence in PLAN.md. */
+export declare const ENV_RENAMES: Readonly<Record<string, string>>;
+interface EnvNote {
+    readonly variable: string;
+    readonly message: string;
+    readonly action: string;
+}
+export declare const ENV_NOTES: readonly EnvNote[];
+export declare const envRenameCodemod: Codemod;
+export {};
+//# sourceMappingURL=env-rename.d.ts.map

package/dist/codemods/env-rename.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * The environment-variable rename map (PLAN.md §23.4).
+ *
+ * One entry, because one rename is documented rather than inferred:
+ * `RECAPTCHA_SECRET_KET` was a typo in `libs/recaptcha` (§2.4), so the variable
+ * was never set, the verification request carried `secret=undefined`, and code
+ * that checked only `success` treated every call as a pass. Renaming it is safe
+ * in the strongest sense available — the old name resolves to nothing anywhere,
+ * so no behaviour can depend on it.
+ *
+ * The map is deliberately not padded out. Two renames that look obvious are
+ * notes instead:
+ *
+ *   - `JWT_SECRET` → `JWT_PRIVATE_KEY` is not a rename. HS256 signs with a
+ *     shared secret and RS256 signs with a private key (§28.3); moving the old
+ *     value under the new name produces an application that fails to sign, or
+ *     worse, one that verifies with a key it also hands out.
+ *   - `APP_ENGINE` has no successor at all. One engine per workspace is a
+ *     structural decision (§28.4), not a variable.
+ *
+ * Files: source *and* `.env`, because the variable is named in both and renaming
+ * only one of them is how a migration ends up with a working build and an
+ * unconfigured deployment.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.envRenameCodemod = exports.ENV_NOTES = exports.ENV_RENAMES = void 0;
+const types_js_1 = require("./types.js");
+/** Legacy name → current name. Every entry needs evidence in PLAN.md. */
+exports.ENV_RENAMES = {
+    RECAPTCHA_SECRET_KET: 'RECAPTCHA_SECRET_KEY',
+};
+exports.ENV_NOTES = [
+    {
+        variable: 'RECAPTCHA_SECRET_KET',
+        message: 'The secret behind this variable travelled in a GET query string, so it is in every proxy and access log that saw a verification.',
+        action: 'Rotate it. Renaming the variable does not un-log the old value.',
+    },
+    {
+        variable: 'JWT_SECRET',
+        message: 'HS256 signs with a shared secret; @nage-api/auth signs with an RS256 private key (§28.3). These are different kinds of material, not the same value under a new name.',
+        action: 'Generate a key pair, set `JWT_PRIVATE_KEY`, and run the dual-verify window in §23.3 phase 4 until the refresh tokens issued under the old secret have cycled out.',
+    },
+    {
+        variable: 'APP_ENGINE',
+        message: 'Engine selection at run time is gone: a workspace installs one driver (§28.4), so both engines are no longer in the build.',
+        action: 'Delete the variable and pick the engine. If the answer is Mongo, note that @nage-api/data-mongo is not written yet.',
+    },
+];
+function isEnvFile(path) {
+    const name = path.split(/[/\\]/).pop() ?? '';
+    return name === '.env' || name.startsWith('.env.');
+}
+/** Whole-word: `RECAPTCHA_SECRET_KET` must not match inside a longer name. */
+function wordPattern(name) {
+    return new RegExp(`(?<![\\w$])${name}(?![\\w$])`, 'g');
+}
+exports.envRenameCodemod = {
+    name: 'env-rename',
+    kind: 'rewrite',
+    section: '§23.4',
+    summary: 'Renames the one documented legacy environment variable, and reports the two that look renameable and are not.',
+    run(files) {
+        const changes = [];
+        const notes = [];
+        for (const file of files) {
+            if (!(0, types_js_1.isSourceFile)(file.path) && !isEnvFile(file.path))
+                continue;
+            const lines = file.content.split('\n');
+            const edits = [];
+            const rewritten = lines.map((line, index) => {
+                if ((0, types_js_1.isCommented)(line))
+                    return line;
+                let next = line;
+                for (const [from, to] of Object.entries(exports.ENV_RENAMES)) {
+                    next = next.replace(wordPattern(from), to);
+                }
+                if (next !== line)
+                    edits.push({ line: index + 1, before: line.trim(), after: next.trim() });
+                return next;
+            });
+            if (edits.length > 0) {
+                changes.push({ path: file.path, content: rewritten.join('\n'), edits });
+            }
+            lines.forEach((line, index) => {
+                if ((0, types_js_1.isCommented)(line))
+                    return;
+                for (const note of exports.ENV_NOTES) {
+                    if (!wordPattern(note.variable).test(line))
+                        continue;
+                    notes.push({
+                        path: file.path,
+                        line: index + 1,
+                        rule: note.variable,
+                        message: note.message,
+                        action: note.action,
+                    });
+                }
+            });
+        }
+        return { changes, notes };
+    },
+};
+//# sourceMappingURL=env-rename.js.map

package/dist/codemods/import-paths.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Import-path rewrites (PLAN.md §23.4, and the table in `docs/migration.md`).
+ *
+ * Two specifiers are rewritten, and only when every name on the import is one
+ * this repository can vouch for:
+ *
+ *   - `…/core.responses` → `@nage-api/compat`, for `Result`/`Created`/`ErrorResponse`.
+ *     Certain because `@nage-api/compat` is what supplies the replacement: the names,
+ *     the arity and the body are this package's own.
+ *   - `…/core.decorators` → `@nage-api/core`, for the four version decorators.
+ *     Certain because §16.2 retained them deliberately, under the same names and
+ *     the same call shapes.
+ *
+ * Everything else in the §22 table is a **note**. The reasons differ and each is
+ * given at the call site, but they reduce to three:
+ *
+ *   - the legacy module has no single successor (`@core/sql` becomes `@nage-api/data`
+ *     *and* `@nage-api/data-sql`, split by symbol);
+ *   - the successor is not written yet (`@nage-api/data-mongo`, the notify channels);
+ *   - the names survive but the meanings do not. `NotFoundError` and
+ *     `ValidationError` exist in both frameworks, so repointing that import
+ *     compiles — and changes the status code and the error code the client sees.
+ *     A rewrite whose failure mode is a *passing* build is exactly the rewrite
+ *     not to make.
+ */
+import { type Codemod } from './types.js';
+interface RewriteRule {
+    readonly rule: string;
+    readonly matches: (specifier: string) => boolean;
+    readonly to: string;
+    /** Only these names may travel; anything else keeps the old import. */
+    readonly names: readonly string[];
+    readonly heldBack: string;
+}
+interface ReportRule {
+    readonly rule: string;
+    readonly matches: (specifier: string) => boolean;
+    readonly message: string;
+    readonly action: string;
+}
+export declare const REWRITE_RULES: readonly RewriteRule[];
+export declare const REPORT_RULES: readonly ReportRule[];
+export declare const importPathsCodemod: Codemod;
+export {};
+//# sourceMappingURL=import-paths.d.ts.map

package/dist/codemods/import-paths.js

@@ -0,0 +1,247 @@
+"use strict";
+/**
+ * Import-path rewrites (PLAN.md §23.4, and the table in `docs/migration.md`).
+ *
+ * Two specifiers are rewritten, and only when every name on the import is one
+ * this repository can vouch for:
+ *
+ *   - `…/core.responses` → `@nage-api/compat`, for `Result`/`Created`/`ErrorResponse`.
+ *     Certain because `@nage-api/compat` is what supplies the replacement: the names,
+ *     the arity and the body are this package's own.
+ *   - `…/core.decorators` → `@nage-api/core`, for the four version decorators.
+ *     Certain because §16.2 retained them deliberately, under the same names and
+ *     the same call shapes.
+ *
+ * Everything else in the §22 table is a **note**. The reasons differ and each is
+ * given at the call site, but they reduce to three:
+ *
+ *   - the legacy module has no single successor (`@core/sql` becomes `@nage-api/data`
+ *     *and* `@nage-api/data-sql`, split by symbol);
+ *   - the successor is not written yet (`@nage-api/data-mongo`, the notify channels);
+ *   - the names survive but the meanings do not. `NotFoundError` and
+ *     `ValidationError` exist in both frameworks, so repointing that import
+ *     compiles — and changes the status code and the error code the client sees.
+ *     A rewrite whose failure mode is a *passing* build is exactly the rewrite
+ *     not to make.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importPathsCodemod = exports.REPORT_RULES = exports.REWRITE_RULES = void 0;
+const types_js_1 = require("./types.js");
+/** `…/core.responses`, `…/core.responses.js`, `@core/core.responses`, … */
+function moduleNamed(name) {
+    const pattern = new RegExp(`(?:^|[/\\\\])${name.replace('.', '\\.')}(?:\\.(?:js|ts))?$`);
+    return (specifier) => pattern.test(specifier);
+}
+function exactly(specifier) {
+    return (candidate) => candidate === specifier;
+}
+exports.REWRITE_RULES = [
+    {
+        rule: 'core.responses',
+        matches: moduleNamed('core.responses'),
+        to: '@nage-api/compat',
+        names: ['Result', 'Created', 'ErrorResponse'],
+        heldBack: 'the rest of `core.responses.ts` — the Swagger definitions and the upload helpers — has no equivalent in @nage-api/compat',
+    },
+    {
+        rule: 'core.decorators',
+        matches: moduleNamed('core.decorators'),
+        to: '@nage-api/core',
+        names: ['ForVersion', 'FromVersion', 'TillVersion', 'BetweenVersions'],
+        heldBack: '`FileUploads`, `MsListener` and `MsEventListener` are not retained: uploads moved to @nage-api/storage and the microservice bus was redesigned as @nage-api/queue (§23 "the job bus and the sockets are redesigns")',
+    },
+];
+exports.REPORT_RULES = [
+    {
+        rule: 'core.errors',
+        matches: moduleNamed('core.errors'),
+        message: '`NotFoundError` and `ValidationError` exist in @nage-api/core under the same names, with different constructors and a stable `error.code` the client now sees.',
+        action: 'Repoint by hand, one throw site at a time, checking the status and code each one now produces (§17.1). A blanket rewrite would compile and change the API.',
+    },
+    {
+        rule: 'core.job',
+        matches: moduleNamed('core.job'),
+        message: '`Job` is now `Job<TEntity, TBody, TParams>` from @nage-api/core (§13).',
+        action: 'Import it from @nage-api/core and supply the entity. `Job<Order>` compiles against both frameworks and means different things in each, so this is not a rewrite.',
+    },
+    {
+        rule: '@core/sql',
+        matches: exactly('@core/sql'),
+        message: '`libs/sql` splits by symbol across two packages.',
+        action: '`ModelService`, `parseQuery` and `defineQueryPolicy` come from @nage-api/data; the Sequelize binding comes from @nage-api/data-sql.',
+    },
+    {
+        rule: '@core/mongo',
+        matches: exactly('@core/mongo'),
+        message: '@nage-api/data-mongo is not written. This is blocking for a MongoDB application.',
+        action: 'Port everything above the data layer, then stop; or move the application to the SQL driver. See `docs/migration.md` → "What has no equivalent yet".',
+    },
+    {
+        rule: '@core/email',
+        matches: exactly('@core/email'),
+        message: '@nage-api/notify has the shape of the legacy notification module but ships no email channel.',
+        action: 'Supply a `NotificationChannel` wrapping the mailer you already use. The hardcoded From name and `tls.rejectUnauthorized: false` do not come with it.',
+    },
+    {
+        rule: '@core/twilio',
+        matches: exactly('@core/twilio'),
+        message: '@nage-api/notify ships no SMS channel.',
+        action: 'Supply a `NotificationChannel` wrapping the Twilio client you already use.',
+    },
+    {
+        rule: '@core/recaptcha',
+        matches: exactly('@core/recaptcha'),
+        message: '@nage-api/integrations-recaptcha exists, but the verifier is a different class with a different method, and the environment variable was renamed (see the `env-rename` codemod).',
+        action: 'Repoint the import by hand and rotate the secret: the legacy verifier sent it in a GET query string, so it is in every proxy log that saw a verification.',
+    },
+    {
+        rule: '@core/firebase',
+        matches: exactly('@core/firebase'),
+        message: 'No equivalent package.',
+        action: 'Keep using the admin SDK directly, behind a port of your own. Note that the legacy controller dispatched on `this.service[job.action]` with no allow-list (§5.2); do not carry that across.',
+    },
+    {
+        rule: '@core/stripe',
+        matches: exactly('@core/stripe'),
+        message: 'No equivalent package.',
+        action: 'The legacy lib was a bare client holder; construct the client where you need it.',
+    },
+    {
+        rule: '@core/square',
+        matches: exactly('@core/square'),
+        message: 'No equivalent package.',
+        action: 'The legacy lib was a bare client holder; construct the client where you need it.',
+    },
+    {
+        rule: '@core/geocoder',
+        matches: exactly('@core/geocoder'),
+        message: 'No equivalent package.',
+        action: 'Keep `node-geocoder` behind a port of your own.',
+    },
+];
+/**
+ * `import`/`export … from '…'`, including multi-line clauses.
+ *
+ * The clause excludes `;` so a lazy match cannot run past the end of one
+ * statement and pair an earlier `import` with a later `from` — which is what a
+ * `[\s\S]*?` clause does to a side-effect import (`import 'reflect-metadata';`)
+ * followed by a real one.
+ */
+const IMPORT_PATTERN = /\b(?:import|export)\b([^;]*?)\bfrom\s*(['"])([^'"]+)\2/g;
+/** The names an import clause binds, or `undefined` when it binds a namespace. */
+function importedNames(clause) {
+    const braces = /\{([^}]*)\}/.exec(clause);
+    if (braces === null)
+        return undefined;
+    // A default or namespace import alongside the braces: `import Default, { A }`.
+    if (/^\s*(?:type\s+)?[A-Za-z_$][\w$]*\s*,/.test(clause))
+        return undefined;
+    if (clause.includes('*'))
+        return undefined;
+    return (braces[1] ?? '')
+        .split(',')
+        .map((entry) => entry
+        .trim()
+        .replace(/^type\s+/, '')
+        .split(/\s+as\s+/)[0]
+        ?.trim() ?? '')
+        .filter((name) => name.length > 0);
+}
+function lineOf(content, index) {
+    let line = 1;
+    for (let position = 0; position < index; position += 1) {
+        if (content[position] === '\n')
+            line += 1;
+    }
+    return line;
+}
+function lineText(content, index) {
+    const start = content.lastIndexOf('\n', index) + 1;
+    const end = content.indexOf('\n', index);
+    return content.slice(start, end === -1 ? content.length : end);
+}
+function runOnFile(file) {
+    const notes = [];
+    const edits = [];
+    let content = file.content;
+    // Offsets shift as the content is spliced, so matches are collected against
+    // the original text first and applied from the end backwards.
+    const matches = [...file.content.matchAll(IMPORT_PATTERN)];
+    for (const match of matches.reverse()) {
+        const index = match.index;
+        const clause = match[1] ?? '';
+        const specifier = match[3] ?? '';
+        const line = lineOf(file.content, index);
+        if ((0, types_js_1.isCommented)(lineText(file.content, index)))
+            continue;
+        const rewrite = exports.REWRITE_RULES.find((candidate) => candidate.matches(specifier));
+        if (rewrite !== undefined) {
+            const names = importedNames(clause);
+            const unsupported = names === undefined ? undefined : names.filter((name) => !rewrite.names.includes(name));
+            if (names !== undefined && unsupported?.length === 0) {
+                const quote = match[2] ?? "'";
+                const specifierStart = file.content.lastIndexOf(`${quote}${specifier}${quote}`, index + match[0].length);
+                // The specifier's own line, not the `import` keyword's: a multi-line
+                // clause puts them several lines apart, and a diff that points at the
+                // wrong one is a diff nobody can check.
+                const before = lineText(file.content, specifierStart);
+                content =
+                    content.slice(0, specifierStart) +
+                        `${quote}${rewrite.to}${quote}` +
+                        content.slice(specifierStart + specifier.length + 2);
+                edits.push({
+                    line: lineOf(file.content, specifierStart),
+                    before: before.trim(),
+                    after: before.replace(specifier, rewrite.to).trim(),
+                });
+                continue;
+            }
+            notes.push({
+                path: file.path,
+                line,
+                rule: rewrite.rule,
+                message: names === undefined
+                    ? `\`${specifier}\` is imported as a default or namespace, so which names travel to ${rewrite.to} cannot be read off the import.`
+                    : `\`${(unsupported ?? []).join('`, `')}\` from \`${specifier}\` cannot move to ${rewrite.to}: ${rewrite.heldBack}.`,
+                action: names === undefined
+                    ? `Split it into a named import; the rewrite then covers ${rewrite.names.join(', ')}.`
+                    : `Move ${rewrite.names.join(', ')} in a separate import — this codemod will then rewrite it — and port the rest by hand.`,
+            });
+            continue;
+        }
+        const report = exports.REPORT_RULES.find((candidate) => candidate.matches(specifier));
+        if (report !== undefined) {
+            notes.push({
+                path: file.path,
+                line,
+                rule: report.rule,
+                message: report.message,
+                action: report.action,
+            });
+        }
+    }
+    return {
+        ...(edits.length === 0 ? {} : { change: { path: file.path, content, edits: edits.reverse() } }),
+        notes: notes.reverse(),
+    };
+}
+exports.importPathsCodemod = {
+    name: 'import-paths',
+    kind: 'rewrite',
+    section: '§23.4',
+    summary: 'Repoints the two legacy modules whose successors are name-for-name identical, and reports the eleven that are not.',
+    run(files) {
+        const changes = [];
+        const notes = [];
+        for (const file of files) {
+            if (!(0, types_js_1.isSourceFile)(file.path))
+                continue;
+            const result = runOnFile(file);
+            if (result.change !== undefined)
+                changes.push(result.change);
+            notes.push(...result.notes);
+        }
+        return { changes, notes };
+    },
+};
+//# sourceMappingURL=import-paths.js.map

package/dist/codemods/job-generics.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `Job` and `ModelService` type parameters (PLAN.md §22, §13) — a report.
+ *
+ * The legacy generics were defeated at the boundary: `body: any`, `records:
+ * any[]`, `payload: any` on `core.job.ts`, so `ModelService<M>` knew the model
+ * and the job handed it `any` anyway (§5.1). The new `Job<TEntity, TBody,
+ * TParams>` types every member against the entity.
+ *
+ * Supplying those arguments is not a text transform. Which entity a job is about
+ * is a fact about the surrounding module — often about which repository is
+ * injected three classes away — and getting it wrong produces code that compiles
+ * and lies. So this locates the sites and names what each one needs; the 146
+ * `any`s §5.1 counted are a list to work through, not a diff to approve.
+ */
+import { type Codemod } from './types.js';
+export declare const jobGenericsCodemod: Codemod;
+//# sourceMappingURL=job-generics.d.ts.map

package/dist/codemods/job-generics.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * `Job` and `ModelService` type parameters (PLAN.md §22, §13) — a report.
+ *
+ * The legacy generics were defeated at the boundary: `body: any`, `records:
+ * any[]`, `payload: any` on `core.job.ts`, so `ModelService<M>` knew the model
+ * and the job handed it `any` anyway (§5.1). The new `Job<TEntity, TBody,
+ * TParams>` types every member against the entity.
+ *
+ * Supplying those arguments is not a text transform. Which entity a job is about
+ * is a fact about the surrounding module — often about which repository is
+ * injected three classes away — and getting it wrong produces code that compiles
+ * and lies. So this locates the sites and names what each one needs; the 146
+ * `any`s §5.1 counted are a list to work through, not a diff to approve.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jobGenericsCodemod = void 0;
+const types_js_1 = require("./types.js");
+const PROBES = [
+    {
+        rule: 'job-any',
+        pattern: /\bJob\s*<\s*any\b/,
+        message: '`Job<any>` re-erases exactly what the new contract types.',
+        action: 'Supply the entity: `Job<Order>`. `TBody` defaults to `DeepPartial<TEntity>` and `TParams` to the route parameters, so most sites need one argument.',
+    },
+    {
+        rule: 'job-untyped',
+        pattern: /:\s*Job\s*(?:[,);=]|$)/,
+        message: '`Job` with no type argument. In the new contract the entity is required.',
+        action: 'Supply the entity the handler operates on.',
+    },
+    {
+        rule: 'service-any',
+        pattern: /\b(?:ModelService|SqlService|MongoService)\s*<\s*any\b/,
+        message: 'The base service is generic over the model; `any` here removes the type safety the class was written for.',
+        action: 'Supply the entity. `ModelService` in @nage-api/data keeps the `doBefore*`/`doAfter*` hook names, so the port is the type argument plus the import.',
+    },
+    {
+        rule: 'payload-any',
+        pattern: /\b(?:body|payload|records|owner|result)\s*[?]?\s*:\s*any\b/,
+        message: 'One of the four members that defeated the legacy generics (`body`, `payload`, `records`, `owner`).',
+        action: 'Type it against the entity or the DTO. `strict: true` will surface whatever the `any` was hiding; that is the migration working, not the migration failing (§23.2).',
+    },
+];
+exports.jobGenericsCodemod = {
+    name: 'job-generics',
+    kind: 'report',
+    section: '§22, §13',
+    summary: 'Locates the `any`s that defeated the legacy `Job`/`ModelService` generics.',
+    run(files) {
+        const notes = [];
+        for (const file of files) {
+            if (!(0, types_js_1.isSourceFile)(file.path))
+                continue;
+            file.content.split('\n').forEach((line, index) => {
+                if ((0, types_js_1.isCommented)(line))
+                    return;
+                for (const probe of PROBES) {
+                    if (!probe.pattern.test(line))
+                        continue;
+                    notes.push({
+                        path: file.path,
+                        line: index + 1,
+                        rule: probe.rule,
+                        message: probe.message,
+                        action: probe.action,
+                    });
+                }
+            });
+        }
+        return { changes: [], notes };
+    },
+};
+//# sourceMappingURL=job-generics.js.map

package/dist/codemods/node-fs.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The real filesystem behind `CodemodFileSystem`.
+ *
+ * Separated from the command layer so every test of the command runs against an
+ * in-memory map. The skip list is the same one the CLI's own scanner uses:
+ * walking `node_modules` of a legacy monorepo is minutes of work producing notes
+ * about somebody else's code.
+ */
+import type { CodemodFileSystem } from './cli-main.js';
+export declare function nodeCodemodFs(): CodemodFileSystem;
+//# sourceMappingURL=node-fs.d.ts.map