@formspec/build 0.1.0-alpha.11 → 0.1.0-alpha.13

package/README.md

@@ -79,13 +79,46 @@ const jsonSchema = generateJsonSchema(ContactForm);
 const uiSchema = generateUiSchema(ContactForm);
 ```
 
+### Canonical IR Pipeline
+
+The build pipeline now flows through a Canonical Intermediate Representation (IR). When you call `buildFormSchemas()`, the form definition is first converted to IR, then the IR is compiled to JSON Schema and UI Schema:
+
+```
+FormSpec definition → Canonical IR → JSON Schema + UI Schema
+```
+
+This enables consistent processing regardless of whether forms are defined via the Chain DSL or analyzed from TypeScript source files.
+
+### Generate from TypeScript Classes
+
+Generate schemas from TypeScript class definitions using static analysis of JSDoc constraint tags:
+
+```typescript
+import { generateSchemasFromClass } from "@formspec/build";
+
+const { jsonSchema, uiSchema } = generateSchemasFromClass({
+  filePath: "./src/forms.ts",
+  className: "UserForm",
+});
+```
+
+The analyzer extracts type information and JSDoc constraint tags (e.g., `/** @Minimum 0 @Maximum 100 */`) from class properties to generate schemas.
+
+### Entry Points
+
+| Entry Point               | Audience           | Description                                                                                       |
+| ------------------------- | ------------------ | ------------------------------------------------------------------------------------------------- |
+| `@formspec/build`         | Public API         | `buildFormSchemas`, `writeSchemas`, `generateSchemasFromClass`, schema generators                 |
+| `@formspec/build/browser` | Browser (playground) | Schema generators without Node.js `fs`/`path` — safe for bundlers                              |
+| `@formspec/build/internals` | CLI (unstable)   | Internal APIs: `createProgramContext`, `analyzeClass`, `generateClassSchemas`                     |
+
 ## Generated Output
 
-### JSON Schema (Draft-07)
+### JSON Schema (2020-12)
 
 ```json
 {
-  "$schema": "https://json-schema.org/draft-07/schema#",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {
     "name": { "type": "string", "title": "Name" },
@@ -116,22 +149,25 @@ const uiSchema = generateUiSchema(ContactForm);
 
 ### Functions
 
-| Function                      | Description                             |
-| ----------------------------- | --------------------------------------- |
-| `buildFormSchemas(form)`      | Generate both JSON Schema and UI Schema |
-| `generateJsonSchema(form)`    | Generate only JSON Schema               |
-| `generateUiSchema(form)`      | Generate only UI Schema                 |
-| `writeSchemas(form, options)` | Build and write schemas to disk         |
+| Function                             | Description                                                        |
+| ------------------------------------ | ------------------------------------------------------------------ |
+| `buildFormSchemas(form)`             | Generate both JSON Schema and UI Schema                            |
+| `generateJsonSchema(form)`           | Generate only JSON Schema                                          |
+| `generateUiSchema(form)`             | Generate only UI Schema                                            |
+| `writeSchemas(form, options)`        | Build and write schemas to disk                                    |
+| `generateSchemasFromClass(options)`  | Generate schemas from a TypeScript class via static analysis       |
+| `generateSchemas(options)`           | Generate schemas from a TypeScript type via static analysis        |
 
 ### Types
 
-| Type                  | Description                       |
-| --------------------- | --------------------------------- |
-| `BuildResult`         | Return type of `buildFormSchemas` |
-| `WriteSchemasOptions` | Options for `writeSchemas`        |
-| `WriteSchemasResult`  | Return type of `writeSchemas`     |
-| `JSONSchema7`         | JSON Schema Draft-07 type         |
-| `UISchema`            | JSON Forms UI Schema type         |
+| Type                      | Description                             |
+| ------------------------- | --------------------------------------- |
+| `BuildResult`             | Return type of `buildFormSchemas`       |
+| `WriteSchemasOptions`     | Options for `writeSchemas`              |
+| `WriteSchemasResult`      | Return type of `writeSchemas`           |
+| `JsonSchema2020`          | JSON Schema 2020-12 type                |
+| `GenerateFromClassOptions` | Options for `generateSchemasFromClass` |
+| `UISchema`                | JSON Forms UI Schema type               |
 
 ## License
 

package/dist/__tests__/chain-dsl-canonicalizer.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=chain-dsl-canonicalizer.test.d.ts.map

package/dist/__tests__/chain-dsl-canonicalizer.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain-dsl-canonicalizer.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/chain-dsl-canonicalizer.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/constraint-validator.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=constraint-validator.test.d.ts.map

package/dist/__tests__/constraint-validator.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraint-validator.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/constraint-validator.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/extension-api.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=extension-api.test.d.ts.map

package/dist/__tests__/extension-api.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-api.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/extension-api.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/fixtures/example-a-builtins.d.ts

@@ -1,8 +1,26 @@
 export declare class ExampleAForm {
+    /** @Field_displayName Full Name
+     *  @Field_description Your legal name
+     *  @MinLength 2
+     *  @MaxLength 100
+     */
     name: string;
+    /** @Field_displayName Age
+     *  @Minimum 0
+     *  @Maximum 150
+     */
     age: number;
+    /** @Field_displayName Score
+     *  @ExclusiveMinimum 0
+     */
     score: number;
+    /** @Field_displayName Email
+     *  @Pattern ^[^@]+@[^@]+$
+     */
     email?: string;
+    /** @Field_displayName Country
+     *  @EnumOptions [{"id":"us","label":"United States"},{"id":"ca","label":"Canada"}]
+     */
     country: "us" | "ca";
     state?: string;
     /** @deprecated Use email instead */

package/dist/__tests__/fixtures/example-a-builtins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"example-a-builtins.d.ts","sourceRoot":"","sources":["../../../src/__tests__/fixtures/example-a-builtins.ts"],"names":[],"mappings":"AAaA,qBAAa,YAAY;IAIvB,IAAI,EAAG,MAAM,CAAC;IAKd,GAAG,EAAG,MAAM,CAAC;IAIb,KAAK,EAAG,MAAM,CAAC;IAIf,KAAK,CAAC,EAAE,MAAM,CAAC;IAQf,OAAO,EAAG,IAAI,GAAG,IAAI,CAAC;IAItB,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,oCAAoC;IAEpC,GAAG,CAAC,EAAE,MAAM,CAAC;IAGb,IAAI,EAAE,OAAO,GAAG,MAAM,CAAU;CACjC"}
+{"version":3,"file":"example-a-builtins.d.ts","sourceRoot":"","sources":["../../../src/__tests__/fixtures/example-a-builtins.ts"],"names":[],"mappings":"AAAA,qBAAa,YAAY;IACvB;;;;OAIG;IACH,IAAI,EAAG,MAAM,CAAC;IAEd;;;OAGG;IACH,GAAG,EAAG,MAAM,CAAC;IAEb;;OAEG;IACH,KAAK,EAAG,MAAM,CAAC;IAEf;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,OAAO,EAAG,IAAI,GAAG,IAAI,CAAC;IAEtB,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,oCAAoC;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,IAAI,EAAE,OAAO,GAAG,MAAM,CAAU;CACjC"}

package/dist/__tests__/guards.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=guards.test.d.ts.map

package/dist/__tests__/guards.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/guards.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/ir-analyzer.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Tests for the IR analysis pipeline.
+ *
+ * Verifies that `analyzeClassToIR`, `analyzeInterfaceToIR`, and
+ * `analyzeTypeAliasToIR` produce canonical IR nodes (FieldNode,
+ * TypeNode, ConstraintNode, AnnotationNode) directly.
+ *
+ * @see packages/core/src/types/ir.ts for IR type definitions
+ */
+export {};
+//# sourceMappingURL=ir-analyzer.test.d.ts.map

package/dist/__tests__/ir-analyzer.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir-analyzer.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/ir-analyzer.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/ir-jsdoc-constraints.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tests for JSDoc constraint and annotation extraction to IR nodes.
+ *
+ * Verifies that {@link extractJSDocConstraintNodes} produces
+ * {@link ConstraintNode} and {@link extractJSDocAnnotationNodes} produces
+ * {@link AnnotationNode} directly.
+ *
+ * @see packages/core/src/types/ir.ts for IR type definitions
+ * @see packages/core/src/types/constraint-definitions.ts for BUILTIN_CONSTRAINT_DEFINITIONS
+ */
+export {};
+//# sourceMappingURL=ir-jsdoc-constraints.test.d.ts.map

package/dist/__tests__/ir-jsdoc-constraints.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir-jsdoc-constraints.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/ir-jsdoc-constraints.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/__tests__/ir-json-schema-generator.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Tests for `generateJsonSchemaFromIR`.
+ *
+ * All tests use hand-constructed FormIR objects and assert against expected
+ * JSON Schema 2020-12 output per design doc 003. Tests do NOT compare against
+ * the legacy `generateJsonSchema` function.
+ *
+ * @see scratch/design/003-json-schema-vocabulary.md
+ */
+export {};
+//# sourceMappingURL=ir-json-schema-generator.test.d.ts.map

package/dist/__tests__/ir-json-schema-generator.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir-json-schema-generator.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/ir-json-schema-generator.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/ir-ui-schema-generator.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ir-ui-schema-generator.test.d.ts.map

package/dist/__tests__/ir-ui-schema-generator.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir-ui-schema-generator.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/ir-ui-schema-generator.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/jsdoc-constraints.test.d.ts

@@ -1,10 +1,10 @@
 /**
- * Unit tests for JSDoc constraint tag extraction.
+ * Unit tests for JSDoc constraint extraction.
  *
- * Verifies that {@link extractJSDocConstraints} correctly parses TSDoc
- * constraint tags into synthetic DecoratorInfo objects.
+ * Verifies that {@link extractJSDocConstraints} correctly parses JSDoc
+ * constraints into synthetic ConstraintInfo objects.
  *
- * @see packages/core/src/types/decorators.ts for CONSTRAINT_TAG_DEFINITIONS
+ * @see packages/core/src/types/constraint-definitions.ts for BUILTIN_CONSTRAINT_DEFINITIONS
  */
 export {};
 //# sourceMappingURL=jsdoc-constraints.test.d.ts.map

package/dist/__tests__/parity/fixtures/address/chain-dsl.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parity fixture — address — chain DSL definition.
+ *
+ * A simple address form with string fields for street, city, and postal code.
+ * No constraints or annotations so the provenance-free IR can be compared
+ * directly with the TSDoc equivalent.
+ */
+export declare const addressForm: import("@formspec/core").FormSpec<readonly [import("@formspec/core").TextField<"street">, import("@formspec/core").TextField<"city">, import("@formspec/core").TextField<"postalCode">, import("@formspec/core").TextField<"country">]>;
+//# sourceMappingURL=chain-dsl.d.ts.map

package/dist/__tests__/parity/fixtures/address/chain-dsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain-dsl.d.ts","sourceRoot":"","sources":["../../../../../src/__tests__/parity/fixtures/address/chain-dsl.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,eAAO,MAAM,WAAW,yOAKvB,CAAC"}

package/dist/__tests__/parity/fixtures/address/expected-ir.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parity fixture — address — expected provenance-free IR.
+ *
+ * This is the canonical shape both the chain DSL and TSDoc surfaces must
+ * produce (after provenance stripping) for the address form.
+ */
+import type { ProvenanceFreeFormIR } from "../../utils.js";
+export declare const expectedIR: ProvenanceFreeFormIR;
+//# sourceMappingURL=expected-ir.d.ts.map

package/dist/__tests__/parity/fixtures/address/expected-ir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expected-ir.d.ts","sourceRoot":"","sources":["../../../../../src/__tests__/parity/fixtures/address/expected-ir.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,eAAO,MAAM,UAAU,EAAE,oBAsCxB,CAAC"}

package/dist/__tests__/parity/fixtures/address/tsdoc.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Parity fixture — address — TSDoc class definition.
+ *
+ * Equivalent form definition using a TypeScript class.
+ * Must produce the same provenance-free IR as the chain DSL fixture.
+ *
+ * Field mapping:
+ *   street:     string (required) → field.text("street", { required: true })
+ *   city:       string (required) → field.text("city", { required: true })
+ *   postalCode: string (required) → field.text("postalCode", { required: true })
+ *   country:    string (optional) → field.text("country")
+ */
+export declare class AddressForm {
+    street: string;
+    city: string;
+    postalCode: string;
+    country?: string;
+}
+//# sourceMappingURL=tsdoc.d.ts.map

package/dist/__tests__/parity/fixtures/address/tsdoc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsdoc.d.ts","sourceRoot":"","sources":["../../../../../src/__tests__/parity/fixtures/address/tsdoc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,qBAAa,WAAW;IACtB,MAAM,EAAG,MAAM,CAAC;IAChB,IAAI,EAAG,MAAM,CAAC;IACd,UAAU,EAAG,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/__tests__/parity/fixtures/product-config/chain-dsl.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Parity fixture — product-config — chain DSL definition.
+ *
+ * A product configuration form with a nested object field for pricing.
+ * Uses field.objectWithConfig() to create an inline ObjectTypeNode — matching
+ * the anonymous inline object type used in the TSDoc fixture.
+ *
+ * Named classes/interfaces in the TSDoc fixture would produce a ReferenceTypeNode
+ * via the type registry, which would diverge from the chain DSL inline object.
+ * Both surfaces therefore use anonymous inline objects for the nested type.
+ */
+export declare const productConfigForm: import("@formspec/core").FormSpec<readonly [import("@formspec/core").TextField<"sku">, import("@formspec/core").TextField<"name">, import("@formspec/core").BooleanField<"available">, import("@formspec/core").ObjectField<"pricing", readonly [import("@formspec/core").NumberField<"basePrice">, import("@formspec/core").TextField<"currency">]>]>;
+//# sourceMappingURL=chain-dsl.d.ts.map

package/dist/__tests__/parity/fixtures/product-config/chain-dsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain-dsl.d.ts","sourceRoot":"","sources":["../../../../../src/__tests__/parity/fixtures/product-config/chain-dsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,eAAO,MAAM,iBAAiB,wVAU7B,CAAC"}

package/dist/__tests__/parity/fixtures/product-config/expected-ir.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parity fixture — product-config — expected provenance-free IR.
+ *
+ * This is the canonical shape both the chain DSL and TSDoc surfaces must
+ * produce (after provenance stripping) for the product-config form.
+ */
+import type { ProvenanceFreeFormIR } from "../../utils.js";
+export declare const expectedIR: ProvenanceFreeFormIR;
+//# sourceMappingURL=expected-ir.d.ts.map

package/dist/__tests__/parity/fixtures/product-config/expected-ir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expected-ir.d.ts","sourceRoot":"","sources":["../../../../../src/__tests__/parity/fixtures/product-config/expected-ir.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,eAAO,MAAM,UAAU,EAAE,oBAyDxB,CAAC"}

package/dist/__tests__/parity/fixtures/product-config/tsdoc.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Parity fixture — product-config — TSDoc class definition.
+ *
+ * Equivalent form definition using a TypeScript class.
+ * Must produce the same provenance-free IR as the chain DSL fixture.
+ *
+ * The `pricing` field uses an anonymous inline object type so the TSDoc
+ * canonicalizer produces an inline ObjectTypeNode (not a ReferenceTypeNode).
+ * A named class or interface would be placed in the type registry and produce
+ * a ReferenceTypeNode, which would diverge from the chain DSL output.
+ *
+ * Field mapping:
+ *   sku:              string (required)  → field.text("sku", { required: true })
+ *   name:             string (required)  → field.text("name", { required: true })
+ *   available:        boolean (optional) → field.boolean("available")
+ *   pricing.basePrice: number (required) → field.number("basePrice", { required: true })
+ *   pricing.currency: string (required)  → field.text("currency", { required: true })
+ */
+export declare class ProductConfigForm {
+    sku: string;
+    name: string;
+    available?: boolean;
+    pricing: {
+        basePrice: number;
+        currency: string;
+    };
+}
+//# sourceMappingURL=tsdoc.d.ts.map

package/dist/__tests__/parity/fixtures/product-config/tsdoc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsdoc.d.ts","sourceRoot":"","sources":["../../../../../src/__tests__/parity/fixtures/product-config/tsdoc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,qBAAa,iBAAiB;IAC5B,GAAG,EAAG,MAAM,CAAC;IACb,IAAI,EAAG,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,EAAG;QACR,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH"}

package/dist/__tests__/parity/fixtures/user-registration/chain-dsl.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Parity fixture — user-registration — chain DSL definition.
+ *
+ * A user registration form with a mix of text, boolean, and enum fields.
+ * No constraints or annotations so the provenance-free IR can be compared
+ * directly with the TSDoc equivalent.
+ *
+ * Uses plain string enum options to match the string literal union type
+ * produced by the TSDoc surface.
+ */
+export declare const userRegistrationForm: import("@formspec/core").FormSpec<readonly [import("@formspec/core").TextField<"email">, import("@formspec/core").TextField<"username">, import("@formspec/core").BooleanField<"agreedToTerms">, import("@formspec/core").StaticEnumField<"accountType", readonly ["personal", "business", "enterprise"]>]>;
+//# sourceMappingURL=chain-dsl.d.ts.map

package/dist/__tests__/parity/fixtures/user-registration/chain-dsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain-dsl.d.ts","sourceRoot":"","sources":["../../../../../src/__tests__/parity/fixtures/user-registration/chain-dsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,eAAO,MAAM,oBAAoB,6SAKhC,CAAC"}

package/dist/__tests__/parity/fixtures/user-registration/expected-ir.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parity fixture — user-registration — expected provenance-free IR.
+ *
+ * This is the canonical shape both the chain DSL and TSDoc surfaces must
+ * produce (after provenance stripping) for the user-registration form.
+ */
+import type { ProvenanceFreeFormIR } from "../../utils.js";
+export declare const expectedIR: ProvenanceFreeFormIR;
+//# sourceMappingURL=expected-ir.d.ts.map

package/dist/__tests__/parity/fixtures/user-registration/expected-ir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expected-ir.d.ts","sourceRoot":"","sources":["../../../../../src/__tests__/parity/fixtures/user-registration/expected-ir.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,eAAO,MAAM,UAAU,EAAE,oBAyCxB,CAAC"}

package/dist/__tests__/parity/fixtures/user-registration/tsdoc.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Parity fixture — user-registration — TSDoc class definition.
+ *
+ * Equivalent form definition using a TypeScript class.
+ * Must produce the same provenance-free IR as the chain DSL fixture.
+ *
+ * Field mapping:
+ *   email:          string (required)                            → field.text("email", { required: true })
+ *   username:       string (required)                            → field.text("username", { required: true })
+ *   agreedToTerms:  boolean (required)                           → field.boolean("agreedToTerms", { required: true })
+ *   accountType:    "personal" | "business" | "enterprise" (req) → field.enum("accountType", [...] as const, { required: true })
+ */
+export declare class UserRegistrationForm {
+    email: string;
+    username: string;
+    agreedToTerms: boolean;
+    accountType: "personal" | "business" | "enterprise";
+}
+//# sourceMappingURL=tsdoc.d.ts.map

package/dist/__tests__/parity/fixtures/user-registration/tsdoc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsdoc.d.ts","sourceRoot":"","sources":["../../../../../src/__tests__/parity/fixtures/user-registration/tsdoc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,qBAAa,oBAAoB;IAC/B,KAAK,EAAG,MAAM,CAAC;IACf,QAAQ,EAAG,MAAM,CAAC;IAClB,aAAa,EAAG,OAAO,CAAC;IACxB,WAAW,EAAG,UAAU,GAAG,UAAU,GAAG,YAAY,CAAC;CACtD"}

package/dist/__tests__/parity/parity.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parity tests.
+ *
+ * Proves that both authoring surfaces (chain DSL and TSDoc/class annotations)
+ * produce identical intermediate representations (IR) for equivalent form
+ * definitions, modulo provenance metadata.
+ *
+ * Three-test pattern per fixture:
+ *   1. Chain DSL → IR matches expected IR
+ *   2. TSDoc class → IR matches expected IR
+ *   3. Chain DSL IR === TSDoc IR (modulo provenance)
+ */
+export {};
+//# sourceMappingURL=parity.test.d.ts.map

package/dist/__tests__/parity/parity.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parity.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/parity/parity.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/__tests__/parity/utils.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Parity testing utilities.
+ *
+ * Provides:
+ * - `ProvenanceFree<T>` — type-level mapper that strips `provenance` fields from IR nodes
+ * - `stripProvenance(ir)` — runtime equivalent for `FormIR`
+ * - `compareIR(a, b)` — structured IR comparison after stripping provenance
+ *
+ * `ProvenanceFree<T>` is implemented as explicit per-type mapped interfaces rather
+ * than a generic deep-recursive mapped type. This keeps the type system's structural
+ * guarantees intact: if an IR node gains or loses a field, the provenance-free variants
+ * here will fail to compile, catching shape regressions at type-check time.
+ */
+import type { FormIR, FormIRElement, PrimitiveTypeNode, EnumMember, DynamicTypeNode, CustomTypeNode, NumericConstraintNode, LengthConstraintNode, PatternConstraintNode, ArrayCardinalityConstraintNode, EnumMemberConstraintNode, CustomConstraintNode, DisplayNameAnnotationNode, DescriptionAnnotationNode, PlaceholderAnnotationNode, DefaultValueAnnotationNode, DeprecatedAnnotationNode, FormatHintAnnotationNode, CustomAnnotationNode, JsonValue } from "@formspec/core";
+/** Primitive type node has no `provenance` field — pass through unchanged. */
+export type ProvenanceFreePrimitiveTypeNode = PrimitiveTypeNode;
+/** Enum member has no `provenance` field. */
+export type ProvenanceFreeEnumMember = EnumMember;
+/** Enum type node has no `provenance` field. */
+export interface ProvenanceFreeEnumTypeNode {
+    readonly kind: "enum";
+    readonly members: readonly ProvenanceFreeEnumMember[];
+}
+/** Array type node — items type is recursively provenance-free. */
+export interface ProvenanceFreeArrayTypeNode {
+    readonly kind: "array";
+    readonly items: ProvenanceFreeTypeNode;
+}
+/** Object property with `provenance` stripped and nested types recursively mapped. */
+export interface ProvenanceFreeObjectProperty {
+    readonly name: string;
+    readonly type: ProvenanceFreeTypeNode;
+    readonly optional: boolean;
+    readonly constraints: readonly ProvenanceFreeConstraintNode[];
+    readonly annotations: readonly ProvenanceFreeAnnotationNode[];
+}
+/** Object type node — properties are recursively provenance-free. */
+export interface ProvenanceFreeObjectTypeNode {
+    readonly kind: "object";
+    readonly properties: readonly ProvenanceFreeObjectProperty[];
+    readonly additionalProperties: boolean;
+}
+/** Union type node — members are recursively provenance-free. */
+export interface ProvenanceFreeUnionTypeNode {
+    readonly kind: "union";
+    readonly members: readonly ProvenanceFreeTypeNode[];
+}
+/** Reference type node — type arguments are recursively provenance-free. */
+export interface ProvenanceFreeReferenceTypeNode {
+    readonly kind: "reference";
+    readonly name: string;
+    readonly typeArguments: readonly ProvenanceFreeTypeNode[];
+}
+/** Dynamic type node has no `provenance` field — pass through unchanged. */
+export type ProvenanceFreeDynamicTypeNode = DynamicTypeNode;
+/** Custom type node has no `provenance` field — pass through unchanged. */
+export type ProvenanceFreeCustomTypeNode = CustomTypeNode;
+/** Union of all provenance-free type node variants. */
+export type ProvenanceFreeTypeNode = ProvenanceFreePrimitiveTypeNode | ProvenanceFreeEnumTypeNode | ProvenanceFreeArrayTypeNode | ProvenanceFreeObjectTypeNode | ProvenanceFreeUnionTypeNode | ProvenanceFreeReferenceTypeNode | ProvenanceFreeDynamicTypeNode | ProvenanceFreeCustomTypeNode;
+export type ProvenanceFreeNumericConstraintNode = Omit<NumericConstraintNode, "provenance">;
+export type ProvenanceFreeLengthConstraintNode = Omit<LengthConstraintNode, "provenance">;
+export type ProvenanceFreePatternConstraintNode = Omit<PatternConstraintNode, "provenance">;
+export type ProvenanceFreeArrayCardinalityConstraintNode = Omit<ArrayCardinalityConstraintNode, "provenance">;
+export type ProvenanceFreeEnumMemberConstraintNode = Omit<EnumMemberConstraintNode, "provenance">;
+export type ProvenanceFreeCustomConstraintNode = Omit<CustomConstraintNode, "provenance">;
+export type ProvenanceFreeConstraintNode = ProvenanceFreeNumericConstraintNode | ProvenanceFreeLengthConstraintNode | ProvenanceFreePatternConstraintNode | ProvenanceFreeArrayCardinalityConstraintNode | ProvenanceFreeEnumMemberConstraintNode | ProvenanceFreeCustomConstraintNode;
+export type ProvenanceFreeDisplayNameAnnotationNode = Omit<DisplayNameAnnotationNode, "provenance">;
+export type ProvenanceFreeDescriptionAnnotationNode = Omit<DescriptionAnnotationNode, "provenance">;
+export type ProvenanceFreePlaceholderAnnotationNode = Omit<PlaceholderAnnotationNode, "provenance">;
+export type ProvenanceFreeDefaultValueAnnotationNode = Omit<DefaultValueAnnotationNode, "provenance">;
+export type ProvenanceFreeDeprecatedAnnotationNode = Omit<DeprecatedAnnotationNode, "provenance">;
+export type ProvenanceFreeFormatHintAnnotationNode = Omit<FormatHintAnnotationNode, "provenance">;
+export type ProvenanceFreeCustomAnnotationNode = Omit<CustomAnnotationNode, "provenance">;
+export type ProvenanceFreeAnnotationNode = ProvenanceFreeDisplayNameAnnotationNode | ProvenanceFreeDescriptionAnnotationNode | ProvenanceFreePlaceholderAnnotationNode | ProvenanceFreeDefaultValueAnnotationNode | ProvenanceFreeDeprecatedAnnotationNode | ProvenanceFreeFormatHintAnnotationNode | ProvenanceFreeCustomAnnotationNode;
+/** Field node with `provenance` and `mergeHistory` stripped; nested structures recursively mapped. */
+export interface ProvenanceFreeFieldNode {
+    readonly kind: "field";
+    readonly name: string;
+    readonly type: ProvenanceFreeTypeNode;
+    readonly required: boolean;
+    readonly constraints: readonly ProvenanceFreeConstraintNode[];
+    readonly annotations: readonly ProvenanceFreeAnnotationNode[];
+}
+/** Group layout node with `provenance` stripped; elements are recursively mapped. */
+export interface ProvenanceFreeGroupLayoutNode {
+    readonly kind: "group";
+    readonly label: string;
+    readonly elements: readonly ProvenanceFreeFormIRElement[];
+}
+/** Conditional layout node with `provenance` stripped. */
+export interface ProvenanceFreeConditionalLayoutNode {
+    readonly kind: "conditional";
+    readonly fieldName: string;
+    readonly value: JsonValue;
+    readonly elements: readonly ProvenanceFreeFormIRElement[];
+}
+/** Union of all provenance-free IR element types. */
+export type ProvenanceFreeFormIRElement = ProvenanceFreeFieldNode | ProvenanceFreeGroupLayoutNode | ProvenanceFreeConditionalLayoutNode;
+/** TypeDefinition with `provenance` stripped. */
+export interface ProvenanceFreeTypeDefinition {
+    readonly name: string;
+    readonly type: ProvenanceFreeTypeNode;
+}
+/** The top-level `FormIR` with all `provenance` fields stripped. */
+export interface ProvenanceFreeFormIR {
+    readonly kind: "form-ir";
+    readonly irVersion: string;
+    readonly elements: readonly ProvenanceFreeFormIRElement[];
+    readonly typeRegistry: Record<string, ProvenanceFreeTypeDefinition>;
+}
+/**
+ * A structured description of a single difference between two IR trees.
+ * Path uses dot notation for object properties and `[n]` for array indices.
+ */
+export interface IRDifference {
+    /** JSONPath-like string describing where the difference is located. */
+    readonly path: string;
+    readonly expected: unknown;
+    readonly actual: unknown;
+}
+/**
+ * Strips all `provenance` (and `mergeHistory`) fields from a `FormIRElement`,
+ * returning a `ProvenanceFreeFormIRElement`.
+ */
+export declare function stripProvenanceFromElement(element: FormIRElement): ProvenanceFreeFormIRElement;
+/**
+ * Strips all `provenance` and `mergeHistory` fields from a complete `FormIR`,
+ * returning a `ProvenanceFreeFormIR` suitable for structural comparison.
+ */
+export declare function stripProvenance(ir: FormIR): ProvenanceFreeFormIR;
+/**
+ * Compares two `FormIR` objects structurally after stripping provenance.
+ *
+ * Returns an empty array when the IRs are identical modulo provenance.
+ * Returns one `IRDifference` per divergence found, with a JSONPath-like
+ * path string indicating where the difference occurs.
+ */
+export declare function compareIR(a: FormIR, b: FormIR): IRDifference[];
+//# sourceMappingURL=utils.d.ts.map

package/dist/__tests__/parity/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/__tests__/parity/utils.ts"],"names":[],"mappings":"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"}