modern-python-guidance 0.4.0__tar.gz → 0.4.2__tar.gz

{modern_python_guidance-0.4.0 → modern_python_guidance-0.4.2}/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.2] — 2026-06-04
+
+### Fixed
+
+- `_find_project_root()` escaping to `$HOME` when `~/.claude/` exists but the repo has no `.claude/` directory. Marker search is now per-level (nearest ancestor with any marker wins) instead of per-marker-type. If you previously ran `mpg setup` and have stale symlinks at `~/.claude/skills/modern-python-guidance` or `~/.claude/rules/modern-python.md`, remove them manually. (closes #90)
+
+## [0.4.1] — 2026-06-03
+
+### Added
+
+- Body text search indexing: API names and identifiers appearing only in guide body text (e.g. `aiter_bytes`, `from_attributes`, `serialize_timestamp`) are now discoverable via `mpg search`. Body matches score at `WEIGHT_BODY=2`, below all frontmatter weights (TAG=10, ALIAS=8, TITLE=5, CATEGORY=3), preserving existing metadata-dominant ranking. Two-tier query tokenization handles code fragments like `aiter_bytes()` and `from_attributes=True`. (closes #22)
+- 25 new tests (911 total).
+
 ## [0.4.0] — 2026-06-03
 
 ### Added

{modern_python_guidance-0.4.0 → modern_python_guidance-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modern-python-guidance
-Version: 0.4.0
+Version: 0.4.2
 Summary: Version-aware BAD/GOOD pattern guides that help AI coding agents generate modern Python
 Project-URL: Homepage, https://github.com/yottayoshida/modern-python-guidance
 Project-URL: Repository, https://github.com/yottayoshida/modern-python-guidance

{modern_python_guidance-0.4.0 → modern_python_guidance-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "modern-python-guidance"
-version = "0.4.0"
+version = "0.4.2"
 description = "Version-aware BAD/GOOD pattern guides that help AI coding agents generate modern Python"
 readme = "README.md"
 license = "Apache-2.0 OR MIT"

{modern_python_guidance-0.4.0 → modern_python_guidance-0.4.2}/src/modern_python_guidance/__init__.py

@@ -1,3 +1,3 @@
 """Modern Python Guidance — version-aware BAD/GOOD pattern guides for AI coding agents."""
 
-__version__ = "0.4.0"
+__version__ = "0.4.2"

{modern_python_guidance-0.4.0 → modern_python_guidance-0.4.2}/src/modern_python_guidance/guide_index.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import importlib.resources
 import logging
+import re
 from dataclasses import dataclass, field
 from itertools import zip_longest
 from pathlib import Path
@@ -13,12 +14,17 @@ from modern_python_guidance.frontmatter import FrontmatterError, GuideMeta, pars
 log = logging.getLogger(__name__)
 
 
+_DOTTED_IDENT_RE = re.compile(r"[a-zA-Z_]\w+(?:\.[a-zA-Z_]\w+)*")
+_URL_RE = re.compile(r"https?://")
+
+
 @dataclass
 class Guide:
     meta: GuideMeta
     body: str
     source_path: str
     snippet: str = ""
+    body_tokens: frozenset[str] = field(default_factory=frozenset)
 
 
 @dataclass
@@ -71,6 +77,7 @@ def build_index(guides_dir: Path | None = None) -> GuideIndex:
                 body=body,
                 source_path=str(md_file),
                 snippet=_extract_snippet(body),
+                body_tokens=_tokenize_body(body),
             )
         except FrontmatterError as e:
             log.warning("Skipping %s: %s", md_file, e)
@@ -117,6 +124,24 @@ def _code_lines(body: str, heading: str) -> list[str]:
     return lines
 
 
+def _tokenize_body(body: str) -> frozenset[str]:
+    """Extract lowercased identifiers from guide body for search indexing."""
+    tokens: set[str] = set()
+    for line in body.splitlines():
+        stripped = line.strip()
+        if _URL_RE.search(stripped):
+            continue
+        if stripped.startswith("```"):
+            continue
+        cleaned = stripped.replace("`", "").lstrip("#").strip()
+        for match in _DOTTED_IDENT_RE.findall(cleaned):
+            lower = match.lower()
+            tokens.add(lower)
+            if "." in lower:
+                tokens.update(lower.split("."))
+    return frozenset(tokens)
+
+
 def _find_guides_dir() -> Path:
     try:
         skills_pkg = importlib.resources.files("modern_python_guidance") / "skills"

{modern_python_guidance-0.4.0 → modern_python_guidance-0.4.2}/src/modern_python_guidance/search.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import difflib
+import re
 from dataclasses import dataclass
 
 from modern_python_guidance.compat import token_estimate, version_compatible
@@ -13,6 +14,7 @@ WEIGHT_TAG = 10
 WEIGHT_ALIAS = 8
 WEIGHT_TITLE = 5
 WEIGHT_CATEGORY = 3
+WEIGHT_BODY = 2
 
 FREQ_BOOST = {"high": 1.0, "medium": 0.5, "low": 0.0}
 
@@ -45,6 +47,8 @@ def search(
     if not tokens:
         return []
 
+    query_idents = frozenset(re.findall(r"[a-zA-Z_]\w+", query))
+
     results: list[SearchResult] = []
 
     for guide_id, guide in index.guides.items():
@@ -56,7 +60,7 @@ def search(
         if python_version and not version_compatible(meta.python, python_version):
             continue
 
-        score = _score(meta, tokens)
+        score = _score(meta, tokens, guide.body_tokens, query_idents)
 
         if score > 0:
             score += FREQ_BOOST.get(meta.frequency, 0.0)
@@ -84,7 +88,12 @@ def search(
     return results[:limit]
 
 
-def _score(meta: GuideMeta, tokens: list[str]) -> float:
+def _score(
+    meta: GuideMeta,
+    tokens: list[str],
+    body_tokens: frozenset[str],
+    query_idents: frozenset[str],
+) -> float:
     score = 0.0
     tags_lower = [t.lower() for t in meta.tags]
     aliases_lower = [a.lower() for a in meta.aliases]
@@ -102,6 +111,10 @@ def _score(meta: GuideMeta, tokens: list[str]) -> float:
         if token == meta.category.lower():
             score += WEIGHT_CATEGORY
 
+    for ident in query_idents:
+        if ident in body_tokens:
+            score += WEIGHT_BODY
+
     return score
 
 

{modern_python_guidance-0.4.0 → modern_python_guidance-0.4.2}/src/modern_python_guidance/setup_cmd.py

@@ -61,20 +61,19 @@ def _find_rule_source() -> Path:
 
 
 def _find_project_root(start: Path | None = None) -> Path:
-    """Walk upward from *start* to find the project root."""
+    """Walk upward; return the nearest ancestor containing any marker."""
     current = (start or Path.cwd()).resolve()
-    markers = [".claude", ".git", "pyproject.toml"]
+    markers = [".git", "pyproject.toml", ".claude"]
 
-    for marker in markers:
-        d = current
-        while True:
-            candidate = d / marker
-            if candidate.exists():
+    d = current
+    while True:
+        for marker in markers:
+            if (d / marker).exists():
                 return d
-            parent = d.parent
-            if parent == d:
-                break
-            d = parent
+        parent = d.parent
+        if parent == d:
+            break
+        d = parent
 
     return current
 

{modern_python_guidance-0.4.0 → modern_python_guidance-0.4.2}/tests/test_guide_index.py

@@ -10,6 +10,7 @@ from modern_python_guidance.guide_index import (
     GuideIndex,
     _code_lines,
     _find_guides_dir,
+    _tokenize_body,
     build_index,
 )
 
@@ -216,6 +217,95 @@ class TestBuildIndex:
 # ---------------------------------------------------------------------------
 
 
+class TestTokenizeBody:
+    def test_empty_body(self):
+        assert _tokenize_body("") == frozenset()
+
+    def test_extracts_identifiers(self):
+        body = "Use `model_dump()` instead of `.dict()`."
+        tokens = _tokenize_body(body)
+        assert "model_dump" in tokens
+        assert "dict" in tokens
+
+    def test_extracts_multi_word_identifiers(self):
+        body = "Call `field_validator` and `model_validate_json`."
+        tokens = _tokenize_body(body)
+        assert "field_validator" in tokens
+        assert "model_validate_json" in tokens
+
+    def test_url_lines_excluded(self):
+        body = (
+            "See https://docs.python.org/3/library/datetime.html for details.\n"
+            "Use `utcnow` instead."
+        )
+        tokens = _tokenize_body(body)
+        assert "python" not in tokens
+        assert "datetime" not in tokens
+        assert "utcnow" in tokens
+
+    def test_fence_markers_excluded_code_preserved(self):
+        body = "```python\naiter_bytes = True\n```\n"
+        tokens = _tokenize_body(body)
+        assert "aiter_bytes" in tokens
+        assert "python" not in tokens
+
+    def test_dot_split_qualified_names(self):
+        body = "Replace `datetime.utcnow` with `datetime.now(tz=UTC)`."
+        tokens = _tokenize_body(body)
+        assert "datetime.utcnow" in tokens
+        assert "datetime" in tokens
+        assert "utcnow" in tokens
+
+    def test_heading_markers_stripped(self):
+        body = "## Migration Guide\nUse `new_api` now."
+        tokens = _tokenize_body(body)
+        assert "migration" in tokens
+        assert "new_api" in tokens
+
+    def test_backticks_stripped(self):
+        body = "Use `AsyncClient` with `base_url`."
+        tokens = _tokenize_body(body)
+        assert "asyncclient" in tokens
+        assert "base_url" in tokens
+
+    def test_returns_frozenset(self):
+        result = _tokenize_body("some text")
+        assert isinstance(result, frozenset)
+
+    def test_single_char_identifiers_excluded(self):
+        body = "x = a + b"
+        tokens = _tokenize_body(body)
+        assert "x" not in tokens
+        assert "a" not in tokens
+        assert "b" not in tokens
+
+
+class TestBuildIndexBodyTokens:
+    def test_body_tokens_populated(self, tmp_path: Path):
+        (tmp_path / "guide-a.md").write_text(
+            _make_guide_md(guide_id="guide-a", bad_code="old_api()", good_code="new_api()")
+        )
+        idx = build_index(tmp_path)
+        guide = idx.get("guide-a")
+        assert guide is not None
+        assert isinstance(guide.body_tokens, frozenset)
+        assert "old_api" in guide.body_tokens
+        assert "new_api" in guide.body_tokens
+
+    def test_body_tokens_default_empty(self):
+        meta = GuideMeta(
+            id="a",
+            title="A",
+            category="c",
+            layer=1,
+            tags=["t"],
+            python=">=3.9",
+            frequency="high",
+        )
+        guide = Guide(meta=meta, body="", source_path="a.md")
+        assert guide.body_tokens == frozenset()
+
+
 class TestCodeLines:
     def test_basic_extraction(self):
         body = "## BAD\n```python\nold()\nnew()\n```\n"

{modern_python_guidance-0.4.0 → modern_python_guidance-0.4.2}/tests/test_search.py

@@ -4,8 +4,9 @@ from pathlib import Path
 
 import pytest
 
-from modern_python_guidance.guide_index import _extract_snippet, build_index
-from modern_python_guidance.search import search
+from modern_python_guidance.frontmatter import GuideMeta
+from modern_python_guidance.guide_index import Guide, GuideIndex, _extract_snippet, build_index
+from modern_python_guidance.search import WEIGHT_BODY, search
 
 GUIDES_DIR = Path(__file__).parent.parent / "skills" / "modern-python-guidance" / "guides"
 
@@ -192,6 +193,101 @@ class TestSnippetExtraction:
         assert snippet == ""
 
 
+class TestBodySearch:
+    """Body text is indexed at WEIGHT_BODY=2, discoverable but below frontmatter."""
+
+    def test_body_only_match_aiter_bytes(self, index):
+        results = search(index, "aiter_bytes")
+        assert len(results) >= 1
+        assert results[0].guide_id == "httpx-streaming"
+        assert not results[0].fuzzy
+
+    def test_body_only_match_serialize_timestamp(self, index):
+        results = search(index, "serialize_timestamp")
+        assert len(results) >= 1
+        assert results[0].guide_id == "pydantic-v2-serialization"
+
+    def test_body_only_match_from_attributes(self, index):
+        results = search(index, "from_attributes")
+        ids = [r.guide_id for r in results]
+        assert "pydantic-v2-config" in ids
+
+    def test_code_fragment_with_parens(self, index):
+        results = search(index, "aiter_bytes()")
+        assert len(results) >= 1
+        assert results[0].guide_id == "httpx-streaming"
+
+    def test_code_fragment_with_equals(self, index):
+        results = search(index, "from_attributes=True")
+        ids = [r.guide_id for r in results]
+        assert "pydantic-v2-config" in ids
+
+    def test_body_score_below_frontmatter(self, index):
+        results = search(index, "typing")
+        assert results[0].guide_id == "use-builtin-generics"
+        assert results[0].score >= 10
+
+    def test_body_match_gets_frequency_boost(self, index):
+        results = search(index, "aiter_bytes")
+        r = results[0]
+        assert r.score > 2.0
+
+    def test_metadata_ranking_preserved(self, index):
+        results = search(index, "typing")
+        assert results[0].guide_id == "use-builtin-generics"
+
+    def test_fuzzy_fallback_still_works(self, index):
+        results = search(index, "genercs")
+        assert len(results) > 0
+        assert results[0].fuzzy is True
+
+
+class TestBodySearchSynthetic:
+    """Synthetic index tests for exact score verification — no real guide dependency."""
+
+    @pytest.fixture
+    def synthetic_index(self):
+        meta = GuideMeta(
+            id="synth",
+            title="Synthetic Guide",
+            category="testing",
+            layer=1,
+            tags=["unrelated_tag"],
+            python=">=3.9",
+            frequency="low",
+        )
+        guide = Guide(
+            meta=meta,
+            body="",
+            source_path="synth.md",
+            body_tokens=frozenset(
+                ["target_api", "another_api", "datetime.utcnow", "datetime", "utcnow"]
+            ),
+        )
+        return GuideIndex(guides={"synth": guide})
+
+    def test_exact_body_only_score(self, synthetic_index):
+        results = search(synthetic_index, "target_api")
+        assert len(results) == 1
+        assert results[0].score == WEIGHT_BODY
+
+    def test_multiple_idents_score_additive(self, synthetic_index):
+        results = search(synthetic_index, "target_api another_api")
+        assert len(results) == 1
+        assert results[0].score == WEIGHT_BODY * 2
+
+    def test_dotted_query_matches_split_parts(self, synthetic_index):
+        results = search(synthetic_index, "datetime.utcnow()")
+        assert len(results) == 1
+        ids_matched = {"datetime", "utcnow"}
+        assert results[0].score == WEIGHT_BODY * len(ids_matched)
+
+    def test_body_match_suppresses_fuzzy(self, synthetic_index):
+        results = search(synthetic_index, "target_api")
+        assert len(results) >= 1
+        assert not results[0].fuzzy
+
+
 class TestEdgeCases:
     def test_empty_query(self, index):
         results = search(index, "")

{modern_python_guidance-0.4.0 → modern_python_guidance-0.4.2}/tests/test_setup.py

@@ -59,13 +59,31 @@ class TestFindProjectRoot:
         sub.mkdir(parents=True)
         assert _find_project_root(sub) == tmp_path
 
-    def test_claude_takes_priority_over_git(self, tmp_path: Path):
-        """.claude/ at parent wins over .git/ at child (higher-priority marker)."""
+    def test_nearest_marker_wins(self, tmp_path: Path):
+        """Nearest ancestor with any marker wins over distant ancestor."""
         (tmp_path / ".claude").mkdir()
         child = tmp_path / "child"
         child.mkdir()
         (child / ".git").mkdir()
-        assert _find_project_root(child) == tmp_path
+        assert _find_project_root(child) == child
+
+    def test_bug_repro_home_claude_escapes(self, tmp_path: Path):
+        """V-001: .claude at home + .git at repo -> repo wins, not home."""
+        home = tmp_path / "home"
+        (home / ".claude").mkdir(parents=True)
+        repo = home / "projects" / "repo"
+        repo.mkdir(parents=True)
+        (repo / ".git").mkdir()
+        src = repo / "src"
+        src.mkdir()
+        assert _find_project_root(src) == repo
+
+    def test_git_as_file(self, tmp_path: Path):
+        """V-008: .git as a file (worktree/submodule) is detected."""
+        (tmp_path / ".git").write_text("gitdir: /some/other/path")
+        sub = tmp_path / "src"
+        sub.mkdir()
+        assert _find_project_root(sub) == tmp_path
 
     def test_falls_back_to_cwd(self, tmp_path: Path):
         bare = tmp_path / "empty"
@@ -308,6 +326,24 @@ class TestSetupSkills:
         err = capsys.readouterr().err
         assert "'" in err or '"' in err
 
+    def test_autodetect_avoids_home_escape(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        """setup_skills auto-discovers repo root, not distant ~/.claude."""
+        source = self._make_source(tmp_path)
+        home = tmp_path / "home"
+        (home / ".claude").mkdir(parents=True)
+        repo = home / "projects" / "repo"
+        repo.mkdir(parents=True)
+        (repo / ".git").mkdir()
+
+        monkeypatch.chdir(repo)
+        with patch("modern_python_guidance.setup_cmd._find_skills_dir", return_value=source):
+            ok = setup_skills()
+
+        assert ok is True
+        link = repo / ".claude" / "skills" / "modern-python-guidance"
+        assert link.is_symlink()
+        assert not (home / ".claude" / "skills" / "modern-python-guidance").exists()
+
     def test_dry_run(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]):
         """V-010: dry-run does not create symlink."""
         source = self._make_source(tmp_path)

{modern_python_guidance-0.4.0 → modern_python_guidance-0.4.2}/tests/test_uninstall.py

@@ -248,6 +248,27 @@ class TestUninstallSkills:
         assert link.is_symlink()  # still there
         assert "Would remove" in capsys.readouterr().out
 
+    def test_resolves_correct_root_not_distant_ancestor(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ):
+        """V-009: uninstall resolves nearest project root, not distant ancestor."""
+        home = tmp_path / "home"
+        (home / ".claude" / "skills" / "modern-python-guidance").mkdir(parents=True)
+        repo = home / "projects" / "repo"
+        repo.mkdir(parents=True)
+        (repo / ".git").mkdir()
+        link = repo / ".claude" / "skills" / "modern-python-guidance"
+        link.parent.mkdir(parents=True)
+        os.symlink(tmp_path / "pkg_skills", link)
+
+        monkeypatch.chdir(repo)
+        ok = uninstall_skills()
+
+        assert ok is True
+        assert not link.is_symlink()
+        # Home-level skills dir must be untouched
+        assert (home / ".claude" / "skills" / "modern-python-guidance").is_dir()
+
     def test_non_symlink_path_quoted(self, tmp_path: Path, capsys):
         """V-028: rm hint uses shell-safe quoting for paths with spaces."""
         project = tmp_path / "my project"