modern-python-guidance 0.3.6__tar.gz → 0.3.8__tar.gz

{modern_python_guidance-0.3.6 → modern_python_guidance-0.3.8}/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.8] — 2026-06-02
+
+### Added
+
+- Fuzzy suggestions on retrieve miss: when a guide ID is not found, `difflib.get_close_matches` suggests up to 3 similar IDs (cutoff=0.5, case-insensitive). CLI shows "Did you mean:" in human format; JSON format and MCP tool return an envelope `{"results": [...], "not_found": [{"id": ..., "suggestions": [...]}]}`. Bare list preserved on all-found for backward compatibility. Exit code 1 when any ID is not found. (closes #14)
+
+### Fixed
+
+- `_handle_request` crash on non-dict JSON input (list, string, number, bool): now returns JSON-RPC -32600 "Invalid Request" error instead of `AttributeError`. Server continues processing subsequent requests. (closes #82)
+
+## [0.3.7] — 2026-06-02
+
+### Fixed
+
+- `_read_message` CWE-674 recursion bug: ~1000 consecutive blank lines on MCP stdin would crash the server with `RecursionError`. Replaced recursive call with iterative `while` loop.
+
+### Added
+
+- 86 in-process unit tests for `cli.py` (33) and `mcp_server.py` (53), raising per-file coverage from 0% to 96%. Covers CLI dispatch, format auto-detection, search/retrieve/list subcommands, `_confine_path` security (8 patterns including symlink escape and CWD=/ guard), JSON-RPC framing, request handling, and serve loop recovery.
+
+### Changed
+
+- Coverage `fail_under` ratcheted from 59% to 92% (actual: 92.48%)
+- CONTRIBUTING.md coverage gate updated to match
+
 ## [0.3.6] — 2026-05-31
 
 ### Added

{modern_python_guidance-0.3.6 → modern_python_guidance-0.3.8}/CONTRIBUTING.md

@@ -58,4 +58,4 @@ All PRs run these checks on Python 3.11, 3.12, and 3.13:
 
 1. `ruff format --check` — formatting
 2. `ruff check` — linting
-3. `pytest --cov` — tests with branch coverage (`fail_under = 59%`)
+3. `pytest --cov` — tests with branch coverage (`fail_under = 92%`)

{modern_python_guidance-0.3.6 → modern_python_guidance-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modern-python-guidance
-Version: 0.3.6
+Version: 0.3.8
 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.3.6 → modern_python_guidance-0.3.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "modern-python-guidance"
-version = "0.3.6"
+version = "0.3.8"
 description = "Version-aware BAD/GOOD pattern guides that help AI coding agents generate modern Python"
 readme = "README.md"
 license = "Apache-2.0 OR MIT"
@@ -76,7 +76,7 @@ branch = true
 [tool.coverage.report]
 show_missing = true
 skip_empty = true
-fail_under = 59
+fail_under = 92
 exclude_lines = [
     "pragma: no cover",
     "if __name__ == .__main__.",

{modern_python_guidance-0.3.6 → modern_python_guidance-0.3.8}/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.3.6"
+__version__ = "0.3.8"

{modern_python_guidance-0.3.6 → modern_python_guidance-0.3.8}/src/modern_python_guidance/cli.py

@@ -12,7 +12,7 @@ from pathlib import Path
 from modern_python_guidance import __version__
 from modern_python_guidance.compat import VERSION_RE, version_compatible
 from modern_python_guidance.guide_index import build_index
-from modern_python_guidance.retrieve import retrieve
+from modern_python_guidance.retrieve import retrieve, suggest_ids
 from modern_python_guidance.search import search as do_search
 from modern_python_guidance.version_detect import detect_version
 
@@ -191,26 +191,42 @@ def _cmd_search(args: argparse.Namespace) -> None:
 
 def _cmd_retrieve(args: argparse.Namespace) -> None:
     index = build_index()
-    guide_ids = [gid.strip() for gid in args.ids.split(",")]
+    guide_ids = [gid.strip() for gid in args.ids.split(",") if gid.strip()]
+    if not guide_ids:
+        print("No guide IDs provided.")
+        sys.exit(1)
     results = retrieve(index, guide_ids, python_version=args.python_version)
 
-    fmt = _resolve_format(args)
+    found_ids = {r["id"] for r in results}
+    missing = [gid for gid in guide_ids if gid not in found_ids]
 
-    if not results:
-        if fmt == "human":
-            print("No guides found.")
-        else:
-            print("[]")
-        sys.exit(1)
+    fmt = _resolve_format(args)
 
     if fmt == "json":
-        print(json.dumps(results, indent=2, ensure_ascii=False))
+        if missing:
+            not_found = [{"id": gid, "suggestions": suggest_ids(index, gid)} for gid in missing]
+            envelope = {"results": results, "not_found": not_found}
+            print(json.dumps(envelope, indent=2, ensure_ascii=False))
+        else:
+            print(json.dumps(results, indent=2, ensure_ascii=False))
     else:
         for r in results:
             match_str = "YES" if r["version_match"] else "NO"
             print(f"--- {r['id']} (version match: {match_str}) ---")
             print(r["content"])
             print()
+        for gid in missing:
+            suggestions = suggest_ids(index, gid)
+            if suggestions:
+                print(f"No guide found for '{gid}'. Did you mean:")
+                for s in suggestions:
+                    print(f"  {s}")
+            else:
+                print(f"No guide found for '{gid}'.")
+                print("Run 'mpg list' to see available guides.")
+
+    if missing:
+        sys.exit(1)
 
 
 def _cmd_list(args: argparse.Namespace) -> None:

{modern_python_guidance-0.3.6 → modern_python_guidance-0.3.8}/src/modern_python_guidance/mcp_server.py

@@ -10,7 +10,7 @@ from pathlib import Path
 from modern_python_guidance import __version__
 from modern_python_guidance.compat import VERSION_RE
 from modern_python_guidance.guide_index import GuideIndex, build_index
-from modern_python_guidance.retrieve import retrieve
+from modern_python_guidance.retrieve import retrieve, suggest_ids
 from modern_python_guidance.search import search
 from modern_python_guidance.version_detect import detect_version
 
@@ -35,12 +35,13 @@ class _Skip(Exception):
 
 def _read_message(stream: object = None) -> dict | None:
     buf = stream or sys.stdin
-    line = buf.readline()
-    if not line:
-        return None
-    line = line.strip()
-    if not line:
-        return _read_message(stream)
+    while True:
+        line = buf.readline()
+        if not line:
+            return None
+        line = line.strip()
+        if line:
+            break
     try:
         return json.loads(line)
     except json.JSONDecodeError as exc:
@@ -279,6 +280,14 @@ def _tool_retrieve(arguments: dict) -> dict:
 
     index = _get_index()
     results = retrieve(index, guide_ids, python_version=pv)
+
+    found_ids = {r["id"] for r in results}
+    missing = [gid for gid in guide_ids if gid not in found_ids]
+    if missing:
+        not_found = [{"id": gid, "suggestions": suggest_ids(index, gid)} for gid in missing]
+        envelope = {"results": results, "not_found": not_found}
+        return _tool_result(json.dumps(envelope, indent=2, ensure_ascii=False))
+
     return _tool_result(json.dumps(results, indent=2, ensure_ascii=False))
 
 
@@ -331,6 +340,8 @@ PROTOCOL_VERSION = "2024-11-05"
 
 
 def _handle_request(msg: dict) -> dict | None:
+    if not isinstance(msg, dict):
+        return _error_response(None, -32600, "Invalid Request: expected JSON object")
     method = msg.get("method", "")
     req_id = msg.get("id")
     params = msg.get("params", {})

{modern_python_guidance-0.3.6 → modern_python_guidance-0.3.8}/src/modern_python_guidance/retrieve.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import difflib
 import json
 from typing import Any
 
@@ -9,6 +10,18 @@ from modern_python_guidance import __version__
 from modern_python_guidance.compat import token_estimate, version_compatible
 from modern_python_guidance.guide_index import Guide, GuideIndex
 
+MAX_ID_LEN = 200
+_SUGGEST_CUTOFF = 0.5
+_SUGGEST_MAX = 3
+
+
+def suggest_ids(index: GuideIndex, missing_id: str) -> list[str]:
+    if not isinstance(missing_id, str):
+        return []
+    truncated = missing_id[:MAX_ID_LEN].lower()
+    all_ids = list(index.guides.keys())
+    return difflib.get_close_matches(truncated, all_ids, n=_SUGGEST_MAX, cutoff=_SUGGEST_CUTOFF)
+
 
 def retrieve(
     index: GuideIndex,

modern_python_guidance-0.3.8/tests/test_cli_unit.py

@@ -0,0 +1,265 @@
+"""In-process unit tests for cli.py — direct function calls for coverage."""
+
+from __future__ import annotations
+
+import json
+import sys
+from unittest.mock import patch
+
+import pytest
+
+from modern_python_guidance.cli import _resolve_format, main
+
+
+class TestMainDispatch:
+    def test_no_command_exits_2(self, capsys):
+        with pytest.raises(SystemExit, match="2"):
+            main(argv=[])
+
+    def test_version_flag(self, capsys):
+        from modern_python_guidance import __version__
+
+        with pytest.raises(SystemExit, match="0"):
+            main(argv=["--version"])
+        assert __version__ in capsys.readouterr().out
+
+    def test_invalid_python_version_exits(self, capsys):
+        with pytest.raises(SystemExit, match="2"):
+            main(argv=["search", "typing", "--python-version", "abc"])
+
+    def test_broken_pipe_exits_0(self, monkeypatch):
+        def raise_broken_pipe(*_a, **_kw):
+            raise BrokenPipeError
+
+        monkeypatch.setattr("modern_python_guidance.cli.do_search", raise_broken_pipe)
+        with pytest.raises(SystemExit, match="0"):
+            main(argv=["search", "typing"])
+
+
+class TestResolveFormat:
+    def test_explicit_json(self):
+        ns = _make_ns(format="json")
+        assert _resolve_format(ns) == "json"
+
+    def test_explicit_human(self):
+        ns = _make_ns(format="human")
+        assert _resolve_format(ns) == "human"
+
+    def test_auto_tty(self, monkeypatch):
+        monkeypatch.setattr(sys.stdout, "isatty", lambda: True)
+        ns = _make_ns(format=None)
+        assert _resolve_format(ns) == "human"
+
+    def test_auto_pipe(self, monkeypatch):
+        monkeypatch.setattr(sys.stdout, "isatty", lambda: False)
+        ns = _make_ns(format=None)
+        assert _resolve_format(ns) == "json"
+
+
+class TestCmdSearch:
+    def test_json_output(self, capsys):
+        main(argv=["search", "typing list", "--format", "json"])
+        data = json.loads(capsys.readouterr().out)
+        assert isinstance(data, list)
+        assert len(data) >= 1
+
+    def test_human_output(self, capsys):
+        main(argv=["search", "typing", "--format", "human"])
+        out = capsys.readouterr().out
+        assert "use-builtin-generics" in out
+
+    def test_no_match_exits_1(self, capsys):
+        with pytest.raises(SystemExit, match="1"):
+            main(argv=["search", "qqqxxx999zzz", "--format", "json"])
+
+    def test_no_match_human_exits_1(self, capsys):
+        with pytest.raises(SystemExit, match="1"):
+            main(argv=["search", "qqqxxx999zzz", "--format", "human"])
+        assert "No guides found" in capsys.readouterr().out
+
+    def test_fuzzy_marker(self, capsys):
+        main(argv=["search", "typng", "--format", "human"])
+        out = capsys.readouterr().out
+        assert "(fuzzy)" in out or "use-builtin-generics" in out
+
+    def test_category_filter(self, capsys):
+        main(argv=["search", "typing", "--category", "typing", "--format", "json"])
+        data = json.loads(capsys.readouterr().out)
+        assert data
+        for item in data:
+            assert item["category"] == "typing"
+
+    def test_limit(self, capsys):
+        main(argv=["search", "python", "--limit", "2", "--format", "json"])
+        data = json.loads(capsys.readouterr().out)
+        assert len(data) <= 2
+
+
+class TestCmdRetrieve:
+    def test_json_output(self, capsys):
+        main(argv=["retrieve", "use-builtin-generics", "--format", "json"])
+        data = json.loads(capsys.readouterr().out)
+        assert isinstance(data, list)
+        assert data[0]["id"] == "use-builtin-generics"
+
+    def test_human_output(self, capsys):
+        main(argv=["retrieve", "use-builtin-generics", "--format", "human"])
+        out = capsys.readouterr().out
+        assert "use-builtin-generics" in out
+        assert "version match:" in out
+
+    def test_comma_split_ids(self, capsys):
+        main(argv=["retrieve", "use-builtin-generics,union-syntax", "--format", "json"])
+        data = json.loads(capsys.readouterr().out)
+        ids = {r["id"] for r in data}
+        assert "use-builtin-generics" in ids
+        assert "union-syntax" in ids
+
+    def test_no_match_exits_1_json_envelope(self, capsys):
+        with pytest.raises(SystemExit, match="1"):
+            main(argv=["retrieve", "nonexistent-guide-id", "--format", "json"])
+        data = json.loads(capsys.readouterr().out)
+        assert "not_found" in data
+        assert data["results"] == []
+        assert data["not_found"][0]["id"] == "nonexistent-guide-id"
+
+    def test_no_match_human_exits_1(self, capsys):
+        with pytest.raises(SystemExit, match="1"):
+            main(argv=["retrieve", "nonexistent-guide-id", "--format", "human"])
+        assert "No guide found for" in capsys.readouterr().out
+
+    def test_suggestion_human(self, capsys):
+        with pytest.raises(SystemExit, match="1"):
+            main(argv=["retrieve", "builtin-generics", "--format", "human"])
+        out = capsys.readouterr().out
+        assert "Did you mean" in out
+        assert "use-builtin-generics" in out
+
+    def test_suggestion_json(self, capsys):
+        with pytest.raises(SystemExit, match="1"):
+            main(argv=["retrieve", "builtin-generics", "--format", "json"])
+        data = json.loads(capsys.readouterr().out)
+        assert "use-builtin-generics" in data["not_found"][0]["suggestions"]
+
+    def test_mixed_valid_and_invalid(self, capsys):
+        with pytest.raises(SystemExit, match="1"):
+            main(argv=["retrieve", "use-builtin-generics,zzz-fake", "--format", "json"])
+        data = json.loads(capsys.readouterr().out)
+        assert len(data["results"]) == 1
+        assert data["results"][0]["id"] == "use-builtin-generics"
+        assert data["not_found"][0]["id"] == "zzz-fake"
+
+    def test_all_found_bare_list(self, capsys):
+        main(argv=["retrieve", "use-builtin-generics", "--format", "json"])
+        data = json.loads(capsys.readouterr().out)
+        assert isinstance(data, list)
+        assert data[0]["id"] == "use-builtin-generics"
+
+    def test_trailing_comma_ignored(self, capsys):
+        main(argv=["retrieve", "use-builtin-generics,", "--format", "json"])
+        data = json.loads(capsys.readouterr().out)
+        assert isinstance(data, list)
+        assert data[0]["id"] == "use-builtin-generics"
+
+    def test_all_commas_exits_1(self, capsys):
+        with pytest.raises(SystemExit, match="1"):
+            main(argv=["retrieve", ",,,", "--format", "human"])
+        assert "No guide IDs provided" in capsys.readouterr().out
+
+    def test_version_match_yes(self, capsys):
+        main(
+            argv=[
+                "retrieve",
+                "use-builtin-generics",
+                "--python-version",
+                "3.12",
+                "--format",
+                "human",
+            ]
+        )
+        out = capsys.readouterr().out
+        assert "YES" in out
+
+
+class TestCmdList:
+    def test_json_output(self, capsys):
+        main(argv=["list", "--format", "json"])
+        data = json.loads(capsys.readouterr().out)
+        assert isinstance(data, list)
+        assert len(data) >= 10
+
+    def test_human_output(self, capsys):
+        main(argv=["list", "--format", "human"])
+        out = capsys.readouterr().out
+        assert "layer" in out
+
+    def test_category_filter(self, capsys):
+        main(argv=["list", "--category", "stdlib", "--format", "json"])
+        data = json.loads(capsys.readouterr().out)
+        assert data
+        for item in data:
+            assert item["category"] == "stdlib"
+
+    def test_version_filter(self, capsys):
+        main(argv=["list", "--python-version", "3.11", "--format", "json"])
+        data = json.loads(capsys.readouterr().out)
+        assert isinstance(data, list)
+        assert len(data) >= 1
+
+    def test_empty_exits_1(self, capsys):
+        with pytest.raises(SystemExit, match="1"):
+            main(argv=["list", "--category", "nonexistent_cat", "--format", "json"])
+
+    def test_category_grouping_human(self, capsys):
+        main(argv=["list", "--format", "human"])
+        out = capsys.readouterr().out
+        assert "[" in out and "]" in out
+
+
+class TestCmdDetectVersion:
+    def test_basic_output(self, capsys):
+        main(argv=["detect-version"])
+        out = capsys.readouterr().out.strip()
+        assert out  # should return some version string
+
+
+class TestCmdSetupUninstall:
+    def test_setup_dispatch(self):
+        with patch("modern_python_guidance.setup_cmd.run_setup", return_value=0) as mock:
+            with pytest.raises(SystemExit, match="0"):
+                main(argv=["setup", "--dry-run"])
+            mock.assert_called_once()
+            call_kwargs = mock.call_args
+            assert call_kwargs[1]["dry_run"] is True
+
+    def test_uninstall_dispatch(self):
+        with patch("modern_python_guidance.uninstall_cmd.run_uninstall", return_value=0) as mock:
+            with pytest.raises(SystemExit, match="0"):
+                main(argv=["uninstall", "--dry-run"])
+            mock.assert_called_once()
+            call_kwargs = mock.call_args
+            assert call_kwargs[1]["dry_run"] is True
+
+    def test_setup_nonzero_exit(self):
+        with (
+            patch("modern_python_guidance.setup_cmd.run_setup", return_value=1),
+            pytest.raises(SystemExit, match="1"),
+        ):
+            main(argv=["setup", "--dry-run"])
+
+    def test_uninstall_nonzero_exit(self):
+        with (
+            patch("modern_python_guidance.uninstall_cmd.run_uninstall", return_value=1),
+            pytest.raises(SystemExit, match="1"),
+        ):
+            main(argv=["uninstall", "--dry-run"])
+
+
+# --- helpers ---
+
+
+def _make_ns(**kwargs):
+    """Build a minimal argparse.Namespace for _resolve_format tests."""
+    import argparse
+
+    return argparse.Namespace(**kwargs)

modern_python_guidance-0.3.8/tests/test_compat.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import pytest
+
+from modern_python_guidance.compat import VERSION_RE, token_estimate, version_compatible
+
+
+class TestVersionCompatible:
+    def test_compatible(self):
+        assert version_compatible(">=3.9", "3.12") is True
+
+    def test_incompatible(self):
+        assert version_compatible(">=3.11", "3.9") is False
+
+    def test_boundary_exact(self):
+        assert version_compatible(">=3.11", "3.11") is True
+
+    def test_compound_specifier_pass(self):
+        assert version_compatible(">=3.9,<3.13", "3.12") is True
+
+    def test_compound_specifier_fail(self):
+        assert version_compatible(">=3.9,<3.13", "3.13") is False
+
+    def test_empty_specifier_matches_all(self):
+        assert version_compatible("", "3.12") is True
+
+    def test_invalid_specifier_fail_open(self):
+        assert version_compatible("not-valid", "3.12") is True
+
+    def test_invalid_target_fail_open(self):
+        assert version_compatible(">=3.9", "abc") is True
+
+    def test_patch_level_target(self):
+        assert version_compatible(">=3.9", "3.11.1") is True
+
+
+class TestTokenEstimate:
+    def test_empty_string(self):
+        assert token_estimate("") == 0
+
+    def test_one_char(self):
+        assert token_estimate("x") == 0
+
+    def test_three_chars(self):
+        assert token_estimate("xxx") == 0
+
+    def test_four_chars(self):
+        assert token_estimate("abcd") == 1
+
+    def test_five_chars(self):
+        assert token_estimate("xxxxx") == 1
+
+    def test_hundred_chars(self):
+        assert token_estimate("x" * 100) == 25
+
+
+class TestVersionRe:
+    @pytest.mark.parametrize(
+        ("value", "expected"),
+        [
+            ("3.12", True),
+            ("3.12.1", False),
+            ("abc", False),
+            ("", False),
+            ("v3.12", False),
+            ("3.", False),
+            (".11", False),
+            ("03.011", True),
+        ],
+        ids=[
+            "major_minor",
+            "patch_no_match",
+            "alpha_no_match",
+            "empty_no_match",
+            "v_prefix_no_match",
+            "trailing_dot_no_match",
+            "leading_dot_no_match",
+            "leading_zeros_match",
+        ],
+    )
+    def test_pattern(self, value: str, expected: bool):
+        assert (VERSION_RE.match(value) is not None) is expected