strictcli 0.29.0__tar.gz → 0.30.1__tar.gz

{strictcli-0.29.0 → strictcli-0.30.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: strictcli
-Version: 0.29.0
+Version: 0.30.1
 Summary: A strict CLI framework for Python
 Project-URL: Homepage, https://github.com/smm-h/strictcli
 Project-URL: Repository, https://github.com/smm-h/strictcli

{strictcli-0.29.0 → strictcli-0.30.1}/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "strictcli",
-  "version": "0.29.0",
+  "version": "0.30.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "strictcli",
-      "version": "0.29.0",
+      "version": "0.30.1",
       "hasInstallScript": true,
       "license": "MIT"
     }

{strictcli-0.29.0 → strictcli-0.30.1}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strictcli",
-  "version": "0.29.0",
+  "version": "0.30.1",
   "description": "A strict, zero-dependency CLI framework for Python (npm wrapper)",
   "main": "index.js",
   "scripts": {

{strictcli-0.29.0 → strictcli-0.30.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "strictcli"
-version = "0.29.0"
+version = "0.30.1"
 description = "A strict CLI framework for Python"
 readme = "README.md"
 license = "MIT"

{strictcli-0.29.0 → strictcli-0.30.1}/strictcli/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.29.0"
+__version__ = "0.30.1"
 
 __all__ = [
     "App", "Flag", "Arg", "FlagSet", "MutexGroup", "CoRequired", "Requires",
@@ -2677,6 +2677,7 @@ class App:
     handshake_env: dict[str, str] | None = None
     checks_path: str | Path | None = None
     checks_embed: bytes | None = None
+    test_coverage: bool = False
     flags: list[Flag] = field(default_factory=list)
     _commands: dict[str, Command] = field(default_factory=dict)
     _groups: dict[str, Group] = field(default_factory=dict)
@@ -2797,6 +2798,20 @@ class App:
         # Config parse error (for config show to pick up)
         self._config_parse_err: str | None = None
 
+        # Test-coverage instrumentation. When enabled, every test() and call()
+        # invocation records which command was dispatched so a check can verify
+        # that every command in the app's surface has been exercised.
+        self._coverage_shard_counter: int = 0
+        self._coverage_shard_path: str | None = None
+        self._last_resolved_path: list[str] = []
+        if self.test_coverage:
+            self._coverage_shard_path = os.path.join(
+                ".strictcli", "coverage",
+                f"{os.getpid()}-{{n}}.jsonl",
+            )
+            os.makedirs(os.path.join(".strictcli", "coverage"), exist_ok=True)
+            self.register_check_provider(self._test_coverage_provider)
+
     def _validate_flag_infra_marker(self, f: Flag) -> None:
         """Panic if a flag's default is a RelativeToRoot marker referencing an
         undeclared root. Called at registration for construction-time errors."""
@@ -2817,6 +2832,107 @@ class App:
             handshakes=set(self._handshake_envs),
         )
 
+    def _record_coverage(self, cmd_path: str) -> None:
+        """Append a coverage record for the resolved command path.
+
+        Each test() or call() invocation writes one JSONL line to a per-process
+        shard file. The shard counter increments on each write to keep files
+        small and unique (handles pytest-xdist where multiple workers share a
+        PID namespace within the coverage directory).
+        """
+        if self._coverage_shard_path is None:
+            return
+        path = self._coverage_shard_path.format(n=self._coverage_shard_counter)
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(json.dumps({"command": cmd_path}) + "\n")
+
+    def _collect_all_command_paths(self) -> set[str]:
+        """Enumerate all non-deprecated leaf command paths as dotted strings."""
+        paths: set[str] = set()
+
+        for name in self._commands:
+            paths.add(name)
+
+        def _walk_group(group: Group, prefix: list[str]) -> None:
+            for cmd_name in group.commands:
+                paths.add(".".join(prefix + [cmd_name]))
+            for sub_name, sub_group in group._groups.items():
+                _walk_group(sub_group, prefix + [sub_name])
+
+        for group_name, group in self._groups.items():
+            _walk_group(group, [group_name])
+
+        return paths
+
+    def _test_coverage_provider(self) -> list[CheckSpec]:
+        """Built-in check provider for cli-test-coverage.
+
+        Registered automatically when test_coverage=True. Merges per-process
+        shard files into the canonical manifest, compares against the schema's
+        command surface (minus deprecated), and hard-FAILs listing every command
+        with zero coverage.
+        """
+        def impl(ctx: CheckContext, reporter: "ErrorReporter") -> "_CheckOutcome":
+            coverage_dir = os.path.join(".strictcli", "coverage")
+            manifest_path = os.path.join(".strictcli", "test-coverage.json")
+
+            # Merge shards
+            covered: set[str] = set()
+            if os.path.isdir(coverage_dir):
+                for fname in os.listdir(coverage_dir):
+                    if not fname.endswith(".jsonl"):
+                        continue
+                    fpath = os.path.join(coverage_dir, fname)
+                    with open(fpath, encoding="utf-8") as f:
+                        for line in f:
+                            line = line.strip()
+                            if not line:
+                                continue
+                            entry = json.loads(line)
+                            if "command" in entry:
+                                covered.add(entry["command"])
+
+            if not covered:
+                reporter.error("stale or empty manifest")
+                return reporter.found(
+                    "no coverage data: .strictcli/coverage/ contains no shard files"
+                )
+
+            # Write canonical manifest
+            manifest = sorted(covered)
+            with open(manifest_path, "w", encoding="utf-8") as f:
+                json.dump(manifest, f, indent=2)
+                f.write("\n")
+
+            # Compare against command surface (exclude the framework-injected
+            # check command -- it is not a user command)
+            all_commands = self._collect_all_command_paths()
+            all_commands.discard("check")
+            uncovered = sorted(all_commands - covered)
+
+            if uncovered:
+                for cmd in uncovered:
+                    reporter.error(f"no test coverage for command: {cmd}")
+                return reporter.found(
+                    f"{len(uncovered)} command(s) with zero test coverage"
+                )
+            return reporter.passed(
+                f"all {len(all_commands)} commands have test coverage"
+            )
+
+        return [
+            error_check_spec(
+                name="cli-test-coverage",
+                tags=["test"],
+                fast=True,
+                pure=True,
+                needs_network=False,
+                depends_on=[],
+                impl=impl,
+            ),
+        ]
+
     @property
     def config_file_path(self) -> str:
         """Return the resolved config file path for this app."""
@@ -4111,6 +4227,7 @@ class App:
             raise _HelpRequested(target=self)
 
         cmd, rest, path = self._resolve_command(remaining)
+        self._last_resolved_path = path
 
         # Check for command-level --help/-h anywhere in remaining tokens
         # (but not after "--" separator, which makes everything literal)
@@ -4751,6 +4868,10 @@ class App:
             stderr_buf.write(f"try '{prefix} --help'\n")
             exit_code = 1
         else:
+            # Record test-coverage hit (command-level only).
+            if self.test_coverage:
+                cmd_path = ".".join(self._last_resolved_path + [cmd.name])
+                self._record_coverage(cmd_path)
             # Store sources for function handlers that need provenance info
             self._last_sources = sources
             with contextlib.redirect_stdout(stdout_buf), contextlib.redirect_stderr(stderr_buf):
@@ -4805,6 +4926,10 @@ class App:
         path_segments = command_path.split(".")
         cmd, _rest, _path = self._resolve_command(path_segments)
 
+        # Record test-coverage hit (command-level only).
+        if self.test_coverage:
+            self._record_coverage(command_path)
+
         # Passthrough commands: forward raw args to the passthrough handler
         if cmd.passthrough is not None:
             raw_args = kwargs.get("_args", [])

strictcli-0.30.1/tests/test_coverage.py

@@ -0,0 +1,257 @@
+"""Tests for the cli-test-coverage mechanism.
+
+Verifies that:
+- test_coverage=True enables recording of command hits
+- test() and call() both record to per-process shard files
+- The cli-test-coverage check merges shards, compares against the command
+  surface, and FAILs listing uncovered commands
+- Full coverage produces a PASS
+- Empty/stale manifest is a hard error
+"""
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+import pytest
+
+import strictcli
+
+
+@dataclass
+class SimpleCtx:
+    project_root: Path
+
+
+def _make_app(tmp_path):
+    """Build a 3-command app with test_coverage enabled, rooted in tmp_path."""
+    os.chdir(tmp_path)
+    app = strictcli.App(
+        name="coverapp", version="1.0.0", help="coverage test app",
+        test_coverage=True,
+    )
+
+    @app.command(name="deploy", help="deploy the app")
+    def cmd_deploy(ctx, **_kw):
+        pass
+
+    @app.command(name="status", help="show status")
+    def cmd_status(ctx, **_kw):
+        pass
+
+    @app.command(name="build", help="build the app")
+    def cmd_build(ctx, **_kw):
+        pass
+
+    app.set_check_context(lambda: SimpleCtx(project_root=tmp_path))
+    return app
+
+
+def _make_grouped_app(tmp_path):
+    """Build an app with grouped commands for dotted-path coverage."""
+    os.chdir(tmp_path)
+    app = strictcli.App(
+        name="grpapp", version="1.0.0", help="grouped coverage test",
+        test_coverage=True,
+    )
+
+    grp = app.group("infra", help="infrastructure commands")
+
+    @grp.command(name="deploy", help="deploy infra")
+    def cmd_infra_deploy(ctx, **_kw):
+        pass
+
+    @grp.command(name="teardown", help="tear down infra")
+    def cmd_infra_teardown(ctx, **_kw):
+        pass
+
+    @app.command(name="status", help="show status")
+    def cmd_status(ctx, **_kw):
+        pass
+
+    app.set_check_context(lambda: SimpleCtx(project_root=tmp_path))
+    return app
+
+
+class TestCoverageRecording:
+    def test_test_creates_shard_file(self, tmp_path):
+        app = _make_app(tmp_path)
+        app.test(["deploy"])
+
+        coverage_dir = tmp_path / ".strictcli" / "coverage"
+        assert coverage_dir.is_dir()
+        shards = list(coverage_dir.glob("*.jsonl"))
+        assert len(shards) >= 1
+
+        entries = []
+        for shard in shards:
+            for line in shard.read_text().strip().splitlines():
+                entries.append(json.loads(line))
+
+        commands = {e["command"] for e in entries}
+        assert "deploy" in commands
+
+    def test_call_records_coverage(self, tmp_path):
+        app = _make_app(tmp_path)
+        app.call("status")
+
+        coverage_dir = tmp_path / ".strictcli" / "coverage"
+        shards = list(coverage_dir.glob("*.jsonl"))
+        assert len(shards) >= 1
+
+        entries = []
+        for shard in shards:
+            for line in shard.read_text().strip().splitlines():
+                entries.append(json.loads(line))
+
+        commands = {e["command"] for e in entries}
+        assert "status" in commands
+
+    def test_multiple_calls_accumulate(self, tmp_path):
+        app = _make_app(tmp_path)
+        app.test(["deploy"])
+        app.test(["status"])
+        app.call("build")
+
+        coverage_dir = tmp_path / ".strictcli" / "coverage"
+        entries = []
+        for shard in coverage_dir.glob("*.jsonl"):
+            for line in shard.read_text().strip().splitlines():
+                entries.append(json.loads(line))
+
+        commands = {e["command"] for e in entries}
+        assert commands == {"deploy", "status", "build"}
+
+    def test_grouped_command_dotted_path(self, tmp_path):
+        app = _make_grouped_app(tmp_path)
+        app.test(["infra", "deploy"])
+
+        coverage_dir = tmp_path / ".strictcli" / "coverage"
+        entries = []
+        for shard in coverage_dir.glob("*.jsonl"):
+            for line in shard.read_text().strip().splitlines():
+                entries.append(json.loads(line))
+
+        commands = {e["command"] for e in entries}
+        assert "infra.deploy" in commands
+
+
+class TestCoverageCheck:
+    def test_partial_coverage_fails_naming_uncovered(self, tmp_path):
+        """One command tested out of 3 -> check FAILs naming the untested two."""
+        app = _make_app(tmp_path)
+        # Only test one command
+        app.test(["deploy"])
+
+        results, _, code = app.run_checks(
+            SimpleCtx(project_root=tmp_path),
+            run_all=True,
+        )
+        cov_result = next(r for r in results if r.name == "cli-test-coverage")
+        assert cov_result.status == "fail"
+        # Should list the two uncovered commands
+        problem_texts = [p.text for p in cov_result.problems]
+        uncovered_cmds = set()
+        for text in problem_texts:
+            if "no test coverage for command:" in text:
+                cmd = text.split("no test coverage for command: ")[1]
+                uncovered_cmds.add(cmd)
+        assert "status" in uncovered_cmds
+        assert "build" in uncovered_cmds
+        assert "deploy" not in uncovered_cmds
+
+    def test_full_coverage_passes(self, tmp_path):
+        """All 3 commands tested -> check PASSes."""
+        app = _make_app(tmp_path)
+        app.test(["deploy"])
+        app.test(["status"])
+        app.test(["build"])
+
+        results, _, code = app.run_checks(
+            SimpleCtx(project_root=tmp_path),
+            run_all=True,
+        )
+        cov_result = next(r for r in results if r.name == "cli-test-coverage")
+        assert cov_result.status == "pass"
+
+    def test_empty_coverage_is_hard_error(self, tmp_path):
+        """No shard files -> check FAILs with stale/empty manifest error."""
+        app = _make_app(tmp_path)
+        # Don't run any test() or call() -- no shards exist
+
+        results, _, code = app.run_checks(
+            SimpleCtx(project_root=tmp_path),
+            run_all=True,
+        )
+        cov_result = next(r for r in results if r.name == "cli-test-coverage")
+        assert cov_result.status == "fail"
+        assert "stale or empty" in cov_result.message or any(
+            "stale or empty" in p.text for p in cov_result.problems
+        )
+
+    def test_manifest_written_on_check(self, tmp_path):
+        """The check writes .strictcli/test-coverage.json with covered commands."""
+        app = _make_app(tmp_path)
+        app.test(["deploy"])
+        app.test(["status"])
+        app.test(["build"])
+
+        app.run_checks(
+            SimpleCtx(project_root=tmp_path),
+            run_all=True,
+        )
+
+        manifest_path = tmp_path / ".strictcli" / "test-coverage.json"
+        assert manifest_path.is_file()
+        manifest = json.loads(manifest_path.read_text())
+        assert sorted(manifest) == ["build", "deploy", "status"]
+
+    def test_grouped_commands_coverage(self, tmp_path):
+        """Grouped commands use dotted paths in coverage tracking."""
+        app = _make_grouped_app(tmp_path)
+        # Test all commands
+        app.test(["infra", "deploy"])
+        app.test(["infra", "teardown"])
+        app.test(["status"])
+
+        results, _, code = app.run_checks(
+            SimpleCtx(project_root=tmp_path),
+            run_all=True,
+        )
+        cov_result = next(r for r in results if r.name == "cli-test-coverage")
+        assert cov_result.status == "pass"
+
+    def test_grouped_partial_coverage_fails(self, tmp_path):
+        """Missing a grouped command -> check FAILs naming it."""
+        app = _make_grouped_app(tmp_path)
+        app.test(["infra", "deploy"])
+        app.test(["status"])
+        # infra.teardown is not tested
+
+        results, _, code = app.run_checks(
+            SimpleCtx(project_root=tmp_path),
+            run_all=True,
+        )
+        cov_result = next(r for r in results if r.name == "cli-test-coverage")
+        assert cov_result.status == "fail"
+        problem_texts = [p.text for p in cov_result.problems]
+        assert any("infra.teardown" in t for t in problem_texts)
+
+
+class TestCoverageDisabled:
+    def test_no_recording_when_disabled(self, tmp_path):
+        """test_coverage=False (default) produces no shard files."""
+        os.chdir(tmp_path)
+        app = strictcli.App(
+            name="nocover", version="1.0.0", help="no coverage",
+        )
+
+        @app.command(name="greet", help="say hello")
+        def cmd_greet(ctx, **_kw):
+            pass
+
+        app.test(["greet"])
+
+        coverage_dir = tmp_path / ".strictcli" / "coverage"
+        assert not coverage_dir.exists()

{strictcli-0.29.0 → strictcli-0.30.1}/uv.lock

@@ -232,7 +232,7 @@ wheels = [
 
 [[package]]
 name = "strictcli"
-version = "0.29.0"
+version = "0.30.1"
 source = { editable = "." }
 dependencies = [
     { name = "tomlkit" },