@formspec/build 0.1.0-alpha.37 → 0.1.0-alpha.39

package/dist/build-alpha.d.ts

@@ -43,6 +43,7 @@ import { Group } from '@formspec/core';
 import type { MetadataPolicyInput } from '@formspec/core';
 import { NumberField } from '@formspec/core';
 import { ObjectField } from '@formspec/core';
+import type { ResolvedMetadata } from '@formspec/core';
 import { StaticEnumField } from '@formspec/core';
 import { TextField } from '@formspec/core';
 import * as ts from 'typescript';
@@ -246,6 +247,34 @@ export { CustomConstraintRegistration }
 
 export { CustomTypeRegistration }
 
+/**
+ * Non-throwing schema generation result with structured diagnostics.
+ *
+ * @public
+ */
+export declare interface DetailedClassSchemasResult {
+    /** Whether schema generation completed without error-severity diagnostics. */
+    readonly ok: boolean;
+    /** Collected analysis and validation diagnostics for this target. */
+    readonly diagnostics: readonly ValidationDiagnostic[];
+    /** JSON Schema 2020-12 for validation, when generation succeeds. */
+    readonly jsonSchema?: JsonSchema2020 | undefined;
+    /** JSON Forms UI Schema for rendering, when generation succeeds. */
+    readonly uiSchema?: UISchema | undefined;
+}
+
+/**
+ * Result for a single target in a batch generation request.
+ *
+ * @public
+ */
+export declare interface DetailedSchemaGenerationTargetResult extends DetailedClassSchemasResult {
+    /** Path to the TypeScript source file. */
+    readonly filePath: string;
+    /** Name of the exported class, interface, or type alias that was analyzed. */
+    readonly typeName: string;
+}
+
 /**
  * Generated schemas for a discovered declaration or signature type.
  *
@@ -259,6 +288,14 @@ export declare interface DiscoveredTypeSchemas {
     readonly jsonSchema: JsonSchema2020;
     /** UI Schema for object-shaped roots, or `null` when not applicable. */
     readonly uiSchema: UISchema | null;
+    /**
+     * Resolved type-level metadata used during generation, when available.
+     *
+     * This preserves explicit and inferred naming metadata such as singular and
+     * plural API/display names for consumers that need the resolved values in
+     * addition to the emitted schema artifacts.
+     */
+    readonly resolvedMetadata?: ResolvedMetadata | undefined;
 }
 
 /**
@@ -447,15 +484,99 @@ export declare interface GenerateJsonSchemaOptions {
  * const result = generateSchemas({
  *   filePath: "./src/config.ts",
  *   typeName: "DiscountConfig",
+ *   errorReporting: "throw",
  * });
  * ```
+ */
+/**
+ * Generates JSON Schema and UI Schema from a named type and throws when
+ * generation reports error-severity diagnostics.
+ *
+ * @param options - File path, type name, and explicit throw-on-error reporting
+ * @returns Generated JSON Schema and UI Schema
+ *
+ * @public
+ */
+export declare function generateSchemas(options: GenerateSchemasOptions & {
+    readonly errorReporting: "throw";
+}): GenerateFromClassResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type and returns structured
+ * diagnostics instead of throwing on validation or analysis failures.
  *
+ * @param options - File path, type name, and explicit diagnostics reporting
+ * @returns Structured generation result with diagnostics
+ *
+ * @public
+ */
+export declare function generateSchemas(options: GenerateSchemasOptions & {
+    readonly errorReporting: "diagnostics";
+}): DetailedClassSchemasResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type.
+ *
+ * @deprecated Pass `errorReporting` explicitly. Omitting it defaults to `"throw"` only for backward compatibility.
  * @param options - File path and type name
  * @returns Generated JSON Schema and UI Schema
  *
  * @public
  */
-export declare function generateSchemas(options: GenerateSchemasOptions): GenerateFromClassResult;
+export declare function generateSchemas(options: StaticSchemaGenerationOptions & {
+    readonly filePath: string;
+    readonly typeName: string;
+}): GenerateFromClassResult;
+
+/**
+ * Generates schemas for many targets and returns per-target diagnostics instead
+ * of failing on the first problem.
+ *
+ * @public
+ */
+export declare function generateSchemasBatch(options: GenerateSchemasBatchOptions): readonly DetailedSchemaGenerationTargetResult[];
+
+/**
+ * Generates schemas for many targets from an existing TypeScript program and
+ * returns per-target diagnostics instead of failing on the first problem.
+ *
+ * @public
+ */
+export declare function generateSchemasBatchFromProgram(options: GenerateSchemasBatchFromProgramOptions): readonly DetailedSchemaGenerationTargetResult[];
+
+/**
+ * Batch options for non-throwing schema generation using an existing program.
+ *
+ * @public
+ */
+export declare interface GenerateSchemasBatchFromProgramOptions extends StaticSchemaGenerationOptions {
+    /** Existing TypeScript program supplied by the caller. */
+    readonly program: ts.Program;
+    /** Targets to analyze and generate. */
+    readonly targets: readonly SchemaGenerationTarget[];
+}
+
+/**
+ * Batch options for non-throwing schema generation.
+ *
+ * @public
+ */
+export declare interface GenerateSchemasBatchOptions extends StaticSchemaGenerationOptions {
+    /** Targets to analyze and generate. */
+    readonly targets: readonly SchemaGenerationTarget[];
+}
+
+/**
+ * Generates JSON Schema and UI Schema from a named type and returns structured
+ * diagnostics instead of throwing on validation or analysis failures.
+ * @deprecated Use `generateSchemas({ ...options, errorReporting: "diagnostics" })` instead.
+ *
+ * @public
+ */
+export declare function generateSchemasDetailed(options: StaticSchemaGenerationOptions & {
+    readonly filePath: string;
+    readonly typeName: string;
+}): DetailedClassSchemasResult;
 
 /**
  * Generates JSON Schema and UI Schema from a decorated TypeScript class.
@@ -529,13 +650,63 @@ export declare interface GenerateSchemasFromParameterOptions extends StaticSchem
  *
  * This low-level entry point lets downstream tooling reuse a host-owned
  * `Program` for both FormSpec extraction and other TypeScript analysis.
+ */
+/**
+ * Generates JSON Schema and UI Schema from a named type within an existing
+ * TypeScript program and throws when generation reports error-severity diagnostics.
+ *
+ * @param options - Host program, file path, type name, and explicit throw-on-error reporting
+ * @returns Generated JSON Schema and UI Schema
  *
- * @param options - Host program, file path, type name, and optional schema generation options
+ * @public
+ */
+export declare function generateSchemasFromProgram(options: GenerateSchemasFromProgramOptions & {
+    readonly errorReporting: "throw";
+}): GenerateFromClassResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type within an existing
+ * TypeScript program and returns structured diagnostics instead of throwing on
+ * validation or analysis failures.
+ *
+ * @param options - Host program, file path, type name, and explicit diagnostics reporting
+ * @returns Structured generation result with diagnostics
+ *
+ * @public
+ */
+export declare function generateSchemasFromProgram(options: GenerateSchemasFromProgramOptions & {
+    readonly errorReporting: "diagnostics";
+}): DetailedClassSchemasResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type within an existing
+ * TypeScript program.
+ *
+ * @deprecated Pass `errorReporting` explicitly. Omitting it defaults to `"throw"` only for backward compatibility.
+ * @param options - Host program, file path, and type name
  * @returns Generated JSON Schema and UI Schema
  *
  * @public
  */
-export declare function generateSchemasFromProgram(options: GenerateSchemasFromProgramOptions): GenerateFromClassResult;
+export declare function generateSchemasFromProgram(options: StaticSchemaGenerationOptions & {
+    readonly program: ts.Program;
+    readonly filePath: string;
+    readonly typeName: string;
+}): GenerateFromClassResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type within an existing
+ * TypeScript program and returns structured diagnostics instead of throwing on
+ * validation or analysis failures.
+ * @deprecated Use `generateSchemasFromProgram({ ...options, errorReporting: "diagnostics" })` instead.
+ *
+ * @public
+ */
+export declare function generateSchemasFromProgramDetailed(options: StaticSchemaGenerationOptions & {
+    readonly program: ts.Program;
+    readonly filePath: string;
+    readonly typeName: string;
+}): DetailedClassSchemasResult;
 
 /**
  * Options for generating schemas from a named type inside an existing TypeScript program.
@@ -549,6 +720,10 @@ export declare interface GenerateSchemasFromProgramOptions extends StaticSchemaG
     readonly filePath: string;
     /** Name of the exported class, interface, or type alias to analyze */
     readonly typeName: string;
+    /**
+     * Controls whether error-severity diagnostics throw or are returned in the result.
+     */
+    readonly errorReporting: "throw" | "diagnostics";
 }
 
 /**
@@ -611,9 +786,13 @@ export declare interface GenerateSchemasFromTypeOptions extends StaticSchemaGene
  */
 export declare interface GenerateSchemasOptions extends StaticSchemaGenerationOptions {
     /** Path to the TypeScript source file */
-    filePath: string;
+    readonly filePath: string;
     /** Name of the exported class, interface, or type alias to analyze */
-    typeName: string;
+    readonly typeName: string;
+    /**
+     * Controls whether error-severity diagnostics throw or are returned in the result.
+     */
+    readonly errorReporting: "throw" | "diagnostics";
 }
 
 /**
@@ -1019,6 +1198,18 @@ export declare interface SchemaBasedCondition {
     readonly schema: RuleConditionSchema;
 }
 
+/**
+ * A batch target for non-throwing schema generation.
+ *
+ * @public
+ */
+export declare interface SchemaGenerationTarget {
+    /** Path to the TypeScript source file. */
+    readonly filePath: string;
+    /** Name of the exported class, interface, or type alias to analyze. */
+    readonly typeName: string;
+}
+
 /**
  * Supported declaration kinds for declaration-driven schema generation.
  *
@@ -1116,6 +1307,78 @@ export declare type UISchemaElementType = "Control" | "VerticalLayout" | "Horizo
  */
 export declare const uiSchemaSchema: z.ZodType<UISchema>;
 
+/**
+ * Options for validating canonical FormIR.
+ *
+ * @public
+ */
+export declare interface ValidateIROptions {
+    /** Vendor prefix used when resolving extension-backed keywords. */
+    readonly vendorPrefix?: string;
+    /** Extension registry used to resolve custom constraints and types. */
+    readonly extensionRegistry?: ExtensionRegistry;
+}
+
+/**
+ * A machine-readable validation diagnostic returned by static schema analysis.
+ *
+ * @public
+ */
+export declare interface ValidationDiagnostic {
+    /** Stable machine-readable diagnostic code. */
+    readonly code: string;
+    /** Human-readable explanation of the validation problem. */
+    readonly message: string;
+    /** Severity of the reported validation problem. */
+    readonly severity: ValidationDiagnosticSeverity;
+    /** Primary source location associated with the diagnostic. */
+    readonly primaryLocation: ValidationDiagnosticLocation;
+    /** Related source locations that add context to the diagnostic. */
+    readonly relatedLocations: readonly ValidationDiagnosticLocation[];
+}
+
+/**
+ * Public source-location shape attached to validation diagnostics.
+ *
+ * This mirrors the provenance information surfaced by the shared analysis
+ * layer without exposing `@formspec/core/internals` through the public API.
+ *
+ * @public
+ */
+export declare interface ValidationDiagnosticLocation {
+    /** Authoring surface that produced the diagnostic location. */
+    readonly surface: "tsdoc" | "chain-dsl" | "extension" | "inferred";
+    /** Absolute path to the source file. */
+    readonly file: string;
+    /** 1-based line number in the source file. */
+    readonly line: number;
+    /** 0-based column number in the source file. */
+    readonly column: number;
+    /** Optional span length in characters. */
+    readonly length?: number;
+    /** Optional tag or construct associated with the location. */
+    readonly tagName?: string;
+}
+
+/**
+ * Supported severity levels returned by static build validation.
+ *
+ * @public
+ */
+export declare type ValidationDiagnosticSeverity = "error" | "warning";
+
+/**
+ * Result of validating canonical FormIR before schema emission.
+ *
+ * @public
+ */
+export declare interface ValidationResult {
+    /** Diagnostics produced during validation. */
+    readonly diagnostics: readonly ValidationDiagnostic[];
+    /** Whether any error-severity diagnostics were produced. */
+    readonly valid: boolean;
+}
+
 /**
  * A vertical layout element.
  *

package/dist/build-beta.d.ts

@@ -43,6 +43,7 @@ import { Group } from '@formspec/core';
 import type { MetadataPolicyInput } from '@formspec/core';
 import { NumberField } from '@formspec/core';
 import { ObjectField } from '@formspec/core';
+import type { ResolvedMetadata } from '@formspec/core';
 import { StaticEnumField } from '@formspec/core';
 import { TextField } from '@formspec/core';
 import * as ts from 'typescript';
@@ -246,6 +247,34 @@ export { CustomConstraintRegistration }
 
 export { CustomTypeRegistration }
 
+/**
+ * Non-throwing schema generation result with structured diagnostics.
+ *
+ * @public
+ */
+export declare interface DetailedClassSchemasResult {
+    /** Whether schema generation completed without error-severity diagnostics. */
+    readonly ok: boolean;
+    /** Collected analysis and validation diagnostics for this target. */
+    readonly diagnostics: readonly ValidationDiagnostic[];
+    /** JSON Schema 2020-12 for validation, when generation succeeds. */
+    readonly jsonSchema?: JsonSchema2020 | undefined;
+    /** JSON Forms UI Schema for rendering, when generation succeeds. */
+    readonly uiSchema?: UISchema | undefined;
+}
+
+/**
+ * Result for a single target in a batch generation request.
+ *
+ * @public
+ */
+export declare interface DetailedSchemaGenerationTargetResult extends DetailedClassSchemasResult {
+    /** Path to the TypeScript source file. */
+    readonly filePath: string;
+    /** Name of the exported class, interface, or type alias that was analyzed. */
+    readonly typeName: string;
+}
+
 /**
  * Generated schemas for a discovered declaration or signature type.
  *
@@ -259,6 +288,14 @@ export declare interface DiscoveredTypeSchemas {
     readonly jsonSchema: JsonSchema2020;
     /** UI Schema for object-shaped roots, or `null` when not applicable. */
     readonly uiSchema: UISchema | null;
+    /**
+     * Resolved type-level metadata used during generation, when available.
+     *
+     * This preserves explicit and inferred naming metadata such as singular and
+     * plural API/display names for consumers that need the resolved values in
+     * addition to the emitted schema artifacts.
+     */
+    readonly resolvedMetadata?: ResolvedMetadata | undefined;
 }
 
 /**
@@ -447,15 +484,99 @@ export declare interface GenerateJsonSchemaOptions {
  * const result = generateSchemas({
  *   filePath: "./src/config.ts",
  *   typeName: "DiscountConfig",
+ *   errorReporting: "throw",
  * });
  * ```
+ */
+/**
+ * Generates JSON Schema and UI Schema from a named type and throws when
+ * generation reports error-severity diagnostics.
+ *
+ * @param options - File path, type name, and explicit throw-on-error reporting
+ * @returns Generated JSON Schema and UI Schema
+ *
+ * @public
+ */
+export declare function generateSchemas(options: GenerateSchemasOptions & {
+    readonly errorReporting: "throw";
+}): GenerateFromClassResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type and returns structured
+ * diagnostics instead of throwing on validation or analysis failures.
  *
+ * @param options - File path, type name, and explicit diagnostics reporting
+ * @returns Structured generation result with diagnostics
+ *
+ * @public
+ */
+export declare function generateSchemas(options: GenerateSchemasOptions & {
+    readonly errorReporting: "diagnostics";
+}): DetailedClassSchemasResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type.
+ *
+ * @deprecated Pass `errorReporting` explicitly. Omitting it defaults to `"throw"` only for backward compatibility.
  * @param options - File path and type name
  * @returns Generated JSON Schema and UI Schema
  *
  * @public
  */
-export declare function generateSchemas(options: GenerateSchemasOptions): GenerateFromClassResult;
+export declare function generateSchemas(options: StaticSchemaGenerationOptions & {
+    readonly filePath: string;
+    readonly typeName: string;
+}): GenerateFromClassResult;
+
+/**
+ * Generates schemas for many targets and returns per-target diagnostics instead
+ * of failing on the first problem.
+ *
+ * @public
+ */
+export declare function generateSchemasBatch(options: GenerateSchemasBatchOptions): readonly DetailedSchemaGenerationTargetResult[];
+
+/**
+ * Generates schemas for many targets from an existing TypeScript program and
+ * returns per-target diagnostics instead of failing on the first problem.
+ *
+ * @public
+ */
+export declare function generateSchemasBatchFromProgram(options: GenerateSchemasBatchFromProgramOptions): readonly DetailedSchemaGenerationTargetResult[];
+
+/**
+ * Batch options for non-throwing schema generation using an existing program.
+ *
+ * @public
+ */
+export declare interface GenerateSchemasBatchFromProgramOptions extends StaticSchemaGenerationOptions {
+    /** Existing TypeScript program supplied by the caller. */
+    readonly program: ts.Program;
+    /** Targets to analyze and generate. */
+    readonly targets: readonly SchemaGenerationTarget[];
+}
+
+/**
+ * Batch options for non-throwing schema generation.
+ *
+ * @public
+ */
+export declare interface GenerateSchemasBatchOptions extends StaticSchemaGenerationOptions {
+    /** Targets to analyze and generate. */
+    readonly targets: readonly SchemaGenerationTarget[];
+}
+
+/**
+ * Generates JSON Schema and UI Schema from a named type and returns structured
+ * diagnostics instead of throwing on validation or analysis failures.
+ * @deprecated Use `generateSchemas({ ...options, errorReporting: "diagnostics" })` instead.
+ *
+ * @public
+ */
+export declare function generateSchemasDetailed(options: StaticSchemaGenerationOptions & {
+    readonly filePath: string;
+    readonly typeName: string;
+}): DetailedClassSchemasResult;
 
 /**
  * Generates JSON Schema and UI Schema from a decorated TypeScript class.
@@ -529,13 +650,63 @@ export declare interface GenerateSchemasFromParameterOptions extends StaticSchem
  *
  * This low-level entry point lets downstream tooling reuse a host-owned
  * `Program` for both FormSpec extraction and other TypeScript analysis.
+ */
+/**
+ * Generates JSON Schema and UI Schema from a named type within an existing
+ * TypeScript program and throws when generation reports error-severity diagnostics.
+ *
+ * @param options - Host program, file path, type name, and explicit throw-on-error reporting
+ * @returns Generated JSON Schema and UI Schema
  *
- * @param options - Host program, file path, type name, and optional schema generation options
+ * @public
+ */
+export declare function generateSchemasFromProgram(options: GenerateSchemasFromProgramOptions & {
+    readonly errorReporting: "throw";
+}): GenerateFromClassResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type within an existing
+ * TypeScript program and returns structured diagnostics instead of throwing on
+ * validation or analysis failures.
+ *
+ * @param options - Host program, file path, type name, and explicit diagnostics reporting
+ * @returns Structured generation result with diagnostics
+ *
+ * @public
+ */
+export declare function generateSchemasFromProgram(options: GenerateSchemasFromProgramOptions & {
+    readonly errorReporting: "diagnostics";
+}): DetailedClassSchemasResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type within an existing
+ * TypeScript program.
+ *
+ * @deprecated Pass `errorReporting` explicitly. Omitting it defaults to `"throw"` only for backward compatibility.
+ * @param options - Host program, file path, and type name
  * @returns Generated JSON Schema and UI Schema
  *
  * @public
  */
-export declare function generateSchemasFromProgram(options: GenerateSchemasFromProgramOptions): GenerateFromClassResult;
+export declare function generateSchemasFromProgram(options: StaticSchemaGenerationOptions & {
+    readonly program: ts.Program;
+    readonly filePath: string;
+    readonly typeName: string;
+}): GenerateFromClassResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type within an existing
+ * TypeScript program and returns structured diagnostics instead of throwing on
+ * validation or analysis failures.
+ * @deprecated Use `generateSchemasFromProgram({ ...options, errorReporting: "diagnostics" })` instead.
+ *
+ * @public
+ */
+export declare function generateSchemasFromProgramDetailed(options: StaticSchemaGenerationOptions & {
+    readonly program: ts.Program;
+    readonly filePath: string;
+    readonly typeName: string;
+}): DetailedClassSchemasResult;
 
 /**
  * Options for generating schemas from a named type inside an existing TypeScript program.
@@ -549,6 +720,10 @@ export declare interface GenerateSchemasFromProgramOptions extends StaticSchemaG
     readonly filePath: string;
     /** Name of the exported class, interface, or type alias to analyze */
     readonly typeName: string;
+    /**
+     * Controls whether error-severity diagnostics throw or are returned in the result.
+     */
+    readonly errorReporting: "throw" | "diagnostics";
 }
 
 /**
@@ -611,9 +786,13 @@ export declare interface GenerateSchemasFromTypeOptions extends StaticSchemaGene
  */
 export declare interface GenerateSchemasOptions extends StaticSchemaGenerationOptions {
     /** Path to the TypeScript source file */
-    filePath: string;
+    readonly filePath: string;
     /** Name of the exported class, interface, or type alias to analyze */
-    typeName: string;
+    readonly typeName: string;
+    /**
+     * Controls whether error-severity diagnostics throw or are returned in the result.
+     */
+    readonly errorReporting: "throw" | "diagnostics";
 }
 
 /**
@@ -1019,6 +1198,18 @@ export declare interface SchemaBasedCondition {
     readonly schema: RuleConditionSchema;
 }
 
+/**
+ * A batch target for non-throwing schema generation.
+ *
+ * @public
+ */
+export declare interface SchemaGenerationTarget {
+    /** Path to the TypeScript source file. */
+    readonly filePath: string;
+    /** Name of the exported class, interface, or type alias to analyze. */
+    readonly typeName: string;
+}
+
 /**
  * Supported declaration kinds for declaration-driven schema generation.
  *
@@ -1116,6 +1307,78 @@ export declare type UISchemaElementType = "Control" | "VerticalLayout" | "Horizo
  */
 export declare const uiSchemaSchema: z.ZodType<UISchema>;
 
+/**
+ * Options for validating canonical FormIR.
+ *
+ * @public
+ */
+export declare interface ValidateIROptions {
+    /** Vendor prefix used when resolving extension-backed keywords. */
+    readonly vendorPrefix?: string;
+    /** Extension registry used to resolve custom constraints and types. */
+    readonly extensionRegistry?: ExtensionRegistry;
+}
+
+/**
+ * A machine-readable validation diagnostic returned by static schema analysis.
+ *
+ * @public
+ */
+export declare interface ValidationDiagnostic {
+    /** Stable machine-readable diagnostic code. */
+    readonly code: string;
+    /** Human-readable explanation of the validation problem. */
+    readonly message: string;
+    /** Severity of the reported validation problem. */
+    readonly severity: ValidationDiagnosticSeverity;
+    /** Primary source location associated with the diagnostic. */
+    readonly primaryLocation: ValidationDiagnosticLocation;
+    /** Related source locations that add context to the diagnostic. */
+    readonly relatedLocations: readonly ValidationDiagnosticLocation[];
+}
+
+/**
+ * Public source-location shape attached to validation diagnostics.
+ *
+ * This mirrors the provenance information surfaced by the shared analysis
+ * layer without exposing `@formspec/core/internals` through the public API.
+ *
+ * @public
+ */
+export declare interface ValidationDiagnosticLocation {
+    /** Authoring surface that produced the diagnostic location. */
+    readonly surface: "tsdoc" | "chain-dsl" | "extension" | "inferred";
+    /** Absolute path to the source file. */
+    readonly file: string;
+    /** 1-based line number in the source file. */
+    readonly line: number;
+    /** 0-based column number in the source file. */
+    readonly column: number;
+    /** Optional span length in characters. */
+    readonly length?: number;
+    /** Optional tag or construct associated with the location. */
+    readonly tagName?: string;
+}
+
+/**
+ * Supported severity levels returned by static build validation.
+ *
+ * @public
+ */
+export declare type ValidationDiagnosticSeverity = "error" | "warning";
+
+/**
+ * Result of validating canonical FormIR before schema emission.
+ *
+ * @public
+ */
+export declare interface ValidationResult {
+    /** Diagnostics produced during validation. */
+    readonly diagnostics: readonly ValidationDiagnostic[];
+    /** Whether any error-severity diagnostics were produced. */
+    readonly valid: boolean;
+}
+
 /**
  * A vertical layout element.
  *