Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

16.2 KB
Raw Blame
"""Data-shape grounding: answer "what fields does X contain" from source.

A data-shape question names a data blob and asks for its field set. Instead of
gating to a best_guesses pointer list (which triggers the agent's Read/get_symbol
drill), the tool mines the field set straight from source: a documented ``{...}``
shape near the identifier (authoritative -> high) or the concrete keys consumers
pull off the parsed value (usage-mined -> medium).

These tests use synthetic repos with varied identifiers and shapes so nothing is
tuned to any one real question. The precision contract is the load-bearing part:
every reported field must be a quoted token from source, and an identifier with
no groundable shape must fall through (return None), never a fabricated field.
"""

from __future__ import annotations

import subprocess
from pathlib import Path

import pytest

from repowise.core.exclusion import build_exclude_spec
from repowise.server.mcp_server.tool_answer.data_shape import (
    _grep_identifier_files,
    _is_data_shape_question,
    mine_data_shape,
)


def _write(root: Path, rel: str, body: str) -> None:
    p = root / rel
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(body, encoding="utf-8")


# --- Question detection ---------------------------------------------------


@pytest.mark.parametrize(
    "question,ids,expected",
    [
        (
            "What fields does each entry in co_change_partners_json contain?",
            {"co_change_partners_json"},
            True,
        ),
        ("what keys are in the blame_record blob", {"blame_record"}, True),
        ("what columns does the health_metric_row have", {"health_metric_row"}, True),
        ("describe the schema of GitCommitMeta", {"GitCommitMeta"}, True),
        ("what does each record in owner_stats consist of", {"owner_stats"}, True),
        # Mechanism questions carry no shape cue -> not data-shape.
        ("how does co_change_partners_json get populated", {"co_change_partners_json"}, False),
        ("where is the coupling graph assembled", set(), False),
        # A shape cue with no named identifier can't ground -> not data-shape.
        ("what fields are typical in a config", set(), False),
    ],
)
def test_detection(question, ids, expected):
    assert _is_data_shape_question(question, ids) is expected


# --- Where the cue is allowed to sit --------------------------------------
#
# The cue is a cheap gate and the miner is the precision gate, which holds for a
# question someone typed and fails for a body someone pasted. A bug report or a
# stack trace mentions `field` or `key` in passing, the identifier extractor
# always finds something to ground on, and the caller who wanted files gets a
# field list back before retrieval has run at all. So the cue has to sit in the
# question's own interrogative clause.

_TICKET = (
    "AuthenticationForm's username field doesn't set maxlength HTML attribute.\n"
    "Description\n"
    "AuthenticationForm's username field doesn't render with maxlength anymore.\n"
    "Regression introduced in #27515 and 5ceaf14686ce626404afb6a5fbd3d8286410bf13.\n"
    "The widget_attrs() call no longer passes the max_length through, so the\n"
    "rendered input element is missing the attribute it used to carry, and every\n"
    "template that relied on it now renders an unbounded text box instead.\n"
)


@pytest.mark.parametrize(
    "question,ids,expected",
    [
        # A long report whose shape noun is incidental. The old cue fired here.
        (_TICKET, {"AuthenticationForm", "widget_attrs"}, False),
        # Same report, with a real data-shape question appended. The question is
        # the question, however much prose precedes it.
        (
            _TICKET + "\nWhat fields does each entry in widget_attrs contain?",
            {"AuthenticationForm", "widget_attrs"},
            True,
        ),
        # Same report, with a question that is not about shape. The shape nouns
        # in the body must not be borrowed by an unrelated interrogative.
        (
            _TICKET + "\nWas this deliberate?",
            {"AuthenticationForm", "widget_attrs"},
            False,
        ),
        # A short unpunctuated body IS the question: people type this way, and
        # demanding a `?` of them would break the case the fast path is for.
        ("what keys does session_payload carry", {"session_payload"}, True),
    ],
)
def test_cue_must_sit_in_an_interrogative_clause(question, ids, expected):
    assert _is_data_shape_question(question, ids) is expected


def test_long_pasted_body_with_no_question_never_fires():
    """The product argument, independent of any benchmark.

    An agent pasting a stack trace into `get_answer` wants the files. Gate 2
    returns before the cache and before retrieval, so firing here is the
    thinnest possible answer to the broadest possible ask.
    """
    trace = (
        'Traceback (most recent call last):\n'
        '  File "app/models.py", line 88, in save\n'
        '    self.full_clean()\n'
        'ValidationError: {"schema": ["This field is required."]}\n'
    ) * 8
    assert len(trace) > 400
    assert _is_data_shape_question(trace, {"full_clean", "ValidationError"}) is False


# --- Documented shape (authoritative -> high) -----------------------------


def test_docstring_brace_shape_high_confidence(tmp_path):
    """A {...} field shape in a docstring near the identifier grounds high."""
    _write(
        tmp_path,
        "pkg/models.py",
        '''\
class GitMeta:
    """Row model.

    ``blame_record_json`` is the raw column: a JSON list of
    ``{"author", "commit_sha", "line_count"}`` blame records.
    """

    blame_record_json: str
''',
    )
    out = mine_data_shape(tmp_path, {"blame_record_json"})
    assert out is not None
    assert out["grounding"] == "docstring"
    assert out["confidence"] == "high"
    assert out["fields"] == ["author", "commit_sha", "line_count"]
    assert out["sources"][0]["file"] == "pkg/models.py"
    assert out["sources"][0]["kind"] == "docstring"


def test_comment_brace_shape(tmp_path):
    """A shape documented in a line comment also grounds (not just docstrings)."""
    _write(
        tmp_path,
        "pkg/store.py",
        """\
def load(raw):
    # owner_stats rows look like {"owner", "files_touched", "last_seen"}
    return parse(raw)
""",
    )
    out = mine_data_shape(tmp_path, {"owner_stats"})
    assert out is not None
    assert out["grounding"] == "docstring"
    assert set(out["fields"]) == {"owner", "files_touched", "last_seen"}


def test_executable_dict_literal_is_not_authoritative(tmp_path):
    """A bare dict literal in code (no doc context) is not a documented shape.

    It has quoted keys, but it's one construction site, not a declared schema.
    The access-mining path may still pick up keys, but the doc path must not
    mislabel an executable literal as authoritative/high.
    """
    _write(
        tmp_path,
        "pkg/build.py",
        """\
def build(widget_payload, count):
    result = {"kind": widget_payload, "n": count, "ok": True}
    return result
""",
    )
    out = mine_data_shape(tmp_path, {"widget_payload"})
    # Nothing is documented and the identifier is a scalar arg (no key access),
    # so this must fall through rather than claim {kind,n,ok} as its shape.
    assert out is None


# --- Access-mined shape (usage -> medium) ---------------------------------


def test_access_mined_shape_medium_when_no_doc(tmp_path):
    """With no documented shape, consistent key accesses ground at medium."""
    _write(
        tmp_path,
        "pkg/consume.py",
        """\
def summarize(partner_records):
    for entry in iter_records(partner_records):
        name = entry.get("file_path")
        weight = entry["co_change_count"]
        stamp = entry.get("last_seen")
    return name, weight, stamp
""",
    )
    out = mine_data_shape(tmp_path, {"partner_records"})
    assert out is not None
    assert out["grounding"] == "access"
    assert out["confidence"] == "medium"
    assert set(out["fields"]) == {"file_path", "co_change_count", "last_seen"}


def test_direct_subscript_on_identifier(tmp_path):
    """When the identifier IS the dict variable, direct key access grounds it."""
    _write(
        tmp_path,
        "pkg/direct.py",
        """\
def read(config_blob):
    host = config_blob["host"]
    port = config_blob.get("port")
    return host, port
""",
    )
    out = mine_data_shape(tmp_path, {"config_blob"})
    assert out is not None
    assert out["grounding"] == "access"
    assert set(out["fields"]) == {"host", "port"}


# --- Precision guards -----------------------------------------------------


def test_no_shape_returns_none(tmp_path):
    """An identifier that names no blob shape falls through (no fabrication)."""
    _write(tmp_path, "pkg/plain.py", "def process_records(x):\n    return x + 1\n")
    assert mine_data_shape(tmp_path, {"process_records"}) is None


def test_single_field_is_too_weak(tmp_path):
    """A one-field shape is below the min-fields floor -> abstain."""
    _write(
        tmp_path,
        "pkg/thin.py",
        """\
def read(thin_blob):
    # thin_blob entries are {"only_field"}
    return thin_blob
""",
    )
    assert mine_data_shape(tmp_path, {"thin_blob"}) is None


def test_generic_short_identifier_skipped(tmp_path):
    """Short/generic identifiers are not specific enough to ground on."""
    _write(
        tmp_path,
        "pkg/rows.py",
        """\
def go(row):
    a = row.get("x")
    b = row.get("y")
    return a, b
""",
    )
    # "row" is below the specificity floor (too short, no underscore/camel).
    assert mine_data_shape(tmp_path, {"row"}) is None


def test_absent_identifier_returns_none(tmp_path):
    """An identifier that appears nowhere in source grounds nothing."""
    _write(tmp_path, "pkg/a.py", "x = 1\n")
    assert mine_data_shape(tmp_path, {"nonexistent_blob_xyz"}) is None


def test_doc_beats_access(tmp_path):
    """When both a doc shape and accesses exist, the doc shape wins (high)."""
    _write(
        tmp_path,
        "pkg/both.py",
        '''\
class M:
    """``event_payload_json`` is a list of
    ``{"kind", "ts", "actor"}`` event records."""

    event_payload_json: str


def consume(event_payload_json):
    for e in parse(event_payload_json):
        k = e.get("kind")
        t = e.get("ts")
    return k, t
''',
    )
    out = mine_data_shape(tmp_path, {"event_payload_json"})
    assert out is not None
    assert out["grounding"] == "docstring"
    assert out["confidence"] == "high"
    assert out["fields"] == ["kind", "ts", "actor"]


# --- Alias divergence (doc omits a key consumers read as a fallback) -------


def test_documented_shape_surfaces_alias_fallback(tmp_path):
    """A doc shape that omits an ``or``-fallback alias must surface the alias.

    The docstring is authoritative for what it declares, but if a consumer reads
    ``x.get("weight_json") or x.get("weight")`` the ``weight`` alias is a real key
    the tool must not hide behind "no verification needed".
    """
    _write(
        tmp_path,
        "pkg/models.py",
        '''\
class M:
    """``metric_rows_json`` is a JSON list of
    ``{"file_path", "weight_json", "ts"}`` metric records."""

    metric_rows_json: str
''',
    )
    _write(
        tmp_path,
        "pkg/consume.py",
        """\
def use(metric_rows_json):
    for row in parse(metric_rows_json):
        w = row.get("weight_json") or row.get("weight") or 0
    return w
""",
    )
    out = mine_data_shape(tmp_path, {"metric_rows_json"})
    assert out is not None
    assert out["grounding"] == "docstring"
    assert out["fields"] == ["file_path", "weight_json", "ts"]
    aliases = {a["field"] for a in out.get("also_accessed", [])}
    assert aliases == {"weight"}
    assert out["also_accessed"][0]["file"] == "pkg/consume.py"


def test_no_alias_key_when_none_diverges(tmp_path):
    """A clean documented shape with no fallback alias carries no also_accessed."""
    _write(
        tmp_path,
        "pkg/clean.py",
        '''\
class M:
    """``clean_rows_json`` is a JSON list of
    ``{"file_path", "score", "ts"}`` records."""

    clean_rows_json: str


def use(clean_rows_json):
    for r in parse(clean_rows_json):
        s = r.get("score")
    return s
''',
    )
    out = mine_data_shape(tmp_path, {"clean_rows_json"})
    assert out is not None
    assert "also_accessed" not in out


def test_alias_precision_ignores_cross_record_comention(tmp_path):
    """A documented key co-mentioned on a different record is NOT an alias.

    ``meta["other_count"] = src[meta["file_path"]]`` reads a documented field
    (``file_path``) and another key on the same line, but it's an assignment on an
    unrelated record, not an ``or`` fallback - it must not be reported as an alias.
    """
    _write(
        tmp_path,
        "pkg/models.py",
        '''\
class M:
    """``rows_json`` is a JSON list of
    ``{"file_path", "amount", "ts"}`` records."""

    rows_json: str
''',
    )
    _write(
        tmp_path,
        "pkg/enrich.py",
        """\
def enrich(rows_json, meta, src):
    for row in parse(rows_json):
        amount = row.get("amount")
    meta["other_count"] = src[meta["file_path"]]
    return amount, meta
""",
    )
    out = mine_data_shape(tmp_path, {"rows_json"})
    assert out is not None
    assert "also_accessed" not in out


def test_identifier_fan_out_is_capped(tmp_path, monkeypatch):
    """A pasted body naming dozens of identifiers greps only the longest few."""
    from repowise.server.mcp_server.tool_answer import data_shape as ds

    grepped: list[str] = []

    def fake_grep(_root, identifier, _spec=None):
        grepped.append(identifier)
        return []

    monkeypatch.setattr(ds, "_grep_identifier_files", fake_grep)
    ids = {f"blob_{'x' * i}" for i in range(2, 30)}
    assert ds.mine_data_shape(tmp_path, ids) is None
    assert grepped == sorted(ids, key=len, reverse=True)[: ds._MAX_SHAPE_IDENTIFIERS]


def test_none_repo_root_is_safe():
    assert mine_data_shape(None, {"anything_json"}) is None


# --- Gitignore / exclude_patterns are honoured (live-grep fallback) --------


def test_grep_skips_gitignored_file(tmp_path):
    """The ``--no-index`` filesystem grep must not return a gitignored path.

    ``tmp_path`` is not a git checkout, so ``_grep_identifier_files`` retries
    with ``git grep --no-index`` (which ignores ``.gitignore``). The compiled
    exclude spec must drop the ignored hit while keeping the tracked one.
    """
    _write(tmp_path, ".gitignore", "ignored/\n")
    _write(tmp_path, "ignored/leak.py", "x = leak_record_json\n")
    _write(tmp_path, "pkg/real.py", "y = leak_record_json\n")
    spec = build_exclude_spec(tmp_path)
    files = _grep_identifier_files(tmp_path, "leak_record_json", spec)
    assert "pkg/real.py" in files
    assert "ignored/leak.py" not in files


def test_grep_paths_ignore_user_color_config(tmp_path):
    """Parsed ``git grep -l`` paths must stay stable under color.ui=always."""
    _write(tmp_path, "pkg/models.py", "value = clean_rows_json\n")
    subprocess.run(["git", "init", "-q"], cwd=tmp_path, check=True)
    subprocess.run(["git", "config", "color.ui", "always"], cwd=tmp_path, check=True)
    subprocess.run(["git", "add", "pkg/models.py"], cwd=tmp_path, check=True)

    files = _grep_identifier_files(tmp_path, "clean_rows_json")

    assert files == ["pkg/models.py"]


def test_mine_data_shape_ignores_gitignored_leak(tmp_path):
    """A gitignored stale copy must never be the shape source served."""
    _write(tmp_path, ".gitignore", "ignored/\n")
    # The gitignored copy documents a stale/wrong shape.
    _write(
        tmp_path,
        "ignored/leak.py",
        '''\
class Stale:
    """``leak_record_json`` is a JSON list of
    ``{"stale_one", "stale_two", "stale_three"}`` records."""

    leak_record_json: str
''',
    )
    # The tracked file documents the real shape.
    _write(
        tmp_path,
        "pkg/models.py",
        '''\
class Real:
    """``leak_record_json`` is a JSON list of
    ``{"author", "commit_sha", "line_count"}`` records."""

    leak_record_json: str
''',
    )
    out = mine_data_shape(tmp_path, {"leak_record_json"})
    assert out is not None
    assert out["fields"] == ["author", "commit_sha", "line_count"]
    # No served source may point at the gitignored copy.
    assert all(s["file"] != "ignored/leak.py" for s in out["sources"])