מנועי המערכת (System Engines)

סקירה כללית

מסמך זה מתאר את המנועים המרכזיים במערכת וכיצד הם עובדים.

מנוע חיפוש (Search Engine)

מיקום: search_engine.py

תפקיד: חיפוש מתקדם בקטעי קוד

סוגי חיפוש: - Text Search - התאמת מחרוזת - Regex Search - ביטויים רגולריים - Fuzzy Search - התאמה משוערת - Content Search - חיפוש Full-Text - Function Search - חיפוש פונקציות

רכיבים מרכזיים:

class SearchEngine:
    def __init__(self):
        self.index = SearchIndex()

    async def search(
        self,
        query: str,
        search_type: SearchType,
        filters: SearchFilter,
        user_id: int
    ) -> List[SearchResult]:
        # בניית אינדקס אם נדרש
        if self.index.needs_rebuild(user_id):
            await self.index.rebuild_index(user_id)

        # ביצוע חיפוש
        results = await self._perform_search(query, search_type, filters, user_id)

        # חישוב relevance score
        for result in results:
            result.relevance_score = self._calculate_relevance(result, query)

        # מיון
        return self._sort_results(results, sort_order)

אינדקס: - Word Index - מילים -> קבצים - Function Index - פונקציות -> קבצים - Language Index - שפות -> קבצים - Tag Index - תגיות -> קבצים

ראו גם: זרימת חיפוש (Search Flow)

מנוע רפקטורינג (Refactoring Engine)

מיקום: refactoring_engine.py

תפקיד: שינוי מבנה קוד בצורה בטוחה

סוגי רפקטורינג: - Split Functions - פיצול קובץ גדול - Extract Functions - חילוץ קוד חוזר - Merge Similar - מיזוג קוד דומה - Convert to Classes - המרה למחלקות - Dependency Injection - הוספת DI

רכיבים מרכזיים:

class RefactoringEngine:
    def __init__(self) -> None:
        self.analyzer: Optional[CodeAnalyzer] = None

    def propose_refactoring(
        self, code: str, filename: str, refactor_type: RefactorType
    ) -> RefactorResult:
        # ניתוח קוד
        self.analyzer = CodeAnalyzer(code, filename)
        if not self.analyzer.analyze():
            return RefactorResult(
                success=False, proposal=None, error="כשל בניתוח הקוד - ייתכן שגיאת תחביר"
            )
        # יצירת הצעה לפי סוג
        try:
            if refactor_type == RefactorType.SPLIT_FUNCTIONS:
                proposal = self._split_functions()
            elif refactor_type == RefactorType.EXTRACT_FUNCTIONS:
                proposal = self._extract_functions()
            elif refactor_type == RefactorType.MERGE_SIMILAR:
                proposal = self._merge_similar()
            elif refactor_type == RefactorType.CONVERT_TO_CLASSES:
                proposal = self._convert_to_classes()
            elif refactor_type == RefactorType.DEPENDENCY_INJECTION:
                proposal = self._add_dependency_injection()
            else:
                return RefactorResult(success=False, proposal=None, error="סוג רפקטורינג לא נתמך")
            # אימות בסיסי (AST) לתוצרים
            validated = self._validate_proposal(proposal)
            return RefactorResult(success=True, proposal=proposal, validation_passed=validated)
        except Exception as e:
            return RefactorResult(success=False, proposal=None, error=f"שגיאה: {e}")

יכולות מתקדמות (Smart Clustering, Cycle Guard)

• Smart Clustering (פיצול חכם לתת‑דומיינים):

  • המנוע בונה גרף תלותים בין פונקציות/מחלקות, מזהה ”קישורים חלשים“ (Weak Links) ומפצל תתי‑גרפים עצמאיים לקבצים נפרדים.

  • דוגמה: Inventory ו‑ApiClient נחתכים לקבצים עצמאיים כאשר אינם תלויים ב‑Users/Finance.

• Coupling Rule (הצמדה): כאשר יש צימוד גבוה בין מנהל לישות (Type Hints/שימוש תכוף), הם יישבו יחד באותו קובץ (Collocation), למשל User + UserManager ב‑users.py.

• Dry‑Run Cycle Guard (מניעת מעגליות):

  • בניית גרף ייבוא בין המודולים שנוצרו, זיהוי SCC (Tarjan) ומיזוג נקודתי רק בתוך המעגל כדי לשבור אותו.

  • ניקוי self‑import ועדכון __init__.py בהתאם. מוסיף אזהרה ידידותית להצעה.

• שמות קבצים דומייניים יציבים (Canonical):

  • users.py, finance.py, inventory.py, network.py (ל‑API clients), workflows.py.

  • דומיינים אחרים יקבלו שם יציב על בסיס שם הקלט: <base>_<group>.py.

מצב שכבות (Layered Mode)

• אופציונלי: דחיפת כל הישויות ל‑Leaf יחיד models.py והמודולים התלויים ייבאו ממנו.

• הפעלה דרך משתנה סביבה (ללא שינוי קוד):

export REFACTOR_LAYERED_MODE=1

• בברירת מחדל (ללא הדגל) מופעל Collocation: מחלקות ופונקציות נוצרות יחד לפי דומיין.

Safe Decomposition ל‑models.py (פיצול בטוח לחבילת models/)

בסנריו שבו קיימת שכבה שכבתית יציבה וכל המחלקות מרוכזות בקובץ יחיד models.py (ללא פונקציות טופ‑לבל), המנוע מבצע פיצול בטוח ל‑תתי‑מודולים דומייניים בתוך חבילת models/:

• models/core.py – ישויות ליבה כגון User, UserManager, PermissionSystem, EmailService.

• models/billing.py – רכיבי תשלום/מנויים כגון PaymentGateway, SubscriptionManager.

• models/inventory.py – ישויות מלאי כגון Product, Inventory.

• לפי צורך: models/network.py (לקוחות API), models/workflows.py (זרימות).

עקרונות:

• זיהוי דומיין לפי יוריסטיקה של שמות וסקשנים; ברירת המחדל היא שיוך ל‑core כאשר אין רמזים.

• יצירת models/__init__.py עם re‑exports עבור תאימות לאחור (ייבוא מ‑models ימשיך לעבוד).

• הזרקת יבוא בין‑מודולי למחלקות נדרשות (למשל billing ייבא User מ‑core: from .core import User).

• Dry‑Run לזיהוי מעגליות בתוך models/ בלבד; פירוק מעגל נעשה ע“י מיזוג נקודתי של מודולים מתוך ה‑SCC ועדכון models/__init__.py.

מתי לבחור Safe Decomposition?

• כאשר המערכת רצה יציב עם models.py יחיד, אך קיים Coupling מלאכותי בין דומיינים שונים.

• כאשר אין תלות הדדית בין קבוצות ישויות (לדוגמה: Inventory אינו תלוי ב‑User).

CodeAnalyzer: - משתמש ב-AST לניתוח Python - מזהה פונקציות, מחלקות, imports - מחשב תלויות ומורכבות

ראו גם: זרימת רפקטורינג (Refactor Flow)

מעבד קוד (Code Processor)

מיקום: code_processor.py

תפקיד: עיבוד וזיהוי קוד

יכולות: - זיהוי שפת תכנות - הדגשת תחביר (Syntax Highlighting) - ניתוח מטריקות קוד - זיהוי קידוד תווים

רכיבים מרכזיים:

class CodeProcessor:
    def detect_language(self, code: str, filename: str = None) -> str:
        # ניסיון לפי שם קובץ
        if filename:
            try:
                lexer = get_lexer_for_filename(filename)
                return lexer.name
            except:
                pass

        # ניסיון לפי תוכן
        try:
            lexer = guess_lexer(code)
            return lexer.name
        except:
            return 'text'

    def highlight_code(
        self,
        code: str,
        language: str,
        format: str = 'html'
    ) -> str:
        lexer = get_lexer_by_name(language)
        formatter = HtmlFormatter(style='monokai')
        return highlight(code, lexer, formatter)

    def analyze_code(self, code: str, language: str) -> Dict:
        # מטריקות בסיסיות
        metrics = {
            'lines': len(code.splitlines()),
            'characters': len(code),
            'functions': self._count_functions(code, language),
            'classes': self._count_classes(code, language),
            'complexity': self._calculate_complexity(code, language)
        }
        return metrics

תמיכה בשפות: - 100+ שפות תכנות (דרך Pygments) - זיהוי אוטומטי לפי שם קובץ או תוכן

מנוע ניתוח (Code Analyzer)

מיקום: refactoring_engine.py (חלק מ-CodeAnalyzer)

תפקיד: ניתוח מבנה קוד Python

יכולות: - AST Parsing - זיהוי פונקציות ומחלקות - חישוב תלויות - חישוב מורכבות ציקלומטית

דוגמה:

analyzer = CodeAnalyzer(code, "example.py")
if analyzer.analyze():
    print(f"Functions: {len(analyzer.functions)}")
    print(f"Classes: {len(analyzer.classes)}")
    for func in analyzer.functions:
        print(f"  {func.name}: complexity={func.complexity}")

מנוע גיבויים (Backup Service)

מיקום: services/backup_service.py

תפקיד: יצירת גיבויים ושחזור

יכולות: - יצירת ZIP מגיבוי מלא - שחזור מגיבוי - ניהול metadata גיבויים

ראו גם: זרימת גיבוי ושחזור (Backup Flow)

מנוע אינטגרציות (Integration Services)

GitHub Service: - מיקום: services/github_service.py - תפקיד: אינטגרציה עם GitHub API - יכולות: העלאה, הורדה, יצירת repos, PRs

Google Drive Service: - מיקום: services/google_drive_service.py - תפקיד: אינטגרציה עם Google Drive - יכולות: העלאה, הורדה, גיבויים אוטומטיים

ראו גם: Integrations

מנוע Observability

מיקום: observability.py, observability_otel.py

תפקיד: מעקב אחר ביצועים ושגיאות

רכיבים: - Structured Logging (structlog) - Metrics (Prometheus) - Tracing (OpenTelemetry) - Error Tracking (Sentry)

ראו גם: אובזרווביליות (Observability)

קישורים

• זרימת חיפוש (Search Flow)

• זרימת רפקטורינג (Refactor Flow)

• זרימת גיבוי ושחזור (Backup Flow)

• search_engine module

• refactoring_engine module

• code_processor module