codeforerunner 0.4.2__tar.gz → 0.4.3__tar.gz

{codeforerunner-0.4.2/src/codeforerunner.egg-info → codeforerunner-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeforerunner
-Version: 0.4.2
+Version: 0.4.3
 Summary: Model-agnostic repository documentation tooling (prompt-first; thin CLI).
 Author: Derek Palmer
 License-Expression: LicenseRef-Codeforerunner-SAL-0.1

{codeforerunner-0.4.2 → codeforerunner-0.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codeforerunner"
-version = "0.4.2"
+version = "0.4.3"
 description = "Model-agnostic repository documentation tooling (prompt-first; thin CLI)."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -54,3 +54,9 @@ codeforerunner = ["py.typed", "prompts/**/*.md"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "pydocstyle>=6.3.0",
+    "pytest-cov>=7.1.0",
+]

{codeforerunner-0.4.2 → codeforerunner-0.4.3}/src/codeforerunner/__init__.py

@@ -1,6 +1,8 @@
+"""codeforerunner — prompt-first repo documentation tooling."""
+
 from importlib.metadata import PackageNotFoundError, version
 
 try:
     __version__ = version("codeforerunner")
-except PackageNotFoundError:
+except PackageNotFoundError:  # pragma: no cover
     __version__ = "0.0.0"  # running from source without install

{codeforerunner-0.4.2 → codeforerunner-0.4.3}/src/codeforerunner/check.py

@@ -11,6 +11,8 @@ from codeforerunner.config import CheckConfig
 
 @dataclass(frozen=True)
 class Violation:
+    """Single rule match: which doc, which line, which rule, and what it means."""
+
     path: Path
     line: int
     rule_id: str

{codeforerunner-0.4.2 → codeforerunner-0.4.3}/src/codeforerunner/cli.py

@@ -61,7 +61,7 @@ def _doc_for(args: argparse.Namespace, task: str) -> int:
 
 
 def cmd_init(args: argparse.Namespace) -> int:
-    """Default + --agents-only = onboarding bundle only. --full prepends scan."""
+    """Emit onboarding bundle; prepend scan bundle when --full is given."""
     if getattr(args, "full", False):
         sys.stdout.write("<!-- forerunner init --full: section 1/2 (scan) -->\n")
         rc = _doc_for(args, "scan")
@@ -72,6 +72,7 @@ def cmd_init(args: argparse.Namespace) -> int:
 
 
 def cmd_scan(args: argparse.Namespace) -> int:
+    """Emit the scan prompt bundle and hint about FORERUNNER_SCAN_DONE."""
     rc = _doc_for(args, "scan")
     if rc == 0:
         print(
@@ -102,6 +103,7 @@ def cmd_check(args: argparse.Namespace) -> int:
 
 
 def cmd_mcp_server(args: argparse.Namespace) -> int:
+    """Start the stdio MCP server exposing prompt bundles as tools."""
     from codeforerunner import mcp_server
     try:
         prompts_root = find_prompts_root(args.repo)
@@ -133,6 +135,7 @@ def cmd_generate(args: argparse.Namespace) -> int:
     if rc != 0:
         return rc
 
+
     explicit_provider = args.provider or (cfg.provider if cfg else None)
     provider_name = explicit_provider or "anthropic"
     model = args.model or (cfg.model if cfg else None)
@@ -193,6 +196,7 @@ def cmd_generate(args: argparse.Namespace) -> int:
 
 
 def cmd_doctor(args: argparse.Namespace) -> int:
+    """Run health checks and print a single-screen report; exit 1 on errors."""
     from codeforerunner import doctor
     from codeforerunner.config import CONFIG_FILENAME
     root = Path(args.repo).resolve() if args.repo else Path.cwd()
@@ -209,6 +213,7 @@ def cmd_doctor(args: argparse.Namespace) -> int:
 
 
 def build_parser() -> argparse.ArgumentParser:
+    """Build and return the top-level argument parser with all subcommands registered."""
     p = argparse.ArgumentParser(
         prog="forerunner",
         description="Prompt-first repo documentation tooling. Thin CLI; product logic in prompts/.",
@@ -285,6 +290,7 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 def main(argv: Sequence[str] | None = None) -> int:
+    """Parse argv and dispatch to the appropriate subcommand handler."""
     parser = build_parser()
     args = parser.parse_args(argv)
     if not hasattr(args, "repo"):

{codeforerunner-0.4.2 → codeforerunner-0.4.3}/src/codeforerunner/config.py

@@ -19,6 +19,8 @@ class ConfigError(Exception):
 
 @dataclass(frozen=True)
 class CheckConfig:
+    """Drift-check task configuration: severity gates and path filters."""
+
     block_on: tuple[str, ...] = ("HIGH", "MEDIUM")
     warn_on: tuple[str, ...] = ("LOW",)
     enabled_rules: tuple[str, ...] | None = None  # None = all rules enabled
@@ -27,6 +29,8 @@ class CheckConfig:
 
 @dataclass(frozen=True)
 class VersionAuditConfig:
+    """Version-audit task configuration: staleness window and live EOL data toggle."""
+
     enabled: bool = True
     stale_after_days: int = 30
     fetch_live_eol_data: bool = False
@@ -34,6 +38,8 @@ class VersionAuditConfig:
 
 @dataclass(frozen=True)
 class ForerunnerConfig:
+    """Top-level forerunner.config.yaml configuration."""
+
     provider: str = "anthropic"
     model: str = "claude-opus-4-7"
     approaching_eol_threshold_months: int = 6
@@ -52,7 +58,7 @@ def _require_type(value: Any, expected: type, field_name: str) -> Any:
 
 
 def _coerce_str_tuple(value: Any, field_name: str) -> tuple[str, ...]:
-    if value is None:
+    if value is None:  # pragma: no cover - callers supply defaults, never pass None
         return ()
     if not isinstance(value, list):
         raise ConfigError(f"{field_name}: expected list, got {type(value).__name__}")
@@ -71,7 +77,7 @@ def _parse_api_key_env(raw: Any) -> dict[str, str]:
         raise ConfigError(f"api_key_env: expected dict, got {type(raw).__name__}")
     out: dict[str, str] = {}
     for k, v in raw.items():
-        if not isinstance(k, str):
+        if not isinstance(k, str):  # pragma: no cover - YAML keys are always strings
             raise ConfigError(
                 f"api_key_env: keys must be strings, got {type(k).__name__}"
             )

{codeforerunner-0.4.2 → codeforerunner-0.4.3}/src/codeforerunner/doctor.py

@@ -33,6 +33,8 @@ _DEFAULT_PROVIDER_ENV = {
 
 @dataclass(frozen=True)
 class Finding:
+    """Single health-check result with severity, check name, and human message."""
+
     severity: str  # "ok" | "warn" | "error"
     check: str
     message: str
@@ -244,7 +246,7 @@ def _check_config_loadable(repo: Path) -> list[Finding]:
 
 
 def _skill_mode_active() -> bool:
-    """True if any installed skill destination has managed markers — agent IS the model."""
+    """Return True if any installed skill destination has managed markers (agent is the model)."""
     for dest in _installed_skill_destinations():
         if dest.exists():
             try:
@@ -315,16 +317,13 @@ def _check_provider_api_key(repo: Path) -> list[Finding]:
     env_var = cfg.api_key_env.get(provider) or _DEFAULT_PROVIDER_ENV.get(provider, "")
     if os.environ.get(env_var):
         return [Finding("ok", "provider-api-key", f"{provider}: {env_var} is set")]
+    # Emit the same warning regardless of skill mode: an explicit provider in config
+    # means the user intends to use that provider, so a missing key is always a real problem.
     return [
         Finding(
             "warn",
             "provider-api-key",
-            f"{provider}: ${env_var} is not set; `forerunner generate` will refuse to run"
-            + (
-                " (use `--prompt-only` for key-free bundle output)"
-                if _skill_mode_active()
-                else ""
-            ),
+            f"{provider}: ${env_var} is not set; `forerunner generate` will refuse to run",
         )
     ]
 
@@ -348,10 +347,12 @@ tasks:
 
 
 def starter_config() -> str:
+    """Return the default forerunner.config.yaml content written by --fix."""
     return _STARTER_CONFIG
 
 
 def run(repo: Path, run_scripts: bool = False) -> list[Finding]:
+    """Run all health checks against *repo* and return findings."""
     repo = repo.resolve()
     findings: list[Finding] = []
     findings.extend(_check_skill_body_parity(repo, run_scripts=run_scripts))
@@ -363,16 +364,18 @@ def run(repo: Path, run_scripts: bool = False) -> list[Finding]:
 
 
 def format_report(findings: list[Finding]) -> str:
+    """Format findings as a human-readable report string with a summary line."""
     lines = [f"[{f.severity}] {f.check}: {f.message}" for f in findings]
     counts: dict[str, int] = {"ok": 0, "warn": 0, "error": 0}
     for f in findings:
-        counts[f.severity] = counts.get(f.severity, 0) + 1
+        counts[f.severity] += 1
     summary = f"summary: {counts['ok']} ok, {counts['warn']} warn, {counts['error']} error"
     lines.append(summary)
     return "\n".join(lines)
 
 
 def main(argv: list[str] | None = None) -> int:
+    """Entry point for `forerunner doctor`; returns 1 when any finding is an error."""
     parser = argparse.ArgumentParser(
         prog="forerunner doctor",
         description="Single-screen health report for codeforerunner repo.",

{codeforerunner-0.4.2 → codeforerunner-0.4.3}/src/codeforerunner/installer.py

@@ -41,6 +41,8 @@ TASK_SKILL_SLUGS: tuple[str, ...] = (
 
 @dataclass(frozen=True)
 class Target:
+    """Resolved install destination: agent name + absolute path."""
+
     name: str
     path: Path
 
@@ -50,6 +52,7 @@ def _home() -> Path:
 
 
 def resolve_target(agent: str, override: Path | None) -> Target:
+    """Return the default install Target for the given agent, or use override path."""
     if agent == "generic":
         if override is None:
             raise ValueError("generic target requires --path PATH")
@@ -126,6 +129,7 @@ def install_all_skills(
 
 
 def resolve_marketplace_target(agent: str, override: Path | None) -> Target:
+    """Return the marketplace install Target for the given agent, or use override path."""
     if agent == "generic":
         if override is None:
             raise ValueError("generic marketplace target requires --path PATH")
@@ -181,6 +185,7 @@ def render(source_text: str, dest_existing: str | None, agent: str) -> str:
 
 
 def find_markers(text: str) -> tuple[int, int] | None:
+    """Return (start, end) byte offsets of the managed region, or None if absent."""
     a = text.find(MARKER_BEGIN)
     if a < 0:
         return None
@@ -202,12 +207,15 @@ def overlay(dest_text: str, source_body: str) -> str:
 
 @dataclass
 class Plan:
+    """Pending install action computed by plan_install or plan_marketplace."""
+
     action: str  # "create" | "update" | "skip" | "abort"
     reason: str
     target: Target
     new_content: str | None = None
 
     def write(self) -> None:
+        """Execute the plan: create or update the destination file."""
         if self.action in ("skip", "abort"):
             return
         assert self.new_content is not None
@@ -306,6 +314,7 @@ def install(
     out=None,
     err=None,
 ) -> int:
+    """Run one install operation (skill or marketplace). Returns an EXIT_* code."""
     out = out or sys.stdout
     err = err or sys.stderr
 
@@ -356,6 +365,7 @@ def install(
 
 
 def add_subparser(sub: argparse._SubParsersAction) -> None:
+    """Register the `forerunner install` subcommand onto *sub*."""
     p = sub.add_parser("install", help="install skill(s) into agent-specific directories (D.installer)")
     p.add_argument("agent", choices=["codex", "claude", "generic"], nargs="?",
                    help="target agent (omit with --all to install to all detected agents)")

{codeforerunner-0.4.2 → codeforerunner-0.4.3}/src/codeforerunner/mcp_server.py

@@ -114,6 +114,7 @@ def _handle(prompts_root: Path, msg: dict[str, Any], state: dict[str, Any]) -> d
 
 
 def serve(prompts_root: Path, stdin: Iterable[str] = sys.stdin, stdout=sys.stdout, stderr=sys.stderr) -> int:
+    """Run the JSON-RPC 2.0 MCP server loop over *stdin*/*stdout* until EOF."""
     state: dict[str, Any] = {"scan_called": False, "initialized": False}
     for raw in stdin:
         line = raw.strip()
@@ -141,6 +142,7 @@ def serve(prompts_root: Path, stdin: Iterable[str] = sys.stdin, stdout=sys.stdou
 
 
 def main(argv: list[str] | None = None) -> int:
+    """Locate prompts root and start the MCP server; returns 2 if prompts not found."""
     try:
         prompts_root = find_prompts_root()
     except FileNotFoundError as e:
@@ -149,5 +151,5 @@ def main(argv: list[str] | None = None) -> int:
     return serve(prompts_root)
 
 
-if __name__ == "__main__":
+if __name__ == "__main__":  # pragma: no cover
     raise SystemExit(main())

{codeforerunner-0.4.2 → codeforerunner-0.4.3}/src/codeforerunner/providers/__init__.py

@@ -30,6 +30,7 @@ REGISTRY: dict[str, type] = {
 
 
 def get(name: str) -> type:
+    """Return the provider class for *name*, or raise ProviderError if unknown."""
     if name not in REGISTRY:
         raise ProviderError(
             f"unknown provider '{name}' (expected one of {sorted(REGISTRY)})"

{codeforerunner-0.4.2 → codeforerunner-0.4.3}/src/codeforerunner/providers/anthropic.py

@@ -11,6 +11,8 @@ from codeforerunner.providers.base import CompletionResult, ProviderError
 
 
 class AnthropicProvider:
+    """Anthropic Messages API provider using stdlib HTTP."""
+
     name = "anthropic"
     default_env_var = "ANTHROPIC_API_KEY"
     default_model = "claude-opus-4-7"
@@ -24,6 +26,7 @@ class AnthropicProvider:
         model: str | None = None,
         api_key: str | None = None,
     ) -> CompletionResult:
+        """Send *prompt* to the Anthropic Messages API and return the full response."""
         if not api_key:
             raise ProviderError(f"missing API key (set ${self.default_env_var})")
         model = model or self.default_model
@@ -68,6 +71,7 @@ class AnthropicProvider:
         model: str | None = None,
         api_key: str | None = None,
     ) -> Iterator[str]:
+        """Yield text chunks from the Anthropic streaming Messages API."""
         if not api_key:
             raise ProviderError(f"missing API key (set ${self.default_env_var})")
         model = model or self.default_model

{codeforerunner-0.4.2 → codeforerunner-0.4.3}/src/codeforerunner/providers/base.py

@@ -8,12 +8,16 @@ from typing import Iterator, Protocol
 
 @dataclass(frozen=True)
 class CompletionResult:
+    """Completed text response returned by a provider."""
+
     text: str
     model: str
     usage: dict | None = None  # provider-reported token counts; None if unknown
 
 
 class Provider(Protocol):
+    """Structural protocol that all LLM provider classes must satisfy."""
+
     name: str
     default_env_var: str  # e.g. "ANTHROPIC_API_KEY"
     default_model: str  # provider's recommended default
@@ -24,7 +28,9 @@ class Provider(Protocol):
         prompt: str,
         model: str | None = None,
         api_key: str | None = None,
-    ) -> CompletionResult: ...
+    ) -> CompletionResult:
+        """Send *prompt* and return the full completion result."""
+        ...
 
     def stream(
         self,
@@ -32,7 +38,9 @@ class Provider(Protocol):
         prompt: str,
         model: str | None = None,
         api_key: str | None = None,
-    ) -> Iterator[str]: ...
+    ) -> Iterator[str]:
+        """Yield text chunks from *prompt* as they arrive from the provider."""
+        ...
 
 
 class ProviderError(Exception):

{codeforerunner-0.4.2 → codeforerunner-0.4.3}/src/codeforerunner/providers/google.py

@@ -12,6 +12,8 @@ from codeforerunner.providers.base import CompletionResult, ProviderError
 
 
 class GoogleProvider:
+    """Google Gemini generateContent provider using stdlib HTTP."""
+
     name = "google"
     default_env_var = "GOOGLE_API_KEY"
     default_model = "gemini-2.5-pro"
@@ -33,6 +35,7 @@ class GoogleProvider:
         model: str | None = None,
         api_key: str | None = None,
     ) -> CompletionResult:
+        """Send *prompt* to the Gemini generateContent endpoint and return the full response."""
         if not api_key:
             raise ProviderError(f"missing API key (set ${self.default_env_var})")
         model = model or self.default_model
@@ -75,6 +78,7 @@ class GoogleProvider:
         model: str | None = None,
         api_key: str | None = None,
     ) -> Iterator[str]:
+        """Yield text chunks from the Gemini streaming generateContent endpoint."""
         if not api_key:
             raise ProviderError(f"missing API key (set ${self.default_env_var})")
         model = model or self.default_model

{codeforerunner-0.4.2 → codeforerunner-0.4.3}/src/codeforerunner/providers/ollama.py

@@ -20,7 +20,7 @@ def _validate_ollama_base(base: str) -> None:
     """Reject URLs that look like cloud metadata endpoints or use unexpected schemes."""
     try:
         parsed = urllib.parse.urlparse(base)
-    except Exception as e:
+    except Exception as e:  # pragma: no cover - urlparse never raises
         raise ValueError(f"OLLAMA_HOST: invalid URL: {e}") from e
     if parsed.scheme not in ("http", "https"):
         raise ValueError(
@@ -46,6 +46,8 @@ def is_available(host: str | None = None) -> bool:
 
 
 class OllamaProvider:
+    """Ollama local provider using stdlib HTTP."""
+
     name = "ollama"
     default_env_var = "OLLAMA_HOST"
     default_model = "llama3"
@@ -57,6 +59,7 @@ class OllamaProvider:
         model: str | None = None,
         api_key: str | None = None,
     ) -> CompletionResult:
+        """Send *prompt* to the Ollama /api/generate endpoint and return the full response."""
         # api_key is interpreted as a base URL override; fall back to env then default.
         base = api_key or os.environ.get(self.default_env_var) or DEFAULT_HOST
         base = base.rstrip("/")
@@ -96,6 +99,7 @@ class OllamaProvider:
         model: str | None = None,
         api_key: str | None = None,
     ) -> Iterator[str]:
+        """Yield text chunks from the Ollama /api/generate streaming endpoint."""
         base = api_key or os.environ.get(self.default_env_var) or DEFAULT_HOST
         base = base.rstrip("/")
         _validate_ollama_base(base)

{codeforerunner-0.4.2 → codeforerunner-0.4.3}/src/codeforerunner/providers/openai.py

@@ -11,6 +11,8 @@ from codeforerunner.providers.base import CompletionResult, ProviderError
 
 
 class OpenAIProvider:
+    """OpenAI chat completions provider using stdlib HTTP."""
+
     name = "openai"
     default_env_var = "OPENAI_API_KEY"
     default_model = "gpt-4o"
@@ -24,6 +26,7 @@ class OpenAIProvider:
         model: str | None = None,
         api_key: str | None = None,
     ) -> CompletionResult:
+        """Send *prompt* to the OpenAI chat completions endpoint and return the full response."""
         if not api_key:
             raise ProviderError(f"missing API key (set ${self.default_env_var})")
         model = model or self.default_model
@@ -66,6 +69,7 @@ class OpenAIProvider:
         model: str | None = None,
         api_key: str | None = None,
     ) -> Iterator[str]:
+        """Yield text chunks from the OpenAI streaming chat completions endpoint."""
         if not api_key:
             raise ProviderError(f"missing API key (set ${self.default_env_var})")
         model = model or self.default_model

{codeforerunner-0.4.2 → codeforerunner-0.4.3/src/codeforerunner.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeforerunner
-Version: 0.4.2
+Version: 0.4.3
 Summary: Model-agnostic repository documentation tooling (prompt-first; thin CLI).
 Author: Derek Palmer
 License-Expression: LicenseRef-Codeforerunner-SAL-0.1

{codeforerunner-0.4.2 → codeforerunner-0.4.3}/src/codeforerunner.egg-info/SOURCES.txt

@@ -37,6 +37,7 @@ src/codeforerunner/providers/base.py
 src/codeforerunner/providers/google.py
 src/codeforerunner/providers/ollama.py
 src/codeforerunner/providers/openai.py
+tests/test_bundle.py
 tests/test_check.py
 tests/test_check_config_integration.py
 tests/test_cli.py

codeforerunner-0.4.3/tests/test_bundle.py

@@ -0,0 +1,64 @@
+"""Tests for bundle.py edge cases."""
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from codeforerunner.bundle import find_prompts_root, resolve_bundle
+
+
+def test_find_prompts_root_raises_when_repo_arg_has_no_tasks(tmp_path):
+    with pytest.raises(FileNotFoundError, match="no prompts/tasks/"):
+        find_prompts_root(tmp_path)
+
+
+def test_find_prompts_root_uses_repo_arg_when_tasks_present(tmp_path):
+    (tmp_path / "prompts" / "tasks").mkdir(parents=True)
+    result = find_prompts_root(tmp_path)
+    assert result == tmp_path / "prompts"
+
+
+def test_find_prompts_root_walks_cwd_to_find_prompts(tmp_path):
+    # Create prompts/tasks/ in tmp_path and change cwd into a subdir
+    (tmp_path / "prompts" / "tasks").mkdir(parents=True)
+    subdir = tmp_path / "deep" / "nested"
+    subdir.mkdir(parents=True)
+    with patch("codeforerunner.bundle.Path") as MockPath:
+        # Replace cwd() so the walk starts from subdir
+        MockPath.cwd.return_value = subdir
+        # Make sure Path still works for everything else
+        MockPath.side_effect = lambda x=None: Path(x) if x is not None else Path()
+        # Directly test the cwd walk logic with the real function
+        pass
+
+    # Simpler approach: call find_prompts_root from within a subdir of tmp_path
+    import os
+    old_cwd = os.getcwd()
+    try:
+        subdir.mkdir(parents=True, exist_ok=True)
+        os.chdir(subdir)
+        result = find_prompts_root()
+        assert result == tmp_path / "prompts"
+    finally:
+        os.chdir(old_cwd)
+
+
+def test_find_prompts_root_raises_when_no_package_prompts(tmp_path, monkeypatch):
+    import os
+    old_cwd = os.getcwd()
+    try:
+        os.chdir(tmp_path)
+        # Patch _package_prompts to point to a dir with no tasks/
+        with patch("codeforerunner.bundle._package_prompts", return_value=tmp_path / "pkg"):
+            with pytest.raises(FileNotFoundError, match="could not find prompts/tasks"):
+                find_prompts_root()
+    finally:
+        os.chdir(old_cwd)
+
+
+def test_resolve_bundle_raises_for_unknown_task(tmp_path):
+    (tmp_path / "tasks").mkdir()
+    with pytest.raises(FileNotFoundError, match="unknown task"):
+        resolve_bundle(tmp_path, "nonexistent-task")

{codeforerunner-0.4.2 → codeforerunner-0.4.3}/tests/test_check.py

@@ -385,6 +385,69 @@ def test_rv1_not_run_when_excluded_from_enabled_rules(tmp_path):
     assert not any(v.rule_id == "RV1-version-drift" for v in run(tmp_path, cfg))
 
 
+# ── Version drift internals ────────────────────────────────────────────────────
+
+def test_rv1_skips_changelog_in_docs_dir(tmp_path):
+    # CHANGELOG.md inside docs/ is picked up by _scanned_docs but must be skipped
+    _seed(
+        tmp_path,
+        {
+            "docs/CHANGELOG.md": "codeforerunner==0.1.0\n",
+            "pyproject.toml": '[project]\nname = "codeforerunner"\nversion = "0.3.1"\n',
+        },
+    )
+    vs = [v for v in run(tmp_path) if v.rule_id == "RV1-version-drift"]
+    assert vs == []
+
+
+def test_rv1_skips_ignored_path(tmp_path):
+    from codeforerunner.config import CheckConfig
+    _seed(
+        tmp_path,
+        {
+            "docs/legacy.md": "codeforerunner==0.1.0\n",
+            "pyproject.toml": '[project]\nname = "codeforerunner"\nversion = "0.3.1"\n',
+        },
+    )
+    cfg = CheckConfig(ignore_paths=("docs/legacy.md",))
+    vs = [v for v in run(tmp_path, cfg) if v.rule_id == "RV1-version-drift"]
+    assert vs == []
+
+
+def test_rv1_skips_unreadable_doc(tmp_path):
+    import pathlib
+    from unittest.mock import MagicMock, patch
+    from codeforerunner.check import _check_version_drift
+
+    (tmp_path / "pyproject.toml").write_text('[project]\nversion = "1.0.0"\n', encoding="utf-8")
+    mock_doc = MagicMock()
+    mock_doc.name = "guide.md"
+    mock_doc.read_text.side_effect = OSError("permission denied")
+
+    violations = _check_version_drift(tmp_path, [mock_doc], (), None)
+    assert violations == []
+
+
+def test_path_ignored_doc_outside_repo():
+    from codeforerunner.check import _path_ignored
+    repo = Path("/tmp/some-repo")
+    doc = Path("/other/location/README.md")
+    # Should not crash; uses abs posix path matching
+    result = _path_ignored(repo, doc, ("*.md",))
+    assert isinstance(result, bool)
+
+
+def test_current_version_returns_none_on_oserror(tmp_path):
+    import pathlib
+    from unittest.mock import patch
+    from codeforerunner.check import _current_version
+
+    (tmp_path / "pyproject.toml").touch()
+    with patch.object(pathlib.Path, "read_text", side_effect=OSError("denied")):
+        result = _current_version(tmp_path)
+    assert result is None
+
+
 def test_workflows_lint_when_actionlint_available():
     import shutil
     import subprocess