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

package/dist/build-alpha.d.ts

@@ -40,6 +40,7 @@ import { ExtensionDefinition } from '@formspec/core';
 import { FormElement } from '@formspec/core';
 import { FormSpec } from '@formspec/core';
 import { Group } from '@formspec/core';
+import type { LoggerLike } from '@formspec/core';
 import type { MetadataPolicyInput } from '@formspec/core';
 import { NumberField } from '@formspec/core';
 import { ObjectField } from '@formspec/core';
@@ -95,6 +96,11 @@ export declare function buildFormSchemas<E extends readonly FormElement[]>(form:
  * @public
  */
 export declare interface BuildFormSchemasOptions extends GenerateJsonSchemaOptions, GenerateUiSchemaOptions {
+    /**
+     * Optional logger for diagnostic output. Defaults to a no-op logger so
+     * existing callers produce no output.
+     */
+    readonly logger?: LoggerLike | undefined;
 }
 
 /**
@@ -463,6 +469,46 @@ 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.
      *
@@ -1008,6 +1054,11 @@ export declare interface GenerateJsonSchemaOptions {
     readonly enumSerialization?: "enum" | "oneOf";
     /** Metadata resolution policy for chain DSL generation. */
     readonly metadata?: MetadataPolicyInput | undefined;
+    /**
+     * Optional logger for diagnostic output. Defaults to a no-op logger so
+     * existing callers produce no output.
+     */
+    readonly logger?: LoggerLike | undefined;
 }
 
 /**
@@ -1390,6 +1441,11 @@ export declare function generateUiSchema<E extends readonly FormElement[]>(form:
 export declare interface GenerateUiSchemaOptions {
     /** Metadata resolution policy for chain DSL UI generation. */
     readonly metadata?: MetadataPolicyInput | undefined;
+    /**
+     * Optional logger for diagnostic output. Defaults to a no-op logger so
+     * existing callers produce no output.
+     */
+    readonly logger?: LoggerLike | undefined;
 }
 
 export { Group }
@@ -2391,6 +2447,11 @@ export declare interface WriteSchemasOptions extends GenerateJsonSchemaOptions {
     readonly name?: string;
     /** Number of spaces for JSON indentation. Defaults to 2 */
     readonly indent?: number;
+    /**
+     * Optional logger for diagnostic output. Defaults to a no-op logger so
+     * existing callers produce no output.
+     */
+    readonly logger?: LoggerLike | undefined;
 }
 
 /**

package/dist/build-beta.d.ts

@@ -40,6 +40,7 @@ import { ExtensionDefinition } from '@formspec/core';
 import { FormElement } from '@formspec/core';
 import { FormSpec } from '@formspec/core';
 import { Group } from '@formspec/core';
+import type { LoggerLike } from '@formspec/core';
 import type { MetadataPolicyInput } from '@formspec/core';
 import { NumberField } from '@formspec/core';
 import { ObjectField } from '@formspec/core';
@@ -95,6 +96,11 @@ export declare function buildFormSchemas<E extends readonly FormElement[]>(form:
  * @public
  */
 export declare interface BuildFormSchemasOptions extends GenerateJsonSchemaOptions, GenerateUiSchemaOptions {
+    /**
+     * Optional logger for diagnostic output. Defaults to a no-op logger so
+     * existing callers produce no output.
+     */
+    readonly logger?: LoggerLike | undefined;
 }
 
 /**
@@ -463,6 +469,46 @@ 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.
      *
@@ -1008,6 +1054,11 @@ export declare interface GenerateJsonSchemaOptions {
     readonly enumSerialization?: "enum" | "oneOf";
     /** Metadata resolution policy for chain DSL generation. */
     readonly metadata?: MetadataPolicyInput | undefined;
+    /**
+     * Optional logger for diagnostic output. Defaults to a no-op logger so
+     * existing callers produce no output.
+     */
+    readonly logger?: LoggerLike | undefined;
 }
 
 /**
@@ -1390,6 +1441,11 @@ export declare function generateUiSchema<E extends readonly FormElement[]>(form:
 export declare interface GenerateUiSchemaOptions {
     /** Metadata resolution policy for chain DSL UI generation. */
     readonly metadata?: MetadataPolicyInput | undefined;
+    /**
+     * Optional logger for diagnostic output. Defaults to a no-op logger so
+     * existing callers produce no output.
+     */
+    readonly logger?: LoggerLike | undefined;
 }
 
 export { Group }
@@ -2391,6 +2447,11 @@ export declare interface WriteSchemasOptions extends GenerateJsonSchemaOptions {
     readonly name?: string;
     /** Number of spaces for JSON indentation. Defaults to 2 */
     readonly indent?: number;
+    /**
+     * Optional logger for diagnostic output. Defaults to a no-op logger so
+     * existing callers produce no output.
+     */
+    readonly logger?: LoggerLike | undefined;
 }
 
 /**

package/dist/build-internal.d.ts

@@ -40,6 +40,7 @@ import { ExtensionDefinition } from '@formspec/core';
 import { FormElement } from '@formspec/core';
 import { FormSpec } from '@formspec/core';
 import { Group } from '@formspec/core';
+import type { LoggerLike } from '@formspec/core';
 import type { MetadataPolicyInput } from '@formspec/core';
 import { NumberField } from '@formspec/core';
 import { ObjectField } from '@formspec/core';
@@ -95,6 +96,11 @@ export declare function buildFormSchemas<E extends readonly FormElement[]>(form:
  * @public
  */
 export declare interface BuildFormSchemasOptions extends GenerateJsonSchemaOptions, GenerateUiSchemaOptions {
+    /**
+     * Optional logger for diagnostic output. Defaults to a no-op logger so
+     * existing callers produce no output.
+     */
+    readonly logger?: LoggerLike | undefined;
 }
 
 /**
@@ -463,6 +469,46 @@ 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.
      *
@@ -1008,6 +1054,11 @@ export declare interface GenerateJsonSchemaOptions {
     readonly enumSerialization?: "enum" | "oneOf";
     /** Metadata resolution policy for chain DSL generation. */
     readonly metadata?: MetadataPolicyInput | undefined;
+    /**
+     * Optional logger for diagnostic output. Defaults to a no-op logger so
+     * existing callers produce no output.
+     */
+    readonly logger?: LoggerLike | undefined;
 }
 
 /**
@@ -1390,6 +1441,11 @@ export declare function generateUiSchema<E extends readonly FormElement[]>(form:
 export declare interface GenerateUiSchemaOptions {
     /** Metadata resolution policy for chain DSL UI generation. */
     readonly metadata?: MetadataPolicyInput | undefined;
+    /**
+     * Optional logger for diagnostic output. Defaults to a no-op logger so
+     * existing callers produce no output.
+     */
+    readonly logger?: LoggerLike | undefined;
 }
 
 export { Group }
@@ -2391,6 +2447,11 @@ export declare interface WriteSchemasOptions extends GenerateJsonSchemaOptions {
     readonly name?: string;
     /** Number of spaces for JSON indentation. Defaults to 2 */
     readonly indent?: number;
+    /**
+     * Optional logger for diagnostic output. Defaults to a no-op logger so
+     * existing callers produce no output.
+     */
+    readonly logger?: LoggerLike | undefined;
 }
 
 /**

package/dist/build.d.ts

@@ -40,6 +40,7 @@ import { ExtensionDefinition } from '@formspec/core';
 import { FormElement } from '@formspec/core';
 import { FormSpec } from '@formspec/core';
 import { Group } from '@formspec/core';
+import type { LoggerLike } from '@formspec/core';
 import type { MetadataPolicyInput } from '@formspec/core';
 import { NumberField } from '@formspec/core';
 import { ObjectField } from '@formspec/core';
@@ -95,6 +96,11 @@ export declare function buildFormSchemas<E extends readonly FormElement[]>(form:
  * @public
  */
 export declare interface BuildFormSchemasOptions extends GenerateJsonSchemaOptions, GenerateUiSchemaOptions {
+    /**
+     * Optional logger for diagnostic output. Defaults to a no-op logger so
+     * existing callers produce no output.
+     */
+    readonly logger?: LoggerLike | undefined;
 }
 
 /**
@@ -463,6 +469,46 @@ 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.
      *
@@ -1008,6 +1054,11 @@ export declare interface GenerateJsonSchemaOptions {
     readonly enumSerialization?: "enum" | "oneOf";
     /** Metadata resolution policy for chain DSL generation. */
     readonly metadata?: MetadataPolicyInput | undefined;
+    /**
+     * Optional logger for diagnostic output. Defaults to a no-op logger so
+     * existing callers produce no output.
+     */
+    readonly logger?: LoggerLike | undefined;
 }
 
 /**
@@ -1390,6 +1441,11 @@ export declare function generateUiSchema<E extends readonly FormElement[]>(form:
 export declare interface GenerateUiSchemaOptions {
     /** Metadata resolution policy for chain DSL UI generation. */
     readonly metadata?: MetadataPolicyInput | undefined;
+    /**
+     * Optional logger for diagnostic output. Defaults to a no-op logger so
+     * existing callers produce no output.
+     */
+    readonly logger?: LoggerLike | undefined;
 }
 
 export { Group }
@@ -2391,6 +2447,11 @@ export declare interface WriteSchemasOptions extends GenerateJsonSchemaOptions {
     readonly name?: string;
     /** Number of spaces for JSON indentation. Defaults to 2 */
     readonly indent?: number;
+    /**
+     * Optional logger for diagnostic output. Defaults to a no-op logger so
+     * existing callers produce no output.
+     */
+    readonly logger?: LoggerLike | undefined;
 }
 
 /**

package/dist/cli/logger.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pino-based logger factory for the @formspec/build CLI.
+ *
+ * Reads `process.env.DEBUG` to determine which namespaces are enabled using
+ * the shared matcher in `@formspec/core` — same semantics as the `debug` npm
+ * package (comma-separated patterns, `*` wildcard, `-` prefix for negation,
+ * negations always win).
+ */
+import type { LoggerLike } from "@formspec/core";
+/**
+ * Creates a logger for the given namespace.
+ *
+ * When the namespace is enabled by `DEBUG`, writes structured JSON to stderr
+ * (with pino-pretty formatting when stderr is a TTY). Otherwise returns the
+ * silent `noopLogger` from `@formspec/core`.
+ *
+ * pino and pino-pretty are loaded lazily via `require()` so that the CLI
+ * pays no load-time cost when logging is disabled, and so the dependencies
+ * can be declared as `optionalDependencies` of `@formspec/build`.
+ */
+export declare function createLogger(namespace: string): LoggerLike;
+//# sourceMappingURL=logger.d.ts.map

package/dist/cli/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/cli/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAIjD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAwB1D"}