Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/architecture/code-index-architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -351,6 +351,11 @@ the matched files. Lessons are read after cached match data, within the request'
remaining deadline. Presence queries and uncovered paths carry none;
`include_lessons=false` skips the read.

`code.enclosing` carries the same file lessons for resolved locations. Repeated
locations share one file read; unresolved locations bring no lessons. The caller's
readable memory namespaces, narrowed-token refusal, timeout and token cap apply
through the shared result enrichment. Empty lesson fields stay off the wire.

Search and grep rank candidate lessons across all selected files by query-term
overlap after constraints and pinned rows. English inflections share stems; equal
matches keep path order, then the listing's confidence and recency order.
Expand Down
4 changes: 4 additions & 0 deletions docs/reference/operations/code.md
Original file line number Diff line number Diff line change
Expand Up @@ -583,6 +583,8 @@ Batched `path:line` -> enclosing function.

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `include_lessons` | `bool` | `True` | Attach `lessons`: the memories about the answer's top files (for code.context_pack, a `task` briefing's only). |
| `lesson_namespaces` | `list[str]` | *(computed)* | The memory namespaces `lessons` reads besides the repository's team rules (over MCP the caller's memory home, filled in); one the caller cannot read is skipped. |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
Expand All @@ -596,6 +598,8 @@ Batched `path:line` -> enclosing function.

| Output field | Type | Meaning |
| --- | --- | --- |
| `lessons` | `list[dict[str, Any]]` | The memories about the answer's top files, best first, capped at `code_result_lessons_tokens`; each row {path, memory_key, namespace, excerpt, code_state}, with `changed_since` and `supersedes_key` when they apply. |
| `lessons_left_out` | `int` | How many rows about those files the lessons' token cap or a cut left out, with the rows another row read for the answer supersedes. |
| `results` | `list[dict[str, Any]]` | one entry per input location, input order preserved: {path, line, symbol, symbol_id, qualified_name, signature, tier, kind, start_line, end_line} kind is "function" / "method" / "fixture" for a line inside a function body; "class"… |
| `resolved` | `int` | Locations that landed inside a function, type, or document section. |
| `paths_indexed` | `int` | distinct input paths that have any symbol rows |
Expand Down
6 changes: 6 additions & 0 deletions sdk/python/loom/ops.py
Original file line number Diff line number Diff line change
Expand Up @@ -6376,6 +6376,8 @@ class CodeCoverageClaimOutput(TypedDict, total=False):
class CodeEnclosingInput(TypedDict, total=False):
"Batched `path:line` -> enclosing function. Built for the grep shim:"

include_lessons: NotRequired[bool]
lesson_namespaces: NotRequired[list[str]]
org: NotRequired[str]
namespace: NotRequired[str]
agent: NotRequired[str]
Expand All @@ -6391,6 +6393,8 @@ class CodeEnclosingInput(TypedDict, total=False):
class CodeEnclosingBody(TypedDict, total=False):
"Batched `path:line` -> enclosing function. Built for the grep shim:"

include_lessons: NotRequired[bool]
lesson_namespaces: NotRequired[list[str]]
org: NotRequired[str]
namespace: NotRequired[str]
agent: NotRequired[str]
Expand All @@ -6404,6 +6408,8 @@ class CodeEnclosingBody(TypedDict, total=False):


class CodeEnclosingOutput(TypedDict, total=False):
lessons: NotRequired[list[dict[str, Any]]]
lessons_left_out: NotRequired[int]
results: Required[list[dict[str, Any]]]
resolved: Required[int]
paths_indexed: Required[int]
Expand Down
4 changes: 4 additions & 0 deletions sdk/typescript/src/generated/ops.ts
Original file line number Diff line number Diff line change
Expand Up @@ -761,6 +761,8 @@ export interface CodeCoverageClaimOutput {
}

export interface CodeEnclosingInput {
include_lessons?: boolean;
lesson_namespaces?: string[];
org?: string;
namespace?: string;
agent?: string;
Expand All @@ -774,6 +776,8 @@ export interface CodeEnclosingInput {
}

export interface CodeEnclosingOutput {
lessons?: Array<Record<string, unknown>>;
lessons_left_out?: number;
results: Array<Record<string, unknown>>;
resolved: number;
paths_indexed: number;
Expand Down
4 changes: 2 additions & 2 deletions server/code/api/models_navigation.py
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ def _drop_empty_head(self, handler: SerializerFunctionWrapHandler) -> dict[str,
# ============================================================


class CodeEnclosingInput(_CodeIdentity):
class CodeEnclosingInput(_CodeIdentity, _ResultLessons):
"""Batched `path:line` -> enclosing function. Built for the grep shim:
real grep stays exact, then ONE round-trip names the function every hit
sits in — the "which function is this line in?" question that otherwise
Expand Down Expand Up @@ -146,7 +146,7 @@ class CodeEnclosingInput(_CodeIdentity):
neighbour_k: int = Field(default=5, ge=1, le=20)


class CodeEnclosingOutput(BaseModel):
class CodeEnclosingOutput(_LessonsOut):
# one entry per input location, input order preserved:
# {path, line, symbol, symbol_id, qualified_name, signature, tier, kind,
# start_line, end_line}
Expand Down
2 changes: 1 addition & 1 deletion server/code/api/ops.py
Original file line number Diff line number Diff line change
Expand Up @@ -385,7 +385,7 @@
session_content=True,
input_model=CodeEnclosingInput,
output_model=CodeEnclosingOutput,
handler=handle_code_enclosing,
handler=result_lessons.WithLessons(handle_code_enclosing, result_lessons.enclosing_paths),
idempotent=True,
required_role=Role.VIEWER,
),
Expand Down
5 changes: 5 additions & 0 deletions server/code/app/result_lessons.py
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,11 @@ def outline_paths(_input: Any, out: Any) -> list[str]:
return [out.path]


def enclosing_paths(_input: Any, out: Any) -> list[str]:
# Unresolved locations are echoed by the handler; they are not indexed evidence.
return [str(row.get("path") or "") for row in out.results if row.get("start_line")]


def pack_paths(_input: Any, out: Any) -> list[str]:
# a task briefing's files; the orientation map and a PR's stored pack name none
return list(out._paths)
2 changes: 1 addition & 1 deletion server/identity/domain/read_scope.py
Original file line number Diff line number Diff line change
Expand Up @@ -349,7 +349,7 @@ def pin_read_filters[M: BaseModel](input: M, auth: Any) -> tuple[M, bool]:
"code.coverage.unwatch": _CODE_INDEX,
"code.coverage.watch": _CODE_INDEX,
"code.coverage_claim": _CODE_INDEX,
"code.enclosing": _CODE_INDEX,
"code.enclosing": _CODE_LESSONS,
"code.examples": _CODE_INDEX,
"code.files": _CODE_INDEX,
"code.first_build": _CODE_INDEX,
Expand Down
48 changes: 48 additions & 0 deletions tests/integration/test_code_result_lessons.py
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,54 @@ async def test_grep_attaches_requested_file_lessons_and_respects_opt_out(
assert "lessons" not in payload.get("data", payload)


async def test_enclosing_attaches_only_authorized_resolved_file_lessons(
control_plane_url: str, mint_test_token: Any, ch_client: Any
) -> None:
org = unique_org("enclosing-lessons")
writer = mint_test_token(org=org, namespaces=["*"], roles=["writer"])
_set(org, control_plane_url, writer, "notes/allowed", "Keep callback order.", [PATH])
_set(org, control_plane_url, writer, "notes/missing", "Unresolved file note.", ["absent.py"])
ch_client.insert(
"loom.code_symbols",
[[org, "code", "treesitter", "pkg::run", "run-id", "run", "function", PATH, 1, 5]],
column_names=[
"org",
"namespace",
"tier",
"qualified_name",
"symbol_id",
"name",
"kind",
"path",
"start_line",
"end_line",
],
)
body = dict(
org=org,
namespace="code",
locations=[f"{PATH}:2", f"{PATH}:3", "absent.py:1"],
lesson_namespaces=["dev"],
)
for names, include in [(["code", "dev"], True), (["code", "dev"], False), (["code"], True)]:
reader = mint_test_token(org=org, namespaces=names, roles=["viewer"])
async with httpx.AsyncClient(
base_url=control_plane_url, headers={"Authorization": f"Bearer {reader}"}, timeout=10
) as client:
response = await client.post(
"/v1/code.enclosing", json={**body, "include_lessons": include}
)
assert response.status_code == 200, response.text
payload = response.json()
data = payload.get("data", payload)
assert data["resolved"] == 2 and len(data["results"]) == 3
if include and "dev" in names:
assert [row["memory_key"] for row in data["lessons"]] == ["notes/allowed"]
assert data["lessons"][0]["path"] == PATH
else:
assert "lessons" not in data


async def test_lessons_match_the_result_file_by_path(
control_plane_url: str, mint_test_token: Any, ch_client: Any
) -> None:
Expand Down
54 changes: 53 additions & 1 deletion tests/unit/test_code_result_lessons.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,12 @@
import pytest

from server.code.api.models_grep import CodeGrepInput, CodeGrepOutput
from server.code.api.models_navigation import CodeOutlineInput, CodeOutlineOutput
from server.code.api.models_navigation import (
CodeEnclosingInput,
CodeEnclosingOutput,
CodeOutlineInput,
CodeOutlineOutput,
)
from server.code.api.models_search import CodeSearchInput, CodeSearchOutput
from server.code.app import result_lessons, search_memo
from server.memory.app import code_plane_reads, path_lessons
Expand Down Expand Up @@ -615,6 +620,7 @@ async def _outline(inp: CodeOutlineInput) -> CodeOutlineOutput:
"code.callees",
"code.impact",
"code.outline",
"code.enclosing",
"code.context_pack",
],
)
Expand Down Expand Up @@ -692,6 +698,7 @@ def test_every_code_result_op_is_wrapped_with_its_files() -> None:
from server.code.app.context import handle_code_context_pack
from server.code.app.grep import handle_code_grep
from server.code.app.search.handler import handle_code_search
from server.code.app.symbol.enclosing import handle_code_enclosing
from server.code.app.symbol.graph import handle_code_callees, handle_code_callers
from server.code.app.symbol.impact import handle_code_impact
from server.code.app.symbol.outline import handle_code_outline
Expand All @@ -703,6 +710,7 @@ def test_every_code_result_op_is_wrapped_with_its_files() -> None:
"code.callees": (handle_code_callees, result_lessons.edge_paths),
"code.impact": (handle_code_impact, result_lessons.impact_paths),
"code.outline": (handle_code_outline, result_lessons.outline_paths),
"code.enclosing": (handle_code_enclosing, result_lessons.enclosing_paths),
"code.context_pack": (handle_code_context_pack, result_lessons.pack_paths),
}
for name, (inner, paths_of) in wanted.items():
Expand Down Expand Up @@ -748,6 +756,50 @@ def test_grep_presence_and_uncovered_paths_have_no_lessons():
]


@pytest.mark.asyncio
@pytest.mark.parametrize("skip", ["none", "argument", "narrowed", "unresolved"])
async def test_enclosing_lessons_follow_only_resolved_files(
monkeypatch: pytest.MonkeyPatch, skip: str
) -> None:
calls: list[dict[str, Any]] = []
_stub_reads(monkeypatch, ["mem-home", "code-repo"], calls)
monkeypatch.setattr(
"server.identity.app.request_scope.request_narrowed", lambda: skip == "narrowed"
)

async def enclosing(inp: CodeEnclosingInput) -> CodeEnclosingOutput:
resolved = skip != "unresolved"
return CodeEnclosingOutput(
results=[
{"path": "src/a.py", "start_line": 1 if resolved else 0, "end_line": 5},
{"path": "src/a.py", "start_line": 2 if resolved else 0, "end_line": 5},
{"path": "missing.py", "start_line": 0, "end_line": 0},
],
resolved=2 if resolved else 0,
paths_indexed=1,
paths_total=2,
took_ms=0,
)

wrapped = result_lessons.WithLessons(enclosing, result_lessons.enclosing_paths)
out = await wrapped(
CodeEnclosingInput(
org="acme",
namespace="code-repo",
locations=["src/a.py:2", "src/a.py:3", "missing.py:1"],
lesson_namespaces=["mem-home", "denied"],
include_lessons=skip != "argument",
)
)
assert len(out.results) == 3
if skip != "none":
assert calls == [] and "lessons" not in out.model_dump()
else:
assert calls[0]["paths"] == ["src/a.py"]
assert calls[0]["nss"] == ["mem-home", "code-repo"]
assert out.lessons[0]["namespace"] == "mem-home"


def test_grep_enrichment_uses_only_the_remaining_deadline(monkeypatch: pytest.MonkeyPatch):
from types import SimpleNamespace

Expand Down
1 change: 1 addition & 0 deletions tests/unit/test_op_scope_fields.py
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@
("code.symbol", "namespaces"): _FANOUT,
("code.grep", "namespaces"): _FANOUT,
("code.grep", "lesson_namespaces"): "server.memory.app.code_plane_reads.lesson_namespaces",
("code.enclosing", "lesson_namespaces"): "server.memory.app.code_plane_reads.lesson_namespaces",
("code.symbol", "lesson_namespaces"): "server.memory.app.code_plane_reads.lesson_namespaces",
("code.callees", "lesson_namespaces"): "server.memory.app.code_plane_reads.lesson_namespaces",
("code.callers", "lesson_namespaces"): "server.memory.app.code_plane_reads.lesson_namespaces",
Expand Down
Loading