جستجوی کد با گراف کد

این راهنما نشان می‌دهد چگونه یک مخزن را به گراف کد بیاورید و سپس از آن برای پاسخ به همان پرسشی استفاده کنید که پیش از بازآرایی واقعاً دارید: چه چیزی به این وابسته است؟

گراف کد یک پایگاه‌دادهٔ نماد و یال است که با تجزیهٔ چک‌اوت‌های ثبت‌شدهٔ شما به‌کمک tree-sitter ساخته می‌شود. ابزارهایش رو به عامل هستند — دسترسی به آن‌ها با درخواست از یک عامل ممکن است.

پیش از شروع

گراف Dart، JavaScript، TypeScript، TSX، PHP، Python، Rust، Zig، C، C++، Go، Java، Ruby، C#، Swift، Kotlin، R، Assembly، MATLAB و Ada را ایندکس می‌کند. فایل‌های هر زبان دیگری تجزیه نمی‌شوند، پس در search_code، code_symbol، code_callers، code_callees یا code_impact ظاهر نمی‌شوند.

دو چیز دیگر هم تعیین می‌کنند چه چیزی ایندکس می‌شود:

در یک work tree از git، فهرست‌کردن به git ls-files --cached --others --exclude-standard واگذار می‌شود، بنابراین هر .gitignore، فایل نادیده‌گیری تودرتو، .git/info/exclude و فایل نادیده‌گیری سراسری رعایت می‌شوند. همین است که node_modules و خروجی ساخت را از گراف بیرون نگه می‌دارد.
Dart تولیدشده در هر حالت کنار گذاشته می‌شود. فایل‌های تولیدشده معمولاً کامیت می‌شوند، پس git به‌تنهایی آن‌ها را مستثنا نمی‌کرد و در هر اجرای تولید کد دستخوش تغییر می‌شوند.

ایندکس کردن یک مخزن

ثبت یک چک‌اوت رویداد RepoAdded را راه می‌اندازد که به‌طور خودکار پایپ‌لاین index_code را برای آن شروع می‌کند. افزودن مخزن به فضای کاری را ببینید.

برای ایندکس دوباره به‌صورت دستی:

تنظیمات → فضای کاری → مخزن‌ها را باز کنید.
روی دکمهٔ ایندکس کد در سطر آن مخزن کلیک کنید.
تا وقتی در حال اجراست، دکمه شمار فایل‌های انجام‌شده را نسبت به کل نشان می‌دهد، همراه با یک کنترل لغو. پس از پایان، به یک تیک همراه با شمار نمادها تبدیل می‌شود.

گراف بر اساس فضای کاری، مخزن و چک‌اوت پارتیشن‌بندی می‌شود: چک‌اوت پیوندشده یک پارتیشن است و هر worktree فضا پارتیشن خودش را می‌گیرد (با کلید شناسهٔ مخزن ایزولهٔ آن).

دو محدودیت ارزش دانستن دارند، چون انتظاری را توضیح می‌دهند که شبیه گیرکردن به نظر می‌رسد:

ناظر فایل در هر میزبان فقط یک اجرای ایندکس را می‌پذیرد — چک‌اوت دوم در انتظار می‌ماند. پایپ‌لاین index_code جداگانه به یک اجرا در هر فضای کاری محدود شده است، پس دو مخزن در یک فضای کاری صف می‌بندند؛ فضاهای کاری مختلف می‌توانند موازی ایندکس کنند. خود ایندکسر دو اجرای همان چک‌اوت را پشت سر هم می‌گذارد تا شروع یک پایپ‌لاین و جاروب ناظر نتوانند آن را دو بار تجزیه کنند.
worktreeهای متعلق به فضاهای خفته (بدون پیامی در هفتهٔ گذشته) نه دیده‌بانی می‌شوند و نه ایندکس. چک‌اوت‌های پیوندشده دیده‌بانی می‌شوند. تصمیم ردکردن هر پنج دقیقه دوباره بررسی می‌شود، پس فضایی که دوباره فعال شود برداشته می‌شود.

یافتن یک نماد

از یک عامل بخواهید جست‌وجو کند. ابزار آن search_code است و هم به یک فضای کاری و هم به یک مخزن نیاز دارد:

search_code(workspace_id: "...", repo_id: "...", query: "authentication middleware")

شناسه‌های مخزن از list_repos می‌آیند. آرگومان اختیاری mode یکی از keyword، semantic یا hybrid است و پیش‌فرضش hybrid است — BM25 روی نام‌ها، امضاها و توضیحات مستند، که با شباهت برداری ترکیب می‌شود.

هر نتیجه شناسه، نام، نام کامل، نوع، مسیر فایل، خط شروع و پایان نماد و در صورت وجود امضایش را همراه دارد. همان id دستگیره‌ای است که به هر ابزار دیگری در این صفحه می‌دهید.

وقتی نام دقیق را می‌دانید، در عوض مستقیم جست‌وجو کنید:

code_symbol(workspace_id: "...", repo_id: "...", name: "MyClass")

ردیابی فراخوانی‌ها

هر دو یک symbol_id از نتیجهٔ جست‌وجو می‌گیرند، به‌همراه یک limit اختیاری (پیش‌فرض 50):

code_callers(workspace_id: "...", symbol_id: "...")
code_callees(workspace_id: "...", symbol_id: "...")

code_callers نمادهایی را برمی‌گرداند که یالی ورودی به این نماد دارند؛ code_callees آن‌هایی را برمی‌گرداند که این نماد به آن‌ها وابسته است.

بررسی اینکه یک تغییر چه چیزی را می‌شکند

این همان ابزاری است که کل این صفحه برای آن نوشته شده:

code_impact(workspace_id: "...", symbol_id: "...", depth: 3)

این ابزار شعاع وابستگی معکوس را محاسبه می‌کند: هر چیزی که به‌طور مستقیم یا غیرمستقیم از راه یال‌های calls، extends و implements به نماد وابسته است (importها، mixes-in و ارجاع‌های جنریک در گراف ذخیره می‌شوند اما اینجا پیمایش نمی‌شوند). depth بیشترین شمار گام‌هاست، بین 1 و 6، با پیش‌فرض 2.

نتیجه سه فیلد دارد:

root — همان نمادی که درباره‌اش پرسیدید
impacted — مجموعهٔ قابل‌دسترس، شامل خود ریشه در عمق 0، که هر کدام depth خود را نسبت به ریشه همراه دارد
edgeCount — شمار یال‌هایی که پیمایش از آن‌ها گذشت، به‌صورت یک عدد و نه خود یال‌ها

پیش از تغییر نام یا تغییر یک امضا آن را اجرا کنید و فهرست impacted را به‌عنوان دامنهٔ کار به عامل بدهید.

نتیجه‌ها با نسخهٔ کاری خودِ فراخوان بررسی می‌شوند

برای فراخوانی که یک عامل است، شناسهٔ فضا به‌طور خودکار تزریق می‌شود و نتیجه‌ها با نسخهٔ کاری همان فضا بررسی می‌شوند. نمادی که فایلش دیگر در درخت فراخوان وجود ندارد کنار گذاشته می‌شود و پاسخ شمار staleOmitted را به‌همراه یادداشتی می‌آورد که می‌گوید ایندکس برای آن نمادها کهنه است.

همین است که چرا شما و یک عامل می‌توانید به یک پرس‌وجوی یکسان پاسخ‌های متفاوت بگیرید و چرا یک عامل در یک فضا می‌تواند پاسخی متفاوت از عاملی در فضای دیگر بگیرد. هر گفتگو در یک فضا همان یک worktree را شریک است. بررسی با شکست باز رفتار می‌کند: پاسخ کهنه بر پاسخ خالی ترجیح داده می‌شود.

وقتی شعاع تأثیر یک تغییر را می‌خواهید، از یک عامل بخواهید code_impact (یا review_studio.blastRadius) را اجرا کند. محاسبهٔ بازبینی را ببینید.

جست‌وجوی معنایی به مدل امبدینگ نیاز دارد

نمادها و واقعیت‌ها هنگام نوشتن امبد می‌شوند و تنها وقتی مدل امبدینگ روی دستگاه نصب باشد. تا آن زمان، mode: "semantic" و نیمهٔ معنایی حالت hybrid چیزی برای مطابقت ندارند و جست‌وجو عملاً فقط کلیدواژه‌ای است.

پیش از ایندکس کردن، مدل را در تنظیمات → سرور → تشخیص و حریم خصوصی → جست‌وجوی معنایی نصب کنید. نمادها وقتی فایلشان وارد ایندکس می‌شود یک بردار می‌گیرند.

همچنین توجه کنید که هر بازسازی باینری سرور، dylibهای گرامر را دوباره آماده می‌کند و mtime آن‌ها را عوض می‌کند، که هر چک‌پوینت ایندکس را بی‌اعتبار می‌سازد و در اجرای بعدی یک پیمایش کامل دوباره روی هر چک‌اوت را الزام می‌کند. فایل‌ها را دوباره هش می‌کند، اما فایل‌های بدون تغییر را دوباره استخراج نمی‌کند.

چه چیزی در گراف هست

انواع نماد: function، method، class، field، enum، constructor، getter، setter، typedef، extension، mixin، variable.

انواع یال: calls، imports، extends، implements، mixes in، references.

امضاهای متعارف این ابزارها در ابزارهای MCP هست.

راهنماهای مرتبط

مفهوم‌های مرتبط

فضاهای کاری و ایزوله‌سازی