java-codebase-rag 0.11.2__py3-none-any.whl → 0.12.0__py3-none-any.whl

java_codebase_rag/graph/build_ast_graph.py

@@ -50,8 +50,24 @@ from java_codebase_rag.ast.ast_java import (
     TypeDecl,
     injection_annotation_names,
     lombok_required_args_annotations,
-    parse_java,
 )
+from java_codebase_rag.ast.language import backend_for
+
+# Kotlin multifile-facade merge (Task 9). Conditionally imported: on installs
+# without the ``tree-sitter-kotlin`` grammar wheel (Intel-Mac graph-only image),
+# ``ast_kotlin`` raises ImportError at module load. ``merge_multifile_facades``
+# is a no-op on Java ASTs (they have no facades), so absent grammar → merge is
+# skipped and Java indexing is byte-identical. Used in pass1 AFTER parsing all
+# files but BEFORE ``_register_type`` (unmerged ``@file:JvmMultifileClass``
+# facades share one FQN → ``tables.types[fqn] = entry`` would overwrite and one
+# file's top-level functions would silently vanish from resolution).
+try:  # pragma: no cover - branch depends on whether the wheel is installed
+    from java_codebase_rag.ast.ast_kotlin import (
+        merge_multifile_facades as _merge_multifile_facades,
+    )
+except ImportError:  # grammar wheel absent — no .kt files to merge.
+    _merge_multifile_facades = None  # type: ignore[assignment]
+
 from java_codebase_rag.graph.graph_enrich import (
     _load_config_cross_service_resolution,
     classify_java_file,
@@ -67,7 +83,7 @@ from java_codebase_rag.graph.graph_enrich import (
     resolve_routes_for_method,
     symbol_id,
 )
-from java_codebase_rag.graph.path_filtering import LayeredIgnore, iter_java_source_files
+from java_codebase_rag.graph.path_filtering import LayeredIgnore, iter_source_files
 from java_codebase_rag.search.search_scoring import SYMBOL_FTS_INDEX as _SYMBOL_FTS_INDEX, _split_identifier
 from java_codebase_rag.graph.java_ontology import (
     CLIENT_KIND_FEIGN_METHOD,
@@ -184,6 +200,60 @@ _JAVA_LANG_SIMPLE = frozenset({
 })
 
 
+# Kotlin default-import simple names → deterministic stdlib FQN (Task 13).
+# Kotlin implicitly imports kotlin.*, kotlin.collections.*, kotlin.sequences.*,
+# kotlin.ranges.*, kotlin.text.*, kotlin.comparisons.*, kotlin.annotation.*,
+# kotlin.reflect.*, kotlin.jvm.*, kotlin.io.*, kotlin.math.*, kotlin.contracts.*.
+# Types from these (e.g. ``List``, ``Map``, ``Sequence``, ``Pair``) referenced as
+# supertypes would otherwise collapse to bare-name phantoms (``fqn="List"``). This
+# map gives the phantom fallback a deterministic FQN, mirroring ``_JAVA_LANG_SIMPLE``
+# for Java. Consulted ONLY when ``ast.language == "kotlin"`` (Kotlin-gated), so the
+# Java resolution path is byte-identical. Curated to the commonly-referenced stdlib
+# types; unknown simples keep falling through to the bare-name guess.
+_KOTLIN_DEFAULT_SIMPLE: dict[str, str] = {
+    # kotlin.*
+    "Any": "kotlin.Any", "Unit": "kotlin.Unit", "Nothing": "kotlin.Nothing",
+    "Int": "kotlin.Int", "Long": "kotlin.Long", "Short": "kotlin.Short",
+    "Byte": "kotlin.Byte", "Double": "kotlin.Double", "Float": "kotlin.Float",
+    "Boolean": "kotlin.Boolean", "Char": "kotlin.Char", "String": "kotlin.String",
+    "Array": "kotlin.Array", "Pair": "kotlin.Pair", "Triple": "kotlin.Triple",
+    "Result": "kotlin.Result", "Enum": "kotlin.Enum", "Annotation": "kotlin.Annotation",
+    "Throwable": "kotlin.Throwable", "Exception": "kotlin.Exception",
+    "Error": "kotlin.Error", "Lazy": "kotlin.Lazy",
+    # kotlin.collections.*
+    "List": "kotlin.collections.List", "MutableList": "kotlin.collections.MutableList",
+    "Set": "kotlin.collections.Set", "MutableSet": "kotlin.collections.MutableSet",
+    "Map": "kotlin.collections.Map", "MutableMap": "kotlin.collections.MutableMap",
+    "Collection": "kotlin.collections.Collection",
+    "MutableCollection": "kotlin.collections.MutableCollection",
+    "Iterable": "kotlin.collections.Iterable",
+    "MutableIterable": "kotlin.collections.MutableIterable",
+    "ArrayList": "kotlin.collections.ArrayList", "HashMap": "kotlin.collections.HashMap",
+    "HashSet": "kotlin.collections.HashSet",
+    "LinkedHashMap": "kotlin.collections.LinkedHashMap",
+    "LinkedHashSet": "kotlin.collections.LinkedHashSet",
+    "Grouping": "kotlin.collections.Grouping",
+    "Iterator": "kotlin.collections.Iterator",
+    "MutableIterator": "kotlin.collections.MutableIterator",
+    "ListIterator": "kotlin.collections.ListIterator",
+    "MutableListIterator": "kotlin.collections.MutableListIterator",
+    "Comparator": "kotlin.Comparator",
+    # kotlin.sequences.*
+    "Sequence": "kotlin.sequences.Sequence",
+    # kotlin.ranges.*
+    "IntRange": "kotlin.ranges.IntRange", "LongRange": "kotlin.ranges.LongRange",
+    "CharRange": "kotlin.ranges.CharRange", "ClosedRange": "kotlin.ranges.ClosedRange",
+    "OpenEndRange": "kotlin.ranges.OpenEndRange",
+    # kotlin.text.*
+    "Regex": "kotlin.text.Regex", "Appendable": "kotlin.text.Appendable",
+    "MatchResult": "kotlin.text.MatchResult",
+    # kotlin.reflect.*
+    "KClass": "kotlin.reflect.KClass", "KCallable": "kotlin.reflect.KCallable",
+    "KProperty": "kotlin.reflect.KProperty", "KFunction": "kotlin.reflect.KFunction",
+    "KType": "kotlin.reflect.KType", "KParameter": "kotlin.reflect.KParameter",
+}
+
+
 # ---------- dataclasses ----------
 
 
@@ -470,6 +540,10 @@ class GraphTables:
     type_role_by_node_id: dict[str, str] = field(default_factory=dict)
     # Populated in pass 1 (classify_java_file) and _load_existing_types for incremental rebuilds.
     type_generated_by_node_id: dict[str, tuple[bool, str | None]] = field(default_factory=dict)
+    # Per-build dedup for the same-FQN cross-file collision warning in
+    # ``_register_type`` (one warning per colliding FQN per build — avoids
+    # spam when >2 files claim one FQN). See ``_register_type``.
+    _warned_fqn_collisions: set[str] = field(default_factory=set)
 
 
 @dataclass
@@ -532,7 +606,7 @@ class FileHashTracker:
         current_files: set[str] = set()
         # Resolve source_root to handle symlinks
         source_root_resolved = source_root.resolve()
-        for abs_path in iter_java_source_files(source_root, ignore=ignore):
+        for abs_path in iter_source_files(source_root, ignore=ignore):
             # Resolve the absolute path and compute relative path
             abs_path_resolved = abs_path.resolve()
             try:
@@ -929,7 +1003,7 @@ def _write_nodes_merge(
     _write_nodes_impl(conn, tables, project_root=project_root, meta_chain=meta_chain)
 
 
-# ---------- file walk (see `path_filtering.iter_java_source_files`) ----------
+# ---------- file walk (see `path_filtering.iter_source_files`) ----------
 
 
 # ---------- pass 1 ----------
@@ -967,6 +1041,24 @@ def _register_type(
         outer_fqn=outer_fqn,
         node_id=node_id,
     )
+    # Warn on a same-FQN collision across DISTINCT files (the Kotlin+Java
+    # mixed-repo case, e.g. ``com.example.Foo`` in both ``Foo.java`` and
+    # ``Foo.kt``). Registration stays last-wins (silent before Task 16); this
+    # only surfaces the collision. Deduped per FQN per build so a pathological
+    # N-way collision warns once, not N-1 times. A same-file re-register
+    # (incremental re-parse) does not warn.
+    existing = tables.types.get(decl.fqn)
+    if (
+        existing is not None
+        and existing.file_path != file_path
+        and decl.fqn not in tables._warned_fqn_collisions
+    ):
+        tables._warned_fqn_collisions.add(decl.fqn)
+        log.warning(
+            "same-FQN type registered from two distinct files (last wins): "
+            "%s in %s and %s",
+            decl.fqn, existing.file_path, file_path,
+        )
     tables.types[decl.fqn] = entry
     tables.by_simple_name.setdefault(decl.name, []).append(entry)
     tables.by_package.setdefault(package, []).append(entry)
@@ -1028,7 +1120,7 @@ def pass1_parse(
             removed = removed_files if removed_files is not None else set()
             pass1_total = len(scope_files - removed)
         else:
-            pass1_total = sum(1 for _ in iter_java_source_files(root, ignore=ignore))
+            pass1_total = sum(1 for _ in iter_source_files(root, ignore=ignore))
         _emit_graph_progress(
             {"pass": "1/6", "done": 0, "total": pass1_total, "status": "running"},
             verbose=verbose,
@@ -1043,7 +1135,11 @@ def pass1_parse(
     with _VerbosePassHeartbeats("[graph] pass 1", verbose=verbose):
         if verbose and slow_sec > 0:
             time.sleep(slow_sec)
-        for p in iter_java_source_files(root, ignore=ignore):
+        # Per-file generated classification, carried through to the registration
+        # loop below (registration is deferred until after the multifile-facade
+        # merge so merged facades win their FQN slot in tables.types).
+        file_meta: dict[str, tuple[str, str, bool, str | None]] = {}
+        for p in iter_source_files(root, ignore=ignore):
             # Skip files not in scope (if scope is provided)
             try:
                 rel = p.resolve().relative_to(root.resolve()).as_posix()
@@ -1064,8 +1160,11 @@ def pass1_parse(
                 continue
             if not content.strip():
                 continue
+            backend = backend_for(rel)
+            if backend is None:
+                continue
             try:
-                ast = parse_java(content, filename=rel, verbose=verbose)
+                ast = backend.parse(content, filename=rel, verbose=verbose)
             except Exception:
                 tables.parse_errors += 1
                 continue
@@ -1081,6 +1180,7 @@ def pass1_parse(
             file_generated, file_generated_by = classify_java_file(
                 content, ast, config=generated_config, project_root=root
             )
+            file_meta[rel] = (module, microservice, file_generated, file_generated_by)
 
             # file node
             file_id = symbol_id("file", rel, rel, 0)
@@ -1090,6 +1190,24 @@ def pass1_parse(
             if ast.package and ast.package not in tables.packages:
                 tables.packages[ast.package] = symbol_id("package", ast.package, "", 0)
 
+        # Merge Kotlin ``@file:JvmMultifileClass`` facades BEFORE type
+        # registration (Task 9 / Task 11). Multiple ``.kt`` files sharing
+        # ``@file:JvmName("X")`` + ``@file:JvmMultifileClass()`` compile into ONE
+        # JVM class ``pkg.X``; the per-file parse emits one facade per file, all
+        # with FQN ``pkg.X``, so registering them per-file would collide in
+        # ``tables.types[fqn]`` (last-write-wins) and silently drop every other
+        # file's top-level functions from resolution. The merge concatenates the
+        # members onto ONE retained facade and strips the duplicates. It is a
+        # no-op on Java ASTs (no facades) and on single-file modules, so Java
+        # registration output is byte-identical (same files, same walk order).
+        if _merge_multifile_facades is not None and asts:
+            _merge_multifile_facades(list(asts.values()))
+
+        # Register types AFTER the merge so a merged facade wins its FQN slot.
+        # Iteration order is the dict's insertion order = walk order, identical
+        # to the former per-file registration, so Java output is unchanged.
+        for rel, ast in asts.items():
+            module, microservice, file_generated, file_generated_by = file_meta[rel]
             for t in ast.top_level_types:
                 _register_type(
                     tables, t, file_path=rel,
@@ -1188,6 +1306,10 @@ def _phantom_target(
         guess_fqn = ast.explicit_imports[bare]
     elif bare in _JAVA_LANG_SIMPLE:
         guess_fqn = f"java.lang.{bare}"
+    elif ast.language == "kotlin" and bare in _KOTLIN_DEFAULT_SIMPLE:
+        # Kotlin default-import stdlib type (kotlin.collections.List etc.) —
+        # Kotlin-gated so Java resolution is byte-identical. See Task 13.
+        guess_fqn = _KOTLIN_DEFAULT_SIMPLE[bare]
     elif ast.wildcard_imports:
         # Pick first wildcard as a hint (imperfect but useful for display).
         guess_fqn = f"{ast.wildcard_imports[0]}.{bare}"
@@ -4170,7 +4292,7 @@ def _init_hash_tracker(source_root: Path, ladybug_path: Path) -> int:
     ignore = LayeredIgnore(source_root)
     all_files: set[str] = set()
     source_root_resolved = source_root.resolve()
-    for p in iter_java_source_files(source_root, ignore=ignore):
+    for p in iter_source_files(source_root, ignore=ignore):
         p_resolved = p.resolve()
         try:
             rel_path = p_resolved.relative_to(source_root_resolved).as_posix()

java_codebase_rag/graph/graph_enrich.py

@@ -38,11 +38,11 @@ from java_codebase_rag.ast.ast_java import (
     CODEBASE_PRODUCER_ANNOTATIONS,
     infer_capabilities_for_type,
     infer_role_for_type,
-    parse_java,
     ROLE_ANNOTATIONS,
     _METHOD_ANN_TO_CAPABILITY,
     _TYPE_ANN_TO_CAPABILITY,
 )
+from java_codebase_rag.ast.language import backend_for
 from java_codebase_rag.graph.java_ontology import (
     CLIENT_KIND_REST_TEMPLATE,
     VALID_CAPABILITIES,
@@ -52,7 +52,7 @@ from java_codebase_rag.graph.java_ontology import (
     VALID_ROUTE_FRAMEWORKS,
     VALID_ROUTE_KINDS,
 )
-from java_codebase_rag.graph.path_filtering import LayeredIgnore, iter_java_source_files
+from java_codebase_rag.graph.path_filtering import LayeredIgnore, iter_source_files
 
 __all__ = [
     "AnnotationDecl",
@@ -387,7 +387,7 @@ def _collect_annotation_decl_index(project_root_str: str) -> dict[str, Annotatio
         return {}
     ignore = LayeredIgnore(root)
     decls: dict[str, AnnotationDecl] = {}
-    for p in sorted(iter_java_source_files(root, ignore=ignore), key=str):
+    for p in sorted(iter_source_files(root, ignore=ignore), key=str):
         try:
             content = p.read_bytes()
         except OSError as exc:
@@ -398,8 +398,11 @@ def _collect_annotation_decl_index(project_root_str: str) -> dict[str, Annotatio
             continue
         if not content.strip():
             continue
+        backend = backend_for(p)
+        if backend is None:
+            continue
         try:
-            jast = parse_java(content)
+            jast = backend.parse(content, filename=str(p))
         except Exception as exc:
             print(
                 f"[lancedb-mcp] parse error in {p}: {exc}",
@@ -1728,7 +1731,7 @@ def classify_java_file(
 
     Args:
         source: Raw file bytes (required for header-banner detection).
-        ast: Parsed Java AST (from ast_java.parse_java_ast).
+        ast: Parsed Java AST (from ast_java.parse_java).
         config: Optional detection config (defaults to empty config).
         project_root: Optional project root for loading default config.
 

java_codebase_rag/graph/ladybug_queries.py

@@ -380,7 +380,7 @@ class LadybugGraph:
                         f"Graph ontology version {graph_version} is older than the "
                         f"required version {_ONTOLOGY_VERSION}. "
                         "Rebuild the graph: `python build_ast_graph.py --source-root <repo>`, "
-                        "or run `java-codebase-rag reprocess --source-root <repo>` for a full "
+                        "or run `jrag reprocess --source-root <repo>` for a full "
                         "Lance+Ladybug re-index."
                     )
                 cls._instance = instance

java_codebase_rag/graph/path_filtering.py

@@ -23,6 +23,8 @@ from typing import overload
 
 from pathspec import GitIgnoreSpec
 
+from java_codebase_rag.ast.language import LANG_BACKENDS
+
 # Pruning for LocalFile sources: skip VCS, build outputs, dependency trees, and
 # test sources (we currently index prod Java only to keep the semantic index clean).
 # Also avoids EMFILE under default ulimits when the engine traverses in parallel.
@@ -427,26 +429,33 @@ class LayeredIgnore:
 
 
 @overload
-def iter_java_source_files(root: Path, exclude_globs: list[str]) -> Iterator[Path]: ...
+def iter_source_files(root: Path, exclude_globs: list[str]) -> Iterator[Path]: ...
 
 
 @overload
-def iter_java_source_files(root: Path, *, ignore: LayeredIgnore) -> Iterator[Path]: ...
+def iter_source_files(root: Path, *, ignore: LayeredIgnore) -> Iterator[Path]: ...
 
 
-def iter_java_source_files(
+def iter_source_files(
     root: Path,
     exclude_globs: list[str] | None = None,
     *,
     ignore: LayeredIgnore | None = None,
 ) -> Iterator[Path]:
-    """Walk ``root`` for ``*.java``, honouring prunes and layered ignore rules."""
+    """Walk ``root`` for source files of any registered language backend.
+
+    Yields files whose suffix is claimed by at least one backend in
+    :data:`~java_codebase_rag.ast.language.LANG_BACKENDS` (``.java`` always;
+    ``.kt`` when the ``tree-sitter-kotlin`` grammar imports). Pruning
+    (``UNCONDITIONAL_PRUNE_DIRS`` + ``_is_build_output_dir``) and the layered
+    ignore rules are unchanged from the former Java-only walk.
+    """
     if exclude_globs is not None and ignore is not None:
         raise TypeError("pass either exclude_globs or ignore=, not both")
     if exclude_globs is not None:
         warnings.warn(
-            "iter_java_source_files(root, exclude_globs) is deprecated; "
-            "use iter_java_source_files(root, ignore=LayeredIgnore(root, ...)).",
+            "iter_source_files(root, exclude_globs) is deprecated; "
+            "use iter_source_files(root, ignore=LayeredIgnore(root, ...)).",
             DeprecationWarning,
             stacklevel=2,
         )
@@ -455,6 +464,11 @@ def iter_java_source_files(
         ignore_ctx = ignore
     else:
         ignore_ctx = LayeredIgnore(root)
+    # Union of suffixes claimed by every registered backend (``.java`` always;
+    # ``.kt`` when the Kotlin grammar imports). Computed once per call.
+    known_suffixes: set[str] = set()
+    for backend in LANG_BACKENDS.values():
+        known_suffixes.update(backend.suffixes)
     root = root.resolve()
     for dirpath, dirnames, filenames in os.walk(root):
         # Universal nuisance dirs (VCS, IDE, deps) are pruned unconditionally.
@@ -469,9 +483,27 @@ def iter_java_source_files(
             and not _is_build_output_dir(dirpath, d)
         ]
         for fn in filenames:
-            if not fn.endswith(".java"):
+            # Literal byte-identity match (mirrors the legacy ``endswith``
+            # behaviour): ``Path(".java").suffix`` is ``""``, so a dotfile named
+            # ``.java`` would be dropped by a suffix-in-set check. ``endswith``
+            # over the registered suffixes restores the exact old semantics.
+            if not any(fn.endswith(s) for s in known_suffixes):
                 continue
             p = Path(dirpath) / fn
             if ignore_ctx.is_ignored(p):
                 continue
             yield p
+
+
+def iter_java_source_files(
+    root: Path,
+    exclude_globs: list[str] | None = None,
+    *,
+    ignore: LayeredIgnore | None = None,
+) -> Iterator[Path]:
+    """Deprecated alias for :func:`iter_source_files`.
+
+    Kept so any import site not migrated to the new name continues to work; new
+    call sites should use :func:`iter_source_files`.
+    """
+    return iter_source_files(root, exclude_globs, ignore=ignore)

java_codebase_rag/index/java_index_flow_lancedb.py

@@ -6,7 +6,7 @@ LanceDB requires a single primary key per table; each chunk gets a UUID `id`.
 Environment:
   JAVA_CODEBASE_RAG_INDEX_DIR — Lance tables + LadybugDB + cocoindex state (default: ./.java-codebase-rag)
   JAVA_CODEBASE_RAG_SOURCE_ROOT — Java repo root for indexing (optional; else cocoindex cwd)
-  SBERT_MODEL / SBERT_DEVICE — embedding (optional; YAML also supported via java-codebase-rag CLI)
+  SBERT_MODEL / SBERT_DEVICE — embedding (optional; YAML also supported via jrag CLI)
 
 Dependencies:
   pip install "cocoindex[lancedb]" sentence-transformers
@@ -50,7 +50,8 @@ from java_codebase_rag.index.java_index_v1_common import (
     position_to_json,
 )
 from java_codebase_rag.graph.path_filtering import LayeredIgnore
-from java_codebase_rag.ast.ast_java import ONTOLOGY_VERSION, parse_java
+from java_codebase_rag.ast.ast_java import ONTOLOGY_VERSION
+from java_codebase_rag.ast.language import LANG_BACKENDS, backend_for
 from java_codebase_rag.graph.graph_enrich import (
     classify_java_file,
     collect_annotation_meta_chain,
@@ -115,6 +116,21 @@ splitter = RecursiveSplitter()
 # parent clamps to total on the terminal event anyway).
 _VECTORS_TICK_EVERY = 25
 
+# Suffixes that index into the ``JavaLanceChunk`` table — the registered
+# language backends (``.java`` always; ``.kt`` when the Kotlin grammar imports).
+# Derived from ``LANG_BACKENDS`` so this never drifts from what the graph builder
+# parses (mirrors the watcher's ``INDEXED_SUFFIXES``). On a grammar-absent
+# install this is just ``(".java",)`` and ``.kt`` files are skipped cleanly.
+_INDEXED_SOURCE_SUFFIXES: tuple[str, ...] = tuple(
+    suffix for backend in LANG_BACKENDS.values() for suffix in backend.suffixes
+)
+# True iff some registered backend claims ``.kt`` (i.e. ``tree-sitter-kotlin``
+# imported). Gates the ``.kt`` cocoindex matcher + ``process_kotlin_file`` drain
+# in ``app_main`` so a grammar-absent install skips ``.kt`` by construction
+# instead of crashing inside ``_parse_and_enrich_java`` (backend-for-``.kt``
+# returns ``None`` → ``classify_java_file`` dereferences ``ast.all_types``).
+_KOTLIN_REGISTERED: bool = ".kt" in _INDEXED_SOURCE_SUFFIXES
+
 # Bounded concurrency for the per-file drain in app_main. cocoindex's embedder
 # is ``@coco.fn.as_async(batching=True, runner=GPU, max_batch_size=64)`` — but
 # its batching layer only coalesces calls that are in flight SIMULTANEOUSLY. A
@@ -129,9 +145,9 @@ _VECTORS_TICK_EVERY = 25
 # This stays inside ONE component, so the earlier mount_each→app_main win is
 # preserved: still exactly ONE merge_insert per table at commit. Memoization
 # (``@coco.fn(memo=True)``) and the lock-guarded tick counter are safe under
-# concurrency; ``parse_java`` uses a per-thread tree-sitter Parser (already
-# routed via ``asyncio.to_thread``) and ``splitter.split`` is synchronous so the
-# event loop cannot reenter it.
+# concurrency; the backend parse (``parse_java`` / ``parse_kotlin``) uses a
+# per-thread tree-sitter Parser (already routed via ``asyncio.to_thread``)
+# and ``splitter.split`` is synchronous so the event loop cannot reenter it.
 #
 # Default 64 is sized to MATCH the embedder's hardcoded max_batch_size=64 (the
 # decorator above; not a constructor arg, so not raisable from the flow): ~64
@@ -209,8 +225,8 @@ def _approximate_vectors_total(project_root: Path) -> int:
     count. The parent clamps the bar to 100% on the terminal ``status=done``
     event, so the over-count cannot stall the bar.
 
-    Mirrors the three ``localfs.walk_dir`` matchers in ``app_main``:
-      - ``**/*.java``
+    Mirrors the ``localfs.walk_dir`` matchers in ``app_main``:
+      - ``**/*.java`` and ``**/*.kt`` (registered language suffixes)
       - ``**/src/main/resources/db/migration/*.sql``
       - ``**/src/main/resources/application*.yml`` and ``.yaml``
     """
@@ -222,7 +238,7 @@ def _approximate_vectors_total(project_root: Path) -> int:
 
     total = 0
     for dirpath, dirnames, filenames in os.walk(project_root):
-        # Prune the same universal nuisance dirs as iter_java_source_files /
+        # Prune the same universal nuisance dirs as iter_source_files /
         # cocoindex walk. (build-output pruning is matcher-dependent in the
         # real walk; for an APPROXIMATE total this cheap prune is sufficient
         # — the clamp absorbs any residual divergence.)
@@ -237,8 +253,12 @@ def _approximate_vectors_total(project_root: Path) -> int:
                 continue
             if _excluded(rel):
                 continue
-            # Java: **/*.java
-            if fn.endswith(".java"):
+            # Java + Kotlin: the registered source-language suffixes (see
+            # ``_INDEXED_SOURCE_SUFFIXES`` / ``LANG_BACKENDS`` — ``.java`` always,
+            # ``.kt`` when the Kotlin grammar imports). Both index into the same
+            # ``JavaLanceChunk`` table via ``process_java_file`` /
+            # ``process_kotlin_file``.
+            if fn.endswith(_INDEXED_SOURCE_SUFFIXES):
                 if not ignore.is_ignored(full):
                     total += 1
                 continue
@@ -380,14 +400,23 @@ def _parse_and_enrich_java(
     parses + enriches, the event loop is free to drive other files and keep the
     embedder's batching queue fed.
 
-    Thread-safety: ``parse_java`` uses a per-thread tree-sitter ``Parser``
-    (see ``ast_java._parser``), so it is safe to call concurrently from these
-    worker threads — including the transitive ``parse_java`` that ``enrich_chunk``
+    Thread-safety: the backend parse (``parse_java`` / ``parse_kotlin``) uses
+    a per-thread tree-sitter ``Parser`` (see ``ast_java._parser`` /
+    ``ast_kotlin._parser``), so it is safe to call concurrently from these
+    worker threads — including the transitive re-parse that ``enrich_chunk``
     triggers via ``collect_annotation_meta_chain`` → ``_collect_annotation_decl_index``.
     ``enrich_chunk`` is otherwise pure-Python over the now-immutable AST; its
     ``lru_cache`` reads are thread-safe under the GIL.
     """
-    ast = parse_java(content_bytes)
+    backend = backend_for(rel)
+    if backend is None:
+        # Defensive: ``app_main`` registers the ``.kt`` matcher + kotlin drain
+        # only when ``_KOTLIN_REGISTERED`` (registry-derived), and ``.java`` is
+        # always registered — so by construction this is unreachable for every
+        # suffix the flow yields. Kept to honor the dispatch contract (a
+        # grammar-absent install never yields ``.kt`` here).
+        return [], None
+    ast = backend.parse(content_bytes, filename=rel)
     enrichments = [
         enrich_chunk(
             ast,
@@ -437,7 +466,8 @@ async def process_java_file(
 
     # (vectors perf lever #2) parse + enrich off the event loop so the loop can
     # keep the embedder's batching queue fed while this file is being parsed.
-    # parse_java is thread-safe (per-thread tree-sitter Parser in ast_java).
+    # The backend parse (parse_java / parse_kotlin) is thread-safe (per-thread
+    # tree-sitter Parser in ast_java / ast_kotlin).
     enrichments, ast = await asyncio.to_thread(
         _parse_and_enrich_java, content_bytes, chunks, rel, project_root
     )
@@ -483,6 +513,98 @@ async def process_java_file(
         )
 
 
+@coco.fn(memo=True)
+async def process_kotlin_file(
+    file: localfs.File,
+    table: lancedb.TableTarget[JavaLanceChunk],
+) -> None:
+    """Index one ``.kt`` file into the SAME ``JavaLanceChunk`` table as Java.
+
+    Mirrors ``process_java_file``'s enrichment path (``enrich_chunk`` /
+    ``classify_java_file``) but parsing dispatches through ``backend_for(rel)``
+    (= ``parse_kotlin``) inside the shared ``_parse_and_enrich_java`` helper,
+    which is already language-agnostic. The chunk ``language`` field is set to
+    ``"kotlin"`` (``detect_code_language`` returns ``"kotlin"`` for ``.kt``).
+    The chunk schema (``primary_type_kind`` / ``role`` / ``capabilities``) is
+    language-agnostic, so no new column is needed.
+
+    Multifile-facade merge is NOT wired here: each ``process_*_file`` parses ONE
+    file independently (concurrent per-file drain), so a cross-file pre-pass is
+    awkward inside cocoindex's dataflow. The merge runs in ``build_ast_graph``
+    pass1 instead — the only site that registers facade TypeDecls into
+    ``tables.types`` (where unmerged facades would collide). Chunk enrichment
+    (``enrich_chunk``) uses the per-file AST only, so it is merge-independent.
+    """
+    embedder = coco.use_context(EMBEDDER)
+    project_root = coco.use_context(PROJECT_ROOT)
+    ignore = coco.use_context(IGNORE)
+    if ignore.is_ignored((project_root / file.file_path.path).resolve()):
+        return
+    try:
+        content = await file.read_text()
+    except UnicodeDecodeError:
+        return
+    if not content.strip():
+        return
+
+    _tick_vectors_done()
+
+    language = detect_code_language(filename=file.file_path.path.name) or "text"
+    cs, mn, ov = JAVA_CHUNK
+    chunks = splitter.split(
+        content,
+        cs,
+        min_chunk_size=mn,
+        chunk_overlap=ov,
+        language=language,
+    )
+    rel = file.file_path.path.as_posix()
+    content_bytes = content.encode("utf-8", errors="replace")
+
+    # ``_parse_and_enrich_java`` dispatches via ``backend_for(rel)`` → parse_kotlin
+    # for ``.kt``; the helper and ``enrich_chunk`` are language-agnostic. Run off
+    # the event loop so the embedder batching queue stays fed (vectors perf #2).
+    enrichments, ast = await asyncio.to_thread(
+        _parse_and_enrich_java, content_bytes, chunks, rel, project_root
+    )
+
+    generated_config = load_generated_detection(project_root)
+    generated, generated_by = classify_java_file(
+        content_bytes, ast, config=generated_config, project_root=project_root
+    )
+
+    # Embed all chunks concurrently → batched encode (vectors perf #1).
+    embeddings = await asyncio.gather(*(embedder.embed(ch.text) for ch in chunks))
+
+    for ch, enrich, emb in zip(chunks, enrichments, embeddings):
+        rs, re = chunk_key_range(ch)
+        table.declare_row(
+            row=JavaLanceChunk(
+                id=str(uuid.uuid4()),
+                filename=rel,
+                language=language,
+                text=ch.text,
+                range_start=rs,
+                range_end=re,
+                start=position_to_json(ch.start),
+                end=position_to_json(ch.end),
+                embedding=emb,
+                package=enrich.package,
+                module=enrich.module,
+                microservice=enrich.microservice,
+                primary_type_fqn=enrich.primary_type_fqn,
+                primary_type_kind=enrich.primary_type_kind,
+                role=enrich.role,
+                capabilities=list(enrich.capabilities),
+                annotations_on_type=enrich.annotations_on_type,
+                symbols=enrich.symbols,
+                ontology_version=ONTOLOGY_VERSION,
+                generated=generated,
+                generated_by=generated_by,
+            )
+        )
+
+
 @coco.fn(memo=True)
 async def process_sql_file(
     file: localfs.File,
@@ -682,6 +804,18 @@ async def app_main() -> None:
             excluded_patterns=_walk_excludes,
         ),
     )
+    kotlin_files = (
+        localfs.walk_dir(
+            PROJECT_ROOT,
+            recursive=True,
+            path_matcher=PatternFilePathMatcher(
+                included_patterns=["**/*.kt"],
+                excluded_patterns=_walk_excludes,
+            ),
+        )
+        if _KOTLIN_REGISTERED
+        else None
+    )
     sql_files = localfs.walk_dir(
         PROJECT_ROOT,
         recursive=True,
@@ -724,6 +858,17 @@ async def app_main() -> None:
     # usually near-empty).
     _sem = asyncio.Semaphore(_FILE_CONCURRENCY)
     await _drain_files_concurrently(java_files, process_java_file, java_table, _sem)
+    # Kotlin drains into the SAME ``java_table`` (JavaLanceChunk) — the chunk
+    # schema is language-agnostic and the ``language`` column distinguishes rows.
+    # Gated on ``_KOTLIN_REGISTERED`` (registry-derived): on a grammar-absent
+    # install ``.kt`` has no backend, so the matcher + drain are skipped entirely
+    # — no wasted read/chunk/embed, and no crash in ``_parse_and_enrich_java``
+    # (``backend_for(.kt)`` returns ``None`` → ``classify_java_file`` would
+    # dereference ``ast.all_types`` on ``None``).
+    if _KOTLIN_REGISTERED:
+        await _drain_files_concurrently(
+            kotlin_files, process_kotlin_file, java_table, _sem
+        )
     await _drain_files_concurrently(sql_files, process_sql_file, sql_table, _sem)
     await _drain_files_concurrently(yaml_files, process_yaml_file, yaml_table, _sem)