Technical Debt: Migrate to file-specific ShellCheck suppressions

[senomorf]

📋 Issue Description

Replace global ShellCheck suppressions (SC2034, SC2329) with file-specific suppressions for better linting hygiene and maintainability.

🎯 Background

From PR #43 linting infrastructure review, Claude noted: "The .shellcheckrc notes that file-specific suppressions need a different approach. Consider using inline directives in specific files rather than global suppressions where appropriate."

📊 Current State

Global suppressions in .shellcheckrc:

# Suppress SC2034 (unused variables) for constants.sh as these are for external use  
# Suppress SC2329 (unused functions) in test files as they're called by test frameworks

Current violations:

• SC2034 + SC2329 combined: ~101 instances across scripts and tests
• Affected files: constants.sh, test files, utility scripts

🔧 Tasks

Phase 1: Analyze Current Suppressions

• Document which files currently rely on global SC2034/SC2329 suppressions
• Identify legitimate cases vs actual unused variables/functions

Phase 2: Implement File-Specific Suppressions

• constants.sh: Add file-level suppression for exported variables

  #!/bin/bash
  # shellcheck disable=SC2034  # Variables exported for external use

• Test files: Add targeted suppressions for framework functions

  # shellcheck disable=SC2329  # Function called by test framework
  test_function_name() { ... }

• Other scripts: Evaluate each case individually

Phase 3: Remove Global Suppressions

• Remove global SC2034/SC2329 suppressions from .shellcheckrc
• Update comments to reflect new file-specific approach
• Test that linting still passes with file-specific suppressions

📈 Benefits

• Better linting hygiene: Only suppress warnings where actually needed
• Easier maintenance: Clear which files have which suppressions
• Improved detection: Real unused variables/functions will be caught
• Self-documenting: Suppressions explain why they're needed

🕒 Estimated Effort

• 1 hour for analysis and implementation
• Risk: Very low (configuration change only)

📝 Acceptance Criteria

• Global SC2034/SC2329 suppressions removed from .shellcheckrc
• File-specific suppressions added where appropriate
• Comments explain rationale for each suppression
• All linting checks still pass
• No new false-positive warnings introduced

🔗 Related

• Depends on: Issue Technical Debt: Fix SC2086 and SC2155 ShellCheck warnings #50 (SC2086/SC2155 cleanup) - should be done first
• Part of: PR PR3: Linting Infrastructure #43 follow-up technical debt

🏷️ Labels

• technical-debt
• code-quality
• shellcheck
• low-priority
• configuration