fix(webapp): קישורי תפריט פנימיים במסמכי Markdown לא גללו לסעיף

[amirbiron]

What

לחיצה על קישור בתוכן העניינים של מסמך Markdown ([תקשורת](#communication)) לא גללה לסעיף. תוקן מהשורש, בלי לוותר על הגנת ה-XSS.

ה-PR כולל גם את עמוד התיעוד החדש ל-Config Inspector ואת עדכון CLAUDE.md (הקומיט הקודם בענף).

Why

מסמכים רבים (בעיקר כאלה שנכתבו ל-GitHub) מגדירים עוגן לכותרת בתחביר HTML:

## 1. תקשורת <a id="communication"></a>

ה-renderer רץ עם html: false — הגנת XSS על תוכן שמשתמשים מעלים — ולכן התגית לא הופכת לאלמנט. אומת בשחזור מלא מול markdown-it האמיתי של הריפו, ונמצאו שלושה נזקים:

1. אין אלמנט עם id="communication" → הקישור לא מוביל לשומקום (קישורים בתוך התוכן נשענים על התנהגות דפדפן טבעית — אין להם handler).
2. התגית מוצגת כטקסט זבל גלוי בתוך הכותרת.
3. אותו טקסט נבלע ל-id האוטומטי ומייצר slug מעוות: id="1-תקשורת-a-idcommunicationa".

באג נוסף שהתגלה אגב: הגלילה לפי עוגן שבכתובת השתמשה ב-querySelector(hash). מזהה שמתחיל בספרה (כמו 1-תקשורת מכותרת ממוספרת) אינו סלקטור CSS חוקי — הקריאה זרקה, כך שגם כניסה לעמוד עם #hash כזה הייתה שבורה.

✨ תיאור קצר

• שליפת עוגני HTML ממקור ה-Markdown לפני הרינדור וניקוי הטקסט; אחרי הרינדור מוסיפים אלמנט יעד בלתי-נראה לפני הכותרת. html: false נשמר — לא נפתחה פרצה.
• תוקן גם querySelector(hash) → getElementById עם decode.
• (מהקומיט הקודם בענף) עמוד docs/webapp/config-inspector.rst + עדכון הנחיית Sphinx ב-CLAUDE.md.

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

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

פירוט נקודות:

• webapp/static/js/md-anchors.js (חדש): extractExplicitAnchors / applyExplicitAnchors / renderWithAnchors. תומך גם בעוגן בשורה נפרדת לפני הכותרת (דפוס GitHub), ב-name= לצד id=, ובכמה עוגנים לאותה כותרת; מדלג על בלוקי קוד.
• אבטחה: ה-id מוצב דרך element.id (DOM property) ולא דרך innerHTML — אין וקטור הזרקה; בנוסף יש סניטציה של המזהה.
• מזהי הכותרות עצמם לא נדרסים — הם משמשים לסימניות על כותרות, ודריסה הייתה שוברת סימניות קיימות. לכן נוצר יעד נפרד ולא שונה heading.id.
• חובר ל-md_preview.html (הצופה הראשי) ול-live-preview.js (תצוגה מקדימה בעורך — אותו באג), עם fallback שקט אם המודול לא נטען.
• CSS: scroll-margin-top ליעד כדי שהכותרת לא תיעצר מתחת לסרגל העליון.
• docs/webapp/config-inspector.rst: למה עמוד 1 = Webapp בלבד, מה בעמוד 2, איך נמנעים מסטטוס Modified שגוי, איך בודקים שיוך שירות לפני הוספת משתנה, ומה מתעדים כשמשתנה משרת כמה שירותים.

🧪 בדיקות

• איך בדקתם? שחזור לפני/אחרי מול markdown-it האמיתי של הריפו + טסטים אוטומטיים + בניית Sphinx עם -W.
• Unit — node tests/md-anchors.test.js: 21 בדיקות ירוקות (שליפה, דפוס GitHub, דילוג על בלוקי קוד, כמה עוגנים, סניטציה, והחלה על DOM כולל אי-דריסת מזהה תפוס). 81 טסטי פייתון קיימים נשארו ירוקים; לא נגעתי בשום קובץ .py בתיקון ה-Markdown.
• Integration
• Manual — נדרש אחרי דיפלוי: לפתוח מסמך עם תוכן עניינים וללחוץ על פריט

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

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

📝 סוג שינוי

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

Rollback: revert של הקומיטים; המודול עצמאי ויש fallback — אם הוא לא נטען, ההתנהגות חוזרת לקודמת. אין מיגרציות.

ידוע ולא בהיקף: webapp/static/js/repo-browser.js (עיון בקבצי GitHub) מרנדר Markdown בלי plugin העוגנים כלל, ולכן שם לכותרות אין id מלכתחילה ושום קישור פנימי לא יעבוד — פער נפרד שממתין להחלטה.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WNFuSyshwpRcxozVZEui5K

[chatgpt-codex-connector]

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

[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): 129

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

Excluded matches (by path pattern)

./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/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]
./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/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/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/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
./Dockerfile:42:    rm -rf /var/lib/apt/lists/*
./Dockerfile:121:    rm -rf /var/lib/apt/lists/*
./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)
./README.md:842:find . -name "__pycache__" -exec rm -rf {} +

[coderabbitai]

Warning

Review limit reached

@amirbiron, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 32 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3abe4b9b-7938-4182-96f3-17ad4555d59f

📥 Commits

Reviewing files that changed from the base of the PR and between 552f4f5 and e8b669b.

📒 Files selected for processing (6)

• docs/webapp/config-inspector.rst
• tests/md-anchors.test.js
• webapp/static/js/live-preview.js
• webapp/static/js/md-anchors.js
• webapp/static/js/repo-browser.js
• webapp/templates/repo/base_repo.html

📝 Walkthrough

Walkthrough

נוספה תמיכה בעוגני HTML מפורשים במסמכי Markdown, כולל חילוץ, סניטציה, רינדור והחלה ב-DOM, בדיקות ייעודיות ושילוב בתבניות התצוגה. נוסף גם תיעוד Config Inspector ועדכוני ניווט וכללי Sphinx.

Changes

עוגני Markdown

Layer / File(s)	Summary
חילוץ והחלת עוגנים webapp/static/js/md-anchors.js	נוסף API שמזהה עוגנים מחוץ לבלוקי קוד, מנקה מזהים ומוסיף יעדים בלתי נראים לפני כותרות.
שילוב בזרימות הרינדור webapp/static/js/live-preview.js, webapp/templates/edit_file.html, webapp/templates/md_preview.html, webapp/templates/upload.html	עוגנים משולבים ברינדור הראשוני ובתצוגה החיה, עם טעינת סקריפט, CSS ושחזור גלילה לפי getElementById.
בדיקות עוגנים tests/md-anchors.test.js	נבדקים חילוץ, סניטציה, שיוך לכותרות, החלה על DOM מדומה, מניעת דריסה ומקרי קצה.

תיעוד Config Inspector

Layer / File(s)	Summary
תיעוד וניווט Sphinx docs/webapp/config-inspector.rst, docs/index.rst, docs/environment-variables.rst, CLAUDE.md	נוסף מדריך Config Inspector, קישור אליו מתיעוד משתני הסביבה, רישום ב-toctree והנחיות מעודכנות לעמודי Sphinx.

Estimated code review effort: 4 (Complex) | ~45 minutes

Poem

עוגן קטן קפץ אל הכותרת,
Markdown קיבל כתובת מסודרת.
ה-DOM לחש: “מצאתי יעד”,
והתיעוד נרשם בצד.
Claude Code כתב — והכול הסתדר ✨
CodeKeeper forever 💫

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Title check	✅ Passed	הכותרת מתארת היטב את התיקון המרכזי: קישורי עוגן/תפריט ב-Markdown שלא גללו לסעיף.
Description check	✅ Passed	התיאור כולל What, Why, שינויים עיקריים, בדיקות, סוג שינוי, סיכון ו-Rollback, ולכן הוא כמעט מלא ועומד בתבנית.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/mcp-codekeeper-webapp-ldnzsg

---

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

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

[github-actions]

⏱️ Performance report

• Run: https://github.com/amirbiron/CodeBot/actions/runs/30537741860
• 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: Thu, 30 Jul 2026 11:16:12 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!

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (1)

webapp/static/js/live-preview.js (1)

440-466: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

מצב משותף (module-level) בין render() ל-enhance() — תלוי בסדר קריאות חיצוני.

pendingExplicitAnchors הוא state גלובלי שנקבע ב-render() ונצרך רק בקריאה נפרדת ל-enhance(root). אם render מופעל שוב (למשל debounce שמתחיל מחזור רינדור נוסף) לפני ש-enhance נקרא על התוצאה הקודמת, ה-state יידרס והעוגנים שיוחלו לא יתאימו ל-DOM שכבר מוצג. קשה לוודא נכונות בלי לראות את קוד הקורא (debounce/scheduler) של הקבצים האלה.

מומלץ להחזיר את anchors מתוך render() (למשל כחלק מאובייקט תוצאה) ולהעביר אותם במפורש ל-enhance/applyPendingAnchors, במקום להסתמך על state חיצוני משותף.

Also applies to: 483-495

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@webapp/static/js/live-preview.js` around lines 440 - 466, Remove the
module-level pendingExplicitAnchors coupling between render() and enhance().
Return anchors from render() as part of its result, pass them explicitly into
enhance(root), and update applyPendingAnchors to consume that parameter so
consecutive renders cannot overwrite anchors awaiting application.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/webapp/config-inspector.rst`:
- Around line 131-133: Update the variable-search commands in the documented
configuration-inspector examples to search for the variable name without
requiring double quotes, so usages such as os.getenv('MY_VAR') are found. Use rg
or equivalent built-in directory exclusions to omit test directories, and apply
the same change to both referenced command blocks.
- Around line 30-32: עדכנו את ההערה המתארת את מיסוך הערכים כך שתציין במפורש שרק
ערכים שסווגו כרגישים ממוסכים תמיד, תוך שמירה על ההפניה הקיימת
ל-config-inspector-sensitive ולפרטי הרשאות האדמין.

In `@webapp/static/js/md-anchors.js`:
- Line 27: Update the heading-counting logic used by renderWithAnchors so
headingIndex includes both ATX and Setext headings, matching the generated h1–h6
elements. Respect the markdown configuration by excluding Setext headings when
md.disable('lheading') is enabled, and apply the same behavior through the
exported renderWithAnchors path.
- Around line 27-128: Update extractExplicitAnchors in
webapp/static/js/md-anchors.js (lines 27-128) to recognize Setext headings
formed by a text line followed by a valid === or --- underline, increment
headingIndex for them, and associate both inline and preceding standalone
anchors with the Setext heading while preserving ATX handling. Add mixed
Setext/ATX anchor coverage in tests/md-anchors.test.js (lines 41-93) to verify
correct heading indices and anchor assignment.

---

Nitpick comments:
In `@webapp/static/js/live-preview.js`:
- Around line 440-466: Remove the module-level pendingExplicitAnchors coupling
between render() and enhance(). Return anchors from render() as part of its
result, pass them explicitly into enhance(root), and update applyPendingAnchors
to consume that parameter so consecutive renders cannot overwrite anchors
awaiting application.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: cdf553ac-f322-489b-af93-7be54068ba36

📥 Commits

Reviewing files that changed from the base of the PR and between cf98d5f and 552f4f5.

📒 Files selected for processing (10)

• CLAUDE.md
• docs/environment-variables.rst
• docs/index.rst
• docs/webapp/config-inspector.rst
• tests/md-anchors.test.js
• webapp/static/js/live-preview.js
• webapp/static/js/md-anchors.js
• webapp/templates/edit_file.html
• webapp/templates/md_preview.html
• webapp/templates/upload.html