sourcecode 1.35.32__py3-none-any.whl → 1.35.34__py3-none-any.whl

sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Deterministic codebase context maps for AI coding agents."""
 
-__version__ = "1.35.32"
+__version__ = "1.35.34"

sourcecode/architecture_analyzer.py

@@ -237,7 +237,7 @@ class ArchitectureAnalyzer:
             return ArchitectureAnalysis(
                 requested=True,
                 pattern="unknown",
-                limitations=["Arquitectura no inferida: proyecto sin archivos de codigo suficientes"],
+                limitations=["Architecture not inferred: insufficient source files in project"],
                 evidence=[{"type": "none", "paths": [], "reason": "insufficient source files", "confidence": "high"}],
                 tentative=False,
             )

sourcecode/classifier.py

@@ -19,6 +19,10 @@ _API_FRAMEWORKS = {
     "Actix Web",
     "Rocket",
     "Spring Boot",
+    "Spring MVC",
+    "Spring WebFlux",
+    "Micronaut",
+    "Vert.x",
     "Quarkus",
     "Jakarta EE",   # JAX-RS / Jakarta REST — pure JAX-RS projects must not fall to "unknown"
     "Laravel",

sourcecode/cli.py

@@ -1227,159 +1227,164 @@ def main(
                 except Exception:
                     pass
 
-            if _git_sha and _git_root_str:
-                _excl_key = (
-                    ",".join(sorted(e.strip() for e in exclude.split(",") if e.strip()))
-                    if exclude else ""
-                )
+            _excl_key = (
+                ",".join(sorted(e.strip() for e in exclude.split(",") if e.strip()))
+                if exclude else ""
+            )
 
-                # ── Core (analysis) flags: affect which analyzers run + scan config ──
-                # Use effective_depth (not raw depth) so Java auto-adjustment is captured.
-                # acv = ANALYZER_CACHE_VERSION — bumped only when analysis logic/schema
-                # changes, NOT on every package release.  Prevents patch-bump cache wipes.
-                _core_flags_str = (
-                    f"acv={_cache_mod.ANALYZER_CACHE_VERSION},"
-                    f"dep={dependencies},gm={graph_modules},"
-                    f"docs={docs},fm={full_metrics},sem={semantics},"
-                    f"arch={architecture},gc={git_context},em={env_map},"
-                    f"cn={code_notes},"
-                    f"ex={_excl_key},depth={effective_depth}"
-                )
-                _core_h = _hashlib.sha256(_core_flags_str.encode()).hexdigest()[:8]
+            # ── Core (analysis) flags: affect which analyzers run + scan config ──
+            # Use effective_depth (not raw depth) so Java auto-adjustment is captured.
+            # acv = ANALYZER_CACHE_VERSION — bumped only when analysis logic/schema
+            # changes, NOT on every package release.  Prevents patch-bump cache wipes.
+            _core_flags_str = (
+                f"acv={_cache_mod.ANALYZER_CACHE_VERSION},"
+                f"dep={dependencies},gm={graph_modules},"
+                f"docs={docs},fm={full_metrics},sem={semantics},"
+                f"arch={architecture},gc={git_context},em={env_map},"
+                f"cn={code_notes},"
+                f"ex={_excl_key},depth={effective_depth}"
+            )
+            _core_h = _hashlib.sha256(_core_flags_str.encode()).hexdigest()[:8]
+            if _git_sha and _git_root_str:
                 _core_key = f"{_git_sha}-{_core_h}"
-
-                # ── View flags: output presentation only (no re-analysis needed) ──
-                _view_flags_str = (
-                    f"c={compact},ag={agent},mode={mode},fmt={format},full={full},"
-                    f"co={changed_only},tree={tree},nt={no_tree},"
-                    f"rb={rank_by},sym={symbol},ep={entrypoints_only},"
-                    f"nr={no_redact},gd={graph_detail},dd={docs_depth},"
-                    f"mn={max_nodes},ge={graph_edges},mi={max_importers},"
-                    f"eg={emit_graph}"
-                )
-                _view_h = _hashlib.sha256(_view_flags_str.encode()).hexdigest()[:8]
-
-                # ── Lookup ──────────────────────────────────────────────────────
-                # Step 1: try L1 to obtain the core_hash needed for L2 key
-                _l1_result = _cache_mod.read_core(target, _core_key)
-
-                # P1-A: --env-map misses L1 when base (em=False) exists.
-                # Try the base key so env analysis can be injected lazily (<1 s)
-                # instead of triggering a 17 s full rescan.
-                _l1_needs_env_inject = False
-                if _l1_result is None and env_map:
-                    _base_flags = _core_flags_str.replace(",em=True,", ",em=False,")
-                    _base_h8 = _hashlib.sha256(_base_flags.encode()).hexdigest()[:8]
-                    _base_key = f"{_git_sha}-{_base_h8}"
-                    _base_result = _cache_mod.read_core(target, _base_key)
-                    if _base_result is not None:
-                        _l1_result = _base_result
-                        _l1_needs_env_inject = True
-
-                if _l1_result is not None:
-                    _core_dict_l1, _core_hash = _l1_result
-                    _view_key = f"{_core_hash}-{_view_h}"
-
-                    # Step 2: try L2 (exact view match).
-                    # Skip L2 for --changed-only: the stored view is a previous
-                    # diff snapshot that is stale for the current diff.
-                    if not changed_only:
-                        _cache_hit_content = _cache_mod.read_view(target, _view_key)
-
-                    # Step 3: L1 hit but L2 miss → rebuild view from core dict
-                    if _cache_hit_content is None:
-                        try:
-                            from sourcecode.serializer import build_view_from_core as _bvfc
-                            _rebuilt = _bvfc(
-                                _core_dict_l1,
-                                compact=compact,
-                                agent=agent,
-                                full=full,
-                                no_tree=no_tree,
-                                tree=tree,
-                            )
-                            # P1-A: inject env analysis when base L1 (em=False) was used.
-                            # EnvAnalyzer walks only env/config files — typically <1 s.
-                            if _rebuilt is not None and _l1_needs_env_inject and compact:
-                                try:
-                                    from sourcecode.env_analyzer import EnvAnalyzer as _EnvA_p1a
-                                    _env_r_p1a, _env_s_p1a = _EnvA_p1a().analyze(target, {})
-                                    if _env_s_p1a and (getattr(_env_s_p1a, "total", 0) or _env_r_p1a):
-                                        _es_p1a: dict = {
-                                            "total": getattr(_env_s_p1a, "total", 0),
-                                            "required": getattr(_env_s_p1a, "required_count", 0),
-                                        }
-                                        _cats = getattr(_env_s_p1a, "categories", None)
-                                        if _cats:
-                                            _es_p1a["categories"] = _cats
-                                        _rebuilt = dict(_rebuilt)
-                                        _rebuilt["env_summary"] = _es_p1a
-                                        if _env_r_p1a:
-                                            _sorted_er = sorted(
-                                                _env_r_p1a,
-                                                key=lambda e: (
-                                                    not getattr(e, "required", False),
-                                                    getattr(e, "key", ""),
-                                                ),
-                                            )
-                                            _rebuilt["env_map"] = [
-                                                {
-                                                    "key": getattr(e, "key", ""),
-                                                    **({"required": True} if getattr(e, "required", False) else {}),
-                                                    **({"category": getattr(e, "category", None)} if getattr(e, "category", None) else {}),
-                                                }
-                                                for e in _sorted_er[:15]
-                                            ]
-                                except Exception:
-                                    pass  # env inject failed — continue without env data
-                            if _rebuilt is not None:
-                                # Apply redaction
-                                if not no_redact:
-                                    from sourcecode.redactor import redact_dict as _red_l1
-                                    _rebuilt = _red_l1(_rebuilt)
-                                # Apply output budget
-                                if agent:
-                                    from sourcecode.output_budget import (
-                                        trim_to_budget as _trim_l1,
-                                        BUDGET_AGENT,
-                                    )
-                                    _rebuilt = _trim_l1(_rebuilt, BUDGET_AGENT, label="agent")
-                                elif compact:
-                                    from sourcecode.output_budget import (
-                                        trim_to_budget as _trim_l1c,
-                                        BUDGET_COMPACT,
-                                    )
-                                    _rebuilt = _trim_l1c(_rebuilt, BUDGET_COMPACT, label="compact")
-                                # Serialize
-                                if format == "yaml":
-                                    from io import StringIO as _SIO_L1
-                                    from ruamel.yaml import YAML as _YAML_L1
-                                    _yl1 = _YAML_L1()
-                                    _yl1.default_flow_style = False
-                                    _yl1.representer.add_representer(
-                                        type(None),
-                                        lambda d, v: d.represent_scalar(
-                                            "tag:yaml.org,2002:null", "null"
-                                        ),
-                                    )
-                                    _sl1 = _SIO_L1()
-                                    _yl1.dump(_rebuilt, _sl1)
-                                    _cache_hit_content = _sl1.getvalue()
-                                else:
-                                    import json as _json_l1
-                                    _cache_hit_content = _json_l1.dumps(
-                                        _rebuilt, indent=2, ensure_ascii=False
-                                    )
-                                # Cache rebuilt view in L2 (skip for --changed-only: stale diff)
-                                if _cache_hit_content and not changed_only:
-                                    _cache_mod.write_view(
-                                        target,
-                                        _view_key,
-                                        _cache_hit_content,
-                                        fmt=format,
-                                    )
-                        except Exception:
-                            _cache_hit_content = None  # rebuild failed → full analysis
+            else:
+                # No git history (untracked/no-commit repo) — stable synthetic key
+                # scoped per repo path via cache_dir(); invalidated by --no-cache or cache clear.
+                _core_key = f"nogit-{_core_h}"
+
+            # ── View flags: output presentation only (no re-analysis needed) ──
+            _view_flags_str = (
+                f"c={compact},ag={agent},mode={mode},fmt={format},full={full},"
+                f"co={changed_only},tree={tree},nt={no_tree},"
+                f"rb={rank_by},sym={symbol},ep={entrypoints_only},"
+                f"nr={no_redact},gd={graph_detail},dd={docs_depth},"
+                f"mn={max_nodes},ge={graph_edges},mi={max_importers},"
+                f"eg={emit_graph}"
+            )
+            _view_h = _hashlib.sha256(_view_flags_str.encode()).hexdigest()[:8]
+
+            # ── Lookup ──────────────────────────────────────────────────────
+            # Step 1: try L1 to obtain the core_hash needed for L2 key
+            _l1_result = _cache_mod.read_core(target, _core_key)
+
+            # P1-A: --env-map misses L1 when base (em=False) exists.
+            # Try the base key so env analysis can be injected lazily (<1 s)
+            # instead of triggering a 17 s full rescan.
+            _l1_needs_env_inject = False
+            if _l1_result is None and env_map:
+                _base_flags = _core_flags_str.replace(",em=True,", ",em=False,")
+                _base_h8 = _hashlib.sha256(_base_flags.encode()).hexdigest()[:8]
+                _sha_prefix = _git_sha if _git_sha else "nogit"
+                _base_key = f"{_sha_prefix}-{_base_h8}"
+                _base_result = _cache_mod.read_core(target, _base_key)
+                if _base_result is not None:
+                    _l1_result = _base_result
+                    _l1_needs_env_inject = True
+
+            if _l1_result is not None:
+                _core_dict_l1, _core_hash = _l1_result
+                _view_key = f"{_core_hash}-{_view_h}"
+
+                # Step 2: try L2 (exact view match).
+                # Skip L2 for --changed-only: the stored view is a previous
+                # diff snapshot that is stale for the current diff.
+                if not changed_only:
+                    _cache_hit_content = _cache_mod.read_view(target, _view_key)
+
+                # Step 3: L1 hit but L2 miss → rebuild view from core dict
+                if _cache_hit_content is None:
+                    try:
+                        from sourcecode.serializer import build_view_from_core as _bvfc
+                        _rebuilt = _bvfc(
+                            _core_dict_l1,
+                            compact=compact,
+                            agent=agent,
+                            full=full,
+                            no_tree=no_tree,
+                            tree=tree,
+                        )
+                        # P1-A: inject env analysis when base L1 (em=False) was used.
+                        # EnvAnalyzer walks only env/config files — typically <1 s.
+                        if _rebuilt is not None and _l1_needs_env_inject and compact:
+                            try:
+                                from sourcecode.env_analyzer import EnvAnalyzer as _EnvA_p1a
+                                _env_r_p1a, _env_s_p1a = _EnvA_p1a().analyze(target, {})
+                                if _env_s_p1a and (getattr(_env_s_p1a, "total", 0) or _env_r_p1a):
+                                    _es_p1a: dict = {
+                                        "total": getattr(_env_s_p1a, "total", 0),
+                                        "required": getattr(_env_s_p1a, "required_count", 0),
+                                    }
+                                    _cats = getattr(_env_s_p1a, "categories", None)
+                                    if _cats:
+                                        _es_p1a["categories"] = _cats
+                                    _rebuilt = dict(_rebuilt)
+                                    _rebuilt["env_summary"] = _es_p1a
+                                    if _env_r_p1a:
+                                        _sorted_er = sorted(
+                                            _env_r_p1a,
+                                            key=lambda e: (
+                                                not getattr(e, "required", False),
+                                                getattr(e, "key", ""),
+                                            ),
+                                        )
+                                        _rebuilt["env_map"] = [
+                                            {
+                                                "key": getattr(e, "key", ""),
+                                                **({"required": True} if getattr(e, "required", False) else {}),
+                                                **({"category": getattr(e, "category", None)} if getattr(e, "category", None) else {}),
+                                            }
+                                            for e in _sorted_er[:15]
+                                        ]
+                            except Exception:
+                                pass  # env inject failed — continue without env data
+                        if _rebuilt is not None:
+                            # Apply redaction
+                            if not no_redact:
+                                from sourcecode.redactor import redact_dict as _red_l1
+                                _rebuilt = _red_l1(_rebuilt)
+                            # Apply output budget
+                            if agent:
+                                from sourcecode.output_budget import (
+                                    trim_to_budget as _trim_l1,
+                                    BUDGET_AGENT,
+                                )
+                                _rebuilt = _trim_l1(_rebuilt, BUDGET_AGENT, label="agent")
+                            elif compact:
+                                from sourcecode.output_budget import (
+                                    trim_to_budget as _trim_l1c,
+                                    BUDGET_COMPACT,
+                                )
+                                _rebuilt = _trim_l1c(_rebuilt, BUDGET_COMPACT, label="compact")
+                            # Serialize
+                            if format == "yaml":
+                                from io import StringIO as _SIO_L1
+                                from ruamel.yaml import YAML as _YAML_L1
+                                _yl1 = _YAML_L1()
+                                _yl1.default_flow_style = False
+                                _yl1.representer.add_representer(
+                                    type(None),
+                                    lambda d, v: d.represent_scalar(
+                                        "tag:yaml.org,2002:null", "null"
+                                    ),
+                                )
+                                _sl1 = _SIO_L1()
+                                _yl1.dump(_rebuilt, _sl1)
+                                _cache_hit_content = _sl1.getvalue()
+                            else:
+                                import json as _json_l1
+                                _cache_hit_content = _json_l1.dumps(
+                                    _rebuilt, indent=2, ensure_ascii=False
+                                )
+                            # Cache rebuilt view in L2 (skip for --changed-only: stale diff)
+                            if _cache_hit_content and not changed_only:
+                                _cache_mod.write_view(
+                                    target,
+                                    _view_key,
+                                    _cache_hit_content,
+                                    fmt=format,
+                                )
+                    except Exception:
+                        _cache_hit_content = None  # rebuild failed → full analysis
 
         except Exception:
             _core_key = ""
@@ -2290,6 +2295,11 @@ def main(
         try:
             from sourcecode.ris import _has_uncommitted_changes as _huc_fresh
             _uncommitted_fresh = _huc_fresh(target)
+            # _huc_fresh uses --untracked-files=no — it misses repos where all
+            # files are untracked (no staged/unstaged changes to tracked files).
+            # Promote to True when _allowed_changed_files contains untracked files.
+            if not _uncommitted_fresh and _allowed_changed_files:
+                _uncommitted_fresh = True
         except Exception:
             _uncommitted_fresh = False
         import datetime as _dt
@@ -2335,44 +2345,51 @@ def main(
         import atexit as _atexit
         import threading as _threading
 
-        # Capture all closure state before handing off to thread
-        _bg_sm = sm
-        _bg_target = target
-        _bg_core_key = _core_key
-        _bg_view_key = _view_key
-        _bg_view_flags_str = _view_flags_str
-        _bg_content = content
-        _bg_format = format
-        _bg_hashlib = _hashlib
-        _bg_cache_mod = _cache_mod
-
-        def _write_cache_async() -> None:
-            try:
-                from sourcecode.serializer import core_view as _core_view_fn
-                _core_dict_write = _core_view_fn(_bg_sm)
-                _written_core_hash = _bg_cache_mod.write_core(
-                    _bg_target, _bg_core_key, _core_dict_write
-                )
-                if _written_core_hash:
-                    _vk = _bg_view_key
-                    if not _vk:
-                        _wvh = _bg_hashlib.sha256(_bg_view_flags_str.encode()).hexdigest()[:8]
-                        _vk = f"{_written_core_hash}-{_wvh}"
-                    _bg_cache_mod.write_view(
-                        _bg_target,
-                        _vk,
-                        _bg_content,
-                        fmt=_bg_format,
-                        layers=_compute_analyzer_fingerprints(),
+        # Pre-compute core dict in the main thread — avoids the 5-second atexit
+        # join race on large repos where core_view(sm) itself takes seconds.
+        # Background thread only does gzip + disk I/O (fast, bounded latency).
+        _bg_core_dict: dict | None = None
+        try:
+            from sourcecode.serializer import core_view as _core_view_fn
+            _bg_core_dict = _core_view_fn(sm)
+        except Exception:
+            pass
+
+        if _bg_core_dict is not None:
+            _bg_target = target
+            _bg_core_key = _core_key
+            _bg_view_key = _view_key
+            _bg_view_flags_str = _view_flags_str
+            _bg_content = content
+            _bg_format = format
+            _bg_hashlib = _hashlib
+            _bg_cache_mod = _cache_mod
+
+            def _write_cache_async() -> None:
+                try:
+                    _written_core_hash = _bg_cache_mod.write_core(
+                        _bg_target, _bg_core_key, _bg_core_dict
                     )
-                    from sourcecode.cache import cache_dir as _cdir, _gc as _run_gc
-                    _run_gc(_cdir(_bg_target))
-            except Exception:
-                pass
+                    if _written_core_hash:
+                        _vk = _bg_view_key
+                        if not _vk:
+                            _wvh = _bg_hashlib.sha256(_bg_view_flags_str.encode()).hexdigest()[:8]
+                            _vk = f"{_written_core_hash}-{_wvh}"
+                        _bg_cache_mod.write_view(
+                            _bg_target,
+                            _vk,
+                            _bg_content,
+                            fmt=_bg_format,
+                            layers=_compute_analyzer_fingerprints(),
+                        )
+                        from sourcecode.cache import cache_dir as _cdir, _gc as _run_gc
+                        _run_gc(_cdir(_bg_target))
+                except Exception:
+                    pass
 
-        _cache_write_thread = _threading.Thread(target=_write_cache_async, daemon=True)
-        _cache_write_thread.start()
-        _atexit.register(_cache_write_thread.join, 5.0)
+            _cache_write_thread = _threading.Thread(target=_write_cache_async, daemon=True)
+            _cache_write_thread.start()
+            _atexit.register(_cache_write_thread.join, 30.0)
 
     # Update RIS with aggregated snapshot data (non-fatal side-effect).
     # Update RIS whenever git is available, even when L1/L2 cache is skipped
@@ -3449,21 +3466,34 @@ def repo_ir_cmd(
         _ir_tokens_est = _ir_size // 4
         # P1-C: abort when estimated tokens > 50K unless --force or --output is given.
         if _ir_tokens_est > 50_000 and not force:
+            if summary_only:
+                _hint = (
+                    "Use --max-nodes N --max-edges N to cap graph size, "
+                    "--output FILE to save to disk, or --force to bypass this guard."
+                )
+            else:
+                _hint = (
+                    "Use --summary-only (~5K tokens), --max-nodes N --max-edges N, "
+                    "--output FILE to save to disk, or --force to bypass this guard."
+                )
             _emit_error_json(
                 "OUTPUT_TOO_LARGE",
                 f"Estimated output is ~{_ir_tokens_est // 1000}K tokens — too large for most LLM context windows.",
-                hint=(
-                    "Use --summary-only (~5K tokens), --max-nodes N --max-edges N, "
-                    "--output FILE to save to disk, or --force to bypass this guard."
-                ),
+                hint=_hint,
                 expected="Output under 50K estimated tokens.",
             )
             raise typer.Exit(1)
         if _ir_tokens_est > 10_000:
-            sys.stderr.write(
-                f"[repo-ir] ~{_ir_tokens_est // 1000}K tokens — "
-                "use --summary-only or --output FILE for smaller output.\n"
-            )
+            if summary_only:
+                sys.stderr.write(
+                    f"[repo-ir] ~{_ir_tokens_est // 1000}K tokens — "
+                    "use --max-nodes N --max-edges N or --output FILE for smaller output.\n"
+                )
+            else:
+                sys.stderr.write(
+                    f"[repo-ir] ~{_ir_tokens_est // 1000}K tokens — "
+                    "use --summary-only or --output FILE for smaller output.\n"
+                )
             sys.stderr.flush()
         try:
             sys.stdout.buffer.write(output.encode("utf-8"))
@@ -3573,6 +3603,15 @@ def impact_cmd(
             sys.stderr.flush()
         target, path = str(path), _target_as_path
 
+    if not target.strip():
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            "Class name must not be empty.",
+            hint="Pass a class name or FQN. Example: sourcecode impact OrderService .",
+            expected="A non-empty class name or FQN.",
+        )
+        raise typer.Exit(1)
+
     root = path.resolve()
     if not root.is_dir():
         _emit_error_json(
@@ -3701,6 +3740,15 @@ def endpoints_cmd(
       sourcecode endpoints . --controller LiquidacionJornada
       sourcecode endpoints . --limit 10
     """
+    if format not in ("json", "yaml"):
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            f"Invalid format '{format}'.",
+            hint="format must be: json or yaml.",
+            expected="json | yaml",
+        )
+        raise typer.Exit(code=1)
+
     target = path.resolve()
     if not target.exists() or not target.is_dir():
         _emit_error_json(
@@ -4241,6 +4289,15 @@ def impact_chain_cmd(
     from sourcecode.spring_impact import run_impact_chain
     from sourcecode.spring_findings import SpringAuditResult
 
+    if not symbol.strip():
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            "Symbol name must not be empty.",
+            hint="Pass a class name or FQN. Example: sourcecode impact-chain OrderService .",
+            expected="A non-empty class name or FQN.",
+        )
+        raise typer.Exit(code=1)
+
     _VALID_TYPES = ("impact", "events")
     if query_type not in _VALID_TYPES:
         _emit_error_json(
@@ -4410,10 +4467,10 @@ def pr_impact_cmd(
         )
         raise typer.Exit(code=1)
 
-    if not files.exists():
+    if not files.exists() or files.is_dir():
         _emit_error_json(
             INVALID_INPUT_CODE,
-            f"--files '{files}' does not exist. Expected a text file listing changed file paths (one per line), not a directory or class name.",
+            f"--files '{files}' does not exist or is a directory. Expected a text file listing changed file paths (one per line).",
             path=str(files),
             hint=(
                 "Create a file with one changed Java file path per line, then pass it with --files. "
@@ -4551,6 +4608,15 @@ def explain_cmd(
     from sourcecode.spring_model import SpringSemanticModel
     from sourcecode.explain import explain_class
 
+    if not class_name.strip():
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            "Class name must not be empty.",
+            hint="Pass a class name. Example: sourcecode explain UserService .",
+            expected="A non-empty class name.",
+        )
+        raise typer.Exit(code=1)
+
     target = path.resolve()
     if not target.exists() or not target.is_dir():
         _emit_error_json(
@@ -5105,7 +5171,7 @@ def rename_class_cmd(
         help="Output format: json (default) or yaml.",
     ),
 ) -> None:
-    """Rename a Java class throughout the repository (BLOCKER-A fix).
+    """Rename a Java class throughout the repository.
 
     \b
     Renames a Java class safely:
@@ -5116,7 +5182,7 @@ def rename_class_cmd(
       - Updates extends / implements
       - Updates generics, casts, Spring @Qualifier names
       - Renames the physical .java file
-      - Emits a structured change audit trail (BLOCKER-C)
+      - Emits a structured change audit trail
 
     \b
     Examples:
@@ -5227,7 +5293,7 @@ def chunk_file_cmd(
         help="Copy output to clipboard after a successful run.",
     ),
 ) -> None:
-    """Split a large Java file into semantic chunks for AI agent consumption (BLOCKER-B fix).
+    """Split a large Java file into semantic chunks for AI agent consumption.
 
     \b
     Splits a Java file at method/class boundaries so AI agents can read
@@ -5261,6 +5327,16 @@ def chunk_file_cmd(
         )
         raise typer.Exit(1)
 
+    if abs_file.suffix != ".java":
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            f"'{abs_file.name}' is not a Java file. chunk-file only supports .java files.",
+            path=str(abs_file),
+            hint="Pass a .java source file.",
+            expected="A .java file path.",
+        )
+        raise typer.Exit(1)
+
     result = chunk_java_file(abs_file, max_lines=max_lines, include_content=not metadata_only)
 
     if chunk_id is not None: