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

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

@@ -6,6 +6,38 @@ 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
+real Presidio install. No existing behaviour changes.
+
+### Added
+
+- `--extension-format EXT=FORMAT` on `inspect`, `plan`, `sanitize` and `rescan` (repeatable) reads
+  files with that extension as FORMAT, for directories and single files. It adds unknown
+  extensions or replaces built-in ones, and cannot be combined with `--format`. The Python API
+  takes `RuntimeSettings(extension_formats=...)`.
+- Tests that run the optional NER detector against a real Presidio install with the
+  `en_core_web_sm` model, including a `sanitize` run with network access disabled. They skip
+  when Presidio is not installed. A new non-required CI job, `ner`, installs the extra and a
+  hash-pinned model and runs them.
+
 ## [0.13.0] - 2026-11-02
 
 Fewer random IDs are reported as payment cards. Cards with an unrecognised prefix and no card
@@ -363,7 +395,9 @@ 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.13.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
 [0.11.0]: https://github.com/aashishkumar-tech/ciphergate/compare/v0.10.0...v0.11.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ciphergate-cli
-Version: 0.13.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.13.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
 
@@ -295,6 +297,10 @@ ciphergate sanitize logs/ --policy ... --output build/logs.sanitized --apply
   `rescan` fails (exit 7) when it skipped any, and `sanitize` leaves them out of the output.
   `--format` on a directory applies to every file, and the run warns when that contradicts an
   extension (for example a CSV read as text loses its column names).
+- `--extension-format EXT=FORMAT` (repeatable) reads files with that extension as FORMAT, for
+  example `--extension-format .dat=csv --extension-format .log=jsonlog`. It adds unknown extensions
+  and replaces built-in ones, works for single files too, and cannot be combined with `--format`.
+  From Python, pass `RuntimeSettings(extension_formats={".dat": InputFormat.CSV})`.
   At most 1000 files by default (`--max-files N`); more fails the run (exit 4) before anything
   is processed. An empty selection fails with `batch_empty` (exit 4).
 - Each file is processed exactly like a single-file run, in sorted path order; a failing file

{ciphergate_cli-0.13.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.13.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
 
@@ -256,6 +258,10 @@ ciphergate sanitize logs/ --policy ... --output build/logs.sanitized --apply
   `rescan` fails (exit 7) when it skipped any, and `sanitize` leaves them out of the output.
   `--format` on a directory applies to every file, and the run warns when that contradicts an
   extension (for example a CSV read as text loses its column names).
+- `--extension-format EXT=FORMAT` (repeatable) reads files with that extension as FORMAT, for
+  example `--extension-format .dat=csv --extension-format .log=jsonlog`. It adds unknown extensions
+  and replaces built-in ones, works for single files too, and cannot be combined with `--format`.
+  From Python, pass `RuntimeSettings(extension_formats={".dat": InputFormat.CSV})`.
   At most 1000 files by default (`--max-files N`); more fails the run (exit 4) before anything
   is processed. An empty selection fails with `batch_empty` (exit 4).
 - Each file is processed exactly like a single-file run, in sorted path order; a failing file

{ciphergate_cli-0.13.0 → ciphergate_cli-0.15.0}/docs/detector-coverage.md

@@ -28,8 +28,12 @@ Needs `pip install 'ciphergate-cli[ner]'` and a spaCy model installed by the use
 `python -m spacy download en_core_web_lg`). CipherGate checks that the model package is importable
 before importing Presidio and fails with `ner_model_missing` instead of letting Presidio download
 it. Strings with no letters or under two characters are not sent to the model. Tests
-(`tests/unit/test_presidio_ner.py`) use a fake engine. Presidio itself is **not** exercised in
-CI, so accuracy on real text has not been measured by this project.
+in `tests/unit/test_presidio_ner.py` use a fake engine. `tests/integration/test_presidio_real.py`
+runs the real Presidio with `en_core_web_sm`: it finds a common synthetic name and place, ignores
+text with no entities, removes them in a `sanitize` run with network access disabled, and fails
+closed when the model is missing. CI runs it in the `ner` job (not a required check). These are
+smoke tests on a few sentences: accuracy on real text has not been measured by this project,
+and the small model misses names that the larger `en_core_web_lg` may find.
 
 ## Text/log specifics
 

{ciphergate_cli-0.13.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.13.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.13.0"
+__version__ = "0.15.0"
 
 from ciphergate.config import RuntimeSettings
 from ciphergate.constants import (

{ciphergate_cli-0.13.0 → ciphergate_cli-0.15.0}/src/ciphergate/cli.py

@@ -117,6 +117,15 @@ PolicyOpt = Annotated[Path, typer.Option("--policy", "-p", help="Policy YAML fil
 FormatOpt = Annotated[
     InputFormat | None, typer.Option("--format", help="Input format (default: from extension).")
 ]
+ExtFormatOpt = Annotated[
+    list[str] | None,
+    typer.Option(
+        "--extension-format",
+        metavar="EXT=FORMAT",
+        help="Read files with this extension as FORMAT, e.g. .dat=csv or .log=jsonlog. "
+        "Repeatable. Cannot be combined with --format.",
+    ),
+]
 ReportOpt = Annotated[
     Path | None, typer.Option("--report", help="Write the privacy-safe report to this file.")
 ]
@@ -192,18 +201,52 @@ def _runtime(
     encoding: str | None,
     path_display: PathDisplayChoice | None,
     max_files: int | None = None,
+    extension_formats: list[str] | None = None,
+    fmt: InputFormat | None = None,
 ) -> RuntimeSettings:
+    mapping = _parse_extension_formats(extension_formats or [])
+    if mapping and fmt is not None:
+        raise UsageError(
+            "use either --format (one format for every file) or --extension-format, not both",
+            code="format_conflict",
+        )
     try:
         return RuntimeSettings().with_overrides(
             max_input_bytes=max_bytes,
             encoding=encoding,
             path_display=str(path_display) if path_display else None,
             max_batch_files=max_files,
+            extension_formats=mapping or None,
         )
     except ValueError as exc:
         raise UsageError(str(exc), code="invalid_runtime_setting") from None
 
 
+def _parse_extension_formats(values: list[str]) -> dict[str, InputFormat]:
+    mapping: dict[str, InputFormat] = {}
+    for value in values:
+        ext, sep, name = value.partition("=")
+        ext = ext.strip().lower()
+        if not ext.startswith("."):
+            ext = "." + ext
+        try:
+            fmt = InputFormat(name.strip().lower())
+        except ValueError:
+            fmt = None
+        if not sep or fmt is None:
+            raise UsageError(
+                "--extension-format needs EXT=FORMAT with FORMAT one of " + "|".join(InputFormat),
+                code="invalid_extension_format",
+            )
+        if ext in mapping and mapping[ext] != fmt:
+            raise UsageError(
+                "--extension-format maps the same extension to two formats",
+                code="invalid_extension_format",
+            )
+        mapping[ext] = fmt
+    return mapping
+
+
 def _err(message: str) -> None:
     sys.stderr.write(escape_control(message)[:2000] + "\n")
 
@@ -501,6 +544,7 @@ def inspect_command(
     ],
     policy: PolicyOpt,
     fmt: FormatOpt = None,
+    extension_format: ExtFormatOpt = None,
     report: ReportOpt = None,
     report_format: ReportFormatOpt = None,
     environment: EnvOpt = None,
@@ -531,7 +575,7 @@ def inspect_command(
             report,
             report_format,
             _context(environment, target_environment, destination, use_case, profile),
-            _runtime(max_bytes, encoding, path_display, max_files),
+            _runtime(max_bytes, encoding, path_display, max_files, extension_format, fmt),
             quiet,
             verbose,
             force,
@@ -547,6 +591,7 @@ def plan_command(
     ],
     policy: PolicyOpt,
     fmt: FormatOpt = None,
+    extension_format: ExtFormatOpt = None,
     report: ReportOpt = None,
     report_format: ReportFormatOpt = None,
     environment: EnvOpt = None,
@@ -577,7 +622,7 @@ def plan_command(
             report,
             report_format,
             _context(environment, target_environment, destination, use_case, profile),
-            _runtime(max_bytes, encoding, path_display, max_files),
+            _runtime(max_bytes, encoding, path_display, max_files, extension_format, fmt),
             quiet,
             verbose,
             force,
@@ -604,6 +649,7 @@ def sanitize_command(
         bool, typer.Option("--apply", help="Actually write output (else plan).")
     ] = False,
     fmt: FormatOpt = None,
+    extension_format: ExtFormatOpt = None,
     report: ReportOpt = None,
     report_format: ReportFormatOpt = None,
     environment: EnvOpt = None,
@@ -636,7 +682,9 @@ def sanitize_command(
                 "--output - uses stdout for data; write the JSON report with --report PATH",
                 code="stdout_conflict",
             )
-        runtime = _runtime(max_bytes, encoding, path_display)
+        runtime = _runtime(
+            max_bytes, encoding, path_display, extension_formats=extension_format, fmt=fmt
+        )
         _check_report_path(report, [p for p in (input_path, output) if not is_stdio(p)], force)
         loaded = load_policy(policy)
         options = SanitizeOptions(apply=apply, force=force, format=selected_fmt, runtime=runtime)
@@ -689,7 +737,7 @@ def sanitize_command(
             raise UsageError(
                 "a directory INPUT needs --output DIR, not stdout", code="stdout_unsupported"
             )
-        runtime = _runtime(max_bytes, encoding, path_display, max_files)
+        runtime = _runtime(max_bytes, encoding, path_display, max_files, extension_format, fmt)
         _check_batch_report_path(report, [input_path, output], force)
         batch = sanitize_directory(
             input_path,
@@ -731,6 +779,7 @@ def rescan_command(
         ),
     ] = None,
     fmt: FormatOpt = None,
+    extension_format: ExtFormatOpt = None,
     report: ReportOpt = None,
     report_format: ReportFormatOpt = None,
     environment: EnvOpt = None,
@@ -764,7 +813,7 @@ def rescan_command(
             report,
             report_format,
             _context(environment, target_environment, destination, use_case, profile),
-            _runtime(max_bytes, encoding, path_display, max_files),
+            _runtime(max_bytes, encoding, path_display, max_files, extension_format, fmt),
             quiet,
             verbose,
             force,

{ciphergate_cli-0.13.0 → ciphergate_cli-0.15.0}/src/ciphergate/config.py

@@ -2,10 +2,14 @@
 
 from __future__ import annotations
 
+import re
 from dataclasses import dataclass, field, replace
 from typing import Literal
 
+from ciphergate.constants import InputFormat
+
 PathDisplay = Literal["basename", "redacted", "full"]
+_EXTENSION_RE = re.compile(r"^\.[a-z0-9_-]{1,16}$")
 
 MIB = 1024 * 1024
 
@@ -27,6 +31,9 @@ class RuntimeSettings:
     encoding: str = "utf-8"
     csv_delimiter: str = ","
     path_display: PathDisplay = "basename"
+    # Extra or replacement extension -> format mappings, e.g. {".dat": csv}. Keys are
+    # lower-case single suffixes. An explicit --format still wins for every file.
+    extension_formats: dict[str, InputFormat] = field(default_factory=dict)
     # Stored for completeness of the run report; never changes decisions.
     extra: dict[str, str] = field(default_factory=dict)
 
@@ -44,6 +51,12 @@ class RuntimeSettings:
                 raise ValueError(f"{name} must be a positive integer")
         if len(self.csv_delimiter) != 1 or self.csv_delimiter in '\r\n"':
             raise ValueError("csv_delimiter must be a single character other than quote or newline")
+        for ext in self.extension_formats:
+            if not _EXTENSION_RE.match(ext):
+                raise ValueError(
+                    "extension_formats keys must look like '.dat' (a dot, then 1-16 "
+                    "lower-case letters, digits, '_' or '-')"
+                )
 
     def with_overrides(self, **changes: object) -> RuntimeSettings:
         clean = {k: v for k, v in changes.items() if v is not None}

{ciphergate_cli-0.13.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.13.0 → ciphergate_cli-0.15.0}/src/ciphergate/pipeline/batch.py

@@ -24,7 +24,7 @@ import shutil
 import stat
 import sys
 import tempfile
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
@@ -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,
         }
 
@@ -171,7 +174,14 @@ def _is_link(entry: os.DirEntry[str]) -> bool:
     return False
 
 
-def discover(root: Path, *, recursive: bool, fmt: InputFormat | None, max_files: int) -> Discovery:
+def discover(
+    root: Path,
+    *,
+    recursive: bool,
+    fmt: InputFormat | None,
+    max_files: int,
+    extensions: Mapping[str, InputFormat] | None = None,
+) -> Discovery:
     """List the files a batch run will process. Raises on limits; never follows links."""
     try:
         st = os.lstat(root)
@@ -210,7 +220,7 @@ def discover(root: Path, *, recursive: bool, fmt: InputFormat | None, max_files:
                         walk(rel, depth + 1)
                 elif not entry.is_file(follow_symlinks=False):
                     skipped.append((rel, "not_regular_file"))
-                elif fmt is None and rel.suffix.lower() not in EXTENSION_FORMATS:
+                elif fmt is None and not _known_extension(rel, extensions):
                     skipped.append((rel, "unsupported_extension"))
                 else:
                     files.append(rel)
@@ -226,6 +236,11 @@ def discover(root: Path, *, recursive: bool, fmt: InputFormat | None, max_files:
     return Discovery(root, sorted(files, key=lambda p: p.as_posix()), skipped)
 
 
+def _known_extension(rel: Path, extensions: Mapping[str, InputFormat] | None) -> bool:
+    suffix = rel.suffix.lower()
+    return suffix in EXTENSION_FORMATS or suffix in (extensions or {})
+
+
 def display_relative(rel: Path, index: int, root: Path, mode: str) -> str:
     if mode == "redacted":
         return f"<redacted:{index:04d}>{rel.suffix}"
@@ -291,7 +306,8 @@ def coverage_warnings(
             f"{unknown} file(s) were skipped and not scanned because their extension is not "
             "recognised"
             + ("; they are not in the output" if sanitize else "")
-            + "; rename them, or pass --format to read every file as one format"
+            + "; map them with --extension-format EXT=FORMAT, or pass --format to read every "
+            "file as one format"
         )
     if fmt is not None:
         mismatched = sum(
@@ -311,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",
         )
 
@@ -332,7 +349,13 @@ def analyze_directory(
 ) -> BatchReport:
     """Batch ``inspect`` / ``plan`` / ``rescan``. Read-only, like the single-file commands."""
     root = Path(root)
-    discovery = discover(root, recursive=recursive, fmt=fmt, max_files=runtime.max_batch_files)
+    discovery = discover(
+        root,
+        recursive=recursive,
+        fmt=fmt,
+        max_files=runtime.max_batch_files,
+        extensions=runtime.extension_formats,
+    )
     _require_files(discovery)
 
     def run(path: Path, rel: Path) -> RunReport:
@@ -471,7 +494,11 @@ def sanitize_directory(
     runtime = options.runtime or RuntimeSettings()
     validate_output_directory(root, output)
     discovery = discover(
-        root, recursive=recursive, fmt=options.format, max_files=runtime.max_batch_files
+        root,
+        recursive=recursive,
+        fmt=options.format,
+        max_files=runtime.max_batch_files,
+        extensions=runtime.extension_formats,
     )
     _require_files(discovery)
     mode = runtime.path_display

{ciphergate_cli-0.13.0 → ciphergate_cli-0.15.0}/src/ciphergate/pipeline/inspector.py

@@ -85,7 +85,7 @@ def prepare_run(
     ctx = resolve_context(policy, context)
     path = Path(input_path)
     validate_input_path(path, runtime.max_input_bytes)
-    detected = detect_format(path, fmt)
+    detected = detect_format(path, fmt, runtime.extension_formats)
     options = ReaderOptions(
         runtime=runtime,
         policy_settings=policy.document.settings,

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

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from pathlib import Path
 from typing import IO
 
@@ -49,11 +50,19 @@ _JSON_PREFIXES = (
 )
 
 
-def detect_format(path: Path, explicit: InputFormat | None = None) -> InputFormat:
-    """Explicit ``--format`` wins; else use the extension, refusing contradicting content."""
+def detect_format(
+    path: Path,
+    explicit: InputFormat | None = None,
+    extensions: Mapping[str, InputFormat] | None = None,
+) -> InputFormat:
+    """Explicit ``--format`` wins; then ``extensions``, then the built-in extension table.
+
+    Content that contradicts a JSON format is refused either way.
+    """
     if explicit is not None:
         return explicit
-    fmt = EXTENSION_FORMATS.get(path.suffix.lower())
+    suffix = path.suffix.lower()
+    fmt = (extensions or {}).get(suffix) or EXTENSION_FORMATS.get(suffix)
     if fmt is None:
         raise UsageError(
             "cannot infer the input format from this file extension; pass --format "

{ciphergate_cli-0.13.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.13.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"