modern-python-guidance 0.3.4__tar.gz → 0.3.5__tar.gz

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.5}/.github/workflows/ci.yml

@@ -30,8 +30,11 @@ jobs:
       - name: Install dependencies
         run: uv pip install --system -e ".[dev]"
 
-      - name: Run tests
-        run: pytest --tb=short -q
+      - name: Check formatting
+        run: ruff format --check src/ tests/
 
       - name: Run linter
         run: ruff check src/ tests/
+
+      - name: Run tests
+        run: pytest --tb=short -q --cov --cov-report=term-missing

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.5}/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.5] — 2026-05-30
+
+### Added
+
+- CI format gate: `ruff format --check src/ tests/` runs before linter, catching formatting regressions at PR time (closes #19)
+- Coverage reporting: `pytest-cov` with branch coverage and `fail_under = 59%` ratchet threshold (closes #15)
+- Guide structure validation: 248 parametrized tests validating all 41 guides — frontmatter fields, section order, code fences, H1 title, no duplicate IDs (closes #16)
+- CONTRIBUTING.md: documented CI checks, format fix command, and guide count update step
+
+### Changed
+
+- Auto-formatted 12 existing source/test files with `ruff format` (whitespace only, no logic changes)
+- CI step order: checkout → setup → install → **format check** → linter → tests (with `--cov`)
+
 ## [0.3.4] — 2026-05-30
 
 ### Fixed

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.5}/CONTRIBUTING.md

@@ -37,13 +37,25 @@ See [docs/design.md](docs/design.md) for the full design document.
 | `frequency` | string | `high` (LLMs do this often), `medium`, `low` |
 
 3. Write BAD/GOOD/Why/Version Notes sections
-4. Run `pytest` to verify the guide parses correctly
+4. Update `EXPECTED_GUIDE_COUNT` in `tests/test_guide_structure.py`
+5. Run `pytest` — the guide structure tests validate frontmatter, section order, and code fences automatically
 
 ## Running tests
 
 ```bash
 uv venv && source .venv/bin/activate
 uv pip install -e ".[dev]"
-pytest
-ruff check src/ tests/
+pytest                              # 510+ tests including guide structure validation
+ruff check src/ tests/              # lint
+ruff format --check src/ tests/     # format check (CI enforced)
 ```
+
+To auto-fix formatting: `ruff format src/ tests/`
+
+## CI checks
+
+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%`)

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modern-python-guidance
-Version: 0.3.4
+Version: 0.3.5
 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
@@ -25,6 +25,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: packaging>=23.0
 Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.4.0; extra == 'dev'
 Description-Content-Type: text/markdown

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.5}/bench/score_v5.py

@@ -1476,14 +1476,17 @@ def main() -> None:
         "c": "C (pytest)",
     }
     v_label = variant_labels.get(args.variant, args.variant)
-    print(f"=== V5 Scoring: Variant {v_label}, Run {args.run_id} ===")
-    print()
+
+    if args.output_format == "human":
+        print(f"=== V5 Scoring: Variant {v_label}, Run {args.run_id} ===")
+        print()
 
     output = {}
     for session_name in ("control", "treatment"):
         session_dir = results_dir / session_name
         if not session_dir.is_dir():
-            print(f"  [{session_name}] Directory not found, skipping.")
+            if args.output_format == "human":
+                print(f"  [{session_name}] Directory not found, skipping.")
             continue
         data = score_session(session_dir, args.variant)
         output[session_name] = data

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "modern-python-guidance"
-version = "0.3.4"
+version = "0.3.5"
 description = "Version-aware BAD/GOOD pattern guides that help AI coding agents generate modern Python"
 readme = "README.md"
 license = "Apache-2.0 OR MIT"
@@ -34,6 +34,7 @@ dependencies = [
 [project.optional-dependencies]
 dev = [
     "pytest>=7.0",
+    "pytest-cov>=4.0",
     "ruff>=0.4.0",
 ]
 
@@ -66,3 +67,17 @@ select = ["E", "F", "W", "I", "UP", "FURB", "B", "SIM", "RUF"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["modern_python_guidance"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true
+fail_under = 59
+exclude_lines = [
+    "pragma: no cover",
+    "if __name__ == .__main__.",
+    "if TYPE_CHECKING:",
+]

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.5}/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.4"
+__version__ = "0.3.5"

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.5}/src/modern_python_guidance/cli.py

@@ -36,7 +36,9 @@ def main(argv: list[str] | None = None) -> None:
     p_search.add_argument("--category", help="Filter by category")
     p_search.add_argument("--limit", type=int, default=10, help="Max results (default: 10)")
     p_search.add_argument(
-        "--format", choices=["json", "human"], default=None,
+        "--format",
+        choices=["json", "human"],
+        default=None,
         help="Output format (default: json when piped, human when TTY)",
     )
 
@@ -45,7 +47,9 @@ def main(argv: list[str] | None = None) -> None:
     p_retrieve.add_argument("ids", help="Comma-separated guide IDs")
     p_retrieve.add_argument("--python-version", help="Target Python version")
     p_retrieve.add_argument(
-        "--format", choices=["json", "human"], default=None,
+        "--format",
+        choices=["json", "human"],
+        default=None,
         help="Output format (default: json when piped, human when TTY)",
     )
 
@@ -54,7 +58,9 @@ def main(argv: list[str] | None = None) -> None:
     p_list.add_argument("--category", help="Filter by category")
     p_list.add_argument("--python-version", help="Filter by Python version")
     p_list.add_argument(
-        "--format", choices=["json", "human"], default=None,
+        "--format",
+        choices=["json", "human"],
+        default=None,
         help="Output format (default: json when piped, human when TTY)",
     )
 
@@ -67,27 +73,35 @@ def main(argv: list[str] | None = None) -> None:
 
     # setup
     p_setup = subparsers.add_parser(
-        "setup", help="Register MCP server and link Agent Skills",
+        "setup",
+        help="Register MCP server and link Agent Skills",
     )
     p_setup.add_argument("--mcp-only", action="store_true", help="MCP registration only")
     p_setup.add_argument("--skills-only", action="store_true", help="Skills symlink only")
     p_setup.add_argument(
-        "--scope", choices=["user", "local"], default="user",
+        "--scope",
+        choices=["user", "local"],
+        default="user",
         help="MCP scope (default: user)",
     )
     p_setup.add_argument(
-        "--project-dir", type=Path, help="Project directory for Skills symlink",
+        "--project-dir",
+        type=Path,
+        help="Project directory for Skills symlink",
     )
     p_setup.add_argument("--dry-run", action="store_true", help="Show what would be done")
 
     # uninstall
     p_uninstall = subparsers.add_parser(
-        "uninstall", help="Reverse 'setup': deregister MCP server and unlink Agent Skills",
+        "uninstall",
+        help="Reverse 'setup': deregister MCP server and unlink Agent Skills",
     )
     p_uninstall.add_argument("--mcp-only", action="store_true", help="MCP deregistration only")
     p_uninstall.add_argument("--skills-only", action="store_true", help="Skills unlink only")
     p_uninstall.add_argument(
-        "--project-dir", type=Path, help="Project directory for Skills symlink",
+        "--project-dir",
+        type=Path,
+        help="Project directory for Skills symlink",
     )
     p_uninstall.add_argument("--dry-run", action="store_true", help="Show what would be done")
 

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.5}/src/modern_python_guidance/frontmatter.py

@@ -75,9 +75,7 @@ def _parse_raw(lines: list[str]) -> dict[str, Any]:
             if current_key is None:
                 raise FrontmatterError("list item without preceding key", line=i)
             if not isinstance(data[current_key], list):
-                raise FrontmatterError(
-                    f"list item for non-list key '{current_key}'", line=i
-                )
+                raise FrontmatterError(f"list item for non-list key '{current_key}'", line=i)
             data[current_key].append(_parse_scalar(list_match.group(1).strip()))
             continue
 

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.5}/src/modern_python_guidance/mcp_server.py

@@ -340,11 +340,14 @@ def _handle_request(msg: dict) -> dict | None:
         return None
 
     if method == "initialize":
-        result = _result_response(req_id, {
-            "protocolVersion": PROTOCOL_VERSION,
-            "capabilities": {"tools": {}},
-            "serverInfo": {"name": "modern-python-guidance", "version": __version__},
-        })
+        result = _result_response(
+            req_id,
+            {
+                "protocolVersion": PROTOCOL_VERSION,
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": "modern-python-guidance", "version": __version__},
+            },
+        )
         return None if is_notification else result
 
     if method == "tools/list":

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.5}/src/modern_python_guidance/search.py

@@ -60,19 +60,25 @@ def search(
 
         if score > 0:
             score += FREQ_BOOST.get(meta.frequency, 0.0)
-            results.append(SearchResult(
-                guide_id=guide_id,
-                score=score,
-                meta=meta,
-                token_estimate=token_estimate(guide.body),
-                snippet=guide.snippet,
-            ))
+            results.append(
+                SearchResult(
+                    guide_id=guide_id,
+                    score=score,
+                    meta=meta,
+                    token_estimate=token_estimate(guide.body),
+                    snippet=guide.snippet,
+                )
+            )
 
     results.sort(key=lambda r: (-r.score, r.guide_id))
 
     if not results:
         return _fuzzy_fallback(
-            index, query, python_version=python_version, category=category, limit=limit,
+            index,
+            query,
+            python_version=python_version,
+            category=category,
+            limit=limit,
         )
 
     return results[:limit]
@@ -139,14 +145,16 @@ def _fuzzy_fallback(
                 continue
             seen.add(guide_id)
             guide = candidates[guide_id]
-            results.append(SearchResult(
-                guide_id=guide_id,
-                score=round(ratio, 3),
-                meta=guide.meta,
-                token_estimate=token_estimate(guide.body),
-                fuzzy=True,
-                snippet=guide.snippet,
-            ))
+            results.append(
+                SearchResult(
+                    guide_id=guide_id,
+                    score=round(ratio, 3),
+                    meta=guide.meta,
+                    token_estimate=token_estimate(guide.body),
+                    fuzzy=True,
+                    snippet=guide.snippet,
+                )
+            )
 
     results.sort(key=lambda r: (-r.score, r.guide_id))
-    return results[:min(limit, FUZZY_MAX)]
+    return results[: min(limit, FUZZY_MAX)]

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.5}/src/modern_python_guidance/version_detect.py

@@ -21,9 +21,7 @@ log = logging.getLogger(__name__)
 
 DEFAULT_VERSION = "3.11"
 
-_KNOWN_MINORS = [
-    Version(f"3.{minor}") for minor in range(7, 20)
-]
+_KNOWN_MINORS = [Version(f"3.{minor}") for minor in range(7, 20)]
 
 _POETRY_CARET_RE = re.compile(r"\^(\d+\.\d+)")
 
@@ -68,9 +66,7 @@ def _from_pyproject(path: Path) -> str | None:
     if requires_python:
         return _min_version_from_specifier(requires_python)
 
-    poetry_python = (
-        data.get("tool", {}).get("poetry", {}).get("dependencies", {}).get("python")
-    )
+    poetry_python = data.get("tool", {}).get("poetry", {}).get("dependencies", {}).get("python")
     if poetry_python:
         m = _POETRY_CARET_RE.search(str(poetry_python))
         if m:

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.5}/tests/test_cli_integration.py

@@ -55,8 +55,17 @@ class TestSearch:
         assert r.returncode == 0
         data = json.loads(r.stdout)
         expected_keys = {
-            "id", "title", "category", "layer", "tags", "python",
-            "frequency", "score", "token_estimate", "fuzzy", "snippet",
+            "id",
+            "title",
+            "category",
+            "layer",
+            "tags",
+            "python",
+            "frequency",
+            "score",
+            "token_estimate",
+            "fuzzy",
+            "snippet",
         }
         assert set(data[0].keys()) == expected_keys
         assert isinstance(data[0]["tags"], list)
@@ -89,14 +98,27 @@ class TestRetrieve:
         r = run_cli("retrieve", "use-builtin-generics", "--format", "json")
         data = json.loads(r.stdout)
         expected_keys = {
-            "id", "title", "category", "layer", "python",
-            "frequency", "version_match", "content", "token_estimate", "source",
+            "id",
+            "title",
+            "category",
+            "layer",
+            "python",
+            "frequency",
+            "version_match",
+            "content",
+            "token_estimate",
+            "source",
         }
         assert set(data[0].keys()) == expected_keys
 
     def test_retrieve_version_match_flag(self):
         r = run_cli(
-            "retrieve", "taskgroup-over-gather", "--python-version", "3.9", "--format", "json",
+            "retrieve",
+            "taskgroup-over-gather",
+            "--python-version",
+            "3.9",
+            "--format",
+            "json",
         )
         data = json.loads(r.stdout)
         assert data[0]["version_match"] is False

modern_python_guidance-0.3.5/tests/test_guide_structure.py

@@ -0,0 +1,129 @@
+"""Structural validation for all guide files.
+
+Ensures every guide in skills/modern-python-guidance/guides/ conforms to:
+- Valid frontmatter (parsed by parse_frontmatter)
+- id matches filename, category matches parent directory
+- Exactly 5 ## sections in order: BAD, GOOD, Why, <any>, References
+- Code fences in BAD and GOOD sections
+- Body starts with H1 title
+- No duplicate IDs across all guides
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+from modern_python_guidance.frontmatter import parse_frontmatter
+from modern_python_guidance.guide_index import _find_guides_dir
+
+GUIDES_DIR = _find_guides_dir()
+EXPECTED_GUIDE_COUNT = 41
+
+REQUIRED_HEADING_ORDER = {
+    0: "BAD",
+    1: "GOOD",
+    2: "Why",
+    4: "References",
+}
+
+
+def _collect_guides() -> list[Path]:
+    return sorted(GUIDES_DIR.rglob("*.md"))
+
+
+def _headings_outside_fences(body: str) -> list[str]:
+    # Handles both ``` and ~~~ fences; guide_index._code_lines only handles ```
+    headings = []
+    in_fence = False
+    for line in body.splitlines():
+        stripped = line.strip()
+        if re.match(r"^(`{3,}|~{3,})", stripped):
+            in_fence = not in_fence
+            continue
+        if not in_fence and line.startswith("## "):
+            headings.append(line[3:].strip())
+    return headings
+
+
+def _section_text(body: str, heading: str) -> str:
+    # Not fence-aware: splits on \n## which could appear inside code fences.
+    # Current guides have no ## at line start inside fences, so this is safe for now.
+    parts = body.split(f"## {heading}\n", 1)
+    if len(parts) < 2:
+        return ""
+    section = parts[1].split("\n## ", 1)[0]
+    return section
+
+
+_GUIDE_FILES = _collect_guides()
+_GUIDE_IDS = [f"{f.parent.name}/{f.stem}" for f in _GUIDE_FILES]
+
+
+@pytest.fixture(params=_GUIDE_FILES, ids=_GUIDE_IDS)
+def guide_file(request: pytest.FixtureRequest) -> Path:
+    return request.param
+
+
+class TestGuideStructure:
+    def test_parses_without_error(self, guide_file: Path):
+        text = guide_file.read_text(encoding="utf-8")
+        parse_frontmatter(text)
+
+    def test_id_matches_filename(self, guide_file: Path):
+        text = guide_file.read_text(encoding="utf-8")
+        meta, _ = parse_frontmatter(text)
+        assert meta.id == guide_file.stem, (
+            f"frontmatter id '{meta.id}' != filename '{guide_file.stem}'"
+        )
+
+    def test_category_matches_dirname(self, guide_file: Path):
+        text = guide_file.read_text(encoding="utf-8")
+        meta, _ = parse_frontmatter(text)
+        assert meta.category == guide_file.parent.name, (
+            f"frontmatter category '{meta.category}' != dir '{guide_file.parent.name}'"
+        )
+
+    def test_section_headings(self, guide_file: Path):
+        text = guide_file.read_text(encoding="utf-8")
+        _, body = parse_frontmatter(text)
+        headings = _headings_outside_fences(body)
+
+        assert len(headings) == 5, f"expected 5 ## headings, got {len(headings)}: {headings}"
+        for idx, expected in REQUIRED_HEADING_ORDER.items():
+            assert headings[idx] == expected, (
+                f"heading[{idx}] expected '{expected}', got '{headings[idx]}'"
+            )
+
+    def test_bad_good_have_code_fences(self, guide_file: Path):
+        text = guide_file.read_text(encoding="utf-8")
+        _, body = parse_frontmatter(text)
+        for section_name in ("BAD", "GOOD"):
+            section = _section_text(body, section_name)
+            assert re.search(r"^(`{3,}|~{3,})", section, re.MULTILINE), (
+                f"## {section_name} section has no code fence"
+            )
+
+    def test_body_starts_with_h1(self, guide_file: Path):
+        text = guide_file.read_text(encoding="utf-8")
+        _, body = parse_frontmatter(text)
+        assert body.startswith("# "), "body does not start with H1 heading"
+
+
+class TestGuideInventory:
+    def test_no_duplicate_ids(self):
+        seen: dict[str, Path] = {}
+        for guide_file in _GUIDE_FILES:
+            text = guide_file.read_text(encoding="utf-8")
+            meta, _ = parse_frontmatter(text)
+            assert meta.id not in seen, (
+                f"duplicate id '{meta.id}': {seen[meta.id]} and {guide_file}"
+            )
+            seen[meta.id] = guide_file
+
+    def test_guide_count(self):
+        assert len(_GUIDE_FILES) == EXPECTED_GUIDE_COUNT, (
+            f"expected {EXPECTED_GUIDE_COUNT} guides, found {len(_GUIDE_FILES)}"
+        )