@wp-typia/project-tools 0.11.1

package/dist/runtime/migration-utils.js

@@ -0,0 +1,246 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import { formatRunScript } from "./package-managers.js";
+export { cloneJsonValue } from "./json-utils.js";
+const MIGRATION_VERSION_LABEL_PATTERN = /^v([1-9]\d*)$/;
+const LEGACY_SEMVER_MIGRATION_VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+export function getValueAtPath(input, pathLabel) {
+    return String(pathLabel)
+        .split(".")
+        .reduce((value, segment) => value && typeof value === "object" ? value[segment] : undefined, input);
+}
+export function setValueAtPath(input, pathLabel, value) {
+    const segments = String(pathLabel).split(".");
+    let target = input;
+    while (segments.length > 1) {
+        const segment = segments.shift();
+        if (!segment) {
+            continue;
+        }
+        if (!target[segment] || typeof target[segment] !== "object" || Array.isArray(target[segment])) {
+            target[segment] = {};
+        }
+        target = target[segment];
+    }
+    target[segments[0]] = value;
+}
+export function deleteValueAtPath(input, pathLabel) {
+    const segments = String(pathLabel).split(".");
+    let target = input;
+    while (segments.length > 1) {
+        const segment = segments.shift();
+        if (!segment || !target[segment] || typeof target[segment] !== "object") {
+            return;
+        }
+        target = target[segment];
+    }
+    delete target[segments[0]];
+}
+export function createFixtureScalarValue(pathLabel) {
+    const normalized = String(pathLabel).toLowerCase();
+    if (normalized.includes("id")) {
+        return "00000000-0000-4000-8000-000000000000";
+    }
+    if (normalized.includes("count") || normalized.includes("number")) {
+        return 1;
+    }
+    if (normalized.includes("visible") || normalized.startsWith("is")) {
+        return true;
+    }
+    return `legacy:${pathLabel}`;
+}
+export function createTransformFixtureValue(attribute, pathLabel) {
+    switch (attribute?.ts?.kind) {
+        case "number":
+            return "42";
+        case "boolean":
+            return "1";
+        case "union":
+            return { kind: "unknown" };
+        default:
+            return createFixtureScalarValue(pathLabel);
+    }
+}
+export function readJson(filePath) {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+export function renderPhpValue(value, indentLevel) {
+    const indent = "\t".repeat(indentLevel);
+    const nestedIndent = "\t".repeat(indentLevel + 1);
+    if (value === null) {
+        return "null";
+    }
+    if (typeof value === "string") {
+        return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            return "[]";
+        }
+        const items = value.map((item) => `${nestedIndent}${renderPhpValue(item, indentLevel + 1)}`);
+        return `[\n${items.join(",\n")}\n${indent}]`;
+    }
+    if (typeof value === "object") {
+        const entries = Object.entries(value);
+        if (entries.length === 0) {
+            return "[]";
+        }
+        const items = entries.map(([key, item]) => `${nestedIndent}'${String(key).replace(/\\/g, "\\\\").replace(/'/g, "\\'")}' => ${renderPhpValue(item, indentLevel + 1)}`);
+        return `[\n${items.join(",\n")}\n${indent}]`;
+    }
+    throw new Error(`Unable to encode PHP migration registry value for ${String(value)}`);
+}
+export function copyFile(sourcePath, targetPath) {
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.copyFileSync(sourcePath, targetPath);
+}
+export function sanitizeSaveSnapshotSource(source) {
+    return source
+        .replace(/^import\s+\{[^}]+\}\s+from\s+['"]\.\/types['"];?\n?/gm, "")
+        .replace(/^interface\s+SaveProps\s*\{[\s\S]*?\}\n?/m, "")
+        .replace(/: SaveProps/g, ": { attributes: any }")
+        .replace(/attributes:\s*[A-Za-z0-9_<>{}\[\]|&,\s]+;/g, "attributes: any;")
+        .replace(/\(\{\s*attributes\s*\}:\s*\{\s*attributes:\s*any\s*\}\)/g, "({ attributes }: { attributes: any })")
+        .replace(/\n{3,}/g, "\n\n")
+        .trimEnd()
+        .concat("\n");
+}
+export function sanitizeSnapshotBlockJson(blockJson) {
+    const snapshot = { ...blockJson };
+    for (const key of [
+        "editorScript",
+        "script",
+        "scriptModule",
+        "viewScript",
+        "viewScriptModule",
+        "style",
+        "editorStyle",
+        "render",
+    ]) {
+        delete snapshot[key];
+    }
+    return snapshot;
+}
+export function runProjectScriptIfPresent(projectDir, scriptName) {
+    const packageJson = readJson(path.join(projectDir, "package.json"));
+    if (!packageJson.scripts?.[scriptName]) {
+        return;
+    }
+    const packageManagerId = detectPackageManagerId(projectDir);
+    execSync(formatRunScript(packageManagerId, scriptName), {
+        cwd: projectDir,
+        stdio: "inherit",
+    });
+}
+export function detectPackageManagerId(projectDir) {
+    const packageJson = readJson(path.join(projectDir, "package.json"));
+    const field = String(packageJson.packageManager ?? "");
+    if (field.startsWith("bun@"))
+        return "bun";
+    if (field.startsWith("npm@"))
+        return "npm";
+    if (field.startsWith("pnpm@"))
+        return "pnpm";
+    if (field.startsWith("yarn@"))
+        return "yarn";
+    return "bun";
+}
+export function getLocalTsxBinary(projectDir) {
+    const filename = process.platform === "win32" ? "tsx.cmd" : "tsx";
+    const binaryPath = path.join(projectDir, "node_modules", ".bin", filename);
+    if (!fs.existsSync(binaryPath)) {
+        throw new Error("Local tsx binary was not found. Install project dependencies before running migration verification.");
+    }
+    return binaryPath;
+}
+/**
+ * Returns whether isInteractiveTerminal() is running with both stdin and stdout
+ * attached to a TTY so CLI and migration flows can safely prompt the user.
+ */
+export function isInteractiveTerminal() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/**
+ * Resolves the `current` sentinel to the current migration version label.
+ *
+ * @param currentMigrationVersion Current migration version label for the workspace.
+ * @param value Requested target value, which may be `current`.
+ * @returns The concrete migration version label that should be used.
+ */
+export function resolveTargetMigrationVersion(currentMigrationVersion, value) {
+    return value === "current" ? currentMigrationVersion : value;
+}
+/**
+ * Returns whether a value matches the canonical `vN` migration label format.
+ *
+ * @param value Candidate migration version label.
+ * @returns `true` when the value is a valid `vN` label with `N >= 1`.
+ */
+export function isMigrationVersionLabel(value) {
+    return MIGRATION_VERSION_LABEL_PATTERN.test(value);
+}
+/**
+ * Returns whether a value looks like a legacy semver-based migration label.
+ *
+ * @param value Candidate migration version label.
+ * @returns `true` when the value matches the legacy `x.y.z` semver pattern.
+ */
+export function isLegacySemverMigrationVersion(value) {
+    return LEGACY_SEMVER_MIGRATION_VERSION_PATTERN.test(value);
+}
+/**
+ * Throws when a migration version label does not match the canonical `vN` format.
+ *
+ * @param value Candidate migration version label.
+ * @param label Human-readable label used in the thrown error message.
+ * @returns Nothing.
+ * @throws Error When the provided value is not a valid `vN` migration label.
+ */
+export function assertMigrationVersionLabel(value, label) {
+    if (!isMigrationVersionLabel(value)) {
+        throw new Error(`Invalid ${label}: ${value}. Expected vN with N >= 1.`);
+    }
+}
+function parseMigrationVersionNumber(value) {
+    const match = value.match(MIGRATION_VERSION_LABEL_PATTERN);
+    if (!match) {
+        throw new Error(`Invalid migration version label: ${value}. Expected vN with N >= 1.`);
+    }
+    return Number.parseInt(match[1], 10);
+}
+/**
+ * Compares two migration version labels by their numeric suffix.
+ *
+ * @param left Left migration version label.
+ * @param right Right migration version label.
+ * @returns A negative number when `left < right`, zero when equal, and a positive number when `left > right`.
+ */
+export function compareMigrationVersionLabels(left, right) {
+    return parseMigrationVersionNumber(left) - parseMigrationVersionNumber(right);
+}
+/**
+ * Formats the reset guidance shown when a legacy semver migration workspace is detected.
+ *
+ * @param reason Optional leading reason that explains what legacy pattern was found.
+ * @returns A user-facing guidance string that explains how to reset to `v1` labels.
+ */
+export function formatLegacyMigrationWorkspaceResetGuidance(reason) {
+    return [
+        reason ? `${reason} ` : "",
+        "Back up `src/migrations/` if needed, remove or reset the existing migration workspace, ",
+        "then rerun `wp-typia migrate init --current-migration-version v1`.",
+    ].join("");
+}
+export function escapeForCode(value) {
+    return String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+export function renderObjectKey(key) {
+    return JSON.stringify(String(key));
+}
+export function isNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}

package/dist/runtime/migrations.d.ts

@@ -0,0 +1,249 @@
+import { createMigrationDiff } from "./migration-diff.js";
+import { formatDiffReport } from "./migration-render.js";
+import { createMigrationRiskSummary } from "./migration-risk.js";
+import type { MigrationBlockConfig, ParsedMigrationArgs, RenderLine } from "./migration-types.js";
+import type { ReadlinePrompt } from "./cli-prompt.js";
+type CommandRenderOptions = {
+    prompt?: ReadlinePrompt;
+    renderLine?: RenderLine;
+};
+type DiffLikeOptions = {
+    fromMigrationVersion?: string;
+    renderLine?: RenderLine;
+    toMigrationVersion?: string;
+};
+type VerifyOptions = {
+    all?: boolean;
+    fromMigrationVersion?: string;
+    renderLine?: RenderLine;
+};
+type FixturesOptions = {
+    all?: boolean;
+    confirmOverwrite?: ((message: string) => boolean) | undefined;
+    force?: boolean;
+    fromMigrationVersion?: string;
+    isInteractive?: boolean;
+    renderLine?: RenderLine;
+    toMigrationVersion?: string;
+};
+type FuzzOptions = {
+    all?: boolean;
+    fromMigrationVersion?: string;
+    iterations?: number;
+    renderLine?: RenderLine;
+    seed?: number;
+};
+type MigrationPlanBlockSummary = {
+    blockName: string;
+    diff: ReturnType<typeof createMigrationDiff>;
+    riskSummary: ReturnType<typeof createMigrationRiskSummary>;
+};
+type MigrationPlanSummary = {
+    availableLegacyVersions: string[];
+    currentMigrationVersion: string;
+    fromMigrationVersion: string;
+    includedBlocks: string[];
+    nextSteps: string[];
+    skippedBlocks: string[];
+    summaries: MigrationPlanBlockSummary[];
+    targetMigrationVersion: string;
+};
+type WizardOptions = CommandRenderOptions & {
+    isInteractive?: boolean;
+};
+/**
+ * Returns the formatted help text for migration CLI commands and flags.
+ *
+ * @returns Multi-line usage text for the `wp-typia migrate` command surface.
+ */
+export declare function formatMigrationHelpText(): string;
+/**
+ * Parses migration CLI arguments into a structured command payload.
+ *
+ * @param argv Command-line arguments that follow the `migrate` subcommand.
+ * @returns Parsed migration command and normalized flags for runtime dispatch.
+ * @throws Error When no arguments are provided, an unknown flag is encountered, or legacy semver flags are used.
+ */
+export declare function parseMigrationArgs(argv: string[]): ParsedMigrationArgs;
+export { formatDiffReport };
+/**
+ * Dispatch a parsed migration command to the matching runtime workflow.
+ *
+ * Most commands execute synchronously and preserve direct throw semantics for
+ * existing callers. The interactive `wizard` command returns a promise because
+ * it waits for prompt selection before running the shared read-only planner.
+ *
+ * @param command Parsed migration command and flags.
+ * @param cwd Project directory to operate on.
+ * @param options Optional prompt/render hooks for testable and interactive execution.
+ * @returns The command result, or a promise when the selected command is interactive.
+ */
+export declare function runMigrationCommand(command: ParsedMigrationArgs, cwd: string, { prompt, renderLine }?: CommandRenderOptions): import("./migration-types.js").MigrationProjectState | import("./migration-types.js").MigrationDiff | MigrationPlanSummary | Promise<MigrationPlanSummary | {
+    cancelled: true;
+}> | {
+    block: import("./migration-types.js").ResolvedMigrationBlockTarget;
+    diff: import("./migration-types.js").MigrationDiff;
+}[] | {
+    blockName: string;
+    diff: ReturnType<typeof createMigrationDiff>;
+    rulePath: string;
+} | {
+    scaffolded: {
+        blockName: string;
+        diff: ReturnType<typeof createMigrationDiff>;
+        rulePath: string;
+    }[];
+} | {
+    verifiedVersions: string[];
+} | {
+    checkedVersions: string[];
+    checks: {
+        detail: string;
+        label: string;
+        status: "fail" | "pass";
+    }[];
+} | {
+    generatedVersions: string[];
+    skippedVersions: string[];
+} | {
+    fuzzedVersions: never[];
+    seed?: undefined;
+} | {
+    fuzzedVersions: string[];
+    seed: number | undefined;
+};
+/**
+ * Preview one migration edge without scaffolding rules, fixtures, or generated files.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param options Selected source/target versions plus optional line rendering overrides.
+ * @returns A structured summary of the selected edge, included/skipped block targets, and next steps.
+ */
+export declare function planProjectMigrations(projectDir: string, { fromMigrationVersion, renderLine, toMigrationVersion }?: DiffLikeOptions): MigrationPlanSummary;
+/**
+ * Interactively choose one legacy version to preview, then run the same read-only planner.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param options Interactive prompt and rendering settings. Throws when no TTY is available.
+ * @returns The planned migration summary, or `{ cancelled: true }` when the user exits the wizard.
+ */
+export declare function wizardProjectMigrations(projectDir: string, { isInteractive, prompt, renderLine, }?: WizardOptions): Promise<MigrationPlanSummary | {
+    cancelled: true;
+}>;
+/**
+ * Initializes migration scaffolding for a detected single-block or multi-block project layout.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param currentMigrationVersion Initial migration version label to seed, such as `v1`.
+ * @param options Console rendering options used to report retrofit detection and initialization output.
+ * @returns The loaded migration project state after the config, snapshots, and generated files are written.
+ * @throws Error When the project layout is unsupported or the migration version label is invalid.
+ */
+export declare function initProjectMigrations(projectDir: string, currentMigrationVersion: string, { renderLine }?: CommandRenderOptions): import("./migration-types.js").MigrationProjectState;
+/**
+ * Captures the current project state as a named migration snapshot and refreshes generated artifacts.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param migrationVersion Migration version label to snapshot, such as `v2`.
+ * @param options Console rendering options and snapshot side-effect flags.
+ * @returns The loaded migration project state after the snapshot files and registry outputs are refreshed.
+ * @throws Error When the label is invalid, the project is not migration-capable, or `sync-types` fails.
+ */
+export declare function snapshotProjectVersion(projectDir: string, migrationVersion: string, { renderLine, skipConfigUpdate, skipSyncTypes, }?: CommandRenderOptions & {
+    skipConfigUpdate?: boolean;
+    skipSyncTypes?: boolean;
+}): import("./migration-types.js").MigrationProjectState;
+/**
+ * Computes and renders migration diffs for a selected legacy-to-target edge.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param options Selected source and target migration versions plus optional line rendering overrides.
+ * @returns A single diff for single-block workspaces, or an array of per-block diffs for multi-block workspaces.
+ * @throws Error When `fromMigrationVersion` is missing or no eligible snapshots exist for the selected edge.
+ */
+export declare function diffProjectMigrations(projectDir: string, { fromMigrationVersion, toMigrationVersion, renderLine, }?: DiffLikeOptions): import("./migration-types.js").MigrationDiff | {
+    block: import("./migration-types.js").ResolvedMigrationBlockTarget;
+    diff: import("./migration-types.js").MigrationDiff;
+}[];
+/**
+ * Scaffolds migration rule and fixture files for a selected legacy-to-target edge.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param options Selected source and target migration versions plus optional line rendering overrides.
+ * @returns A single scaffold result for single-block workspaces, or a grouped result for multi-block workspaces.
+ * @throws Error When `fromMigrationVersion` is missing or no eligible snapshots exist for the selected edge.
+ */
+export declare function scaffoldProjectMigrations(projectDir: string, { fromMigrationVersion, toMigrationVersion, renderLine, }?: DiffLikeOptions): {
+    blockName: string;
+    diff: ReturnType<typeof createMigrationDiff>;
+    rulePath: string;
+} | {
+    scaffolded: {
+        blockName: string;
+        diff: ReturnType<typeof createMigrationDiff>;
+        rulePath: string;
+    }[];
+};
+/**
+ * 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";
+    }[];
+};
+/**
+ * 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: never[];
+    seed?: undefined;
+} | {
+    fuzzedVersions: string[];
+    seed: number | undefined;
+};
+/**
+ * Initialize migration scaffolding for one or more block targets.
+ *
+ * Writes the migration config, creates the initial scaffold files, snapshots
+ * the current project state, and regenerates generated migration artifacts.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param currentMigrationVersion Initial migration version label to seed into the migration config.
+ * @param blocks Block targets to register for migration-aware scaffolding.
+ * @param options Console rendering options for initialization output.
+ * @returns The loaded migration project state after initialization completes.
+ */
+export declare function seedProjectMigrations(projectDir: string, currentMigrationVersion: string, blocks: MigrationBlockConfig[], { renderLine }?: CommandRenderOptions): import("./migration-types.js").MigrationProjectState;