@wp-typia/project-tools 0.24.3 → 0.24.5

package/dist/runtime/migration/migration-project-layout-discovery.js

@@ -0,0 +1,337 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CONFIG_FILE, ROOT_BLOCK_JSON, ROOT_MANIFEST, ROOT_SAVE_FILE, ROOT_TYPES_FILE, SRC_BLOCK_JSON, SRC_MANIFEST, SUPPORTED_PROJECT_FILES, } from "./migration-constants.js";
+import { readJson, } from "./migration-utils.js";
+import { normalizeRelativePath, parseMigrationConfig, } from "./migration-project-config-source.js";
+const DEFAULT_BLOCK_KEY = "default";
+const SINGLE_BLOCK_LAYOUT_NOT_FOUND = "No supported single-block migration layout was found.";
+const SINGLE_BLOCK_LAYOUT_CANDIDATES = [
+    {
+        blockJsonFile: SRC_BLOCK_JSON,
+        manifestFile: SRC_MANIFEST,
+    },
+    {
+        blockJsonFile: ROOT_BLOCK_JSON,
+        manifestFile: ROOT_MANIFEST,
+    },
+];
+const LEGACY_ROOT_SINGLE_BLOCK_LAYOUT = SINGLE_BLOCK_LAYOUT_CANDIDATES[1];
+function readSingleBlockTarget(projectDir, { blockJsonFile, manifestFile, }) {
+    const requiredFiles = [blockJsonFile, ROOT_SAVE_FILE, ROOT_TYPES_FILE];
+    if (requiredFiles.some((relativePath) => !fs.existsSync(path.join(projectDir, relativePath)))) {
+        return null;
+    }
+    const blockName = readJson(path.join(projectDir, blockJsonFile))?.name;
+    if (typeof blockName !== "string" || blockName.length === 0) {
+        throw new Error(`Unable to resolve block name from ${normalizeRelativePath(blockJsonFile)}`);
+    }
+    return {
+        blockJsonFile: normalizeRelativePath(blockJsonFile),
+        blockName,
+        key: DEFAULT_BLOCK_KEY,
+        manifestFile: normalizeRelativePath(manifestFile),
+        saveFile: ROOT_SAVE_FILE,
+        typesFile: ROOT_TYPES_FILE,
+    };
+}
+function collectSingleBlockCandidates(projectDir) {
+    return SINGLE_BLOCK_LAYOUT_CANDIDATES.filter(({ blockJsonFile }) => hasSingleBlockLayoutFiles(projectDir, blockJsonFile));
+}
+function hasSingleBlockLayoutFiles(projectDir, blockJsonFile) {
+    return [blockJsonFile, ROOT_SAVE_FILE, ROOT_TYPES_FILE].every((relativePath) => fs.existsSync(path.join(projectDir, relativePath)));
+}
+function orderSingleBlockCandidates(projectDir, candidates) {
+    const candidatesWithManifest = candidates.filter(({ manifestFile }) => fs.existsSync(path.join(projectDir, manifestFile)));
+    return [
+        ...candidatesWithManifest,
+        ...candidates.filter((candidate) => !candidatesWithManifest.includes(candidate)),
+    ];
+}
+/**
+ * Synthesizes the implicit legacy migration block target for single-block projects.
+ *
+ * @param projectDir Project directory that may contain a legacy root migration layout.
+ * @param blockName Optional configured block name used to prefer a matching legacy root target.
+ * @returns The discovered single-block migration target keyed as `default`.
+ */
+export function createImplicitLegacyBlock(projectDir, blockName) {
+    if (blockName) {
+        try {
+            const rootTarget = readSingleBlockTarget(projectDir, LEGACY_ROOT_SINGLE_BLOCK_LAYOUT);
+            const srcTarget = readSingleBlockTarget(projectDir, SINGLE_BLOCK_LAYOUT_CANDIDATES[0]);
+            const hasSrcManifest = fs.existsSync(path.join(projectDir, SRC_MANIFEST));
+            if (rootTarget?.blockName === blockName &&
+                (!srcTarget || srcTarget.blockName !== blockName || !hasSrcManifest)) {
+                return {
+                    ...rootTarget,
+                    key: DEFAULT_BLOCK_KEY,
+                };
+            }
+        }
+        catch {
+            // Fall back to the shared discovery flow so malformed legacy roots do not block valid layouts.
+        }
+    }
+    const discovered = discoverSingleBlockTarget(projectDir, blockName);
+    return {
+        ...discovered,
+        key: DEFAULT_BLOCK_KEY,
+    };
+}
+function createMalformedMultiBlockTargetError(directory, reason) {
+    return new Error("Unable to auto-detect a supported migration retrofit layout. " +
+        `Detected ${path.join("src", "blocks", directory, "block.json")} but ${reason}. ` +
+        "Create `src/migrations/config.ts` manually if your project uses a custom layout.");
+}
+function getRequiredProjectFiles(projectDir, blocks) {
+    if (Array.isArray(blocks) && blocks.length > 0) {
+        return [
+            "package.json",
+            ...blocks.flatMap((block) => [block.blockJsonFile, block.saveFile, block.typesFile]),
+        ];
+    }
+    const configPath = path.join(projectDir, CONFIG_FILE);
+    if (fs.existsSync(configPath)) {
+        const config = parseMigrationConfig(fs.readFileSync(configPath, "utf8"));
+        const configuredBlocks = config.blocks ?? [createImplicitLegacyBlock(projectDir, config.blockName)];
+        return [
+            "package.json",
+            ...configuredBlocks.flatMap((block) => [block.blockJsonFile, block.saveFile, block.typesFile]),
+        ];
+    }
+    const discoveredLayout = discoverMigrationLayout(projectDir);
+    if (discoveredLayout?.mode === "multi") {
+        return [
+            "package.json",
+            ...discoveredLayout.blocks.flatMap((block) => [block.blockJsonFile, block.saveFile, block.typesFile]),
+        ];
+    }
+    if (discoveredLayout?.mode === "single") {
+        return [
+            "package.json",
+            discoveredLayout.block.blockJsonFile,
+            discoveredLayout.block.saveFile,
+            discoveredLayout.block.typesFile,
+        ];
+    }
+    return SUPPORTED_PROJECT_FILES;
+}
+/**
+ * Verifies that a project directory contains the files required for migration tooling.
+ *
+ * @param projectDir Project directory to validate.
+ * @param blocks Optional block targets to validate directly instead of auto-discovering them.
+ * @returns Nothing.
+ * @throws Error When any required project file is missing.
+ */
+export function ensureAdvancedMigrationProject(projectDir, blocks) {
+    const missing = getRequiredProjectFiles(projectDir, blocks).filter((relativePath) => !fs.existsSync(path.join(projectDir, relativePath)));
+    if (missing.length > 0) {
+        throw new Error(`This directory is not a supported migration-capable project. Missing: ${missing.join(", ")}`);
+    }
+}
+function createBlockTarget(projectDir, { blockJsonFile, key, manifestFile, saveFile, typesFile, }) {
+    const requiredFiles = [blockJsonFile, saveFile, typesFile];
+    if (requiredFiles.some((relativePath) => !fs.existsSync(path.join(projectDir, relativePath)))) {
+        return null;
+    }
+    const blockName = readJson(path.join(projectDir, blockJsonFile))?.name;
+    if (typeof blockName !== "string" || blockName.length === 0) {
+        return null;
+    }
+    return {
+        blockJsonFile: normalizeRelativePath(blockJsonFile),
+        blockName,
+        key,
+        manifestFile: normalizeRelativePath(manifestFile),
+        saveFile: normalizeRelativePath(saveFile),
+        typesFile: normalizeRelativePath(typesFile),
+    };
+}
+function discoverSingleBlockTarget(projectDir, preferredBlockName) {
+    const candidates = collectSingleBlockCandidates(projectDir);
+    if (candidates.length === 0) {
+        throw new Error(SINGLE_BLOCK_LAYOUT_NOT_FOUND);
+    }
+    const readCandidate = (candidate) => readSingleBlockTarget(projectDir, candidate);
+    const orderedCandidates = orderSingleBlockCandidates(projectDir, candidates);
+    if (preferredBlockName) {
+        const validTargets = [];
+        let firstReadError = null;
+        for (const candidate of orderedCandidates) {
+            try {
+                const target = readCandidate(candidate);
+                if (!target) {
+                    continue;
+                }
+                if (target.blockName === preferredBlockName) {
+                    return target;
+                }
+                validTargets.push(target);
+            }
+            catch (error) {
+                if (!firstReadError && error instanceof Error) {
+                    firstReadError = error;
+                }
+            }
+        }
+        if (validTargets.length > 0) {
+            throw new Error(`Configured migration blockName ${preferredBlockName} does not match the detected single-block layout(s): ${validTargets
+                .map((target) => target.blockName)
+                .join(", ")}.`);
+        }
+        if (firstReadError) {
+            throw firstReadError;
+        }
+    }
+    let firstReadError;
+    let sawReadError = false;
+    for (const candidate of orderedCandidates) {
+        try {
+            const target = readCandidate(candidate);
+            if (target) {
+                return target;
+            }
+        }
+        catch (error) {
+            if (!sawReadError) {
+                firstReadError = error;
+                sawReadError = true;
+            }
+        }
+    }
+    if (sawReadError) {
+        throw firstReadError;
+    }
+    throw new Error(SINGLE_BLOCK_LAYOUT_NOT_FOUND);
+}
+function discoverMigrationLayout(projectDir) {
+    const blocksRoot = path.join(projectDir, "src", "blocks");
+    let firstMultiBlockError = null;
+    if (fs.existsSync(blocksRoot) && fs.statSync(blocksRoot).isDirectory()) {
+        const blockDirectories = fs
+            .readdirSync(blocksRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+        const candidateDirectories = blockDirectories.filter((directory) => fs.existsSync(path.join(blocksRoot, directory, "block.json")));
+        if (candidateDirectories.length > 0) {
+            const blocks = candidateDirectories.flatMap((directory) => {
+                const saveFile = path.join("src", "blocks", directory, "save.tsx");
+                const typesFile = path.join("src", "blocks", directory, "types.ts");
+                const missingFiles = [saveFile, typesFile].filter((relativePath) => !fs.existsSync(path.join(projectDir, relativePath)));
+                if (missingFiles.length > 0) {
+                    firstMultiBlockError ?? (firstMultiBlockError = createMalformedMultiBlockTargetError(directory, `the block target is missing ${missingFiles.join(", ")}`));
+                    return [];
+                }
+                let block = null;
+                try {
+                    block = createBlockTarget(projectDir, {
+                        blockJsonFile: path.join("src", "blocks", directory, "block.json"),
+                        key: directory,
+                        manifestFile: path.join("src", "blocks", directory, "typia.manifest.json"),
+                        saveFile,
+                        typesFile,
+                    });
+                }
+                catch (error) {
+                    firstMultiBlockError ?? (firstMultiBlockError = error instanceof Error
+                        ? createMalformedMultiBlockTargetError(directory, `could not be parsed (${error.message})`)
+                        : createMalformedMultiBlockTargetError(directory, "could not be parsed"));
+                    return [];
+                }
+                if (!block) {
+                    firstMultiBlockError ?? (firstMultiBlockError = createMalformedMultiBlockTargetError(directory, "it does not expose a valid block name"));
+                    return [];
+                }
+                return [block];
+            });
+            if (blocks.length > 0) {
+                return {
+                    blocks: blocks.sort((left, right) => left.key.localeCompare(right.key)),
+                    mode: "multi",
+                };
+            }
+        }
+    }
+    try {
+        return {
+            block: discoverSingleBlockTarget(projectDir),
+            mode: "single",
+        };
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === SINGLE_BLOCK_LAYOUT_NOT_FOUND) {
+            if (firstMultiBlockError) {
+                throw firstMultiBlockError;
+            }
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Detects the supported migration retrofit layout for `migrate init`.
+ *
+ * Multi-block targets under `src/blocks/<slug>` take precedence over
+ * single-block layouts.
+ * Returns the detected layout on success and throws an actionable error when no
+ * supported first-party layout can be inferred.
+ *
+ * @param projectDir Project directory to inspect.
+ * @returns The discovered migration layout.
+ * @throws Error When no supported layout can be inferred.
+ */
+export function discoverMigrationInitLayout(projectDir) {
+    const discoveredLayout = discoverMigrationLayout(projectDir);
+    if (discoveredLayout) {
+        return discoveredLayout;
+    }
+    throw new Error("Unable to auto-detect a supported migration retrofit layout. " +
+        "Expected either `src/blocks/*/block.json` with matching `types.ts` and `save.tsx`, " +
+        "or a single-block layout using `src/block.json` (or legacy root `block.json`) with `src/types.ts` and `src/save.tsx`. " +
+        "Create `src/migrations/config.ts` manually if your project uses a custom layout.");
+}
+/**
+ * Resolves the configured migration block targets and their current artifacts.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @param config Parsed migration configuration.
+ * @returns The resolved block targets, including current block.json and manifest documents.
+ */
+export function resolveMigrationBlocks(projectDir, config) {
+    if (Array.isArray(config.blocks)) {
+        if (config.blocks.length === 0) {
+            return [];
+        }
+        return config.blocks.map((block) => {
+            const blockJsonPath = path.join(projectDir, block.blockJsonFile);
+            const manifestPath = path.join(projectDir, block.manifestFile);
+            return {
+                ...block,
+                currentBlockJson: readJson(blockJsonPath),
+                currentManifest: readJson(manifestPath),
+                layout: "multi",
+            };
+        });
+    }
+    return [createImplicitLegacyBlock(projectDir, config.blockName)].map((block) => {
+        const blockJsonPath = path.join(projectDir, block.blockJsonFile);
+        const manifestPath = path.join(projectDir, block.manifestFile);
+        return {
+            ...block,
+            currentBlockJson: readJson(blockJsonPath),
+            currentManifest: readJson(manifestPath),
+            layout: "legacy",
+        };
+    });
+}
+/**
+ * Returns the discovered block name for a supported single-block project.
+ *
+ * Uses `discoverSingleBlockTarget(projectDir)` internally and throws when the
+ * project directory does not resolve to a supported single-block migration
+ * layout.
+ */
+export function readProjectBlockName(projectDir) {
+    return discoverSingleBlockTarget(projectDir).blockName;
+}

package/dist/runtime/migration/migration-project-layout-paths.d.ts

@@ -0,0 +1,135 @@
+import type { MigrationBlockConfig, MigrationEntry, MigrationProjectPaths, MigrationProjectState, ResolvedMigrationBlockTarget, RuleMetadata } from "./migration-types.js";
+/**
+ * Resolves the canonical migration workspace paths for a project directory.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @returns Absolute filesystem paths for config, generated, fixture, rule, and snapshot roots.
+ */
+export declare function getProjectPaths(projectDir: string): MigrationProjectPaths;
+/**
+ * Resolves the snapshot root for a block target and migration version.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @param block Block target or resolved block target.
+ * @param version Migration version label.
+ * @returns The absolute snapshot root directory for the requested block/version pair.
+ */
+export declare function getSnapshotRoot(projectDir: string, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, version: string): string;
+/**
+ * Resolves the snapshot `block.json` path for a block target and migration version.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @param block Block target or resolved block target.
+ * @param version Migration version label.
+ * @returns The absolute snapshot `block.json` path.
+ */
+export declare function getSnapshotBlockJsonPath(projectDir: string, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, version: string): string;
+/**
+ * Resolves the snapshot manifest path for a block target and migration version.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @param block Block target or resolved block target.
+ * @param version Migration version label.
+ * @returns The absolute snapshot manifest path.
+ */
+export declare function getSnapshotManifestPath(projectDir: string, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, version: string): string;
+/**
+ * Lists the snapshot versions currently present for a specific block target.
+ *
+ * Returns the sorted subset of supported migration versions that have a manifest on disk
+ * for the provided block, or an empty array when none exist.
+ */
+export declare function getAvailableSnapshotVersionsForBlock(projectDir: string, supportedMigrationVersions: string[], block: MigrationBlockConfig | ResolvedMigrationBlockTarget): string[];
+/**
+ * Formats the standard missing-snapshot guidance for a block target.
+ *
+ * Returns a user-facing message that either lists the available snapshot
+ * versions or explains that no snapshots exist yet for the block.
+ */
+export declare function createMissingBlockSnapshotMessage(blockName: string, fromVersion: string, availableSnapshotVersions: string[]): string;
+/**
+ * Resolves the snapshot save source path for a block target and migration version.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @param block Block target or resolved block target.
+ * @param version Migration version label.
+ * @returns The absolute snapshot `save.tsx` path.
+ */
+export declare function getSnapshotSavePath(projectDir: string, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, version: string): string;
+/**
+ * Resolves the generated directory used for a block's migration output.
+ *
+ * @param paths Resolved migration project paths.
+ * @param block Block target or resolved block target.
+ * @returns The absolute generated directory for the block.
+ */
+export declare function getGeneratedDirForBlock(paths: MigrationProjectPaths, block: MigrationBlockConfig | ResolvedMigrationBlockTarget): string;
+/**
+ * Resolves the migration rule file path for a block version edge.
+ *
+ * @param paths Resolved migration project paths.
+ * @param block Block target or resolved block target.
+ * @param fromVersion Source migration version.
+ * @param toVersion Destination migration version.
+ * @returns The absolute migration rule file path.
+ */
+export declare function getRuleFilePath(paths: MigrationProjectPaths, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, fromVersion: string, toVersion: string): string;
+/**
+ * Resolves the migration fixture path for a block version edge.
+ *
+ * @param paths Resolved migration project paths.
+ * @param block Block target or resolved block target.
+ * @param fromVersion Source migration version.
+ * @param toVersion Destination migration version.
+ * @returns The absolute migration fixture file path.
+ */
+export declare function getFixtureFilePath(paths: MigrationProjectPaths, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, fromVersion: string, toVersion: string): string;
+/**
+ * Resolves the validators import path for generated migration artifacts.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @param block Block target or resolved block target.
+ * @param fromDir Directory that will import the validators module.
+ * @returns A relative module import path without a file extension.
+ */
+export declare function getValidatorsImportPath(projectDir: string, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, fromDir: string): string;
+/**
+ * Ensures the migration fixture, generated, rule, and snapshot directories exist.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @param blocks Optional block targets whose scoped rule/fixture directories should be created.
+ * @returns Nothing.
+ */
+export declare function ensureMigrationDirectories(projectDir: string, blocks?: MigrationBlockConfig[]): void;
+/**
+ * Discovers the generated migration registry entries for a loaded project state.
+ *
+ * @param state Loaded migration project state.
+ * @returns Sorted migration registry entries for every available block/version edge.
+ */
+export declare function discoverMigrationEntries(state: MigrationProjectState): MigrationEntry[];
+/**
+ * Verifies that a migration rule file exists and no TODO markers remain in it.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @param block Block target or resolved block target.
+ * @param fromMigrationVersion Source migration version.
+ * @param toMigrationVersion Destination migration version.
+ * @returns Nothing.
+ * @throws Error When the rule file is missing or still contains TODO markers.
+ */
+export declare function assertRuleHasNoTodos(projectDir: string, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, fromMigrationVersion: string, toMigrationVersion: string): void;
+/**
+ * Reads lightweight metadata from a migration rule source file.
+ *
+ * @param rulePath Absolute path to the migration rule source file.
+ * @returns Parsed unresolved paths, rename mappings, and transform keys.
+ */
+export declare function readRuleMetadata(rulePath: string): RuleMetadata;
+/**
+ * Normalizes a migration block config against the current working directory.
+ *
+ * @param block Migration block config with project-relative file paths.
+ * @returns A normalized migration block config with ensured relative paths.
+ */
+export declare function createMigrationBlockConfig(block: MigrationBlockConfig): MigrationBlockConfig;