Function _run_rg

agent/src/opentrace_agent/cli/source_grep.py:164–240

Spawn ripgrep against *repo_root*; return ``(matches, truncated, error)``. Each entry in *matches* is a scrubbed line of the form ``[ ] : : ``; lines that don't match the expected `` : : `` shape are dropped. The docstri

(
    pattern: str,
    repo_id: str,
    repo_root: Path,
    include: str | None,
    max_count: int,
)

def _run_rg(
    pattern: str,
    repo_id: str,
    repo_root: Path,
    include: str | None,
    max_count: int,
) -> tuple[list[str], bool, str | None]:
    """Spawn ripgrep against *repo_root*; return ``(matches, truncated, error)``.

    Each entry in *matches* is a scrubbed line of the form
    ``[<repo_id>] <repo-relative-path>:<line>:<content>``; lines that
    don&#x27;t match the expected ``<abs-path>:<line>:<content>`` shape are
    dropped. The docstring promise is that absolute indexing-host
    paths never reach the caller, so anything we can&#x27;t safely rewrite
    (binary-file notes, permission warnings, malformed lines) is
    filtered out rather than echoed verbatim.

    *max_count* is enforced **per repo** — rg&#x27;s own ``--max-count`` is
    a per-file cap, so a repo with N matching files would otherwise
    return up to ``N × max_count`` lines. We pass it through as a
    safety bound on per-file work and then truncate the joined result
    to ``max_count`` here. *truncated* is True when more matches
    existed than were returned.
    """
    cmd = [
        "rg",
        "--no-heading",
        "--line-number",
        # rg's ``--max-count`` is a per-file cap. The +1 ensures a
        # single file with > max_count matches yields enough rows to
        # trip the post-slice's ``len(scrubbed) > max_count`` overflow
        # check, which then slices the joined output back to max_count.
        "--max-count",
        str(max_count + 1),
    ]
    if include:
        cmd.extend(["--glob", include])
    # `--` separator: defends against patterns that begin with `-`
    # being interpreted as an rg flag.
    cmd.append("--")
    cmd.append(pattern)
    cmd.append(str(repo_root))

    try:
        proc = subprocess.run(
            cmd,
            capture_output=True,
            text=True,
            timeout=_RG_TIMEOUT_SECONDS,
        )
    except subprocess.TimeoutExpired:
        return [], False, f"ripgrep timed out after {_RG_TIMEOUT_SECONDS}s."

    # rg exit code 1 means "no matches" — that's a normal outcome,
    # not an error. Anything else (2 = invalid args/regex, 130 =
    # signal, etc.) is a real failure worth surfacing.
    if proc.returncode == 1:
        return [], False, None