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

package/README.md

@@ -180,6 +180,41 @@ 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 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.
+
+```ts
+import { generateSchemas } from "@formspec/build";
+
+try {
+  const { jsonSchema, uiSchema } = generateSchemas({
+    filePath: "./src/forms.ts",
+    typeName: "Invoice",
+  });
+} 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;
+}
+```
+
+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.
+
+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`.

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"}

package/dist/cli.cjs

@@ -2223,6 +2223,16 @@ function buildSupportingDeclarations(sourceFile, extensionTypeNames) {
     return true;
   }).map((statement) => statement.getText(sourceFile));
 }
+function pushUniqueCompilerDiagnostics(target, additions) {
+  for (const diagnostic of additions) {
+    if ((diagnostic.code === "UNSUPPORTED_CUSTOM_TYPE_OVERRIDE" || diagnostic.code === "SYNTHETIC_SETUP_FAILURE") && target.some(
+      (existing) => existing.code === diagnostic.code && existing.message === diagnostic.message
+    )) {
+      continue;
+    }
+    target.push(diagnostic);
+  }
+}
 function renderSyntheticArgumentExpression(valueKind, argumentText) {
   const trimmed = argumentText.trim();
   if (trimmed === "") {
@@ -2489,6 +2499,16 @@ function buildCompilerBackedConstraintDiagnostics(node, sourceFile, tagName, par
   if (result.diagnostics.length === 0) {
     return [];
   }
+  const setupDiagnostic = result.diagnostics.find((diagnostic) => diagnostic.kind !== "typescript");
+  if (setupDiagnostic !== void 0) {
+    return [
+      makeDiagnostic(
+        setupDiagnostic.kind === "unsupported-custom-type-override" ? "UNSUPPORTED_CUSTOM_TYPE_OVERRIDE" : "SYNTHETIC_SETUP_FAILURE",
+        setupDiagnostic.message,
+        provenance
+      )
+    ];
+  }
   const expectedLabel = definition.valueKind === null ? "compatible argument" : capabilityLabel(definition.valueKind);
   return [
     makeDiagnostic(
@@ -2652,7 +2672,7 @@ function parseTSDocTags(node, file = "", options) {
           options
         );
         if (compilerDiagnostics.length > 0) {
-          diagnostics.push(...compilerDiagnostics);
+          pushUniqueCompilerDiagnostics(diagnostics, compilerDiagnostics);
           continue;
         }
         const constraintNode = (0, import_internal2.parseConstraintTagValue)(
@@ -2739,7 +2759,7 @@ function parseTSDocTags(node, file = "", options) {
         options
       );
       if (compilerDiagnostics.length > 0) {
-        diagnostics.push(...compilerDiagnostics);
+        pushUniqueCompilerDiagnostics(diagnostics, compilerDiagnostics);
         continue;
       }
       const constraintNode = (0, import_internal2.parseConstraintTagValue)(
@@ -2773,7 +2793,7 @@ function parseTSDocTags(node, file = "", options) {
         options
       );
       if (compilerDiagnostics.length > 0) {
-        diagnostics.push(...compilerDiagnostics);
+        pushUniqueCompilerDiagnostics(diagnostics, compilerDiagnostics);
         continue;
       }
       const constraintNode = (0, import_internal2.parseConstraintTagValue)(