Files
audita/docs/internal/cli-config.md

69 lines
3.6 KiB
Markdown

# Configuration and CLI Change Recipes
This document owns contributor editing and validation steps for configuration,
CLI wiring, and maintained examples. Definitions of behavior belong to the
[configuration](../config.md) and [CLI](../cli.md) contracts.
## Changing Configuration
1. Update fields, defaults, loading, and validation in `internal/core/config`.
2. Update file, selected overlay, credential reference, and CLI mapping as
applicable. Preserve the precedence defined in the
[configuration contract](../config.md#loading-and-composition), including the
distinct validation and effective-config commands.
3. Review configuration tests and related CLI tests for precedence, validation,
and source-specific behavior. Add or adjust tests for the changed contract
according to the [testing policy](../policy/testing.md).
4. Update the configuration reference and affected [examples](../../examples/).
## Changing CLI Behavior
1. Implement parsing and wiring in `internal/cli`.
2. Preserve [stream and exit contracts](../cli.md) unless a change is intentional
and documented. Review [subprocess integration](../integrations/subprocess.md)
when changing output, error, or report handling.
3. Review `internal/cli` tests and `cmd/audita` subprocess tests; update coverage
for the changed behavior.
4. Update the CLI reference and affected integration guidance.
The `version` route uses ReleaseKit's public `buildinfo.Version()` accessor and
stays independent of application runtime assembly. Preserve its behavior from
the [CLI contract](../cli.md) when changing the command; the
adoption decision is recorded in [ADR 0001](../adr/0001-releasekit.md).
Processing preflight checks glossary selections before inspecting proposal,
validation, and enabled repair profiles in pipeline order. The checked plan
carries the resolved module specs and glossary views into execution. It reuses
profile and backend inspections and equivalent glossary views within the
invocation. Native inspection commands continue to inspect configuration
without running processing readiness checks.
## Validating Examples
Keep complete copyable files in [examples](../../examples/) and link to them from
their canonical contract documentation. Keep them valid and secret-free.
Run the commands in the [example guide](../../examples/README.md) from each
project's directory. `internal/cli/examples_integration_test.go` exercises the
maintained projects with a controlled provider, and the preview fixture can be
prepared without inference. Review automatic companion sources and overlays in
their actual project directories. Keep service credentials synthetic in tests.
## Runtime Change Checks
Select checks according to the [testing policy](../policy/testing.md):
- Configuration or CLI changes: inspect `internal/core/config` tests,
`internal/cli` tests, and `cmd/audita` integration tests.
- Process/output changes: verify stdout, stderr, exit, output-file, and report
behavior against the [CLI contract](../cli.md) and
[subprocess guidance](../integrations/subprocess.md), including failures.
- Report or diagnostics changes: review [report assembly tests](diagnostics-reporting.md#key-tests), metadata fields, and artifact paths.
- Schema or serialization changes: review [output-schema tests](output-schemas.md#key-tests)
and `internal/core/schema` tests, including supported formats and rejection of
unsupported schemas.
- Changes affecting assembled output: inspect controlled HTTP subprocess workflows
and retained report/artifact assertions.
Use the [contributor guide](../development.md#baseline-validation) for baseline
commands. These recipes supplement, rather than duplicate, public contracts.