MethodenAnalyser3.py

import argparse
import ast
import builtins
import codecs
import collections
import datetime
import difflib
import fnmatch
import json
import os
import pathlib
import pkgutil
import re
import sqlite3
import stat
import sys
import tempfile
import threading
import tkinter as tk
import warnings
from collections.abc import Callable
from dataclasses import dataclass, field
from functools import lru_cache
from tkinter import filedialog, messagebox, scrolledtext
from typing import Any

try:
    from translator import TranslationSystem, detect_system_language
except ImportError:  # pragma: no cover - Übersetzung ist optional
    TranslationSystem = None

    def detect_system_language(default: str = "de") -> str:
        return default

# ============================================================================
# KONSTANTEN
# ============================================================================

# GUI Konfiguration
WINDOW_GEOMETRY = "1200x700"

# Globale Variablen für Auto-Fix
_last_analysis_path: str = ""
_last_analysis_result: 'AnalysisResult' = None
OUTPUT_WIDTH = 140
OUTPUT_HEIGHT = 40
OUTPUT_FONT = ("Courier", 9)
APP_ICON_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), "MethodenAnalyser.ico")
TOOL_VERSION = "3.0"
__version__ = "3.0.2"
JSON_SCHEMA_VERSION = "methodenanalyser-report-v1"
DEFAULT_JSON_REPORT_NAME = f"{JSON_SCHEMA_VERSION}.json"

# CLI Exit-Codes
EXIT_OK = 0
EXIT_ANALYSIS_ERROR = 1
EXIT_FINDINGS = 2
EXIT_PARTIAL_ERROR = 3

# ============================================================================
# SPRACHE / KONFIGURATION (Welle-1 U1: sichtbarer DE/EN-Sprachschalter)
# ============================================================================

SUPPORTED_LANGUAGES = ("de", "en", "es", "zh", "ja", "ru")
DEFAULT_LANGUAGE = "de"

# Erste Zeile der Willkommensnachricht je Sprache (für Live-Neurendern beim Sprachwechsel)
_WELCOME_HEADS = (
    "Willkommen beim Python Code Analyzer!",
    "Welcome to Python Code Analyzer!",
    "¡Bienvenido a Python Code Analyzer!",
    "欢迎使用 Python 代码分析器！",
    "Python コードアナライザーへようこそ！",
    "Добро пожаловать в Python Code Analyzer!",
)


def _config_dir() -> pathlib.Path:
    """Per-User-Konfigverzeichnis (auch bei read-only Store-Installation schreibbar)."""
    if sys.platform.startswith("win"):
        base = os.environ.get("APPDATA") or os.path.expanduser("~")
    else:
        base = os.environ.get("XDG_CONFIG_HOME") or os.path.join(
            os.path.expanduser("~"), ".config"
        )
    return pathlib.Path(base) / "MethodenAnalyser"


def _config_path() -> pathlib.Path:
    return _config_dir() / "config.json"


def load_app_config() -> dict[str, Any]:
    """Liest die persistente App-Konfiguration (leer bei Fehlen/Korruption)."""
    try:
        with open(_config_path(), "r", encoding="utf-8") as handle:
            data = json.load(handle)
        return data if isinstance(data, dict) else {}
    except (OSError, ValueError):
        return {}


def save_app_config(config: dict[str, Any]) -> bool:
    """Speichert die App-Konfiguration; True bei Erfolg."""
    try:
        _config_dir().mkdir(parents=True, exist_ok=True)
        with open(_config_path(), "w", encoding="utf-8") as handle:
            json.dump(config, handle, indent=2, ensure_ascii=False)
        return True
    except OSError:
        return False


def get_saved_language() -> str:
    """Gespeicherte Sprache oder System-Locale, validiert gegen SUPPORTED_LANGUAGES."""
    config_lang = load_app_config().get("language")
    if config_lang in SUPPORTED_LANGUAGES:
        return config_lang
    detected = detect_system_language(DEFAULT_LANGUAGE)
    return detected if detected in SUPPORTED_LANGUAGES else DEFAULT_LANGUAGE


def set_saved_language(lang: str) -> bool:
    """Persistiert die gewaehlte Sprache in der App-Konfiguration."""
    if lang not in SUPPORTED_LANGUAGES:
        return False
    config = load_app_config()
    config["language"] = lang
    return save_app_config(config)


_TRANSLATOR = None


def get_translator():
    """Lazy-Singleton des TranslationSystem, mit gespeicherter Sprache initialisiert."""
    global _TRANSLATOR
    if _TRANSLATOR is None and TranslationSystem is not None:
        _TRANSLATOR = TranslationSystem(get_saved_language())
    return _TRANSLATOR


def _t(key: str) -> str:
    """Übersetzt key in die aktuelle Sprache (Fallback: key selbst)."""
    translator = get_translator()
    return translator.t(key) if translator is not None else key


def set_runtime_language(lang: str) -> bool:
    """Setzt die Sprache für einen einzelnen nicht-interaktiven Lauf ohne Persistenz."""
    translator = get_translator()
    return translator.set_language(lang) if translator is not None else False


# Analyse Konfiguration
SIMILARITY_THRESHOLD = 0.8

# Builtin Namen
BUILTINS = set(dir(builtins))

# Callback und Handler Suffixe
CALLBACK_SUFFIXES = (
    "_callback", "_fetch", "_stage", "_emit", "_process", "_task", "_async", "_handler"
)

# Framework-spezifische Methoden
COMMON_FRAMEWORK_METHODS = {
    "__enter__", "__exit__", "__eq__", "__hash__", "__init__",
    "__str__", "__repr__", "__len__", "__getitem__", "__setitem__",
    "on_start", "on_stop", "on_close", "on_refresh", "mainloop"
}

# Gängige GUI-Widgets
COMMON_WIDGETS = {
    "Button", "Label", "Frame", "Canvas", "Entry", "Text", "Scrollbar", "Treeview",
    "Menu", "MenuItem", "Checkbutton", "Radiobutton", "Scale", "Spinbox",
    "BooleanVar", "StringVar", "IntVar", "DoubleVar", "Listbox", "Combobox"
}

# Framework-Methoden Zuordnung
FRAMEWORK_MAP = {
    "LabelFrame": "tkinter", "Progressbar": "tkinter", "after": "tkinter",
    "after_idle": "tkinter", "grid": "tkinter", "pack": "tkinter",
    "rowconfigure": "tkinter", "columnconfigure": "tkinter",
    "update_idletasks": "tkinter", "update_menu": "tkinter", "winfo_children": "tkinter",
    "askopenfilename": "tkinter", "asksaveasfilename": "tkinter", "askyesno": "tkinter",
    "showerror": "tkinter", "showinfo": "tkinter", "showwarning": "tkinter",
    "tag_configure": "tkinter", "tag_add": "tkinter", "tag_remove": "tkinter",
    "ClientSession": "aiohttp", "ClientTimeout": "aiohttp",
    "Session": "requests", "HTTPAdapter": "requests", "raise_for_status": "requests",
    "Workbook": "openpyxl", "cell": "openpyxl", "load_workbook": "openpyxl",
    "Image": "PIL", "ImageDraw": "PIL", "Icon": "PIL", "Draw": "PIL",
    "drawString": "reportlab", "showPage": "reportlab", "setFont": "reportlab",
}

# Modul-zu-Attribut Mapping für Standard Library und häufige Third-Party
# Format: "modul": {"attribut1", "attribut2", ...}
STDLIB_EXPORTS = {
    # threading
    "threading": {
        "Thread", "Lock", "RLock", "Event", "Semaphore", "BoundedSemaphore",
        "Condition", "Timer", "Barrier", "current_thread", "active_count",
        "enumerate", "main_thread", "get_ident", "get_native_id"
    },
    # subprocess
    "subprocess": {
        "Popen", "PIPE", "STDOUT", "DEVNULL", "run", "call", "check_call",
        "check_output", "CompletedProcess", "CalledProcessError", "TimeoutExpired"
    },
    # io
    "io": {
        "BytesIO", "StringIO", "BufferedReader", "BufferedWriter", "TextIOWrapper",
        "BufferedRandom", "FileIO", "open", "SEEK_SET", "SEEK_CUR", "SEEK_END"
    },
    # gzip
    "gzip": {
        "GzipFile", "open", "compress", "decompress", "BadGzipFile"
    },
    # asyncio
    "asyncio": {
        "get_event_loop", "get_running_loop", "new_event_loop", "set_event_loop",
        "run", "create_task", "gather", "wait", "sleep", "timeout", "Queue",
        "Event", "Lock", "Semaphore", "run_coroutine_threadsafe", "run_until_complete"
    },
    # collections
    "collections": {
        "Counter", "OrderedDict", "defaultdict", "deque", "namedtuple",
        "ChainMap", "UserDict", "UserList", "UserString"
    },
    # concurrent.futures
    "concurrent": {
        "ThreadPoolExecutor", "ProcessPoolExecutor", "Future", "as_completed",
        "wait", "FIRST_COMPLETED", "ALL_COMPLETED", "Executor"
    },
    # traceback
    "traceback": {
        "format_exc", "format_exception", "print_exc", "print_exception",
        "extract_tb", "format_tb", "print_tb", "TracebackException"
    },
    # psutil
    "psutil": {
        "cpu_percent", "cpu_count", "virtual_memory", "swap_memory",
        "disk_usage", "disk_partitions", "net_io_counters", "Process",
        "pid_exists", "process_iter", "wait_procs", "NoSuchProcess"
    },
    # tkinter (Attribut-Zugriffe)
    "tkinter": {
        "Tk", "Frame", "Label", "Button", "Entry", "Text", "Canvas", "Scrollbar",
        "Menu", "Toplevel", "Listbox", "Checkbutton", "Radiobutton", "Scale",
        "Spinbox", "LabelFrame", "PanedWindow", "messagebox", "filedialog",
        "StringVar", "IntVar", "DoubleVar", "BooleanVar", "PhotoImage",
        # Methoden die oft via obj.method() aufgerufen werden
        "wait_window", "winfo_width", "winfo_height", "winfo_x", "winfo_y",
        "bind_all", "unbind_all", "grab_set", "grab_release", "destroy",
        "winfo_children", "create_window", "yview_scroll", "xview_scroll",
        "get_children", "identify_row", "identify_column", "trace_add",
        # Menu-Methoden
        "add_command", "add_cascade", "add_separator", "add_checkbutton",
        "add_radiobutton"
    },
    # openpyxl
    "openpyxl": {
        "Workbook", "load_workbook", "cell", "iter_rows", "get_column_letter",
        "styles", "chart", "worksheet", "utils"
    },
    # requests
    "requests": {
        "Session", "Request", "Response", "get", "post", "put", "delete",
        "head", "options", "patch", "HTTPAdapter", "iter_content", "raise_for_status"
    },
    # aiohttp
    "aiohttp": {
        "ClientSession", "ClientTimeout", "ClientError", "TCPConnector",
        "request", "get", "post", "put", "delete"
    },
    # Bio.Align (Biopython)
    "Bio": {
        "SeqIO", "AlignIO", "Align", "Seq", "SeqRecord", "PairwiseAligner"
    },
    # pyfaidx
    "pyfaidx": {
        "Faidx", "Fasta", "FastaRecord"
    },
    # intervaltree
    "intervaltree": {
        "Interval", "IntervalTree"
    },
    # PIL/Pillow
    "PIL": {
        "Image", "ImageDraw", "ImageFont", "ImageFilter", "ImageEnhance"
    },
    # myvariant
    "myvariant": {
        "MyVariantInfo", "get_client"
    },
}

# Kompilierte Regex-Patterns für dynamische Aufrufe
DYNAMIC_PATTERNS = {
    "getattr": re.compile(r"\bgetattr\s*\("),
    "setattr": re.compile(r"\bsetattr\s*\("),
    "globals": re.compile(r"\bglobals\s*\(\s*\)"),
    "locals": re.compile(r"\blocals\s*\(\s*\)"),
    "exec": re.compile(r"\bexec\s*\("),
    "eval": re.compile(r"\beval\s*\("),
    # Verbesserte Regex für bind - funktioniert auch mit Lambda
    "bind": re.compile(r"\.bind\s*\(\s*['\"]<[^>]+>['\"],?\s*(?:lambda[^:]*:\s*)?self\.(\w+)"),
    # Verbesserte Regex für command
    "command": re.compile(r"command\s*=\s*(?:lambda[^:]*:\s*)?self\.(\w+)"),
    # Thread-Target
    "ThreadTarget": re.compile(r"Thread\s*\([^)]*target\s*=\s*self\.(\w+)"),
}

# Case-Transition Pattern (für CamelCase Erkennung)
CASE_TRANSITION_PATTERN = re.compile(r'[a-z][A-Z]|[A-Z][a-z]')


# ============================================================================
# DATENKLASSEN
# ============================================================================

@dataclass
class AnalysisResult:
    """Struktur für Analyse-Ergebnisse mit konsistenten Typen."""
    # Listen statt Sets für UI-Darstellung
    calls: list[str]
    defs: list[str]
    imported_definitions: list[str]  # Explizit importierte Namen
    module_provided_attrs: list[str]  # NEU: Durch Module verfügbar gemachte Attribute
    missing_defs: list[str]
    unused_defs: list[str]
    imports: list[str]
    used_imports: list[str]
    unused_imports: list[str]
    duplicate_imports: list[str]
    missing_imports: list[str]
    dynamic_usage: list[str] = field(default_factory=list)
    dynamic_methods: list[str] = field(default_factory=list)
    check_builtins_and_stdlib: list[tuple[str, str]] = field(default_factory=list)
    framework_hooks: list[tuple[str, str]] = field(default_factory=list)
    import_scopes: dict[str, list[str]] = field(default_factory=dict)
    name_matches: list[tuple[str, str]] = field(default_factory=list)
    typehints: list[str] = field(default_factory=list)
    module_attribute_usage: dict[str, list[str]] = field(default_factory=dict)  # NEU: Modul → Attribute Mapping
    todo_comments: list[tuple[int, str, str]] = field(default_factory=list)  # (Zeile, Typ, Text)
    total_lines: int = 0


# ============================================================================
# AST VISITOR KLASSEN
# ============================================================================

class ImportScopeAnalyzer(ast.NodeVisitor):
    """Analysiert Imports nach Scope (Top-Level, Klasse, Methode)."""

    def __init__(self):
        self.top_level: set[str] = set()
        self.class_level: dict[str, set[str]] = collections.defaultdict(set)
        self.method_level: dict[str, set[str]] = collections.defaultdict(set)
        self.scope_stack: list[tuple[str, str]] = []

    def visit_Import(self, node: ast.Import) -> None:
        """Verarbeitet Import-Statements."""
        names = {alias.asname or alias.name.split(".")[0] for alias in node.names}
        self._assign_imports(names)
        self.generic_visit(node)

    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
        """Verarbeitet From-Import-Statements."""
        if node.module == "__future__":
            self.generic_visit(node)
            return
        names = {alias.asname or alias.name for alias in node.names if alias.name != "*"}
        if names:
            self._assign_imports(names)
        self.generic_visit(node)

    def visit_ClassDef(self, node: ast.ClassDef) -> None:
        """Verarbeitet Klassendefinitionen."""
        self.scope_stack.append(("class", node.name))
        self.generic_visit(node)
        self.scope_stack.pop()

    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
        """Verarbeitet Funktionsdefinitionen."""
        self.scope_stack.append(("func", node.name))
        self.generic_visit(node)
        self.scope_stack.pop()

    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
        """Verarbeitet asynchrone Funktionsdefinitionen."""
        self.scope_stack.append(("func", node.name))
        self.generic_visit(node)
        self.scope_stack.pop()

    def _assign_imports(self, names: set[str]) -> None:
        """Ordnet Imports dem aktuellen Scope zu (qualifizierter Pfad gegen Kollisionen)."""
        if not self.scope_stack:
            self.top_level |= names
        else:
            scope_type, _ = self.scope_stack[-1]
            qual_scope = ".".join(name for _, name in self.scope_stack)
            if scope_type == "class":
                self.class_level[qual_scope] |= names
            elif scope_type == "func":
                self.method_level[qual_scope] |= names


class CodeAnalyzer(ast.NodeVisitor):
    """Analysiert Aufrufe, Definitionen und Imports mit Attribut-Zugriff-Erkennung."""

    def __init__(self):
        self.calls: set[str] = set()
        self.defs: set[str] = set()
        self.imports: list[str] = []
        self.import_names: set[str] = set()
        self.imported_definitions: set[str] = set()
        self.used_names: set[str] = set()
        self.local_names: set[str] = set()
        # NEU: Track Modul.Attribut Zugriffe
        self.module_attribute_calls: dict[str, set[str]] = collections.defaultdict(set)
        self.imported_modules: set[str] = set()  # Nur Modulnamen (für import X)
        self.class_methods: dict[str, set[str]] = collections.defaultdict(set)

    def visit_Call(self, node: ast.Call) -> None:
        """Verarbeitet Funktionsaufrufe und erkennt Modul-Attribut-Zugriffe."""
        if isinstance(node.func, ast.Attribute):
            # Attribut-Aufruf: obj.method()
            attr_name = node.func.attr
            self.calls.add(attr_name)
            
            # Vollständige Attribut-Kette auflösen (z.B. concurrent.futures.ThreadPoolExecutor)
            root_id, chain = _extract_attribute_chain(node.func)
            if root_id and chain:
                self.module_attribute_calls[root_id].update(chain)
                for i in range(1, len(chain)):
                    subpath = f"{root_id}.{'.'.join(chain[:i])}"
                    self.module_attribute_calls[subpath].add(chain[i])
                    self.module_attribute_calls[subpath].update(chain[i:])
                
        elif isinstance(node.func, ast.Name):
            # Direkter Aufruf: function()
            self.calls.add(node.func.id)
            
        self.generic_visit(node)

    def visit_Attribute(self, node: ast.Attribute) -> None:
        """Verarbeitet Attribut-Zugriffe (auch ohne Call)."""
        root_id, chain = _extract_attribute_chain(node)
        if root_id and chain:
            self.module_attribute_calls[root_id].update(chain)
            for i in range(1, len(chain)):
                subpath = f"{root_id}.{'.'.join(chain[:i])}"
                self.module_attribute_calls[subpath].add(chain[i])
                self.module_attribute_calls[subpath].update(chain[i:])
        self.generic_visit(node)

    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
        """Verarbeitet Funktionsdefinitionen."""
        self.defs.add(node.name)
        self.generic_visit(node)

    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
        """Verarbeitet asynchrone Funktionsdefinitionen."""
        self.defs.add(node.name)
        self.generic_visit(node)

    def visit_ClassDef(self, node: ast.ClassDef) -> None:
        """Verarbeitet Klassendefinitionen."""
        self.defs.add(node.name)
        for item in node.body:
            if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
                self.class_methods[node.name].add(item.name)
        self.generic_visit(node)

    def visit_Import(self, node: ast.Import) -> None:
        """Verarbeitet Import-Statements und trackt importierte Namen."""
        for alias in node.names:
            module_base = alias.name.split(".")[0]
            self.imports.append(module_base)
            # Speichere den tatsächlich verwendbaren Namen (alias oder module)
            import_name = alias.asname if alias.asname else module_base
            self.import_names.add(import_name)
            self.imported_definitions.add(import_name)
            # Track auch Modulnamen für Attribut-Zugriff (inkl. Submodule & Aliase)
            if alias.asname:
                self.imported_modules.add(alias.asname)
            else:
                self.imported_modules.add(module_base)
                self.imported_modules.add(alias.name)

    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
        """Verarbeitet From-Import-Statements und trackt importierte Namen."""
        if node.module:
            module_base = node.module.split(".")[0]
            self.imports.append(module_base)
            self.imported_modules.add(module_base)
            self.imported_modules.add(node.module)
        else:
            # Relative Imports ohne Modulnamen (z.B. `from . import utils, config`)
            for alias in node.names:
                if alias.name != '*':
                    module_base = alias.name.split(".")[0]
                    self.imports.append(module_base)
                    self.imported_modules.add(module_base)
                    self.imported_modules.add(alias.name)
        
        # __future__-Features (z.B. 'annotations', 'division') sind Compiler-Direktiven,
        # keine aufrufbaren Symbole oder Variablen. Sie dürfen nicht als import_names
        # registriert werden, da sie sonst fälschlich als ungenutzt gemeldet werden.
        if node.module == "__future__":
            return

        # Füge die importierten Namen hinzu
        for alias in node.names:
            # Überspringe Wildcard-Imports
            if alias.name == '*':
                continue
            
            import_name = alias.asname if alias.asname else alias.name
            self.import_names.add(import_name)
            self.imported_definitions.add(import_name)
            self.imported_modules.add(import_name)

    def visit_Name(self, node: ast.Name) -> None:
        """Verarbeitet Namensreferenzen."""
        if isinstance(node.ctx, ast.Load):
            self.used_names.add(node.id)
        elif isinstance(node.ctx, ast.Store):
            self.local_names.add(node.id)
        self.generic_visit(node)

    def visit_arg(self, node: ast.arg) -> None:
        """Erfasst Funktionsparameter als lokale Namen."""
        self.local_names.add(node.arg)
        self.generic_visit(node)

    def visit_ExceptHandler(self, node: ast.ExceptHandler) -> None:
        """Erfasst Exception-Binding-Namen als lokale Namen."""
        if node.name:
            self.local_names.add(node.name)
        self.generic_visit(node)

    def visit_MatchAs(self, node: Any) -> None:
        """Erfasst Pattern-Matching Variable-Bindings als lokale Namen."""
        if getattr(node, "name", None):
            self.local_names.add(node.name)
        self.generic_visit(node)

    def visit_MatchStar(self, node: Any) -> None:
        """Erfasst Pattern-Matching Star-Bindings (*rest) als lokale Namen."""
        if getattr(node, "name", None):
            self.local_names.add(node.name)
        self.generic_visit(node)

    def visit_MatchMapping(self, node: Any) -> None:
        """Erfasst Pattern-Matching Mapping-Rest-Bindings (**rest) als lokale Namen."""
        if getattr(node, "rest", None):
            self.local_names.add(node.rest)
        self.generic_visit(node)

    def visit_Global(self, node: ast.Global) -> None:
        """Erfasst globale Variablen-Deklarationen als lokale Namen."""
        for name in node.names:
            self.local_names.add(name)
        self.generic_visit(node)

    def visit_Nonlocal(self, node: ast.Nonlocal) -> None:
        """Erfasst nonlocal Variablen-Deklarationen als lokale Namen."""
        for name in node.names:
            self.local_names.add(name)
        self.generic_visit(node)

    def visit_TypeVar(self, node: Any) -> None:
        """Erfasst PEP 695 TypeVar-Namen ([T]) als lokale Typ-Parameter."""
        if getattr(node, "name", None):
            self.local_names.add(node.name)
        self.generic_visit(node)

    def visit_TypeVarTuple(self, node: Any) -> None:
        """Erfasst PEP 695 TypeVarTuple-Namen ([*Ts]) als lokale Typ-Parameter."""
        if getattr(node, "name", None):
            self.local_names.add(node.name)
        self.generic_visit(node)

    def visit_ParamSpec(self, node: Any) -> None:
        """Erfasst PEP 695 ParamSpec-Namen ([**P]) als lokale Typ-Parameter."""
        if getattr(node, "name", None):
            self.local_names.add(node.name)
        self.generic_visit(node)

    def visit_TypeAlias(self, node: Any) -> None:
        """Erfasst PEP 695 TypeAlias-Definitionen (type X = ...) als Definition."""
        alias_name = getattr(node, "name", None)
        if isinstance(alias_name, ast.Name):
            self.defs.add(alias_name.id)
            self.local_names.add(alias_name.id)
        elif isinstance(alias_name, str):
            self.defs.add(alias_name)
            self.local_names.add(alias_name)
        self.generic_visit(node)



# ============================================================================
# HILFSFUNKTIONEN
# ============================================================================

def _extract_attribute_chain(node: ast.AST) -> tuple[str | None, list[str]]:
    """
    Extrahiert den Wurzel-Namen und die geordnete Kette von Attributen.
    Z.B. os.path.exists -> ('os', ['path', 'exists'])
    """
    chain: list[str] = []
    curr = node
    while isinstance(curr, ast.Attribute):
        chain.append(curr.attr)
        curr = curr.value
    if isinstance(curr, ast.Name):
        chain.reverse()
        return curr.id, chain
    return None, []


def has_case_transition(name: str) -> bool:
    """
    Prüft, ob Name CamelCase oder gemischte Schreibweise hat.
    
    Args:
        name: Zu prüfender Name
        
    Returns:
        True wenn CamelCase erkannt wurde
    """
    return bool(CASE_TRANSITION_PATTERN.search(name))


def scan_dynamic_usage(code: str) -> tuple[list[str], set[str]]:
    """
    Erkennt dynamische Methodenaufrufe (getattr, bind, command, etc.).
    
    Args:
        code: Python-Quellcode als String
        
    Returns:
        Tuple aus (gefundene Pattern-Namen, extrahierte Methodennamen)
    """
    dynamic_hits = []
    dynamic_methods = set()

    for name, pattern in DYNAMIC_PATTERNS.items():
        matches = pattern.findall(code)
        if matches:
            dynamic_hits.append(name)
            # Nur echte Bezeichner (Methodennamen) hinzufügen — Patterns ohne
            # Capture-Gruppe liefern den vollen Match inkl. '(' (z.B. 'getattr('),
            # die kein gueltiger Methodenname sind.
            for match in matches:
                if isinstance(match, str) and match and "(" not in match:
                    dynamic_methods.add(match)

    return dynamic_hits, dynamic_methods


@lru_cache(maxsize=1)
def build_stdlib_whitelist() -> set[str]:
    """
    Erstellt Whitelist für Standard-Library-Methoden.
    
    Returns:
        Set aller Builtin- und Standardbibliothek-Namen
    """
    wl = set(dir(builtins))

    # Standardbibliothek-Module
    if hasattr(sys, "stdlib_module_names"):
        wl |= sys.stdlib_module_names
    else:
        wl |= {m.name for m in pkgutil.iter_modules()}

    # Methoden von builtin Types
    builtin_types = [str, list, dict, set, tuple, int, float, bool, complex, bytes]
    for t in builtin_types:
        wl |= set(dir(t))

    # Wichtige Standardbibliothek-Objekte
    wl |= set(dir(datetime))
    wl |= set(dir(pathlib.Path))
    wl |= set(dir(sqlite3.Cursor))

    return wl


# Pre-warm Whitelist im Hintergrund (pkgutil.iter_modules ist langsam auf Python < 3.10)
_whitelist_prewarm = threading.Thread(
    target=build_stdlib_whitelist,
    daemon=True,
    name="stdlib-whitelist-prewarm"
)
_whitelist_prewarm.start()


def is_valid_missing_def(name: str) -> bool:
    """
    Prüft, ob ein Name als fehlende Definition gemeldet werden sollte.
    Unterstützt sowohl CamelCase als auch snake_case.
    
    Args:
        name: Zu prüfender Name
        
    Returns:
        True wenn der Name gemeldet werden sollte
    """
    # Private/Protected Namen überspringen
    if name.startswith("_"):
        return False

    # Technische Suffixe generell überspringen (eindeutig interne Patterns)
    if name.endswith(("_fetch", "_stage", "_emit", "_process", "_task", "_async")):
        return False

    # _callback/_handler nur in Framework-Kontext überspringen, nicht pauschal
    if name.endswith(("_callback", "_handler")) and name in FRAMEWORK_MAP:
        return False

    # Framework-Methoden überspringen
    if name in FRAMEWORK_MAP:
        return False
    
    # Namen mit mindestens 3 Zeichen und gültiger Struktur
    if len(name) >= 3:
        # CamelCase ODER snake_case erlauben
        has_camel = has_case_transition(name)
        has_snake = '_' in name and not name.startswith('_')
        return has_camel or has_snake
    
    return False


def filter_missing_defs(
    missing_defs: set[str],
    false_positives: set[str],
    typehints: set[str],
    whitelist: set[str],
) -> list[str]:
    """
    Filtert falsche Positive aus fehlenden Definitionen.
    
    Args:
        missing_defs: Set der potenziell fehlenden Definitionen
        false_positives: Set bekannter False Positives
        typehints: Set der Type-Hints
        whitelist: Set erlaubter Namen (Builtins, Stdlib)
        
    Returns:
        Sortierte Liste der tatsächlich fehlenden Definitionen
    """
    filtered = []
    for name in missing_defs:
        # Überspringe bekannte False Positives
        if name in false_positives or name in typehints or name in whitelist:
            continue
        
        # Prüfe mit verbesserter Logik
        if is_valid_missing_def(name):
            filtered.append(name)
    
    return sorted(filtered)


def filter_unused_defs(
    defs: set[str],
    calls: set[str],
    used_names: set[str],
    typehints: set[str],
    string_refs: set[str],
    framework_and_widgets: set[str],
    exported_class_methods: set[str] | None = None,
) -> list[str]:
    """
    Filtert echte ungenutzte Definitionen heraus und eliminiert False Positives.

    Eine Definition gilt als genutzt, wenn:
    - sie aufgerufen wird (calls)
    - sie als Name referenziert wird (z.B. Callback, Decorator, Basisklasse in used_names)
    - sie als Type-Hint verwendet wird (typehints)
    - sie in String-Literalen (z.B. __all__, Forward-Refs in string_refs) vorkommt
    - sie eine öffentliche Methode einer exportierten Klasse ist (exported_class_methods)
    - es sich um eine Magic/Dunder-Methode handelt (__init__, __str__, __enter__, etc.)
    - es sich um einen Framework-Hook (COMMON_FRAMEWORK_METHODS, on_*, visit_*) handelt
    """
    if exported_class_methods is None:
        exported_class_methods = set()

    unused = []
    for name in defs:
        # Aufrufe, Referenzen, Typ-Annotationen, __all__-Exports, Methoden exportierter Klassen
        if (
            name in calls
            or name in used_names
            or name in typehints
            or name in string_refs
            or name in exported_class_methods
        ):
            continue

        # Magic / Dunder-Methoden (__init__, __str__, __repr__, __enter__, etc.)
        if name.startswith("__") and name.endswith("__"):
            continue

        # Standard Framework-Methoden und Widgets
        if name in COMMON_FRAMEWORK_METHODS or name in framework_and_widgets:
            continue

        # Event-Handler und AST-Visitor-Hooks
        if name.startswith(("on_", "visit_")):
            continue

        unused.append(name)

    return sorted(unused)


_TODO_PATTERN = re.compile(
    r"#\s*(TODO|FIXME|HACK|NOTE|XXX)[:\s]+(.*)", re.IGNORECASE
)


def scan_todo_comments(code: str) -> list[tuple[int, str, str]]:
    """
    Scannt Quellcode nach TODO/FIXME/HACK/NOTE/XXX Kommentaren.

    Args:
        code: Python-Quellcode als String

    Returns:
        Liste von Tupeln (Zeilennummer, Typ, Text).
        Text wird nur gekürzt wenn er länger als 50 Zeichen ist.
    """
    results = []
    for lineno, line in enumerate(code.splitlines(), start=1):
        match = _TODO_PATTERN.search(line)
        if match:
            tag = match.group(1).upper()
            text = match.group(2).strip()
            if len(text) > 50:
                text = text[:50] + "..."
            results.append((lineno, tag, text))
    return results


@lru_cache(maxsize=128)
def _get_module_all_attributes(module_name: str) -> set[str] | None:
    """Liest Attribute bereits geladener Module, ohne Analyse-Imports auszuführen."""
    mod = sys.modules.get(module_name)
    if mod is None:
        return None
    return set(dir(mod))


def get_available_module_attributes(analyzer: 'CodeAnalyzer') -> set[str]:
    """
    Ermittelt alle Attribute, die durch importierte Module verfügbar sind.
    
    Wenn z.B. 'threading' importiert ist und Code 'threading.Lock()' oder
    'concurrent.futures.ThreadPoolExecutor()' verwendet, werden diese Attribute
    als verfügbar erkannt und nicht fälschlich als fehlende Definitionen gemeldet.
    
    Args:
        analyzer: CodeAnalyzer-Instanz mit Import- und Verwendungs-Informationen
        
    Returns:
        Set aller durch Module verfügbar gemachten Attributnamen
    """
    available_attrs = set()
    
    # Durchlaufe alle Modul.Attribut Zugriffe
    for module_name, attributes in analyzer.module_attribute_calls.items():
        base_mod = module_name.split(".")[0]
        is_imported = (
            module_name in analyzer.imported_modules
            or module_name in analyzer.import_names
            or base_mod in analyzer.imported_modules
            or base_mod in analyzer.import_names
        )
        if not is_imported:
            continue

        # 1. Sichere Introspektion ausschließlich bereits geladener Module
        mod_attrs = _get_module_all_attributes(module_name)

        if mod_attrs is not None:
            for attr in attributes:
                if attr in mod_attrs:
                    available_attrs.add(attr)
            continue

        # 2. Prüfe ob wir die Exports dieses Moduls aus statischer Tabelle kennen (Fallback)
        if module_name in STDLIB_EXPORTS or base_mod in STDLIB_EXPORTS:
            known_exports = STDLIB_EXPORTS.get(module_name, STDLIB_EXPORTS.get(base_mod, set()))
            matched = False
            for attr in attributes:
                if attr in known_exports:
                    available_attrs.add(attr)
                    matched = True
            if matched:
                continue

        # 3. Modul importiert aber offline / unbekannt → akzeptiere alle Attribute
        # (um False Positives bei externen Third-Party-Bibliotheken zu vermeiden)
        available_attrs.update(attributes)
    
    return available_attrs


# ============================================================================
# HAUPTANALYSE
# ============================================================================

def analyze_source(code: str, source_name: str = "<snippet>") -> AnalysisResult:
    """
    Führt komplette Analyse für Python-Quellcode aus.

    Args:
        code: Python-Quellcode als String
        source_name: Anzeigename für Fehlerkontext und JSON-Reports

    Returns:
        AnalysisResult mit allen Analyseergebnissen

    Raises:
        RuntimeError: Bei Parsing-Fehlern
    """
    # Code parsen (nur einmal!)
    try:
        tree = ast.parse(code, filename=source_name)
    except SyntaxError as e:
        raise RuntimeError(f"Syntax-Fehler in Zeile {e.lineno}: {e.msg}")
    except (ValueError, TypeError, RecursionError, MemoryError) as e:
        raise RuntimeError(f"Fehler beim Parsen: {e}") from e

    # AST-Analysen
    analyzer = CodeAnalyzer()
    analyzer.visit(tree)

    scope_analyzer = ImportScopeAnalyzer()
    scope_analyzer.visit(tree)

    # Dynamische Aufrufe scannen
    dynamic_hits, dynamic_methods = scan_dynamic_usage(code)

    # TODO-Kommentare scannen
    todo_comments = scan_todo_comments(code)

    # TypeHints extrahieren (verwendet bereits geparsten Tree!)
    typehints = _extract_typehints(tree)

    # Zusammengesetzte Mengen
    calls = analyzer.calls | dynamic_methods
    # FIX: Kombiniere echte Definitionen mit importierten Namen
    defs = analyzer.defs | analyzer.imported_definitions
    imports_unique = set(analyzer.imports)

    # NEU: Ermittle durch Module verfügbar gemachte Attribute
    module_provided_attrs = get_available_module_attributes(analyzer)

    # VERBESSERT: Berücksichtige Framework-Namen und Widgets
    framework_and_widgets = COMMON_FRAMEWORK_METHODS | COMMON_WIDGETS | set(FRAMEWORK_MAP.keys())

    # ERWEITERT: Berücksichtige auch Modul-Attribute
    missing_defs = (calls - defs) - BUILTINS - framework_and_widgets - module_provided_attrs

    # VERBESSERT: Nur tatsächliche Import-Namen vergleichen
    # FIX: Namen, die NUR als String-Literal vorkommen (z.B. __all__ = ["Foo"] oder
    # String-/Forward-Ref-Annotationen "Bar" / "List[Bar]"), erfasst die AST-Name-Analyse
    # NICHT als 'used' -> sie wuerden faelschlich als ungenutzt gemeldet und vom Auto-Fix
    # aus der echten Datei geloescht (NameError / fehlendes __all__-Public-API). Daher
    # alle in String-Literalen vorkommenden Bezeichner als genutzt behandeln (konservativ).
    _string_refs: set[str] = set()
    for _n in ast.walk(tree):
        if isinstance(_n, ast.Constant) and isinstance(_n.value, str):
            _string_refs.update(re.findall(r"[A-Za-z_][A-Za-z0-9_]*", _n.value))
    unused_imports = analyzer.import_names - analyzer.used_names - _string_refs

    # Öffentliche Methoden exportierter Klassen (in __all__) erfassen
    exported_class_methods: set[str] = set()
    for cls_name in (analyzer.defs & _string_refs):
        for method_name in analyzer.class_methods.get(cls_name, set()):
            if not method_name.startswith("_"):
                exported_class_methods.add(method_name)

    # BUGSWEEP 2026-09-22: False Positives bei unused_defs herausfiltern (Dunders,
    # Callbacks/Referenzen, TypeHints, __all__-Exports und Framework-Hooks)
    unused_defs = filter_unused_defs(
        defs=analyzer.defs,
        calls=calls,
        used_names=analyzer.used_names,
        typehints=typehints,
        string_refs=_string_refs,
        framework_and_widgets=framework_and_widgets,
        exported_class_methods=exported_class_methods,
    )

    # Whitelist und False-Positive-Checks
    whitelist = build_stdlib_whitelist()
    false_positives = {
        name for name in calls
        if (name.startswith("__") and name.endswith("__")) or
           name.isupper() or len(name) <= 2 or
           name in whitelist or name in framework_and_widgets or
           name.startswith("_") or name.endswith(CALLBACK_SUFFIXES)
    }

    # Endergebnisse
    check_builtins = [
        (name, "framework" if name in FRAMEWORK_MAP else "builtin")
        for name in sorted(false_positives)
    ]

    framework_hooks = [
        (name, "magic" if name.startswith("__") else "handler")
        for name in sorted(defs)
        if name.startswith(("__", "on_"))
    ]

    # Import-Scopes analysieren
    import_scopes = _analyze_import_scopes(scope_analyzer, analyzer, _string_refs)

    # Name-Matching mit verbesserter Lesbarkeit
    name_matches = _find_name_matches(calls, defs)

    # VERBESSERT: missing_imports berücksichtigt Framework-Namen
    missing_imports = (
        analyzer.used_names - defs - imports_unique -
        calls - analyzer.local_names - BUILTINS - framework_and_widgets - module_provided_attrs
    )
    # Module-level Dunders (__file__, __name__, __doc__ etc.) sind implizit
    # verfügbar, aber nicht in dir(builtins) — Falsch-Positive herausfiltern
    missing_imports = {
        name for name in missing_imports
        if not (name.startswith("__") and name.endswith("__"))
    }

    return AnalysisResult(
        calls=sorted(calls),
        defs=sorted(analyzer.defs),  # Nur echte Definitionen
        imported_definitions=sorted(analyzer.imported_definitions),  # Importierte Namen
        module_provided_attrs=sorted(module_provided_attrs),  # NEU: Modul-Attribute
        missing_defs=filter_missing_defs(missing_defs, false_positives, typehints, whitelist),
        unused_defs=sorted(unused_defs),
        imports=sorted(imports_unique),
        used_imports=sorted(analyzer.import_names & analyzer.used_names),
        unused_imports=sorted(unused_imports),
        duplicate_imports=[
            imp for imp, cnt in collections.Counter(analyzer.imports).items() if cnt > 1
        ],
        missing_imports=sorted(missing_imports),
        dynamic_usage=dynamic_hits,
        dynamic_methods=sorted(dynamic_methods),
        check_builtins_and_stdlib=check_builtins,
        framework_hooks=framework_hooks,
        import_scopes=import_scopes,
        name_matches=name_matches,
        typehints=sorted(typehints),
        module_attribute_usage={  # NEU: Modul-Attribut Usage
            mod: sorted(attrs) for mod, attrs in analyzer.module_attribute_calls.items()
            if mod in analyzer.imported_modules or mod in analyzer.import_names
        },
        todo_comments=todo_comments,
        total_lines=len(code.splitlines()),
    )


def analyze_file(path: str) -> AnalysisResult:
    """
    Führt komplette Analyse einer Python-Datei durch.

    Args:
        path: Pfad zur zu analysierenden Python-Datei

    Returns:
        AnalysisResult mit allen Analyseergebnissen

    Raises:
        RuntimeError: Bei Lese- oder Parsing-Fehlern
        FileNotFoundError: Wenn Datei nicht existiert
    """
    # Validierung
    if not os.path.exists(path):
        raise FileNotFoundError(f"Datei nicht gefunden: {path}")

    if not os.path.isfile(path):
        raise RuntimeError(f"Pfad ist keine Datei: {path}")

    # Datei lesen
    try:
        with open(path, "r", encoding="utf-8-sig") as f:
            code = f.read()
    except UnicodeDecodeError:
        try:
            # Fallback zu latin-1
            with open(path, "r", encoding="latin-1") as f:
                code = f.read()
            warnings.warn(
                f"Datei '{path}' konnte nicht als UTF-8 gelesen werden. "
                "latin-1 Fallback wurde verwendet -- Analyse-Ergebnisse können Artefakte enthalten.",
                UnicodeWarning,
                stacklevel=2,
            )
        except (OSError, UnicodeError) as e:
            raise RuntimeError(f"Fehler beim Lesen der Datei: {e}") from e
    except (OSError, UnicodeError) as e:
        raise RuntimeError(f"Fehler beim Lesen der Datei: {e}") from e

    return analyze_source(code, source_name=path)


def _extract_typehints(tree: ast.AST) -> set[str]:
    """
    Extrahiert verwendete Type-Hints aus bereits geparstem AST.
    
    Args:
        tree: Bereits geparster AST
        
    Returns:
        Set der verwendeten Type-Hint-Namen
    """
    hints: set[str] = set()
    try:
        for node in ast.walk(tree):
            # Variable Annotationen
            if isinstance(node, ast.AnnAssign) and node.annotation or isinstance(node, ast.arg) and node.annotation:
                for sub in ast.walk(node.annotation):
                    if isinstance(sub, ast.Name):
                        hints.add(sub.id)
            # Funktions-Return-Annotationen
            elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.returns:
                for sub in ast.walk(node.returns):
                    if isinstance(sub, ast.Name):
                        hints.add(sub.id)
            # Python 3.12+ type-Statement (TypeAlias)
            elif hasattr(ast, "TypeAlias") and isinstance(node, ast.TypeAlias) and node.value:
                for sub in ast.walk(node.value):
                    if isinstance(sub, ast.Name):
                        hints.add(sub.id)
            # Python 3.12+ PEP 695 TypeVar-Bounds
            elif hasattr(ast, "TypeVar") and isinstance(node, ast.TypeVar) and getattr(node, "bound", None):
                for sub in ast.walk(node.bound):
                    if isinstance(sub, ast.Name):
                        hints.add(sub.id)
    except Exception as e:  # noqa: BLE001 -- optional AST enrichment reports errors without aborting analysis
        # Logge Fehler, aber breche nicht ab
        print(f"Warnung beim Extrahieren von Type-Hints: {e}", file=sys.stderr)
    
    return hints


def _find_name_matches(calls: set[str], defs: set[str]) -> list[tuple[str, str]]:
    """
    Findet ähnliche Namen zwischen Aufrufen und Definitionen.
    
    Args:
        calls: Set der aufgerufenen Namen
        defs: Set der definierten Namen
        
    Returns:
        Liste von Tupeln (aufruf, ähnliche_definition)
    """
    matches = []
    sorted_defs = sorted(defs)
    for call in sorted(calls):
        if call in defs:
            continue
        
        similar = difflib.get_close_matches(
            call, sorted_defs, n=1, cutoff=SIMILARITY_THRESHOLD
        )
        
        if similar:
            matches.append((call, similar[0]))
    
    return sorted(matches)


def _analyze_import_scopes(
    scope_analyzer: ImportScopeAnalyzer, 
    analyzer: CodeAnalyzer,
    string_refs: set[str] | None = None,
) -> dict[str, list[str]]:
    """
    Analysiert Import-Scopes und gibt Empfehlungen.
    
    Args:
        scope_analyzer: ImportScopeAnalyzer-Instanz
        analyzer: CodeAnalyzer-Instanz
        string_refs: Optionale Menge von Bezeichnern in String-Literalen
        
    Returns:
        Dictionary mit Scope-Analyse-Ergebnissen
    """
    top = scope_analyzer.top_level
    all_class = (
        set.union(*scope_analyzer.class_level.values()) 
        if scope_analyzer.class_level else set()
    )
    all_methods = (
        set.union(*scope_analyzer.method_level.values()) 
        if scope_analyzer.method_level else set()
    )
    used_all = analyzer.used_names | (string_refs or set())

    results = {
        "multi_local": sorted(
            imp for imp in (all_class | all_methods)
            if imp not in top and
            sum(imp in v for v in scope_analyzer.class_level.values()) +
            sum(imp in v for v in scope_analyzer.method_level.values()) > 1
        ),
        "redundant_local": sorted(
            imp for imp in top 
            if imp in all_class or imp in all_methods
        ),
        "unused_global": sorted(
            imp for imp in top
            if imp not in used_all and 
               imp not in all_class and 
               imp not in all_methods
        ),
    }
    return results


# ============================================================================
# ERGEBNISSE FORMATIEREN
# ============================================================================

def generate_report(result: AnalysisResult) -> str:
    """
    Generiert einen formatierten Report.
    
    Args:
        result: AnalysisResult-Objekt
        
    Returns:
        Formatierter Report als String
    """
    report = []

    report.append("=" * 70 + "\n")
    report.append(_t("cli_report_title") + "\n")
    report.append("=" * 70 + "\n\n")

    # Hauptergebnisse
    report.append("[ANALYSE] " + _t("cli_main_results").upper() + "\n")
    report.append("-" * 70 + "\n")
    report.append(f"{_t('cli_missing_definitions')} ({len(result.missing_defs)}):\n")
    report.append(f"  {', '.join(result.missing_defs) if result.missing_defs else _t('cli_none')}\n\n")
    
    report.append(f"{_t('cli_unused_definitions')} ({len(result.unused_defs)}):\n")
    report.append(f"  {', '.join(result.unused_defs) if result.unused_defs else _t('cli_none')}\n\n")
    
    report.append(f"{_t('cli_unused_imports')} ({len(result.unused_imports)}):\n")
    report.append(f"  {', '.join(result.unused_imports) if result.unused_imports else _t('cli_none')}\n\n")
    report.append(f"{_t('cli_missing_imports')} ({len(result.missing_imports)}):\n")
    report.append(f"  {', '.join(result.missing_imports) if result.missing_imports else _t('cli_none')}\n\n")

    # Import-Analyse
    if result.import_scopes:
        report.append(f"\n{_t('cli_section_import_scopes')}\n")
        report.append("-" * 70 + "\n")
        
        scopes = result.import_scopes
        multi = scopes.get('multi_local', [])
        redundant = scopes.get('redundant_local', [])
        unused_global = scopes.get('unused_global', [])
        
        if multi:
            report.append(f"{_t('cli_multi_local_imported')}\n  {', '.join(multi)}\n\n")
        if redundant:
            report.append(f"{_t('cli_redundant_local_imported')}\n  {', '.join(redundant)}\n\n")
        if unused_global:
            report.append(f"{_t('cli_unused_global_imports')}\n  {', '.join(unused_global)}\n\n")

    # Duplikate
    if result.duplicate_imports:
        report.append(f"\n{_t('cli_section_duplicate_imports')}\n")
        report.append("-" * 70 + "\n")
        report.append(f"  {', '.join(result.duplicate_imports)}\n\n")

    # Dynamische Aufrufe
    if result.dynamic_usage:
        report.append(f"\n{_t('cli_section_dynamic_calls')}\n")
        report.append("-" * 70 + "\n")
        report.append(f"{_t('cli_detected_patterns')} {', '.join(result.dynamic_usage)}\n")
        if result.dynamic_methods:
            report.append(f"{_t('cli_extracted_methods')} {', '.join(result.dynamic_methods)}\n")
        report.append("\n")

    # Namens-Matches
    if result.name_matches:
        report.append(f"\n{_t('cli_section_name_matches')}\n")
        report.append("-" * 70 + "\n")
        for call, match in result.name_matches:
            report.append(f"  '{call}' -> {_t('cli_maybe')} '{match}'?\n")
        report.append("\n")

    # Statistik
    report.append(f"\n{_t('cli_section_stats')}\n")
    report.append("-" * 70 + "\n")
    report.append(f"  {_t('cli_total_calls')} {len(result.calls)}\n")
    report.append(f"  {_t('cli_total_definitions')} {len(result.defs)}\n")
    report.append(f"  {_t('cli_imported_definitions')} {len(result.imported_definitions)}\n")
    report.append(f"  {_t('cli_module_provided_attrs')} {len(result.module_provided_attrs)}\n")
    report.append(f"  {_t('cli_total_imports')} {len(result.imports)}\n")
    report.append(f"  {_t('cli_framework_hooks')} {len(result.framework_hooks)}\n")
    report.append(f"  {_t('cli_typehints')} {len(result.typehints)}\n")

    # Optional: Zeige importierte Definitionen wenn gewünscht
    if result.imported_definitions:
        report.append(f"\n{_t('cli_section_imported_definitions')}\n")
        report.append("-" * 70 + "\n")
        # Gruppiere nach Typ für bessere Lesbarkeit
        classes = [name for name in result.imported_definitions if name[0].isupper()]
        functions = [name for name in result.imported_definitions if name[0].islower()]
        
        if classes:
            report.append(f"  {_t('cli_classes_types')} ({len(classes)}): {', '.join(sorted(classes)[:20])}")
            if len(classes) > 20:
                report.append(f" ... +{len(classes) - 20} {_t('cli_more')}")
            report.append("\n")
        
        if functions:
            report.append(f"  {_t('cli_functions')} ({len(functions)}): {', '.join(sorted(functions)[:20])}")
            if len(functions) > 20:
                report.append(f" ... +{len(functions) - 20} {_t('cli_more')}")
            report.append("\n")

    # NEU: Zeige Modul-Attribut Usage
    if result.module_attribute_usage:
        report.append(f"\n{_t('cli_section_module_attr_usage')}\n")
        report.append("-" * 70 + "\n")
        report.append(f"  {_t('cli_module_attr_desc')}\n\n")
        
        for module, attrs in sorted(result.module_attribute_usage.items())[:10]:
            attrs_str = ', '.join(sorted(attrs)[:10])
            if len(attrs) > 10:
                attrs_str += f' ... +{len(attrs) - 10} ' + _t('cli_more')
            report.append(f"  {module}: {attrs_str}\n")
        
        if len(result.module_attribute_usage) > 10:
            report.append(f"  ... {_t('cli_and_more')} {len(result.module_attribute_usage) - 10} {_t('cli_more')}\n")

    # TODO-Kommentare
    if result.todo_comments:
        report.append(f"\n{_t('cli_section_todos')} ({len(result.todo_comments)})\n")
        report.append("-" * 70 + "\n")
        for lineno, tag, text in result.todo_comments:
            report.append(f"  {_t('cli_line')} {lineno:4d}: [{tag}] {text}\n")

    report.append("\n" + "=" * 70 + "\n")

    return "".join(report)


# ============================================================================
# GUI
# ============================================================================

def create_safe_filename(original_path: str, suffix: str) -> str:
    """
    Erstellt sicheren Export-Dateinamen ohne bestehende Dateien zu überschreiben.
    
    Args:
        original_path: Ursprünglicher Dateipfad
        suffix: Suffix für neue Datei (z.B. "_analysis.txt")
        
    Returns:
        Sicherer Dateipfad
    """
    # VERBESSERT: Verwende rsplit statt replace
    base_path = original_path.rsplit(".py", 1)[0]
    export_path = f"{base_path}{suffix}"
    
    # Wenn Datei existiert, nummeriere
    counter = 1
    while os.path.lexists(export_path):
        export_path = f"{base_path}_{counter}{suffix}"
        counter += 1
    
    return export_path


def run_analysis(output_widget: scrolledtext.ScrolledText, status_widget: tk.Label | None = None) -> None:
    """
    Lädt Datei und führt Analyse durch.
    
    Args:
        output_widget: ScrolledText-Widget für Ausgabe
        status_widget: Optionales Statusleisten-Widget für Statusanzeigen
    """
    path = filedialog.askopenfilename(
        title=_t("dialog_select_file"),
        filetypes=[(_t("dialog_filetypes_py"), "*.py"), (_t("dialog_filetypes_all"), "*.*")]
    )
    
    if not path:
        return
    if status_widget is not None:
        status_widget.config(text=_t("status_analyzing_file"))
        status_widget.update_idletasks()
    try:
        result = analyze_file(path)
        # Für Auto-Fix speichern
        global _last_analysis_path, _last_analysis_result
        _last_analysis_path = path
        _last_analysis_result = result
    except FileNotFoundError as e:
        output_widget.delete("1.0", tk.END)
        output_widget.insert(tk.END, f"[FEHLER] {e}")
        if status_widget is not None:
            status_widget.config(text=f"[FEHLER] {e}")
        messagebox.showerror(_t("dialog_file_error_title"), str(e))
        return
    except RuntimeError as e:
        output_widget.delete("1.0", tk.END)
        output_widget.insert(tk.END, f"[FEHLER] {e}")
        if status_widget is not None:
            status_widget.config(text=f"[FEHLER] {e}")
        messagebox.showerror(_t("dialog_analysis_error_title"), str(e))
        return
    except Exception as e:  # noqa: BLE001 -- GUI boundary reports unexpected analysis failures to the user
        output_widget.delete("1.0", tk.END)
        output_widget.insert(tk.END, f"[FEHLER] {_t('dialog_unexpected_error')}: {e}")
        if status_widget is not None:
            status_widget.config(text=f"[FEHLER] {e}")
        messagebox.showerror(_t("dialog_error_title"), f"{_t('dialog_unexpected_error')}: {e}")
        return

    # Ergebnisse anzeigen ([DATEI]-Tag via _t('gui_analyzed_file'))
    output_widget.delete("1.0", tk.END)
    output_widget.insert(tk.END, f"{_t('gui_analyzed_file')}: {os.path.basename(path)}\n\n")
    output_widget.insert(tk.END, generate_report(result))

    # Export mit Bestätigung
    try:
        text = (
            f"{_t('gui_analyzed_file')}: {path}\n"
            f"{_t('gui_date')}: {datetime.datetime.now().astimezone().strftime('%Y-%m-%d %H:%M:%S')}\n\n"
            + generate_report(result)
        )
        while True:
            export_path = create_safe_filename(path, "_analysis.txt")
            try:
                _write_report_bytes(text.encode("utf-8"), export_path, exclusive=True, label="Text")
            except FileExistsError:
                continue
            break
        
        output_widget.insert(tk.END, f"\n{_t('gui_report_saved')}: {export_path}")
        if status_widget is not None:
            status_widget.config(text=f"{_t('status_analysis_done')} {os.path.basename(path)}")

    except PermissionError:
        output_widget.insert(tk.END, f"\n{_t('gui_no_permission_export')}")
        if status_widget is not None:
            status_widget.config(text=_t("gui_no_permission_export"))
        messagebox.showwarning(_t("dialog_export_error_title"), _t("dialog_export_no_permission"))
    except Exception as e:  # noqa: BLE001 -- GUI boundary reports export failures to the user
        output_widget.insert(tk.END, f"\n{_t('gui_export_error')}: {e}")
        if status_widget is not None:
            status_widget.config(text=f"{_t('gui_export_error')}: {e}")
        messagebox.showwarning(_t("dialog_export_error_title"), str(e))




def _unused_import_nodes(tree: ast.AST, unused_set: set[str]) -> list[ast.stmt]:
    """Find fully unused imports, excluding wildcard and future imports."""
    nodes: list[ast.stmt] = []
    for node in ast.walk(tree):
        if isinstance(node, (ast.Import, ast.ImportFrom)):
            # __future__-Imports niemals entfernen — sie aendern Python-Semantik
            # (z.B. 'from __future__ import annotations' aktiviert PEP 563)
            if isinstance(node, ast.ImportFrom) and node.module == "__future__":
                continue
            names = [alias.asname or alias.name.split(".")[0] for alias in node.names
                     if alias.name != "*"]
            if names and all(name in unused_set for name in names):
                nodes.append(node)
    return nodes


def _collect_unused_import_lines(tree: ast.AST, unused_set: set[str]) -> set[int]:
    """Gibt die Zeilennummern vollständig ungenutzter Imports zurück."""
    return {line for node in _unused_import_nodes(tree, unused_set)
            for line in range(node.lineno, node.end_lineno + 1)}


def _remove_unused_imports(source: str, tree: ast.AST, unused_set: set[str]) -> tuple[str, set[int]]:
    """Remove AST import spans without deleting neighboring executable code."""
    raw = source.encode("utf-8")
    offsets = [0]
    # AST columns count UTF-8 bytes. Recognize physical CR/LF boundaries
    # without counting form-feed or rewriting untouched newline sequences.
    offsets.extend(match.end() for match in re.finditer(rb"\r\n|\r|\n", raw))
    nodes = sorted(_unused_import_nodes(tree, unused_set),
                   key=lambda node: (node.lineno, node.col_offset), reverse=True)
    changed_lines: set[int] = set()
    for node in nodes:
        start = offsets[node.lineno - 1] + node.col_offset
        end = offsets[node.end_lineno - 1] + node.end_col_offset
        line_start = offsets[node.lineno - 1]
        line_end = offsets[node.end_lineno] if node.end_lineno < len(offsets) else len(raw)
        standalone = (not raw[line_start:start].strip(b" \t\f")
                      and not raw[end:line_end].strip())
        candidate = raw[:line_start] + raw[line_end:] if standalone else None
        if candidate is not None:
            try:
                ast.parse(candidate.decode("utf-8"))
            except SyntaxError:
                candidate = None
        # A pass keeps inline suites, empty function bodies and semicolon
        # separators valid while leaving their neighboring statements intact.
        raw = candidate if candidate is not None else raw[:start] + b"pass" + raw[end:]
        changed_lines.update(range(node.lineno, node.end_lineno + 1))
    updated = raw.decode("utf-8")
    ast.parse(updated)  # Validate the complete result before touching any file.
    return updated, changed_lines


def _stage_auto_fix_bytes(path: pathlib.Path, data: bytes) -> pathlib.Path:
    """Fully write and flush a same-directory temporary file."""
    staged = None
    complete = False
    try:
        with tempfile.NamedTemporaryFile(mode="wb", dir=path.parent,
                                         prefix=f".{path.name}.autofix-", delete=False) as handle:
            staged = pathlib.Path(handle.name)
            if handle.write(data) != len(data):
                raise OSError("Incomplete Auto-Fix write")
            handle.flush()
            os.fsync(handle.fileno())
        complete = True
        return staged
    finally:
        if staged is not None and not complete:
            staged.unlink(missing_ok=True)


def _commit_auto_fix(path: str, original: bytes, updated: bytes) -> str:
    """Publish a complete backup exclusively, then atomically replace the source."""
    source = pathlib.Path(path).resolve(strict=True)
    mode = stat.S_IMODE(source.stat().st_mode)
    staged_source = staged_backup = None
    try:
        staged_source = _stage_auto_fix_bytes(source, updated)
        staged_backup = _stage_auto_fix_bytes(source, original)
        if source.read_bytes() != original:
            raise OSError("Source changed during Auto-Fix")
        index = 0
        while True:
            suffix = f".bak.{index}" if index else ".bak"
            backup = pathlib.Path(str(source) + suffix)
            try:
                # Same-directory hard-link publication is atomic and exclusive:
                # an existing or concurrently created recovery copy is preserved.
                os.link(staged_backup, backup)
            except FileExistsError:
                index += 1
            else:
                break
        os.chmod(staged_source, mode)
        if source.read_bytes() != original:
            raise OSError("Source changed during Auto-Fix")
        os.replace(staged_source, source)
        return str(backup)
    finally:
        for staged in (staged_source, staged_backup):
            if staged is not None:
                try:
                    # A staged source may carry the original read-only flag.
                    # Clear it only on our temporary path before cleanup.
                    staged.chmod(stat.S_IRUSR | stat.S_IWUSR)
                except FileNotFoundError:
                    continue
                staged.unlink(missing_ok=True)


def auto_fix_unused_imports(output_widget: scrolledtext.ScrolledText, status_widget: tk.Label | None = None) -> None:
    """
    Entfernt ungenutzte Imports aus der zuletzt analysierten Datei.
    
    Args:
        output_widget: ScrolledText-Widget für Ausgabe
        status_widget: Optionales Statusleisten-Widget für Statusanzeigen
    """
    if not _last_analysis_path or not _last_analysis_result:
        if status_widget is not None:
            status_widget.config(text=_t("dialog_no_file_msg"))
        messagebox.showwarning(_t("dialog_no_file_title"), _t("dialog_no_file_msg"))
        return
    
    if not _last_analysis_result.unused_imports:
        if status_widget is not None:
            status_widget.config(text=_t("status_no_unused_imports"))
        messagebox.showinfo(_t("dialog_no_unused_title"), _t("dialog_no_unused_msg"))
        return
    
    # Bestätigung
    unused_list = ", ".join(_last_analysis_result.unused_imports)
    prompt_text = _t("dialog_autofix_prompt").replace("{unused_list}", unused_list)
    if not messagebox.askyesno(
        _t("dialog_autofix_title"),
        prompt_text
    ):
        return
    
    try:
        # Datei lesen mit Encoding-Fallback — erkanntes Encoding für Schreibzugriff merken
        detected_encoding = "utf-8"
        original_bytes = pathlib.Path(_last_analysis_path).read_bytes()
        if original_bytes.startswith(codecs.BOM_UTF8):
            detected_encoding = "utf-8-sig"
        try:
            original_text = original_bytes.decode(detected_encoding)
        except UnicodeDecodeError:
            detected_encoding = "latin-1"
            original_text = original_bytes.decode("latin-1")
        # Parse the original text; physical byte offsets preserve mixed
        # newline sequences and avoid treating form-feed as a new line.
        tree = ast.parse(original_text)

        # Import-Zeilen markieren die entfernt werden sollen
        # Findings may be stale after an editor change or the confirmation
        # dialog. Remove only names approved earlier AND still unused now.
        current_result = analyze_source(original_text, _last_analysis_path)
        unused_set = set(_last_analysis_result.unused_imports) & set(current_result.unused_imports)
        updated_source, lines_to_remove = _remove_unused_imports(original_text, tree, unused_set)

        if not lines_to_remove:
            if status_widget is not None:
                status_widget.config(text=_t("status_no_unused_imports"))
            messagebox.showinfo(
                _t("dialog_partial_unused_title"),
                _t("dialog_partial_unused_msg"),
            )
            return

        # Backup und Ausgabe im erkannten Encoding — verhindert Korrumpierung von
        # latin-1-Dateien mit nicht-ASCII-Zeichen und # coding: latin-1 Deklaration
        updated_bytes = updated_source.encode(detected_encoding)
        backup_path = _commit_auto_fix(_last_analysis_path, original_bytes, updated_bytes)
        
        # Ausgabe
        output_widget.insert(tk.END, f"\n\n{_t('gui_autofix_success_header')}\n")
        output_widget.insert(tk.END, f"{_t('gui_removed_lines')}: {sorted(lines_to_remove)}\n")
        output_widget.insert(tk.END, f"{_t('gui_backup_created')}: {backup_path}\n")
        output_widget.insert(tk.END, f"\n{_t('gui_reanalyze_prompt')}")
        if status_widget is not None:
            status_widget.config(text=_t("status_autofix_done"))
        
        messagebox.showinfo(_t("dialog_success_title"), f"{_t('dialog_autofix_success')}\nBackup: {backup_path}")
        
    except Exception as e:  # noqa: BLE001 -- GUI boundary reports cleanup failures to the user
        if status_widget is not None:
            status_widget.config(text=f"[FEHLER] {e}")
        messagebox.showerror(_t("dialog_error_title"), f"{_t('dialog_autofix_failed')}: {e}")




# ============================================================================
# MULTI-FILE / PROJEKT-ANALYSE
# ============================================================================

DEFAULT_EXCLUDE_PATTERNS: list[str] = [
    "__pycache__", ".git", ".venv", "venv", "env",
    "node_modules", ".eggs", "build", "dist"
]


def _should_exclude_path(
    py_file: pathlib.Path,
    rel_posix: str,
    patterns: list[str],
    case_insensitive: bool = False,
) -> bool:
    """Prüft, ob eine Python-Datei durch Ausschlussmuster ignoriert werden soll."""
    file_name = py_file.name
    parts = list(py_file.parts)
    if case_insensitive:
        file_name_cmp = file_name.lower()
        parts_cmp = [p.lower() for p in parts]
        rel_cmp = rel_posix.lower()
    else:
        file_name_cmp = file_name
        parts_cmp = parts
        rel_cmp = rel_posix

    for pat in patterns:
        pat_clean = pat.replace("\\", "/").strip().rstrip("/")
        if not pat_clean:
            continue
        pat_cmp = pat_clean.lower() if case_insensitive else pat_clean

        # 1. Pfad-spezifisches Muster mit Schrägstrich (z.B. 'tests/fixtures', 'build/*', 'docs/html')
        if "/" in pat_cmp:
            if fnmatch.fnmatch(rel_cmp, pat_cmp):
                return True
            if fnmatch.fnmatch(rel_cmp, f"{pat_cmp}/*"):
                return True
            if rel_cmp == pat_cmp or rel_cmp.startswith(f"{pat_cmp}/"):
                return True
            continue

        # 2. Einzelner Bezeichner oder Wildcard (z.B. 'build', '__pycache__', 'test_*', '*.tmp.py')
        for part in parts_cmp:
            if fnmatch.fnmatch(part, pat_cmp):
                return True

        if fnmatch.fnmatch(file_name_cmp, pat_cmp):
            return True

        if fnmatch.fnmatch(rel_cmp, pat_cmp):
            return True

    return False


def collect_python_files(folder_path: str, exclude_patterns: list[str] | None = None) -> list[str]:
    """Sammelt alle Python-Dateien in einem Ordner rekursiv mit Verzeichnis-Pruning."""
    if not os.path.exists(folder_path):
        raise FileNotFoundError(f"Projekt-Verzeichnis nicht gefunden: {folder_path}")
    if not os.path.isdir(folder_path):
        raise NotADirectoryError(f"Projekt-Pfad ist kein Verzeichnis: {folder_path}")

    if exclude_patterns is None:
        exclude_patterns = DEFAULT_EXCLUDE_PATTERNS

    python_files = []
    folder = pathlib.Path(folder_path).resolve()
    case_insensitive = (os.name == "nt")

    for root, dirs, files in os.walk(folder):
        root_path = pathlib.Path(root)
        try:
            rel_dir_posix = root_path.relative_to(folder).as_posix()
        except ValueError:
            rel_dir_posix = ""

        # In-Place Directory-Pruning: überspringe unerwünschte Verzeichnisse vor dem Betreten
        pruned_dirs = []
        for d in dirs:
            dir_path = root_path / d
            rel_sub_posix = f"{rel_dir_posix}/{d}" if rel_dir_posix and rel_dir_posix != "." else d
            if not _should_exclude_path(dir_path, rel_sub_posix, exclude_patterns, case_insensitive=case_insensitive):
                pruned_dirs.append(d)
        dirs[:] = pruned_dirs

        for f in files:
            if not f.endswith(".py"):
                continue
            py_file = root_path / f
            rel_posix = f"{rel_dir_posix}/{f}" if rel_dir_posix and rel_dir_posix != "." else f
            if not _should_exclude_path(py_file, rel_posix, exclude_patterns, case_insensitive=case_insensitive):
                python_files.append(str(py_file))

    return sorted(python_files)


@dataclass
class ProjectAnalysisResult:
    """Aggregierte Ergebnisse einer Projekt-Analyse."""
    folder_path: str
    files_analyzed: int
    files_with_errors: list[tuple[str, str]]
    total_lines: int
    total_defs: int
    total_imports: int
    all_unused_imports: dict[str, list[str]]
    all_unused_defs: dict[str, list[str]]
    all_missing_defs: dict[str, list[str]]
    all_missing_imports: dict[str, list[str]]
    all_duplicate_imports: dict[str, list[str]]
    file_results: dict[str, AnalysisResult]


def analyze_project(
    folder_path: str,
    progress_callback=None,
    exclude_patterns: list[str] | None = None,
) -> ProjectAnalysisResult:
    """Analysiert alle Python-Dateien in einem Projektordner."""
    # The collector resolves aliases (e.g. /var -> /private/var on macOS,
    # or Windows junctions). Reports must use the same canonical base.
    folder_path = str(pathlib.Path(folder_path).resolve())
    python_files = collect_python_files(folder_path, exclude_patterns=exclude_patterns)
    files_with_errors, file_results = [], {}
    all_unused_imports, all_unused_defs = {}, {}
    all_missing_defs, all_missing_imports, all_duplicate_imports = {}, {}, {}
    total_lines, total_defs, total_imports = 0, 0, 0
    
    for i, file_path in enumerate(python_files):
        if progress_callback:
            progress_callback(i + 1, len(python_files), file_path)
        try:
            result = analyze_file(file_path)
            file_results[file_path] = result
            total_defs += len(result.defs)
            total_imports += len(result.imports)
            total_lines += getattr(result, "total_lines", 0)
            rel_path = os.path.relpath(file_path, folder_path)
            if result.unused_imports:
                all_unused_imports[rel_path] = result.unused_imports
            if result.unused_defs:
                all_unused_defs[rel_path] = result.unused_defs
            if result.missing_defs:
                all_missing_defs[rel_path] = result.missing_defs
            if result.missing_imports:
                all_missing_imports[rel_path] = result.missing_imports
            if result.duplicate_imports:
                all_duplicate_imports[rel_path] = result.duplicate_imports
        except Exception as e:  # noqa: BLE001 -- project scan isolates failures per file and records each error
            files_with_errors.append((file_path, str(e)))
    
    return ProjectAnalysisResult(
        folder_path=folder_path, files_analyzed=len(python_files) - len(files_with_errors),
        files_with_errors=files_with_errors, total_lines=total_lines,
        total_defs=total_defs, total_imports=total_imports,
        all_unused_imports=all_unused_imports, all_unused_defs=all_unused_defs,
        all_missing_defs=all_missing_defs, all_missing_imports=all_missing_imports,
        all_duplicate_imports=all_duplicate_imports,
        file_results=file_results
    )


def _extract_project_display_name(path: str) -> str:
    """Extrahiert einen sauberen Anzeigenamen für ein Projektverzeichnis."""
    if not path or not path.strip():
        return ""
    clean = path.strip()
    norm = os.path.normpath(clean)
    base = os.path.basename(norm)
    if not base or base == ".":
        abs_norm = os.path.normpath(os.path.abspath(clean))
        base = os.path.basename(abs_norm)
    return base


def generate_project_report(
    result: ProjectAnalysisResult,
    project_name: str | None = None,
) -> str:
    """Generiert einen formatierten Projekt-Report."""
    proj_name = (
        project_name.strip()
        if project_name and project_name.strip()
        else _extract_project_display_name(result.folder_path)
    )
    report = ["=" * 70 + "\n", _t("cli_project_report_title") + "\n", "=" * 70 + "\n\n"]
    report.append(f"{_t('cli_project')}: {proj_name}\n\n")
    report.append(f"{_t('cli_files')}: {result.files_analyzed} | {_t('cli_lines')}: {result.total_lines:,}\n")
    report.append(f"{_t('cli_definitions')}: {result.total_defs:,} | {_t('cli_imports')}: {result.total_imports:,}\n\n")
    
    total_ui = sum(len(v) for v in result.all_unused_imports.values())
    total_ud = sum(len(v) for v in result.all_unused_defs.values())
    report.append(f"{_t('cli_unused_imports')}: {total_ui} | {_t('cli_unused_definitions')}: {total_ud}\n\n")
    
    if result.all_unused_imports:
        report.append(f"{_t('cli_unused_imports').upper()}:\n" + "-" * 50 + "\n")
        for fp, imps in sorted(result.all_unused_imports.items()):
            report.append(f"  {fp}: {', '.join(imps)}\n")
    
    if result.all_unused_defs:
        report.append(f"\n{_t('cli_unused_definitions').upper()}:\n" + "-" * 50 + "\n")
        for fp, defs in sorted(result.all_unused_defs.items()):
            report.append(f"  {fp}: {', '.join(defs)}\n")

    if result.all_missing_defs:
        report.append(f"\n{_t('cli_missing_definitions').upper()}:\n" + "-" * 50 + "\n")
        for fp, defs in sorted(result.all_missing_defs.items()):
            report.append(f"  {fp}: {', '.join(defs)}\n")

    if result.all_missing_imports:
        report.append(f"\n{_t('cli_missing_imports').upper()}:\n" + "-" * 50 + "\n")
        for fp, imports in sorted(result.all_missing_imports.items()):
            report.append(f"  {fp}: {', '.join(imports)}\n")

    if result.all_duplicate_imports:
        report.append(f"\n{_t('cli_duplicate_imports_title')}\n" + "-" * 50 + "\n")
        for fp, imports in sorted(result.all_duplicate_imports.items()):
            report.append(f"  {fp}: {', '.join(imports)}\n")

    if result.files_with_errors:
        report.append(f"\n{_t('cli_files_with_errors')}:\n" + "-" * 50 + "\n")
        for fp, error in sorted(result.files_with_errors):
            try:
                disp_path = os.path.relpath(fp, result.folder_path) if os.path.isabs(fp) else fp
            except ValueError:
                disp_path = fp
            report.append(f"  {disp_path}: {error}\n")

    score = max(0, 100 - total_ui * 2 - total_ud * 2)
    report.append(f"\n{'=' * 70}\n{_t('cli_score')}: {score}/100\n{'=' * 70}\n")
    return "".join(report)


def _generated_at_iso() -> str:
    """Erzeugt einen stabilen UTC-Zeitstempel für JSON-Reports."""
    return (
        datetime.datetime.now(datetime.timezone.utc)
        .replace(microsecond=0)
        .isoformat()
        .replace("+00:00", "Z")
    )


def _todo_comments_as_dicts(result: AnalysisResult) -> list[dict[str, Any]]:
    """Wandelt TODO-Kommentare in JSON-kompatible Objekte um."""
    return [
        {"line": lineno, "tag": tag, "text": text}
        for lineno, tag, text in result.todo_comments
    ]


def _analysis_summary(result: AnalysisResult) -> dict[str, int]:
    """Verdichtete Metriken für eine einzelne Analyse."""
    return {
        "calls": len(result.calls),
        "definitions": len(result.defs),
        "imports": len(result.imports),
        "unused_imports": len(result.unused_imports),
        "unused_definitions": len(result.unused_defs),
        "missing_definitions": len(result.missing_defs),
        "missing_imports": len(result.missing_imports),
        "duplicate_imports": len(result.duplicate_imports),
        "todos": len(result.todo_comments),
    }


def _analysis_result_to_json(result: AnalysisResult) -> dict[str, Any]:
    """Serialisiert ein Dateiergebnis in das Austauschformat."""
    return {
        "summary": _analysis_summary(result),
        "calls": result.calls,
        "definitions": result.defs,
        "imported_definitions": result.imported_definitions,
        "imports": result.imports,
        "used_imports": result.used_imports,
        "unused_imports": result.unused_imports,
        "unused_definitions": result.unused_defs,
        "missing_definitions": result.missing_defs,
        "missing_imports": result.missing_imports,
        "duplicate_imports": result.duplicate_imports,
        "dynamic_usage": result.dynamic_usage,
        "dynamic_methods": result.dynamic_methods,
        "framework_hooks": [
            {"name": name, "kind": kind}
            for name, kind in result.framework_hooks
        ],
        "import_scopes": result.import_scopes,
        "name_matches": [
            {"name": name, "candidate": candidate}
            for name, candidate in result.name_matches
        ],
        "typehints": result.typehints,
        "module_attribute_usage": result.module_attribute_usage,
        "todos": _todo_comments_as_dicts(result),
    }


def _json_file_entry(path: str, result: AnalysisResult) -> dict[str, Any]:
    """Erstellt einen files[]-Eintrag für den JSON-Report."""
    return {
        "path": path,
        "analysis": _analysis_result_to_json(result),
    }


def _project_summary(result: ProjectAnalysisResult) -> dict[str, int]:
    """Verdichtete Metriken für eine Projektanalyse."""
    return {
        "files_analyzed": result.files_analyzed,
        "files_with_errors": len(result.files_with_errors),
        "total_lines": result.total_lines,
        "total_definitions": result.total_defs,
        "total_imports": result.total_imports,
        "unused_imports": sum(len(v) for v in result.all_unused_imports.values()),
        "unused_definitions": sum(len(v) for v in result.all_unused_defs.values()),
        "missing_definitions": sum(len(v) for v in result.all_missing_defs.values()),
        "missing_imports": sum(len(v) for v in result.all_missing_imports.values()),
        "duplicate_imports": sum(len(v) for v in result.all_duplicate_imports.values()),
    }


def build_json_report(
    source_kind: str,
    result: AnalysisResult | ProjectAnalysisResult,
    source_name: str | None = None,
) -> dict[str, Any]:
    """
    Baut `methodenanalyser-report-v1.json` für Datei, Projekt oder Snippet.

    Das Format ist bewusst stabil und PWA-freundlich: keine absoluten Pfade in
    files[], Textreports bleiben unabhängig davon unverändert.
    """
    if source_kind not in {"file", "project", "snippet", "zip"}:
        raise ValueError(f"Unbekannte source_kind: {source_kind}")

    report: dict[str, Any] = {
        "schema_version": JSON_SCHEMA_VERSION,
        "tool_version": TOOL_VERSION,
        "source_kind": source_kind,
        "generated_at": _generated_at_iso(),
        "source": {"name": source_name or source_kind},
        "files": [],
        "unused_imports": {},
        "unused_definitions": {},
        "missing_definitions": {},
        "missing_imports": {},
        "duplicate_imports": {},
        "summary": {},
    }

    if isinstance(result, ProjectAnalysisResult):
        source_root = result.folder_path
        if source_name and source_name.strip():
            source_label = _extract_project_display_name(source_name)
        else:
            source_label = _extract_project_display_name(source_root)

        def normalize(value: str) -> str:
            return value.replace("\\", "/")

        report["source"] = {"name": source_label, "kind": source_kind}
        report["files"] = [
            _json_file_entry(normalize(os.path.relpath(path, source_root)), file_result)
            for path, file_result in sorted(result.file_results.items())
        ]
        report["unused_imports"] = {
            normalize(path): values for path, values in sorted(result.all_unused_imports.items())
        }
        report["unused_definitions"] = {
            normalize(path): values for path, values in sorted(result.all_unused_defs.items())
        }
        report["missing_definitions"] = {
            normalize(path): values for path, values in sorted(result.all_missing_defs.items())
        }
        report["missing_imports"] = {
            normalize(path): values for path, values in sorted(result.all_missing_imports.items())
        }
        report["duplicate_imports"] = {
            normalize(path): values for path, values in sorted(result.all_duplicate_imports.items())
        }
        def _safe_relpath(p: str) -> str:
            if not os.path.isabs(p):
                return normalize(p)
            try:
                return normalize(os.path.relpath(p, source_root))
            except ValueError:
                return normalize(p)

        report["errors"] = [
            {
                "path": _safe_relpath(path),
                "message": message,
            }
            for path, message in result.files_with_errors
        ]
        report["summary"] = _project_summary(result)
        return report

    file_key = source_name or ("<snippet>" if source_kind == "snippet" else "file.py")
    if source_kind == "file":
        file_key = os.path.basename(os.path.normpath(file_key)) or os.path.basename(file_key)

    report["files"] = [_json_file_entry(file_key, result)]
    report["unused_imports"] = {file_key: result.unused_imports}
    report["unused_definitions"] = {file_key: result.unused_defs}
    report["missing_definitions"] = {file_key: result.missing_defs}
    report["missing_imports"] = {file_key: result.missing_imports}
    report["duplicate_imports"] = {file_key: result.duplicate_imports}
    report["summary"] = _analysis_summary(result)
    return report


def _resolve_json_export_path(output_path: str) -> str:
    """
    Löst einen Exportpfad robust auf: Verzeichnisse und Pfade mit Slash
    werden automatisch mit DEFAULT_JSON_REPORT_NAME ergänzt.
    """
    clean = output_path.strip()
    if clean.endswith(("/", "\\")) or (os.path.exists(clean) and os.path.isdir(clean)):
        return os.path.join(clean, DEFAULT_JSON_REPORT_NAME)
    return clean


def write_json_report(report: dict[str, Any], output_path: str) -> str:
    """Veröffentlicht einen vollständigen JSON-Report per atomarem Dateitausch."""
    resolved_path = _resolve_json_export_path(output_path)
    data = (json.dumps(report, indent=2, ensure_ascii=False) + "\n").encode("utf-8")
    return _write_report_bytes(data, resolved_path)


def _write_report_bytes(
    data: bytes, output_path: str, *, exclusive: bool = False, label: str = "JSON",
) -> str:
    """Write a complete report; publish exclusively or replace atomically."""
    target = os.path.abspath(output_path)
    raw_path = pathlib.Path(target)
    destination = raw_path.parent.resolve() / raw_path.name if exclusive else raw_path.resolve()
    destination.parent.mkdir(parents=True, exist_ok=True)
    mode = stat.S_IMODE(destination.stat().st_mode) if not exclusive and destination.exists() else None
    if mode is not None and not mode & (stat.S_IWUSR | stat.S_IWGRP | stat.S_IWOTH):
        raise PermissionError(f"{label} report target is read-only")
    staged = None
    try:
        with tempfile.NamedTemporaryFile(
            mode="wb", dir=destination.parent,
            prefix=f".{destination.name}.report-", delete=False,
        ) as handle:
            staged = pathlib.Path(handle.name)
            if handle.write(data) != len(data):
                raise OSError(f"Incomplete {label} report write")
            handle.flush()
            os.fsync(handle.fileno())
        if mode is not None:
            staged.chmod(mode)
        if exclusive:
            os.link(staged, destination)
        else:
            os.replace(staged, destination)
            staged = None
    finally:
        if staged is not None:
            staged.chmod(stat.S_IRUSR | stat.S_IWUSR)
            staged.unlink(missing_ok=True)
    return target


class ToolTip:
    """
    Barrierefreies, leichtgewichtiges Tooltip-Widget für Tkinter-Komponenten.
    Unterstützt Maus-Hover (<Enter>/<Leave>) und Tastaturfokus (<FocusIn>/<FocusOut>).
    """

    def __init__(self, widget: tk.Widget, text: str = ""):
        self.widget = widget
        self.text = text
        self.tip_window: tk.Toplevel | None = None
        self.widget.bind("<Enter>", self.show_tip, add="+")
        self.widget.bind("<Leave>", self.hide_tip, add="+")
        self.widget.bind("<FocusIn>", self.show_tip, add="+")
        self.widget.bind("<FocusOut>", self.hide_tip, add="+")
        self.widget.bind("<ButtonPress>", self.hide_tip, add="+")
        self.widget.bind("<Escape>", self.hide_tip, add="+")

    def set_text(self, text: str) -> None:
        self.text = text
        if self.tip_window and self.tip_window.winfo_exists():
            for child in self.tip_window.winfo_children():
                if isinstance(child, tk.Label):
                    child.config(text=self.text)

    def show_tip(self, event: Any | None = None) -> None:
        if self.tip_window or not self.text:
            return
        try:
            x = self.widget.winfo_rootx() + 20
            y = self.widget.winfo_rooty() + self.widget.winfo_height() + 5
        except tk.TclError:
            return

        self.tip_window = tw = tk.Toplevel(self.widget)
        tw.wm_overrideredirect(True)
        tw.wm_geometry(f"+{x}+{y}")
        try:
            tw.attributes("-topmost", True)
        except tk.TclError:
            pass

        label = tk.Label(
            tw,
            text=self.text,
            justify=tk.LEFT,
            background="#2c3e50",
            foreground="#ffffff",
            relief=tk.SOLID,
            borderwidth=1,
            font=("Segoe UI" if os.name == "nt" else "Arial", 9),
            padx=8,
            pady=4,
        )
        label.pack(ipadx=1)

    def hide_tip(self, event: Any | None = None) -> None:
        if self.tip_window:
            try:
                self.tip_window.destroy()
            except tk.TclError:
                pass
            self.tip_window = None


def run_project_analysis(output_widget: scrolledtext.ScrolledText, status_widget: tk.Label | None = None) -> None:
    """Ordner-Dialog und Projekt-Analyse."""
    folder_path = filedialog.askdirectory(title=_t("dialog_select_project"))
    if not folder_path:
        return
    
    if status_widget is not None:
        status_widget.config(text=_t("status_analyzing_project"))
        status_widget.update_idletasks()

    output_widget.delete("1.0", tk.END)
    output_widget.insert(tk.END, f"{_t('gui_analyzing_folder')}: {folder_path}\n\n")
    output_widget.update_idletasks()  # nur Render-Jobs, keine User-Events (Re-entranz-Schutz)

    def progress_cb(cur, tot, fp):
        output_widget.insert(tk.END, f"[{cur}/{tot}] {os.path.basename(fp)}\n")
        output_widget.see(tk.END)
        output_widget.update_idletasks()  # nur Render-Jobs, keine User-Events (Re-entranz-Schutz)
        if status_widget is not None:
            status_widget.config(text=f"[{cur}/{tot}] {os.path.basename(fp)}")
            status_widget.update_idletasks()
    
    try:
        result = analyze_project(folder_path, progress_cb)
        output_widget.delete("1.0", tk.END)
        output_widget.insert(tk.END, generate_project_report(result))
        
        export_path = os.path.join(folder_path, "project_analysis.txt")
        text = generate_project_report(result, project_name=_extract_project_display_name(folder_path))
        _write_report_bytes(text.encode("utf-8"), export_path, label="Text")
        output_widget.insert(tk.END, f"\n{_t('gui_saved')}: {export_path}")
        if status_widget is not None:
            status_widget.config(text=f"{_t('status_analysis_done')} {os.path.basename(folder_path)}")
    except Exception as e:  # noqa: BLE001 -- GUI boundary reports project failures to the user
        if status_widget is not None:
            status_widget.config(text=f"[FEHLER] {e}")
        messagebox.showerror(_t("dialog_error_title"), str(e))


def _build_welcome_text() -> str:
    """Baut die übersetzte Willkommensnachricht inkl. eingesetztem Shortcut-Hinweis."""
    return _t("welcome_body").replace("{shortcut}", _get_keyboard_shortcut_hint())


def show_info_dialog(parent: Any = None) -> None:
    """Zeigt den Versions- und Informationsdialog."""
    messagebox.showinfo(
        _t("dialog_info_title"),
        _t("info_body").replace("{version}", TOOL_VERSION),
    )


def _build_shortcuts_text() -> str:
    """Baut die strukturierte Kurzübersicht für den Barrierefreiheits-Dialog."""
    lines = [
        f"[{_t('dialog_shortcuts_cat_nav')}]",
        f"  Alt+D / Ctrl+O        {_t('tooltip_analyze_file')}",
        f"  Alt+P / Ctrl+Shift+O  {_t('tooltip_analyze_project')}",
        f"  Ctrl+S                {_t('menu_save_report')}",
        f"  Ctrl+Q                {_t('menu_exit')}",
        "",
        f"[{_t('dialog_shortcuts_cat_actions')}]",
        f"  Alt+F                 {_t('tooltip_autofix')}",
        f"  Ctrl+A                {_t('menu_select_all')}",
        f"  Ctrl+C                {_t('menu_copy')}",
        f"  Ctrl+L                {_t('menu_clear_output')}",
        "",
        f"[{_t('dialog_shortcuts_cat_general')}]",
        f"  F1                    {_t('menu_shortcuts')}",
        f"  Shift+F1              {_t('menu_about')}",
        f"  Esc / Enter           {_t('dialog_btn_close')}",
    ]
    return "\n".join(lines)


def show_shortcuts_dialog(parent: Any = None) -> tk.Toplevel | None:
    """Zeigt einen barrierefreien Tastaturkürzel- und Accessibility-Dialog nach WCAG 2.1 AA / BITV 2.0."""
    if os.environ.get("HEADLESS") == "1":
        return None

    try:
        dlg = tk.Toplevel(parent) if parent is not None else tk.Toplevel()
    except tk.TclError:
        return None

    dlg.title(f"{_t('dialog_shortcuts_title')} - {_t('app_title')}")
    dlg.geometry("620x520")
    dlg.minsize(480, 380)
    if parent is not None:
        try:
            dlg.transient(parent)
        except tk.TclError:
            pass

    try:
        if parent is not None and parent.winfo_viewable():
            px = parent.winfo_rootx() + (parent.winfo_width() // 2) - 310
            py = parent.winfo_rooty() + (parent.winfo_height() // 2) - 260
            dlg.geometry(f"+{max(0, px)}+{max(0, py)}")
    except (tk.TclError, AttributeError):
        pass

    header_frame = tk.Frame(dlg, bg="#2c3e50", padx=16, pady=12)
    header_frame.pack(fill=tk.X)

    title_label = tk.Label(
        header_frame,
        text=f"⌨️  {_t('dialog_shortcuts_title')}",
        font=("Segoe UI" if os.name == "nt" else "Arial", 13, "bold"),
        fg="#ffffff",
        bg="#2c3e50",
    )
    title_label.pack(anchor=tk.W)

    subtitle_label = tk.Label(
        header_frame,
        text=_t("dialog_shortcuts_subtitle"),
        font=("Segoe UI" if os.name == "nt" else "Arial", 9),
        fg="#ecf0f1",
        bg="#2c3e50",
    )
    subtitle_label.pack(anchor=tk.W, pady=(2, 0))

    content_frame = tk.Frame(dlg, padx=16, pady=12)
    content_frame.pack(fill=tk.BOTH, expand=True)

    txt = scrolledtext.ScrolledText(
        content_frame,
        wrap=tk.WORD,
        font=("Consolas" if os.name == "nt" else "Courier", 9),
        bg="#fafafa",
        fg="#222222",
        relief=tk.SOLID,
        bd=1,
    )
    txt.pack(fill=tk.BOTH, expand=True)
    txt.insert("1.0", _build_shortcuts_text())
    txt.config(state=tk.DISABLED)

    a11y_notice = tk.Label(
        content_frame,
        text=_t("dialog_shortcuts_a11y_notice"),
        font=("Segoe UI" if os.name == "nt" else "Arial", 8, "italic"),
        fg="#555555",
        wraplength=560,
        justify=tk.LEFT,
    )
    a11y_notice.pack(fill=tk.X, pady=(8, 0))

    btn_frame = tk.Frame(dlg, padx=16, pady=10)
    btn_frame.pack(fill=tk.X)

    close_btn = tk.Button(
        btn_frame,
        text=_t("dialog_btn_close"),
        command=dlg.destroy,
        bg="#2c3e50",
        fg="#ffffff",
        font=("Segoe UI" if os.name == "nt" else "Arial", 9, "bold"),
        padx=18,
        pady=5,
        cursor="hand2",
    )
    close_btn.pack(side=tk.RIGHT)
    close_btn.focus_set()

    # Barrierefreie Tastaturnavigation im Dialog ohne Trap (WCAG 2.1 SC 2.1.2)
    txt.bind("<Tab>", lambda _e: (close_btn.focus_set(), "break")[1])
    txt.bind("<Shift-Tab>", lambda _e: (close_btn.focus_set(), "break")[1])
    txt.bind("<ISO_Left_Tab>", lambda _e: (close_btn.focus_set(), "break")[1])
    close_btn.bind("<Tab>", lambda _e: (txt.focus_set(), "break")[1])
    close_btn.bind("<Shift-Tab>", lambda _e: (txt.focus_set(), "break")[1])
    close_btn.bind("<ISO_Left_Tab>", lambda _e: (txt.focus_set(), "break")[1])

    dlg.bind("<Escape>", lambda _e: dlg.destroy())
    dlg.bind("<Return>", lambda _e: dlg.destroy())

    try:
        dlg.grab_set()
    except tk.TclError:
        pass

    return dlg


def save_report_as(output_widget: scrolledtext.ScrolledText, status_widget: tk.Label | None = None) -> None:
    """Ermöglicht das manuelle Speichern des aktuellen Berichts in eine frei wählbare Datei."""
    report_text = output_widget.get("1.0", tk.END).strip()
    if not report_text:
        return
    file_path = filedialog.asksaveasfilename(
        title=_t("dialog_save_report_title"),
        defaultextension=".txt",
        filetypes=[(_t("dialog_filetypes_txt"), "*.txt"), (_t("dialog_filetypes_all"), "*.*")],
    )
    if not file_path:
        return
    try:
        _write_report_bytes(report_text.encode("utf-8"), file_path, label="Text")
        if status_widget is not None:
            status_widget.config(text=f"{_t('status_report_saved')} {os.path.basename(file_path)}")
        messagebox.showinfo(_t("dialog_success_title"), f"{_t('status_report_saved')} {file_path}")
    except Exception as e:
        if status_widget is not None:
            status_widget.config(text=f"[FEHLER] {e}")
        messagebox.showerror(_t("dialog_error_title"), str(e))


def clear_output_view(output_widget: scrolledtext.ScrolledText, status_widget: tk.Label | None = None) -> None:
    """Leert das Ausgabefenster und stellt den Willkommenstext wieder her."""
    output_widget.delete("1.0", tk.END)
    output_widget.insert(tk.END, _build_welcome_text())
    if status_widget is not None:
        status_widget.config(text=_t("status_output_cleared"))


def create_gui() -> None:
    """Erstellt und startet die GUI-Anwendung."""
    root = tk.Tk()
    root.title(_t("app_title"))
    root.geometry(WINDOW_GEOMETRY)
    if os.path.exists(APP_ICON_PATH):
        try:
            root.iconbitmap(default=APP_ICON_PATH)
        except tk.TclError:
            pass
    
    # Status-Bar am unteren Fensterrand für barrierefreie Live-Meldungen
    status_bar = tk.Label(
        root,
        text=_t("status_ready"),
        bd=1,
        relief=tk.SUNKEN,
        anchor=tk.W,
        font=("Segoe UI" if os.name == "nt" else "Arial", 9),
        bg="#e0e0e0",
        fg="#333333",
        padx=8,
        pady=3,
    )
    status_bar.pack(side=tk.BOTTOM, fill=tk.X)

    # Button-Frame für besseres Layout
    button_frame = tk.Frame(root)
    button_frame.pack(pady=10)

    # Analyse-Button
    btn = tk.Button(
        button_frame,
        text=_t("btn_analyze_file"),
        command=lambda: run_analysis(output, status_bar),
        bg="#4CAF50",
        fg="white",
        font=("Arial", 11, "bold"),
        padx=20,
        pady=10,
        cursor="hand2"
    )
    btn.pack(side=tk.LEFT, padx=5)
    btn.bind("<Return>", lambda _e: btn.invoke(), add="+")
    btn.bind("<Shift-Tab>", lambda _e: (output.focus_set(), "break")[1])
    btn.bind("<ISO_Left_Tab>", lambda _e: (output.focus_set(), "break")[1])
    btn_tip = ToolTip(btn, _t("tooltip_analyze_file"))
    
    # Info-Button
    info_btn = tk.Button(
        button_frame,
        text=_t("btn_info"),
        command=lambda: show_info_dialog(root),
        bg="#2196F3",
        fg="white",
        font=("Arial", 10),
        padx=15,
        pady=10,
        cursor="hand2"
    )
    info_btn.pack(side=tk.LEFT, padx=5)
    info_btn.bind("<Return>", lambda _e: info_btn.invoke(), add="+")
    info_tip = ToolTip(info_btn, _t("tooltip_info"))
    
    # Auto-Fix Button
    fix_btn = tk.Button(
        button_frame,
        text=_t("btn_autofix"),
        command=lambda: auto_fix_unused_imports(output, status_bar),
        bg="#FF9800",
        fg="white",
        font=("Arial", 10),
        padx=15,
        pady=10,
        cursor="hand2"
    )
    fix_btn.pack(side=tk.LEFT, padx=5)
    fix_btn.bind("<Return>", lambda _e: fix_btn.invoke(), add="+")
    fix_tip = ToolTip(fix_btn, _t("tooltip_autofix"))

    # Projekt-Analyse Button
    project_btn = tk.Button(
        button_frame,
        text=_t("btn_analyze_project"),
        command=lambda: run_project_analysis(output, status_bar),
        bg="#9C27B0",
        fg="white",
        font=("Arial", 10),
        padx=15,
        pady=10,
        cursor="hand2"
    )
    project_btn.pack(side=tk.LEFT, padx=5)
    project_btn.bind("<Return>", lambda _e: project_btn.invoke(), add="+")
    project_btn.bind("<Tab>", lambda _e: (output.focus_set(), "break")[1])
    project_tip = ToolTip(project_btn, _t("tooltip_analyze_project"))

    def _bind_status_hint(widget: tk.Widget, tooltip_key: str) -> None:
        def _on_enter(_e: Any) -> None:
            status_bar.config(text=_t(tooltip_key))
        def _on_leave(_e: Any) -> None:
            status_bar.config(text=_t("status_ready"))
        widget.bind("<Enter>", _on_enter, add="+")
        widget.bind("<Leave>", _on_leave, add="+")
        widget.bind("<FocusIn>", _on_enter, add="+")
        widget.bind("<FocusOut>", _on_leave, add="+")

    _bind_status_hint(btn, "tooltip_analyze_file")
    _bind_status_hint(info_btn, "tooltip_info")
    _bind_status_hint(fix_btn, "tooltip_autofix")
    _bind_status_hint(project_btn, "tooltip_analyze_project")

    shortcut_hint = tk.Label(
        root,
        text=_get_keyboard_shortcut_hint(),
        anchor="w",
        fg="#555555",
        font=("Arial", 9),
    )
    shortcut_hint.pack(fill=tk.X, padx=12, pady=(0, 8))

    # Output-Widget als globale Referenz
    output = scrolledtext.ScrolledText(
        root,
        width=OUTPUT_WIDTH,
        height=OUTPUT_HEIGHT,
        font=OUTPUT_FONT,
        wrap=tk.WORD,
        bg="#f5f5f5",
        fg="#333333"
    )
    output.pack(fill=tk.BOTH, expand=True, padx=10, pady=(0, 10))
    
    # Willkommensnachricht
    output.insert(tk.END, _build_welcome_text())

    def _select_all_output(_event: Any = None) -> str:
        output.tag_add("sel", "1.0", tk.END)
        output.mark_set("insert", "1.0")
        output.see("insert")
        return "break"

    output.bind("<Control-a>", _select_all_output)
    output.bind("<Control-A>", _select_all_output)

    # Barrierefreie Tastaturnavigation ohne Keyboard-Trap (WCAG 2.1 SC 2.1.2)
    output.bind("<Tab>", lambda _e: (btn.focus_set(), "break")[1])
    output.bind("<Shift-Tab>", lambda _e: (project_btn.focus_set(), "break")[1])
    output.bind("<ISO_Left_Tab>", lambda _e: (project_btn.focus_set(), "break")[1])

    # Kontextmenü für das Ausgabefeld
    output_ctx_menu = tk.Menu(output, tearoff=0)
    output_ctx_menu.add_command(
        label=_t("menu_copy"),
        command=lambda: output.event_generate("<<Copy>>"),
    )
    output_ctx_menu.add_command(
        label=_t("menu_select_all"),
        command=_select_all_output,
    )
    output_ctx_menu.add_separator()
    output_ctx_menu.add_command(
        label=_t("menu_save_report"),
        command=lambda: save_report_as(output, status_bar),
    )
    output_ctx_menu.add_command(
        label=_t("menu_clear_output"),
        command=lambda: clear_output_view(output, status_bar),
    )

    def _show_output_context_menu(event: Any) -> None:
        try:
            output_ctx_menu.tk_popup(event.x_root, event.y_root)
        finally:
            output_ctx_menu.grab_release()

    output.bind("<Button-3>", _show_output_context_menu)
    output.bind(
        "<App>",
        lambda _e: output_ctx_menu.tk_popup(output.winfo_rootx() + 20, output.winfo_rooty() + 20),
    )

    # --- Menüleiste mit Mnemonics & Standardmenüs (WCAG 2.1 AA / BITV 2.0) ---
    translator = get_translator()
    current_lang = translator.get_language() if translator is not None else get_saved_language()
    lang_var = tk.StringVar(value=current_lang)

    menubar = tk.Menu(root)

    # Datei-Menü
    file_menu = tk.Menu(menubar, tearoff=0)
    file_menu.add_command(
        label=_t("menu_analyze_file"),
        command=lambda: run_analysis(output, status_bar),
        accelerator="Alt+D",
    )
    file_menu.add_command(
        label=_t("menu_analyze_project"),
        command=lambda: run_project_analysis(output, status_bar),
        accelerator="Alt+P",
    )
    file_menu.add_separator()
    file_menu.add_command(
        label=_t("menu_save_report"),
        command=lambda: save_report_as(output, status_bar),
        accelerator="Ctrl+S",
    )
    file_menu.add_separator()
    file_menu.add_command(
        label=_t("menu_exit"),
        command=root.destroy,
        accelerator="Ctrl+Q",
    )
    menubar.add_cascade(label=_t("menu_file"), menu=file_menu)

    # Aktionen-Menü
    actions_menu = tk.Menu(menubar, tearoff=0)
    actions_menu.add_command(
        label=_t("menu_autofix"),
        command=lambda: auto_fix_unused_imports(output, status_bar),
        accelerator="Alt+F",
    )
    actions_menu.add_separator()
    actions_menu.add_command(
        label=_t("menu_select_all"),
        command=_select_all_output,
        accelerator="Ctrl+A",
    )
    actions_menu.add_command(
        label=_t("menu_copy"),
        command=lambda: output.event_generate("<<Copy>>"),
        accelerator="Ctrl+C",
    )
    actions_menu.add_command(
        label=_t("menu_clear_output"),
        command=lambda: clear_output_view(output, status_bar),
        accelerator="Ctrl+L",
    )
    menubar.add_cascade(label=_t("menu_actions"), menu=actions_menu)

    # Sprache-Menü
    lang_menu = tk.Menu(menubar, tearoff=0)
    for label, code in (
        ("Deutsch", "de"),
        ("English", "en"),
        ("Español", "es"),
        ("中文", "zh"),
        ("日本語", "ja"),
        ("Русский", "ru"),
    ):
        lang_menu.add_radiobutton(
            label=label,
            value=code,
            variable=lang_var,
            command=lambda c=code: apply_language(c),
        )
    menubar.add_cascade(label=_t("menu_language"), menu=lang_menu)

    # Hilfe-Menü
    help_menu = tk.Menu(menubar, tearoff=0)
    help_menu.add_command(
        label=_t("menu_shortcuts"),
        command=lambda: show_shortcuts_dialog(root),
        accelerator="F1",
    )
    help_menu.add_command(
        label=_t("menu_about"),
        command=lambda: show_info_dialog(root),
        accelerator="Shift+F1",
    )
    menubar.add_cascade(label=_t("menu_help"), menu=help_menu)

    root.config(menu=menubar)

    def apply_language(lang: str) -> None:
        """Wechselt Sprache, persistiert sie und stellt die gesamte Oberfläche live um."""
        if translator is not None:
            translator.set_language(lang)
        set_saved_language(lang)
        lang_var.set(lang)
        root.title(_t("app_title"))
        btn.config(text=_t("btn_analyze_file"))
        info_btn.config(text=_t("btn_info"))
        fix_btn.config(text=_t("btn_autofix"))
        project_btn.config(text=_t("btn_analyze_project"))
        btn_tip.set_text(_t("tooltip_analyze_file"))
        info_tip.set_text(_t("tooltip_info"))
        fix_tip.set_text(_t("tooltip_autofix"))
        project_tip.set_text(_t("tooltip_analyze_project"))
        shortcut_hint.config(text=_get_keyboard_shortcut_hint())
        status_bar.config(text=_t("status_ready"))

        # Menü-Beschriftungen dynamisch nachführen
        try:
            menubar.entryconfig(0, label=_t("menu_file"))
            menubar.entryconfig(1, label=_t("menu_actions"))
            menubar.entryconfig(2, label=_t("menu_language"))
            menubar.entryconfig(3, label=_t("menu_help"))

            file_menu.entryconfig(0, label=_t("menu_analyze_file"))
            file_menu.entryconfig(1, label=_t("menu_analyze_project"))
            file_menu.entryconfig(3, label=_t("menu_save_report"))
            file_menu.entryconfig(5, label=_t("menu_exit"))

            actions_menu.entryconfig(0, label=_t("menu_autofix"))
            actions_menu.entryconfig(2, label=_t("menu_select_all"))
            actions_menu.entryconfig(3, label=_t("menu_copy"))
            actions_menu.entryconfig(4, label=_t("menu_clear_output"))

            help_menu.entryconfig(0, label=_t("menu_shortcuts"))
            help_menu.entryconfig(1, label=_t("menu_about"))

            output_ctx_menu.entryconfig(0, label=_t("menu_copy"))
            output_ctx_menu.entryconfig(1, label=_t("menu_select_all"))
            output_ctx_menu.entryconfig(3, label=_t("menu_save_report"))
            output_ctx_menu.entryconfig(4, label=_t("menu_clear_output"))
        except tk.TclError:
            pass

        # Willkommenstext nur neu rendern, solange keine Analyse-Ausgabe angezeigt wird.
        if output.get("1.0", "1.end").strip() in _WELCOME_HEADS:
            output.delete("1.0", tk.END)
            output.insert(tk.END, _build_welcome_text())
        messagebox.showinfo(_t("dialog_language_title"), _t("lang_switched_msg"))

    _register_gui_shortcuts(
        root,
        analyze_file_cb=lambda: run_analysis(output, status_bar),
        info_cb=lambda: show_info_dialog(root),
        auto_fix_cb=lambda: auto_fix_unused_imports(output, status_bar),
        analyze_project_cb=lambda: run_project_analysis(output, status_bar),
        shortcuts_cb=lambda: show_shortcuts_dialog(root),
        save_report_cb=lambda: save_report_as(output, status_bar),
        clear_output_cb=lambda: clear_output_view(output, status_bar),
        quit_cb=root.destroy,
    )
    output.focus_set()

    root.mainloop()


def _get_keyboard_shortcut_hint() -> str:
    """Liefert den sichtbaren Kurzhinweis für die Hauptaktionen der GUI."""
    return _t("shortcut_hint")


def _register_gui_shortcuts(
    root: Any,
    analyze_file_cb: Callable[[], None],
    info_cb: Callable[[], None],
    auto_fix_cb: Callable[[], None],
    analyze_project_cb: Callable[[], None],
    shortcuts_cb: Callable[[], None] | None = None,
    save_report_cb: Callable[[], None] | None = None,
    clear_output_cb: Callable[[], None] | None = None,
    quit_cb: Callable[[], None] | None = None,
) -> None:
    """Bindet globale Tastaturkürzel für die primären GUI-Aktionen."""
    f1_target = shortcuts_cb if shortcuts_cb is not None else info_cb
    shortcuts = {
        "<Alt-d>": analyze_file_cb,
        "<Alt-D>": analyze_file_cb,
        "<Alt-p>": analyze_project_cb,
        "<Alt-P>": analyze_project_cb,
        "<Alt-f>": auto_fix_cb,
        "<Alt-F>": auto_fix_cb,
        "<F1>": f1_target,
    }
    if shortcuts_cb is not None:
        shortcuts["<Shift-F1>"] = info_cb
    if save_report_cb is not None:
        shortcuts["<Control-s>"] = save_report_cb
        shortcuts["<Control-S>"] = save_report_cb
    if clear_output_cb is not None:
        shortcuts["<Control-l>"] = clear_output_cb
        shortcuts["<Control-L>"] = clear_output_cb
    if quit_cb is not None:
        shortcuts["<Control-q>"] = quit_cb
        shortcuts["<Control-Q>"] = quit_cb
    shortcuts["<Control-o>"] = analyze_file_cb
    shortcuts["<Control-O>"] = analyze_file_cb
    shortcuts["<Control-Shift-O>"] = analyze_project_cb
    shortcuts["<Control-Shift-o>"] = analyze_project_cb

    for sequence, callback in shortcuts.items():
        def _handler(_event: Any, cb: Callable[[], None] = callback) -> str:
            cb()
            return "break"

        root.bind_all(sequence, _handler)


def _file_has_findings(result: AnalysisResult) -> bool:
    """Prüft, ob eine Dateianalyse relevante Funde enthält."""
    return any((
        result.missing_defs,
        result.unused_defs,
        result.unused_imports,
        result.duplicate_imports,
        result.missing_imports,
        result.todo_comments,
    ))


def _project_has_findings(result: ProjectAnalysisResult) -> bool:
    """Prüft, ob eine Projektanalyse relevante Funde enthält."""
    return any((
        result.all_unused_imports,
        result.all_unused_defs,
        result.all_missing_defs,
        result.all_missing_imports,
        result.all_duplicate_imports,
        result.files_with_errors,
    ))


def _emit_cli_report(report: str) -> None:
    """Schreibt Reports konsistent nach stdout mit defensiver Encoding-Behandlung."""
    try:
        sys.stdout.write(report)
        if not report.endswith("\n"):
            sys.stdout.write("\n")
    except UnicodeEncodeError:
        encoding = getattr(sys.stdout, "encoding", None) or "utf-8"
        sanitized = report.encode(encoding, errors="replace").decode(encoding)
        sys.stdout.write(sanitized)
        if not sanitized.endswith("\n"):
            sys.stdout.write("\n")


def _write_cli_json_if_requested(
    report: dict[str, Any], output_path: str | None,
    protected_paths: list[str] | None = None,
) -> bool:
    """Schreibt optional den JSON-Report; Fehler gehen nach stderr."""
    if not output_path:
        return True
    try:
        resolved_path = _resolve_json_export_path(output_path)
        target = os.path.normcase(os.path.realpath(resolved_path))
        for source in protected_paths or []:
            same_path = target == os.path.normcase(os.path.realpath(source))
            same_file = (
                os.path.exists(resolved_path) and os.path.exists(source)
                and os.path.samefile(resolved_path, source)
            )
            if same_path or same_file:
                raise ValueError("JSON-Ausgabe darf keine analysierte Quelldatei ersetzen.")
        written_path = write_json_report(report, resolved_path)
    except Exception as exc:  # noqa: BLE001 -- CLI boundary reports export failures and returns a failure result
        print(f"[FEHLER] {_t('cli_json_export_failed')}: {exc}", file=sys.stderr)
        return False
    print(f"[OK] {_t('cli_json_saved')}: {written_path}", file=sys.stderr)
    return True


def _run_cli_file(path: str, json_output: str | None = None) -> int:
    """Führt eine Datei-Analyse ohne GUI aus."""
    try:
        result = analyze_file(path)
    except Exception as exc:  # noqa: BLE001 -- CLI boundary converts analysis failures to a nonzero exit code
        print(f"[FEHLER] {exc}", file=sys.stderr)
        return EXIT_ANALYSIS_ERROR

    _emit_cli_report(generate_report(result))
    json_report = build_json_report("file", result, source_name=path)
    if not _write_cli_json_if_requested(json_report, json_output, [path]):
        return EXIT_ANALYSIS_ERROR
    return EXIT_FINDINGS if _file_has_findings(result) else EXIT_OK


def _run_cli_project(path: str, json_output: str | None = None) -> int:
    """Führt eine Projektanalyse ohne GUI aus."""
    if not os.path.isdir(path):
        print(f"[FEHLER] {_t('cli_project_not_found')}: {path}", file=sys.stderr)
        return EXIT_ANALYSIS_ERROR

    try:
        result = analyze_project(path)
    except Exception as exc:  # noqa: BLE001 -- CLI boundary converts project failures to a nonzero exit code
        print(f"[FEHLER] {_t('cli_project_analysis_failed')}: {exc}", file=sys.stderr)
        return EXIT_ANALYSIS_ERROR

    _emit_cli_report(generate_project_report(result, project_name=_extract_project_display_name(path)))
    json_report = build_json_report("project", result, source_name=path)
    protected_paths = list(result.file_results) + [p for p, _ in result.files_with_errors]
    if not _write_cli_json_if_requested(json_report, json_output, protected_paths):
        return EXIT_ANALYSIS_ERROR

    if result.files_with_errors:
        return EXIT_PARTIAL_ERROR
    return EXIT_FINDINGS if _project_has_findings(result) else EXIT_OK


def _run_cli_snippet(code: str, json_output: str | None = None) -> int:
    """Analysiert ein Snippet ohne temporäre Projektdateien."""
    try:
        result = analyze_source(code, source_name="<snippet>")
    except Exception as exc:  # noqa: BLE001 -- CLI boundary converts snippet failures to a nonzero exit code
        print(f"[FEHLER] {exc}", file=sys.stderr)
        return EXIT_ANALYSIS_ERROR

    _emit_cli_report(generate_report(result))
    json_report = build_json_report("snippet", result, source_name="<snippet>")
    if not _write_cli_json_if_requested(json_report, json_output):
        return EXIT_ANALYSIS_ERROR
    return EXIT_FINDINGS if _file_has_findings(result) else EXIT_OK


class LocalizedArgumentParser(argparse.ArgumentParser):
    """Ersetzt den nutzerrelevanten Zielkonflikt durch den aktiven Sprachtext."""

    _MUTUALLY_EXCLUSIVE_ERROR = re.compile(
        r"argument (?P<argument>--[\w-]+): not allowed with argument (?P<other>--[\w-]+)"
    )

    def error(self, message: str) -> None:
        match = self._MUTUALLY_EXCLUSIVE_ERROR.fullmatch(message)
        if match:
            message = _t("cli_error_mutually_exclusive").format(**match.groupdict())
        super().error(message)


def build_cli_parser() -> argparse.ArgumentParser:
    """Erstellt den Argument-Parser für den CLI-Modus."""
    parser = LocalizedArgumentParser(
        description=_t("cli_help_description"),
        add_help=False,
    )
    parser.add_argument("-h", "--help", action="help", help=_t("cli_help_help"))
    target_group = parser.add_mutually_exclusive_group()
    target_group.add_argument(
        "--file",
        metavar=_t("cli_help_file_metavar"),
        help=_t("cli_help_file"),
    )
    target_group.add_argument(
        "--project",
        metavar=_t("cli_help_project_metavar"),
        help=_t("cli_help_project"),
    )
    target_group.add_argument(
        "--stdin",
        action="store_true",
        help=_t("cli_help_stdin"),
    )
    parser.add_argument(
        "--json-output",
        nargs="?",
        const=DEFAULT_JSON_REPORT_NAME,
        metavar=_t("cli_help_json_output_metavar"),
        help=_t("cli_help_json_output").format(
            schema=JSON_SCHEMA_VERSION,
            default_name=DEFAULT_JSON_REPORT_NAME,
        ),
    )
    current_lang = get_translator().get_language() if get_translator() is not None else DEFAULT_LANGUAGE
    parser.add_argument(
        "--lang",
        choices=SUPPORTED_LANGUAGES,
        default=current_lang,
        help=_t("cli_help_language"),
    )
    return parser


def main(argv: list[str] | None = None) -> int:
    """Startet GUI oder CLI je nach Argumenten."""
    language_parser = argparse.ArgumentParser(add_help=False)
    language_parser.add_argument("--lang", choices=SUPPORTED_LANGUAGES, default=None)
    initial_args, _ = language_parser.parse_known_args(argv)

    if initial_args.lang:
        chosen_lang = initial_args.lang
    else:
        chosen_lang = get_saved_language()

    set_runtime_language(chosen_lang)
    parser = build_cli_parser()
    args = parser.parse_args(argv)

    if args.file:
        return _run_cli_file(args.file, args.json_output)
    if args.project:
        return _run_cli_project(args.project, args.json_output)
    if args.stdin:
        return _run_cli_snippet(sys.stdin.read(), args.json_output)

    create_gui()
    return EXIT_OK


# ============================================================================
# MAIN
# ============================================================================

if __name__ == "__main__":
    sys.exit(main())