### Nix```bash
nix profile install github:brennhill/sloppy-joe

### 2. التصيد الإملائي (فحوصات توليدية + احتياطي مسافة التحرير)

**الهجوم:** يُسجِّل مهاجم الحزمة `expresz` على npm — حرف واحد مختلف عن `express`. قد تُنشئها الذكاء الاصطناعي، أو قد يخطئ المطور في كتابتها. الحزمة موجودة، وتجتاز فحص الوجود، وتُثبّت برامج ضارة.

**كيف يمنعها sloppy-joe:** يقوم sloppy-joe بتشغيل 10 فحوصات توليدية قبل اللجوء إلى احتياطي مسافة التحرير. يُنتِج كل فحص توليدي تحويرًا محددًا لاسم التبعية (تبديل الأحرف، تكرار الأحرف المتجاورة، إزالة اللواحق، إعادة ترتيب الكلمات، توحيد الفواصل، استبدال الحروف المتشابهة شكليًا، فحص النطاقات) ويختبر التطابق التام مع الحزم الشائعة المعروفة. هذا الأسلوب، المستوحى من مكتبة [Typomania لمؤسسة Rust](https://github.com/rustfoundation/typomania)، يتمتع باحتمال ضئيل جدًا للإيجابيات الكاذبة لأنه يعمل فقط على التطابقات التامة بعد التحوير.

تعمل مسافة التحرير لـ Levenshtein في النهاية كشبكة أمان للتحويرات الجديدة التي لم يتوقعها أي فحص محدد. معًا، تغطي أنماط الهجوم المعروفة (بدقة) وغير المعروفة (على نطاق واسع).```
ERROR expresz [similarity/edit-distance]
      'expresz' is 1 character away from 'express'. This could be a typosquat.
 Fix: If you meant 'express', fix the name in your manifest.

### 4. الارتباك في الفاصل

**الهجوم:** `python-dateutil` مقابل `python_dateutil` مقابل `pythondateutil`. في بعض السجلات، هذه حزم مختلفة. يسجل المهاجم المتغير.

**كيف يحجبها sloppy-joe:** يقوم بتطبيع جميع الفواصل (`-`, `_`, `.`) قبل المقارنة. إذا تطابق الشكل المُطبّع مع حزمة معروفة، يتم وضع علامة عليها.```
ERROR socket_io [similarity/separator-confusion]
      'socket_io' matches 'socket.io' after normalizing separators.
 Fix: Use the canonical name 'socket.io' with the correct separators.

### 6. تبديل الأحرف المتجاورة

**الهجوم:** `reqeust` بدلاً من `request`. حرفان متجاوران تم قلبهما — خطأ إملائي شائع يستغله المهاجمون.

**كيف يمنعه sloppy-joe:** يقوم بتوليد جميع متغيرات التبادل المتجاور لاسم التبعية ويتحقق من كل منها مقابل المجموعة.```
ERROR reqeusts [similarity/char-swap]
      'reqeusts' matches 'requests' with two adjacent characters swapped.
 Fix: Use 'requests' — two characters are transposed.

### 8. الهوموغليف (المتشابهات البصرية)

**الهجوم:** `rеquests` بحرف `е` سيريلي (U+0435) بدلاً من الحرف اللاتيني `e` (U+0065). متطابقة بصريًا. يبدو اسم الحزمة تمامًا مثل `requests` لكنه يشير إلى حزمة ضارة مختلفة.

**كيف يمنعه sloppy-joe:** يستبدل 17 حرفًا هوموغليفيًا معروفًا (سيريلية، عريضة، متغيرات خطية) بنظيراتها اللاتينية ويتحقق مما إذا كانت النتيجة تطابق حزمة معروفة.```
ERROR rеquests [similarity/homoglyph]
      'rеquests' contains characters that look identical to 'requests'
      but are different Unicode codepoints (homoglyphs).
 Fix: Replace the lookalike characters with standard ASCII.

### 10. هجمات تباين الحالة (سجلات حساسة لحالة الأحرف)

**الهجوم:** في Go و Maven و Ruby، فإن `Rails` و `rails` هما حزمتان مختلفتان. يقوم المهاجم بتسجيل المتغير الذي يحتوي على حرف كبير.

**كيف يمنعه sloppy-joe:** في السجلات الحساسة لحالة الأحرف، يتم وضع علامة على أي تباين في حالة حزمة معروفة كخطأ. في السجلات غير الحساسة لحالة الأحرف (npm, PyPI, Cargo, NuGet, PHP)، تكون تباينات الحالة آمنة ويتم تخطيها.```
ERROR Rails [similarity/case-variant]
      'Rails' differs from 'rails' only in letter casing.
      On case-sensitive registries (ruby) these resolve to different packages.
 Fix: Use the exact casing 'rails' in your manifest.

### 12. احتلال النطاق (npm, PHP, Go, JVM)

**الهجوم:** يسجِّل المهاجم `@typos/lodash` على npm — بفارق حرف واحد عن `@types/lodash`. أو `larvael/framework` على Packagist — بفارق حرفين عن `laravel/framework`. أو `github.com/gooogle/protobuf` على Go — بحرف `o` زائد. يبدو النطاق شرعيًا للوهلة الأولى. يتم تحميل الحزمة. يتم تثبيت البرنامج الضار.

هذا نادر ولكنه محتمل — و"نادر ولكنه محتمل" هو تحديدًا ما وُجد من أجله sloppy-joe. حادثة `ua-parser-js` في عام 2021 كانت متعلقة بالنطاق. إذا كان يمكن أن يحدث لحزمة بملايين التنزيلات الأسبوعية، فيمكن أن يحدث لحزمتك.

**كيف يمنعه sloppy-joe:** يستخرج النطاق/الاسم الفضائي من اسم التبعية ويقارنه بقائمة النطاقات المعروفة الموثوقة باستخدام مسافة التعديل. يعمل على npm (`@scope`)، وPHP (`vendor/`)، وGo (`github.com/org`)، وJVM (`com.group`).```
ERROR @typos/lodash [similarity/scope-squatting]
      Scope '@typos' is 1 character away from the known scope '@types'.
      Scope squatting is a known supply chain attack vector.
 Fix: If you meant '@types/lodash', fix the scope in your manifest.

### 13. الحزم غير القانونية (ليست هجومًا — بوابة اتساق)

**الهجوم:** ليس هجومًا — مشكلة اتساق. تختار الذكاء الاصطناعي `moment` لأنه كان شائعًا في بيانات التدريب، لكن فريقك يستخدم `dayjs`. استخدام فرق مختلفة لحزم مختلفة لنفس المهمة يخلق دينًا صيانةً وتضخمًا في التبعيات.

**كيف يحجب sloppy-joe ذلك:** يقوم تكوينك بتعيين كل حزمة قانونية إلى بدائلها المرفوضة. إذا تطابقت تبعية مع بديل، يفشل البناء.```
ERROR moment [canonical]
      'moment' is not the approved package for this purpose.
      Your team uses 'dayjs'.
 Fix: Replace 'moment' with 'dayjs' in your manifest file.

### 15. الحزم الجديدة تمامًا

**الهجوم:** حزمة تم إنشاؤها أمس مع 3 تنزيلات ولها اسم مشابه لحزمة شائعة. احتمال كبير أنها انتحال اسم أو عنصر نائب لهجوم مستقبلي.

**كيف يمنعها sloppy-joe:** يشير إلى أي حزمة تم إنشاؤها منذ أقل من 30 يومًا.```
ERROR sketchy-lib [metadata/new-package]
      'sketchy-lib' was first published 2 days ago.
      New packages are higher risk.
 Fix: Verify 'sketchy-lib' at its registry page and source repository.

---

## الأنظمة البيئية المدعومة

| النظام البيئي | الملف الدال (Manifest) | سياسة ملف القفل (Lockfile Policy) | الوجود (Existence) | البيانات الوصفية (Metadata) | بوابة العمر (Age Gate) |
|-----------|----------|-----------------|:---------:|:--------:|:--------:|
| npm | package.json | `package-lock.json` أو `npm-shrinkwrap.json` مطلوب | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| PyPI | `pyproject.toml`, `requirements*.txt`, `Pipfile`, `setup.cfg`, `setup.py` | يتم الوثوق بـ Poetry مع `poetry.lock`، ويتم الوثوق بـ uv مع `uv.lock`، ويتم الوثوق بـ pip-tools المقيد بالتجزئة الكاملة فقط عندما يربط رسم التبعيات الملتزم `--index-url` وقيم `--extra-index-url` المسموح بها بالضبط، ويمكن الوثوق بفهارس Poetry/uv المخصصة المرئية في المستودع فقط بواسطة قائمة السماح `trusted_indexes.pypi` بالضبط؛ الملفات الدالة القديمة تحذر في كل تشغيل ما لم يكن `python_enforcement` هو `poetry_only` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Cargo | Cargo.toml | `Cargo.lock` مطلوب | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Go | go.mod | `go.sum` مطلوب للتبعيات الخارجية؛ غير مطلوب للمكتبة القياسية فقط أو `replace` المحلية بالكامل | :white_check_mark: | :x: | :x: |
| Ruby | Gemfile | `Gemfile.lock` مطلوب | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| PHP | composer.json | `composer.lock` مطلوب | :white_check_mark: | :x: | :x: |
| JVM (Gradle) | build.gradle / build.gradle.kts | `gradle.lockfile` مطلوب | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| JVM (Maven) | pom.xml | تحذير فقط: لا يوجد تطبيق صارم لملف القفل | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| .NET | *.csproj | `packages.lock.json` مطلوب | :white_check_mark: | :x: | :x: |

جميع الأنظمة البيئية تحصل على فحوصات الوجود + التشابه + القانونية. تعتمد البيانات الوصفية وبوابة العمر على ما يعرضه واجهة برمجة تطبيقات السجل. يدعم ملف القفل فحص التبعيات العابرة وحل الإصدارات الدقيق حيث يوفر النظام البيئي نموذج ملف قفل موثوق به على مستوى المستودع.

## بدء الاستخدام السريع```bash
# Install
cargo install sloppy-joe

# Check current project (auto-detects ecosystem)
sloppy-joe check

# Check with canonical enforcement and age gate
sloppy-joe check --config /etc/sloppy-joe/config.json

# Output as JSON for CI
sloppy-joe check --json

**`canonical`** — المفاتيح هي حزم معتمدة؛ القيم هي بدائل مرفوضة.

**`internal`** — حزم مؤسستك. تخطي جميع الفحوصات. هذه تتغير باستمرار.

**`allowed`** — حزم خارجية مدققة. تخطي فحص الوجود والتشابه، ولكن لا تزال تخضع لشرط عمر الإصدار.

**`similarity_exceptions`** — إلغاءات دقيقة للحزمة/المرشح/المولد للإيجابيات الكاذبة للتشابه التي تمت مراجعتها. استخدم هذا عندما تكون حالة تشابه واحدة خاطئة ولكنك لا تزال ترغب في الفحوصات العادية على الحزمة.

**`metadata_exceptions`** — إلغاءات دقيقة للبيانات الوصفية التي تمت مراجعتها. حالياً هذا يدعم فقط `metadata/maintainer-change`، ويتطلب تطابقاً دقيقاً للحزمة/الإصدار/الناشر السابق/الناشر الحالي.

استخدم `sloppy-joe check --review-exceptions` عندما تحتاج إلى مراجعة حاصرات تغيير الصيانة. لا يزال المسح يحظر بشكل طبيعي، لكن الإخراج البشري يضيف قسم `REVIEW EXCEPTIONS` مع المالكين، رابط المستودع، ومقتطف `metadata_exceptions` جاهز للصق. `--json` يتضمن نفس البيانات في حقل `review_candidates` على المستوى الأعلى.

**`min_version_age_hours`** — حظر أي إصدار نُشر قبل أقل من هذا العدد من الساعات. الافتراضي: 72 (3 أيام). اضبط على 0 لتعطيله. الحزم الداخلية مستثناة.

**`allow_legacy_npm_v1_lockfile`** — السماح بملفات قفل npm `lockfileVersion: 1` من npm v5/v6 في وضع الثقة المنخفضة. الافتراضي: `false`. أبقه مغلقاً إلا إذا كنت عالقاً عمداً في npm القديم وتقبل التحذيرات الصاخبة بالإضافة إلى تغطية npm الانتقالية الموثوقة المنخفضة.

**`python_enforcement`** — يتحكم في سياسة الثقة في بايثون. `prefer_poetry` (الافتراضي) يثق في مشاريع Poetry ومشاريع uv، ويثق في متطلبات pip-tools المقفلة بالكامل بالتجزئة فقط عندما يربط رسم المتطلبات الملتزمة القيم `--index-url` وأي `--extra-index-url` غير PyPI بالضبط، وبخلاف ذلك يخفض pip-tools إلى ثقة منخفضة. الملفات القديمة مثل `requirements*.txt` غير المجزأة، `Pipfile`، `setup.cfg`، `setup.py`، و `pyproject.toml` غير Poetry/uv تحذر في كل تشغيل. `poetry_only` يحظر تلك سير عمل بايثون غير Poetry ويتطلب Poetry.

### أمان التكوين

لا **يُقرأ التكوين أبداً من دليل المشروع**. يمكن لوكيل ذكاء اصطناعي مع وصول إلى شل إعادة كتابة تكوين داخل المستودع لإدراج ما يريد في القائمة البيضاء.

حل التكوين:
1. `--config /path/to/config.json` — ملف محلي (علم CLI، أعلى أولوية)
2. `--config https://example.com/config.json` — جلب من URL
3. `SLOPPY_JOE_CONFIG=...` — متغير بيئة (مسار ملف أو URL)
4. لا تكوين = فحوصات الوجود والتشابه والبيانات الوصفية فقط

التكوينات التالفة **تفشل بشدة** مع رسائل خطأ قابلة للتنفيذ — لا يتراجع التكوين المعطل بصمت إلى عدم وجود حماية.

راجع [CONFIG.md](https://github.com/brennhill/sloppy-joe/blob/HEAD/CONFIG.md) للمرجع الكامل للتنسيق، وأنماط تكامل CI، والأمثلة.

تكوين التمهيد:```bash
sloppy-joe init --greenfield --ecosystem npm
sloppy-joe init --from-current
sloppy-joe init --from-current --register
sloppy-joe init --register

#### مدخلات الإجراء

| المدخل | الوصف | الافتراضي |
|-------|-------------|---------|
| `config` | مسار ملف التكوين أو رابط HTTPS | *(لا شيء)* |
| `dir` | دليل المشروع المراد مسحه | `.` |
| `type` | النظام البيئي (`npm`, `pypi`, `cargo`, `go`, `ruby`, `php`, `jvm`, `dotnet`) | اكتشاف تلقائي |
| `deep` | تمكين فحوصات تشابه التبعيات المتعدية | `false` |
| `paranoid` | تمكين تغييرات bitflip | `false` |
| `args` | وسائط سطر أوامر إضافية | *(لا شيء)* |
| `version` | إصدار sloppy-joe المراد تثبيته | `latest` |

#### أمثلة```yaml
# Minimal — CI-oriented scan, auto-detect ecosystem, no config
- uses: brennhill/[email protected]

# With org config from a URL
- uses: brennhill/[email protected]
  with:
    config: https://raw.githubusercontent.com/yourorg/configs/main/sloppy-joe.json

# Deep scan with paranoid mode
- uses: brennhill/[email protected]
  with:
    config: ${{ secrets.SLOPPY_JOE_CONFIG }}
    deep: true
    paranoid: true

# Scan a subdirectory, pin to a specific version
- uses: brennhill/[email protected]
  with:
    dir: ./packages/api
    version: '1.1.0'

### pre-commit

يعمل sloppy-joe مع إطار [pre-commit](https://pre-commit.com).
أضفه إلى ملف `.pre-commit-config.yaml` الخاص بك:```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/brennhill/sloppy-joe
    rev: v1.1.0
    hooks:
      - id: sloppy-joe

أو استخدم ربط شل بسيط دون الإطار:```bash
#!/bin/sh
sloppy-joe check || exit 1

تشغيل التشابه على 4 مراحل:
- **Phase 0: Scope squatting** — فحص محلي، بدون اتصال بالشبكة. يقارن النطاق/الفضاء الاسمي مع نطاقات معروفة جيدة عبر مسافة ليفنشتاين.
- **Phase 1: Intra-manifest** — فحص محلي. يشير إلى وجود تبعيتين في نفس المانيفست تكونان طفرات من بعضهما البعض.
- **Phase 2: Registry query** — يولد الطفرات، ويستعلم السجل بشكل دفعاتي لوجودها، ويخزن النتائج مؤقتًا (7 أيام TTL).
- **Phase 3: Metadata enrichment** — يجلب أعداد التحميلات وتواريخ النشر للمطابقات لإضافة أدلة إلى التقارير.

كل مولد طفرة يوسم مخرجاته، لذلك فإن نوع الفحص المُبلَّغ عنه (مثل `similarity/homoglyph`) حتمي — المولد ذو الخطورة الأعلى يفوز عندما تنتج مولدات متعددة نفس المرشح.

## موثوقية التكامل المستمر

صمم sloppy-joe لخطوط أنابيب التكامل المستمر حيث الفشل المتقلب غير مقبول.

**إعادة المحاولة مع التباطؤ.** جميع استدعاءات HTTP للسجل تعيد المحاولة 3 مرات مع تباطؤ أسي (200ms، 400ms، 800ms) عند الفشل المؤقت (5xx، مهلات، أخطاء اتصال). خلل شبكة واحد لن يعطل بناءك.

**الإغلاق عند الفشل في أخطاء الاستعلام.** إذا فشلت استعلامات السجل أو OSV، يُصدر sloppy-joe خطأ حظرًا `registry-unreachable` بدلاً من تخطي الفحوصات بصمت. لم يعد الفحص يعتمد على عتبات لكل نظام بيئي أو عتبات حجم العينة قبل الحظر.

**ذاكرة تشابه مؤقتة.** تُخزَّن نتائج وجود الطفرات مؤقتًا لمدة 7 أيام. بعد أول فحص، تُخدم معظم الاستعلامات من الذاكرة المؤقتة بدون استدعاءات شبكة. فقط التبعيات الجديدة تؤدي إلى استعلامات السجل.

**تحليل واعي بملف القفل.** عندما يكون ملف القفل المدعوم موجودًا وجديرًا بالثقة (`package-lock.json`, `npm-shrinkwrap.json`, `Cargo.lock`, `Gemfile.lock`, `poetry.lock` لمشاريع Poetry, `uv.lock` لمشاريع uv, `composer.lock`, `gradle.lockfile`, `packages.lock.json`), يحلل sloppy-joe الإصدارات الدقيقة منه بدلاً من التخمين من النطاقات. كما يمكن لـ `requirements*.txt` المغلقة بالهاش بالكامل توفير إصدارات مثبتة دقيقة، وتصبح موثوقة تمامًا عندما يربط رسم التبعيات المُلتزَم به قيم `--index-url` الخاصة وقيم `--extra-index-url` المسموح بها بدقة.

## الاختبارات

تغطي مجموعة الاختبارات فحوصات التشابه، إشارات البيانات الوصفية، سلوك OSV، تحليل الإعدادات والتحقق منها، تحليل ملف القفل، سياسة الفحص المسبق للمانيفست وملف القفل، تنسيق التقارير، ومنطق إعادة محاولة HTTP.```bash
cargo test