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

Settle discovery slug and custom path rules

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-24 01:58:48 +00:00
parent cce8356b8e
commit ac5bf29ddc
1 changed files with 21 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
docs/roadmap/discovery.md
View File

@@ -1,10 +1,8 @@
# Composable Configuration Discovery Roadmap # Composable Configuration Discovery Roadmap
Status: proposal with the agreed direction, filename groups, and search presets Status: proposal with OD-1 through OD-5 settled and integrated below.
captured below. Remaining behavioral choices are under
[Open Decisions](#open-decisions).
This document describes future work, not an implemented contract. A staged This document describes future work, not an implemented contract. A staged
implementation plan will follow once the decisions are settled. implementation plan will follow review of the complete roadmap.
## Purpose And Ownership ## Purpose And Ownership
@@ -280,6 +278,24 @@ represent both intentions clearly. Presets retain their specified filename group
Selecting a single preset keeps the simple case concise. Search-wide requiredness Selecting a single preset keeps the simple case concise. Search-wide requiredness
provides the check for consumers that must find a configuration file. provides the check for consumers that must find a configuration file.
### Slugs And Custom Path Interpretation (OD-5 — Settled)
Require a nonempty single-component application slug whenever a selected search
uses it to construct a directory or filename. Reject path separators, `.` and
`..`, and forms unusable as that component on the target platform. Preserve
spelling and case; do not trim, lowercase, or impose a kebab-case naming scheme.
Validation keeps the slug from changing the intended directory structure without
imposing a separate naming style.
Searches that do not use the slug do not require one. Examples include explicit
file candidates and a custom directory searched with only Generic filenames.
Treat custom paths as literal host paths. Resolve relative paths against the
working directory at load time. Do not expand shell variables, `~`, or wildcard
syntax. Consumers can construct expanded paths themselves; User and Home presets
provide the common directory-resolution conveniences. These rules keep custom
paths consistent with explicit file loading.
### Placement, Provenance, And Existing Features ### Placement, Provenance, And Existing Features
The selected file participates as the actual file source. Preserve its physical The selected file participates as the actual file source. Preserve its physical
@@ -320,6 +336,7 @@ The subsequent implementation plan should cover:
group precedence, the Unix system preset's 14 candidates and named-only `/etc` group precedence, the Unix system preset's 14 candidates and named-only `/etc`
search, custom-list composition, both filename extensions, no-match behavior, search, custom-list composition, both filename extensions, no-match behavior,
empty components and searches, omitted versus empty filename selections, empty components and searches, omitted versus empty filename selections,
slug-dependent and slug-independent searches, literal custom paths,
required searches, unavailable preset bases, errors that must stop fallback, required searches, unavailable preset bases, errors that must stop fallback,
repeated loads, and untouched explicit `File` repeated loads, and untouched explicit `File`
behavior. Cover imports, overlays, underlays, defaults, CLI, source versions, behavior. Cover imports, overlays, underlays, defaults, CLI, source versions,
@@ -334,26 +351,3 @@ The subsequent implementation plan should cover:
This roadmap does not change implementation, policy, or ADRs by itself. Coordinate This roadmap does not change implementation, policy, or ADRs by itself. Coordinate
implementation with the ongoing sequence integration audit rather than assuming implementation with the ongoing sequence integration audit rather than assuming
its in-progress changes are part of a fixed implementation baseline. its in-progress changes are part of a fixed implementation baseline.
## Open Decisions
### OD-5 — Slugs And Custom Path Interpretation
**Recommendation:** require a nonempty single-component slug when a selected
preset uses it to construct filenames. Reject path separators, `.` and `..`,
and other forms that cannot be used as that component on the target platform.
Preserve spelling; do not silently lowercase, trim, or impose a kebab-case naming
scheme. A composition made only of explicit custom paths need not require an
application slug.
Treat custom paths as literal host file paths. Resolve relative paths against
the working directory at load time; do not expand shell variables, `~`, or glob
syntax. Consumers can construct expanded paths themselves. Selected presets
provide the convenience for user and working-directory bases.
**Alternative:** require a restricted portable slug grammar, such as lowercase
ASCII letters, digits, and hyphens. This is easy to document and portable, but
unnecessarily excludes otherwise usable application names. Automatic shell-like
custom-path expansion is also viable, but adds escaping and environment semantics
that ordinary `File(path)` does not supply. Literal paths keep both interfaces
consistent.