Support templated strings in APIView (#7940)

* Initial work to support StringTemplates.

* Closes #7930

* Bump version and add changelog.

Author: tjprescott

tools/apiview/emitters/typespec-apiview/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Release History
 
+## Version 0.4.7 (03-22-2024)
+Support TypeSpec string templates.
+Fix display issue with templated aliases.
+Ensure alias statements end with semicolon.
+
 ## Version 0.4.6 (03-08-2024)
 Support CrossLanguagePackageId.
 

tools/apiview/emitters/typespec-apiview/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-tools/typespec-apiview",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "author": "Microsoft Corporation",
   "description": "Library for emitting APIView token files from TypeSpec",
   "homepage": "https://github.com/Azure/azure-sdk-tools",

tools/apiview/emitters/typespec-apiview/package.json

@@ -8,27 +8,29 @@ import {
   EnumMemberNode,
   EnumSpreadMemberNode,
   EnumStatementNode,
+  Expression,
   getNamespaceFullName,
   getSourceLocation,
   IdentifierNode,
   InterfaceStatementNode,
   IntersectionExpressionNode,
-  listServices,
   MemberExpressionNode,
   ModelExpressionNode,
   ModelPropertyNode,
   ModelSpreadPropertyNode,
   ModelStatementNode,
   Namespace,
   navigateProgram,
-  NoTarget,
   NumericLiteralNode,
   OperationSignatureDeclarationNode,
   OperationSignatureReferenceNode,
   OperationStatementNode,
   Program,
   ScalarStatementNode,
   StringLiteralNode,
+  StringTemplateExpressionNode,
+  StringTemplateHeadNode,
+  StringTemplateSpanNode,
   SyntaxKind,
   TemplateArgumentNode,
   TemplateParameterDeclarationNode,
@@ -43,7 +45,6 @@ import { ApiViewDiagnostic, ApiViewDiagnosticLevel } from "./diagnostic.js";
 import { ApiViewNavigation } from "./navigation.js";
 import { generateId, NamespaceModel } from "./namespace-model.js";
 import { LIB_VERSION } from "./version.js";
-import { reportDiagnostic } from "./lib.js";
 
 const WHITESPACE = " ";
 
@@ -383,6 +384,7 @@ export class ApiView {
         this.namespaceStack.push(obj.id.sv);
         this.keyword("alias", false, true);
         this.typeDeclaration(obj.id.sv, this.namespaceStack.value(), true);
+        this.tokenizeTemplateParameters(obj.templateParameters);
         this.punctuation("=", true, true);
         this.tokenize(obj.value);
         this.namespaceStack.pop();
@@ -633,10 +635,83 @@ export class ApiView {
             this.tokenize(obj.argument);
         }
         break;
+      case SyntaxKind.StringTemplateExpression:
+        obj = node as StringTemplateExpressionNode;
+        const stringValue = this.buildTemplateString(obj);
+        const multiLine = stringValue.includes("\n");
+        // single line case
+        if (!multiLine) {
+          this.stringLiteral(stringValue);
+          break;
+        }
+        // otherwise multiline case
+        const lines = stringValue.split("\n");
+        this.punctuation(`"""`);
+        this.newline();
+        this.indent();
+        for (const line of lines) {
+          this.literal(line);
+          this.newline();
+        }
+        this.deindent();
+        this.punctuation(`"""`);
+        break;
+      case SyntaxKind.StringTemplateSpan:
+        obj = node as StringTemplateSpanNode;
+        this.punctuation("${", false, false);
+        this.tokenize(obj.expression);
+        this.punctuation("}", false, false);
+        this.tokenize(obj.literal);
+        break;
+      case SyntaxKind.StringTemplateHead:
+      case SyntaxKind.StringTemplateMiddle:
+      case SyntaxKind.StringTemplateTail:
+        obj = node as StringTemplateHeadNode;
+        this.literal(obj.value);
+        break;
+      default:
+        // All Projection* cases should fail here...
+        throw new Error(`Case "${SyntaxKind[node.kind].toString()}" not implemented`);
+    }
+  }
+
+  private buildExpressionString(node: Expression) {
+    switch (node.kind) {
+      case SyntaxKind.StringLiteral:
+        return `"${(node as StringLiteralNode).value}"`;
+      case SyntaxKind.NumericLiteral:
+        return (node as NumericLiteralNode).value.toString();
+      case SyntaxKind.BooleanLiteral:
+        return (node as BooleanLiteralNode).value.toString();
+      case SyntaxKind.StringTemplateExpression:
+        return this.buildTemplateString(node as StringTemplateExpressionNode);
+      case SyntaxKind.VoidKeyword:
+        return "void";
+      case SyntaxKind.NeverKeyword:
+        return "never";
+      case SyntaxKind.TypeReference:
+        const obj = node as TypeReferenceNode;
+        switch (obj.target.kind) {
+          case SyntaxKind.Identifier:
+            return (obj.target as IdentifierNode).sv;
+          case SyntaxKind.MemberExpression:
+            return this.getFullyQualifiedIdentifier(obj.target as MemberExpressionNode);
+        }
+        break;
       default:
-        // All Projection* cases should fall in here...
-        throw new Error(`Case "${node.kind.toString()}" not implemented`);
+        throw new Error(`Unsupported expression kind: ${SyntaxKind[node.kind]}`);
+      //unsupported ArrayExpressionNode | MemberExpressionNode | ModelExpressionNode | TupleExpressionNode | UnionExpressionNode | IntersectionExpressionNode | TypeReferenceNode | ValueOfExpressionNode | AnyKeywordNode;
+    }
+  }
+
+  /** Constructs a single string with template markers. */
+  private buildTemplateString(node: StringTemplateExpressionNode): string {
+    let result = node.head.value;
+    for (const span of node.spans) {
+      result += "${" + this.buildExpressionString(span.expression) + "}";
+      result += span.literal.value;
     }
+    return result;
   }
 
   private tokenizeModelStatement(node: ModelStatementNode) {
@@ -891,6 +966,7 @@ export class ApiView {
     }
     for (const node of model.aliases.values()) {
         this.tokenize(node);
+        this.punctuation(";");
         this.blankLines(1);
     }  
     this.endGroup();

tools/apiview/emitters/typespec-apiview/src/apiview.ts

@@ -1 +1 @@
-export const LIB_VERSION = "0.4.6";
+export const LIB_VERSION = "0.4.7";

tools/apiview/emitters/typespec-apiview/src/version.ts

@@ -243,15 +243,41 @@ describe("apiview: tests", () => {
           species: string;
         }
   
-        alias Creature = Animal
+        alias Creature = Animal;
       }
       `;
       const apiview = await apiViewFor(input, {});
       const actual = apiViewText(apiview);
       compare(expect, actual, 9);
       validateDefinitionIds(apiview);
     });  
-  });
+
+    it("templated alias", async () => {
+        const input = `
+        @TypeSpec.service( { title: "Test", version: "1" } )
+        namespace Azure.Test {
+          model Animal {
+            species: string;
+          }
+
+          alias Template<T extends valueof string> = "Foo \${T} bar";
+        }
+        `;
+        const expect = `
+        namespace Azure.Test {
+          model Animal {
+            species: string;
+          }
+    
+          alias Template<T extends valueof string> = "Foo \${T} bar";
+        }
+        `;
+        const apiview = await apiViewFor(input, {});
+        const actual = apiViewText(apiview);
+        compare(expect, actual, 9);
+        validateDefinitionIds(apiview);
+      });  
+    });
 
   describe("augment decorators", () => {
     it("simple augment", async () => {
@@ -693,4 +719,50 @@ describe("apiview: tests", () => {
       validateDefinitionIds(apiview);
     });  
   });
+
+  describe("string templates", () => {
+    it("templates", async () => {
+      const input = `
+      @TypeSpec.service( { title: "Test", version: "1" } )
+      namespace Azure.Test {  
+        alias myconst = "foobar";
+        model Person {
+          simple: "Simple \${123} end";
+          multiline: """
+            Multi
+              \${123}
+              \${true}
+            line
+          """;
+          ref: "Ref this alias \${myconst} end";
+          template: Template<"custom">;          
+        }
+        alias Template<T extends valueof string> = "Foo \${T} bar";
+      }`;
+
+      const expect = `
+      namespace Azure.Test {
+        model Person {
+          simple: "Simple \${123} end";
+          multiline: """
+              Multi
+                \${123}
+                \${true}
+              line
+          """;
+          ref: "Ref this alias \${myconst} end";
+          template: Template<"custom">;
+        }
+
+        alias myconst = "foobar";
+
+        alias Template<T extends valueof string> = "Foo \${T} bar";
+      }
+      `;
+      const apiview = await apiViewFor(input, {});
+      const lines = apiViewText(apiview);
+      compare(expect, lines, 9);
+      validateDefinitionIds(apiview);
+    });
+  });
 });