Slopo با بردارهای معنایی تکرارهای پنهان در کدهای پیچیده را می‌یابد

تصور کنید منطق یک تابع حیاتی در پنج جای مختلف از پروژه شما تکرار شده است، اما چون نام متغیرها متفاوت است، هیچ ابزار جست‌وجوی معمولی آن‌ها را پیدا نمی‌کند. این یعنی «بدهی فنی نامرئی» که ریسک بروز باگ‌های پیش‌بینی‌نشده هنگام به‌روزرسانی را به‌شدت بالا می‌برد. این چالش بسیار پیچیده‌تر از یافتن خطاهای ساده‌ی کپی-پیست است، زیرا منطق‌های مشابه در ماژول‌های مختلف پراکنده شده‌اند.

برای حل این مشکل، ابزار Slopo در ۲ ژوئیه ۲۰۲۶ به‌عنوان یک ابزار خط فرمان (CLI) سبک معرفی شد. هدف این ابزار شناسایی دقیقاً همین شکاف است؛ یعنی تشخیص تکرارهای غیردقیق در کد، جایی که منطق یکسان است اما نوشتار متفاوت. اکثر ابزارهای شناسایی تکرار بر اساس تطبیق رشته‌ای (String Matching) عمل می‌کنند که وقتی برنامه‌نویس نام یک متغیر را کمی تغییر دهد یا ترتیب چند خط را عوض کند، با شکست مواجه می‌شوند. Slopo برای عبور از این محدودیت، به‌جای تکیه بر متن، بر تحلیل معنایی واحدهای کد تمرکز می‌کند. طبق گزارش منتشرشده در مخزن github.com، این ابزار از بردار معنایی (Embedding) استفاده می‌کند تا تکه‌های کدی که شبیه به هم نوشته شده‌اند اما در نقاط دور از هم در codebase یا در ماژول‌های مجزا قرار گرفته‌اند را شناسایی کند.

بردار معنایی — شبیه کارت معرفی عددی برای هر واژه که می‌گوید این کلمه «همسایه‌ی» چه کلمات دیگری است — به Slopo اجازه می‌دهد مفهوم کد را بفهمد، نه فقط حروف آن را. بر اساس مستندات فنی، این ابزار با محاسبه یک Embedding برای هر واحد کد و شناسایی جفت‌هایی با «شباهت کسینوسی» نزدیک عمل می‌کند. این ابزار برای زبان‌های پایتون، تایپ‌اسکریپت، جاوااسکریپت، جاوا، کاتلین، سی‌شارپ، گو و راست پشتیبانی کامل ارائه می‌دهد. البته یک نکته حیاتی وجود دارد: اگر یک منطق با روشی کاملاً متفاوت پیاده‌سازی شده باشد، بردارهای معنایی فاصله زیادی خواهند داشت و ابزار آن‌ها را شناسایی نخواهد کرد.

همان‌طور که در تحلیل‌های پیشین ما درباره‌ی اتوماسیون بازسازی کد اشاره کردیم، چالش اصلی همواره تشخیص «قصد برنامه‌نویس» از میان سینتکس‌های مختلف بوده است. Slopo با هدفمند کردن این فرآیند، تمرکز خود را بر تکه‌های کدی می‌گذارد که در فایل‌های بزرگ یا ماژول‌های مختلف پراکنده شده‌اند و به‌سادگی دیده نمی‌شوند.

سازوکار فنی

Slopo از یک خط لوله چندمرحله‌ای برای پالایش نتایج و کاهش خطاها استفاده می‌کند:

• آستانه شباهت: در مرحله اول، از شباهت کسینوسی (Cosine Similarity) که بازه‌ای بین ۱- تا ۱ دارد (که ۱ به معنای همسان بودن کامل است) برای خوشه‌بندی کدهای مشابه استفاده می‌شود. پارامتر similarity_threshold تعیین می‌کند که حداقل میزان شباهت برای پذیرش یک جفت کد در این خوشه‌ها چقدر باشد.
• تقویت بازرتبه‌بندی: ابزار برای دقت بیشتر، یک «تقویت» (Boost) بر اساس نزدیکی اعمال می‌کند. جفت‌هایی که در یک فایل هستند، بر اساس فاصله تعداد خطوط (حداکثر ۱۰٪ تقویت) و مواردی که نیاز به جابه‌جایی بین دایرکتوری‌ها دارند، بر اساس تعداد گام‌های دایرکتوری (حداکثر ۱۵٪ تقویت) امتیاز می‌گیرند تا رتبه‌بندی دقیق‌تر شود.
• فیلتر نهایی: در این مرحله، پارامتر rerank_threshold وارد عمل شده و خوشه‌هایی را که بالاترین امتیاز جفت آن‌ها حتی پس از اعمال تقویت، به حد نصاب شباهت نرسیده باشد، حذف می‌کند.
• فیلتر پیچیدگی: برای جلوگیری از شناسایی تکه‌های کد بدیهی و بسیار کوتاه (Trivial)، پارامتر body_node_count_threshold استفاده می‌شود. این پارامتر به‌جای طول متن، تعداد گوه های درخت نحو مجرد (AST) را در بدنه کد (بدون احتساب امضا و حاشیه‌ها یا Annotations) می‌شمارد تا حداقل پیچیدگی کد مورد نظر تضمین شود.

پیکربندی و راه‌اندازی

این ابزار برای سازگاری با ارائه‌دهندگان مختلف مدل‌های زبانی از LiteLLM بهره می‌برد. نویسندگان ابزار برای دریافت بهترین نتایج، مدل‌های تخصصی کد مانند Voyage AI را پیشنهاد می‌کنند که به‌خصوص با ابعاد پایین (مانند ۵۱۲) عملکرد بسیار خوبی دارد. نصب Slopo از طریق مدیریت بسته uv در پایتون انجام می‌شود که اجازه می‌دهد ابزار در یک محیط مجازی ایزوله و بدون نیاز به نصب جداگانه پایتون در سیستم اجرا شود.

کاربران می‌توانند تنظیمات را از طریق فایل پیکربندی که با دستور slopo init تولید می‌شود، مدیریت کنند. اگرچه اکثر پارامترها دارای مقادیر پیش‌فرض مناسبی هستند، اما تنظیمات کلیدی شامل موارد زیر است:

• source_dir: مسیر مطلق یا نسبی به کدهای منبع.
• source_dir_exclude: الگوهایی شبیه به .gitignore برای نادیده گرفتن پوشه‌هایی مانند تست‌ها.
• db_file: دیتابیس SQLite که برای ذخیره داده‌های ابزار استفاده می‌شود (این فایل نباید در گیت Commit شود).
• report_dir: مسیری که گزارش‌های تحلیل در آن ذخیره می‌گردد.
• embedding_batch_size و embedding_batch_chars: تنظیماتی برای دسته‌ای کردن درخواست‌های API جهت افزایش کارایی و سرعت.

در مورد امنیت، کلید API از طریق متغیر محیطی SLOPO_EMBEDDING_API_KEY یا یک فایل .env دریافت می‌شود تا از ثبت تصادفی کلیدهای حساس در مخزن کد جلوگیری شود.

گردش کار در دنیای واقعی

فرآیند اجرای Slopo به‌صورت افزایشی طراحی شده است تا کاربر کنترل کاملی داشته باشد. کاربر ابتدا با دستور slopo show-config پارامترها را اعتبارسنجی کرده و سپس توالی دستورات زیر را اجرا می‌کند:
۱. slopo index برای نقشه‌برداری از ساختار کد.
۲. slopo embed برای محاسبه بردارهای معنایی.
۳. slopo analyze برای تولید گزارش نهایی.

پس از تولید نتایج در فایل index.md است که نقش اصلی را عامل (Agent) — شبیه دستی که تمام فایل‌های پروژه را می‌شناسد و طبق دستور شما تغییر می‌دهد — ایفا می‌کند. از آنجایی که هر تکه کد مشابه لزوماً یک تکرار نیازمند اصلاح نیست، عامل هوش مصنوعی این خوشه‌ها را بازبینی کرده و موارد غیرتکراری را فیلتر می‌کند. سپس شناسه‌های (Hash) خوشه‌های ردشده را در فایل slopo.ignore.txt قرار می‌دهد. این فایل می‌تواند در گیت Commit شده و بین اعضای تیم به اشتراک گذاشته شود. در تحلیل‌های بعدی، تنها خوشه‌های جدید یا تغییریافته نمایش داده می‌شوند که مبنایی پاک برای بازسازی کد (Refactoring) فراهم می‌کند.

مدیریت تکرارهای دقیق

در حالی که هدف اصلی Slopo شناسایی تکرارهای غیردقیق است، اما کپی‌های دقیق را نیز مدیریت می‌کند. برای کاهش نویز در گزارش، این موارد به‌گونه‌ای متفاوت گزارش می‌شوند: به‌جای تکرار یک تکه کد یکسان چندین بار، کد تنها یک‌بار نمایش داده شده و تمام مسیرهایی که این کد در آن‌ها ظاهر شده است، لیست می‌شوند. علاوه بر این، دستور analyze یک «نسبت شباهت» (Similarity Ratio) ارائه می‌دهد که سهم واحدهای کد علامت‌گذاری شده را به دو صورت محاسبه می‌کند: با احتساب کپی‌های دقیق و بدون احتساب آن‌ها.

در یک تست عملی روی دایرکتوری منبع خود Slopo (با استفاده از تگ گیت v0.2.0)، ابزار تکرارهای قابل‌توجهی را در تجزی‌کننده‌های زبانی (Parsers) شناسایی کرد. گزارش نشان داد که برخی از پارسرها کپی‌های دقیق بودند و برخی دیگر نسخه‌های مشابه با تغییرات جزئی، که این موضوع نیاز مبرم به بازسازی کد در آن بخش را تایید کرد.

در نهایت، Slopo مسئله تکرار کد را از یک «جست‌وجو» به یک «فیلتراسیون» تبدیل کرده است. با ادغام در گردش کار عامل‌های هوش مصنوعی برای بازبینی نهایی، این ابزار حلقه شناسایی و اصلاح کد را به‌طور کامل می‌بندد.

گام بعدی شما

• اگر پروژه بزرگی دارید، Slopo را با مدل Voyage AI تست کنید تا تکرارهای پنهان در ماژول‌های مختلف را بیابید.
• فایل slopo.ignore.txt را در گیت خود قرار دهید تا تیم شما روی خوشه‌های تکراریِ تاییدشده تمرکز کند.
• از یک عامل کدنویس (مثل Cursor یا GitHub Copilot) برای بازبینی سریع گزارش index.md استفاده کنید.

اما اثر این رویکرد بر هزینه پردازش در مقیاس‌های میلیونی خط کد، موضوع پیچیده‌تری است — در تحلیل ما درباره بهینه‌سازی هزینه استنتاج بخوانید.