refactor: move to src/ layout, organize package + tests into layer folders

pyproject.toml

@@ -64,36 +64,11 @@ Issues = "https://github.com/HumanBean17/java-codebase-rag/issues"
 
 [project.scripts]
 java-codebase-rag = "java_codebase_rag.cli:_console_script_main"
-java-codebase-rag-mcp = "server:main"
+java-codebase-rag-mcp = "java_codebase_rag.mcp.server:main"
 jrag = "java_codebase_rag.jrag:_console_script_main"
 
-[tool.setuptools]
-packages = ["java_codebase_rag"]
-py-modules = [
-    "absence_types",
-    "absence_vocab",
-    "absence_diagnosis",
-    "ast_java",
-    "brownfield_events",
-    "build_ast_graph",
-    "chunk_heuristics",
-    "graph_enrich",
-    "graph_types",
-    "index_common",
-    "java_index_flow_lancedb",
-    "java_index_v1_common",
-    "java_ontology",
-    "ladybug_queries",
-    "mcp_hints",
-    "mcp_v2",
-    "path_filtering",
-    "pr_analysis",
-    "resolve_service",
-    "search_lancedb",
-    "search_lexical",
-    "search_scoring",
-    "server",
-]
+[tool.setuptools.packages.find]
+where = ["src"]
 
 [tool.ruff]
 line-length = 100

pytest.ini

@@ -1,3 +1,4 @@
 [pytest]
 asyncio_mode = auto
 testpaths = tests
+pythonpath = src tests

scripts/generate_edge_navigation.py

@@ -7,10 +7,11 @@
 from pathlib import Path
 
 _REPO_ROOT = Path(__file__).resolve().parent.parent
-if str(_REPO_ROOT) not in sys.path:
-    sys.path.insert(0, str(_REPO_ROOT))
+_SRC = _REPO_ROOT / "src"
+if str(_SRC) not in sys.path:
+    sys.path.insert(0, str(_SRC))
 
-from java_ontology import (  # noqa: E402
+from java_codebase_rag.graph.java_ontology import (  # noqa: E402
     EDGE_SCHEMA,
     EdgeSpec,
     _COMPOSED_MEMBER_TYPE_TRAVERSAL,

scripts/sync_agent_artifacts.py

@@ -27,9 +27,9 @@
 # Mapping of source (dev) paths to destination (install_data) paths
 # Only these subtrees are shipped - skills/README.md is explicitly excluded
 SYNC_MAP: list[tuple[Path, Path]] = [
-    (Path("skills/explore-codebase"), Path("java_codebase_rag/install_data/skills/explore-codebase")),
-    (Path("skills/explore-codebase-cli"), Path("java_codebase_rag/install_data/skills/explore-codebase-cli")),
-    (Path("agents"), Path("java_codebase_rag/install_data/agents")),
+    (Path("skills/explore-codebase"), Path("src/java_codebase_rag/install_data/skills/explore-codebase")),
+    (Path("skills/explore-codebase-cli"), Path("src/java_codebase_rag/install_data/skills/explore-codebase-cli")),
+    (Path("agents"), Path("src/java_codebase_rag/install_data/agents")),
 ]
 
 

absence_diagnosis.py → src/java_codebase_rag/absence/absence_diagnosis.py

@@ -30,17 +30,17 @@
 from difflib import SequenceMatcher
 from typing import Any, Literal
 
-from absence_types import (
+from java_codebase_rag.absence.absence_types import (
     AbsenceDiagnosis,
     AbsenceProof,
     ExternalIdentity,
     FilterRelaxation,
     FilterRelaxationDim,
     VocabularyContext,
 )
-from absence_vocab import SymbolRecord, VocabularyIndex, _normalize_name
-from graph_types import NodeRef
-from mcp_hints import _IDENTIFIER_FILTER_FIELDS
+from java_codebase_rag.absence.absence_vocab import SymbolRecord, VocabularyIndex, _normalize_name
+from java_codebase_rag.graph.graph_types import NodeRef
+from java_codebase_rag.mcp.mcp_hints import _IDENTIFIER_FILTER_FIELDS
 
 log = logging.getLogger(__name__)
 

absence_types.py → src/java_codebase_rag/absence/absence_types.py

@@ -8,7 +8,7 @@
 
 from pydantic import BaseModel, Field
 
-from graph_types import NodeRef
+from java_codebase_rag.graph.graph_types import NodeRef
 
 __all__ = [
     "AbsenceVerdict",

absence_vocab.py → src/java_codebase_rag/absence/absence_vocab.py

@@ -204,7 +204,7 @@ def load(cls, path: Path) -> "VocabularyIndex":
             VocabIndexStale: If sidecar format_version or ontology_version
                 doesn't match expected
         """
-        from ast_java import ONTOLOGY_VERSION
+        from java_codebase_rag.ast.ast_java import ONTOLOGY_VERSION
 
         with open(path, encoding="utf-8") as f:
             data = json.load(f)
@@ -304,7 +304,7 @@ def is_external(self, name: str) -> tuple[bool, str | None]:
         Returns:
             (is_external, reason) tuple
         """
-        from ladybug_queries import _is_external_fqn, _EXTERNAL_PREFIXES
+        from java_codebase_rag.graph.ladybug_queries import _is_external_fqn, _EXTERNAL_PREFIXES
 
         # First, check if it's an external prefix (highest priority)
         if _is_external_fqn(name):
@@ -354,7 +354,7 @@ def get_vocabulary_index(graph: Any, cfg: Any) -> VocabularyIndex:
     Returns:
         VocabularyIndex (cached or newly built)
     """
-    from ast_java import ONTOLOGY_VERSION
+    from java_codebase_rag.ast.ast_java import ONTOLOGY_VERSION
 
     # Determine graph db path for cache key
     db_path = graph.db_path if hasattr(graph, 'db_path') else str(cfg.ladybug_path)
@@ -403,7 +403,7 @@ def reset_cache() -> None:
 
 def _row_to_symbol_record(row: dict[str, Any]) -> SymbolRecord:
     """Convert a Ladybug row to a SymbolRecord."""
-    from ladybug_queries import _type_part_fqn
+    from java_codebase_rag.graph.ladybug_queries import _type_part_fqn
 
     fqn = row.get("fqn") or ""
     name = row.get("name") or ""

pr_analysis.py → src/java_codebase_rag/analysis/pr_analysis.py

@@ -12,7 +12,7 @@
 from unidiff import PatchSet
 from unidiff.errors import UnidiffParseError
 
-from ladybug_queries import SymbolHit, find_symbols_in_file_range, _row_to_symbol
+from java_codebase_rag.graph.ladybug_queries import SymbolHit, find_symbols_in_file_range, _row_to_symbol
 
 
 @dataclass

resolve_service.py → src/java_codebase_rag/analysis/resolve_service.py

@@ -10,20 +10,20 @@
 
 from pydantic import BaseModel, ConfigDict, Field
 
-from absence_types import AbsenceDiagnosis
-from absence_diagnosis import diagnose
-from absence_vocab import get_vocabulary_index
-from graph_types import (
+from java_codebase_rag.absence.absence_types import AbsenceDiagnosis
+from java_codebase_rag.absence.absence_diagnosis import diagnose
+from java_codebase_rag.absence.absence_vocab import get_vocabulary_index
+from java_codebase_rag.graph.graph_types import (
     NodeRef,
     StructuredHint,
     _hints_or_skip,
     _node_ref_from_row,
     _to_structured_hints,
     set_hints_enabled,
 )
-from java_ontology import ResolveReason
-from ladybug_queries import LadybugGraph
-from mcp_hints import MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION
+from java_codebase_rag.graph.java_ontology import ResolveReason
+from java_codebase_rag.graph.ladybug_queries import LadybugGraph
+from java_codebase_rag.mcp.mcp_hints import MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION
 
 __all__ = [
     "resolve_v2",

ast_java.py → src/java_codebase_rag/ast/ast_java.py

@@ -20,7 +20,7 @@
 
 import tree_sitter_java as _ts_java
 
-from brownfield_events import (
+from java_codebase_rag.ast.brownfield_events import (
     emit_brownfield_exclusivity_shadowing,
     emit_brownfield_method_string_literal,
 )
@@ -1617,7 +1617,7 @@ def _parse_codebase_http_client_annotation(
         val, vkind = _annotation_value(pairs["clientKind"], src)
         if val and vkind == "enum":
             kind_val = str(val)
-            from java_ontology import VALID_CLIENT_KINDS  # deferred: java_ontology imports ast_java
+            from java_codebase_rag.graph.java_ontology import VALID_CLIENT_KINDS  # deferred: java_ontology imports ast_java
             if kind_val in VALID_CLIENT_KINDS:
                 client_kind = kind_val
             else:
@@ -1697,7 +1697,7 @@ def _parse_codebase_producer_annotation(
         val, vkind = _annotation_value(kind_node, src)
         if val and vkind == "enum":
             kind_val = str(val)
-            from java_ontology import VALID_PRODUCER_KINDS  # deferred: java_ontology imports ast_java
+            from java_codebase_rag.graph.java_ontology import VALID_PRODUCER_KINDS  # deferred: java_ontology imports ast_java
             if kind_val in VALID_PRODUCER_KINDS:
                 client_kind = kind_val
             else:
@@ -1868,7 +1868,7 @@ def _collect_outgoing_calls(
     file_rel: str,
 ) -> list[OutgoingCallDecl]:
     del project_root
-    from java_ontology import (  # deferred: java_ontology imports ast_java
+    from java_codebase_rag.graph.java_ontology import (  # deferred: java_ontology imports ast_java
         CLIENT_KIND_FEIGN_METHOD,
         CLIENT_KIND_REST_TEMPLATE,
         CLIENT_KIND_WEB_CLIENT,

java_codebase_rag/cli.py → src/java_codebase_rag/cli.py

@@ -36,7 +36,7 @@
     run_cocoindex_update,
     run_incremental_graph,
 )
-from java_ontology import VALID_UNRESOLVED_CALL_REASONS
+from java_codebase_rag.graph.java_ontology import VALID_UNRESOLVED_CALL_REASONS
 
 LADYBUG_INCREMENTAL_TRACKING_ISSUE_URL = "https://github.com/HumanBean17/java-codebase-rag/issues/73"
 
@@ -602,7 +602,7 @@ def work(progress: "PipelineProgress | None") -> int:
             _emit_reprocess_outcome(payload, selective_tty_mode="graph" if ok else None)
             return _reprocess_exit_code(payload)
 
-        import server  # lazy: pulls sentence_transformers/torch/lancedb/ladybug
+        from java_codebase_rag.mcp import server  # lazy: pulls sentence_transformers/torch/lancedb/ladybug
 
         result = asyncio.run(
             server.run_refresh_pipeline(
@@ -677,7 +677,7 @@ def _cmd_erase(args: argparse.Namespace) -> int:
     # tree_sitter (~54ms), and these filenames are only needed on the erase path.
     # Keeping it out of the top-level import lets `java-codebase-rag --help` (and
     # every other command) stay fast -- see the lazy-import invariant atop this file.
-    from build_ast_graph import BUILDER_OWNED_INDEX_FILES
+    from java_codebase_rag.graph.build_ast_graph import BUILDER_OWNED_INDEX_FILES
     builder_paths = [cfg.ladybug_path.parent / name for name in BUILDER_OWNED_INDEX_FILES]
     operator_paths = [cfg.index_dir / name for name in OPERATOR_OWNED_INDEX_FILES]
     to_describe: list[Path] = [
@@ -768,12 +768,12 @@ def work(progress: "PipelineProgress | None") -> int:
 
 
 def _cmd_meta(args: argparse.Namespace) -> int:
-    import server  # lazy
+    from java_codebase_rag.mcp import server  # lazy
 
     cfg = _resolved_from_ns(args)
     _startup_hints(cfg)
     cfg.apply_to_os_environ()
-    from ladybug_queries import LadybugGraph  # lazy
+    from java_codebase_rag.graph.ladybug_queries import LadybugGraph  # lazy
 
     LadybugGraph._instance = None
     LadybugGraph._instance_path = None
@@ -792,7 +792,7 @@ def _cmd_meta(args: argparse.Namespace) -> int:
 
 
 def _cmd_tables(args: argparse.Namespace) -> int:
-    import server  # lazy
+    from java_codebase_rag.mcp import server  # lazy
 
     cfg = _resolved_from_ns(args)
     _startup_hints(cfg)
@@ -803,8 +803,8 @@ def _cmd_tables(args: argparse.Namespace) -> int:
 
 
 def _cmd_diagnose_ignore(args: argparse.Namespace) -> int:
-    import server  # lazy
-    from path_filtering import LayeredIgnore  # lazy
+    from java_codebase_rag.mcp import server  # lazy
+    from java_codebase_rag.graph.path_filtering import LayeredIgnore  # lazy
 
     cfg = _resolved_from_ns(args)
     _startup_hints(cfg)
@@ -833,7 +833,7 @@ def _cmd_unresolved_calls_list(args: argparse.Namespace) -> int:
     cfg = _resolved_from_ns(args)
     _startup_hints(cfg)
     cfg.apply_to_os_environ()
-    from ladybug_queries import LadybugGraph  # lazy
+    from java_codebase_rag.graph.ladybug_queries import LadybugGraph  # lazy
 
     if not LadybugGraph.exists():
         _emit({"success": False, "message": "LadybugDB graph not found"})
@@ -854,7 +854,7 @@ def _cmd_unresolved_calls_stats(args: argparse.Namespace) -> int:
     cfg = _resolved_from_ns(args)
     _startup_hints(cfg)
     cfg.apply_to_os_environ()
-    from ladybug_queries import LadybugGraph  # lazy
+    from java_codebase_rag.graph.ladybug_queries import LadybugGraph  # lazy
 
     if not LadybugGraph.exists():
         _emit({"success": False, "message": "LadybugDB graph not found"})
@@ -878,8 +878,8 @@ def _cmd_analyze_pr(args: argparse.Namespace) -> int:
     if not diff_text.strip():
         _emit({"success": False, "message": "Diff is empty"})
         return 1
-    import pr_analysis  # lazy
-    from ladybug_queries import LadybugGraph  # lazy
+    from java_codebase_rag.analysis import pr_analysis  # lazy
+    from java_codebase_rag.graph.ladybug_queries import LadybugGraph  # lazy
 
     if not LadybugGraph.exists():
         _emit({"success": False, "message": "LadybugDB graph not found"})

build_ast_graph.py → src/java_codebase_rag/graph/build_ast_graph.py

@@ -41,7 +41,7 @@
 import ladybug
 import pyarrow as pa
 
-from ast_java import (
+from java_codebase_rag.ast.ast_java import (
     ONTOLOGY_VERSION,
     CallSite,
     JavaFileAst,
@@ -52,7 +52,7 @@
     lombok_required_args_annotations,
     parse_java,
 )
-from graph_enrich import (
+from java_codebase_rag.graph.graph_enrich import (
     _load_config_cross_service_resolution,
     classify_java_file,
     collect_annotation_meta_chain,
@@ -67,8 +67,8 @@
     resolve_routes_for_method,
     symbol_id,
 )
-from path_filtering import LayeredIgnore, iter_java_source_files
-from java_ontology import (
+from java_codebase_rag.graph.path_filtering import LayeredIgnore, iter_java_source_files
+from java_codebase_rag.graph.java_ontology import (
     CLIENT_KIND_FEIGN_METHOD,
     CLIENT_KIND_REST_TEMPLATE,
     VALID_CLIENT_KINDS,
@@ -4256,8 +4256,8 @@ def _try_build_vocabulary_index(db_path: Path, source_root: Path, verbose: bool)
         verbose: Whether to emit verbose progress
     """
     try:
-        from absence_vocab import VocabularyIndex, VOCAB_INDEX_FILENAME
-        from ladybug_queries import LadybugGraph
+        from java_codebase_rag.absence.absence_vocab import VocabularyIndex, VOCAB_INDEX_FILENAME
+        from java_codebase_rag.graph.ladybug_queries import LadybugGraph
 
         t0 = time.time()
         if verbose:

graph_enrich.py → src/java_codebase_rag/graph/graph_enrich.py

@@ -25,7 +25,7 @@
 from functools import lru_cache
 from pathlib import Path
 from typing import Any, TypeVar
-from ast_java import (
+from java_codebase_rag.ast.ast_java import (
     AnnotationRef,
     JavaFileAst,
     MethodDecl,
@@ -43,7 +43,7 @@
     _METHOD_ANN_TO_CAPABILITY,
     _TYPE_ANN_TO_CAPABILITY,
 )
-from java_ontology import (
+from java_codebase_rag.graph.java_ontology import (
     CLIENT_KIND_REST_TEMPLATE,
     VALID_CAPABILITIES,
     VALID_CLIENT_KINDS,
@@ -52,7 +52,7 @@
     VALID_ROUTE_FRAMEWORKS,
     VALID_ROUTE_KINDS,
 )
-from path_filtering import LayeredIgnore, iter_java_source_files
+from java_codebase_rag.graph.path_filtering import LayeredIgnore, iter_java_source_files
 
 __all__ = [
     "AnnotationDecl",

graph_types.py → src/java_codebase_rag/graph/graph_types.py

@@ -10,8 +10,8 @@
 
 from pydantic import BaseModel
 
-from ladybug_queries import LadybugGraph
-from mcp_hints import generate_hints
+from java_codebase_rag.graph.ladybug_queries import LadybugGraph
+from java_codebase_rag.mcp.mcp_hints import generate_hints
 
 __all__ = [
     "NodeRef",

java_ontology.py → src/java_codebase_rag/graph/java_ontology.py

@@ -7,7 +7,7 @@
 from dataclasses import dataclass
 from typing import Literal
 
-from ast_java import (
+from java_codebase_rag.ast.ast_java import (
     ROLE_ANNOTATIONS,
     _INJECTED_TYPES_TO_CAPABILITY,
     _METHOD_ANN_TO_CAPABILITY,

ladybug_queries.py → src/java_codebase_rag/graph/ladybug_queries.py

@@ -24,7 +24,7 @@
 
 import ladybug
 
-from ast_java import ONTOLOGY_VERSION as _ONTOLOGY_VERSION
+from java_codebase_rag.ast.ast_java import ONTOLOGY_VERSION as _ONTOLOGY_VERSION
 
 log = logging.getLogger(__name__)