feat(mcp): פארסר Markdown ל-docs_get_section, מעל markdown-it-py

CLAUDE.md

@@ -60,13 +60,14 @@ codekeeper_search_repo(repo="amir-bug-patterns", query="<מונח>")
 | `LOCK_FAIL_OPEN` — מריץ polling בלי מנעול ה-singleton, כלומר שני מריצים במקום אחד | `CORE-PATTERNS.md` U1 |
 | העלאת שרת HTTP או שינוי כתובת האזנה (`0.0.0.0`) — `main.py`, `services/webserver.py`, `webapp/app.py`, `mcp_server/app.py` | `CRITICAL-PATTERNS.md` K5 + `bugbot-rules/network-exposed-without-auth.md` |
 | אתחול עצל של משאב משותף (חיבור, לקוח, pool, קאש) — או **הסרה** של התנהגות מנוונת שקיימת מזמן | `CRITICAL-PATTERNS.md` K15 + `bugbot-rules/lazy-init-guard-publish-order.md` |
+| מופע של ספרייה חיצונית שנבנה **ברמת המודול** ומשותף לחוטים — ובמיוחד כשהבנייה כוללת קריאות תצורה (`use`, `enable`, `disable`, `register`, `add_*`, `before`) | `CRITICAL-PATTERNS.md` K15 + `bugbot-rules/lazy-init-guard-publish-order.md` — מתי אובייקט נחשב מוכן, וכשהתצורה קורית בתוכו. ואם אותו מופע גם נבנה מ-`os.environ` או מפעיל משהו — ראה גם את השורה על ברמה העליונה של מודול |
 | `getattr(x, "y", None)` או `except` שאחריו **מסלול חלופי בגלל כשל** — לא ערך ברירת מחדל, ולא זיהוי יכולת סטטי | `bugbot-rules/silent-fallback-to-worse-path.md` |
 | CSP, כותרות תגובה, או עמוד שנגיש בלי התחברות | `BY-STACK/browser-policy.md` |
 | `create_index` — ובמיוחד `partialFilterExpression` או `sparse=True` | `BY-STACK/mongodb.md` דפוס 1 + `bugbot-rules/mongo-index-and-operator-traps.md` — אופרטורים שהפילטר החלקי לא מקבל, ואתחול שבולע את השגיאה |
 | צינור `aggregate` — `$project`, `$sort`, `$group` — או `find_one` בתוך לולאה | `RECURRING-PATTERNS.md` R8 + `bugbot-rules/work-disproportionate-to-answer.md` |
 | `startswith` / `endswith` על נתיב, URL או דומיין | `CRITICAL-PATTERNS.md` K16 |
 | `replace(tzinfo=` · `datetime.now()` **בלי** אזור זמן · כל `date.today()` · הצגת תאריך למשתמש | `RECURRING-PATTERNS.md` R7 |
-| **ברמה העליונה של מודול** (מחוץ לכל פונקציה): `Thread(`, `.start()`, `scheduler`, `asyncio.create_task`, לקוח או חיבור שנבנה מ-`os.environ`, או קריאת רשת, מסד או קובץ | `bugbot-rules/import-time-side-effects.md` |
+| **ברמה העליונה של מודול** (מחוץ לכל פונקציה): `Thread(`, `.start()`, `scheduler`, `asyncio.create_task`, לקוח או חיבור שנבנה מ-`os.environ`, או קריאת רשת, מסד או קובץ | `bugbot-rules/import-time-side-effects.md` — מה רץ בזמן ייבוא. ואם מה שנבנה שם הוא מופע של ספרייה חיצונית שמשותף לחוטים — ראה גם את השורה על מופע של ספרייה חיצונית |
 | שינוי שנעשה כדי לספק לינטר: הזזת `import`, ניקוי אזהרת escape, הרחבת `except` | `bugbot-rules/linter-fix-changes-runtime-behavior.md` |
 | מחיקה / שיתוף / שינוי שם לפי `_id` שהגיע מהממשק, `created_at`, או פעולה גורפת על `code_snippets` ו-`large_files` | `bugbot-rules/logical-entity-vs-version-document.md` |
 | שליחה לספק עם תקרת קלט (טוקנים, אורך שדה), או `value[:LIMIT]` לפני שמירה | `bugbot-rules/silent-truncation-at-sink.md` |

mcp_server/outline.py

@@ -34,6 +34,13 @@
 #:
 #: ``search`` ולא ``replace``: הוא עוצר על ההתאמה הראשונה ואינו מקצה עותק
 #: של הטקסט, שיכול להיות 10MB לפי ``RANGE_READ_MAX_BYTES``.
+#:
+#: **עותק שני של אותו כלל קיים ב-**``services/md_parser.py::_CR_WITHOUT_LF``.
+#: הוא אינו מיובא משם ולא לשם, כי ``services`` אינו מייבא מ-``mcp_server``
+#: והמסלול השני אינו עובר דרך המנתב הזה בכלל. השקילות אינה תקווה:
+#: ``tests/test_md_parser.py::test_the_lone_cr_rule_matches_markdown_it``
+#: מריץ את שניהם מול ההתנהגות של ``markdown-it-py`` עצמו. איחוד השניים
+#: בשכבת ``services`` הוא אישו נפרד.
 _CR_WITHOUT_LF = re.compile(r"\r(?!\n)")
 
 #: **השורה היחידה שהמסלול הזה כותב, והיא נכתבת כאן ולא בסורקים.** כאן יש גם

mcp_server/outline_scanners/_ceiling.py

@@ -61,6 +61,12 @@
 #:
 #: **מי שמשנה את המספר צריך למדוד מחדש את שתיהן.** העלאה בלי המדידה
 #: הראשונה מחזירה את מחלקת הכשל; הורדה בלי השנייה חוסמת קובץ אמיתי.
+#:
+#: **ויש כאן עותק שני של אותו מספר:** ``services/md_parser.py::MAX_SECTIONS``.
+#: הוא אינו מיובא מכאן, כי ``services`` אינו מייבא מ-``mcp_server``, ולכן
+#: הערך מוקלד פעמיים. מה שמונע סחיפה הוא
+#: ``tests/test_md_parser.py::test_the_two_ceilings_are_the_same_number``,
+#: שקורא את שניהם ומשווה — כלומר שינוי כאן לבדו מפיל את ה-CI.
 MAX_SYMBOLS = 50_000
 
 

requirements/base.txt

@@ -138,6 +138,37 @@ rapidfuzz==3.14.1
 # CLI Tools
 # Flask-Limiter 3.5.0 דורש rich<14 — נצמיד לגרסה יציבה תואמת
 rich==14.2.0
+
+# פארסר ה-Markdown של ``services/md_parser.py``, שבונה את מפת הסעיפים
+# ל-``codekeeper_docs_get_section``. **הוא כבר היה מותקן כאן כתלות
+# עקיפה** — ``rich`` מבקשת ``markdown-it-py>=2.2.0``, בטווח פתוח — ולכן
+# הנעיצה הישירה אינה מוסיפה משטח התקנה; היא מונעת ששדרוג של ``rich``,
+# או שינוי בפותר התלויות, יזיז את הפארסר בשקט. אותו נימוק בדיוק שכתוב
+# למעלה על ``http-ece``.
+#
+# **והמספר עצמו נגזר מ-docs/requirements.txt ולא נבחר כאחרון.**
+# ‏``myst-parser==4.0.1`` שנעוץ שם דורש ``markdown-it-py~=3.0`` ו-
+# ``mdit-py-plugins>=0.4.1,~=0.4``. נמדד: התקנה של 4.2.0 יחד איתו נופלת
+# ב-``ResolutionImpossible``, ו-``documentation-py39.yml`` מתקין את שתי
+# הקבוצות באותה סביבה. כלומר נעיצה גבוהה יותר כאן הייתה סתירה בין שני
+# קבצים באותו ריפו. נמדד גם הכיוון השני: **כל** חבילת הטסטים של
+# הפארסר, כולל 11,543 הצורות מול cmark-gfm, עוברת על 3.0.0 בדיוק כמו
+# על 4.2.0. ‏(בלי מספר טסטים: הוא משתנה בכל תוספת טסט, כולל כאלה
+# שמתווספים באותו PR, ומספר שמתיישן בכל שינוי לגיטימי הוא מספר שלומדים
+# להתעלם ממנו.)
+#
+# המעבר ל-4.x גדור בשדרוג של myst-parser ל-5.x (שדורש ``~=4.2`` ו-
+# ``mdit-py-plugins~=0.6``), והוא שינוי של שרשרת בניית התיעוד — לא של
+# הפארסר. ``tests/test_md_parser.py`` מקבע את הקשר הזה כדי ששני הצדדים
+# לא ייסחפו.
+markdown-it-py==3.0.0
+# התוסף שמזהה front matter. הוא ההגדרה ש-MyST משתמש בה, ולכן הוא הכלל
+# שקובע מהו front matter גם בקובצי ה-.md שתחת docs/ בריפו הזה. הוא נרשם
+# על מופע הפארסר במקום שנכתוב את הכלל ביד: נמדד שכלל שכתבנו בעצמנו חולק
+# על התוסף בחמש מתוך שתים-עשרה צורות — `---` מוזח, סוגר מוזח בארבעה
+# רווחים, ארבעה מקפים, סוגר ארוך מהפותח, ופותח שיש אחריו טקסט. הטבלה
+# עצמה ב-`tests/test_md_parser.py`, והמספר נגזר ממנה ולא מוקלד פעמיים.
+mdit-py-plugins==0.4.2
 typer==0.20.0
 
 # Resilience utilities

requirements/development.txt

@@ -1,6 +1,13 @@
 # Development requirements - extend production
 -r production.txt
 
+# האורקל הבלתי-תלוי של tests/test_md_parser_oracle.py: ספריית cmark-gfm
+# עצמה, כלומר הפארסר ש-GitHub מריץ בפועל. **לטסטים בלבד** — הפרודקשן
+# משתמש ב-markdown-it-py — והיא כאן ולא ב-base.txt כי אורקל שגוזר את
+# הציפייה מאותו מימוש שהוא בודק אינו אורקל. הרחבת C עם גלגלי manylinux
+# ל-cp311 ול-cp312, שתי הגרסאות שרצות ב-CI, ולכן אין קומפילציה בהתקנה.
+cmarkgfm==2025.10.22
+
 # Test frameworks
 pytest==8.4.2
 pytest-asyncio==1.2.0

scripts/compare_md_parser_to_cmark.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""משווה את ``services/md_parser`` מול cmark-gfm על **כל** קובצי ה-``.md``
+בריפו שמעבירים לו.
+
+**מה מושווה, כדי שהתוצאה לא תיקרא רחבה ממה שהיא:** לכל כותרת ברמת
+המסמך — **הרמה ומספר השורה**. טקסט הכותרת אינו מושווה כאן, כי אצלנו
+הוא המקור הגולמי ומ-cmark חוזר HTML מרונדר. הצד הזה נבדק בנפרד ועל
+תת-קבוצה, ב-``tests/test_md_parser_oracle.py``.
+
+**למה הוא קיים, ולמה זה לא טסט.** ``tests/test_md_parser_oracle.py`` רץ
+ב-CI על **צורות מחוללות** ולא על קבצים אמיתיים, וזו החלטה: קורפוס
+אמיתי הוא בדיקת שפיות חד-פעמית ולא רשת שתופסת רגרסיה עתידית, והוא היה
+דורש להחזיק בריפו הזה עותק של תוכן שאינו שלו — עותק שמתיישן ברגע
+שהמקור זז. הסקריפט הוא מה שמחליף אותו: אותה השוואה בדיוק, על הקורפוס
+החי, **על פי דרישה**.
+
+**שלוש הנקודות בזמן שבהן כדאי להריץ אותו:** לפני שלב 2 (האאוטליין
+ל-``.md``), אחרי שדרוג של ``markdown-it-py``, וכשנוגעים ב-
+``services/md_parser.py``.
+
+**ואותה השוואה פירושה אותו קוד.** האורקל אינו נכתב כאן מחדש אלא נטען
+מקובץ הטסטים, כי שני עותקים של "מה נחשב הסכמה" היו נסחפים זה מזה —
+והראשון שהיה נשבר הוא זה שרץ לעיתים רחוקות, כלומר הסקריפט.
+
+שימוש::
+
+    python scripts/compare_md_parser_to_cmark.py /path/to/amir-bug-patterns
+    python scripts/compare_md_parser_to_cmark.py /path/to/repo --out /tmp/report.txt
+
+דורש ``cmarkgfm``, שנעוץ ב-``requirements/development.txt``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import sys
+from pathlib import Path
+
+_REPO = Path(__file__).resolve().parent.parent
+# לפני כל ייבוא מ-``services``: הסקריפט רץ כנקודת כניסה עצמאית,
+# ו-``scripts`` אינה חבילה.
+sys.path.insert(0, str(_REPO))
+
+from services.doc_sections import InconsistentLineEndings, TooManySections  # noqa: E402
+
+
+def _load_oracle():
+    """טוען את האורקל מקובץ הטסטים — הגדרה אחת לשני המריצים."""
+    spec = importlib.util.spec_from_file_location(
+        "md_parser_oracle", _REPO / "tests" / "test_md_parser_oracle.py"
+    )
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    # הנתיב הוא ארגומנט **חובה** ובלי ברירת מחדל: ברירת מחדל ל-``.``
+    # הייתה גורמת לסקריפט לסרוק את הריפו שהוא עצמו יושב בו, ולדווח
+    # "אפס פערים" על קורפוס שאינו הקורפוס.
+    parser.add_argument("repo", type=Path, help="שורש הריפו שקובצי ה-.md שלו ייסרקו")
+    parser.add_argument("--out", type=Path, default=None, help="קובץ דוח (ברירת מחדל: stdout)")
+    args = parser.parse_args(argv)
+
+    root: Path = args.repo.expanduser().resolve()
+    if not root.is_dir():
+        parser.error(f"אינו תיקייה: {root}")
+
+    oracle = _load_oracle()
+    files = sorted(p for p in root.rglob("*.md") if ".git" not in p.parts)
+    if not files:
+        parser.error(f"אפס קובצי .md תחת {root} — זה כישלון, לא ריצה ריקה")
+
+    lines: list[str] = []
+    skipped: list[str] = []
+    mismatched = 0
+    compared = 0
+    total_headings = 0
+    for path in files:
+        name = path.relative_to(root)
+        # **``read_bytes().decode`` ולא ``read_text``.** האחרון פותח את
+        # הקובץ במצב טקסט עם universal newlines וממיר כל ``\r`` ל-
+        # ``\n`` לפני שהמחרוזת מגיעה לפארסר — כלומר
+        # ``InconsistentLineEndings`` לא הייתה יכולה להידלק כאן על שום
+        # קובץ, והסקריפט היה מדווח "אפס אי-הסכמות" גם על מחלקת קלט
+        # שבורה לגמרי. ``newline=""`` אינו פתרון: הפרמטר נוסף ל-
+        # ``Path.read_text`` רק בפייתון 3.13, וה-CI רץ על 3.11 ו-3.12.
+        #
+        # **וכל קובץ עומד בפני עצמו.** הסקריפט מכוון על ריפו זר, ולכן
+        # קובץ מוזר הוא המקרה הצפוי ולא החריג — נפילה עליו הייתה מוחקת
+        # גם את התוצאות של כל מה שכבר נסרק, כי הדוח נבנה אחרי הלולאה.
+        # **``utf-8`` ולא ``utf-8-sig`` — בכוונה.** הסקריפט הוא בדיקה של
+        # הפארסר, ו-``parse_document`` הוא זה שמסיר BOM. אילו הפענוח כאן
+        # היה מסיר אותו קודם, רגרסיה בדיוק בהתנהגות הזאת הייתה בלתי
+        # נראית מכאן. הייצור מפענח אחרת — ``git_mirror_service.
+        # _try_decode_content`` משתמש ב-``utf-8-sig`` — וזה בסדר: שם
+        # המטרה היא תוכן נקי, כאן המטרה היא לראות מה הפארסר עושה.
+        try:
+            text = path.read_bytes().decode("utf-8")
+            ours = oracle._ours(text)
+            theirs = oracle._oracle_sections(text)
+        except UnicodeDecodeError:
+            skipped.append(f"⊘ {name} — אינו UTF-8")
+            continue
+        except OSError as exc:
+            skipped.append(f"⊘ {name} — לא ניתן לקריאה: {exc.strerror}")
+            continue
+        except InconsistentLineEndings:
+            skipped.append(f"⊘ {name} — ‏\\r בודד, הפארסר סירב")
+            continue
+        except TooManySections as exc:
+            skipped.append(f"⊘ {name} — מעל התקרה, הפארסר סירב בשורה {exc.args[0]}")
+            continue
+
+        compared += 1
+        total_headings += len(theirs)
+        if ours != theirs:
+            mismatched += 1
+            lines.append(f"✘ {name}")
+            lines.append(f"    שלנו : {ours}")
+            lines.append(f"    cmark: {theirs}")
+
+    header = [
+        f"ריפו:       {root}",
+        f"קבצים:      {len(files)} (הושוו {compared}, סורבו {len(skipped)})",
+        f"כותרות:     {total_headings} (לפי cmark-gfm, ברמת המסמך)",
+        f"אי-הסכמות:  {mismatched} — ההשוואה היא על **רמה ומספר שורה** בלבד,",
+        "            ולא על טקסט הכותרת. ההנמקה בראש קובץ האורקל.",
+        "",
+    ]
+    if skipped:
+        header.extend(skipped)
+        header.append("")
+    report = "\n".join(header + lines) + "\n"
+    if args.out:
+        args.out.write_text(report, encoding="utf-8")
+        print(f"הדוח נכתב ל-{args.out}")
+    print(report)
+
+    # **"אפס אי-הסכמות" על אפס קבצים שהושוו אינו הצלחה.** מאותו נימוק
+    # בדיוק שכתוב למעלה על ריפו בלי קובצי ``.md``: מספר שנראה טוב כי
+    # לא נבדק דבר הוא אישור שקרי, ומי שיראה ``exit 0`` יסיק שהפארסר
+    # מסכים עם cmark על הקורפוס הזה.
+    if not compared:
+        print("כל הקבצים סורבו — לא הושווה דבר, וזה כישלון ולא ריצה נקייה.")
+        return 1
+    return 1 if mismatched else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/generate_ai_map.py

@@ -130,6 +130,22 @@ def _body_start(lines: list[str]) -> int:
 
     לפי ``markdown_it``/MyST, front matter הוא בלוק שנפתח ב-``---`` בשורה
     הראשונה ממש ונסגר ב-``---`` או ``...``.
+
+    .. warning::
+
+       **הכלל כאן אינו מדויק מול התוסף שהוא מתאר, וזה נמדד.**
+       ``mdit_py_plugins.front_matter`` — שהוא מה ש-MyST באמת מריץ, וש-
+       ``services/md_parser.py`` רושם על מופע הפארסר שלו במקום לכתוב את
+       הכלל ביד — חולק על הפונקציה הזאת בחמש צורות: ``---`` מוזח (כאן
+       מתקבל, שם נדחה), ``----`` בן ארבעה מקפים, סוגר ארוך מהפותח, פותח
+       שיש אחריו טקסט, וסוגר מוזח בארבעה רווחים שהוא בלוק קוד. בקורפוס
+       של היום אין לאף אחת מהן מופע — 23 מתוך 34 קובצי ה-``.md`` תחת
+       ``docs/`` פותחים ב-``---`` מדויק — ולכן המפה שנוצרת כאן נכונה.
+
+       הפער מקובע ב-
+       ``tests/test_md_parser.py::test_the_front_matter_rules_still_disagree_as_measured``
+       כדי שלא ייסחף בשקט, והיעד — שהפונקציה הזאת תשתמש בתוסף — הוא
+       אישו נפרד.
     """
     if not lines or lines[0].strip() != "---":
         return 0