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

package/README.md

@@ -74,6 +74,7 @@ Public helpers in this workflow:
 - `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).
+- `resolveDeclarationMetadata(...)` - Resolve metadata for named types, methods, and properties using FormSpec's active metadata policy.
 - `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, unwrapping awaited `Promise<T>`-style returns before generation.
@@ -91,6 +92,7 @@ import {
   generateSchemasFromDeclaration,
   generateSchemasFromParameter,
   generateSchemasFromReturnType,
+  resolveDeclarationMetadata,
   resolveModuleExport,
   resolveModuleExportDeclaration,
 } from "@formspec/build";
@@ -107,6 +109,10 @@ if (serviceDeclaration && ts.isClassDeclaration(serviceDeclaration)) {
   );
 
   if (submitMethod?.parameters[0]) {
+    const methodMetadata = resolveDeclarationMetadata({
+      context,
+      declaration: submitMethod,
+    });
     const inputSchemas = generateSchemasFromParameter({
       context,
       parameter: submitMethod.parameters[0],

package/dist/build-alpha.d.ts

@@ -1086,6 +1086,17 @@ export declare interface LabelElement {
     readonly [k: string]: unknown;
 }
 
+/**
+ * Supported declaration kinds for standalone metadata resolution.
+ *
+ * This helper is intentionally limited to named type declarations,
+ * methods/functions, and object-like properties. It does not currently expose
+ * parameter or variable metadata resolution on the public build surface.
+ *
+ * @public
+ */
+export declare type MetadataSourceDeclaration = SchemaSourceDeclaration | ts.MethodDeclaration | ts.FunctionDeclaration | ts.PropertyDeclaration | ts.PropertySignature;
+
 /**
  * Result of generating schemas from a mixed-authoring composition.
  *
@@ -1102,6 +1113,27 @@ export { NumberField }
 
 export { ObjectField }
 
+/**
+ * Resolves metadata from a declaration using FormSpec's configured metadata
+ * policy for the matching declaration kind.
+ *
+ * @public
+ */
+export declare function resolveDeclarationMetadata(options: ResolveDeclarationMetadataOptions): ResolvedMetadata | undefined;
+
+/**
+ * Options for resolving metadata from a declaration against the active
+ * metadata policy.
+ *
+ * @public
+ */
+export declare interface ResolveDeclarationMetadataOptions extends StaticSchemaGenerationOptions {
+    /** Supported build context used for checker access and related analysis. */
+    readonly context: StaticBuildContext;
+    /** Declaration whose metadata should be resolved. */
+    readonly declaration: MetadataSourceDeclaration;
+}
+
 /**
  * Resolves an export from the context source file, following aliases and re-exports.
  *

package/dist/build-beta.d.ts

@@ -1086,6 +1086,17 @@ export declare interface LabelElement {
     readonly [k: string]: unknown;
 }
 
+/**
+ * Supported declaration kinds for standalone metadata resolution.
+ *
+ * This helper is intentionally limited to named type declarations,
+ * methods/functions, and object-like properties. It does not currently expose
+ * parameter or variable metadata resolution on the public build surface.
+ *
+ * @public
+ */
+export declare type MetadataSourceDeclaration = SchemaSourceDeclaration | ts.MethodDeclaration | ts.FunctionDeclaration | ts.PropertyDeclaration | ts.PropertySignature;
+
 /**
  * Result of generating schemas from a mixed-authoring composition.
  *
@@ -1102,6 +1113,27 @@ export { NumberField }
 
 export { ObjectField }
 
+/**
+ * Resolves metadata from a declaration using FormSpec's configured metadata
+ * policy for the matching declaration kind.
+ *
+ * @public
+ */
+export declare function resolveDeclarationMetadata(options: ResolveDeclarationMetadataOptions): ResolvedMetadata | undefined;
+
+/**
+ * Options for resolving metadata from a declaration against the active
+ * metadata policy.
+ *
+ * @public
+ */
+export declare interface ResolveDeclarationMetadataOptions extends StaticSchemaGenerationOptions {
+    /** Supported build context used for checker access and related analysis. */
+    readonly context: StaticBuildContext;
+    /** Declaration whose metadata should be resolved. */
+    readonly declaration: MetadataSourceDeclaration;
+}
+
 /**
  * Resolves an export from the context source file, following aliases and re-exports.
  *

package/dist/build-internal.d.ts

@@ -1086,6 +1086,17 @@ export declare interface LabelElement {
     readonly [k: string]: unknown;
 }
 
+/**
+ * Supported declaration kinds for standalone metadata resolution.
+ *
+ * This helper is intentionally limited to named type declarations,
+ * methods/functions, and object-like properties. It does not currently expose
+ * parameter or variable metadata resolution on the public build surface.
+ *
+ * @public
+ */
+export declare type MetadataSourceDeclaration = SchemaSourceDeclaration | ts.MethodDeclaration | ts.FunctionDeclaration | ts.PropertyDeclaration | ts.PropertySignature;
+
 /**
  * Result of generating schemas from a mixed-authoring composition.
  *
@@ -1102,6 +1113,27 @@ export { NumberField }
 
 export { ObjectField }
 
+/**
+ * Resolves metadata from a declaration using FormSpec's configured metadata
+ * policy for the matching declaration kind.
+ *
+ * @public
+ */
+export declare function resolveDeclarationMetadata(options: ResolveDeclarationMetadataOptions): ResolvedMetadata | undefined;
+
+/**
+ * Options for resolving metadata from a declaration against the active
+ * metadata policy.
+ *
+ * @public
+ */
+export declare interface ResolveDeclarationMetadataOptions extends StaticSchemaGenerationOptions {
+    /** Supported build context used for checker access and related analysis. */
+    readonly context: StaticBuildContext;
+    /** Declaration whose metadata should be resolved. */
+    readonly declaration: MetadataSourceDeclaration;
+}
+
 /**
  * Resolves an export from the context source file, following aliases and re-exports.
  *

package/dist/build.d.ts

@@ -1086,6 +1086,17 @@ export declare interface LabelElement {
     readonly [k: string]: unknown;
 }
 
+/**
+ * Supported declaration kinds for standalone metadata resolution.
+ *
+ * This helper is intentionally limited to named type declarations,
+ * methods/functions, and object-like properties. It does not currently expose
+ * parameter or variable metadata resolution on the public build surface.
+ *
+ * @public
+ */
+export declare type MetadataSourceDeclaration = SchemaSourceDeclaration | ts.MethodDeclaration | ts.FunctionDeclaration | ts.PropertyDeclaration | ts.PropertySignature;
+
 /**
  * Result of generating schemas from a mixed-authoring composition.
  *
@@ -1102,6 +1113,27 @@ export { NumberField }
 
 export { ObjectField }
 
+/**
+ * Resolves metadata from a declaration using FormSpec's configured metadata
+ * policy for the matching declaration kind.
+ *
+ * @public
+ */
+export declare function resolveDeclarationMetadata(options: ResolveDeclarationMetadataOptions): ResolvedMetadata | undefined;
+
+/**
+ * Options for resolving metadata from a declaration against the active
+ * metadata policy.
+ *
+ * @public
+ */
+export declare interface ResolveDeclarationMetadataOptions extends StaticSchemaGenerationOptions {
+    /** Supported build context used for checker access and related analysis. */
+    readonly context: StaticBuildContext;
+    /** Declaration whose metadata should be resolved. */
+    readonly declaration: MetadataSourceDeclaration;
+}
+
 /**
  * Resolves an export from the context source file, following aliases and re-exports.
  *

package/dist/cli.cjs

@@ -5875,6 +5875,32 @@ function omitApiName(metadata) {
   const { apiName: _apiName, ...rest } = metadata;
   return Object.keys(rest).length > 0 ? rest : void 0;
 }
+function enforceRequiredMetadata(metadata, declarationKind, logicalName, options) {
+  const declarationPolicy = getDeclarationMetadataPolicy(
+    normalizeMetadataPolicy(options.metadata),
+    declarationKind
+  );
+  if (metadata?.apiName === void 0 && declarationPolicy.apiName.mode === "require-explicit") {
+    throw new Error(
+      `Metadata policy requires explicit apiName for ${declarationKind} "${logicalName}" on the tsdoc surface.`
+    );
+  }
+  if (metadata?.displayName === void 0 && declarationPolicy.displayName.mode === "require-explicit") {
+    throw new Error(
+      `Metadata policy requires explicit displayName for ${declarationKind} "${logicalName}" on the tsdoc surface.`
+    );
+  }
+  if (metadata?.apiNamePlural === void 0 && declarationPolicy.apiName.pluralization.mode === "require-explicit") {
+    throw new Error(
+      `Metadata policy requires explicit apiNamePlural for ${declarationKind} "${logicalName}" on the tsdoc surface.`
+    );
+  }
+  if (metadata?.displayNamePlural === void 0 && declarationPolicy.displayName.pluralization.mode === "require-explicit") {
+    throw new Error(
+      `Metadata policy requires explicit displayNamePlural for ${declarationKind} "${logicalName}" on the tsdoc surface.`
+    );
+  }
+}
 function describeRootType(rootType, typeRegistry, fallbackName) {
   if (rootType.kind !== "reference") {
     return {
@@ -6115,6 +6141,21 @@ function generateSchemasFromReturnType(options) {
     name: fallbackName
   });
 }
+function resolveDeclarationMetadata(options) {
+  const analysis = (0, import_internal5.analyzeMetadataForNodeWithChecker)({
+    checker: options.context.checker,
+    node: options.declaration,
+    metadata: options.metadata,
+    extensions: options.extensionRegistry?.extensions,
+    buildContext: options.context
+  });
+  if (analysis === null) {
+    return void 0;
+  }
+  const metadata = analysis.resolvedMetadata;
+  enforceRequiredMetadata(metadata, analysis.declarationKind, analysis.logicalName, options);
+  return metadata;
+}
 function unwrapPromiseType(checker, type) {
   if (!("getAwaitedType" in checker) || typeof checker.getAwaitedType !== "function") {
     return type;
@@ -6134,11 +6175,12 @@ function unwrapPromiseTypeNode(typeNode) {
 function isPromiseTypeReferenceNode(typeNode) {
   return ts7.isTypeReferenceNode(typeNode) && ts7.isIdentifier(typeNode.typeName) && typeNode.typeName.text === "Promise" && typeNode.typeArguments !== void 0 && typeNode.typeArguments.length > 0;
 }
-var ts7, import_internals6;
+var ts7, import_internal5, import_internals6;
 var init_discovered_schema = __esm({
   "src/generators/discovered-schema.ts"() {
     "use strict";
     ts7 = __toESM(require("typescript"), 1);
+    import_internal5 = require("@formspec/analysis/internal");
     init_class_analyzer();
     init_class_schema();
     init_ir_generator();
@@ -6370,6 +6412,7 @@ __export(index_exports, {
   generateSchemasFromType: () => generateSchemasFromType,
   generateUiSchema: () => generateUiSchema,
   jsonSchema7Schema: () => jsonSchema7Schema,
+  resolveDeclarationMetadata: () => resolveDeclarationMetadata,
   resolveModuleExport: () => resolveModuleExport,
   resolveModuleExportDeclaration: () => resolveModuleExportDeclaration,
   uiSchemaSchema: () => uiSchema,