fix(semantic): stop following circular type declarations

When aliases or class parents point back to themselves, stop using that
loop for normal analysis instead of trying to expand it forever.

Pure alias loops now become any, and circular class parents are still
visible to the existing diagnostic.

Author: lewis6991

crates/emmylua_code_analysis/src/compilation/analyzer/doc/type_def_tags.rs

@@ -19,8 +19,7 @@ use crate::{
         LuaDeclId, LuaGenericParamInfo, LuaMemberId, LuaSemanticDeclId, LuaSignatureId, LuaType,
     },
 };
-use std::sync::Arc;
-use std::vec;
+use std::{collections::HashSet, sync::Arc, vec};
 
 pub fn analyze_class(analyzer: &mut DocAnalyzer, tag: LuaDocTagClass) -> Option<()> {
     let file_id = analyzer.file_id;
@@ -159,7 +158,10 @@ pub fn analyze_alias(analyzer: &mut DocAnalyzer, tag: LuaDocTagAlias) -> Option<
             .append_generic_params(scope_id, generic_params);
     }
 
-    let origin_type = infer_type(analyzer, tag.get_type()?);
+    let mut origin_type = infer_type(analyzer, tag.get_type()?);
+    if alias_origin_reaches(analyzer.db, &origin_type, &alias_decl_id) {
+        origin_type = LuaType::Any;
+    }
 
     let alias = analyzer
         .db
@@ -173,6 +175,40 @@ pub fn analyze_alias(analyzer: &mut DocAnalyzer, tag: LuaDocTagAlias) -> Option<
     Some(())
 }
 
+fn alias_origin_reaches(db: &crate::DbIndex, origin: &LuaType, target_id: &LuaTypeDeclId) -> bool {
+    // Collapse only pure alias chains. Structural recursive aliases can be
+    // meaningful, but `A = B; B = A` has no useful declaration skeleton.
+    let mut seen_aliases = HashSet::new();
+    let mut current = alias_chain_ref(origin);
+
+    while let Some(ref_id) = current {
+        if &ref_id == target_id {
+            return true;
+        }
+
+        if !seen_aliases.insert(ref_id.clone()) {
+            return false;
+        }
+
+        current = db
+            .get_type_index()
+            .get_type_decl(&ref_id)
+            .filter(|type_decl| type_decl.is_alias())
+            .and_then(|type_decl| type_decl.get_alias_ref())
+            .and_then(alias_chain_ref);
+    }
+
+    false
+}
+
+fn alias_chain_ref(typ: &LuaType) -> Option<LuaTypeDeclId> {
+    match typ {
+        LuaType::Ref(id) => Some(id.clone()),
+        LuaType::Generic(generic) => Some(generic.get_base_type_id()),
+        _ => None,
+    }
+}
+
 /// 分析属性定义
 pub fn analyze_attribute(analyzer: &mut DocAnalyzer, tag: LuaDocTagAttribute) -> Option<()> {
     let file_id = analyzer.file_id;

crates/emmylua_code_analysis/src/compilation/test/annotation_test.rs

@@ -125,6 +125,48 @@ mod test {
         ));
     }
 
+    #[test]
+    fn test_class_super_cycle_filters_query_supers() {
+        let mut ws = VirtualWorkspace::new();
+
+        assert!(!ws.check_code_for(
+            DiagnosticCode::CircleDocClass,
+            r#"
+            ---@class ClassCycleA: ClassCycleB
+            ---@class ClassCycleB: ClassCycleA
+            "#,
+        ));
+    }
+
+    #[test]
+    fn test_generic_class_super_cycle_reports_diagnostic() {
+        let mut ws = VirtualWorkspace::new();
+
+        assert!(!ws.check_code_for(
+            DiagnosticCode::CircleDocClass,
+            r#"
+            ---@class GenericCycleA<T>: GenericCycleB<T>
+            ---@class GenericCycleB<T>: GenericCycleA<T>
+            "#,
+        ));
+    }
+
+    #[test]
+    fn test_pure_alias_cycle_collapses_to_any() {
+        let mut ws = VirtualWorkspace::new();
+
+        ws.def(
+            r#"
+            ---@alias AliasCycleA AliasCycleB
+            ---@alias AliasCycleB AliasCycleA
+            ---@type AliasCycleA
+            AliasValue = nil
+            "#,
+        );
+
+        assert_eq!(ws.expr_ty("AliasValue.field"), ws.ty("any"));
+    }
+
     #[test]
     fn test_generic_type_extends() {
         let mut ws = VirtualWorkspace::new_with_init_std_lib();

crates/emmylua_code_analysis/src/db_index/type/mod.rs

@@ -329,18 +329,64 @@ impl LuaTypeIndex {
     }
 
     pub fn get_super_types(&self, decl_id: &LuaTypeDeclId) -> Option<Vec<LuaType>> {
+        self.get_super_types_iter(decl_id)
+            .map(|supers| supers.cloned().collect())
+    }
+
+    pub fn get_super_types_raw(&self, decl_id: &LuaTypeDeclId) -> Option<Vec<LuaType>> {
         self.supers
             .get(decl_id)
             .map(|supers| supers.iter().map(|s| s.value.clone()).collect())
     }
 
-    pub fn get_super_types_iter(
+    pub fn get_super_types_iter<'a>(
+        &'a self,
+        decl_id: &'a LuaTypeDeclId,
+    ) -> Option<impl Iterator<Item = &'a LuaType> + 'a> {
+        self.supers.get(decl_id).map(move |supers| {
+            let mut visited = HashSet::new();
+            supers.iter().map(|s| &s.value).filter(move |super_type| {
+                visited.clear();
+                !self.is_cyclic_super_edge(decl_id, super_type, &mut visited)
+            })
+        })
+    }
+
+    fn is_cyclic_super_edge(
         &self,
         decl_id: &LuaTypeDeclId,
-    ) -> Option<impl Iterator<Item = &LuaType> + '_> {
-        self.supers
-            .get(decl_id)
-            .map(|supers| supers.iter().map(|s| &s.value))
+        super_type: &LuaType,
+        visited: &mut HashSet<LuaTypeDeclId>,
+    ) -> bool {
+        let Some(super_id) = super_type_base_decl_id(super_type) else {
+            return false;
+        };
+
+        self.super_reaches(super_id, decl_id, visited)
+    }
+
+    fn super_reaches(
+        &self,
+        current_id: &LuaTypeDeclId,
+        target_id: &LuaTypeDeclId,
+        visited: &mut HashSet<LuaTypeDeclId>,
+    ) -> bool {
+        if current_id == target_id {
+            return true;
+        }
+
+        if !visited.insert(current_id.clone()) {
+            return false;
+        }
+
+        let Some(supers) = self.supers.get(current_id) else {
+            return false;
+        };
+
+        supers
+            .iter()
+            .filter_map(|super_type| super_type_base_decl_id(&super_type.value))
+            .any(|super_id| self.super_reaches(super_id, target_id, visited))
     }
 
     /// Get all direct subclasses of a given type
@@ -480,6 +526,14 @@ impl LuaTypeIndex {
     }
 }
 
+pub(crate) fn super_type_base_decl_id(super_type: &LuaType) -> Option<&LuaTypeDeclId> {
+    match super_type {
+        LuaType::Ref(id) => Some(id),
+        LuaType::Generic(generic) => Some(generic.get_base_type_id_ref()),
+        _ => None,
+    }
+}
+
 impl LuaIndex for LuaTypeIndex {
     fn remove(&mut self, file_id: FileId) {
         self.file_namespace.remove(&file_id);

crates/emmylua_code_analysis/src/diagnostic/checker/circle_doc_class.rs

@@ -3,7 +3,7 @@ use std::collections::HashSet;
 use emmylua_parser::{LuaAstNode, LuaAstToken, LuaDocTagClass};
 use rowan::TextRange;
 
-use crate::{DiagnosticCode, LuaType, SemanticModel};
+use crate::{DiagnosticCode, SemanticModel, super_type_base_decl_id};
 
 use super::{Checker, DiagnosticContext};
 
@@ -39,22 +39,21 @@ fn check_doc_tag_class(
         return Some(());
     }
 
-    let name = class_decl.get_full_name();
-
+    let class_id = class_decl.get_id();
     let mut queue = Vec::new();
     let mut visited = HashSet::new();
 
-    queue.push(class_decl.get_id());
+    queue.push(class_id.clone());
     while let Some(current_id) = queue.pop() {
         if !visited.insert(current_id.clone()) {
             continue;
         }
 
-        let super_types = type_index.get_super_types(&current_id);
+        let super_types = type_index.get_super_types_raw(&current_id);
         if let Some(super_types) = super_types {
             for super_type in super_types {
-                if let LuaType::Ref(super_type_id) = &super_type {
-                    if super_type_id.get_name() == name {
+                if let Some(super_type_id) = super_type_base_decl_id(&super_type) {
+                    if super_type_id == &class_id {
                         context.add_diagnostic(
                             DiagnosticCode::CircleDocClass,
                             get_lint_range(tag).unwrap_or(tag.get_range()),