assurance-cli 0.1.0__tar.gz

assurance_cli-0.1.0/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions. Notwithstanding
+      the above, nothing herein shall supersede or modify the terms of any
+      separate license agreement you may have executed with Licensor regarding
+      such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 I-Ops Operations Intelligence, LLC
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

assurance_cli-0.1.0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: assurance-cli
+Version: 0.1.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
+Project-URL: Homepage, https://i-ops.dev
+Project-URL: Source, https://github.com/i-ops-hq/assurance-cli
+Keywords: cli,ai-agents,governance,auditing,assurance,reproducibility
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: assurance-core>=0.2
+Requires-Dist: openpyxl>=3.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# assurance-cli
+
+Command-line assurance checks over a folder — coverage gaps, baseline staleness, and machine-readable output for CI.
+
+```bash
+pip install assurance-cli
+assurance check ~/data
+assurance init ~/thesis-data
+assurance check ~/thesis-data --against-baseline
+```
+
+See `assurance_core` for the pure arithmetic; this package owns all filesystem I/O.

assurance_cli-0.1.0/README.md

@@ -0,0 +1,12 @@
+# assurance-cli
+
+Command-line assurance checks over a folder — coverage gaps, baseline staleness, and machine-readable output for CI.
+
+```bash
+pip install assurance-cli
+assurance check ~/data
+assurance init ~/thesis-data
+assurance check ~/thesis-data --against-baseline
+```
+
+See `assurance_core` for the pure arithmetic; this package owns all filesystem I/O.

assurance_cli-0.1.0/assurance_cli/__init__.py

@@ -0,0 +1,8 @@
+"""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"

assurance_cli-0.1.0/assurance_cli/__main__.py

@@ -0,0 +1,4 @@
+from assurance_cli.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

assurance_cli-0.1.0/assurance_cli/baseline.py

@@ -0,0 +1,120 @@
+"""Baseline file — the only thing this tool may write."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from assurance_cli.paths import resolve_folder, resolve_inside
+from assurance_cli.profile import TABULAR_SUFFIXES, file_sha256, profile_file
+
+BASELINE_NAME = ".assurance.json"
+BASELINE_VERSION = 1
+
+
+def init_baseline(folder: str, *, update: bool = False) -> dict[str, Any]:
+    """Write `.assurance.json` with hashes, sizes, mtimes, and computed totals."""
+    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"}
+
+    entries: dict[str, Any] = {}
+    for file_path in sorted(root.rglob("*")):
+        if not file_path.is_file():
+            continue
+        if file_path.name == BASELINE_NAME:
+            continue
+        if file_path.suffix.lower() not in TABULAR_SUFFIXES:
+            continue
+        try:
+            rel = str(file_path.relative_to(root))
+            resolve_inside(root, rel)
+        except Exception:
+            continue
+        stat = file_path.stat()
+        profile = profile_file(file_path)
+        entries[rel] = {
+            "sha256": file_sha256(file_path),
+            "size": stat.st_size,
+            "mtime": stat.st_mtime,
+            "profile": profile,
+        }
+
+    payload = {
+        "version": BASELINE_VERSION,
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "folder": str(root),
+        "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)}
+
+
+def check_against_baseline(folder: str) -> dict[str, Any]:
+    """Compare the folder to its baseline — each file against its own entry only."""
+    root = resolve_folder(folder)
+    path = root / BASELINE_NAME
+    if not path.is_file():
+        return {
+            "ok": False,
+            "summary": f"No baseline at {BASELINE_NAME}. Run `assurance init` first.",
+            "changed": [],
+            "vanished": [],
+            "new": [],
+        }
+
+    baseline = json.loads(path.read_text(encoding="utf-8"))
+    recorded: dict[str, Any] = baseline.get("files") or {}
+    findings: list[dict[str, Any]] = []
+    changed: list[str] = []
+    vanished: list[str] = []
+    new_files: list[str] = []
+
+    for rel, entry in sorted(recorded.items()):
+        file_path = root / rel
+        if not file_path.is_file():
+            vanished.append(rel)
+            findings.append({"file": rel, "status": "vanished"})
+            continue
+        stat = file_path.stat()
+        current_hash = file_sha256(file_path)
+        current_profile = profile_file(file_path)
+        if (
+            current_hash != entry.get("sha256")
+            or stat.st_size != entry.get("size")
+            or abs(stat.st_mtime - float(entry.get("mtime", 0))) > 0.001
+            or current_profile != entry.get("profile")
+        ):
+            changed.append(rel)
+            findings.append({"file": rel, "status": "changed"})
+
+    for file_path in sorted(root.rglob("*")):
+        if not file_path.is_file() or file_path.name == BASELINE_NAME:
+            continue
+        if file_path.suffix.lower() not in TABULAR_SUFFIXES:
+            continue
+        rel = str(file_path.relative_to(root))
+        if rel not in recorded:
+            new_files.append(rel)
+            findings.append({"file": rel, "status": "new"})
+
+    parts: list[str] = []
+    if changed:
+        parts.append(f"{len(changed)} file(s) changed since the baseline")
+    if vanished:
+        parts.append(f"{len(vanished)} vanished")
+    if new_files:
+        parts.append(f"{len(new_files)} new (not in baseline)")
+    summary = "; ".join(parts) if parts else "All baseline files match."
+
+    return {
+        "ok": not findings,
+        "summary": summary,
+        "changed": changed,
+        "vanished": vanished,
+        "new": new_files,
+        "findings": findings,
+    }

assurance_cli-0.1.0/assurance_cli/cli.py

@@ -0,0 +1,106 @@
+"""Command-line entry for assurance checks."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from assurance_cli.baseline import check_against_baseline, init_baseline
+from assurance_cli.gather import check_coverage
+from assurance_cli.paths import PathEscapeError
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="assurance", description="Folder assurance checks — arithmetic, not models.")
+    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.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")
+    check_parser.add_argument("--to", dest="to_point", metavar="TO")
+    check_parser.add_argument("--against-baseline", action="store_true")
+    check_parser.add_argument("--json", action="store_true", dest="as_json")
+    check_parser.add_argument("--fail-on-gap", action="store_true")
+    check_parser.add_argument("period_range", nargs="?", help="Optional period range (monthly)")
+
+    args = parser.parse_args(argv)
+
+    try:
+        if args.command == "init":
+            result = init_baseline(args.folder, update=args.update)
+            return _emit(result, args, finding=not result.get("written") and not args.update)
+        return _run_check(args)
+    except (PathEscapeError, FileNotFoundError, NotADirectoryError) as exc:
+        return _emit({"error": str(exc)}, args if args.command == "check" else argparse.Namespace(as_json=False), code=2)
+
+
+def _run_check(args: argparse.Namespace) -> int:
+    output: dict[str, Any] = {}
+    findings = False
+
+    if args.against_baseline:
+        baseline = check_against_baseline(args.folder)
+        output["baseline"] = baseline
+        findings = findings or not baseline.get("ok", True)
+
+    coverage = check_coverage(
+        args.folder,
+        getattr(args, "period_range", None),
+        expect=args.expect,
+        from_point=args.from_point,
+        to_point=args.to_point,
+    )
+    output["coverage"] = coverage
+    if coverage.get("error"):
+        return _emit(output, args, code=2)
+
+    if args.against_baseline and not output.get("baseline", {}).get("ok", True):
+        findings = True
+    if not coverage.get("complete", False) and args.fail_on_gap:
+        findings = True
+
+    return _emit(output, args, finding=findings)
+
+
+def _emit(payload: dict[str, Any], args: argparse.Namespace, *, code: int = 0, finding: bool = False) -> int:
+    if getattr(args, "as_json", False):
+        print(json.dumps(payload, indent=2))
+    else:
+        print(_format_text(payload))
+    if code:
+        return code
+    if finding:
+        return 1
+    if _has_findings(payload):
+        return 1
+    return 0
+
+
+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"))
+
+
+def _format_text(payload: dict[str, Any]) -> str:
+    lines: list[str] = []
+    if "baseline" in payload:
+        lines.append(payload["baseline"].get("summary", ""))
+    coverage = payload.get("coverage") or payload
+    if coverage.get("summary"):
+        lines.append(coverage["summary"])
+    if coverage.get("derivation") and coverage["derivation"] not in (coverage.get("summary") or ""):
+        lines.append(coverage["derivation"])
+    return "\n".join(line for line in lines if line)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

assurance_cli-0.1.0/assurance_cli/gather.py

@@ -0,0 +1,328 @@
+"""Gather facts from a folder, then hand them to assurance-core for verdicts."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from assurance_core.coverage import Coverage, EvidenceRef, Expectation
+from assurance_core.report_period import Period, parse_period_range
+from assurance_core.sequence import (
+    DetectedSeries,
+    SeriesKind,
+    detect_series,
+    enumerate_between,
+    explicit_derivation,
+    inference_derivation,
+    parse_point,
+    point_from_filename,
+    point_key,
+)
+from assurance_core.staleness import Finding, Verdict, compare
+
+from assurance_cli.paths import PathEscapeError, resolve_folder, resolve_inside
+from assurance_cli.profile import TABULAR_SUFFIXES, profile_file
+
+MAX_PERIODS = 36
+MAX_NUMBERED = 500
+MIN_FILES_TO_INFER = 3
+
+_KIND_FROM_NAME = {
+    "monthly": SeriesKind.MONTHLY,
+    "quarterly": SeriesKind.QUARTERLY,
+    "weekly": SeriesKind.WEEKLY,
+    "daily": SeriesKind.DAILY,
+    "numbered": SeriesKind.NUMBERED,
+}
+
+
+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)
+    keys = sorted(by_key)
+    return {
+        "folder": str(root),
+        "periods": [
+            {
+                "key": key,
+                "label": _label_for_key(key, by_key[key][0].name),
+                "files": [str(path) for path in by_key[key]],
+            }
+            for key in keys
+        ],
+        "count": len(keys),
+    }
+
+
+def check_coverage(
+    folder: str,
+    period_range: str | None = None,
+    *,
+    expect: str | None = None,
+    from_point: str | None = None,
+    to_point: str | None = None,
+) -> 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)
+    if not by_key:
+        return {
+            "folder": str(root),
+            "summary": f"Nothing in {root.name} has a recognisable sequence in its name.",
+            "complete": False,
+            "derivation": "",
+            "coverage": _coverage_to_dict(
+                Coverage(scope_label=f"items in {root.name}", expected=[])
+            ),
+        }
+
+    filenames = [path.name for paths in by_key.values() for path in paths]
+    detected = detect_series(filenames)
+    kind = _resolve_kind(expect, detected)
+
+    if kind is None:
+        return {
+            "folder": str(root),
+            "summary": "No dated or numbered series detected.",
+            "complete": False,
+            "derivation": "",
+            "coverage": _coverage_to_dict(
+                Coverage(scope_label=f"items in {root.name}", expected=[])
+            ),
+        }
+
+    unit = _unit_for_kind(kind)
+    derivation = ""
+
+    if from_point and to_point:
+        start = parse_point(from_point, kind)
+        end = parse_point(to_point, kind)
+        if start is None or end is None:
+            return _error_result(root, "Could not parse --from / --to for the detected series kind.")
+        expected_keys = enumerate_between(start, end)
+        derivation = explicit_derivation(kind, point_key(start), point_key(end))  # type: ignore[arg-type]
+        scope = f"{unit} from {point_key(start)} to {point_key(end)} in {root.name}"  # type: ignore[arg-type]
+    elif period_range and kind is SeriesKind.MONTHLY:
+        available = sorted(p for p in (point_from_filename(n) for n in filenames) if isinstance(p, Period))
+        window = parse_period_range(period_range, available)  # type: ignore[arg-type]
+        if window is None:
+            return _error_result(root, f"Could not parse period range: {period_range!r}")
+        expected_keys = enumerate_between(window[0], window[1])
+        derivation = f"Range set by request: {period_range!r}."
+        scope = f"months from {window[0].label} to {window[1].label} in {root.name}"
+    elif detected is not None and len(detected.points) >= MIN_FILES_TO_INFER:
+        expected_keys = enumerate_between(detected.earliest, detected.latest)  # type: ignore[arg-type]
+        derivation = inference_derivation(detected)
+        scope = f"{unit} from {point_key(detected.earliest)} to {point_key(detected.latest)} in {root.name}"  # type: ignore[arg-type]
+    else:
+        return {
+            "folder": str(root),
+            "summary": "No dated or numbered series detected.",
+            "complete": False,
+            "derivation": "",
+            "coverage": _coverage_to_dict(
+                Coverage(scope_label=f"items in {root.name}", expected=[])
+            ),
+        }
+
+    truncated = ""
+    cap = MAX_NUMBERED if kind is SeriesKind.NUMBERED else MAX_PERIODS
+    if len(expected_keys) > cap:
+        truncated = f"stopped at {cap} {unit}"
+        expected_keys = expected_keys[-cap:]
+
+    cov = Coverage(scope_label=scope, truncated=truncated, derivation=derivation)
+    for key, label in expected_keys:
+        expectation = Expectation(key=key, label=label, why=derivation or f"in {scope}")
+        cov.expected.append(expectation)
+        candidates = by_key.get(key, [])
+
+        if not candidates:
+            cov.missing.append(expectation)
+            continue
+        if len(candidates) > 1:
+            cov.ambiguous[key] = [str(path) for path in candidates]
+            continue
+
+        path = candidates[0]
+        facts = profile_file(path)
+        if facts is None or facts.get("rows", 0) == 0:
+            cov.unreadable[key] = "could not be read as a table"
+            continue
+
+        cov.found[key] = EvidenceRef(key=key, path=str(path), reader="assurance-cli")
+
+    return {
+        "folder": str(root),
+        "summary": cov.summary(),
+        "complete": cov.complete,
+        "derivation": cov.derivation,
+        "coverage": _coverage_to_dict(cov),
+    }
+
+
+def check_staleness(
+    folder: str,
+    document: str,
+    source: str,
+    *,
+    recorded_facts: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Compare recorded figures to a freshly profiled source the caller names."""
+    root = resolve_folder(folder)
+    document_path = resolve_inside(root, document)
+    source_path = resolve_inside(root, source)
+
+    if not document_path.is_file():
+        return _finding_to_dict(
+            compare(
+                artifact_name=document_path.name,
+                artifact_path=str(document_path),
+                generated_at="",
+                source_name=source_path.name,
+                source_mtime=None,
+                recorded_facts=None,
+                current_facts=None,
+                uncheckable_reason=document_path.name,
+            )
+        )
+
+    if not source_path.is_file():
+        return _finding_to_dict(
+            compare(
+                artifact_name=document_path.name,
+                artifact_path=str(document_path),
+                generated_at="",
+                source_name=source_path.name,
+                source_mtime=None,
+                recorded_facts=recorded_facts,
+                current_facts=None,
+                source_gone=True,
+            )
+        )
+
+    recorded = recorded_facts if recorded_facts is not None else profile_file(document_path)
+    current = profile_file(source_path)
+    source_mtime = source_path.stat().st_mtime if source_path.exists() else None
+
+    finding = compare(
+        artifact_name=document_path.name,
+        artifact_path=str(document_path),
+        generated_at="",
+        source_name=source_path.name,
+        source_mtime=source_mtime,
+        recorded_facts=recorded,
+        current_facts=current,
+    )
+    return _finding_to_dict(finding)
+
+
+def _indexed_files(root: Path) -> dict[str, list[Path]]:
+    found: dict[str, list[Path]] = {}
+    for path in sorted(root.rglob("*")):
+        if not path.is_file() or path.suffix.lower() not in TABULAR_SUFFIXES:
+            continue
+        if path.name == ".assurance.json":
+            continue
+        try:
+            resolve_inside(root, str(path.relative_to(root)))
+        except PathEscapeError:
+            continue
+        point = point_from_filename(path.name)
+        if point is None:
+            continue
+        key = point_key(point)  # type: ignore[arg-type]
+        found.setdefault(key, []).append(path)
+    return found
+
+
+def _label_for_key(key: str, filename: str) -> str:
+    point = point_from_filename(filename)
+    if point is None:
+        return key
+    if isinstance(point, Period):
+        return point.label
+    return point.label
+
+
+def _resolve_kind(expect: str | None, detected: DetectedSeries | None) -> SeriesKind | None:
+    if expect:
+        return _KIND_FROM_NAME.get(expect.lower())
+    if detected is not None:
+        return detected.kind
+    return None
+
+
+def _unit_for_kind(kind: SeriesKind) -> str:
+    return {
+        SeriesKind.MONTHLY: "months",
+        SeriesKind.QUARTERLY: "quarters",
+        SeriesKind.WEEKLY: "weeks",
+        SeriesKind.DAILY: "days",
+        SeriesKind.NUMBERED: "runs",
+    }[kind]
+
+
+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=[])),
+        "error": message,
+    }
+
+
+def _coverage_to_dict(cov: Coverage) -> dict[str, Any]:
+    return {
+        "scope_label": cov.scope_label,
+        "read": cov.read,
+        "required": cov.required,
+        "complete": cov.complete,
+        "derivation": cov.derivation,
+        "expected": [_expectation(e) for e in cov.expected],
+        "found": {key: _evidence(ref) for key, ref in cov.found.items()},
+        "missing": [_expectation(e) for e in cov.missing],
+        "gone": dict(cov.gone),
+        "ambiguous": dict(cov.ambiguous),
+        "unreadable": dict(cov.unreadable),
+        "unauthorized": dict(cov.unauthorized),
+        "truncated": cov.truncated,
+    }
+
+
+def _expectation(exp: Expectation) -> dict[str, str]:
+    return {"key": exp.key, "label": exp.label, "why": exp.why}
+
+
+def _evidence(ref: EvidenceRef) -> dict[str, Any]:
+    return {
+        "key": ref.key,
+        "path": ref.path,
+        "reader": ref.reader,
+        "bytes": ref.bytes,
+        "sha256": ref.sha256,
+    }
+
+
+def _finding_to_dict(finding: Finding) -> dict[str, Any]:
+    return {
+        "verdict": finding.verdict.value,
+        "sentence": finding.sentence(),
+        "artifact_name": finding.artifact_name,
+        "artifact_path": finding.artifact_path,
+        "source_name": finding.source_name,
+        "source_modified_at": finding.source_modified_at,
+        "divergences": [
+            {
+                "measure": div.measure,
+                "claimed": div.claimed,
+                "current": div.current,
+                "delta": div.delta,
+            }
+            for div in finding.divergences
+        ],
+        "uncheckable": finding.verdict is Verdict.UNCHECKABLE,
+    }

assurance_cli-0.1.0/assurance_cli/paths.py

@@ -0,0 +1,42 @@
+"""Resolve caller paths and refuse escapes outside the named folder."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class PathEscapeError(ValueError):
+    """A path would read outside the folder the caller named."""
+
+
+def resolve_folder(folder: str) -> Path:
+    """Resolve and validate a folder the caller named."""
+    if not folder or not str(folder).strip():
+        raise PathEscapeError("folder is required")
+    root = Path(folder).expanduser()
+    if not root.exists():
+        raise FileNotFoundError(f"folder does not exist: {folder}")
+    if not root.is_dir():
+        raise NotADirectoryError(f"not a directory: {folder}")
+    return _real(root)
+
+
+def resolve_inside(root: Path, path: str) -> Path:
+    """Resolve `path` and require it stays inside `root`."""
+    if not path or not str(path).strip():
+        raise PathEscapeError("path is required")
+    root = _real(root)
+    candidate = Path(path).expanduser()
+    if not candidate.is_absolute():
+        candidate = root / candidate
+    resolved = _real(candidate)
+    if resolved != root and root not in resolved.parents:
+        raise PathEscapeError(f"path escapes the named folder: {path}")
+    return resolved
+
+
+def _real(path: Path) -> Path:
+    try:
+        return path.resolve(strict=False)
+    except OSError as exc:
+        raise PathEscapeError(f"cannot resolve path: {path}") from exc

assurance_cli-0.1.0/assurance_cli/profile.py

@@ -0,0 +1,95 @@
+"""Tabular profiling for coverage and staleness — CSV, TSV, and XLSX."""
+
+from __future__ import annotations
+
+import csv
+import hashlib
+from pathlib import Path
+
+TABULAR_SUFFIXES = {".csv", ".tsv", ".xlsx"}
+
+
+def profile_file(path: Path) -> dict | None:
+    """Return a facts-shaped dict compatible with `staleness.extract_measures`, or None."""
+    suffix = path.suffix.lower()
+    if suffix == ".xlsx":
+        return _profile_xlsx(path)
+    if suffix in {".csv", ".tsv"}:
+        return _profile_csv(path, delimiter="\t" if suffix == ".tsv" else ",")
+    return None
+
+
+def file_sha256(path: Path) -> str:
+    """Hash file contents, or empty string on failure."""
+    try:
+        digest = hashlib.sha256()
+        with path.open("rb") as handle:
+            for chunk in iter(lambda: handle.read(65536), b""):
+                digest.update(chunk)
+        return digest.hexdigest()
+    except OSError:
+        return ""
+
+
+def _profile_csv(path: Path, *, delimiter: str) -> dict | None:
+    try:
+        with path.open(newline="", encoding="utf-8") as handle:
+            reader = csv.DictReader(handle, delimiter=delimiter)
+            fieldnames = reader.fieldnames or []
+            rows = list(reader)
+    except (OSError, UnicodeDecodeError, csv.Error):
+        return None
+
+    if not fieldnames:
+        return {"rows": 0, "numeric": []}
+
+    return _facts_from_rows(fieldnames, rows)
+
+
+def _profile_xlsx(path: Path) -> dict | None:
+    try:
+        from openpyxl import load_workbook
+    except ImportError:
+        return None
+
+    try:
+        workbook = load_workbook(path, read_only=True, data_only=True)
+        sheet = workbook.active
+        rows_iter = sheet.iter_rows(values_only=True)
+        header = next(rows_iter, None)
+        if not header:
+            workbook.close()
+            return {"rows": 0, "numeric": []}
+        fieldnames = [str(cell) if cell is not None else "" for cell in header]
+        rows = [
+            {fieldnames[i]: ("" if value is None else value) for i, value in enumerate(row)}
+            for row in rows_iter
+        ]
+        workbook.close()
+    except (OSError, ValueError):
+        return None
+
+    return _facts_from_rows(fieldnames, rows)
+
+
+def _facts_from_rows(fieldnames: list[str], rows: list[dict]) -> dict:
+    numeric: list[dict[str, object]] = []
+    row_count = len(rows)
+    for column in fieldnames:
+        values: list[float] = []
+        for row in rows:
+            raw = str(row.get(column) or "").strip()
+            if not raw:
+                continue
+            cleaned = raw.replace(",", "").replace("$", "").replace("£", "").replace("€", "")
+            if cleaned.endswith("%"):
+                cleaned = cleaned[:-1]
+            try:
+                values.append(float(cleaned))
+            except ValueError:
+                values = []
+                break
+        if values and len(values) >= max(1, int(row_count * 0.8)):
+            numeric.append({"name": column, "total": sum(values)})
+
+    return {"rows": row_count, "numeric": numeric}

assurance_cli-0.1.0/assurance_cli.egg-info/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: assurance-cli
+Version: 0.1.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
+Project-URL: Homepage, https://i-ops.dev
+Project-URL: Source, https://github.com/i-ops-hq/assurance-cli
+Keywords: cli,ai-agents,governance,auditing,assurance,reproducibility
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: assurance-core>=0.2
+Requires-Dist: openpyxl>=3.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# assurance-cli
+
+Command-line assurance checks over a folder — coverage gaps, baseline staleness, and machine-readable output for CI.
+
+```bash
+pip install assurance-cli
+assurance check ~/data
+assurance init ~/thesis-data
+assurance check ~/thesis-data --against-baseline
+```
+
+See `assurance_core` for the pure arithmetic; this package owns all filesystem I/O.

assurance_cli-0.1.0/assurance_cli.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+assurance_cli/__init__.py
+assurance_cli/__main__.py
+assurance_cli/baseline.py
+assurance_cli/cli.py
+assurance_cli/gather.py
+assurance_cli/paths.py
+assurance_cli/profile.py
+assurance_cli.egg-info/PKG-INFO
+assurance_cli.egg-info/SOURCES.txt
+assurance_cli.egg-info/dependency_links.txt
+assurance_cli.egg-info/entry_points.txt
+assurance_cli.egg-info/requires.txt
+assurance_cli.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_read_only.py

assurance_cli-0.1.0/assurance_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

assurance_cli-0.1.0/assurance_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+assurance = assurance_cli.cli:main

assurance_cli-0.1.0/assurance_cli.egg-info/requires.txt

@@ -0,0 +1,5 @@
+assurance-core>=0.2
+openpyxl>=3.1
+
+[dev]
+pytest>=8.0

assurance_cli-0.1.0/assurance_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+assurance_cli

assurance_cli-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "assurance-cli"
+version = "0.1.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.2",
+  "openpyxl>=3.1",
+]
+keywords = ["cli", "ai-agents", "governance", "auditing", "assurance", "reproducibility"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.urls]
+Homepage = "https://i-ops.dev"
+Source = "https://github.com/i-ops-hq/assurance-cli"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.scripts]
+assurance = "assurance_cli.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["assurance_cli*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

assurance_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

assurance_cli-0.1.0/tests/test_cli.py

@@ -0,0 +1,125 @@
+"""CLI and gather tests."""
+
+from __future__ import annotations
+
+import csv
+import json
+from pathlib import Path
+
+import pytest
+
+from assurance_cli.baseline import BASELINE_NAME, check_against_baseline, init_baseline
+from assurance_cli.cli import main
+from assurance_cli.gather import check_coverage
+from assurance_cli.paths import PathEscapeError, resolve_inside
+
+
+@pytest.fixture
+def monthly_folder(tmp_path: Path) -> Path:
+    root = tmp_path / "reports"
+    root.mkdir()
+    for year in (2024, 2025):
+        for month in range(1, 13):
+            if (year, month) in {(2024, 3), (2025, 7)}:
+                continue
+            path = root / f"billing_{year}-{month:02d}.csv"
+            with path.open("w", newline="", encoding="utf-8") as handle:
+                writer = csv.writer(handle)
+                writer.writerow(["amount"])
+                writer.writerow([100 * month])
+    return root
+
+
+@pytest.fixture
+def numbered_folder(tmp_path: Path) -> Path:
+    root = tmp_path / "runs"
+    root.mkdir()
+    for n in range(1, 201):
+        if n in (47, 82):
+            continue
+        path = root / f"run_{n:03d}.csv"
+        path.write_text("value\n1\n", encoding="utf-8")
+    return root
+
+
+def test_check_coverage_reports_missing_months(monthly_folder: Path):
+    result = check_coverage(str(monthly_folder))
+    assert result["complete"] is False
+    assert "22 of 24" in result["summary"]
+    assert "March 2024" in result["summary"]
+    assert "July 2025" in result["summary"]
+    assert "Range inferred from filenames" in result["derivation"]
+
+
+def test_check_coverage_numbered_runs(numbered_folder: Path):
+    result = check_coverage(str(numbered_folder))
+    assert result["complete"] is False
+    assert "198 of 200" in result["summary"]
+    missing_keys = {item["key"] for item in result["coverage"]["missing"]}
+    assert missing_keys == {"run_047", "run_082"}
+
+
+def test_explicit_range(monthly_folder: Path):
+    result = check_coverage(
+        str(monthly_folder),
+        expect="monthly",
+        from_point="2024-04",
+        to_point="2024-06",
+    )
+    assert result["coverage"]["required"] == 3
+    assert result["complete"] is True
+
+
+def test_path_escape_refuses_parent_traversal(monthly_folder: Path):
+    with pytest.raises(PathEscapeError):
+        resolve_inside(monthly_folder, "../outside.csv")
+
+
+def test_baseline_init_and_detect_change(monthly_folder: Path):
+    init = init_baseline(str(monthly_folder))
+    assert init["written"] is True
+    assert (monthly_folder / BASELINE_NAME).is_file()
+
+    check = check_against_baseline(str(monthly_folder))
+    assert check["ok"] is True
+
+    target = next(monthly_folder.glob("billing_2024-01.csv"))
+    target.write_text("amount\n999\n", encoding="utf-8")
+    changed = check_against_baseline(str(monthly_folder))
+    assert changed["ok"] is False
+    assert "billing_2024-01.csv" in changed["changed"]
+
+
+def test_cli_exit_codes(monthly_folder: Path, numbered_folder: Path):
+    assert main(["check", str(monthly_folder)]) == 0
+    assert main(["check", str(monthly_folder), "--fail-on-gap"]) == 1
+    assert main(["check", "/no/such/folder"]) == 2
+
+
+def test_cli_json_output(monthly_folder: Path, capsys):
+    code = main(["check", str(monthly_folder), "--json"])
+    assert code == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert "coverage" in payload
+
+
+def test_counterfactual_complete_span_fails_when_month_removed(monthly_folder: Path, tmp_path: Path):
+    complete = tmp_path / "complete"
+    complete.mkdir()
+    for path in monthly_folder.glob("*.csv"):
+        (complete / path.name).write_text(path.read_text(encoding="utf-8"), encoding="utf-8")
+    (complete / "billing_2024-03.csv").write_text("amount\n300\n", encoding="utf-8")
+    (complete / "billing_2025-07.csv").write_text("amount\n700\n", encoding="utf-8")
+
+    assert check_coverage(str(complete))["complete"] is True
+    (complete / "billing_2024-03.csv").unlink()
+    assert check_coverage(str(complete))["complete"] is False
+
+
+def test_mixed_series_folder_reports_none(tmp_path: Path):
+    root = tmp_path / "mixed"
+    root.mkdir()
+    for name in ("2024-01.csv", "2024-02.csv", "2024-03.csv", "run_001.csv"):
+        (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"]

assurance_cli-0.1.0/tests/test_read_only.py

@@ -0,0 +1,34 @@
+"""CLI write gate — baseline is the only permitted write."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+PACKAGE = Path(__file__).resolve().parents[1] / "assurance_cli"
+BASELINE_MODULE = "baseline.py"
+
+
+def test_only_baseline_writes():
+    offenders: list[str] = []
+    for path in sorted(PACKAGE.glob("*.py")):
+        if path.name == BASELINE_MODULE:
+            continue
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+        offenders.extend(_forbidden_writes(path, tree))
+    assert not offenders, "unexpected writes outside baseline.py:\n" + "\n".join(offenders)
+
+
+def _forbidden_writes(path: Path, tree: ast.AST) -> list[str]:
+    hits: list[str] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute):
+            if node.func.attr in {"write_text", "write_bytes"}:
+                hits.append(f"{path.name}: calls .{node.func.attr}()")
+    return hits
+
+
+def test_baseline_write_counterfactual():
+    sample = 'path.write_text("x")\n'
+    tree = ast.parse(sample)
+    assert _forbidden_writes(Path("cli.py"), tree)