hcl-checker 1.6.3 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44527a5a8434256fcd8047949c77e74a00f19ddc13ae277a211bd644ddc3d33f
-  data.tar.gz: b815cfa83eb6fce5cece1896b403584c7e61b97f293002d6b45c289d33a1d69f
+  metadata.gz: 377ff190a52bcc216535c048cab19155c0f07c22a246740678f58171d4b17d6e
+  data.tar.gz: a9b1b18a57d077470ebfd8c27629a7dbd5769d2eafb2525ce809613f78f0b351
 SHA512:
-  metadata.gz: 6b3195d31385fa8df29acf196c77865f93a0fb9c219899701f9037298896aaa1d5a76bb973e8937ea28001ea765b0ea0abde59d700053d85d4aff0fc6eb3ee86
-  data.tar.gz: 1f08787b7f08e6d9d1e560acaf42cf0f5592a3bc4c8dc3001eace7ad253a1564b83c8b2ce6907376b786f3918337e303faabcdff60409ee20ea04c86d999e87a
+  metadata.gz: 5dcdcff0e7169f375e045a9e27eb5fd7f0f98046b57f021884eff0dd70b8afaf0be22c6d34d0f460374efcfce766f91cfa4aec7fe85baa7d7c345bf297d0a6b7
+  data.tar.gz: 63cefafcb6395a016c5403f8ea9a639d3a6f25311a2de5349547aa15a2a010337f730ed9d164c8eb57331cd33231552484fbbba422594c5c7bd723fb44279bec

data/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['3.3', '3.4', '4.0']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rake spec

data/.gitignore

@@ -1,4 +1,5 @@
 /.bundle/
+/vendor/
 /.yardoc
 /_yardoc/
 /coverage/

data/.ruby-version

@@ -1 +1 @@
-2.7.0
+3.4.10

data/Gemfile

@@ -1,14 +1,5 @@
 source 'https://rubygems.org'
 
-# This is needed due https://nvd.nist.gov/vuln/detail/CVE-2018-14404
-# A NULL pointer dereference vulnerability exists in the xpath.c:xmlXPathCompOpEval()
-# function of libxml2 through 2.9.8 when parsing an invalid XPath expression in the
-# XPATH_OP_AND or XPATH_OP_OR case. Applications processing untrusted XSL format inputs
-# with the use of the libxml2 library may be vulnerable to a denial of service attack due
-# to a crash of the application.
-# Nokogiri >= 1.8.5 solves this problem
-gem 'nokogiri', '>= 1.14.2'
-
 git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in hcl-checker.gemspec

data/Gemfile.lock

@@ -1,60 +1,44 @@
 PATH
   remote: .
   specs:
-    hcl-checker (1.6.3)
+    hcl-checker (2.0.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    diff-lcs (1.5.0)
-    filesize (0.2.0)
-    jsobfu (0.4.2)
-      rkelly-remix
-    json (2.6.1)
-    metasm (1.0.5)
-    nokogiri (1.14.2-arm64-darwin)
-      racc (~> 1.4)
-    nokogiri (1.14.2-x86_64-darwin)
-      racc (~> 1.4)
-    racc (1.5.0)
-    rake (12.3.3)
-    rb-readline (0.5.5)
-    rex (2.0.12)
-      filesize (~> 0)
-      jsobfu (~> 0)
-      json (~> 2)
-      metasm (~> 1)
-      nokogiri (~> 1)
-      rb-readline (~> 0)
-    rexical (1.0.7)
-    rkelly-remix (0.0.7)
-    rspec (3.11.0)
-      rspec-core (~> 3.11.0)
-      rspec-expectations (~> 3.11.0)
-      rspec-mocks (~> 3.11.0)
-    rspec-core (3.11.0)
-      rspec-support (~> 3.11.0)
-    rspec-expectations (3.11.0)
+    diff-lcs (1.6.2)
+    getoptlong (0.2.1)
+    racc (1.8.1)
+    rake (13.4.2)
+    rexical (1.0.8)
+      getoptlong
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-mocks (3.11.1)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-support (3.11.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
 
 PLATFORMS
-  arm64-darwin-21
-  x86_64-darwin-21
+  aarch64-linux-gnu
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux-gnu
 
 DEPENDENCIES
-  bundler (~> 2.4.7)
+  bundler (~> 2.4)
   hcl-checker!
-  nokogiri (>= 1.14.2)
-  racc (= 1.5.0)
-  rake (~> 12.3.3)
-  rex (= 2.0.12)
-  rexical (>= 1.0.7)
+  racc (~> 1.8)
+  rake (~> 13.0)
+  rexical (>= 1.0.8)
   rspec (~> 3.0)
 
 BUNDLED WITH
-   2.4.7
+   2.4.22

data/README.md

@@ -2,10 +2,6 @@
 
 **Hashicorp Configuration Language** syntax checker and parser.
 
-Parser originally created by [Sikula](https://github.com/sikula) and available
-at [Ruby HCL Repository](https://github.com/sikula/ruby-hcl). Only works with
-[HCL Version 1](https://github.com/hashicorp/hcl).
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -26,7 +22,7 @@ Or install it yourself as:
 
 Load HCL string:
 
-```
+```ruby
 hcl_string = 'provider "aws" {
     region = "${var.aws_region}"
     access_key = "${var.aws_access_key}"
@@ -46,45 +42,153 @@ resource "aws_vpc" "default" {
 You can validate the `hcl_string` contents with `valid?` method. This will
 return `true` if is a valid HCL or `false` if not.
 
-```
-2.3.2 :014 > HCL::Checker.valid? hcl_string
- => true
+```ruby
+HCL::Checker.valid? hcl_string
+# => true
 ```
 
 You can parse the `hcl_string` into a `Hash` with `parse` method.
 
-```
-2.3.2 :015 > HCL::Checker.parse(hcl_string)
- => {"provider"=>{"aws"=>{"region"=>"${var.aws_region}", "access_key"=>"${var.aws_access_key}", "secret_key"=>"${var.aws_secret_key}"}}, "resource"=>{"aws_vpc"=>{"default"=>{"cidr_block"=>"10.0.0.0/16", "enable_dns_hostnames"=>true, "tags"=>{"Name"=>"Event Store VPC"}}}}}
+```ruby
+HCL::Checker.parse(hcl_string)
+# => {"provider"=>{"aws"=>{"region"=>"${var.aws_region}", "access_key"=>"${var.aws_access_key}", "secret_key"=>"${var.aws_secret_key}"}}, "resource"=>{"aws_vpc"=>{"default"=>{"cidr_block"=>"10.0.0.0/16", "enable_dns_hostnames"=>true, "tags"=>{"Name"=>"Event Store VPC"}}}}}
 ```
 
-If after a `parse` you got `false` you can check `last_error` with:
+If after a `parse` you got a `String` back instead of a `Hash`, that string
+is the parse error message, and it is also available afterwards via
+`last_error`:
 
-```
-2.4.2 :063 > HCL::Checker.last_error
- => "Parse error at  \"eec8b16c-ee89-4ea0-bdcc-d094300a42e8\" , (invalid token: ,)"
+```ruby
+HCL::Checker.last_error
+# => "Parse error on line 7, column 18: unexpected \",\" (after \"instance_type\")"
 ```
 
+## Compatibility
+
+This gem parses full [HCL1](https://github.com/hashicorp/hcl) syntax, plus a
+substantial subset of HCL2 expression syntax: arithmetic/comparison/logical
+operators, ternary expressions, `for` expressions (list and object
+comprehensions), splat expressions (`list[*]` and the legacy `list.*`),
+chained indexing/attribute access, the `null` literal, scientific notation,
+string escape sequences, `<<-` heredoc dedenting, and `%{ if }`/`%{ for }`
+string template directives.
+
+Not supported:
+- The JSON variant of HCL2 (`.tf.json` files) — a fully separate parsing mode.
+- Expression evaluation — this is a structural parser/checker, not an
+  interpreter. `${...}` interpolations and bare expressions (function calls,
+  arithmetic, `for`/ternary, etc.) are preserved as opaque text, never
+  evaluated.
+
+Known caveats:
+- A quoted string used as an operand inside a larger expression loses its
+  surrounding quotes in the reconstructed text (e.g. `var.env == "prod"`
+  becomes the text `var.env == prod`). A string assigned directly as a value
+  is unaffected (`region = "us-east-1"` stays exactly `"us-east-1"`).
+- A list/object literal used as an operand inside a larger expression is
+  rendered with Ruby's own `Array`/`Hash` text representation, not HCL
+  syntax (e.g. `merge({a = 1}, {b = 2})` becomes the text
+  `merge({"a"=>1}, {"b"=>2})`).
+
+### Upgrading from 1.x
+
+Version 2.0 adds the HCL2 support described above and fixes several parsing
+bugs (including two that could hang or silently return wrong output). Most
+HCL1 configs continue to parse identically, but a few things changed:
+
+- **Ruby 3.3 or newer is now required** (previously `>= 2.7.0`).
+- **`null` now parses as a real `nil`**, not the string `"null"`.
+- **Parse error messages changed format** and now include a line and column
+  number, e.g. `"Parse error on line 7, column 18: unexpected \",\" (after
+  \"instance_type\")"`. Code that pattern-matches the exact old error text
+  will need updating; code that only checks whether `parse` returned a
+  `Hash` or a `String` (the documented, recommended pattern above) is
+  unaffected.
+- `for`, `in`, `if` and `null` are now reserved words when they appear as a
+  standalone token, needed for HCL2's `for` expressions and the `null`
+  literal. They still work as plain, unquoted attribute names and block
+  labels (`for = 1`, `resource for "x" {}`), but not in every conceivable
+  position — a nested block literally *labeled* `for` immediately followed
+  by another bare identifier no longer parses, an extremely unusual
+  construct in practice.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
 `rake spec` to run the tests. You can also run `bin/console` for an interactive
 prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To
-release a new version, update the version number in `version.rb`, and then run
-`bundle exec rake release`, which will create a git tag for the version, push
-git commits and tags, and push the `.gem` file to
-[rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+> **Note:** if you run `bundle install` directly instead of `bin/setup` and
+> get a `Bundler::PermissionError` trying to write to something like
+> `/var/lib/gems/3.3.0/cache`, your system Ruby's gem directory is
+> root-owned (common when Ruby was installed via a distro package, e.g.
+> apt's `ruby3.3`). Fix it by installing into a local, writable path
+> instead: `bundle config set --local path 'vendor/bundle' && bundle
+> install` — this is exactly what `bin/setup` already does for you.
 
 ### Building grammar
 
+If you change `assets/lexer.rex` or `assets/parse.y`, regenerate the lexer
+and parser with:
+
 ```
 $ bundle exec rake build_grammar
 Building Lexer....done
 Building Parser....done
 ```
 
+This overwrites `lib/hcl/checker/lexer.rb` and `lib/hcl/checker/parser.rb` —
+never edit those two files directly, they're marked `DO NOT MODIFY` and any
+changes will be lost the next time this task runs.
+
+## Publishing to RubyGems.org
+
+This project uses Bundler's standard gem release workflow (`rake release`,
+provided by `bundler/gem_tasks` in the `Rakefile`).
+
+1. **Bump the version** in `lib/hcl/checker/version.rb`.
+2. **Run the test suite** and make sure it's green: `bundle exec rake spec`.
+3. **Commit the version bump**, e.g. `git commit -am "Bump version to X.Y.Z"`.
+4. **Release**:
+
+   ```
+   $ bundle exec rake release
+   ```
+
+   This single command builds the `.gem` file from `hcl-checker.gemspec`,
+   creates a git tag `vX.Y.Z`, pushes the tag and any pending commits to the
+   configured remote, and pushes the built gem to
+   [rubygems.org](https://rubygems.org).
+
+If you've never pushed to rubygems.org from this machine before, `gem push`
+will prompt you to sign in (or run `gem signin` beforehand to store an API
+key). This gem has enough downloads that RubyGems requires multi-factor
+authentication to push a new version — have your TOTP code ready, or pass it
+directly with `gem push --otp <code> pkg/hcl-checker-X.Y.Z.gem` if you need
+to push the built `.gem` file manually instead of via `rake release`.
+
+To build the `.gem` file without publishing it — useful to double check its
+contents first — run `bundle exec rake build`; the file is written to `pkg/`.
+
+## Roadmap / Future work
+
+- [ ] `HCL::Checker.last_error` is mutable class-level state (not thread-safe).
+- [ ] `parse` returns a `Hash` on success and a `String` (error message) on
+      failure — an ambiguous return type that forces callers to duck-type
+      the result instead of, say, raising a dedicated exception class.
+- [ ] No JSON variant of HCL2 (`.tf.json`) support.
+- [ ] No expression evaluation — by design (see Compatibility above), but
+      worth revisiting if there's ever demand for it as a separate,
+      opt-in mode.
+
+## Implementation details
+
+Initial parser version with partial HCL 1.0 suppport was created and developed 
+by [Sikula](https://github.com/sikula) 
+and available at [Ruby HCL Repository](https://github.com/sikula/ruby-hcl).
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at

data/assets/lexer.rex

@@ -8,13 +8,34 @@ macro
   COMMENT               \#.*|\/\/.*$
   MCOMMENTIN            \/\*
   BOOL                  true|false
-  NUMBER                -?\d+
-  FLOAT                 \-?\d+\.\d+
+  NULL                  null(?![a-zA-Z0-9_\-])
+  FOR                   for(?![a-zA-Z0-9_\-])
+  IN                    in(?![a-zA-Z0-9_\-])
+  IF                    if(?![a-zA-Z0-9_\-])
+  NUMBER                \d+
+  FLOAT                 \d+(\.\d+)?[eE][-+]?\d+|\d+\.\d+
   COMMA                 \,
-  IDENTIFIER            [a-zA-Z_][a-zA-Z0-9_\-\.]*
+  IDENTIFIER            [a-zA-Z_][a-zA-Z0-9_\-]*
   EQUAL                 \=
   QUOTE                 \"
   MINUS                 \-
+  PLUS                  \+
+  STAR                  \*
+  SLASH                 \/
+  PERCENT               \%
+  ANDAND                \&\&
+  OROR                  \|\|
+  EQEQ                  \=\=
+  NEQ                   \!\=
+  LE                    \<\=
+  GE                    \>\=
+  LT                    \<
+  GT                    \>
+  ARROW                 \=\>
+  QUESTION              \?
+  COLON                 \:
+  PERIOD                \.
+  BANG                  \!
   LEFTBRACE             \{
   RIGHTBRACE            \}
   LEFTBRACKET           \[
@@ -32,10 +53,14 @@ rule
 #-------------------------------------------------------------------------------
                 {MCOMMENTIN}              { consume_comment(text) }
                 {BOOL}                    { [:BOOL,         to_boolean(text)]}
+                {NULL}                    { [:NULL,         text]}
+                {FOR}                     { [:FOR,          text]}
+                {IN}                      { [:IN,           text]}
+                {IF}                      { [:IF,           text]}
                 {FLOAT}                   { [:FLOAT,        text.to_f] }
                 {NUMBER}                  { [:NUMBER,       text.to_i] }
                 {QUOTE}                   { [:STRING,       consume_string(text)] }
-                {HEREDOCUMENT}            { [:STRING,       consume_heredoc] }
+                {HEREDOCUMENT}            { [:STRING,       consume_heredoc(text.end_with?('-'))] }
 #-------------------------------------------------------------------------------
                 {LEFTBRACE}               { [:LEFTBRACE,        text]}
                 {RIGHTBRACE}              { [:RIGHTBRACE,       text]}
@@ -46,30 +71,62 @@ rule
 #-------------------------------------------------------------------------------
                 {COMMA}                   { [:COMMA,        text]}
                 {IDENTIFIER}              { [:IDENTIFIER,   text]}
+#-- two-character operators must come before their one-character prefixes,
+#-- since this scanner uses first-match-wins (not longest-match-wins).
+                {EQEQ}                    { [:EQEQ,         text]}
+                {NEQ}                     { [:NEQ,          text]}
+                {LE}                      { [:LE,           text]}
+                {GE}                      { [:GE,           text]}
+                {ARROW}                   { [:ARROW,        text]}
+                {LT}                      { [:LT,           text]}
+                {GT}                      { [:GT,           text]}
                 {EQUAL}                   { [:EQUAL,        text]}
                 {MINUS}                   { [:MINUS,        text]}
+                {PLUS}                    { [:PLUS,         text]}
+                {STAR}                    { [:STAR,         text]}
+                {SLASH}                   { [:SLASH,        text]}
+                {PERCENT}                 { [:PERCENT,      text]}
+                {ANDAND}                  { [:ANDAND,       text]}
+                {OROR}                    { [:OROR,         text]}
+                {QUESTION}                { [:QUESTION,     text]}
+                {COLON}                   { [:COLON,        text]}
+                {PERIOD}                  { [:PERIOD,       text]}
+                {BANG}                    { [:BANG,         text]}
 
 inner
+  attr_reader :token_positions
+
   def lex(input)
     scan_setup(input)
     tokens = []
+    @token_positions = []
+
     while token = next_token
       tokens << token
+      @token_positions << current_position
     end
 
     tokens
   end
 
+  # Position (line, column) right after the token that was just consumed.
+  # Good enough for error reporting: for the overwhelming majority of
+  # tokens (identifiers, punctuation, keywords, numbers) which never span
+  # multiple lines, this is exactly where the token is. It only becomes an
+  # approximation (pointing at the end rather than the start) for
+  # constructs that can span several lines, such as heredocs, multi-line
+  # strings or block comments.
+  def current_position
+    consumed = @ss.string[0...@ss.pos]
+    line = consumed.count("\n") + 1
+    column = consumed.length - (consumed.rindex("\n") || -1)
+
+    [line, column]
+  end
+
 
   def to_boolean(input)
-    case input
-    when /true/
-      true
-    when /false/
-      false
-    else
-      raise "Invalid value for `to_boolean`, expected true/false got #{input}"
-    end
+    input == 'true'
   end
 
 
@@ -79,11 +136,11 @@ inner
     until nested.zero?
       case(text = @ss.scan_until(%r{/\*|\*/|\z}) )
       when %r{/\*\z}
-        nested =+ 1
+        nested += 1
       when %r{\*/\z}
         nested -= 1
       else
-        break
+        raise ScanError, 'unterminated block comment'
       end
     end
   end
@@ -94,13 +151,18 @@ inner
     nested = 0
 
     loop do
-      case(text = @ss.scan_until(%r{\"|\$\{|\}|\\}))
+      text = @ss.scan_until(%r{\"|\$\{|%\{|\}|\\})
+      raise ScanError, 'unterminated string' if text.nil?
+
+      case text
       when %r{\$\{\z}
         nested += 1
+      when %r{%\{\z}
+        nested += 1
       when %r{\}\z}
         nested -= 1 if nested.positive?
       when %r{\\\z}
-        result += text.chop + @ss.getch
+        result += text.chop + decode_escape
         next
       end
 
@@ -112,10 +174,48 @@ inner
     result.chop
   end
 
-  def consume_heredoc
-      token = Regexp.new @ss.scan_until(%r{\n})
-      document = @ss.scan_until(token)
+  def decode_escape
+    char = @ss.getch
+
+    case char
+    when 'n' then "\n"
+    when 't' then "\t"
+    when 'r' then "\r"
+    when '"' then '"'
+    when '\\' then '\\'
+    when 'u'
+      hex = @ss.scan(/[0-9a-fA-F]{4}/)
+      hex ? [hex.to_i(16)].pack('U') : 'u'
+    when 'U'
+      hex = @ss.scan(/[0-9a-fA-F]{8}/)
+      hex ? [hex.to_i(16)].pack('U') : 'U'
+    else
+      char.to_s
+    end
+  end
+
+  def consume_heredoc(indented)
+    marker_line = @ss.scan_until(%r{\n})
+    raise ScanError, 'unterminated heredoc: missing marker' if marker_line.nil?
+
+    marker = marker_line.strip
+    closing = /^[ \t]*#{Regexp.escape(marker)}[ \t]*(?:\n|\z)/
+    raw = @ss.scan_until(closing)
+    raise ScanError, "unterminated heredoc: missing closing marker '#{marker}'" if raw.nil?
+
+    content = raw.sub(closing, '')
+
+    indented ? dedent(content) : content
+  end
+
+  # Strips the common leading whitespace shared by every non-blank line, as
+  # required for the `<<-` heredoc form. Blank (or whitespace-only) lines
+  # are ignored when computing how much to strip, and are left untouched.
+  def dedent(text)
+    lines = text.split("\n", -1)
+    indents = lines.reject { |line| line.strip.empty? }.map { |line| line[/\A[ \t]*/].length }
+    indent = indents.min || 0
 
-      document.chop
+    lines.map { |line| line.strip.empty? ? line : line[indent..] }.join("\n")
   end
 end