@wp-typia/project-tools 0.11.1

package/dist/runtime/cli-templates.js

@@ -0,0 +1,61 @@
+import { getBuiltInTemplateLayerDirs } from "./template-builtins.js";
+import { getTemplateById, getTemplateSelectOptions, isBuiltInTemplateId, listTemplates, } from "./template-registry.js";
+/**
+ * Format one line of template list output for a built-in template.
+ *
+ * @param template Template metadata including `id` and `description`.
+ * @returns One-line summary text for `templates list`.
+ */
+export function formatTemplateSummary(template) {
+    return `${template.id.padEnd(14)} ${template.description}`;
+}
+/**
+ * Format the feature hint line shown under a template summary.
+ *
+ * @param template Template metadata including the `features` list.
+ * @returns Indented feature text for CLI list output.
+ */
+export function formatTemplateFeatures(template) {
+    return `  ${template.features.join(" • ")}`;
+}
+/**
+ * Format the detailed template description for `templates inspect`.
+ *
+ * This expands special layer combinations for the `persistence` and `compound`
+ * templates and returns a multi-line block including category, overlay path,
+ * resolved layers, and feature labels.
+ *
+ * @param template Template metadata including `id`, `defaultCategory`,
+ * `templateDir`, and `features`.
+ * @returns Multi-line template details text for CLI output.
+ */
+export function formatTemplateDetails(template) {
+    const layers = template.id === "persistence"
+        ? [
+            `authenticated: ${getBuiltInTemplateLayerDirs(template.id, { persistencePolicy: "authenticated" }).join(" -> ")}`,
+            `public: ${getBuiltInTemplateLayerDirs(template.id, { persistencePolicy: "public" }).join(" -> ")}`,
+        ]
+        : template.id === "compound"
+            ? [
+                `pure: ${getBuiltInTemplateLayerDirs(template.id).join(" -> ")}`,
+                `authenticated+persistence: ${getBuiltInTemplateLayerDirs(template.id, {
+                    persistenceEnabled: true,
+                    persistencePolicy: "authenticated",
+                }).join(" -> ")}`,
+                `public+persistence: ${getBuiltInTemplateLayerDirs(template.id, {
+                    persistenceEnabled: true,
+                    persistencePolicy: "public",
+                }).join(" -> ")}`,
+            ]
+            : [getBuiltInTemplateLayerDirs(template.id).join(" -> ")];
+    return [
+        template.id,
+        template.description,
+        `Category: ${template.defaultCategory}`,
+        `Overlay path: ${template.templateDir}`,
+        `Layers: ${layers.join("\n")}`,
+        `Features: ${template.features.join(", ")}`,
+    ].join("\n");
+}
+export { getTemplateById, getTemplateSelectOptions, listTemplates };
+export { isBuiltInTemplateId };

package/dist/runtime/index.d.ts

@@ -0,0 +1,9 @@
+export { scaffoldProject, collectScaffoldAnswers, getDefaultAnswers, getTemplateVariables, resolvePackageManagerId, resolveTemplateId, } from "./scaffold.js";
+export { formatMigrationHelpText, parseMigrationArgs, runMigrationCommand, } from "./migrations.js";
+export { manifestAttributeToJsonSchema, projectJsonSchemaDocument, manifestToJsonSchema, manifestToOpenApi, normalizeEndpointAuthDefinition, } from "./schema-core.js";
+export { buildCompoundChildStarterManifestDocument, getStarterManifestFiles, stringifyStarterManifest, } from "./starter-manifests.js";
+export type { EndpointAuthIntent, EndpointOpenApiAuthMode, EndpointOpenApiContractDocument, EndpointOpenApiDocumentOptions, EndpointOpenApiEndpointDefinition, EndpointOpenApiMethod, EndpointWordPressAuthDefinition, EndpointWordPressAuthMechanism, JsonSchemaDocument, JsonSchemaProjectionProfile, JsonSchemaObject, NormalizedEndpointAuthDefinition, OpenApiDocument, OpenApiInfo, OpenApiOperation, OpenApiParameter, OpenApiPathItem, OpenApiSecurityScheme, } from "./schema-core.js";
+export { PACKAGE_MANAGER_IDS, PACKAGE_MANAGERS, formatPackageExecCommand, formatInstallCommand, formatRunScript, getPackageManager, getPackageManagerSelectOptions, transformPackageManagerText, } from "./package-managers.js";
+export { TEMPLATE_IDS, TEMPLATE_REGISTRY, getTemplateById, getTemplateSelectOptions, listTemplates, } from "./template-registry.js";
+export { createAddPlaceholderMessage, formatAddHelpText, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getNextSteps, getOptionalOnboarding, runAddBlockCommand, runDoctor, runScaffoldFlow, } from "./cli-core.js";
+export type { DoctorCheck, ReadlinePrompt } from "./cli-core.js";

package/dist/runtime/index.js

@@ -0,0 +1,7 @@
+export { scaffoldProject, collectScaffoldAnswers, getDefaultAnswers, getTemplateVariables, resolvePackageManagerId, resolveTemplateId, } from "./scaffold.js";
+export { formatMigrationHelpText, parseMigrationArgs, runMigrationCommand, } from "./migrations.js";
+export { manifestAttributeToJsonSchema, projectJsonSchemaDocument, manifestToJsonSchema, manifestToOpenApi, normalizeEndpointAuthDefinition, } from "./schema-core.js";
+export { buildCompoundChildStarterManifestDocument, getStarterManifestFiles, stringifyStarterManifest, } from "./starter-manifests.js";
+export { PACKAGE_MANAGER_IDS, PACKAGE_MANAGERS, formatPackageExecCommand, formatInstallCommand, formatRunScript, getPackageManager, getPackageManagerSelectOptions, transformPackageManagerText, } from "./package-managers.js";
+export { TEMPLATE_IDS, TEMPLATE_REGISTRY, getTemplateById, getTemplateSelectOptions, listTemplates, } from "./template-registry.js";
+export { createAddPlaceholderMessage, formatAddHelpText, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getNextSteps, getOptionalOnboarding, runAddBlockCommand, runDoctor, runScaffoldFlow, } from "./cli-core.js";

package/dist/runtime/json-utils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Create a deep clone of a JSON-serializable value.
+ *
+ * @param value JSON-compatible data to clone.
+ * @returns A deep-cloned copy created with `JSON.parse(JSON.stringify(...))`.
+ *
+ * Values that are not JSON-serializable, such as functions, `undefined`,
+ * `BigInt`, class instances, and `Date` objects, are not preserved faithfully.
+ */
+export declare function cloneJsonValue<T>(value: T): T;

package/dist/runtime/json-utils.js

@@ -0,0 +1,12 @@
+/**
+ * Create a deep clone of a JSON-serializable value.
+ *
+ * @param value JSON-compatible data to clone.
+ * @returns A deep-cloned copy created with `JSON.parse(JSON.stringify(...))`.
+ *
+ * Values that are not JSON-serializable, such as functions, `undefined`,
+ * `BigInt`, class instances, and `Date` objects, are not preserved faithfully.
+ */
+export function cloneJsonValue(value) {
+    return JSON.parse(JSON.stringify(value));
+}

package/dist/runtime/local-dev-presets.d.ts

@@ -0,0 +1,26 @@
+import { type PackageManagerId } from "./package-managers.js";
+import type { ScaffoldTemplateVariables } from "./scaffold.js";
+interface LocalDevPresetOptions {
+    compoundPersistenceEnabled?: boolean;
+    packageManager: PackageManagerId;
+    projectDir: string;
+    templateId: string;
+    variables: ScaffoldTemplateVariables;
+    withTestPreset?: boolean;
+    withWpEnv?: boolean;
+}
+/**
+ * Copies opt-in local development preset files into a generated project.
+ */
+export declare function applyLocalDevPresetFiles({ projectDir, variables, withTestPreset, withWpEnv, }: Pick<LocalDevPresetOptions, "projectDir" | "variables" | "withTestPreset" | "withWpEnv">): Promise<void>;
+/**
+ * Adds generated-project watch scripts and preset-specific dependencies to
+ * `package.json`.
+ */
+export declare function applyGeneratedProjectDxPackageJson({ compoundPersistenceEnabled, packageManager, projectDir, templateId, withTestPreset, withWpEnv, }: Omit<LocalDevPresetOptions, "variables">): Promise<void>;
+/**
+ * Returns the recommended first-run development command for the given
+ * scaffolded template.
+ */
+export declare function getPrimaryDevelopmentScript(templateId: string): "dev" | "start";
+export {};

package/dist/runtime/local-dev-presets.js

@@ -0,0 +1,132 @@
+/**
+ * Helpers for the generated-project local development experience.
+ *
+ * These utilities apply optional preset files and watch-oriented package
+ * scripts after a scaffold has been rendered.
+ */
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { formatRunScript, } from "./package-managers.js";
+import { SHARED_TEST_PRESET_TEMPLATE_ROOT, SHARED_WP_ENV_PRESET_TEMPLATE_ROOT, } from "./template-registry.js";
+import { copyInterpolatedDirectory } from "./template-render.js";
+function templateHasPersistenceSync(templateId, compoundPersistenceEnabled) {
+    return templateId === "persistence" || (templateId === "compound" && compoundPersistenceEnabled);
+}
+function getWatchSyncTypesScript(packageManager, templateId) {
+    if (templateId === "compound") {
+        return `chokidar "src/blocks/**/types.ts" "scripts/block-config.ts" --debounce 200 -c "${formatRunScript(packageManager, "sync-types")}"`;
+    }
+    return `chokidar "src/types.ts" --debounce 200 -c "${formatRunScript(packageManager, "sync-types")}"`;
+}
+function getWatchSyncRestScript(packageManager, templateId) {
+    if (templateId === "compound") {
+        return `chokidar "src/blocks/**/api-types.ts" "scripts/block-config.ts" --debounce 200 -c "${formatRunScript(packageManager, "sync-rest")}"`;
+    }
+    return `chokidar "src/api-types.ts" --debounce 200 -c "${formatRunScript(packageManager, "sync-rest")}"`;
+}
+function getDevScript(packageManager, compoundPersistenceEnabled, templateId) {
+    const syncProcesses = [
+        `"${formatRunScript(packageManager, "watch:sync-types")}"`,
+    ];
+    const names = ["sync-types"];
+    const colors = ["yellow"];
+    if (templateHasPersistenceSync(templateId, compoundPersistenceEnabled)) {
+        syncProcesses.push(`"${formatRunScript(packageManager, "watch:sync-rest")}"`);
+        names.push("sync-rest");
+        colors.push("magenta");
+    }
+    syncProcesses.push(`"${formatRunScript(packageManager, "start:editor")}"`);
+    names.push("editor");
+    colors.push("blue");
+    return `concurrently -k -n ${names.join(",")} -c ${colors.join(",")} ${syncProcesses.join(" ")}`;
+}
+async function mutatePackageJson(projectDir, mutate) {
+    const packageJsonPath = path.join(projectDir, "package.json");
+    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
+    mutate(packageJson);
+    await fsp.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, "\t")}\n`, "utf8");
+}
+async function appendGitignoreLines(projectDir, lines) {
+    if (lines.length === 0) {
+        return;
+    }
+    const gitignorePath = path.join(projectDir, ".gitignore");
+    const current = fs.existsSync(gitignorePath)
+        ? await fsp.readFile(gitignorePath, "utf8")
+        : "";
+    const missingLines = lines.filter((line) => !current.includes(`${line}\n`) && !current.endsWith(line));
+    if (missingLines.length === 0) {
+        return;
+    }
+    const suffix = current.endsWith("\n") ? "" : "\n";
+    await fsp.writeFile(gitignorePath, `${current}${suffix}${missingLines.join("\n")}\n`, "utf8");
+}
+/**
+ * Copies opt-in local development preset files into a generated project.
+ */
+export async function applyLocalDevPresetFiles({ projectDir, variables, withTestPreset = false, withWpEnv = false, }) {
+    if (withWpEnv) {
+        await copyInterpolatedDirectory(SHARED_WP_ENV_PRESET_TEMPLATE_ROOT, projectDir, variables);
+    }
+    if (withTestPreset) {
+        await copyInterpolatedDirectory(SHARED_TEST_PRESET_TEMPLATE_ROOT, projectDir, variables);
+        await appendGitignoreLines(projectDir, ["playwright-report/", "test-results/"]);
+    }
+}
+/**
+ * Adds generated-project watch scripts and preset-specific dependencies to
+ * `package.json`.
+ */
+export async function applyGeneratedProjectDxPackageJson({ compoundPersistenceEnabled = false, packageManager, projectDir, templateId, withTestPreset = false, withWpEnv = false, }) {
+    const hasPersistenceSync = templateHasPersistenceSync(templateId, compoundPersistenceEnabled);
+    await mutatePackageJson(projectDir, (packageJson) => {
+        packageJson.devDependencies = {
+            ...(packageJson.devDependencies ?? {}),
+            "chokidar-cli": "^3.0.0",
+            concurrently: "^9.0.1",
+        };
+        if (withWpEnv || withTestPreset) {
+            packageJson.devDependencies["@wordpress/env"] = "^11.2.0";
+        }
+        if (withTestPreset) {
+            packageJson.devDependencies["@playwright/test"] = "^1.54.2";
+        }
+        const scripts = {
+            ...(packageJson.scripts ?? {}),
+        };
+        scripts["start:editor"] = "wp-scripts start --experimental-modules";
+        scripts["watch:sync-types"] = getWatchSyncTypesScript(packageManager, templateId);
+        if (hasPersistenceSync) {
+            scripts["watch:sync-rest"] = getWatchSyncRestScript(packageManager, templateId);
+        }
+        scripts.dev = getDevScript(packageManager, compoundPersistenceEnabled, templateId);
+        if (withWpEnv) {
+            scripts["wp-env:start"] = "wp-env start";
+            scripts["wp-env:stop"] = "wp-env stop";
+            scripts["wp-env:reset"] = "wp-env destroy all && wp-env start";
+        }
+        if (withTestPreset) {
+            scripts["wp-env:start:test"] = "wp-env start --config=.wp-env.test.json";
+            scripts["wp-env:stop:test"] = "wp-env stop --config=.wp-env.test.json";
+            scripts["wp-env:reset:test"] =
+                "wp-env destroy all --config=.wp-env.test.json && wp-env start --config=.wp-env.test.json";
+            scripts["wp-env:wait:test"] =
+                "node scripts/wait-for-wp-env.mjs http://localhost:8889 180000 .wp-env.test.json";
+            scripts["test:e2e"] = `${formatRunScript(packageManager, "wp-env:start:test")} && ${formatRunScript(packageManager, "wp-env:wait:test")} && playwright test`;
+        }
+        packageJson.scripts = scripts;
+    });
+}
+/**
+ * Returns the recommended first-run development command for the given
+ * scaffolded template.
+ */
+export function getPrimaryDevelopmentScript(templateId) {
+    return templateId === "basic" ||
+        templateId === "interactivity" ||
+        templateId === "persistence" ||
+        templateId === "compound"
+        ? "dev"
+        : "start";
+}

package/dist/runtime/metadata-analysis.d.ts

@@ -0,0 +1,11 @@
+import ts from "typescript";
+export interface AnalysisContext {
+    allowedExternalPackages: Set<string>;
+    checker: ts.TypeChecker;
+    packageNameCache: Map<string, string | null>;
+    projectRoot: string;
+    program: ts.Program;
+    recursionGuard: Set<string>;
+}
+export declare function getTaggedSyncBlockMetadataFailureCode(error: Error): "typescript-diagnostic" | undefined;
+export declare function createAnalysisContext(projectRoot: string, typesFilePath: string): AnalysisContext;

package/dist/runtime/metadata-analysis.js

@@ -0,0 +1,285 @@
+import { createHash } from "node:crypto";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+class LruCache {
+    constructor(maxEntries) {
+        this.maxEntries = maxEntries;
+        this.entries = new Map();
+    }
+    get(key) {
+        const value = this.entries.get(key);
+        if (value === undefined) {
+            return undefined;
+        }
+        this.entries.delete(key);
+        this.entries.set(key, value);
+        return value;
+    }
+    set(key, value) {
+        if (this.entries.has(key)) {
+            this.entries.delete(key);
+        }
+        this.entries.set(key, value);
+        if (this.entries.size <= this.maxEntries) {
+            return;
+        }
+        const oldestKey = this.entries.keys().next().value;
+        if (oldestKey !== undefined) {
+            this.entries.delete(oldestKey);
+        }
+    }
+}
+const DEFAULT_ALLOWED_EXTERNAL_PACKAGES = ["@wp-typia/block-types"];
+const ANALYSIS_PROGRAM_CACHE_MAX_ENTRIES = 20;
+const TYPESCRIPT_LIB_DIRECTORY = path.dirname(ts.getDefaultLibFilePath({}));
+const RUNTIME_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const SYNC_BLOCK_METADATA_FAILURE_CODE = Symbol("sync-block-metadata-failure-code");
+const analysisProgramCache = new LruCache(ANALYSIS_PROGRAM_CACHE_MAX_ENTRIES);
+function tagMetadataDiagnosticError(error) {
+    error[SYNC_BLOCK_METADATA_FAILURE_CODE] = "typescript-diagnostic";
+    return error;
+}
+export function getTaggedSyncBlockMetadataFailureCode(error) {
+    return error[SYNC_BLOCK_METADATA_FAILURE_CODE];
+}
+function isProjectLocalSourceFile(filePath, projectRoot) {
+    if (filePath.startsWith(TYPESCRIPT_LIB_DIRECTORY)) {
+        return false;
+    }
+    if (filePath.includes(`${path.sep}node_modules${path.sep}`)) {
+        return false;
+    }
+    return !path.relative(projectRoot, filePath).startsWith("..");
+}
+function collectSourceFileModuleSpecifiers(sourceFile) {
+    const moduleSpecifiers = [];
+    for (const statement of sourceFile.statements) {
+        if ((ts.isImportDeclaration(statement) ||
+            ts.isExportDeclaration(statement)) &&
+            statement.moduleSpecifier &&
+            ts.isStringLiteralLike(statement.moduleSpecifier)) {
+            moduleSpecifiers.push(statement.moduleSpecifier.text);
+        }
+    }
+    ts.forEachChild(sourceFile, (node) => {
+        if (ts.isImportTypeNode(node) &&
+            ts.isLiteralTypeNode(node.argument) &&
+            ts.isStringLiteral(node.argument.literal)) {
+            moduleSpecifiers.push(node.argument.literal.text);
+        }
+    });
+    return moduleSpecifiers;
+}
+function collectReferencedLocalSourceFiles(program, entryFilePath, compilerOptions, projectRoot) {
+    const visited = new Set();
+    const queue = [entryFilePath];
+    while (queue.length > 0) {
+        const filePath = queue.pop();
+        if (filePath === undefined ||
+            visited.has(filePath) ||
+            !isProjectLocalSourceFile(filePath, projectRoot)) {
+            continue;
+        }
+        visited.add(filePath);
+        const sourceFile = program.getSourceFile(filePath);
+        if (sourceFile === undefined) {
+            continue;
+        }
+        for (const moduleSpecifier of collectSourceFileModuleSpecifiers(sourceFile)) {
+            const resolved = ts.resolveModuleName(moduleSpecifier, filePath, compilerOptions, ts.sys).resolvedModule;
+            const resolvedFileName = resolved?.resolvedFileName;
+            if (resolvedFileName &&
+                isProjectLocalSourceFile(resolvedFileName, projectRoot)) {
+                queue.push(resolvedFileName);
+            }
+        }
+    }
+    return visited;
+}
+function stableSerializeAnalysisValue(value) {
+    if (value === undefined) {
+        return '"__undefined__"';
+    }
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => stableSerializeAnalysisValue(entry)).join(",")}]`;
+    }
+    return `{${Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => `${JSON.stringify(key)}:${stableSerializeAnalysisValue(entry)}`)
+        .join(",")}}`;
+}
+function buildAnalysisProgramStructureKey(projectRoot, typesFilePath, { compilerOptions, configPath, rootNames, typiaTagsAugmentationPath, }) {
+    return stableSerializeAnalysisValue({
+        compilerOptions,
+        configPath,
+        projectRoot,
+        rootNames: [...rootNames].sort(),
+        typiaTagsAugmentationPath,
+        typesFilePath,
+    });
+}
+function createAnalysisProgramContentFingerprint(filePaths, onMissingFile = "throw") {
+    const hash = createHash("sha1");
+    const fingerprintPaths = [...new Set(filePaths)].sort();
+    for (const filePath of fingerprintPaths) {
+        const fileContents = ts.sys.readFile(filePath);
+        if (fileContents === undefined) {
+            if (onMissingFile === "return-null") {
+                return null;
+            }
+            if (onMissingFile === "hash-missing") {
+                hash.update(filePath);
+                hash.update("\0");
+                hash.update("__missing__");
+                hash.update("\0");
+                continue;
+            }
+            throw new Error(`Unable to read metadata analysis dependency: ${filePath}`);
+        }
+        hash.update(filePath);
+        hash.update("\0");
+        hash.update(fileContents);
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}
+function getAnalysisProgramDependencyPaths(program, configPath) {
+    const sourceFilePaths = program
+        .getSourceFiles()
+        .map((sourceFile) => sourceFile.fileName)
+        .filter((filePath) => !filePath.startsWith(TYPESCRIPT_LIB_DIRECTORY));
+    const dependencyPaths = new Set(sourceFilePaths);
+    for (const filePath of sourceFilePaths) {
+        let currentDir = path.dirname(filePath);
+        while (true) {
+            dependencyPaths.add(path.join(currentDir, "package.json"));
+            const parentDir = path.dirname(currentDir);
+            if (parentDir === currentDir) {
+                break;
+            }
+            currentDir = parentDir;
+        }
+    }
+    if (configPath) {
+        dependencyPaths.add(configPath);
+    }
+    return [...dependencyPaths].sort();
+}
+function resolveAnalysisProgramInputs(projectRoot, typesFilePath) {
+    const configPath = ts.findConfigFile(projectRoot, ts.sys.fileExists, "tsconfig.json");
+    const compilerOptions = {
+        allowJs: false,
+        esModuleInterop: true,
+        module: ts.ModuleKind.NodeNext,
+        moduleResolution: ts.ModuleResolutionKind.NodeNext,
+        resolveJsonModule: true,
+        skipLibCheck: true,
+        target: ts.ScriptTarget.ES2022,
+    };
+    let rootNames = [typesFilePath];
+    const typiaTagsAugmentationPath = resolveTypiaTagsAugmentationPath();
+    if (configPath !== undefined) {
+        const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
+        if (configFile.error) {
+            throw formatDiagnosticError(configFile.error);
+        }
+        const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, path.dirname(configPath), compilerOptions, configPath);
+        if (parsed.errors.length > 0) {
+            throw formatDiagnosticError(parsed.errors[0]);
+        }
+        rootNames = parsed.fileNames.includes(typesFilePath)
+            ? parsed.fileNames
+            : [...parsed.fileNames, typesFilePath];
+        if (typiaTagsAugmentationPath &&
+            !rootNames.includes(typiaTagsAugmentationPath)) {
+            rootNames = [...rootNames, typiaTagsAugmentationPath];
+        }
+        Object.assign(compilerOptions, parsed.options);
+    }
+    else if (typiaTagsAugmentationPath) {
+        rootNames = [...rootNames, typiaTagsAugmentationPath];
+    }
+    const structureKey = buildAnalysisProgramStructureKey(projectRoot, typesFilePath, {
+        compilerOptions,
+        configPath: configPath ?? null,
+        rootNames,
+        typiaTagsAugmentationPath,
+    });
+    return {
+        compilerOptions,
+        configPath: configPath ?? null,
+        rootNames,
+        structureKey,
+        typiaTagsAugmentationPath,
+    };
+}
+export function createAnalysisContext(projectRoot, typesFilePath) {
+    const analysisInputs = resolveAnalysisProgramInputs(projectRoot, typesFilePath);
+    const cachedAnalysis = analysisProgramCache.get(analysisInputs.structureKey);
+    if (cachedAnalysis) {
+        const currentDependencyFingerprint = createAnalysisProgramContentFingerprint(cachedAnalysis.dependencyPaths, "hash-missing");
+        if (currentDependencyFingerprint !== null &&
+            currentDependencyFingerprint === cachedAnalysis.dependencyFingerprint) {
+            return {
+                allowedExternalPackages: new Set(DEFAULT_ALLOWED_EXTERNAL_PACKAGES),
+                checker: cachedAnalysis.checker,
+                packageNameCache: new Map(),
+                projectRoot,
+                program: cachedAnalysis.program,
+                recursionGuard: new Set(),
+            };
+        }
+    }
+    const program = ts.createProgram({
+        oldProgram: cachedAnalysis?.program,
+        options: analysisInputs.compilerOptions,
+        rootNames: analysisInputs.rootNames,
+    });
+    const diagnostics = ts.getPreEmitDiagnostics(program);
+    const localSourceFiles = collectReferencedLocalSourceFiles(program, typesFilePath, analysisInputs.compilerOptions, projectRoot);
+    const blockingDiagnostic = diagnostics.find((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error &&
+        diagnostic.file !== undefined &&
+        localSourceFiles.has(diagnostic.file.fileName));
+    if (blockingDiagnostic) {
+        throw formatDiagnosticError(blockingDiagnostic);
+    }
+    const checker = program.getTypeChecker();
+    const dependencyPaths = getAnalysisProgramDependencyPaths(program, analysisInputs.configPath);
+    const dependencyFingerprint = createAnalysisProgramContentFingerprint(dependencyPaths, "hash-missing");
+    if (dependencyFingerprint === null) {
+        throw new Error("Unable to fingerprint metadata analysis dependencies.");
+    }
+    analysisProgramCache.set(analysisInputs.structureKey, {
+        checker,
+        dependencyFingerprint,
+        dependencyPaths,
+        program,
+    });
+    return {
+        allowedExternalPackages: new Set(DEFAULT_ALLOWED_EXTERNAL_PACKAGES),
+        checker,
+        packageNameCache: new Map(),
+        projectRoot,
+        program,
+        recursionGuard: new Set(),
+    };
+}
+function resolveTypiaTagsAugmentationPath() {
+    const candidates = [
+        path.join(RUNTIME_DIRECTORY, "typia-tags.d.ts"),
+        path.join(RUNTIME_DIRECTORY, "typia-tags.ts"),
+    ];
+    for (const candidate of candidates) {
+        if (ts.sys.fileExists(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function formatDiagnosticError(diagnostic) {
+    return tagMetadataDiagnosticError(new Error(ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n")));
+}

package/dist/runtime/metadata-model.d.ts

@@ -0,0 +1,84 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type AttributeKind = "string" | "number" | "boolean" | "array" | "object" | "union";
+export type WordPressAttributeKind = "string" | "number" | "boolean" | "array" | "object";
+export type WordPressAttributeSource = "html" | "text" | "rich-text";
+export interface AttributeConstraints {
+    exclusiveMaximum: number | null;
+    exclusiveMinimum: number | null;
+    format: string | null;
+    maxLength: number | null;
+    maxItems: number | null;
+    maximum: number | null;
+    minLength: number | null;
+    minItems: number | null;
+    minimum: number | null;
+    multipleOf: number | null;
+    pattern: string | null;
+    typeTag: string | null;
+}
+export interface AttributeNode {
+    constraints: AttributeConstraints;
+    defaultValue?: JsonValue;
+    enumValues: Array<string | number | boolean> | null;
+    items?: AttributeNode;
+    kind: AttributeKind;
+    path: string;
+    properties?: Record<string, AttributeNode>;
+    required: boolean;
+    union?: AttributeUnion | null;
+    wp: {
+        selector: string | null;
+        source: WordPressAttributeSource | null;
+    };
+}
+export interface AttributeUnion {
+    branches: Record<string, AttributeNode>;
+    discriminator: string;
+}
+export interface BlockJsonAttribute {
+    default?: JsonValue;
+    enum?: Array<string | number | boolean>;
+    selector?: string;
+    source?: WordPressAttributeSource;
+    type: WordPressAttributeKind;
+}
+export interface ManifestAttribute {
+    typia: {
+        constraints: AttributeConstraints;
+        defaultValue: JsonValue | null;
+        hasDefault: boolean;
+    };
+    ts: {
+        items: ManifestAttribute | null;
+        kind: AttributeKind;
+        properties: Record<string, ManifestAttribute> | null;
+        required: boolean;
+        union: ManifestUnion | null;
+    };
+    wp: {
+        defaultValue: JsonValue | null;
+        enum: Array<string | number | boolean> | null;
+        hasDefault: boolean;
+        selector?: string | null;
+        source?: WordPressAttributeSource | null;
+        type: WordPressAttributeKind;
+    };
+}
+export interface ManifestUnion {
+    branches: Record<string, ManifestAttribute>;
+    discriminator: string;
+}
+export interface ManifestDocument {
+    attributes: Record<string, ManifestAttribute>;
+    manifestVersion: 2;
+    sourceType: string;
+}
+export declare function defaultAttributeConstraints(): AttributeConstraints;
+export declare function getWordPressKind(node: AttributeNode): WordPressAttributeKind;
+export declare function baseNode(kind: AttributeKind, pathLabel: string): AttributeNode;
+export declare function withRequired(node: AttributeNode, required: boolean): AttributeNode;
+export declare function cloneUnion(union: AttributeUnion): AttributeUnion;
+export declare function cloneProperties(properties: Record<string, AttributeNode>): Record<string, AttributeNode>;