Polish some API names in TCGC (Azure#1463)

Fixes Azure#874 Fixes Azure#933 Fixes Azure#1462 Fixes Azure#1466
markcowl · Sep 24, 2024 · 8d5a810 · 8d5a810
1 parent f64b066
commit 8d5a810
Show file tree

Hide file tree

Showing 16 changed files with 178 additions and 214 deletions.
diff --git a/.chronus/changes/change-some-bad-apis-2024-8-3-7-4-12.md b/.chronus/changes/change-some-bad-apis-2024-8-3-7-4-12.md
@@ -0,0 +1,12 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: breaking
+packages:
+  - "@azure-tools/typespec-client-generator-core"
+---
+
+1. The kind for `unknown` renamed from `any` to `unknown`.
+2. The `values` property in `SdkUnionType` renamed to `variantTypes`.
+3. The `values` property in `SdkTupleType` renamed to `valueTypes`.
+4. The example types for parameter, response and `SdkType` has been renamed to `XXXExampleValue` to emphasize that they are values instead of the example itself.
+5. The `@format` decorator is no longer able to change the type of the property. 
diff --git a/packages/typespec-client-generator-core/src/example.ts b/packages/typespec-client-generator-core/src/example.ts
@@ -12,28 +12,25 @@ import {
 import { HttpStatusCodeRange } from "@typespec/http";
 import { getOperationId } from "@typespec/openapi";
 import {
-  SdkAnyExample,
-  SdkArrayExample,
+  SdkArrayExampleValue,
   SdkArrayType,
   SdkBodyModelPropertyType,
   SdkClientType,
-  SdkDictionaryExample,
+  SdkDictionaryExampleValue,
   SdkDictionaryType,
+  SdkExampleValue,
   SdkHttpOperation,
   SdkHttpOperationExample,
   SdkHttpParameter,
-  SdkHttpParameterExample,
+  SdkHttpParameterExampleValue,
   SdkHttpResponse,
-  SdkHttpResponseExample,
-  SdkModelExample,
+  SdkHttpResponseExampleValue,
+  SdkModelExampleValue,
   SdkModelPropertyType,
   SdkModelType,
-  SdkNullExample,
   SdkServiceMethod,
   SdkServiceOperation,
   SdkType,
-  SdkTypeExample,
-  SdkUnionExample,
   TCGCContext,
   isSdkFloatKind,
   isSdkIntKind,
@@ -225,7 +222,7 @@ function handleHttpOperationExamples(
   operation.examples = [];
 
   for (const [title, example] of Object.entries(examples)) {
-    const operationExample = {
+    const operationExample: SdkHttpOperationExample = {
       kind: "http",
       name: title,
       description: title,
@@ -243,7 +240,7 @@ function handleHttpOperationExamples(
         handleHttpResponses(operation.responses, example.data, example.relativePath)
       ),
       rawExample: example.data,
-    } as SdkHttpOperationExample;
+    };
 
     operation.examples.push(operationExample);
   }
@@ -255,9 +252,9 @@ function handleHttpParameters(
   parameters: SdkHttpParameter[],
   example: any,
   relativePath: string
-): [SdkHttpParameterExample[], readonly Diagnostic[]] {
+): [SdkHttpParameterExampleValue[], readonly Diagnostic[]] {
   const diagnostics = createDiagnosticCollector();
-  const parameterExamples = [] as SdkHttpParameterExample[];
+  const parameterExamples: SdkHttpParameterExampleValue[] = [];
   if (
     "parameters" in example &&
     typeof example.parameters === "object" &&
@@ -297,9 +294,9 @@ function handleHttpResponses(
   responses: Map<number | HttpStatusCodeRange, SdkHttpResponse>,
   example: any,
   relativePath: string
-): [Map<number, SdkHttpResponseExample>, readonly Diagnostic[]] {
+): [Map<number, SdkHttpResponseExampleValue>, readonly Diagnostic[]] {
   const diagnostics = createDiagnosticCollector();
-  const responseExamples = new Map<number, SdkHttpResponseExample>();
+  const responseExamples = new Map<number, SdkHttpResponseExampleValue>();
   if (
     "responses" in example &&
     typeof example.responses === "object" &&
@@ -346,12 +343,12 @@ function handleHttpResponse(
   response: SdkHttpResponse,
   example: any,
   relativePath: string
-): [SdkHttpResponseExample, readonly Diagnostic[]] {
+): [SdkHttpResponseExampleValue, readonly Diagnostic[]] {
   const diagnostics = createDiagnosticCollector();
-  const responseExample = {
+  const responseExample: SdkHttpResponseExampleValue = {
     response,
     headers: [],
-  } as SdkHttpResponseExample;
+  };
   if (typeof example === "object" && example !== null) {
     for (const name of Object.keys(example)) {
       if (name === "description") {
@@ -397,7 +394,7 @@ function getSdkTypeExample(
   type: SdkType | SdkModelPropertyType,
   example: any,
   relativePath: string
-): [SdkTypeExample | undefined, readonly Diagnostic[]] {
+): [SdkExampleValue | undefined, readonly Diagnostic[]] {
   const diagnostics = createDiagnosticCollector();
 
   if (isSdkIntKind(type.kind) || isSdkFloatKind(type.kind)) {
@@ -406,29 +403,29 @@ function getSdkTypeExample(
     switch (type.kind) {
       case "string":
       case "bytes":
-        return getSdkBaseTypeExample("string", type as SdkType, example, relativePath);
+        return getSdkBaseTypeExample("string", type, example, relativePath);
       case "boolean":
-        return getSdkBaseTypeExample("boolean", type as SdkType, example, relativePath);
+        return getSdkBaseTypeExample("boolean", type, example, relativePath);
       case "url":
       case "plainDate":
       case "plainTime":
-        return getSdkBaseTypeExample("string", type as SdkType, example, relativePath);
+        return getSdkBaseTypeExample("string", type, example, relativePath);
       case "nullable":
         if (example === null) {
           return diagnostics.wrap({
             kind: "null",
             type,
             value: null,
-          } as SdkNullExample);
+          });
         } else {
           return getSdkTypeExample(type.type, example, relativePath);
         }
-      case "any":
+      case "unknown":
         return diagnostics.wrap({
-          kind: "any",
+          kind: "unknown",
           type,
           value: example,
-        } as SdkAnyExample);
+        });
       case "constant":
         if (example === type.value) {
           return getSdkBaseTypeExample(
@@ -478,7 +475,7 @@ function getSdkTypeExample(
           kind: "union",
           type,
           value: example,
-        } as SdkUnionExample);
+        });
       case "array":
         return getSdkArrayExample(type, example, relativePath);
       case "dict":
@@ -495,14 +492,14 @@ function getSdkBaseTypeExample(
   type: SdkType,
   example: any,
   relativePath: string
-): [SdkTypeExample | undefined, readonly Diagnostic[]] {
+): [SdkExampleValue | undefined, readonly Diagnostic[]] {
   const diagnostics = createDiagnosticCollector();
   if (typeof example === kind) {
     return diagnostics.wrap({
       kind,
       type,
       value: example,
-    } as SdkTypeExample);
+    } as SdkExampleValue);
   } else {
     addExampleValueNoMappingDignostic(diagnostics, example, relativePath);
   }
@@ -513,10 +510,10 @@ function getSdkArrayExample(
   type: SdkArrayType,
   example: any,
   relativePath: string
-): [SdkArrayExample | undefined, readonly Diagnostic[]] {
+): [SdkArrayExampleValue | undefined, readonly Diagnostic[]] {
   const diagnostics = createDiagnosticCollector();
   if (Array.isArray(example)) {
-    const arrayExample = [] as SdkTypeExample[];
+    const arrayExample: SdkExampleValue[] = [];
     for (const item of example) {
       const result = diagnostics.pipe(getSdkTypeExample(type.valueType, item, relativePath));
       if (result) {
@@ -527,7 +524,7 @@ function getSdkArrayExample(
       kind: "array",
       type,
       value: arrayExample,
-    } as SdkArrayExample);
+    });
   } else {
     addExampleValueNoMappingDignostic(diagnostics, example, relativePath);
     return diagnostics.wrap(undefined);
@@ -538,13 +535,13 @@ function getSdkDictionaryExample(
   type: SdkDictionaryType,
   example: any,
   relativePath: string
-): [SdkDictionaryExample | undefined, readonly Diagnostic[]] {
+): [SdkDictionaryExampleValue | undefined, readonly Diagnostic[]] {
   const diagnostics = createDiagnosticCollector();
   if (typeof example === "object") {
     if (example === null) {
       return diagnostics.wrap(undefined);
     }
-    const dictionaryExample = {} as Record<string, SdkTypeExample>;
+    const dictionaryExample: Record<string, SdkExampleValue> = {};
     for (const key of Object.keys(example)) {
       const result = diagnostics.pipe(
         getSdkTypeExample(type.valueType, example[key], relativePath)
@@ -557,7 +554,7 @@ function getSdkDictionaryExample(
       kind: "dict",
       type,
       value: dictionaryExample,
-    } as SdkDictionaryExample);
+    });
   } else {
     addExampleValueNoMappingDignostic(diagnostics, example, relativePath);
     return diagnostics.wrap(undefined);
@@ -568,7 +565,7 @@ function getSdkModelExample(
   type: SdkModelType,
   example: any,
   relativePath: string
-): [SdkModelExample | undefined, readonly Diagnostic[]] {
+): [SdkModelExampleValue | undefined, readonly Diagnostic[]] {
   const diagnostics = createDiagnosticCollector();
   if (typeof example === "object") {
     if (example === null) {
@@ -593,10 +590,10 @@ function getSdkModelExample(
 
     let additionalPropertiesType: SdkType | undefined;
     const additionalProperties: Record<string, any> = new Map();
-    const additionalPropertiesExample: Record<string, SdkTypeExample> = {};
+    const additionalPropertiesExample: Record<string, SdkExampleValue> = {};
 
     const properties: Map<string, SdkModelPropertyType> = new Map();
-    const propertiesExample: Record<string, SdkTypeExample> = {};
+    const propertiesExample: Record<string, SdkExampleValue> = {};
 
     // get all properties type and additional properties type if exist
     const modelQueue = [type];
@@ -654,7 +651,7 @@ function getSdkModelExample(
         Object.keys(additionalPropertiesExample).length > 0
           ? additionalPropertiesExample
           : undefined,
-    } as SdkModelExample);
+    });
   } else {
     addExampleValueNoMappingDignostic(diagnostics, example, relativePath);
     return diagnostics.wrap(undefined);

diff --git a/packages/typespec-client-generator-core/src/http.ts b/packages/typespec-client-generator-core/src/http.ts
@@ -67,7 +67,6 @@ import {
 } from "./public-utils.js";
 import {
   addEncodeInfo,
-  addFormatInfo,
   getClientTypeWithDiagnostics,
   getSdkModelPropertyTypeBase,
   getTypeSpecBuiltInType,
@@ -434,7 +433,6 @@ function getSdkHttpResponseAndExceptions(
           ? "application/json"
           : innerResponse.body?.contentTypes[0];
         addEncodeInfo(context, header, clientType, defaultContentType);
-        addFormatInfo(context, header, clientType);
         headers.push({
           __raw: header,
           description: getDocHelper(context, header).description,