84 lines
4.1 KiB
Markdown
84 lines
4.1 KiB
Markdown
# ADR 0016: Separate Import Selection, Traversal, and Presence Requirements
|
|
|
|
## Status
|
|
|
|
Accepted. Implemented behavior is described in the
|
|
[configuration contract](../config.md#explicit-imports), the
|
|
[public API declarations](../../lifecycle.go), and the
|
|
[internal import overview](../internal/imports.md).
|
|
|
|
## 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](0015-shared-dependency-ready-ordering.md) 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](../policy/architecture.md#simplicity-defaults-and-explicit-controls)
|
|
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.
|