Configuration and Coding Standards

CLI-First Configuration Precedence#

Gold Digger enforces a CLI-first configuration precedence: command-line flags always override environment variables, which in turn override built-in defaults. This approach is implemented throughout the codebase and documented in the requirements and architecture documentation. The database URL, query, and output file are resolved by first checking for CLI arguments, then falling back to environment variables if the CLI arguments are not provided. This ensures explicit, predictable behavior, especially in automated or scripted environments.

Configuration resolution pattern (implemented in src/config.rs):

Cli is parsed once at the binary boundary (src/main.rs::main), then projected into a fully-validated ResolvedConfig via ResolvedConfig::from_cli(&cli). Downstream code (src/run.rs, src/connection.rs) takes &ResolvedConfig and never touches Cli directly. The Cli > env > error precedence rule lives in ResolvedConfig::from_cli_with_env (src/config.rs). Environment variables are captured once via EnvSnapshot::from_process_env so concurrent environment mutation cannot shift values mid-run. Resolution failures route through typed GoldDiggerError::Config(ConfigError::*) variants for stable exit-code classification (exit 2).

See docs/solutions/best-practices/front-load-validation-with-resolved-config-type-2026-04-25.md for the full pattern. Implementation in src/config.rs, src/main.rs, and requirements.md.

Strict Error Handling with `anyhow::Result`#

All fallible functions use anyhow::Result<T>, ensuring that errors are never ignored or silently handled. Errors are surfaced with meaningful context and never result in panics in production code paths. Custom error enums are used for specific error types, and error propagation is handled with context to aid debugging and operational clarity.

Example pattern:

use anyhow::{Context, Result};

fn process_data() -> Result<()> {
    let data = fetch_data()?;
    transform_data(data)?;
    Ok(())
}

Error messages are constructed to avoid leaking sensitive information, and structured error matching is used for database errors to provide actionable feedback. See src/main.rs and architecture.md for more.

Credential Redaction Policies#

Credentials and sensitive information are never logged or exposed. All configuration dumps redact database URLs, and SQL queries containing sensitive keywords (such as "password" or "identified by") are replaced with a redacted marker. Error messages and logs are scrubbed using regex-based redaction to remove passwords, tokens, API keys, secrets, and connection string credentials.

Example redaction function (src/utils.rs):

pub fn redact_sql_error(message: &str) -> String {
    let patterns = [
        (r"(?i)password\s*[=:]\s*\S+", "***REDACTED***"),
        (r"(?i)identified\s+by\s+\S+", "***REDACTED***"),
        (r"(?i)token\s*[=:]\s*\S+", "***REDACTED***"),
        (r"(?i)token\s+\S+", "***REDACTED***"),
        (r"(?i)api[_-]?key\s*[=:]\s*\S+", "***REDACTED***"),
        (r"(?i)secret\s*[=:]\s*\S+", "***REDACTED***"),
        (r"(?i)secret\s+\S+", "***REDACTED***"),
        (r"(?i)://[^:]+:[^@]+@", "://***:***@"),
    ];
    // ... apply regex replacements ...
}

Files like .env.local are gitignored and never committed. The documentation explicitly instructs developers not to log or expose credentials. See src/utils.rs and requirements.md.

Zero Tolerance for Clippy Warnings and Formatting Issues#

All code must pass cargo clippy -- -D warnings (deny all warnings) and cargo fmt --check (enforce formatting) before merging. This is enforced at multiple levels:

Pre-commit hooks: Run automatically on each commit, covering formatting, linting, and security auditing.
Justfile tasks: Provide local equivalents for all CI checks, such as just ci-check.
CI workflows: GitHub Actions run rustfmt and clippy checks on every push and pull request. The build fails if any warnings or formatting issues are present.

Example from .pre-commit-config.yaml:

- id: rust-clippy
  entry: cargo clippy -- -D warnings
- id: rust-fmt
  entry: cargo fmt -- --check

See .pre-commit-config.yaml, justfile, and ci.yml.

Commit Message Conventions#

Commit messages must follow the Conventional Commits specification. Example formats:

feat: add new output format
fix: handle NULL values correctly
docs: update installation guide

This is enforced by pre-commit hooks using commitizen and is documented in the contributing guide. The CI pipeline also checks commit message format as part of the quality gates.

The project uses git-cliff for automated changelog generation based on Conventional Commits. Developers can generate changelogs locally with just changelog TAG or generate release notes (without headers, suitable for GitHub release bodies) with just release-notes TAG. The changelog configuration (cliff.toml) groups commits by type (Features, Bug Fixes, Documentation, etc.) and linkifies issue references.

See contributing.md, .pre-commit-config.yaml, and cliff.toml.

Enforcement via Tooling and CI#

All standards are enforced through a combination of pre-commit hooks, justfile tasks, and CI workflows. Pre-commit hooks cover formatting, linting, security audit, YAML/JSON/Markdown formatting, shell script validation (via mise-based execution), GitHub Actions workflow validation, and commit message format validation. Setup steps use mise for toolchain management, providing consistent environment configuration across local development and CI. Developers install hooks with pre-commit install and can run all checks with pre-commit run --all-files.

The justfile provides local tasks (just ci-check, just lint, just fmt-check, just changelog, just release-notes) that mirror CI checks and release automation. CI workflows (see .github/workflows/ci.yml) run on every push and pull request, blocking merges if any check fails. GitHub Actions workflows use pinned commit SHAs instead of floating tags for improved security and reproducibility. Security gates in CI include cargo-cyclonedx, Grype, and FOSSA for vulnerability and license scanning, and all release artifacts are signed and provenance-attested.

Additional enforcement and automation mechanisms include:

OpenSSF Scorecard: The scorecard.yml workflow runs supply-chain security checks on a schedule and uploads results to the code-scanning dashboard. This validates security best practices (branch protection, dependency pinning, signed releases, etc.) and publishes a Scorecard badge.
CODEOWNERS: The .github/CODEOWNERS file automatically assigns code review requests to the project maintainer for all pull requests.
DCO enforcement: The .github/dco.yml configuration enforces Developer Certificate of Origin sign-offs on all commits, with support for remediation commits to fix missing sign-offs.
Dependabot commit prefixes: Dependabot is configured to prefix all dependency update commit messages with chore(deps) for consistency with Conventional Commits and changelog generation.