Module config 

User config: parse config.toml, resolve its path, and apply per-segment overrides. Full contract in docs/specs/config.md.

Structs

Config

Parsed config.toml. Serde ignores unknown keys so a file from a newer linesmith still parses on an older binary; fields this version doesn’t know are dropped rather than rejected. The schema-side additionalProperties: false tightens editor validation so typos like thme = "default" get flagged at the authoring layer; the runtime stays permissive (the unknown-key warning channel lives in from_str_validated).

ConfigPath

Where linesmith found its config path and how. explicit = true means the user named a path directly (--config or LINESMITH_CONFIG); the run-time diagnostics use this to decide whether a missing file is worth warning about (explicit paths warn, implicit XDG fallbacks stay silent for first-run users).

LayoutOptions

[layout_options] section: render-path tunables that aren’t tied to a specific segment. See docs/specs/config.md §layout_options.

LineConfig

[line] section: ordered list of segment ids to render in single-line mode, plus any numbered child tables ([line.1], [line.2], …) for multi-line mode. The flatten-captured numbered map carries every other key as a raw toml::Value. Key validation (positive integer pointing at a table with a segments array) and ordering happen in the segment builder, which keeps the spec’s “unknown keys are warnings, not errors” forward-compat contract: a typo like [line] segmnts = [...] parses as a toml::Value::Array, reaches the builder, and emits a warning rather than failing the config load. Per spec docs/specs/config.md §Multi-line layouts.

LineEntryItem

Inline-table form of LineEntry. Typed fields cover today’s known knobs; everything else lands in extra so future fields parse without a schema bump.

SegmentOverride

[segments.<id>] override block. Each typed field, when Some, replaces the segment’s built-in default. Any unrecognized keys land in extra, which the segment builder forwards to plugin scripts as ctx.config.<key>. style is stored as a raw string; the segment builder parses it at build time so parse errors emit warnings through the same callback that handles unknown-ID and inverted-bounds diagnostics.

WidthBoundsConfig

Width-bounds override. Either side may be omitted; a missing side inherits from the segment’s built-in default.

Enums

ColorPolicy

Config-level color override. auto honors CLI flags and env vars; always forces color even in non-TTY output; never strips all color. Sits below CLI flags and env vars in the precedence chain.

ConfigError

Failure modes when loading a config. A missing file is not an error; callers treat it as “use defaults.”

LayoutMode

Top-level layout = "..." selector. Defaults to SingleLine (preserves pre-multi-line config behavior). MultiLine instructs the builder + render loop to consume [line.N] sub-tables.

LineEntry

One entry in [line].segments. Per ADR-0024, the array is a mixed shape: bare strings ("model") round-trip as LineEntry::Id for backward compatibility with the v0.x string- only schema; inline tables ({ type = "separator", character = " | " }) round-trip as LineEntry::Item and carry per-boundary settings.

Constants

SCHEMA_URL

URL for the published JSON Schema, pinned to main. Single canonical URL — same shape bacon, starship, and dprint ship. The schema evolves forward-compatibly (fields added, not removed); editors validate “config field is allowed by schema” rather than “binary supports field,” so a schema slightly ahead of the installed binary loosens validation rather than tightens it. Versioned per-tag self-hosted URLs (biome’s model) are the destination once linesmith has its own website plus schemastore.org coverage.

Functions

detect_config_path

Thin wrapper around resolve_config_path that reads the process env directly. Used at startup.

resolve_config_path

Where linesmith looks for its config file, in precedence order. OsStr-typed env args so non-UTF-8 paths (/srv/café-bin in a non-UTF-8 locale) survive the cascade rather than collapse to None upstream.

with_schema_directive

Prepend #:schema <url> directive (taplo / VS Code / Zed convention) to a freshly-generated config body so editors pick up the published schema without per-user setup.