burgee/config

import { ConfigError, envName, resolve, … } from 'burgee/config';

function envName(name: string, spec: OptionSpec, prefix: string | undefined): string | undefined;

function explain(name: string, resolution: Resolution): string;

function resolve(specs: Record<string, OptionSpec>, layers: Layers): Resolution;

function screaming(name: string): string;

class ConfigError extends Error {
    readonly hint?: string | undefined;
    constructor(message: string, hint?: string | undefined);
}

interface Candidate {
    source: Source;
    location: string;
    /** `undefined` when the layer had nothing for this option. */
    value: unknown;
    /** The line in `location` that set it, when the layer knows (R3). */
    line?: number;
}

interface Layers {
    /** What the user typed: only options present on the command line. */
    flags: Record<string, unknown>;
    env: Record<string, string | undefined>;
    /** With a prefix, an option without `env:` reads `PREFIX_OPTION_NAME` (R2). */
    envPrefix?: string;
    config?: Layer;
    /** The `package.json` field named after the program, when present. */
    pkg?: Layer;
    /** Plugin-contributed sources, already read — see `seniority/plugin`'s `sources()`. */
    sources?: readonly SourceLayer[];
}

interface Provenance {
    source: Source;
    /** The env name, the config file, or `package.json` — where a person would look. */
    location?: string;
    /** The line within `location`, when the layer recorded one (R3). A file source may; an env name cannot. */
    line?: number;
}

interface Resolution {
    values: Record<string, unknown>;
    provenance: Record<string, Provenance>;
    candidates: Record<string, Candidate[]>;
}

type Source = BuiltinSource | (string & {});