فهرس شيفرة التبعيات

يجيب elide index عن أسئلة حول الشيفرة في تبعيات Maven المحلولة وفي مصادر Java و Kotlin الرئيسية المصرَّفة: أي تبعية تعرّف صنفًا ما، وإلامَ يشير صنف ما، وأي ملفات مصدر محلية تستخدم نوعًا أو عضوًا. ويستخدم OpenRewrite الفهرس نفسه لأنواع التبعيات واختيار الملفات المرشّحة.

ميزة تجريبية في 1.6.0؛ ومن المخطط تحسين التوافق في 1.6.1.

بناء الفهرس

شغّل من مشروع Elide فيه elide.pkl:

elide index build --layers=l1,l2,l3
elide index status

يحلّ build التبعيات، ويبني طبقات التبعيات المطلوبة، ويصرّف مصادر Java و Kotlin الرئيسية لتحديث فهرس المراجع المحلي. ويعرض status الطبقات المتاحة لكل مُخرَج Maven محلول، ولا يسرد الأصناف المحلية.

على سبيل المثال، يمكن لمشروع يستخدم Guava أن يصرّح بما يلي:

amends "elide:project.pkl"

name = "index-demo"

dependencies {
  maven {
    packages { "com.google.guava:guava:33.4.8-jre" }
  }
}

أضف src/main/java/demo/Main.java:

package demo;

import com.google.common.collect.ImmutableList;

public class Main {
  public static void main(String[] args) {
    System.out.println(ImmutableList.of());
  }
}

بعد بناء الفهرس، تفحص الاستعلامات التالية هذه التبعية واستخدامها في المشروع.

العثور على التبعية التي تعرّف صنفًا

elide index resolve com.google.common.collect.ImmutableList

النتيجة الأولى هي عنوان الصنف على classpath التصريف الرئيسي:

maven:com.google.guava:guava:33.4.8-jre/com.google.common.collect.ImmutableList

إذا عرّفت مُخرَجات مفهرسة أخرى على ذلك الـ classpath الصنف نفسه، فإن الأسطر التالية تبدأ بـ shadows وتذكر تلك العناوين. يتبع الحلّ ترتيب classpath. وإذا افتقر مُخرَج سابق إلى فهرس الأنواع المطلوب، أبلغ الأمر عن الطبقة الناقصة بدلًا من تخمين التعريف الغالب.

لطباعة إدخالات classpath في نظام الملفات، استخدم elide classpath. يحدّد فهرس الشيفرة التعريفات والمراجع في الشيفرة، ولا يطبع مسار التبعيات المتعدّية الذي أدخل مُخرَجًا ما.

فحص الأنواع والأعضاء

elide index get maven:com.google.guava:guava:33.4.8-jre
elide index get maven:com.google.guava:guava:33.4.8-jre/com.google.common.collect.ImmutableList
elide index get 'maven:com.google.guava:guava:33.4.8-jre/com.google.common.collect.ImmutableList#of()'

يسرد الاستعلام عن مُخرَج الأنواعَ المفهرسة. ويطبع الاستعلام عن نوع صنفه وإمكانية رؤيته وأنواعه الأعلى وإدخاله في الأرشيف، ويطبع الاستعلام عن عضو نوع العضو المطابق وإمكانية رؤيته وكونه ثابتًا أو تابعًا للمثيل وواصف JVM الخاص به.

استخدم أسماء الأنواع الثنائية (package.Outer$Inner للصنف المتداخل). تُسقط مفاتيح الدوال نوع القيمة المُعادة، وتستخدم المُنشِئات ⁦<init>(...)⁩. ضع العناوين التي تحتوي على أقواس أو # أو $ بين علامتي اقتباس كي لا تفسّرها الصدفة.

تتبّع المراجع الصادرة

elide index references maven:com.google.guava:guava:33.4.8-jre/com.google.common.collect.ImmutableList
elide index references local:index-demo/demo.Main

يطبع references أسطر type و member للأنواع والأعضاء التي يشير إليها ذلك الصنف المصرَّف. ويأخذ عنوان نوع لا عنوان عضو. في العنوان المحلي، اسم المشروع هو name من elide.pkl (أو project إن لم يكن للمشروع اسم).

العثور على الاستخدامات المحلية

elide index used-by com.google.common.collect.ImmutableList
elide index used-by 'com.google.common.collect.ImmutableList#of'
elide index used-by 'com.google.common.collect.ImmutableList#of()'

يبحث used-by في فهرس مراجع المصادر الرئيسية المصرَّفة ويطبع ملفات المصدر المطابقة بمسارات نسبية إلى الحزمة، مثل demo/Main.java. يطابق اسم الدالة المجرّد كل تحميلاتها الزائدة، وتختار قائمة المعاملات توقيعًا واحدًا. تُرتَّب النتائج وتُزال المكررات. وإن لم توجد مطابقات فلا مخرجات، وينتهي الأمر بنجاح.

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

الطبقات والتحديث

يبني elide index build افتراضيًا طبقتَي التبعيات l0,l1. يختار --layers الطبقات المراد إضافتها، وتُضمَّن l0 دائمًا، وتُحفظ الطبقات المبنية سابقًا. ضمّن l1,l2 معًا لاستعلامات الأعضاء. ويحدّث build فهرس المراجع المحلي بغضّ النظر عن طبقات التبعيات المختارة.

تقرأ الاستعلامات بيانات الفهرس الموجودة. قد تحلّ تبعيات المشروع، لكنها لا تبني الطبقات الناقصة. يخرج get و references و resolve بالرمز 1 عند عنوان أو اسم غير معروف. وعند غياب طبقة مطلوبة يخرج الأمر بالرمز 2 ويطبع أمر بناء. استخدم --offline لمنع تنزيل التبعيات من الشبكة، وعندها يجب أن تكون المُخرَجات المطلوبة متاحة محليًا.

تُخزَّن بيانات فهرس التبعيات تحت .dev/dependencies/index/، ومفتاحها محتوى المُخرَج وإصدار صيغة الفهرس. وتُخزَّن بيانات المراجع المحلية في مجلد البناء الخاص بالمشروع. لا يطلب التصريف العادي كل طبقات الفهرس، فابنها صراحةً أو دع مستهلكًا مثل OpenRewrite يطلب ما يحتاجه.

النطاق والتكامل مع أدوات البناء

يغطي فهرس التبعيات ملفات JAR المحلولة من Maven دون مصنِّفات. أما حزم npm و PyPI، ومسارات JAR الاعتباطية في نظام الملفات، ومخرجات المشاريع الشقيقة في مساحة العمل، فليست مدخلات لفهرس التبعيات. يبحث resolve في مُخرَجات Maven المفهرسة على classpath التصريف الرئيسي، ولا يحلّ الأصناف المحلية ولا أصناف JDK. تدعم العناوين المحلية حاليًا references، بينما يبحث used-by في الفهرس المحلي باسم النوع أو العضو.

تستخدم الأوامر تعريف مشروع في elide.pkl. لا يؤدي استخدام مُصرّف Elide عبر إضافة Maven أو إضافة Gradle أو قواعد Bazel إلى ملء هذا الفهرس من رسوم تبعيات تلك الأدوات. عرّف المصادر والتبعيات المطابقة في مشروع Elide لاستخدام هذه الاستعلامات.

راجع التبعيات للتصريح بالتبعيات، و OpenRewrite لتطبيق الوصفات باستخدام الفهرس.