diff --git a/docs/roadmap/discovery.md b/docs/roadmap/discovery.md index ad8028d..7b3d371 100644 --- a/docs/roadmap/discovery.md +++ b/docs/roadmap/discovery.md @@ -131,7 +131,7 @@ Resolve the user-configuration base with [`os.UserHomeDir`](https://pkg.go.dev/os#UserHomeDir), and the working-directory base with [`os.Getwd`](https://pkg.go.dev/os#Getwd). Adopt the Go helpers' platform-specific directory and environment behavior, including their errors; -OD-2 determines how discovery responds to a resolution error. +the settled OD-2 rules below govern how discovery handles resolution errors. The goal is to support familiar conventions through idiomatic Go. This feature does not add a separate XDG compatibility layer or XDG system preset. A selected @@ -213,6 +213,29 @@ The exact Go names, constructors, and representation of search-wide options belong in the implementation plan. Keep the public surface root-owned and keep the single-preset case concise. +### Unavailable Bases And Platform Applicability (OD-2 — Settled) + +Resolve directory bases only as the ordered search reaches them. Once an earlier +candidate is selected, later searches do not resolve their bases. Static invalid +search arguments still fail ordinary option validation before source acquisition. + +If a selected directory's base cannot be resolved, stop and report the error. +A missing directory or candidate file beneath a resolved base allows the search +to continue; a directory-resolution error does not. This distinction also applies +to optional searches: permitting no match does not suppress errors encountered +while searching. Preserve the agreed errors for inaccessible or unreadable +candidates. + +Treat using the Unix system preset on an unsupported platform as an explicit +configuration error when that preset is reached. Specify its supported platforms +in the implementation plan. Do not translate the Unix preset into a different +platform's convention. User, home, and working-directory presets use their native +Go directory helpers. + +This keeps search priority predictable when directory resolution fails. Consumers +select the presets appropriate to their application and environment; this proposal +does not add an option to skip unavailable bases or unsupported presets. + ### Placement, Provenance, And Existing Features The selected file participates as the actual file source. Preserve its physical @@ -268,28 +291,6 @@ its in-progress changes are part of a fixed implementation baseline. ## Open Decisions -### OD-2 — Unavailable Bases And Platform Applicability - -**Recommendation:** resolve directory bases as the ordered search reaches them. -If a selected directory's base cannot be resolved, report an error. Treat using the -Unix system preset on a platform where it is unsupported as an explicit -configuration error when that preset is reached. Specify the supported platforms -in the implementation plan. Do not silently translate the Unix preset into a -different platform's convention. User, home, and working-directory presets use their -platform-native bases. - -An unavailable base is different from a candidate file being absent. Failure to -determine the user's configuration directory should not silently redirect loading -to a different directory. Once an earlier candidate is selected, later searches need -not resolve their bases. Static invalid search arguments still fail ordinary -option validation before source acquisition. - -**Alternative:** treat unsupported presets or unavailable bases as empty searches -and continue. This makes one preset composition usable across more environments, -but can unexpectedly select a lower-priority configuration. A selectable -skip-unavailable behavior could serve that need later; it adds a distinct policy -from the search-wide requirement that at least one file exist. - ### OD-3 — No Match, Imports, And Selected Overlays **Recommendation:** use a shared absent-main lifecycle for optional no-match and