Development Setup#

# Install Xcode Command Line Tools
xcode-select --install

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install build dependencies
sudo apt update
sudo apt install build-essential pkg-config libssl-dev git

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Visual Studio Build Tools
# Download from: https://visualstudio.microsoft.com/downloads/

# Install Rust
# Download from: https://rustup.rs/

git clone https://github.com/EvilBit-Labs/gold_digger.git
cd gold_digger

# Use the justfile for automated setup
just setup

# Or install manually:
rustup component add rustfmt clippy
cargo install cargo-nextest --locked
cargo install cargo-llvm-cov --locked
cargo install cargo-audit --locked
cargo install cargo-deny --locked

# Install pre-commit
pip install pre-commit

# Install hooks for this repository
pre-commit install

# Test hooks on all files (optional)
pre-commit run --all-files

# Install mdBook and plugins for documentation
just docs-install

# Or install manually:
cargo install mdbook mdbook-admonish mdbook-mermaid mdbook-linkcheck mdbook-toc mdbook-open-on-gh mdbook-tabs mdbook-i18n-helpers

# Build the project
cargo build

# Run tests
cargo test

# Check code quality
just ci-check

# Test pre-commit hooks (if installed)
pre-commit run --all-files

src/
├── main.rs # CLI entry point, env handling, format dispatch
├── lib.rs # Public API, shared utilities (rows_to_strings)
├── cli.rs # Clap CLI definitions and configuration
├── csv.rs # CSV output format (RFC4180, QuoteStyle::Necessary)
├── json.rs # JSON output format ({"data": [...]} with BTreeMap)
├── tab.rs # TSV output format (QuoteStyle::Necessary)
├── tls.rs # TLS/SSL configuration utilities
└── exit.rs # Exit code definitions and utilities

├── Cargo.toml # Package configuration and dependencies
├── Cargo.lock # Dependency lock file
├── justfile # Task runner recipes
├── rustfmt.toml # Code formatting configuration
├── deny.toml # Security and license policy
├── rust-toolchain.toml # Rust version specification
├── cliff.toml # Changelog generation configuration
├── .pre-commit-config.yaml # Pre-commit hooks
└── .editorconfig # Editor configuration

docs/
├── book.toml # mdBook configuration
├── src/ # Documentation source
│ ├── SUMMARY.md # Table of contents
│ ├── introduction.md # Landing page
│ ├── installation/ # Installation guides
│ ├── usage/ # Usage documentation
│ ├── security/ # Security considerations
│ ├── development/ # Developer guides
│ └── troubleshooting/ # Common issues
└── book/ # Generated output (gitignored)

# Format code (includes pre-commit hooks)
just format

# Check formatting
just fmt-check

# Run linter
just lint

# Run all quality checks
just ci-check

# Run pre-commit hooks manually
pre-commit run --all-files

# Run security audit
just audit

# Check licenses and security policies
just deny

# Comprehensive security scanning (audit + deny + grype)
just security

# Generate Software Bill of Materials (SBOM)
just sbom

# Cargo-deny configuration validation
just deny

# Run cargo deny check
just deny

# CI workflow uses the same configuration
# See .github/workflows/security.yml

# Run tests (standard)
just test

# Run tests (fast parallel)
just test-nextest

# Run with coverage
just coverage

# Run specific test
cargo test test_name

# Integration testing (requires Docker)
just test-integration

# All tests including integration tests
just test-all

# Debug build
just build

# Release build
just build-release

# Build all variants
just build-all

# Build documentation
just docs-build

# Serve documentation locally
just docs-serve

# Check documentation links
just docs-check

# Generate rustdoc only
just docs

# Default features
default = ["json", "csv", "additional_mysql_types", "verbose"]

# Individual features
json = [] # Enable JSON output format
csv = [] # Enable CSV output format
additional_mysql_types = ["mysql_common?/bigdecimal"]
verbose = [] # Enable verbose logging

# TLS is always enabled with rustls - no feature flags needed

# Test default features
cargo test

# Test minimal features
cargo test --no-default-features --features "csv json"

# Test with all features
cargo test --release

# Test without optional features
cargo test --no-default-features

# Integration tests automatically manage database containers
just test-integration

# No manual database setup required - testcontainers handles:
# - MySQL 8.0/8.1 container startup and configuration
# - MariaDB 10.11+ container with TLS certificates
# - Test schema creation and data seeding
# - Container cleanup after tests complete

# Install MySQL (macOS)
brew install mysql
brew services start mysql

# Install MariaDB (Ubuntu)
sudo apt install mariadb-server
sudo systemctl start mariadb

# Create test database
mysql -u root -p
CREATE DATABASE gold_digger_test;
CREATE USER 'test_user'@'localhost' IDENTIFIED BY 'test_password';
GRANT ALL PRIVILEGES ON gold_digger_test.* TO 'test_user'@'localhost';

# Start MySQL container for manual testing
docker run --name gold-digger-mysql \
  -e MYSQL_ROOT_PASSWORD=rootpass \
  -e MYSQL_DATABASE=gold_digger_test \
  -e MYSQL_USER=test_user \
  -e MYSQL_PASSWORD=test_password \
  -p 3306:3306 \
  -d mysql:8.0

# Test connection
export DATABASE_URL="mysql://test_user:test_password@localhost:3306/gold_digger_test"
export DATABASE_QUERY="SELECT 1 as test"
export OUTPUT_FILE="test.json"
cargo run

// Standard library imports
use std::{env, fs::File};

// External crate imports
use anyhow::Result;
use mysql::Pool;

// Local module imports
use gold_digger::rows_to_strings;

use anyhow::Result;
use mysql::{Value, from_value_opt};

fn example_function() -> Result<()> {
    let database_value = Value::NULL; // example value

    // ✅ Safe database value conversion
    let converted_value = match database_value {
        Value::NULL => "".to_string(),
        val => from_value_opt::<String>(val.clone()).unwrap_or_else(|_| format!("{:?}", val)),
    };

    // ✅ Feature-gated compilation
    #[cfg(feature = "verbose")]
    eprintln!("Debug information: {}", converted_value);

    Ok(())
}

// ✅ Error propagation
fn process_data() -> anyhow::Result<()> {
    let data = fetch_data()?;
    transform_data(data)?;
    Ok(())
}

fn fetch_data() -> anyhow::Result<String> {
    Ok("data".to_string())
}

fn transform_data(_data: String) -> anyhow::Result<()> {
    Ok(())
}

# Enable Rust backtrace
export RUST_BACKTRACE=1

# Enable verbose logging
export RUST_LOG=debug

# Test with safe example
just run-safe

type(scope): description

feat(csv): add support for custom delimiters
fix(json): handle null values in nested objects
docs(api): update configuration examples
test(integration): add TLS connection tests

# Install act
just act-setup

# Run CI workflow locally (dry-run)
just act-ci-dry

# Run full CI workflow
just act-ci

# .env.local
GITHUB_TOKEN=ghp_your_github_token_here
CODECOV_TOKEN=your_codecov_token_here
DATABASE_URL=mysql://user:pass@localhost:3306/testdb

# Test CI workflow with environment file
act --env-file .env.local

# Test specific job
act -j validate --env-file .env.local

# Test with secrets
act --env-file .env.local -s GITHUB_TOKEN=ghp_xxx -s CODECOV_TOKEN=xxx

# Dry run (simulation only)
act --dryrun --env-file .env.local

# Test release workflow
act workflow_dispatch --env-file .env.local -s GITHUB_TOKEN=ghp_xxx --input tag=v0.test.1

# Test specific job
just act-job validate

# Test release workflow
just act-release-dry v1.0.0

# Test cargo-dist workflow
just dist-plan

# Build cargo-dist artifacts locally
just dist-build

# Clean up act containers
just act-clean

# Run benchmarks (when available)
just bench

# Profile release build
just profile

# Build with debug info
cargo build --release --profile release-with-debug

# Use valgrind (Linux)
valgrind --tool=massif target/release/gold_digger

# Use Instruments (macOS)
instruments -t "Time Profiler" target/release/gold_digger

# Quick development check
just check

# Full CI reproduction
just ci-check

# Security scanning
just security

# Generate SBOM
just sbom

# Coverage analysis
just cover

# Generate changelog for a version
just changelog vX.Y.Z

# Extract release notes for a version
just release-notes vX.Y.Z

# Release preparation
just release-check

# Show all available commands
just help