@wp-typia/project-tools 0.24.3 → 0.24.5

package/dist/runtime/migration/migration-command-surface.d.ts

@@ -0,0 +1,67 @@
+import type { ReadlinePrompt } from '../cli/cli-prompt.js';
+import type { ParsedMigrationArgs, RenderLine } from './migration-types.js';
+export type CommandRenderOptions = {
+    prompt?: ReadlinePrompt;
+    renderLine?: RenderLine;
+};
+export type DiffLikeOptions = {
+    fromMigrationVersion?: string;
+    renderLine?: RenderLine;
+    toMigrationVersion?: string;
+};
+export type VerifyOptions = {
+    all?: boolean;
+    fromMigrationVersion?: string;
+    renderLine?: RenderLine;
+};
+export type FixturesOptions = {
+    all?: boolean;
+    confirmOverwrite?: ((message: string) => boolean) | undefined;
+    force?: boolean;
+    fromMigrationVersion?: string;
+    isInteractive?: boolean;
+    renderLine?: RenderLine;
+    toMigrationVersion?: string;
+};
+export type FuzzOptions = {
+    all?: boolean;
+    fromMigrationVersion?: string;
+    iterations?: number;
+    renderLine?: RenderLine;
+    seed?: number;
+};
+export type WizardOptions = CommandRenderOptions & {
+    isInteractive?: boolean;
+};
+/**
+ * Returns the formatted help text for migration CLI commands and flags.
+ *
+ * @returns Multi-line usage text for the `wp-typia migrate` command surface.
+ */
+export declare function formatMigrationHelpText(): string;
+/**
+ * Parses migration CLI arguments into a structured command payload.
+ *
+ * @param argv Command-line arguments that follow the `migrate` subcommand.
+ * @returns Parsed migration command and normalized flags for runtime dispatch.
+ * @throws Error When no arguments are provided, an unknown flag is encountered, or legacy semver flags are used.
+ */
+export declare function parseMigrationArgs(argv: string[]): ParsedMigrationArgs;
+/**
+ * Parse an optional positive integer flag value.
+ *
+ * @param value Raw CLI flag value, or `undefined` when the flag was omitted.
+ * @param label Human-readable flag label used in validation error messages.
+ * @returns The parsed integer when provided, otherwise `undefined`.
+ * @throws Error When the value is not a base-10 integer greater than zero.
+ */
+export declare function parsePositiveInteger(value: string | undefined, label: string): number | undefined;
+/**
+ * Parse an optional non-negative integer flag value.
+ *
+ * @param value Raw CLI flag value, or `undefined` when the flag was omitted.
+ * @param label Human-readable flag label used in validation error messages.
+ * @returns The parsed integer when provided, otherwise `undefined`.
+ * @throws Error When the value is not a base-10 integer greater than or equal to zero.
+ */
+export declare function parseNonNegativeInteger(value: string | undefined, label: string): number | undefined;

package/dist/runtime/migration/migration-command-surface.js

@@ -0,0 +1,191 @@
+import { formatLegacyMigrationWorkspaceResetGuidance } from './migration-utils.js';
+/**
+ * Returns the formatted help text for migration CLI commands and flags.
+ *
+ * @returns Multi-line usage text for the `wp-typia migrate` command surface.
+ */
+export function formatMigrationHelpText() {
+    return `Usage:
+  wp-typia migrate init --current-migration-version <label>
+  wp-typia migrate snapshot --migration-version <label>
+  wp-typia migrate plan --from-migration-version <label> [--to-migration-version current]
+  wp-typia migrate wizard
+  wp-typia migrate diff --from-migration-version <label> [--to-migration-version current]
+  wp-typia migrate scaffold --from-migration-version <label> [--to-migration-version current]
+  wp-typia migrate verify [--from-migration-version <label>|--all]
+  wp-typia migrate doctor [--from-migration-version <label>|--all]
+  wp-typia migrate fixtures [--from-migration-version <label>|--all] [--to-migration-version current] [--force]
+  wp-typia migrate fuzz [--from-migration-version <label>|--all] [--iterations <n>] [--seed <n>]
+
+Notes:
+  \`migrate init\` auto-detects supported single-block and \`src/blocks/*\` multi-block layouts.
+  \`migrate init\` only retrofits migration support into projects that already match those layouts.
+  A broader project-level \`wp-typia init\` path remains future work.
+  Migration versions use strict schema labels like \`v1\`, \`v2\`, and \`v3\`.
+  \`migrate wizard\` is TTY-only and helps you choose one legacy migration version to preview.
+  \`migrate plan\` and \`migrate wizard\` are read-only previews; they do not scaffold rules or fixtures.
+  --all runs across every configured legacy migration version and every configured block target.
+  Existing fixture files are preserved and reported as skipped unless you pass \`--force\`.
+  Use \`migrate fixtures --force\` as the explicit refresh path for generated fixture files.
+  In TTY usage, \`migrate fixtures --force\` asks before overwriting existing fixture files.
+  In non-interactive usage, \`migrate fixtures --force\` overwrites immediately for script compatibility.`;
+}
+/**
+ * Parses migration CLI arguments into a structured command payload.
+ *
+ * @param argv Command-line arguments that follow the `migrate` subcommand.
+ * @returns Parsed migration command and normalized flags for runtime dispatch.
+ * @throws Error When no arguments are provided, an unknown flag is encountered, or legacy semver flags are used.
+ */
+export function parseMigrationArgs(argv) {
+    const parsed = {
+        command: undefined,
+        flags: {
+            all: false,
+            currentMigrationVersion: undefined,
+            force: false,
+            fromMigrationVersion: undefined,
+            iterations: undefined,
+            migrationVersion: undefined,
+            seed: undefined,
+            toMigrationVersion: 'current',
+        },
+    };
+    if (argv.length === 0) {
+        throw new Error(formatMigrationHelpText());
+    }
+    parsed.command = argv[0];
+    for (let index = 1; index < argv.length; index += 1) {
+        const arg = argv[index];
+        const next = argv[index + 1];
+        if (arg === '--')
+            continue;
+        if (arg === '--all') {
+            parsed.flags.all = true;
+            continue;
+        }
+        if (arg === '--force') {
+            parsed.flags.force = true;
+            continue;
+        }
+        if (arg === '--current-migration-version') {
+            parsed.flags.currentMigrationVersion = next;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--current-migration-version=')) {
+            parsed.flags.currentMigrationVersion = arg.split('=', 2)[1];
+            continue;
+        }
+        if (arg === '--from-migration-version') {
+            parsed.flags.fromMigrationVersion = next;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--from-migration-version=')) {
+            parsed.flags.fromMigrationVersion = arg.split('=', 2)[1];
+            continue;
+        }
+        if (arg === '--iterations') {
+            parsed.flags.iterations = next;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--iterations=')) {
+            parsed.flags.iterations = arg.split('=', 2)[1];
+            continue;
+        }
+        if (arg === '--seed') {
+            parsed.flags.seed = next;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--seed=')) {
+            parsed.flags.seed = arg.split('=', 2)[1];
+            continue;
+        }
+        if (arg === '--to-migration-version') {
+            parsed.flags.toMigrationVersion = next;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--to-migration-version=')) {
+            parsed.flags.toMigrationVersion = arg.split('=', 2)[1];
+            continue;
+        }
+        if (arg === '--migration-version') {
+            parsed.flags.migrationVersion = next;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--migration-version=')) {
+            parsed.flags.migrationVersion = arg.split('=', 2)[1];
+            continue;
+        }
+        if (arg === '--current-version' ||
+            arg.startsWith('--current-version=') ||
+            arg === '--version' ||
+            arg.startsWith('--version=') ||
+            arg === '--from' ||
+            arg.startsWith('--from=') ||
+            arg === '--to' ||
+            arg.startsWith('--to=')) {
+            throwLegacyMigrationFlagError(arg);
+        }
+        throw new Error(`Unknown migration flag: ${arg}`);
+    }
+    return parsed;
+}
+/**
+ * Parse an optional positive integer flag value.
+ *
+ * @param value Raw CLI flag value, or `undefined` when the flag was omitted.
+ * @param label Human-readable flag label used in validation error messages.
+ * @returns The parsed integer when provided, otherwise `undefined`.
+ * @throws Error When the value is not a base-10 integer greater than zero.
+ */
+export function parsePositiveInteger(value, label) {
+    if (!value) {
+        return undefined;
+    }
+    if (!/^\d+$/.test(value)) {
+        throw new Error(`Invalid ${label}: ${value}. Expected a positive integer.`);
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`Invalid ${label}: ${value}. Expected a positive integer.`);
+    }
+    return parsed;
+}
+/**
+ * Parse an optional non-negative integer flag value.
+ *
+ * @param value Raw CLI flag value, or `undefined` when the flag was omitted.
+ * @param label Human-readable flag label used in validation error messages.
+ * @returns The parsed integer when provided, otherwise `undefined`.
+ * @throws Error When the value is not a base-10 integer greater than or equal to zero.
+ */
+export function parseNonNegativeInteger(value, label) {
+    if (!value) {
+        return undefined;
+    }
+    if (!/^\d+$/.test(value)) {
+        throw new Error(`Invalid ${label}: ${value}. Expected a non-negative integer.`);
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new Error(`Invalid ${label}: ${value}. Expected a non-negative integer.`);
+    }
+    return parsed;
+}
+function throwLegacyMigrationFlagError(flag) {
+    const replacement = flag.startsWith('--current-version')
+        ? '--current-migration-version'
+        : flag.startsWith('--version')
+            ? '--migration-version'
+            : flag.startsWith('--from')
+                ? '--from-migration-version'
+                : '--to-migration-version';
+    throw new Error(`Legacy migration flag \`${flag}\` is no longer supported. Use \`${replacement}\` with schema labels like \`v1\` and \`v2\` instead. ` +
+        formatLegacyMigrationWorkspaceResetGuidance());
+}

package/dist/runtime/migration/migration-constants.d.ts

@@ -0,0 +1,15 @@
+export declare const ROOT_BLOCK_JSON = "block.json";
+export declare const ROOT_MANIFEST = "typia.manifest.json";
+export declare const ROOT_PHP_MIGRATION_REGISTRY = "typia-migration-registry.php";
+export declare const SRC_BLOCK_JSON: string;
+export declare const SRC_MANIFEST: string;
+export declare const ROOT_SAVE_FILE: string;
+export declare const ROOT_TYPES_FILE: string;
+export declare const MIGRATIONS_DIR: string;
+export declare const CONFIG_FILE: string;
+export declare const GENERATED_DIR: string;
+export declare const FIXTURES_DIR: string;
+export declare const RULES_DIR: string;
+export declare const SNAPSHOT_DIR: string;
+export declare const SUPPORTED_PROJECT_FILES: string[];
+export declare const MIGRATION_TODO_PREFIX = "TODO MIGRATION:";

package/dist/runtime/migration/migration-constants.js

@@ -0,0 +1,16 @@
+import path from "node:path";
+export const ROOT_BLOCK_JSON = "block.json";
+export const ROOT_MANIFEST = "typia.manifest.json";
+export const ROOT_PHP_MIGRATION_REGISTRY = "typia-migration-registry.php";
+export const SRC_BLOCK_JSON = path.join("src", "block.json");
+export const SRC_MANIFEST = path.join("src", "typia.manifest.json");
+export const ROOT_SAVE_FILE = path.join("src", "save.tsx");
+export const ROOT_TYPES_FILE = path.join("src", "types.ts");
+export const MIGRATIONS_DIR = path.join("src", "migrations");
+export const CONFIG_FILE = path.join(MIGRATIONS_DIR, "config.ts");
+export const GENERATED_DIR = path.join(MIGRATIONS_DIR, "generated");
+export const FIXTURES_DIR = path.join(MIGRATIONS_DIR, "fixtures");
+export const RULES_DIR = path.join(MIGRATIONS_DIR, "rules");
+export const SNAPSHOT_DIR = path.join(MIGRATIONS_DIR, "versions");
+export const SUPPORTED_PROJECT_FILES = ["package.json", ROOT_BLOCK_JSON, ROOT_SAVE_FILE, ROOT_TYPES_FILE];
+export const MIGRATION_TODO_PREFIX = "TODO MIGRATION:";

package/dist/runtime/migration/migration-diff-rename.d.ts

@@ -0,0 +1,13 @@
+import type { FlattenedAttributeDescriptor, ManifestAttribute, RenameCandidate } from "./migration-types.js";
+interface CreateRenameCandidatesOptions {
+    addedKeys: string[];
+    isUnionRenameCompatible: (oldAttribute: ManifestAttribute, newAttribute: ManifestAttribute) => boolean;
+    newAttributes: Record<string, ManifestAttribute>;
+    newLeafAttributes: FlattenedAttributeDescriptor[];
+    oldAttributes: Record<string, ManifestAttribute>;
+    oldLeafAttributes: FlattenedAttributeDescriptor[];
+    removedKeys: string[];
+}
+export declare function createRenameCandidates({ addedKeys, isUnionRenameCompatible, newAttributes, newLeafAttributes, oldAttributes, oldLeafAttributes, removedKeys, }: CreateRenameCandidatesOptions): RenameCandidate[];
+export declare function passesNameSimilarityRule(legacyPath: string, currentPath: string): boolean;
+export {};

package/dist/runtime/migration/migration-diff-rename.js

@@ -0,0 +1,192 @@
+export function createRenameCandidates({ addedKeys, isUnionRenameCompatible, newAttributes, newLeafAttributes, oldAttributes, oldLeafAttributes, removedKeys, }) {
+    const assessments = [];
+    for (const currentPath of addedKeys) {
+        const nextAttribute = newAttributes[currentPath];
+        if (!nextAttribute)
+            continue;
+        for (const legacyPath of removedKeys) {
+            const previous = oldAttributes[legacyPath];
+            if (!previous)
+                continue;
+            const candidate = assessRenameCandidate(previous, nextAttribute, legacyPath, currentPath, isUnionRenameCompatible);
+            if (candidate) {
+                assessments.push(candidate);
+            }
+        }
+    }
+    const oldLeafMap = new Map(oldLeafAttributes.map((descriptor) => [descriptor.currentPath, descriptor]));
+    const newLeafMap = new Map(newLeafAttributes.map((descriptor) => [descriptor.currentPath, descriptor]));
+    const removedLeafDescriptors = oldLeafAttributes.filter((descriptor) => !newLeafMap.has(descriptor.currentPath));
+    const addedLeafDescriptors = newLeafAttributes.filter((descriptor) => !oldLeafMap.has(descriptor.currentPath));
+    for (const nextDescriptor of addedLeafDescriptors) {
+        if (!nextDescriptor.currentPath.includes(".")) {
+            continue;
+        }
+        for (const previousDescriptor of removedLeafDescriptors) {
+            if (!previousDescriptor.currentPath.includes(".")) {
+                continue;
+            }
+            const candidate = assessRenameCandidate(previousDescriptor.attribute, nextDescriptor.attribute, previousDescriptor.currentPath, nextDescriptor.currentPath, isUnionRenameCompatible);
+            if (candidate) {
+                assessments.push(candidate);
+            }
+        }
+    }
+    return assessments
+        .map((candidate) => {
+        const currentMatches = assessments
+            .filter((item) => item.currentPath === candidate.currentPath)
+            .sort((left, right) => right.score - left.score);
+        const legacyMatches = assessments
+            .filter((item) => item.legacyPath === candidate.legacyPath)
+            .sort((left, right) => right.score - left.score);
+        const currentLeader = currentMatches[0];
+        const legacyLeader = legacyMatches[0];
+        const currentHasTie = currentMatches.length > 1 && Math.abs((currentMatches[1]?.score ?? 0) - currentLeader.score) < 0.05;
+        const legacyHasTie = legacyMatches.length > 1 && Math.abs((legacyMatches[1]?.score ?? 0) - legacyLeader.score) < 0.05;
+        return {
+            ...candidate,
+            autoApply: currentLeader.legacyPath === candidate.legacyPath &&
+                legacyLeader.currentPath === candidate.currentPath &&
+                !currentHasTie &&
+                !legacyHasTie &&
+                candidate.score >= 0.6,
+        };
+    })
+        .filter((candidate, index, list) => {
+        const firstMatch = list.findIndex((item) => item.currentPath === candidate.currentPath && item.legacyPath === candidate.legacyPath);
+        return firstMatch === index;
+    })
+        .sort((left, right) => right.score - left.score);
+}
+export function passesNameSimilarityRule(legacyPath, currentPath) {
+    return scoreRenameSimilarity(legacyPath, currentPath) >= 0.6;
+}
+function isRenameCandidateShapeCompatible(oldAttribute, newAttribute, isUnionRenameCompatible) {
+    if (!oldAttribute || !newAttribute || oldAttribute.ts.kind !== newAttribute.ts.kind) {
+        return false;
+    }
+    if (["string", "number", "boolean"].includes(oldAttribute.ts.kind)) {
+        return hasRenameCompatibleConstraints(oldAttribute, newAttribute);
+    }
+    if (oldAttribute.ts.kind === "union") {
+        return isUnionRenameCompatible(oldAttribute, newAttribute);
+    }
+    return false;
+}
+function assessRenameCandidate(oldAttribute, newAttribute, legacyPath, currentPath, isUnionRenameCompatible) {
+    if (!isRenameCandidateShapeCompatible(oldAttribute, newAttribute, isUnionRenameCompatible)) {
+        return null;
+    }
+    const baseScore = scoreRenameSimilarity(legacyPath, currentPath);
+    const score = getParentPath(legacyPath) === getParentPath(currentPath) ? Math.max(baseScore, 0.75) : baseScore;
+    return {
+        autoApply: false,
+        currentPath,
+        legacyPath,
+        reason: describeRenameReason(oldAttribute, legacyPath, currentPath, score),
+        score,
+    };
+}
+function hasRenameCompatibleConstraints(oldAttribute, newAttribute) {
+    const oldEnum = oldAttribute.wp.enum ?? null;
+    const nextEnum = newAttribute.wp.enum ?? null;
+    if (oldEnum && nextEnum) {
+        const oldIsSubset = oldEnum.every((value) => nextEnum.includes(value));
+        if (!oldIsSubset) {
+            return false;
+        }
+    }
+    else if (oldEnum && !nextEnum) {
+        return false;
+    }
+    const oldConstraints = oldAttribute.typia.constraints ?? {};
+    const nextConstraints = newAttribute.typia.constraints ?? {};
+    return [
+        compareMinimumBound(oldConstraints.minLength, nextConstraints.minLength),
+        compareMaximumBound(oldConstraints.maxLength, nextConstraints.maxLength),
+        compareMinimumBound(oldConstraints.minimum, nextConstraints.minimum),
+        compareMaximumBound(oldConstraints.maximum, nextConstraints.maximum),
+        comparePatternBound(oldConstraints.pattern, nextConstraints.pattern),
+        comparePatternBound(oldConstraints.format, nextConstraints.format),
+        comparePatternBound(oldConstraints.typeTag, nextConstraints.typeTag),
+    ].every(Boolean);
+}
+function compareMinimumBound(oldValue, nextValue) {
+    if (nextValue === null || nextValue === undefined)
+        return true;
+    if (oldValue === null || oldValue === undefined)
+        return true;
+    return Number(oldValue) <= Number(nextValue);
+}
+function compareMaximumBound(oldValue, nextValue) {
+    if (nextValue === null || nextValue === undefined)
+        return true;
+    if (oldValue === null || oldValue === undefined)
+        return true;
+    return Number(oldValue) >= Number(nextValue);
+}
+function comparePatternBound(oldValue, nextValue) {
+    return oldValue === nextValue || oldValue === null || oldValue === undefined;
+}
+function scoreRenameSimilarity(legacyPath, currentPath) {
+    const legacy = normalizeFieldName(legacyPath);
+    const current = normalizeFieldName(currentPath);
+    if (legacy === current)
+        return 1;
+    if (shareAliasGroup(legacy, current))
+        return 0.9;
+    const legacyTokens = tokenizeFieldName(legacy);
+    const currentTokens = tokenizeFieldName(current);
+    const overlap = legacyTokens.filter((token) => currentTokens.includes(token));
+    const jaccard = overlap.length / new Set([...legacyTokens, ...currentTokens]).size;
+    if (legacy.includes(current) || current.includes(legacy)) {
+        return Math.max(jaccard, 0.7);
+    }
+    if (legacyTokens.length > 0 &&
+        currentTokens.length > 0 &&
+        legacyTokens[legacyTokens.length - 1] === currentTokens[currentTokens.length - 1]) {
+        return Math.max(jaccard, 0.6);
+    }
+    return jaccard;
+}
+function normalizeFieldName(name) {
+    return String(name)
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[^a-zA-Z0-9]+/g, " ")
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, "");
+}
+function tokenizeFieldName(name) {
+    return String(name)
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}
+function getParentPath(pathLabel) {
+    const segments = String(pathLabel).split(".");
+    return segments.length <= 1 ? "" : segments.slice(0, -1).join(".");
+}
+function shareAliasGroup(left, right) {
+    const aliasGroups = [
+        ["content", "headline", "body", "text", "copy", "message"],
+        ["id", "uniqueid", "uuid"],
+        ["visible", "isvisible", "show", "shown", "enabled"],
+        ["align", "alignment", "textalign"],
+        ["count", "clickcount", "counter"],
+        ["url", "href", "link"],
+    ];
+    return aliasGroups.some((group) => group.includes(left) && group.includes(right));
+}
+function describeRenameReason(attribute, legacyPath, currentPath, score) {
+    if (attribute.ts.kind === "union") {
+        return `compatible discriminated union (${legacyPath} → ${currentPath})`;
+    }
+    if (score >= 0.9)
+        return "high-confidence compatible field";
+    if (score >= 0.6)
+        return "name-similar compatible field";
+    return "compatible field requiring review";
+}

package/dist/runtime/migration/migration-diff-transform.d.ts

@@ -0,0 +1,14 @@
+import type { DiffOutcome, FlattenedAttributeDescriptor, ManifestAttribute, RenameCandidate, TransformSuggestion } from "./migration-types.js";
+interface CreateTransformSuggestionsOptions {
+    addedKeys: string[];
+    manualItems: DiffOutcome[];
+    newAttributes: Record<string, ManifestAttribute>;
+    newLeafAttributes: FlattenedAttributeDescriptor[];
+    oldAttributes: Record<string, ManifestAttribute>;
+    oldLeafAttributes: FlattenedAttributeDescriptor[];
+    removedKeys: string[];
+    renameCandidates: RenameCandidate[];
+}
+export declare function createTransformSuggestions({ oldAttributes, newAttributes, addedKeys, removedKeys, manualItems, renameCandidates, oldLeafAttributes, newLeafAttributes, }: CreateTransformSuggestionsOptions): TransformSuggestion[];
+export declare function describeConstraintChange(oldAttribute: ManifestAttribute, newAttribute: ManifestAttribute): string;
+export {};

package/dist/runtime/migration/migration-diff-transform.js

@@ -0,0 +1,105 @@
+import { getAttributeByCurrentPath } from "./migration-manifest.js";
+import { passesNameSimilarityRule } from "./migration-diff-rename.js";
+export function createTransformSuggestions({ oldAttributes, newAttributes, addedKeys, removedKeys, manualItems, renameCandidates, oldLeafAttributes, newLeafAttributes, }) {
+    const suggestions = [];
+    const activeRenameTargets = new Set(renameCandidates.filter((candidate) => candidate.autoApply).map((candidate) => candidate.currentPath));
+    const oldLeafMap = new Map(oldLeafAttributes.map((descriptor) => [descriptor.currentPath, descriptor]));
+    const newLeafMap = new Map(newLeafAttributes.map((descriptor) => [descriptor.currentPath, descriptor]));
+    for (const currentPath of [
+        ...new Set([
+            ...Object.keys(newAttributes),
+            ...manualItems.map((item) => item.path),
+            ...newLeafAttributes.map((item) => item.currentPath),
+        ]),
+    ]) {
+        if (activeRenameTargets.has(currentPath)) {
+            continue;
+        }
+        const manualItem = manualItems.find((item) => item.path === currentPath || item.path.startsWith(`${currentPath}.`));
+        const currentAttribute = newLeafMap.get(currentPath)?.attribute ??
+            getAttributeByCurrentPath(newAttributes, currentPath) ??
+            null;
+        if (!manualItem || !currentAttribute) {
+            continue;
+        }
+        const exactLegacy = oldLeafMap.get(currentPath)?.attribute ??
+            getAttributeByCurrentPath(oldAttributes, currentPath) ??
+            null;
+        if (exactLegacy && exactLegacy.ts.kind !== currentAttribute.ts.kind) {
+            suggestions.push({
+                bodyLines: buildTransformBodyLines(currentAttribute, currentPath),
+                attribute: currentAttribute,
+                currentPath,
+                legacyPath: currentPath,
+                reason: `semantic coercion suggested for ${manualItem.kind}`,
+            });
+            continue;
+        }
+        const bestRenameCandidate = renameCandidates.find((candidate) => candidate.currentPath === currentPath);
+        if (bestRenameCandidate && !bestRenameCandidate.autoApply) {
+            suggestions.push({
+                bodyLines: buildTransformBodyLines(currentAttribute, bestRenameCandidate.legacyPath),
+                attribute: currentAttribute,
+                currentPath,
+                legacyPath: bestRenameCandidate.legacyPath,
+                reason: `review coercion from ${bestRenameCandidate.legacyPath}`,
+            });
+            continue;
+        }
+        const addedCurrent = addedKeys.includes(currentPath) ||
+            (newLeafMap.has(currentPath) && !oldLeafMap.has(currentPath));
+        if (!addedCurrent) {
+            continue;
+        }
+        const compatibleLegacyPath = [
+            ...removedKeys,
+            ...oldLeafAttributes
+                .filter((descriptor) => !newLeafMap.has(descriptor.currentPath))
+                .map((descriptor) => descriptor.currentPath),
+        ].find((legacyPath) => passesNameSimilarityRule(legacyPath, currentPath));
+        if (compatibleLegacyPath) {
+            suggestions.push({
+                bodyLines: buildTransformBodyLines(currentAttribute, compatibleLegacyPath),
+                attribute: currentAttribute,
+                currentPath,
+                legacyPath: compatibleLegacyPath,
+                reason: `review coercion from ${compatibleLegacyPath}`,
+            });
+        }
+    }
+    return suggestions;
+}
+export function describeConstraintChange(oldAttribute, newAttribute) {
+    const details = [];
+    const oldConstraints = oldAttribute.typia.constraints;
+    const nextConstraints = newAttribute.typia.constraints;
+    if (newAttribute.wp.enum && JSON.stringify(newAttribute.wp.enum) !== JSON.stringify(oldAttribute.wp.enum)) {
+        details.push("enum changed");
+    }
+    for (const key of ["minLength", "maxLength", "minimum", "maximum", "pattern", "format", "typeTag"]) {
+        if (oldConstraints[key] !== nextConstraints[key]) {
+            details.push(`${key}: ${oldConstraints[key]} -> ${nextConstraints[key]}`);
+        }
+    }
+    return details.join(", ");
+}
+function buildTransformBodyLines(attribute, legacyPath) {
+    switch (attribute.ts.kind) {
+        case "string":
+            return [`// return typeof legacyValue === "string" ? legacyValue : String(legacyValue ?? "");`];
+        case "number":
+            return [
+                `// const numericValue = typeof legacyValue === "number" ? legacyValue : Number(legacyValue ?? 0);`,
+                `// return Number.isNaN(numericValue) ? undefined : numericValue;`,
+            ];
+        case "boolean":
+            return [`// return typeof legacyValue === "boolean" ? legacyValue : Boolean(legacyValue);`];
+        case "union":
+            return [
+                `// const legacyObject = typeof legacyValue === "object" && legacyValue !== null ? legacyValue : {};`,
+                `// return legacyObject; // adjust discriminator / branch fields before verify`,
+            ];
+        default:
+            return [`// return legacyValue; // customize migration from ${legacyPath}`];
+    }
+}

package/dist/runtime/migration/migration-diff.d.ts

@@ -0,0 +1,2 @@
+import type { MigrationBlockConfig, MigrationDiff, MigrationProjectState, ResolvedMigrationBlockTarget } from "./migration-types.js";
+export declare function createMigrationDiff(state: MigrationProjectState, blockOrFromVersion: MigrationBlockConfig | ResolvedMigrationBlockTarget | string, fromVersionOrToVersion: string, maybeToVersion?: string): MigrationDiff;