‏Pastoralist؛ دفترچهٔ خاطرات override‌های پکیج

به گفتهٔ صفحهٔ پروژه، Pastoralist یه «رد بازبینی» برای override‌های پکیج‌منیجره. مشکلی که حل می‌کنه آشناست: یه override اغلب برای یه دلیل درست شروع می‌شه، مثل وصلهٔ یه CVE، یه پین سازگاری، یه fork یا یه دور زدنِ موقتِ وابستگیِ غیرمستقیم. ولی چند ماه بعد اون خط هنوز توی package.json هست و دلیلش یه جای دیگه گم شده.

راه‌حلش اینه که دستور پکیج‌منیجر رو از جاش تکون نمی‌ده و فقط رکورد گم‌شده رو کنارش اضافه می‌کنه: چرا این override وجود داره، کدوم پکیج‌ها هنوز لازمش دارن، کدوم ارائه‌دهندهٔ امنیتی پیداش کرده و کِی می‌شه برش داشت. این اطلاعات توی یه بخش جدا به اسم appendix ذخیره می‌شه.

برای نمونه، وقتی نسخهٔ یه پکیج مثل qs رو پین می‌کنی، Pastoralist کنارش یه دفترچه می‌سازه که وابسته‌ها و یه ledger با تاریخ اضافه‌شدن و دلیل و منبع رو نگه می‌داره:

"pastoralist": {
  "appendix": {
    "qs@6.11.2": {
      "dependents": { "express": "qs@6.11.0" },
      "ledger": { "reason": "Pin qs while upstream adopts the patch", "source": "manual" }
    }
  }
}

کارهای اصلی‌ش اینن: override‌های npm و Bun، بخش pnpm.overrides و resolutions مربوط به Yarn رو ردیابی می‌کنه؛ دلیل اضافه‌شدن و پکیج‌های وابسته رو ثبت می‌کنه؛ متادیتای امنیتی مثل CVE و شدت و نسخهٔ وصله‌شده رو وصل می‌کنه؛ فایل‌های patch-package رو به ورودی مربوط لینک می‌کنه؛ و override‌های راکد رو گزارش می‌ده، ولی فقط وقتی خودت پرچم حذف رو بدی پاکشون می‌کنه.

نویسنده تأکید می‌کنه چون این ابزار می‌تونه توی package.json بنویسه، باید تأییدش «کسل‌کننده» و مطمئن باشه. برای همین انتشارها از GitHub Actions با provenance مربوط به npm منتشر می‌شن، بسته‌های منتشرشده امضای artifact دارن و CI هم CodeQL و OpenSSF Scorecard و آزمون‌های واحد و یکپارچه و e2e رو اجرا می‌کنه.

خروجی‌های dry-run، خلاصه، حالت quiet و JSON برای CI هم داره و می‌شه با یه GitHub Action وضعیت ردیابیِ override‌ها رو موقع pull request بررسی کرد. برای شروع، یه فرمان doctor فقط‌خواندنی هم داره که سلامت override‌ها رو بدون تغییر چیزی چک می‌کنه.

نکات کلیدی:

• برای هر override پکیج‌منیجر یه رد بازبینی نگه می‌داره بی‌اینکه خود override رو جابه‌جا کنه
• از npm، pnpm، Yarn و Bun پشتیبانی می‌کنه
• دلیل، پکیج‌های وابسته و متادیتای امنیتی مثل CVE و نسخهٔ وصله رو ثبت می‌کنه
• override‌های راکد رو گزارش می‌ده و فقط با پرچم صریح حذفشون می‌کنه
• انتشار امن با provenance و امضای artifact و بررسی‌های CI