Deprecate known values (#3094)

fix #3009

---------

Co-authored-by: Mark Cowlishaw <markcowl@microsoft.com>

.chronus/changes/deprecate-known-values-2024-3-2-11-42-15.md

@@ -0,0 +1,15 @@
+---
+changeKind: deprecation
+packages:
+  - "@typespec/compiler"
+---
+
+Deprecate `@knownValues` decorator. Use a named union of string literal with a string variant to achieve the same result without a decorator
+
+Example:
+```diff
+-enum FooKV { a, b, c}
+-@knownValues(FooKV)
+-scalar foo extends string;
++union Foo { "a", "b", "c", string }
+```

.chronus/changes/deprecate-known-values-2024-3-2-18-48-59.md

@@ -0,0 +1,6 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: internal
+packages:
+  - "@typespec/openapi3"
+---

packages/compiler/lib/decorators.tsp

@@ -321,6 +321,7 @@ extern dec friendlyName(target: unknown, name: valueof string, formatArgs?: unkn
  * }
  * ```
  */
+#deprecated "This decorator has been deprecated. Use a named union of string literals with a string variant to achieve the same result without a decorator."
 extern dec knownValues(target: string | numeric | ModelProperty, values: Enum);
 
 /**

packages/compiler/test/decorators/decorators.test.ts

@@ -416,6 +416,7 @@ describe("compiler: built-in decorators", () => {
     it("assign the known values to string scalar", async () => {
       const { Bar } = (await runner.compile(`
         enum Foo {one: "one", two: "two"}
+        #suppress "deprecated" "For testing"
         @test
         @knownValues(Foo)
         scalar Bar extends string;
@@ -433,6 +434,7 @@ describe("compiler: built-in decorators", () => {
           one: 1; 
           two: 2;
         }
+        #suppress "deprecated" "For testing"
         @test
         @knownValues(Foo)
         scalar Bar extends int32;
@@ -447,6 +449,7 @@ describe("compiler: built-in decorators", () => {
     it("emit diagnostics when used on non model", async () => {
       const diagnostics = await runner.diagnose(`
         enum Foo {one, two}
+        #suppress "deprecated" "For testing"
         @knownValues(Foo)
         enum Bar {}
       `);
@@ -464,6 +467,7 @@ describe("compiler: built-in decorators", () => {
           one: 1; 
           two: 2;
         }
+        #suppress "deprecated" "For testing"
         @knownValues(Foo)
         scalar Bar extends string;
       `);
@@ -476,6 +480,7 @@ describe("compiler: built-in decorators", () => {
 
     it("emit diagnostics when used on non string model", async () => {
       const diagnostics = await runner.diagnose(`
+        #suppress "deprecated" "For testing"
         enum Foo {one, two}
         @knownValues(Foo)
         model Bar {}
@@ -491,6 +496,7 @@ describe("compiler: built-in decorators", () => {
     it("emit diagnostics when known values is not an enum", async () => {
       const diagnostics = await runner.diagnose(`
         model Foo {}
+        #suppress "deprecated" "For testing"
         @knownValues(Foo)
         scalar Bar extends string;
       `);

packages/openapi3/test/models.test.ts

@@ -549,6 +549,7 @@ describe("openapi3: models", () => {
         Dog, Cat
       }
 
+      #suppress "deprecated" "For testing"
       @knownValues(KnownPetType)
       scalar PetType extends string;
       model Pet { type: PetType };