witan-code 0.3.0__tar.gz → 0.6.0__tar.gz

witan_code-0.6.0/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+All notable changes to `witan-code` are documented in this file.
+
+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.6.0] - 2026-07-21
+
+### Fixed
+
+- **`repo.detect(override=...)` and the `WITAN_REPO` env var now route
+  through `normalise`** (issue #142), same as an auto-detected git remote —
+  matching the fix in witan-council 0.6.0. Previously an explicitly-passed
+  `repo=` (or `WITAN_REPO`) was stored verbatim, bypassing
+  canonicalization. `graph_id` (the shared-cluster graph id) already
+  case-folded unconditionally and needs no change; a repo whose canonical
+  key changes case after this fix should be re-indexed (`witan-code
+  reindex`) so its per-repo store lands under the new key.
+- Depends on `witan-core[cli]>=0.2,<1` (unchanged range; picks up 0.4.0's
+  repo-key case-fold in `normalise`, which this package's `repo.detect`
+  relies on).
+
+## [0.5.0] - 2026-07-20
+
+### Added
+
+- `config.toml` + `[targets.<name>]` support (previously env-var only):
+  `WITAN_CONFIG` / `~/.config/witan/config.toml`, a global `code_dir`/
+  `author`, and named targets overriding `code_dir`/`author`, selected by
+  `WITAN_TARGET` env var, an explicit `load(target=...)`, or auto-detection
+  via `match_paths`/`match_repos`/`match_hosts`/`match_orgs` (same
+  precedence and file as witan — see `witan_core.target_config` and
+  `witan.config.load()`'s docstring). A target can carry witan's
+  `server`/`graph`/`token` alongside this server's `code_dir` under one
+  name; witan-code reads only the fields it knows. `Config` gained
+  `target_name`. `load()` now optionally takes a `target` argument (was
+  zero-argument only). New dependency: `pydantic>=2,<3`.
+
+### Changed
+
+- Now depends on `witan-core[cli]>=0.2,<1` (unchanged range; picks up
+  0.3.0, which adds the shared target-routing logic this release uses).
+
+## [0.4.0] - 2026-07-16
+
+### Added
+
+- **`witan-code --output-format`**: `repos`, `symbols`, and `stitch` can now
+  render their table data as `json`, `toml`, or `yaml` in addition to the
+  default Rich table output. The same option is honored when mounted as
+  `witan --output-format … code …`.
+
+### Changed
+
+- Adopted the shared `witan-core` package for the CLI scaffolding
+  (`make_app`/`report_install`/`resolve_author` + agent-name constants),
+  replacing the previously duplicated copies. No user-facing behavior change.
+  Now depends on `witan-core[cli]>=0.2,<1`.
+
+## [0.3.0] - 2026-07-10
+
+### Added
+
+- **`witan-code --version`**: prints the installed package version,
+  appending a git short ref when installed editable (local workspace) or
+  directly from a VCS URL (`uvx --from git+...`), via the new
+  `agent_config_kit.resolve_version()` helper.
+
+### Changed
+
+- `agent-config-kit` dependency bumped to `>=0.4,<1` (was `>=0.1,<1`) to
+  require the version that ships `resolve_version`, which backs the new
+  `--version` flag.
+
+## [0.2.1] - 2026-07-09
+
+### Fixed
+
+- **Pinned `tree-sitter` to `0.25.x`**: `0.26.0` has a use-after-free in its
+  pyo3 `Node` binding that segfaults (exit 139) under the heavy
+  `.parent()`/`.children()` churn `_walk_defs` does on real-world-sized
+  files — deterministically on the 2nd-3rd parse in one process, so
+  `witan-code index` hard-crashed on any real repo. `0.25.0`-`0.25.2` are
+  crash-free with the same ABI-15 grammar wheels.
+
+## [0.2.0] - 2026-07-09
+
+Initial PyPI release. `witan-code` is a tree-sitter-based code graph MCP
+server (Layer 2): indexes a repo's symbols (functions, methods, classes,
+modules) and their relationships, then exposes `code_search_symbol` /
+`code_find_definition` / `code_find_references` / `code_callers` /
+`code_impact` queries to the agent. Includes the Layer 2.5 cross-repo bridge,
+linking SOA repos by shared `env_var`/`endpoint`/`package`/`service` contract
+keys. Mounts standalone as `witan-code` or under `witan code …` when the
+`witan` umbrella CLI is installed alongside it.

witan_code-0.3.0/README.md → witan_code-0.6.0/PKG-INFO

@@ -1,3 +1,33 @@
+Metadata-Version: 2.4
+Name: witan-code
+Version: 0.6.0
+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
+Project-URL: Documentation, https://github.com/mitodl/agent-kit/blob/main/mcp/servers/witan-code/README.md
+Project-URL: Issues, https://github.com/mitodl/agent-kit/issues
+License-Expression: BSD-3-Clause
+Keywords: agent,code-graph,coding-agent,mcp,static-analysis,tree-sitter
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: agent-config-kit<1,>=0.4
+Requires-Dist: cyclopts<5,>=4
+Requires-Dist: fastmcp<4,>=3.4.2
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: rich>=13
+Requires-Dist: tomli-w<2,>=1
+Requires-Dist: tree-sitter-bash<0.26,>=0.25
+Requires-Dist: tree-sitter-go<0.26,>=0.25
+Requires-Dist: tree-sitter-hcl<1.3,>=1.2
+Requires-Dist: tree-sitter-python<0.26,>=0.25
+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]<1,>=0.2
+Description-Content-Type: text/markdown
+
 # witan-code
 
 > "witan" is pronounced `WIT-ən` (/ˈwɪtən/) — rhymes with "written" minus the r.
@@ -60,6 +90,22 @@ machine's local code index.
 - [CLI reference](https://github.com/mitodl/agent-kit/blob/main/mcp/servers/witan-code/docs/CLI_REFERENCE.md) — every `witan-code` command with
   its full flag table and an example invocation.
 
+## CLI structured output
+
+`witan-code` table-producing commands can emit machine-readable output instead
+of Rich tables:
+
+```bash
+witan-code --output-format json repos
+witan-code --output-format yaml symbols --role exported
+witan --output-format toml code stitch --unresolved
+```
+
+Supported formats are `txt` (default), `json`, `toml`, and `yaml`. The same
+setting is available through `WITAN_OUTPUT_FORMAT`. It currently applies to
+`repos`, `symbols`, and `stitch`; free-text commands such as `index` and hook
+commands keep their existing output.
+
 ## Cross-repo context bridge (Layer 2.5)
 
 The per-repo graph stops at a repo boundary, but service-oriented architectures
@@ -256,11 +302,12 @@ witan's). Run `witan-code setup` on its own for a witan-code-only install, or
 when witan-code isn't importable from witan's environment. See
 [Hooks](#hooks) and [Skill](#skill).
 
-This downloads the omnigraph release pinned by `_OMNIGRAPH_VERSION` in
-[`witan_code/setup.py`](./witan_code/setup.py) — the same pin `witan`'s own
-`setup.py` uses, kept in lockstep by Renovate (see the repo-root
-`renovate.json`'s `omnigraph-version` customManager, which bumps both files
-in one PR). There is no build-time bundling of the binary into the wheel —
+This downloads the omnigraph release pinned by `_OMNIGRAPH_VERSION` in the
+shared installer
+[`witan_core.omnigraph_install`](../../../packages/witan-core/witan_core/omnigraph_install.py)
+— the same pin `witan` uses (both import it from `witan-core`), bumped by
+Renovate (see the repo-root `renovate.json`'s `omnigraph-version`
+customManager). There is no build-time bundling of the binary into the wheel —
 `witan-code setup` (or `witan setup`) is the only source of the binary, and
 re-running it is how you pick up a version bump.
 
@@ -288,12 +335,35 @@ symlink alternative:
 | `WITAN_AUTHOR` / `USER` | `unknown` | attribution string |
 | `WITAN_REPO` | — | override the detected repo slug |
 | `WITAN_CODE_OPTIMIZE_INTERVAL` | `86400` (daily) | throttle window (seconds) for `checkpoint`'s opportunistic store compaction; `0` disables it |
+| `WITAN_CONFIG` | `~/.config/witan/config.toml` | config file path (see below) |
+| `WITAN_TARGET` | — | force a named `[targets.<name>]` block instead of auto-detecting one |
 
 The store URI for a repo is `<dir>/<sanitized-slug>.omni`, where the slug's `/`
 and `:` are replaced with `_`. The shared cross-repo bridge lives alongside them
 at `<dir>/_bridge.omni` and is created lazily on the first index that yields any
 bindings.
 
+### config.toml
+
+witan-code reads the same `config.toml` as witan (witan-council) — a global
+`code_dir`/`author`, plus named `[targets.<name>]` blocks that override them
+and are selected by `WITAN_TARGET`, `load(target=...)` (Python API only — no
+CLI `--target` flag yet), or auto-detection against the current
+repo/checkout (`match_paths` > `match_repos` > `match_hosts` > `match_orgs`
+— see witan's README/`witan/config.py` docstring for the full precedence).
+Because the file is shared, one target block can carry witan's
+`server`/`graph`/`token` alongside `code_dir` under
+the same name — each server reads only the fields it knows:
+
+```toml
+[targets.work]
+server = "http://witan.internal:8080"  # witan (witan-council)
+code_dir = "/mnt/work/witan-code"      # witan-code
+match_orgs = ["myorg"]
+```
+
+Environment variables always win over `config.toml`.
+
 ## MCP tools
 
 Each tool resolves the per-repo store from the current working directory and

witan_code-0.3.0/PKG-INFO → witan_code-0.6.0/README.md

@@ -1,30 +1,3 @@
-Metadata-Version: 2.4
-Name: witan-code
-Version: 0.3.0
-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
-Project-URL: Documentation, https://github.com/mitodl/agent-kit/blob/main/mcp/servers/witan-code/README.md
-Project-URL: Issues, https://github.com/mitodl/agent-kit/issues
-License-Expression: BSD-3-Clause
-Keywords: agent,code-graph,coding-agent,mcp,static-analysis,tree-sitter
-Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.11
-Requires-Dist: agent-config-kit<1,>=0.4
-Requires-Dist: cyclopts<5,>=4
-Requires-Dist: fastmcp<4,>=3.4.2
-Requires-Dist: pyyaml<7,>=6
-Requires-Dist: rich>=13
-Requires-Dist: tree-sitter-bash<0.26,>=0.25
-Requires-Dist: tree-sitter-go<0.26,>=0.25
-Requires-Dist: tree-sitter-hcl<1.3,>=1.2
-Requires-Dist: tree-sitter-python<0.26,>=0.25
-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
-Description-Content-Type: text/markdown
-
 # witan-code
 
 > "witan" is pronounced `WIT-ən` (/ˈwɪtən/) — rhymes with "written" minus the r.
@@ -87,6 +60,22 @@ machine's local code index.
 - [CLI reference](https://github.com/mitodl/agent-kit/blob/main/mcp/servers/witan-code/docs/CLI_REFERENCE.md) — every `witan-code` command with
   its full flag table and an example invocation.
 
+## CLI structured output
+
+`witan-code` table-producing commands can emit machine-readable output instead
+of Rich tables:
+
+```bash
+witan-code --output-format json repos
+witan-code --output-format yaml symbols --role exported
+witan --output-format toml code stitch --unresolved
+```
+
+Supported formats are `txt` (default), `json`, `toml`, and `yaml`. The same
+setting is available through `WITAN_OUTPUT_FORMAT`. It currently applies to
+`repos`, `symbols`, and `stitch`; free-text commands such as `index` and hook
+commands keep their existing output.
+
 ## Cross-repo context bridge (Layer 2.5)
 
 The per-repo graph stops at a repo boundary, but service-oriented architectures
@@ -283,11 +272,12 @@ witan's). Run `witan-code setup` on its own for a witan-code-only install, or
 when witan-code isn't importable from witan's environment. See
 [Hooks](#hooks) and [Skill](#skill).
 
-This downloads the omnigraph release pinned by `_OMNIGRAPH_VERSION` in
-[`witan_code/setup.py`](./witan_code/setup.py) — the same pin `witan`'s own
-`setup.py` uses, kept in lockstep by Renovate (see the repo-root
-`renovate.json`'s `omnigraph-version` customManager, which bumps both files
-in one PR). There is no build-time bundling of the binary into the wheel —
+This downloads the omnigraph release pinned by `_OMNIGRAPH_VERSION` in the
+shared installer
+[`witan_core.omnigraph_install`](../../../packages/witan-core/witan_core/omnigraph_install.py)
+— the same pin `witan` uses (both import it from `witan-core`), bumped by
+Renovate (see the repo-root `renovate.json`'s `omnigraph-version`
+customManager). There is no build-time bundling of the binary into the wheel —
 `witan-code setup` (or `witan setup`) is the only source of the binary, and
 re-running it is how you pick up a version bump.
 
@@ -315,12 +305,35 @@ symlink alternative:
 | `WITAN_AUTHOR` / `USER` | `unknown` | attribution string |
 | `WITAN_REPO` | — | override the detected repo slug |
 | `WITAN_CODE_OPTIMIZE_INTERVAL` | `86400` (daily) | throttle window (seconds) for `checkpoint`'s opportunistic store compaction; `0` disables it |
+| `WITAN_CONFIG` | `~/.config/witan/config.toml` | config file path (see below) |
+| `WITAN_TARGET` | — | force a named `[targets.<name>]` block instead of auto-detecting one |
 
 The store URI for a repo is `<dir>/<sanitized-slug>.omni`, where the slug's `/`
 and `:` are replaced with `_`. The shared cross-repo bridge lives alongside them
 at `<dir>/_bridge.omni` and is created lazily on the first index that yields any
 bindings.
 
+### config.toml
+
+witan-code reads the same `config.toml` as witan (witan-council) — a global
+`code_dir`/`author`, plus named `[targets.<name>]` blocks that override them
+and are selected by `WITAN_TARGET`, `load(target=...)` (Python API only — no
+CLI `--target` flag yet), or auto-detection against the current
+repo/checkout (`match_paths` > `match_repos` > `match_hosts` > `match_orgs`
+— see witan's README/`witan/config.py` docstring for the full precedence).
+Because the file is shared, one target block can carry witan's
+`server`/`graph`/`token` alongside `code_dir` under
+the same name — each server reads only the fields it knows:
+
+```toml
+[targets.work]
+server = "http://witan.internal:8080"  # witan (witan-council)
+code_dir = "/mnt/work/witan-code"      # witan-code
+match_orgs = ["myorg"]
+```
+
+Environment variables always win over `config.toml`.
+
 ## MCP tools
 
 Each tool resolves the per-repo store from the current working directory and

{witan_code-0.3.0 → witan_code-0.6.0}/docs/CLI_REFERENCE.md

@@ -7,7 +7,13 @@ the `witan` umbrella package. Run `witan-code --help` or `witan-code
 <command> --help` for the live version of this table — it is generated from
 the same docstrings.
 
-Global flags: `--help` / `-h`, `--version`.
+Global flags: `--help` / `-h`, `--version`, `--output-format txt|json|toml|yaml`.
+
+`--output-format` controls table-producing commands (`repos`, `symbols`, and
+`stitch`) and is also available as `WITAN_OUTPUT_FORMAT`. The default `txt`
+renders the existing Rich tables; `json`, `toml`, and `yaml` emit a wrapper
+object with `title` and `rows` for machine parsing. The same option works when
+mounted under the umbrella CLI, e.g. `witan --output-format json code repos`.
 
 Boolean flags follow cyclopts' `--flag`/`--no-flag` convention; both forms are
 always available even where only `--flag` is shown below.

{witan_code-0.3.0 → witan_code-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "witan-code"
-version = "0.3.0"
+version = "0.6.0"
 description = "witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)"
 readme = "README.md"
 license = "BSD-3-Clause"
@@ -11,8 +11,12 @@ classifiers = [
 ]
 dependencies = [
     "agent-config-kit>=0.4,<1",
+    "witan-core[cli]>=0.2,<1",
     "fastmcp>=3.4.2,<4",
     "cyclopts>=4,<5",
+    # [targets.<name>] override models (config.py) — also transitively pulled
+    # in by fastmcp, declared explicitly since config.py imports it directly.
+    "pydantic>=2,<3",
     # Pinned to 0.25.x: tree-sitter 0.26.0 has a use-after-free in its pyo3 Node
     # binding that segfaults (exit 139) under the heavy .parent()/.children()
     # churn _walk_defs does on real-world-sized files — deterministically on the
@@ -35,6 +39,7 @@ dependencies = [
     "tree-sitter-hcl>=1.2,<1.3",
     "tree-sitter-go>=0.25,<0.26",
     "pyyaml>=6,<7",
+    "tomli-w>=1,<2",
     "rich>=13",
 ]
 
@@ -56,7 +61,8 @@ build-backend = "hatchling.build"
 # agent-config-kit version bumped alongside it — even before that version
 # has actually landed on PyPI. Published wheels only see the PyPI-range
 # dependency declared above.
-agent-config-kit = { path = "../../../packages/agent-config-kit", editable = true }
+agent-config-kit = { workspace = true }
+witan-core = { workspace = true }
 
 [dependency-groups]
 test = ["pytest>=8"]
@@ -69,7 +75,7 @@ testpaths = ["tests"]
 packages = ["witan_code"]
 
 [tool.bumpversion]
-current_version = "0.3.0"
+current_version = "0.6.0"
 allow_dirty = true
 
 [[tool.bumpversion.files]]

witan_code-0.6.0/tests/test_cli_output_format.py

@@ -0,0 +1,91 @@
+"""Tests for the global ``--output-format`` option."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from witan_code import cli as cli_module
+from witan_code import output as output_module
+
+
+@pytest.fixture(autouse=True)
+def _reset_output_format():
+    """Every test starts and ends on the txt default regardless of order."""
+    output_module.set_output_format("txt")
+    yield
+    output_module.set_output_format("txt")
+
+
+def test_render_table_json_dumps_normalized_rows(capsys):
+    output_module.set_output_format("json")
+
+    cli_module._render_table(
+        title="Indexed repositories",
+        columns=["repo", "files"],
+        rows=[{"repo": "https://github.com/test/repo", "files": None}],
+    )
+
+    payload = json.loads(capsys.readouterr().out)
+    assert payload == {
+        "title": "Indexed repositories",
+        "rows": [{"repo": "https://github.com/test/repo", "files": ""}],
+    }
+
+
+def test_render_table_toml_dumps_normalized_rows(capsys):
+    import tomllib
+
+    output_module.set_output_format("toml")
+
+    cli_module._render_table(
+        title="Symbol table — https://github.com/test/repo",
+        columns=["role", "refs"],
+        rows=[{"role": "exported", "refs": 2}],
+    )
+
+    payload = tomllib.loads(capsys.readouterr().out)
+    assert payload["title"] == "Symbol table — https://github.com/test/repo"
+    assert payload["rows"] == [{"role": "exported", "refs": 2}]
+
+
+def test_repos_honors_structured_output(tmp_path, monkeypatch, capsys):
+    code_dir = tmp_path / "code"
+    code_dir.mkdir()
+    store = code_dir / "https_github.com_test_repo.omni"
+    store.mkdir()
+    (code_dir / f"{store.name}.repo").write_text("https://github.com/test/repo")
+    monkeypatch.setenv("WITAN_CODE_DIR", str(code_dir))
+    monkeypatch.setattr(
+        cli_module,
+        "_code_store_stats",
+        lambda store: ("https://github.com/test/repo", "7"),
+    )
+    monkeypatch.setattr(cli_module, "_dir_stats", lambda path: (1024, "2026-07-13"))
+    output_module.set_output_format("json")
+
+    cli_module.repos()
+
+    payload = json.loads(capsys.readouterr().out)
+    assert payload == {
+        "title": "Indexed repositories",
+        "rows": [
+            {
+                "repo": "https://github.com/test/repo",
+                "files": "7",
+                "size": "1.0KB",
+                "last indexed": "2026-07-13",
+            }
+        ],
+    }
+
+
+def test_launcher_sets_output_format_and_forwards_tokens(monkeypatch):
+    calls = []
+    monkeypatch.setattr(cli_module, "app", lambda tokens: calls.append(tokens))
+
+    cli_module._launcher("repos", output_format="yaml")
+
+    assert output_module.get_output_format() == "yaml"
+    assert calls == [("repos",)]

witan_code-0.6.0/tests/test_config.py

@@ -0,0 +1,64 @@
+"""Canonical cluster graph-id derivation (config.graph_id).
+
+This id is a cross-repo contract: witan-code addresses `--graph <id>` and
+ol-infrastructure's cluster.yaml provisioning declares the same `<id>`. If this
+algorithm drifts from the provisioning side, clients address graphs the cluster
+never created — so pin the observable mapping here.
+"""
+
+from witan_code import config
+
+
+def test_graph_id_canonical_example():
+    # The example from the deployment decision; must be byte-for-byte stable.
+    assert (
+        config.graph_id("https://github.com/mitodl/ol-django")
+        == "code-github-com-mitodl-ol-django"
+    )
+
+
+def test_graph_id_matches_constraint():
+    for repo in (
+        "https://github.com/mitodl/ol-django",
+        "http://example.com/x",
+        "git@github.com:mitodl/agent-kit.git",
+        "github.com/mitodl/ol-infrastructure",
+        "https://github.com/MITODL/Mixed_Case.Repo",
+    ):
+        assert config.GRAPH_ID_RE.match(config.graph_id(repo)), repo
+
+
+def test_graph_id_no_underscores_and_lowercase():
+    gid = config.graph_id("https://github.com/MITODL/Mixed_Case.Repo")
+    assert "_" not in gid
+    assert gid == gid.lower()
+
+
+def test_graph_id_strips_scheme():
+    with_scheme = config.graph_id("https://github.com/mitodl/x")
+    without = config.graph_id("github.com/mitodl/x")
+    assert with_scheme == without == "code-github-com-mitodl-x"
+
+
+def test_graph_id_is_prefixed():
+    assert config.graph_id("github.com/a/b").startswith(config.CODE_GRAPH_PREFIX)
+
+
+def test_graph_id_long_repo_truncates_with_hash():
+    long_repo = "https://github.com/mitodl/" + "a" * 200
+    gid = config.graph_id(long_repo)
+    assert len(gid) <= 64
+    assert config.GRAPH_ID_RE.match(gid)
+    # Distinct long repos disambiguate via the URI hash, never colliding.
+    other = config.graph_id("https://github.com/mitodl/" + "a" * 199 + "b")
+    assert gid != other
+
+
+def test_graph_id_is_deterministic():
+    repo = "https://github.com/mitodl/" + "z" * 100
+    assert config.graph_id(repo) == config.graph_id(repo)
+
+
+def test_bridge_graph_id_constant():
+    assert config.BRIDGE_GRAPH_ID == "code-bridge"
+    assert config.GRAPH_ID_RE.match(config.BRIDGE_GRAPH_ID)