strictcli 0.31.0__tar.gz → 0.32.1__tar.gz

strictcli-0.32.1/CLAUDE.md

@@ -0,0 +1,26 @@
+# strictcli (Python)
+
+Python implementation of strictcli. Published to PyPI. Part of the strictcli
+rlsbl monorepo as releasable `py-strictcli`.
+
+## Development
+
+- `uv sync` then `uv run pytest` from this directory. Always use `uv`, never pip.
+- Run the conformance suite after changes: `cd ../conformance && python run.py --target python`.
+- CI (`ci-router.yml` at the repo root) runs the full pytest suite on every push touching `python/**`.
+
+## Release workflow
+
+Releases go through [rlsbl](https://github.com/smm-h/rlsbl) monorepo releases.
+
+- CHANGELOG.md is generated from JSONL changelog entries — never edit it by hand.
+  Add entries with `rlsbl changelog add` from inside `python/` after each commit
+  (they land in `.rlsbl-monorepo/releasables/py-strictcli/changes/unreleased.jsonl`).
+- To release: from the repo root, run `rlsbl monorepo release init`, edit the
+  scaffolded release file (bump type, description, and context live in the file),
+  then run `rlsbl monorepo release run --no-allow-dirty --watch --yes`.
+- Never publish or push manually — CI publishes to PyPI via Trusted Publishing.
+
+## Conventions
+
+- No tokens or secrets in command-line arguments (use env vars or config files).

{strictcli-0.31.0 → strictcli-0.32.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: strictcli
-Version: 0.31.0
+Version: 0.32.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.31.0 → strictcli-0.32.1}/pyproject.toml

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

{strictcli-0.31.0 → strictcli-0.32.1}/strictcli/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.31.0"
+__version__ = "0.32.1"
 
 __all__ = [
     "App", "Flag", "Arg", "FlagSet", "MutexGroup", "CoRequired", "Requires",
@@ -2803,13 +2803,25 @@ class App:
         # 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._coverage_dir: str | None = None
+        self._coverage_manifest_path: str | None = None
         self._last_resolved_path: list[str] = []
         if self.test_coverage:
+            # Anchor the coverage root to the cwd AT CONSTRUCTION TIME. Both the
+            # recorder and the check provider use these absolute paths so that
+            # tests which chdir still record into the repo, and a check evaluated
+            # from a foreign cwd reads the app's own repo state.
+            self._coverage_dir = os.path.abspath(
+                os.path.join(".strictcli", "coverage")
+            )
+            self._coverage_manifest_path = os.path.abspath(
+                os.path.join(".strictcli", "test-coverage.json")
+            )
             self._coverage_shard_path = os.path.join(
-                ".strictcli", "coverage",
+                self._coverage_dir,
                 f"{os.getpid()}-{{n}}.jsonl",
             )
-            os.makedirs(os.path.join(".strictcli", "coverage"), exist_ok=True)
+            os.makedirs(self._coverage_dir, exist_ok=True)
             self.register_check_provider(self._test_coverage_provider)
 
     def _validate_flag_infra_marker(self, f: Flag) -> None:
@@ -2868,18 +2880,67 @@ class App:
     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.
+        Registered automatically when test_coverage=True. The verdict is derived
+        from committed state: the covered set is the union of the committed
+        manifest (.strictcli/test-coverage.json) and any per-process shard files
+        merged from .strictcli/coverage/. Every live registered command path
+        (minus the injected check command) must be present in that union to pass;
+        otherwise the check fails naming each uncovered command.
+
+        Because the verdict reads the committed manifest, it is deterministic on
+        every machine -- a machine that never ran the suite (no local shards)
+        still gets a stable verdict from the committed manifest alone. Both the
+        coverage dir and the manifest path are anchored to the App's
+        construction-time cwd, so the check evaluated from a foreign cwd reads
+        the app's own repo state.
+
+        The manifest is rewritten as the monotonic union of its prior contents
+        and the freshly merged shards, but ONLY when that content actually
+        changes -- a pure check must not dirty a byte-identical file. Accepted
+        staleness: deleting a test leaves its command covered in the manifest
+        until the manifest is deliberately regenerated (e.g. by removing it and
+        re-running the suite), because the union never removes a command.
         """
         def impl(ctx: CheckContext, reporter: "ErrorReporter") -> "_CheckOutcome":
-            coverage_dir = os.path.join(".strictcli", "coverage")
-            manifest_path = os.path.join(".strictcli", "test-coverage.json")
+            coverage_dir = self._coverage_dir
+            manifest_path = self._coverage_manifest_path
+
+            # Subject-matter gating (the sanctioned skip class, mirroring
+            # project-type gating): when the anchored coverage root holds NEITHER
+            # a committed manifest NOR any shard files, this is not the app's own
+            # development tree -- e.g. an installed app running its checks from a
+            # foreign project's cwd, where the construction-anchored root points
+            # at a directory with no coverage state. Report a visible SKIP instead
+            # of failing with the app's entire command surface listed as
+            # uncovered. When EITHER exists, behavior is unchanged: a partial
+            # manifest still fails honestly, and an empty-manifest file present
+            # still means "coverage configured but empty" = fail listing all.
+            manifest_exists = bool(manifest_path) and os.path.isfile(manifest_path)
+            shards_exist = bool(coverage_dir) and os.path.isdir(coverage_dir) and any(
+                fname.endswith(".jsonl") for fname in os.listdir(coverage_dir)
+            )
+            if not manifest_exists and not shards_exist:
+                anchor = os.path.dirname(manifest_path) if manifest_path else coverage_dir
+                return reporter.skipped(
+                    f"no coverage state at {anchor} -- cli-test-coverage applies "
+                    "to the app's own development tree"
+                )
 
-            # Merge shards
             covered: set[str] = set()
-            if os.path.isdir(coverage_dir):
+
+            # Seed from the committed manifest -- this is what makes the verdict
+            # deterministic on machines that never ran the suite.
+            if manifest_path and os.path.isfile(manifest_path):
+                try:
+                    with open(manifest_path, encoding="utf-8") as f:
+                        data = json.load(f)
+                    if isinstance(data, list):
+                        covered.update(c for c in data if isinstance(c, str))
+                except (json.JSONDecodeError, OSError):
+                    pass
+
+            # Merge shards (optional freshness input)
+            if coverage_dir and os.path.isdir(coverage_dir):
                 for fname in os.listdir(coverage_dir):
                     if not fname.endswith(".jsonl"):
                         continue
@@ -2893,17 +2954,22 @@ class App:
                             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")
+            # Rewrite the manifest as the monotonic union, but only when the
+            # content actually changes (keeps a pure check from dirtying a
+            # byte-identical file).
+            if manifest_path and covered:
+                new_content = json.dumps(sorted(covered), indent=2) + "\n"
+                existing: str | None = None
+                if os.path.isfile(manifest_path):
+                    try:
+                        with open(manifest_path, encoding="utf-8") as f:
+                            existing = f.read()
+                    except OSError:
+                        existing = None
+                if existing != new_content:
+                    os.makedirs(os.path.dirname(manifest_path), exist_ok=True)
+                    with open(manifest_path, "w", encoding="utf-8") as f:
+                        f.write(new_content)
 
             # Compare against command surface (exclude the framework-injected
             # check command -- it is not a user command)

{strictcli-0.31.0 → strictcli-0.32.1}/tests/test_coverage.py

@@ -175,20 +175,49 @@ class TestCoverageCheck:
         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."""
+    def test_zero_coverage_state_skips(self, tmp_path):
+        """No shards and no manifest -> SKIP with a subject-matter reason.
+
+        Subject-matter gating: when the anchored coverage root holds NEITHER a
+        committed manifest NOR any shard files, this is not the app's own
+        development tree (e.g. an installed app running its checks from a foreign
+        project's cwd). The check reports a visible SKIP naming the anchored path
+        rather than failing with the whole command surface listed as uncovered.
+        """
         app = _make_app(tmp_path)
-        # Don't run any test() or call() -- no shards exist
+        # Don't run any test() or call() -- no shards, no manifest
 
         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
+        assert cov_result.status == "skip"
+        assert "development tree" in cov_result.message
+        # Reason names the anchored .strictcli path, not the foreign cwd.
+        assert str(tmp_path / ".strictcli") in cov_result.message
+
+    def test_empty_manifest_file_present_fails_listing_all(self, tmp_path):
+        """An empty-manifest file present means "coverage configured but empty"
+        -> FAIL listing every command, NOT a skip. The skip class only triggers
+        when NEITHER a manifest NOR any shards exist."""
+        app = _make_app(tmp_path)
+        manifest_path = tmp_path / ".strictcli" / "test-coverage.json"
+        manifest_path.write_text("[]\n")
+
+        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]
+        uncovered = {
+            t.split("no test coverage for command: ")[1]
+            for t in problem_texts
+            if "no test coverage for command:" in t
+        }
+        assert uncovered == {"build", "deploy", "status"}
 
     def test_manifest_written_on_check(self, tmp_path):
         """The check writes .strictcli/test-coverage.json with covered commands."""
@@ -239,6 +268,93 @@ class TestCoverageCheck:
         assert any("infra.teardown" in t for t in problem_texts)
 
 
+class TestCoverageChdirSafety:
+    def test_record_anchored_to_construction_cwd(self, tmp_path):
+        """test() records into the construction-time coverage dir, not the cwd
+        that a test happened to chdir into."""
+        app = _make_app(tmp_path)  # constructs with cwd == tmp_path
+        other = tmp_path / "elsewhere"
+        other.mkdir()
+        os.chdir(other)
+
+        app.test(["deploy"])
+
+        construction_shards = list(
+            (tmp_path / ".strictcli" / "coverage").glob("*.jsonl")
+        )
+        assert construction_shards, "shard must land under the construction cwd"
+        foreign = other / ".strictcli" / "coverage"
+        assert not foreign.exists(), "must not record into the chdir'd cwd"
+
+
+class TestManifestUnionVerdict:
+    def test_manifest_present_shards_absent_passes(self, tmp_path):
+        """Committed manifest covering every command -> deterministic PASS even
+        with no shard files (the machine never ran the suite)."""
+        app = _make_app(tmp_path)
+        manifest_path = tmp_path / ".strictcli" / "test-coverage.json"
+        manifest_path.write_text(
+            json.dumps(["build", "deploy", "status"], indent=2) + "\n"
+        )
+
+        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_check_from_foreign_cwd_reads_app_state(self, tmp_path):
+        """The check evaluated from a foreign cwd reads the app's own repo state
+        (anchored manifest), not the foreign directory."""
+        app = _make_app(tmp_path)
+        manifest_path = tmp_path / ".strictcli" / "test-coverage.json"
+        manifest_path.write_text(
+            json.dumps(["build", "deploy", "status"], indent=2) + "\n"
+        )
+        other = tmp_path / "foreign"
+        other.mkdir()
+        os.chdir(other)
+
+        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_manifest_union_is_monotonic(self, tmp_path):
+        """A run recording only a subset keeps prior commands covered (union)."""
+        app = _make_app(tmp_path)
+        manifest_path = tmp_path / ".strictcli" / "test-coverage.json"
+        manifest_path.write_text(
+            json.dumps(["build", "deploy", "status"], indent=2) + "\n"
+        )
+        app.test(["deploy"])  # only one recorded this run
+
+        app.run_checks(SimpleCtx(project_root=tmp_path), run_all=True)
+
+        manifest = json.loads(manifest_path.read_text())
+        assert sorted(manifest) == ["build", "deploy", "status"]
+
+    def test_manifest_not_rewritten_when_unchanged(self, tmp_path):
+        """A pure check must not dirty a byte-identical manifest."""
+        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"
+        content1 = manifest_path.read_text()
+        mtime1 = manifest_path.stat().st_mtime_ns
+
+        app.run_checks(SimpleCtx(project_root=tmp_path), run_all=True)
+
+        assert manifest_path.read_text() == content1
+        assert manifest_path.stat().st_mtime_ns == mtime1
+
+
 class TestCoverageDisabled:
     def test_no_recording_when_disabled(self, tmp_path):
         """test_coverage=False (default) produces no shard files."""

{strictcli-0.31.0 → strictcli-0.32.1}/uv.lock

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

strictcli-0.31.0/CLAUDE.md

@@ -1,20 +0,0 @@
-# strictcli
-
-## Release workflow
-
-This project uses [rlsbl](https://github.com/smm-h/rlsbl) for release orchestration.
-
-- Update CHANGELOG.md with a `## X.Y.Z` entry describing changes
-- Run `rlsbl release [patch|minor|major]` to bump version and create a GitHub Release
-- CI handles publishing automatically via the publish workflow
-- Never publish manually — always use `rlsbl release`
-- Configure Trusted Publishing on pypi.org for automated PyPI releases
-- Use `rlsbl release --dry-run` to preview a release without making changes
-
-## Conventions
-
-- No tokens or secrets in command-line arguments (use env vars or config files)
-- All file writes to shared state should be atomic (write to tmp, then rename)
-- External calls (APIs, CLI tools) must have timeouts and graceful fallbacks
-- Use `uv pip install -e .` for local development
-- CI runs smoke tests on every push; manual testing for UI/UX changes