Maintain "behavior" meta-data in specification (#2638)

Author: flobernd

compiler/src/model/build-model.ts

@@ -459,7 +459,8 @@ function compileClassOrInterfaceDeclaration (declaration: ClassDeclaration | Int
       properties: new Array<model.Property>()
     }
 
-    hoistTypeAnnotations(type, declaration.getJsDocs())
+    const jsDocs = declaration.getJsDocs()
+    hoistTypeAnnotations(type, jsDocs)
 
     const variant = parseVariantNameTag(declaration.getJsDocs())
     if (typeof variant === 'string') {
@@ -532,7 +533,7 @@ function compileClassOrInterfaceDeclaration (declaration: ClassDeclaration | Int
     if (Node.isClassDeclaration(declaration)) {
       for (const implement of declaration.getImplements()) {
         if (isKnownBehavior(implement)) {
-          type.behaviors = (type.behaviors ?? []).concat(modelBehaviors(implement))
+          type.behaviors = (type.behaviors ?? []).concat(modelBehaviors(implement, jsDocs))
         } else {
           type.implements = (type.implements ?? []).concat(modelImplements(implement))
         }

compiler/src/model/metamodel.ts

@@ -215,6 +215,12 @@ export class Inherits {
   generics?: ValueOf[]
 }
 
+export class Behavior {
+  type: TypeName
+  generics?: ValueOf[]
+  meta?: { [p: string]: string }
+}
+
 /**
  * An interface type
  */
@@ -231,7 +237,7 @@ export class Interface extends BaseType {
   /**
    * Behaviors directly implemented by this interface
    */
-  behaviors?: Inherits[]
+  behaviors?: Behavior[]
 
   /**
    * Behaviors attached to this interface, coming from the interface itself (see `behaviors`)
@@ -275,7 +281,7 @@ export class Request extends BaseType {
    * that don't have a body.
    */
   body: Body
-  behaviors?: Inherits[]
+  behaviors?: Behavior[]
   attachedBehaviors?: string[]
 }
 
@@ -286,7 +292,7 @@ export class Response extends BaseType {
   kind: 'response'
   generics?: TypeName[]
   body: Body
-  behaviors?: Inherits[]
+  behaviors?: Behavior[]
   attachedBehaviors?: string[]
   exceptions?: ResponseException[]
 }

compiler/src/model/utils.ts

@@ -414,14 +414,40 @@ export function modelImplements (node: ExpressionWithTypeArguments): model.Inher
  * A class could have multiple behaviors from multiple classes,
  * which are defined inside the node typeArguments.
  */
-export function modelBehaviors (node: ExpressionWithTypeArguments): model.Inherits {
+export function modelBehaviors (node: ExpressionWithTypeArguments, jsDocs: JSDoc[]): model.Behavior {
+  const behaviorName = node.getExpression().getText()
   const generics = node.getTypeArguments().map(node => modelType(node))
+
+  let meta: Map<string, string> | undefined
+  const tags = parseJsDocTagsAllowDuplicates(jsDocs)
+  if (tags.behavior_meta !== undefined) {
+    // Extracts whitespace/comma-separated key-value-pairs with a "=" delimiter and handles double-quotes
+    const re = /(?<key>[^=\s,]+)=(?<value>"([^"]*)"|([^\s,]+))/g
+
+    for (const tag of tags.behavior_meta) {
+      const id = tag.split(' ')
+      if (id[0].trim() !== behaviorName) {
+        continue
+      }
+      const matches = [...id.slice(1).join(' ').matchAll(re)]
+      meta = new Map<string, string>()
+      for (const match of matches) {
+        if (match.groups == null) {
+          continue
+        }
+        meta.set(match.groups.key, match.groups.value.replace(/^"(.+(?="$))"$/, '$1'))
+      }
+      break
+    }
+  }
+
   return {
     type: {
-      name: node.getExpression().getText(),
+      name: behaviorName,
       namespace: getNameSpace(node)
     },
-    ...(generics.length > 0 && { generics })
+    ...(generics.length > 0 && { generics }),
+    meta: (meta === undefined) ? undefined : Object.fromEntries(meta)
   }
 }
 
@@ -579,7 +605,7 @@ function setTags<TType extends model.BaseType | model.Property | model.EnumMembe
   )
 
   for (const tag of validTags) {
-    if (tag === 'behavior') continue
+    if (tag === 'behavior' || tag === 'behavior_meta') continue
     if (tags[tag] !== undefined) {
       setter(tags, tag, tags[tag])
     }
@@ -700,7 +726,7 @@ export function hoistTypeAnnotations (type: model.TypeDefinition, jsDocs: JSDoc[
   assert(jsDocs, jsDocs.length < 2, 'Use a single multiline jsDoc block instead of multiple single line blocks')
 
   const validTags = ['class_serializer', 'doc_url', 'doc_id', 'behavior', 'variants', 'variant', 'shortcut_property',
-    'codegen_names', 'non_exhaustive', 'es_quirk']
+    'codegen_names', 'non_exhaustive', 'es_quirk', 'behavior_meta']
   const tags = parseJsDocTags(jsDocs)
   if (jsDocs.length === 1) {
     const description = jsDocs[0].getDescription()

compiler/src/steps/validate-model.ts

@@ -643,6 +643,13 @@ export default async function validateModel (apiModel: model.Model, restSpec: Ma
       context.push('Behaviors')
       for (const parent of typeDef.behaviors) {
         validateTypeRef(parent.type, parent.generics, openGenerics)
+
+        if (parent.type.name === 'AdditionalProperty' && (parent.meta == null || parent.meta.key == null || parent.meta.value == null)) {
+          modelError(`AdditionalProperty behavior for type '${fqn(typeDef.name)}' requires a 'behavior_meta' decorator with at least 2 arguments (key, value)`)
+        }
+        if (parent.type.name === 'AdditionalProperties' && (parent.meta == null || parent.meta.fieldname == null || parent.meta.description == null)) {
+          modelError(`AdditionalProperties behavior for type '${fqn(typeDef.name)}' requires a 'behavior_meta' decorator with exactly 2 arguments (fieldname, description)`)
+        }
       }
       context.pop()
     }

docs/behaviors.md

@@ -15,12 +15,18 @@ This puts it into a bin that needs a client specific solution.
 We therefore document the requirement to behave like a dictionary for unknown properties with this interface.
 
 ```ts
+/**
+ * @behavior_meta AdditionalProperties fieldname=sub_aggregations
+ */
 class IpRangeBucket implements AdditionalProperties<AggregateName, Aggregate> {}
 ```
 
 There are also many places where we expect only one runtime-defined property, such as in field-related queries. To capture that uniqueness constraint, we can use the `AdditionalProperty` (singular) behavior.
 
 ```ts
+/**
+ * @behavior_meta AdditionalProperty key=field value=bounding_box
+ */
 class GeoBoundingBoxQuery extends QueryBase
   implements AdditionalProperty<Field, BoundingBox>
 ```