Error-handling sweep: crash/logic bug fixes, ERROR-token crash logging, shared helpers

[ggmarshall]

Systematic bug-fix and error-handling sweep across the package, following the same review recently applied to legend-dataflow.

Crash bugs

• par-geds-hit-aoe crashed with NameError on every run without --override-files; same undefined-in-branch class in hit/ecal.py (hit_dict/in_results_dict without --in-hit-dict) and dsp/eopt.py (optimiser plot objects when run_eopt: false).
• hit/qc.py crashed for any channel with <4000 clean events (rng.choice(..., replace=False)).
• hit/ecal.py guess-offset lookup subscripted a string default (.get(key, "fallback")["parameters"]) — the default is a fallback key into hit_dict.
• build-tier-hit-single-channel passed an empty {} to build_hit and discarded the computed config (silently useless output); it now passes hit_config=hit_cfg and extracts ["pars"] like the multi-channel path.
• --table-map (build-tier-dsp/hit) and --qbb-grid-path (par-geds-dsp-eopt) are now required=True — the rules always pass them and omitting them crashed with TypeError.
• dataflow -v with no subcommand raised AttributeError; it now prints help and exits 1.
• cfgtools.get_channel_config evaluated the __default__ lookup eagerly, raising KeyError even when the channel was present.
• filedb.py ran scan_files twice, with the second call outside the error-context wrapper.

Wrong results

• hit/ecal.py get_median/get_err had inverted conditions — they returned NaN for well-populated time bins and values for near-empty ones, effectively blanking pulser-stability monitoring.
• alias_table tested struct membership by substring, so adding an alias whose name is a substring of an existing field (e.g. raw next to raw_blind) silently skipped the datatype registration.
• as_ro on Path inputs returned only the rewritten basename, dropping all directory components.
• hit/lq.py results are now stored per timestamp, mirroring hit/aoe.py.

Logging: crashes now reach log files as ERROR records

build_log's excepthook wrote raw tracebacks via traceback.print_exception to a handler stream discovered from the named logger — which has no handlers of its own in the dictConfig path (the FileHandler sits on root), so uncaught tracebacks fell back to stdout and never reached the per-job log file; even when they did, they carried no ERROR token for downstream log scanning. The excepthook now emits log.error("uncaught exception", exc_info=...) (formatted, severity-tagged, propagates to the root FileHandler), delegates KeyboardInterrupt to the default hook, and the fallback logger name is honoured in the dictConfig branch.

New shared helpers (legenddataflowscripts.utils)

expand_filelist, check_pulser_mask, require_config_keys, get_rule_config, and the fixed get_channel_config (now with an optional name= for error context). Adopted across the hit/dsp scripts: filelist arguments fail with named errors on empty/missing input, every mask[threshold_mask] is preceded by a length check that names the table and suggests mismatched pulser/input filelists, and the run_*/calibration config contracts are validated up front naming the channel and config file. These helpers are also intended to replace the duplicated copies in legend-dataflow (companion change there; its pin will need a bump to the next release).

Tests (18 → 49)

• Console-script smoke test: imports every [project.scripts] entry point and runs --help (17 scripts) — catches broken imports, entry-point typos, and argparse regressions.
• Unit tests for all new error paths: helper behaviors, the get_channel_config eager-default regression, as_ro Path regression, dataflow no-subcommand, alias_table membership on a synthetic HDF5 file, and the build_log excepthook (asserts the ERROR record + traceback lands in the log file).

Noted, not changed

• eval() of config strings in aoe/lq/ecal/dplms/eopt — replacing these needs a whitelist built from the names production configs actually use; follow-up.
• CLI contract note: aoe/lq/ecal previously treated files[0] as a filelist unconditionally; with expand_filelist a single argument is only expanded when it has a .filelist suffix (the Snakemake rules always pass .filelist paths).

Verification

• pytest: 49 passed (warnings-as-errors)
• ruff check / ruff format --check: clean
• dataflow -v: prints help, exits 1, no traceback

---

Per AI_POLICY.md: this contribution was drafted with AI assistance (Claude Code) and reviewed by the submitter.

🤖 Generated with Claude Code