context-finder

Context Finder Skill

Use code/context to answer "which classes does this file actually need?" and "how many tokens will that cost?" — the module behind the project_tree, find_context, estimate_tokens and okf_bundle MCP tools.

The core contract

public interface Context {
    Set<ClassContainer> find(ClassContainer root, int depth);
}

A ClassContainer is just a className (the file name) plus its originalCode. depth bounds a breadth-first expansion, so nearest dependencies come first — which is what makes budgeting meaningful.

Load a project's sources with new ProjectSources(Language.JAVA).load(root), which returns Map<Path, ClassContainer>. Languages: JAVA (.java), KOTLIN (.kt), SCALA (.scala).

Pick the right finder

Finder	Resolves by	Use when
Finder	simple file name, indexed once at construction	one class per simple name; fastest
PackageAwareFinder	package + import declarations	two classes share a simple name in different packages

PackageAwareFinder prefers, in order: an explicit import, the referencing file's own package, a wildcard import, then a sole project-wide candidate — and leaves a genuinely ambiguous reference unresolved rather than guessed. Both strip comments and string/character literals before matching, so a class name mentioned in a comment is not reported as a dependency. The package/import grammar is shared by all three languages.

Budgeting

BudgetedContext decorates any Context: it keeps the delegate's breadth-first order and accepts containers until the next one would exceed the budget, so you keep the highest-priority prefix of the graph.

Context context = new BudgetedContext(new Finder(containers), new SubwordTokenEstimator(), 8_000);

Estimators implement TokenEstimator: SubwordTokenEstimator (respects word and symbol boundaries — the better default) and HeuristicTokenEstimator.

Project tree

ProjectTreeBuilder(contextFactory, language, depth).build(root) returns a ProjectTreeNode. Serialize with a ProjectTreeSerializer: ProjectTreeJsonSerializer (the MCP default), …Markdown…, …Dot… (Graphviz), …Mermaid…, or print with ProjectTreePrinter. The builder takes a ContextFactory, so a different finder can be substituted without touching the builder — add a serializer or a factory rather than branching inside the builder.