@azure-tools/typespec-ts 0.30.1 → 0.31.0-alpha.20240723.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-tools/typespec-ts",
-  "version": "0.30.1",
+  "version": "0.31.0-alpha.20240723.1",
   "description": "An experimental TypeSpec emitter for TypeScript RLC",
   "main": "dist/src/index.js",
   "type": "module",
@@ -18,16 +18,16 @@
   "license": "MIT",
   "devDependencies": {
     "@azure-rest/core-client": "^2.1.0",
-    "@azure-tools/cadl-ranch-expect": "^0.13.4",
-    "@azure-tools/cadl-ranch-specs": "^0.33.4",
-    "@azure-tools/cadl-ranch": "^0.12.8",
-    "@azure-tools/typespec-autorest": ">=0.43.0 <1.0.0",
-    "@azure-tools/typespec-azure-core": ">=0.43.0 <1.0.0",
-    "@azure-tools/typespec-azure-resource-manager": ">=0.43.0 <1.0.0",
-    "@azure-tools/typespec-client-generator-core": ">=0.43.0 <1.0.0",
+    "@azure-tools/cadl-ranch-expect": "^0.14.1",
+    "@azure-tools/cadl-ranch-specs": "^0.34.7",
+    "@azure-tools/cadl-ranch": "^0.13.4",
+    "@azure-tools/typespec-autorest": ">=0.44.0 <1.0.0",
+    "@azure-tools/typespec-azure-core": ">=0.44.0 <1.0.0",
+    "@azure-tools/typespec-azure-resource-manager": ">=0.44.0 <1.0.0",
+    "@azure-tools/typespec-client-generator-core": ">=0.44.1 <1.0.0",
     "@azure/abort-controller": "^2.1.2",
     "@azure/core-auth": "^1.6.0",
-    "@azure/core-lro": "3.0.0",
+    "@azure/core-lro": "^3.0.0",
     "@azure/core-paging": "^1.5.0",
     "@azure/core-rest-pipeline": "^1.14.0",
     "@azure/core-util": "^1.4.0",
@@ -39,12 +39,12 @@
     "@types/node": "^18.0.0",
     "@typescript-eslint/eslint-plugin": "^6.8.0",
     "@typescript-eslint/parser": "^6.8.0",
-    "@typespec/compiler": ">=0.57.0 <1.0.0",
-    "@typespec/http": ">=0.57.0 <1.0.0",
-    "@typespec/openapi": ">=0.57.0, <1.0.0",
-    "@typespec/rest": ">=0.57.0 <1.0.0",
+    "@typespec/compiler": ">=0.58.1 <1.0.0",
+    "@typespec/http": ">=0.58.0 <1.0.0",
+    "@typespec/openapi": ">=0.58.0, <1.0.0",
+    "@typespec/rest": ">=0.58.0 <1.0.0",
     "@typespec/ts-http-runtime": "1.0.0-alpha.20240314.2",
-    "@typespec/versioning": ">=0.57.0 <1.0.0",
+    "@typespec/versioning": ">=0.58.0 <1.0.0",
     "chai": "^4.3.6",
     "chalk": "^4.0.0",
     "cross-env": "^7.0.3",
@@ -56,21 +56,21 @@
     "prettier": "^3.1.0",
     "rimraf": "^5.0.0",
     "ts-node": "~10.9.1",
-    "typescript": "~5.4.5",
+    "typescript": "~5.5.3",
     "vitest": "~1.6.0",
     "@vitest/coverage-v8": "~1.6.0",
     "@vitest/coverage-istanbul": "~1.6.0"
   },
   "peerDependencies": {
-    "@azure-tools/typespec-azure-core": ">=0.43.0 <1.0.0",
-    "@azure-tools/typespec-client-generator-core": ">=0.43.0 <1.0.0",
-    "@typespec/compiler": ">=0.57.0 <1.0.0",
-    "@typespec/http": ">=0.57.0 <1.0.0",
-    "@typespec/rest": ">=0.57.0 <1.0.0",
-    "@typespec/versioning": ">=0.57.0 <1.0.0"
+    "@azure-tools/typespec-azure-core": ">=0.44.0 <1.0.0",
+    "@azure-tools/typespec-client-generator-core": ">=0.44.1 <1.0.0",
+    "@typespec/compiler": ">=0.58.1 <1.0.0",
+    "@typespec/http": ">=0.58.0 <1.0.0",
+    "@typespec/rest": ">=0.58.0 <1.0.0",
+    "@typespec/versioning": ">=0.58.0 <1.0.0"
   },
   "dependencies": {
-    "@azure-tools/rlc-common": "^0.30.0",
+    "@azure-tools/rlc-common": "^0.31.0",
     "fs-extra": "^11.1.0",
     "lodash": "^4.17.21",
     "prettier": "^3.1.0",
@@ -99,7 +99,7 @@
     "test-next:coverage": "vitest run ./test-next --coverage",
     "clean": "rimraf ./dist ./typespec-output",
     "build": "tsc -p .",
-    "test": "npm run unit-test && npm run integration-test-ci",
+    "test": "npm run test-next && npm run unit-test && npm run integration-test-ci",
     "lint": "eslint src --ext .ts --max-warnings=0",
     "lint:fix": "eslint src --fix --ext .ts",
     "format": "npm run -s prettier -- --write",

package/src/contextManager.ts

@@ -2,6 +2,8 @@ import { Project, SourceFile } from "ts-morph";
 import { ModularMetaTree, RlcMetaTree } from "./metaTree.js";
 import { EmitContext } from "@typespec/compiler";
 import { SdkContext } from "@azure-tools/typespec-client-generator-core";
+import { SdkTypeContext } from "./framework/hooks/sdkTypes.js";
+import { Binder } from "./framework/hooks/binder.js";
 
 /**
  * Contexts Object Guidelines
@@ -21,10 +23,12 @@ type Contexts = {
   modularMetaTree: ModularMetaTree; // Context for modular types metadata.
   outputProject: Project; // The TS-Morph root project context for code generation.
   symbolMap: Map<string, SourceFile>; // Mapping of symbols to their corresponding source files.
+  sdkTypes: SdkTypeContext;
   emitContext: {
     compilerContext: EmitContext;
     tcgcContext: SdkContext;
   };
+  binder: Binder;
 };
 
 type ContextKey = keyof Contexts;

package/src/framework/declaration.ts

@@ -0,0 +1,100 @@
+import {
+  SourceFile,
+  ClassDeclarationStructure,
+  EnumDeclarationStructure,
+  FunctionDeclarationStructure,
+  InterfaceDeclarationStructure,
+  TypeAliasDeclarationStructure,
+  StructureKind,
+  ClassDeclaration,
+  EnumDeclaration,
+  FunctionDeclaration,
+  InterfaceDeclaration,
+  TypeAliasDeclaration
+} from "ts-morph";
+import { useBinder } from "./hooks/binder.js";
+import { refkey as getRefKey } from "./refkey.js";
+export type DeclarationStructures =
+  | ClassDeclarationStructure
+  | EnumDeclarationStructure
+  | FunctionDeclarationStructure
+  | InterfaceDeclarationStructure
+  | TypeAliasDeclarationStructure;
+
+export type Declarations =
+  | ClassDeclaration
+  | EnumDeclaration
+  | FunctionDeclaration
+  | InterfaceDeclaration
+  | TypeAliasDeclaration;
+
+export function addDeclaration(
+  sourceFile: SourceFile,
+  declaration: ClassDeclarationStructure,
+  refkey: unknown
+): ClassDeclaration;
+
+export function addDeclaration(
+  sourceFile: SourceFile,
+  declaration: EnumDeclarationStructure,
+  refkey: unknown
+): EnumDeclaration;
+
+export function addDeclaration(
+  sourceFile: SourceFile,
+  declaration: FunctionDeclarationStructure,
+  refkey: unknown
+): FunctionDeclaration;
+
+export function addDeclaration(
+  sourceFile: SourceFile,
+  declaration: InterfaceDeclarationStructure,
+  refkey: unknown
+): InterfaceDeclaration;
+
+export function addDeclaration(
+  sourceFile: SourceFile,
+  declaration: TypeAliasDeclarationStructure,
+  refkey: unknown
+): TypeAliasDeclaration;
+export function addDeclaration(
+  sourceFile: SourceFile,
+  declaration: DeclarationStructures,
+  refkey: unknown
+): Declarations {
+  const binder = useBinder();
+
+  if (!declaration.name) {
+    throw new Error(
+      `Declaration must have a name ${JSON.stringify(declaration)}`
+    );
+  }
+
+  const stringRefkey = typeof refkey === "string" ? refkey : getRefKey(refkey);
+
+  const trackedDeclarationName = binder.trackDeclaration(
+    stringRefkey,
+    declaration.name,
+    sourceFile
+  );
+
+  // Update the declaration name to be unique
+  const trackedDeclaration = { ...declaration, name: trackedDeclarationName };
+
+  switch (trackedDeclaration.kind) {
+    case StructureKind.Class:
+      return sourceFile.addClass(trackedDeclaration);
+    case StructureKind.Enum:
+      return sourceFile.addEnum(trackedDeclaration);
+    case StructureKind.Function:
+      return sourceFile.addFunction(trackedDeclaration);
+    case StructureKind.Interface:
+      return sourceFile.addInterface(trackedDeclaration);
+    case StructureKind.TypeAlias:
+      return sourceFile.addTypeAlias(trackedDeclaration);
+    default:
+      throw new Error(
+        `Unsupported declaration kind ${(trackedDeclaration as any).kind}`
+      );
+  }
+}

package/src/framework/hooks/binder.ts

@@ -0,0 +1,259 @@
+import {
+  SourceFile,
+  ImportDeclarationStructure,
+  StructureKind,
+  ImportSpecifierStructure,
+  Project
+} from "ts-morph";
+import { provideContext, useContext } from "../../contextManager.js";
+
+export interface DeclarationInfo {
+  name: string;
+  sourceFile: SourceFile;
+  alias?: string;
+}
+
+export interface Binder {
+  /**
+   * Tracks a new declaration.
+   * @param refkey - A unique reference key for the declaration.
+   * @param name - The name of the declaration.
+   * @param sourceFile - The source file where the declaration is made.
+   * @returns The tracked declaration name.
+   */
+  trackDeclaration(
+    refkey: unknown,
+    name: string,
+    sourceFile: SourceFile
+  ): string;
+  resolveReference(refkey: unknown): string;
+  applyImports(): void;
+}
+
+class BinderImp implements Binder {
+  private declarations = new Map<unknown, DeclarationInfo>();
+  private imports = new Map<SourceFile, ImportDeclarationStructure[]>();
+  private symbolsBySourceFile = new Map<SourceFile, Set<string>>();
+  private project: Project;
+
+  constructor(project?: Project) {
+    this.project = project ?? new Project();
+  }
+
+  trackDeclaration(
+    refkey: unknown,
+    name: string,
+    sourceFile: SourceFile
+  ): string {
+    const uniqueName = this.generateLocallyUniqueDeclarationName(
+      name,
+      sourceFile
+    );
+    const declarationInfo: DeclarationInfo = { name: uniqueName, sourceFile };
+    this.declarations.set(refkey, declarationInfo);
+
+    // Ensure symbolsBySourceFile has an entry for this sourceFile
+    if (!this.symbolsBySourceFile.has(sourceFile)) {
+      this.symbolsBySourceFile.set(sourceFile, new Set());
+    }
+    this.symbolsBySourceFile.get(sourceFile)!.add(uniqueName);
+
+    return uniqueName;
+  }
+
+  /**
+   * Generates a locally unique name for a declaration within a source file.
+   * @param name - The base name of the declaration.
+   * @param sourceFile - The source file where the declaration is made.
+   * @returns A unique name for the declaration within the file.
+   */
+  private generateLocallyUniqueDeclarationName(
+    name: string,
+    sourceFile: SourceFile
+  ): string {
+    const existingNamesInFile =
+      this.symbolsBySourceFile.get(sourceFile) ?? new Set<string>();
+    return this.generateLocallyUniqueName(name, existingNamesInFile);
+  }
+
+  /**
+   * Generates a locally unique name for an import within a source file.
+   * @param name - The base name of the import.
+   * @param sourceFile - The source file where the import is made.
+   * @returns A unique name for the import within the file.
+   */
+  private generateLocallyUniqueImportName(
+    name: string,
+    sourceFile: SourceFile
+  ): string {
+    const existingImports = (this.imports.get(sourceFile) ?? [])
+      .flatMap((i) => i.namedImports as ImportSpecifierStructure[])
+      .map((i) => i.alias ?? i.name);
+
+    const existingDeclarations =
+      this.symbolsBySourceFile.get(sourceFile) ?? new Set<string>();
+    return this.generateLocallyUniqueName(
+      name,
+      new Set([...existingImports, ...existingDeclarations])
+    );
+  }
+
+  /**
+   * Generates a locally unique name within a set of existing names.
+   * @param name - The base name.
+   * @param existingNames - A set of names already in use.
+   * @returns A unique name not present in the existing names set.
+   */
+  private generateLocallyUniqueName(
+    name: string,
+    existingNames: Set<string>
+  ): string {
+    let uniqueName = name;
+    let counter = 1;
+    while (existingNames.has(uniqueName)) {
+      uniqueName = `${name}_${counter}`;
+      counter++;
+    }
+    return uniqueName;
+  }
+
+  /**
+   * Resolves a reference to a declaration.
+   *  If a declaration is not ready yet, a placeholder is added to the source file.
+   *  Placeholders will be resolved when the imports are applied.
+   * @param refkey - The reference key for the declaration.
+   * @param currentSourceFile - The current source file where the reference is being resolved.
+   * @returns The declaration information if resolved, or a placeholder if not found.
+   */
+  resolveReference(refkey: unknown): string {
+    return this.serializePlaceholder(refkey);
+  }
+
+  /**
+   * Serializes a placeholder reference key to a string.
+   * @param refkey - The reference key.
+   * @returns The serialized placeholder string.
+   */
+  private serializePlaceholder(refkey: unknown): string {
+    return `PLACEHOLDER:${String(refkey)}`;
+  }
+
+  /**
+   * Adds an import declaration to a source file.
+   * @param fileWhereImportIsAdded - The source file where the import is added.
+   * @param fileWhereImportPointsTo - The source file being imported.
+   * @param name - The name of the import.
+   * @returns The import specifier structure.
+   */
+  private addImport(
+    fileWhereImportIsAdded: SourceFile,
+    fileWhereImportPointsTo: SourceFile,
+    name: string
+  ): ImportSpecifierStructure {
+    const importAlias = this.generateLocallyUniqueImportName(
+      name,
+      fileWhereImportIsAdded
+    );
+    const relativePath =
+      fileWhereImportIsAdded.getRelativePathAsModuleSpecifierTo(
+        fileWhereImportPointsTo
+      );
+    const importStructures = this.imports.get(fileWhereImportIsAdded) || [];
+
+    let importStructure = importStructures.find(
+      (imp) => imp.moduleSpecifier === relativePath
+    );
+
+    if (!importStructure) {
+      importStructure = {
+        kind: StructureKind.ImportDeclaration,
+        moduleSpecifier: relativePath,
+        namedImports: []
+      };
+      importStructures.push(importStructure);
+    }
+
+    const namedImports =
+      importStructure.namedImports as ImportSpecifierStructure[];
+    let importSpecifier = namedImports.find((n) => n.name === importAlias);
+
+    if (!importSpecifier) {
+      importSpecifier = {
+        name: name,
+        alias: name === importAlias ? undefined : importAlias,
+        kind: StructureKind.ImportSpecifier
+      };
+      namedImports.push(importSpecifier);
+    }
+
+    importStructure.namedImports = namedImports;
+    this.imports.set(fileWhereImportIsAdded, importStructures);
+    return importSpecifier;
+  }
+
+  /**
+   * Applies all tracked imports to their respective source files.
+   */
+  applyImports(): void {
+    for (const file of this.project.getSourceFiles()) {
+      for (const [declarationKey, declaration] of this.declarations) {
+        const placeholderKey = this.serializePlaceholder(declarationKey);
+        let name = declaration.name;
+        if (file !== declaration.sourceFile) {
+          const importDec = this.addImport(
+            file,
+            declaration.sourceFile,
+            declaration.name
+          );
+          name = importDec.alias ?? declaration.name;
+        }
+        replacePlaceholder(file, placeholderKey, name);
+      }
+    }
+
+    for (const [sourceFile, importStructures] of this.imports) {
+      for (const importStructure of importStructures) {
+        sourceFile.addImportDeclaration(importStructure);
+      }
+    }
+  }
+}
+
+// Provide the binder context to be used globally
+export function provideBinder(project?: Project): void {
+  return provideContext("binder", new BinderImp(project));
+}
+
+/**
+ * Hook to use the binder context.
+ * @returns The binder instance.
+ */
+export function useBinder(): Binder {
+  return useContext("binder");
+}
+
+/**
+ * Replaces all instances of a placeholder in a source file with a given value.
+ * @param sourceFile - The source file where the replacement occurs.
+ * @param placeholder - The placeholder string to replace.
+ * @param value - The value to replace the placeholder with.
+ */
+function replacePlaceholder(
+  sourceFile: SourceFile,
+  placeholder: string,
+  value: string
+): void {
+  const fileText = sourceFile.getFullText();
+  const regex = new RegExp(escapeRegExp(placeholder), "g");
+  const updatedText = fileText.replace(regex, value);
+  sourceFile.replaceWithText(updatedText);
+}
+
+/**
+ * Escapes special characters in a string to be used in a regular expression.
+ * @param string - The input string.
+ * @returns The escaped string.
+ */
+function escapeRegExp(string: string): string {
+  return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/framework/hooks/sdkTypes.ts

@@ -0,0 +1,101 @@
+import {
+  SdkClientType,
+  SdkHttpOperation,
+  SdkPackage,
+  SdkServiceMethod,
+  SdkType,
+  getClientType
+} from "@azure-tools/typespec-client-generator-core";
+import { Operation, Type, getNamespaceFullName } from "@typespec/compiler";
+import { provideContext, useContext } from "../../contextManager.js";
+
+export interface SdkTypeContext {
+  operations: Map<Type, SdkServiceMethod<SdkHttpOperation>>;
+  types: Map<Type, SdkType>;
+}
+
+export function useSdkTypes() {
+  const sdkTypesContext = useContext("sdkTypes");
+  const { tcgcContext } = useContext("emitContext");
+
+  function getSdkType(type: Operation): SdkServiceMethod<SdkHttpOperation>;
+  function getSdkType(type: Type): SdkType;
+  function getSdkType(
+    type: Type | Operation
+  ): SdkType | SdkServiceMethod<SdkHttpOperation> {
+    let sdkType: SdkType | SdkServiceMethod<SdkHttpOperation> | undefined;
+
+    if (type.kind === "Operation") {
+      sdkType = sdkTypesContext.operations.get(type);
+    } else {
+      sdkType =
+        sdkTypesContext.types.get(type) ?? getClientType(tcgcContext, type);
+    }
+
+    if (!sdkType) {
+      throw new Error(
+        `SdkType not found for type: ${type.kind} ${
+          "name" in type && typeof type.name == "string" ? type.name : ""
+        } ${
+          "namespace" in type && type.namespace
+            ? ` in ${getNamespaceFullName(type.namespace)}`
+            : ""
+        }`
+      );
+    }
+
+    return sdkType;
+  }
+
+  return getSdkType;
+}
+
+export function provideSdkTypes(sdkPackage: SdkPackage<SdkHttpOperation>) {
+  const sdkTypesContext = {
+    operations: new Map<Type, SdkServiceMethod<SdkHttpOperation>>(),
+    types: new Map<Type, SdkType>()
+  };
+
+  for (const sdkEnum of sdkPackage.enums) {
+    if (!sdkEnum.__raw) {
+      continue;
+    }
+
+    sdkTypesContext.types.set(sdkEnum.__raw, sdkEnum);
+  }
+
+  for (const sdkModel of sdkPackage.models) {
+    if (!sdkModel.__raw) {
+      continue;
+    }
+
+    sdkTypesContext.types.set(sdkModel.__raw, sdkModel);
+  }
+
+  for (const client of sdkPackage.clients) {
+    for (const method of getAllOperationsFromClient(client)) {
+      if (!method.__raw) {
+        continue;
+      }
+
+      sdkTypesContext.operations.set(method.__raw, method);
+    }
+  }
+
+  provideContext("sdkTypes", sdkTypesContext);
+}
+
+function getAllOperationsFromClient(client: SdkClientType<SdkHttpOperation>) {
+  const methodQueue = [...client.methods];
+  const operations: SdkServiceMethod<SdkHttpOperation>[] = [];
+  while (methodQueue.length > 0) {
+    const method = methodQueue.pop()!;
+    if (method.kind === "clientaccessor") {
+      method.response.methods.forEach((m) => methodQueue.push(m));
+    } else {
+      operations.push(method);
+    }
+  }
+
+  return operations;
+}

package/src/framework/reference.ts

@@ -0,0 +1,9 @@
+import { useBinder } from "./hooks/binder.js";
+import { refkey as getRefKey } from "./refkey.js";
+
+export function resolveReference(refkey: unknown): string | undefined {
+  const binder = useBinder();
+  const stringRefkey = typeof refkey === "string" ? refkey : getRefKey(refkey);
+
+  return binder.resolveReference(stringRefkey);
+}

package/src/framework/refkey.ts

@@ -0,0 +1,28 @@
+const objectIds = new WeakMap<WeakKey, string>();
+let objId = 0;
+
+function getObjectKey(value: WeakKey) {
+  if (objectIds.has(value)) {
+    return `${objectIds.get(value)}`;
+  }
+
+  const key = `o${objId++}`;
+  objectIds.set(value, key);
+
+  return key;
+}
+
+declare const RefkeySym: unique symbol;
+export type RefKey = string & { [RefkeySym]: true };
+
+function getKey(value: unknown): RefKey {
+  if (typeof value === "object" && value !== null) {
+    return getObjectKey(value) as RefKey;
+  } else {
+    return `s${String(value)}` as RefKey;
+  }
+}
+
+export function refkey(...args: unknown[]) {
+  return args.map((v) => getKey(v)).join("\u2063");
+}