# Dependency code index

> Build and query Elide's Maven dependency code index: resolve class origins, inspect types and members, and find outbound references or local Java and Kotlin callers.

`elide index` answers questions about code in your resolved Maven dependencies and compiled main Java and Kotlin
sources: which dependency defines a class, what a class references, and which local source files use a type or
member. [OpenRewrite](https://elide.help/docs/toolchain/jvm/rewrite) uses the same index for dependency types and candidate file selection.

Experimental in 1.6.0; compatibility hardening is planned for 1.6.1.

## Build the index

Run from an Elide project with `elide.pkl`:

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

`build` resolves dependencies, builds the requested dependency layers, and compiles the main Java and Kotlin
sources to refresh the local reference index. `status` reports the layers available for each resolved Maven
artifact; it does not list local classes.

For example, a project using Guava can declare:

```pkl
amends "elide:project.pkl"

name = "index-demo"

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

Add `src/main/java/demo/Main.java`:

```java
package demo;

import com.google.common.collect.ImmutableList;

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

After building the index, the following queries inspect this dependency and its use in the project.

## Find the dependency that defines a class

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

The first result is the class address on the main compile classpath:

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

If other indexed artifacts on that classpath define the same class, subsequent lines begin with `shadows` and name
those addresses. Resolution follows classpath order. If an earlier artifact lacks the required type index, the
command reports the missing layer instead of guessing which definition wins.

To print filesystem classpath entries, use [`elide classpath`](https://elide.help/docs/toolchain/source-sets#dependencies-and-classpaths).
The code index identifies definitions and code references; it does not print the transitive dependency path that
introduced an artifact.

## Inspect types and members

```bash
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()'
```

The artifact query lists indexed types. A type query prints its kind, visibility, supertypes, and archive entry;
a member query prints the matching member's kind, visibility, static/instance status, and JVM descriptor.

| Address | Identifies |
| --- | --- |
| `maven:group:artifact:version` | A resolved Maven artifact. |
| `maven:group:artifact:version/package.Type` | A type in that artifact. |
| `maven:group:artifact:version/package.Type#method(java.lang.String,int)` | A method, selected by parameter types. |
| `maven:group:artifact:version/package.Type#FIELD` | A field. |
| `local:project-name/package.Type` | A compiled local type, for `references`. |

Use binary type names (`package.Outer$Inner` for a nested class). Method keys omit the return type; constructors
use `<init>(...)`. Quote addresses with parentheses, `#`, or `$` to keep the shell from interpreting them.

## Follow outbound references

```bash
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` prints `type` and `member` lines for the types and members referenced by that compiled class. It takes
a type address, not a member address. In a local address, the project name is `name` from `elide.pkl` (or `project`
when unnamed).

## Find local uses

```bash
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` searches the compiled main-source reference index and prints matching package-relative source files,
such as `demo/Main.java`. A bare method name matches its overloads; a parameter list selects a signature. Results
are sorted and deduplicated. No matches produce no output and exit successfully.

The query covers local Java and Kotlin classes, not every dependency's callers. References erased during
compilation, unused imports, comments, and reflective uses named only by strings can be absent. Rebuild the index
after changing sources; a query does not compile them or refresh local references.

## Layers and refresh behavior

| Layer | Indexed information | Used by |
| --- | --- | --- |
| `l0` | Artifact entries and metadata | Artifact status and recipe discovery. |
| `l1` | Types, visibility, supertypes, and annotations | Type queries and class resolution. |
| `l2` | Fields, methods, constructors, and signatures | Member queries and rewrite type information. |
| `l3` | Outbound type and member references | Dependency `references` queries. |

`elide index build` defaults to dependency layers `l0,l1`. `--layers` selects layers to add; `l0` is always included,
and layers already built are retained. Include `l1,l2` together for member queries. The local reference index is
refreshed by `build` independently of the selected dependency layers.

Queries read existing index data. They may resolve project dependencies, but do not build missing index layers.
`get`, `references`, and `resolve` exit `1` for an unknown address or name. A missing required layer exits `2` and
prints a build command. Use `--offline` to prevent remote dependency downloads; required artifacts must already
be available locally.

Dependency index data lives under `.dev/dependencies/index/`, keyed by artifact content and index format version.
Local reference data lives under the project's build directory. Ordinary compilation does not request all index
layers; build them explicitly, or let a consumer such as OpenRewrite request what it needs.

## Scope and build-tool integration

The dependency index covers resolved Maven JARs without classifiers. npm, PyPI, arbitrary filesystem JAR paths,
and workspace sibling outputs are not dependency-index inputs. `resolve` searches indexed Maven artifacts on the
main compile classpath; it does not resolve local classes or JDK classes. Local addresses currently support
`references`, while `used-by` searches the local index by type/member name.

The commands use an `elide.pkl` project definition. Using Elide's compiler through the [Maven plugin](https://elide.help/docs/build-tools-maven),
[Gradle plugin](https://elide.help/docs/build-tools-gradle), or [Bazel rules](https://elide.help/docs/build-tools-bazel) does not populate this index from those
tools' dependency graphs. Define the matching sources and dependencies in an Elide project to use these queries.

See [Dependencies](https://elide.help/docs/toolchain/dependencies) for dependency declarations, and [OpenRewrite](https://elide.help/docs/toolchain/jvm/rewrite) for
applying recipes with the index.