foxtail-tools 0.5.0

data/lib/foxtail/syntax/serializer.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module Foxtail
+  module Syntax
+    # Serializes AST nodes back to FTL format
+    class Serializer
+      # Create a new Serializer instance
+      # @param with_junk [Boolean] Whether to include junk entries in output (default: false)
+      def initialize(with_junk: false)
+        @with_junk = with_junk
+      end
+
+      # @return [Boolean] Whether to include junk entries in output
+      def with_junk? = @with_junk
+
+      # Serialize a Resource AST to FTL string
+      # @param resource [Parser::AST::Resource] Resource to serialize
+      # @return [String] FTL formatted source text
+      def serialize(resource)
+        has_entries = false
+        parts = []
+
+        resource.body.each do |entry|
+          next if entry.is_a?(Parser::AST::Junk) && !with_junk?
+
+          parts << serialize_entry(entry, has_entries:)
+          has_entries = true
+        end
+
+        parts.join
+      end
+
+      # Serialize a single entry (Message, Term, Comment, or Junk)
+      # @param entry [Parser::AST::Message, Parser::AST::Term, Parser::AST::BaseComment, Parser::AST::Junk] Entry to serialize
+      # @param has_entries [Boolean] Whether previous entries exist (for spacing)
+      # @return [String] FTL formatted entry text
+      def serialize_entry(entry, has_entries: false)
+        case entry
+        when Parser::AST::Message
+          serialize_message(entry)
+        when Parser::AST::Term
+          serialize_term(entry)
+        when Parser::AST::Comment
+          serialize_standalone_comment(entry, "#", has_entries)
+        when Parser::AST::GroupComment
+          serialize_standalone_comment(entry, "##", has_entries)
+        when Parser::AST::ResourceComment
+          serialize_standalone_comment(entry, "###", has_entries)
+        when Parser::AST::Junk
+          serialize_junk(entry)
+        else
+          raise ArgumentError, "Unknown entry type: #{entry.class}"
+        end
+      end
+
+      private def serialize_standalone_comment(comment, prefix, has_entries)
+        result = serialize_comment(comment, prefix)
+        if has_entries
+          "\n#{result}\n"
+        else
+          "#{result}\n"
+        end
+      end
+
+      private def serialize_comment(comment, prefix="#")
+        prefixed = comment.content.split("\n").map {|line|
+          line.empty? ? prefix : "#{prefix} #{line}"
+        }.join("\n")
+        "#{prefixed}\n"
+      end
+
+      private def serialize_junk(junk) = junk.content
+
+      private def serialize_message(message)
+        parts = []
+        parts << serialize_comment(message.comment) if message.comment
+        parts << "#{message.id.name} ="
+        parts << serialize_pattern(message.value) if message.value
+        message.attributes.each {|attr| parts << serialize_attribute(attr) }
+        parts << "\n"
+        parts.join
+      end
+
+      private def serialize_term(term)
+        parts = []
+        parts << serialize_comment(term.comment) if term.comment
+        parts << "-#{term.id.name} ="
+        parts << serialize_pattern(term.value)
+        term.attributes.each {|attr| parts << serialize_attribute(attr) }
+        parts << "\n"
+        parts.join
+      end
+
+      private def serialize_attribute(attribute)
+        value = indent_except_first_line(serialize_pattern(attribute.value))
+        "\n    .#{attribute.id.name} =#{value}"
+      end
+
+      private def serialize_pattern(pattern)
+        content = pattern.elements.map {|elem| serialize_element(elem) }.join
+
+        if should_start_on_new_line?(pattern)
+          "\n    #{indent_except_first_line(content)}"
+        else
+          " #{indent_except_first_line(content)}"
+        end
+      end
+
+      private def serialize_element(element)
+        case element
+        when Parser::AST::TextElement
+          element.value
+        when Parser::AST::Placeable
+          serialize_placeable(element)
+        else
+          raise ArgumentError, "Unknown element type: #{element.class}"
+        end
+      end
+
+      private def serialize_placeable(placeable)
+        expr = placeable.expression
+        case expr
+        when Parser::AST::Placeable
+          "{#{serialize_placeable(expr)}}"
+        when Parser::AST::SelectExpression
+          "{ #{serialize_expression(expr)}}"
+        else
+          "{ #{serialize_expression(expr)} }"
+        end
+      end
+
+      private def serialize_expression(expr)
+        case expr
+        when Parser::AST::StringLiteral
+          "\"#{expr.value}\""
+        when Parser::AST::NumberLiteral
+          expr.value
+        when Parser::AST::VariableReference
+          "$#{expr.id.name}"
+        when Parser::AST::TermReference
+          serialize_term_reference(expr)
+        when Parser::AST::MessageReference
+          serialize_message_reference(expr)
+        when Parser::AST::FunctionReference
+          "#{expr.id.name}#{serialize_call_arguments(expr.arguments)}"
+        when Parser::AST::SelectExpression
+          serialize_select_expression(expr)
+        when Parser::AST::Placeable
+          serialize_placeable(expr)
+        else
+          raise ArgumentError, "Unknown expression type: #{expr.class}"
+        end
+      end
+
+      private def serialize_term_reference(ref)
+        out = "-#{ref.id.name}"
+        out += ".#{ref.attribute.name}" if ref.attribute
+        out += serialize_call_arguments(ref.arguments) if ref.arguments
+        out
+      end
+
+      private def serialize_message_reference(ref)
+        out = ref.id.name
+        out += ".#{ref.attribute.name}" if ref.attribute
+        out
+      end
+
+      private def serialize_select_expression(expr)
+        out = "#{serialize_expression(expr.selector)} ->"
+        expr.variants.each {|variant| out += serialize_variant(variant) }
+        "#{out}\n"
+      end
+
+      private def serialize_variant(variant)
+        key = serialize_variant_key(variant.key)
+        value = indent_except_first_line(serialize_pattern(variant.value))
+
+        if variant.default
+          "\n   *[#{key}]#{value}"
+        else
+          "\n    [#{key}]#{value}"
+        end
+      end
+
+      private def serialize_variant_key(key)
+        case key
+        when Parser::AST::Identifier
+          key.name
+        when Parser::AST::NumberLiteral
+          key.value
+        else
+          raise ArgumentError, "Unknown variant key type: #{key.class}"
+        end
+      end
+
+      private def serialize_call_arguments(args)
+        return "()" if args.nil?
+
+        positional = args.positional.map {|arg| serialize_expression(arg) }.join(", ")
+        named = args.named.map {|arg| serialize_named_argument(arg) }.join(", ")
+
+        if !positional.empty? && !named.empty?
+          "(#{positional}, #{named})"
+        else
+          "(#{positional}#{named})"
+        end
+      end
+
+      private def serialize_named_argument(arg)
+        value = serialize_expression(arg.value)
+        "#{arg.name.name}: #{value}"
+      end
+
+      private def indent_except_first_line(content)
+        content.split("\n").join("\n    ")
+      end
+
+      private def should_start_on_new_line?(pattern)
+        is_multiline = pattern.elements.any? {|elem|
+          select_expr?(elem) || includes_newline?(elem)
+        }
+
+        return false unless is_multiline
+
+        first_element = pattern.elements.first
+        return true unless first_element.is_a?(Parser::AST::TextElement)
+
+        first_char = first_element.value[0]
+        # These characters may not appear as the first character on a new line
+        !["[", ".", "*"].include?(first_char)
+      end
+
+      private def select_expr?(elem)
+        elem.is_a?(Parser::AST::Placeable) && elem.expression.is_a?(Parser::AST::SelectExpression)
+      end
+
+      private def includes_newline?(elem)
+        elem.is_a?(Parser::AST::TextElement) && elem.value.include?("\n")
+      end
+    end
+  end
+end

data/lib/foxtail/syntax/visitor.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Foxtail
+  module Syntax
+    # Visitor module for traversing AST nodes
+    #
+    # Include this module and override the visit_* methods you need.
+    # By default, all visit_* methods traverse children automatically.
+    # Override a method and omit `super` to stop traversal at that node.
+    #
+    # @example Collecting message IDs
+    #   class MessageIdCollector
+    #     include Foxtail::Syntax::Visitor
+    #
+    #     def initialize
+    #       @ids = []
+    #     end
+    #
+    #     attr_reader :ids
+    #
+    #     def visit_message(node)
+    #       @ids << node.id.name
+    #       super  # continue traversal
+    #     end
+    #   end
+    #
+    #   collector = MessageIdCollector.new
+    #   resource.accept(collector)
+    #   collector.ids # => ["hello", "goodbye", ...]
+    module Visitor
+      def visit_resource(node) = visit_children(node)
+      def visit_message(node) = visit_children(node)
+      def visit_term(node) = visit_children(node)
+      def visit_attribute(node) = visit_children(node)
+      def visit_pattern(node) = visit_children(node)
+      def visit_placeable(node) = visit_children(node)
+      def visit_select_expression(node) = visit_children(node)
+      def visit_variant(node) = visit_children(node)
+      def visit_call_arguments(node) = visit_children(node)
+      def visit_named_argument(node) = visit_children(node)
+      def visit_message_reference(node) = visit_children(node)
+      def visit_term_reference(node) = visit_children(node)
+      def visit_function_reference(node) = visit_children(node)
+      def visit_variable_reference(node) = visit_children(node)
+      def visit_string_literal(node) = visit_children(node)
+      def visit_number_literal(node) = visit_children(node)
+      def visit_text_element(node) = visit_children(node)
+      def visit_identifier(node) = visit_children(node)
+      def visit_comment(node) = visit_children(node)
+      def visit_group_comment(node) = visit_children(node)
+      def visit_resource_comment(node) = visit_children(node)
+      def visit_junk(node) = visit_children(node)
+      def visit_annotation(node) = visit_children(node)
+      def visit_span(node) = visit_children(node)
+
+      def visit_children(node)
+        node.children.each {|child| child&.accept(self) }
+      end
+    end
+  end
+end

data/lib/foxtail/syntax.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Foxtail
+  # Syntax module provides full FTL parsing with complete AST representation.
+  # This is the fluent-syntax equivalent, suitable for tools like linters,
+  # formatters, and editors that need position information and comments.
+  #
+  # For runtime message formatting, use {Foxtail::Bundle} instead which uses
+  # a lightweight parser optimized for execution.
+  module Syntax
+  end
+end

data/lib/foxtail/tools/error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Foxtail
+  module Tools
+    # Base error class for all Foxtail Tools-specific exceptions
+    class Error < StandardError; end
+  end
+end

data/lib/foxtail/tools/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Foxtail
+  module Tools
+    # Current version of the Foxtail tools gem
+    VERSION = "0.5.0"
+    public_constant :VERSION
+  end
+end

data/lib/foxtail-tools.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require_relative "foxtail/tools/version"
+
+# Tooling entrypoint for Foxtail (syntax + CLI)
+module Foxtail
+  loader = Zeitwerk::Loader.new
+  loader.push_dir(__dir__ + "/foxtail", namespace: Foxtail)
+
+  # Ignore version.rb since it's required by gemspec before Zeitwerk loads
+  loader.ignore(__dir__ + "/foxtail/tools/version.rb")
+  # Ignore gem entrypoint file (no constant defined)
+  loader.ignore(__dir__ + "/foxtail-tools.rb")
+
+  loader.inflector.inflect(
+    "ast" => "AST",
+    "cli" => "CLI"
+  )
+
+  loader.setup
+end

metadata

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification
+name: foxtail-tools
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- OZAWA Sakuro
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-05-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: dry-inflector
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+description: 'Tooling components for Foxtail: fluent syntax parser/serializer and
+  CLI utilities.
+
+  '
+email:
+- 10973+sakuro@users.noreply.github.com
+executables:
+- foxtail
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/foxtail
+- lib/foxtail-tools.rb
+- lib/foxtail/cli.rb
+- lib/foxtail/cli/commands/check.rb
+- lib/foxtail/cli/commands/dump.rb
+- lib/foxtail/cli/commands/ids.rb
+- lib/foxtail/cli/commands/tidy.rb
+- lib/foxtail/syntax.rb
+- lib/foxtail/syntax/error.rb
+- lib/foxtail/syntax/parser.rb
+- lib/foxtail/syntax/parser/ast.rb
+- lib/foxtail/syntax/parser/ast/annotation.rb
+- lib/foxtail/syntax/parser/ast/attribute.rb
+- lib/foxtail/syntax/parser/ast/base_comment.rb
+- lib/foxtail/syntax/parser/ast/base_literal.rb
+- lib/foxtail/syntax/parser/ast/base_node.rb
+- lib/foxtail/syntax/parser/ast/call_arguments.rb
+- lib/foxtail/syntax/parser/ast/comment.rb
+- lib/foxtail/syntax/parser/ast/function_reference.rb
+- lib/foxtail/syntax/parser/ast/group_comment.rb
+- lib/foxtail/syntax/parser/ast/identifier.rb
+- lib/foxtail/syntax/parser/ast/junk.rb
+- lib/foxtail/syntax/parser/ast/message.rb
+- lib/foxtail/syntax/parser/ast/message_reference.rb
+- lib/foxtail/syntax/parser/ast/named_argument.rb
+- lib/foxtail/syntax/parser/ast/number_literal.rb
+- lib/foxtail/syntax/parser/ast/pattern.rb
+- lib/foxtail/syntax/parser/ast/placeable.rb
+- lib/foxtail/syntax/parser/ast/resource.rb
+- lib/foxtail/syntax/parser/ast/resource_comment.rb
+- lib/foxtail/syntax/parser/ast/select_expression.rb
+- lib/foxtail/syntax/parser/ast/span.rb
+- lib/foxtail/syntax/parser/ast/string_literal.rb
+- lib/foxtail/syntax/parser/ast/syntax_node.rb
+- lib/foxtail/syntax/parser/ast/term.rb
+- lib/foxtail/syntax/parser/ast/term_reference.rb
+- lib/foxtail/syntax/parser/ast/text_element.rb
+- lib/foxtail/syntax/parser/ast/variable_reference.rb
+- lib/foxtail/syntax/parser/ast/variant.rb
+- lib/foxtail/syntax/parser/parse_error.rb
+- lib/foxtail/syntax/parser/stream.rb
+- lib/foxtail/syntax/serializer.rb
+- lib/foxtail/syntax/visitor.rb
+- lib/foxtail/tools/error.rb
+- lib/foxtail/tools/version.rb
+homepage: https://github.com/sakuro/foxtail
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/sakuro/foxtail
+  source_code_uri: https://github.com/sakuro/foxtail.git
+  changelog_uri: https://github.com/sakuro/foxtail/blob/main/foxtail-tools/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Foxtail CLI and syntax tooling for Project Fluent
+test_files: []