codeui-python 0.1.0__tar.gz → 0.1.1__tar.gz

{codeui_python-0.1.0 → codeui_python-0.1.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 codeui maintainers
+Copyright (c) 2026 Akram Alsubari 
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

codeui_python-0.1.1/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: codeui-python
+Version: 0.1.1
+Summary: Universal static analysis code intelligence library, defect detector, graph visualizer, and agent context builder
+Author-email: Akram Alsubari <akram.alsubari87@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/AAlsubari/codeUI
+Project-URL: Documentation, https://github.com/AAlsubari/codeUI#readme
+Project-URL: Repository, https://github.com/AAlsubari/codeUI.git
+Project-URL: Issues, https://github.com/AAlsubari/codeUI/issues
+Keywords: code-analysis,static-analysis,code-graph,ast,ai-agents,code-intelligence,llm-context,defect-detection
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# codeui-python 🌐⚡
+
+[![PyPI Version](https://img.shields.io/pypi/v/codeui-python.svg)](https://pypi.org/project/codeui-python/)
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code Style](https://img.shields.io/badge/code%20style-strict-green.svg)](https://github.com/AAlsubari/codeUI)
+
+**`codeui-python`** (`codeui`) is an open-source static analysis engine that converts any Python or polyglot software repository into a rich, **interactive web graph visualizer**, call-hierarchy tracer, defect detector, live code editor, and AI agent context builder.
+
+It safely parses codebases via AST (Abstract Syntax Tree) without ever executing or importing target code, producing a universal intermediate representation (IR) graph.
+
+📦 **PyPI Package**: [https://pypi.org/project/codeui-python/](https://pypi.org/project/codeui-python/)  
+🐙 **GitHub Repository**: [https://github.com/AAlsubari/codeUI](https://github.com/AAlsubari/codeUI)
+
+---
+
+## 🌟 Main Features
+
+### 1. 🕸️ Convert Any Project into an Interactive Graph
+Effortlessly explore your entire codebase as a force-directed, interactive visual dependency graph:
+- **Universal AST Parsing**: Maps modules, classes, functions, variables, imports, and calls across Python, TypeScript, Go, Rust, Java, .etc.
+- **Multi-Window Subgraph Workspaces**: Open symbols, modules, and call chains in floating, draggable windows.
+- **Cross-Usage Navigation**: Trace incoming/outgoing references across files in real time.
+
+### 2. 📝 Interactive Code Editor & Live Edits
+Edit and refactor code directly inside the graph UI (`http://127.0.0.1:3000`):
+- **Direct Disk Writing**: Save edits directly to your local source files on disk with a single click.
+- **In-Memory Shadow Overrides**: Test edits non-destructively in an in-memory shadow store with instant diff inspection before writing to disk.
+
+### 3. 🔍 Static Defect Detection Engine
+Includes 8 built-in static defect analyzers that identify structural code bugs before runtime:
+- `undefined`: Missing or undefined symbols and functions.
+- `dead_code`: Unreferenced private functions and unused module exports.
+- `unresolved_import`: Broken or unresolvable import statements.
+- `circular`: Cyclic dependency chains via Tarjan's Strongly Connected Components algorithm.
+- `duplicates`: Structural code clones and duplicate routines.
+- `unreachable`: Code paths following terminal control statements (`return`, `raise`, `exit`).
+- `shadowing`: Variable shadowing across nested lexical scopes.
+- `api_drift`: Public API signature changes and breaking contract drift against baseline snapshots.
+
+### 4. 🤖 AI Agent Context Engine 
+- **Smart Subgraph Bundling**: Extracts minimal, context-complete subgraphs for LLMs (Claude, GPT-4, Gemini) without token bloat.
+
+
+---
+
+## ⚠️ Initial Release Notice & Call for Contributions
+
+> **Note on Version 0.1.1**:  
+> `codeui-python` is currently in an **initial pre-release version**. Static analysis across complex, dynamic multi-language codebases is intricate, and you may encounter bugs, unparsed syntax edge cases, or unsupported language features.
+>
+> 🚀 **We Welcome All Contributions!**  
+> We actively invite developers, researchers, and open-source contributors to try `codeui-python`, report issues, submit feature requests, or open pull requests to help expand language support and parser capabilities.
+
+---
+
+## 📦 Installation
+
+Install the library via PyPI:
+
+```bash
+pip install codeui-python
+```
+
+Or install the development version from source:
+
+```bash
+git clone https://github.com/AAlsubari/codeUI.git
+cd codeUI
+pip install -e ".[dev]"
+```
+
+---
+
+## 🚀 Quickstart
+
+### 1. Launch Interactive Graph Visualizer
+
+Run `codeui serve` in any repository directory to open the interactive browser graph:
+
+```bash
+codeui serve . --port 3000
+```
+
+Then open `http://127.0.0.1:3000` in your browser to interactively explore, search, trace, and edit your code.
+
+### 2. Command Line Interface (CLI)
+
+```bash
+# Scan a codebase into a JSON graph representation
+codeui scan .
+
+# Trace forward execution dependencies for a symbol
+codeui trace "src/main.py::run" . --direction forward --depth 3
+
+# Generate minimal LLM Context Bundle for AI agents
+codeui context . --symbol "src/main.py::run"
+
+# Scan codebase for defects (SARIF format)
+codeui defects . --format sarif
+```
+
+### 3. Python API Usage
+
+```python
+from pathlib import Path
+from codeui.cli.main import scan_project
+from codeui.tracer.tracer import Tracer
+from codeui.agent.context import ContextBuilder
+
+# 1. Scan codebase into a Universal AST Graph (No code execution)
+graph = scan_project(Path("."))
+
+# 2. Perform Call Graph Tracing
+tracer = Tracer(graph)
+dependencies = list(tracer.forward("src/main.py::run"))
+
+# 3. Extract LLM Context Bundle for AI Agents
+builder = ContextBuilder(graph)
+bundle = builder.for_symbol("src/main.py::run", depth=2)
+print(bundle.to_json())
+```
+
+---
+
+## 📚 Documentation & Resources
+
+- [Quickstart Guide](./docs/quickstart.md)
+- [Python API Reference](./docs/api.md)
+- [AI Agent Integration & Context Engine](./docs/agent_integration.md)
+- [Architecture Overview](./docs/architecture.md)
+- [Static Analyzer & Defect Reference](./docs/analyzer_reference.md)
+- [Extending codeui](./docs/extending.md)
+
+---
+
+## 📄 License
+
+`codeui-python` is distributed under the [MIT License](./LICENSE). Copyright (c) 2026 Akram Alsubari and contributors.

codeui_python-0.1.1/README.md

@@ -0,0 +1,139 @@
+# codeui-python 🌐⚡
+
+[![PyPI Version](https://img.shields.io/pypi/v/codeui-python.svg)](https://pypi.org/project/codeui-python/)
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code Style](https://img.shields.io/badge/code%20style-strict-green.svg)](https://github.com/AAlsubari/codeUI)
+
+**`codeui-python`** (`codeui`) is an open-source static analysis engine that converts any Python or polyglot software repository into a rich, **interactive web graph visualizer**, call-hierarchy tracer, defect detector, live code editor, and AI agent context builder.
+
+It safely parses codebases via AST (Abstract Syntax Tree) without ever executing or importing target code, producing a universal intermediate representation (IR) graph.
+
+📦 **PyPI Package**: [https://pypi.org/project/codeui-python/](https://pypi.org/project/codeui-python/)  
+🐙 **GitHub Repository**: [https://github.com/AAlsubari/codeUI](https://github.com/AAlsubari/codeUI)
+
+---
+
+## 🌟 Main Features
+
+### 1. 🕸️ Convert Any Project into an Interactive Graph
+Effortlessly explore your entire codebase as a force-directed, interactive visual dependency graph:
+- **Universal AST Parsing**: Maps modules, classes, functions, variables, imports, and calls across Python, TypeScript, Go, Rust, Java, .etc.
+- **Multi-Window Subgraph Workspaces**: Open symbols, modules, and call chains in floating, draggable windows.
+- **Cross-Usage Navigation**: Trace incoming/outgoing references across files in real time.
+
+### 2. 📝 Interactive Code Editor & Live Edits
+Edit and refactor code directly inside the graph UI (`http://127.0.0.1:3000`):
+- **Direct Disk Writing**: Save edits directly to your local source files on disk with a single click.
+- **In-Memory Shadow Overrides**: Test edits non-destructively in an in-memory shadow store with instant diff inspection before writing to disk.
+
+### 3. 🔍 Static Defect Detection Engine
+Includes 8 built-in static defect analyzers that identify structural code bugs before runtime:
+- `undefined`: Missing or undefined symbols and functions.
+- `dead_code`: Unreferenced private functions and unused module exports.
+- `unresolved_import`: Broken or unresolvable import statements.
+- `circular`: Cyclic dependency chains via Tarjan's Strongly Connected Components algorithm.
+- `duplicates`: Structural code clones and duplicate routines.
+- `unreachable`: Code paths following terminal control statements (`return`, `raise`, `exit`).
+- `shadowing`: Variable shadowing across nested lexical scopes.
+- `api_drift`: Public API signature changes and breaking contract drift against baseline snapshots.
+
+### 4. 🤖 AI Agent Context Engine 
+- **Smart Subgraph Bundling**: Extracts minimal, context-complete subgraphs for LLMs (Claude, GPT-4, Gemini) without token bloat.
+
+
+---
+
+## ⚠️ Initial Release Notice & Call for Contributions
+
+> **Note on Version 0.1.1**:  
+> `codeui-python` is currently in an **initial pre-release version**. Static analysis across complex, dynamic multi-language codebases is intricate, and you may encounter bugs, unparsed syntax edge cases, or unsupported language features.
+>
+> 🚀 **We Welcome All Contributions!**  
+> We actively invite developers, researchers, and open-source contributors to try `codeui-python`, report issues, submit feature requests, or open pull requests to help expand language support and parser capabilities.
+
+---
+
+## 📦 Installation
+
+Install the library via PyPI:
+
+```bash
+pip install codeui-python
+```
+
+Or install the development version from source:
+
+```bash
+git clone https://github.com/AAlsubari/codeUI.git
+cd codeUI
+pip install -e ".[dev]"
+```
+
+---
+
+## 🚀 Quickstart
+
+### 1. Launch Interactive Graph Visualizer
+
+Run `codeui serve` in any repository directory to open the interactive browser graph:
+
+```bash
+codeui serve . --port 3000
+```
+
+Then open `http://127.0.0.1:3000` in your browser to interactively explore, search, trace, and edit your code.
+
+### 2. Command Line Interface (CLI)
+
+```bash
+# Scan a codebase into a JSON graph representation
+codeui scan .
+
+# Trace forward execution dependencies for a symbol
+codeui trace "src/main.py::run" . --direction forward --depth 3
+
+# Generate minimal LLM Context Bundle for AI agents
+codeui context . --symbol "src/main.py::run"
+
+# Scan codebase for defects (SARIF format)
+codeui defects . --format sarif
+```
+
+### 3. Python API Usage
+
+```python
+from pathlib import Path
+from codeui.cli.main import scan_project
+from codeui.tracer.tracer import Tracer
+from codeui.agent.context import ContextBuilder
+
+# 1. Scan codebase into a Universal AST Graph (No code execution)
+graph = scan_project(Path("."))
+
+# 2. Perform Call Graph Tracing
+tracer = Tracer(graph)
+dependencies = list(tracer.forward("src/main.py::run"))
+
+# 3. Extract LLM Context Bundle for AI Agents
+builder = ContextBuilder(graph)
+bundle = builder.for_symbol("src/main.py::run", depth=2)
+print(bundle.to_json())
+```
+
+---
+
+## 📚 Documentation & Resources
+
+- [Quickstart Guide](./docs/quickstart.md)
+- [Python API Reference](./docs/api.md)
+- [AI Agent Integration & Context Engine](./docs/agent_integration.md)
+- [Architecture Overview](./docs/architecture.md)
+- [Static Analyzer & Defect Reference](./docs/analyzer_reference.md)
+- [Extending codeui](./docs/extending.md)
+
+---
+
+## 📄 License
+
+`codeui-python` is distributed under the [MIT License](./LICENSE). Copyright (c) 2026 Akram Alsubari and contributors.

{codeui_python-0.1.0 → codeui_python-0.1.1}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codeui-python"
-version = "0.1.0"
+version = "0.1.1"
 description = "Universal static analysis code intelligence library, defect detector, graph visualizer, and agent context builder"
 readme = "README.md"
 authors = [
-    { name = "Akram Alsubari", email = "akramsubari@gmail.com" }
+    { name = "Akram Alsubari", email = "akram.alsubari87@gmail.com" }
 ]
 license = { text = "MIT" }
 requires-python = ">=3.10"
@@ -60,14 +60,15 @@ codeui = "codeui.cli.main:main"
 where = ["src"]
 include = ["codeui*"]
 
+[tool.setuptools.package-data]
+codeui = ["server/static/**/*", "server/static/*"]
+
 [tool.pytest.ini_options]
-pythonpath = ["src"]
 testpaths = ["tests"]
 addopts = "--doctest-modules"
 
 [tool.mypy]
 python_version = "3.10"
-mypy_path = "src"
 strict = true
 warn_return_any = true
 warn_unused_configs = true

{codeui_python-0.1.0 → codeui_python-0.1.1}/src/codeui/__init__.py

@@ -4,7 +4,7 @@ from codeui.core.graph import Graph
 from codeui.core.override import Override, OverrideKind, OverrideStore
 from codeui.core.repo import get_library_repo_url
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 
 __all__ = [
     "Location",

{codeui_python-0.1.0 → codeui_python-0.1.1}/src/codeui/agent/context.py

@@ -110,7 +110,9 @@ class ContextBuilder:
 
         relevant_findings = [
             f.to_dict() for f in self.graph.get_findings()
-            if f.symbol_id in {s.id for s in syms} or f.location.file_id == target_sym.location.file_id
+            if (f.symbol_id and f.symbol_id in {s.id for s in syms}) or (
+                f.location and target_sym.location and f.location.file_id == target_sym.location.file_id
+            )
         ]
 
         manifest = {
@@ -147,7 +149,7 @@ class ContextBuilder:
                 bodies[s.id] = f"{cm} {file_id}:{s.location.start_line if s.location else 1}\n{s.signature or s.name}"
         relevant_findings = [
             f.to_dict() for f in self.graph.get_findings()
-            if f.location.file_id == file_id
+            if f.location and f.location.file_id == file_id
         ]
         return ContextBundle(
             symbol_bodies=bodies,
@@ -189,6 +191,18 @@ class ContextBuilder:
             manifest={"query": task.query, "symbols": task.target_symbols, "files": task.target_files},
         )
 
+    def build_context(self, task: TaskSpec, depth: int = 1) -> ContextBundle:
+        """Alias for for_task to build context bundle.
+        Example:
+            >>> g = Graph()
+            >>> builder = ContextBuilder(g)
+            >>> spec = TaskSpec("Fix issue")
+            >>> bundle = builder.build_context(spec)
+            >>> "query" in bundle.manifest
+            True
+        """
+        return self.for_task(task, depth=depth)
+
     def for_defect(self, finding_id: str) -> ContextBundle:
         """Build context bundle targeting a specific defect finding.
         Example:
@@ -204,4 +218,6 @@ class ContextBuilder:
         f = matching[0]
         if f.symbol_id:
             return self.for_symbol(f.symbol_id, depth=1)
-        return self.for_file(f.location.file_id, depth=1)
+        if f.location and f.location.file_id:
+            return self.for_file(f.location.file_id, depth=1)
+        return ContextBundle({}, {}, [], [], {"finding_id": finding_id, "status": "no_location"})

{codeui_python-0.1.0 → codeui_python-0.1.1}/src/codeui/analysis/dead_code.py

@@ -3,7 +3,7 @@ from pathlib import Path
 from typing import ClassVar, Iterable, List, Set
 from codeui.analysis.base import AnalysisContext, Analyzer
 from codeui.core.graph import Graph
-from codeui.core.ir import EdgeKind, Finding, Location, Severity, SymbolKind, Visibility
+from codeui.core.ir import EdgeKind, Finding, LayerKind, Location, Severity, SymbolKind, Visibility
 
 class DeadCodeAnalyzer(Analyzer):
     """Detects unused functions, unused private symbols, and orphan files.
@@ -22,7 +22,10 @@ class DeadCodeAnalyzer(Analyzer):
         "__init__", "__post_init__", "__str__", "__repr__", "__eq__", "__hash__",
         "__iter__", "__getitem__", "__setitem__", "__delitem__", "__len__",
         "__contains__", "__enter__", "__exit__", "__call__", "__await__",
-        "constructor", "init", "dispose", "render", "setup", "teardown", "setUp", "tearDown"
+        "constructor", "init", "dispose", "render", "build", "initialize",
+        "setup", "teardown", "setUp", "tearDown", "beforeEach", "afterEach",
+        "beforeAll", "afterAll", "onCreate", "onDestroy", "onStart", "onStop",
+        "onResume", "onPause", "componentDidMount", "componentWillUnmount"
     }
 
     def run(self, graph: Graph, ctx: AnalysisContext) -> Iterable[Finding]:
@@ -43,6 +46,14 @@ class DeadCodeAnalyzer(Analyzer):
                 referenced_targets.add(raw_target.split(".")[-1])
 
         for sym in graph.get_all_symbols():
+            if sym.location and sym.location.file_id:
+                cls = graph.get_file_classification(sym.location.file_id)
+                if cls.layer in (LayerKind.TEST, LayerKind.CONFIG):
+                    continue
+                file_lower = sym.location.file_id.replace("\\", "/").lower()
+                if any(p in file_lower for p in ("/tests/", "/test/", "/benches/", "/bench/", "/examples/", "/example/", "/fixtures/")):
+                    continue
+
             if sym.kind in (SymbolKind.FUNCTION, SymbolKind.METHOD, SymbolKind.CLASS):
                 if sym.name in self.ENTRY_POINTS or any(sym.name.startswith(p) for p in self.ENTRY_POINTS):
                     continue

codeui_python-0.1.1/src/codeui/analysis/undefined.py

@@ -0,0 +1,167 @@
+"""Undefined symbol analyzer."""
+import builtins
+from pathlib import Path
+from typing import ClassVar, Iterable, List, Set
+from codeui.analysis.base import AnalysisContext, Analyzer
+from codeui.core.graph import Graph
+from codeui.core.ir import EdgeKind, Finding, Location, Severity
+
+class UndefinedSymbolAnalyzer(Analyzer):
+    """Detects references or calls to undefined symbols.
+    Example:
+        >>> analyzer = UndefinedSymbolAnalyzer()
+        >>> g = Graph()
+        >>> ctx = AnalysisContext(Path("."))
+        >>> list(analyzer.run(g, ctx))
+        []
+    """
+    id: ClassVar[str] = "undefined"
+    severity_default: ClassVar[Severity] = Severity.ERROR
+
+    PYTHON_BUILTINS = set(dir(builtins)) | {
+        "Optional", "List", "Dict", "Set", "Tuple", "Any", "Callable", "Union",
+        "Sequence", "Iterable", "Mapping", "Type", "ClassVar", "Literal", "Self",
+        "dataclass", "field", "asdict", "Path", "Enum", "auto", "StrEnum",
+    }
+
+    JS_BUILTINS = {
+        "console", "window", "document", "Math", "JSON", "Object", "Array", "String",
+        "Number", "Boolean", "Symbol", "Map", "Set", "WeakMap", "WeakSet", "Proxy",
+        "Reflect", "Promise", "Error", "TypeError", "RangeError", "SyntaxError",
+        "encodeURIComponent", "decodeURIComponent", "encodeURI", "decodeURI",
+        "fetch", "setTimeout", "clearTimeout", "setInterval", "clearInterval",
+        "Element", "HTMLElement", "Event", "CustomEvent", "URLSearchParams",
+        "FormData", "Headers", "Request", "Response", "Blob", "File", "FileReader",
+        "localStorage", "sessionStorage", "location", "history", "globalThis",
+        "process", "Buffer", "require", "exports", "module", "undefined", "NaN", "Infinity",
+    }
+
+    OTHER_BUILTINS = {
+        "fmt", "make", "new", "println", "println!", "format!", "vec!", "panic!",
+        "main", "self", "this", "super", "__name__", "__file__", "__doc__", "__all__"
+    }
+
+    BUILTINS = PYTHON_BUILTINS | JS_BUILTINS | OTHER_BUILTINS
+
+    def run(self, graph: Graph, ctx: AnalysisContext) -> Iterable[Finding]:
+        """Identify missing symbol references.
+        Example:
+            >>> analyzer = UndefinedSymbolAnalyzer()
+            >>> g = Graph()
+            >>> list(analyzer.run(g, AnalysisContext(Path("."))))
+            []
+        """
+        findings: List[Finding] = []
+        all_symbol_names = {s.name for s in graph.get_all_symbols()}
+        all_symbol_names.update(self.BUILTINS)
+        file_imports: dict[str, Set[str]] = {}
+        for edge in graph.get_edges():
+            if edge.kind == EdgeKind.IMPORTS:
+                src_file = edge.source_id.split("::")[0]
+                file_imports.setdefault(src_file, set())
+                raw_mod = edge.target_id.replace("module::", "")
+                imported = raw_mod.split(".")[-1]
+                file_imports[src_file].add(imported)
+                for part in raw_mod.split("."):
+                    file_imports[src_file].add(part)
+
+        for edge in graph.get_edges():
+            if edge.kind in (EdgeKind.CALLS, EdgeKind.REFERENCES):
+                target_id = edge.target_id
+                if target_id.startswith("module::"):
+                    continue
+                target_name = target_id.split("::")[-1]
+                src_file = edge.source_id.split("::")[0]
+
+                if "." in target_name:
+                    continue
+
+                local_names = set()
+                try:
+                    caller_sym = graph.get_symbol(edge.source_id)
+                    if caller_sym and caller_sym.kind in (SymbolKind.FUNCTION, SymbolKind.METHOD):
+                        file_path = ctx.root_dir / caller_sym.location.file_id
+                        if file_path.exists():
+                            import ast
+                            source = file_path.read_text(encoding="utf-8")
+                            tree = ast.parse(source)
+                            for node in ast.walk(tree):
+                                if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.lineno == caller_sym.location.start_line:
+                                    for arg in getattr(node.args, "posonlyargs", []) + getattr(node.args, "args", []) + getattr(node.args, "kwonlyargs", []):
+                                        if hasattr(arg, "arg"):
+                                            local_names.add(arg.arg)
+                                    if getattr(node.args, "vararg", None):
+                                        local_names.add(node.args.vararg.arg)
+                                    if getattr(node.args, "kwarg", None):
+                                        local_names.add(node.args.kwarg.arg)
+                                    
+                                    for subnode in ast.walk(node):
+                                        if isinstance(subnode, ast.Assign):
+                                            for target in subnode.targets:
+                                                if isinstance(target, ast.Name):
+                                                    local_names.add(target.id)
+                                                elif isinstance(target, (ast.Tuple, ast.List)):
+                                                    def _ext_names(t):
+                                                        res = set()
+                                                        if isinstance(t, ast.Name): res.add(t.id)
+                                                        elif isinstance(t, (ast.Tuple, ast.List)):
+                                                            for e in t.elts: res.update(_ext_names(e))
+                                                        return res
+                                                    local_names.update(_ext_names(target))
+                                        elif isinstance(subnode, ast.AnnAssign):
+                                            if isinstance(subnode.target, ast.Name):
+                                                local_names.add(subnode.target.id)
+                                        elif isinstance(subnode, (ast.For, ast.AsyncFor)):
+                                            def _ext_names(t):
+                                                res = set()
+                                                if isinstance(t, ast.Name): res.add(t.id)
+                                                elif isinstance(t, (ast.Tuple, ast.List)):
+                                                    for e in t.elts: res.update(_ext_names(e))
+                                                return res
+                                            local_names.update(_ext_names(subnode.target))
+                                        elif isinstance(subnode, (ast.With, ast.AsyncWith)):
+                                            for item in subnode.items:
+                                                if item.optional_vars:
+                                                    def _ext_names(t):
+                                                        res = set()
+                                                        if isinstance(t, ast.Name): res.add(t.id)
+                                                        elif isinstance(t, (ast.Tuple, ast.List)):
+                                                            for e in t.elts: res.update(_ext_names(e))
+                                                        return res
+                                                    local_names.update(_ext_names(item.optional_vars))
+                                        elif isinstance(subnode, ast.ExceptHandler):
+                                            if subnode.name:
+                                                local_names.add(subnode.name)
+                                        elif isinstance(subnode, (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)):
+                                            for gen in subnode.generators:
+                                                def _ext_names(t):
+                                                    res = set()
+                                                    if isinstance(t, ast.Name): res.add(t.id)
+                                                    elif isinstance(t, (ast.Tuple, ast.List)):
+                                                        for e in t.elts: res.update(_ext_names(e))
+                                                    return res
+                                                local_names.update(_ext_names(gen.target))
+                                    break
+                except Exception:
+                    pass
+
+                if (
+                    not graph.has_symbol(target_id)
+                    and target_name not in all_symbol_names
+                    and target_name not in file_imports.get(src_file, set())
+                    and target_name not in local_names
+                    and not target_name.startswith("_")
+                ):
+                    loc = edge.location or Location(edge.source_id, 1, 0, 1, 0)
+                    finding = Finding(
+                        id=f"undefined::{target_id}",
+                        rule_id="undefined_symbol",
+                        message=f"Undefined symbol '{target_name}' referenced",
+                        severity=self.severity_default,
+                        location=loc,
+                        symbol_id=edge.source_id,
+                        fix_hint=f"Define symbol '{target_name}' or import it from module",
+                        confidence=0.9,
+                    )
+                    findings.append(finding)
+        return findings