Scalex

Keep scope and output deliberate

Start with a qualified symbol or the relevant path when known. Use --path, --kind, and command-supported package filters to reduce noise. Use --no-tests only when excluding tests fits the question; retain tests during impact analysis. overview excludes tests by default; add --include-tests when needed.

Prefer --limit N for readable samples and --count for counts. --max-output N limits result characters; with --json, oversized output becomes a valid truncation object instead of the requested result payload. Inspect truncation metadata before consuming JSON. A display limit is not a guarantee of less scanning work.

refs, imports, and grep have scan deadlines and can return partial results. Read stderr and timeout indicators; never present an incomplete scan as exhaustive. coverage currently discards the underlying timeout indicator, so use refs and inspect test-file matches when scan completeness matters.

Use ordinary text search for literal strings, configuration, unsupported files, or fresh edits. scalex grep is useful for symbol-scoped bodies and integrated source filters; it is not a required replacement for rg. Its patterns use Java regex syntax and invalid patterns may be rewritten with a diagnostic; check that diagnostic when matching punctuation.

Cache freshness after edits

The current cache compares Git index OIDs, not working-tree content hashes. Unstaged edits can leave cached symbols, imports, and bloom filters stale. Text reads may therefore disagree with cached navigation, and stale bloom filters can hide newly added names.

After editing, verify affected code directly. index reports the normally loaded index; it does not force a clean rebuild. Do not stage changes or delete caches merely to make a query work. Use the project's compile/test workflow to validate code changes.

diff <ref> reads current source and the Git ref directly, including unstaged edits. It reports declaration-text changes, including bodies, rather than semantic equivalence; see the diff reference for scope and display limits.

Several independent lookups

Use batch to share one index load when several queries are already known:

printf '%s\n' 'def UserService' 'members UserService' 'impl UserService' |
  bash /absolute/path/to/scalex/scripts/scalex-cli batch -w /repo

Batch lines are split on whitespace, without shell-style quote parsing. Run queries containing spaced arguments, such as test names, as separate commands. Set the workspace on the outer batch invocation. Batch output includes command separators; do not parse the entire stream as one JSON document. The index is shared for that batch, so start a new invocation after edits.

Failures and diagrams

Usage errors exit 2; operational failures exit 1. JSON-mode failures use an error object on stdout; text diagnostics use stderr. Batch continues after failed queries and returns the highest failure status. Report a tool failure separately from an empty successful result.

Run graph --render or graph --parse only for an explicit diagram request. Read graph-examples.md for syntax. Do not add a graph step to ordinary navigation; hierarchy, deps, and explain already format their results.