Fix #3003

Author: Gerrit0

CHANGELOG.md

@@ -4,6 +4,11 @@ title: Changelog
 
 ## Unreleased
 
+### Bug Fixes
+
+- Variables marked with `@enum` now work for symbols imported from another module, #3003.
+- Improved magic introduced with #2999 to work with imported symbols, #3003.
+
 ## v0.28.11 (2025-08-25)
 
 ### Features

src/lib/converter/comments/discovery.ts

@@ -4,6 +4,7 @@ import { CommentStyle } from "../../utils/options/declaration.js";
 import { nicePath } from "../../utils/paths.js";
 import { ok } from "assert";
 import { assertNever, filter, firstDefined, i18n, type Logger } from "#utils";
+import { resolveAliasedSymbol } from "../utils/symbols.js";
 
 const variablePropertyKinds = [
     ts.SyntaxKind.PropertyDeclaration,
@@ -539,6 +540,20 @@ function declarationToCommentNodes(
                 );
             }
         }
+
+        // #3003 even more magic for handling an imported symbol which appears in a shorthand property assignment
+        const originalSymbol = sourceSymbol && resolveAliasedSymbol(sourceSymbol, checker);
+        if (originalSymbol !== sourceSymbol && originalSymbol?.valueDeclaration) {
+            const commentNode = declarationToCommentNodeIgnoringParents(originalSymbol?.valueDeclaration);
+            if (commentNode) {
+                result.push(
+                    {
+                        node: commentNode,
+                        inheritedFromParentDeclaration: true,
+                    },
+                );
+            }
+        }
     }
 
     // With overloaded functions/methods, TypeScript will use the comment on the first signature

src/lib/converter/symbols.ts

@@ -1133,7 +1133,17 @@ function convertVariableAsEnum(
     context.finalizeDeclarationReflection(reflection);
     const rc = context.withScope(reflection);
 
-    const declaration = symbol.declarations!.find(ts.isVariableDeclaration)!;
+    const declaration = symbol.valueDeclaration;
+    if (!declaration) {
+        context.logger.error(
+            i18n.converting_0_as_enum_requires_value_declaration(
+                symbol.name,
+            ),
+            symbol.declarations?.[0],
+        );
+        return;
+    }
+
     const type = context.checker.getTypeAtLocation(declaration);
 
     for (const prop of type.getProperties()) {

src/lib/internationalization/locales/en.cts

@@ -51,6 +51,8 @@ export = {
         `Converting {0} as a class requires a declaration which represents a non-type value`,
     converting_0_as_class_without_construct_signatures:
         `{0} is being converted as a class, but does not have any construct signatures`,
+    converting_0_as_enum_requires_value_declaration:
+        `Converting {0} as an enum requires a declaration which represents a non-type value`,
 
     comment_for_0_should_not_contain_block_or_modifier_tags:
         `The comment for {0} should not contain any block or modifier tags`,

src/test/converter2/issues/gh3003/enums.ts

@@ -0,0 +1,9 @@
+/**
+ * This is a custom enum that is exported as a constant object.
+ *
+ * @enum
+ */
+export const CustomEnum = {
+    /** A */
+    A: "A",
+} as const;

src/test/converter2/issues/gh3003/index.ts

@@ -0,0 +1,17 @@
+import { CustomEnum } from "./enums.js";
+
+/**
+ * This is a second custom enum that is exported as a constant object.
+ *
+ * @enum
+ */
+const CustomEnum2 = {
+    ...CustomEnum,
+    D: "D",
+} as const;
+
+/** @namespace */
+export const ExportedObject = {
+    CustomEnum,
+    CustomEnum2,
+};

src/test/issues.c2.test.ts

@@ -2158,4 +2158,17 @@ describe("Issue Tests", () => {
         const local = opts.type.declaration.getChildByName("LocalObject");
         equal(Comment.combineDisplayParts(local?.comment?.summary), "A test object with property a.");
     });
+
+    it("#3003 handles @enum on properties within @namespace", () => {
+        const project = convert();
+
+        const a = query(project, "ExportedObject.CustomEnum");
+        equalKind(a, ReflectionKind.Enum);
+        equal(a.children?.map(c => c.name), ["A"]);
+        equal(a.children?.map(c => c.type?.toString()), ['"A"']);
+        const b = query(project, "ExportedObject.CustomEnum2");
+        equalKind(b, ReflectionKind.Enum);
+        equal(b.children?.map(c => c.name), ["A", "D"]);
+        equal(b.children?.map(c => c.type?.toString()), ['"A"', '"D"']);
+    });
 });

src/test/utils.ts

@@ -108,7 +108,7 @@ export function equalKind(refl: Reflection, kind: ReflectionKind) {
     equal(
         refl.kind,
         kind,
-        `Expected ${ReflectionKind[kind]} but got ${ReflectionKind[refl.kind]}`,
+        `Expected ${ReflectionKind[kind]} but got ${ReflectionKind[refl.kind]} for ${refl.getFullName()}`,
     );
 }