@wp-typia/project-tools 0.11.1

package/dist/runtime/migration-fuzz-plan.js

@@ -0,0 +1,50 @@
+import { flattenManifestLeafAttributes } from "./migration-manifest.js";
+function isBlockedPath(pathLabel, blockedPaths) {
+    return blockedPaths.some((blockedPath) => pathLabel === blockedPath || pathLabel.startsWith(`${blockedPath}.`));
+}
+function unique(items) {
+    return [...new Set(items)];
+}
+export function createMigrationFuzzPlan(legacyManifest, currentManifest, diff) {
+    const legacyLeafMap = new Map(flattenManifestLeafAttributes(legacyManifest.attributes ?? {}).map((descriptor) => [
+        descriptor.currentPath,
+        descriptor,
+    ]));
+    const currentLeafDescriptors = flattenManifestLeafAttributes(currentManifest.attributes ?? {});
+    const autoRenameMap = new Map(diff.summary.renameCandidates
+        .filter((candidate) => candidate.autoApply)
+        .map((candidate) => [candidate.currentPath, candidate.legacyPath]));
+    const blockedPaths = unique([
+        ...diff.summary.manualItems.map((item) => item.path),
+        ...diff.summary.transformSuggestions.map((item) => item.currentPath),
+        ...diff.summary.renameCandidates
+            .filter((candidate) => !candidate.autoApply)
+            .map((candidate) => candidate.currentPath),
+    ]);
+    const compatibleMappings = [];
+    for (const descriptor of currentLeafDescriptors) {
+        const currentPath = descriptor.currentPath;
+        if (isBlockedPath(currentPath, blockedPaths)) {
+            continue;
+        }
+        const legacyPath = autoRenameMap.get(currentPath) ?? currentPath;
+        const legacyDescriptor = legacyLeafMap.get(legacyPath);
+        if (!legacyDescriptor) {
+            continue;
+        }
+        if (legacyDescriptor.attribute.ts.kind !== descriptor.attribute.ts.kind) {
+            continue;
+        }
+        if (!["string", "number", "boolean"].includes(descriptor.attribute.ts.kind)) {
+            continue;
+        }
+        compatibleMappings.push({
+            currentPath,
+            legacyPath,
+        });
+    }
+    return {
+        blockedPaths,
+        compatibleMappings,
+    };
+}

package/dist/runtime/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-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-project.d.ts

@@ -0,0 +1,94 @@
+import type { MigrationBlockConfig, MigrationConfig, MigrationEntry, MigrationProjectPaths, MigrationProjectState, ResolvedMigrationBlockTarget, RuleMetadata } from "./migration-types.js";
+/**
+ * Describes the migration retrofit layout discovered in a project directory.
+ *
+ * Multi-block discovery wins when block targets are discovered under
+ * `src/blocks/<slug>/block.json`.
+ * Otherwise the runtime falls back to a supported single-block layout.
+ */
+export type DiscoveredMigrationLayout = {
+    block: MigrationBlockConfig;
+    mode: "single";
+} | {
+    blocks: MigrationBlockConfig[];
+    mode: "multi";
+};
+export declare function ensureAdvancedMigrationProject(projectDir: string, blocks?: MigrationBlockConfig[]): void;
+export declare function getProjectPaths(projectDir: string): MigrationProjectPaths;
+/**
+ * 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.
+ */
+export declare function discoverMigrationInitLayout(projectDir: string): DiscoveredMigrationLayout;
+export declare function resolveMigrationBlocks(projectDir: string, config: MigrationConfig): ResolvedMigrationBlockTarget[];
+export declare function getSnapshotRoot(projectDir: string, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, version: string): string;
+export declare function getSnapshotBlockJsonPath(projectDir: string, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, version: string): string;
+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;
+export declare function getSnapshotSavePath(projectDir: string, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, version: string): string;
+export declare function getGeneratedDirForBlock(paths: MigrationProjectPaths, block: MigrationBlockConfig | ResolvedMigrationBlockTarget): string;
+export declare function getRuleFilePath(paths: MigrationProjectPaths, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, fromVersion: string, toVersion: string): string;
+export declare function getFixtureFilePath(paths: MigrationProjectPaths, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, fromVersion: string, toVersion: string): string;
+export declare function getValidatorsImportPath(projectDir: string, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, fromDir: string): string;
+export declare function ensureMigrationDirectories(projectDir: string, blocks?: MigrationBlockConfig[]): void;
+export declare function writeInitialMigrationScaffold(projectDir: string, currentMigrationVersion: string, blocks?: MigrationBlockConfig[]): void;
+/**
+ * Guards a project directory against legacy semver-based migration workspaces.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @returns Nothing.
+ * @throws Error When legacy config keys or semver-named migration artifacts are detected.
+ */
+export declare function assertNoLegacySemverMigrationWorkspace(projectDir: string): void;
+/**
+ * Loads the migration workspace state for a project directory.
+ *
+ * By default this loader may run the project's `sync-types` script when the
+ * current manifest files are missing, because later migration commands depend
+ * on those generated artifacts. Pass `allowSyncTypes: false` to keep the call
+ * read-only and fail instead of mutating the workspace.
+ *
+ * When `allowMissingConfig` is enabled and the migration config file does not
+ * exist yet, the loader synthesizes a minimal legacy-root config so bootstrap
+ * flows can continue before the first config write.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param options Loader flags controlling config fallback and `sync-types` side effects.
+ * @returns The resolved migration project state, including config, block targets, and helper paths.
+ * @throws Error When the project is not migration-capable, required manifests remain missing, or generated files cannot be read.
+ */
+export declare function loadMigrationProject(projectDir: string, { allowMissingConfig, allowSyncTypes, }?: {
+    allowMissingConfig?: boolean;
+    allowSyncTypes?: boolean;
+}): MigrationProjectState;
+export declare function discoverMigrationEntries(state: MigrationProjectState): MigrationEntry[];
+export declare function parseMigrationConfig(source: string): MigrationConfig;
+export declare function writeMigrationConfig(projectDir: string, config: MigrationConfig): void;
+/**
+ * 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 declare function readProjectBlockName(projectDir: string): string;
+export declare function assertRuleHasNoTodos(projectDir: string, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, fromMigrationVersion: string, toMigrationVersion: string): void;
+export declare function readRuleMetadata(rulePath: string): RuleMetadata;
+export declare function createMigrationBlockConfig(block: MigrationBlockConfig): MigrationBlockConfig;