docs: add Configliere specification draft#14
Conversation
commit: |
Formatting-only: line wrapping, trailing-space line breaks to backslash continuations, asterisk-italics to underscore-italics. No content changes.
cowboyd
left a comment
cowboyd
left a comment
There was a problem hiding this comment.
The ambiguity around env vars makes me feel as though there is something missing.
|
|
||
| Within the supported field model, every field SHOULD be configurable through | ||
| every source channel, and every source MUST be validated by the same schema. | ||
| Where a source cannot naturally represent a field's value (e.g., an env var for |
There was a problem hiding this comment.
ENV vars can represent a nested value.
|
|
||
| - Command _selection_ is CLI-only (§9.1). This is an explicit asymmetry, not a | ||
| gap. | ||
| - Env vars undergo string coercion that CLI and config values do not require. |
There was a problem hiding this comment.
CLI values undergo coercion: string -> T but it is a different transform than the one of ENV With config values T no conversion is necessary because it is already what it is.
| - Env vars have no natural representation for nested objects or arrays beyond | ||
| simple conventions (e.g., comma-separated lists). |
There was a problem hiding this comment.
this is not true. It might be awkward, but it is possible, configliere attempts it.
| - Not every structural concept (e.g., a command map, a nested object tree) has a | ||
| direct env-var equivalent. |
There was a problem hiding this comment.
technically true, but the two examples are categorically false.
| the resulting types MUST be inferred without explicit annotation. Inference | ||
| failures in the library's generic signatures are treated as bugs with blocking | ||
| priority. |
| > hierarchy. The exact implementation (closure capture vs. explicit context | ||
| > parameter) is implementation-defined. What the spec requires is the behavioral | ||
| > invariant: the resolved parser behaves as if it has the original context. | ||
|
|
There was a problem hiding this comment.
The AI LOVES the term "baking." I've tried to get it not to use it and it keeps creeping back in.
| The current observed set of helpers includes: | ||
|
|
||
| - `ConfigType<P>` — extracts `T` from `Parser<T>`. | ||
| - `CommandsType<P>` — extracts the command union. | ||
| - `CommandType<P, N>` — extracts a single command member by name, prettified. | ||
| - `ProgramType<P>` — unwraps `Program<T>` to get `T`. | ||
|
|
||
| What is normative: | ||
|
|
||
| - The convention that extraction helpers operate on parser types, not on | ||
| extracted value types. [Directly stated by the project lead.] | ||
| - Any provided extraction helper MUST produce correct types for the supported | ||
| composition patterns. | ||
|
|
||
| What is the current intended direction but may evolve: | ||
|
|
||
| - The exact set and naming of helpers listed above is the current observed | ||
| roster. Future versions may add, rename, or restructure these helpers as the | ||
| type-level architecture matures. | ||
|
|
||
| > **Open.** Whether this set is complete — and in particular whether a | ||
| > `ConfigFileType` or similar helper for config-file authoring shapes is needed | ||
| > — is an unresolved question (see §13.7 and §17). |
There was a problem hiding this comment.
general note: type inference helpers are a mess now and there are some refactors that need to happen around command. On the timeline of iterations it's like not even at step 1, so take anything that is there with a grain of salt
| union, which collapses to `{}`). | ||
|
|
||
| ### 13.5 Computed maps and annotation | ||
|
|
There was a problem hiding this comment.
"command maps" mess WRT the type-system and needs to be revisited. It was an attempt to have a more user friendly command construction, but it looks terrible from the perspective of the type system.
| When `program()` detects `--help`, it MUST produce help text even if the | ||
| underlying parse would fail. The help/version screening occurs before config | ||
| parsing. |
| 1. **Provenance preservation of original env keys after scoping.** After | ||
| `scope()` transforms env keys, the original key (e.g., `SERVE_PORT`) is lost. | ||
| This conflicts with the project's inspectability emphasis. Whether to track | ||
| pre-scoping identity is an open design question. |
2 participants
Motivation
Add a repository spec that captures Configliere's current architecture and behavioral contract in one place. The draft gives the project a shared reference for parser composition, source precedence, provenance, command/env scoping, phased parsing, and future contract tests.
Approach
Add
specs/configliere-spec.md, a normative draft that documents the library's purpose, design philosophy, core abstractions, parsing and precedence models, command behavior, help and introspection model, error model, explicit non-goals, open questions, and a normative test agenda.