docsterra 0.1.0

data/lib/docsterra/model/resource.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Docsterra
+  module Model
+    class Resource
+      attr_reader :type, :name, :attributes, :project, :references, :meta, :source_file,
+                  :comment, :kind, :display_name, :category, :key_attributes
+
+      def initialize(
+        type:,
+        name:,
+        attributes:,
+        project:,
+        references: [],
+        meta: {},
+        source_file: nil,
+        comment: nil,
+        kind: :resource,
+        display_name: nil,
+        category: :other,
+        key_attributes: []
+      )
+        @type = type
+        @name = name
+        @attributes = attributes || {}
+        @project = project
+        @references = Array(references).uniq
+        @meta = meta || {}
+        @source_file = source_file
+        @comment = comment
+        @kind = kind
+        @display_name = display_name || type
+        @category = category || :other
+        @key_attributes = Array(key_attributes)
+      end
+
+      def identifier
+        "#{type}.#{name}"
+      end
+
+      def data_source?
+        kind == :data
+      end
+
+      def resource?
+        kind == :resource
+      end
+
+      def description
+        attribute_text("description") || comment
+      end
+
+      def attribute(path)
+        segments = path.to_s.split(".")
+        traverse(@attributes, segments)
+      end
+
+      def attribute_text(path)
+        value = attribute(path)
+        return nil if value.nil?
+
+        case value
+        when Array
+          value.map { |item| item.is_a?(Hash) ? compact_hash(item) : Docsterra::Parser::ExpressionInspector.to_text(item) }
+               .map(&:to_s)
+               .join(", ")
+        when Hash
+          compact_hash(value).inspect
+        else
+          Docsterra::Parser::ExpressionInspector.to_text(value)
+        end
+      end
+
+      def attribute_ruby(path)
+        value = attribute(path)
+        return nil if value.nil?
+        return value.map { |item| item.is_a?(Hash) ? hash_to_ruby(item) : Docsterra::Parser::ExpressionInspector.to_ruby(item) } if value.is_a?(Array)
+        return hash_to_ruby(value) if value.is_a?(Hash)
+
+        Docsterra::Parser::ExpressionInspector.to_ruby(value)
+      end
+
+      private
+
+      def traverse(value, segments)
+        return value if segments.empty?
+
+        head = segments.first
+        tail = segments.drop(1)
+
+        case value
+        when Hash
+          traverse(value[head], tail)
+        when Array
+          next_value = if integer_string?(head)
+                         value[head.to_i]
+                       else
+                         value.first
+                       end
+          traverse(next_value, integer_string?(head) ? tail : segments)
+        end
+      end
+
+      def integer_string?(value)
+        value.match?(/\A\d+\z/)
+      end
+
+      def compact_hash(hash)
+        hash.transform_values do |value|
+          if value.is_a?(Hash)
+            compact_hash(value)
+          elsif value.is_a?(Array)
+            value.map { |entry| entry.is_a?(Hash) ? compact_hash(entry) : Docsterra::Parser::ExpressionInspector.to_text(entry) }
+          else
+            Docsterra::Parser::ExpressionInspector.to_text(value)
+          end
+        end
+      end
+
+      def hash_to_ruby(hash)
+        hash.transform_values do |value|
+          if value.is_a?(Hash)
+            hash_to_ruby(value)
+          elsif value.is_a?(Array)
+            value.map { |entry| entry.is_a?(Hash) ? hash_to_ruby(entry) : Docsterra::Parser::ExpressionInspector.to_ruby(entry) }
+          else
+            Docsterra::Parser::ExpressionInspector.to_ruby(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docsterra/parser/expression_inspector.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Docsterra
+  module Parser
+    module ExpressionInspector
+      module_function
+
+      def to_text(node)
+        case node
+        when nil
+          nil
+        when AST::Literal
+          format_literal(node.value)
+        when AST::Reference
+          node.parts.map { |part| part.is_a?(String) ? part : to_text(part) }.join(".")
+        when AST::TemplateExpr
+          node.parts.join
+        when AST::RawExpr
+          node.text
+        when AST::ListExpr
+          "[" + node.elements.map { |element| to_text(element) }.join(", ") + "]"
+        when AST::MapExpr
+          "{" + node.pairs.map { |k, v| "#{k} = #{to_text(v)}" }.join(", ") + "}"
+        when AST::FunctionCall
+          "#{node.name}(#{node.args.map { |arg| to_text(arg) }.join(', ')})"
+        when AST::IndexExpr
+          "#{to_text(node.expr)}[#{to_text(node.index)}]"
+        when AST::ConditionalExpr
+          "#{to_text(node.cond)} ? #{to_text(node.true_val)} : #{to_text(node.false_val)}"
+        when AST::UnaryExpr
+          "#{node.op}#{to_text(node.expr)}"
+        when AST::BinaryExpr
+          "#{to_text(node.left)} #{node.op} #{to_text(node.right)}"
+        when AST::SplatExpr
+          [to_text(node.expr), "*", node.attr].compact.join(".").gsub(".*.", ".*.")
+        when AST::ForExpr
+          render_for_expr(node)
+        else
+          node.to_s
+        end
+      end
+
+      def to_ruby(node)
+        case node
+        when nil
+          nil
+        when AST::Literal
+          node.value
+        when AST::ListExpr
+          node.elements.map { |element| to_ruby(element) }
+        when AST::MapExpr
+          node.pairs.transform_values { |value| to_ruby(value) }
+        else
+          to_text(node)
+        end
+      end
+
+      def collect_references(node)
+        refs = []
+        walk(node) do |value|
+          refs << to_text(value) if value.is_a?(AST::Reference)
+        end
+        refs.uniq.compact
+      end
+
+      def walk(node, &block)
+        return if node.nil?
+
+        yield node
+
+        case node
+        when AST::ListExpr
+          node.elements.each { |element| walk(element, &block) }
+        when AST::MapExpr
+          node.pairs.each_value { |value| walk(value, &block) }
+        when AST::FunctionCall
+          node.args.each { |arg| walk(arg, &block) }
+        when AST::IndexExpr
+          walk(node.expr, &block)
+          walk(node.index, &block)
+        when AST::ConditionalExpr
+          walk(node.cond, &block)
+          walk(node.true_val, &block)
+          walk(node.false_val, &block)
+        when AST::ForExpr
+          walk(node.collection, &block)
+          walk(node.body, &block)
+          walk(node.cond, &block)
+        when AST::UnaryExpr
+          walk(node.expr, &block)
+        when AST::BinaryExpr
+          walk(node.left, &block)
+          walk(node.right, &block)
+        when AST::SplatExpr
+          walk(node.expr, &block)
+        end
+      end
+
+      def render_for_expr(node)
+        vars = [node.key_var, node.val_var].compact.join(", ")
+        text = "for #{vars} in #{to_text(node.collection)} : #{to_text(node.body)}"
+        text += " if #{to_text(node.cond)}" if node.cond
+        wrapper_left = node.is_map ? "{" : "["
+        wrapper_right = node.is_map ? "}" : "]"
+        "#{wrapper_left}#{text}#{wrapper_right}"
+      end
+      private_class_method :render_for_expr
+
+      def format_literal(value)
+        case value
+        when String
+          value
+        when NilClass
+          "null"
+        else
+          value.to_s
+        end
+      end
+      private_class_method :format_literal
+    end
+  end
+end

data/lib/docsterra/parser/hcl_ast.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Docsterra
+  module Parser
+    module AST
+      def self.node(*members)
+        Struct.new(*members, keyword_init: true)
+      end
+
+      # File-level AST nodes
+      File = node(:blocks, :comments)
+      Block = node(:type, :labels, :body, :comment)
+      Attribute = node(:key, :value, :comment)
+
+      # Value / expression nodes
+      Literal = node(:value)
+      ListExpr = node(:elements)
+      MapExpr = node(:pairs)
+      Reference = node(:parts)
+      FunctionCall = node(:name, :args)
+      TemplateExpr = node(:parts)
+      IndexExpr = node(:expr, :index)
+      ConditionalExpr = node(:cond, :true_val, :false_val)
+      ForExpr = node(:key_var, :val_var, :collection, :body, :cond, :is_map)
+      UnaryExpr = node(:op, :expr)
+      BinaryExpr = node(:left, :op, :right)
+      SplatExpr = node(:expr, :attr)
+      RawExpr = node(:text)
+    end
+  end
+end

data/lib/docsterra/parser/hcl_lexer.rb

@@ -0,0 +1,378 @@
+# frozen_string_literal: true
+
+module Docsterra
+  module Parser
+    class HclLexer
+      Token = Struct.new(
+        :type,
+        :value,
+        :lexeme,
+        :line,
+        :column,
+        :start_pos,
+        :end_pos,
+        keyword_init: true
+      )
+
+      SINGLE_CHAR_TOKENS = {
+        "{" => :LBRACE,
+        "}" => :RBRACE,
+        "[" => :LBRACK,
+        "]" => :RBRACK,
+        "(" => :LPAREN,
+        ")" => :RPAREN,
+        "=" => :EQUALS,
+        "," => :COMMA,
+        "." => :DOT
+      }.freeze
+
+      EXTRA_TOKENS = {
+        "?" => :QUESTION,
+        ":" => :COLON,
+        "+" => :PLUS,
+        "-" => :MINUS,
+        "*" => :STAR,
+        "/" => :SLASH,
+        "%" => :PERCENT,
+        "!" => :BANG,
+        ">" => :GT,
+        "<" => :LT
+      }.freeze
+
+      def initialize(text = nil)
+        @text = text
+      end
+
+      def tokenize(text = @text)
+        raise ArgumentError, "text is required" if text.nil?
+
+        setup(text)
+        tokens = []
+
+        until eof?
+          case current_char
+          when " ", "\t", "\r"
+            advance
+          when "\n"
+            tokens << build_token(:NEWLINE, "\n", consume_newline)
+          when "#"
+            tokens << consume_line_comment("#")
+          when "/"
+            tokens << if peek_char == "/"
+                        consume_line_comment("//")
+                      elsif peek_char == "*"
+                        consume_block_comment
+                      else
+                        consume_single_char_token(EXTRA_TOKENS.fetch("/"))
+                      end
+          when "\""
+            tokens << consume_string
+          when "<"
+            tokens << if peek_char == "<"
+                        consume_heredoc
+                      else
+                        consume_single_char_token(EXTRA_TOKENS.fetch("<"))
+                      end
+          else
+            tokens << consume_token
+          end
+        end
+
+        tokens << Token.new(
+          type: :EOF,
+          value: nil,
+          lexeme: "",
+          line: @line,
+          column: @column,
+          start_pos: @index,
+          end_pos: @index
+        )
+        tokens
+      end
+
+      private
+
+      def setup(text)
+        @text = text
+        @index = 0
+        @line = 1
+        @column = 1
+      end
+
+      def consume_token
+        return consume_number if digit?(current_char)
+        return consume_identifier if identifier_start?(current_char)
+        return consume_single_char_token(SINGLE_CHAR_TOKENS.fetch(current_char)) if SINGLE_CHAR_TOKENS.key?(current_char)
+        return consume_single_char_token(EXTRA_TOKENS.fetch(current_char)) if EXTRA_TOKENS.key?(current_char)
+
+        consume_unknown
+      end
+
+      def consume_single_char_token(type)
+        start_pos = @index
+        start_line = @line
+        start_column = @column
+        advance
+        build_token(type, @text[start_pos...@index], [start_pos, start_line, start_column])
+      end
+
+      def consume_newline
+        start_pos = @index
+        start_line = @line
+        start_column = @column
+        advance
+        [start_pos, start_line, start_column]
+      end
+
+      def consume_line_comment(prefix)
+        start_pos = @index
+        start_line = @line
+        start_column = @column
+        advance(prefix.length)
+        advance until eof? || current_char == "\n"
+        lexeme = @text[start_pos...@index]
+        value = lexeme.delete_prefix(prefix).strip
+        Token.new(
+          type: :COMMENT,
+          value: value,
+          lexeme: lexeme,
+          line: start_line,
+          column: start_column,
+          start_pos: start_pos,
+          end_pos: @index
+        )
+      end
+
+      def consume_block_comment
+        start_pos = @index
+        start_line = @line
+        start_column = @column
+        advance(2)
+
+        until eof?
+          if current_char == "*" && peek_char == "/"
+            advance(2)
+            break
+          end
+
+          advance
+        end
+
+        lexeme = @text[start_pos...@index]
+        value = lexeme.sub(%r{\A/\*}, "").sub(%r{\*/\z}, "").strip
+        Token.new(
+          type: :COMMENT,
+          value: value,
+          lexeme: lexeme,
+          line: start_line,
+          column: start_column,
+          start_pos: start_pos,
+          end_pos: @index
+        )
+      end
+
+      def consume_string
+        start_pos = @index
+        start_line = @line
+        start_column = @column
+        advance # opening quote
+
+        content = +""
+        until eof?
+          char = current_char
+          if char == "\\"
+            content << char
+            advance
+            break if eof?
+
+            content << current_char
+            advance
+            next
+          end
+
+          if char == "\""
+            advance
+            break
+          end
+
+          content << char
+          advance
+        end
+
+        Token.new(
+          type: :STRING,
+          value: content,
+          lexeme: @text[start_pos...@index],
+          line: start_line,
+          column: start_column,
+          start_pos: start_pos,
+          end_pos: @index
+        )
+      end
+
+      def consume_heredoc
+        start_pos = @index
+        start_line = @line
+        start_column = @column
+        advance(2) # <<
+        advance if current_char == "-"
+
+        header_delimiter_start = @index
+        advance while !eof? && current_char != "\n"
+        header_delimiter = @text[header_delimiter_start...@index].strip
+        indented = @text[start_pos...header_delimiter_start].end_with?("<<-")
+
+        advance if current_char == "\n"
+
+        content = +""
+        loop do
+          break if eof?
+
+          line_start = @index
+          advance while !eof? && current_char != "\n"
+          line_text = @text[line_start...@index]
+
+          match = indented ? line_text.strip == header_delimiter : line_text == header_delimiter
+          if !header_delimiter.empty? && match
+            advance if current_char == "\n"
+            break
+          end
+
+          content << line_text
+          if current_char == "\n"
+            content << "\n"
+            advance
+          end
+        end
+
+        Token.new(
+          type: :HEREDOC,
+          value: content,
+          lexeme: @text[start_pos...@index],
+          line: start_line,
+          column: start_column,
+          start_pos: start_pos,
+          end_pos: @index
+        )
+      end
+
+      def consume_number
+        start_pos = @index
+        start_line = @line
+        start_column = @column
+
+        advance while digit?(current_char)
+        if current_char == "." && digit?(peek_char)
+          advance
+          advance while digit?(current_char)
+        end
+
+        lexeme = @text[start_pos...@index]
+        value = lexeme.include?(".") ? lexeme.to_f : lexeme.to_i
+        Token.new(
+          type: :NUMBER,
+          value: value,
+          lexeme: lexeme,
+          line: start_line,
+          column: start_column,
+          start_pos: start_pos,
+          end_pos: @index
+        )
+      end
+
+      def consume_identifier
+        start_pos = @index
+        start_line = @line
+        start_column = @column
+        advance while identifier_part?(current_char)
+        lexeme = @text[start_pos...@index]
+
+        if %w[true false].include?(lexeme)
+          type = :BOOL
+          value = lexeme == "true"
+        else
+          type = :IDENT
+          value = lexeme
+        end
+
+        Token.new(
+          type: type,
+          value: value,
+          lexeme: lexeme,
+          line: start_line,
+          column: start_column,
+          start_pos: start_pos,
+          end_pos: @index
+        )
+      end
+
+      def consume_unknown
+        start_pos = @index
+        start_line = @line
+        start_column = @column
+        char = current_char
+        advance
+        Token.new(
+          type: :UNKNOWN,
+          value: char,
+          lexeme: char,
+          line: start_line,
+          column: start_column,
+          start_pos: start_pos,
+          end_pos: @index
+        )
+      end
+
+      def build_token(type, value, triple)
+        start_pos, start_line, start_column = triple
+        Token.new(
+          type: type,
+          value: value,
+          lexeme: @text[start_pos...@index],
+          line: start_line,
+          column: start_column,
+          start_pos: start_pos,
+          end_pos: @index
+        )
+      end
+
+      def current_char
+        @text[@index]
+      end
+
+      def peek_char(offset = 1)
+        @text[@index + offset]
+      end
+
+      def advance(count = 1)
+        count.times do
+          break if eof?
+
+          if current_char == "\n"
+            @line += 1
+            @column = 1
+          else
+            @column += 1
+          end
+          @index += 1
+        end
+      end
+
+      def eof?
+        @index >= @text.length
+      end
+
+      def digit?(char)
+        !char.nil? && char >= "0" && char <= "9"
+      end
+
+      def identifier_start?(char)
+        !char.nil? && ((char >= "a" && char <= "z") || (char >= "A" && char <= "Z") || char == "_")
+      end
+
+      def identifier_part?(char)
+        identifier_start?(char) || digit?(char) || char == "-"
+      end
+    end
+  end
+end