why

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 18 Imported by: 0

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

View Source
const FooterHint = `values are redacted — tag fields safe:"true" to display`

FooterHint is the point-of-use self-documentation rendered after any redacted row, advertising the safe struct tag.

View Source
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.

View Source
const SchemaURI = "https://conga.sh/schemas/why/v1.json"

SchemaURI is the canonical JSON schema URI for --why=json.

View Source
const SchemaVersion = 1

SchemaVersion is the current JSON schema version emitted by --why=json.

Variables

This section is empty.

Functions

func FlagType

func FlagType(flagSpec *spec.Flag) string

FlagType classifies a flag's schema type for the JSON report.

func FormatJSONReport

func FormatJSONReport(report *Report) string

FormatJSONReport enriches the report with JSON-only metadata and renders it as a machine-readable JSON document.

func HasRedactedRows

func HasRedactedRows(rows, globalRows []Row) bool

HasRedactedRows reports whether any row in either table carries a redacted value.

func IsColorEnabled

func IsColorEnabled(writer io.Writer) bool

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, or "no config file" when the candidate is an
	// existing directory holding no matching file.
	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 or failed.
	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, loaded []string, configProbed map[string][]string) []ConfigPath

BuildConfigPaths assembles the candidate configuration path table from the session's candidate and loaded paths and the per-tier probe results.

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

func (r Report) Format() string

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

func (r Report) FormatJSON() string

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

func BuildFlagRow(input FlagInput) Row

BuildFlagRow assembles one report row for a flag from prepared provenance inputs, applying the display formatting and redaction policy.

type SubRow

type SubRow struct {
	Value  string
	Source string
	Detail string
}

SubRow is a single sub-item beneath a row, such as one loaded file of a multi-file configuration container.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL