Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

feat(graph): full-fidelity Kotlin extraction (#130)

shovelmn1218b72813615f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 89062b5b..a87a4507 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,22 @@
## 0.12.0
+### Added
+
+- **Kotlin moves to full-fidelity extraction.** `.kt` and `.kts` files are now
+ parsed by a hand-written tree-sitter extractor — the same tier as TypeScript,
+ Python, Go, and Java — instead of the generic breadth grammar, so Kotlin
+ symbols, call edges, heritage, and imports resolve with scope awareness. The
+ kind mapping now matches tree-sitter-kotlin's real node types (the earlier
+ attempt reused Java's, which do not exist in the Kotlin grammar and emitted no
+ symbols at all): `class_declaration` is re-read off its own keyword into
+ class / interface / enum / annotation, `object` and `companion object` become
+ classes, secondary constructors and member functions become methods,
+ `typealias` becomes a type, and top-level `val`/`var` become variables.
+- **Kotlin edges.** Calls resolve through `call_expression` (member calls via
+ `navigation_expression`, with `this`/`super` receivers), the `:` heritage
+ clause yields `extends` edges, `import_header` yields import edges, and
+ `internal`/`private`/`protected` visibility maps to the exported flag.
### Changed
- **graft now collects anonymous usage stats, and the README no longer says it
diff --git a/node_modules b/node_modules
new file mode 120000
index 00000000..9cf9293f
--- /dev/null
+++ b/node_modules
@@ -0,0 +1 @@
+/Users/shrishdwivedi/Documents/Context graphs/context-graph-engine/node_modules
\ No newline at end of file
diff --git a/package-lock.json b/package-lock.json
index dee5ff2d..515935b6 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -18,6 +18,7 @@
"tree-sitter": "^0.21.1",
"tree-sitter-go": "^0.23.4",
"tree-sitter-java": "^0.23.5",
+ "tree-sitter-kotlin": "^0.3.8",
"tree-sitter-php": "^0.23.4",
"tree-sitter-python": "^0.21.0",
"tree-sitter-typescript": "^0.23.2",
@@ -914,6 +915,31 @@
}
}
},
+ "node_modules/tree-sitter-kotlin": {
+ "version": "0.3.8",
+ "resolved": "https://registry.npmjs.org/tree-sitter-kotlin/-/tree-sitter-kotlin-0.3.8.tgz",
+ "integrity": "sha512-A4obq6bjzmYrA+F0JLLoheFPcofFkctNaZSpnDd+GPn1SfVZLY4/GG4C0cYVBTOShuPBGGAOPLM1JWLZQV4m1g==",
+ "hasInstallScript": true,
+ "license": "MIT",
+ "dependencies": {
+ "node-addon-api": "^7.1.0",
+ "node-gyp-build": "^4.8.0"
+ },
+ "peerDependencies": {
+ "tree-sitter": "^0.21.0"
+ },
+ "peerDependenciesMeta": {
+ "tree_sitter": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/tree-sitter-kotlin/node_modules/node-addon-api": {
+ "version": "7.1.1",
+ "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.1.1.tgz",
+ "integrity": "sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==",
+ "license": "MIT"
+ },
"node_modules/tree-sitter-php": {
"version": "0.23.12",
"resolved": "https://registry.npmjs.org/tree-sitter-php/-/tree-sitter-php-0.23.12.tgz",
diff --git a/package.json b/package.json
index 1dab777e..114003c5 100644
--- a/package.json
+++ b/package.json
@@ -63,6 +63,7 @@
"tree-sitter": "^0.21.1",
"tree-sitter-go": "^0.23.4",
"tree-sitter-java": "^0.23.5",
+"tree-sitter-kotlin": "^0.3.8",
"tree-sitter-php": "^0.23.4",
"tree-sitter-python": "^0.21.0",
"tree-sitter-typescript": "^0.23.2",
@@ -85,6 +86,10 @@
}
}
diff --git a/src/graph/extract.ts b/src/graph/extract.ts
index 86e162e6..84f11387 100644
--- a/src/graph/extract.ts
+++ b/src/graph/extract.ts
@@ -11,13 +11,14 @@ import TypeScript from "tree-sitter-typescript";
import Python from "tree-sitter-python";
import Go from "tree-sitter-go";
import Java from "tree-sitter-java";
+import Kotlin from "tree-sitter-kotlin";
import PHP from "tree-sitter-php";
import { basename } from "node:path";
import { contentHash } from "../util/id.js";
import { collectBindings, goReceiverVarOf, resolveRecvType, type FileBindings } from "./bindings.js";
import type { Kind, NodeV1, Relation } from "./types.js";
-export type Language = "typescript" | "tsx" | "python" | "go" | "java" | "php";
+export type Language = "typescript" | "tsx" | "python" | "go" | "java" | "kotlin" | "php";
/**
* Extension → the tree-sitter grammar that parses it, and the label a human expects
@@ -47,6 +48,8 @@ const EXTENSIONS: ReadonlyArray<{ ext: string; grammar: Language; label: string
{ ext: ".py", grammar: "python", label: "python" },
{ ext: ".go", grammar: "go", label: "go" },
{ ext: ".java", grammar: "java", label: "java" },
+ { ext: ".kt", grammar: "kotlin", label: "kotlin" },
+ { ext: ".kts", grammar: "kotlin", label: "kotlin" },
{ ext: ".php", grammar: "php", label: "php" },
];
@@ -181,6 +184,20 @@ const JAVA_KINDS: Record<string, Kind> = {
* which "class"-only logic would miss for a record's or interface's members. */
const JAVA_TYPE_KINDS: ReadonlySet<Kind> = new Set<Kind>(["class", "interface", "enum", "struct"]);
+const KOTLIN_KINDS: Record<string, Kind> = {
+ class_declaration: "class", // → "interface" / "enum" / "interface" (annotation) in describeKotlin
+ object_declaration: "class", // a singleton object is class-like (companion objects included)
+ function_declaration: "function", // → "method" inside a type (resolved in the walk)
+ secondary_constructor: "method", // the class's own secondary constructor
+ type_alias: "type",
+ property_declaration: "variable", // top-level `val`/`var` only (fields resolved in the walk)
+};
+
+/** Kotlin type declarations: they set `enclosingClass` for the members nested in them.
+ * "class" also covers object_declaration (it maps to "class"); interface/enum are the
+ * same class_declaration node rekinded in describeKotlin, so all three land in the set. */
+const KOTLIN_TYPE_KINDS: ReadonlySet<Kind> = new Set<Kind>(["class", "interface", "enum"]);
+
// PHP: definition node types are all distinct (no py-style function→method
// promotion needed — a class body uses `method_declaration`, not
// `function_definition`). `trait_declaration` maps to the PHP-only `trait` kind.
@@ -193,13 +210,13 @@ const PHP_KINDS: Record<string, Kind> = {
enum_declaration: "enum",
};
-
const KINDS_BY_LANG: Record<Language, Record<string, Kind>> = {
typescript: TS_KINDS,
tsx: TS_KINDS,
python: PY_KINDS,
go: GO_KINDS,
java: JAVA_KINDS,
+ kotlin: KOTLIN_KINDS,
php: PHP_KINDS,
};
@@ -218,6 +235,7 @@ const CALL_TYPES: Record<Language, ReadonlySet<string>> = {
python: new Set(["call"]),
go: new Set(["call_expression"]),
java: new Set(["method_invocation", "object_creation_expression"]),
+ kotlin: new Set(["call_expression"]),
php: new Set([
"function_call_expression",
"member_call_expression",
@@ -240,6 +258,7 @@ const GRAMMARS: Record<Language, unknown> = {
python: Python,
go: Go,
java: Java,
+ kotlin: Kotlin,
php: PHP.php,
};
@@ -480,6 +499,8 @@ function walk(node: Parser.SyntaxNode, ctx: WalkCtx, out: NodeV1[], edges: RawEd
? goExported(desc.name)
: ctx.lang === "java"
? javaExported(node)
+: ctx.lang === "kotlin"
+ ? kotlinExported(node)
: ctx.lang === "php"
? phpExported(node)
: tsExported(node),
@@ -498,11 +519,13 @@ function walk(node: Parser.SyntaxNode, ctx: WalkCtx, out: NodeV1[], edges: RawEd
// class heritage — in Java an interface may also `extends`, and a record/enum
// may `implements`, so every type declaration is a heritage site, not just a class.
const javaTypeDecl = ctx.lang === "java" && JAVA_TYPE_KINDS.has(desc.kind);
- if (desc.kind === "class" || javaTypeDecl) edges.push(...heritageEdges(node, id, ctx));
+ const kotlinTypeDecl = ctx.lang === "kotlin" && KOTLIN_TYPE_KINDS.has(desc.kind);
+ if (desc.kind === "class" || javaTypeDecl || kotlinTypeDecl)
+ edges.push(...heritageEdges(node, id, ctx));
if (ctx.lang === "php") edges.push(...phpAttributeReferenceEdges(node, id, ctx));
const enclosingClass =
- desc.kind === "class" || javaTypeDecl
+ desc.kind === "class" || javaTypeDecl || kotlinTypeDecl
? desc.name
: isGoMethod
? goReceiverType(node)
@@ -856,6 +879,7 @@ function isDeclarationName(node: Parser.SyntaxNode): boolean {
function describe(node: Parser.SyntaxNode, ctx: WalkCtx): DefDescriptor | null {
if (ctx.lang === "go") return describeGo(node, ctx);
if (ctx.lang === "java") return describeJava(node, ctx);
+ if (ctx.lang === "kotlin") return describeKotlin(node, ctx);
// PHP closures: `$h = function () {…}` / `fn() => …`, and bare callbacks
// (`$routes->get('/x', function () {…})`). Captured as function nodes so a
@@ -997,6 +1021,90 @@ function describeJava(node: Parser.SyntaxNode, ctx: WalkCtx): DefDescriptor | nu
return desc;
}
+/** Kotlin definition shapes. Unlike Java's, tree-sitter-kotlin exposes no `name`
+ * or `body` fields: a definition's name is an unnamed `simple_identifier` (functions)
+ * or `type_identifier` (types) child, and its body is a `class_body` / `function_body`
+ * / `statements` child. `class_declaration` also folds classes, interfaces, and enum
+ * classes into one node type — the kind is read off the declaration's own keywords. */
+function describeKotlin(node: Parser.SyntaxNode, ctx: WalkCtx): DefDescriptor | null {
+ // The first direct `type_identifier` is the declared name (type parameters, primary
+ // constructor parameters and delegation specifiers are all nested beneath it).
+ const typeName = (): string | null =>
+ node.namedChildren.find((c) => c.type === "type_identifier")?.text ?? null;
+ // The first direct `simple_identifier` is the function name (receiver type, params
+ // and type parameters are all nested beneath other child nodes).
+ const funcName = (): string | null =>
+ node.namedChildren.find((c) => c.type === "simple_identifier")?.text ?? null;
+ // `class X : A, B()` heritage lives in `delegation_specifier` children; a nested
+ // type parameter's identifier is one of the same node type, so only direct children
+ // count as the declared name.
+ const headEnd = (type: string): number => {
+ const body = node.namedChildren.find((c) => c.type === type);
+ return body ? body.startIndex : node.endIndex;
+ };
+
+ if (node.type === "class_declaration") {
+ const name = typeName();
+ if (!name) return null;
+ let kind: Kind = "class";
+ if (node.namedChildren.some((c) => c.type === "enum_class_body")) kind = "enum";
+ else if (node.children.some((c) => c.type === "interface")) kind = "interface";
+ else {
+ const mods = node.namedChildren.find((c) => c.type === "modifiers");
+ // `annotation class` → the interface role Java's annotation_type_declaration plays.
+ if (mods?.namedChildren.some((c) => c.type === "class_modifier" && c.text === "annotation"))
+ kind = "interface";
+ }
+ const body = node.namedChildren.find(
+ (c) => c.type === "class_body" || c.type === "enum_class_body",
+ );
+ return { name, kind, headerEnd: body ? body.startIndex : node.endIndex, hashNode: node };
+ }
+
+ if (node.type === "object_declaration") {
+ const name = typeName();
+ if (!name) return null;
+ return { name, kind: "class", headerEnd: headEnd("class_body"), hashNode: node };
+ }
+
+ if (node.type === "function_declaration") {
+ const name = funcName();
+ if (!name) return null;
+ const kind: Kind = KOTLIN_TYPE_KINDS.has(ctx.enclosingKind ?? "file") ? "method" : "function";
+ return { name, kind, headerEnd: headEnd("function_body"), hashNode: node };
+ }
+
+ if (node.type === "secondary_constructor") {
+ // Constructors carry no name of their own — they are the class's own, so scope the
+ // node under the enclosing class the same way Java's constructor_declaration does.
+ if (!ctx.enclosingClass) return null;
+ return {
+ name: ctx.enclosingClass,
+ kind: "method",
+ headerEnd: headEnd("statements"),
+ hashNode: node,
+ };
+ }
+
+ if (node.type === "type_alias") {
+ const name = typeName();
+ if (!name) return null;
+ return { name, kind: "type", headerEnd: node.endIndex, hashNode: node };
+ }
+
+ if (node.type === "property_declaration") {
+ // Top-level `val`/`var` only — a class property is a field, not a definition node
+ // (no depth tier emits fields), so it must not become one.
+ if (ctx.enclosingKind !== null) return null;
+ const decl = node.namedChildren.find((c) => c.type === "variable_declaration");
+ const name = decl?.namedChildren.find((c) => c.type === "simple_identifier")?.text;
+ if (!name) return null;
+ return { name, kind: "variable", headerEnd: node.endIndex, hashNode: node };
+ }
+
+ return null;
+}
+
/** Java visibility: `public` (or `protected`) on the declaration's own modifier list.
* A package-private or private member is not part of the API surface. Read off the
* `modifiers` child's tokens, ignoring annotations, which live in the same node. */
@@ -1006,6 +1114,15 @@ function javaExported(node: Parser.SyntaxNode): boolean {
return mods.children.some((c) => c.type === "public" || c.type === "protected");
}
+/** Kotlin visibility: exported by default (`public` is implicit); only an explicit
+ * `internal` / `private` / `protected` visibility modifier hides a definition. */
+function kotlinExported(node: Parser.SyntaxNode): boolean {
+ const mods = node.namedChildren.find((c) => c.type === "modifiers");
+ if (!mods) return true;
+ const vis = mods.namedChildren.find((c) => c.type === "visibility_modifier");
+ return !vis || vis.text === "public";
+}
+
/** The receiver's base type name for a Go method, unwrapping a pointer receiver
* (`func (u *User) …` → `User`). Null if it can't be read. */
function goReceiverType(node: Parser.SyntaxNode): string | null {
@@ -1079,6 +1196,20 @@ function heritageEdges(node: Parser.SyntaxNode, classId: string, ctx: WalkCtx):
}
return edges;
}
+ if (ctx.lang === "kotlin") {
+ // The `:` clause is a list of `delegation_specifier`s — a superclass construction
+ // (`class A : B()`), an interface, or `by` delegation. The first `type_identifier`
+ // under each names the type; everything else (type args, delegation target) is not
+ // the heritage target, so only the head type counts.
+ for (const child of node.namedChildren) {
+ if (child.type !== "delegation_specifier") continue;
+ const t = child.namedChildren.find((c) => c.type === "user_type")?.namedChildren.find(
+ (c) => c.type === "type_identifier",
+ );
+ if (t) edges.push({ source: classId, relation: "extends", name: t.text, file: ctx.rel });
+ }
+ return edges;
+ }
if (ctx.lang === "python") {
const supers = node.childForFieldName("superclasses"); // argument_list
for (const c of supers?.namedChildren ?? []) {
@@ -1199,6 +1330,25 @@ function calleeName(
return { name: nameNode.text, viaMember: true, receiver: javaReceiver(obj) };
}
+if (lang === "kotlin") {
+ // `call_expression` = callee expression + `call_suffix`. A bare `foo()` names a
+ // plain call; `obj.foo()` is a `navigation_expression` whose trailing
+ // `navigation_suffix` holds the method name and whose object is the receiver.
+ const target = node.namedChildren[0];
+ if (target?.type === "simple_identifier") return { name: target.text, viaMember: false };
+ if (target?.type === "navigation_expression") {
+ const suffix = target.namedChildren.find((c) => c.type === "navigation_suffix");
+ const name = suffix?.namedChildren.find((c) => c.type === "simple_identifier");
+ const receiver = target.namedChildren[0];
+ if (!name) return null;
+ if (receiver?.type === "simple_identifier")
+ return { name: name.text, viaMember: true, receiver: receiver.text };
+ if (receiver?.type === "this_expression" || receiver?.type === "super_expression")
+ return { name: name.text, viaMember: true, receiver: receiver.type === "this_expression" ? "this" : "super" };
+ }
+ return null;
+ }
+
if (lang === "php") return phpCallee(node);
const fn = node.childForFieldName("function");
@@ -1359,6 +1509,7 @@ function isImport(node: Parser.SyntaxNode, lang: Language): boolean {
// (`import ( … )`) forms each yield one edge as the walk recurses into the list.
if (lang === "go") return node.type === "import_spec";
if (lang === "java") return node.type === "import_declaration";
+if (lang === "kotlin") return node.type === "import_header";
// PHP: one edge per imported symbol — the clause leaf inside a (possibly
// grouped) `use A\B, C\D;` / `use A\{B, C};` declaration.
if (lang === "php") return node.type === "namespace_use_clause";
@@ -1391,6 +1542,12 @@ function importSpecifier(node: Parser.SyntaxNode, lang: Language): string | null
);
return id?.text ?? null;
}
+ if (lang === "kotlin") {
+ // `import com.example.Foo` — the dotted path is the `identifier` child. A
+ // wildcard (`import a.b.*`) and an `as` alias are separate children, so the
+ // identifier text is already the module path (wildcards dropped, like Java).
+ return node.namedChildren.find((c) => c.type === "identifier")?.text ?? null;
+ }
const str = node.namedChildren.find((c) => c.type === "string");
if (!str) return null;
const frag = str.namedChildren.find((c) => c.type === "string_fragment");
diff --git a/src/graph/generic.ts b/src/graph/generic.ts
index e8d7cbe5..26fec6d9 100644
--- a/src/graph/generic.ts
+++ b/src/graph/generic.ts
@@ -49,7 +49,6 @@ export const GENERIC_LANGS: readonly GenericLang[] = [
{ name: "c_sharp", exts: [".cs"], wasm: "c_sharp" },
// These ship a tags.scm (calls + symbols); ocaml/zig have none and use the
// node-kind walker fallback (symbols only) — still one row, zero query.
- { name: "kotlin", exts: [".kt", ".kts"], wasm: "kotlin" },
{ name: "scala", exts: [".scala", ".sc"], wasm: "scala" },
{ name: "swift", exts: [".swift"], wasm: "swift" },
{ name: "elixir", exts: [".ex", ".exs"], wasm: "elixir" },
diff --git a/test/graph-languages.test.ts b/test/graph-languages.test.ts
index c81d4ae1..61357dff 100644
--- a/test/graph-languages.test.ts
+++ b/test/graph-languages.test.ts
@@ -28,6 +28,7 @@ const INDEXED = [
"a.py", "a.pyi",
"a.go",
"a.java",
+"a.kt", "a.kts",
"a.php",
];
@@ -56,6 +57,8 @@ test("labels name the language, not the grammar that parses it", () => {
assert.equal(languageLabelOf("api/main.pyi"), "python");
assert.equal(languageLabelOf("cmd/main.go"), "go");
assert.equal(languageLabelOf("src/main/java/com/acme/App.java"), "java");
+assert.equal(languageLabelOf("src/main/kotlin/com/acme/App.kt"), "kotlin");
+ assert.equal(languageLabelOf("scripts/main.kts"), "kotlin");
assert.equal(languageLabelOf("app/Models/User.php"), "php");
// The grammar is unchanged — extraction, the extract cache and every `Language`
@@ -79,9 +82,10 @@ test("the build banner and repo map report every language they indexed", async (
writeFileSync(join(d, "scripts", "tool.mjs"), "export function mjsOnlySymbol() {\n return 1;\n}\n");
writeFileSync(join(d, "scripts", "web.jsx"), "export function JsxOnly() {\n return null;\n}\n");
writeFileSync(join(d, "src", "c.py"), "def py_only():\n return 1\n");
+ writeFileSync(join(d, "src", "a.kt"), "fun ktOnly(): Int {\n return 1\n}\n");
const r = await buildGraph(d);
- assert.deepEqual(r.languages, ["javascript", "jsx", "python", "tsx", "typescript"]);
+ assert.deepEqual(r.languages, ["javascript", "jsx", "kotlin", "python", "tsx", "typescript"]);
// The reported symbol was queryable all along — that mismatch is what the issue was
// about, so pin both halves together.
diff --git a/test/supported-extensions.test.ts b/test/supported-extensions.test.ts
index 01ca401f..8ce9a8dd 100644
--- a/test/supported-extensions.test.ts
+++ b/test/supported-extensions.test.ts
@@ -16,9 +16,9 @@ import { supportedExtensions, unsupportedExtensions } from "../src/graph/source-
test("supportedExtensions covers both tiers, sorted and de-duped", () => {
const exts = supportedExtensions();
// depth tier
- for (const e of [".ts", ".tsx", ".py", ".go", ".java", ".js", ".php"]) assert.ok(exts.includes(e), `depth ${e}`);
+ for (const e of [".ts", ".tsx", ".py", ".go", ".java", ".js", ".php", ".kt", ".kts"]) assert.ok(exts.includes(e), `depth ${e}`);
// breadth tier
- for (const e of [".rs", ".rb", ".c", ".cpp", ".kt", ".swift"]) assert.ok(exts.includes(e), `breadth ${e}`);
+ for (const e of [".rs", ".rb", ".c", ".cpp", ".swift"]) assert.ok(exts.includes(e), `breadth ${e}`);
// container tier
assert.ok(exts.includes(".vue"), "container .vue");
// de-duped (.java is in BOTH tiers but must appear once) and sorted