کوڈ گراف سے کوڈ تلاش کریں

یہ گائیڈ دکھاتی ہے کہ کسی ریپو کو کوڈ گراف میں کیسے لایا جائے اور پھر اسے اُس سوال کے جواب کے لیے کیسے استعمال کیا جائے جو ری فیکٹر سے پہلے واقعی آپ کے ذہن میں ہوتا ہے: اس پر کس چیز کا انحصار ہے؟

کوڈ گراف ایک سمبل اور ایج کا ڈیٹا بیس ہے جو آپ کے رجسٹر شدہ چیک آؤٹس کو 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 میں نظر نہیں آتیں۔

دو مزید باتیں طے کرتی ہیں کہ کیا کچھ انڈیکس ہوگا:

git ورک ٹری میں فائلوں کا شمار git ls-files --cached --others --exclude-standard کے حوالے ہوتا ہے، چنانچہ ہر .gitignore، نیسٹڈ اگنور فائل، .git/info/exclude اور عالمی excludes فائل کا لحاظ رکھا جاتا ہے۔ یہی چیز node_modules اور بلڈ آؤٹ پٹ کو گراف سے باہر رکھتی ہے۔
جنریٹ شدہ Dart ہر صورت نکال دی جاتی ہے۔ جنریٹ شدہ فائلیں عموماً کمٹ ہوتی ہیں، اس لیے اکیلے git انہیں خارج نہیں کرتا اور ہر codegen رَن پر وہ بدلتی رہتی ہیں۔

کسی ریپو کو انڈیکس کرائیں

چیک آؤٹ رجسٹر کرنا RepoAdded چلاتا ہے، جو اس کے لیے index_code پائپ لائن خود بخود شروع کر دیتا ہے۔ دیکھیں ورک اسپیس میں ریپوز شامل کریں۔

ہاتھ سے دوبارہ انڈیکس کرنے کے لیے:

ترتیبات → ورک اسپیس → ریپوزٹریز کھولیں۔
ریپو کی قطار پر کوڈ انڈیکس کریں بٹن پر کلک کریں۔
جب یہ چل رہا ہو تو بٹن کل کے مقابلے مکمل ہونے والی فائلیں دکھاتا ہے، ساتھ ایک منسوخی کنٹرول۔ ختم ہونے پر یہ سمبلز کی تعداد کے ساتھ ایک نشان میں ڈھل جاتا ہے۔

گراف ورک اسپیس، ریپو اور چیک آؤٹ کے حساب سے پارٹیشنز میں بٹا ہے: لنک شدہ چیک آؤٹ ایک پارٹیشن ہے، اور ہر اسپیس کا worktree اپنا الگ پارٹیشن رکھتا ہے (جس کی کلید اس کی isolated-repo id ہوتی ہے)۔

دو تھروٹل جاننے کے قابل ہیں، کیونکہ یہی ایسے انتظار کی وضاحت کرتے ہیں جو ہینگ لگے:

فائل واچر میزبان پر ایک وقت میں صرف ایک انڈیکس رَن قبول کرتا ہے — دوسرا چیک آؤٹ انتظار کرتا ہے۔ index_code پائپ لائن الگ سے فی ورک اسپیس ایک رَن تک محدود ہے، چنانچہ ایک ہی ورک اسپیس کے دو ریپوز قطار میں لگتے ہیں؛ مختلف ورک اسپیسز متوازی طور پر انڈیکس کر سکتے ہیں۔ انڈیکسر خود اُسی چیک آؤٹ کے دو رَن سلسلے وار کرتا ہے تاکہ پائپ لائن کا آغاز اور واچر کا جھاڑو اسے دو بار پارس نہ کر سکیں۔
غیر فعال اسپیسز (جن میں پچھلے ہفتے کوئی پیغام نہ ہو) کے worktrees نہ واچ کیے جاتے ہیں نہ انڈیکس۔ لنک شدہ چیک آؤٹس واچ ہوتے رہتے ہیں۔ چھوڑنے کا فیصلہ پانچ منٹ بعد دوبارہ جانچا جاتا ہے، چنانچہ دوبارہ فعال ہونے والی اسپیس اٹھا لی جاتی ہے۔

کوئی سمبل تلاش کریں

کسی ایجنٹ سے تلاش کرنے کو کہیں۔ ٹول search_code ہے اور اسے ورک اسپیس اور ریپو دونوں چاہیے:

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

ریپو ids list_repos سے آتی ہیں۔ اختیاری mode آرگیومنٹ keyword، semantic یا hybrid ہوتا ہے اور بطور ڈیفالٹ hybrid ہے — ناموں، سگنیچرز اور doc comments پر BM25، جو ویکٹر مماثلت کے ساتھ ملا دیا جاتا ہے۔

ہر نتیجہ سمبل کی id، نام، qualified name، kind، فائل پاتھ، آغاز اور اختتامی لائن، اور جب ہو تو اس کا سگنیچر ساتھ رکھتا ہے۔ 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 ایجز کے ساتھ اس سمبل پر براہِ راست یا بالواسطہ انحصار کرتا ہے (imports، mixes-in اور generic حوالے گراف میں محفوظ ہوتے ہیں مگر یہاں اُن پر چلا نہیں جاتا)۔ depth زیادہ سے زیادہ ہوپس کی تعداد ہے، 1 سے 6 کے درمیان، ڈیفالٹ 2۔

نتیجہ تین فیلڈز پر مشتمل ہے:

root — وہ سمبل جس کے بارے میں آپ نے پوچھا
impacted — قابلِ رسائی سیٹ، جس میں depth 0 پر root بھی شامل ہے، اور ہر ایک اپنے root سے depth ساتھ رکھتا ہے
edgeCount — ٹراوِرسل نے کتنے ایجز عبور کیے، بطور گنتی نہ کہ خود ایجز

کسی چیز کا نام بدلنے یا سگنیچر تبدیل کرنے سے پہلے اسے چلائیں اور ایجنٹ کو متاثرہ فہرست بطور اسکوپ دیں۔

نتائج کالر کی اپنی ورکنگ کاپی سے جانچے جاتے ہیں

ایجنٹ کالر کے لیے اسپیس id خود بخود داخل کر دی جاتی ہے اور نتائج اسی اسپیس کی ورکنگ کاپی کے خلاف جانچے جاتے ہیں۔ جس سمبل کی فائل کالر کے درخت میں اب موجود نہ ہو، وہ خارج کر دیا جاتا ہے اور جواب میں staleOmitted کی گنتی کے ساتھ ایک نوٹ آتا ہے کہ اُن سمبلز کے لیے انڈیکس پرانا ہے۔

اسی وجہ سے آپ کو اور ایجنٹ کو ایک ہی کوئری کے مختلف جواب مل سکتے ہیں، اور اسی وجہ سے ایک اسپیس کا ایجنٹ دوسری اسپیس کے ایجنٹ سے مختلف جواب پا سکتا ہے۔ ایک اسپیس کی ہر گفتگو وہی ایک worktree شیئر کرتی ہے۔ تصدیق کھلے انداز میں ناکام ہوتی ہے: خالی جواب کے بجائے پرانا جواب ترجیح پاتا ہے۔

جب آپ کو کسی تبدیلی کا اثر دائرہ جاننا ہو تو ایجنٹ سے code_impact (یا review_studio.blastRadius) چلانے کو کہیں۔ دیکھیں ریویو کمپیوٹ۔

سیمانٹک تلاش کے لیے ایمبیڈنگ ماڈل ضروری ہے

سمبلز اور حقائق لکھتے وقت ایمبیڈ کیے جاتے ہیں، اور صرف اُس وقت جب آن-ڈیوائس ایمبیڈنگ ماڈل انسٹال ہو۔ تب تک mode: "semantic" اور hybrid کے سیمانٹک حصے کے پاس موازنے کو کچھ نہیں ہوتا اور تلاش عملاً صرف کلیدی الفاظ تک محدود رہتی ہے۔

انڈیکس کرنے سے پہلے ماڈل ترتیبات → سرور → تشخیص اور پرائیویسی → سیمانٹک تلاش سے انسٹال کریں۔ سمبلز کو ایک ویکٹر اُس وقت ملتا ہے جب ان کی فائل انجسٹ ہوتی ہے۔

یہ بھی ذہن میں رکھیں کہ سرور بائنری کا کوئی بھی دوبارہ بلڈ گرامر dylibs کو نئے سرے سے اسٹیج کرتا ہے اور ان کے mtimes بدل دیتا ہے، جو ہر انڈیکس چیک پوائنٹ کو باطل کر دیتا ہے اور اگلے رَن پر ہر چیک آؤٹ کا ایک مکمل دوبارہ جھاڑو لازم کر دیتا ہے۔ یہ دوبارہ ہیش کرتا ہے، مگر غیر تبدیل شدہ فائلوں کو دوبارہ ایکسٹریکٹ نہیں کرتا۔

گراف میں کیا ہے

سمبل کی اقسام: function، method، class، field، enum، constructor، getter، setter، typedef، extension، mixin، variable۔

ایج کی اقسام: calls، imports، extends، implements، mixes in، references۔

ان ٹولز کے مستند سگنیچرز MCP ٹولز میں موجود ہیں۔