@cosmicdrift/kumiko-framework 0.334.0 → 0.335.0

package/src/scripts/codemod/unprocessable-error-details-reason.ts

@@ -193,42 +193,99 @@ function processNewExpression(args: readonly Node[], report: (note: string) => v
   return "changed";
 }
 
+// `failUnprocessable(reason, details)` takes the details literal directly as
+// its second argument (no `{ details }` wrapper like the ctor's opts).
+function processFailUnprocessableCall(
+  args: readonly Node[],
+  report: (note: string) => void,
+): CallOutcome {
+  const detailsArg = args[1];
+  if (!detailsArg) return "not-a-match";
+
+  if (!Node.isObjectLiteralExpression(detailsArg)) {
+    report(
+      "second argument (details) is not a statically-analyzable object literal — cannot verify details.reason",
+    );
+    return "skipped";
+  }
+
+  const removal = removeReasonProperty(detailsArg);
+  if (removal.kind === "absent") return "not-a-match";
+  if (removal.kind === "skip") {
+    report(removal.note);
+    return "skipped";
+  }
+  return "changed";
+}
+
 type SkipEntry = { readonly file: string; readonly line: number; readonly note: string };
 
+type MigratableCall = {
+  readonly exportName: "UnprocessableError" | "failUnprocessable";
+  readonly localKind: "class" | "function";
+  readonly process: (args: readonly Node[], report: (note: string) => void) => CallOutcome;
+};
+
+const UNPROCESSABLE_ERROR_CTOR: MigratableCall = {
+  exportName: "UnprocessableError",
+  localKind: "class",
+  process: processNewExpression,
+};
+const FAIL_UNPROCESSABLE_CALL: MigratableCall = {
+  exportName: "failUnprocessable",
+  localKind: "function",
+  process: processFailUnprocessableCall,
+};
+
+function migrateCallSite(
+  sourceFile: SourceFile,
+  importedNames: ReadonlyMap<string, ImportedBinding>,
+  site: Node & { getExpression(): Node; getArguments(): Node[] },
+  target: MigratableCall,
+  skips: SkipEntry[],
+): boolean {
+  const callee = site.getExpression();
+  if (!Node.isIdentifier(callee)) return false;
+  const localName = callee.getText();
+  const line = site.getStartLineNumber();
+  const file = sourceFile.getFilePath();
+
+  const binding = importedNames.get(localName);
+  if (binding?.importedName !== target.exportName) {
+    if (localName !== target.exportName) return false;
+    const note = binding
+      ? `${target.exportName} is imported from "${binding.moduleSpecifier}", not a @cosmicdrift/kumiko-* package`
+      : `${target.exportName} has no @cosmicdrift/kumiko-* import in this file (likely a locally defined ${target.localKind})`;
+    skips.push({ file, line, note });
+    return false;
+  }
+  if (!KUMIKO_MODULE_RE.test(binding.moduleSpecifier)) {
+    skips.push({
+      file,
+      line,
+      note: `${target.exportName} is imported from "${binding.moduleSpecifier}", not a @cosmicdrift/kumiko-* package`,
+    });
+    return false;
+  }
+
+  const outcome = target.process(site.getArguments(), (note) => skips.push({ file, line, note }));
+  return outcome === "changed";
+}
+
 /** Migrates one file in place. Returns how many `reason` properties were removed. */
 function migrateFile(sourceFile: SourceFile, skips: SkipEntry[]): number {
   const importedNames = collectImportedNames(sourceFile);
   let removedCount = 0;
 
   for (const newExpr of sourceFile.getDescendantsOfKind(SyntaxKind.NewExpression)) {
-    const callee = newExpr.getExpression();
-    if (!Node.isIdentifier(callee)) continue;
-    const localName = callee.getText();
-
-    const binding = importedNames.get(localName);
-    const isFrameworkUnprocessableError = binding?.importedName === "UnprocessableError";
-
-    if (!isFrameworkUnprocessableError) {
-      if (localName !== "UnprocessableError") continue;
-      const note = binding
-        ? `UnprocessableError is imported from "${binding.moduleSpecifier}", not a @cosmicdrift/kumiko-* package`
-        : "UnprocessableError has no @cosmicdrift/kumiko-* import in this file (likely a locally defined class)";
-      skips.push({ file: sourceFile.getFilePath(), line: newExpr.getStartLineNumber(), note });
-      continue;
+    if (migrateCallSite(sourceFile, importedNames, newExpr, UNPROCESSABLE_ERROR_CTOR, skips)) {
+      removedCount++;
     }
-    if (!KUMIKO_MODULE_RE.test(binding.moduleSpecifier)) {
-      skips.push({
-        file: sourceFile.getFilePath(),
-        line: newExpr.getStartLineNumber(),
-        note: `UnprocessableError is imported from "${binding.moduleSpecifier}", not a @cosmicdrift/kumiko-* package`,
-      });
-      continue;
+  }
+  for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    if (migrateCallSite(sourceFile, importedNames, call, FAIL_UNPROCESSABLE_CALL, skips)) {
+      removedCount++;
     }
-
-    const outcome = processNewExpression(newExpr.getArguments(), (note) => {
-      skips.push({ file: sourceFile.getFilePath(), line: newExpr.getStartLineNumber(), note });
-    });
-    if (outcome === "changed") removedCount++;
   }
 
   return removedCount;

package/dist/scripts/codemod/crypto-shredding-testing-move.d.ts

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

package/dist/scripts/codemod/crypto-shredding-testing-move.js

@@ -1,109 +0,0 @@
-#!/usr/bin/env bun
-// Rewrites `import { resetPiiSubjectKmsForTests, resetBlindIndexKeyForTests }
-// from "@cosmicdrift/kumiko-framework/crypto"` to import both names from
-// "@cosmicdrift/kumiko-framework/testing" instead (fw#1631). Only the
-// package barrel specifier is rewritten — relative deep-imports of the
-// defining module are left untouched, per the changes.json migration note.
-// Idempotent: an already-migrated file has nothing left to move.
-//
-// Usage: bun scripts/codemod/crypto-shredding-testing-move.ts <targetDir> [--dry-run]
-import { readdirSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { Project } from "ts-morph";
-const OLD_SPECIFIER = "@cosmicdrift/kumiko-framework/crypto";
-const NEW_SPECIFIER = "@cosmicdrift/kumiko-framework/testing";
-const MOVED_NAMES = new Set(["resetPiiSubjectKmsForTests", "resetBlindIndexKeyForTests"]);
-const EXCLUDE_DIRS = new Set(["node_modules", "dist", "build"]);
-function findTargetFiles(rootDir) {
-    // Walk the tree and skip excluded dirs while descending — filtering the
-    // absolute path after a full Glob scan silently no-ops when the repo root
-    // itself contains "/build/" or "/node_modules/" (fw#2289).
-    const files = [];
-    const walk = (dir) => {
-        let entries;
-        try {
-            entries = readdirSync(dir, { withFileTypes: true });
-        }
-        catch {
-            // skip: unreadable directory during walk — treat as empty.
-            return;
-        }
-        for (const ent of entries) {
-            if (ent.isDirectory()) {
-                if (EXCLUDE_DIRS.has(ent.name) || ent.name.startsWith("."))
-                    continue;
-                walk(join(dir, ent.name));
-                continue;
-            }
-            if (ent.isFile() && /\.(ts|tsx)$/.test(ent.name)) {
-                files.push(join(dir, ent.name));
-            }
-        }
-    };
-    walk(rootDir);
-    return files.sort();
-}
-/** Move matching value imports from crypto → testing. Returns count of names moved. */
-function migrateFile(sourceFile) {
-    // Value imports only — a pre-existing `import type { … } from testing`
-    // must not receive runtime helpers (they would be erased).
-    const oldImports = sourceFile
-        .getImportDeclarations()
-        .filter((d) => d.getModuleSpecifierValue() === OLD_SPECIFIER && !d.isTypeOnly());
-    if (oldImports.length === 0)
-        return 0;
-    let fileMoved = 0;
-    for (const oldImport of oldImports) {
-        const movedHere = oldImport.getNamedImports().filter((spec) => MOVED_NAMES.has(spec.getName()));
-        if (movedHere.length === 0)
-            continue;
-        const names = movedHere.map((spec) => spec.getName());
-        const existingNewImport = sourceFile
-            .getImportDeclarations()
-            .find((d) => d.getModuleSpecifierValue() === NEW_SPECIFIER && !d.isTypeOnly());
-        if (existingNewImport) {
-            const already = new Set(existingNewImport.getNamedImports().map((s) => s.getName()));
-            for (const name of names) {
-                if (!already.has(name))
-                    existingNewImport.addNamedImport(name);
-            }
-        }
-        else {
-            sourceFile.addImportDeclaration({ moduleSpecifier: NEW_SPECIFIER, namedImports: names });
-        }
-        for (const spec of movedHere)
-            spec.remove();
-        const remaining = oldImport.getNamedImports().length > 0 ||
-            !!oldImport.getDefaultImport() ||
-            !!oldImport.getNamespaceImport();
-        if (!remaining)
-            oldImport.remove();
-        fileMoved += names.length;
-    }
-    return fileMoved;
-}
-async function main() {
-    const positional = process.argv.slice(2).filter((a) => !a.startsWith("--"));
-    const dryRun = process.argv.includes("--dry-run");
-    const rootDir = resolve(positional[0] ?? process.cwd());
-    const files = findTargetFiles(rootDir);
-    const project = new Project({
-        skipAddingFilesFromTsConfig: true,
-        skipFileDependencyResolution: true,
-    });
-    let touchedFiles = 0;
-    let movedNames = 0;
-    for (const file of files) {
-        const sourceFile = project.addSourceFileAtPath(file);
-        const fileMoved = migrateFile(sourceFile);
-        if (fileMoved === 0)
-            continue;
-        touchedFiles++;
-        movedNames += fileMoved;
-        if (!dryRun)
-            sourceFile.saveSync();
-    }
-    console.log(`\nScanned ${files.length} files under ${rootDir}${dryRun ? " (dry-run)" : ""}.`);
-    console.log(`Touched ${touchedFiles} files, moved ${movedNames} import(s) from "${OLD_SPECIFIER}" to "${NEW_SPECIFIER}".\n`);
-}
-await main();

package/dist/scripts/codemod/migrate-cross-tenant.d.ts

@@ -1,19 +0,0 @@
-#!/usr/bin/env bun
-export interface Rewrite {
-    readonly file: string;
-    readonly line: number;
-    readonly before: string;
-    readonly after: string;
-}
-export interface ManualSite {
-    readonly file: string;
-    readonly line: number;
-    readonly why: string;
-    readonly handlerName?: string;
-}
-export interface MigrateCrossTenantResult {
-    readonly output: string;
-    readonly rewrites: Rewrite[];
-    readonly manual: ManualSite[];
-}
-export declare function migrateCrossTenantSource(source: string, fileName: string): MigrateCrossTenantResult;

package/dist/scripts/codemod/migrate-cross-tenant.js

@@ -1,266 +0,0 @@
-#!/usr/bin/env bun
-// migrate-cross-tenant — rewrites `crossTenant: true` on entity-convention
-// handlers to `escapeHatch: { reason }` where the handler name and verb can
-// be derived from the call, and reports every other site for review (fw#2915).
-//
-// Usage:
-//   bun scripts/codemod/migrate-cross-tenant.ts [--dry-run] <path...>
-import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { Node, Project, SyntaxKind, } from "ts-morph";
-const VERB_IN_NAME_CALLEES = {
-    defineEntityCreateHandler: "create",
-    defineEntityUpdateHandler: "update",
-    defineEntityDeleteHandler: "delete",
-    defineEntityRestoreHandler: "restore",
-    defineEntityListHandler: "list",
-    defineEntityDetailHandler: "detail",
-};
-const VERB_IN_ARG_CALLEES = new Set(["defineEntityWriteHandler", "defineEntityQueryHandler"]);
-const READ_VERBS = new Set(["list", "detail"]);
-function isCrossTenantAssignment(node) {
-    return Node.isPropertyAssignment(node) && node.getName() === "crossTenant";
-}
-function getCalleeName(call) {
-    const expr = call.getExpression();
-    if (Node.isIdentifier(expr))
-        return expr.getText();
-    if (Node.isPropertyAccessExpression(expr))
-        return expr.getName();
-    return undefined;
-}
-function hasEscapeHatchProperty(obj) {
-    return obj.getProperty("escapeHatch") !== undefined;
-}
-function deriveAutoRewriteTarget(objectLiteral) {
-    const call = objectLiteral.getParentIfKind(SyntaxKind.CallExpression);
-    if (!call)
-        return undefined;
-    if (!call.getArguments().includes(objectLiteral))
-        return undefined;
-    const calleeName = getCalleeName(call);
-    if (!calleeName)
-        return undefined;
-    const firstArg = call.getArguments()[0];
-    if (!firstArg || !Node.isStringLiteral(firstArg))
-        return undefined;
-    const firstArgValue = firstArg.getLiteralValue();
-    const verbFromName = VERB_IN_NAME_CALLEES[calleeName];
-    if (verbFromName) {
-        return {
-            handlerName: `${firstArgValue}:${verbFromName}`,
-            entityName: firstArgValue,
-            verb: verbFromName,
-        };
-    }
-    if (VERB_IN_ARG_CALLEES.has(calleeName)) {
-        const sep = firstArgValue.indexOf(":");
-        if (sep === -1)
-            return undefined;
-        const entityName = firstArgValue.slice(0, sep);
-        const verb = firstArgValue.slice(sep + 1);
-        if (!entityName || !verb)
-            return undefined;
-        return { handlerName: firstArgValue, entityName, verb };
-    }
-    return undefined;
-}
-function deriveEntityCrudContext(objectLiteral) {
-    const verbGroupAssignment = objectLiteral.getParent();
-    if (!Node.isPropertyAssignment(verbGroupAssignment))
-        return undefined;
-    const verbGroup = verbGroupAssignment.getName();
-    if (verbGroup !== "write" && verbGroup !== "read")
-        return undefined;
-    const optionsObject = verbGroupAssignment.getParentIfKind(SyntaxKind.ObjectLiteralExpression);
-    const call = optionsObject?.getParentIfKind(SyntaxKind.CallExpression);
-    if (!call || !optionsObject || !call.getArguments().includes(optionsObject))
-        return undefined;
-    const calleeName = getCalleeName(call);
-    if (calleeName !== "registerEntityCrud" && calleeName !== "crud")
-        return undefined;
-    const args = call.getArguments();
-    const entityArg = calleeName === "crud" ? args[0] : args[1];
-    const entityName = entityArg && Node.isStringLiteral(entityArg) ? entityArg.getLiteralValue() : undefined;
-    return `under ${calleeName}(${entityName ? `"${entityName}", ` : ""}...) → ${verbGroup}: multiple verbs share this crossTenant — set escapeHatch per verb manually, one reason each`;
-}
-function classifyManualReason(objectLiteral) {
-    const entityCrudWhy = deriveEntityCrudContext(objectLiteral);
-    if (entityCrudWhy)
-        return entityCrudWhy;
-    const call = objectLiteral.getParentIfKind(SyntaxKind.CallExpression);
-    if (!call?.getArguments().includes(objectLiteral)) {
-        return "crossTenant is not set directly in a handler call (e.g. a spread/shared object) — give each consuming handler its own escapeHatch reason";
-    }
-    const calleeName = getCalleeName(call);
-    if (!calleeName || (!VERB_IN_NAME_CALLEES[calleeName] && !VERB_IN_ARG_CALLEES.has(calleeName))) {
-        return `call \`${calleeName ?? "<unknown>"}\` is not a recognized entity-convention handler factory — add escapeHatch manually`;
-    }
-    return "handler name/verb could not be derived from the call's first argument — add escapeHatch manually";
-}
-function deriveBestEffortHandlerName(assignment) {
-    const call = assignment.getFirstAncestorByKind(SyntaxKind.CallExpression);
-    const firstArg = call?.getArguments()[0];
-    return firstArg && Node.isStringLiteral(firstArg) ? firstArg.getLiteralValue() : undefined;
-}
-function buildEscapeHatchReason(target) {
-    const verbKind = READ_VERBS.has(target.verb) ? "reads" : "writes";
-    return `${target.handlerName} ${verbKind} ${target.entityName} rows across every tenant (migrated from crossTenant: true; state the operator use case here)`;
-}
-export function migrateCrossTenantSource(source, fileName) {
-    const project = new Project({ useInMemoryFileSystem: true, skipFileDependencyResolution: true });
-    const sourceFile = project.createSourceFile(fileName, source);
-    const targets = sourceFile
-        .getDescendantsOfKind(SyntaxKind.PropertyAssignment)
-        .filter(isCrossTenantAssignment);
-    const rewrites = [];
-    const manual = [];
-    for (const assignment of targets) {
-        if (assignment.wasForgotten())
-            continue;
-        const line = assignment.getStartLineNumber();
-        const init = assignment.getInitializer();
-        if (init?.getKind() === SyntaxKind.FalseKeyword)
-            continue;
-        if (init?.getKind() !== SyntaxKind.TrueKeyword) {
-            manual.push({
-                file: fileName,
-                line,
-                why: `crossTenant is not a literal boolean (\`${init?.getText() ?? "<missing>"}\`) — replace manually with escapeHatch: { reason }`,
-                ...(deriveBestEffortHandlerName(assignment) !== undefined && {
-                    handlerName: deriveBestEffortHandlerName(assignment),
-                }),
-            });
-            continue;
-        }
-        const objectLiteral = assignment.getParentIfKind(SyntaxKind.ObjectLiteralExpression);
-        if (!objectLiteral)
-            continue;
-        if (hasEscapeHatchProperty(objectLiteral)) {
-            manual.push({
-                file: fileName,
-                line,
-                why: "this object already declares escapeHatch — merge the two manually and remove crossTenant",
-                ...(deriveBestEffortHandlerName(assignment) !== undefined && {
-                    handlerName: deriveBestEffortHandlerName(assignment),
-                }),
-            });
-            continue;
-        }
-        const target = deriveAutoRewriteTarget(objectLiteral);
-        if (!target) {
-            manual.push({
-                file: fileName,
-                line,
-                why: classifyManualReason(objectLiteral),
-                ...(deriveBestEffortHandlerName(assignment) !== undefined && {
-                    handlerName: deriveBestEffortHandlerName(assignment),
-                }),
-            });
-            continue;
-        }
-        const before = assignment.getText();
-        const after = `escapeHatch: { reason: ${JSON.stringify(buildEscapeHatchReason(target))} }`;
-        assignment.replaceWithText(after);
-        rewrites.push({ file: fileName, line, before, after });
-    }
-    return { output: sourceFile.getFullText(), rewrites, manual };
-}
-class CliError extends Error {
-}
-function parseArgs(argv) {
-    let dryRun = false;
-    const paths = [];
-    for (const arg of argv) {
-        if (arg === "--dry-run") {
-            dryRun = true;
-            continue;
-        }
-        if (arg.startsWith("--"))
-            throw new CliError(`unknown flag: ${arg}`);
-        paths.push(arg);
-    }
-    if (paths.length === 0)
-        throw new CliError("at least one path is required");
-    return { dryRun, paths };
-}
-function isMigratableFile(name) {
-    return /\.(ts|tsx)$/.test(name);
-}
-function walkDir(dir, out) {
-    for (const name of readdirSync(dir)) {
-        if (name === "node_modules")
-            continue;
-        const full = join(dir, name);
-        const stat = statSync(full);
-        if (stat.isDirectory()) {
-            walkDir(full, out);
-            continue;
-        }
-        if (isMigratableFile(name))
-            out.push(full);
-    }
-}
-function collectFiles(paths) {
-    const files = [];
-    for (const p of paths) {
-        const abs = resolve(p);
-        const stat = statSync(abs);
-        if (stat.isDirectory())
-            walkDir(abs, files);
-        else if (isMigratableFile(abs))
-            files.push(abs);
-    }
-    return files;
-}
-async function main() {
-    let options;
-    try {
-        options = parseArgs(process.argv.slice(2));
-    }
-    catch (err) {
-        if (err instanceof CliError) {
-            console.error(`[migrate-cross-tenant] ${err.message}`);
-            process.exit(2);
-        }
-        throw err;
-    }
-    const files = collectFiles(options.paths);
-    const allManual = [];
-    let filesChanged = 0;
-    let totalRewrites = 0;
-    for (const file of files) {
-        const before = readFileSync(file, "utf8");
-        if (!before.includes("crossTenant"))
-            continue;
-        const result = migrateCrossTenantSource(before, file);
-        allManual.push(...result.manual);
-        if (result.rewrites.length === 0)
-            continue;
-        filesChanged += 1;
-        totalRewrites += result.rewrites.length;
-        if (options.dryRun) {
-            console.log(`\n=== ${file} (${result.rewrites.length} rewrite(s)) ===`);
-            for (const r of result.rewrites) {
-                console.log(`${file}:${r.line}`);
-                console.log(`- ${r.before}`);
-                console.log(`+ ${r.after}`);
-            }
-        }
-        else {
-            writeFileSync(file, result.output);
-        }
-    }
-    console.log(`\n[migrate-cross-tenant] ${options.dryRun ? "would change" : "changed"} ${filesChanged} file(s); ` +
-        `rewrites: ${totalRewrites}`);
-    if (allManual.length > 0) {
-        console.log(`\n[migrate-cross-tenant] manual review needed (${allManual.length}):`);
-        for (const m of allManual) {
-            console.log(`${m.file}:${m.line}  ${m.handlerName ?? "<unknown>"}  ${m.why}`);
-        }
-    }
-    process.exit(0);
-}
-if (import.meta.main) {
-    await main();
-}

package/dist/scripts/codemod/migrate-db-raw.d.ts

@@ -1,23 +0,0 @@
-#!/usr/bin/env bun
-export type RewriteRule = "global-table" | "own-tenant";
-export interface Rewrite {
-    readonly file: string;
-    readonly line: number;
-    readonly rule: RewriteRule;
-    readonly before: string;
-    readonly after: string;
-}
-export interface ManualSite {
-    readonly file: string;
-    readonly line: number;
-    readonly enclosing: string;
-    readonly text: string;
-}
-export interface MigrateDbRawResult {
-    readonly output: string;
-    readonly rewrites: Rewrite[];
-    readonly manual: ManualSite[];
-}
-export declare function migrateDbRawSource(source: string, fileName: string, opts: {
-    globalTables: ReadonlySet<string>;
-}): MigrateDbRawResult;