@truefoundry/tfy-infra-engine 0.1.0 → 0.1.2-canary.e8cd23d

package/scripts/canonical_hash.sh

@@ -0,0 +1,278 @@
+#!/bin/sh
+# canonical_hash.sh -- Format-independent canonical hashing for HCL files.
+#
+# Produces a deterministic SHA-256 hash of HCL content that is independent of
+# formatting differences (indentation, alignment, comments, trailing commas).
+# Two semantically identical HCL files with different formatting will produce
+# the same hash.
+#
+# USAGE:
+#   canonical_hash.sh <file>     Hash a file by path
+#   canonical_hash.sh            Hash from stdin (or explicit "-")
+#   canonical_hash.sh --test     Run self-test to verify the pipeline
+#
+# OUTPUT:
+#   sha256:<64-hex-chars>
+#
+# EXIT CODES:
+#   0  Success
+#   1  No SHA-256 tool found
+#   2  Input error (file not found, etc.)
+#
+# PIPELINE:
+#   1. Strip @tfy-status header (sed)
+#   2. Strip carriage returns (tr -d '\r')
+#   3. Canonicalize (AWK 4-state machine)
+#   4. SHA-256 hash
+#
+# ---------------------------------------------------------------------------
+# CANONICALIZATION ALGORITHM
+#
+# A 4-state character scanner implemented in POSIX AWK. It processes input
+# character by character, stripping comments and whitespace outside strings,
+# normalizing trailing commas, and preserving string content exactly.
+#
+# States:
+#   NORMAL (0)        -- Outside strings and comments
+#   STRING (1)        -- Inside a double-quoted string
+#   LINE_COMMENT (2)  -- Inside a # or // comment (until end of line)
+#   BLOCK_COMMENT (3) -- Inside a /* ... */ comment
+#
+# State transitions:
+#
+#   State         | Whitespace | "              | #             | //            | /*             | */        | ,                      | Other
+#   ------------- | ---------- | -------------- | ------------- | ------------- | -------------- | --------- | ---------------------- | ---------
+#   NORMAL        | discard    | emit, ->STRING | ->LINE_COMMENT| ->LINE_COMMENT| ->BLOCK_COMMENT| n/a       | buffer (trailing logic) | emit
+#   STRING        | emit       | emit, ->NORMAL | emit          | emit          | emit           | emit      | emit                   | emit
+#                 |            | (if unescaped) |               |               |                |           |                        |
+#   LINE_COMMENT  | discard    | discard        | discard       | discard       | discard        | discard   | discard                | discard
+#                 |            |                |               |               |                |           |                        | (newline->NORMAL)
+#   BLOCK_COMMENT | discard    | discard        | discard       | discard       | discard        | ->NORMAL  | discard                | discard
+#
+# Trailing comma normalization:
+#   When "," is seen in NORMAL state, it is buffered (not emitted immediately).
+#   When the next non-whitespace character arrives:
+#     - If it is "}" or "]", discard the buffered comma (trailing comma removed)
+#     - Otherwise, emit the buffered comma then the character
+#
+# Escape handling in STRING state:
+#   A backslash (\) sets an escape flag. \" does NOT exit STRING state.
+#   \\ (escaped backslash) clears the escape flag, so a following " DOES exit.
+#
+# EXAMPLE:
+#   Input A (formatted):
+#     resource "aws_instance" "main" {
+#       ami           = "ami-12345"   # AMI ID
+#       instance_type = "t2.micro"
+#       tags          = { Name = "prod", }
+#     }
+#
+#   Input B (compact):
+#     resource "aws_instance" "main" {
+#       ami = "ami-12345"
+#       instance_type = "t2.micro"
+#       tags = {Name = "prod"}
+#     }
+#
+#   Both produce identical canonical form:
+#     resource"aws_instance""main"{ami="ami-12345"instance_type="t2.micro"tags={Name="prod"}}
+#
+# KNOWN TRADE-OFFS (consistently wrong, but deterministic):
+#   1. Template expressions with nested quotes: "${lookup(map, "default")}"
+#      The inner " toggles STRING state. Whitespace inside "default" may be
+#      stripped. Both formatted and unformatted versions produce the same result.
+#   2. Heredocs: No HEREDOC state. Whitespace inside heredocs is stripped as
+#      normal code. Both versions produce the same result since formatters
+#      never change heredoc content.
+#   3. Escaped backslash before quote: "C:\\dir\\" -- the closing " appears
+#      escaped. Rare in HCL.
+#   4. Block comment */ split across lines: * at end of line 1 and / at start
+#      of line 2 won't be detected as */. Extremely unlikely in practice.
+# ---------------------------------------------------------------------------
+
+set -e
+
+# Detect SHA-256 tool (once)
+detect_sha_cmd() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    SHA_CMD="sha256sum"
+  elif command -v shasum >/dev/null 2>&1; then
+    SHA_CMD="shasum -a 256"
+  elif command -v openssl >/dev/null 2>&1; then
+    SHA_CMD="openssl dgst -sha256 -r"
+  else
+    printf "ERROR: no SHA-256 tool found\n" >&2
+    exit 1
+  fi
+}
+
+# Strip @tfy-status header block: 3-line block delimited by begin/end sentinels
+strip_header() {
+  sed '/^# @tfy-status:begin$/,/^# @tfy-status:end$/d'
+}
+
+# AWK 4-state canonicalizer
+canonicalize() {
+  awk '
+  BEGIN {
+    state = 0  # 0=NORMAL, 1=STRING, 2=LINE_COMMENT, 3=BLOCK_COMMENT
+    esc = 0
+    pending_comma = 0
+    out = ""
+  }
+
+  {
+    n = length($0)
+    for (i = 1; i <= n; i++) {
+      c = substr($0, i, 1)
+      nx = (i < n) ? substr($0, i + 1, 1) : ""
+
+      if (state == 0) {
+        # NORMAL
+        if (c == " " || c == "\t") continue
+
+        # Comment starts must NOT flush pending comma -- the comment
+        # is invisible, so the comma stays pending for the next real char
+        if (c == "#") {
+          state = 2
+          continue
+        }
+        if (c == "/" && nx == "/") {
+          state = 2
+          i++
+          continue
+        }
+        if (c == "/" && nx == "*") {
+          state = 3
+          i++
+          continue
+        }
+
+        # Non-whitespace, non-comment: flush pending comma
+        if (pending_comma) {
+          if (c != "}" && c != "]") out = out ","
+          pending_comma = 0
+        }
+
+        if (c == "\"") {
+          out = out c
+          state = 1
+          esc = 0
+        } else if (c == ",") {
+          pending_comma = 1
+        } else {
+          out = out c
+        }
+
+      } else if (state == 1) {
+        # STRING
+        out = out c
+        if (c == "\"" && !esc) {
+          state = 0
+        }
+        if (c == "\\" && !esc) {
+          esc = 1
+        } else {
+          esc = 0
+        }
+
+      } else if (state == 2) {
+        # LINE_COMMENT -- discard until end of line (handled by line loop)
+
+      } else if (state == 3) {
+        # BLOCK_COMMENT
+        if (c == "*" && nx == "/") {
+          state = 0
+          i++
+        }
+      }
+    }
+
+    # End of line resets LINE_COMMENT state
+    if (state == 2) state = 0
+  }
+
+  END {
+    if (pending_comma) out = out ","
+    printf "%s", out
+  }
+  '
+}
+
+# Compute SHA-256 and format as "sha256:<hex>"
+compute_hash() {
+  hex=$($SHA_CMD | awk '{ print $1 }')
+  printf "sha256:%s\n" "$hex"
+}
+
+# Run the full pipeline on stdin
+hash_stdin() {
+  strip_header | tr -d '\r' | canonicalize | compute_hash
+}
+
+# Run the full pipeline on a file
+hash_file() {
+  if [ ! -f "$1" ]; then
+    printf "ERROR: file not found: %s\n" "$1" >&2
+    exit 2
+  fi
+  hash_stdin < "$1"
+}
+
+# Self-test mode
+run_self_test() {
+  detect_sha_cmd
+
+  # Test 1: output format
+  result=$(printf 'a = 1\n' | hash_stdin)
+  case "$result" in
+    sha256:[a-f0-9]*)
+      ;;
+    *)
+      printf "FAIL: output format: %s\n" "$result" >&2
+      exit 1
+      ;;
+  esac
+
+  # Test 2: format independence
+  formatted=$(printf 'resource "null" "a" {\n  ami   = "x"   # comment\n  tags  = { Name = "prod", }\n}\n' | hash_stdin)
+  compact=$(printf 'resource "null" "a" {\nami="x"\ntags={Name="prod"}\n}\n' | hash_stdin)
+  if [ "$formatted" != "$compact" ]; then
+    printf "FAIL: format independence\n  formatted: %s\n  compact:   %s\n" "$formatted" "$compact" >&2
+    exit 1
+  fi
+
+  # Test 3: header stripping
+  with_header=$(printf '# @tfy-status:begin\n# {"managed":true}\n# @tfy-status:end\na = 1\n' | hash_stdin)
+  without_header=$(printf 'a = 1\n' | hash_stdin)
+  if [ "$with_header" != "$without_header" ]; then
+    printf "FAIL: header stripping\n  with:    %s\n  without: %s\n" "$with_header" "$without_header" >&2
+    exit 1
+  fi
+
+  # Test 4: string preservation (comment chars inside strings)
+  hash_a=$(printf 'a = "# not a comment"\n' | hash_stdin)
+  hash_b=$(printf 'a = "# different comment"\n' | hash_stdin)
+  if [ "$hash_a" = "$hash_b" ]; then
+    printf "FAIL: string preservation -- different strings produced same hash\n" >&2
+    exit 1
+  fi
+
+  printf "OK: all self-tests passed\n"
+  exit 0
+}
+
+# Main entry point
+detect_sha_cmd
+
+case "${1:-}" in
+  --test)
+    run_self_test
+    ;;
+  ""|-)
+    hash_stdin
+    ;;
+  *)
+    hash_file "$1"
+    ;;
+esac