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

java_codebase_rag/_deprecation.py

@@ -0,0 +1,103 @@
+"""Legacy-alias deprecation notice for the ``jrag`` rename.
+
+The tool is being renamed from ``java-codebase-rag`` to ``jrag``. The legacy
+command aliases (``java-codebase-rag`` and ``java-codebase-rag-mcp``) continue
+to work; when invoked through one of them in an interactive context, this
+helper emits a single-line notice pointing the operator at the new name.
+
+Suppression rule
+----------------
+The notice is suppressed when **either** of the following holds:
+
+* ``$JRAG_NO_DEPRECATION`` is present and non-empty — any non-empty value
+  suppresses (so ``"1"``, ``"0"``, ``"false"``, ``"yes"`` all suppress; the
+  empty string and an unset variable do not). The simpler "present and
+  non-empty" rule is preferred over parsing truthy values so that operators
+  can shut the notice up with whatever value is easiest to reach for.
+* ``sys.stderr.isatty()`` is false (or ``sys.stderr`` lacks ``isatty``) — i.e.
+  non-interactive contexts: piped, redirected, or captured stderr. Under real
+  MCP use stderr is not a TTY, so the call is silent in production; it exists
+  for the rare human-debug case.
+
+This module is stdlib-only and import-light: it runs at MCP-server startup and
+before ``--help``, so it must not pull in any backend (cli, search, mcp) code.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+_LEGACY_ALIASES = frozenset({"java-codebase-rag", "java-codebase-rag-mcp"})
+
+_DEPRECATION_LINE = (
+    "jrag: 'java-codebase-rag' is now 'jrag'; this alias continues to work. "
+    "Set JRAG_NO_DEPRECATION=1 to silence.\n"
+)
+
+#: Executable suffixes appended by Windows (and packaging tools like pip) to
+#: console-script wrappers. All three are exactly 4 characters long (``.exe``,
+#: ``.bat``, ``.cmd``) so a single ``b[:-4]`` slice strips any of them. Stripping
+#: keeps routing decisions stable across POSIX and Windows installs:
+#: ``C:\\Users\\foo\\Scripts\\jrag.exe`` → ``"jrag"``;
+#: ``...\\java-codebase-rag.exe`` → ``"java-codebase-rag"``.
+_WINDOWS_EXE_SUFFIXES: tuple[str, ...] = (".exe", ".bat", ".cmd")
+
+
+def _invoked_program_name() -> str:
+    """Basename of ``sys.argv[0]`` with a Windows executable suffix stripped.
+
+    Returns the empty string when ``sys.argv`` is empty. Otherwise takes
+    ``os.path.basename(sys.argv[0])`` and, if it ends (case-insensitively) with
+    one of ``.exe`` / ``.bat`` / ``.cmd``, drops the 4-character suffix.
+
+    Shared with :mod:`java_codebase_rag.cli_dispatch` for identity-default
+    routing: both legacy-alias deprecation here and ``jrag``-vs-alias routing
+    there rely on the same canonicalized basename. Without this, Windows builds
+    would route ``jrag.exe --version`` through the wrong parser and never emit
+    the deprecation notice for ``java-codebase-rag.exe``.
+    """
+    argv = sys.argv
+    if not argv:
+        return ""
+    base = os.path.basename(argv[0])
+    if base.lower().endswith(_WINDOWS_EXE_SUFFIXES):
+        return base[:-4]
+    return base
+
+
+def _stderr_is_tty() -> bool:
+    """True iff ``sys.stderr`` reports itself as a TTY.
+
+    Defensive against stderr replacements that omit ``isatty``.
+    """
+    stderr = sys.stderr
+    return hasattr(stderr, "isatty") and stderr.isatty()
+
+
+def _suppressed() -> bool:
+    """True iff the notice should be suppressed."""
+    if os.environ.get("JRAG_NO_DEPRECATION"):
+        return True
+    return not _stderr_is_tty()
+
+
+def maybe_warn_legacy_alias(stream=None) -> None:
+    """Emit a one-line legacy-alias deprecation notice when appropriate.
+
+    Detects a legacy invocation (``sys.argv[0]`` basename is exactly
+    ``java-codebase-rag`` or ``java-codebase-rag-mcp``) and, if not suppressed,
+    writes a single line to ``stream`` (defaulting to ``sys.stderr``). Never
+    raises: any error inside the write is swallowed so the rename helper can
+    never break tool startup.
+
+    See module docstring for the suppression rule.
+    """
+    if _invoked_program_name() not in _LEGACY_ALIASES:
+        return
+    if _suppressed():
+        return
+    target = stream if stream is not None else sys.stderr
+    try:
+        target.write(_DEPRECATION_LINE)
+    except Exception:  # pragma: no cover - defensive: never break startup
+        return

java_codebase_rag/_version.py

@@ -1,7 +1,7 @@
 """Version string for the CLI ``--version`` flag.
 
 The single source of truth is the installed distribution metadata
-(``java-codebase-rag`` in pyproject.toml), read via :mod:`importlib.metadata`
+(``jrag-cli`` in pyproject.toml), read via :mod:`importlib.metadata`
 so a pyproject bump propagates with no second hardcoded copy.
 :func:`version_string` appends the CPython version for the
 ``<prog> <version> (python <x.y.z>)`` format chosen for the ``--version`` flag.
@@ -15,7 +15,7 @@ import platform
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as _dist_version
 
-_PACKAGE = "java-codebase-rag"
+_PACKAGE = "jrag-cli"
 
 
 def package_version() -> str:

java_codebase_rag/ast/ast_java.py

@@ -249,6 +249,11 @@ class AnnotationRef:
     container_capability_values: tuple[str, ...] = field(default_factory=tuple)
     # Entry-aligned with `container_capability_values`; each value is "enum" | "string".
     container_capability_kinds: tuple[str, ...] = field(default_factory=tuple)
+    # Kotlin use-site target (one of "field"|"get"|"set"|"param"|"property"|"file") or
+    # None. Java ``parse_java`` always leaves this None — Java has no use-site targets.
+    # This is an AST-level field (not a persisted graph column); it drives Kotlin-only
+    # routing of an annotation to the FieldDecl / accessor MethodDecl / ParamDecl slot.
+    use_site_target: str | None = None
 
 
 @dataclass
@@ -394,11 +399,26 @@ class JavaFileAst:
     explicit_imports: dict[str, str]  # "List" -> "java.util.List"
     top_level_types: list[TypeDecl]
     all_types: list[TypeDecl]  # flat, includes nested
+    # Language-dispatch seam (Task 1). Required — no default — so every
+    # construction site names the language explicitly. Validated against the
+    # registry in ``language.KNOWN_LANGUAGE_IDS``. Lazily imported inside
+    # ``__post_init__`` to avoid a module-load cycle (``language`` imports
+    # ``JavaFileAst``/``parse_java`` from this module).
+    language: str
     parse_error: bool = False
     source_bytes: int = 0
     file_imports: FileImports = field(default_factory=FileImports)
     routes_skipped_unresolved: int = 0
 
+    def __post_init__(self) -> None:
+        from .language import KNOWN_LANGUAGE_IDS
+
+        if self.language not in KNOWN_LANGUAGE_IDS:
+            raise ValueError(
+                f"Unknown language id {self.language!r}; "
+                f"expected one of {sorted(KNOWN_LANGUAGE_IDS)}"
+            )
+
 
 @dataclass
 class _ParseCtx:
@@ -2625,6 +2645,7 @@ def parse_java(source: bytes | str, *, filename: str = "", verbose: bool = False
         explicit_imports={},
         top_level_types=[],
         all_types=[],
+        language="java",
         parse_error=False,
         source_bytes=len(src),
         file_imports=FileImports(),
@@ -2710,6 +2731,7 @@ def parse_java(source: bytes | str, *, filename: str = "", verbose: bool = False
         explicit_imports=explicit_imports,
         top_level_types=top_types,
         all_types=all_types,
+        language="java",
         parse_error=root.has_error,
         source_bytes=len(src),
         file_imports=file_imports,