@formspec/build 0.1.0-alpha.54 → 0.1.0-alpha.57

package/dist/build-alpha.d.ts

@@ -469,46 +469,6 @@ declare interface CustomTypeRegistration_2 {
      * Note: `"__integerBrand"` is reserved for the builtin Integer type.
      */
     readonly brand?: string;
-    /**
-     * Optional callback to extract a payload from the TypeScript type at
-     * analysis time. The returned value is stored on the custom type node
-     * and later passed to `toJsonSchema`.
-     *
-     * Use this to carry type-level information (e.g., a generic argument's
-     * resolved literal value) through the IR into schema generation.
-     *
-     * **Parameters:** typed as `unknown` because `@formspec/core` does not
-     * depend on the TypeScript compiler API. Implementations should cast to
-     * `ts.Type` and `ts.TypeChecker`. Both parameters originate from the
-     * host program's type checker — extensions may rely on host-program
-     * symbol identity.
-     *
-     * **Contract:**
-     * - Must be a pure function of `(type, checker)` — no I/O or shared state.
-     * - May be invoked multiple times for the same type (no memoization is provided).
-     * - Must return a JSON-serializable `ExtensionPayloadValue`. Returning live
-     *   compiler objects (e.g., `ts.Type`) will corrupt any IR caching.
-     * - Errors thrown by the callback are attributed to the extension and
-     *   reported as build diagnostics.
-     * - Returning `undefined` is coerced to `null` at the call site.
-     *
-     * @param type - The resolved TypeScript type (cast to `ts.Type`).
-     * @param checker - The TypeScript type checker (cast to `ts.TypeChecker`).
-     * @returns A JSON-serializable payload, or `null` if no payload can be extracted.
-     *
-     * @example
-     * ```typescript
-     * extractPayload: (type: unknown, checker: unknown) => {
-     *   const tsType = type as ts.Type;
-     *   const tsChecker = checker as ts.TypeChecker;
-     *   const prop = tsType.getProperty('target');
-     *   if (!prop) return null;
-     *   const propType = tsChecker.getTypeOfSymbol(prop);
-     *   return propType.isStringLiteral() ? propType.value : null;
-     * }
-     * ```
-     */
-    readonly extractPayload?: (type: unknown, checker: unknown) => ExtensionPayloadValue;
     /**
      * Converts the custom type's payload into a JSON Schema fragment.
      *
@@ -945,11 +905,12 @@ export declare interface FormSpecConfig {
     readonly vendorPrefix?: string;
     /**
      * JSON Schema representation for static enums.
-     * - "enum": flat { "enum": ["a", "b"] }
-     * - "oneOf": { "oneOf": [{ "const": "a" }, ...] }
+     * - "enum": compact `enum` output, plus a display-name extension when labels exist
+     * - "oneOf": per-member `const` output, with `title` only for distinct labels
+     * - "smart-size": uses `enum` unless a distinct display label would be lost
      * @defaultValue "enum"
      */
-    readonly enumSerialization?: "enum" | "oneOf";
+    readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
     /**
      * Per-package configuration overrides for monorepos.
      * Keys are glob patterns matched against file paths relative to
@@ -968,7 +929,7 @@ declare interface FormSpecPackageOverride {
     /** Override constraint surface for this package. */
     readonly constraints?: ConstraintConfig;
     /** Override enum serialization for this package. */
-    readonly enumSerialization?: "enum" | "oneOf";
+    readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
     /** Override metadata policy for this package. */
     readonly metadata?: MetadataPolicyInput_2;
 }
@@ -1051,7 +1012,7 @@ export declare interface GenerateJsonSchemaOptions {
      * JSON Schema representation to use for static enums.
      * @defaultValue "enum"
      */
-    readonly enumSerialization?: "enum" | "oneOf";
+    readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
     /** Metadata resolution policy for chain DSL generation. */
     readonly metadata?: MetadataPolicyInput | undefined;
     /**
@@ -2213,7 +2174,7 @@ export declare interface StaticSchemaGenerationOptions {
      * @defaultValue "enum"
      * @deprecated Provide a `FormSpecConfig` via the `config` option instead.
      */
-    readonly enumSerialization?: "enum" | "oneOf";
+    readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
     /**
      * Metadata resolution policy for static schema generation.
      * @deprecated Provide a `FormSpecConfig` via the `config` option instead.

package/dist/build-beta.d.ts

@@ -469,46 +469,6 @@ declare interface CustomTypeRegistration_2 {
      * Note: `"__integerBrand"` is reserved for the builtin Integer type.
      */
     readonly brand?: string;
-    /**
-     * Optional callback to extract a payload from the TypeScript type at
-     * analysis time. The returned value is stored on the custom type node
-     * and later passed to `toJsonSchema`.
-     *
-     * Use this to carry type-level information (e.g., a generic argument's
-     * resolved literal value) through the IR into schema generation.
-     *
-     * **Parameters:** typed as `unknown` because `@formspec/core` does not
-     * depend on the TypeScript compiler API. Implementations should cast to
-     * `ts.Type` and `ts.TypeChecker`. Both parameters originate from the
-     * host program's type checker — extensions may rely on host-program
-     * symbol identity.
-     *
-     * **Contract:**
-     * - Must be a pure function of `(type, checker)` — no I/O or shared state.
-     * - May be invoked multiple times for the same type (no memoization is provided).
-     * - Must return a JSON-serializable `ExtensionPayloadValue`. Returning live
-     *   compiler objects (e.g., `ts.Type`) will corrupt any IR caching.
-     * - Errors thrown by the callback are attributed to the extension and
-     *   reported as build diagnostics.
-     * - Returning `undefined` is coerced to `null` at the call site.
-     *
-     * @param type - The resolved TypeScript type (cast to `ts.Type`).
-     * @param checker - The TypeScript type checker (cast to `ts.TypeChecker`).
-     * @returns A JSON-serializable payload, or `null` if no payload can be extracted.
-     *
-     * @example
-     * ```typescript
-     * extractPayload: (type: unknown, checker: unknown) => {
-     *   const tsType = type as ts.Type;
-     *   const tsChecker = checker as ts.TypeChecker;
-     *   const prop = tsType.getProperty('target');
-     *   if (!prop) return null;
-     *   const propType = tsChecker.getTypeOfSymbol(prop);
-     *   return propType.isStringLiteral() ? propType.value : null;
-     * }
-     * ```
-     */
-    readonly extractPayload?: (type: unknown, checker: unknown) => ExtensionPayloadValue;
     /**
      * Converts the custom type's payload into a JSON Schema fragment.
      *
@@ -945,11 +905,12 @@ export declare interface FormSpecConfig {
     readonly vendorPrefix?: string;
     /**
      * JSON Schema representation for static enums.
-     * - "enum": flat { "enum": ["a", "b"] }
-     * - "oneOf": { "oneOf": [{ "const": "a" }, ...] }
+     * - "enum": compact `enum` output, plus a display-name extension when labels exist
+     * - "oneOf": per-member `const` output, with `title` only for distinct labels
+     * - "smart-size": uses `enum` unless a distinct display label would be lost
      * @defaultValue "enum"
      */
-    readonly enumSerialization?: "enum" | "oneOf";
+    readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
     /**
      * Per-package configuration overrides for monorepos.
      * Keys are glob patterns matched against file paths relative to
@@ -968,7 +929,7 @@ declare interface FormSpecPackageOverride {
     /** Override constraint surface for this package. */
     readonly constraints?: ConstraintConfig;
     /** Override enum serialization for this package. */
-    readonly enumSerialization?: "enum" | "oneOf";
+    readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
     /** Override metadata policy for this package. */
     readonly metadata?: MetadataPolicyInput_2;
 }
@@ -1051,7 +1012,7 @@ export declare interface GenerateJsonSchemaOptions {
      * JSON Schema representation to use for static enums.
      * @defaultValue "enum"
      */
-    readonly enumSerialization?: "enum" | "oneOf";
+    readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
     /** Metadata resolution policy for chain DSL generation. */
     readonly metadata?: MetadataPolicyInput | undefined;
     /**
@@ -2213,7 +2174,7 @@ export declare interface StaticSchemaGenerationOptions {
      * @defaultValue "enum"
      * @deprecated Provide a `FormSpecConfig` via the `config` option instead.
      */
-    readonly enumSerialization?: "enum" | "oneOf";
+    readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
     /**
      * Metadata resolution policy for static schema generation.
      * @deprecated Provide a `FormSpecConfig` via the `config` option instead.

package/dist/build-internal.d.ts

@@ -469,46 +469,6 @@ declare interface CustomTypeRegistration_2 {
      * Note: `"__integerBrand"` is reserved for the builtin Integer type.
      */
     readonly brand?: string;
-    /**
-     * Optional callback to extract a payload from the TypeScript type at
-     * analysis time. The returned value is stored on the custom type node
-     * and later passed to `toJsonSchema`.
-     *
-     * Use this to carry type-level information (e.g., a generic argument's
-     * resolved literal value) through the IR into schema generation.
-     *
-     * **Parameters:** typed as `unknown` because `@formspec/core` does not
-     * depend on the TypeScript compiler API. Implementations should cast to
-     * `ts.Type` and `ts.TypeChecker`. Both parameters originate from the
-     * host program's type checker — extensions may rely on host-program
-     * symbol identity.
-     *
-     * **Contract:**
-     * - Must be a pure function of `(type, checker)` — no I/O or shared state.
-     * - May be invoked multiple times for the same type (no memoization is provided).
-     * - Must return a JSON-serializable `ExtensionPayloadValue`. Returning live
-     *   compiler objects (e.g., `ts.Type`) will corrupt any IR caching.
-     * - Errors thrown by the callback are attributed to the extension and
-     *   reported as build diagnostics.
-     * - Returning `undefined` is coerced to `null` at the call site.
-     *
-     * @param type - The resolved TypeScript type (cast to `ts.Type`).
-     * @param checker - The TypeScript type checker (cast to `ts.TypeChecker`).
-     * @returns A JSON-serializable payload, or `null` if no payload can be extracted.
-     *
-     * @example
-     * ```typescript
-     * extractPayload: (type: unknown, checker: unknown) => {
-     *   const tsType = type as ts.Type;
-     *   const tsChecker = checker as ts.TypeChecker;
-     *   const prop = tsType.getProperty('target');
-     *   if (!prop) return null;
-     *   const propType = tsChecker.getTypeOfSymbol(prop);
-     *   return propType.isStringLiteral() ? propType.value : null;
-     * }
-     * ```
-     */
-    readonly extractPayload?: (type: unknown, checker: unknown) => ExtensionPayloadValue;
     /**
      * Converts the custom type's payload into a JSON Schema fragment.
      *
@@ -945,11 +905,12 @@ export declare interface FormSpecConfig {
     readonly vendorPrefix?: string;
     /**
      * JSON Schema representation for static enums.
-     * - "enum": flat { "enum": ["a", "b"] }
-     * - "oneOf": { "oneOf": [{ "const": "a" }, ...] }
+     * - "enum": compact `enum` output, plus a display-name extension when labels exist
+     * - "oneOf": per-member `const` output, with `title` only for distinct labels
+     * - "smart-size": uses `enum` unless a distinct display label would be lost
      * @defaultValue "enum"
      */
-    readonly enumSerialization?: "enum" | "oneOf";
+    readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
     /**
      * Per-package configuration overrides for monorepos.
      * Keys are glob patterns matched against file paths relative to
@@ -968,7 +929,7 @@ declare interface FormSpecPackageOverride {
     /** Override constraint surface for this package. */
     readonly constraints?: ConstraintConfig;
     /** Override enum serialization for this package. */
-    readonly enumSerialization?: "enum" | "oneOf";
+    readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
     /** Override metadata policy for this package. */
     readonly metadata?: MetadataPolicyInput_2;
 }
@@ -1051,7 +1012,7 @@ export declare interface GenerateJsonSchemaOptions {
      * JSON Schema representation to use for static enums.
      * @defaultValue "enum"
      */
-    readonly enumSerialization?: "enum" | "oneOf";
+    readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
     /** Metadata resolution policy for chain DSL generation. */
     readonly metadata?: MetadataPolicyInput | undefined;
     /**
@@ -2213,7 +2174,7 @@ export declare interface StaticSchemaGenerationOptions {
      * @defaultValue "enum"
      * @deprecated Provide a `FormSpecConfig` via the `config` option instead.
      */
-    readonly enumSerialization?: "enum" | "oneOf";
+    readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
     /**
      * Metadata resolution policy for static schema generation.
      * @deprecated Provide a `FormSpecConfig` via the `config` option instead.

package/dist/build.d.ts

@@ -469,46 +469,6 @@ declare interface CustomTypeRegistration_2 {
      * Note: `"__integerBrand"` is reserved for the builtin Integer type.
      */
     readonly brand?: string;
-    /**
-     * Optional callback to extract a payload from the TypeScript type at
-     * analysis time. The returned value is stored on the custom type node
-     * and later passed to `toJsonSchema`.
-     *
-     * Use this to carry type-level information (e.g., a generic argument's
-     * resolved literal value) through the IR into schema generation.
-     *
-     * **Parameters:** typed as `unknown` because `@formspec/core` does not
-     * depend on the TypeScript compiler API. Implementations should cast to
-     * `ts.Type` and `ts.TypeChecker`. Both parameters originate from the
-     * host program's type checker — extensions may rely on host-program
-     * symbol identity.
-     *
-     * **Contract:**
-     * - Must be a pure function of `(type, checker)` — no I/O or shared state.
-     * - May be invoked multiple times for the same type (no memoization is provided).
-     * - Must return a JSON-serializable `ExtensionPayloadValue`. Returning live
-     *   compiler objects (e.g., `ts.Type`) will corrupt any IR caching.
-     * - Errors thrown by the callback are attributed to the extension and
-     *   reported as build diagnostics.
-     * - Returning `undefined` is coerced to `null` at the call site.
-     *
-     * @param type - The resolved TypeScript type (cast to `ts.Type`).
-     * @param checker - The TypeScript type checker (cast to `ts.TypeChecker`).
-     * @returns A JSON-serializable payload, or `null` if no payload can be extracted.
-     *
-     * @example
-     * ```typescript
-     * extractPayload: (type: unknown, checker: unknown) => {
-     *   const tsType = type as ts.Type;
-     *   const tsChecker = checker as ts.TypeChecker;
-     *   const prop = tsType.getProperty('target');
-     *   if (!prop) return null;
-     *   const propType = tsChecker.getTypeOfSymbol(prop);
-     *   return propType.isStringLiteral() ? propType.value : null;
-     * }
-     * ```
-     */
-    readonly extractPayload?: (type: unknown, checker: unknown) => ExtensionPayloadValue;
     /**
      * Converts the custom type's payload into a JSON Schema fragment.
      *
@@ -945,11 +905,12 @@ export declare interface FormSpecConfig {
     readonly vendorPrefix?: string;
     /**
      * JSON Schema representation for static enums.
-     * - "enum": flat { "enum": ["a", "b"] }
-     * - "oneOf": { "oneOf": [{ "const": "a" }, ...] }
+     * - "enum": compact `enum` output, plus a display-name extension when labels exist
+     * - "oneOf": per-member `const` output, with `title` only for distinct labels
+     * - "smart-size": uses `enum` unless a distinct display label would be lost
      * @defaultValue "enum"
      */
-    readonly enumSerialization?: "enum" | "oneOf";
+    readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
     /**
      * Per-package configuration overrides for monorepos.
      * Keys are glob patterns matched against file paths relative to
@@ -968,7 +929,7 @@ declare interface FormSpecPackageOverride {
     /** Override constraint surface for this package. */
     readonly constraints?: ConstraintConfig;
     /** Override enum serialization for this package. */
-    readonly enumSerialization?: "enum" | "oneOf";
+    readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
     /** Override metadata policy for this package. */
     readonly metadata?: MetadataPolicyInput_2;
 }
@@ -1051,7 +1012,7 @@ export declare interface GenerateJsonSchemaOptions {
      * JSON Schema representation to use for static enums.
      * @defaultValue "enum"
      */
-    readonly enumSerialization?: "enum" | "oneOf";
+    readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
     /** Metadata resolution policy for chain DSL generation. */
     readonly metadata?: MetadataPolicyInput | undefined;
     /**
@@ -2213,7 +2174,7 @@ export declare interface StaticSchemaGenerationOptions {
      * @defaultValue "enum"
      * @deprecated Provide a `FormSpecConfig` via the `config` option instead.
      */
-    readonly enumSerialization?: "enum" | "oneOf";
+    readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
     /**
      * Metadata resolution policy for static schema generation.
      * @deprecated Provide a `FormSpecConfig` via the `config` option instead.