כלי עזר למפתחים
================

עמוד זה מרכז שני כלים ייעודיים שנמצאים תחת ``tools/`` ונועדו לסייע באיתור צווארי בקבוק במאגר ובסדר הקוד. לפני השימוש ודאו שהקבצים אינם מתועדים במקום אחר כדי למנוע כפילות.

.. contents::
   :local:
   :depth: 2

``tools/analyze_queries.py``
----------------------------

מטרה
~~~~~
- הפעלת MongoDB profiler לפרק זמן קצר כדי לאסוף שאילתות איטיות (לפי ``--min-ms``).
- הפקת מדדים על שימוש באינדקסים באמצעות ``collStats``.
- קבלת ``explain()`` עבור שאילתות טיפוסיות במאגר.

דרישות
~~~~~~~
- משתני סביבה: ``MONGODB_URL`` ו-``DATABASE_NAME`` (ברירת מחדל ``code_keeper_bot``).
- התקנת ``motor`` בסביבת העבודה.
- הרשאות להפעלת profiler על האינדקס שבו אתם משתמשים.

דוגמת הרצה
~~~~~~~~~~

.. code-block:: bash

   export MONGODB_URL="mongodb://localhost:27017"
   export DATABASE_NAME="code_keeper_bot"
   python tools/analyze_queries.py --duration 60 --min-ms 120

פלט אופייני
~~~~~~~~~~~
- ``Slow Queries`` – רשימה ממוינת לפי ``millis`` עם פירוט פעולה, namespace ופילטר.
- ``Index Usage`` – ספירת אינדקסים לפי ``collStats`` כדי לאתר אוספים ללא אינדקס מתאים.
- ``Explain common queries`` – זמן ביצוע משוער עבור שאילתות נפוצות בקולקציות הליבה.

טיפים
~~~~~~
- הפעילו את הכלי בסביבת staging/נתונים מקומיים בלבד והחזירו את רמת ה-profiler ל-``0`` בסיום (הסקריפט עושה זאת אוטומטית).
- לשאילתות ייעודיות אפשר לשנות את `samples` בסוף הקובץ כדי לקבל ``explain`` אחר.
- ניתן להריץ במצב shadow בעת ניתוח production על-ידי יצוא הנתונים מקבצי profile ושימוש במכונה מקומית.

``tools/dup_scan.py``
---------------------

מטרה
~~~~~
- איתור קבצים זהים (sha1/hash) בתוך עץ פרויקט כדי למנוע כפילויות או קוד מודבק.
- שימוש במודול ``duplicate_detector`` שסורק ברמת תוכן ולא רק בשם הקובץ.

דוגמת הרצה
~~~~~~~~~~

.. code-block:: bash

   # חיפוש כפילויות בקבצי Python גדולים מ-5 שורות
   python tools/dup_scan.py --path . --include "*.py" --min-lines 5

   # הרצת JSON עבור אינטגרציה עם CI
   python tools/dup_scan.py --path src --include "*.py" --json > dup-report.json

פרמטרים חשובים
~~~~~~~~~~~~~~~
- ``--path`` – בסיס הסריקה. ברירת המחדל היא הספרייה הנוכחית.
- ``--include`` – ניתן לחזור כמה פעמים כדי למקד לקבצים ספציפיים (למשל ``--include "*.py"``).
- ``--min-lines`` – הסף המינימלי לקבצים שייכנסו לחישוב (ברירת מחדל 5).
- ``--max-files`` – מונע סריקות ענקיות בטעות (ברירת מחדל 500 קבצים).
- ``--json`` – פלט מרוכז בפורמט JSON לשימוש בטסטים/CI.

Best Practices
~~~~~~~~~~~~~~
- הפעילו את הכלי כחלק מבדיקות refactoring כדי לוודא שלא הועתק קוד בין handlers/services.
- במקרה של פלט גדול, התחילו מה-hash עם מספר הקבצים הגבוה ביותר וצרו issue ממוקד לכל קבוצה.
- לצמצום false positives הוסיפו ``.dup-scan-ignore`` (אם נדרש) והרחיבו את הפילטרים בקובץ.