strictcli 0.41.1__tar.gz → 0.42.0__tar.gz

{strictcli-0.41.1 → strictcli-0.42.0}/PKG-INFO

@@ -1,16 +1,21 @@
 Metadata-Version: 2.5
 Name: strictcli
-Version: 0.41.1
-Summary: A strict CLI framework for Python
-Project-URL: Homepage, https://github.com/smm-h/strictcli
+Version: 0.42.0
+Summary: A CLI framework for the Era of Agents: nothing is inferred, everything is declared. First-class support for Go, Python, and TypeScript (Python implementation)
+Project-URL: Homepage, https://smmh.dev/strictcli/
+Project-URL: Documentation, https://smmh.dev/strictcli/
 Project-URL: Repository, https://github.com/smm-h/strictcli
+Project-URL: Issues, https://github.com/smm-h/strictcli/issues
+Project-URL: Changelog, https://github.com/smm-h/strictcli/blob/main/CHANGELOG.md
 Author-email: "S. M. Hosseini" <m.hosseini@veliu.com>
 License-Expression: MIT
 License-File: LICENSE
-Keywords: argparse,cli,command-line,framework,rlsbl,strictcli
+Keywords: argparse,argument-parser,cli,cli-framework,command-line,framework,rlsbl,strictcli
 Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
@@ -19,7 +24,7 @@ Description-Content-Type: text/markdown
 
 # strictcli
 
-A strict CLI framework for Python.
+A CLI framework for the Era of Agents: nothing is inferred, everything is declared. First-class support for Go, Python, and TypeScript (Python implementation).
 
 strictcli makes you declare everything -- every command, flag, argument, and environment variable must have help text or the framework errors at registration time. Four types only: `str`, `bool`, `int`, `float`. No magic type inference, no implicit defaults.
 

{strictcli-0.41.1 → strictcli-0.42.0}/README.md

@@ -1,6 +1,6 @@
 # strictcli
 
-A strict CLI framework for Python.
+A CLI framework for the Era of Agents: nothing is inferred, everything is declared. First-class support for Go, Python, and TypeScript (Python implementation).
 
 strictcli makes you declare everything -- every command, flag, argument, and environment variable must have help text or the framework errors at registration time. Four types only: `str`, `bool`, `int`, `float`. No magic type inference, no implicit defaults.
 

{strictcli-0.41.1 → strictcli-0.42.0}/pyproject.toml

@@ -4,17 +4,28 @@ build-backend = "hatchling.build"
 
 [project]
 name = "strictcli"
-version = "0.41.1"
-description = "A strict CLI framework for Python"
+version = "0.42.0"
+description = "A CLI framework for the Era of Agents: nothing is inferred, everything is declared. First-class support for Go, Python, and TypeScript (Python implementation)"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.11"
 authors = [{ name = "S. M. Hosseini", email = "m.hosseini@veliu.com" }]
-keywords = ["strictcli", "cli", "argparse", "command-line", "framework", "rlsbl"]
+keywords = [
+    "strictcli",
+    "cli",
+    "cli-framework",
+    "command-line",
+    "argument-parser",
+    "argparse",
+    "framework",
+    "rlsbl",
+]
 classifiers = [
     "Development Status :: 3 - Alpha",
+    "Environment :: Console",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
@@ -29,5 +40,8 @@ dev = ["pytest", "allpairspy", "jsonschema"]
 testpaths = ["tests"]
 
 [project.urls]
-Homepage = "https://github.com/smm-h/strictcli"
+Homepage = "https://smmh.dev/strictcli/"
+Documentation = "https://smmh.dev/strictcli/"
 Repository = "https://github.com/smm-h/strictcli"
+Issues = "https://github.com/smm-h/strictcli/issues"
+Changelog = "https://github.com/smm-h/strictcli/blob/main/CHANGELOG.md"

{strictcli-0.41.1 → strictcli-0.42.0}/strictcli/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.41.1"
+__version__ = "0.42.0"
 
 __all__ = [
     "App", "Flag", "Arg", "FlagSet",
@@ -8724,6 +8724,17 @@ def warn_check_spec(
     )
 
 
+def _msg_test_coverage_boolean_retired() -> str:
+    """The retired boolean's refusal (contract §12.12: one sentence, each
+    language's own spellings inside it -- `test_coverage` / `test_coverage_dir`
+    here, `WithTestCoverage` / `WithTestCoverageDir` in Go, `testCoverage` /
+    `testCoverageDir` in TypeScript)."""
+    return (
+        "test_coverage is not accepted; declare the directory holding "
+        "coverage/ and test-coverage.json with test_coverage_dir"
+    )
+
+
 @dataclass
 class App:
     """The root CLI application."""
@@ -8761,13 +8772,25 @@ class App:
     proc_observe_allowlist: list[list[str]] | None = None
     checks_path: str | Path | None = None
     checks_embed: bytes | None = None
-    test_coverage: bool = False
+    # The directory holding this app's coverage state: `coverage/` (per-process
+    # shard files) and `test-coverage.json` (the committed manifest). Declared,
+    # never discovered. Absent means coverage is off -- no provider registered,
+    # no paths computed, nothing touched. A declared directory that does not
+    # exist at construction likewise leaves coverage off: that is the installed
+    # distribution, where the path naming the source checkout is simply gone.
+    test_coverage_dir: str | os.PathLike | None = None
+    # Refusal-only. The retired boolean has no accepted spelling; this field
+    # exists so that passing it names the option that replaced it instead of
+    # raising CPython's bare "unexpected keyword argument" TypeError.
+    test_coverage: bool | None = None
     flags: list[Flag] = field(default_factory=list)
     _commands: dict[str, Command] = field(default_factory=dict)
     _groups: dict[str, Group] = field(default_factory=dict)
     _deprecated: dict[str, DeprecatedCommand] = field(default_factory=dict)
 
     def __post_init__(self) -> None:
+        if self.test_coverage is not None:
+            raise ValueError(_msg_test_coverage_boolean_retired())
         _require_non_empty_str(self.version, "version", "App")
         _require_non_empty_str(self.help, "help", "App")
         # Check for duplicate and reserved global flag names
@@ -8973,23 +8996,27 @@ class App:
         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(
-                self._coverage_dir,
-                f"{os.getpid()}.jsonl",
-            )
-            os.makedirs(self._coverage_dir, exist_ok=True)
-            self.register_check_provider(self._test_coverage_provider)
+        if self.test_coverage_dir is not None:
+            # The declared directory decides everything. An app installed
+            # elsewhere finds it absent and stays uninstrumented: no provider,
+            # no paths, no writes anywhere -- in particular not into whatever
+            # directory the consumer happened to start the CLI from.
+            root = os.path.abspath(os.fspath(self.test_coverage_dir))
+            if os.path.isdir(root):
+                # Only the PATHS are computed here. The coverage directory
+                # itself is created lazily by _record_coverage, immediately
+                # before the first shard write: shards are written only on the
+                # test-harness paths (test() and call()), so a plain CLI
+                # invocation leaves no coverage/ behind.
+                self._coverage_dir = os.path.join(root, "coverage")
+                self._coverage_manifest_path = os.path.join(
+                    root, "test-coverage.json"
+                )
+                self._coverage_shard_path = os.path.join(
+                    self._coverage_dir,
+                    f"{os.getpid()}.jsonl",
+                )
+                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
@@ -9069,19 +9096,19 @@ class App:
     def _test_coverage_provider(self) -> list[CheckSpec]:
         """Built-in check provider for cli-test-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.
+        Registered automatically when test_coverage_dir names a directory that
+        exists. The verdict is derived from committed state: the covered set is
+        the union of the committed manifest (test-coverage.json in that
+        directory) and any per-process shard files merged from its coverage/
+        subdirectory. 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.
+        coverage dir and the manifest path sit under the DECLARED directory, so
+        the check evaluated from any 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
@@ -11510,7 +11537,7 @@ class App:
         self._begin_dispatch()
         cmd_path = ".".join(self._last_resolved_path + [cmd.name])
         # Record test-coverage hit (command-level only, test mode only).
-        if mode == "test" and self.test_coverage:
+        if mode == "test" and self._coverage_shard_path is not None:
             self._record_coverage(cmd_path)
         # Store sources for function handlers that need provenance info
         self._last_sources = sources
@@ -11777,7 +11804,7 @@ class App:
 
         self._begin_dispatch()
         # Record test-coverage hit (command-level only).
-        if self.test_coverage:
+        if self._coverage_shard_path is not None:
             self._record_coverage(command_path)
 
         # Passthrough commands: forward raw args to the passthrough handler

{strictcli-0.41.1 → strictcli-0.42.0}/tests/test_coverage.py

@@ -1,12 +1,14 @@
 """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
+- test_coverage_dir=<existing dir> enables recording of command hits
+- test() and call() both record to per-process shard files under that directory
 - 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
+- A declared directory that does not exist leaves the instrumentation off
+- The retired boolean is refused by name
 """
 
 import json
@@ -24,12 +26,18 @@ class SimpleCtx:
     project_root: Path
 
 
+def _coverage_root(tmp_path):
+    """The declared coverage directory, created so the option takes effect."""
+    root = tmp_path / ".strictcli"
+    root.mkdir(parents=True, exist_ok=True)
+    return root
+
+
 def _make_app(tmp_path):
-    """Build a 3-command app with test_coverage enabled, rooted in tmp_path."""
-    os.chdir(tmp_path)
+    """Build a 3-command app whose coverage directory is tmp_path/.strictcli."""
     app = strictcli.App(
         name="coverapp", version="1.0.0", help="coverage test app",
-        test_coverage=True,
+        test_coverage_dir=str(_coverage_root(tmp_path)),
     )
 
     @app.command(name="deploy", effect="read_only", forwarding=strictcli.Forwarding(reason="test handler absorbs global flag values"), help="deploy the app")
@@ -50,10 +58,9 @@ def _make_app(tmp_path):
 
 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,
+        test_coverage_dir=str(_coverage_root(tmp_path)),
     )
 
     grp = app.group("infra", help="infrastructure commands")
@@ -206,6 +213,7 @@ class TestCoverageCheck:
         when NEITHER a manifest NOR any shards exist."""
         app = _make_app(tmp_path)
         manifest_path = tmp_path / ".strictcli" / "test-coverage.json"
+        manifest_path.parent.mkdir(parents=True, exist_ok=True)
         manifest_path.write_text("[]\n")
 
         results, _, code = app.run_checks(
@@ -272,20 +280,20 @@ class TestCoverageCheck:
 
 
 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
+    def test_record_anchored_to_declared_directory(self, tmp_path):
+        """test() records into the declared coverage dir, not the cwd that a
+        test happened to chdir into."""
+        app = _make_app(tmp_path)  # declares tmp_path/.strictcli
         other = tmp_path / "elsewhere"
         other.mkdir()
         os.chdir(other)
 
         app.test(["deploy"])
 
-        construction_shards = list(
+        declared_shards = list(
             (tmp_path / ".strictcli" / "coverage").glob("*.jsonl")
         )
-        assert construction_shards, "shard must land under the construction cwd"
+        assert declared_shards, "shard must be written under the declared dir"
         foreign = other / ".strictcli" / "coverage"
         assert not foreign.exists(), "must not record into the chdir'd cwd"
 
@@ -296,6 +304,7 @@ class TestManifestUnionVerdict:
         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.parent.mkdir(parents=True, exist_ok=True)
         manifest_path.write_text(
             json.dumps(["build", "deploy", "status"], indent=2) + "\n"
         )
@@ -309,9 +318,10 @@ class TestManifestUnionVerdict:
 
     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."""
+        (the declared manifest), not the foreign directory."""
         app = _make_app(tmp_path)
         manifest_path = tmp_path / ".strictcli" / "test-coverage.json"
+        manifest_path.parent.mkdir(parents=True, exist_ok=True)
         manifest_path.write_text(
             json.dumps(["build", "deploy", "status"], indent=2) + "\n"
         )
@@ -330,6 +340,7 @@ class TestManifestUnionVerdict:
         """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.parent.mkdir(parents=True, exist_ok=True)
         manifest_path.write_text(
             json.dumps(["build", "deploy", "status"], indent=2) + "\n"
         )
@@ -360,7 +371,7 @@ class TestManifestUnionVerdict:
 
 class TestCoverageDisabled:
     def test_no_recording_when_disabled(self, tmp_path):
-        """test_coverage=False (default) produces no shard files."""
+        """An undeclared test_coverage_dir (the default) produces no shards."""
         os.chdir(tmp_path)
         app = strictcli.App(
             name="nocover", version="1.0.0", help="no coverage",
@@ -374,3 +385,132 @@ class TestCoverageDisabled:
 
         coverage_dir = tmp_path / ".strictcli" / "coverage"
         assert not coverage_dir.exists()
+
+
+class TestCoverageDirectoryIsLazy:
+    def test_construction_leaves_no_coverage_subdirectory(self, tmp_path):
+        """Constructing an app with a declared coverage directory must not
+        create coverage/ inside it -- a plain CLI invocation never records
+        coverage, so it must not plant an empty directory."""
+        app = _make_app(tmp_path)
+        assert app is not None
+        assert not (tmp_path / ".strictcli" / "coverage").exists()
+
+    def test_recording_creates_the_directory(self, tmp_path):
+        """The recorder creates the coverage directory immediately before the
+        first shard write."""
+        app = _make_app(tmp_path)
+        app.test(["deploy"])
+
+        shard = tmp_path / ".strictcli" / "coverage" / f"{os.getpid()}.jsonl"
+        assert shard.is_file()
+
+    def test_check_skips_when_coverage_state_absent(self, tmp_path):
+        """The provider reads a declared root holding no coverage state without
+        raising -- it reports the subject-matter SKIP."""
+        app = _make_app(tmp_path)
+        assert not (tmp_path / ".strictcli" / "coverage").exists()
+
+        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 == "skip"
+
+
+class TestDeclaredDirectoryAbsent:
+    """A declared directory that does not exist leaves coverage off.
+
+    This is the installed-wheel case: the path that names the source
+    checkout's ``.strictcli`` directory is simply not there once the CLI is
+    installed elsewhere, so the app registers no check, computes no paths and
+    creates nothing.
+    """
+
+    def test_missing_directory_registers_no_check(self, tmp_path):
+        missing = tmp_path / "nowhere" / ".strictcli"
+        app = strictcli.App(
+            name="coverapp", version="1.0.0", help="coverage test app",
+            test_coverage_dir=str(missing),
+        )
+
+        @app.command(name="deploy", effect="read_only", help="deploy the app")
+        def cmd_deploy(ctx):
+            pass
+
+        # No provider, so the check system never turns on: there is no `check`
+        # command to route to, and no cli-test-coverage to list.
+        result = app.test(["check", "--all"])
+        assert result.exit_code == 1
+        assert "cli-test-coverage" not in result.stdout
+        with pytest.raises(ValueError, match="checks are not enabled"):
+            app.run_checks(SimpleCtx(project_root=tmp_path), run_all=True)
+
+    def test_missing_directory_creates_nothing(self, tmp_path):
+        missing = tmp_path / "nowhere" / ".strictcli"
+        app = strictcli.App(
+            name="coverapp", version="1.0.0", help="coverage test app",
+            test_coverage_dir=str(missing),
+        )
+
+        @app.command(name="deploy", effect="read_only", help="deploy the app")
+        def cmd_deploy(ctx):
+            pass
+
+        app.test(["deploy"])
+        app.call("deploy")
+
+        assert not (tmp_path / "nowhere").exists()
+
+
+class TestForeignDirectoryRun:
+    """A consumer-style run from a foreign directory.
+
+    The installed CLI is started in some unrelated project. Its declared
+    coverage directory does not exist there, so `check` must neither list
+    cli-test-coverage nor write a `.strictcli/` into the foreign directory.
+    """
+
+    def test_foreign_run_lists_no_check_and_touches_nothing(self, tmp_path):
+        foreign = tmp_path / "some-other-project"
+        foreign.mkdir()
+        os.chdir(foreign)
+
+        app = strictcli.App(
+            name="coverapp", version="1.0.0", help="coverage test app",
+            test_coverage_dir=str(tmp_path / "gone" / ".strictcli"),
+        )
+
+        @app.command(name="deploy", effect="read_only", help="deploy the app")
+        def cmd_deploy(ctx):
+            pass
+
+        result = app.test(["check", "--all"])
+        assert "cli-test-coverage" not in result.stdout
+
+        assert not (foreign / ".strictcli").exists()
+        assert list(foreign.iterdir()) == []
+
+
+class TestRetiredBooleanRefused:
+    def test_boolean_true_is_refused_naming_the_directory_option(self):
+        with pytest.raises(ValueError) as exc:
+            strictcli.App(
+                name="coverapp", version="1.0.0", help="coverage test app",
+                test_coverage=True,
+            )
+        assert str(exc.value) == (
+            "test_coverage is not accepted; declare the directory holding "
+            "coverage/ and test-coverage.json with test_coverage_dir"
+        )
+
+    def test_boolean_false_is_refused_too(self):
+        """There is no accepted spelling of the retired option, not even the
+        one that used to mean "off" -- absence is how coverage is declared off."""
+        with pytest.raises(ValueError) as exc:
+            strictcli.App(
+                name="coverapp", version="1.0.0", help="coverage test app",
+                test_coverage=False,
+            )
+        assert "test_coverage_dir" in str(exc.value)

{strictcli-0.41.1 → strictcli-0.42.0}/tests/test_effects.py

@@ -1147,7 +1147,8 @@ class TestCacheWrites:
 
     def test_cache_writes_never_appear_in_the_would_do_log(self, tmp_path, monkeypatch):
         monkeypatch.chdir(tmp_path)
-        app = _app(test_coverage=True)
+        (tmp_path / ".strictcli").mkdir()
+        app = _app(test_coverage_dir=str(tmp_path / ".strictcli"))
 
         @app.command("run", help="run", effect="read_only")
         def _run(ctx):
@@ -1166,7 +1167,8 @@ class TestCacheWrites:
         would move user-visible numbering for no visible reason.
         """
         monkeypatch.chdir(tmp_path)
-        app = _app(test_coverage=True)
+        (tmp_path / ".strictcli").mkdir()
+        app = _app(test_coverage_dir=str(tmp_path / ".strictcli"))
 
         @app.command("rel", help="rel", effect="mutating")
         def _rel(ctx):
@@ -1189,7 +1191,8 @@ class TestCacheWrites:
     def test_cache_writes_do_not_shift_the_truncation_step(self, tmp_path,
                                                            monkeypatch):
         monkeypatch.chdir(tmp_path)
-        app = _app(test_coverage=True)
+        (tmp_path / ".strictcli").mkdir()
+        app = _app(test_coverage_dir=str(tmp_path / ".strictcli"))
 
         @app.command("rel", help="rel", effect="mutating")
         def _rel(ctx):

{strictcli-0.41.1 → strictcli-0.42.0}/uv.lock

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