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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assurance-cli
-Version: 0.2.1
+Version: 0.2.2
 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
+Requires-Dist: assurance-core>=0.3.2
 Requires-Dist: openpyxl>=3.1
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
@@ -107,12 +107,25 @@ assurance check ~/thesis-data --against-baseline
 
 | | |
 |---|---|
-| `0` | ran, no gap — or not asked to fail on one |
-| `1` | a finding: a gap with `--fail-on-gap`, or a baseline that no longer holds |
-| `2` | could not run: bad path, unreadable list, unparseable JSON |
+| `0` | it checked, and either found no gap or wasn't asked to fail on one |
+| `1` | a finding: a gap with `--fail-on-gap`, a stale baseline, or **nothing it could check** |
+| `2` | could not run: bad path, unreadable list, unparseable JSON, a table where keys were expected |
+
+**"I couldn't check this" exits 1, not 0.** A folder whose filenames it can't parse must not look
+like a folder it checked and found whole.
 
 Diagnostics go to **stderr**, results to **stdout**, so `--json` stays pipeable.
 
+## It expects your files, not tidy ones
+
+- **Excel exports work.** UTF-8 BOM and CRLF are handled; a BOM used to glue itself to your first
+  key and report it as missing *and* unexpected in the same sentence
+- **Spaces, unicode and month words in filenames** — `Inventory Report August 2024.csv` parses
+- **`.xlsx`, and nested subfolders**
+- **A piped CSV is refused, not misread.** It names the column-picking command instead of quietly
+  admitting your header row as a key
+- **When it can't work out a series it says so**, rather than reporting an empty check as a pass
+
 ## Use it for
 
 | | expected | found |

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

@@ -80,12 +80,25 @@ assurance check ~/thesis-data --against-baseline
 
 | | |
 |---|---|
-| `0` | ran, no gap — or not asked to fail on one |
-| `1` | a finding: a gap with `--fail-on-gap`, or a baseline that no longer holds |
-| `2` | could not run: bad path, unreadable list, unparseable JSON |
+| `0` | it checked, and either found no gap or wasn't asked to fail on one |
+| `1` | a finding: a gap with `--fail-on-gap`, a stale baseline, or **nothing it could check** |
+| `2` | could not run: bad path, unreadable list, unparseable JSON, a table where keys were expected |
+
+**"I couldn't check this" exits 1, not 0.** A folder whose filenames it can't parse must not look
+like a folder it checked and found whole.
 
 Diagnostics go to **stderr**, results to **stdout**, so `--json` stays pipeable.
 
+## It expects your files, not tidy ones
+
+- **Excel exports work.** UTF-8 BOM and CRLF are handled; a BOM used to glue itself to your first
+  key and report it as missing *and* unexpected in the same sentence
+- **Spaces, unicode and month words in filenames** — `Inventory Report August 2024.csv` parses
+- **`.xlsx`, and nested subfolders**
+- **A piped CSV is refused, not misread.** It names the column-picking command instead of quietly
+  admitting your header row as a key
+- **When it can't work out a series it says so**, rather than reporting an empty check as a pass
+
 ## Use it for
 
 | | expected | found |

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

@@ -136,7 +136,12 @@ def _has_findings(payload: dict[str, Any]) -> bool:
     if payload.get("baseline") and not payload["baseline"].get("ok", True):
         return True
     coverage = payload.get("coverage") or payload
-    return bool(coverage.get("error"))
+    if coverage.get("error"):
+        return True
+    # "I could not work out what to check" is a finding, not a success. Exiting 0 here made a folder
+    # whose filenames we cannot parse indistinguishable, to a CI job, from a folder we checked and
+    # found whole — which is the one thing this tool exists not to do.
+    return bool((coverage.get("coverage") or {}).get("undetermined"))
 
 
 def _format_text(payload: dict[str, Any]) -> str:

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

@@ -73,7 +73,7 @@ def check_coverage(
             "complete": False,
             "derivation": "",
             "coverage": _coverage_to_dict(
-                Coverage(scope_label=f"items in {root.name}", expected=[])
+                Coverage(scope_label=f"items in {root.name}", expected=[], undetermined=_UNDETERMINED)
             ),
         }
 
@@ -88,7 +88,7 @@ def check_coverage(
             "complete": False,
             "derivation": "",
             "coverage": _coverage_to_dict(
-                Coverage(scope_label=f"items in {root.name}", expected=[])
+                Coverage(scope_label=f"items in {root.name}", expected=[], undetermined=_UNDETERMINED)
             ),
         }
 
@@ -122,7 +122,7 @@ def check_coverage(
             "complete": False,
             "derivation": "",
             "coverage": _coverage_to_dict(
-                Coverage(scope_label=f"items in {root.name}", expected=[])
+                Coverage(scope_label=f"items in {root.name}", expected=[], undetermined=_UNDETERMINED)
             ),
         }
 
@@ -264,13 +264,21 @@ def _unit_for_kind(kind: SeriesKind) -> str:
     }[kind]
 
 
+_UNDETERMINED = "no dated or numbered series could be read from these filenames"
+"""Why nothing was checked. Carried INTO the coverage record, not just the wrapper around it.
+
+Until 0.2.2 these paths emitted an empty `Coverage`, whose `complete` is True by the arithmetic —
+nothing was required, so nothing is missing. So the payload carried `complete: false` at the top and
+`complete: true` one level down, and an integrator reading either one was reading a real field."""
+
+
 def _error_result(root: Path, message: str) -> dict[str, Any]:
     return {
         "folder": str(root),
         "summary": message,
         "complete": False,
         "derivation": "",
-        "coverage": _coverage_to_dict(Coverage(scope_label=f"items in {root.name}", expected=[])),
+        "coverage": _coverage_to_dict(Coverage(scope_label=f"items in {root.name}", expected=[], undetermined=_UNDETERMINED)),
         "error": message,
     }
 
@@ -290,6 +298,7 @@ def _coverage_to_dict(cov: Coverage) -> dict[str, Any]:
         "unreadable": dict(cov.unreadable),
         "unauthorized": dict(cov.unauthorized),
         "truncated": cov.truncated,
+        "undetermined": cov.undetermined,
     }
 
 

{assurance_cli-0.2.1 → assurance_cli-0.2.2}/assurance_cli/setdiff.py

@@ -45,7 +45,11 @@ def read_keys(spec: str | None, *, label: str) -> list[str]:
         if candidate.exists():
             if candidate.is_dir():
                 raise KeySpecError(f"{label}: {spec} is a directory, not a list of keys")
-            text = candidate.read_text(encoding="utf-8")
+            # `utf-8-sig`, not `utf-8`. Excel writes CSV and TXT with a byte-order mark by default,
+            # and reading it as plain utf-8 glues U+FEFF to the FIRST key — so `doc-1` was reported
+            # as missing AND as unexpected in the same sentence, which is a confidently wrong answer
+            # produced by the most common export path there is.
+            text = candidate.read_text(encoding="utf-8-sig")
 
     if text is None:
         return _dedupe(part.strip() for part in spec.split(","))
@@ -64,11 +68,38 @@ def _parse(text: str, *, label: str) -> list[str]:
         return _keys_from_json(payload, label=label)
     # A full-line comment is dropped; a `#` inside a key is part of the key, because guessing which
     # is which would silently change someone's denominator.
-    return [
+    lines = [
         line.strip()
         for line in stripped.splitlines()
         if line.strip() and not line.lstrip().startswith("#")
     ]
+    _refuse_a_table(lines, label=label)
+    return lines
+
+
+def _refuse_a_table(lines: list[str], *, label: str) -> None:
+    """A delimited table is not a list of keys, and reading it as one is silent nonsense.
+
+    Piping a CSV is the obvious thing to try — it is what people have. Read line by line it produced
+    `0 of 3 — also present and not expected: doc_id,score, doc-1,0.9, doc-2,0.8`: a header row and
+    two score columns admitted as keys, and a confident zero. We cannot pick the column for you, so
+    this says which command does.
+
+    Deliberately narrow, because a key may legitimately contain a comma: it fires only when EVERY
+    line carries the SAME delimiter the SAME number of times, which is a table and not a coincidence.
+    """
+    if len(lines) < 2:
+        return
+    for delimiter, flag in (("\t", "-f1"), (",", "-d, -f1")):
+        counts = {line.count(delimiter) for line in lines}
+        if len(counts) == 1 and counts.pop() >= 1:
+            name = "tab" if delimiter == "\t" else "comma"
+            raise KeySpecError(
+                f"{label}: this looks like a {name}-delimited table, not a list of keys — every "
+                f"line has the same number of {name}s. Reading it line by line would admit the "
+                f"header and every other column as keys. Pick the column you mean, e.g. "
+                f"`cut {flag} file | assurance diff ... --{label.lstrip('-')} -`, or pass JSON."
+            )
 
 
 def _keys_from_json(payload: Any, *, label: str) -> list[str]:
@@ -106,7 +137,9 @@ def _dedupe(values: Any) -> list[str]:
     seen: set[str] = set()
     out: list[str] = []
     for value in values:
-        value = str(value).strip()
+        # A BOM can still arrive from stdin, where there is no decode step to strip it, and inside a
+        # JSON string. Strip it per key too: a stray U+FEFF changes what a key IS.
+        value = str(value).replace("\ufeff", "").strip()
         if value and value not in seen:
             seen.add(value)
             out.append(value)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assurance-cli
-Version: 0.2.1
+Version: 0.2.2
 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
+Requires-Dist: assurance-core>=0.3.2
 Requires-Dist: openpyxl>=3.1
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
@@ -107,12 +107,25 @@ assurance check ~/thesis-data --against-baseline
 
 | | |
 |---|---|
-| `0` | ran, no gap — or not asked to fail on one |
-| `1` | a finding: a gap with `--fail-on-gap`, or a baseline that no longer holds |
-| `2` | could not run: bad path, unreadable list, unparseable JSON |
+| `0` | it checked, and either found no gap or wasn't asked to fail on one |
+| `1` | a finding: a gap with `--fail-on-gap`, a stale baseline, or **nothing it could check** |
+| `2` | could not run: bad path, unreadable list, unparseable JSON, a table where keys were expected |
+
+**"I couldn't check this" exits 1, not 0.** A folder whose filenames it can't parse must not look
+like a folder it checked and found whole.
 
 Diagnostics go to **stderr**, results to **stdout**, so `--json` stays pipeable.
 
+## It expects your files, not tidy ones
+
+- **Excel exports work.** UTF-8 BOM and CRLF are handled; a BOM used to glue itself to your first
+  key and report it as missing *and* unexpected in the same sentence
+- **Spaces, unicode and month words in filenames** — `Inventory Report August 2024.csv` parses
+- **`.xlsx`, and nested subfolders**
+- **A piped CSV is refused, not misread.** It names the column-picking command instead of quietly
+  admitting your header row as a key
+- **When it can't work out a series it says so**, rather than reporting an empty check as a pass
+
 ## Use it for
 
 | | expected | found |

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

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

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

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "assurance-cli"
-version = "0.2.1"
+version = "0.2.2"
 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",
+  "assurance-core>=0.3.2",
   "openpyxl>=3.1",
 ]
 keywords = ["cli", "ai-agents", "governance", "auditing", "assurance", "reproducibility"]

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

@@ -123,3 +123,34 @@ def test_mixed_series_folder_reports_none(tmp_path: Path):
         (root / name).write_text("v\n1\n", encoding="utf-8")
     result = check_coverage(str(root))
     assert "No dated or numbered series detected" in result["summary"]
+
+
+# --- "I could not check" must not exit like "I checked and it was fine" ---------------------------
+
+
+def test_a_folder_with_no_readable_series_is_a_finding(tmp_path: Path) -> None:
+    """Exit 0 here made an unparseable folder indistinguishable, to a CI job, from a whole one."""
+    for name in ("15.01.2024 shipment.csv", "Jan-24 summary.csv", "20240115_dump.csv"):
+        (tmp_path / name).write_text("a,b\n1,2\n", encoding="utf-8")
+
+    assert main(["check", str(tmp_path)]) == 1
+
+
+def test_the_nested_record_agrees_with_the_wrapper(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """The payload carried `complete: false` at the top and `complete: true` one level down, and an
+    integrator reading either one was reading a real field."""
+    (tmp_path / "Jan-24 summary.csv").write_text("a,b\n1,2\n", encoding="utf-8")
+
+    main(["check", str(tmp_path), "--json"])
+    payload = json.loads(capsys.readouterr().out)["coverage"]
+
+    assert payload["complete"] is False
+    assert payload["coverage"]["complete"] is False
+    assert payload["coverage"]["undetermined"]
+
+
+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

{assurance_cli-0.2.1 → assurance_cli-0.2.2}/tests/test_setdiff.py

@@ -150,3 +150,89 @@ def test_an_error_is_printed_rather_than_swallowed(capsys: pytest.CaptureFixture
     captured = capsys.readouterr()
     assert captured.out.strip() == ""
     assert "folder does not exist" in captured.err
+
+
+# --- what an outsider's files actually look like --------------------------------------------------
+#
+# From the 2026-08-29 smoke test against fixtures nobody here designed against: Excel exports,
+# filenames with spaces, month words, six-digit purchase orders. Most of it worked. This did not.
+
+
+def test_a_byte_order_mark_does_not_change_what_a_key_is(tmp_path: Path) -> None:
+    """Excel writes CSV and TXT with a BOM by default. Read as plain utf-8 it glues U+FEFF to the
+    FIRST key, so `doc-1` came back reported as missing AND as unexpected in one sentence — a
+    confidently wrong answer, from the most common export path there is."""
+    listing = tmp_path / "keys.txt"
+    listing.write_bytes(b"\xef\xbb\xbfdoc-1\r\ndoc-2\r\ndoc-3\r\n")
+
+    assert read_keys(str(listing), label="--expected") == ["doc-1", "doc-2", "doc-3"]
+
+
+def test_a_bom_in_a_json_export_is_stripped_too(tmp_path: Path) -> None:
+    listing = tmp_path / "found.json"
+    listing.write_bytes(b'\xef\xbb\xbf["doc-1", "doc-2"]')
+
+    assert read_keys(str(listing), label="--found") == ["doc-1", "doc-2"]
+
+
+def test_the_bom_case_end_to_end_reports_one_gap_not_two_wrong_ones(tmp_path: Path) -> None:
+    listing = tmp_path / "keys.txt"
+    listing.write_bytes(b"\xef\xbb\xbfdoc-1\r\ndoc-2\r\ndoc-3\r\n")
+
+    payload = diff_sets(str(listing), "doc-1,doc-2")
+
+    assert payload["read"] == 2
+    assert [entry["key"] for entry in payload["missing"]] == ["doc-3"]
+    assert payload["unexpected"] == []
+
+
+def test_crlf_line_endings_do_not_become_part_of_the_key(tmp_path: Path) -> None:
+    listing = tmp_path / "keys.txt"
+    listing.write_bytes(b"doc-1\r\ndoc-2\r\n")
+
+    assert read_keys(str(listing), label="--expected") == ["doc-1", "doc-2"]
+
+
+def test_a_bom_arriving_on_stdin_is_stripped(monkeypatch: pytest.MonkeyPatch) -> None:
+    """`cat export.txt | assurance diff --found -` has no decode step to strip a BOM: `sys.stdin`
+    is already decoded, by the locale's plain utf-8. The README documents piping, so this path is
+    real and needs the per-key strip that `utf-8-sig` cannot reach."""
+    import io
+
+    monkeypatch.setattr("sys.stdin", io.StringIO("doc-1\ndoc-2\n"))
+
+    assert read_keys("-", label="--found") == ["doc-1", "doc-2"]
+
+
+def test_a_piped_csv_is_refused_rather_than_read_as_keys(tmp_path: Path) -> None:
+    """Piping a CSV is the obvious thing to try. Read line by line it produced a confident `0 of 3`
+    with the header row and two score columns admitted as keys."""
+    listing = tmp_path / "found.csv"
+    listing.write_text("doc_id,score\ndoc-1,0.9\ndoc-2,0.8\n", encoding="utf-8")
+
+    with pytest.raises(KeySpecError, match="comma-delimited table"):
+        read_keys(str(listing), label="--found")
+
+
+def test_the_refusal_names_the_command_that_fixes_it(tmp_path: Path) -> None:
+    listing = tmp_path / "found.tsv"
+    listing.write_text("doc_id\tscore\ndoc-1\t0.9\n", encoding="utf-8")
+
+    with pytest.raises(KeySpecError, match=r"cut -f1"):
+        read_keys(str(listing), label="--found")
+
+
+def test_a_key_that_merely_contains_a_comma_is_still_a_key(tmp_path: Path) -> None:
+    """The guard fires only when EVERY line has the SAME delimiter count — a table, not a
+    coincidence. A false refusal blocks a legitimate user, so it stays narrow."""
+    listing = tmp_path / "keys.txt"
+    listing.write_text("Smith, John\nDoe, Jane\nplain-key\n", encoding="utf-8")
+
+    assert read_keys(str(listing), label="--expected") == ["Smith, John", "Doe, Jane", "plain-key"]
+
+
+def test_a_single_line_is_never_a_table(tmp_path: Path) -> None:
+    listing = tmp_path / "keys.txt"
+    listing.write_text("a,b,c\n", encoding="utf-8")
+
+    assert read_keys(str(listing), label="--expected") == ["a,b,c"]