java-codebase-rag 0.2.2__tar.gz → 0.3.1__tar.gz

{java_codebase_rag-0.2.2/java_codebase_rag.egg-info → java_codebase_rag-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: java-codebase-rag
-Version: 0.2.2
+Version: 0.3.1
 Summary: MCP server for semantic + structural search over Java codebases
 Author: HumanBean17
 License-Expression: MIT
@@ -27,7 +27,6 @@ Requires-Dist: pathspec<2,>=1.0.4
 Requires-Dist: pyarrow<24,>=23.0.1
 Requires-Dist: PyYAML<7,>=6.0.3
 Requires-Dist: sentence-transformers<6,>=5.4.0
-Requires-Dist: transformers<=5.5.3,>=4.48.3
 Requires-Dist: tree-sitter<0.26,>=0.25.2
 Requires-Dist: tree-sitter-java<0.24,>=0.23.5
 Requires-Dist: unidiff<1,>=0.7.3

{java_codebase_rag-0.2.2 → java_codebase_rag-0.3.1}/ast_java.py

@@ -83,7 +83,7 @@ _DTO_LOMBOK_ANNOTATIONS: frozenset[str] = frozenset({
 # Phase 11: `EDGE_SCHEMA` in `java_ontology.py` (canonical edge navigation schema; v14 re-index).
 # Phase 12: CALLS `callee_declaring_role`, supertype-walk dedup, pass3 unresolved counters (v15 re-index).
 # Bumps whenever extraction / enrichment semantics change.
-ONTOLOGY_VERSION = 15
+ONTOLOGY_VERSION = 16
 
 ROLE_ANNOTATIONS: dict[str, str] = {
     # Spring Web
@@ -2732,6 +2732,19 @@ def infer_role(annotation_names: Iterable[str]) -> str:
     return "OTHER"
 
 
+def _type_injects_messaging(type_decl: "TypeDecl") -> bool:
+    """True when the type injects a messaging template via field or constructor."""
+    for fld in type_decl.fields:
+        if fld.type_name in _INJECTED_TYPES_TO_CAPABILITY:
+            return True
+    for method in type_decl.methods:
+        if method.is_constructor:
+            for p in method.parameters:
+                if p.type_name in _INJECTED_TYPES_TO_CAPABILITY:
+                    return True
+    return False
+
+
 def infer_role_for_type(type_decl: "TypeDecl") -> str:
     """Role inference that also detects DTO-like passive data carriers.
 
@@ -2763,6 +2776,11 @@ def infer_role_for_type(type_decl: "TypeDecl") -> str:
         if name.endswith(suffix) and name != suffix:
             return "DTO"
 
+    # Types injecting messaging templates are outbound callers (CLIENT role),
+    # symmetric with CONTROLLER covering both HTTP and messaging inbound.
+    if _type_injects_messaging(type_decl):
+        return "CLIENT"
+
     return "OTHER"
 
 

{java_codebase_rag-0.2.2 → java_codebase_rag-0.3.1}/build_ast_graph.py

@@ -70,13 +70,13 @@ log = logging.getLogger(__name__)
 
 _VERBOSE_STDERR_LOCK = threading.Lock()
 
-_PASS1_START = "[pass1] starting · parsing Java files under source root"
-_PASS2_START = "[pass2] starting · emitting EXTENDS / IMPLEMENTS / DECLARES rows"
-_PASS3_START = "[pass3] starting · call resolution (outgoing calls per site)"
-_PASS4_START = "[pass4] starting · route and EXPOSES extraction"
-_PASS5_START = "[pass5] starting · imperative HTTP_CALLS / ASYNC_CALLS edges"
-_PASS6_START = "[pass6] starting · cross-service call-edge matching"
-_WRITE_START = "[write] starting · writing Kuzu graph to disk"
+_PASS1_START = "[graph] pass 1 · parsing Java files"
+_PASS2_START = "[graph] pass 2 · emitting EXTENDS / IMPLEMENTS / DECLARES rows"
+_PASS3_START = "[graph] pass 3 · call resolution (outgoing calls per site)"
+_PASS4_START = "[graph] pass 4 · route and EXPOSES extraction"
+_PASS5_START = "[graph] pass 5 · imperative HTTP_CALLS / ASYNC_CALLS edges"
+_PASS6_START = "[graph] pass 6 · cross-service call-edge matching"
+_WRITE_START = "[graph] writing · Kuzu graph to disk"
 
 
 def _verbose_stderr_line(content: str) -> None:
@@ -104,7 +104,7 @@ class _VerbosePassHeartbeats:
             t0 = time.monotonic()
             while not stop.wait(timeout=5.0):
                 elapsed = int(time.monotonic() - t0)
-                _verbose_stderr_line(f"{tag} running … {elapsed}s elapsed")
+                _verbose_stderr_line(f"{tag} · {elapsed}s elapsed")
 
         self._thr = threading.Thread(target=worker, name=f"hb-{tag}", daemon=True)
         self._thr.start()
@@ -476,7 +476,7 @@ def pass1_parse(root: Path, tables: GraphTables, *, verbose: bool) -> dict[str,
             slow_sec = float(raw_slow)
         except ValueError:
             slow_sec = 0.0
-    with _VerbosePassHeartbeats("[pass1]", verbose=verbose):
+    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):
@@ -521,7 +521,7 @@ def pass1_parse(root: Path, tables: GraphTables, *, verbose: bool) -> dict[str,
     if verbose:
         elapsed = time.time() - t0
         _verbose_stderr_line(
-            f"[pass1] parsed {n_files} files in {elapsed:.2f}s: "
+            f"[graph] pass 1 · parsed {n_files} files in {elapsed:.2f}s: "
             f"{len(tables.types)} types, {len(tables.members)} members, "
             f"{tables.parse_errors} parse errors, {tables.skipped_files} skipped",
         )
@@ -759,7 +759,7 @@ def pass2_edges(tables: GraphTables, asts: dict[str, JavaFileAst], *, verbose: b
     seen_inj: set[tuple[str, str, str, str]] = set()
     if verbose:
         _verbose_stderr_line(_PASS2_START)
-    with _VerbosePassHeartbeats("[pass2]", verbose=verbose):
+    with _VerbosePassHeartbeats("[graph] pass 2", verbose=verbose):
         for fqn, entry in tables.types.items():
             ast = asts.get(entry.file_path)
             if ast is None:
@@ -769,7 +769,7 @@ def pass2_edges(tables: GraphTables, asts: dict[str, JavaFileAst], *, verbose: b
     if verbose:
         elapsed = time.time() - t0
         _verbose_stderr_line(
-            f"[pass2] emitted {len(tables.extends_rows)} EXTENDS, "
+            f"[graph] pass 2 · emitted {len(tables.extends_rows)} EXTENDS, "
             f"{len(tables.implements_rows)} IMPLEMENTS, "
             f"{len(tables.injects_rows)} INJECTS, "
             f"{len(tables.phantoms)} phantoms in {elapsed:.2f}s",
@@ -1432,7 +1432,7 @@ def pass3_calls(tables: GraphTables, asts: dict[str, JavaFileAst], *, verbose: b
         _verbose_stderr_line(_PASS3_START)
     _build_member_indexes(tables)
     stats = CallResolutionStats()
-    with _VerbosePassHeartbeats("[pass3]", verbose=verbose):
+    with _VerbosePassHeartbeats("[graph] pass 3", verbose=verbose):
         for rel_path, file_ast in asts.items():
             try:
                 _process_file_calls(file_ast, rel_path, tables, stats)
@@ -1455,7 +1455,7 @@ def pass3_calls(tables: GraphTables, asts: dict[str, JavaFileAst], *, verbose: b
     )
     log.info(msg)
     if verbose:
-        _verbose_stderr_line(f"[pass3] {msg}")
+        _verbose_stderr_line(f"[graph] pass 3 · {msg}")
 
 
 _PATH_VAR_SEG = re.compile(r"^\{([^:{}]+)(?::([^}]*))?\}$")  # whole path segment
@@ -1586,7 +1586,7 @@ def pass4_routes(
     meta_chain = collect_annotation_meta_chain(prs)
     if verbose:
         _verbose_stderr_line(_PASS4_START)
-    with _VerbosePassHeartbeats("[pass4]", verbose=verbose):
+    with _VerbosePassHeartbeats("[graph] pass 4", verbose=verbose):
 
         for ast in asts.values():
             stats.routes_skipped_unresolved += ast.routes_skipped_unresolved
@@ -1710,7 +1710,7 @@ def pass4_routes(
     )
     log.info(msg)
     if verbose:
-        _verbose_stderr_line(f"[pass4] {msg}")
+        _verbose_stderr_line(f"[graph] pass 4 · {msg}")
 
 
 def pass5_imperative_edges(
@@ -1763,7 +1763,7 @@ def pass5_imperative_edges(
 
     if verbose:
         _verbose_stderr_line(_PASS5_START)
-    with _VerbosePassHeartbeats("[pass5]", verbose=verbose):
+    with _VerbosePassHeartbeats("[graph] pass 5", verbose=verbose):
         for member in sorted(tables.members, key=lambda x: x.node_id):
             if member.decl.is_constructor:
                 continue
@@ -2018,7 +2018,7 @@ def pass5_imperative_edges(
         http_strategy = dict(sorted(tables.call_edge_stats.http_calls_by_strategy.items()))
         async_strategy = dict(sorted(tables.call_edge_stats.async_calls_by_strategy.items()))
         _verbose_stderr_line(
-            f"[pass5] HTTP_CALLS: {len(tables.http_call_rows)} edges, "
+            f"[graph] pass 5 · HTTP_CALLS: {len(tables.http_call_rows)} edges, "
             f"ASYNC_CALLS: {len(tables.async_call_rows)} edges; "
             f"http_by_client_kind={http_client}, async_by_client_kind={async_client}, "
             f"http_by_strategy={http_strategy}, async_by_strategy={async_strategy}",
@@ -2165,7 +2165,7 @@ def pass6_match_edges(
 
     if verbose:
         _verbose_stderr_line(_PASS6_START)
-    with _VerbosePassHeartbeats("[pass6]", verbose=verbose):
+    with _VerbosePassHeartbeats("[graph] pass 6", verbose=verbose):
         for row in tables.http_call_rows:
             if row.match != "unresolved":
                 continue
@@ -2317,14 +2317,14 @@ def pass6_match_edges(
             first_http = ", ".join(suppressed_auto_cross_http)
             first_async = ", ".join(suppressed_auto_cross_async)
             _verbose_stderr_line(
-                f"[pass6] cross_service_resolution=brownfield_only:\n"
+                f"[graph] pass 6 · cross_service_resolution=brownfield_only:\n"
                 f"        {n_bf} cross_service edges from brownfield layers,\n"
                 f"        {suppressed_auto_cross_count} auto-cross-service candidates suppressed -> unresolved\n"
                 f"        (first 5 http: {first_http})\n"
                 f"        (first 5 async: {first_async})",
             )
         _verbose_stderr_line(
-            f"[pass6] http_match={dict(sorted(tables.call_edge_stats.http_calls_match_breakdown.items()))}, "
+            f"[graph] pass 6 · http_match={dict(sorted(tables.call_edge_stats.http_calls_match_breakdown.items()))}, "
             f"async_match={dict(sorted(tables.call_edge_stats.async_calls_match_breakdown.items()))}, "
             f"cross_service_calls_total={tables.call_edge_stats.cross_service_calls_total}",
         )
@@ -3004,7 +3004,7 @@ def write_kuzu(
         )
     if verbose:
         _verbose_stderr_line(_WRITE_START)
-    with _VerbosePassHeartbeats("[write]", verbose=verbose):
+    with _VerbosePassHeartbeats("[graph] writing", verbose=verbose):
         db_path.parent.mkdir(parents=True, exist_ok=True)
         db = kuzu.Database(str(db_path))
         conn = kuzu.Connection(db)
@@ -3018,17 +3018,17 @@ def write_kuzu(
             meta_chain=meta_chain,
         )
         if verbose:
-            _verbose_stderr_line(f"[write] nodes written in {time.time() - t0:.2f}s")
+            _verbose_stderr_line(f"[graph] writing · nodes written in {time.time() - t0:.2f}s")
         _populate_declares_rows(tables)
         _populate_overrides_rows(tables)
         t1 = time.time()
         _write_edges(conn, tables)
         if verbose:
-            _verbose_stderr_line(f"[write] edges written in {time.time() - t1:.2f}s")
+            _verbose_stderr_line(f"[graph] writing · edges written in {time.time() - t1:.2f}s")
         t2 = time.time()
         _write_routes_and_exposes(conn, tables)
         if verbose:
-            _verbose_stderr_line(f"[write] routes/exposes written in {time.time() - t2:.2f}s")
+            _verbose_stderr_line(f"[graph] writing · routes/exposes written in {time.time() - t2:.2f}s")
         _write_meta(conn, tables, source_root)
         conn.close()
 
@@ -3073,7 +3073,7 @@ def main() -> int:
     pass6_match_edges(tables, verbose=args.verbose)
     write_kuzu(kuzu_path, tables, source_root=root, verbose=args.verbose)
     if args.verbose:
-        _verbose_stderr_line(f"[done] kuzu at {kuzu_path}")
+        _verbose_stderr_line(f"[graph] done · kuzu at {kuzu_path}")
     return 0
 
 

{java_codebase_rag-0.2.2 → java_codebase_rag-0.3.1}/java_codebase_rag/cli.py

@@ -100,19 +100,25 @@ _PIPELINE_SEP = "\u00b7"
 
 
 def _pipeline_header(subcommand: str, cfg: ResolvedOperatorConfig) -> None:
+    from java_codebase_rag.cli_format import bold
+
     root = cfg.source_root.resolve()
     idx = cfg.index_dir.resolve()
     print(
-        f"java-codebase-rag {subcommand} {_PIPELINE_SEP} source={root} {_PIPELINE_SEP} index={idx}",
+        bold(f"java-codebase-rag {subcommand} {_PIPELINE_SEP} source={root} {_PIPELINE_SEP} index={idx}"),
         file=sys.stderr,
         flush=True,
     )
 
 
 def _pipeline_footer(subcommand: str, started: float, exit_code: int) -> None:
+    from java_codebase_rag.cli_format import bold, styled_check, styled_cross
+
     elapsed = time.perf_counter() - started
+    marker = styled_check() if exit_code == 0 else styled_cross()
     print(
-        f"java-codebase-rag {subcommand} {_PIPELINE_SEP} finished in {elapsed:.2f}s (exit={exit_code})",
+        f"{marker} {bold(f'java-codebase-rag {subcommand} {_PIPELINE_SEP} finished in {elapsed:.2f}s')}"
+        + (f" (exit={exit_code})" if exit_code != 0 else ""),
         file=sys.stderr,
         flush=True,
     )
@@ -205,6 +211,22 @@ def _add_index_embedding_flags(p: argparse.ArgumentParser) -> None:
     p.add_argument("--embedding-device", type=str, default=None, help="Override SBERT_DEVICE / YAML embedding.device")
 
 
+def _add_verbosity_flags(p: argparse.ArgumentParser) -> None:
+    g = p.add_mutually_exclusive_group()
+    g.add_argument(
+        "--quiet", "-q",
+        action="store_true",
+        dest="quiet",
+        help="Suppress stderr progress relay; stdout payload unchanged.",
+    )
+    g.add_argument(
+        "--verbose", "-v",
+        action="store_true",
+        dest="verbose",
+        help="Show full subprocess output (Lance warnings, brownfield events, progress bars).",
+    )
+
+
 def _cmd_init(args: argparse.Namespace) -> int:
     cfg = _resolved_from_ns(args)
     _startup_hints(cfg)
@@ -227,10 +249,12 @@ def _cmd_init(args: argparse.Namespace) -> int:
 
     def work() -> int:
         env = cfg.subprocess_env()
+        verbose = bool(args.verbose)
         coco = run_cocoindex_update(
             env,
             full_reprocess=False,
             quiet=bool(args.quiet),
+            verbose=verbose,
             lance_project_root=None if args.quiet else cfg.source_root,
         )
         if coco.returncode != 0:
@@ -244,10 +268,13 @@ def _cmd_init(args: argparse.Namespace) -> int:
                 }
             )
             return 1
+        if not args.quiet:
+            print(file=sys.stderr, flush=True)
         g = run_build_ast_graph(
             source_root=cfg.source_root,
             kuzu_path=cfg.kuzu_path,
-            verbose=not args.quiet,
+            verbose=verbose,
+            quiet=bool(args.quiet),
             env=env,
         )
         if g.returncode != 0:
@@ -279,6 +306,7 @@ def _cmd_increment(args: argparse.Namespace) -> int:
             env,
             full_reprocess=False,
             quiet=bool(args.quiet),
+            verbose=bool(args.verbose),
             lance_project_root=None if args.quiet else cfg.source_root,
         )
         if coco.returncode != 0:
@@ -305,11 +333,12 @@ def _cmd_reprocess(args: argparse.Namespace) -> int:
 
     def work() -> int:
         env = cfg.subprocess_env()
+        verbose = bool(args.verbose)
         vectors_only = bool(getattr(args, "vectors_only", False))
         graph_only = bool(getattr(args, "graph_only", False))
 
         if vectors_only:
-            coco = run_cocoindex_update(env, full_reprocess=True, quiet=bool(args.quiet))
+            coco = run_cocoindex_update(env, full_reprocess=True, quiet=bool(args.quiet), verbose=verbose)
             if _is_cocoindex_preflight_blocker(coco):
                 payload: dict[str, Any] = {
                     "success": False,
@@ -345,7 +374,8 @@ def _cmd_reprocess(args: argparse.Namespace) -> int:
             g = run_build_ast_graph(
                 source_root=cfg.source_root,
                 kuzu_path=cfg.kuzu_path,
-                verbose=not args.quiet,
+                verbose=verbose,
+                quiet=bool(args.quiet),
                 env=env,
             )
             if _is_graph_preflight_blocker(g):
@@ -381,7 +411,7 @@ def _cmd_reprocess(args: argparse.Namespace) -> int:
 
         import server  # lazy: pulls sentence_transformers/torch/lancedb/kuzu
 
-        result = asyncio.run(server.run_refresh_pipeline(quiet=bool(args.quiet)))
+        result = asyncio.run(server.run_refresh_pipeline(quiet=bool(args.quiet), verbose=verbose))
         payload = result.model_dump()
         _emit_reprocess_outcome(payload)
         return _reprocess_exit_code(payload)
@@ -473,6 +503,8 @@ def _cmd_meta(args: argparse.Namespace) -> int:
     payload["index_dir"] = str(cfg.index_dir.resolve())
     payload["kuzu_path"] = str(cfg.kuzu_path.resolve())
     payload["index_dir_source"] = cfg.index_dir_source
+    payload["hints_enabled"] = cfg.hints_enabled
+    payload["hints_enabled_source"] = cfg.hints_enabled_source
     _emit(payload)
     return 0 if payload.get("success") else 2
 
@@ -612,11 +644,7 @@ def build_parser() -> argparse.ArgumentParser:
         ),
     )
     _add_index_embedding_flags(init)
-    init.add_argument(
-        "--quiet",
-        action="store_true",
-        help="Suppress stderr progress relay; stdout payload unchanged.",
-    )
+    _add_verbosity_flags(init)
     init.set_defaults(handler=_cmd_init)
 
     increment = subparsers.add_parser(
@@ -625,11 +653,7 @@ def build_parser() -> argparse.ArgumentParser:
         description="Runs cocoindex catch-up (no full reprocess). Does not rebuild Kuzu; see stderr warning.",
     )
     _add_index_embedding_flags(increment)
-    increment.add_argument(
-        "--quiet",
-        action="store_true",
-        help="Suppress stderr progress relay; stdout payload unchanged.",
-    )
+    _add_verbosity_flags(increment)
     increment.set_defaults(handler=_cmd_increment)
 
     reprocess = subparsers.add_parser(
@@ -641,11 +665,7 @@ def build_parser() -> argparse.ArgumentParser:
         ),
     )
     _add_index_embedding_flags(reprocess)
-    reprocess.add_argument(
-        "--quiet",
-        action="store_true",
-        help="Suppress stderr progress relay; stdout payload unchanged.",
-    )
+    _add_verbosity_flags(reprocess)
     _rex = reprocess.add_mutually_exclusive_group()
     _rex.add_argument(
         "--vectors-only",
@@ -667,8 +687,9 @@ def build_parser() -> argparse.ArgumentParser:
     _add_index_embedding_flags(erase)
     erase.add_argument("--yes", action="store_true", help="Confirm destructive deletion (required in CI)")
     erase.add_argument(
-        "--quiet",
+        "--quiet", "-q",
         action="store_true",
+        dest="quiet",
         help="Suppress stderr progress relay; stdout payload unchanged.",
     )
     erase.set_defaults(handler=_cmd_erase)

java_codebase_rag-0.3.1/java_codebase_rag/cli_format.py

@@ -0,0 +1,112 @@
+"""TTY-aware ANSI formatting for CLI stderr progress."""
+from __future__ import annotations
+
+import itertools
+import sys
+import threading
+import time
+
+_RESET = "\033[0m"
+_BOLD = "\033[1m"
+_DIM = "\033[2m"
+_GREEN = "\033[32m"
+_RED = "\033[31m"
+_CYAN = "\033[36m"
+
+CHECK = "✓"
+CROSS = "✗"
+
+_SPINNER_FRAMES = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+
+_NOISE_CONTAINS: tuple[bytes, ...] = (
+    b"lance::",
+    b"FutureWarning",
+    b"Loading weights:",
+    b'"event": "brownfield-',
+    b"unknown producer source strategy",
+    b"unknown client source strategy",
+)
+
+
+def is_noise_line(line: bytes) -> bool:
+    return any(p in line for p in _NOISE_CONTAINS)
+
+
+def stderr_is_tty() -> bool:
+    return hasattr(sys.stderr, "isatty") and sys.stderr.isatty()
+
+
+def _styled(text: str, *codes: str) -> str:
+    if not stderr_is_tty():
+        return text
+    return "".join(codes) + text + _RESET
+
+
+def bold(text: str) -> str:
+    return _styled(text, _BOLD)
+
+
+def dim(text: str) -> str:
+    return _styled(text, _DIM)
+
+
+def green(text: str) -> str:
+    return _styled(text, _GREEN)
+
+
+def red(text: str) -> str:
+    return _styled(text, _RED)
+
+
+def cyan(text: str) -> str:
+    return _styled(text, _CYAN)
+
+
+def bold_green(text: str) -> str:
+    return _styled(text, _BOLD, _GREEN)
+
+
+def bold_red(text: str) -> str:
+    return _styled(text, _BOLD, _RED)
+
+
+def bold_cyan(text: str) -> str:
+    return _styled(text, _BOLD, _CYAN)
+
+
+def styled_check() -> str:
+    return green(CHECK) if stderr_is_tty() else CHECK
+
+
+def styled_cross() -> str:
+    return red(CROSS) if stderr_is_tty() else CROSS
+
+
+class Spinner:
+    """Braille spinner that overwrites the current stderr line until stopped."""
+
+    def __init__(self, label: str) -> None:
+        self._label = label
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def start(self) -> None:
+        self._thread = threading.Thread(target=self._run, name="spinner", daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=2.0)
+        sys.stderr.buffer.write(b"\r\x1b[2K")
+        sys.stderr.buffer.flush()
+
+    def _run(self) -> None:
+        frames = itertools.cycle(_SPINNER_FRAMES)
+        t0 = time.monotonic()
+        while not self._stop.wait(0.3):
+            elapsed = time.monotonic() - t0
+            frame = next(frames)
+            line = f"\r{frame} {self._label} · {elapsed:.0f}s"
+            sys.stderr.buffer.write(line.encode())
+            sys.stderr.buffer.flush()

java_codebase_rag-0.3.1/java_codebase_rag/cli_progress.py

@@ -0,0 +1,98 @@
+"""CLI-owned stderr progress lines (shared by server reprocess path and pipeline helpers)."""
+from __future__ import annotations
+
+import asyncio
+import sys
+
+from java_codebase_rag.cli_format import bold_cyan, is_noise_line, styled_check, styled_cross
+
+
+def emit_vectors_start() -> None:
+    print(
+        bold_cyan("[vectors]") + " running · cocoindex update",
+        file=sys.stderr,
+        flush=True,
+    )
+
+
+def emit_vectors_finish(*, elapsed_s: float, exit_code: int) -> None:
+    marker = styled_check() if exit_code == 0 else styled_cross()
+    print(
+        f"{marker} {bold_cyan('[vectors]')} finished · {elapsed_s:.2f}s"
+        + (f" (exit={exit_code})" if exit_code != 0 else ""),
+        file=sys.stderr,
+        flush=True,
+    )
+
+
+class _AsyncLineFilter:
+    """Buffers byte chunks and relays only non-noise lines to stderr (async drain path)."""
+
+    def __init__(self) -> None:
+        self._buf = bytearray()
+        self._suppress_next = False
+
+    def feed(self, chunk: bytes) -> None:
+        self._buf.extend(chunk)
+        while b"\n" in self._buf:
+            line, self._buf = self._buf.split(b"\n", 1)
+            line += b"\n"
+            noise = is_noise_line(line)
+            if noise:
+                self._suppress_next = True
+                continue
+            if self._suppress_next and line[:1] in (b" ", b"\t"):
+                continue
+            self._suppress_next = False
+            sys.stderr.buffer.write(line)
+            sys.stderr.buffer.flush()
+
+    def flush(self) -> None:
+        if self._buf:
+            if not is_noise_line(self._buf):
+                sys.stderr.buffer.write(bytes(self._buf))
+                sys.stderr.buffer.flush()
+            self._buf.clear()
+        self._suppress_next = False
+
+
+async def accumulate_and_relay_subprocess_streams(
+    proc: asyncio.subprocess.Process,
+    *,
+    relay: bool,
+    verbose: bool = True,
+) -> tuple[bytes, bytes]:
+    """Read stdout and stderr until EOF; optionally copy non-noise stderr chunks to stderr."""
+    stdout = proc.stdout
+    stderr = proc.stderr
+    if stdout is None or stderr is None:
+        raise RuntimeError("subprocess must be created with stdout=PIPE and stderr=PIPE")
+
+    out_buf = bytearray()
+    err_buf = bytearray()
+    filt = _AsyncLineFilter() if (relay and not verbose) else None
+
+    async def drain_stdout(reader: asyncio.StreamReader, target: bytearray) -> None:
+        while True:
+            chunk = await reader.read(65536)
+            if not chunk:
+                break
+            target.extend(chunk)
+
+    async def drain_stderr(reader: asyncio.StreamReader, target: bytearray) -> None:
+        while True:
+            chunk = await reader.read(65536)
+            if not chunk:
+                break
+            target.extend(chunk)
+            if filt is not None:
+                filt.feed(chunk)
+            elif relay:
+                sys.stderr.buffer.write(chunk)
+                sys.stderr.buffer.flush()
+
+    await asyncio.gather(drain_stdout(stdout, out_buf), drain_stderr(stderr, err_buf))
+    await proc.wait()
+    if filt is not None:
+        filt.flush()
+    return bytes(out_buf), bytes(err_buf)