Skip to content
NetflixPublic

About

Source aware symbol search for Java classes

Topics

Resources

Stars

13 stars

Watchers

0 watching

Forks

Latest commit

 

History

85 Commits

Folders and files

Repository files navigation

jist

Maven Central JDK 25+

jist provides high-performance, source-aware search of Java class symbols for a given class or module path.

Search targets can be an exact simple name, a qualified namespace prefix, a source file, or a ClassFile:

$ jist java.lang.String.intern
java.lang.String(String.java:4711):     public native String intern();

Capabilities include:

  • Find modules, packages, types, methods, constructors, and fields
  • Search the JDK without additional configuration
  • Search project source and compiled dependencies using standard Java path and module options
  • Show literal source signatures, documentation, definitions, enclosing types, or complete source files
  • Find semantic usages of an exact type or member, including overriding methods
  • Find caller and callee edges for matching executables or every executable declared by a matching type
  • Produce terminal-friendly, stable line-oriented, or streaming JSON output

Positional names are literal Java names, not regular expressions. A simple name matches that complete terminal name wherever it is visible. A qualified name selects that exact delimiter-bounded namespace and the symbols beneath it. For declaration discovery, -e / --regexp searches simple names with a Java regular expression. Expressions match anywhere in the name unless anchored with ^ or $; repeated expressions form a union. -i / --ignore-case makes declaration-name matching case-insensitive without changing the names or identities in the results. List mode also accepts * wildcards.

Combine a positional name with -e to search declarations within that owner or namespace. Expressions match each declaration's own simple name, not its owner, parameter types, documentation, or source text. Constructors use the name new. Selection is independent of -l, source depth, and output format; widening --source expands the selected declarations rather than changing the name search. No matches produces a successful empty result for an expression search.

Usage and relationship queries accept exact simple names and delimiter-bounded type or member suffixes, such as String.repeat. Referenced-type queries accept type suffixes, such as Map.Entry. Source descriptions accept those suffixes when no qualified prefix matches. Multiple matching subjects form a union. -e and -i select declarations, not semantic relationship targets. There is no fuzzy scoring, ranking, or typo correction.

Important

This tool is currently in preview. Please share feedback for any of the tools in Discussions.

Installation

Note

Netflix engineers should use the internally bundled toolchain rather than installing this tool separately.

Follow the ja Installation Guide to install the bundled tools, including jist.

For standalone use, resolve the modular JAR and its dependencies from Maven Central. JDK 25 or later is required. Run module com.netflix.tools.jist with the resolved modules on the module path:

java --module-path <resolved-modules> --module com.netflix.tools.jist java.lang.String

JMOD artifacts are also published for building custom runtime images.

Quick start

Find every visible symbol with a complete simple name:

jist HttpClient

List declarations whose terminal names contain a fragment:

jist -l -e Queue

Search declaration names without case sensitivity:

jist -l -i -e queue

Search a type's declarations with an anchored expression:

jist java.lang.String -e '^(intern|repeat)$'

Select an exact package, type, or member prefix with a qualified name:

jist java.lang.String.valueOf

Find semantic references to an exact type or member:

jist --usages java.lang.Integer.MAX_VALUE

Find calls to methods matching a simple name or type/member suffix:

jist --callers repeat
jist --callers String.repeat

Find calls to any method or constructor declared by a matching type:

jist --callers String

Show source documentation and the complete declaration:

jist --source definition java.lang.String.length

Results include compact resolution origins by default. Named modules use module@version/ qualification, with versions taken from resolved module descriptors, including the selected JDK system image. Class-path entries remain unnamed even when a JAR contains a module descriptor. Archive names identify containing binaries; attached source does not replace that defining location. For example:

class example.library@1.2.3/example.Widget(library-1.2.3.jar)
class example.Widget(library-1.2.3.jar)
java.base@27.0.1/java.lang.String(String.java:4034): java.lang.String.indent(int) -> java.lang.String.repeat(int)

Use --show-origin for full resolution locations instead of short archive or source filenames.

Stream qualified, machine-readable results:

jist --format json java.lang.String.length

JSON output streams a version 1 envelope with format: "jist" and a results array. Each result contains text and available structured origin and source information. Symbol listings also contain undecorated symbol identities and declaration kind; source and ClassFile presentation rows contain the owning unit. Consumers should use these identities rather than parsing display text. origin.classLocation retains the defining ClassFile location separately from attached-source locations and ranges. The envelope ends with exitCode and diagnostics, for example:

{"format":"jist","version":1,"results":[],"exitCode":1,"diagnostics":[{"kind":"not_found","message":"Executable not found: example.Missing.run"}]}

A successful search has exitCode: 0 and an empty diagnostics array, even when it finds no references or call edges. An unsuccessful search retains results emitted before the failure. Each diagnostic has a kind and message: not_found means the requested target was absent; error means the query was invalid or the search failed. Exit code 1 alone does not distinguish these cases. Consumers must inspect the outcome before treating results as complete. These fields extend the version 1 envelope without changing existing result fields.

Diagnostics also remain on standard error, and exitCode matches the tool's return status. Errors encountered before command-line parsing selects JSON output are reported only on standard error; help, version, and completion output retain their own formats.

--release applies javac's Java SE API signatures when Jist attributes project or attached source. It does not change the ClassFiles Jist searches or select historical JDK implementation source; when matching source is unavailable, Jist falls back to ClassFile signatures.

Compiled caller identities and parameter signatures come from ClassFile descriptors, so a caller can be reported even when an optional parameter type is absent from the compilation context. Semantic resolution is still required for call targets and source attribution.

A Java file on a directory source path takes precedence over matching ClassFiles, so searches reflect current project source without requiring compilation. Source archives remain attached source for their matching ClassFiles.

--exclude-path <path> narrows searches by excluding input roots. Separate multiple paths with the platform path separator, as with --class-path and --module-path. Paths are matched by normalized absolute location, not by a recursive pattern. Excluded inputs remain available for type resolution, relationship targets, ancestor traversal, and source attachment.

Documentation

The wiki covers:

About

Source aware symbol search for Java classes

Topics

Resources

Stars

13 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages