Documentation
¶
Overview ¶
Package why assembles and renders the neutral value-provenance report produced by the --why builtin: one row per flag and configuration-file container with its display value, the source tier, and the env/config channels that can set the value. It owns row construction, display formatting, redaction, text layout, and the opt-in JSON document. Engine binding state (App and Session internals) is extracted by package conga and passed in as plain values; this package never observes container handles, mirroring the internal/help split.
Index ¶
- Constants
- func FlagType(flagSpec *spec.Flag) string
- func FormatJSONReport(report *Report) string
- func HasRedactedRows(rows, globalRows []Row) bool
- func IsColorEnabled(writer io.Writer) bool
- type ConfigPath
- type FeatureInput
- type FeatureRow
- type FlagInput
- type MapEntry
- type Report
- type Row
- type SubRow
Constants ¶
FooterHint is the point-of-use self-documentation rendered after any redacted row, advertising the safe struct tag.
const Redacted = "██████"
Redacted is the fixed-width placeholder shown for every value whose field is not tagged safe:"true". The width is constant so the output leaks nothing about the underlying value's length.
const SchemaURI = "https://conga.sh/schemas/why/v1.json"
SchemaURI is the canonical JSON schema URI for --why=json.
const SchemaVersion = 1
SchemaVersion is the current JSON schema version emitted by --why=json.
Variables ¶
This section is empty.
Functions ¶
func FormatJSONReport ¶
FormatJSONReport enriches the report with JSON-only metadata and renders it as a machine-readable JSON document.
func HasRedactedRows ¶
HasRedactedRows reports whether any row in either table carries a redacted value.
func IsColorEnabled ¶
IsColorEnabled reports whether styled color output should be enabled for writer, honoring CONGA_COLOR, NO_COLOR, CLICOLOR, TERM=dumb, and TTY detection.
Types ¶
type ConfigPath ¶
type ConfigPath struct {
// Path is the expanded candidate location (a search-path tier, an
// environment-derived path, or an explicit --config-file location).
Path string
// Status is the probe outcome: "loaded" when the candidate resolved to a
// configuration file, "directory does not exist" when the candidate
// location is absent, "no config file" when the candidate is an existing
// directory holding no matching file, "skipped (an earlier location
// loaded)" when first-hit resolution stopped at an earlier search path
// before reaching it, or "skipped" when the candidate is a named target
// (a config-file flag path, a configuration environment variable path, or
// the explicit option path) that lost to a higher-precedence named source
// and was never opened.
Status string
// Loaded is the concrete file the candidate resolved to when it differs
// from Path, such as a search-directory tier or a stem candidate. It is
// empty when Path itself loaded.
Loaded string
// ProbedFiles lists the concrete configuration file locations the
// resolution probed for a search-path tier that found nothing, as full
// paths (e.g. "<tier>/config.json", "<tier>.yaml"). One report line is
// rendered per entry. Empty for whole-path candidates and for tiers
// that loaded a file, failed, or were skipped.
ProbedFiles []string
}
ConfigPath is one candidate configuration file path probed during config resolution, annotated with the outcome of the probe.
func BuildConfigPaths ¶
func BuildConfigPaths(candidates, skipped, loaded []string, configProbed map[string][]string, firstHit bool) []ConfigPath
BuildConfigPaths assembles the candidate configuration path table from the session's candidate, skipped, and loaded paths and the per-tier probe results. configProbed holds an entry for every search-path tier candidate. In first-hit mode (firstHit), resolution stops at the first tier that yields a file, so every later tier is reported as skipped rather than probed. Skipped named targets, which lost to a higher-precedence named source, follow the candidates in precedence order; a skipped path that is also a candidate is listed once, as the candidate.
type FeatureInput ¶
type FeatureInput struct {
// Fields lists the declared feature toggles in declaration order.
Fields []*spec.FeatureField
// Sources records the per-key source tier of the merged feature map.
Sources map[string]container.Source
// Origins records the per-key configuration origin of the merged feature
// map.
Origins map[string]configdata.Value
// Values holds the canonical resolved value of each feature toggle.
Values map[string]string
}
FeatureInput carries the engine-extracted provenance for the feature-toggle table.
type FeatureRow ¶
type FeatureRow struct {
// Name is the normalized kebab-case feature name.
Name string
// Value is the canonical resolved value ("true"/"false" or a decimal level).
Value string
// Source is the bare source-tier word ("cli", "env", "config", "default",
// "unset").
Source string
// Detail optionally annotates the source with the concrete origin, e.g.
// the configuration file that contributed the toggle. Detail is always the
// pure origin; Scope carries any region within it.
Detail string
// Scope optionally names a region within Detail. Rendered after Detail
// inside the same parentheses; empty renders Detail alone.
Scope string
}
FeatureRow is one feature-toggle line in the report.
func BuildFeatureRows ¶
func BuildFeatureRows(input FeatureInput) []FeatureRow
BuildFeatureRows assembles the feature-toggle table from prepared provenance inputs.
type FlagInput ¶
type FlagInput struct {
// Command is the command that declares the flag.
Command *spec.Command
// CommandChain is the active command path from the root to the leaf.
CommandChain []*spec.Command
// CommandIndex is the position of Command within CommandChain.
CommandIndex int
// EnvPrefix is the application-level environment prefix used when the
// command declares none.
EnvPrefix string
// Flag is the flag's schema metadata.
Flag *spec.Flag
// Source is the tier that supplied the value.
Source container.Source
// Value is the coerced native value, or nil when Source is SourceNone.
Value any
// MapSources records the per-key source tier of a merged map value.
MapSources map[string]container.Source
// MapOrigins records the per-key configuration origin of a merged map
// value.
MapOrigins map[string]configdata.Value
// ConfigOrigin is the pure configuration origin for a scalar or slice
// config value.
ConfigOrigin string
// ConfigScope is the optional region within ConfigOrigin.
ConfigScope string
// EnvOrigin is the .env file that supplied an environment-sourced scalar
// or slice value, or "" for host environment variables.
EnvOrigin string
// RowType classifies the flag's schema type for the JSON report. It is nil
// when JSON output is not enabled, keeping the reflection machinery
// unreferenced.
RowType func(*spec.Flag) string
}
FlagInput carries the engine-extracted provenance for one flag row. The caller supplies value and source state as plain data; this package never observes engine container handles.
type MapEntry ¶
type MapEntry struct {
// Key is the map key.
Key string
// Value is the key's formatted or redacted display value.
Value string
// RawValue is the coerced native value for machine-readable export.
RawValue any
// Redacted marks this entry's value as sensitive/redacted.
Redacted bool
// Source is the bare source-tier word for the tier that last wrote the key.
Source string
// Detail optionally annotates the source with the concrete origin, e.g.
// the configuration file that contributed the key. Rendered in
// parentheses after the source word; empty renders the bare word. Detail
// is always the pure origin; Scope carries any region within it.
Detail string
// Scope optionally names a region within Detail. Rendered after Detail
// inside the same parentheses; empty renders Detail alone.
Scope string
}
MapEntry is one key of a merged map flag value with the source tier that last wrote it.
type Report ¶
type Report struct {
CommandPath string
Version string
Timestamp string
WorkingDirectory string
Rows []Row
GlobalRows []Row
// Features lists the declared feature toggles of the root command with
// their resolved value and source tier.
Features []FeatureRow
ConfigPaths []ConfigPath
// ConfigDecoders lists the registered configuration decoder extensions
// (e.g. ".json", ".toml") that drove the configuration file probes;
// rendered as a standalone line above the config paths.
ConfigDecoders []string
// ConfigExamples lists example configuration file locations the user can
// create for the application to see, rendered when no configuration file
// was loaded anywhere.
ConfigExamples []string
RedactedRows bool
// Color enables ANSI color styling in Format(). When false, plain text is
// rendered.
Color bool
}
Report is the complete --why report: the invocation's command path, the rows for the active command's flags, the rows for inherited ancestor flags, the candidate configuration paths probed during resolution, the registered configuration decoder extensions driving those probes, example configuration file locations suggested when nothing was loaded, and whether any value was redacted (driving the footer hint).
func (Report) Format ¶
Format renders the report as plain text following internal/help table conventions: a titled line, the aligned flag/value/source/env/config-path table for the active command, an inherited "Global Flags" table when ancestors contribute flags, the map-entry and sub-row trees, and the redaction footer hint.
func (Report) FormatJSON ¶
FormatJSON renders the report as a machine-readable JSON object following RFC 8259, using internal/jsonwire to avoid linking encoding/json.
type Row ¶
type Row struct {
// Name is the bare flag identifier (e.g. "port").
Name string
// Type is the schema type name ("int", "string", "string[]", "map", etc.).
Type string
// RawValue is the coerced native value for machine-readable export.
RawValue any
// Redacted marks this individual row's value as sensitive/redacted.
Redacted bool
// Label is the flag display label (e.g. "--port").
Label string
// Value is the formatted or redacted display value; empty for unset
// values (the source column says "unset"). Not rendered for a row
// carrying per-key entries: the sub-rows state each key's value. For
// a row carrying sub-rows it is the parent value cell, such as
// "(2 files)" or "(3 values)".
Value string
// Source is the bare source-tier word ("cli", "env", "config", "default",
// "unset"). For a merged map flag this is the highest contributing tier.
// Not rendered for a row carrying per-key entries: the sub-rows state each
// key's tier.
Source string
// Detail optionally annotates the source with the concrete origin, e.g.
// the configuration file that supplied the value. Rendered in parentheses
// after the source word; empty renders the bare word. Detail is always the
// pure origin; Scope carries any region within it.
Detail string
// Scope optionally names a region within Detail. Rendered after Detail
// inside the same parentheses; empty renders Detail alone.
Scope string
// Env lists the environment variables that can set the flag, or "-" when
// none apply.
Env string
// ConfigPath is the config-document key that can set the flag, or "-" when
// the flag is excluded from configuration files.
ConfigPath string
// Hidden marks flags hidden from help and completion.
Hidden bool
// Entries lists the per-key provenance of a merged map flag value,
// rendered as sub-rows beneath the flag row. Empty for scalar and slice
// flags.
Entries []MapEntry
// SubRows lists sub-items (such as multiple loaded config file paths)
// rendered as tree branches beneath the flag row.
SubRows []SubRow
}
Row is one neutral report line for a single flag or config-file container.
func BuildFlagRow ¶
BuildFlagRow assembles one report row for a flag from prepared provenance inputs, applying the display formatting and redaction policy.