Add runtime control of how to check the payload "data" directory against the manifest

Author: DocOtak

CHANGELOG.md

@@ -7,6 +7,7 @@
 * Increase the cnv generation attempts from 3 to 5
 * Add HTML/leaflet based map output
 * If no files to test (empty breakout), set overall score to black
+* Add runtime control of how to check the payload "data" directory against the manifest
 
 ## v2025.08.0 (2025-08-11)
 * Initial release.

src/r2r_ctd/__main__.py

@@ -19,7 +19,7 @@
 import click
 from rich.logging import RichHandler
 
-from r2r_ctd.breakout import Breakout
+from r2r_ctd.breakout import Breakout, PayloadStrictness
 from r2r_ctd.docker_ctl import test_docker as _test_docker
 from r2r_ctd.maps import make_map
 from r2r_ctd.reporting import (
@@ -58,10 +58,17 @@ def test_docker():
     type=click.Path(exists=True, file_okay=False, writable=True, path_type=Path),
 )
 @click.option("--gen-cnvs/--no-gen-cnvs", default=True)
-def qa(gen_cnvs: bool, paths: tuple[Path, ...]):
+@click.option(
+    "--payload-strictness",
+    show_default=True,
+    default=PayloadStrictness.FLEX,
+    type=click.Choice(PayloadStrictness, case_sensitive=False),
+    help=PayloadStrictness.__doc__,
+)
+def qa(gen_cnvs: bool, paths: tuple[Path, ...], payload_strictness: PayloadStrictness):
     """Run the QA routines on one or more directories."""
     for path in paths:
-        breakout = Breakout(path=path)
+        breakout = Breakout(path=path, payload=payload_strictness)
         ra = ResultAggregator(breakout)
 
         # write geoCSV

src/r2r_ctd/breakout.py

@@ -6,6 +6,7 @@
 
 from dataclasses import dataclass
 from datetime import datetime, timedelta
+from enum import StrEnum, auto
 from functools import cached_property
 from hashlib import file_digest
 from logging import getLogger
@@ -105,6 +106,19 @@ def contains(self, dt: datetime) -> bool:
         return self.dtstart <= dt < self.dtend
 
 
+class PayloadStrictness(StrEnum):
+    """Strictness of how to validate the payload against the manifest
+
+    * "strict":  any files in the payload directory and not in the manifest cause the test to fail.
+    * "flex": a reasonable set of files in the payload directory and not in the manifest are ignored (.DS_Store files).
+    * "manifest": only files in the manifest are checked and others are ignored.
+    """
+
+    STRICT = auto()
+    FLEX = auto()
+    MANIFEST = auto()
+
+
 @dataclass
 class Breakout:
     """Convenience wrapper for manipulating the various Paths of the r2r breakout
@@ -123,6 +137,9 @@ class Breakout:
     path: Path
     """Path to the breakout itself, this set on instantiating a Breakout"""
 
+    payload: PayloadStrictness = PayloadStrictness.FLEX
+    """How strictly should the payload directory be validated"""
+
     @property
     def manifest_path(self) -> Path:
         """The Path of the manifest-md5.txt file in this breakout"""
@@ -133,6 +150,11 @@ def manifest(self) -> str:
         """Reads the manifest file as returns its contents as a string"""
         return self.manifest_path.read_text()
 
+    @property
+    def payload_path(self) -> Path:
+        """The path to the "data" directory assuming this is a BagIt bag"""
+        return self.path / "data"
+
     @cached_property
     def manifest_dict(self) -> dict[Path, str]:
         """Transforms the manifest file into a dict containing file path to file hash mappings"""
@@ -150,14 +172,28 @@ def manifest_dict(self) -> dict[Path, str]:
     def manifest_ok(self) -> bool:
         """Iterate over the manifest and check all the file hashes against the files in the breakout
 
-        In an actual bag-it bag, it would be an error for extra stuff to be in the data directory.
-        For example, a .DS_Store file if you looked at the breakout data directory on a mac.
-        This ignores anything not in the manifest file.
+        See :py:class:`PayloadStrictness` for how to control behavior.
 
         This returns True if both all the files in the manifest are present and their md5 hashes match.
 
         This is one of the checks that goes into the stoplight report.
         """
+        flex_files = {
+            ".DS_Store",
+        }
+        logger.info(f"Payload validation mode: {self.payload}")
+        err_message = "Files are in payload directory and not in manifest, breakout is likely invalid or corrupted"
+        for root, _, files in self.payload_path.walk():
+            paths = {root / file for file in files}
+            diff = paths - self.manifest_dict.keys()
+            if self.payload == "strict" and any(diff):
+                logger.critical(err_message)
+                return False
+
+            if self.payload == "flex" and not all(d.name in flex_files for d in diff):
+                logger.critical(err_message)
+                return False
+
         for file_path, manifest_hash in self.manifest_dict.items():
             if not file_path.exists():
                 return False