@wp-typia/project-tools 0.24.3 → 0.24.5

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

@@ -0,0 +1,267 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { ROOT_PHP_MIGRATION_REGISTRY, } from './migration-constants.js';
+import { createMigrationDiff } from './migration-diff.js';
+import { createEdgeFixtureDocument, } from './migration-fixtures.js';
+import { collectGeneratedMigrationEntries, } from './migration-generated-artifacts.js';
+import { formatScaffoldCommand, getSelectedEntriesByBlock, hasSnapshotForVersion, isLegacySingleBlockProject, isSnapshotOptionalForBlockVersion, resolveLegacyVersions, } from './migration-planning.js';
+import { assertRuleHasNoTodos, getFixtureFilePath, getGeneratedDirForBlock, getRuleFilePath, getSnapshotBlockJsonPath, getSnapshotManifestPath, getSnapshotRoot, getSnapshotSavePath, loadMigrationProject, readRuleMetadata, } from './migration-project.js';
+import { renderFuzzFile, renderGeneratedDeprecatedFile, renderGeneratedMigrationIndexFile, renderMigrationRegistryFile, renderPhpMigrationRegistryFile, renderVerifyFile, } from './migration-render.js';
+import { createMigrationRiskSummary, formatMigrationRiskSummary, } from './migration-risk.js';
+import { getLocalTsxBinary, readJson, } from './migration-utils.js';
+import { readWorkspaceInventory } from '../workspace/workspace-inventory.js';
+import { getInvalidWorkspaceProjectReason, tryResolveWorkspaceProject, } from '../workspace/workspace-project.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 function verifyProjectMigrations(projectDir, { all = false, fromMigrationVersion, renderLine = console.log, } = {}) {
+    const state = loadMigrationProject(projectDir);
+    const targetVersions = resolveLegacyVersions(state, { all, fromMigrationVersion });
+    const blockEntries = getSelectedEntriesByBlock(state, targetVersions, 'verify');
+    const legacySingleBlock = isLegacySingleBlockProject(state);
+    if (targetVersions.length === 0) {
+        renderLine('No legacy migration versions configured for verification.');
+        return { verifiedVersions: [] };
+    }
+    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 verifyScriptPath = path.join(getGeneratedDirForBlock(state.paths, block), 'verify.ts');
+        if (!fs.existsSync(verifyScriptPath)) {
+            const selectedVersionsForBlock = entries.map((entry) => entry.fromVersion);
+            throw new Error(`Generated verify 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 filteredArgs = all
+            ? ['--all']
+            : ['--from-migration-version', selectedVersionsForBlock[0]];
+        execFileSync(tsxBinary, [verifyScriptPath, ...filteredArgs], {
+            cwd: projectDir,
+            shell: process.platform === 'win32',
+            stdio: 'inherit',
+        });
+        renderLine(legacySingleBlock
+            ? `Verified migrations for ${selectedVersionsForBlock.join(', ')}`
+            : `Verified ${block.blockName} migrations for ${selectedVersionsForBlock.join(', ')}`);
+    }
+    return { verifiedVersions: targetVersions };
+}
+function recordWorkspaceMigrationTargetAlignment(projectDir, state, recordCheck) {
+    // `migrate doctor` is still a synchronous maintenance command: it shares
+    // sync migration project loading, generated artifact comparisons, and
+    // execFileSync verification with the rest of migration maintenance.
+    let invalidWorkspaceReason = null;
+    let workspace;
+    try {
+        invalidWorkspaceReason = getInvalidWorkspaceProjectReason(projectDir);
+        workspace = tryResolveWorkspaceProject(projectDir);
+    }
+    catch (error) {
+        recordCheck('fail', 'Workspace migration targets', error instanceof Error ? error.message : String(error));
+        return;
+    }
+    if (!workspace) {
+        if (invalidWorkspaceReason) {
+            recordCheck('fail', 'Workspace migration targets', invalidWorkspaceReason);
+        }
+        return;
+    }
+    try {
+        // Maintenance verification is intentionally synchronous so it can compare
+        // migration state against a single inventory snapshot.
+        const inventory = readWorkspaceInventory(workspace.projectDir);
+        const expectedTargets = inventory.blocks.map((block) => `${workspace.workspace.namespace}/${block.slug}`);
+        const configuredTargets = state.blocks.map((block) => block.blockName);
+        const expectedTargetSet = new Set(expectedTargets);
+        const configuredTargetSet = new Set(configuredTargets);
+        const missingTargets = expectedTargets.filter((target) => !configuredTargetSet.has(target));
+        const staleTargets = configuredTargets.filter((target) => !expectedTargetSet.has(target));
+        recordCheck(missingTargets.length === 0 && staleTargets.length === 0 ? 'pass' : 'fail', 'Workspace migration targets', missingTargets.length === 0 && staleTargets.length === 0
+            ? `${expectedTargets.length} workspace block target(s) align with migration config`
+            : [
+                missingTargets.length > 0
+                    ? `Missing from migration config: ${missingTargets.join(', ')}`
+                    : null,
+                staleTargets.length > 0
+                    ? `Not present in scripts/block-config.ts: ${staleTargets.join(', ')}`
+                    : null,
+            ]
+                .filter((detail) => typeof detail === 'string')
+                .join('; '));
+    }
+    catch (error) {
+        recordCheck('fail', 'Workspace migration targets', error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * 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 function doctorProjectMigrations(projectDir, { all = false, fromMigrationVersion, renderLine = console.log, } = {}) {
+    const checks = [];
+    const recordCheck = (status, label, detail) => {
+        checks.push({ detail, label, status });
+        renderLine(`${status === 'pass' ? 'PASS' : 'FAIL'} ${label}: ${detail}`);
+    };
+    let state;
+    try {
+        state = loadMigrationProject(projectDir);
+        const legacySingleBlock = isLegacySingleBlockProject(state);
+        recordCheck('pass', 'Migration config', legacySingleBlock
+            ? `Loaded ${state.blocks[0]?.blockName} @ ${state.config.currentMigrationVersion}`
+            : `Loaded ${state.blocks.length} block target(s) @ ${state.config.currentMigrationVersion}`);
+    }
+    catch (error) {
+        recordCheck('fail', 'Migration config', error instanceof Error ? error.message : String(error));
+        throw new Error('Migration doctor failed.');
+    }
+    const targetVersions = resolveLegacyVersions(state, { all, fromMigrationVersion });
+    const legacySingleBlock = isLegacySingleBlockProject(state);
+    const snapshotVersions = new Set(targetVersions.length > 0
+        ? [state.config.currentMigrationVersion, ...targetVersions]
+        : state.config.supportedMigrationVersions);
+    recordWorkspaceMigrationTargetAlignment(projectDir, state, recordCheck);
+    for (const version of snapshotVersions) {
+        for (const block of state.blocks) {
+            const snapshotRoot = getSnapshotRoot(projectDir, block, version);
+            const blockJsonPath = getSnapshotBlockJsonPath(projectDir, block, version);
+            const manifestPath = getSnapshotManifestPath(projectDir, block, version);
+            const savePath = getSnapshotSavePath(projectDir, block, version);
+            const hasSnapshot = fs.existsSync(snapshotRoot);
+            const snapshotIsOptional = !hasSnapshot && isSnapshotOptionalForBlockVersion(state, block, version);
+            recordCheck(hasSnapshot || snapshotIsOptional ? 'pass' : 'fail', legacySingleBlock ? `Snapshot ${version}` : `Snapshot ${block.blockName} @ ${version}`, hasSnapshot
+                ? path.relative(projectDir, snapshotRoot)
+                : 'Not present for this version');
+            if (!hasSnapshot) {
+                continue;
+            }
+            for (const targetPath of [blockJsonPath, manifestPath, savePath]) {
+                recordCheck(fs.existsSync(targetPath) ? 'pass' : 'fail', legacySingleBlock
+                    ? `Snapshot file ${version}`
+                    : `Snapshot file ${block.blockName} @ ${version}`, fs.existsSync(targetPath)
+                    ? path.relative(projectDir, targetPath)
+                    : `Missing ${path.relative(projectDir, targetPath)}`);
+            }
+        }
+    }
+    try {
+        const generatedEntries = collectGeneratedMigrationEntries(state);
+        const expectedGeneratedFiles = new Map();
+        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);
+            expectedGeneratedFiles.set(path.join(generatedDir, 'registry.ts'), renderMigrationRegistryFile(state, block.key, blockGeneratedEntries));
+            expectedGeneratedFiles.set(path.join(generatedDir, 'deprecated.ts'), renderGeneratedDeprecatedFile(state, block.key, entries));
+            expectedGeneratedFiles.set(path.join(generatedDir, 'verify.ts'), renderVerifyFile(state, block.key, entries));
+            expectedGeneratedFiles.set(path.join(generatedDir, 'fuzz.ts'), renderFuzzFile(state, block.key, blockGeneratedEntries));
+        }
+        expectedGeneratedFiles.set(path.join(state.paths.generatedDir, 'index.ts'), renderGeneratedMigrationIndexFile(state, generatedEntries.map(({ entry }) => entry)));
+        expectedGeneratedFiles.set(path.join(projectDir, ROOT_PHP_MIGRATION_REGISTRY), renderPhpMigrationRegistryFile(state, generatedEntries.map(({ entry }) => entry)));
+        for (const [filePath, expectedSource] of expectedGeneratedFiles) {
+            const inSync = fs.existsSync(filePath) && fs.readFileSync(filePath, 'utf8') === expectedSource;
+            recordCheck(inSync ? 'pass' : 'fail', `Generated ${path.relative(projectDir, filePath)}`, inSync
+                ? 'In sync'
+                : 'Run `wp-typia migrate scaffold --from-migration-version <label>` or regenerate artifacts');
+        }
+    }
+    catch (error) {
+        recordCheck('fail', 'Generated artifacts', error instanceof Error ? error.message : String(error));
+    }
+    for (const version of targetVersions) {
+        for (const block of state.blocks) {
+            if (!hasSnapshotForVersion(state, block, version)) {
+                recordCheck('pass', `Snapshot coverage ${block.blockName} @ ${version}`, 'Target not present for this version');
+                continue;
+            }
+            const rulePath = getRuleFilePath(state.paths, block, version, state.config.currentMigrationVersion);
+            const fixturePath = getFixtureFilePath(state.paths, block, version, state.config.currentMigrationVersion);
+            recordCheck(fs.existsSync(rulePath) ? 'pass' : 'fail', legacySingleBlock ? `Rule ${version}` : `Rule ${block.blockName} @ ${version}`, fs.existsSync(rulePath)
+                ? path.relative(projectDir, rulePath)
+                : `Missing ${path.relative(projectDir, rulePath)}`);
+            recordCheck(fs.existsSync(fixturePath) ? 'pass' : 'fail', legacySingleBlock ? `Fixture ${version}` : `Fixture ${block.blockName} @ ${version}`, fs.existsSync(fixturePath)
+                ? path.relative(projectDir, fixturePath)
+                : `Missing ${path.relative(projectDir, fixturePath)}`);
+            if (!fs.existsSync(rulePath) || !fs.existsSync(fixturePath)) {
+                continue;
+            }
+            try {
+                assertRuleHasNoTodos(projectDir, block, version, state.config.currentMigrationVersion);
+                recordCheck('pass', legacySingleBlock
+                    ? `Rule TODOs ${version}`
+                    : `Rule TODOs ${block.blockName} @ ${version}`, 'No TODO MIGRATION markers remain');
+            }
+            catch (error) {
+                recordCheck('fail', legacySingleBlock
+                    ? `Rule TODOs ${version}`
+                    : `Rule TODOs ${block.blockName} @ ${version}`, error instanceof Error ? error.message : String(error));
+            }
+            try {
+                const ruleMetadata = readRuleMetadata(rulePath);
+                recordCheck(ruleMetadata.unresolved.length === 0 ? 'pass' : 'fail', legacySingleBlock
+                    ? `Rule unresolved ${version}`
+                    : `Rule unresolved ${block.blockName} @ ${version}`, ruleMetadata.unresolved.length === 0
+                    ? 'No unresolved entries remain'
+                    : ruleMetadata.unresolved.join(', '));
+            }
+            catch (error) {
+                recordCheck('fail', legacySingleBlock
+                    ? `Rule unresolved ${version}`
+                    : `Rule unresolved ${block.blockName} @ ${version}`, error instanceof Error ? error.message : String(error));
+            }
+            try {
+                const fixtureDocument = readJson(fixturePath);
+                recordCheck(Array.isArray(fixtureDocument.cases) && fixtureDocument.cases.length > 0
+                    ? 'pass'
+                    : 'fail', legacySingleBlock
+                    ? `Fixture parse ${version}`
+                    : `Fixture parse ${block.blockName} @ ${version}`, Array.isArray(fixtureDocument.cases) && fixtureDocument.cases.length > 0
+                    ? `${fixtureDocument.cases.length} case(s)`
+                    : 'Fixture document has no cases');
+                const diff = createMigrationDiff(state, block, version, state.config.currentMigrationVersion);
+                const expectedFixture = createEdgeFixtureDocument(projectDir, block, version, state.config.currentMigrationVersion, diff);
+                const actualCaseNames = new Set((fixtureDocument.cases ?? []).map((fixtureCase) => fixtureCase.name));
+                const missingCases = expectedFixture.cases
+                    .map((fixtureCase) => fixtureCase.name)
+                    .filter((name) => !actualCaseNames.has(name));
+                recordCheck(missingCases.length === 0 ? 'pass' : 'fail', legacySingleBlock
+                    ? `Fixture coverage ${version}`
+                    : `Fixture coverage ${block.blockName} @ ${version}`, missingCases.length === 0
+                    ? 'All expected fixture cases are present'
+                    : `Missing ${missingCases.join(', ')}`);
+                recordCheck('pass', legacySingleBlock
+                    ? `Risk summary ${version}`
+                    : `Risk summary ${block.blockName} @ ${version}`, formatMigrationRiskSummary(createMigrationRiskSummary(diff)));
+            }
+            catch (error) {
+                recordCheck('fail', legacySingleBlock
+                    ? `Fixture parse ${version}`
+                    : `Fixture parse ${block.blockName} @ ${version}`, error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+    const failedChecks = checks.filter((check) => check.status === 'fail');
+    renderLine(`${failedChecks.length === 0 ? 'PASS' : 'FAIL'} Migration doctor summary: ${checks.length - failedChecks.length}/${checks.length} checks passed`);
+    if (failedChecks.length > 0) {
+        throw new Error('Migration doctor failed.');
+    }
+    return {
+        checkedVersions: targetVersions,
+        checks,
+    };
+}

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

@@ -0,0 +1,2 @@
+export * from './migration-maintenance-verify.js';
+export * from './migration-maintenance-fixtures.js';

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

@@ -0,0 +1,2 @@
+export * from './migration-maintenance-verify.js';
+export * from './migration-maintenance-fixtures.js';

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

@@ -0,0 +1,19 @@
+import type { FlattenedAttributeDescriptor, JsonValue, ManifestAttribute, ManifestDocument, ManifestSummary, UnionBranchSummary } from "./migration-types.js";
+interface FlattenContext {
+    rootPath: string;
+    unionBranch: string | null;
+    unionDiscriminator: string | null;
+    unionRoot: string | null;
+}
+type ManifestDefaultValue = ManifestAttribute["typia"]["defaultValue"] | JsonValue[] | Record<string, JsonValue>;
+export declare function flattenManifestLeafAttributes(attributes: Record<string, ManifestAttribute>): FlattenedAttributeDescriptor[];
+export declare function flattenManifestAttribute(attribute: ManifestAttribute | undefined | null, currentPath: string, sourcePath: string, context: FlattenContext): FlattenedAttributeDescriptor[];
+export declare function getAttributeByCurrentPath(attributes: Record<string, ManifestAttribute>, currentPath: string): ManifestAttribute | null;
+export declare function hasManifestDefault(attribute: ManifestAttribute | undefined | null): boolean;
+export declare function getManifestDefaultValue(attribute: ManifestAttribute | undefined | null): string | number | boolean | JsonValue[] | {
+    [key: string]: JsonValue;
+} | null;
+export declare function summarizeManifest(manifest: ManifestDocument): ManifestSummary;
+export declare function summarizeUnionBranches(manifestSummary: ManifestSummary): UnionBranchSummary[];
+export declare function defaultValueForManifestAttribute(attribute: ManifestAttribute): ManifestDefaultValue | null;
+export {};

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

@@ -0,0 +1,129 @@
+export function flattenManifestLeafAttributes(attributes) {
+    return Object.entries(attributes).flatMap(([key, attribute]) => flattenManifestAttribute(attribute, key, key, {
+        rootPath: key,
+        unionBranch: null,
+        unionDiscriminator: null,
+        unionRoot: null,
+    }));
+}
+export function flattenManifestAttribute(attribute, currentPath, sourcePath, context) {
+    if (!attribute) {
+        return [];
+    }
+    if (attribute.ts.kind === "object") {
+        const properties = Object.entries(attribute.ts.properties ?? {});
+        if (properties.length === 0) {
+            return [{ ...context, attribute, currentPath, sourcePath }];
+        }
+        return properties.flatMap(([key, property]) => flattenManifestAttribute(property, `${currentPath}.${key}`, `${sourcePath}.${key}`, {
+            ...context,
+        }));
+    }
+    if (attribute.ts.kind === "union" && attribute.ts.union) {
+        const unionMetadata = attribute.ts.union;
+        return Object.entries(attribute.ts.union.branches ?? {}).flatMap(([branchKey, branchAttribute]) => Object.entries(branchAttribute.ts.properties ?? {})
+            .filter(([key]) => key !== unionMetadata.discriminator)
+            .flatMap(([key, property]) => flattenManifestAttribute(property, `${currentPath}.${branchKey}.${key}`, `${sourcePath}.${key}`, {
+            rootPath: context.rootPath,
+            unionBranch: branchKey,
+            unionDiscriminator: unionMetadata.discriminator,
+            unionRoot: currentPath,
+        })));
+    }
+    return [{ ...context, attribute, currentPath, sourcePath }];
+}
+export function getAttributeByCurrentPath(attributes, currentPath) {
+    const segments = String(currentPath).split(".");
+    const rootKey = segments.shift();
+    if (!rootKey) {
+        return null;
+    }
+    let attribute = attributes[rootKey] ?? null;
+    while (attribute && segments.length > 0) {
+        if (attribute.ts.kind === "union" && attribute.ts.union) {
+            const branchKey = segments.shift();
+            if (!branchKey || !(branchKey in attribute.ts.union.branches)) {
+                return null;
+            }
+            attribute = attribute.ts.union.branches[branchKey];
+            continue;
+        }
+        if (attribute.ts.kind === "object" && attribute.ts.properties) {
+            const propertyKey = segments.shift();
+            if (!propertyKey || !(propertyKey in attribute.ts.properties)) {
+                return null;
+            }
+            attribute = attribute.ts.properties[propertyKey];
+            continue;
+        }
+        return null;
+    }
+    return attribute;
+}
+export function hasManifestDefault(attribute) {
+    return attribute?.typia?.hasDefault === true;
+}
+export function getManifestDefaultValue(attribute) {
+    return attribute?.typia?.defaultValue ?? null;
+}
+export function summarizeManifest(manifest) {
+    return {
+        attributes: Object.fromEntries(Object.entries(manifest.attributes ?? {}).map(([name, attribute]) => [
+            name,
+            {
+                constraints: attribute.typia?.constraints ?? {},
+                defaultValue: attribute.typia?.defaultValue ?? null,
+                hasDefault: attribute.typia?.hasDefault ?? false,
+                enum: attribute.wp?.enum ?? null,
+                kind: attribute.ts?.kind ?? null,
+                required: attribute.ts?.required ?? false,
+                union: attribute.ts?.union ?? null,
+            },
+        ])),
+        manifestVersion: manifest.manifestVersion ?? null,
+        sourceType: manifest.sourceType ?? null,
+    };
+}
+export function summarizeUnionBranches(manifestSummary) {
+    if (!manifestSummary?.attributes) {
+        return [];
+    }
+    return Object.entries(manifestSummary.attributes)
+        .filter(([, attribute]) => attribute.kind === "union" && attribute.union)
+        .map(([field, attribute]) => ({
+        branches: Object.keys(attribute.union?.branches ?? {}),
+        discriminator: attribute.union?.discriminator ?? null,
+        field,
+    }));
+}
+export function defaultValueForManifestAttribute(attribute) {
+    if (attribute.typia?.hasDefault) {
+        return attribute.typia.defaultValue;
+    }
+    if (attribute.wp?.enum && attribute.wp.enum.length > 0) {
+        return attribute.wp.enum[0] ?? null;
+    }
+    switch (attribute.ts.kind) {
+        case "string":
+            return "";
+        case "number":
+            return 0;
+        case "boolean":
+            return false;
+        case "array":
+            return [];
+        case "object": {
+            const result = {};
+            for (const [key, property] of Object.entries(attribute.ts.properties ?? {})) {
+                result[key] = defaultValueForManifestAttribute(property);
+            }
+            return result;
+        }
+        case "union": {
+            const firstBranch = Object.values(attribute.ts.union?.branches ?? {})[0];
+            return firstBranch ? defaultValueForManifestAttribute(firstBranch) : null;
+        }
+        default:
+            return null;
+    }
+}

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

@@ -0,0 +1,23 @@
+import type { MigrationProjectState } from "./migration-types.js";
+export declare function hasSnapshotForVersion(state: MigrationProjectState, block: MigrationProjectState["blocks"][number], version: string): boolean;
+export declare function listConfiguredLegacyVersions(state: MigrationProjectState): string[];
+export declare function listPreviewableLegacyVersions(state: MigrationProjectState): string[];
+export declare function resolveLegacyVersions(state: MigrationProjectState, { all, availableVersions, fromMigrationVersion, }: {
+    all?: boolean;
+    availableVersions?: string[];
+    fromMigrationVersion?: string;
+}): string[];
+export declare function isSnapshotOptionalForBlockVersion(state: MigrationProjectState, block: MigrationProjectState["blocks"][number], version: string): boolean;
+export declare function isLegacySingleBlockProject(state: MigrationProjectState): boolean;
+export declare function getSelectedEntriesByBlock(state: MigrationProjectState, targetVersions: string[], command: "fuzz" | "verify"): Record<string, import("./migration-types.js").MigrationEntry[]>;
+export declare function assertDistinctMigrationEdge(command: "diff" | "plan" | "scaffold", fromVersion: string, toVersion: string): void;
+export declare function createMigrationPlanNextSteps(fromVersion: string, targetVersion: string, currentVersion: string): string[];
+export declare function formatEdgeCommand(command: "fixtures" | "scaffold", fromVersion: string, targetVersion: string, currentVersion: string): string;
+export declare function createMissingProjectSnapshotMessage(state: MigrationProjectState, fromVersion: string): string;
+export declare function formatScaffoldCommand(versions: string[]): string;
+export declare function collectFixtureTargets(state: MigrationProjectState, targetVersions: string[], targetVersion: string): {
+    block: import("./migration-types.js").ResolvedMigrationBlockTarget;
+    fixturePath: string;
+    scopedLabel: string;
+    version: string;
+}[];

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

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import { discoverMigrationEntries, getAvailableSnapshotVersionsForBlock, getFixtureFilePath, getSnapshotManifestPath, } from "./migration-project.js";
+import { compareMigrationVersionLabels } from "./migration-utils.js";
+export function hasSnapshotForVersion(state, block, version) {
+    return fs.existsSync(getSnapshotManifestPath(state.projectDir, block, version));
+}
+export function listConfiguredLegacyVersions(state) {
+    return state.config.supportedMigrationVersions
+        .filter((version) => version !== state.config.currentMigrationVersion)
+        .sort(compareMigrationVersionLabels);
+}
+export function listPreviewableLegacyVersions(state) {
+    return [
+        ...new Set(state.blocks.flatMap((block) => getAvailableSnapshotVersionsForBlock(state.projectDir, state.config.supportedMigrationVersions, block))),
+    ]
+        .filter((version) => version !== state.config.currentMigrationVersion)
+        .sort(compareMigrationVersionLabels);
+}
+export function resolveLegacyVersions(state, { all = false, availableVersions, fromMigrationVersion, }) {
+    const configuredLegacyVersions = listConfiguredLegacyVersions(state);
+    const legacyVersions = availableVersions ?? configuredLegacyVersions;
+    if (fromMigrationVersion) {
+        if (!legacyVersions.includes(fromMigrationVersion)) {
+            throw new Error(legacyVersions.length === 0
+                ? availableVersions && configuredLegacyVersions.length > 0
+                    ? `Unsupported migration version: ${fromMigrationVersion}. No previewable legacy migration versions are available yet because none currently have snapshot coverage. ` +
+                        `Restore or recapture the missing snapshots first.`
+                    : `Unsupported migration version: ${fromMigrationVersion}. No legacy migration versions are configured yet. ` +
+                        `Capture an older schema release with \`wp-typia migrate snapshot --migration-version <label>\` first.`
+                : `Unsupported migration version: ${fromMigrationVersion}. Available legacy migration versions: ${legacyVersions.join(", ")}.`);
+        }
+        return [fromMigrationVersion];
+    }
+    if (all) {
+        return legacyVersions;
+    }
+    return legacyVersions.slice(0, 1);
+}
+export function isSnapshotOptionalForBlockVersion(state, block, version) {
+    if (block.layout !== "multi") {
+        return false;
+    }
+    const introducedVersions = [...new Set(state.config.supportedMigrationVersions)]
+        .filter((candidateVersion) => hasSnapshotForVersion(state, block, candidateVersion))
+        .sort(compareMigrationVersionLabels);
+    const firstIntroducedVersion = introducedVersions[0];
+    if (!firstIntroducedVersion) {
+        return false;
+    }
+    return compareMigrationVersionLabels(version, firstIntroducedVersion) < 0;
+}
+export function isLegacySingleBlockProject(state) {
+    return state.blocks.length === 1 && state.blocks[0]?.layout === "legacy";
+}
+export function getSelectedEntriesByBlock(state, targetVersions, command) {
+    const discoveredEntries = discoverMigrationEntries(state);
+    const discoveredEntryKeys = new Set(discoveredEntries.map((entry) => `${entry.block.key}:${entry.fromVersion}`));
+    const missingEntries = targetVersions.flatMap((version) => state.blocks
+        .filter((block) => hasSnapshotForVersion(state, block, version))
+        .filter((block) => !discoveredEntryKeys.has(`${block.key}:${version}`))
+        .map((block) => ({ block, version })));
+    if (missingEntries.length > 0) {
+        const missingLabels = missingEntries
+            .map(({ block, version }) => `${block.blockName} @ ${version}`)
+            .join(", ");
+        const missingVersions = [...new Set(missingEntries.map(({ version }) => version))].sort(compareMigrationVersionLabels);
+        throw new Error(`Missing migration ${command} inputs for ${missingLabels}. ` +
+            `Run \`${formatScaffoldCommand(missingVersions)}\` first, then \`wp-typia migrate doctor --all\` if the workspace should already be scaffolded.`);
+    }
+    return groupEntriesByBlock(discoveredEntries.filter((entry) => targetVersions.includes(entry.fromVersion)));
+}
+export function assertDistinctMigrationEdge(command, fromVersion, toVersion) {
+    if (fromVersion === toVersion) {
+        throw new Error(`\`migrate ${command}\` requires different source and target migration versions, but both resolved to ${fromVersion}. ` +
+            `Choose an older snapshot with \`--from-migration-version <label>\` or capture a newer schema release with \`wp-typia migrate snapshot --migration-version <label>\` first.`);
+    }
+}
+export function createMigrationPlanNextSteps(fromVersion, targetVersion, currentVersion) {
+    if (targetVersion !== currentVersion) {
+        return [
+            formatEdgeCommand("scaffold", fromVersion, targetVersion, currentVersion),
+        ];
+    }
+    return [
+        formatEdgeCommand("scaffold", fromVersion, targetVersion, currentVersion),
+        `wp-typia migrate doctor --from-migration-version ${fromVersion}`,
+        `wp-typia migrate verify --from-migration-version ${fromVersion}`,
+        `wp-typia migrate fuzz --from-migration-version ${fromVersion}`,
+    ];
+}
+export function formatEdgeCommand(command, fromVersion, targetVersion, currentVersion) {
+    return targetVersion === currentVersion
+        ? `wp-typia migrate ${command} --from-migration-version ${fromVersion}`
+        : `wp-typia migrate ${command} --from-migration-version ${fromVersion} --to-migration-version ${targetVersion}`;
+}
+export function createMissingProjectSnapshotMessage(state, fromVersion) {
+    const snapshotVersions = [
+        ...new Set(state.blocks.flatMap((block) => getAvailableSnapshotVersionsForBlock(state.projectDir, state.config.supportedMigrationVersions, block))),
+    ].sort(compareMigrationVersionLabels);
+    return snapshotVersions.length === 0
+        ? `No migration block targets have a snapshot for ${fromVersion}. No snapshots exist yet in this project. ` +
+            `Run \`wp-typia migrate snapshot --migration-version ${fromVersion}\` first if you want to preserve that schema state.`
+        : `No migration block targets have a snapshot for ${fromVersion}. ` +
+            `Available snapshot versions in this project: ${snapshotVersions.join(", ")}. ` +
+            `Run \`wp-typia migrate snapshot --migration-version ${fromVersion}\` first if you want to preserve that schema state.`;
+}
+export function formatScaffoldCommand(versions) {
+    const uniqueVersions = [...new Set(versions)].sort(compareMigrationVersionLabels);
+    return uniqueVersions.length === 1
+        ? `wp-typia migrate scaffold --from-migration-version ${uniqueVersions[0]}`
+        : "wp-typia migrate scaffold --from-migration-version <label>";
+}
+export function collectFixtureTargets(state, targetVersions, targetVersion) {
+    return targetVersions.flatMap((version) => state.blocks
+        .filter((block) => hasSnapshotForVersion(state, block, version))
+        .map((block) => ({
+        block,
+        fixturePath: getFixtureFilePath(state.paths, block, version, targetVersion),
+        scopedLabel: `${block.key}@${version}`,
+        version,
+    })));
+}
+function groupEntriesByBlock(entries) {
+    return entries.reduce((accumulator, entry) => {
+        if (!accumulator[entry.block.key]) {
+            accumulator[entry.block.key] = [];
+        }
+        accumulator[entry.block.key].push(entry);
+        return accumulator;
+    }, {});
+}

package/dist/runtime/migration/migration-project-config-source.d.ts

@@ -0,0 +1,6 @@
+import type { MigrationConfig } from "./migration-types.js";
+export declare function normalizeRelativePath(value: string): string;
+export declare function ensureRelativePath(projectDir: string, filePath: string): string;
+export declare function hasLegacyConfigKeys(source: string): boolean;
+export declare function createLegacyMigrationWorkspaceResetError(reason: string): Error;
+export declare function parseMigrationConfig(source: string): MigrationConfig;