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

package/README.md

@@ -180,6 +180,78 @@ const result = generateSchemas({
 
 Generation validates canonical IR before emitting schemas. Invalid inputs now fail generation with structured diagnostic codes surfaced in the thrown error.
 
+### Handling Generation Failures
+
+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, 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);
+
+  if (message.includes("UNSUPPORTED_CUSTOM_TYPE_OVERRIDE")) {
+    // An extension tried to override a TS global built-in such as Date or Array
+  } else if (message.includes("SYNTHETIC_SETUP_FAILURE")) {
+    // Extension setup failed before tag type-checking could run
+  } else if (message.includes("TYPE_MISMATCH")) {
+    // A tag was applied to an incompatible field or target type
+  }
+
+  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:
+
+- `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.
+
 ## Internal Entry Point
 
 Low-level canonical IR generators, analyzer primitives, and validation helpers are intentionally no longer exported from the package root. If you need those unstable internals inside the monorepo, import them from `@formspec/build/internals`.
@@ -193,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"}

package/dist/analyzer/tsdoc-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tsdoc-parser.d.ts","sourceRoot":"","sources":["../../src/analyzer/tsdoc-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,EAcL,KAAK,4BAA4B,EAGlC,MAAM,6BAA6B,CAAC;AAkBrC,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,cAAc,EAEnB,KAAK,UAAU,EACf,KAAK,QAAQ,EACd,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AA4lBhE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;IAChD,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;IAChD,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,SAAS,4BAA4B,EAAE,CAAC;CAC/D;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC;IAClC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1D;AA4DD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,IAAI,SAAK,EACT,OAAO,CAAC,EAAE,iBAAiB,GAC1B,gBAAgB,CAsSlB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,OAAO,CAsB5D;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,mBAAmB,CAmC7E;AAMD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,GACX;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAEpD"}
+{"version":3,"file":"tsdoc-parser.d.ts","sourceRoot":"","sources":["../../src/analyzer/tsdoc-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,EAcL,KAAK,4BAA4B,EAGlC,MAAM,6BAA6B,CAAC;AAkBrC,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,cAAc,EAEnB,KAAK,UAAU,EACf,KAAK,QAAQ,EACd,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AA4nBhE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;IAChD,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;IAChD,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,SAAS,4BAA4B,EAAE,CAAC;CAC/D;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC;IAClC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1D;AA4DD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,IAAI,SAAK,EACT,OAAO,CAAC,EAAE,iBAAiB,GAC1B,gBAAgB,CAsSlB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,OAAO,CAsB5D;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,mBAAmB,CAmC7E;AAMD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,GACX;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAEpD"}