@wp-typia/block-runtime 0.2.3 → 0.3.0

package/dist/metadata-projection.js

@@ -0,0 +1,233 @@
+import { cloneJsonValue } from "./json-utils.js";
+import { getWordPressKind, } from "./metadata-model.js";
+export function createBlockJsonAttribute(node, warnings) {
+    const attribute = {
+        type: getWordPressKind(node),
+    };
+    if (node.defaultValue !== undefined) {
+        attribute.default = cloneJsonValue(node.defaultValue);
+    }
+    if (node.enumValues !== null && node.enumValues.length > 0) {
+        attribute.enum = [...node.enumValues];
+    }
+    if (node.wp.source !== null) {
+        attribute.source = node.wp.source;
+    }
+    if (node.wp.selector !== null) {
+        attribute.selector = node.wp.selector;
+    }
+    const reasons = [];
+    if (node.constraints.exclusiveMaximum !== null)
+        reasons.push("exclusiveMaximum");
+    if (node.constraints.exclusiveMinimum !== null)
+        reasons.push("exclusiveMinimum");
+    if (node.constraints.format !== null)
+        reasons.push("format");
+    if (node.constraints.maxLength !== null)
+        reasons.push("maxLength");
+    if (node.constraints.maxItems !== null)
+        reasons.push("maxItems");
+    if (node.constraints.maximum !== null)
+        reasons.push("maximum");
+    if (node.constraints.minLength !== null)
+        reasons.push("minLength");
+    if (node.constraints.minItems !== null)
+        reasons.push("minItems");
+    if (node.constraints.minimum !== null)
+        reasons.push("minimum");
+    if (node.constraints.multipleOf !== null)
+        reasons.push("multipleOf");
+    if (node.constraints.pattern !== null)
+        reasons.push("pattern");
+    if (node.constraints.typeTag !== null)
+        reasons.push("typeTag");
+    if (node.kind === "array" && node.items !== undefined)
+        reasons.push("items");
+    if (node.kind === "object" && node.properties !== undefined)
+        reasons.push("properties");
+    if (node.kind === "union" && node.union !== null)
+        reasons.push("union");
+    if (reasons.length > 0) {
+        warnings.push(`${node.path}: ${reasons.join(", ")}`);
+    }
+    return attribute;
+}
+export function createManifestAttribute(node) {
+    return {
+        typia: {
+            constraints: { ...node.constraints },
+            defaultValue: node.defaultValue === undefined ? null : cloneJsonValue(node.defaultValue),
+            hasDefault: node.defaultValue !== undefined,
+        },
+        ts: {
+            items: node.items ? createManifestAttribute(node.items) : null,
+            kind: node.kind,
+            properties: node.properties
+                ? Object.fromEntries(Object.entries(node.properties).map(([key, property]) => [
+                    key,
+                    createManifestAttribute(property),
+                ]))
+                : null,
+            required: node.required,
+            union: node.union
+                ? {
+                    branches: Object.fromEntries(Object.entries(node.union.branches).map(([key, branch]) => [
+                        key,
+                        createManifestAttribute(branch),
+                    ])),
+                    discriminator: node.union.discriminator,
+                }
+                : null,
+        },
+        wp: {
+            defaultValue: node.defaultValue === undefined ? null : cloneJsonValue(node.defaultValue),
+            enum: node.enumValues ? [...node.enumValues] : null,
+            hasDefault: node.defaultValue !== undefined,
+            ...(node.wp.selector !== null ? { selector: node.wp.selector } : {}),
+            ...(node.wp.source !== null ? { source: node.wp.source } : {}),
+            type: getWordPressKind(node),
+        },
+    };
+}
+export function createManifestDocument(sourceTypeName, attributes) {
+    return {
+        attributes: Object.fromEntries(Object.entries(attributes).map(([key, node]) => [
+            key,
+            createManifestAttribute(node),
+        ])),
+        manifestVersion: 2,
+        sourceType: sourceTypeName,
+    };
+}
+export function validateWordPressExtractionAttributes(attributes) {
+    for (const attribute of Object.values(attributes)) {
+        validateWordPressExtractionAttribute(attribute, true);
+    }
+}
+export function validateWordPressExtractionAttribute(node, isTopLevel = false) {
+    const hasSelector = node.wp.selector !== null;
+    const hasSource = node.wp.source !== null;
+    if (hasSelector || hasSource) {
+        if (!isTopLevel) {
+            throw new Error(`WordPress extraction tags are only supported on top-level block attributes at ${node.path}`);
+        }
+        if (!hasSelector || !hasSource) {
+            throw new Error(`WordPress extraction tags require both Source and Selector at ${node.path}`);
+        }
+        if (node.kind !== "string") {
+            throw new Error(`WordPress extraction tags are only supported on string attributes at ${node.path}`);
+        }
+    }
+    if (node.items !== undefined) {
+        validateWordPressExtractionAttribute(node.items, false);
+    }
+    if (node.properties !== undefined) {
+        for (const property of Object.values(node.properties)) {
+            validateWordPressExtractionAttribute(property, false);
+        }
+    }
+    if (node.union?.branches) {
+        for (const branch of Object.values(node.union.branches)) {
+            validateWordPressExtractionAttribute(branch, false);
+        }
+    }
+}
+export function createExampleValue(node, key) {
+    if (node.defaultValue !== undefined) {
+        return cloneJsonValue(node.defaultValue);
+    }
+    if (node.enumValues !== null && node.enumValues.length > 0) {
+        return cloneJsonValue(node.enumValues[0]);
+    }
+    switch (node.kind) {
+        case "string":
+            return fitStringExampleToConstraints(createFormattedStringExample(node.constraints.format, key), node.constraints);
+        case "number":
+            return createNumericExample(node);
+        case "boolean":
+            return true;
+        case "array":
+            return createArrayExample(node, key);
+        case "object":
+            return Object.fromEntries(Object.entries(node.properties ?? {}).map(([propertyKey, propertyNode]) => [
+                propertyKey,
+                createExampleValue(propertyNode, propertyKey),
+            ]));
+        case "union": {
+            const firstBranch = node.union
+                ? Object.values(node.union.branches)[0]
+                : undefined;
+            if (!firstBranch || firstBranch.kind !== "object") {
+                return {};
+            }
+            return Object.fromEntries(Object.entries(firstBranch.properties ?? {}).map(([propertyKey, propertyNode]) => [
+                propertyKey,
+                createExampleValue(propertyNode, propertyKey),
+            ]));
+        }
+    }
+}
+function createFormattedStringExample(format, key) {
+    switch (format) {
+        case "uuid":
+            return "00000000-0000-4000-8000-000000000000";
+        case "email":
+            return "example@example.com";
+        case "url":
+        case "uri":
+            return "https://example.com";
+        case "ipv4":
+            return "127.0.0.1";
+        case "ipv6":
+            return "::1";
+        case "date-time":
+            return "2024-01-01T00:00:00Z";
+        default:
+            return `Example ${key}`;
+    }
+}
+function fitStringExampleToConstraints(value, constraints) {
+    let nextValue = value;
+    if (constraints.maxLength !== null &&
+        nextValue.length > constraints.maxLength) {
+        nextValue = nextValue.slice(0, constraints.maxLength);
+    }
+    if (constraints.minLength !== null &&
+        nextValue.length < constraints.minLength) {
+        nextValue = nextValue.padEnd(constraints.minLength, "x");
+    }
+    return nextValue;
+}
+function createNumericExample(node) {
+    const { exclusiveMaximum, exclusiveMinimum, maximum, minimum, multipleOf, } = node.constraints;
+    const step = multipleOf && multipleOf !== 0 ? multipleOf : 1;
+    const minCandidate = minimum ?? (exclusiveMinimum !== null ? exclusiveMinimum + step : null);
+    const maxCandidate = maximum ?? (exclusiveMaximum !== null ? exclusiveMaximum - step : null);
+    let candidate = multipleOf && multipleOf !== 0
+        ? minCandidate !== null
+            ? Math.ceil(minCandidate / multipleOf) * multipleOf
+            : maxCandidate !== null
+                ? Math.floor(maxCandidate / multipleOf) * multipleOf
+                : multipleOf
+        : minCandidate ?? maxCandidate ?? 42;
+    if (maxCandidate !== null && candidate > maxCandidate) {
+        candidate =
+            multipleOf && multipleOf !== 0
+                ? Math.floor(maxCandidate / multipleOf) * multipleOf
+                : maxCandidate;
+    }
+    if (minCandidate !== null && candidate < minCandidate) {
+        candidate =
+            multipleOf && multipleOf !== 0
+                ? Math.ceil(minCandidate / multipleOf) * multipleOf
+                : minCandidate;
+    }
+    return candidate;
+}
+function createArrayExample(node, key) {
+    const minimumItems = Math.max(node.constraints.minItems ?? 0, 0);
+    if (minimumItems === 0 || node.items === undefined) {
+        return [];
+    }
+    return Array.from({ length: minimumItems }, (_value, index) => createExampleValue(node.items, `${key}${index + 1}`));
+}

package/dist/migration-types.d.ts

@@ -0,0 +1,53 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type ManifestTsKind = "string" | "number" | "boolean" | "array" | "object" | "union";
+export interface ManifestConstraints {
+    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 ManifestUnionMetadata {
+    discriminator: string;
+    branches: Record<string, ManifestAttribute>;
+}
+export interface ManifestTsMetadata {
+    items?: ManifestAttribute | null;
+    kind: ManifestTsKind;
+    properties?: Record<string, ManifestAttribute> | null;
+    required?: boolean;
+    union?: ManifestUnionMetadata | null;
+}
+export interface ManifestTypiaMetadata {
+    constraints: ManifestConstraints;
+    defaultValue?: JsonValue | null;
+    hasDefault?: boolean;
+}
+export interface ManifestWpMetadata {
+    defaultValue?: JsonValue | null;
+    enum?: JsonValue[] | null;
+    hasDefault?: boolean;
+    selector?: string | null;
+    source?: "html" | "text" | "rich-text" | null;
+    type?: string | null;
+}
+export interface ManifestAttribute {
+    ts: ManifestTsMetadata;
+    typia: ManifestTypiaMetadata;
+    wp: ManifestWpMetadata;
+}
+export interface ManifestDocument {
+    attributes?: Record<string, ManifestAttribute>;
+    manifestVersion?: number | null;
+    sourceType?: string | null;
+}

package/dist/migration-types.js

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

package/dist/object-utils.d.ts

@@ -0,0 +1,2 @@
+export type UnknownRecord = Record<string, unknown>;
+export declare function isPlainObject(value: unknown): value is UnknownRecord;

package/dist/object-utils.js

@@ -0,0 +1,7 @@
+export function isPlainObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}

package/dist/schema-core.d.ts

@@ -0,0 +1,267 @@
+import type { JsonValue, ManifestAttribute, ManifestDocument } from "./migration-types.js";
+export interface JsonSchemaObject {
+    [key: string]: JsonValue | JsonSchemaObject | JsonSchemaObject[] | undefined;
+}
+/**
+ * Full JSON Schema document for a manifest-derived root object.
+ */
+export interface JsonSchemaDocument extends JsonSchemaObject {
+    $schema: string;
+    additionalProperties: boolean;
+    properties: Record<string, JsonSchemaObject>;
+    required: string[];
+    title: string;
+    type: "object";
+}
+/**
+ * Document-level metadata applied to generated OpenAPI files.
+ */
+export interface OpenApiInfo {
+    description?: string;
+    title?: string;
+    version?: string;
+}
+/**
+ * JSON Schema reference used inside generated OpenAPI documents.
+ */
+export interface OpenApiSchemaReference extends JsonSchemaObject {
+    $ref: string;
+}
+/**
+ * OpenAPI query parameter emitted from a manifest attribute.
+ */
+export interface OpenApiParameter extends JsonSchemaObject {
+    in: "query";
+    name: string;
+    required: boolean;
+    schema: JsonSchemaObject;
+}
+/**
+ * OpenAPI media type wrapper for JSON responses and request bodies.
+ */
+export interface OpenApiMediaType extends JsonSchemaObject {
+    schema: OpenApiSchemaReference;
+}
+/**
+ * OpenAPI request body definition for generated JSON endpoints.
+ */
+export interface OpenApiRequestBody extends JsonSchemaObject {
+    content: {
+        "application/json": OpenApiMediaType;
+    };
+    required: true;
+}
+/**
+ * Successful JSON response entry in the generated OpenAPI document.
+ */
+export interface OpenApiResponse extends JsonSchemaObject {
+    content: {
+        "application/json": OpenApiMediaType;
+    };
+    description: string;
+}
+/**
+ * Header-based security scheme used by authenticated WordPress REST routes.
+ */
+export interface OpenApiSecurityScheme extends JsonSchemaObject {
+    description?: string;
+    in: "header";
+    name: string;
+    type: "apiKey";
+}
+/**
+ * One generated OpenAPI operation for a scaffolded REST endpoint.
+ */
+export interface OpenApiOperation extends JsonSchemaObject {
+    operationId: string;
+    parameters?: OpenApiParameter[];
+    requestBody?: OpenApiRequestBody;
+    responses: Record<string, OpenApiResponse>;
+    security?: Array<Record<string, string[]>>;
+    summary?: string;
+    tags: string[];
+    "x-typia-authIntent": EndpointAuthIntent;
+    "x-wp-typia-authPolicy"?: EndpointOpenApiAuthMode;
+    "x-wp-typia-publicTokenField"?: string;
+}
+/**
+ * Path item containing one or more generated REST operations.
+ */
+export type OpenApiPathItem = JsonSchemaObject & Partial<Record<Lowercase<EndpointOpenApiMethod>, OpenApiOperation>>;
+/**
+ * Named tag entry surfaced at the top level of generated OpenAPI docs.
+ */
+export interface OpenApiTag extends JsonSchemaObject {
+    name: string;
+}
+/**
+ * OpenAPI component registry for generated schemas and security schemes.
+ */
+export interface OpenApiComponents extends JsonSchemaObject {
+    schemas: Record<string, JsonSchemaDocument>;
+    securitySchemes?: Record<string, OpenApiSecurityScheme>;
+}
+/**
+ * Complete OpenAPI 3.1 document emitted for endpoint-aware REST contracts.
+ */
+export interface OpenApiDocument extends JsonSchemaObject {
+    components: OpenApiComponents;
+    info: {
+        description?: string;
+        title: string;
+        version: string;
+    };
+    openapi: "3.1.0";
+    paths: Record<string, OpenApiPathItem>;
+    tags?: OpenApiTag[];
+}
+/**
+ * Backend-neutral auth intent for one manifest-defined endpoint.
+ */
+export type EndpointAuthIntent = "authenticated" | "public" | "public-write-protected";
+/**
+ * WordPress-specific authentication mechanisms that can implement neutral auth intent.
+ */
+export type EndpointWordPressAuthMechanism = "public-signed-token" | "rest-nonce";
+/**
+ * Optional WordPress adapter metadata that explains how the default runtime satisfies auth intent.
+ */
+export interface EndpointWordPressAuthDefinition {
+    mechanism: EndpointWordPressAuthMechanism;
+    publicTokenField?: string;
+}
+/**
+ * Legacy WordPress auth-mode literals kept for backward compatibility.
+ */
+export type EndpointOpenApiAuthMode = "authenticated-rest-nonce" | "public-read" | "public-signed-token";
+/**
+ * Supported HTTP methods for generated REST OpenAPI endpoints.
+ */
+export type EndpointOpenApiMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+/**
+ * Contract document used when composing an endpoint-aware OpenAPI file.
+ */
+export interface EndpointOpenApiContractDocument {
+    /** Manifest-derived contract document for this schema component. */
+    document: ManifestDocument;
+    /** Optional component name override for the generated schema reference. */
+    schemaName?: string;
+}
+interface EndpointOpenApiEndpointBaseDefinition {
+    /** Authentication policy surfaced in OpenAPI metadata. */
+    auth?: EndpointAuthIntent;
+    /** @deprecated Prefer `auth` plus `wordpressAuth` for new manifests. */
+    authMode?: EndpointOpenApiAuthMode;
+    /** Contract key for a JSON request body, when the endpoint accepts one. */
+    bodyContract?: string;
+    /** HTTP method exposed by the route. */
+    method: EndpointOpenApiMethod;
+    /** Stable OpenAPI operation id for this route. */
+    operationId: string;
+    /** Absolute REST path including namespace and version. */
+    path: string;
+    /** Contract key for query parameters, when the endpoint reads from the query string. */
+    queryContract?: string;
+    /** Contract key for the successful JSON response body. */
+    responseContract: string;
+    /** Optional short endpoint summary shown in generated docs. */
+    summary?: string;
+    /** OpenAPI tag names applied to this endpoint. */
+    tags: readonly string[];
+    /** Optional WordPress adapter metadata for the default runtime. */
+    wordpressAuth?: EndpointWordPressAuthDefinition;
+}
+/**
+ * Route metadata for one REST endpoint in the aggregate OpenAPI document.
+ */
+export type EndpointOpenApiEndpointDefinition = (EndpointOpenApiEndpointBaseDefinition & {
+    auth: EndpointAuthIntent;
+}) | (EndpointOpenApiEndpointBaseDefinition & {
+    /** @deprecated Prefer `auth` plus `wordpressAuth` for new manifests. */
+    authMode: EndpointOpenApiAuthMode;
+});
+export interface NormalizedEndpointAuthDefinition {
+    auth: EndpointAuthIntent;
+    authMode?: EndpointOpenApiAuthMode;
+    wordpressAuth?: EndpointWordPressAuthDefinition;
+}
+/**
+ * Options for building an aggregate endpoint-aware OpenAPI document.
+ */
+export interface EndpointOpenApiDocumentOptions {
+    /** Named contract documents keyed by the endpoint registry identifiers. */
+    contracts: Readonly<Record<string, EndpointOpenApiContractDocument>>;
+    /** Route definitions that should appear in the generated OpenAPI file. */
+    endpoints: readonly EndpointOpenApiEndpointDefinition[];
+    /** Optional document-level OpenAPI info metadata. */
+    info?: OpenApiInfo;
+}
+/**
+ * Supported schema projection profiles derived from one canonical wp-typia JSON Schema document.
+ */
+export type JsonSchemaProjectionProfile = "ai-structured-output" | "rest";
+/**
+ * Options for projecting one generated JSON Schema document into another consumer-facing profile.
+ */
+export interface JsonSchemaProjectionOptions {
+    /** Projection profile that controls schema transformation rules. */
+    profile: JsonSchemaProjectionProfile;
+}
+/**
+ * Converts one manifest attribute definition into a JSON Schema fragment.
+ *
+ * @param attribute Manifest-derived attribute metadata.
+ * @returns A JSON-compatible schema fragment for the attribute.
+ */
+export declare function manifestAttributeToJsonSchema(attribute: ManifestAttribute): JsonSchemaObject;
+/**
+ * Builds a full JSON Schema document from a Typia manifest document.
+ *
+ * @param doc Manifest-derived attribute document.
+ * @returns A draft 2020-12 JSON Schema document for the manifest root object.
+ */
+export declare function manifestToJsonSchema(doc: ManifestDocument): JsonSchemaDocument;
+/**
+ * Projects one generated wp-typia JSON Schema document into a consumer-facing profile.
+ *
+ * @param schema Existing generated JSON Schema document.
+ * @param options Projection profile options.
+ * @returns A cloned schema document adjusted for the requested profile.
+ */
+export declare function projectJsonSchemaDocument<Schema extends JsonSchemaDocument | JsonSchemaObject>(schema: Schema, options: JsonSchemaProjectionOptions): Schema;
+/**
+ * Wraps a manifest-derived JSON Schema document in a minimal OpenAPI 3.1 shell.
+ *
+ * @param doc Manifest-derived attribute document.
+ * @param info Optional OpenAPI document metadata.
+ * @returns An OpenAPI document containing the schema as a single component.
+ */
+export declare function manifestToOpenApi(doc: ManifestDocument, info?: OpenApiInfo): OpenApiDocument;
+/**
+ * Normalizes endpoint auth metadata into backend-neutral intent plus optional
+ * WordPress adapter details.
+ *
+ * This public runtime helper accepts either the authored `auth` and optional
+ * `wordpressAuth` shape or the deprecated `authMode` field. It validates that
+ * the provided fields are compatible, resolves the legacy compatibility mode,
+ * and returns a normalized definition without mutating the input endpoint.
+ *
+ * @param endpoint - Endpoint auth fields to normalize, including `auth`,
+ * `authMode`, `wordpressAuth`, and optional identity fields used in error
+ * messages (`operationId`, `path`, and `method`).
+ * @returns The normalized auth definition for the endpoint.
+ * @throws When `auth` and deprecated `authMode` conflict.
+ * @throws When `wordpressAuth` is attached to the `public` auth intent.
+ * @throws When the selected `wordpressAuth` mechanism is incompatible with the
+ * chosen auth intent.
+ * @throws When neither `auth` nor deprecated `authMode` is defined.
+ */
+export declare function normalizeEndpointAuthDefinition(endpoint: Pick<EndpointOpenApiEndpointDefinition, "auth" | "authMode" | "operationId" | "path" | "wordpressAuth" | "method">): NormalizedEndpointAuthDefinition;
+/**
+ * Build a complete OpenAPI 3.1 document from contract manifests and route metadata.
+ *
+ * @param options Aggregate contract and endpoint definitions for the REST surface.
+ * @returns A JSON-compatible OpenAPI document with paths, components, and auth metadata.
+ */
+export declare function buildEndpointOpenApiDocument(options: EndpointOpenApiDocumentOptions): OpenApiDocument;
+export {};