asciisourcerer 0.1.0 → 0.2.1

data/lib/sourcerer/sync/block_parser.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module Sourcerer
+  module Sync
+    # Parses tagged regions from any text file, regardless of comment style
+    #
+    # Recognizes AsciiDoc `tag::`/`end::` markers in HTML comments, AsciiDoc line comments,
+    #  and shell/Ruby/YAML comments.
+    # The trailing `[]` is optional.
+    # See the project README for the full tag-syntax reference.
+    module BlockParser
+      # A tagged region extracted from a file
+      #
+      # @!attribute tag [String] The tag name (e.g. `universal-agency`)
+      # @!attribute open_line [String] The complete opening marker line, including newline
+      # @!attribute content [String] Everything between the open and close markers
+      # @!attribute close_line [String] The complete closing marker line, including newline
+      Block = Struct.new(:tag, :open_line, :content, :close_line, keyword_init: true)
+
+      # Plain text in between (or around) tagged blocks
+      #
+      # @!attribute content [String] The raw text
+      TextSegment = Struct.new(:content, keyword_init: true)
+
+      # Raised when tag markers are structurally invalid
+      class ParseError < StandardError
+      end
+
+      # Default prefix that marks a block as canonical (managed by Sync/Cast).
+      DEFAULT_CANONICAL_PREFIX = 'universal-'
+
+      # Default opening tag marker template.
+      # `<tagged_block_name>` is the placeholder for the block name character class.
+      # A trailing `[]` is treated as optional in the compiled pattern.
+      DEFAULT_TAG_SYNTAX_START = 'tag::<tagged_block_name>[]'
+
+      # Default closing tag marker template.
+      DEFAULT_TAG_SYNTAX_END = 'end::<tagged_block_name>[]'
+
+      # Default comment-wrapper templates.
+      # `<tag_syntax>` is the placeholder for the compiled tag marker pattern.
+      # A space between the comment delimiter and `<tag_syntax>` compiles as `\s*`.
+      DEFAULT_COMMENT_SYNTAX_PATTERNS = [
+        '<!-- <tag_syntax> -->',
+        '// <tag_syntax>',
+        '# <tag_syntax>'
+      ].freeze
+
+      # Compile a tag marker template string into a plain regex fragment (no `\A` anchor).
+      #
+      # `<tagged_block_name>` is replaced with the `(?<tag>[\w-]+)` named capture group.
+      # A trailing `[]` in the template becomes `(?:\[\])?` (optional literal brackets).
+      #
+      # @param template [String] e.g. `'tag::<tagged_block_name>[]'`
+      # @return [String] regex source string
+      def self.tag_template_to_inner_regex template
+        parts  = template.split('<tagged_block_name>', 2)
+        left   = Regexp.escape(parts[0])
+        right  = parts[1].to_s
+        suffix = right == '[]' ? '(?:\[\])?' : Regexp.escape(right)
+        "#{left}(?<tag>[\\w-]+)#{suffix}"
+      end
+
+      # Wrap a compiled inner-tag regex fragment with a comment-wrapper template.
+      #
+      # `<tag_syntax>` in `comment_template` is replaced by `inner_regex`.
+      # Adjacent literal spaces around `<tag_syntax>` are compiled as `\s*`.
+      # The result is anchored to `\A`.
+      #
+      # @param comment_template [String] e.g. `'<!-- <tag_syntax> -->'`
+      # @param inner_regex [String] regex source from {.tag_template_to_inner_regex}
+      # @return [String] full anchored regex source string
+      def self.comment_template_to_full_regex comment_template, inner_regex
+        halves    = comment_template.split('<tag_syntax>', 2)
+        left_raw  = halves[0]
+        right_raw = halves[1].to_s
+        left_trim  = left_raw.rstrip
+        right_trim = right_raw.lstrip
+        left_re  = Regexp.escape(left_trim) + (left_trim == left_raw ? '' : '\s*')
+        right_re = (right_trim == right_raw ? '' : '\s*') + Regexp.escape(right_trim)
+        "\\A#{left_re}#{inner_regex}#{right_re}"
+      end
+
+      # Compile template strings into a patterns array compatible with {.parse}.
+      #
+      # Each entry in the returned array is a `{open: Regexp, close: Regexp}` hash.
+      # This is the same shape as {DEFAULT_TAG_PATTERNS} and may be passed directly
+      # to {.parse} via the `tag_patterns:` keyword to avoid recompilation per call.
+      #
+      # @param tag_start [String] opening tag template (default {DEFAULT_TAG_SYNTAX_START})
+      # @param tag_end [String] closing tag template (default {DEFAULT_TAG_SYNTAX_END})
+      # @param comment_patterns [Array<String>] comment-wrapper templates
+      #   (default {DEFAULT_COMMENT_SYNTAX_PATTERNS})
+      # @return [Array<Hash>]
+      def self.build_tag_patterns tag_start, tag_end, comment_patterns
+        open_inner  = tag_template_to_inner_regex(tag_start)
+        close_inner = tag_template_to_inner_regex(tag_end)
+        comment_patterns.map do |cp|
+          {
+            open:  Regexp.new(comment_template_to_full_regex(cp, open_inner)),
+            close: Regexp.new(comment_template_to_full_regex(cp, close_inner))
+          }
+        end
+      end
+
+      # Default compiled pattern set, built from the three DEFAULT_* template constants.
+      # Retained for backward compatibility; prefer the template constants for customisation.
+      DEFAULT_TAG_PATTERNS = build_tag_patterns(
+        DEFAULT_TAG_SYNTAX_START,
+        DEFAULT_TAG_SYNTAX_END,
+        DEFAULT_COMMENT_SYNTAX_PATTERNS).freeze
+
+      # Backward-compatible alias for {DEFAULT_TAG_PATTERNS}.
+      TAG_PATTERNS = DEFAULT_TAG_PATTERNS
+
+      # Parse a text string into an array of {TextSegment} and {Block} objects.
+      #
+      # The result is ordered and reconstructable: joining every element's
+      #  serialized form reproduces the original text character-perfectly.
+      #
+      # Only blocks whose tag name starts with `canonical_prefix` are parsed as
+      #  proper {Block} objects; all other tag markers (open and close) are
+      #  treated as ordinary text.
+      # This makes the parser robust against files that use tag markers for unrelated
+      #  purposes (e.g. AsciiDoc `include::` target regions or non-canonical project sections)
+      #  regardless of whether those regions are properly closed or even nested.
+      #
+      # When a canonical block is open, every line is treated as content until
+      #  the matching close marker appears (including any inner tag markers).
+      # Canonical blocks therefore cannot be nested.
+      #
+      # @param text [String] Full text of the file to parse
+      # @param canonical_prefix [String] Only tags starting with this prefix
+      #   are parsed as managed {Block} objects (default {DEFAULT_CANONICAL_PREFIX}).
+      # @param tag_syntax_start [String] Opening tag template; used to build
+      #   patterns when `tag_patterns:` is not given (default {DEFAULT_TAG_SYNTAX_START}).
+      # @param tag_syntax_end [String] Closing tag template (default {DEFAULT_TAG_SYNTAX_END}).
+      # @param comment_syntax_patterns [Array<String>] Comment-wrapper templates
+      #   (default {DEFAULT_COMMENT_SYNTAX_PATTERNS}).
+      # @param tag_patterns [Array<Hash>, nil] Pre-compiled pattern set; skips template
+      #   compilation when provided. Build once with {.build_tag_patterns} and reuse.
+      # @return [Array<TextSegment, Block>]
+      # @raise [ParseError] if a canonical tag is opened but never closed.
+      def self.parse text,
+        canonical_prefix: DEFAULT_CANONICAL_PREFIX,
+        tag_syntax_start: DEFAULT_TAG_SYNTAX_START,
+        tag_syntax_end: DEFAULT_TAG_SYNTAX_END,
+        comment_syntax_patterns: DEFAULT_COMMENT_SYNTAX_PATTERNS,
+        tag_patterns: nil
+        patterns = tag_patterns ||
+                   build_tag_patterns(tag_syntax_start, tag_syntax_end, comment_syntax_patterns)
+        lines = text.lines
+        segments = []
+        text_acc = []
+        block_state = nil # nil or { tag:, open_line:, content_lines: [] }
+
+        lines.each do |line|
+          stripped = line.chomp
+
+          if block_state.nil?
+            tag = detect_open_tag(stripped, patterns)
+            if tag&.start_with?(canonical_prefix)
+              segments << TextSegment.new(content: text_acc.join) unless text_acc.empty?
+              text_acc = []
+              block_state = { tag: tag, open_line: line, content_lines: [] }
+            else
+              # Non-canonical open tags and all close tags at the top level are
+              # treated as ordinary text.
+              text_acc << line
+            end
+          else
+            close_tag = detect_close_tag(stripped, patterns)
+            if close_tag == block_state[:tag]
+              segments << Block.new(
+                tag: block_state[:tag],
+                open_line: block_state[:open_line],
+                content: block_state[:content_lines].join,
+                close_line: line)
+              block_state = nil
+            else
+              # Nested open tags or mismatched close tags: treat as block content
+              block_state[:content_lines] << line
+            end
+          end
+        end
+
+        raise ParseError, "Unclosed canonical tag '#{block_state[:tag]}'" if block_state
+
+        segments << TextSegment.new(content: text_acc.join) unless text_acc.empty?
+        segments
+      end
+
+      # Return the tag name if `stripped_line` is an opening tag marker, else nil.
+      #
+      # @param stripped_line [String] A single line with the trailing newline removed
+      # @param patterns [Array<Hash>] compiled pattern set from {.build_tag_patterns}
+      # @return [String, nil]
+      def self.detect_open_tag stripped_line, patterns
+        patterns.each do |p|
+          m = stripped_line.match(p[:open])
+          return m[:tag] if m
+        end
+        nil
+      end
+
+      # Return the tag name if `stripped_line` is a closing tag marker, else nil.
+      #
+      # @param stripped_line [String] A single line with the trailing newline removed
+      # @param patterns [Array<Hash>] compiled pattern set from {.build_tag_patterns}
+      # @return [String, nil]
+      def self.detect_close_tag stripped_line, patterns
+        patterns.each do |p|
+          m = stripped_line.match(p[:close])
+          return m[:tag] if m
+        end
+        nil
+      end
+
+      # Extract all canonical blocks (those whose tag name starts with
+      #  `canonical_prefix`) as a Hash keyed by tag name.
+      #
+      # Because {.parse} already filters for canonical blocks when given the
+      #  same `canonical_prefix`, this method is largely a deduplication check.
+      # It raises {ParseError} if more than one canonical block carries the same
+      #  tag name, which would make synchronization ambiguous.
+      #
+      # @param segments [Array<TextSegment, Block>]
+      # @param canonical_prefix [String] Prefix that identifies managed blocks
+      # @return [Hash{String => Block}]
+      def self.extract_canonical segments, canonical_prefix: DEFAULT_CANONICAL_PREFIX
+        result = {}
+        segments.each do |s|
+          next unless s.is_a?(Block) && s.tag.start_with?(canonical_prefix)
+
+          raise ParseError, "Duplicate canonical block '#{s.tag}'" if result.key?(s.tag)
+
+          result[s.tag] = s
+        end
+        result
+      end
+
+      private_class_method :detect_open_tag, :detect_close_tag
+    end
+  end
+end

data/lib/sourcerer/sync/cast.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require_relative 'block_parser'
+
+module Sourcerer
+  module Sync
+    # Synchronizes canonical blocks from a prime template into one target file.
+    #
+    # See {Sourcerer::Sync} for the high-level interface and the project README
+    # for usage examples and a full description of the Sync/Cast model.
+    class Cast
+      # Returned by both {.sync} and {.init}.
+      #
+      # @!attribute target_path [String] Absolute path of the target file.
+      # @!attribute applied_changes [Array<String>] Tag names whose block
+      #  content was replaced (empty on a dry run even when differences exist).
+      # @!attribute warnings [Array<String>] Non-fatal diagnostic messages.
+      # @!attribute errors [Array<String>] Fatal messages; file was not written.
+      # @!attribute diff [String, nil] Unified diff output when differences were
+      #  detected (populated on dry runs and when changes were applied).
+      CastResult = Struct.new(
+        :target_path,
+        :applied_changes,
+        :warnings,
+        :errors,
+        :diff,
+        keyword_init: true)
+
+      # Synchronize canonical blocks from `prime_path` into `target_path`.
+      #
+      # @param prime_path [String] Path to the prime template file
+      # @param target_path [String] Path to the target file
+      # @param data [Hash] Liquid variables used when rendering block content
+      # @param canonical_prefix [String] Tag prefix that marks managed blocks
+      # @param tag_syntax_start [String] Opening tag marker template
+      #   (see {BlockParser::DEFAULT_TAG_SYNTAX_START})
+      # @param tag_syntax_end [String] Closing tag marker template
+      #   (see {BlockParser::DEFAULT_TAG_SYNTAX_END})
+      # @param comment_syntax_patterns [Array<String>] Comment-wrapper templates
+      #   (see {BlockParser::DEFAULT_COMMENT_SYNTAX_PATTERNS})
+      # @param dry_run [Boolean] When true, compute the diff but do not write
+      # @return [CastResult]
+      def self.sync prime_path, target_path,
+        data: {},
+        canonical_prefix: BlockParser::DEFAULT_CANONICAL_PREFIX,
+        tag_syntax_start: BlockParser::DEFAULT_TAG_SYNTAX_START,
+        tag_syntax_end: BlockParser::DEFAULT_TAG_SYNTAX_END,
+        comment_syntax_patterns: BlockParser::DEFAULT_COMMENT_SYNTAX_PATTERNS,
+        dry_run: false
+        new(
+          prime_path, target_path,
+          data: data,
+          canonical_prefix: canonical_prefix,
+          tag_syntax_start: tag_syntax_start,
+          tag_syntax_end: tag_syntax_end,
+          comment_syntax_patterns: comment_syntax_patterns,
+          dry_run: dry_run).run_sync
+      end
+
+      # Bootstrap a new target file from the prime template.
+      #
+      # During init the entire prime is rendered through Liquid before writing;
+      #  during sync only canonical block content is rendered.
+      #  See the project README for a full description of init vs sync semantics.
+      #
+      # @param prime_path [String] Path to the prime template file
+      # @param target_path [String] Path to the target file to create
+      # @param data [Hash] Liquid variables used when rendering
+      # @param dry_run [Boolean] When true, return rendered content in `diff`
+      #  but do not write.
+      # @return [CastResult]
+      def self.init prime_path, target_path, data: {}, dry_run: false
+        prime_text = File.read(prime_path)
+        rendered = data.empty? ? prime_text : render_liquid_string(prime_text, data)
+
+        unless dry_run
+          FileUtils.mkdir_p(File.dirname(File.expand_path(target_path)))
+          File.write(target_path, rendered)
+        end
+
+        CastResult.new(
+          target_path: target_path,
+          applied_changes: [],
+          warnings: [],
+          errors: [],
+          diff: dry_run ? rendered : nil)
+      end
+
+      # @api private
+      def initialize prime_path, target_path,
+        data:, canonical_prefix:,
+        tag_syntax_start:, tag_syntax_end:, comment_syntax_patterns:,
+        dry_run:
+        @prime_path = prime_path
+        @target_path = target_path
+        @data = data
+        @canonical_prefix = canonical_prefix
+        @tag_syntax_start = tag_syntax_start
+        @dry_run = dry_run
+        @tag_patterns = BlockParser.build_tag_patterns(
+          tag_syntax_start, tag_syntax_end, comment_syntax_patterns)
+      end
+
+      # @api private
+      def run_sync
+        prime_text = File.read(@prime_path)
+        target_text = File.read(@target_path)
+
+        prime_segments  = BlockParser.parse(
+          prime_text,
+          canonical_prefix: @canonical_prefix,
+          tag_patterns: @tag_patterns)
+        target_segments = BlockParser.parse(
+          target_text,
+          canonical_prefix: @canonical_prefix,
+          tag_patterns: @tag_patterns)
+
+        prime_blocks = BlockParser.extract_canonical(prime_segments, canonical_prefix: @canonical_prefix)
+        target_blocks, errors = validate_target_canonical(target_segments)
+
+        if errors.any?
+          return CastResult.new(
+            target_path: @target_path,
+            applied_changes: [],
+            warnings: [],
+            errors: errors,
+            diff: nil)
+        end
+
+        warnings = collect_warnings(prime_blocks, target_blocks, target_text)
+        new_segments, applied_changes = apply_prime_blocks(target_segments, prime_blocks)
+
+        new_text = reconstruct(new_segments)
+        diff = generate_diff(target_text, new_text) if applied_changes.any? || @dry_run
+
+        File.write(@target_path, new_text) unless @dry_run
+
+        CastResult.new(
+          target_path: @target_path,
+          applied_changes: @dry_run ? [] : applied_changes,
+          warnings: warnings,
+          errors: [],
+          diff: diff)
+      end
+
+      # @api private
+      def self.render_liquid_string content, data
+        require_relative '../jekyll'
+        require_relative '../jekyll/liquid/filters'
+        require_relative '../jekyll/liquid/tags'
+        require 'liquid' unless defined?(Liquid::Template)
+        Sourcerer::Jekyll.initialize_liquid_runtime
+
+        template = Liquid::Template.parse(content)
+        template.render(data.transform_keys(&:to_s))
+      end
+
+      private
+
+      # Collect canonical blocks from target, raising errors for duplicates.
+      # Returns [hash_of_canonical_blocks, errors_array].
+      def validate_target_canonical target_segments
+        seen = {}
+        errors = []
+        target_segments.each do |s|
+          next unless s.is_a?(BlockParser::Block) && canonical?(s.tag)
+
+          if seen.key?(s.tag)
+            errors << "Duplicate canonical block '#{s.tag}' in target file"
+          else
+            seen[s.tag] = s
+          end
+        end
+        [seen, errors]
+      end
+
+      def collect_warnings prime_blocks, target_blocks, target_text
+        warnings = []
+
+        prime_blocks.each_key do |tag|
+          next if target_blocks.key?(tag)
+          next if alternate_exists?(tag, target_text)
+
+          warnings << "Prime canonical block '#{tag}' not found in target"
+        end
+
+        target_blocks.each_key do |tag|
+          warnings << "Target canonical block '#{tag}' not found in prime" unless prime_blocks.key?(tag)
+        end
+
+        warnings
+      end
+
+      def apply_prime_blocks target_segments, prime_blocks
+        applied_changes = []
+
+        new_segments = target_segments.map do |segment|
+          next segment unless segment.is_a?(BlockParser::Block) && canonical?(segment.tag)
+          next segment unless prime_blocks.key?(segment.tag)
+
+          prime_content = prime_blocks[segment.tag].content
+          rendered_content = render_content(prime_content)
+
+          if rendered_content == segment.content
+            segment
+          else
+            applied_changes << segment.tag
+            BlockParser::Block.new(
+              tag: segment.tag,
+              open_line: segment.open_line,
+              content: rendered_content,
+              close_line: segment.close_line)
+          end
+        end
+
+        [new_segments, applied_changes]
+      end
+
+      def reconstruct segments
+        segments.map do |s|
+          case s
+          when BlockParser::Block
+            "#{s.open_line}#{s.content}#{s.close_line}"
+          when BlockParser::TextSegment
+            s.content
+          end
+        end.join
+      end
+
+      def canonical? tag
+        tag.start_with?(@canonical_prefix)
+      end
+
+      def alternate_exists? canonical_tag, target_text
+        # Scan the raw target text for any tag marker that shares the suffix of
+        #  the canonical tag but uses a different (non-canonical) prefix.
+        # Ex: `local-agency` is an alternate for `universal-agency`.
+        suffix     = canonical_tag.delete_prefix(@canonical_prefix)
+        inner      = BlockParser.tag_template_to_inner_regex(@tag_syntax_start)
+        scan_pat   = Regexp.new(inner.gsub('(?<tag>', '('))
+        target_text.scan(scan_pat).flatten.any? do |found_tag|
+          found_tag.end_with?(suffix) && !found_tag.start_with?(@canonical_prefix)
+        end
+      end
+
+      def render_content content
+        return content if @data.empty?
+
+        self.class.render_liquid_string(content, @data)
+      end
+
+      def generate_diff old_text, new_text
+        return nil if old_text == new_text
+
+        require 'open3'
+        require 'tempfile'
+
+        result = nil
+        Tempfile.open(['cast_old', '.txt']) do |old_f|
+          old_f.write(old_text)
+          old_f.flush
+          Tempfile.open(['cast_new', '.txt']) do |new_f|
+            new_f.write(new_text)
+            new_f.flush
+            stdout, = Open3.capture2('diff', '-u', old_f.path, new_f.path)
+            result = stdout
+          end
+        end
+        result
+      end
+    end
+  end
+end

data/lib/sourcerer/sync.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'sync/block_parser'
+require_relative 'sync/cast'
+
+module Sourcerer
+  # Canonical block synchronization and Liquid rendering for flat text files.
+  #
+  # @see Sourcerer::Sync::Cast  The main orchestrator class.
+  # @see Sourcerer::Sync::BlockParser  The file-agnostic block parser.
+  # @see https://github.com/DocOps/asciisourcerer Sync/Cast documentation
+  module Sync
+    # Synchronise canonical blocks from `prime_path` into `target_path`.
+    #
+    # @param prime_path [String]
+    # @param target_path [String]
+    # @param options [Hash] Passed through to {Cast.sync}.
+    # @return [Cast::CastResult]
+    def self.sync(prime_path, target_path, **)
+      Cast.sync(prime_path, target_path, **)
+    end
+
+    # Bootstrap a brand-new target file from the prime template.
+    #
+    # @param prime_path [String]
+    # @param target_path [String]
+    # @param options [Hash] Passed through to {Cast.init}.
+    # @return [Cast::CastResult]
+    def self.init(prime_path, target_path, **)
+      Cast.init(prime_path, target_path, **)
+    end
+  end
+end

data/lib/sourcerer/util/list_amend.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Sourcerer
+  module Util
+    # Merge a user-supplied list into a default list using +/- amendment tokens.
+    #
+    # Not required internally; callers must require this file explicitly.
+    module ListAmend
+      # Apply a custom list on top of a default list.
+      #
+      # @param default_list [Array<#to_s>] the baseline list of items
+      # @param custom_list  [nil, String, Array<#to_s>] the user-supplied overrides
+      # @param normalize    [nil, #call] optional normalizer for deduplication comparisons (e.g. +:downcase+.to_proc)
+      # @return [Array<String>]
+      #
+      # Behavior:
+      #   - +nil+ / empty custom ⇒ return stringified +default_list+
+      #   - custom with no +/- tokens ⇒ fixed-list mode: return stringified custom
+      #   - custom with any +/- token ⇒ amendment mode:
+      #       -slug  removes slug from working set (or no-op)
+      #       +slug  adds slug if not already present
+      #       bare   treated as +slug
+      def self.apply default_list, custom_list, normalize: nil
+        tokens = parse_tokens(custom_list)
+        return default_list.map(&:to_s) if tokens.empty?
+
+        amendment_mode = tokens.any? { |t| t.start_with?('+', '-') }
+        return tokens.map(&:to_s) unless amendment_mode
+
+        working = default_list.map(&:to_s)
+        norm    = normalize || ->(s) { s }
+
+        # Apply removals first, then additions in token order.
+        tokens.each do |token|
+          if token.start_with?('-')
+            slug = token[1..]
+            working.reject! { |item| norm.call(item) == norm.call(slug) }
+          else
+            slug = token.start_with?('+') ? token[1..] : token
+            working << slug unless working.any? { |item| norm.call(item) == norm.call(slug) }
+          end
+        end
+
+        working
+      end
+
+      # Normalize a raw custom_list value into an array of non-empty token strings.
+      def self.parse_tokens raw
+        case raw
+        when nil
+          []
+        when Array
+          raw.map(&:to_s).reject(&:empty?)
+        when String
+          raw.split(/[\s,]+/).reject(&:empty?)
+        else
+          Array(raw).map(&:to_s).reject(&:empty?)
+        end
+      end
+      private_class_method :parse_tokens
+    end
+  end
+end