@cosmicdrift/kumiko-feature-ast 0.0.0-stage → 0.390.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marc Frost
+
+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

@@ -1,3 +1,12 @@
-# Temporary Holding Version
+# @cosmicdrift/kumiko-feature-ast
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Feature-file AST for Kumiko: parse, patch and render feature definitions, plus the pattern library that describes every feature pattern.
+
+## Entry points
+
+- `@cosmicdrift/kumiko-feature-ast` - `parseFeatureFile`, `renderFeatureFile`, the patcher and `PATTERN_LIBRARY`.
+- `@cosmicdrift/kumiko-feature-ast/codemod` - the pipeline codemod (Bun only, uses ts-morph).
+
+## Codemods
+
+The upgrade codemods live in `src/scripts/codemod/`. They run through `kumiko-upgrade` or `kumiko codemod`; you rarely call them directly.

package/dist/codemod/index.d.ts

@@ -0,0 +1,2 @@
+export type { CodemodOptions, CodemodReport, CodemodResult, FileAnalysis, ParsedHandlerInfo, } from "./pipeline-codemod.ts";
+export { analyzeFile, analyzeHandlerArrow, convertFile, generatePerformBlock, runCodemod, scanForCandidates, } from "./pipeline-codemod.ts";

package/dist/codemod/index.js

@@ -0,0 +1 @@
+export { analyzeFile, analyzeHandlerArrow, convertFile, generatePerformBlock, runCodemod, scanForCandidates, } from "./pipeline-codemod.js";

package/dist/codemod/pipeline-codemod.d.ts

@@ -0,0 +1,50 @@
+import { Project } from "ts-morph";
+export type CodemodResult = {
+    readonly filePath: string;
+    readonly status: "converted" | "skipped" | "error";
+    readonly reason?: string;
+};
+export type CodemodReport = {
+    readonly results: readonly CodemodResult[];
+    readonly converted: number;
+    readonly skipped: number;
+    readonly errors: number;
+};
+export type CodemodOptions = {
+    readonly dryRun?: boolean;
+    readonly verbose?: boolean;
+};
+export type GuardConfig = {
+    readonly condition: string;
+    readonly failureReturn: string;
+    readonly successReturn: string;
+};
+export type ParsedHandlerInfo = {
+    readonly handlerBodyText: string;
+    readonly isStaticReturn: boolean;
+    readonly isSimpleExecutorCreate: boolean;
+    readonly isSimpleExecutorUpdate: boolean;
+    readonly hasConditionalLogic: boolean;
+    readonly executorName?: string;
+    readonly executorCreateVar?: string;
+    readonly executorCreateArgs?: string[];
+    readonly executorUpdateVar?: string;
+    readonly isExpressionBodyCreate: boolean;
+    readonly isExpressionBodyUpdate: boolean;
+    readonly expressionBodyArgs: string[] | undefined;
+    readonly isGuardedCreate: boolean;
+    readonly guardConfig: GuardConfig | undefined;
+};
+export declare function analyzeHandlerArrow(arrowText: string): ParsedHandlerInfo;
+export declare function generatePerformBlock(analysis: ParsedHandlerInfo, schemaType: string, indent: string): string | null;
+export declare function scanForCandidates(rootDir: string): FileAnalysis[];
+export type FileAnalysis = {
+    readonly filePath: string;
+    readonly pattern: "free-form-write" | "pipeline-write" | "query-handler" | "other";
+    readonly convertible: boolean;
+    readonly reason: string;
+    readonly handlerLine?: number;
+};
+export declare function analyzeFile(filePath: string): FileAnalysis | null;
+export declare function runCodemod(rootDir: string, options?: CodemodOptions): Promise<CodemodReport>;
+export declare function convertFile(filePath: string, project?: Project, options?: CodemodOptions): Promise<CodemodResult>;

package/dist/codemod/pipeline-codemod.js

@@ -0,0 +1,536 @@
+// biome-ignore-all lint/style/noNonNullAssertion: regex capture-group indexing — match-success implies non-null capture
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { Glob } from "bun";
+import { Node, Project, SyntaxKind } from "ts-morph";
+export function analyzeHandlerArrow(arrowText) {
+    const text = arrowText.trim();
+    let handlerBodyText;
+    let isStaticReturn = false;
+    let isSimpleExecutorCreate = false;
+    let isSimpleExecutorUpdate = false;
+    let hasConditionalLogic = false;
+    let executorName;
+    let executorCreateVar;
+    let executorCreateArgs;
+    let executorUpdateVar;
+    let isExpressionBodyCreate = false;
+    let isExpressionBodyUpdate = false;
+    let expressionBodyArgs;
+    let isGuardedCreate = false;
+    let guardConfig;
+    if (text.startsWith("async (")) {
+        const arrowIdx = text.indexOf("=>");
+        if (arrowIdx === -1) {
+            return {
+                handlerBodyText: text,
+                isStaticReturn: false,
+                isSimpleExecutorCreate: false,
+                isSimpleExecutorUpdate: false,
+                hasConditionalLogic: false,
+                isExpressionBodyCreate: false,
+                isExpressionBodyUpdate: false,
+                expressionBodyArgs: undefined,
+                isGuardedCreate: false,
+                guardConfig: undefined,
+            };
+        }
+        const afterArrow = text.slice(arrowIdx + 2).trim();
+        if (afterArrow.startsWith("(")) {
+            isStaticReturn = true;
+            handlerBodyText = afterArrow;
+        }
+        else if (afterArrow.startsWith("{")) {
+            handlerBodyText = afterArrow;
+            const lines = handlerBodyText
+                .split("\n")
+                .map((l) => l.trim())
+                .filter(Boolean);
+            // Detect conditional logic (if/try/for/while/catch)
+            hasConditionalLogic = lines.some((l) => l.startsWith("if ") ||
+                l.startsWith("try ") ||
+                l.startsWith("for ") ||
+                l.startsWith("while ") ||
+                l.startsWith("} else"));
+            const [, createVar, createExecutor] = handlerBodyText.match(/const\s+(\w+)\s*=\s*await\s+(\w+)\.create\s*\(/) ?? [];
+            const updateMatch = handlerBodyText.match(/const\s+(\w+)\s*=\s*await\s+(\w+)\.update\s*\(/);
+            const hasSimpleReturn = /return\s*\{[^}]*isSuccess:\s*true/.test(handlerBodyText);
+            if (createVar !== undefined &&
+                createExecutor !== undefined &&
+                hasSimpleReturn &&
+                !hasConditionalLogic) {
+                isSimpleExecutorCreate = true;
+                executorName = createExecutor;
+                executorCreateVar = createVar;
+                executorCreateArgs = extractArgs(handlerBodyText, createExecutor, "create");
+            }
+            else if (createVar !== undefined &&
+                createExecutor !== undefined &&
+                hasSimpleReturn &&
+                hasConditionalLogic) {
+                // Try to match the guard pattern: if (!<var>.isSuccess) { return fail } return success
+                const guard = extractGuardedPattern(handlerBodyText, createVar);
+                if (guard) {
+                    isGuardedCreate = true;
+                    guardConfig = guard;
+                    executorName = createExecutor;
+                    executorCreateVar = createVar;
+                    executorCreateArgs = extractArgs(handlerBodyText, createExecutor, "create");
+                }
+            }
+            if (updateMatch &&
+                hasSimpleReturn &&
+                !hasConditionalLogic &&
+                !isSimpleExecutorCreate &&
+                !isGuardedCreate) {
+                isSimpleExecutorUpdate = true;
+                executorName = updateMatch[2];
+                executorUpdateVar = updateMatch[1];
+            }
+        }
+        else {
+            handlerBodyText = afterArrow;
+            // Expression body — check for member-call patterns like
+            // `crud.create(event.payload)` or `crud.update({ id, changes })`.
+            const exprCallMatch = afterArrow.match(/^(\w+)\.(create|update)\s*\(/);
+            if (exprCallMatch) {
+                executorName = exprCallMatch[1];
+                const method = exprCallMatch[2];
+                expressionBodyArgs = extractExprArgs(afterArrow, executorName, method);
+                if (method === "create") {
+                    isExpressionBodyCreate = true;
+                }
+                else {
+                    isExpressionBodyUpdate = true;
+                }
+            }
+            else if (afterArrow.startsWith("(") && afterArrow.endsWith(")")) {
+                isStaticReturn = true;
+            }
+        }
+    }
+    else {
+        handlerBodyText = text;
+    }
+    return {
+        handlerBodyText,
+        isStaticReturn,
+        isSimpleExecutorCreate,
+        isSimpleExecutorUpdate,
+        hasConditionalLogic,
+        executorName,
+        executorCreateVar,
+        executorCreateArgs,
+        executorUpdateVar,
+        isExpressionBodyCreate,
+        isExpressionBodyUpdate,
+        expressionBodyArgs,
+        isGuardedCreate,
+        guardConfig,
+    };
+}
+function extractArgs(body, executorVar, method) {
+    const pattern = new RegExp(`const\\s+\\w+\\s*=\\s*await\\s+${escapeRegex(executorVar)}\\.${method}\\s*\\(`);
+    const match = body.match(pattern);
+    if (!match)
+        return undefined;
+    const startIdx = (match.index ?? 0) + match[0].length;
+    let depth = 1;
+    let endIdx = startIdx;
+    while (endIdx < body.length && depth > 0) {
+        if (body[endIdx] === "(")
+            depth++;
+        else if (body[endIdx] === ")")
+            depth--;
+        if (depth > 0)
+            endIdx++;
+    }
+    const argsStr = body.slice(startIdx, endIdx);
+    return splitTopLevel(argsStr);
+}
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function splitTopLevel(args) {
+    const result = [];
+    let depth = 0;
+    let current = "";
+    for (const ch of args) {
+        if (ch === "(" || ch === "{" || ch === "[")
+            depth++;
+        else if (ch === ")" || ch === "}" || ch === "]")
+            depth--;
+        if (ch === "," && depth === 0) {
+            result.push(current.trim());
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+    }
+    if (current.trim())
+        result.push(current.trim());
+    return result;
+}
+function extractExprArgs(body, executorVar, method) {
+    const escaped = executorVar.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(`${escaped}\\.${method}\\s*\\(`);
+    const match = body.match(pattern);
+    if (!match)
+        return undefined;
+    const startIdx = (match.index ?? 0) + match[0].length;
+    let depth = 1;
+    let endIdx = startIdx;
+    while (endIdx < body.length && depth > 0) {
+        if (body[endIdx] === "(")
+            depth++;
+        else if (body[endIdx] === ")")
+            depth--;
+        if (depth > 0)
+            endIdx++;
+    }
+    const argsStr = body.slice(startIdx, endIdx);
+    return splitTopLevel(argsStr);
+}
+function transpileEventRefs(argsStr) {
+    // Transform `event.<prop>` → `ctx.event.<prop>` inside a resolver fn.
+    // The original handler has `event` as a parameter; inside the pipeline
+    // resolver, `event` lives on `ctx`, not as a standalone binding.
+    // `ctx` references stay as-is (the resolver also receives ctx).
+    return argsStr.replace(/\bevent\./g, "ctx.event.");
+}
+function transpileGuardRefs(body, varName) {
+    // Transform `<var>` → `ctx.steps.result` in guard body text.
+    // The original handler references the executor result via
+    // `result.isSuccess`, `result.error`, `result.data`, or standalone
+    // `return result`. Inside the compute step, executor result lives at
+    // `ctx.steps.result`. `\b` word boundary ensures we only match the
+    // exact variable name.
+    return body.replace(new RegExp(`\\b${escapeRegex(varName)}\\b`, "g"), "ctx.steps.result");
+}
+function extractGuardedPattern(body, varName) {
+    const escaped = escapeRegex(varName);
+    // Match: if (!<varName>.isSuccess) { return ... }
+    const ifOpenPattern = new RegExp(`if\\s*\\(!${escaped}\\.isSuccess\\)\\s*\\{`);
+    const ifOpenMatch = body.match(ifOpenPattern);
+    if (!ifOpenMatch)
+        return undefined;
+    // Extract condition
+    const condPattern = new RegExp(`if\\s*\\((!${escaped}\\.isSuccess)\\)`);
+    const condMatch = body.match(condPattern);
+    if (!condMatch)
+        return undefined;
+    const condition = condMatch[1];
+    // Extract if body (between { and matching })
+    const ifBodyStart = (ifOpenMatch.index ?? 0) + ifOpenMatch[0].length;
+    let depth = 1;
+    let ifBodyEnd = ifBodyStart;
+    while (ifBodyEnd < body.length && depth > 0) {
+        if (body[ifBodyEnd] === "{")
+            depth++;
+        else if (body[ifBodyEnd] === "}")
+            depth--;
+        if (depth > 0)
+            ifBodyEnd++;
+    }
+    const ifBodyContent = body.slice(ifBodyStart, ifBodyEnd).trim();
+    const failRetMatch = ifBodyContent.match(/return\s*([^;]+)\s*;/);
+    if (!failRetMatch)
+        return undefined;
+    const failureReturn = failRetMatch[1].trim();
+    // Extract trailing return after the if block
+    const afterIf = body.slice(ifBodyEnd + 1).trim();
+    const succRetMatch = afterIf.match(/return\s*([^;]+)\s*;/);
+    if (!succRetMatch)
+        return undefined;
+    const successReturn = succRetMatch[1].trim();
+    return { condition, failureReturn, successReturn };
+}
+export function generatePerformBlock(analysis, schemaType, indent) {
+    const steps = [];
+    if (analysis.isStaticReturn) {
+        let body = analysis.handlerBodyText.trim();
+        if (body.startsWith("(") && body.endsWith(")")) {
+            body = body.slice(1, -1);
+        }
+        steps.push(`r.step.return((ctx) => (${body}))`);
+    }
+    else if (analysis.isSimpleExecutorCreate &&
+        analysis.executorName &&
+        analysis.executorCreateArgs) {
+        const dataArg = analysis.executorCreateArgs[0] ?? "{}";
+        steps.push(`r.step.aggregate.create("result", { executor: ${analysis.executorName}, data: (ctx) => ${dataArg} })`);
+        steps.push(`r.step.return((ctx) => ({ isSuccess: true, data: ctx.steps.result }))`);
+    }
+    else if (analysis.isSimpleExecutorUpdate && analysis.executorName) {
+        steps.push(`r.step.aggregate.update("result", { executor: ${analysis.executorName}, id: event.payload.id, changes: event.payload.changes })`);
+        steps.push(`r.step.return((ctx) => ({ isSuccess: true, data: ctx.steps.result }))`);
+    }
+    else if (analysis.isExpressionBodyCreate &&
+        analysis.executorName &&
+        analysis.expressionBodyArgs) {
+        const dataArg = transpileEventRefs(analysis.expressionBodyArgs[0] ?? "{}");
+        steps.push(`r.step.aggregate.create("result", { executor: ${analysis.executorName}, data: (ctx) => ${dataArg} })`);
+        steps.push(`r.step.return((ctx) => ({ isSuccess: true, data: ctx.steps.result }))`);
+    }
+    else if (analysis.isExpressionBodyUpdate &&
+        analysis.executorName &&
+        analysis.expressionBodyArgs) {
+        const argStr = transpileEventRefs(analysis.expressionBodyArgs[0] ?? "{}");
+        steps.push(`r.step.compute("result", (ctx) => ${analysis.executorName}.update(${argStr}))`);
+        steps.push(`r.step.return((ctx) => ({ isSuccess: true, data: ctx.steps.result }))`);
+    }
+    else if (analysis.isGuardedCreate &&
+        analysis.executorName &&
+        analysis.executorCreateArgs &&
+        analysis.guardConfig) {
+        const varName = analysis.executorCreateVar ?? "result";
+        const dataArg = analysis.executorCreateArgs[0] ?? "{}";
+        const guard = analysis.guardConfig;
+        const condition = guard.condition; // already references varName
+        const failureReturn = transpileGuardRefs(guard.failureReturn, varName);
+        const successReturn = transpileGuardRefs(guard.successReturn, varName);
+        // The condition references the original var name — transpile it too
+        const condTranspiled = transpileGuardRefs(condition, varName);
+        steps.push(`r.step.aggregate.create("result", { executor: ${analysis.executorName}, data: (ctx) => ${dataArg} })`);
+        steps.push(`r.step.compute("outcome", (ctx) => {
+      if (${condTranspiled}) {
+        return ${failureReturn};
+      }
+      return ${successReturn};
+    })`);
+        steps.push(`r.step.return((ctx) => ctx.steps.outcome)`);
+    }
+    else {
+        return null;
+    }
+    const stepIndent = indent;
+    const stepsStr = steps.map((s) => `${stepIndent}    ${s}`).join(",\n");
+    const pipelineType = schemaType ? `<${schemaType}, unknown>` : "";
+    return [
+        `perform: stepsPipeline${pipelineType}(({ event, r }) => [`,
+        stepsStr,
+        `  ${stepIndent}]),`,
+    ].join("\n");
+}
+function inferSchemaType(objLiteral) {
+    const schemaProp = objLiteral.getProperty("schema");
+    if (!schemaProp)
+        return "unknown";
+    if (!Node.isPropertyAssignment(schemaProp))
+        return "unknown";
+    const init = schemaProp.getInitializer();
+    if (!init)
+        return "unknown";
+    const text = init.getText();
+    // Only return simple names (like `InvoiceSchema`), not inline definitions
+    if (/^[A-Za-z_$][\w$.]*$/.test(text)) {
+        return `typeof ${text}`;
+    }
+    return ""; // Empty = omit type params
+}
+function findFiles(rootDir) {
+    const glob = new Glob("**/*.write.ts");
+    const files = [];
+    for (const file of glob.scanSync(rootDir)) {
+        files.push(join(rootDir, file));
+    }
+    return files.sort();
+}
+export function scanForCandidates(rootDir) {
+    const files = findFiles(rootDir);
+    const results = [];
+    for (const file of files) {
+        const analysis = analyzeFile(file);
+        if (analysis)
+            results.push(analysis);
+    }
+    return results;
+}
+export function analyzeFile(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const content = readFileSync(filePath, "utf8");
+        if (!content.includes("defineWriteHandler") && !content.includes("defineQueryHandler")) {
+            return null;
+        }
+        if (content.includes("defineWriteHandler") && content.includes("perform:")) {
+            return {
+                filePath,
+                pattern: "pipeline-write",
+                convertible: false,
+                reason: "already_uses_pipeline_form",
+            };
+        }
+        if (content.includes("defineWriteHandler")) {
+            return {
+                filePath,
+                pattern: "free-form-write",
+                convertible: true,
+                reason: "free_form_write_handler",
+            };
+        }
+        if (content.includes("defineQueryHandler")) {
+            return {
+                filePath,
+                pattern: "query-handler",
+                convertible: false,
+                reason: "query_handlers_not_convertible",
+            };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function runCodemod(rootDir, options = {}) {
+    const project = new Project({
+        skipAddingFilesFromTsConfig: true,
+        skipFileDependencyResolution: true,
+    });
+    const candidates = scanForCandidates(rootDir);
+    const writeHandlers = candidates.filter((c) => c.pattern === "free-form-write");
+    console.log(`\n  Scanning ${rootDir}...`);
+    console.log(`  Found ${writeHandlers.length} file(s) with free-form write handlers.\n`);
+    if (writeHandlers.length === 0) {
+        return { results: [], converted: 0, skipped: 0, errors: 0 };
+    }
+    const results = [];
+    for (const candidate of writeHandlers) {
+        const result = await convertFile(candidate.filePath, project, options);
+        results.push(result);
+    }
+    const converted = results.filter((r) => r.status === "converted").length;
+    const skipped = results.filter((r) => r.status === "skipped").length;
+    const errors = results.filter((r) => r.status === "error").length;
+    console.log(`\n  Results: ${converted} converted, ${skipped} skipped, ${errors} errors\n`);
+    if (options.verbose) {
+        for (const r of results) {
+            if (r.status === "error") {
+                console.log(`  ✗ ${relative(process.cwd(), r.filePath)}: ${r.reason}`);
+            }
+            else if (r.status === "converted") {
+                console.log(`  ✓ ${relative(process.cwd(), r.filePath)}`);
+            }
+            else {
+                console.log(`  - ${relative(process.cwd(), r.filePath)}: ${r.reason}`);
+            }
+        }
+    }
+    return { results, converted, skipped, errors };
+}
+function contentHasPipelineImport(content) {
+    // Check the actual import line, not later usage of the word `pipeline`
+    // in the perform block. Single-line import matching only (standard
+    // formatting in this codebase — never multi-line).
+    const importLine = content
+        .split("\n")
+        .find((l) => l.includes("import") && l.includes("@cosmicdrift/kumiko-framework/engine"));
+    return !!importLine && importLine.includes("stepsPipeline");
+}
+function ensurePipelineImport(content) {
+    if (contentHasPipelineImport(content))
+        return null;
+    // Single-line regex is safe — imports in this codebase are always
+    // `import { ... } from "@cosmicdrift/kumiko-framework/engine"`.
+    const importRegex = /import\s*\{([^}]*)\}\s*from\s*["']@cosmicdrift\/kumiko-framework\/engine["']/;
+    const match = content.match(importRegex);
+    if (match) {
+        const existingImports = (match[1] ?? "").trim();
+        const newImports = existingImports ? `${existingImports}, stepsPipeline` : "stepsPipeline";
+        return content.replace(importRegex, `import { ${newImports} } from "@cosmicdrift/kumiko-framework/engine"`);
+    }
+    return null;
+}
+export async function convertFile(filePath, project, options = {}) {
+    try {
+        const contentBefore = readFileSync(filePath, "utf8");
+        const proj = project ??
+            new Project({
+                skipAddingFilesFromTsConfig: true,
+                skipFileDependencyResolution: true,
+            });
+        const sourceFile = proj.addSourceFileAtPath(filePath);
+        const handlerCalls = findDefineWriteHandlerCalls(sourceFile);
+        if (handlerCalls.length === 0) {
+            return { filePath, status: "skipped", reason: "no_define_write_handler_calls" };
+        }
+        let content = contentBefore;
+        let hadChanges = false;
+        for (const call of handlerCalls) {
+            const arg = call.getArguments()[0];
+            if (!arg || arg.getKind() !== SyntaxKind.ObjectLiteralExpression) {
+                continue;
+            }
+            const objLiteral = arg.asKind(SyntaxKind.ObjectLiteralExpression);
+            if (!objLiteral)
+                continue;
+            const handlerProp = objLiteral.getProperty("handler");
+            if (!handlerProp)
+                continue;
+            const propAssign = handlerProp.asKind(SyntaxKind.PropertyAssignment);
+            if (!propAssign)
+                continue;
+            const handlerInit = propAssign.getInitializer();
+            if (!handlerInit)
+                continue;
+            const analysis = analyzeHandlerArrow(handlerInit.getText());
+            if (!analysis.isStaticReturn &&
+                !analysis.isSimpleExecutorCreate &&
+                !analysis.isSimpleExecutorUpdate &&
+                !analysis.isExpressionBodyCreate &&
+                !analysis.isExpressionBodyUpdate &&
+                !analysis.isGuardedCreate) {
+                if (options.verbose) {
+                    console.log(`  ~ ${relative(process.cwd(), filePath)}: non-trivial handler, skipping`);
+                }
+                continue;
+            }
+            const schemaType = inferSchemaType(objLiteral);
+            const indent = propAssign.getIndentationText() ?? "    ";
+            const performBlock = generatePerformBlock(analysis, schemaType, indent);
+            if (!performBlock)
+                continue;
+            const start = propAssign.getStart();
+            let end = propAssign.getEnd();
+            // Consume trailing comma after the property assignment
+            if (end < content.length && content[end] === ",") {
+                end++;
+            }
+            content = content.slice(0, start) + performBlock + content.slice(end);
+            hadChanges = true;
+        }
+        if (hadChanges) {
+            const importResult = ensurePipelineImport(content);
+            if (importResult) {
+                content = importResult;
+            }
+            else if (options.verbose) {
+                console.log(`  ~ ${filePath}: stepsPipeline import not needed or already present`);
+            }
+        }
+        if (hadChanges && !options.dryRun) {
+            writeFileSync(filePath, content, "utf8");
+        }
+        const status = hadChanges ? "converted" : "skipped";
+        const reason = hadChanges
+            ? "handler replaced with perform: stepsPipeline(...)"
+            : "no convertible handler";
+        return { filePath, status, reason };
+    }
+    catch (err) {
+        return {
+            filePath,
+            status: "error",
+            reason: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function findDefineWriteHandlerCalls(sourceFile) {
+    return sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression).filter((call) => {
+        const expr = call.getExpression();
+        return expr.getText() === "defineWriteHandler";
+    });
+}

package/dist/entity-field-types.d.ts

@@ -0,0 +1,13 @@
+export type UnknownEntityFieldType = {
+    readonly fieldName: string;
+    readonly type: string;
+};
+/**
+ * Scans `definition.fields.<name>.type` for values outside the FieldDefinition
+ * catalogue. Tolerant of RawRefSentinel at every level (definition itself,
+ * `fields`, a single field, or its `type`) — those are unresolvable source
+ * references, not validated field shapes, and readDataLiteralNode already
+ * chose not to fail the whole extraction over them.
+ */
+export declare function findUnknownEntityFieldTypes(definition: unknown): readonly UnknownEntityFieldType[];
+export declare function describeUnknownFieldType(entry: UnknownEntityFieldType): string;

package/dist/entity-field-types.js

@@ -0,0 +1,35 @@
+// Shared field-type validation for EntityDefinition. Used by both the
+// static extractor (extractEntity, parse-time ParseError) and the runtime
+// PatternChange validator (pattern-change-schema.ts) so the two never drift
+// into reporting different "unknown field type" catalogues.
+import { FIELD_TYPE_NAMES } from "@cosmicdrift/kumiko-types/fields";
+import { isPlainObject, isRawRefSentinel } from "./extractors/shared.js";
+/**
+ * Scans `definition.fields.<name>.type` for values outside the FieldDefinition
+ * catalogue. Tolerant of RawRefSentinel at every level (definition itself,
+ * `fields`, a single field, or its `type`) — those are unresolvable source
+ * references, not validated field shapes, and readDataLiteralNode already
+ * chose not to fail the whole extraction over them.
+ */
+export function findUnknownEntityFieldTypes(definition) {
+    if (isRawRefSentinel(definition) || !isPlainObject(definition))
+        return [];
+    const fields = definition["fields"];
+    if (isRawRefSentinel(fields) || !isPlainObject(fields))
+        return [];
+    const out = [];
+    for (const [fieldName, fieldDef] of Object.entries(fields)) {
+        if (isRawRefSentinel(fieldDef) || !isPlainObject(fieldDef))
+            continue;
+        const type = fieldDef["type"];
+        if (isRawRefSentinel(type) || typeof type !== "string")
+            continue;
+        if (!FIELD_TYPE_NAMES.includes(type)) {
+            out.push({ fieldName, type });
+        }
+    }
+    return out;
+}
+export function describeUnknownFieldType(entry) {
+    return `unknown field type "${entry.type}"; expected one of: ${FIELD_TYPE_NAMES.join(", ")}`;
+}