fix(mcp): תקרה לרשימת המועמדים של ambiguous_section, וטסט שמקבע את חוזה Suggestions במסלול ה-Markdown (#3426)

[amirbiron]

✨ תיאור קצר

• candidates היה השדה היחיד בתשובת codekeeper_docs_get_section בלי תקרה: toc חסום ב-400, suggestions ב-50, ורק המועמדים חזרו כולם. נמדד בסקירת feat(mcp): docs_get_section מוצא סעיף לפי מזהה, ולא רק לפי השם המלא #3425: עמוד סינתטי של 512KB עם 13,030 כותרות שנפתחות ב-K11. החזיר 13,030 מועמדים — 1,393,787 בתים ושיא הקצאה של 12.6MB — על שאילתה בת שלושה תווים. הענף נדלק מכותרות שנושאות מזהה, ומאז feat(mcp): docs_get_section קורא גם Markdown, לפי מדיניות נתיבים לכל ריפו #3428 הקורפוס שנושא אותם (amir-bug-patterns) מוגש, ולכן זה חוב פתוח בייצור ולא מניעה.
• עכשיו המועמדים חסומים ב-50, עם candidates_truncated: true רק כשנחתך — אותה מוסכמה של suggestions_truncated, remaining_chars ו-next_offset. ובאותו PR: טסט שמקבע שגם במסלול ה-Markdown suggestions הוא רשימת מחרוזות ולא ה-NamedTuple (הפריט השני ב-docs_get_section: תקרה ל-candidates, ושמירת חוזה Suggestions — לפני שחיבור ה-Markdown נוחת #3426).

📦 שינויים עיקריים

• קוד (Backend)
• בוט טלגרם
• מסד נתונים/מיגרציות
• תיעוד (docs/)
• DevOps/CI/CD

פירוט נקודות (רשימת תבליטים):

• אומת מול הקוד של היום, לא מול גוף האישו: פריט 1 עדיין פתוח (candidates נבנה מכל matches בלי גבול); פריט 2 השתנה מאז שנכתב — "הצרכן השני" מ-feat(mcp): docs_get_section קורא גם Markdown, לפי מדיניות נתיבים לכל ריפו #3428 הוא בפועל אותו אתר קריאה שמשרת את שני הפורמטים (doc_sections.suggest נקרא פעם אחת ב-docs_handlers), והוא כבר כותב .titles. לכן שם אין תיקון, יש טסט שמקבע.
• mcp_server/docs_handlers.py: _CANDIDATES_MAX = 50 — אותו מספר כמו doc_sections.MAX_IDENTIFIER_SUGGESTIONS ומאותה סיבה: רשימת המועמדים היא מלאי בסדר הופעה ולא דירוג, ולכן חיתוך שלה מסתיר פריטים בלי קריטריון, והתקרה גבוהה מספיק שכל עמוד אמיתי ייענה במלואו (כותרת כפולה בקורפוס חוזרת פעמיים או שלוש). השוויון בין שני המספרים מקובע בטסט, כמו שני גבולות האאוטליין והפארסר.
• R6, ולא עותק שני: החיתוך של toc (שהיה inline ב-_toc) ושל candidates עובר דרך עוזר אחד, _capped(items, limit), שמחזיר (items, truncated) — True רק כשהיו יותר מהתקרה, ולעולם לא על רשימה שבדיוק בגודלה (אותו גבול כמו Capped.append ו-max_sections).
• הדגל מותנה, וזה מה שמחזיק את אפס-הדיף: שדה שקיים תמיד היה משנה כל תשובת ambiguous_section בתצלום בלי ששום התנהגות השתנתה.
• תיאור הפרמטר section ב-mcp_server/server.py אומר את התקרה והדגל; docs/mcp-server.rst (הסעיף על ambiguous_section) ו-docs/whats-new.rst עודכנו.
• שורה ריקה אחת נוספה ב-server.py לפני _build_docs_path_doc — E302 שהגיע עם feat(mcp): docs_get_section קורא גם Markdown, לפי מדיניות נתיבים לכל ריפו #3428; CI בוחר רק E9,F63,F7,F82 ולכן לא נפל שם, אבל flake8 בקונפיג של הריפו כן.

🧪 בדיקות

• איך בדקתם? מה עבר? מה נשאר?
• Unit — 135 טסטים ב-tests/test_mcp_docs_handlers.py + tests/test_doc_sections.py, ו-36 ב-tests/test_mcp_server_build.py, ירוקים; flake8 נקי.
• שלושה טסטים חדשים: test_candidates_are_capped_and_the_flag_appears_only_when_they_were_cut (התקרה מוקטנת ל-2 דרך המודול, כמו בטסט תקרת הסקשנים, במקום לבנות 51 כותרות: בדיוק בתקרה — בלי דגל; מעליה — שני הראשונים בסדר הופעה והדגל True), test_the_candidates_cap_is_the_suggestions_inventory_number, ו-test_suggestions_on_a_markdown_page_are_a_list_of_strings_too (דרך הריפו של ה-Markdown, both_repos).
• הטסטים החדשים על הקוד הישן (origin/main, ב-worktree נפרד): טסט התקרה וטסט השוויון נופלים; טסט ה-Markdown עובר — הוא מקבע התנהגות קיימת, וזה מה שהאישו ביקש.
• אפס-דיף מדוד: scripts/docs_section_zero_diff.py על אותו קורפוס (ה-docs/ של origin/main, כדי שעריכות התיעוד של ה-PR לא יזהמו את ההשוואה), פעם על הקוד הישן ופעם על החדש — 5,928 רשומות בשתיהן, sha256 זהה (f31c53f5…2db87), cmp בינארי: זהה.
• Integration — לא רלוונטי (אין שירות חיצוני).
• Manual — docutils על שני עמודי התיעוד בלי אזהרות מרקאפ (לא בנייה מלאה, לפי CLAUDE.md; RTD יתפוס על ה-PR).

🧪 בדיקות נדרשות ב‑PR

• 🔍 Code Quality & Security
• Unit Tests (3.11)
• Unit Tests (3.12)

📝 סוג שינוי

• feat: פיצ'ר חדש
• fix: תיקון באג
• docs: שינוי תיעוד בלבד
• refactor: שינוי קוד ללא שינוי התנהגות
• perf: שיפור ביצועים
• chore/ci: תשתית/CI
• breaking change: שינוי שובר תאימות

✅ צ'קליסט

• הקוד עוקב אחרי הסגנון (Black/isort/flake8/mypy)
• בדיקות רצות ועוברות
• תיעוד עודכן (README/Docs)
• אם נוספו ג'ובים חדשים (Background Jobs) – לא נוספו
• אם נוספו/שונו משתני סביבה – לא נוספו
• אם נוספו/השתנו טוקנים – לא רלוונטי
• אין סודות/מפתחות בקוד
• אין מחיקות מסוכנות/פעולות על root (ראו .cursorrules)
• הודעת הקומיט תואמת Conventional Commits (ע"פ הטבלה)
• CHANGELOG עודכן אם נדרש — docs/whats-new.rst
• כל ה‑Required Checks לעיל ירוקים
• צילום/וידאו UI מצורף אם רלוונטי — אין UI
• עיינתי במסמכי אתר התיעוד — נתיב: AI-MAP.md ← docs/mcp-server.rst ("איך docs_get_section מוצא כותרת", והסעיף על 50 ההצעות) | המשפט: "והכמות: עד 50 הצעות. ... התקרה גבוהה מספיק כדי שעמוד רגיל ייענה במלואו" — זה הנימוק שהתקרה החדשה יורשת. וגם docs/doc-authoring.rst (בלי מספרי שורות, בלי שינוי עוגנים). מ-amir-bug-patterns: bugbot-rules/silent-truncation-at-sink.md (חיתוך שאינו שקט — הדגל), RECURRING-PATTERNS.md R6 (עוזר אחד לשני הגבולות), claude-md-snippets/testing.md (הטסטים הורצו על הקוד הישן).
• לא נדרש עיון — לא רלוונטי, עיון נעשה

🧩 השפעות/סיכונים

• שינוי חוזה קטן בכלי ציבורי: תשובת ambiguous_section נושאת לכל היותר 50 מועמדים, ומעבר לזה candidates_truncated: true. אף עמוד אמיתי בקורפוס אינו מגיע לזה (אפס-דיף על 208 קובצי ה-RST), ולכן ההשפעה בפועל היא רק על קלט שנבנה בכוונה.

🔗 קישורים

• Issues קשורים: docs_get_section: תקרה ל-candidates, ושמירת חוזה Suggestions — לפני שחיבור ה-Markdown נוחת #3426 (סוגר את שני הפריטים)
• Docs Preview:
• מסמכים/מפרטים רלוונטיים:
• Branch Protection & PR Rules
• הדוח המקורי: code-review-3425-identifier-lookup.md ב-CodeKeeper

🧯 סיכון / החזרה לאחור (Rollback)

• תוכנית חזרה לאחור במקרה תקלה: revert של הקומיט היחיד; אין שינוי בסכימה, במסד או במשתני סביבה.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SfJTSpDAhDr2yhtmpFkwTx

---

Generated by Claude Code

Summary by Sourcery

Prevent oversized ambiguous-section responses while preserving existing results and suggestion output contracts.

Bug Fixes:

• Cap ambiguous-section candidate results at 50 items and report candidates_truncated only when candidates are actually omitted.
• Add regression coverage ensuring Markdown suggestions remain a list of strings.

Enhancements:

• Centralize TOC and candidate truncation behavior to preserve consistent boundary semantics and document the updated response contract.

Documentation:

• Document the candidate limit and conditional truncation flag for ambiguous section responses and record the change in release notes.

Tests:

• Add coverage for candidate caps, exact-limit behavior, shared cap alignment with identifier suggestions, and Markdown suggestions.

[qodo-code-review]

ⓘ Qodo reviews are paused because your trial has ended. Ask your workspace admin to add credits to resume reviews. Manage billing

[sourcery-ai]

Sorry @amirbiron, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 1 hour and 22 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[sourcery-ai]

Reviewer's Guide

This PR bounds ambiguous_section candidate lists to 50 entries, reports candidates_truncated only when candidates are actually omitted, and consolidates truncation behavior while adding regression tests for both the new contract and Markdown suggestion serialization. Documentation and tool descriptions are updated, with corpus-level zero-diff validation intended to confirm no changes to unaffected responses.

Sequence diagram for capped ambiguous section candidates

sequenceDiagram
    participant Client
    participant DocsHandler as docs_handlers
    participant Document

    Client->>DocsHandler: docs_get_section(section)
    DocsHandler->>Document: find matching sections
    Document-->>DocsHandler: matches
    alt multiple matches
        DocsHandler->>DocsHandler: _capped(matches, _CANDIDATES_MAX)
        DocsHandler-->>Client: ambiguous_section with up to 50 candidates
        opt more than 50 matches
            DocsHandler-->>Client: candidates_truncated: true
        end
    end

Loading

File-Level Changes

Change	Details	Files
Cap ambiguous-section candidate results and expose truncation only when data is actually omitted.	Add a 50-item candidates limit aligned with the suggestions inventory limit. Centralize TOC and candidate slicing in a shared helper with exact-boundary truncation semantics. Return candidates in document order and add conditional candidates_truncated metadata. Document the response contract and rationale for the new cap.	mcp_server/docs_handlers.py mcp_server/server.py docs/mcp-server.rst docs/whats-new.rst
Add regression coverage for candidate limiting and Markdown suggestion output.	Verify exact-cap responses omit the truncation flag while oversized responses retain the first items and set it. Lock equality between the candidates cap and MAX_IDENTIFIER_SUGGESTIONS. Verify Markdown suggestions are serialized as a list of strings.	tests/test_mcp_docs_handlers.py
Preserve existing behavior for unaffected documentation responses.	Validate zero-diff output against the existing corpus after introducing the conditional field. Keep the formatting fix required by repository flake8 configuration.	mcp_server/docs_handlers.py mcp_server/server.py tests/test_mcp_docs_handlers.py

Possibly linked issues

• docs_get_section: תקרה ל-candidates, ושמירת חוזה Suggestions — לפני שחיבור ה-Markdown נוחת #3426: PR docs_get_section: תקרה ל-candidates, ושמירת חוזה Suggestions — לפני שחיבור ה-Markdown נוחת #3426 directly addresses both issue findings: capped candidates with conditional truncation and validated Markdown suggestions output.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[github-actions]

🧯 Dangerous deletes guard report

Policy: see .cursorrules — dangerous deletions are blocked unless wrapped safely.

Summary:

• Flagged findings (blocking): 0
  0
• Excluded matches (not blocking): 15
• Total matches (all files): 128

Flagged findings (file:line:snippet):
(none)

Excluded matches (by path pattern)

./webapp/static/js/md_preview.bundle.js.map:4:  "sourcesContent": ["// Markdown-it plugin to render GitHub-style task lists; see\n//\n// https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-comments\n// https://github.com/blog/1825-t … [truncated]
./docs/DOCUMENTATION_GUIDE.md:453:rm -rf _build
./docs/Makefile:24:	rm -rf $(BUILDDIR)
./Dockerfile:42:    rm -rf /var/lib/apt/lists/*
./Dockerfile:121:    rm -rf /var/lib/apt/lists/*
./node_modules/katex/package.json:153:    "build": "rimraf dist/ && mkdirp dist && cp README.md dist && rollup -c --failAfterWarnings && webpack && node update-sri.js package dist/README.md",
./node_modules/katex/src/fonts/Makefile:139:	rm -rf pfa ff otf ttf woff woff2
./node_modules/mermaid/dist/mermaid.js.map:4:  "sourcesContent": ["/**\n* Default values for dimensions\n*/\nconst defaultIconDimensions = Object.freeze({\n\tleft: 0,\n\ttop: 0,\n\twidth: 16,\n\theight: 16\n});\n/**\n* Default values for tr … [truncated]
./node_modules/mermaid/dist/chunks/mermaid.esm/chunk-2M32CCKP.mjs.map:4:  "sourcesContent": ["{\n  \"name\": \"mermaid\",\n  \"version\": \"11.12.0\",\n  \"description\": \"Markdown-ish syntax for generating flowcharts, mindmaps, sequence d … [truncated]
./node_modules/mermaid/dist/chunks/mermaid.esm.min/chunk-4HFYJGYH.mjs.map:4:  "sourcesContent": ["{\n  \"name\": \"mermaid\",\n  \"version\": \"11.12.0\",\n  \"description\": \"Markdown-ish syntax for generating flowcharts, mindmaps, sequen … [truncated]
./node_modules/mermaid/dist/chunks/mermaid.esm.min/chunk-4HFYJGYH.mjs:1:var r={name:"mermaid",version:"11.12.0",description:"Markdown-ish syntax for generating flowcharts, mindmaps, sequence diagrams, class diagrams, gantt charts, git graph … [truncated]
./node_modules/mermaid/dist/chunks/mermaid.core/chunk-KS23V3DP.mjs.map:4:  "sourcesContent": ["{\n  \"name\": \"mermaid\",\n  \"version\": \"11.12.0\",\n  \"description\": \"Markdown-ish syntax for generating flowcharts, mindmaps, sequence  … [truncated]
./node_modules/mermaid/dist/mermaid.min.js:1524:`,"getStyles"),c1e=RQe});var h1e={};dr(h1e,{diagram:()=>NQe});var NQe,f1e=N(()=>{"use strict";$ge();a1e();l1e();u1e();NQe={parser:Fge,db:n1e,renderer:o1e,styles:c1e}});var m1e,g1e=N(()=>{"use  … [truncated]
./node_modules/mermaid/dist/mermaid.min.js.map:4:  "sourcesContent": ["/**\n* Default values for dimensions\n*/\nconst defaultIconDimensions = Object.freeze({\n\tleft: 0,\n\ttop: 0,\n\twidth: 16,\n\theight: 16\n});\n/**\n* Default values fo … [truncated]
./README.md:842:find . -name "__pycache__" -exec rm -rf {} +

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 5d7d990b-2af8-446e-8d50-01da2fa920ed

📥 Commits

Reviewing files that changed from the base of the PR and between 3b8628f and b15461a.

📒 Files selected for processing (5)

• docs/mcp-server.rst
• docs/whats-new.rst
• mcp_server/docs_handlers.py
• mcp_server/server.py
• tests/test_mcp_docs_handlers.py

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

העדכון מגביל את ambiguous_section ל-50 מועמדים, מוסיף את candidates_truncated רק לאחר חיתוך, מאחד את לוגיקת החיתוך, מוסיף בדיקות, ומעדכן את תיעוד השרת ויומן השינויים.

Changes

הגבלת מועמדים בזרימת החיפוש

Layer / File(s)	Summary
מימוש תקרת המועמדים mcp_server/docs_handlers.py	נוסף _CANDIDATES_MAX עם ערך 50 ונוסף _capped. מסלול ambiguous_section מחזיר עד 50 מועמדים ומוסיף candidates_truncated: True רק כאשר הרשימה נחתכת.
בדיקות ההתנהגות tests/test_mcp_docs_handlers.py	הבדיקות מאמתות חיתוך לפי התקרה, שמירת סדר ההופעה, היעדר הדגל כאשר אין חיתוך, התאמה ל-MAX_IDENTIFIER_SUGGESTIONS, וסוג suggestions במסלול Markdown.
תיעוד חוזה התשובה mcp_server/server.py, docs/mcp-server.rst, docs/whats-new.rst	תיעוד השרת, מדריך ה-MCP ויומן השינויים מתארים את התקרה ואת candidates_truncated. נוסף גם תיקון עיצוב קטן בתיעוד path.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Medium

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 54.55% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 3 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	הכותרת מתארת בצורה ברורה את השינוי המרכזי: הגבלת רשימת המועמדים של ambiguous_section והוספת בדיקת חוזה ל-Suggestions במסלול Markdown. הכותרת מעט ארוכה, אך היא ממוקדת ורלוונטית.
Description check	✅ Passed	תיאור ה-PR מקיף את המטרה, השינויים, הבדיקות, הסיכונים, התיעוד ותוכנית החזרה לאחור. הוא מציין גם שבדיקות ה-Required Checks עדיין לא סומנו כירוקות ושאין קישור פעיל ל-Docs Preview, אך אלה אינם מונעים מעב…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 54.55% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 3 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{חמישים מועמדים עומדים בשורה,
ודגל קטן מודיע על גזירה.
הבדיקות שומרות על הסדר והדיוק,
Claude Code מקבל מחיאות כפיים על החיזוק.
התיעוד מאיר את הנתיב,
CodeKeeper forever 💫}

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

⏱️ Performance report

• Run: https://github.com/amirbiron/CodeBot/actions/runs/35541949426
• Artifact: perf-durations

(No performance test durations collected. Mark tests with @pytest.mark.performance.)

[github-actions]

📖 Documentation Preview

The documentation has been built successfully!

• 📦 Download Documentation Artifacts
• 🔍 Check the workflow summary for coverage report
• 📊 Build completed at: Sun, 20 Sep 2026 22:33:59 GMT

To view locally:

1. Download the artifacts
2. Extract the zip file
3. Open index.html in your browser

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[amirbiron]

נכנס דרך #3443