منصوبے کے بارے میں

CoalLedger ایک ڈاکومنٹیشن-کوالٹی ٹول ہے جس کا مقصد AI کوڈنگ ایجنٹس کی مدد کرنا ہے، جسے اس کے مصنف نے "دستاویزات کے لیے CoalMine" کے طور پر بیان کیا ہے۔ یہ TheColliery کا حصہ ہے، جو چھوٹے ایڈ-آن سوٹس (CoalMine, CoalTipple, CoalBoard, CoalHearth, CoalFace, CoalWash) کی ایک فیملی ہے جو زیرو-ڈیپینڈینسی ہکس، سنگل-سورس کنفیگ اسکیمات، رضامندی پر مبنی اخراجات اور خودکار ترمیم نہ کرنے کے نظریے پر قائم ہیں۔ CoalLedger کو اکیلے یا دیگر ٹولز کے ساتھ انسٹال کیا جا سکتا ہے۔ اس کا بنیادی تصور یہ ہے کہ کوڈ کے لیے linters، ٹیسٹ اور CI موجود ہوتے ہیں، جبکہ دستاویزات زیادہ تر صرف امید پر منحصر ہوتی ہیں: ایک README جو کوڈ سے دور ہو چکا ہو، ایک ترجمہ جو اب اپنے اصل متن سے میل نہ کھاتا ہو، ایک مردہ انسٹال لنک یا ایک پرانا ورژن بیج ایسی خاموش ناکامیاں ہیں جن پر قاری پھر بھی بھروسہ کرتا ہے۔ CoalLedger کسی بھی دستاویز — README، اسپیک، رپورٹ، ترجمہ — کو اسکین کرتا ہے اور اس کے دعووں کا موازنہ اس کی اصل حقیقت سے کرتا ہے۔ سات کینریز (canaries)، جن میں سے ہر ایک ایک مخصوص ناکامی کی نشاندہی کرتا ہے: 1. doc-grounding — ایسے دعووں کو پکڑتا ہے جو اپنی حقیقت (کوڈ، ڈیٹا، اصل متن، حقیقت) سے میل نہیں کھاتے۔ 2. doc-standard — اس قسم کی دستاویز کے معیار کے مطابق نامکمل حصوں، بشمول ضروری سیکشنز اور غیر دستاویزی پبلک سرفس کی نشاندہی کرتا ہے۔ 3. doc-rot — پرانے ورژن، تاریخوں، بیجز، مردہ TODOs اور منسوخ شدہ ہدایات کو پکڑتا ہے۔ 4. doc-consistency — ایسی دستاویزات کو پکڑتا ہے جو ایک دوسرے کی ضد ہوں، اصطلاحات میں تبدیلی اور مختلف زبانوں کے درمیان تضاد کی نشاندہی کرتا ہے۔ 5. doc-structure — ٹوٹی ہوئی لنکس، اینکرز، ہیڈنگز، ٹیبلز، حوالہ جات اور امیج آلٹ ٹیکسٹ کو پکڑتا ہے۔ 6. doc-quality — غیر ضروری مواد، غیر واضح نثر اور لسانی غلطیوں جیسے ٹائپوز، گرامر اور ہجے کی نشاندہی کرتا ہے۔ 7. doc-leak (کنفیگ-گیٹڈ) — عوامی دستاویزات میں نثر کی سطح پر حساس مواد کی نشاندہی کرتا ہے؛ ٹوکن کی شکل کے رازوں کو دوسرے ٹولز کے لیے چھوڑ دیا جاتا ہے۔ اسکینز دو تہوں (tiers) میں چلتے ہیں۔ Quick میکینیکل تہوں کو کور کرتا ہے جو کہ یقینی (deterministic) اور مؤثر طور پر مفت ہیں، اور صرف رپورٹ فراہم کرتے ہیں۔ Full سیمیٹک تہوں کو شامل کرتا ہے، جو ماڈل کے فیصلے (judgment) کا استعمال کرتے ہیں، بامعاوضہ ہیں، اور ہمیشہ علیحدہ رضامندی کے متقاضی ہوتے ہیں۔ چار کینریز میکینیکل اور سیمیٹک تہوں کا مجموعہ ہیں؛ doc-consistency اور doc-leak صرف سیمیٹک ہیں۔ ایک بنڈل شدہ زیرو-ڈیپینڈینسی CommonMark+GFM AST انجن اسٹرکچرل چیکس کو پاور کرتا ہے تاکہ درست رینڈر ہونے والے مواد کو فلیگ نہ کیا جائے؛ مصنف واضح کرتا ہے کہ اس کی درستگی کی حد اسپیک-لیول ہے، نہ کہ پکسل-پرفیکٹ GitHub رینڈرنگ۔ سنگینی (Severity) کا فیصلہ ہمیشہ سیاق و سباق میں کیا جاتا ہے نہ کہ میکینیکل طور پر: آرکائیو میں ایک ٹوٹی ہوئی لنک کی سنگینی کم ہے، لیکن انسٹالیشن کے مرحلے میں وہی لنک انتہائی اہم (critical) ہے۔ تصدیق شدہ نتائج کو مشکوک نتائج سے الگ رپورٹ کیا جاتا ہے۔ اصلاحات کبھی بھی خودکار طور پر لاگو نہیں کی جاتیں؛ ہر رپورٹ ایک مینو کے ساتھ ختم ہوتی ہے جو محفوظ اصلاحات، صارف کے منتخب کردہ حل، یا صرف رپورٹ کا آپشن دیتی ہے۔ میکینیکل تہیں ڈیزائن کے لحاظ سے زبان سے آزاد ہیں، اور سیمیٹک تہیں دستاویز کی اپنی زبان میں کام کرتی ہیں۔ ایک علیحدہ، اختیاری فیچر docs memory-drift ریمائنڈر ہے۔ یہ کچھ اسکین یا رپورٹ نہیں کرتا۔ اگر دستاویزات کی فائلیں (.md, .mdx, .markdown, .rst, .txt, .adoc, .asciidoc, .org) ایڈٹ کی گئیں لیکن سیشن میں MEMORY.md کو اپ ڈیٹ نہیں کیا گیا، اور پروجیکٹ MEMORY.md کنونشن استعمال کرتا ہے، تو CoalLedger ایجنٹ کے جواب مکمل کرنے پر ایک خاموش سسٹم میسج جاری کرتا ہے۔ مطابقت (Compatibility) پلیٹ فارم ٹیبل کے بجائے کیپبلٹی پر مبنی ہے: لائف سائیکل ہکس والے پلیٹ فارمز کو ایک سیشن-اسٹارٹ کنڈکٹر ملتا ہے؛ بغیر ہکس والے پلیٹ فارمز کو ایجنٹ کے ذریعے بہترین کوشش (best-effort) کے ساتھ کال کیا جاتا ہے۔ مصنف سپورٹ ٹیرز کو ایمانداری سے لیبل کرتا ہے — Claude Code کو لائیو پلگ ان کے ساتھ تصدیق شدہ بتایا گیا ہے، جبکہ دیگر تمام پلیٹ فارمز (Antigravity, Cursor, Codex, Gemini CLI, Cline, Copilot, claude.ai) کو "works with" کہا گیا ہے۔ Claude Code کے لیے انسٹالیشن دو کمانڈز پر مشتمل ہے، جو کنڈکٹر اور میموری-ڈرفٹ ریمائنڈر کو بھی فعال کرتی ہے۔ دیگر ایجنٹس سیلف-کنٹینڈ اسکل فولڈرز کاپی کرتے ہیں۔ claude.ai صارفین کو مشورہ دیا جاتا ہے کہ وہ اسکلز کو دستی طور پر زپ (zip) نہ کریں کیونکہ فرنٹ میٹر تفصیلات پلیٹ فارم کی حد سے زیادہ ہیں؛ اس کے بجائے، مختصر تفصیلات کے ساتھ ہر کینری کے لیے علیحدہ ZIPs ریلیز پیج پر SHA256 چیک سمز کے ساتھ دستیاب ہیں۔ کمانڈز میں ہر کینری کے لیے ایک کمانڈ کے علاوہ /coalledger:stats اور /coalledger:update شامل ہیں۔ کنفیگریشن ایک گلوبل فائل اور فی-پروجیکٹ فائل کو سپورٹ کرتی ہے۔ کیز (Keys) میں آن/آف موڈ، رپورٹ کی زبان، غیر فعال کینریز، سنگینی کی حد، اسکین-آل اوور رائیڈ، اور دیگر ترتیبات شامل ہیں۔ اجازات (Permissions) محدود ہیں: یہ صرف نامزد دستاویزات اور ان کے لنکس والی فائلیں پڑھتا ہے، صرف اپنی عارضی فائلیں اور اپ ڈیٹ اسٹیمپ لکھتا ہے، اور کبھی بھی کسی دستاویز کو خود سے ایڈٹ نہیں کرتا۔ نیٹ ورک کا استعمال اختیاری ہے: بامعاوضہ Full ٹیر کی تصدیق اور سیلف-اپ ڈیٹ چیک کے لیے علیحدہ رضامندی درکار ہوتی ہے۔ کسی API کی یا npm install کی ضرورت نہیں ہے۔ بینچ مارکنگ پر، پروجیکٹ ایماندار ہے: یہ کسی من گھڑت نمبر کے بجائے بغیر بینچ مارک کے لانچ ہوا ہے۔ میکینیکل تہہ کو ریپوزٹری میں ایک ویریفیکیشن اسکرپٹ کے ذریعے ٹیسٹ کیا گیا ہے، اور مستقبل میں ایک رزلٹ ڈائجسٹ پلان کیا گیا ہے۔ یہ Apache 2.0 کے تحت لائسنس شدہ ہے۔