seiso کے ساتھ AI سے لکھی گئی پروجیکٹ دستاویزات کی لِنٹ جانچ

seiso کیا کرتا ہے

seiso AI کے ذریعے لکھی گئی اور لوگوں तथा کوڈنگ ایجنٹس کے ذریعے پڑھی جانے والی پروجیکٹ دستاویزات کے لیے Markdown کا ایک طریقۂ کار اور linter ہے۔ یہ ریپوزٹریز کو دستاویزات کو یکساں، قابلِ نگہداشت، اور آئندہ تبدیلیوں کے لیے context کے طور پر استعمال میں آسان رکھنے میں مدد دیتا ہے۔

یہ ٹول ہر پروجیکٹ سے دستاویزات کے اپنے اصول ایجاد کرنے کا تقاضا کرنے کے بجائے، دستاویزات کو ایک مشترکہ طریقۂ کار کے مطابق جانچتا ہے۔ ہر دستاویز ایک قسم بیان کرتی ہے، جیسے howto، reference، یا adr، اور اس قسم کے لیے موزوں مواد ہی پر مشتمل ہوتی ہے۔

seiso یہ بھی ترغیب دیتا ہے کہ ہر حقیقت کا ایک مستند مقام ہو۔ دیگر صفحات کو وہی معلومات دہرانے کے بجائے اس ماخذ سے لنک کرنا چاہیے۔ اس سے تضادات کم ہوتے ہیں، خاص طور پر جب AI سے تیار کردہ دستاویزات کسی فیلڈ کی فہرست، ورژن، حیثیت، یا تعداد کو کئی فائلوں میں نقل کر دیں۔

دستاویزات کے بنیادی اصول

• ہر دستاویز ایک قسم بیان کرتی ہے اور اسی قسم کے مقصد کی پیروی کرتی ہے۔ how-to اقدامات کی وضاحت کرتا ہے، جبکہ ڈیزائن سے متعلق استدلال ADR میں ہونا چاہیے۔
• ہر حقیقت کا ایک ہی مقام ہوتا ہے۔ دیگر دستاویزات اسے دوبارہ بیان کرنے کے بجائے مستند صفحے سے لنک کرتی ہیں۔
• طویل عرصے تک برقرار رہنے والے صفحات میں ایسے اقدار سے گریز کیا جاتا ہے جو صفحے کے مقابلے میں زیادہ تیزی سے بدلتی ہیں، جن میں ورژن، تعیناتی کی حیثیت، اور تعداد شامل ہیں۔
• جب کوئی جملہ کسی ٹھوس نفاذی تفصیل کا حوالہ دے تو pointer فائل یا symbol کی نشان دہی کرتا ہے۔
• مکمل شدہ دستاویزات میں اس شخص سے خطاب نہیں ہونا چاہیے جس نے یہ دستاویز طلب کی ہو، اور نہ ہی دستاویز کی تیاری کا احوال بیان کرنا چاہیے۔
• ایسے فیصلے جنہیں ٹول نہیں کر سکتا، وجہ کے ساتھ درج کیے جانے چاہییں۔ بغیر وضاحت کی گئی استثنا خود ایک خلاف ورزی ہے۔

seiso دستاویزات کے ان اصولوں پر توجہ مرکوز کرتا ہے۔ یہ یہ تعین کرنے کی کوشش نہیں کرتا کہ نثر مشینی طور پر لکھی ہوئی محسوس ہوتی ہے یا نہیں، اور فارمیٹنگ و ہجے کا کام دوسرے ٹولز پر چھوڑ دیتا ہے۔

seiso انسٹال کریں

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

cargo install seiso

uv tool install seiso
# Or use pipx:
pipx install seiso

npm install -g @scarletkc/seiso

PyPI اور npm پیکیجز macOS کے Apple silicon اور Intel، glibc کے ساتھ Linux x64 اور arm64، اور Windows x64 کے لیے پہلے سے تیار کردہ بائنریز شامل کرتے ہیں۔ دیگر پلیٹ فارمز پر، بشمول musl پر مبنی Linux ڈسٹری بیوشنز جیسے Alpine، Cargo کے ذریعے انسٹال کریں۔ ان پلیٹ فارمز پر PyPI پیکیج source سے بھی build ہو سکتا ہے، بشرطیکہ Rust toolchain دستیاب ہو۔

اگر آپ source checkout سے کام کر رہے ہیں تو کمانڈز Cargo کے ذریعے چلائیں:

cargo run -- <command>

ریپوزٹری شروع کریں

seiso کو ریپوزٹری کے root سے چلائیں۔ ابتدا میں اس سے ابتدائی configuration بنانے کو کہیں:

seiso init

یہ ریپوزٹری کے root پر seiso.toml فائل لکھتا ہے۔ تیار کردہ configuration میں تجویز کردہ exclusions اور document-kind mappings شامل ہوتی ہیں۔ نتائج پر انحصار کرنے سے پہلے ان تجاویز کا جائزہ لیں، کیونکہ ابتدائی mapping آپ کی ریپوزٹری کے لیے نقطۂ آغاز ہے، پروجیکٹ کے فیصلوں کا متبادل نہیں۔

پہلی جانچ چلائیں

تیار کردہ configuration کا جائزہ لینے کے بعد ریپوزٹری کو check کریں:

seiso check

بطورِ ڈیفالٹ، seiso check صرف stable rules چلاتا ہے۔ یہ rules seiso کے promotion criteria پر پورے اتر چکے ہیں اور پروجیکٹ کے لیے قابلِ اعتماد بنیادی معیار فراہم کرنے کے لیے بنائے گئے ہیں۔

Diagnostics مسئلے کا مقام بتاتے ہیں اور اسے درست کرنے کا طریقہ سمجھاتے ہیں۔ اس لیے بہت سی findings کو کمانڈ کے output سے براہِ راست درست کیا جا سکتا ہے۔ جب کسی finding کے لیے انسانی فیصلہ درکار ہو، مثلاً یہ طے کرنا کہ دو صفحات میں سے کس میں کوئی حقیقت درج ہونی چاہیے، تو diagnostic مطلوبہ فیصلے کی نشان دہی کرتا ہے۔

rules اور دستاویز کی ساخت دریافت کریں

seiso کیا check کر سکتا ہے، یہ سمجھنے کے لیے rule commands استعمال کریں:

seiso rule --all
seiso rule <CODE>

seiso rule --all ہر rule کی فہرست اور اس کی حیثیت دکھاتا ہے۔ کسی ایک rule کو مثالوں کے ساتھ دیکھنے کے لیے seiso rule <CODE> استعمال کریں۔

rules چلائے بغیر seiso کے document model کا جائزہ لینے کے لیے یہ کمانڈ استعمال کریں:

seiso parse

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

preview rules احتیاط سے استعمال کریں

وہ rules جو ابھی promotion criteria پر پورے نہیں اترے، previews کے طور پر دستیاب ہیں۔ Preview rules تجرباتی ہوتے ہیں اور false positives رپورٹ کر سکتے ہیں، اس لیے standard check میں فعال نہیں ہوتے۔

انہیں مقامی طور پر --preview option کے ساتھ آزمائیں:

seiso check --preview

Preview rules ممکنہ دستاویزی مسائل کو جلد تلاش کرنے کے لیے مفید ہیں، لیکن README تجویز کرتا ہے کہ مستحکم ہونے تک انہیں CI gates سے باہر رکھا جائے۔ ایک عملی workflow یہ ہے کہ لازمی checks کے لیے stable rules اور اختیاری مقامی جائزے کے لیے preview rules استعمال کیے جائیں۔

دستاویزات کے workflow میں seiso اپنائیں

1. Cargo، uv، pipx، یا npm کے ذریعے seiso انسٹال کریں۔
2. ریپوزٹری کے root سے seiso init چلائیں۔
3. seiso.toml میں تجویز کردہ exclusions اور kind mappings کا جائزہ لیں۔
4. seiso check چلائیں اور رپورٹ کی گئی findings حل کریں۔
5. جب کسی diagnostic کو سمجھنے کی ضرورت ہو تو seiso rule --all اور انفرادی rule کی وضاحتیں استعمال کریں۔
6. مقامی طور پر seiso check --preview آزمائیں، لیکن preview findings کو CI gates کے طور پر استعمال کرنے سے گریز کریں۔

بڑے workflows کے لیے seiso کی دستاویزات میں configuration، rule selection، اور output formats کے ساتھ ساتھ Claude Code hooks، pre-commit، اور CI integrations کے بارے میں رہنمائی شامل ہے۔

اعلیٰ درجے کی رہنمائی

حقائق کو مستند رکھیں

جب seiso نقل شدہ یا غلط جگہ موجود معلومات کی رپورٹ کرے، تو فیصلہ کریں کہ اس حقیقت کا اصل مالک کون سا دستاویز ہونا چاہیے۔ بنیادی وضاحت وہاں منتقل کریں اور متعلقہ صفحات سے اس کا لنک دیں۔ اس سے اپ ڈیٹس زیادہ محفوظ ہوتی ہیں اور قارئین اور ایجنٹس، دونوں کو معلومات کا واضح مستند ماخذ ملتا ہے۔

دستاویز کی قسم کو مقصد کے مطابق منتخب کریں

طریقۂ کار کے مراحل کے لیے howto، مستقل حقائق پر مبنی معلومات کے لیے reference، اور کسی ڈیزائن فیصلے کے پسِ پشت دلیل کے لیے adr استعمال کریں۔ ان مقاصد کو الگ رکھنے سے صفحہ ہدایات، حوالہ جاتی ڈیٹا اور تاریخی فیصلہ سازی کے ملے جلے مجموعے میں تبدیل نہیں ہوتا۔

جائز استثناؤں کا ریکارڈ رکھیں

ریپوزٹری کے بعض فیصلوں کے لیے میکانی اصول کے بجائے صواب دیدی فیصلہ درکار ہوتا ہے۔ جب آپ کوئی استثنا برقرار رکھیں تو اس کی وجہ درج کریں۔ seiso ایسی وضاحت کے بغیر استثنا کو دستاویزات کا مسئلہ سمجھتا ہے، کیونکہ مستقبل کے معاونین اور ایجنٹس یہ نہیں جان سکتے کہ یہ جان بوجھ کر کیا گیا تھا یا نہیں۔

جب کوئی اصول غیر واضح ہو تو کنونشن سے رجوع کریں

seiso کنونشن ہر دستاویز کی قسم کے معاہدے اور ان شواہد کی وضاحت کرتا ہے جن کا کوئی تشخیصی عمل دعویٰ کر سکتا ہے۔ متوقع ساخت سمجھنے یا کسی دریافت شدہ مسئلے کی اصلاح کا طریقہ طے کرنے کے لیے اسے seiso rule <CODE> کے آؤٹ پٹ کے ساتھ استعمال کریں۔

نتیجہ

seiso منصوبے کی دستاویزات کو مشترکہ ساخت اور مرکوز توثیقی ٹول فراہم کرتا ہے۔ اسے انسٹال کریں، seiso.toml بنائیں اور اس کا جائزہ لیں، مستقل جانچیں چلائیں، اور دستاویزات کو انسانوں اور کوڈنگ ایجنٹس کے لیے زیادہ قابلِ اعتماد بنانے کے لیے اصولوں کی وضاحتیں استعمال کریں۔ پیش نظارہ اصولوں کو اس وقت تک تجرباتی سمجھیں جب تک انہیں باقاعدہ طور پر شامل نہ کر لیا جائے، اور ریپوزٹری میں ملکیت اور استثناؤں سے متعلق فیصلوں کو واضح رکھیں۔