clearer self-test error messages

Author: InertSloth

ROADMAP.md

@@ -37,10 +37,6 @@ API
   - [ ] can utils/config be made into a single submodule? how does that play with the bundler?
   - [ ] do we want a way to dump the schema for documentation purposes?
 
-utils
-  - [ ] do things that call is_excluded need to check if root exists?
-  - [ ] improve the self-test to give specific errors along the way
-
 config_validate
   - [ ] key in wrong place: "Ignored watch_interval in build #0: applies only at root level (move it above your builds: block)." could use `ROOT_ONLY_HINTS = {"watch_interval": "move it above your builds list"}`
   - [ ] type examples for _infer_type_label(), TYPE_EXAMPLES, "key 'include' expected list[str], got int" could add "expected list[str] (e.g. ["src/", "lib/"]), got int"

src/pocket_build/actions.py

@@ -196,66 +196,92 @@ def get_metadata() -> Metadata:
     return Metadata(version, commit)
 
 
-def run_selftest() -> bool:
+def run_selftest() -> bool:  #  noqa: PLR0915
     """Run a lightweight functional test of the tool itself."""
     logger = get_logger()
     logger.info("🧪 Running self-test...")
 
+    start_time = time.time()
     tmp_dir: Path | None = None
+
     try:
         tmp_dir = Path(tempfile.mkdtemp(prefix=f"{PROGRAM_SCRIPT}-selftest-"))
         src = tmp_dir / "src"
         out = tmp_dir / "out"
         src.mkdir()
 
-        # Create a tiny file to copy
+        logger.debug("[SELFTEST] Temp dir: %s", tmp_dir)
+
+        # --- Phase 1: Create input file ---
+        test_msg = f"hello {PROGRAM_DISPLAY}!"
         file = src / "hello.txt"
-        file.write_text(f"hello {PROGRAM_DISPLAY}!", encoding="utf-8")
-
-        # --- Construct minimal BuildConfigResolved using helpers ---
-        build_cfg: BuildConfigResolved = {
-            "include": [make_includeresolved(str(src / "**"), tmp_dir, "code")],
-            "exclude": [],
-            "out": make_pathresolved(out, tmp_dir, "code"),
-            "respect_gitignore": False,
-            "log_level": "info",
-            "dry_run": False,
-            "__meta__": {"cli_root": tmp_dir, "config_root": tmp_dir},
-        }
+        file.write_text(test_msg, encoding="utf-8")
+        # file_write should raise an exception on failure making this check unnecesary
+        if not file.exists():
+            xmsg = f"Input file creation failed: {file}"
+            raise RuntimeError(xmsg)  # noqa: TRY301
+        logger.debug("[SELFTEST] Created input file: %s", file)
+
+        # --- Phase 2: Prepare config ---
+        try:
+            build_cfg: BuildConfigResolved = {
+                "include": [make_includeresolved(str(src / "**"), tmp_dir, "code")],
+                "exclude": [],
+                "out": make_pathresolved(out, tmp_dir, "code"),
+                "respect_gitignore": False,
+                "log_level": "info",
+                "dry_run": False,
+                "__meta__": {"cli_root": tmp_dir, "config_root": tmp_dir},
+            }
+        except Exception as e:
+            xmsg = f"Config construction failed: {e}"
+            raise RuntimeError(xmsg) from e
 
         logger.debug("[SELFTEST] using temp dir: %s", tmp_dir)
 
-        # --- Run the build directly ---
+        # --- Phase 3: Execute build (both dry and real) ---
         for dry_run in (True, False):
             build_cfg["dry_run"] = dry_run
-            run_build(build_cfg)
-
-        # Verify file copy
+            logger.debug("[SELFTEST] Running build (dry_run=%s)", dry_run)
+            try:
+                run_build(build_cfg)
+            except Exception as e:
+                xmsg = f"Build execution failed (dry_run={dry_run}): {e}"
+                raise RuntimeError(xmsg) from e
+
+        # --- Phase 4: Validate results ---
         copied = out / "hello.txt"
-        if (
-            copied.exists()
-            and copied.read_text().strip() == f"hello {PROGRAM_DISPLAY}!"
-        ):
-            logger.info(
-                "✅ Self-test passed — %s is working correctly.", PROGRAM_DISPLAY
-            )
-            return True
-
-        logger.error("Self-test failed: output file not found or invalid.")
+        if not copied.exists():
+            xmsg = f"Expected output file missing: {copied}"
+            raise RuntimeError(xmsg)  # noqa: TRY301
+
+        actual = copied.read_text(encoding="utf-8").strip()
+        if actual != test_msg:
+            xmsg = f"Output content mismatch: got '{actual}', expected '{test_msg}'"
+            raise AssertionError(xmsg)  # noqa: TRY301
+
+        elapsed = time.time() - start_time
+        logger.info(
+            "✅ Self-test passed in %.2fs — %s is working correctly.",
+            elapsed,
+            PROGRAM_DISPLAY,
+        )
+        return True
+
+    except (PermissionError, FileNotFoundError) as e:
+        logger.error_if_not_debug("Self-test failed due to environment issue: %s", e)
         return False
 
-    except PermissionError:
-        logger.error("Self-test failed: insufficient permissions.")  # noqa: TRY400
+    except RuntimeError as e:
+        logger.error_if_not_debug("Self-test failed: %s", e)
         return False
-    except FileNotFoundError:
-        logger.error("Self-test failed: missing file or directory.")  # noqa: TRY400
+
+    except AssertionError as e:
+        logger.error_if_not_debug("Self-test failed validation: %s", e)
         return False
+
     except Exception:
-        # Unexpected bug — show traceback and ask for a bug report
-        logger.exception(
-            "Unexpected self-test failure. "
-            "Please report this issue with the following traceback:"
-        )
+        logger.exception("Unexpected self-test failure. Please report this traceback:")
         return False
 
     finally:

src/pocket_build/build.py

@@ -201,15 +201,15 @@ def copy_item(
     """Copy one file or directory entry, using built-in root info."""
     logger = get_logger()
     src = Path(src_entry["path"])
-    root_src = Path(src_entry["root"]).resolve()
-    src = (root_src / src).resolve() if not src.is_absolute() else src.resolve()
+    src_root = Path(src_entry["root"]).resolve()
+    src = (src_root / src).resolve() if not src.is_absolute() else src.resolve()
     dest = Path(dest_entry["path"])
-    root_dest = (dest_entry["root"]).resolve()
-    dest = (root_dest / dest).resolve() if not dest.is_absolute() else dest.resolve()
+    dest_root = (dest_entry["root"]).resolve()
+    dest = (dest_root / dest).resolve() if not dest.is_absolute() else dest.resolve()
     origin = src_entry.get("origin", "?")
 
     # Combine output directory with the precomputed dest (if relative)
-    dest = dest if dest.is_absolute() else (root_dest / dest)
+    dest = dest if dest.is_absolute() else (dest_root / dest)
 
     exclude_patterns_raw = [str(e["path"]) for e in exclude_patterns]
     pattern_str = str(src_entry.get("pattern", src_entry["path"]))
@@ -220,8 +220,8 @@ def copy_item(
     )
 
     # Exclusion check relative to its root
-    if is_excluded_raw(src, exclude_patterns_raw, root_src):
-        logger.debug("🚫  Skipped (excluded): %s", src.relative_to(root_src))
+    if is_excluded_raw(src, exclude_patterns_raw, src_root):
+        logger.debug("🚫  Skipped (excluded): %s", src.relative_to(src_root))
         return
 
     # Detect shallow single-star pattern
@@ -233,7 +233,7 @@ def copy_item(
     #  — copy only the directory itself, not its contents
     if src.is_dir() and is_shallow_star:
         logger.trace(
-            f"📁 (shallow from pattern={pattern_str!r}) {src.relative_to(root_src)}",
+            f"📁 (shallow from pattern={pattern_str!r}) {src.relative_to(src_root)}",
         )
         if not dry_run:
             dest.mkdir(parents=True, exist_ok=True)
@@ -245,14 +245,14 @@ def copy_item(
             src,
             dest,
             exclude_patterns_raw,
-            src_root=root_src,
+            src_root=src_root,
             dry_run=dry_run,
         )
     else:
         copy_file(
             src,
             dest,
-            src_root=root_src,
+            src_root=src_root,
             dry_run=dry_run,
         )
 

src/pocket_build/cli.py

@@ -319,20 +319,15 @@ def main(argv: list[str] | None = None) -> int:  # noqa: C901, PLR0911, PLR0912,
         silent = getattr(e, "silent", False)
         if not silent:
             try:
-                logger.error(str(e))  # noqa: TRY400
+                logger.error_if_not_debug(str(e))
             except Exception:  # noqa: BLE001
                 safe_log(f"[FATAL] Logging failed while reporting: {e}")
         return getattr(e, "code", 1)
 
     except Exception as e:  # noqa: BLE001
         # unexpected internal error
         try:
-            if logger.level_name in {"DEBUG", "TRACE"}:  # how to get the name?
-                # Show traceback only in verbose/debug modes
-                logger.exception("Unexpected internal error:")
-            else:
-                # Just a one-line summary for normal users
-                logger.critical("Unexpected internal error: %s", e)
+            logger.critical_if_not_debug("Unexpected internal error: %s", e)
         except Exception:  # noqa: BLE001
             safe_log(f"[FATAL] Logging failed while reporting: {e}")
 

src/pocket_build/utils.py

@@ -231,6 +231,10 @@ def is_excluded_raw(  # noqa: PLR0911
     - Treats 'path' as relative to 'root' unless already absolute.
     - If 'root' is a file, match directly.
     - Handles absolute or relative glob patterns.
+
+    Note:
+    The function does not require `root` to exist; if it does not,
+    a debug message is logged and matching is purely path-based.
     """
     logger = get_logger()
     root = Path(root).resolve()

src/pocket_build/utils_logs.py

@@ -84,13 +84,13 @@ def safe_log(msg: str) -> None:
 
 
 def make_test_trace(icon: str = "🧰") -> Callable[..., Any]:
-    def local_trace(label: str, *args: object) -> Any:
+    def local_trace(label: str, *args: Any) -> Any:
         return TEST_TRACE(label, *args, icon=icon)
 
     return local_trace
 
 
-def TEST_TRACE(label: str, *args: object, icon: str = "🧰") -> None:  # noqa: N802
+def TEST_TRACE(label: str, *args: Any, icon: str = "🧰") -> None:  # noqa: N802
     """Emit a synchronized, flush-safe diagnostic line.
 
     Args:
@@ -245,6 +245,26 @@ def level_name(self) -> str:
         (see also: logging.getLevelName)."""
         return logging.getLevelName(self.getEffectiveLevel())
 
+    def error_if_not_debug(self, msg: str, *args: Any, **kwargs: Any) -> None:
+        """Logs an exception with the real traceback starting from the caller.
+        Only shows full traceback if debug/trace is enabled."""
+        exc_info = kwargs.pop("exc_info", True)
+        stacklevel = kwargs.pop("stacklevel", 2)  # skip helper frame
+        if self.isEnabledFor(logging.DEBUG):
+            self.exception(msg, *args, exc_info=exc_info, stacklevel=stacklevel)
+        else:
+            self.error(msg, *args)
+
+    def critical_if_not_debug(self, msg: str, *args: Any, **kwargs: Any) -> None:
+        """Logs an exception with the real traceback starting from the caller.
+        Only shows full traceback if debug/trace is enabled."""
+        exc_info = kwargs.pop("exc_info", True)
+        stacklevel = kwargs.pop("stacklevel", 2)  # skip helper frame
+        if self.isEnabledFor(logging.DEBUG):
+            self.exception(msg, *args, exc_info=exc_info, stacklevel=stacklevel)
+        else:
+            self.critical(msg, *args)
+
     def colorize(
         self, text: str, color: str, *, enable_color: bool | None = None
     ) -> str:

tests/utils/proj_root.py

@@ -3,4 +3,4 @@
 from pathlib import Path
 
 
-PROJ_ROOT = Path(__file__).resolve().parent.parent.parent
+PROJ_ROOT = Path(__file__).resolve().parent.parent.parent.resolve()