@wp-typia/project-tools 0.24.3 → 0.24.5

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

@@ -0,0 +1,234 @@
+import fs from "node:fs";
+import path from "node:path";
+import { summarizeManifest, summarizeUnionBranches } from "./migration-manifest.js";
+import { getSnapshotBlockJsonPath, getSnapshotManifestPath, getSnapshotSavePath, readRuleMetadata, } from "./migration-project.js";
+import { getGeneratedDir, normalizeImportPath } from "./migration-render-support.js";
+import { readJson, renderPhpValue } from "./migration-utils.js";
+/**
+ * Renders the generated migration registry module for a block target.
+ *
+ * Prefers manifest wrapper modules when they are available in the project,
+ * while still validating the imported manifest before the registry consumes it.
+ *
+ * @param state The resolved migration project state.
+ * @param blockKey The stable key for the block whose registry is being generated.
+ * @param entries The generated migration entries to include in the registry.
+ * @returns The generated TypeScript source code for the migration registry file.
+ */
+export function renderMigrationRegistryFile(state, blockKey, entries) {
+    const block = state.blocks.find((entry) => entry.key === blockKey);
+    if (!block) {
+        throw new Error(`Unknown migration block target: ${blockKey}`);
+    }
+    const generatedDir = getGeneratedDir(block, state);
+    const currentManifestWrapperCandidates = [
+        block.manifestFile.replace(/typia\.manifest\.json$/u, "manifest-document.ts"),
+        path.join(path.dirname(block.typesFile), "manifest-document.ts"),
+    ].filter((candidate, index, allCandidates) => candidate !== block.manifestFile && allCandidates.indexOf(candidate) === index);
+    const currentManifestWrapperFile = currentManifestWrapperCandidates.find((candidate) => fs.existsSync(path.join(state.projectDir, candidate))) ?? null;
+    const currentManifestSourceFile = currentManifestWrapperFile ?? block.manifestFile;
+    const currentManifestImport = normalizeImportPath(path.relative(generatedDir, path.join(state.projectDir, currentManifestSourceFile)), currentManifestWrapperFile !== null);
+    const imports = [
+        `import rawCurrentManifest from "${currentManifestImport}";`,
+        `import type { ManifestDocument, MigrationRiskSummary } from "${normalizeImportPath(path.relative(getGeneratedDir(block, state), path.join(state.projectDir, "src", "migrations", "helpers.ts")), true)}";`,
+        `import { parseManifestDocument } from "@wp-typia/block-runtime/editor";`,
+    ];
+    const body = [];
+    entries.forEach(({ entry, riskSummary }, index) => {
+        imports.push(`import manifest_${index} from "${entry.manifestImport}";`);
+        imports.push(`import * as rule_${index} from "${entry.ruleImport}";`);
+        body.push(`\t{`);
+        body.push(`\t\tfromMigrationVersion: "${entry.fromVersion}",`);
+        body.push(`\t\tmanifest: parseManifestDocument<ManifestDocument>(manifest_${index}),`);
+        body.push(`\t\triskSummary: ${JSON.stringify(riskSummary, null, "\t").replace(/\n/g, "\n\t\t")},`);
+        body.push(`\t\trule: rule_${index},`);
+        body.push(`\t},`);
+    });
+    return `/* eslint-disable prettier/prettier, @typescript-eslint/method-signature-style */
+${imports.join("\n")}
+
+interface MigrationRegistryEntry {
+\tfromMigrationVersion: string;
+\tmanifest: ManifestDocument;
+\triskSummary: MigrationRiskSummary;
+\trule: {
+\t\tmigrate(input: Record<string, unknown>): Record<string, unknown>;
+\t\tunresolved?: readonly string[];
+\t};
+}
+
+export const migrationRegistry: {
+\tcurrentMigrationVersion: string;
+\tcurrentManifest: ManifestDocument;
+\tentries: MigrationRegistryEntry[];
+} = {
+\tcurrentMigrationVersion: "${state.config.currentMigrationVersion}",
+\tcurrentManifest: parseManifestDocument<ManifestDocument>(rawCurrentManifest),
+\tentries: [
+${body.join("\n")}
+\t],
+};
+
+export default migrationRegistry;
+`;
+}
+/**
+ * Renders the generated deprecated module for a block target.
+ *
+ * The emitted module exposes the ordered deprecation array consumed by block
+ * registration and migration helpers.
+ *
+ * @param state The resolved migration project state.
+ * @param blockKey The stable key for the block whose deprecated entries are being generated.
+ * @param entries The migration entries that define deprecated manifest versions.
+ * @returns The generated TypeScript source code for the deprecated module.
+ */
+export function renderGeneratedDeprecatedFile(state, blockKey, entries) {
+    const block = state.blocks.find((entry) => entry.key === blockKey);
+    if (!block) {
+        throw new Error(`Unknown migration block target: ${blockKey}`);
+    }
+    const currentTypeName = typeof block.currentManifest.sourceType === "string" &&
+        block.currentManifest.sourceType.length > 0
+        ? block.currentManifest.sourceType
+        : "Record<string, unknown>";
+    const hasNamedCurrentType = currentTypeName !== "Record<string, unknown>";
+    const generatedDir = getGeneratedDir(block, state);
+    const typesImport = normalizeImportPath(path.relative(generatedDir, path.join(state.projectDir, block.typesFile)), true);
+    if (entries.length === 0) {
+        return `/* eslint-disable prettier/prettier */
+import type { BlockDeprecationList } from "@wp-typia/block-types/blocks/registration";
+${hasNamedCurrentType ? `import type { ${currentTypeName} } from "${typesImport}";\n` : ""}
+
+export const deprecated: BlockDeprecationList<${currentTypeName}> = [];
+`;
+    }
+    const imports = [
+        `import type { BlockConfiguration, BlockDeprecationList } from "@wp-typia/block-types/blocks/registration";`,
+        ...(hasNamedCurrentType
+            ? [`import type { ${currentTypeName} } from "${typesImport}";`]
+            : []),
+    ];
+    const definitions = [];
+    const arrayEntries = [];
+    entries.forEach((entry, index) => {
+        imports.push(`import block_${index} from "${entry.blockJsonImport}";`);
+        imports.push(`import save_${index} from "${entry.saveImport}";`);
+        imports.push(`import * as rule_${index} from "${entry.ruleImport}";`);
+        definitions.push(`const deprecated_${index}: BlockDeprecationList<${currentTypeName}>[number] = {`);
+        definitions.push(`\tattributes: (block_${index}.attributes ?? {}) as BlockConfiguration["attributes"],`);
+        definitions.push(`\tsave: save_${index} as BlockConfiguration["save"],`);
+        definitions.push(`\tmigrate(attributes: Record<string, unknown>) {`);
+        definitions.push(`\t\treturn rule_${index}.migrate(attributes);`);
+        definitions.push(`\t},`);
+        definitions.push(`};`);
+        arrayEntries.push(`deprecated_${index}`);
+    });
+    return `/* eslint-disable prettier/prettier */
+${imports.join("\n")}
+
+${definitions.join("\n\n")}
+
+export const deprecated: BlockDeprecationList<${currentTypeName}> = [${arrayEntries.join(", ")}];
+`;
+}
+export function renderGeneratedMigrationIndexFile(state, entries) {
+    if (state.blocks.length === 0) {
+        return `export const migrationBlocks = [] as const;\nexport default migrationBlocks;\n`;
+    }
+    const generatedDir = state.paths.generatedDir;
+    const imports = [];
+    const definitions = [];
+    state.blocks.forEach((block, index) => {
+        const scopedEntries = entries.filter((entry) => entry.block.key === block.key);
+        const registryImport = block.layout === "legacy" ? "./registry" : `./${block.key}/registry`;
+        const deprecatedImport = block.layout === "legacy" ? "./deprecated" : `./${block.key}/deprecated`;
+        const validatorsImport = normalizeImportPath(path.relative(generatedDir, path.join(state.projectDir, block.typesFile.replace(/types\.ts$/u, "validators.ts"))), true);
+        imports.push(`import registry_${index} from "${registryImport}";`);
+        imports.push(`import { deprecated as deprecated_${index} } from "${deprecatedImport}";`);
+        imports.push(`import { validators as validators_${index} } from "${validatorsImport}";`);
+        definitions.push(`\t{`);
+        definitions.push(`\t\tkey: "${block.key}",`);
+        definitions.push(`\t\tblockName: "${block.blockName}",`);
+        definitions.push(`\t\tregistry: registry_${index},`);
+        definitions.push(`\t\tdeprecated: deprecated_${index},`);
+        definitions.push(`\t\tvalidators: validators_${index},`);
+        definitions.push(`\t\tlegacyMigrationVersions: ${JSON.stringify(scopedEntries.map((entry) => entry.fromVersion))},`);
+        definitions.push(`\t},`);
+    });
+    return `/* eslint-disable prettier/prettier */
+${imports.join("\n")}
+
+export const migrationBlocks = [
+${definitions.join("\n")}
+] as const;
+
+export default migrationBlocks;
+`;
+}
+export function renderPhpMigrationRegistryFile(state, entries) {
+    const blocks = state.blocks.map((block) => {
+        const snapshots = Object.fromEntries(state.config.supportedMigrationVersions.map((version) => {
+            const manifestPath = getSnapshotManifestPath(state.projectDir, block, version);
+            const blockJsonPath = getSnapshotBlockJsonPath(state.projectDir, block, version);
+            const savePath = getSnapshotSavePath(state.projectDir, block, version);
+            return [
+                version,
+                {
+                    blockJson: fs.existsSync(blockJsonPath)
+                        ? {
+                            attributeNames: Object.keys((readJson(blockJsonPath).attributes ?? {})),
+                            name: readJson(blockJsonPath).name ?? null,
+                        }
+                        : null,
+                    hasSaveSnapshot: fs.existsSync(savePath),
+                    manifest: fs.existsSync(manifestPath)
+                        ? summarizeManifest(readJson(manifestPath))
+                        : null,
+                },
+            ];
+        }));
+        const edgeSummaries = entries
+            .filter((entry) => entry.block.key === block.key)
+            .map((entry) => {
+            const ruleMetadata = readRuleMetadata(entry.rulePath);
+            const snapshotManifest = snapshots[entry.fromVersion]?.manifest ?? null;
+            return {
+                autoAppliedRenameCount: ruleMetadata.renameMap.length,
+                autoAppliedRenames: ruleMetadata.renameMap,
+                fromMigrationVersion: entry.fromVersion,
+                nestedPathRenames: ruleMetadata.renameMap.filter((item) => item.currentPath.includes(".")),
+                ruleFile: path.relative(state.projectDir, entry.rulePath).replace(/\\/g, "/"),
+                toMigrationVersion: entry.toVersion,
+                transformKeys: ruleMetadata.transforms,
+                unionBranches: snapshotManifest ? summarizeUnionBranches(snapshotManifest) : [],
+                unresolved: ruleMetadata.unresolved,
+            };
+        });
+        return {
+            blockName: block.blockName,
+            currentManifest: summarizeManifest(block.currentManifest),
+            edges: edgeSummaries,
+            key: block.key,
+            legacyMigrationVersions: state.config.supportedMigrationVersions.filter((version) => version !== state.config.currentMigrationVersion),
+            snapshots,
+        };
+    });
+    return `<?php
+declare(strict_types=1);
+
+if ( ! defined( 'ABSPATH' ) ) {
+\texit;
+}
+
+/**
+ * Generated from advanced migration snapshots. Do not edit manually.
+ */
+return ${renderPhpValue({
+        currentMigrationVersion: state.config.currentMigrationVersion,
+        blocks,
+        snapshotDir: state.config.snapshotDir,
+        supportedMigrationVersions: state.config.supportedMigrationVersions,
+    }, 0)};
+`;
+}

package/dist/runtime/migration/migration-render-support.d.ts

@@ -0,0 +1,3 @@
+import type { MigrationProjectState } from "./migration-types.js";
+export declare function normalizeImportPath(relativePath: string, stripExtension?: boolean): string;
+export declare function getGeneratedDir(block: MigrationProjectState["blocks"][number], state: MigrationProjectState): string;

package/dist/runtime/migration/migration-render-support.js

@@ -0,0 +1,16 @@
+import path from "node:path";
+export function normalizeImportPath(relativePath, stripExtension = false) {
+    let nextPath = relativePath.replace(/\\/g, "/");
+    if (!nextPath.startsWith(".")) {
+        nextPath = `./${nextPath}`;
+    }
+    if (stripExtension) {
+        nextPath = nextPath.replace(/\.[^.]+$/u, "");
+    }
+    return nextPath;
+}
+export function getGeneratedDir(block, state) {
+    return block.layout === "legacy"
+        ? state.paths.generatedDir
+        : path.join(state.paths.generatedDir, block.key);
+}

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

@@ -0,0 +1,3 @@
+export { formatDiffReport, renderMigrationRuleFile } from "./migration-render-diff-rule.js";
+export { renderGeneratedDeprecatedFile, renderGeneratedMigrationIndexFile, renderMigrationRegistryFile, renderPhpMigrationRegistryFile, } from "./migration-render-generated.js";
+export { renderFuzzFile, renderVerifyFile } from "./migration-render-execution.js";

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

@@ -0,0 +1,3 @@
+export { formatDiffReport, renderMigrationRuleFile } from "./migration-render-diff-rule.js";
+export { renderGeneratedDeprecatedFile, renderGeneratedMigrationIndexFile, renderMigrationRegistryFile, renderPhpMigrationRegistryFile, } from "./migration-render-generated.js";
+export { renderFuzzFile, renderVerifyFile } from "./migration-render-execution.js";

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

@@ -0,0 +1,4 @@
+import type { MigrationDiff, MigrationRiskSummary } from "./migration-types.js";
+export declare function createEmptyMigrationRiskSummary(): MigrationRiskSummary;
+export declare function formatMigrationRiskSummary(summary: MigrationRiskSummary): string;
+export declare function createMigrationRiskSummary(diff: MigrationDiff): MigrationRiskSummary;

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

@@ -0,0 +1,52 @@
+function createRiskBucket(items) {
+    return {
+        count: items.length,
+        items,
+    };
+}
+function formatDiffOutcome(item) {
+    return `${item.path}: ${item.kind}${item.detail ? ` (${item.detail})` : ""}`;
+}
+function formatRenameCandidate(candidate) {
+    return `${candidate.currentPath} <- ${candidate.legacyPath} (${candidate.autoApply ? "auto" : "review"}, ${candidate.reason})`;
+}
+function formatTransformSuggestion(suggestion) {
+    return `${suggestion.currentPath}${suggestion.legacyPath ? ` <- ${suggestion.legacyPath}` : ""} (${suggestion.reason})`;
+}
+function unique(items) {
+    return [...new Set(items)];
+}
+export function createEmptyMigrationRiskSummary() {
+    return {
+        additive: createRiskBucket([]),
+        rename: createRiskBucket([]),
+        semanticTransform: createRiskBucket([]),
+        unionBreaking: createRiskBucket([]),
+    };
+}
+export function formatMigrationRiskSummary(summary) {
+    return `additive=${summary.additive.count}, rename=${summary.rename.count}, semanticTransform=${summary.semanticTransform.count}, unionBreaking=${summary.unionBreaking.count}`;
+}
+export function createMigrationRiskSummary(diff) {
+    const additiveKinds = new Set([
+        "add-default",
+        "add-optional",
+        "drop",
+        "hydrate",
+        "union-branch-addition",
+    ]);
+    const additiveItems = unique(diff.summary.autoItems
+        .filter((item) => additiveKinds.has(item.kind))
+        .map(formatDiffOutcome));
+    const renameItems = unique(diff.summary.renameCandidates.map(formatRenameCandidate));
+    const semanticTransformItems = unique(diff.summary.transformSuggestions.map(formatTransformSuggestion));
+    const unionBreakingItems = unique(diff.summary.manualItems
+        .filter((item) => item.kind.startsWith("union-"))
+        .map(formatDiffOutcome));
+    return {
+        additive: createRiskBucket(additiveItems),
+        rename: createRiskBucket(renameItems),
+        semanticTransform: createRiskBucket(semanticTransformItems),
+        unionBreaking: createRiskBucket(unionBreakingItems),
+    };
+}

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

@@ -0,0 +1,205 @@
+/**
+ * Shared migration contract facade for project-tools runtime.
+ *
+ * Re-exports canonical manifest and migration contracts from
+ * `@wp-typia/block-runtime/migration-types` and layers project-tools-specific
+ * migration workspace types on top.
+ */
+import type { JsonValue, ManifestAttribute, ManifestDocument } from "@wp-typia/block-runtime/migration-types";
+export type { JsonPrimitive, JsonValue, ManifestAttribute, ManifestConstraints, ManifestDocument, ManifestTsKind, ManifestTsMetadata, ManifestTypiaMetadata, ManifestUnionMetadata, ManifestWpMetadata, } from "@wp-typia/block-runtime/migration-types";
+export interface ManifestSummaryAttribute {
+    constraints: ManifestAttribute["typia"]["constraints"];
+    defaultValue: ManifestAttribute["typia"]["defaultValue"] | null;
+    enum: ManifestAttribute["wp"]["enum"] | null;
+    hasDefault: boolean;
+    kind: ManifestAttribute["ts"]["kind"] | null;
+    required: boolean;
+    union: ManifestAttribute["ts"]["union"] | null;
+}
+export interface ManifestSummary {
+    attributes: Record<string, ManifestSummaryAttribute>;
+    manifestVersion: number | null;
+    sourceType: string | null;
+}
+export interface UnionBranchSummary {
+    branches: string[];
+    discriminator: string | null;
+    field: string;
+}
+/**
+ * Declares the migration-lineage labels and block targets used by a project migration workspace.
+ *
+ * These labels describe schema lineage such as `v1`, `v2`, and `v3`; they do
+ * not represent package, plugin, or release versions.
+ */
+export interface MigrationConfig {
+    /** Optional single-block name used by legacy-root retrofit layouts. */
+    blockName?: string;
+    /** Optional explicit block target list for multi-block migration workspaces. */
+    blocks?: MigrationBlockConfig[];
+    /** Current migration-lineage label for newly generated snapshots and rules. */
+    currentMigrationVersion: string;
+    /** Relative directory that stores versioned migration snapshots. */
+    snapshotDir: string;
+    /** Ordered migration-lineage labels configured for this workspace, including the current label. */
+    supportedMigrationVersions: string[];
+}
+/**
+ * Declares one migration-capable block target inside a project workspace.
+ */
+export interface MigrationBlockConfig {
+    /** Relative path to the target block.json metadata file. */
+    blockJsonFile: string;
+    /** Registered block name for this migration target. */
+    blockName: string;
+    /** Stable block key used for generated file naming and registry entries. */
+    key: string;
+    /** Relative path to the generated manifest snapshot input for the block. */
+    manifestFile: string;
+    /** Relative path to the saved-markup source file used for snapshot capture. */
+    saveFile: string;
+    /** Relative path to the canonical types source for the block. */
+    typesFile: string;
+}
+export interface ResolvedMigrationBlockTarget extends MigrationBlockConfig {
+    currentBlockJson: Record<string, unknown>;
+    currentManifest: ManifestDocument;
+    layout: "legacy" | "multi";
+}
+export interface MigrationProjectPaths {
+    configFile: string;
+    fixturesDir: string;
+    generatedDir: string;
+    rulesDir: string;
+    snapshotDir: string;
+}
+export interface MigrationProjectState {
+    blocks: ResolvedMigrationBlockTarget[];
+    config: MigrationConfig;
+    currentBlockJson: Record<string, unknown>;
+    currentManifest: ManifestDocument;
+    paths: MigrationProjectPaths;
+    projectDir: string;
+}
+export interface MigrationEntry {
+    block: MigrationBlockConfig;
+    blockJsonImport: string;
+    fixtureImport: string;
+    fromVersion: string;
+    generatedDir: string;
+    manifestImport: string;
+    ruleImport: string;
+    rulePath: string;
+    saveImport: string;
+    toVersion: string;
+    validatorImport: string;
+}
+export interface RuleMetadata {
+    renameMap: Array<{
+        currentPath: string;
+        legacyPath: string;
+    }>;
+    transforms: string[];
+    unresolved: string[];
+}
+export interface FlattenedAttributeDescriptor {
+    attribute: ManifestAttribute;
+    currentPath: string;
+    rootPath: string;
+    sourcePath: string;
+    unionBranch: string | null;
+    unionDiscriminator: string | null;
+    unionRoot: string | null;
+}
+export interface DiffOutcome {
+    detail?: string;
+    kind: string;
+    path: string;
+    status: "auto" | "manual";
+}
+export interface RenameCandidate {
+    autoApply: boolean;
+    currentPath: string;
+    legacyPath: string;
+    reason: string;
+    score: number;
+}
+export interface TransformSuggestion {
+    attribute: ManifestAttribute | null;
+    bodyLines: string[];
+    currentPath: string;
+    legacyPath: string | null;
+    reason: string;
+}
+export interface MigrationDiffSummary {
+    auto: number;
+    autoItems: DiffOutcome[];
+    manual: number;
+    manualItems: DiffOutcome[];
+    renameCandidates: RenameCandidate[];
+    transformSuggestions: TransformSuggestion[];
+}
+export interface MigrationDiff {
+    currentTypeName: string | null | undefined;
+    fromVersion: string;
+    summary: MigrationDiffSummary;
+    toVersion: string;
+}
+export interface MigrationRiskBucket {
+    count: number;
+    items: string[];
+}
+export interface MigrationRiskSummary {
+    additive: MigrationRiskBucket;
+    rename: MigrationRiskBucket;
+    semanticTransform: MigrationRiskBucket;
+    unionBreaking: MigrationRiskBucket;
+}
+export interface MigrationFuzzMapping {
+    currentPath: string;
+    legacyPath: string;
+}
+export interface MigrationFuzzPlan {
+    blockedPaths: string[];
+    compatibleMappings: MigrationFuzzMapping[];
+}
+export interface GeneratedMigrationEntry {
+    diff: MigrationDiff;
+    entry: MigrationEntry;
+    fuzzPlan: MigrationFuzzPlan;
+    riskSummary: MigrationRiskSummary;
+}
+export interface MigrationRuleFileInput {
+    block: MigrationBlockConfig;
+    currentAttributes: Record<string, ManifestAttribute>;
+    currentTypeName: string | null | undefined;
+    diff: MigrationDiff;
+    fromVersion: string;
+    projectDir: string;
+    rulePath: string;
+    targetVersion: string;
+}
+export interface MigrationFixtureCase {
+    input: JsonObject;
+    name: string;
+}
+export interface MigrationFixtureDocument {
+    cases: MigrationFixtureCase[];
+    fromVersion: string;
+    toVersion: string;
+}
+export interface ParsedMigrationArgs {
+    command?: string;
+    flags: {
+        all: boolean;
+        currentMigrationVersion?: string;
+        force: boolean;
+        fromMigrationVersion?: string;
+        iterations?: string;
+        migrationVersion?: string;
+        seed?: string;
+        toMigrationVersion?: string;
+    };
+}
+export type RenderLine = (line: string) => void;
+export type JsonObject = Record<string, JsonValue>;

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

@@ -0,0 +1 @@
+export {};

package/dist/runtime/migration/migration-ui-capability.d.ts

@@ -0,0 +1,17 @@
+import type { PackageManagerId } from "../shared/package-managers.js";
+import type { ScaffoldTemplateVariables } from "../templates/scaffold.js";
+interface ApplyMigrationUiCapabilityOptions {
+    packageManager: PackageManagerId;
+    projectDir: string;
+    templateId: string;
+    variables: ScaffoldTemplateVariables;
+}
+/**
+ * Layer the migration dashboard capability onto a freshly scaffolded project.
+ *
+ * This copies the shared migration UI files, wires template-specific editor
+ * hooks, and injects pinned migration scripts that shell out to the matching
+ * `wp-typia` CLI version.
+ */
+export declare function applyMigrationUiCapability({ packageManager, projectDir, templateId, variables, }: ApplyMigrationUiCapabilityOptions): Promise<void>;
+export {};