@typespec/compiler 0.49.0-dev.13 → 0.49.0-dev.15

package/dist/manifest.js

@@ -1,4 +1,4 @@
 export default {
-  "version": "0.49.0-dev.13",
-  "commit": "f9c9a945b340ab6187dd65c4ce43d186cb9359a2"
+  "version": "0.49.0-dev.15",
+  "commit": "9a2a1bf771a8504cdd80bccaae3b01fdf382863a"
 };

package/dist/src/core/checker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checker.d.ts","sourceRoot":"","sources":["../../../src/core/checker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"checker.d.ts","sourceRoot":"","sources":["../../../src/core/checker.ts"],"names":[],"mappings":"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"}

package/dist/src/core/checker.js

@@ -43,6 +43,8 @@ export function createChecker(program) {
     const globalNamespaceNode = createGlobalNamespaceNode();
     const globalNamespaceType = createGlobalNamespaceType();
     let typespecNamespaceNode;
+    // Caches the deprecation test of nodes in the program
+    const nodeDeprecationMap = new Map();
     const errorType = createType({ kind: "Intrinsic", name: "ErrorType" });
     const voidType = createType({ kind: "Intrinsic", name: "void" });
     const neverType = createType({ kind: "Intrinsic", name: "never" });
@@ -525,6 +527,41 @@ export function createChecker(program) {
             reportDeprecation(program, target, deprecationDetails.message, reportCheckerDiagnostic);
         }
     }
+    function isTypeReferenceContextDeprecated(node) {
+        function checkDeprecatedNode(node) {
+            var _a;
+            // Perform a simple check if the parent node is deprecated.  We do this
+            // out of band because `checkDirectives` usually gets called on the parent
+            // type after child types have already been checked (including their
+            // deprecations).
+            if (!nodeDeprecationMap.has(node)) {
+                nodeDeprecationMap.set(node, ((_a = node.directives) !== null && _a !== void 0 ? _a : []).findIndex((d) => d.target.sv === "deprecated") >= 0);
+            }
+            return nodeDeprecationMap.get(node);
+        }
+        // Walk the parent hierarchy up to a node which might have a
+        // deprecation which would mitigate the deprecation warning of the original
+        // type reference. This is done to prevent multiple deprecation notices from
+        // being raised when a parent context is already being deprecated.
+        switch (node.kind) {
+            case SyntaxKind.ModelStatement:
+                return checkDeprecatedNode(node);
+            case SyntaxKind.OperationStatement:
+                return (checkDeprecatedNode(node) ||
+                    (node.parent.kind === SyntaxKind.InterfaceStatement &&
+                        isTypeReferenceContextDeprecated(node.parent)));
+            case SyntaxKind.InterfaceStatement:
+                return checkDeprecatedNode(node);
+            case SyntaxKind.IntersectionExpression:
+            case SyntaxKind.UnionExpression:
+            case SyntaxKind.ModelProperty:
+            case SyntaxKind.OperationSignatureDeclaration:
+            case SyntaxKind.OperationSignatureReference:
+                return isTypeReferenceContextDeprecated(node.parent);
+            default:
+                return false;
+        }
+    }
     function checkTypeReferenceArgs(node, mapper) {
         const args = [];
         if (node.kind !== SyntaxKind.TypeReference) {
@@ -680,10 +717,14 @@ export function createChecker(program) {
                 }
             }
         }
-        // Check for deprecations here, first on symbol, then on type.
+        // Check for deprecations here, first on symbol, then on type.  However,
+        // don't raise deprecation when the usage site is also a deprecated
+        // declaration.
         const declarationNode = sym === null || sym === void 0 ? void 0 : sym.declarations[0];
         if (declarationNode && mapper === undefined) {
-            checkDeprecated(baseType, declarationNode, node);
+            if (!isTypeReferenceContextDeprecated(node.parent)) {
+                checkDeprecated(baseType, declarationNode, node);
+            }
         }
         return baseType;
     }
@@ -2323,10 +2364,7 @@ export function createChecker(program) {
                 ((_c = prop.parent.parent.parent) === null || _c === void 0 ? void 0 : _c.kind) === SyntaxKind.OperationStatement) {
                 const doc = extractParamDoc(prop.parent.parent.parent, type.name);
                 if (doc) {
-                    type.decorators.unshift({
-                        decorator: $docFromComment,
-                        args: [{ value: createLiteralType(doc), jsValue: doc }],
-                    });
+                    type.decorators.unshift(createDocFromCommentDecorator("self", doc));
                 }
             }
             finishType(type);
@@ -2334,6 +2372,15 @@ export function createChecker(program) {
         pendingResolutions.finish(symId, ResolutionKind.Type);
         return type;
     }
+    function createDocFromCommentDecorator(key, doc) {
+        return {
+            decorator: $docFromComment,
+            args: [
+                { value: createLiteralType(key), jsValue: key },
+                { value: createLiteralType(doc), jsValue: doc },
+            ],
+        };
+    }
     function isValueType(type) {
         if (type === nullType) {
             return true;
@@ -2533,10 +2580,16 @@ export function createChecker(program) {
         // Doc comment should always be the first decorator in case an explicit @doc must override it.
         const docComment = extractMainDoc(targetType);
         if (docComment) {
-            decorators.unshift({
-                decorator: $docFromComment,
-                args: [{ value: createLiteralType(docComment), jsValue: docComment }],
-            });
+            decorators.unshift(createDocFromCommentDecorator("self", docComment));
+        }
+        if (targetType.kind === "Operation") {
+            const returnTypesDocs = extractReturnsDocs(targetType);
+            if (returnTypesDocs.returns) {
+                decorators.unshift(createDocFromCommentDecorator("returns", returnTypesDocs.returns));
+            }
+            if (returnTypesDocs.errors) {
+                decorators.unshift(createDocFromCommentDecorator("errors", returnTypesDocs.errors));
+            }
         }
         return decorators;
     }
@@ -4437,6 +4490,27 @@ function extractMainDoc(type) {
     const trimmed = mainDoc.trim();
     return trimmed === "" ? undefined : trimmed;
 }
+function extractReturnsDocs(type) {
+    var _a;
+    const result = {
+        returns: undefined,
+        errors: undefined,
+    };
+    if (((_a = type.node) === null || _a === void 0 ? void 0 : _a.docs) === undefined) {
+        return result;
+    }
+    for (const doc of type.node.docs) {
+        for (const tag of doc.tags) {
+            if (tag.kind === SyntaxKind.DocReturnsTag) {
+                result.returns = getDocContent(tag.content);
+            }
+            if (tag.kind === SyntaxKind.DocErrorsTag) {
+                result.errors = getDocContent(tag.content);
+            }
+        }
+    }
+    return result;
+}
 function extractParamDoc(node, paramName) {
     if (node.docs === undefined) {
         return undefined;