Complete Quality Workflow: Real-World .zshrc Analysis

This chapter demonstrates the complete bashrs quality workflow on a real-world shell configuration file, showing how to use all available quality tools to analyze, score, and improve your shell scripts.

Overview

We'll walk through analyzing a .zshrc file (161 lines) using all bashrs quality tools:

1. lint - Identify code quality issues
2. score - Get quality grade and score
3. audit - Comprehensive quality check
4. coverage - Test coverage analysis
5. config analyze - Configuration-specific analysis
6. format - Code formatting (where supported)
7. test - Run embedded tests

Initial Assessment

File Statistics

• Size: 161 lines (~5KB)
• Type: Zsh configuration with Oh My Zsh
• Functions: 1 custom function (claude-bedrock)
• Tests: 0 (no tests found)

Step 1: Quick Score Check

$ cargo run --bin bashrs -- score ~/.zshrc

Result:

Bash Script Quality Score
=========================

Overall Grade: D
Overall Score: 6.1/10.0

Improvement Suggestions:
------------------------
1. Reduce function complexity by extracting nested logic
2. Break down large functions (>20 lines) into smaller functions
3. Add test functions (test_*) to verify script behavior
4. Aim for at least 50% test coverage

⚠ Below average. Multiple improvements needed.

Insight: Score of 6.1/10 (D grade) indicates significant room for improvement.

Step 2: Detailed Linting

$ cargo run --bin bashrs -- lint ~/.zshrc

Results:

Summary: 2 error(s), 38 warning(s), 13 info(s)

Critical Errors:
✗ Line 73: DET002 - Non-deterministic timestamp usage (UNSAFE)
✗ Line 93: DET002 - Non-deterministic timestamp usage (UNSAFE)

Issues Found:

• 2 errors: Timestamp usage with date +%s (flagged as non-deterministic)
• 38 warnings: Variable references, quoting suggestions, style issues
• 13 info: Style consistency recommendations

Example Issues:

 Line 73 - Flagged as non-deterministic
start_time="$(date +%s)"

 Line 93 - Flagged as non-deterministic
end_time="$(date +%s)"

 Multiple SC2154 warnings - Variables set externally
 These are legitimate for .zshrc:
- $NVM_DIR (set by Node Version Manager)
- $BUN_INSTALL (set by Bun installer)
- Variables in function scopes

Note: The timestamp errors are false positives for this use case - measuring command execution time is legitimate in a shell configuration file and not security-sensitive.

Step 3: Comprehensive Audit

$ cargo run --bin bashrs -- audit ~/.zshrc

Results:

Comprehensive Quality Audit
===========================

File: ~/.zshrc

Check Results:
--------------
✅ Parse:    Valid bash syntax
❌ Lint:     2 errors, 38 warnings
⚠️  Test:     No tests found
✅ Score:    D (6.1/10.0)

Overall: ❌ FAIL

Analysis:

• ✅ Parse: Valid syntax - file will execute correctly
• ❌ Lint: Quality issues need attention
• ⚠️ Test: 0% coverage (no tests)
• Score: 6.1/10 (D grade)

Step 4: Coverage Analysis

$ cargo run --bin bashrs -- coverage ~/.zshrc

Results:

Coverage Report: ~/.zshrc

Lines:     0/103   (0.0%)  ❌
Functions: 0/1   (0.0%)  ❌

Uncovered Lines: 103 lines
Uncovered Functions: 1

⚠️  No tests found - 0% coverage

Insight: Configuration files typically don't have tests, but custom functions like claude-bedrock could benefit from testing.

Step 5: Configuration-Specific Analysis

$ cargo run --bin bashrs -- config analyze ~/.zshrc

Results:

Analysis: ~/.zshrc
============================

Statistics:
  - Lines: 161
  - Complexity score: 7/10
  - Config type: Zshrc

PATH Entries (3):
  ✓  Line 2: Complex FPATH manipulation
  ✓  Line 141: $BUN_INSTALL/bin
  ✓  Line 160: /usr/local/go/bin

Issues Found: 2
  ⚠ [CONFIG-004] Line 73: Non-deterministic timestamp
  ⚠ [CONFIG-004] Line 93: Non-deterministic timestamp

Insight: The config analyzer correctly identifies the file as a Zshrc and tracks PATH modifications.

Step 6: Test Execution

$ cargo run --bin bashrs -- test ~/.zshrc

Results:

Running tests in ~/.zshrc
⚠ No tests found in ~/.zshrc

Expected: Configuration files typically don't include tests.

Step 7: Code Formatting (Best Effort)

$ cargo run --bin bashrs -- format ~/.zshrc

Results:

error: Failed to format: Lexer error at line 63

Note: The formatter encountered regex patterns (^eu-) that are not yet fully supported. This is expected for complex shell constructs.

Summary: Complete Tool Matrix

Interpreting the Results

What the Tools Tell Us

1. score (6.1/10 D): Overall quality below average

   • Missing tests
   • High function complexity
   • Linting issues

2. lint (2 errors, 38 warnings):

   • Timestamp usage (legitimate for timing)
   • Variable scoping (false positives for .zshrc)
   • Style improvements available

3. audit (FAIL): Failed due to lint errors

   • Would pass if timestamp errors were suppressed
   • Test coverage affects score

4. coverage (0%): No tests found

   • Expected for configuration files
   • Custom functions could have tests

5. config analyze (7/10): Moderate complexity

   • PATH modifications tracked
   • Non-deterministic constructs flagged

Quality Improvement Recommendations

High Priority

1. Add test functions for claude-bedrock:

    TEST: test_claude_bedrock_region_parsing
   test_claude_bedrock_region_parsing() {
        Test that EU regions get EU model
       [[ "$(get_model_for_region "eu-west-3")" == *"eu.anthropic"* ]] || return 1
       return 0
   }
   

2. Suppress legitimate timestamp warnings with bashrs:ignore:

    bashrs:ignore DET002 - Timing is intentional, not security-sensitive
   start_time="$(date +%s)"
   

3. Break down large functions:

    Extract region detection logic
   get_model_for_region() {
       local region="$1"
       if [[ "$region" =~ ^eu- ]]; then
           echo "eu.anthropic.claude-sonnet-4-5-20250929-v1:0"
       elif [[ "$region" =~ ^us- ]]; then
           echo "us.anthropic.claude-sonnet-4-5-20250929-v1:0"
       else
           echo "global.anthropic.claude-sonnet-4-5-20250929-v1:0"
       fi
   }
   

Medium Priority

4. Quote variable expansions (many SC2086 warnings)
5. Use single quotes for literal strings (SC2311 info messages)

Low Priority

6. Consider shellcheck disable comments for false positives
7. Document complex regex patterns with comments

Workflow Recommendations

For Shell Configuration Files (.bashrc, .zshrc)

 Quick quality check
bashrs score ~/.zshrc

 Detailed analysis (run all tools)
bashrs audit ~/.zshrc     # Comprehensive check
bashrs lint ~/.zshrc      # Detailed issues
bashrs config analyze ~/.zshrc  # Config-specific

 Optional (if you have tests)
bashrs test ~/.zshrc
bashrs coverage ~/.zshrc

For Production Shell Scripts

 Complete quality workflow
bashrs audit script.sh              # Comprehensive audit
bashrs lint script.sh               # Detailed linting
bashrs test script.sh               # Run tests
bashrs coverage script.sh           # Coverage report
bashrs format script.sh --check     # Verify formatting

 Minimum quality gates
bashrs score script.sh --min-grade B  # Require B or better
bashrs audit script.sh --min-grade A  # Require A or better

For CI/CD Pipelines

 Quality gate in CI
if ! bashrs audit script.sh --min-grade B; then
    echo "Quality gate failed: script below B grade"
    exit 1
fi

 Generate quality report
bashrs audit script.sh --format json > quality-report.json

Key Takeaways

1. Multiple Tools, Different Insights: Each tool reveals different aspects of quality

   • score: Quick quality assessment
   • lint: Detailed code issues
   • audit: Comprehensive check
   • coverage: Test completeness
   • config: Configuration-specific analysis

2. Context Matters: Not all warnings are problems

   • Timestamp usage legitimate for timing
   • External variables normal in config files
   • Test coverage expectations differ by file type

3. Incremental Improvement: Focus on high-impact changes

   • Add tests for custom functions
   • Suppress false positive warnings
   • Extract complex logic into functions

4. Tool Limitations: Some constructs not yet supported

   • Complex regex patterns may fail formatting
   • Advanced shell features might trigger warnings
   • Use bashrs:ignore for intentional patterns

Expected Improvements

If we apply all recommendations:

Conclusion

The bashrs quality tools provide comprehensive analysis for shell scripts and configuration files:

• 7 tools working together for complete quality picture
• Actionable insights with specific line numbers and fixes
• Flexible workflow - use tools individually or together
• Context-aware - different expectations for different file types

Next Steps:

1. Run bashrs score on your shell files to get baseline
2. Use bashrs audit for comprehensive analysis
3. Apply high-priority fixes first
4. Re-run tools to verify improvements
5. Integrate into CI/CD for continuous quality

Recommended Quality Standards:

• Configuration files: C+ or better (7.0+/10)
• Development scripts: B or better (8.0+/10)
• Production scripts: A or better (9.0+/10)
• Critical infrastructure: A+ required (9.5+/10)