pj
b44077afde
* refactor: rename inspect to replay across the codebase Renames inspect-ui/ to replay-ui/, internal/inspect/ to internal/replay/, the CLI subcommand from `sanderling inspect` to `sanderling replay`, and updates all references in docs, Makefile, README, and Go comments. * feat(replay-ui): show spec filename with full path on hover RunList and RunDetail now render the basename of spec_path (e.g. login.spec.ts) with the full path available as a title tooltip.
2.8 KiB
title
| title |
|---|
| Decisions |
Decisions
Architectural and organizational decisions worth recording. Each entry states the decision and the reasoning.
Directory and Package Organization
web/ renamed to replay-ui/
The directory containing the React/TypeScript frontend is replay-ui/, not web/. The name web/ was ambiguous (the project also has a web/Chrome driver target). replay-ui/ makes the purpose explicit: this is the UI for the sanderling replay command.
Keep internal/
Go's internal/ directory restriction prevents any code outside this module from importing these packages. Sanderling is a CLI tool today, but the restriction costs nothing to keep and prevents accidental coupling if the module is ever used as a Go dependency. All implementation packages live under internal/.
internal/driver/ is an interface + subdirectory implementations
The driver.go file defines the DeviceDriver interface. Concrete implementations live in subdirectories: sidecar/ (gRPC to the native sidecar), chrome/ (CDP), mock/ (tests). This pattern keeps the runner and verifier decoupled from any specific platform.
internal/verifier/marshal.go moves to internal/replay/
marshal.go serializes LTL formulas to JSON for the replay UI. That is a replay concern, not a verifier concern. Verifier should not know replay exists.
internal/verifier/bindings.go splits into types.go + bindings.go
bindings.go currently holds shared types (Action, ActionKind, LogEntry, Exception) alongside JavaScript runtime wiring. The types half moves to types.go so the two concerns are separately navigable.
internal/permissions/ is deleted
Dead code with zero importers. Removed. Reintroduce a permission helper only when a platform actually needs one.
cmd/sanderling/android_env.go moves to internal/android/
Android device enumeration, AVD selection, and emulator boot logic moves to internal/android/. This keeps cmd/sanderling/ as a thin CLI wrapper and makes the Android logic independently testable.
cmd/sanderling/test_run.go logic moves to internal/testrun/
Driver setup, agent connection, verifier init, trace setup, and runner orchestration extract to internal/testrun/. cmd/sanderling/ wires CLI flags to testrun calls and nothing more.
internal/replay/runs.go splits into multiple files
429 LOC with mixed concerns (cache, file I/O, JSON decoding, summary types) splits into at least runs_cache.go and runs_decode.go within the same package.
cmd/internal-tools/ stays in cmd/
bundle-check and hier-check are dev/debug binaries. Leave them under cmd/ for now.
pkg/spec-api/ renamed to pkg/spec/
Aligns the directory name with the npm package name @sanderling/spec.