@formspec/build 0.1.0-alpha.31 → 0.1.0-alpha.33

package/README.md

@@ -19,11 +19,11 @@ Most app code can use `formspec`, but use `@formspec/build` directly when you ne
 
 ## Public Entry Points
 
-| Entry point                 | Purpose                                |
-| --------------------------- | -------------------------------------- |
-| `@formspec/build`           | Public build APIs                      |
-| `@formspec/build/browser`   | Browser-safe chain-DSL and IR surface  |
-| `@formspec/build/internals` | Unstable low-level IR/analyzer APIs    |
+| Entry point                 | Purpose                               |
+| --------------------------- | ------------------------------------- |
+| `@formspec/build`           | Public build APIs                     |
+| `@formspec/build/browser`   | Browser-safe chain-DSL and IR surface |
+| `@formspec/build/internals` | Unstable low-level IR/analyzer APIs   |
 
 ## Chain DSL Generation
 
@@ -63,6 +63,83 @@ const result = generateSchemasFromClass({
 });
 ```
 
+### Static Build Context
+
+Use the static build context APIs when you need to inspect exports, declarations,
+or method signatures before deciding what schemas to generate.
+
+Public helpers in this workflow:
+
+- `createStaticBuildContext(filePath)` - Create a reusable compiler-backed context from a file.
+- `createStaticBuildContextFromProgram(program, filePath)` - Reuse a host-owned `ts.Program`.
+- `resolveModuleExport(context, exportName?)` - Resolve any exported symbol, including functions and other non-schema declarations.
+- `resolveModuleExportDeclaration(context, exportName?)` - Resolve only schema-source declarations (`class`, `interface`, `type` alias).
+- `generateSchemasFromDeclaration(...)` - Generate from a resolved schema-source declaration.
+- `generateSchemasFromParameter(...)` - Generate from a method or function parameter declaration.
+- `generateSchemasFromReturnType(...)` - Generate from a method or function return type.
+- `generateSchemasFromType(...)` - Generate directly from a resolved `ts.Type`.
+
+Use `resolveModuleExportDeclaration(...)` when your tooling wants to hand a resolved
+declaration straight to `generateSchemasFromDeclaration(...)`. Use `resolveModuleExport(...)`
+when you need lower-level TypeScript access first, for example to inspect a function
+export and then generate schemas from one of its signature types.
+
+```ts
+import * as ts from "typescript";
+import {
+  createStaticBuildContext,
+  generateSchemasFromDeclaration,
+  generateSchemasFromParameter,
+  generateSchemasFromReturnType,
+  resolveModuleExport,
+  resolveModuleExportDeclaration,
+} from "@formspec/build";
+
+const context = createStaticBuildContext("./src/service.ts");
+const serviceDeclaration = resolveModuleExportDeclaration(context, "PaymentService");
+
+if (serviceDeclaration && ts.isClassDeclaration(serviceDeclaration)) {
+  const submitMethod = serviceDeclaration.members.find(
+    (member): member is ts.MethodDeclaration =>
+      ts.isMethodDeclaration(member) &&
+      ts.isIdentifier(member.name) &&
+      member.name.text === "submit"
+  );
+
+  if (submitMethod?.parameters[0]) {
+    const inputSchemas = generateSchemasFromParameter({
+      context,
+      parameter: submitMethod.parameters[0],
+    });
+  }
+}
+
+const inputDeclaration = resolveModuleExportDeclaration(context, "SubmitInput");
+if (inputDeclaration) {
+  const inputSchemas = generateSchemasFromDeclaration({
+    context,
+    declaration: inputDeclaration,
+  });
+}
+
+const paymentSymbol = resolveModuleExport(context, "submitPayment");
+const paymentDeclaration = paymentSymbol?.declarations?.find(ts.isFunctionDeclaration);
+if (paymentDeclaration) {
+  const outputSchemas = generateSchemasFromReturnType({
+    context,
+    declaration: paymentDeclaration,
+  });
+}
+```
+
+If you already own a `ts.Program`, use `createStaticBuildContextFromProgram(program, filePath)`
+instead of letting FormSpec create one. If your tool has already resolved a raw
+`ts.Type` or signature declaration, use `generateSchemasFromType(...)` or
+`generateSchemasFromReturnType(...)` directly.
+
+This is the supported public path for build-time analysis workflows that used to
+require `@formspec/build/internals`.
+
 ### Supported TSDoc Examples
 
 ```ts

package/dist/analyzer/class-analyzer.d.ts

@@ -57,7 +57,17 @@ export type AnalyzeTypeAliasToIRResult = {
     readonly ok: false;
     readonly error: string;
 };
-type AnalyzerMetadataPolicy = ReturnType<typeof normalizeMetadataPolicy>;
+export interface DeclarationRootInfo {
+    readonly metadata?: ResolvedMetadata;
+    readonly annotations: readonly AnnotationNode[];
+    readonly diagnostics: readonly ConstraintSemanticDiagnostic[];
+}
+interface AnalyzerMetadataPolicy {
+    readonly raw: MetadataPolicyInput | undefined;
+    readonly normalized: ReturnType<typeof normalizeMetadataPolicy>;
+}
+export declare function createAnalyzerMetadataPolicy(input?: MetadataPolicyInput): AnalyzerMetadataPolicy;
+export declare function analyzeDeclarationRootInfo(declaration: ts.ClassDeclaration | ts.InterfaceDeclaration | ts.TypeAliasDeclaration, checker: ts.TypeChecker, file?: string, extensionRegistry?: ExtensionRegistry, metadataPolicy?: MetadataPolicyInput): DeclarationRootInfo;
 /**
  * Analyzes a class declaration and produces canonical IR FieldNodes.
  */

package/dist/analyzer/class-analyzer.d.ts.map

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

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

@@ -14,9 +14,12 @@
  *    — Parsed via TSDocParser as custom block tags.
  *    Both camelCase and PascalCase forms are accepted (e.g., `@Minimum`).
  *
- * 2. **Annotation tags** (`@displayName`, `@format`, `@placeholder`):
- *    These are parsed as structured custom block tags and mapped directly
- *    onto annotation IR nodes.
+ * 2. **Metadata and annotation tags** (`@apiName`, `@displayName`,
+ *    `@format`, `@placeholder`):
+ *    These are parsed as structured custom block tags so summary extraction
+ *    stops at recognized FormSpec tags. `@displayName`, `@format`, and
+ *    `@placeholder` also map onto annotation IR nodes, while `@apiName`
+ *    remains metadata-only and is resolved separately by the class analyzer.
  *
  * The `@deprecated` tag is a standard TSDoc block tag, parsed structurally.
  *

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,EAaL,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;AAqjBhE;;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;AA4CD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,IAAI,SAAK,EACT,OAAO,CAAC,EAAE,iBAAiB,GAC1B,gBAAgB,CAiSlB;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;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"}

package/dist/browser.cjs

@@ -1594,13 +1594,29 @@ function getSchemaExtension(schema, key) {
 }
 
 // src/extensions/registry.ts
+var import_internals3 = require("@formspec/core/internals");
+var import_internal = require("@formspec/analysis/internal");
+var BUILTIN_METADATA_TAGS = /* @__PURE__ */ new Set(["apiName", "displayName"]);
+function buildConstraintTagSources(extensions) {
+  return extensions.map((extension) => ({
+    extensionId: extension.extensionId,
+    ...extension.constraintTags !== void 0 ? {
+      constraintTags: extension.constraintTags.map((tag) => ({
+        tagName: (0, import_internal.normalizeFormSpecTagName)(tag.tagName)
+      }))
+    } : {}
+  }));
+}
 function createExtensionRegistry(extensions) {
+  const reservedTagSources = buildConstraintTagSources(extensions);
   const typeMap = /* @__PURE__ */ new Map();
   const typeNameMap = /* @__PURE__ */ new Map();
   const constraintMap = /* @__PURE__ */ new Map();
   const constraintTagMap = /* @__PURE__ */ new Map();
   const builtinBroadeningMap = /* @__PURE__ */ new Map();
   const annotationMap = /* @__PURE__ */ new Map();
+  const metadataSlotMap = /* @__PURE__ */ new Map();
+  const metadataTagMap = /* @__PURE__ */ new Map();
   for (const ext of extensions) {
     if (ext.types !== void 0) {
       for (const type of ext.types) {
@@ -1643,10 +1659,11 @@ function createExtensionRegistry(extensions) {
     }
     if (ext.constraintTags !== void 0) {
       for (const tag of ext.constraintTags) {
-        if (constraintTagMap.has(tag.tagName)) {
-          throw new Error(`Duplicate custom constraint tag: "@${tag.tagName}"`);
+        const canonicalTagName = (0, import_internal.normalizeFormSpecTagName)(tag.tagName);
+        if (constraintTagMap.has(canonicalTagName)) {
+          throw new Error(`Duplicate custom constraint tag: "@${canonicalTagName}"`);
         }
-        constraintTagMap.set(tag.tagName, {
+        constraintTagMap.set(canonicalTagName, {
           extensionId: ext.extensionId,
           registration: tag
         });
@@ -1661,13 +1678,54 @@ function createExtensionRegistry(extensions) {
         annotationMap.set(qualifiedId, annotation);
       }
     }
+    if (ext.metadataSlots !== void 0) {
+      for (const slot of ext.metadataSlots) {
+        if (metadataSlotMap.has(slot.slotId)) {
+          throw new Error(`Duplicate metadata slot ID: "${slot.slotId}"`);
+        }
+        metadataSlotMap.set(slot.slotId, true);
+        const canonicalTagName = (0, import_internal.normalizeFormSpecTagName)(slot.tagName);
+        if (slot.allowBare === false && (slot.qualifiers?.length ?? 0) === 0) {
+          throw new Error(
+            `Metadata tag "@${canonicalTagName}" must allow bare usage or declare at least one qualifier.`
+          );
+        }
+        if (metadataTagMap.has(canonicalTagName)) {
+          throw new Error(`Duplicate metadata tag: "@${canonicalTagName}"`);
+        }
+        if (BUILTIN_METADATA_TAGS.has(canonicalTagName)) {
+          throw new Error(
+            `Metadata tag "@${canonicalTagName}" conflicts with built-in metadata tags.`
+          );
+        }
+        if (constraintTagMap.has(canonicalTagName)) {
+          throw new Error(
+            `Metadata tag "@${canonicalTagName}" conflicts with existing FormSpec tag "@${canonicalTagName}".`
+          );
+        }
+        if (Object.hasOwn(import_internals3.BUILTIN_CONSTRAINT_DEFINITIONS, (0, import_internals3.normalizeConstraintTagName)(canonicalTagName))) {
+          throw new Error(
+            `Metadata tag "@${canonicalTagName}" conflicts with existing FormSpec tag "@${(0, import_internals3.normalizeConstraintTagName)(canonicalTagName)}".`
+          );
+        }
+        const existingTag = (0, import_internal.getTagDefinition)(canonicalTagName, reservedTagSources);
+        if (existingTag !== null) {
+          throw BUILTIN_METADATA_TAGS.has(existingTag.canonicalName) ? new Error(
+            `Metadata tag "@${canonicalTagName}" conflicts with built-in metadata tags.`
+          ) : new Error(
+            `Metadata tag "@${canonicalTagName}" conflicts with existing FormSpec tag "@${existingTag.canonicalName}".`
+          );
+        }
+        metadataTagMap.set(canonicalTagName, true);
+      }
+    }
   }
   return {
     extensions,
     findType: (typeId) => typeMap.get(typeId),
     findTypeByName: (typeName) => typeNameMap.get(typeName),
     findConstraint: (constraintId) => constraintMap.get(constraintId),
-    findConstraintTag: (tagName) => constraintTagMap.get(tagName),
+    findConstraintTag: (tagName) => constraintTagMap.get((0, import_internal.normalizeFormSpecTagName)(tagName)),
     findBuiltinConstraintBroadening: (typeId, tagName) => builtinBroadeningMap.get(`${typeId}:${tagName}`),
     findAnnotation: (annotationId) => annotationMap.get(annotationId)
   };
@@ -1736,9 +1794,9 @@ var jsonSchema7Schema = import_zod3.z.lazy(
 );
 
 // src/validate/constraint-validator.ts
-var import_internal = require("@formspec/analysis/internal");
+var import_internal2 = require("@formspec/analysis/internal");
 function validateFieldNode(ctx, field) {
-  const analysis = (0, import_internal.analyzeConstraintTargets)(
+  const analysis = (0, import_internal2.analyzeConstraintTargets)(
     field.name,
     field.type,
     field.constraints,
@@ -1756,7 +1814,7 @@ function validateFieldNode(ctx, field) {
 }
 function validateObjectProperty(ctx, parentName, property) {
   const qualifiedName = `${parentName}.${property.name}`;
-  const analysis = (0, import_internal.analyzeConstraintTargets)(
+  const analysis = (0, import_internal2.analyzeConstraintTargets)(
     qualifiedName,
     property.type,
     property.constraints,