Improve config discovery and scorer resolution

Centralize and harden config.yaml discovery and scorer resolution across the plugin. Key changes:
- Prefer find_nearest_config for automatic config lookup and switch core/io to use it when loading colormap for HDF files.
- Remove legacy misc.find_project_config_path and provenance.find_config_scorer_nearby; provenance now imports find_nearest_config.
- Overhauled the save flow in KeypointControls: auto-load scorer from an auto-discovered config, present a project-config chooser when no config is found, validate unreadable/missing scorers, fall back to sidecar or manual prompt only when appropriate, and persist sidecar defaults when possible.
- Add UI dialog helpers in ui/dialogs.py: load_scorer_from_config, warn_invalid_config_for_scorer, and extend prompt_for_project_config_for_save to optionally resolve and return a scorer.
- Add module-level note in _widgets.py recommending future refactors to keep the file small.

These changes make project association and scorer selection more robust and user-friendly, add clearer warnings for invalid configs, and consolidate config lookup logic.

Author: C-Achard

src/napari_deeplabcut/_widgets.py

@@ -1,4 +1,13 @@
-"""Main widget and controls for napari-deeplabcut, including the tutorial and shortcuts windows."""
+"""Main widget and controls for napari-deeplabcut, including the tutorial and shortcuts windows.
+
+NOTE: This file is generally already too long. For future development, please consider:
+- Moving existing responsibilities out into separate modules (existing or new)
+- Avoiding adding anything that is not strictly related to :
+  - Building the final UI (blocks can be moved to ui/ for better organization)
+  - Wiring to the core plugin functionality (e.g. via signals/slots, method calls, etc.)
+  - Anything that requires the full widget+viewer+signal/event context to function properly
+  - Similarly, test_widgets.py is a bit of a default drawer right now, please create new tests in _tests/ui
+"""
 
 # src/napari_deeplabcut/_widgets.py
 from __future__ import annotations
@@ -79,7 +88,7 @@
 )
 from napari_deeplabcut.core.provenance import (
     apply_gt_save_target,
-    find_config_scorer_nearby,
+    find_nearest_config,
     is_projectless_folder_association_candidate,
     requires_gt_promotion,
     suggest_human_placeholder,
@@ -1447,31 +1456,89 @@ def _ensure_promotion_save_target(self, layer: Points) -> bool:
             QMessageBox.warning(self, "Cannot save", "Could not determine a folder anchor for saving.")
             return False
 
-        scorer = find_config_scorer_nearby(anchor) or get_default_scorer(anchor)
-        if not scorer:
-            suggested = suggest_human_placeholder(anchor)
-            while True:
-                s = _prompt_for_scorer(self, anchor=anchor, suggested=suggested)
-                if s is None:
-                    return False
-                if s.startswith("human_"):
-                    choice = QMessageBox.question(
-                        self,
-                        "Generic scorer name",
-                        "You entered a generic scorer name starting with 'human_'.\n\n"
-                        "We strongly recommend using a real name or stable identifier.\n"
-                        "Do you want to keep this generic scorer anyway?",
-                        QMessageBox.Yes | QMessageBox.No,
-                    )
-                    if choice == QMessageBox.No:
-                        suggested = s
-                        continue
-                scorer = s
-                break
+        scorer = None
+
+        # 1) Auto-discovered config.yaml always wins
+        cfg_path = None
+        try:
+            cfg_path = find_nearest_config(anchor)
+        except Exception:
+            logger.debug("Automatic config discovery failed for anchor=%r", anchor, exc_info=True)
+
+        if cfg_path:
             try:
-                set_default_scorer(anchor, scorer)
+                scorer = ui_dialogs.load_scorer_from_config(cfg_path)
             except Exception:
-                logger.debug("Failed to persist default scorer to sidecar", exc_info=True)
+                logger.exception("Failed to load auto-discovered config.yaml: %s", cfg_path)
+                ui_dialogs.warn_invalid_config_for_scorer(
+                    self,
+                    config_path=cfg_path,
+                    reason="unreadable",
+                    auto_found=True,
+                )
+                return False
+
+            if not scorer:
+                ui_dialogs.warn_invalid_config_for_scorer(
+                    self,
+                    config_path=cfg_path,
+                    reason="missing_scorer",
+                    auto_found=True,
+                )
+                return False
+
+        else:
+            # 2) No config found automatically -> let the user choose one
+            dialog_result = ui_dialogs.prompt_for_project_config_for_save(
+                self,
+                initial_dir=self._project_path or anchor,
+                window_title="Locate DLC config for scorer resolution",
+                message=(
+                    "No DeepLabCut config.yaml could be found automatically for this machine-labeled layer.\n\n"
+                    "If this layer belongs to a DLC project, choose its config.yaml so the save uses the "
+                    "project scorer and standard naming.\n\n"
+                    "If no config.yaml exists, you can continue without one."
+                ),
+                choose_button_text="Choose config.yaml",
+                skip_button_text="Continue without config",
+                resolve_scorer=True,
+            )
+
+            if dialog_result.action is ui_dialogs.ProjectConfigPromptAction.CANCEL:
+                return False
+
+            if dialog_result.action is ui_dialogs.ProjectConfigPromptAction.ASSOCIATE:
+                scorer = dialog_result.scorer
+
+            else:
+                # 3) Only if no config is available at all may sidecar be consulted
+                scorer = get_default_scorer(anchor)
+
+                # 4) Final fallback: prompt manually
+                if not scorer:
+                    suggested = suggest_human_placeholder(anchor)
+                    while True:
+                        s = _prompt_for_scorer(self, anchor=anchor, suggested=suggested)
+                        if s is None:
+                            return False
+                        if s.startswith("human_"):
+                            choice = QMessageBox.question(
+                                self,
+                                "Generic scorer name",
+                                "You entered a generic scorer name starting with 'human_'.\n\n"
+                                "We strongly recommend using a real name or stable identifier.\n"
+                                "Do you want to keep this generic scorer anyway?",
+                                QMessageBox.Yes | QMessageBox.No,
+                            )
+                            if choice == QMessageBox.No:
+                                suggested = s
+                                continue
+                        scorer = s
+                        break
+                    try:
+                        set_default_scorer(anchor, scorer)
+                    except Exception:
+                        logger.debug("Failed to persist default scorer to sidecar", exc_info=True)
 
         updated = apply_gt_save_target(
             pts,

src/napari_deeplabcut/core/io.py

@@ -48,7 +48,11 @@
 from napari_deeplabcut.core.errors import AmbiguousSaveError, MissingProvenanceError
 from napari_deeplabcut.core.layers import populate_keypoint_layer_properties
 from napari_deeplabcut.core.metadata import attach_source_and_io_to_layer_kwargs, parse_points_metadata
-from napari_deeplabcut.core.project_paths import canonicalize_path, infer_dlc_project_from_points_meta
+from napari_deeplabcut.core.project_paths import (
+    canonicalize_path,
+    find_nearest_config,
+    infer_dlc_project_from_points_meta,
+)
 from napari_deeplabcut.core.provenance import resolve_output_path_from_metadata
 
 logger = logging.getLogger(__name__)
@@ -135,7 +139,7 @@ def read_hdf_single(file: Path, *, kind: AnnotationKind | None = None) -> list[L
     # Handle legacy/single-animal column layout by inserting empty "individuals" level.
     # Colormap selection also falls back to config when possible.
     try:
-        cfg = load_config(misc.find_project_config_path(str(file)))
+        cfg = load_config(find_nearest_config(file, max_levels=3))
         config_colormap = str(cfg.get("colormap", DEFAULT_SINGLE_ANIMAL_CMAP))
     except Exception as e:
         logger.warning("Could not load config for %s; falling back to default colormap. Error: %s", file, e)

src/napari_deeplabcut/core/provenance.py

@@ -7,35 +7,20 @@
 
 from pydantic import ValidationError
 
-import napari_deeplabcut.core.io as io
-from napari_deeplabcut import misc
 from napari_deeplabcut.config.models import AnnotationKind, IOProvenance, PointsMetadata
 from napari_deeplabcut.core.errors import MissingProvenanceError, UnresolvablePathError
 from napari_deeplabcut.core.metadata import parse_points_metadata
-from napari_deeplabcut.core.project_paths import infer_dlc_project_from_points_meta, is_windows_absolute_path
+from napari_deeplabcut.core.project_paths import (
+    infer_dlc_project_from_points_meta,
+    is_windows_absolute_path,
+)
 
 logger = logging.getLogger(__name__)
 
 
 # ----------------------------------------
 # Helper functions
 # ----------------------------------------
-def find_config_scorer_nearby(anchor: str) -> str | None:
-    """
-    Best-effort lookup of DLC config.yaml scorer near a folder anchor.
-    """
-    try:
-        cfg_path = misc.find_project_config_path(anchor)
-        if cfg_path:
-            cfg = io.load_config(cfg_path)
-            scorer = cfg.get("scorer")
-            if isinstance(scorer, str) and scorer.strip():
-                return scorer.strip()
-    except Exception:
-        pass
-    return None
-
-
 def suggest_human_placeholder(anchor: str) -> str:
     """
     Deterministic fallback scorer placeholder derived from anchor path.

src/napari_deeplabcut/misc.py

@@ -5,7 +5,6 @@
 from collections.abc import Sequence
 from enum import Enum, EnumMeta
 from itertools import cycle
-from pathlib import Path
 from typing import Protocol
 
 import numpy as np
@@ -24,10 +23,6 @@ def bodyparts(self) -> list[str]: ...
     def individuals(self) -> list[str]: ...
 
 
-def find_project_config_path(labeled_data_path: str) -> str:
-    return str(Path(labeled_data_path).parents[2] / "config.yaml")
-
-
 @deprecated(
     since="napari-deeplabcut>0.2.1.8, DLC>3.0.0rc14",
     mode=DeprecationMode.WARN,

src/napari_deeplabcut/ui/dialogs.py

@@ -26,6 +26,7 @@
     QWidget,
 )
 
+import napari_deeplabcut.core.io as io
 from napari_deeplabcut.config.keybinds import iter_shortcuts
 from napari_deeplabcut.config.settings import get_overwrite_confirmation_enabled
 from napari_deeplabcut.core.conflicts import OverwriteConflictReport
@@ -483,38 +484,96 @@ class ProjectConfigPromptAction(str, Enum):
 class ProjectConfigPromptResult:
     action: ProjectConfigPromptAction
     config_path: str | None = None
+    scorer: str | None = None
+
+
+def load_scorer_from_config(config_path: str | Path) -> str | None:
+    """Return the non-empty DLC scorer from a config.yaml, if present."""
+    cfg = io.load_config(str(config_path))
+    scorer = cfg.get("scorer") if isinstance(cfg, dict) else None
+    if isinstance(scorer, str) and scorer.strip():
+        return scorer.strip()
+    return None
+
+
+def warn_invalid_config_for_scorer(
+    parent,
+    *,
+    config_path: str | Path,
+    reason: str = "missing_scorer",
+    auto_found: bool = False,
+) -> None:
+    """Explain why a config.yaml cannot be used to resolve a scorer."""
+    config_path = str(config_path)
+
+    if reason == "unreadable":
+        if auto_found:
+            text = (
+                "A DeepLabCut config.yaml was found automatically, but it could not be read:\n\n"
+                f"{config_path}\n\n"
+                "Please fix the file or choose another config.yaml."
+            )
+        else:
+            text = f"The selected file could not be read as a DeepLabCut config.yaml:\n\n{config_path}"
+    else:
+        if auto_found:
+            text = (
+                "A DeepLabCut config.yaml was found automatically, but its 'scorer' field is missing or empty:\n\n"
+                f"{config_path}\n\n"
+                "Please fix the config.yaml scorer or choose another valid project configuration."
+            )
+        else:
+            text = f"The selected config.yaml does not define a valid non-empty 'scorer' field:\n\n{config_path}"
+
+    QMessageBox.warning(parent, "Invalid project configuration", text)
 
 
 def prompt_for_project_config_for_save(
     parent,
     *,
     initial_dir: str | None = None,
+    window_title: str = "Associate folder with DLC project?",
+    message: str | None = None,
+    choose_button_text: str = "Choose config.yaml",
+    skip_button_text: str = "Continue without association",
+    resolve_scorer: bool = False,
 ) -> ProjectConfigPromptResult:
     """
     Ask the user whether to associate the current labeled folder with an
-    existing DLC project.
+    existing DLC project, optionally resolving a scorer from the selected config.
 
     Returns
     -------
     ProjectConfigPromptResult
         - ASSOCIATE: user selected a config.yaml
         - SKIP: user explicitly chose not to associate, but wants to continue
         - CANCEL: user cancelled the flow and the caller should abort save
+
+    Notes
+    -----
+    If resolve_scorer=True:
+    - the selected config.yaml is loaded immediately
+    - its scorer is validated
+    - the returned result includes `scorer`
+    - invalid/unreadable config files are warned about and the flow is cancelled
     """
     msg = QMessageBox(parent)
     msg.setIcon(QMessageBox.Question)
-    msg.setWindowTitle("Associate folder with DLC project?")
+    msg.setWindowTitle(window_title)
     msg.setText(
-        "No DLC project root could be inferred for this layer.\n\n"
-        "Do you want to choose a config.yaml so this labeled folder can be saved "
-        "using DeepLabCut's standard dataset paths?\n\n"
-        "Important: the current folder name will become the DLC dataset name:\n"
-        "labeled-data/<current-folder-name>/...\n\n"
-        "This will not move files on disk or edit config.yaml."
+        message
+        or (
+            "No DLC project root could be inferred for this layer.\n\n"
+            "Do you want to choose a config.yaml so this labeled folder can be saved "
+            "using DeepLabCut's standard dataset paths?\n\n"
+            "Important: the current folder name will become the DLC dataset name:\n"
+            "labeled-data/<current-folder-name>/...\n\n"
+            "This will not move files on disk or edit config.yaml."
+        )
     )
 
-    yes_btn = msg.addButton("Choose config.yaml", QMessageBox.YesRole)
-    no_btn = msg.addButton("Continue without association", QMessageBox.NoRole)
+    yes_btn = msg.addButton(choose_button_text, QMessageBox.YesRole)
+    no_btn = msg.addButton(skip_button_text, QMessageBox.NoRole)
     msg.addButton(QMessageBox.Cancel)
 
     msg.setDefaultButton(yes_btn)
@@ -538,9 +597,32 @@ def prompt_for_project_config_for_save(
     if not filename:
         return ProjectConfigPromptResult(ProjectConfigPromptAction.CANCEL)
 
+    scorer = None
+    if resolve_scorer:
+        try:
+            scorer = load_scorer_from_config(filename)
+        except Exception:
+            warn_invalid_config_for_scorer(
+                parent,
+                config_path=filename,
+                reason="unreadable",
+                auto_found=False,
+            )
+            return ProjectConfigPromptResult(ProjectConfigPromptAction.CANCEL)
+
+        if not scorer:
+            warn_invalid_config_for_scorer(
+                parent,
+                config_path=filename,
+                reason="missing_scorer",
+                auto_found=False,
+            )
+            return ProjectConfigPromptResult(ProjectConfigPromptAction.CANCEL)
+
     return ProjectConfigPromptResult(
         ProjectConfigPromptAction.ASSOCIATE,
         config_path=filename,
+        scorer=scorer,
     )