assurance-cli 0.2.3__tar.gz → 0.3.1__tar.gz

{assurance_cli-0.2.3 → assurance_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assurance-cli
-Version: 0.2.3
+Version: 0.3.1
 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.3
+Requires-Dist: assurance-core>=0.7
 Requires-Dist: openpyxl>=3.1
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
@@ -99,6 +99,14 @@ 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_cli-0.2.3 → assurance_cli-0.3.1}/README.md

@@ -72,6 +72,14 @@ 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_cli-0.2.3 → assurance_cli-0.3.1}/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.3 → assurance_cli-0.3.1}/assurance_cli/setdiff.py

@@ -120,19 +120,40 @@ def _keys_from_json(payload: Any, *, label: str) -> list[str]:
         if isinstance(entry, str):
             keys.append(entry)
         elif isinstance(entry, dict):
-            for field in ("key", "id", "name", "path"):
-                if isinstance(entry.get(field), str):
-                    keys.append(entry[field])
-                    break
-            else:
+            found = _identifier(entry)
+            if found is None:
                 raise KeySpecError(
-                    f"{label}: entry {index} is an object with no key/id/name/path field"
+                    f"{label}: entry {index} is an object with none of {', '.join(_ID_FIELDS)}, "
+                    "at the top level or under 'metadata'"
                 )
+            keys.append(found)
         else:
             raise KeySpecError(f"{label}: entry {index} is {type(entry).__name__}, not a key")
     return keys
 
 
+# What a chunk record from a vector store calls its parent document. `document`/`doc`/`source`
+# were added in 0.3.1 so a retrieval payload works without being reshaped first: chunks are what a
+# retriever returns, documents are what a scope is declared in, and the de-duplication below turns
+# five chunks of one document into one document covered. Diffing chunks directly is the mistake that
+# makes a coverage record report a gap nobody can ever close.
+_ID_FIELDS = ("key", "id", "name", "path", "document", "doc", "source", "document_id", "doc_id")
+
+
+def _identifier(entry: dict[str, Any]) -> str | None:
+    for field in _ID_FIELDS:
+        value = entry.get(field)
+        if isinstance(value, str) and value:
+            return value
+    metadata = entry.get("metadata")
+    if isinstance(metadata, dict):
+        for field in _ID_FIELDS:
+            value = metadata.get(field)
+            if isinstance(value, str) and value:
+                return value
+    return None
+
+
 def _dedupe(values: Any) -> list[str]:
     seen: set[str] = set()
     out: list[str] = []

{assurance_cli-0.2.3 → assurance_cli-0.3.1}/assurance_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assurance-cli
-Version: 0.2.3
+Version: 0.3.1
 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.3
+Requires-Dist: assurance-core>=0.7
 Requires-Dist: openpyxl>=3.1
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
@@ -99,6 +99,14 @@ 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_cli-0.2.3 → assurance_cli-0.3.1}/assurance_cli.egg-info/requires.txt

@@ -1,4 +1,4 @@
-assurance-core>=0.3.3
+assurance-core>=0.7
 openpyxl>=3.1
 
 [dev]

{assurance_cli-0.2.3 → assurance_cli-0.3.1}/pyproject.toml

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

{assurance_cli-0.2.3 → assurance_cli-0.3.1}/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.2.3 → assurance_cli-0.3.1}/tests/test_setdiff.py

@@ -81,7 +81,7 @@ def test_an_object_entry_with_no_identifying_field_is_refused(tmp_path: Path) ->
     listing = tmp_path / "found.json"
     listing.write_text('[{"score": 0.9}]', encoding="utf-8")
 
-    with pytest.raises(KeySpecError, match="no key/id/name/path"):
+    with pytest.raises(KeySpecError, match="none of"):
         read_keys(str(listing), label="--found")
 
 
@@ -236,3 +236,48 @@ def test_a_single_line_is_never_a_table(tmp_path: Path) -> None:
     listing.write_text("a,b,c\n", encoding="utf-8")
 
     assert read_keys(str(listing), label="--expected") == ["a,b,c"]
+
+
+# --- a chunk payload from a vector store ---------------------------------------------------------
+#
+# Added 0.3.1 after building a real retrieval pipeline. A retriever returns chunks with the parent
+# document under `source` or `metadata.source`; a scope is declared in documents. Requiring the
+# caller to reshape that first is friction with no honesty benefit, and the de-duplication is what
+# turns five chunks of one document into one document covered.
+
+
+def test_a_vector_store_payload_is_read_without_reshaping(tmp_path: Path) -> None:
+    listing = tmp_path / "chunks.json"
+    listing.write_text(json.dumps([
+        {"text": "...", "score": 0.84, "metadata": {"source": "acme/msa-2023.md"}},
+        {"text": "...", "score": 0.77, "metadata": {"source": "acme/msa-2023.md"}},
+        {"text": "...", "score": 0.75, "metadata": {"source": "acme/sla-exhibit-b.md"}},
+    ]), encoding="utf-8")
+
+    assert read_keys(str(listing), label="--found") == ["acme/msa-2023.md", "acme/sla-exhibit-b.md"]
+
+
+@pytest.mark.parametrize("field", ["document", "doc", "source", "document_id", "doc_id"])
+def test_the_common_parent_document_fields_are_read(tmp_path: Path, field: str) -> None:
+    listing = tmp_path / "chunks.json"
+    listing.write_text(json.dumps([{field: "acme/msa-2023.md", "text": "..."}]), encoding="utf-8")
+
+    assert read_keys(str(listing), label="--found") == ["acme/msa-2023.md"]
+
+
+def test_five_chunks_from_two_documents_are_two_keys(tmp_path: Path) -> None:
+    """Five chunks of one document is one document covered, not five."""
+    listing = tmp_path / "chunks.json"
+    listing.write_text(json.dumps(
+        [{"source": "a.md"}] * 4 + [{"source": "b.md"}]), encoding="utf-8")
+
+    assert read_keys(str(listing), label="--found") == ["a.md", "b.md"]
+
+
+def test_a_chunk_with_no_identifying_field_still_refuses(tmp_path: Path) -> None:
+    """Widening the accepted fields must not turn into guessing at somebody's schema."""
+    listing = tmp_path / "chunks.json"
+    listing.write_text(json.dumps([{"text": "...", "score": 0.9}]), encoding="utf-8")
+
+    with pytest.raises(KeySpecError, match="none of"):
+        read_keys(str(listing), label="--found")