Skip to content

Commit 514d106

Browse files
cdeustclaude
andcommitted
fix(core): remove pathlib from abstention_gate and codebase_graph (#560)
core/ must be zero-I/O and may not import os/pathlib (docs/module-inventory.md, Dependency Rules table), but both modules did: - codebase_graph.py used PurePosixPath purely for string manipulation (path normalization and dirname) with no filesystem access. Replaced with local pure-string helpers (_posix_normalize/_posix_parent) whose equivalence to PurePosixPath is pinned by a new test (TestPosixPathHelpers). Zero blast radius: no caller signature changed. - abstention_gate.py used Path.home()/".cache"/... to locate and load an optional ML model file, which is genuine filesystem I/O. Moved that read into a new mcp_server/infrastructure/abstention_classifier.py (load_abstention_classifier), and core now accepts an injectable classifier_factory callable (None by default, matching the historical "package not installed" fallback). This module has no production caller today (verified repo-wide grep; only its own tests exercise it, despite ADR-0097 documenting intent) so there is no composition root to wire yet; whoever wires it into retrieval later passes classifier_factory=load_abstention_classifier from the handler. Pruned exactly the 3 now-stale layer-violation baseline entries for these two files (pathlib x2, cortex_beam_abstain x1); left the other pre-existing, unrelated baseline entries for these files untouched (method-size, unsourced-constant, networkx layer-violation; none of these reproduce differently after this change). Part of #560 (17 core/ modules import os/pathlib); 15 remain, tracked for follow-up PRs (ablation.py's is_mechanism_disabled alone fans out to about 30 call sites and needs its own dedicated pass). Verified: scripts/check_craftsmanship.py --base origin/main returns OK; grep for os/pathlib in the two touched files returns empty; ruff check/format are clean; pyright mcp_server/ reports 0 errors; full pytest reports 8118 passed, 290 skipped, 1 pre-existing failure (test_pg_driver_passes_in_dev_env, reproduces identically on unmodified origin/main under this same --extra dev --extra sqlite sync since no postgresql extra is installed, per the contract's prescribed env; unrelated to this change). Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 1f3c7ff commit 514d106

7 files changed

Lines changed: 236 additions & 53 deletions

File tree

‎.craftsmanship-baseline.json‎

Lines changed: 0 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -657,16 +657,6 @@
657657
"kind": "unsourced-constant",
658658
"detail": "_IMPORTANT_IMPACT_THRESHOLD"
659659
},
660-
{
661-
"file": "mcp_server/core/abstention_gate.py",
662-
"kind": "layer-violation",
663-
"detail": "cortex_beam_abstain"
664-
},
665-
{
666-
"file": "mcp_server/core/abstention_gate.py",
667-
"kind": "layer-violation",
668-
"detail": "pathlib"
669-
},
670660
{
671661
"file": "mcp_server/core/abstention_gate.py",
672662
"kind": "method-size",
@@ -907,11 +897,6 @@
907897
"kind": "layer-violation",
908898
"detail": "networkx"
909899
},
910-
{
911-
"file": "mcp_server/core/codebase_graph.py",
912-
"kind": "layer-violation",
913-
"detail": "pathlib"
914-
},
915900
{
916901
"file": "mcp_server/core/codebase_graph.py",
917902
"kind": "method-size",

‎mcp_server/core/abstention_gate.py‎

Lines changed: 34 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
from __future__ import annotations
66

77
import logging
8-
from pathlib import Path
8+
from collections.abc import Callable
99
from typing import Any
1010

1111
logger = logging.getLogger(__name__)
@@ -19,12 +19,25 @@
1919

2020
DEFAULT_THRESHOLD = 0.45
2121

22-
23-
def _get_classifier() -> Any:
24-
"""Lazy-load the abstention classifier.
25-
26-
Returns None if the model isn't available — caller should treat
27-
that as "no filtering" (return all results unchanged).
22+
# A classifier factory performs filesystem I/O (model cache lookup, possible
23+
# download) and therefore must be supplied by the composition root — see
24+
# mcp_server.infrastructure.abstention_classifier.load_abstention_classifier.
25+
# source: issue #560 (core/ may not import os/pathlib)
26+
ClassifierFactory = Callable[[], Any | None]
27+
28+
29+
def _get_classifier(classifier_factory: ClassifierFactory | None) -> Any:
30+
"""Lazy-load the abstention classifier via an injected factory.
31+
32+
Precondition: ``classifier_factory``, when provided, returns a loaded
33+
classifier or ``None`` on failure/absence; it may perform I/O (that I/O
34+
lives in infrastructure/, never here).
35+
Postcondition: memoizes the first non-``None`` result (or the fact that
36+
loading was attempted) in module state, exactly as before this seam was
37+
introduced — the "reads/attempts once per process" caching semantics
38+
are unchanged. Returns ``None`` if the model isn't available or no
39+
factory was given — caller should treat that as "no filtering" (return
40+
all results unchanged).
2841
"""
2942
global _classifier, _load_attempted
3043

@@ -34,28 +47,11 @@ def _get_classifier() -> Any:
3447
return None
3548

3649
_load_attempted = True
37-
try:
38-
# Lazy import — package is optional
39-
from cortex_beam_abstain import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] — source: ADR-0097
40-
AbstentionClassifier,
41-
)
42-
43-
cache = Path.home() / ".cache" / "cortex-abstention" / "model.onnx"
44-
if cache.exists():
45-
_classifier = AbstentionClassifier(model_path=cache)
46-
else:
47-
_classifier = AbstentionClassifier() # auto-download
50+
if classifier_factory is None:
51+
return None
52+
_classifier = classifier_factory()
53+
if _classifier is not None:
4854
logger.info("Abstention classifier loaded")
49-
except ImportError:
50-
logger.debug(
51-
"cortex-beam-abstain not installed; abstention gate disabled. "
52-
"Install: pip install cortex-beam-abstain"
53-
)
54-
_classifier = None
55-
except Exception as e: # noqa: BLE001 — source: ADR-0097
56-
logger.warning("Failed to load abstention classifier: %s", e)
57-
_classifier = None
58-
5955
return _classifier
6056

6157

@@ -64,6 +60,7 @@ def filter_by_abstention(
6460
candidates: list[dict[str, Any]],
6561
threshold: float = DEFAULT_THRESHOLD,
6662
keep_at_least: int = 0,
63+
classifier_factory: ClassifierFactory | None = None,
6764
) -> tuple[list[dict[str, Any]], list[float]]:
6865
"""Filter retrieval results using the abstention classifier.
6966
@@ -73,6 +70,10 @@ def filter_by_abstention(
7370
threshold: Minimum relevance score to keep a result (default 0.45).
7471
keep_at_least: Minimum results retained, even below the threshold;
7572
zero enables strict filtering and may return no results.
73+
classifier_factory: Composition-root-supplied loader (see
74+
mcp_server.infrastructure.abstention_classifier); omit to run
75+
with abstention filtering disabled (candidates pass through
76+
unchanged), e.g. in tests.
7677
source: ADR-0097
7778
7879
Returns:
@@ -83,7 +84,7 @@ def filter_by_abstention(
8384
if not candidates:
8485
return [], []
8586

86-
clf = _get_classifier()
87+
clf = _get_classifier(classifier_factory)
8788
if clf is None:
8889
# Model unavailable — return everything unchanged
8990
return candidates, [1.0] * len(candidates)
@@ -112,10 +113,13 @@ def should_abstain(
112113
query: str,
113114
candidates: list[dict[str, Any]],
114115
threshold: float = DEFAULT_THRESHOLD,
116+
classifier_factory: ClassifierFactory | None = None,
115117
) -> bool:
116118
"""Quick check: should the system return empty results entirely?
117119
118120
True when ALL candidates score below threshold (no relevant match).
119121
"""
120-
filtered, _ = filter_by_abstention(query, candidates, threshold)
122+
filtered, _ = filter_by_abstention(
123+
query, candidates, threshold, classifier_factory=classifier_factory
124+
)
121125
return len(filtered) == 0

‎mcp_server/core/codebase_graph.py‎

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,6 @@
44

55
from __future__ import annotations
66

7-
from pathlib import PurePosixPath
8-
9-
# source: ADR-0127
10-
117
from mcp_server.core.codebase_communities import (
128
compute_centrality,
139
detect_communities,
@@ -20,6 +16,39 @@
2016
# ── Import resolution ─────────────────────────────────────────────────────
2117

2218

19+
def _posix_normalize(path: str) -> str:
20+
"""Pure-string equivalent of ``str(PurePosixPath(path))`` (no filesystem
21+
access). Collapses empty/"." segments, keeps ".." literal, keeps a
22+
leading "/". Pinned equal to PurePosixPath by
23+
tests_py/core/test_codebase_graph.py::TestPosixPathHelpers.
24+
25+
source: issue #560 (core/ may not import pathlib)
26+
"""
27+
if not path:
28+
return "."
29+
is_abs = path.startswith("/")
30+
segments = [seg for seg in path.split("/") if seg not in ("", ".")]
31+
if not segments:
32+
return "/" if is_abs else "."
33+
body = "/".join(segments)
34+
return f"/{body}" if is_abs else body
35+
36+
37+
def _posix_parent(path: str) -> str:
38+
"""Pure-string equivalent of ``PurePosixPath(path).parent``; "." and "/"
39+
are their own parent. source: issue #560 (core/ may not import pathlib)
40+
"""
41+
normalized = _posix_normalize(path)
42+
if normalized in (".", "/"):
43+
return normalized
44+
is_abs = normalized.startswith("/")
45+
segments = normalized[1:].split("/") if is_abs else normalized.split("/")
46+
if len(segments) <= 1:
47+
return "/" if is_abs else "."
48+
parent_body = "/".join(segments[:-1])
49+
return f"/{parent_body}" if is_abs else parent_body
50+
51+
2352
def resolve_import_to_file(
2453
module: str,
2554
importing_file: str,
@@ -39,7 +68,7 @@ def resolve_import_to_file(
3968
"""
4069
candidates = _build_candidates(module, importing_file, is_relative)
4170
for candidate in candidates:
42-
normalized = str(PurePosixPath(candidate))
71+
normalized = _posix_normalize(candidate)
4372
if normalized in known_files:
4473
return normalized
4574
return None
@@ -54,7 +83,7 @@ def _build_candidates(
5483
candidates: list[str] = []
5584

5685
if is_relative:
57-
base_dir = str(PurePosixPath(importing_file).parent)
86+
base_dir = _posix_parent(importing_file)
5887
clean = module.lstrip(".")
5988
if clean:
6089
rel = clean.replace(".", "/")
@@ -184,8 +213,6 @@ def build_resolved_call_edges(
184213
``[(caller_file, caller_qname, callee_file, callee_qname), ...]``.
185214
The fourth position is the full qualified callee name, e.g. Foo.baz.
186215
source: ADR-0127"""
187-
# source: ADR-0127
188-
189216
symbol_to_qname: dict[str, tuple[str, str]] = {}
190217
for analysis in analyses:
191218
for sym in analysis.definitions:
Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
"""Abstention classifier loading — filesystem boundary for core/abstention_gate.py.
2+
3+
source: ADR-0097 (issue #560: core/ may not import os/pathlib)
4+
"""
5+
6+
from __future__ import annotations
7+
8+
import logging
9+
from pathlib import Path
10+
from typing import Any
11+
12+
logger = logging.getLogger(__name__)
13+
14+
15+
def load_abstention_classifier() -> Any | None:
16+
"""Load the cortex-beam-abstain classifier from its on-disk cache.
17+
18+
Precondition: none (safe to call with the optional dependency absent).
19+
Postcondition: returns a loaded ``AbstentionClassifier`` instance, or
20+
``None`` if the optional ``cortex-beam-abstain`` package is not
21+
installed or fails to load — callers must treat ``None`` as
22+
"no filtering available". Performs a filesystem read
23+
(``~/.cache/cortex-abstention/model.onnx`` existence check) and, on a
24+
cache miss, an auto-download; this is exactly why the function lives
25+
in infrastructure/ and not core/abstention_gate.py (core is zero-I/O).
26+
27+
source: ADR-0097
28+
"""
29+
try:
30+
# Lazy import — package is optional
31+
from cortex_beam_abstain import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] — source: ADR-0097
32+
AbstentionClassifier,
33+
)
34+
35+
cache = Path.home() / ".cache" / "cortex-abstention" / "model.onnx"
36+
if cache.exists():
37+
return AbstentionClassifier(model_path=cache)
38+
return AbstentionClassifier() # auto-download
39+
except ImportError:
40+
logger.debug(
41+
"cortex-beam-abstain not installed; abstention gate disabled. "
42+
"Install: pip install cortex-beam-abstain"
43+
)
44+
return None
45+
except Exception as e: # noqa: BLE001 — source: ADR-0097
46+
logger.warning("Failed to load abstention classifier: %s", e)
47+
return None

‎tests_py/core/test_abstention_gate.py‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,53 @@ def test_no_op_when_model_unavailable(self, monkeypatch):
2424
assert len(result) == 2
2525
assert scores == [1.0, 1.0]
2626

27+
def test_no_classifier_factory_disables_filtering(self, monkeypatch):
28+
"""No injected factory (the composition-root seam) means no filtering,
29+
matching the historical "model not installed" fallback — proves the
30+
os/pathlib-free core function never silently loads a classifier on
31+
its own. source: issue #560"""
32+
from mcp_server.core import abstention_gate
33+
34+
monkeypatch.setattr(abstention_gate, "_classifier", None)
35+
monkeypatch.setattr(abstention_gate, "_load_attempted", False)
36+
37+
candidates = [{"memory_id": 1, "content": "test"}]
38+
result, scores = filter_by_abstention(
39+
"query", candidates, classifier_factory=None
40+
)
41+
assert len(result) == 1
42+
assert scores == [1.0]
43+
44+
def test_classifier_factory_is_invoked_and_memoized(self, monkeypatch):
45+
"""Injecting a factory (infrastructure's runtime seam) makes the
46+
classifier take effect; a second call reuses the memoized instance
47+
without invoking the factory again. source: issue #560"""
48+
from mcp_server.core import abstention_gate
49+
50+
monkeypatch.setattr(abstention_gate, "_classifier", None)
51+
monkeypatch.setattr(abstention_gate, "_load_attempted", False)
52+
53+
class MockClf:
54+
def predict_batch(self, pairs):
55+
return [0.9] * len(pairs)
56+
57+
calls = {"n": 0}
58+
59+
def factory():
60+
calls["n"] += 1
61+
return MockClf()
62+
63+
candidates = [{"memory_id": 1, "content": "test"}]
64+
result, scores = filter_by_abstention(
65+
"query", candidates, classifier_factory=factory
66+
)
67+
assert scores == [0.9]
68+
assert calls["n"] == 1
69+
70+
# Second call: memoized, factory not invoked again.
71+
filter_by_abstention("query", candidates, classifier_factory=factory)
72+
assert calls["n"] == 1
73+
2774
def test_keep_at_least_returns_top_n(self, monkeypatch):
2875
"""When threshold filters everything, keep_at_least falls back to top-N."""
2976
from mcp_server.core import abstention_gate

‎tests_py/core/test_codebase_graph.py‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
from __future__ import annotations
44

5+
from pathlib import PurePosixPath
56

67
from mcp_server.core.codebase_parser import FileAnalysis, ImportInfo, SymbolDef
78
from mcp_server.core.codebase_graph import (
@@ -11,9 +12,42 @@
1112
detect_communities,
1213
compute_impact,
1314
build_call_edges,
15+
_posix_normalize,
16+
_posix_parent,
1417
)
1518
from mcp_server.core.codebase_type_resolver import resolve_type_references
1619

20+
21+
class TestPosixPathHelpers:
22+
"""core/codebase_graph.py may not import pathlib (issue #560); these pure
23+
string helpers must match PurePosixPath semantics exactly — the test
24+
imports pathlib itself (a test, not core, may) to pin the equivalence."""
25+
26+
_CASES = [
27+
"a/b/../c",
28+
"./a",
29+
"a//b",
30+
"",
31+
"a/",
32+
"/c.py",
33+
"a/b/c.py",
34+
"c.py",
35+
"/a/b",
36+
".",
37+
"/",
38+
"a",
39+
"/a",
40+
]
41+
42+
def test_normalize_matches_purepath(self) -> None:
43+
for case in self._CASES:
44+
assert _posix_normalize(case) == str(PurePosixPath(case)), case
45+
46+
def test_parent_matches_purepath(self) -> None:
47+
for case in self._CASES:
48+
assert _posix_parent(case) == str(PurePosixPath(case).parent), case
49+
50+
1751
_has_networkx = True
1852
try:
1953
import networkx # noqa: F401

0 commit comments

Comments
 (0)