assurance-cli 0.2.2__tar.gz → 0.3.0__tar.gz

{assurance_cli-0.2.2 → assurance_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assurance-cli
-Version: 0.2.2
+Version: 0.3.0
 Summary: CLI for folder assurance checks — coverage, staleness, and baselines.
 Author-email: "I-Ops Operations Intelligence, LLC" <hello@i-ops.dev>
 License: Apache-2.0
@@ -19,7 +19,7 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: assurance-core>=0.3.2
+Requires-Dist: assurance-core>=0.4
 Requires-Dist: openpyxl>=3.1
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
@@ -56,6 +56,10 @@ No account · no API key · no network call · **no model decides any of it**
 
 ## Three commands
 
+**`diff` is the general one.** `check` is the special case for a folder of
+dated or numbered *tabular* files — if your files are `.md`, or named in a format it can't read, use
+`diff` and declare the set yourself.
+
 ### `assurance diff` — any two sets of keys
 
 ```bash
@@ -95,10 +99,20 @@ assurance check ~/invoices --expect numbered
 Monthly, quarterly, weekly, daily, numbered. That last line is the **derivation**: it prints with
 every ratio so you can disagree with the denominator, not just the result.
 
+When a file is there under a name it can't read, it says so beside the gap, because that's the
+difference between *never produced* and *produced and named differently*:
+
+```
+11 of 12 months from 2025-01 to 2025-12 — not in this folder: March 2025
+— 1 name here could not be read as any of them: March FINAL v2.csv
+```
+
 ### `assurance init` — did anything change underneath?
 
 ```bash
 assurance init ~/thesis-data
+# Baseline written to ~/thesis-data/.assurance.json — 34 tabular files recorded.
+
 # ... weeks pass, several people touch the folder ...
 assurance check ~/thesis-data --against-baseline
 ```

{assurance_cli-0.2.2 → assurance_cli-0.3.0}/README.md

@@ -29,6 +29,10 @@ No account · no API key · no network call · **no model decides any of it**
 
 ## Three commands
 
+**`diff` is the general one.** `check` is the special case for a folder of
+dated or numbered *tabular* files — if your files are `.md`, or named in a format it can't read, use
+`diff` and declare the set yourself.
+
 ### `assurance diff` — any two sets of keys
 
 ```bash
@@ -68,10 +72,20 @@ assurance check ~/invoices --expect numbered
 Monthly, quarterly, weekly, daily, numbered. That last line is the **derivation**: it prints with
 every ratio so you can disagree with the denominator, not just the result.
 
+When a file is there under a name it can't read, it says so beside the gap, because that's the
+difference between *never produced* and *produced and named differently*:
+
+```
+11 of 12 months from 2025-01 to 2025-12 — not in this folder: March 2025
+— 1 name here could not be read as any of them: March FINAL v2.csv
+```
+
 ### `assurance init` — did anything change underneath?
 
 ```bash
 assurance init ~/thesis-data
+# Baseline written to ~/thesis-data/.assurance.json — 34 tabular files recorded.
+
 # ... weeks pass, several people touch the folder ...
 assurance check ~/thesis-data --against-baseline
 ```

assurance_cli-0.3.0/assurance_cli/__init__.py

@@ -0,0 +1,19 @@
+"""assurance-cli — folder checks anyone can run without I-Ops.
+
+Shared filesystem I/O (`paths`, `profile`, `gather`) lives in this package so `assurance-mcp` can
+import it instead of duplicating the profiler. MCP depends on this package for gathering only; the
+CLI does not depend on MCP. Two copies of the profiler is how they disagree.
+"""
+
+# Read from the installed distribution rather than typed here. A hardcoded literal is a second place
+# the version lives, and the second place is the one that goes stale: these sat at "0.1.0" through
+# five releases and were reported by an outside reviewer on 2026-08-29. One source of truth is
+# `pyproject.toml`, and this reads what was actually installed from it.
+from importlib.metadata import PackageNotFoundError, version as _version
+
+try:
+    __version__ = _version("assurance-cli")
+except PackageNotFoundError:  # running from a source tree that was never installed
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

{assurance_cli-0.2.2 → assurance_cli-0.3.0}/assurance_cli/baseline.py

@@ -19,7 +19,12 @@ def init_baseline(folder: str, *, update: bool = False) -> dict[str, Any]:
     root = resolve_folder(folder)
     path = root / BASELINE_NAME
     if path.exists() and not update:
-        return {"written": False, "path": str(path), "reason": "baseline already exists; use --update"}
+        return {
+            "written": False,
+            "path": str(path),
+            "reason": "baseline already exists; use --update",
+            "summary": f"A baseline already exists at {path}. Pass --update to overwrite it.",
+        }
 
     entries: dict[str, Any] = {}
     for file_path in sorted(root.rglob("*")):
@@ -50,7 +55,22 @@ def init_baseline(folder: str, *, update: bool = False) -> dict[str, Any]:
         "files": entries,
     }
     path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
-    return {"written": True, "path": str(path), "file_count": len(entries)}
+    # A summary, because text mode renders one and prints nothing without it. `assurance init`
+    # wrote the file and then said nothing at all, so success was indistinguishable from a hung
+    # command — reported by an outside reviewer 2026-08-29. The count is the useful half: a baseline
+    # over zero files is a baseline that will never notice anything.
+    noun = "file" if len(entries) == 1 else "files"
+    return {
+        "written": True,
+        "path": str(path),
+        "file_count": len(entries),
+        "summary": (
+            f"Baseline written to {path} — {len(entries)} tabular {noun} recorded. "
+            "Re-check with `assurance check <folder> --against-baseline`."
+            if entries
+            else f"Baseline written to {path} — no tabular files found, so it records nothing."
+        ),
+    }
 
 
 def check_against_baseline(folder: str) -> dict[str, Any]:

{assurance_cli-0.2.2 → assurance_cli-0.3.0}/assurance_cli/cli.py

@@ -14,14 +14,24 @@ from assurance_cli.setdiff import KeySpecError, diff_sets, format_diff
 
 
 def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(prog="assurance", description="Folder assurance checks — arithmetic, not models.")
+    parser = argparse.ArgumentParser(
+        prog="assurance",
+        description=(
+            "Did the job cover everything it was supposed to cover? Arithmetic, not models. "
+            "`diff` is the general command — it compares any two sets of keys. `check` is the "
+            "special case for a folder of dated or numbered files."
+        ),
+    )
     sub = parser.add_subparsers(dest="command", required=True)
 
     init_parser = sub.add_parser("init", help="Write .assurance.json baseline")
     init_parser.add_argument("folder", help="Folder to baseline")
     init_parser.add_argument("--update", action="store_true", help="Overwrite an existing baseline")
 
-    check_parser = sub.add_parser("check", help="Check a folder for coverage or staleness")
+    check_parser = sub.add_parser(
+        "check",
+        help="Special case: a folder of DATED or NUMBERED files (tabular). For anything else use `diff`",
+    )
     check_parser.add_argument("folder", help="Folder to check")
     check_parser.add_argument("--expect", choices=["monthly", "quarterly", "weekly", "daily", "numbered"])
     check_parser.add_argument("--from", dest="from_point", metavar="FROM")

{assurance_cli-0.2.2 → assurance_cli-0.3.0}/assurance_cli/gather.py

@@ -25,6 +25,8 @@ from assurance_cli.profile import TABULAR_SUFFIXES, profile_file
 
 MAX_PERIODS = 36
 MAX_NUMBERED = 500
+# Enough to say "it is probably right there" without pasting a whole directory into one sentence.
+MAX_UNREAD = 20
 MIN_FILES_TO_INFER = 3
 
 _KIND_FROM_NAME = {
@@ -39,7 +41,7 @@ _KIND_FROM_NAME = {
 def list_dated_files(folder: str) -> dict[str, Any]:
     """List sequence points present in a folder from dated tabular filenames."""
     root = resolve_folder(folder)
-    by_key = _indexed_files(root)
+    by_key, unread = _indexed_files(root)
     keys = sorted(by_key)
     return {
         "folder": str(root),
@@ -65,7 +67,7 @@ def check_coverage(
 ) -> dict[str, Any]:
     """Check whether every step in the span is present — cold start, no prior state."""
     root = resolve_folder(folder)
-    by_key = _indexed_files(root)
+    by_key, unread = _indexed_files(root)
     if not by_key:
         return {
             "folder": str(root),
@@ -132,7 +134,7 @@ def check_coverage(
         truncated = f"stopped at {cap} {unit}"
         expected_keys = expected_keys[-cap:]
 
-    cov = Coverage(scope_label=scope, truncated=truncated, derivation=derivation)
+    cov = Coverage(scope_label=scope, truncated=truncated, derivation=derivation, unmatched=unread)
     for key, label in expected_keys:
         expectation = Expectation(key=key, label=label, why=derivation or f"in {scope}")
         cov.expected.append(expectation)
@@ -218,8 +220,17 @@ def check_staleness(
     return _finding_to_dict(finding)
 
 
-def _indexed_files(root: Path) -> dict[str, list[Path]]:
+def _indexed_files(root: Path) -> tuple[dict[str, list[Path]], list[str]]:
+    """The files that parse to a point, and the names of the tabular files that do not.
+
+    That second list used to be `continue` and nothing else. It is the difference between two causes
+    that produce an identical `missing` line — never produced, or produced under a name the
+    enumeration could not read — and it was being discarded at the one moment we had it. A folder of
+    twelve files, eleven parsing as months and one called "March FINAL v2.csv", reported March as
+    not in the folder and never mentioned the twelfth file anywhere.
+    """
     found: dict[str, list[Path]] = {}
+    unread: list[str] = []
     for path in sorted(root.rglob("*")):
         if not path.is_file() or path.suffix.lower() not in TABULAR_SUFFIXES:
             continue
@@ -231,10 +242,11 @@ def _indexed_files(root: Path) -> dict[str, list[Path]]:
             continue
         point = point_from_filename(path.name)
         if point is None:
+            unread.append(path.name)
             continue
         key = point_key(point)  # type: ignore[arg-type]
         found.setdefault(key, []).append(path)
-    return found
+    return found, unread[:MAX_UNREAD]
 
 
 def _label_for_key(key: str, filename: str) -> str:
@@ -296,6 +308,7 @@ def _coverage_to_dict(cov: Coverage) -> dict[str, Any]:
         "gone": dict(cov.gone),
         "ambiguous": dict(cov.ambiguous),
         "unreadable": dict(cov.unreadable),
+        "unmatched": list(cov.unmatched),
         "unauthorized": dict(cov.unauthorized),
         "truncated": cov.truncated,
         "undetermined": cov.undetermined,

{assurance_cli-0.2.2 → assurance_cli-0.3.0}/assurance_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assurance-cli
-Version: 0.2.2
+Version: 0.3.0
 Summary: CLI for folder assurance checks — coverage, staleness, and baselines.
 Author-email: "I-Ops Operations Intelligence, LLC" <hello@i-ops.dev>
 License: Apache-2.0
@@ -19,7 +19,7 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: assurance-core>=0.3.2
+Requires-Dist: assurance-core>=0.4
 Requires-Dist: openpyxl>=3.1
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
@@ -56,6 +56,10 @@ No account · no API key · no network call · **no model decides any of it**
 
 ## Three commands
 
+**`diff` is the general one.** `check` is the special case for a folder of
+dated or numbered *tabular* files — if your files are `.md`, or named in a format it can't read, use
+`diff` and declare the set yourself.
+
 ### `assurance diff` — any two sets of keys
 
 ```bash
@@ -95,10 +99,20 @@ assurance check ~/invoices --expect numbered
 Monthly, quarterly, weekly, daily, numbered. That last line is the **derivation**: it prints with
 every ratio so you can disagree with the denominator, not just the result.
 
+When a file is there under a name it can't read, it says so beside the gap, because that's the
+difference between *never produced* and *produced and named differently*:
+
+```
+11 of 12 months from 2025-01 to 2025-12 — not in this folder: March 2025
+— 1 name here could not be read as any of them: March FINAL v2.csv
+```
+
 ### `assurance init` — did anything change underneath?
 
 ```bash
 assurance init ~/thesis-data
+# Baseline written to ~/thesis-data/.assurance.json — 34 tabular files recorded.
+
 # ... weeks pass, several people touch the folder ...
 assurance check ~/thesis-data --against-baseline
 ```

{assurance_cli-0.2.2 → assurance_cli-0.3.0}/assurance_cli.egg-info/SOURCES.txt

@@ -17,4 +17,5 @@ assurance_cli.egg-info/requires.txt
 assurance_cli.egg-info/top_level.txt
 tests/test_cli.py
 tests/test_read_only.py
-tests/test_setdiff.py
+tests/test_setdiff.py
+tests/test_version.py

{assurance_cli-0.2.2 → assurance_cli-0.3.0}/assurance_cli.egg-info/requires.txt

@@ -1,4 +1,4 @@
-assurance-core>=0.3.2
+assurance-core>=0.4
 openpyxl>=3.1
 
 [dev]

{assurance_cli-0.2.2 → assurance_cli-0.3.0}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "assurance-cli"
-version = "0.2.2"
+version = "0.3.0"
 description = "CLI for folder assurance checks — coverage, staleness, and baselines."
 readme = "README.md"
 license = { text = "Apache-2.0" }
 authors = [{ name = "I-Ops Operations Intelligence, LLC", email = "hello@i-ops.dev" }]
 requires-python = ">=3.10"
 dependencies = [
-  "assurance-core>=0.3.2",
+  "assurance-core>=0.4",
   "openpyxl>=3.1",
 ]
 keywords = ["cli", "ai-agents", "governance", "auditing", "assurance", "reproducibility"]

{assurance_cli-0.2.2 → assurance_cli-0.3.0}/tests/test_cli.py

@@ -154,3 +154,26 @@ def test_the_nested_record_agrees_with_the_wrapper(
 def test_a_folder_that_checks_out_still_exits_zero(monthly_folder: Path) -> None:
     """The counterweight: the ordinary path must not start failing."""
     assert main(["check", str(monthly_folder)]) == 0
+
+
+def test_a_file_named_outside_the_scheme_is_reported_beside_the_gap(tmp_path: Path) -> None:
+    """The case an outside reader described on 2026-08-29: eleven months parse, March is "not in
+    this folder", and a file called `March FINAL v2.csv` sits there unmentioned. Knowing a name here
+    could not be read is what separates "never produced" from "produced and named differently"."""
+    for month in ("01", "02", "04", "05", "06", "07", "08", "09", "10", "11", "12"):
+        (tmp_path / f"2025-{month}-report.csv").write_text("a,b\n1,2\n", encoding="utf-8")
+    (tmp_path / "March FINAL v2.csv").write_text("a,b\n1,2\n", encoding="utf-8")
+
+    result = check_coverage(str(tmp_path))
+
+    assert result["coverage"]["unmatched"] == ["March FINAL v2.csv"]
+    assert "could not be read as any of them" in result["summary"]
+    assert "March FINAL v2.csv" in result["summary"]
+
+
+def test_a_folder_where_everything_parses_reports_nothing_unread(monthly_folder: Path) -> None:
+    """The clause must stay rare enough to mean something."""
+    result = check_coverage(str(monthly_folder))
+
+    assert result["coverage"]["unmatched"] == []
+    assert "could not be read" not in result["summary"]

assurance_cli-0.3.0/tests/test_version.py

@@ -0,0 +1,33 @@
+"""`__version__` must agree with `pyproject.toml`.
+
+Both were hardcoded at "0.1.0" and sat there through five releases, so anyone reading
+`assurance_cli.__version__` was told the wrong thing. Reported by an outside reviewer 2026-08-29.
+
+They now read the installed distribution's metadata, which makes `pyproject.toml` the only place a
+version is written. This is the guard that the two agree: CI installs the package immediately before
+running the suite, so the metadata is current there. Locally it can lag a version behind after an
+edit — `pip install -e .` resyncs it, and a lagging editable install is exactly the drift worth
+being told about.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import assurance_cli
+
+
+def _declared() -> str:
+    text = (Path(__file__).resolve().parent.parent / "pyproject.toml").read_text(encoding="utf-8")
+    match = re.search(r'^version = "([^"]+)"', text, re.MULTILINE)
+    assert match, "pyproject.toml has no version"
+    return match.group(1)
+
+
+def test_version_agrees_with_pyproject() -> None:
+    assert assurance_cli.__version__ == _declared()
+
+
+def test_version_is_not_a_placeholder() -> None:
+    assert assurance_cli.__version__ != "0.0.0+unknown"

assurance_cli-0.2.2/assurance_cli/__init__.py

@@ -1,8 +0,0 @@
-"""assurance-cli — folder checks anyone can run without I-Ops.
-
-Shared filesystem I/O (`paths`, `profile`, `gather`) lives in this package so `assurance-mcp` can
-import it instead of duplicating the profiler. MCP depends on this package for gathering only; the
-CLI does not depend on MCP. Two copies of the profiler is how they disagree.
-"""
-
-__version__ = "0.1.0"