67 lines
3.4 KiB
Markdown
67 lines
3.4 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-precedence), including the
|
|
distinct validation and effective-config commands.
|
|
3. Update redaction when secrets are involved.
|
|
4. 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).
|
|
5. 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.
|
|
|
|
## Validating Examples
|
|
|
|
Keep complete copyable files in [examples](../../examples/) and link to them from
|
|
their canonical contract documentation. Keep them valid and secret-free.
|
|
From the repository root, validate the maintained configuration examples:
|
|
|
|
```sh
|
|
go run ./cmd/audita config validate --config examples/minimal-config.yml
|
|
AUDITA_SERVICE_KEY=synthetic-example go run ./cmd/audita config validate --config examples/production-config.yml
|
|
AUDITA_SERVICE_KEY=synthetic-example go run ./cmd/audita config validate --config examples/production-config.yml --overlay testing
|
|
go run ./cmd/audita config print-effective --config examples/minimal-config.yml --view profiles
|
|
```
|
|
|
|
Only referenced credentials read environment values; use a controlled synthetic
|
|
value when validating the service example. Check affected CLI examples against the
|
|
parser and use schema tests for maintained transcript/glossary inputs. Example
|
|
validation should not invoke a live LLM merely to check documentation.
|
|
|
|
## 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 and redaction
|
|
checks](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.
|