Deprecate known values (#3094)

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

Author: timotheeguerin

.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 };