@wp-typia/project-tools 0.24.4 → 0.24.5

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

@@ -1,337 +1 @@
-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;
-}
+export * from "./migration/migration-project-layout-discovery.js";

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

@@ -1,135 +1 @@
-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;
+export * from "./migration/migration-project-layout-paths.js";