@wp-typia/project-tools 0.24.3 → 0.24.5

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

@@ -0,0 +1,252 @@
+import fs from "node:fs";
+import { flattenManifestLeafAttributes, getManifestDefaultValue, hasManifestDefault, } from "./migration-manifest.js";
+import { createRenameCandidates } from "./migration-diff-rename.js";
+import { createTransformSuggestions, describeConstraintChange, } from "./migration-diff-transform.js";
+import { createMissingBlockSnapshotMessage, getAvailableSnapshotVersionsForBlock, getSnapshotManifestPath, } from "./migration-project.js";
+import { isNumber, readJson } from "./migration-utils.js";
+export function createMigrationDiff(state, blockOrFromVersion, fromVersionOrToVersion, maybeToVersion) {
+    if (typeof blockOrFromVersion === "string" && state.blocks.length > 1) {
+        throw new Error("A block key is required when diffing a multi-block migration project.");
+    }
+    const block = typeof blockOrFromVersion === "string"
+        ? state.blocks[0]
+        : state.blocks.find((entry) => entry.key === blockOrFromVersion.key) ?? null;
+    const fromVersion = typeof blockOrFromVersion === "string"
+        ? blockOrFromVersion
+        : fromVersionOrToVersion;
+    const toVersion = typeof blockOrFromVersion === "string"
+        ? fromVersionOrToVersion
+        : maybeToVersion ?? state.config.currentMigrationVersion;
+    if (!block) {
+        throw new Error(typeof blockOrFromVersion === "string"
+            ? "No migration block targets are configured for this project."
+            : `Unknown migration block key: ${blockOrFromVersion.key}`);
+    }
+    const snapshotManifestPath = getSnapshotManifestPath(state.projectDir, block, fromVersion);
+    if (!fs.existsSync(snapshotManifestPath)) {
+        throw new Error(createMissingBlockSnapshotMessage(block.blockName, fromVersion, getAvailableSnapshotVersionsForBlock(state.projectDir, state.config.supportedMigrationVersions, block)));
+    }
+    const targetManifest = toVersion === state.config.currentMigrationVersion
+        ? block.currentManifest
+        : readJson(getSnapshotManifestPath(state.projectDir, block, toVersion));
+    const oldManifest = readJson(snapshotManifestPath);
+    const oldAttributes = oldManifest.attributes ?? {};
+    const newAttributes = targetManifest.attributes ?? {};
+    const oldLeafAttributes = flattenManifestLeafAttributes(oldAttributes);
+    const newLeafAttributes = flattenManifestLeafAttributes(newAttributes);
+    const autoItems = [];
+    const manualItems = [];
+    const addedKeys = [];
+    const removedKeys = [];
+    for (const [key, newAttribute] of Object.entries(newAttributes)) {
+        const oldAttribute = oldAttributes[key];
+        if (!oldAttribute) {
+            addedKeys.push(key);
+            if (newAttribute.ts.required && !hasManifestDefault(newAttribute)) {
+                manualItems.push({
+                    detail: "required field has no default in current schema",
+                    kind: "required-addition",
+                    path: key,
+                    status: "manual",
+                });
+            }
+            else {
+                autoItems.push({
+                    detail: hasManifestDefault(newAttribute)
+                        ? `default ${JSON.stringify(getManifestDefaultValue(newAttribute))}`
+                        : "optional addition",
+                    kind: hasManifestDefault(newAttribute) ? "add-default" : "add-optional",
+                    path: key,
+                    status: "auto",
+                });
+            }
+            continue;
+        }
+        const outcome = compareManifestAttribute(oldAttribute, newAttribute, key);
+        if (outcome.status === "manual") {
+            manualItems.push(outcome);
+        }
+        else {
+            autoItems.push(outcome);
+        }
+    }
+    for (const key of Object.keys(oldAttributes)) {
+        if (!(key in newAttributes)) {
+            removedKeys.push(key);
+            autoItems.push({
+                detail: "field removed from current schema",
+                kind: "drop",
+                path: key,
+                status: "auto",
+            });
+        }
+    }
+    const renameCandidates = createRenameCandidates({
+        addedKeys,
+        isUnionRenameCompatible: (oldAttribute, newAttribute) => compareUnionAttribute(oldAttribute, newAttribute, "$rename").status === "auto",
+        newAttributes,
+        newLeafAttributes,
+        oldAttributes,
+        oldLeafAttributes,
+        removedKeys,
+    });
+    const activeRenameCandidates = renameCandidates.filter((candidate) => candidate.autoApply);
+    for (const candidate of activeRenameCandidates) {
+        removeOutcomeByPath(autoItems, candidate.legacyPath, "drop");
+        removeOutcomeByPath(autoItems, candidate.currentPath, "add-default");
+        removeOutcomeByPath(autoItems, candidate.currentPath, "add-optional");
+        removeOutcomeByPath(manualItems, candidate.currentPath, "required-addition");
+        removeOutcomesByPath(manualItems, candidate.currentPath);
+        autoItems.push({
+            detail: `legacy field ${candidate.legacyPath}`,
+            kind: "rename",
+            path: candidate.currentPath,
+            status: "auto",
+        });
+    }
+    const transformSuggestions = createTransformSuggestions({
+        addedKeys,
+        manualItems,
+        newAttributes,
+        newLeafAttributes,
+        oldAttributes,
+        oldLeafAttributes,
+        renameCandidates,
+        removedKeys,
+    });
+    return {
+        currentTypeName: targetManifest.sourceType ?? block.currentManifest.sourceType,
+        fromVersion,
+        summary: {
+            auto: autoItems.length,
+            autoItems,
+            manual: manualItems.length,
+            manualItems,
+            renameCandidates,
+            transformSuggestions,
+        },
+        toVersion,
+    };
+}
+function removeOutcomeByPath(items, pathLabel, kind) {
+    const index = items.findIndex((item) => item.path === pathLabel && item.kind === kind);
+    if (index >= 0) {
+        items.splice(index, 1);
+    }
+}
+function removeOutcomesByPath(items, pathLabel) {
+    for (let index = items.length - 1; index >= 0; index -= 1) {
+        if (items[index]?.path === pathLabel) {
+            items.splice(index, 1);
+        }
+    }
+}
+function compareManifestAttribute(oldAttribute, newAttribute, attributePath) {
+    if (oldAttribute.ts.kind !== newAttribute.ts.kind) {
+        return manualOutcome(attributePath, "type-change", `${oldAttribute.ts.kind} -> ${newAttribute.ts.kind}`);
+    }
+    if (oldAttribute.ts.kind === "union") {
+        return compareUnionAttribute(oldAttribute, newAttribute, attributePath);
+    }
+    if (oldAttribute.ts.kind === "object") {
+        return compareObjectAttribute(oldAttribute, newAttribute, attributePath);
+    }
+    if (oldAttribute.ts.kind === "array") {
+        if (!oldAttribute.ts.items || !newAttribute.ts.items) {
+            return autoOutcome(attributePath, "copy", "array shape unchanged");
+        }
+        const nested = compareManifestAttribute(oldAttribute.ts.items, newAttribute.ts.items, `${attributePath}[]`);
+        return nested.status === "manual"
+            ? nested
+            : autoOutcome(attributePath, "hydrate", "array items can be normalized");
+    }
+    if (hasStricterConstraints(oldAttribute, newAttribute)) {
+        return manualOutcome(attributePath, "stricter-constraints", describeConstraintChange(oldAttribute, newAttribute));
+    }
+    return autoOutcome(attributePath, "copy", "compatible primitive field");
+}
+function compareObjectAttribute(oldAttribute, newAttribute, attributePath) {
+    const oldProperties = oldAttribute.ts.properties ?? {};
+    const newProperties = newAttribute.ts.properties ?? {};
+    for (const [key, nextProperty] of Object.entries(newProperties)) {
+        const previousProperty = oldProperties[key];
+        if (!previousProperty) {
+            if (nextProperty.ts.required && !hasManifestDefault(nextProperty)) {
+                return manualOutcome(`${attributePath}.${key}`, "object-change", "required field has no default in current schema");
+            }
+            continue;
+        }
+        const nested = compareManifestAttribute(previousProperty, nextProperty, `${attributePath}.${key}`);
+        if (nested.status === "manual") {
+            return nested;
+        }
+    }
+    return autoOutcome(attributePath, "hydrate", "object can be normalized with current manifest defaults");
+}
+function compareUnionAttribute(oldAttribute, newAttribute, attributePath) {
+    const oldUnion = oldAttribute.ts.union;
+    const newUnion = newAttribute.ts.union;
+    if (!oldUnion || !newUnion) {
+        return manualOutcome(attributePath, "union-change", "missing union metadata");
+    }
+    if (oldUnion.discriminator !== newUnion.discriminator) {
+        return manualOutcome(attributePath, "union-discriminator-change", `${oldUnion.discriminator} -> ${newUnion.discriminator}`);
+    }
+    const oldBranchKeys = Object.keys(oldUnion.branches);
+    const newBranchKeys = Object.keys(newUnion.branches);
+    for (const branchKey of oldBranchKeys) {
+        if (!(branchKey in newUnion.branches)) {
+            return manualOutcome(attributePath, "union-branch-removal", `branch ${branchKey} was removed`);
+        }
+        const nested = compareManifestAttribute(oldUnion.branches[branchKey], newUnion.branches[branchKey], `${attributePath}.${branchKey}`);
+        if (nested.status === "manual") {
+            return manualOutcome(nested.path, nested.kind.startsWith("union-") ? nested.kind : "union-manual", nested.detail ?? `branch ${branchKey} requires manual review`);
+        }
+    }
+    const addedBranches = newBranchKeys.filter((branchKey) => !(branchKey in oldUnion.branches));
+    if (addedBranches.length > 0) {
+        return autoOutcome(attributePath, "union-branch-addition", `branches added: ${addedBranches.join(", ")}`);
+    }
+    return autoOutcome(attributePath, "copy", "compatible discriminated union");
+}
+function hasStricterConstraints(oldAttribute, newAttribute) {
+    const oldConstraints = oldAttribute.typia.constraints;
+    const nextConstraints = newAttribute.typia.constraints;
+    const oldEnum = oldAttribute.wp.enum ?? null;
+    const nextEnum = newAttribute.wp.enum ?? null;
+    if (nextEnum && (!oldEnum || !oldEnum.every((value) => nextEnum.includes(value)))) {
+        return true;
+    }
+    if (isNumber(nextConstraints.minLength) &&
+        (!isNumber(oldConstraints.minLength) || nextConstraints.minLength > oldConstraints.minLength)) {
+        return true;
+    }
+    if (isNumber(nextConstraints.maxLength) &&
+        (!isNumber(oldConstraints.maxLength) || nextConstraints.maxLength < oldConstraints.maxLength)) {
+        return true;
+    }
+    if (isNumber(nextConstraints.minimum) &&
+        (!isNumber(oldConstraints.minimum) || nextConstraints.minimum > oldConstraints.minimum)) {
+        return true;
+    }
+    if (isNumber(nextConstraints.maximum) &&
+        (!isNumber(oldConstraints.maximum) || nextConstraints.maximum < oldConstraints.maximum)) {
+        return true;
+    }
+    if (nextConstraints.pattern && nextConstraints.pattern !== oldConstraints.pattern) {
+        return true;
+    }
+    if (nextConstraints.format && nextConstraints.format !== oldConstraints.format) {
+        return true;
+    }
+    if (nextConstraints.typeTag && nextConstraints.typeTag !== oldConstraints.typeTag) {
+        return true;
+    }
+    return false;
+}
+function autoOutcome(pathLabel, kind, detail) {
+    return { detail, kind, path: pathLabel, status: "auto" };
+}
+function manualOutcome(pathLabel, kind, detail) {
+    return { detail, kind, path: pathLabel, status: "manual" };
+}

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

@@ -0,0 +1,8 @@
+import type { MigrationBlockConfig, MigrationDiff, MigrationFixtureDocument } from "./migration-types.js";
+export declare function ensureEdgeFixtureFile(projectDir: string, block: MigrationBlockConfig, fromVersion: string, toVersion: string, diff: MigrationDiff, { force }?: {
+    force?: boolean;
+}): {
+    fixturePath: string;
+    written: boolean;
+};
+export declare function createEdgeFixtureDocument(projectDir: string, block: MigrationBlockConfig, fromVersion: string, toVersion: string, diff: MigrationDiff): MigrationFixtureDocument;

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

@@ -0,0 +1,94 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getProjectPaths, getFixtureFilePath, getSnapshotManifestPath, } from "./migration-project.js";
+import { defaultValueForManifestAttribute } from "./migration-manifest.js";
+import { cloneJsonValue, createFixtureScalarValue, createTransformFixtureValue, deleteValueAtPath, readJson, setValueAtPath, getValueAtPath, } from "./migration-utils.js";
+export function ensureEdgeFixtureFile(projectDir, block, fromVersion, toVersion, diff, { force = false } = {}) {
+    const fixturePath = getFixtureFilePath(getProjectPaths(projectDir), block, fromVersion, toVersion);
+    fs.mkdirSync(path.dirname(fixturePath), { recursive: true });
+    if (!force && fs.existsSync(fixturePath)) {
+        return { fixturePath, written: false };
+    }
+    const fixtureDocument = createEdgeFixtureDocument(projectDir, block, fromVersion, toVersion, diff);
+    fs.writeFileSync(fixturePath, `${JSON.stringify(fixtureDocument, null, "\t")}\n`, "utf8");
+    return { fixturePath, written: true };
+}
+export function createEdgeFixtureDocument(projectDir, block, fromVersion, toVersion, diff) {
+    const manifest = readJson(getSnapshotManifestPath(projectDir, block, fromVersion));
+    const attributes = {};
+    for (const [key, attribute] of Object.entries(manifest.attributes ?? {})) {
+        attributes[key] = defaultValueForManifestAttribute(attribute) ?? null;
+    }
+    const cases = [
+        {
+            input: attributes,
+            name: "default",
+        },
+        ...createRenameFixtureCases(attributes, diff.summary.renameCandidates),
+        ...createTransformFixtureCases(attributes, diff.summary.transformSuggestions),
+        ...createUnionFixtureCases(attributes, manifest.attributes ?? {}, diff.summary.renameCandidates),
+    ];
+    return {
+        cases,
+        fromVersion,
+        toVersion,
+    };
+}
+function createRenameFixtureCases(baseAttributes, renameCandidates) {
+    return renameCandidates
+        .filter((candidate) => candidate.autoApply)
+        .map((candidate) => {
+        const nextInput = cloneJsonValue(baseAttributes);
+        const legacyValue = getValueAtPath(nextInput, candidate.legacyPath);
+        deleteValueAtPath(nextInput, candidate.currentPath);
+        if (legacyValue === undefined) {
+            setValueAtPath(nextInput, candidate.legacyPath, createFixtureScalarValue(candidate.currentPath));
+        }
+        return {
+            input: nextInput,
+            name: `rename:${candidate.legacyPath}->${candidate.currentPath}`,
+        };
+    });
+}
+function createTransformFixtureCases(baseAttributes, transformSuggestions) {
+    return transformSuggestions.map((suggestion) => {
+        const nextInput = cloneJsonValue(baseAttributes);
+        const legacyPath = suggestion.legacyPath ?? suggestion.currentPath;
+        setValueAtPath(nextInput, legacyPath, createTransformFixtureValue(suggestion.attribute, suggestion.currentPath));
+        return {
+            input: nextInput,
+            name: `transform:${legacyPath}->${suggestion.currentPath}`,
+        };
+    });
+}
+function createUnionFixtureCases(baseAttributes, manifestAttributes, renameCandidates) {
+    const cases = [];
+    for (const [key, attribute] of Object.entries(manifestAttributes)) {
+        if (attribute.ts.kind !== "union" || !attribute.ts.union) {
+            continue;
+        }
+        for (const [branchKey, branch] of Object.entries(attribute.ts.union.branches ?? {})) {
+            const nextInput = cloneJsonValue(baseAttributes);
+            const legacyPath = renameCandidates.find((candidate) => candidate.autoApply && candidate.currentPath === key)?.legacyPath ??
+                key;
+            setValueAtPath(nextInput, legacyPath, createUnionBranchFixtureValue(attribute.ts.union.discriminator, branchKey, branch));
+            cases.push({
+                input: nextInput,
+                name: `union:${key}:${branchKey}`,
+            });
+        }
+    }
+    return cases;
+}
+function createUnionBranchFixtureValue(discriminator, branchKey, branchAttribute) {
+    const branchValue = defaultValueForManifestAttribute(branchAttribute);
+    if (typeof branchValue === "object" && branchValue !== null && !Array.isArray(branchValue)) {
+        return {
+            ...branchValue,
+            [discriminator]: branchKey,
+        };
+    }
+    return {
+        [discriminator]: branchKey,
+    };
+}

package/dist/runtime/migration/migration-fuzz-plan.d.ts

@@ -0,0 +1,2 @@
+import type { ManifestDocument, MigrationDiff, MigrationFuzzPlan } from "./migration-types.js";
+export declare function createMigrationFuzzPlan(legacyManifest: ManifestDocument, currentManifest: ManifestDocument, diff: MigrationDiff): MigrationFuzzPlan;

package/dist/runtime/migration/migration-fuzz-plan.js

@@ -0,0 +1,50 @@
+import { flattenManifestLeafAttributes } from "./migration-manifest.js";
+function isBlockedPath(pathLabel, blockedPaths) {
+    return blockedPaths.some((blockedPath) => pathLabel === blockedPath || pathLabel.startsWith(`${blockedPath}.`));
+}
+function unique(items) {
+    return [...new Set(items)];
+}
+export function createMigrationFuzzPlan(legacyManifest, currentManifest, diff) {
+    const legacyLeafMap = new Map(flattenManifestLeafAttributes(legacyManifest.attributes ?? {}).map((descriptor) => [
+        descriptor.currentPath,
+        descriptor,
+    ]));
+    const currentLeafDescriptors = flattenManifestLeafAttributes(currentManifest.attributes ?? {});
+    const autoRenameMap = new Map(diff.summary.renameCandidates
+        .filter((candidate) => candidate.autoApply)
+        .map((candidate) => [candidate.currentPath, candidate.legacyPath]));
+    const blockedPaths = unique([
+        ...diff.summary.manualItems.map((item) => item.path),
+        ...diff.summary.transformSuggestions.map((item) => item.currentPath),
+        ...diff.summary.renameCandidates
+            .filter((candidate) => !candidate.autoApply)
+            .map((candidate) => candidate.currentPath),
+    ]);
+    const compatibleMappings = [];
+    for (const descriptor of currentLeafDescriptors) {
+        const currentPath = descriptor.currentPath;
+        if (isBlockedPath(currentPath, blockedPaths)) {
+            continue;
+        }
+        const legacyPath = autoRenameMap.get(currentPath) ?? currentPath;
+        const legacyDescriptor = legacyLeafMap.get(legacyPath);
+        if (!legacyDescriptor) {
+            continue;
+        }
+        if (legacyDescriptor.attribute.ts.kind !== descriptor.attribute.ts.kind) {
+            continue;
+        }
+        if (!["string", "number", "boolean"].includes(descriptor.attribute.ts.kind)) {
+            continue;
+        }
+        compatibleMappings.push({
+            currentPath,
+            legacyPath,
+        });
+    }
+    return {
+        blockedPaths,
+        compatibleMappings,
+    };
+}

package/dist/runtime/migration/migration-generated-artifacts.d.ts

@@ -0,0 +1,3 @@
+import type { GeneratedMigrationEntry, MigrationProjectState } from "./migration-types.js";
+export declare function collectGeneratedMigrationEntries(state: MigrationProjectState): GeneratedMigrationEntry[];
+export declare function regenerateGeneratedArtifacts(projectDir: string): void;

package/dist/runtime/migration/migration-generated-artifacts.js

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ROOT_PHP_MIGRATION_REGISTRY } from "./migration-constants.js";
+import { createMigrationDiff } from "./migration-diff.js";
+import { createMigrationFuzzPlan } from "./migration-fuzz-plan.js";
+import { discoverMigrationEntries, getGeneratedDirForBlock, getSnapshotManifestPath, loadMigrationProject, } from "./migration-project.js";
+import { renderFuzzFile, renderGeneratedDeprecatedFile, renderGeneratedMigrationIndexFile, renderMigrationRegistryFile, renderPhpMigrationRegistryFile, renderVerifyFile, } from "./migration-render.js";
+import { createMigrationRiskSummary } from "./migration-risk.js";
+import { readJson } from "./migration-utils.js";
+export function collectGeneratedMigrationEntries(state) {
+    return discoverMigrationEntries(state).map((entry) => {
+        const block = state.blocks.find((target) => target.key === entry.block.key);
+        if (!block) {
+            throw new Error(`Unknown migration block target: ${entry.block.key}`);
+        }
+        const diff = createMigrationDiff(state, entry.block, entry.fromVersion, entry.toVersion);
+        const legacyManifest = readJson(getSnapshotManifestPath(state.projectDir, entry.block, entry.fromVersion));
+        return {
+            diff,
+            entry,
+            fuzzPlan: createMigrationFuzzPlan(legacyManifest, block.currentManifest, diff),
+            riskSummary: createMigrationRiskSummary(diff),
+        };
+    });
+}
+export function regenerateGeneratedArtifacts(projectDir) {
+    const state = loadMigrationProject(projectDir);
+    const generatedEntries = collectGeneratedMigrationEntries(state);
+    for (const block of state.blocks) {
+        const blockGeneratedEntries = generatedEntries.filter(({ entry }) => entry.block.key === block.key);
+        const entries = blockGeneratedEntries.map(({ entry }) => entry);
+        const generatedDir = getGeneratedDirForBlock(state.paths, block);
+        fs.mkdirSync(generatedDir, { recursive: true });
+        fs.writeFileSync(path.join(generatedDir, "registry.ts"), renderMigrationRegistryFile(state, block.key, blockGeneratedEntries), "utf8");
+        fs.writeFileSync(path.join(generatedDir, "deprecated.ts"), renderGeneratedDeprecatedFile(state, block.key, entries), "utf8");
+        fs.writeFileSync(path.join(generatedDir, "verify.ts"), renderVerifyFile(state, block.key, entries), "utf8");
+        fs.writeFileSync(path.join(generatedDir, "fuzz.ts"), renderFuzzFile(state, block.key, blockGeneratedEntries), "utf8");
+    }
+    fs.writeFileSync(path.join(state.paths.generatedDir, "index.ts"), renderGeneratedMigrationIndexFile(state, generatedEntries.map(({ entry }) => entry)), "utf8");
+    fs.writeFileSync(path.join(projectDir, ROOT_PHP_MIGRATION_REGISTRY), renderPhpMigrationRegistryFile(state, generatedEntries.map(({ entry }) => entry)), "utf8");
+}

package/dist/runtime/migration/migration-maintenance-fixtures.d.ts

@@ -0,0 +1,23 @@
+import type { FixturesOptions, FuzzOptions } from './migration-command-surface.js';
+/**
+ * Generate or refresh migration fixtures for one or more legacy edges.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param options Fixture generation scope and refresh options.
+ * @returns Generated and skipped legacy versions.
+ */
+export declare function fixturesProjectMigrations(projectDir: string, { all, confirmOverwrite, force, fromMigrationVersion, isInteractive, renderLine, toMigrationVersion, }?: FixturesOptions): {
+    generatedVersions: string[];
+    skippedVersions: string[];
+};
+/**
+ * Run seeded migration fuzz verification against generated fuzz artifacts.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param options Fuzz scope, iteration count, seed, and console rendering options.
+ * @returns Fuzzed legacy versions and the effective seed.
+ */
+export declare function fuzzProjectMigrations(projectDir: string, { all, fromMigrationVersion, iterations, renderLine, seed, }?: FuzzOptions): {
+    fuzzedVersions: string[];
+    seed: number | undefined;
+};

package/dist/runtime/migration/migration-maintenance-fixtures.js

@@ -0,0 +1,126 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { createMigrationDiff } from './migration-diff.js';
+import { ensureEdgeFixtureFile, } from './migration-fixtures.js';
+import { collectFixtureTargets, formatScaffoldCommand, getSelectedEntriesByBlock, isLegacySingleBlockProject, resolveLegacyVersions, } from './migration-planning.js';
+import { assertRuleHasNoTodos, getGeneratedDirForBlock, loadMigrationProject, } from './migration-project.js';
+import { getLocalTsxBinary, isInteractiveTerminal, resolveTargetMigrationVersion, } from './migration-utils.js';
+/**
+ * Generate or refresh migration fixtures for one or more legacy edges.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param options Fixture generation scope and refresh options.
+ * @returns Generated and skipped legacy versions.
+ */
+export function fixturesProjectMigrations(projectDir, { all = false, confirmOverwrite, force = false, fromMigrationVersion, isInteractive = isInteractiveTerminal(), renderLine = console.log, toMigrationVersion = 'current', } = {}) {
+    const state = loadMigrationProject(projectDir);
+    const targetMigrationVersion = resolveTargetMigrationVersion(state.config.currentMigrationVersion, toMigrationVersion);
+    const targetVersions = resolveLegacyVersions(state, { all, fromMigrationVersion });
+    if (targetVersions.length === 0) {
+        renderLine('No legacy migration versions configured for fixture generation.');
+        return { generatedVersions: [], skippedVersions: [] };
+    }
+    const generatedVersions = [];
+    const skippedVersions = [];
+    const fixtureTargets = collectFixtureTargets(state, targetVersions, targetMigrationVersion);
+    if (force) {
+        const overwriteTargets = fixtureTargets.filter(({ fixturePath }) => fs.existsSync(fixturePath));
+        if (isInteractive && overwriteTargets.length > 0) {
+            const confirmed = confirmOverwrite?.(`About to overwrite ${overwriteTargets.length} existing migration fixture file(s). Continue?`) ??
+                promptForConfirmation(`About to overwrite ${overwriteTargets.length} existing migration fixture file(s). Continue?`);
+            if (!confirmed) {
+                renderLine(`Cancelled fixture refresh. Kept ${overwriteTargets.length} existing fixture file(s).`);
+                return {
+                    generatedVersions,
+                    skippedVersions: overwriteTargets.map(({ scopedLabel }) => scopedLabel),
+                };
+            }
+        }
+    }
+    for (const { block, fixturePath, scopedLabel, version } of fixtureTargets) {
+        const existed = fs.existsSync(fixturePath);
+        const diff = createMigrationDiff(state, block, version, targetMigrationVersion);
+        const result = ensureEdgeFixtureFile(projectDir, block, version, targetMigrationVersion, diff, { force });
+        if (result.written) {
+            generatedVersions.push(scopedLabel);
+            renderLine(`${existed ? 'Refreshed' : 'Generated'} fixture ${path.relative(projectDir, fixturePath)}`);
+        }
+        else {
+            skippedVersions.push(scopedLabel);
+            renderLine(`Preserved existing fixture ${path.relative(projectDir, fixturePath)} (use --force to refresh)`);
+        }
+    }
+    return {
+        generatedVersions,
+        skippedVersions,
+    };
+}
+/**
+ * Run seeded migration fuzz verification against generated fuzz artifacts.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param options Fuzz scope, iteration count, seed, and console rendering options.
+ * @returns Fuzzed legacy versions and the effective seed.
+ */
+export function fuzzProjectMigrations(projectDir, { all = false, fromMigrationVersion, iterations = 25, renderLine = console.log, seed, } = {}) {
+    const state = loadMigrationProject(projectDir);
+    const targetVersions = resolveLegacyVersions(state, { all, fromMigrationVersion });
+    const blockEntries = getSelectedEntriesByBlock(state, targetVersions, 'fuzz');
+    const legacySingleBlock = isLegacySingleBlockProject(state);
+    if (targetVersions.length === 0) {
+        renderLine('No legacy migration versions configured for fuzzing.');
+        return { fuzzedVersions: [], seed };
+    }
+    const tsxBinary = getLocalTsxBinary(projectDir);
+    for (const [blockKey, entries] of Object.entries(blockEntries)) {
+        const block = state.blocks.find((entry) => entry.key === blockKey);
+        if (!block || entries.length === 0) {
+            continue;
+        }
+        for (const entry of entries) {
+            assertRuleHasNoTodos(projectDir, block, entry.fromVersion, state.config.currentMigrationVersion);
+        }
+        const fuzzScriptPath = path.join(getGeneratedDirForBlock(state.paths, block), 'fuzz.ts');
+        if (!fs.existsSync(fuzzScriptPath)) {
+            const selectedVersionsForBlock = entries.map((entry) => entry.fromVersion);
+            throw new Error(`Generated fuzz script is missing for ${block.blockName} (${selectedVersionsForBlock.join(', ')}). ` +
+                `Run \`${formatScaffoldCommand(selectedVersionsForBlock)}\` first, then \`wp-typia migrate doctor --all\` if the workspace should already be scaffolded.`);
+        }
+        const selectedVersionsForBlock = entries.map((entry) => entry.fromVersion);
+        const args = [
+            fuzzScriptPath,
+            ...(all ? ['--all'] : ['--from-migration-version', selectedVersionsForBlock[0]]),
+            '--iterations',
+            String(iterations),
+            ...(seed === undefined ? [] : ['--seed', String(seed)]),
+        ];
+        execFileSync(tsxBinary, args, {
+            cwd: projectDir,
+            shell: process.platform === 'win32',
+            stdio: 'inherit',
+        });
+        renderLine(legacySingleBlock
+            ? `Fuzzed migrations for ${selectedVersionsForBlock.join(', ')}`
+            : `Fuzzed ${block.blockName} migrations for ${selectedVersionsForBlock.join(', ')}`);
+    }
+    return { fuzzedVersions: targetVersions, seed };
+}
+function promptForConfirmation(message) {
+    process.stdout.write(`${message} [y/N]: `);
+    const buffer = Buffer.alloc(1);
+    let answer = '';
+    while (true) {
+        const bytesRead = fs.readSync(process.stdin.fd, buffer, 0, 1, null);
+        if (bytesRead === 0) {
+            break;
+        }
+        const char = buffer.toString('utf8', 0, bytesRead);
+        if (char === '\n' || char === '\r') {
+            break;
+        }
+        answer += char;
+    }
+    const normalized = answer.trim().toLowerCase();
+    return normalized === 'y' || normalized === 'yes';
+}

package/dist/runtime/migration/migration-maintenance-verify.d.ts

@@ -0,0 +1,26 @@
+import type { VerifyOptions } from './migration-command-surface.js';
+/**
+ * Run deterministic migration verification against generated fixtures.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param options Verification scope and console rendering options.
+ * @returns Verified legacy versions.
+ */
+export declare function verifyProjectMigrations(projectDir: string, { all, fromMigrationVersion, renderLine, }?: VerifyOptions): {
+    verifiedVersions: string[];
+};
+/**
+ * Validate the migration workspace without mutating files.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param options Doctor scope and console rendering options.
+ * @returns Structured doctor check results for the selected legacy versions.
+ */
+export declare function doctorProjectMigrations(projectDir: string, { all, fromMigrationVersion, renderLine, }?: VerifyOptions): {
+    checkedVersions: string[];
+    checks: {
+        detail: string;
+        label: string;
+        status: "fail" | "pass";
+    }[];
+};