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

package/README.md

@@ -182,15 +182,22 @@ Generation validates canonical IR before emitting schemas. Invalid inputs now fa
 
 ### Handling Generation Failures
 
-Static generation APIs such as `generateSchemas()` still throw on invalid input, but the thrown error message now includes stable diagnostic codes that consumers can inspect or surface directly.
+Static generation now uses explicit error reporting on the main entry points:
+
+- `generateSchemas({ ..., errorReporting: "throw" })` and `generateSchemasFromProgram({ ..., errorReporting: "throw" })` keep the simple throw-on-error contract.
+- `generateSchemas({ ..., errorReporting: "diagnostics" })` and `generateSchemasFromProgram({ ..., errorReporting: "diagnostics" })` return structured diagnostics instead of throwing for analysis and validation failures.
+- `generateSchemasBatch()` and `generateSchemasBatchFromProgram()` continue to return per-target diagnostics across multiple targets.
+
+Use the `"throw"` mode when you want "schema or failure" ergonomics. Use the `"diagnostics"` mode when you want to surface as much feedback as possible in one pass, especially in editor, CI, or migration tooling. The older `generateSchemasDetailed()` and `generateSchemasFromProgramDetailed()` wrappers remain available only as deprecated compatibility shims.
 
 ```ts
-import { generateSchemas } from "@formspec/build";
+import { generateSchemas, generateSchemasBatch } from "@formspec/build";
 
 try {
   const { jsonSchema, uiSchema } = generateSchemas({
     filePath: "./src/forms.ts",
     typeName: "Invoice",
+    errorReporting: "throw",
   });
 } catch (error) {
   const message = error instanceof Error ? error.message : String(error);
@@ -205,6 +212,33 @@ try {
 
   throw error;
 }
+
+const detailed = generateSchemas({
+  filePath: "./src/forms.ts",
+  typeName: "Invoice",
+  errorReporting: "diagnostics",
+});
+
+if (!detailed.ok) {
+  for (const diagnostic of detailed.diagnostics) {
+    console.error(`${diagnostic.code}: ${diagnostic.message}`);
+  }
+}
+
+const batch = generateSchemasBatch({
+  targets: [
+    { filePath: "./src/forms.ts", typeName: "Invoice" },
+    { filePath: "./src/forms.ts", typeName: "PaymentTerms" },
+  ],
+});
+
+for (const result of batch) {
+  if (!result.ok) {
+    console.error(
+      `${result.typeName} failed: ${result.diagnostics.map((diagnostic) => diagnostic.code).join(", ")}`
+    );
+  }
+}
 ```
 
 The most relevant codes for extension-backed static analysis failures are:
@@ -212,6 +246,9 @@ The most relevant codes for extension-backed static analysis failures are:
 - `UNSUPPORTED_CUSTOM_TYPE_OVERRIDE` for extension custom types that conflict with unsupported TypeScript global built-ins.
 - `SYNTHETIC_SETUP_FAILURE` for invalid or conflicting extension custom type registrations and other synthetic compiler setup failures.
 - `TYPE_MISMATCH` for normal tag-on-type incompatibilities in author source.
+- `TYPE_NOT_FOUND` when a requested exported target cannot be resolved.
+- `UNSUPPORTED_ROOT_TYPE` and `DUPLICATE_ROOT_PROPERTIES` when a requested type alias cannot be treated as a schema root.
+- `PROGRAM_CONTEXT_FAILURE` when the package cannot create or reuse a TypeScript program for the requested file.
 
 As a rule of thumb, `UNSUPPORTED_CUSTOM_TYPE_OVERRIDE` and `SYNTHETIC_SETUP_FAILURE` indicate extension configuration problems, while `TYPE_MISMATCH` usually indicates an authoring error in the analyzed source.
 
@@ -228,6 +265,8 @@ Low-level canonical IR generators, analyzer primitives, and validation helpers a
 - `generateSchemas(options)`
 - `generateSchemasFromClass(options)`
 - `generateSchemasFromProgram(options)`
+- `generateSchemasBatch(options)`
+- `generateSchemasBatchFromProgram(options)`
 - `buildMixedAuthoringSchemas(options)`
 - `createExtensionRegistry(extensions)`
 

package/dist/analyzer/program.d.ts

@@ -5,6 +5,7 @@
  * using the project's tsconfig.json for compiler options.
  */
 import * as ts from "typescript";
+import type { ConstraintSemanticDiagnostic } from "@formspec/analysis/internal";
 import { type DiscriminatorResolutionOptions, type IRClassAnalysis } from "./class-analyzer.js";
 import type { ExtensionRegistry } from "../extensions/index.js";
 import type { MetadataPolicyInput } from "@formspec/core";
@@ -19,6 +20,13 @@ export interface ProgramContext {
     /** The source file being analyzed */
     sourceFile: ts.SourceFile;
 }
+export type AnalyzeNamedTypeToIRDetailedResult = {
+    readonly ok: true;
+    readonly analysis: IRClassAnalysis;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly ConstraintSemanticDiagnostic[];
+};
 /**
  * Resolves a source file and checker from an existing TypeScript program.
  *
@@ -74,6 +82,11 @@ export declare function findTypeAliasByName(sourceFile: ts.SourceFile, aliasName
  * @returns IR analysis result
  */
 export declare function analyzeNamedTypeToIR(filePath: string, typeName: string, extensionRegistry?: ExtensionRegistry, metadataPolicy?: MetadataPolicyInput, discriminatorOptions?: DiscriminatorResolutionOptions): IRClassAnalysis;
+/**
+ * Analyzes a named type from an existing program context and returns either an
+ * `IRClassAnalysis` or structured diagnostics instead of throwing.
+ */
+export declare function analyzeNamedTypeToIRFromProgramContextDetailed(ctx: ProgramContext, filePath: string, typeName: string, extensionRegistry?: ExtensionRegistry, metadataPolicy?: MetadataPolicyInput, discriminatorOptions?: DiscriminatorResolutionOptions): AnalyzeNamedTypeToIRDetailedResult;
 /**
  * Analyzes a named type from an existing program context and returns an `IRClassAnalysis`.
  */

package/dist/analyzer/program.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../../src/analyzer/program.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAIjC,OAAO,EASL,KAAK,8BAA8B,EACnC,KAAK,eAAe,EAErB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC;IACpB,uCAAuC;IACvC,OAAO,EAAE,EAAE,CAAC,WAAW,CAAC;IACxB,qCAAqC;IACrC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,EAAE,CAAC,OAAO,EACnB,QAAQ,EAAE,MAAM,GACf,cAAc,CAahB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CA6DrE;AA6BD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,SAAS,EAAE,MAAM,GAChB,EAAE,CAAC,gBAAgB,GAAG,IAAI,CAE5B;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,aAAa,EAAE,MAAM,GACpB,EAAE,CAAC,oBAAoB,GAAG,IAAI,CAEhC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,SAAS,EAAE,MAAM,GAChB,EAAE,CAAC,oBAAoB,GAAG,IAAI,CAEhC;AAiID;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,iBAAiB,CAAC,EAAE,iBAAiB,EACrC,cAAc,CAAC,EAAE,mBAAmB,EACpC,oBAAoB,CAAC,EAAE,8BAA8B,GACpD,eAAe,CAUjB;AAED;;GAEG;AACH,wBAAgB,sCAAsC,CACpD,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,iBAAiB,CAAC,EAAE,iBAAiB,EACrC,cAAc,CAAC,EAAE,mBAAmB,EACpC,oBAAoB,CAAC,EAAE,8BAA8B,GACpD,eAAe,CAkGjB"}
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../../src/analyzer/program.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAGjC,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,EASL,KAAK,8BAA8B,EACnC,KAAK,eAAe,EAErB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC;IACpB,uCAAuC;IACvC,OAAO,EAAE,EAAE,CAAC,WAAW,CAAC;IACxB,qCAAqC;IACrC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC;CAC3B;AAED,MAAM,MAAM,kCAAkC,GAC1C;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;CAAE,GACzD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,WAAW,EAAE,SAAS,4BAA4B,EAAE,CAAC;CAC/D,CAAC;AAEN;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,EAAE,CAAC,OAAO,EACnB,QAAQ,EAAE,MAAM,GACf,cAAc,CAahB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CA6DrE;AA6BD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,SAAS,EAAE,MAAM,GAChB,EAAE,CAAC,gBAAgB,GAAG,IAAI,CAE5B;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,aAAa,EAAE,MAAM,GACpB,EAAE,CAAC,oBAAoB,GAAG,IAAI,CAEhC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,SAAS,EAAE,MAAM,GAChB,EAAE,CAAC,oBAAoB,GAAG,IAAI,CAEhC;AAoID;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,iBAAiB,CAAC,EAAE,iBAAiB,EACrC,cAAc,CAAC,EAAE,mBAAmB,EACpC,oBAAoB,CAAC,EAAE,8BAA8B,GACpD,eAAe,CAUjB;AAED;;;GAGG;AACH,wBAAgB,8CAA8C,CAC5D,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,iBAAiB,CAAC,EAAE,iBAAiB,EACrC,cAAc,CAAC,EAAE,mBAAmB,EACpC,oBAAoB,CAAC,EAAE,8BAA8B,GACpD,kCAAkC,CA0IpC;AAED;;GAEG;AACH,wBAAgB,sCAAsC,CACpD,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,iBAAiB,CAAC,EAAE,iBAAiB,EACrC,cAAc,CAAC,EAAE,mBAAmB,EACpC,oBAAoB,CAAC,EAAE,8BAA8B,GACpD,eAAe,CAcjB"}