eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Settle discovery behavior when no main file is found

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-24 01:51:08 +00:00
parent 9c32b8d3b5
commit b746dcc609
1 changed files with 25 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
docs/roadmap/discovery.md
View File

@@ -183,7 +183,7 @@ searches changes search priority.
| A candidate file is selected | Stop searching and load that file. |
| Candidate is inaccessible, unreadable, or not an accepted file type | Fail using normal source diagnostics. |
| Selected file fails parsing, version checks, composition, decoding, or validation | Fail without trying another candidate. |
| Entire search has no match | Absence is permitted by default; continue through applicable defaults and normal validation. The interaction with other inputs is addressed under OD-3. |
| Entire search has no match | Absence is permitted by default; follow the shared absent-main lifecycle settled under OD-3 below. |
| Entire search has no match and is required | Fail with a diagnostic explaining the unsuccessful search. |
| Caller explicitly uses `File(path)` | Retain existing exclusive-file behavior, including errors for a missing file. |
@@ -236,6 +236,30 @@ This keeps search priority predictable when directory resolution fails. Consumer
select the presets appropriate to their application and environment; this proposal
does not add an option to skip unavailable bases or unsupported presets.
### No Match, Imports, And Selected Overlays (OD-3 — Settled)
Use a shared absent-main lifecycle for optional no-match and explicit `NoSource()`.
Allow imports to be enabled when the main file is absent: there are no main-file
import declarations to process, and enablement does not introduce automatic
directory scanning. Other actual sources retain their normal import behavior.
In layered loads, process underlays normally and retain the existing explicit
`OverlayFilesystem` requirement for an active overlay.
For ordinary loads with an active overlay and no main file, require an explicit
filesystem context to locate the overlay. Do not infer an overlay root from the
first or last searched directory. A missing selected overlay remains an error;
absence of a main file does not silently disable a requested overlay.
Defaults, CLI overrides, application resolution, and validation continue through
the normal lifecycle. Main-version checking receives an absent main input and
may reject it under the application's existing policy. Create no synthetic empty
document or source record for the absent main file.
This deliberately relaxes the current `NoSource()` restrictions on imports and
on overlays with explicit context. Both ways of obtaining an absent main input
have the same behavior. Implementation must cover this lifecycle change as well
as candidate selection.
### Placement, Provenance, And Existing Features
The selected file participates as the actual file source. Preserve its physical
@@ -291,31 +315,6 @@ its in-progress changes are part of a fixed implementation baseline.
## Open Decisions
### OD-3 — No Match, Imports, And Selected Overlays
**Recommendation:** use a shared absent-main lifecycle for optional no-match and
explicit `NoSource()`. Allow import enablement when the main file is absent;
there are no main-file declarations to traverse. Other actual sources retain
their normal import behavior. In layered loads, retain underlays and the existing
explicit overlay-filesystem requirement.
For ordinary loads with an active overlay and no main file, require an explicit
filesystem context. Do not infer an overlay root from the first or last searched
directory. A missing selected overlay remains an error. Defaults, CLI overrides,
resolution, and validation continue normally, and main-version checking receives
absence rather than a fabricated document.
This would deliberately relax the current `NoSource()` restrictions on imports
and on overlays with explicit context. It keeps one meaning for absent main input
and lets optional configuration remain optional without silently ignoring a
requested overlay. It requires lifecycle work beyond candidate selection.
**Alternative:** map no-match to the current `NoSource()` contract and retain its
restrictions. This minimizes lifecycle changes, but an otherwise valid optional
search with imports enabled can fail solely because no file was found, and
ordinary overlay-only loading would remain unavailable. A special absent-search
case could avoid changing `NoSource()`, at the cost of two different absence rules.
### OD-4 — Empty Composition And Implicit Preset Selection
**Recommendation:** require explicit preset or search selection to activate a