D4CMPP2 0.4.0__py3-none-any.whl

D4CMPP2/src/utils/config_validation.py

@@ -0,0 +1,370 @@
+"""Early, dependency-light validation for training configuration values."""
+
+import difflib
+import importlib
+import re
+import warnings
+
+
+def _dependency_error(message):
+    """Keep dependency-light source tests while categorizing package imports."""
+
+    try:
+        from D4CMPP2.exceptions import DependencyError
+    except ImportError:
+        return RuntimeError(message)
+    return DependencyError(message)
+
+
+SCALERS = ("standard", "minmax", "normalizer", "robust", "identity")
+REGISTRY_FIELDS = (
+    "network",
+    "data_manager_module",
+    "data_manager_class",
+    "network_manager_module",
+    "network_manager_class",
+    "train_manager_module",
+    "train_manager_class",
+)
+
+
+def _type_name(value):
+    return type(value).__name__
+
+
+def validate_entry_args(kwargs):
+    """Validate arguments whose contract is known before config/path loading."""
+    modes = [
+        key for key in ("LOAD_PATH", "RESUME_PATH", "TRANSFER_PATH")
+        if kwargs.get(key) is not None
+    ]
+    if len(modes) > 1:
+        raise ValueError(
+            f"{modes} are mutually exclusive. Use LOAD_PATH for weight-only continuation, "
+            "RESUME_PATH for full-state resume, or TRANSFER_PATH for parameter transfer."
+        )
+    if modes:
+        key = modes[0]
+        path = kwargs[key]
+        if not isinstance(path, str) or not path.strip():
+            raise TypeError(
+                f"{key} must be a non-empty string, got {path!r} "
+                f"({_type_name(path)}). Provide a saved model folder or checkpoint path."
+            )
+        if key in {"LOAD_PATH", "RESUME_PATH"}:
+            return
+
+    data = kwargs.get("data")
+    if not isinstance(data, str) or not data.strip():
+        raise TypeError(
+            f"data must be a non-empty CSV name or path string, got {data!r} "
+            f"({_type_name(data)}). Example: data='Aqsoldb.csv'."
+        )
+
+    target = kwargs.get("target")
+    if not isinstance(target, list) or not target or not all(
+        isinstance(column, str) and column.strip() for column in target
+    ):
+        raise TypeError(
+            f"target must be a non-empty list of column-name strings, got {target!r} "
+            f"({_type_name(target)}). Example: target=['Solubility']."
+        )
+
+    network = kwargs.get("network")
+    if not isinstance(network, str) or not network.strip():
+        raise TypeError(
+            f"network must be a non-empty network ID string, got {network!r} "
+            f"({_type_name(network)}). Example: network='GCN'."
+        )
+
+
+def validate_network_entry(network_id, entry, available_ids):
+    """Validate one selected network registry entry before manager loading."""
+    if entry is None:
+        candidates = difflib.get_close_matches(network_id, available_ids, n=3, cutoff=0.5)
+        message = (
+            f"Network ID {network_id!r} was not found. "
+            f"Available network IDs: {', '.join(available_ids)}."
+        )
+        if candidates:
+            message += f" Did you mean {', '.join(repr(item) for item in candidates)}?"
+        raise ValueError(message)
+
+    missing = [
+        field
+        for field in REGISTRY_FIELDS
+        if not isinstance(entry.get(field), str) or not entry[field].strip()
+    ]
+    if missing:
+        raise ValueError(
+            f"Registry entry for network {network_id!r} is missing required non-empty "
+            f"keys: {missing}. Check the selected network reference YAML file."
+        )
+
+
+def validate_training_config(config, optimizer_names=None):
+    """Validate merged training values without mutating the configuration."""
+    scaler = config.get("scaler")
+    if scaler not in SCALERS:
+        raise ValueError(
+            f"scaler must be one of {list(SCALERS)}, got {scaler!r}. "
+            "Choose a supported target scaling method."
+        )
+
+    optimizer = config.get("optimizer")
+    if not isinstance(optimizer, str) or not optimizer.strip():
+        raise TypeError(
+            f"optimizer must be a torch.optim class name string, got {optimizer!r} "
+            f"({_type_name(optimizer)}). Example: optimizer='Adam'."
+        )
+    if optimizer_names is not None and optimizer not in optimizer_names:
+        candidates = difflib.get_close_matches(optimizer, sorted(optimizer_names), n=3, cutoff=0.5)
+        hint = f" Did you mean {', '.join(repr(item) for item in candidates)}?" if candidates else ""
+        raise ValueError(
+            f"Optimizer {optimizer!r} is not available in torch.optim.{hint} "
+            "Use a torch.optim optimizer class name such as 'Adam'."
+        )
+
+    _positive_int(config, "max_epoch")
+    _positive_int(config, "batch_size")
+    _non_negative_int(config, "lr_patience")
+    _non_negative_int(config, "early_stopping_patience")
+    _positive_number(config, "learning_rate")
+    _non_negative_number(config, "weight_decay")
+    _non_negative_number(config, "min_lr")
+
+    learning_rate = config["learning_rate"]
+    min_lr = config["min_lr"]
+    if min_lr > learning_rate:
+        raise ValueError(
+            f"min_lr ({min_lr!r}) must not exceed learning_rate ({learning_rate!r}). "
+            "Lower min_lr or increase learning_rate."
+        )
+
+    pin_memory = config.get("pin_memory")
+    if not isinstance(pin_memory, bool):
+        raise TypeError(
+            f"pin_memory must be bool, got {pin_memory!r} ({_type_name(pin_memory)}). "
+            "Use pin_memory=True or pin_memory=False."
+        )
+
+    legacy_silent_errors = config.get("legacy_silent_errors", False)
+    if not isinstance(legacy_silent_errors, bool):
+        raise TypeError(
+            f"legacy_silent_errors must be bool, got {legacy_silent_errors!r} "
+            f"({_type_name(legacy_silent_errors)}). Use True only for temporary legacy compatibility."
+        )
+
+    verbose = config.get("verbose", True)
+    if not isinstance(verbose, bool):
+        raise TypeError(
+            f"verbose must be bool, got {verbose!r} ({_type_name(verbose)}). "
+            "Use verbose=True to show status output or verbose=False to hide it."
+        )
+
+    device = config.get("device")
+    if not isinstance(device, str) or not re.fullmatch(r"cpu|cuda(?::\d+)?", device):
+        raise ValueError(
+            f"device must be 'cpu', 'cuda', or 'cuda:<non-negative index>', got {device!r}. "
+            "Example: device='cpu' or device='cuda:0'."
+        )
+
+    scaler_scope = config.get("target_scaler_fit_scope", "train")
+    if scaler_scope not in {"train", "all"}:
+        raise ValueError(
+            f"target_scaler_fit_scope must be 'train' or 'all', got {scaler_scope!r}. "
+            "Use 'train' to avoid validation/test leakage or 'all' only for legacy numerical compatibility."
+        )
+
+    cache_policy = config.get("graph_cache_policy", "v2")
+    if cache_policy not in {"v2", "legacy", "regenerate"}:
+        raise ValueError(
+            f"graph_cache_policy must be 'v2', 'legacy', or 'regenerate', got {cache_policy!r}. "
+            "Use 'v2' for verified caches, 'legacy' only for explicit schema-v1 compatibility, "
+            "or 'regenerate' to rebuild an invalid v2 cache."
+        )
+
+    split_strategy = config.get("split_strategy", "auto")
+    if split_strategy not in {"auto", "random", "predefined", "scaffold"}:
+        raise ValueError(
+            f"split_strategy must be 'auto', 'random', 'predefined', or "
+            f"'scaffold', got {split_strategy!r}."
+        )
+    scaffold_column = config.get("scaffold_column")
+    if scaffold_column is not None and (
+        not isinstance(scaffold_column, str) or not scaffold_column.strip()
+    ):
+        raise TypeError(
+            f"scaffold_column must be a non-empty molecule-column string or None, "
+            f"got {scaffold_column!r}."
+        )
+    include_chirality = config.get("scaffold_include_chirality", False)
+    if not isinstance(include_chirality, bool):
+        raise TypeError(
+            f"scaffold_include_chirality must be bool, got "
+            f"{include_chirality!r} ({_type_name(include_chirality)})."
+        )
+
+    random_seed = config.get("random_seed")
+    if random_seed is not None and (
+        isinstance(random_seed, bool) or not isinstance(random_seed, int) or random_seed < 0
+    ):
+        raise ValueError(
+            f"random_seed must be a non-negative integer or None, got {random_seed!r}. "
+            "Example: random_seed=42."
+        )
+    deterministic = config.get("deterministic_algorithms", False)
+    if not isinstance(deterministic, bool):
+        raise TypeError(
+            f"deterministic_algorithms must be bool, got {deterministic!r} "
+            f"({_type_name(deterministic)})."
+        )
+    if deterministic and random_seed is None:
+        raise ValueError(
+            "deterministic_algorithms=True requires random_seed to be set. "
+            "Example: random_seed=42, deterministic_algorithms=True."
+        )
+
+    lr_dict = config.get("lr_dict", {})
+    if not isinstance(lr_dict, dict):
+        raise TypeError(
+            f"lr_dict must be a mapping of layer-name components to learning rates, "
+            f"got {lr_dict!r} ({_type_name(lr_dict)})."
+        )
+    invalid_lr_entries = {
+        key: value for key, value in lr_dict.items()
+        if (
+            not isinstance(key, str)
+            or not key.strip()
+            or isinstance(value, bool)
+            or not isinstance(value, (int, float))
+            or value <= 0
+        )
+    }
+    if invalid_lr_entries:
+        raise ValueError(
+            "lr_dict keys must be non-empty layer-name strings and values must be "
+            f"positive learning rates; invalid entries: {invalid_lr_entries!r}."
+        )
+
+    _validate_sculptor_config(config)
+
+
+def validate_runtime_environment(config, backend="pyg", torch_module=None, importer=None):
+    """Validate device availability and graph backend imports before model creation."""
+    importer = importer or importlib.import_module
+    if torch_module is None:
+        try:
+            torch_module = importer("torch")
+        except (ImportError, OSError) as exc:
+            raise _dependency_error(
+                "PyTorch could not be imported, so training cannot start. "
+                "Install a PyTorch build compatible with your Python and requested CPU/CUDA environment. "
+                f"Original import error: {exc}"
+            ) from exc
+
+    device = config["device"]
+    if device.startswith("cuda"):
+        cuda = torch_module.cuda
+        if not cuda.is_available():
+            raise _dependency_error(
+                f"Requested device {device!r}, but CUDA is not available to PyTorch "
+                f"{getattr(torch_module, '__version__', 'unknown')!r}. "
+                "Check the NVIDIA driver and CUDA-enabled PyTorch installation, or explicitly set device='cpu'. "
+                "D4CMPP2 does not switch devices automatically."
+            )
+        index = 0 if device == "cuda" else int(device.split(":", 1)[1])
+        count = cuda.device_count()
+        if index >= count:
+            raise _dependency_error(
+                f"Requested device {device!r}, but PyTorch reports {count} CUDA device(s) "
+                f"with valid indices 0..{count - 1}. Choose an available index or set device='cpu'."
+            )
+    elif config.get("pin_memory", False):
+        warnings.warn(
+            "pin_memory=True was requested with device='cpu'. Pinned host memory normally benefits "
+            "CUDA transfers and may add overhead for CPU-only training; consider pin_memory=False.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    if backend != "pyg":
+        raise ValueError(f"Unknown graph backend {backend!r}; this version supports only 'pyg'.")
+    module_name = "torch_geometric"
+    try:
+        backend_module = importer(module_name)
+    except (ImportError, OSError) as exc:
+        torch_version = getattr(torch_module, "__version__", "unknown")
+        raise _dependency_error(
+            f"Graph backend {backend!r} could not be imported with PyTorch {torch_version!r}. "
+            f"Install compatible torch/{module_name} builds for the same Python and CPU/CUDA environment. "
+            f"Original import error: {exc}"
+        ) from exc
+    return {
+        "torch": str(getattr(torch_module, "__version__", "unknown")),
+        backend: str(getattr(backend_module, "__version__", "unknown")),
+    }
+
+
+def validate_sculptor_index_argument(value):
+    """Validate the legacy tuple form before it is expanded into config keys."""
+    if not isinstance(value, tuple):
+        return
+    if len(value) != 3 or any(
+        isinstance(item, bool) or not isinstance(item, int) or item < 0 for item in value
+    ):
+        raise ValueError(
+            f"sculptor_index must be a tuple of three non-negative integers, got {value!r}. "
+            "Example: sculptor_index=(6, 2, 0)."
+        )
+
+
+def _positive_int(config, key):
+    value = config.get(key)
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise ValueError(f"{key} must be a positive integer, got {value!r} ({_type_name(value)}).")
+
+
+def _non_negative_int(config, key):
+    value = config.get(key)
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        raise ValueError(f"{key} must be a non-negative integer, got {value!r} ({_type_name(value)}).")
+
+
+def _positive_number(config, key):
+    value = config.get(key)
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or value <= 0:
+        raise ValueError(f"{key} must be a positive number, got {value!r} ({_type_name(value)}).")
+
+
+def _non_negative_number(config, key):
+    value = config.get(key)
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or value < 0:
+        raise ValueError(f"{key} must be a non-negative number, got {value!r} ({_type_name(value)}).")
+
+
+def _validate_sculptor_config(config):
+    isa_manager = config.get("data_manager_module") == "ISADataManager"
+    if not isa_manager:
+        return
+
+    keys = ("sculptor_s", "sculptor_c", "sculptor_a")
+    missing = [key for key in keys if key not in config]
+    if missing:
+        original = config.get("sculptor_index")
+        if isinstance(original, list):
+            raise TypeError(
+                f"sculptor_index must be a tuple of three non-negative integers, got list {original!r}. "
+                "Example: sculptor_index=(6, 2, 0)."
+            )
+        raise ValueError(
+            f"ISA network {config.get('network')!r} requires sculptor_index=(split, combine, absorb); "
+            f"missing normalized keys: {missing}. Example: sculptor_index=(6, 2, 0)."
+        )
+
+    invalid = {key: config[key] for key in keys if isinstance(config[key], bool) or not isinstance(config[key], int) or config[key] < 0}
+    if invalid:
+        raise ValueError(
+            f"ISA sculptor values must be non-negative integers, got {invalid!r}. "
+            "Example: sculptor_index=(6, 2, 0)."
+        )

D4CMPP2/src/utils/csv_validation.py

@@ -0,0 +1,105 @@
+"""Dependency-light CSV schema and split validation helpers."""
+
+import math
+
+
+ALLOWED_SET_LABELS = ("train", "val", "test")
+
+
+def validate_csv_schema(path, columns, row_count, molecule_columns, target_columns, numeric_columns):
+    """Validate required columns and basic table shape without mutating data."""
+    if row_count == 0:
+        raise ValueError(
+            f"CSV file {path!r} contains no data rows. Add at least one row and the required columns."
+        )
+
+    groups = {
+        "molecule": list(molecule_columns),
+        "target": list(target_columns),
+        "numeric input": list(numeric_columns),
+    }
+    duplicates = {
+        name: sorted({column for column in requested if requested.count(column) > 1})
+        for name, requested in groups.items()
+    }
+    duplicates = {name: values for name, values in duplicates.items() if values}
+    if duplicates:
+        raise ValueError(
+            f"Duplicate configured CSV columns were found for {path!r}: {duplicates}. "
+            "List each molecule, target, and numeric input column once."
+        )
+
+    available = list(columns)
+    missing = {
+        name: [column for column in requested if column not in available]
+        for name, requested in groups.items()
+    }
+    missing = {name: values for name, values in missing.items() if values}
+    if missing:
+        raise ValueError(
+            f"Required CSV columns were not found in {path!r}: {missing}. "
+            f"Available columns: {available}. Check molecule_columns, target, and "
+            "numeric_input_columns spelling."
+        )
+
+
+def validate_numeric_columns(path, invalid_rows_by_column, kind):
+    """Report non-numeric cells with original row indices."""
+    invalid = {column: list(rows) for column, rows in invalid_rows_by_column.items() if rows}
+    if invalid:
+        raise ValueError(
+            f"{kind} columns in {path!r} contain non-numeric values at row indices: {invalid}. "
+            "Replace those values with numbers or blank/NaN values."
+        )
+
+
+def validate_nonempty_targets(path, all_nan_by_column):
+    """Reject target columns that contain no usable values."""
+    empty = [column for column, all_nan in all_nan_by_column.items() if all_nan]
+    if empty:
+        raise ValueError(
+            f"Target columns {empty} in {path!r} contain only NaN/blank values. "
+            "Provide at least one numeric target value in each target column."
+        )
+
+
+def validate_set_labels(path, values, require_train_val=True):
+    """Validate explicit split labels and return their counts."""
+    labels = list(values)
+    invalid = sorted({repr(value) for value in labels if _is_missing(value) or value not in ALLOWED_SET_LABELS})
+    counts = {label: labels.count(label) for label in ALLOWED_SET_LABELS}
+    if invalid:
+        raise ValueError(
+            f"Column 'set' in {path!r} contains invalid labels {invalid}. "
+            f"Allowed labels: {list(ALLOWED_SET_LABELS)}. Split counts: {counts}."
+        )
+    if require_train_val and (counts["train"] == 0 or counts["val"] == 0):
+        missing = [label for label in ("train", "val") if counts[label] == 0]
+        raise ValueError(
+            f"Column 'set' in {path!r} is missing required split labels {missing}. "
+            f"Split counts: {counts}. Add at least one train and one val row."
+        )
+    return counts
+
+
+def validate_automatic_split_size(path, row_count, minimum=10):
+    """Reject datasets too small for the legacy 80/10/10 automatic split."""
+    if row_count < minimum:
+        raise ValueError(
+            f"Dataset {path!r} has {row_count} usable rows, but automatic splitting requires "
+            f"at least {minimum}. Add rows or provide a 'set' column with train/val labels."
+        )
+
+
+def validate_aligned_lengths(path, lengths):
+    """Assert that extracted CSV arrays still share one row count."""
+    normalized = {name: int(length) for name, length in lengths.items()}
+    if len(set(normalized.values())) > 1:
+        raise ValueError(
+            f"CSV-derived arrays from {path!r} have inconsistent lengths: {normalized}. "
+            "Check that all molecule, numeric input, target, and set values use the same rows."
+        )
+
+
+def _is_missing(value):
+    return value is None or (isinstance(value, float) and math.isnan(value))

D4CMPP2/src/utils/data_quality.py

@@ -0,0 +1,181 @@
+"""Non-mutating data quality summaries for molecular CSV inputs."""
+
+import json
+import os
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+import pandas as pd
+from rdkit import Chem
+
+
+REPORT_SCHEMA_VERSION = 1
+
+
+def _canonical_smiles(value):
+    if pd.isna(value) or not str(value).strip():
+        return None, "empty_smiles"
+    molecule = Chem.MolFromSmiles(str(value))
+    if molecule is None:
+        return None, "invalid_smiles"
+    return Chem.MolToSmiles(molecule, canonical=True), None
+
+
+def _target_summary(frame, targets):
+    result = {}
+    for target in targets:
+        if target not in frame:
+            result[target] = {"missing_column": True}
+            continue
+        numeric = pd.to_numeric(frame[target], errors="coerce")
+        usable = numeric.dropna()
+        result[target] = {
+            "count": int(len(numeric)),
+            "usable_count": int(usable.size),
+            "missing_count": int(numeric.isna().sum()),
+            "min": float(usable.min()) if not usable.empty else None,
+            "max": float(usable.max()) if not usable.empty else None,
+            "mean": float(usable.mean()) if not usable.empty else None,
+            "std": float(usable.std()) if usable.size > 1 else None,
+        }
+    return result
+
+
+def build_data_quality_report(frame, config, graph_errors=None):
+    """Build summary and issue rows without changing the input DataFrame."""
+    molecule_columns = list(config.get("molecule_columns", ["compound"]))
+    targets = list(config.get("target", []))
+    issues = []
+    canonical_columns = {}
+
+    for column in molecule_columns:
+        if column not in frame:
+            issues.append({
+                "issue": "missing_molecule_column",
+                "row_index": None,
+                "column": column,
+                "value": None,
+                "detail": "Configured molecule column is absent.",
+            })
+            continue
+        canonical = []
+        for row_index, value in frame[column].items():
+            normalized, issue = _canonical_smiles(value)
+            canonical.append(normalized)
+            if issue:
+                issues.append({
+                    "issue": issue,
+                    "row_index": row_index,
+                    "column": column,
+                    "value": None if pd.isna(value) else str(value),
+                    "detail": "RDKit could not produce a canonical molecule." if issue == "invalid_smiles" else "SMILES is empty.",
+                })
+        canonical_columns[column] = pd.Series(canonical, index=frame.index)
+
+    signature = None
+    if len(canonical_columns) == len(molecule_columns):
+        signature_frame = pd.DataFrame(canonical_columns)
+        valid_signature = signature_frame.notna().all(axis=1)
+        signature = signature_frame.astype(str).agg("||".join, axis=1).where(valid_signature)
+        duplicate_mask = signature.notna() & signature.duplicated(keep=False)
+        for row_index in frame.index[duplicate_mask]:
+            issues.append({
+                "issue": "duplicate_molecule",
+                "row_index": row_index,
+                "column": "|".join(molecule_columns),
+                "value": signature.loc[row_index],
+                "detail": "Canonical molecule input appears in multiple rows.",
+            })
+
+        if "set" in frame:
+            grouped = pd.DataFrame({"signature": signature, "set": frame["set"]}).dropna()
+            overlap = grouped.groupby("signature")["set"].agg(lambda values: sorted(set(values)))
+            for molecule, labels in overlap.items():
+                if len(labels) > 1:
+                    issues.append({
+                        "issue": "split_molecule_overlap",
+                        "row_index": None,
+                        "column": "set",
+                        "value": molecule,
+                        "detail": f"Canonical molecule occurs across splits {labels}.",
+                    })
+
+    for target in targets:
+        if target not in frame:
+            continue
+        numeric = pd.to_numeric(frame[target], errors="coerce")
+        for row_index in frame.index[numeric.isna()]:
+            issues.append({
+                "issue": "missing_target",
+                "row_index": row_index,
+                "column": target,
+                "value": None if pd.isna(frame.at[row_index, target]) else str(frame.at[row_index, target]),
+                "detail": "Target is blank, NaN, or non-numeric.",
+            })
+        if signature is not None:
+            grouped = pd.DataFrame({"signature": signature, "target": numeric}).dropna()
+            conflicts = grouped.groupby("signature")["target"].nunique()
+            for molecule in conflicts[conflicts > 1].index:
+                issues.append({
+                    "issue": "conflicting_duplicate_target",
+                    "row_index": None,
+                    "column": target,
+                    "value": molecule,
+                    "detail": "Duplicate canonical molecule has differing target values.",
+                })
+
+    for error in graph_errors or []:
+        issues.append({
+            "issue": "graph_generation_failure",
+            "row_index": error.get("row_index"),
+            "column": error.get("type"),
+            "value": str(error.get("smiles")),
+            "detail": str(error.get("reason")),
+        })
+
+    issue_counts = {}
+    for issue in issues:
+        issue_counts[issue["issue"]] = issue_counts.get(issue["issue"], 0) + 1
+    split_counts = (
+        {str(key): int(value) for key, value in frame["set"].value_counts(dropna=False).items()}
+        if "set" in frame else {"automatic": int(len(frame))}
+    )
+    report = {
+        "report_schema_version": REPORT_SCHEMA_VERSION,
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "data_path": str(config.get("DATA_PATH", "")),
+        "row_count": int(len(frame)),
+        "molecule_columns": molecule_columns,
+        "target_columns": targets,
+        "split_counts": split_counts,
+        "target_summary": _target_summary(frame, targets),
+        "issue_counts": issue_counts,
+        "issue_count": len(issues),
+    }
+    return report, pd.DataFrame(
+        issues,
+        columns=["issue", "row_index", "column", "value", "detail"],
+    )
+
+
+def write_data_quality_report(frame, config, graph_errors=None):
+    """Atomically write JSON summary and issue CSV; return both paths."""
+    model_path = Path(config["MODEL_PATH"])
+    model_path.mkdir(parents=True, exist_ok=True)
+    report, issues = build_data_quality_report(frame, config, graph_errors)
+    json_path = model_path / "data_quality_report.json"
+    csv_path = model_path / "data_quality_issues.csv"
+    token = uuid.uuid4().hex
+    json_staging = json_path.with_name(f".{json_path.name}.{token}.tmp")
+    csv_staging = csv_path.with_name(f".{csv_path.name}.{token}.tmp")
+    try:
+        json_staging.write_text(json.dumps(report, indent=2, sort_keys=True), encoding="utf-8")
+        issues.to_csv(csv_staging, index=False)
+        os.replace(json_staging, json_path)
+        os.replace(csv_staging, csv_path)
+    finally:
+        for staging in (json_staging, csv_staging):
+            if staging.exists():
+                staging.unlink()
+    return json_path, csv_path