Индекс кода зависимостей

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.