witan-code 0.13.3__tar.gz → 0.13.5__tar.gz

{witan_code-0.13.3 → witan_code-0.13.5}/CHANGELOG.md

@@ -6,6 +6,29 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/) (pre-1.0:
 a MINOR bump may include breaking changes).
 
+## [0.13.5] - 2026-08-21
+
+### Changed
+
+- Raised the `witan-core` floor to `>=0.28` for the refreshed omnigraph
+  `edge` digest (see witan-core's CHANGELOG) — a version below it fails
+  `witan-code setup`'s checksum and leaves the indexer with no binary to
+  shell out to.
+
+## [0.13.4] - 2026-08-19
+
+### Changed
+
+- **Every `code_*` tool parameter now carries a description in its JSON
+  Schema.** Seven parameters across seven tools had none — the `symbol_id`
+  argument of `code_callers`, `code_find_references`, `code_impact`, and
+  `code_cross_repo_impact`, the `repo` filter on `code_find_definition` and
+  `code_search_symbol`, and `branch` on `code_indexed_branches`. FastMCP
+  sends these schemas to the model, so an undescribed parameter leaves the
+  calling agent guessing. `symbol_id` in particular now says where the value
+  comes from (the `symbol_id` field of `code_find_definition` /
+  `code_search_symbol`) and what shape it has.
+
 ## [0.13.3] - 2026-08-18
 
 ### Changed

{witan_code-0.13.3 → witan_code-0.13.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: witan-code
-Version: 0.13.3
+Version: 0.13.5
 Summary: witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)
 Project-URL: Homepage, https://github.com/mitodl/agent-kit/tree/main/mcp/servers/witan-code
 Project-URL: Repository, https://github.com/mitodl/agent-kit
@@ -26,7 +26,7 @@ Requires-Dist: tree-sitter-sql<0.4,>=0.3
 Requires-Dist: tree-sitter-typescript<0.24,>=0.23
 Requires-Dist: tree-sitter-yaml<0.8,>=0.7
 Requires-Dist: tree-sitter<0.26,>=0.25
-Requires-Dist: witan-core[cli,observability,remote,sentry]<1,>=0.24
+Requires-Dist: witan-core[cli,observability,remote,sentry]<1,>=0.28
 Provides-Extra: tasks
 Requires-Dist: fastmcp-tasks<5,>=4.0.0b1; extra == 'tasks'
 Description-Content-Type: text/markdown

{witan_code-0.13.3 → witan_code-0.13.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "witan-code"
-version = "0.13.3"
+version = "0.13.5"
 description = "witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)"
 readme = "README.md"
 license = "BSD-3-Clause"
@@ -78,7 +78,16 @@ dependencies = [
     # published, so anything resolving below 0.24 would silently install
     # without sentry-sdk (or error on the unknown extra) rather than getting
     # Sentry reporting at all.
-    "witan-core[cli,remote,observability,sentry]>=0.24,<1",
+    #
+    # ★ >=0.28 IS NOT ABOUT AN IMPORT, same exception witan-council's floor
+    # documents: witan-core 0.28.0 carries the current omnigraph `edge`
+    # digest, and every version below it fails `witan setup`'s checksum and
+    # installs no binary at all — indexer tests skip without one
+    # (tests/conftest.py) and a real indexer run has nothing to shell out to.
+    # Expect this floor to keep moving while omnigraph 0.10.0 stays on the
+    # moving `edge` tag; see
+    # packages/witan-core/witan_core/omnigraph_install.py.
+    "witan-core[cli,remote,observability,sentry]>=0.28,<1",
     "fastmcp>=3.4.2,<5",
     "cyclopts>=4,<5",
     # [targets.<name>] override models (config.py) — also transitively pulled
@@ -162,7 +171,7 @@ testpaths = ["tests"]
 packages = ["witan_code"]
 
 [tool.bumpversion]
-current_version = "0.13.3"
+current_version = "0.13.5"
 allow_dirty = true
 
 [[tool.bumpversion.files]]

witan_code-0.13.5/tests/test_tool_schema.py

@@ -0,0 +1,49 @@
+"""Every `code_*` tool parameter must carry a description in its schema.
+
+The witan-council twin of this file explains the reasoning at length; briefly:
+FastMCP derives each tool's JSON Schema from its docstring's numpydoc
+``Parameters`` section, and that schema is what the calling model sees. Seven
+parameters here — including the ``symbol_id`` of ``code_callers``,
+``code_find_references``, ``code_impact`` and ``code_cross_repo_impact`` —
+reached the model with nothing but a name and a type, and the existing
+``list_tools`` coverage asserts only that ``code_reindex`` exists, so a
+regression would not have been reported.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+
+def _tool_properties() -> list[tuple[str, str, dict]]:
+    """(tool, parameter, schema) for every exposed parameter of every tool."""
+    from witan_code import server as code_server
+
+    tools = asyncio.run(code_server.mcp._list_tools())
+    return [
+        (tool.name, name, schema)
+        for tool in tools
+        for name, schema in ((tool.parameters or {}).get("properties", {})).items()
+    ]
+
+
+def test_every_tool_parameter_has_a_description():
+    missing = [
+        f"{tool}.{param}"
+        for tool, param, schema in _tool_properties()
+        if not (schema.get("description") or "").strip()
+    ]
+    assert not missing, (
+        f"{len(missing)} tool parameter(s) reach the model with no description. "
+        "Add a numpydoc `Parameters` entry for each in witan_code/server.py:\n  "
+        + "\n  ".join(sorted(missing))
+    )
+
+
+def test_the_tool_surface_is_actually_being_inspected():
+    """Guard the guard — an empty listing would make the assertion vacuous."""
+    properties = _tool_properties()
+    assert len(properties) > 20, (
+        f"only {len(properties)} tool parameters found; the code_* surface is "
+        "larger than that, so the schema inspection is probably broken"
+    )

{witan_code-0.13.3 → witan_code-0.13.5}/witan_code/graph.py

@@ -249,11 +249,19 @@ class OmnigraphClient(_BaseOmnigraphClient):
                 f"omnigraph commit list returned no commit array for branch "
                 f"{name!r}: {parsed!r}"
             )
+        # ★ TWO FIELD NAMES, ONE MEANING. omnigraph's 2026-08-20 vocabulary
+        # sweep (upstream ecf1d6aedd, #538) renamed `manifest_branch` to
+        # `graph_branch` in `commit list --json` without bumping the reported
+        # version, so both are in the wild. Reading only one is not a cosmetic
+        # miss here: no row matches, `stamps` is empty, and this returns None —
+        # which the docstring above makes load-bearing as "never reap this
+        # view". The reaper would then quietly stop reaping anything at all,
+        # and nothing would raise to say so.
         stamps = [
             row["created_at"]
             for row in commits
             if isinstance(row, dict)
-            and row.get("manifest_branch") == name
+            and name in (row.get("manifest_branch"), row.get("graph_branch"))
             and isinstance(row.get("created_at"), (int, float))
         ]
         # created_at is microseconds since the epoch.

{witan_code-0.13.3 → witan_code-0.13.5}/witan_code/server.py

@@ -424,6 +424,12 @@ async def code_find_definition(
     ----------
     name:
         Bare name (``run``) or qualified name (``Service.run``).
+    repo:
+        Canonical repo URI to search. Defaults to the repo detected from the
+        checkout, and fans out across every indexed repo only when no repo is
+        detected at all. Note this differs from the witan memory/task tools:
+        ``repo=""`` does **not** force a fan-out here — it is falsy, so it
+        behaves exactly like omitting the argument.
     branch:
         Git branch whose indexed view to query (e.g. another agent's in-flight
         branch). Defaults to the checkout's branch when querying the current
@@ -464,6 +470,13 @@ async def code_find_references(
 
     Supersets code_callers (references includes calls); use code_callers when
     you want calls only. Heuristic — may miss or over-report.
+
+    Parameters
+    ----------
+    symbol_id:
+        The symbol to start from, as returned in the ``symbol_id`` field of
+        code_find_definition or code_search_symbol. Form:
+        ``<repo>#<path/to/file.py>::<QualifiedName>``.
     """
     client = _client_for_symbol(symbol_id)
     if client is None:
@@ -483,6 +496,13 @@ async def code_callers(symbol_id: str, ctx: Context | None = None) -> list[dict]
 
     Heuristic name-resolution based; not a precise call graph. For calls plus
     other references use code_find_references.
+
+    Parameters
+    ----------
+    symbol_id:
+        The symbol to start from, as returned in the ``symbol_id`` field of
+        code_find_definition or code_search_symbol. Form:
+        ``<repo>#<path/to/file.py>::<QualifiedName>``.
     """
     client = _client_for_symbol(symbol_id)
     if client is None:
@@ -508,6 +528,12 @@ async def code_impact(
 
     Parameters
     ----------
+    symbol_id:
+        The symbol to start from, as returned in the ``symbol_id`` field of
+        code_find_definition or code_search_symbol. Form:
+        ``<repo>#<path/to/file.py>::<QualifiedName>``.
+        This is the symbol you are about to change; the result is its blast
+        radius.
     max_depth:
         Maximum BFS depth (default 5).
     max_nodes:
@@ -635,6 +661,13 @@ def code_search_symbol(
         ``class``, ``module``, ``variable``, ``interface``, ``type``, ``enum``,
         ``key``, ``table``, ``cte``, or ``block``. Pass e.g. ``kind="function"``
         to exclude the many YAML ``key`` symbols when searching for code.
+    repo:
+        Canonical repo URI to search. Defaults to the repo detected from the
+        checkout, and fans out across every indexed repo only when no repo is
+        detected at all — ``repo=""`` does **not** force that, unlike the witan
+        memory/task tools; it is falsy and behaves like omitting the argument.
+        BM25 ranking is per-store, so a fan-out concatenates each store's
+        ranked results rather than producing one global ordering.
     branch:
         Git branch whose indexed view to query. Defaults to the checkout's
         branch when querying the current repo; when ``repo`` names a different
@@ -767,6 +800,11 @@ async def code_cross_repo_impact(
 
     Parameters
     ----------
+    symbol_id:
+        The symbol whose cross-repo surface to trace, as returned in the
+        ``symbol_id`` field of code_find_definition or code_search_symbol. Its
+        repo prefix also scopes the bridge read, so asking about another repo's
+        symbol does not pick up an unrelated overlay from your own checkout.
     min_precision:
         ``heuristic`` (default) | ``precise`` — see server instructions.
     """
@@ -1018,6 +1056,13 @@ def code_indexed_branches(branch: str | None = None) -> list[dict]:
     sanitized git branch it is a view of, ``actor`` its owner (null on a
     single-writer local store). ``views`` is null for a store that could not be
     listed.
+
+    Parameters
+    ----------
+    branch:
+        A raw git branch name (not a view name) to filter by, showing every
+        writer's view of that one branch — this is how you find a teammate's
+        in-flight work. Omit to list every view of every indexed repo.
     """
     wanted = repo_module.branch_store_name(branch) if branch else None