ast-template 7.1.10 → 7.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4509a90704ed26fc5cf41a36d21cebde27bb6c0859831f61234b3e0f4236dc89
-  data.tar.gz: 8764fbc1188e4d07232410d74bb073b45c6aa8f9f556c1ad3015621ff2d0bafd
+  metadata.gz: d333d88ffe0b32f1cf3bce7401deaaad28eaca1f40defae1d787e3fe782c6ebd
+  data.tar.gz: 903c10dc9ad0b5825ade7d2cd41fc0d9a2b0722b1ee0be425d41a5d70efe5c52
 SHA512:
-  metadata.gz: be5a7b2e71c9b7132f6e9595e9795b0e8b2f614ae3a76ec9e9a386881a3af43d197e332ed39a9f07b5d1cf2eae25d6fe55c7ce8d055ca23a9dc449328b0e63fd
-  data.tar.gz: a0048712a2b6158324b1991d026769dbd35ebc0a69820fec77c5987b69057eccda088d8bdcd0b266e49834c181e7449264f73c79990209b8a196bf68dd389b55
+  metadata.gz: 618776085a1f8680cba8e8640149129a71c8d9589a08c6a0536bef146a15d38db0fb5832b450d596d2368dc6a30c198be22f2e2b2c57a8e8ffa5a23343e8e991
+  data.tar.gz: f86daa1f153f431e3b27c8fd0fb9d63a4cf5f9af1657a6ea88116361e89db7de473e3e46d743d4bcd0e324be8a04b382977dcbe2b5816a9511402307b7ecdd84

data/lib/ast/template/file_types.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Ast
+  module Template
+    # Destination-path file-type detection. Contract: structuredmerge/spec
+    # slice-1043, fixtures at
+    # structuredmerge/fixtures/templating/slice-1043-merge-dispatch.
+    #
+    # First match wins; the rule order is load-bearing (e.g. `.gemfile`
+    # shadows the appraisals rule for `Appraisal.root.gemfile` — preserved
+    # from kettle-jem's effective behavior and documented in the slice).
+    module FileTypes
+      RUBY_BASENAMES = %w[Gemfile Rakefile Appraisals Appraisal.root.gemfile .simplecov].freeze
+      RUBY_SUFFIXES = %w[.gemspec .gemfile].freeze
+      RUBY_EXTENSIONS = %w[.rb .rake].freeze
+
+      module_function
+
+      # @param path [String] logical destination path
+      # @param configured [String, Symbol, nil] destination-config override
+      # @return [Symbol] the file type
+      def detect(path, configured: nil)
+        return configured.to_sym unless configured.to_s.empty?
+
+        relative_path = path.to_s
+        basename = File.basename(relative_path)
+        extension = File.extname(relative_path).downcase
+        return :gitignore if basename == ".gitignore"
+        return :gemfile if basename == "Gemfile" || basename.end_with?(".gemfile")
+        return :appraisals if basename.start_with?("Appraisals")
+        return :gemspec if basename.end_with?(".gemspec")
+        return :rakefile if basename == "Rakefile" || extension == ".rake"
+        return :ruby if RUBY_BASENAMES.include?(basename) ||
+          RUBY_SUFFIXES.any? { |suffix| basename.end_with?(suffix) } ||
+          RUBY_EXTENSIONS.include?(extension)
+        return :yaml if extension.match?(/\A\.ya?ml\z/) || basename.casecmp("citation.cff").zero?
+        return :toml if extension == ".toml"
+        return :jsonc if relative_path == ".devcontainer/devcontainer.json"
+        return :jsonc if extension == ".jsonc"
+        return :json5 if extension == ".json5"
+        return :json if extension == ".json"
+        return :markdown if extension.match?(/\A\.md(?:own)?\z/)
+        return :dotenv if basename.start_with?(".env") || basename.end_with?(".env") || extension == ".env"
+        return :rbs if extension == ".rbs"
+
+        :text
+      end
+    end
+  end
+end

data/lib/ast/template/merge_dispatch.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Ast
+  module Template
+    # Merge dispatch: route a file type to its merger adapter. Contract:
+    # structuredmerge/spec slice-1043, fixtures at
+    # structuredmerge/fixtures/templating/slice-1043-merge-dispatch.
+    #
+    # Default adapters wrap the ast-merge family gems and are required LAZILY —
+    # ast-template does not hard-depend on merger gems; the consumer's bundle
+    # provides them. Types needing consumer policy (gemspec, the Ruby family,
+    # json variants, dotenv, rbs, bash, gitignore) have no default adapter —
+    # register one.
+    module MergeDispatch
+      Adapter = Struct.new(:gem_name, :require_path, :invoke)
+
+      DEFAULT_ADAPTERS = {
+        yaml: Adapter.new("psych-merge", "psych/merge", ->(t, d, **opts) { Psych::Merge.merge_yaml(t, d, "yaml", **opts) }),
+        toml: Adapter.new("citrus-toml-merge", "citrus/toml/merge", ->(t, d, **opts) { Citrus::Toml::Merge.merge_toml(t, d, "toml", **opts) }),
+        markdown: Adapter.new("markdown-merge", "markdown/merge", ->(t, d, **opts) { Markdown::Merge.merge_markdown(t, d, "markdown", **opts) })
+      }.freeze
+
+      @adapters = {}
+
+      class << self
+        # Register an adapter for a file type. The callable receives
+        # (template_content, destination_content, **options) and returns the
+        # merger result hash ({ok:, output:, diagnostics:}).
+        def register(file_type, callable = nil, &block)
+          adapter = callable || block
+          raise ArgumentError, "adapter callable required" unless adapter.respond_to?(:call)
+
+          adapters[file_type.to_sym] = adapter
+        end
+
+        # Whether any adapter (registered or default) exists for the type.
+        def registered?(file_type)
+          adapters.key?(file_type.to_sym) || DEFAULT_ADAPTERS.key?(file_type.to_sym)
+        end
+
+        # Dispatch to the type's adapter. Returns nil when no adapter exists —
+        # the caller's fallback is the template content.
+        #
+        # @return [Hash, nil] the merger result, or nil when unregistered
+        def dispatch(file_type, template_content, destination_content, **options)
+          type = file_type.to_sym
+          registered = adapters[type]
+          return registered.call(template_content, destination_content, **options) if registered
+
+          default = DEFAULT_ADAPTERS[type]
+          return nil unless default
+
+          begin
+            require default.require_path
+          rescue LoadError
+            raise LoadError, "merge dispatch for #{type} requires #{default.gem_name}; add it to the consumer bundle"
+          end
+          default.invoke.call(template_content, destination_content, **options)
+        end
+
+        # Test support: clear consumer-registered adapters.
+        def reset!
+          @adapters = {}
+        end
+
+        private
+
+        def adapters
+          @adapters ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/ast/template/strategies.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Ast
+  module Template
+    # Strategy resolution and application decisions for template entries.
+    # Contract: structuredmerge/spec slice-1042, conformance fixtures at
+    # structuredmerge/fixtures/templating/slice-1042-strategy-application.
+    #
+    # The vocabulary (execution_action / write_action / status) matches the
+    # slice-353 session transport fixtures. The merger itself is the next
+    # contract surface (slice-1043); `merge` on differing content stops at
+    # the decision here.
+    module Strategies
+      # The four strategy names a destination config may declare.
+      STRATEGIES = %w[merge keep_destination raw_copy accept_template].freeze
+      DEFAULT_STRATEGY = "merge"
+
+      module_function
+
+      # Effective strategy for a destination path: the matching override wins,
+      # else the default. Overrides are TemplateStrategyOverride-shaped
+      # entries ({path:, strategy:} with string or symbol keys).
+      #
+      # @param default [String] strategy when no override matches
+      # @param overrides [Array<Hash>] per-path strategy overrides
+      # @param path [String] logical destination path
+      # @return [String] the effective strategy
+      def resolve(default: DEFAULT_STRATEGY, overrides: [], path:)
+        override = Array(overrides).find { |entry| (entry[:path] || entry["path"]) == path }
+        strategy = override && (override[:strategy] || override["strategy"])
+        strategy.to_s.empty? ? default : strategy.to_s
+      end
+
+      # The decision for one entry. Content is present only when this contract
+      # owns it (raw_copy, accept_template, merge-with-empty-destination);
+      # keep decisions and merge-of-differences return no content (the latter
+      # defers to the merger).
+      #
+      # @param strategy [String] resolved strategy for the entry
+      # @param template_content [String] prepared template content
+      # @param destination_content [String, nil] current destination content
+      #   (nil when the destination file is absent)
+      # @return [Hash] {execution_action:, write_action:, status:, content:}
+      def plan_entry(strategy:, template_content:, destination_content:)
+        strategy = strategy.to_s
+        return keep_decision if strategy == "keep_destination"
+
+        absent = destination_content.nil?
+        if strategy == "merge"
+          trivial = trivial_merge_outcome(template_content, destination_content)
+          return keep_decision if trivial == :identical
+          return write_decision("merge_prepared_content", absent, template_content) if trivial == :empty_destination
+        end
+
+        # accept_template and merge-of-differences both write prepared content;
+        # for merge-of-differences the content is the merger's, not ours.
+        content = (strategy == "merge") ? nil : template_content
+        write_decision(execution_action_for(strategy), absent, content)
+      end
+
+      # Whether the strategy leaves the destination untouched. Absent
+      # destinations are not created under keep_destination.
+      def keep_destination?(strategy)
+        strategy.to_s == "keep_destination"
+      end
+
+      # The merge short-circuits that never invoke a merger:
+      # :empty_destination when there is nothing to merge into (template
+      # becomes the content), :identical when destination already equals
+      # template (destination is kept), nil when a real merge is required.
+      def trivial_merge_outcome(template_content, destination_content)
+        return :empty_destination if destination_content.to_s.strip.empty?
+        return :identical if destination_content == template_content
+
+        nil
+      end
+
+      def keep_decision
+        {execution_action: "keep", write_action: "keep", status: "keep", content: nil}
+      end
+
+      def write_decision(execution_action, create, content)
+        action = create ? "create" : "update"
+        {execution_action: execution_action, write_action: action, status: action, content: content}
+      end
+
+      def execution_action_for(strategy)
+        (strategy == "raw_copy") ? "raw_copy" : "merge_prepared_content"
+      end
+    end
+  end
+end

data/lib/ast/template/token_application.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'token/resolver'
+
+module Ast
+  module Template
+    # Token application policy: normalize replacements, resolve with
+    # on-missing keep, then police tokens that survive in the consumer's
+    # namespace. Token mechanics (parsing, grammar) live in token-resolver;
+    # this module is the contract surface defined by
+    # structuredmerge/spec slice-1041 and its conformance fixtures.
+    module TokenApplication
+      # Raised when resolved output still contains tokens in the consumer's
+      # namespace. Carries the sorted, deduplicated canonical full keys so
+      # consumers can re-raise with their own branded message.
+      class UnresolvedTokensError < ArgumentError
+        # @return [Array<String>] canonical full token keys, sorted
+        attr_reader :tokens
+
+        def initialize(tokens)
+          @tokens = tokens
+          super("unresolved template tokens: #{tokens.map { |token| "{#{token}}" }.join(', ')}")
+        end
+      end
+
+      module_function
+
+      # Resolve tokens in content, then (when scanning) raise if any token in
+      # the consumer's namespace survived. Missing replacements are kept
+      # verbatim — in canonical form, so the scan sees canonical keys.
+      #
+      # @param content [String] template content
+      # @param replacements [Hash] token canonical key => value (keys and
+      #   values are stringified before resolution)
+      # @param config [Token::Resolver::Config] token structure config
+      # @param namespace [String] first-segment namespace the consumer owns
+      # @param scan_unresolved [Boolean] when false, unresolved tokens pass
+      # @return [String] resolved content
+      # @raise [UnresolvedTokensError] unresolved namespaced tokens remain
+      def apply_tokens(content, replacements, config:, namespace:, scan_unresolved: true)
+        document = Token::Resolver::Document.new(content.to_s, config: config)
+        resolved = Token::Resolver::Resolve.new(on_missing: :keep).resolve(document, stringify_replacements(replacements))
+        return resolved unless scan_unresolved
+
+        unresolved = unresolved_namespaced_tokens(resolved, config: config, namespace: namespace)
+        return resolved if unresolved.empty?
+
+        raise UnresolvedTokensError, unresolved
+      end
+
+      # Sorted, deduplicated canonical keys of tokens in content whose first
+      # segment equals namespace.
+      #
+      # @return [Array<String>]
+      def unresolved_namespaced_tokens(content, config:, namespace:)
+        Token::Resolver::Document.new(content.to_s, config: config)
+          .token_keys
+          .select { |key| key.split(config.separators.first, 2).first == namespace }
+          .uniq
+          .sort
+      end
+
+      # Normalize replacements for the resolver: string keys and values.
+      #
+      # @return [Hash{String => String}]
+      def stringify_replacements(replacements)
+        replacements.to_h.transform_keys(&:to_s).transform_values(&:to_s)
+      end
+    end
+  end
+end

data/lib/ast/template/version.rb

@@ -5,7 +5,7 @@ module Ast
     # Version namespace for this gem.
     module Version
       # Current gem version.
-      VERSION = '7.1.10'
+      VERSION = '7.1.11'
     end
     # Current gem version exposed at the traditional constant location.
     VERSION = Version::VERSION # Traditional Constant Location

data/lib/ast/template.rb

@@ -25,7 +25,11 @@ module Ast
       'rust' => 'Rust',
       'typescript' => 'TypeScript'
     }.freeze
+    autoload :FileTypes, 'ast/template/file_types'
+    autoload :MergeDispatch, 'ast/template/merge_dispatch'
     autoload :RustHostProvider, 'ast/template/rust_host_provider'
+    autoload :Strategies, 'ast/template/strategies'
+    autoload :TokenApplication, 'ast/template/token_application'
 
     class << self
       def rust_host_provider

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ast-template
 version: !ruby/object:Gem::Version
-  version: 7.1.10
+  version: 7.1.11
 platform: ruby
 authors:
 - Peter H. Boling
@@ -43,14 +43,34 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.10
+        version: 7.1.11
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.10
+        version: 7.1.11
+- !ruby/object:Gem::Dependency
+  name: token-resolver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.10
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.10
 - !ruby/object:Gem::Dependency
   name: version_gem
   requirement: !ruby/object:Gem::Requirement
@@ -285,7 +305,11 @@ files:
 - README.md
 - lib/ast-template.rb
 - lib/ast/template.rb
+- lib/ast/template/file_types.rb
+- lib/ast/template/merge_dispatch.rb
 - lib/ast/template/rust_host_provider.rb
+- lib/ast/template/strategies.rb
+- lib/ast/template/token_application.rb
 - lib/ast/template/typed_core_bridge.rb
 - lib/ast/template/version.rb
 - sig/ast/template.rbs
@@ -295,10 +319,10 @@ licenses:
 - PolyForm-Small-Business-1.0.0
 metadata:
   homepage_uri: https://structuredmerge.org
-  source_code_uri: https://github.com/structuredmerge/structuredmerge-ruby/tree/v7.1.10
-  changelog_uri: https://github.com/structuredmerge/structuredmerge-ruby/blob/v7.1.10/CHANGELOG.md
+  source_code_uri: https://github.com/structuredmerge/structuredmerge-ruby/tree/v7.1.11
+  changelog_uri: https://github.com/structuredmerge/structuredmerge-ruby/blob/v7.1.11/CHANGELOG.md
   bug_tracker_uri: https://github.com/structuredmerge/structuredmerge-ruby/issues
-  documentation_uri: https://www.rubydoc.info/gems/ast-template/7.1.10
+  documentation_uri: https://www.rubydoc.info/gems/ast-template/7.1.11
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/structuredmerge/structuredmerge-ruby/wiki
   news_uri: https://www.railsbling.com/tags/ast-template