===============================================================================
Folder Hash
===============================================================================

Overview
-------------------------------------------------------------------------------

This module calculates a SHA256 hash of all files in a source directory. It's
designed for change detection in Terraform workflows, particularly useful
for determining when source code has changed and rebuilds are needed.

Features
-------------------------------------------------------------------------------

- **Cross-platform compatibility** - Automatically detects and uses ``sha256sum`` (Linux) or ``shasum`` (macOS)
- **Optional debug output** - Enable detailed logging for troubleshooting (disabled by default)
- **File filtering** - Exclude common directories/files (``.git``, ``node_modules``, etc.)
- **Error handling** - Gracefully handles missing directories
- **Consistent hashing** - Uses absolute paths and sorted file lists for reproducible results
- **Performance optimized** - Excludes build artifacts and dependency directories by default

Usage
-------------------------------------------------------------------------------

Basic Usage
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: hcl

    module "folder_hash" {
      source = "./modules/utils/folder_hash"
      source_dir = "/path/to/your/source/directory"
    }

    # Use the hash in other modules
    output "source_hash" {
      value = module.folder_hash.folder_hash
    }

Advanced Usage with Custom Exclusions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: hcl

    module "folder_hash" {
      source = "./modules/utils/folder_hash"
      source_dir = "/path/to/your/source/directory"

      # Enable debug output
      debug = true

      # Custom exclude patterns
      exclude_patterns = [
        ".git",
        "node_modules",
        "dist",
        "*.log",
        ".terraform",
        ".venv",
      ]
    }

Inputs
-------------------------------------------------------------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 40 15 15 10

   * - Name
     - Description
     - Type
     - Default
     - Required
   * - source_dir
     - The source directory to calculate hash for
     - string
     - n/a
     - Yes
   * - debug
     - Enable debug output to stderr
     - bool
     - false
     - No
   * - exclude_patterns
     - List of glob patterns to exclude from hash calculation
     - list(string)
     - [".git", ".terraform", "node_modules", ".DS_Store"]
     - No

Outputs
-------------------------------------------------------------------------------

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Name
     - Description
   * - folder_hash
     - The calculated SHA256 hash of the source directory

How It Works
-------------------------------------------------------------------------------

1. **Path Resolution**: Converts the source directory to an absolute path
2. **File Discovery**: Finds all files in the directory recursively
3. **Hash Calculation**: Calculates SHA256 of each file, sorts the results, and creates a final hash
4. **Debug Output**: Provides detailed logging for troubleshooting

Example Debug Output
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When ``debug = true``:

.. code-block:: text

    Debug: Source directory is: /path/to/source
    Debug: Current working directory is: /current/dir
    Debug: Exclude patterns: .git .terraform node_modules .DS_Store
    Debug: Using hash command: sha256sum
    Debug: Absolute source directory is: /absolute/path/to/source
    Debug: Directory exists, calculating hash...
    Debug: Changed to directory: /absolute/path/to/source
    Debug: Find command: find . -type f ! -path '*/.git/*' ! -name '.git' ...
    Debug: Files found:
    ./file1.py
    ./file2.py
    ./subdir/file3.py
    Debug: Calculated hash: a1b2c3d4e5f6...

Platform Support
-------------------------------------------------------------------------------

- **Linux** - Uses ``sha256sum``
- **macOS** - Uses ``shasum -a 256``
- **Windows** - Requires bash (WSL, Git Bash, or Cygwin)

Dependencies
-------------------------------------------------------------------------------

- ``bash`` shell
- ``find`` command
- ``sha256sum`` (Linux) or ``shasum`` (macOS)

Notes
-------------------------------------------------------------------------------

- The hash is calculated based on file content, not file names or timestamps
- Empty directories are ignored
- Hidden files (starting with ``.``) are included unless explicitly excluded
- The hash is deterministic and will be the same for identical directory contents
- Exclusion patterns use standard shell glob syntax (``*`` matches any characters, ``?`` matches single character)
- Debug output is sent to stderr and won't affect Terraform output when disabled