@wp-typia/block-runtime 0.2.3 → 0.4.0

package/dist/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/metadata-core.d.ts

@@ -0,0 +1,286 @@
+import { type EndpointOpenApiEndpointDefinition, type OpenApiInfo } from './schema-core.js';
+export interface SyncBlockMetadataOptions {
+    blockJsonFile: string;
+    jsonSchemaFile?: string;
+    manifestFile?: string;
+    openApiFile?: string;
+    phpValidatorFile?: string;
+    projectRoot?: string;
+    sourceTypeName: string;
+    typesFile: string;
+}
+export interface SyncBlockMetadataResult {
+    attributeNames: string[];
+    blockJsonPath: string;
+    jsonSchemaPath?: string;
+    lossyProjectionWarnings: string[];
+    manifestPath: string;
+    openApiPath?: string;
+    phpGenerationWarnings: string[];
+    phpValidatorPath: string;
+}
+export interface ArtifactSyncExecutionOptions {
+    /**
+     * Verify that generated artifacts are already current without rewriting them.
+     */
+    check?: boolean;
+}
+/**
+ * High-level outcome for one `runSyncBlockMetadata()` execution.
+ *
+ * - `success`: metadata sync completed without warnings.
+ * - `warning`: metadata sync completed, but warn-only findings were recorded.
+ * - `error`: metadata sync failed, or warnings were promoted to errors by flags.
+ */
+export type SyncBlockMetadataStatus = 'success' | 'warning' | 'error';
+/**
+ * Stable failure bucket for structured `sync-types` error reporting.
+ */
+export type SyncBlockMetadataFailureCode = 
+/** Generated artifact files are missing or stale relative to the current sources. */
+'stale-generated-artifact'
+/** A TypeScript node kind is not supported by the metadata parser. */
+ | 'unsupported-type-node'
+/** A supported node kind was used in an unsupported pattern or combination. */
+ | 'unsupported-type-pattern'
+/** Recursive type analysis was detected and aborted. */
+ | 'recursive-type'
+/** The configured types file or source type could not be resolved correctly. */
+ | 'invalid-source-type'
+/** TypeScript diagnostics blocked analysis before metadata generation ran. */
+ | 'typescript-diagnostic'
+/** The failure did not match a more specific structured bucket. */
+ | 'unknown-internal-error';
+/**
+ * Structured failure payload returned when `runSyncBlockMetadata()` does not complete.
+ */
+export interface SyncBlockMetadataFailure {
+    /** Stable failure bucket suitable for branching in scripts or CI. */
+    code: SyncBlockMetadataFailureCode;
+    /** Human-readable error message captured from the original failure. */
+    message: string;
+    /** Original thrown error name when available. */
+    name: string;
+}
+/**
+ * Optional execution flags that control how warnings affect the final report status.
+ */
+export interface SyncBlockMetadataExecutionOptions extends ArtifactSyncExecutionOptions {
+    /** Promote lossy WordPress projection warnings to `error` status. */
+    failOnLossy?: boolean;
+    /** Promote PHP validator coverage warnings to `error` status. */
+    failOnPhpWarnings?: boolean;
+    /**
+     * Promote all warnings to `error` status.
+     *
+     * When `true`, this behaves like setting both `failOnLossy` and
+     * `failOnPhpWarnings` to `true`.
+     */
+    strict?: boolean;
+}
+/**
+ * Structured result returned by `runSyncBlockMetadata()`.
+ */
+export interface SyncBlockMetadataReport {
+    /** Attribute keys discovered from the source type. Empty when analysis fails early. */
+    attributeNames: string[];
+    /** Absolute path to the generated or target `block.json`. */
+    blockJsonPath: string | null;
+    /** Absolute path to the generated JSON Schema file when schema output is enabled. */
+    jsonSchemaPath: string | null;
+    /** Warn-only notices for Typia constraints that cannot round-trip into `block.json`. */
+    lossyProjectionWarnings: string[];
+    /** Absolute path to the generated or target manifest file. */
+    manifestPath: string | null;
+    /** Absolute path to the generated aggregate OpenAPI file when enabled. */
+    openApiPath: string | null;
+    /** Warn-only notices for Typia constraints not yet enforced by PHP validation. */
+    phpGenerationWarnings: string[];
+    /** Absolute path to the generated or target PHP validator file. */
+    phpValidatorPath: string | null;
+    /** Structured failure payload when analysis or generation throws. */
+    failure: SyncBlockMetadataFailure | null;
+    /** Effective lossy-warning failure flag after `strict` has been applied. */
+    failOnLossy: boolean;
+    /** Effective PHP-warning failure flag after `strict` has been applied. */
+    failOnPhpWarnings: boolean;
+    /** Final execution status after warnings and failure handling are applied. */
+    status: SyncBlockMetadataStatus;
+    /** Whether the report was computed in strict mode. */
+    strict: boolean;
+}
+export interface SyncTypeSchemaOptions {
+    jsonSchemaFile: string;
+    openApiFile?: string;
+    openApiInfo?: OpenApiInfo;
+    projectRoot?: string;
+    sourceTypeName: string;
+    typesFile: string;
+}
+export interface SyncTypeSchemaResult {
+    jsonSchemaPath: string;
+    openApiPath?: string;
+    sourceTypeName: string;
+}
+/**
+ * Source type mapping used by endpoint manifests and aggregate REST OpenAPI generation.
+ */
+export interface EndpointManifestContractDefinition {
+    /** Optional component name override for the generated schema reference. */
+    schemaName?: string;
+    /** Type name exported from the source `typesFile`. */
+    sourceTypeName: string;
+}
+/**
+ * Portable route metadata stored in one endpoint manifest entry.
+ */
+export type EndpointManifestEndpointDefinition = EndpointOpenApiEndpointDefinition;
+/**
+ * Canonical TypeScript description of one scaffolded REST surface.
+ */
+export interface EndpointManifestDefinition<Contracts extends Readonly<Record<string, EndpointManifestContractDefinition>> = Readonly<Record<string, EndpointManifestContractDefinition>>, Endpoints extends readonly EndpointManifestEndpointDefinition[] = readonly EndpointManifestEndpointDefinition[]> {
+    /** Contract registry keyed by logical route contract ids. */
+    contracts: Contracts;
+    /** Route registry keyed by concrete REST path and method pairs. */
+    endpoints: Endpoints;
+    /** Optional document-level metadata for aggregate OpenAPI output. */
+    info?: OpenApiInfo;
+}
+/**
+ * Preserve literal TypeScript inference for backend-neutral endpoint manifests.
+ *
+ * @param manifest Canonical REST surface metadata authored in TypeScript.
+ * @returns The same manifest object with literal contract and endpoint metadata preserved.
+ */
+export declare function defineEndpointManifest<const Contracts extends Readonly<Record<string, EndpointManifestContractDefinition>>, const Endpoints extends readonly EndpointManifestEndpointDefinition[]>(manifest: EndpointManifestDefinition<Contracts, Endpoints>): EndpointManifestDefinition<Contracts, Endpoints>;
+/**
+ * Backward-compatible source type mapping used when generating aggregate REST OpenAPI documents.
+ */
+export interface RestOpenApiContractDefinition extends EndpointManifestContractDefinition {
+}
+/**
+ * Backward-compatible route metadata consumed by `syncRestOpenApi()`.
+ */
+export type RestOpenApiEndpointDefinition = EndpointManifestEndpointDefinition;
+/**
+ * Shared file and project inputs for REST OpenAPI generation.
+ */
+interface SyncRestOpenApiBaseOptions {
+    /** Output path for the aggregate OpenAPI document. */
+    openApiFile: string;
+    /** Optional project root used to resolve file paths. */
+    projectRoot?: string;
+    /** Source file that exports the REST contract types. */
+    typesFile: string;
+}
+/**
+ * Manifest-first options for writing a canonical endpoint-aware REST OpenAPI document.
+ */
+export interface SyncRestOpenApiManifestOptions extends SyncRestOpenApiBaseOptions {
+    /** Canonical endpoint manifest describing the REST surface. */
+    manifest: EndpointManifestDefinition;
+    /** Not accepted when `manifest` is provided. */
+    contracts?: never;
+    /** Not accepted when `manifest` is provided. */
+    endpoints?: never;
+    /** Not accepted when `manifest` is provided. */
+    openApiInfo?: never;
+}
+/**
+ * Backward-compatible options for writing a canonical endpoint-aware REST OpenAPI document.
+ */
+export interface SyncRestOpenApiContractsOptions extends SyncRestOpenApiBaseOptions {
+    /** Contract registry keyed by logical route contract ids. */
+    contracts: Readonly<Record<string, RestOpenApiContractDefinition>>;
+    /** Endpoint registry describing the REST paths, methods, and auth policies to document. */
+    endpoints: readonly RestOpenApiEndpointDefinition[];
+    /** Optional OpenAPI document metadata. */
+    openApiInfo?: OpenApiInfo;
+    /** Not accepted when `contracts` and `endpoints` are provided directly. */
+    manifest?: never;
+}
+/**
+ * Options for writing a canonical endpoint-aware REST OpenAPI document.
+ */
+export type SyncRestOpenApiOptions = SyncRestOpenApiManifestOptions | SyncRestOpenApiContractsOptions;
+/**
+ * Result returned after writing an aggregate REST OpenAPI document.
+ */
+export interface SyncRestOpenApiResult {
+    /** Number of endpoints included in the generated OpenAPI file. */
+    endpointCount: number;
+    /** Absolute path to the generated OpenAPI file. */
+    openApiPath: string;
+    /** Component schema names included in the generated document. */
+    schemaNames: string[];
+}
+interface SyncEndpointClientBaseOptions {
+    /** Output path for the generated portable client module. */
+    clientFile: string;
+    /** Optional project root used to resolve file paths. */
+    projectRoot?: string;
+    /** Source file that exports the endpoint contract types. */
+    typesFile: string;
+    /** Optional explicit path to the validator module. */
+    validatorsFile?: string;
+}
+/**
+ * Manifest-first options for writing a portable endpoint client module.
+ */
+export interface SyncEndpointClientOptions extends SyncEndpointClientBaseOptions {
+    /** Canonical endpoint manifest describing the REST surface. */
+    manifest: EndpointManifestDefinition;
+}
+/**
+ * Result returned after writing a generated portable endpoint client module.
+ */
+export interface SyncEndpointClientResult {
+    /** Number of endpoints included in the generated client file. */
+    endpointCount: number;
+    /** Absolute path to the generated client file. */
+    clientPath: string;
+    /** Operation ids emitted as endpoint constants and convenience wrappers. */
+    operationIds: string[];
+}
+/**
+ * Synchronizes block metadata artifacts from a source TypeScript contract.
+ *
+ * This updates `block.json` attributes/examples and emits the related JSON
+ * Schema, manifest, OpenAPI, and optional PHP validator artifacts derived from
+ * the same source type.
+ *
+ * @param options Configuration for locating the project root, source types
+ * file/type name, and output artifact paths.
+ * @returns The generated artifact paths plus any lossy WordPress projection or
+ * PHP validator coverage warnings discovered during synchronization.
+ */
+export declare function syncBlockMetadata(options: SyncBlockMetadataOptions, executionOptions?: ArtifactSyncExecutionOptions): Promise<SyncBlockMetadataResult>;
+/**
+ * Execute `syncBlockMetadata()` and return a structured status report.
+ *
+ * This wrapper preserves the existing artifact-generation behavior while adding
+ * stable status, warning, and failure metadata for scripts and CI integrations.
+ * Hard analysis failures are normalized into `failure`, and warning promotion is
+ * controlled by `strict`, `failOnLossy`, and `failOnPhpWarnings`.
+ *
+ * @param options Artifact generation inputs shared with `syncBlockMetadata()`.
+ * @param executionOptions Optional warning-promotion flags for CI/reporting flows.
+ * @returns A structured execution report describing generated paths, warnings, and failures.
+ */
+export declare function runSyncBlockMetadata(options: SyncBlockMetadataOptions, executionOptions?: SyncBlockMetadataExecutionOptions): Promise<SyncBlockMetadataReport>;
+export declare function syncTypeSchemas(options: SyncTypeSchemaOptions, executionOptions?: ArtifactSyncExecutionOptions): Promise<SyncTypeSchemaResult>;
+/**
+ * Generate and write a canonical OpenAPI document for scaffolded REST contracts.
+ *
+ * @param options Contracts, endpoint metadata, source file, and output file settings.
+ * @returns Information about the generated OpenAPI document and included schema components.
+ */
+export declare function syncRestOpenApi(options: SyncRestOpenApiOptions, executionOptions?: ArtifactSyncExecutionOptions): Promise<SyncRestOpenApiResult>;
+/**
+ * Generate and write a manifest-first portable endpoint client module.
+ *
+ * @param options Manifest, source file, validator file, and output path settings.
+ * @returns Information about the generated client file and emitted operation ids.
+ */
+export declare function syncEndpointClient(options: SyncEndpointClientOptions, executionOptions?: ArtifactSyncExecutionOptions): Promise<SyncEndpointClientResult>;
+export {};