Revera

درجة الائتمان لحزم npm.

تساعدك Revera في تحديد ما إذا كانت الحزمة تستحق التثبيت قبل تشغيل npm install. وهي تحلل جودة الحزمة، والصيانة، والأمان، وصحة النظام البيئي، وموثوقية الناشر — وتنشر الآن المخاطر انتقاليًا عبر مخطط التبعيات بالكامل — ثم تُنتج تقرير سمعة قابلًا للتفسير قائمًا على الاستدلال البايزي.

العرض التوضيحي

شاهد Revera وهو يفحص الحزم ويشرحها في الوقت الفعلي.

البدء السريع

شغّل Revera فورًا دون تثبيت:

npx revera check react

مثال

فحص حزمة مثل request (التي أُهملت في عام 2020) يحذّرك فورًا مع ذكر أسباب محددة:

$ revera why request

  ▲ revera EXPLAIN
  ──────────────────────────────────────────────────
  Package:   [email protected]
  Overall:   38/100  Not Recommended

  Score Breakdown

    Maintenance             15/100  ███░░░░░░░░░░░░░░░░░
                           Release cadence, commit activity, issue responsiveness, maintainer count

    Stability               90/100  ██████████████████░░
                           SemVer compliance, major version history, API volatility over time

    Security               100/100  ████████████████████
                           Known CVEs, install scripts, repository transparency

    Package Quality         40/100  ████████░░░░░░░░░░░░
                           README completeness, license, test coverage indicators, exports

    Ecosystem              100/100  ████████████████████
                           Weekly download volume, GitHub stars, community forks

    Documentation           90/100  ██████████████████░░
                           README length, code examples, API references, external docs presence

    Developer Experience    40/100  ████████░░░░░░░░░░░░
                           TypeScript support, ESM compatibility, CLI tooling

    Publisher Trust        100/100  ████████████████████
                           Known malicious releases, protestware history, supply-chain incidents

  Why it scores well
    +  Stable API (v1.0.0+)
    +  Low API volatility
    +  Zero known vulnerabilities
    +  Permissive open-source license
    +  Code examples in README
    +  Structured API documentation
    +  No known publisher trust incidents

  Minor deductions
    -  Last release was 59 months ago
    -  Single maintainer (bus factor of 1)
    -  Missing native type definitions
    -  Legacy CommonJS only
    -  No native typings (bad TypeScript DX)

  Warnings
    !  Last release: 59 months ago. No recent updates detected. This may be normal for mature, stable libraries.
    !  Package has been officially marked as deprecated by the maintainer.

  Verdict
    Request has low confidence. revera recommends looking for alternatives due to security, activity, or stability concerns.

التثبيت

ثبّت الحزمة عالميًا للوصول إلى الملف التنفيذي من أي مجلد:

npm install -g @aaravmaloo/revera

الاستخدام

1. فحص سمعة الحزمة

حلّل حزمة واحصل على تقرير ملخص عالي المستوى:

revera check lodash

شغّل في وضع عدم الاتصال باستخدام الملفات المخزنة مؤقتًا:

revera check express --offline

2. شرح تقييم الحزمة

احصل على تحليل تفصيلي للدرجة والإشارات الإيجابية والاستقطاعات:

revera why node-ipc

3. فحص وإضافة تبعية

يفحص الحزم قبل التثبيت ويحذّر عندما تنخفض سمعة الحزمة عن الحد الأدنى الذي قمت بتعيينه:

revera add express

يمكنك تمرير العلامات مباشرة إلى مدير الحزم لديك:

revera add typescript --save-dev

4. تدقيق مساحة العمل المحلية

دقّق جميع الحزم في المشروع الحالي (يشمل التبعيات الانتقالية) واحسب درجة صحة المشروع الإجمالية:

revera audit

دقّق تبعيات الإنتاج فقط:

revera audit --prod

دقّق التبعيات المباشرة فقط، متخطيًا التبعيات الانتقالية:

revera audit --direct

5. مصادقة GitHub

مصادقة عبر GitHub لزيادة حدود معدل API (60/ساعة للمجهول مقابل 5,000/ساعة للمصادق). يمكنك الاختيار بين OAuth2 المستند إلى المتصفح أو إدخال رمز وصول شخصي يدويًا. بمجرد التفويض، تشفّر Revera الرمز وتخزّنه بأمان في حلقة مفاتيح نظام التشغيل لديك (Windows DPAPI أو macOS Keychain أو Linux Secret Service):

revera login

6. إعدادات واجهة الأوامر (CLI)

إدارة الإعدادات المحلية المحفوظة في ~/.revera/config.json:

revera config
revera config set minScoreThreshold 75
revera config get minScoreThreshold

7. فحص النظام

تحقق من إعدادات البيئة وحالة API وزمن استجابة اتصالات الشبكة:

revera doctor

8. التحكم في ذاكرة التخزين المؤقت

افحص أو امسح ذاكرة التخزين المؤقت للبيانات الوصفية المحلية:

revera cache
revera cache clear

9. التحقق من التحديث

تحقق مما إذا كنت تشغّل أحدث إصدار من محرك Revera:

revera update

المقارنة

محرك التسجيل (v2)

استبدل Revera v2 النموذج القديم القائم على المجموع المرجّح المسطّح بخط أنابيب بايزي من أربع مراحل قائم على المخطط البياني الموجّه غير الدوري (DAG).

المرحلة 1 — مخطط التبعيات (DAG)

تُحل جميع التبعيات في المشروع إلى مخطط بياني موجّه غير دوري. يتتبّع كل عقدة مجموعة التابعين الانتقاليين الكاملة له بحيث يمكن للمراحل اللاحقة حساب أنصاف أقطار الانفجار بدقة.

lodash ──► your-app
express ──► your-app
axios ──► some-lib ──► your-app   ← transitive

المرحلة 2 — تسجيل كل حزمة على حدة (الاحتمالات الخلفية البايزية لتوزيع بيتا)

تبدأ كل فئة من فئات التسجيل الثماني من احتمال قبلي خاص بالنموذج الأصلي (framework, cli, types-only, utility) بدلًا من خط أساس مسطّح غير مستنير. تعمل الإشارات المرصودة على تحديث الاحتمال الخلفي لتوزيع بيتا — مما يعني أن انتهاء المهلة أو نقص البيانات يوسّع فاصل المصداقية بدلًا من الافتراض الصامت بأن الحزمة «نظيفة».

الدرجة النهائية لكل حزمة هي إجمالي مرجّح بالثقة للاحتمالات الخلفية للفئات (الترجيح بالتباين العكسي)، مما يُنتج تقديرًا نقطيًا وفاصل مصداقية بنسبة 95%.

المرحلة 3 — فحوصات النقض

ثلاثة تجاوزات صارمة تتجاوز التسجيل البايزي بالكامل وتُسقط الحزمة فورًا:

المرحلة 4 — انتشار المخاطر الانتقالي

بعد حساب درجات كل حزمة، تُنشر المخاطر من الأسفل إلى الأعلى عبر مخطط DAG (بالترتيب الطوبولوجي، الأوراق أولًا):

• إذا تجاوز effectiveRisk لتبعية ما عتبة معينة، يتم تثبيت مخاطر الأصل عند 0.8 كحد أدنى (يُعلَّم كملوث).
• نصف قطر الانفجار لكل عقدة = effectiveRisk × transitive_dependent_count.
• يتم تتبّع أسوأ مسار فرعي وإظهاره في مخرجات التدقيق لتعرف بالضبط سلسلة التبعيات التي تسببت في هذا العلم.

المرحلة 5 — تجميع التقرير

يدمج تقرير التدقيق النهائي الدرجات الجوهرية، والتلوث الموروث، وفترات المصداقية، وأنصاف أقطار الانفجار في مخرجات واحدة مرتبة. درجة مساحة العمل الإجمالية هي متوسط مرجّح حسب نصف قطر الانفجار.

قواعد بيانات الثغرات

يستعلم Revera عن ثلاث قواعد بيانات ثغرات مستقلة بالتوازي في كل فحص. تُدمج النتائج وتُزال تكراراتها بواسطة الاسم المستعار CVE/GHSA قبل استخدامها في التسجيل.

إذا انتهت مهلة أحد المصادر أو حدث خطأ فيه، تستمر المصادر الأخرى بشكل مستقل. يكشف VulnResult عن المصادر التي استجابت (sources) والتي فشلت (failedSources) حتى يتمكن المسجّل البايزي من توسيع فاصل عدم اليقين بشكل مناسب بدلًا من افتراض أن الحزمة نظيفة.

البنية والهيكل

.github/              # CI configurations
docs/                 # Architecture specs and algorithm diagrams
src/
  ├── commands/       # CLI command handlers (check, why, add, audit, config, cache, update)
  ├── engine/
  │   ├── dag.ts          # DAG construction + topological sort + blast-radius computation
  │   ├── propagation.ts  # Bottom-up transitive risk propagation
  │   ├── scoring.ts      # Bayesian Beta posteriors, archetype priors, veto checks
  │   ├── vuln.ts         # Multi-source vuln aggregator (OSV + GitHub + npm)
  │   ├── trust.ts        # Publisher trust incident database
  │   ├── typosquat.ts    # Edit-distance typosquat detection
  │   ├── npm.ts          # npm registry + download stats fetcher
  │   └── github.ts       # GitHub repo stats + README fetcher
  ├── ui/             # Console view templates (reporter formatters, theme styles)
  └── utils/          # Filesystem helpers (caching, configuration, package managers)
tests/                # Unit test suites
benchmarker/          # Large-scale benchmark suite (100k+ packages)

المعايير

تأتي Revera مع مجموعة معايير مدمجة واسعة النطاق في benchmarker/ تختبر أكثر من 100 ألف حزمة npm بالتوازي وتُنتج تقريرًا واحدًا قابلًا للقراءة على GitHub.

تشغيل معيار

cd benchmarker
npm install
npm run fetch-dataset          # one-time: pulls ~100k packages into datasets/npm.jsonl
./benchmark.sh --workers 16   # runs the full suite

يُنتج كل تشغيل مجلد مخرجات مكتفيًا ذاتيًا يحتوي على:

أحدث معيار (خوارزمية v2، مجموعة البيانات الأولية)

أُجري معيار v1 قبل نشر فحوصات النقض في v2. تعكس أرقام التصنيفات الخبيثة/التصيد الطباعي لكل تصنيف الخوارزمية القديمة. سيُنشر إعادة تشغيل كاملة لـ v2 في الإصدار القادم.

خارطة الطريق

• تسجيل سمعة الحزمة
• تقارير تسجيل قابلة للتفسير
• تدقيق المشروع المباشر والانتقالي
• فحوصات حوادث موثوقية الناشر
• تحذيرات Levenshtein للتصيد الطباعي
• تسجيل الاحتمال الخلفي لتوزيع بيتا البايزي (v2)
• انتشار مخاطر مخطط DAG الانتقالي (v2)
• تجميع الثغرات متعدد المصادر (OSV + GitHub + npm)
• تقارير معايير قابلة للقراءة على GitHub (BENCHMARK.md)
• أوامر مقارنة متعددة الحزم
• GitHub Action رسمي لفحوصات CI
• إضافة رسمية لـ VS Code
• دعم أصلي لـ pnpm
• دعم أصلي لـ Yarn

الأسئلة الشائعة

كيف أتجنب حدود معدل GitHub API؟

بدون رمز، تكون الاستعلامات المجهولة محدودة بـ 60 طلبًا في الساعة. يمكنك تعيين رمز وصول شخصي في إعداداتك:

revera config set githubToken ghp_YOUR_TOKEN

ماذا يحدث إذا كنت غير متصل بالإنترنت؟

يتراجع Revera إلى استخدام ملفات ذاكرة التخزين المؤقت. يمكنك تشغيل الأوامر صراحةً في وضع عدم الاتصال باستخدام علامة --offline. إذا كان مصدر الثغرات غير متاح، يوسّع المسجّل البايزي فاصل المصداقية لتلك الحزمة بدلًا من افتراض أنها نظيفة.

هل يعدّل أمر add مشروعي؟

يعمل Revera كغلاف شل. يشغّل مثبّت الحزم الفعلي بعد الفحص.

ما هي الحزمة «الملوثة» في مخرجات التدقيق؟

تُعلَّم الحزمة كملوثة عندما تؤدي إحدى تبعياتها الانتقالية إلى تفعيل نقض أو تحصل على درجة منخفضة بشكل حرج. تُظهر مخرجات التدقيق أسوأ مسار فرعي لتتمكن من تتبّع سلسلة التبعيات الدقيقة التي تسببت في هذا العلم.

كيف تُزال تكرارات الثغرات عبر قواعد البيانات الثلاث؟

تُعرَّف كل ثغرة بواسطة معرّف CVE أو معرّف GHSA أو معرّف استشارات npm (npm advisory). عندما تظهر الثغرة نفسها في مصادر متعددة، تُدمج في إدخال أساسي واحد. تحظى بيانات OSV بالأولوية في الحقول النصية (الملخص، التفاصيل)؛ ويُحتفظ بأعلى تصنيف خطورة وأكمل نطاق للإصدارات المصححة عبر جميع المصادر.

المساهمة

يرجى مراجعة دليل المساهمة للبدء في الإعداد وقواعد الأسلوب وإرشادات طلبات السحب (PR).

إخلاء المسؤولية

تقدّم Revera درجة سمعة استنادًا إلى إشارات المشروع القابلة للملاحظة والبيانات التاريخية. وهي تهدف إلى المساعدة في القرارات الهندسية ولا ينبغي التعامل معها كتدقيق أمني قاطع.

الترخيص

Revera موزعة بموجب رخصة MIT.