ciphergate-cli 0.14.0__tar.gz → 0.15.0__tar.gz

{ciphergate_cli-0.14.0 → ciphergate_cli-0.15.0}/CHANGELOG.md

@@ -6,6 +6,22 @@ versioning: [PEP 440](https://peps.python.org/pep-0440/) with SemVer meaning (pr
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-11-02
+
+JSON reports now include the next-step hints, so CI pipelines can act on them. The field is new;
+nothing existing changes.
+
+### Added
+
+- JSON reports (single-file and directory) include `next_steps`: the hints from the terminal
+  summary as `{"code", "message"}` pairs, empty for a successful run. The field is new and
+  optional to read; the schema names are unchanged.
+
+### Fixed
+
+- The `batch_empty` error for a directory with no recognised files now mentions
+  `--extension-format`.
+
 ## [0.14.0] - 2026-11-02
 
 Adds `--extension-format` for mixed directories and tests the optional NER detector against a
@@ -379,7 +395,8 @@ Pre-release (alpha). Licensed under Apache-2.0. Not a final release: the securit
 See `docs/limitations.md`. Deferred: optional NER/Presidio detectors, stdin/stdout streaming,
 directory processing, structured log parsers, key files, reversible token vault, lossy decoding.
 
-[Unreleased]: https://github.com/aashishkumar-tech/ciphergate/compare/v0.14.0...HEAD
+[Unreleased]: https://github.com/aashishkumar-tech/ciphergate/compare/v0.15.0...HEAD
+[0.15.0]: https://github.com/aashishkumar-tech/ciphergate/compare/v0.14.0...v0.15.0
 [0.14.0]: https://github.com/aashishkumar-tech/ciphergate/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/aashishkumar-tech/ciphergate/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/aashishkumar-tech/ciphergate/compare/v0.11.0...v0.12.0

{ciphergate_cli-0.14.0 → ciphergate_cli-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ciphergate-cli
-Version: 0.14.0
+Version: 0.15.0
 Summary: Local-first, environment- and destination-aware inspection and sanitization of logs and test datasets.
 Project-URL: Homepage, https://github.com/aashishkumar-tech/ciphergate
 Project-URL: Source, https://github.com/aashishkumar-tech/ciphergate
@@ -50,7 +50,7 @@ vendor ticket. CipherGate replaces that with a local, explainable, scriptable ga
 inspect  ->  plan  ->  sanitize --apply  ->  rescan
 ```
 
-> **Status: 0.14.0 (alpha).** No detector finds every sensitive value. A passing run means the
+> **Status: 0.15.0 (alpha).** No detector finds every sensitive value. A passing run means the
 > configured processing completed under the selected policy; it is **not** proof that the output
 > contains no sensitive information, and it is not a compliance (GDPR, HIPAA, PCI DSS, ...) or
 > anonymization guarantee. Policy templates must be reviewed before use.
@@ -89,6 +89,8 @@ inspect  ->  plan  ->  sanitize --apply  ->  rescan
   `--force`, input/output alias protection, input-change detection, cleanup on failure/Ctrl-C.
 - **Reports:** counts by category/detector/action/reason/rule, safe locations, effective context
   and its source, gates, key *status* (never key material), no raw values or fingerprints.
+  A failed run's report lists `next_steps` as `{"code", "message"}` pairs, the same hints the
+  terminal prints as `next:` lines, so CI can act on them.
 
 ## Install
 

{ciphergate_cli-0.14.0 → ciphergate_cli-0.15.0}/README.md

@@ -11,7 +11,7 @@ vendor ticket. CipherGate replaces that with a local, explainable, scriptable ga
 inspect  ->  plan  ->  sanitize --apply  ->  rescan
 ```
 
-> **Status: 0.14.0 (alpha).** No detector finds every sensitive value. A passing run means the
+> **Status: 0.15.0 (alpha).** No detector finds every sensitive value. A passing run means the
 > configured processing completed under the selected policy; it is **not** proof that the output
 > contains no sensitive information, and it is not a compliance (GDPR, HIPAA, PCI DSS, ...) or
 > anonymization guarantee. Policy templates must be reviewed before use.
@@ -50,6 +50,8 @@ inspect  ->  plan  ->  sanitize --apply  ->  rescan
   `--force`, input/output alias protection, input-change detection, cleanup on failure/Ctrl-C.
 - **Reports:** counts by category/detector/action/reason/rule, safe locations, effective context
   and its source, gates, key *status* (never key material), no raw values or fingerprints.
+  A failed run's report lists `next_steps` as `{"code", "message"}` pairs, the same hints the
+  terminal prints as `next:` lines, so CI can act on them.
 
 ## Install
 

{ciphergate_cli-0.14.0 → ciphergate_cli-0.15.0}/docs/security-and-privacy.md

@@ -67,7 +67,8 @@ Reports contain: run ID, UTC time, version, input basename (or `<redacted>`), fo
 record counts, policy name/version/SHA-256 digest of the policy file, effective context with
 sources, gates, counts by category/detector/action/band/reason/rule, safe locations (record,
 line, field path, character span), rule IDs and reason codes, key status, changes, parse error
-line numbers and codes, rescan summary, warnings and a disclaimer. They never contain values,
+line numbers and codes, rescan summary, warnings, `next_steps` (fixed hint text with a reason
+code, for failed runs only) and a disclaimer. They never contain values,
 snippets, keys, mappings, or hashes of values. Field paths whose segments look like sensitive
 values are replaced with `<redacted-key>`; control and bidi characters are escaped.
 

{ciphergate_cli-0.14.0 → ciphergate_cli-0.15.0}/src/ciphergate/__init__.py

@@ -24,7 +24,7 @@ Supported public API (everything else is internal and may change without notice)
     rescan_directory(root, policy, context=None, *, recursive=False, strict=None) -> BatchReport
 """
 
-__version__ = "0.14.0"
+__version__ = "0.15.0"
 
 from ciphergate.config import RuntimeSettings
 from ciphergate.constants import (

{ciphergate_cli-0.14.0 → ciphergate_cli-0.15.0}/src/ciphergate/models/report.py

@@ -11,6 +11,7 @@ from enum import StrEnum
 from typing import Any
 
 from ciphergate.constants import DISCLAIMER, REPORT_SCHEMA, ExitCode
+from ciphergate.reporting.next_steps import next_step_items
 
 
 class RunStatus(StrEnum):
@@ -89,7 +90,7 @@ class RunReport:
         return self.exit_code == 0
 
     def to_dict(self) -> dict[str, Any]:
-        return {
+        data: dict[str, Any] = {
             "schema": REPORT_SCHEMA,
             "command": self.command,
             "status": str(self.status),
@@ -111,5 +112,8 @@ class RunReport:
             "output": self.output,
             "rescan": self.rescan.to_dict() if self.rescan else None,
             "warnings": self.warnings,
-            "disclaimer": DISCLAIMER,
         }
+        # Fixed hint text chosen by reason code: never contains input values.
+        data["next_steps"] = next_step_items(data)
+        data["disclaimer"] = DISCLAIMER
+        return data

{ciphergate_cli-0.14.0 → ciphergate_cli-0.15.0}/src/ciphergate/pipeline/batch.py

@@ -52,6 +52,7 @@ from ciphergate.pipeline.sanitizer import (
 from ciphergate.policy.validator import Policy
 from ciphergate.readers import EXTENSION_FORMATS
 from ciphergate.reporting.audit import new_run_id, utc_now
+from ciphergate.reporting.next_steps import merge_next_steps
 
 logger = logging.getLogger("ciphergate")
 
@@ -136,6 +137,7 @@ class BatchReport:
 
     def to_dict(self) -> dict[str, Any]:
         first = next((r.report for r in self.files if r.report is not None), None)
+        files = [r.to_dict() for r in self.files]
         return {
             "schema": BATCH_REPORT_SCHEMA,
             "command": self.command,
@@ -148,10 +150,11 @@ class BatchReport:
             "policy": first.policy if first is not None else None,
             "context": first.context if first is not None else None,
             "summary": self.summary(),
-            "files": [r.to_dict() for r in self.files],
+            "files": files,
             "skipped": self.skipped,
             "output": self.output,
             "warnings": self.warnings,
+            "next_steps": merge_next_steps([f["report"] for f in files if "report" in f]),
             "disclaimer": DISCLAIMER,
         }
 
@@ -324,7 +327,8 @@ def coverage_warnings(
 def _require_files(discovery: Discovery) -> None:
     if not discovery.files:
         raise InputFormatError(
-            "no supported input files found in the directory (see --format, --recursive)",
+            "no supported input files found in the directory (see --extension-format, --format, "
+            "--recursive)",
             code="batch_empty",
         )
 

{ciphergate_cli-0.14.0 → ciphergate_cli-0.15.0}/src/ciphergate/reporting/next_steps.py

@@ -83,7 +83,12 @@ _KEY_HINT = (
 
 
 def next_steps(report: dict[str, Any]) -> list[str]:
-    """Hints for a run that ended with a non-zero exit code; empty otherwise."""
+    """Hint messages for a run that ended with a non-zero exit code; empty otherwise."""
+    return [step["message"] for step in next_step_items(report)]
+
+
+def next_step_items(report: dict[str, Any]) -> list[dict[str, str]]:
+    """``{"code", "message"}`` pairs for a failed run; ``code`` is a stable reason code."""
     if not report.get("exit_code"):
         return []
     codes = [gate["reason_code"] for gate in report.get("gates", [])]
@@ -93,14 +98,28 @@ def next_steps(report: dict[str, Any]) -> list[str]:
     rescan = report.get("rescan")
     if rescan and rescan.get("failed"):
         codes.append(ReasonCode.RESIDUAL_FINDING)
-    hints: list[str] = []
+    items: list[dict[str, str]] = []
     for code in codes:
         hint = _HINTS.get(code)
-        if hint and hint not in hints:
-            hints.append(hint)
+        if hint:
+            _add(items, str(code), hint)
     for key in report.get("keys", []):
-        if key.get("status") != "available":
-            hint = _KEY_HINT.format(env=key["key_env"])
-            if hint not in hints:
-                hints.append(hint)
-    return hints
+        status = key.get("status")
+        if status != "available":
+            code = ReasonCode.KEY_MISSING if status == "missing" else ReasonCode.KEY_INVALID
+            _add(items, str(code), _KEY_HINT.format(env=key["key_env"]))
+    return items
+
+
+def merge_next_steps(reports: list[dict[str, Any]]) -> list[dict[str, str]]:
+    """Combine the hints of several reports (a directory run), first occurrence first."""
+    items: list[dict[str, str]] = []
+    for report in reports:
+        for step in report.get("next_steps") or next_step_items(report):
+            _add(items, step["code"], step["message"])
+    return items
+
+
+def _add(items: list[dict[str, str]], code: str, message: str) -> None:
+    if all(step["message"] != message for step in items):
+        items.append({"code": code, "message": message})

{ciphergate_cli-0.14.0 → ciphergate_cli-0.15.0}/src/ciphergate/reporting/terminal.py

@@ -7,7 +7,6 @@ from typing import Any
 from ciphergate.constants import DISCLAIMER, RESCAN_LIMIT
 from ciphergate.models.report import RunReport
 from ciphergate.pipeline.batch import BatchReport
-from ciphergate.reporting.next_steps import next_steps
 from ciphergate.reporting.safe_text import escape_control
 
 SUMMARY_ITEMS = 15
@@ -120,8 +119,8 @@ def render_summary(report: RunReport, *, verbose: bool = False) -> str:
             lines.append(f"  output:  not written ({out['withheld_reason']})")
     for warning in d["warnings"]:
         lines.append(f"  warning: {escape_control(warning)}")
-    for hint in next_steps(d):
-        lines.append(f"  next: {hint}")
+    for step in d["next_steps"]:
+        lines.append(f"  next: {step['message']}")
     lines.append(f"  note: {DISCLAIMER}")
     return "\n".join(lines) + "\n"
 
@@ -161,13 +160,8 @@ def render_batch_summary(report: BatchReport, *, verbose: bool = False) -> str:
             lines.append(f"  output:  not written ({out.get('withheld_reason')})")
     for warning in d["warnings"]:
         lines.append(f"  warning: {escape_control(warning)}")
-    hints: list[str] = []
-    for entry in d["files"]:
-        for hint in next_steps(entry.get("report") or {}):
-            if hint not in hints:
-                hints.append(hint)
-    for hint in hints:
-        lines.append(f"  next: {hint}")
+    for step in d["next_steps"]:
+        lines.append(f"  next: {step['message']}")
     lines.append("  note: per-file details are in the JSON report (--report).")
     lines.append(f"  note: {DISCLAIMER}")
     return "\n".join(lines) + "\n"

{ciphergate_cli-0.14.0 → ciphergate_cli-0.15.0}/tests/integration/test_batch.py

@@ -405,6 +405,11 @@ def test_directory_summary_carries_next_steps(tmp_path: Path) -> None:
     (root / "app.log").write_text(SECRET_LINE, encoding="utf-8")
     r = invoke("inspect", root, "--policy", POLICIES / "developer_logs.yml")
     assert r.exit_code == 1 and "next: pass --environment" in r.stdout
+    report = tmp_path / "report.json"
+    invoke("inspect", root, "--policy", POLICIES / "developer_logs.yml", "--report", report)
+    data = _report(report)
+    assert "environment_required_but_missing" in [s["code"] for s in data["next_steps"]]
+    assert data["next_steps"] == data["files"][0]["report"]["next_steps"]
 
 
 # --------------------------------------------------------------------------- --extension-format
@@ -496,3 +501,11 @@ def test_sanitize_directory_with_extension_format(tmp_path: Path, env) -> None:
     assert r.exit_code == 0, r.stdout
     assert sorted(p.name for p in out.iterdir()) == ["app.log", "users.dat"]
     assert "alice@example.com" not in (out / "users.dat").read_text(encoding="utf-8")
+
+
+def test_empty_directory_error_mentions_extension_format(tmp_path: Path, env) -> None:
+    root = tmp_path / "in"
+    root.mkdir()
+    (root / "users.dat").write_text("email\nx\n", encoding="utf-8")
+    r = invoke("inspect", root, *PRD_EXTERNAL, env=env)
+    assert r.exit_code == 4 and "--extension-format" in r.stdout + r.stderr

{ciphergate_cli-0.14.0 → ciphergate_cli-0.15.0}/tests/integration/test_cli_e2e.py

@@ -206,6 +206,20 @@ def test_blocked_run_says_what_to_do_next(tmp_path: Path) -> None:
     assert "next: pass --environment" in r.stdout and "next: pass --destination" in r.stdout
 
 
+def test_json_report_lists_next_steps(tmp_path: Path) -> None:
+    src = tmp_path / "raw.csv"
+    shutil.copy(EXAMPLES / "sample.csv", src)
+    report = tmp_path / "report.json"
+    r = invoke("inspect", src, "--policy", POLICIES / "developer_logs.yml", "--report", report)
+    assert r.exit_code == 1
+    steps = json.loads(report.read_text(encoding="utf-8"))["next_steps"]
+    codes = [s["code"] for s in steps]
+    assert codes[:2] == ["environment_required_but_missing", "destination_required_but_missing"]
+    assert len(codes) == len(set(codes))
+    for step in steps:
+        assert f"next: {step['message']}" in r.stdout
+
+
 def test_successful_run_has_no_next_steps(tmp_path: Path) -> None:
     clean = tmp_path / "clean.log"
     clean.write_text("service started\n", encoding="utf-8")

{ciphergate_cli-0.14.0 → ciphergate_cli-0.15.0}/tests/unit/test_next_steps.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from typing import Any
 
 from ciphergate.constants import ReasonCode
-from ciphergate.reporting.next_steps import _HINTS, next_steps
+from ciphergate.reporting.next_steps import _HINTS, merge_next_steps, next_step_items, next_steps
 
 
 def report(**extra: Any) -> dict[str, Any]:
@@ -60,3 +60,35 @@ def test_hints_are_fixed_text() -> None:
     # Hints come from a fixed table, so they can never carry input values.
     unknown = {"by_reason_code": {"explicit_policy_match": 3, "not_a_code": 1}}
     assert next_steps(report(summary=unknown)) == []
+
+
+def test_items_carry_stable_codes() -> None:
+    items = next_step_items(
+        report(
+            gates=[{"reason_code": ReasonCode.ENVIRONMENT_REQUIRED_BUT_MISSING}],
+            keys=[
+                {"key_env": "CIPHERGATE_HMAC_KEY", "status": "missing"},
+                {"key_env": "OTHER_KEY", "status": "too_short"},
+            ],
+        )
+    )
+    assert [i["code"] for i in items] == [
+        "environment_required_but_missing",
+        "key_missing",
+        "key_invalid",
+    ]
+    assert all(set(i) == {"code", "message"} for i in items)
+
+
+def test_merge_keeps_first_occurrence_order() -> None:
+    a = report(gates=[{"reason_code": ReasonCode.DESTINATION_REQUIRED_BUT_MISSING}])
+    b = report(
+        gates=[
+            {"reason_code": ReasonCode.ENVIRONMENT_REQUIRED_BUT_MISSING},
+            {"reason_code": ReasonCode.DESTINATION_REQUIRED_BUT_MISSING},
+        ]
+    )
+    assert [i["code"] for i in merge_next_steps([a, b])] == [
+        "destination_required_but_missing",
+        "environment_required_but_missing",
+    ]