4.1 KiB
ADR 0016: Separate Import Selection, Traversal, and Presence Requirements
Status
Accepted. Implemented behavior is described in the configuration contract, the public API declarations, and the internal import overview.
Date
2026-10-19
Context
Consumers assemble configurations from named files and collections whose layout varies between installations. Simple imports should require little setup, while larger collections need control over discovery, recursion, filtering, and required contributions. Combining those choices implicitly makes declarations harder to interpret and pushes source-selection work into applications.
Discovery can also reach a candidate through overlapping searches or encounter different names for one canonical source. Selection and source admission need distinct identities to support useful search unions while preserving ConfigKit's existing source-integrity rules.
Decision
ConfigKit owns import discovery and selection within its source-loading lifecycle. Support explicit files, directory searches, and path globs as distinct selection forms. Keep traversal, filename filtering, and presence requirements independently expressible. Discovery determines the selected contributions; the shared scheduler in ADR 0015 determines their resolution order.
Use optional-by-default imports with explicit requiredness controls. Selected sources remain subject to ConfigKit's validity, containment, resource, and composition contracts. This applies the library's simplicity and defaults principles to import absence while retaining meaningful errors for invalid contributions.
Applications own their selected import defaults. Authored declaration values take precedence over application defaults, which take precedence over library defaults. Each declaration resolves applicable controls independently, including declarations in imported sources. This gives applications a shared baseline while preserving explicit choices in individual declarations.
Keep declaration-local candidate identity separate from canonical source identity. Search unions coalesce repeated candidate paths within a source namespace before symlink resolution; filename filtering uses the selected or discovered name. Source admission continues to use canonical identity and the existing repeated-source rules. Distinct aliases retain their separate inclusion routes.
Alternatives Considered
- Use path globs for all discovery. Offers one selection form, but makes collection traversal depend on path-pattern structure and complicates independently controlling recursion and filename filtering.
- Offer only explicit files and directory searches. Reduces the selector vocabulary, but moves wildcard directory selection into repeated declarations or application-side discovery.
- Require every import by default. Detects absent contributions immediately, but requires repeated opt-outs for installations with optional components.
- Make application settings override authored declarations. Provides central enforcement, but prevents declarations from expressing local exceptions.
- Deduplicate selections globally by canonical source identity. Coalesces aliases and separate inclusion routes, but changes the existing repeated-source contract and obscures independently authored contributions.
Consequences
Consumers can express simple imports and more selective collection searches through the same loading lifecycle. Applications choose defaults and validate their required effective configuration; ConfigKit owns consistent selection, source admission, composition, and inspection.
Optional absence can conceal misspelled selectors, so requiredness and inspection provide explicit ways to detect and explain missing contributions. Declaration-local deduplication requires the loader to preserve candidate identity alongside canonical source identity. The configuration and public API contracts own the implemented behavior.