textus 0.2.0

data/lib/textus/manifest.rb

@@ -0,0 +1,394 @@
+require "yaml"
+
+module Textus
+  class Manifest
+    # New stricter grammar: lowercase + digits + internal hyphens. No underscores.
+    KEY_SEGMENT = /\A[a-z0-9][a-z0-9-]*\z/
+    MAX_SEGMENTS = 8
+    MAX_SEGMENT_LEN = 64
+
+    EXT_TO_FORMAT = {
+      ".md" => "markdown",
+      ".json" => "json",
+      ".yaml" => "yaml",
+      ".yml" => "yaml",
+      ".txt" => "text",
+    }.freeze
+
+    attr_reader :root, :entries, :raw
+
+    LEGACY_ZONES = {
+      "fixed" => ["human"],
+      "state" => %w[human ai script],
+      "derived" => ["build"],
+    }.freeze
+
+    def zones
+      @zones ||= begin
+        declared = Array(@raw["zones"])
+        if declared.empty?
+          LEGACY_ZONES.transform_values(&:dup)
+        else
+          declared.to_h do |z|
+            [z["name"], Array(z["writable_by"])]
+          end
+        end
+      end
+    end
+
+    def zone_writers(zone_name)
+      zones[zone_name] or raise UsageError.new("undeclared zone '#{zone_name}'")
+    end
+
+    def self.load(root)
+      manifest_path = File.join(root, "manifest.yaml")
+      raise IoError.new("manifest not found: #{manifest_path}") unless File.exist?(manifest_path)
+
+      raw = YAML.safe_load_file(manifest_path, aliases: false)
+      raise BadFrontmatter.new(manifest_path, "unsupported manifest version #{raw["version"].inspect}") unless raw["version"] == PROTOCOL
+
+      new(root, raw)
+    end
+
+    def initialize(root, raw)
+      @root = root
+      @raw = raw
+      @entries = Array(raw["entries"]).map { |e| ManifestEntry.new(self, e) }
+      validate_declared_keys!
+    end
+
+    # Returns [ManifestEntry, resolved_path, remaining_segments]
+    def resolve(key)
+      validate_key!(key)
+      segments = key.split(".")
+      # longest-prefix match
+      candidates = @entries
+                   .map { |e| [e, e.key.split(".")] }
+                   .select { |(_, esegs)| esegs == segments[0, esegs.length] }
+                   .sort_by { |(_, esegs)| -esegs.length }
+      raise UnknownKey.new(key, suggestions: suggestions_for(key)) if candidates.empty?
+
+      entry, esegs = candidates.first
+      remaining = segments[esegs.length..]
+      if remaining.empty?
+        path = resolve_leaf_path(entry)
+        [entry, path, []]
+      else
+        raise UnknownKey.new(key, suggestions: suggestions_for(key)) unless entry.nested
+
+        primary_ext = Entry.for_format(entry.format).extensions.first
+        path = File.join(@root, "zones", entry.path, *remaining) + primary_ext
+        [entry, path, remaining]
+      end
+    end
+
+    # Returns up to 5 dotted keys from the manifest that look similar to the
+    # requested key, ranked by shared-prefix length then Levenshtein distance.
+    def suggestions_for(key)
+      candidates = enumerate.map { |r| r[:key] }
+      # Include declared (non-nested) entry keys even if file is missing.
+      candidates.concat(@entries.reject(&:nested).map(&:key))
+      candidates.uniq!
+      KeyDistance.suggest(key, candidates, limit: 5)
+    rescue StandardError
+      []
+    end
+
+    # Enumerate all entry files reachable through the manifest. Returns
+    # [{ key:, path:, manifest_entry: }, ...]
+    # rubocop:disable Metrics/AbcSize
+    def enumerate(prefix: nil)
+      out = []
+      @entries.each do |entry|
+        if entry.nested
+          base = File.join(@root, "zones", entry.path)
+          next unless File.directory?(base)
+
+          glob_pattern = nested_glob(entry.format)
+          Dir.glob(File.join(base, glob_pattern)).each do |fp|
+            rel = fp.sub(%r{\A#{Regexp.escape(base)}/?}, "")
+            stripped = rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "")
+            segs = stripped.split("/").reject(&:empty?)
+            next if segs.empty?
+
+            illegal = segs.find { |s| !valid_segment?(s) }
+            if illegal
+              warn("textus: skipping illegal key segment '#{illegal}' at #{fp} — run 'textus migrate-keys --dry-run'")
+              next
+            end
+
+            full_key = (entry.key.split(".") + segs).join(".")
+            out << { key: full_key, path: fp, manifest_entry: entry }
+          end
+        else
+          fp = resolve_leaf_path(entry)
+          out << { key: entry.key, path: fp, manifest_entry: entry } if File.exist?(fp)
+        end
+      end
+      out.select! { |row| row[:key] == prefix || row[:key].start_with?("#{prefix}.") } if prefix
+      out.sort_by { |row| row[:key] }
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # Validates all declared entry keys; raises UsageError listing all offenders.
+    def validate_keys!
+      offenders = []
+      @entries.each do |entry|
+        validate_key!(entry.key)
+      rescue UsageError => e
+        offenders << e.message
+      end
+      raise UsageError.new("invalid manifest keys: #{offenders.join("; ")}") unless offenders.empty?
+    end
+
+    def validate_key!(key)
+      raise UsageError.new("empty key") if key.nil? || key.empty?
+
+      segs = key.split(".")
+      raise UsageError.new("key '#{key}' has #{segs.length} segments (max #{MAX_SEGMENTS})") if segs.length > MAX_SEGMENTS
+
+      segs.each do |seg|
+        if seg.empty?
+          raise UsageError.new("empty segment in key '#{key}'")
+        elsif seg.length > MAX_SEGMENT_LEN
+          raise UsageError.new("segment '#{seg}' in key '#{key}' exceeds #{MAX_SEGMENT_LEN} chars")
+        elsif !seg.match?(KEY_SEGMENT)
+          raise UsageError.new(
+            "invalid key segment '#{seg}' in '#{key}': must match [a-z0-9][a-z0-9-]* " \
+            "(lowercase, digits, hyphens; no underscores or uppercase)",
+          )
+        end
+      end
+    end
+
+    private
+
+    def valid_segment?(seg)
+      return false if seg.nil? || seg.empty?
+      return false if seg.length > MAX_SEGMENT_LEN
+
+      seg.match?(KEY_SEGMENT)
+    end
+
+    def validate_declared_keys!
+      @entries.each { |e| validate_key!(e.key) }
+    end
+
+    def resolve_leaf_path(entry)
+      primary_ext = Entry.for_format(entry.format).extensions.first
+      if File.extname(entry.path) == ""
+        File.join(@root, "zones", entry.path + primary_ext)
+      else
+        File.join(@root, "zones", entry.path)
+      end
+    end
+
+    def nested_glob(format)
+      case format
+      when "markdown" then "**/*.md"
+      when "json" then "**/*.json"
+      when "yaml" then "**/*.{yaml,yml}"
+      when "text" then "**/*.txt"
+      else raise UsageError.new("unknown format #{format.inspect} for nested glob")
+      end
+    end
+  end
+
+  class ManifestEntry
+    PUBLISH_EACH_VARS = %w[leaf basename key ext].freeze
+    PUBLISH_EACH_VAR_RE = /\{([a-z]+)\}/
+
+    attr_reader :key, :path, :zone, :schema, :owner, :nested, :generator, :raw, :format,
+                :projection, :template, :publish_to, :publish_each, :fetcher, :fetcher_config, :ttl, :events,
+                :inject_intro
+
+    def initialize(manifest, raw)
+      @manifest = manifest
+      @raw = raw
+      @key = raw["key"] or raise UsageError.new("manifest entry missing key")
+      @path = raw["path"] or raise UsageError.new("manifest entry '#{@key}' missing path")
+      @zone = raw["zone"] or raise UsageError.new("manifest entry '#{@key}' missing zone")
+      @schema = raw["schema"]
+      @owner = raw["owner"]
+      @nested = raw["nested"] == true
+      @generator = raw["generator"]
+      @projection = raw["projection"]
+      @template = raw["template"]
+      @publish_to = Array(raw["publish_to"])
+      @publish_each = raw["publish_each"]
+      @events = raw["events"] || {}
+      @inject_intro = raw["inject_intro"] == true
+      @format = resolve_format!(raw["format"])
+
+      reject_legacy!(raw)
+      parse_source!(raw["source"])
+      validate_format_matrix!
+      validate_publish_each!
+      validate_inject_intro!
+    end
+
+    # Resolves the per-leaf target path (relative to repo root) for a full
+    # dotted key under this entry's prefix. Returns nil if this entry has no
+    # publish_each template.
+    def publish_target_for(full_key)
+      return nil if @publish_each.nil?
+
+      entry_segs = @key.split(".")
+      key_segs = full_key.split(".")
+      raise UsageError.new("key '#{full_key}' is not under entry '#{@key}'") unless key_segs[0, entry_segs.length] == entry_segs
+
+      remaining = key_segs[entry_segs.length..] || []
+      leaf = remaining.join("/")
+      basename = remaining.last || ""
+      ext = Entry.for_format(@format).extensions.first.to_s.sub(/^\./, "")
+
+      vars = { "leaf" => leaf, "basename" => basename, "key" => full_key, "ext" => ext }
+      @publish_each.gsub(PUBLISH_EACH_VAR_RE) { vars.fetch(::Regexp.last_match(1)) }
+    end
+
+    def derived?
+      writers = @manifest.zone_writers(@zone)
+      writers.include?("build")
+    rescue UsageError => e
+      raise UsageError.new("entry '#{@key}': #{e.message}")
+    end
+
+    private
+
+    def validate_inject_intro!
+      return unless @inject_intro
+
+      unless derived?
+        raise UsageError.new(
+          "entry '#{@key}': inject_intro: is only valid on derived entries",
+        )
+      end
+      return unless @template.nil?
+
+      raise UsageError.new(
+        "entry '#{@key}': inject_intro: requires a template:",
+      )
+    end
+
+    def validate_publish_each!
+      return if @publish_each.nil?
+
+      raise UsageError.new("entry '#{@key}': publish_each requires nested: true") unless @nested
+      raise UsageError.new("entry '#{@key}': publish_to and publish_each are mutually exclusive") unless @publish_to.empty?
+      raise UsageError.new("entry '#{@key}': publish_each must be a string") unless @publish_each.is_a?(String)
+
+      used_vars = @publish_each.scan(PUBLISH_EACH_VAR_RE).flatten
+      unknown = used_vars - PUBLISH_EACH_VARS
+      unless unknown.empty?
+        raise UsageError.new(
+          "entry '#{@key}': publish_each uses unknown template variable(s) " \
+          "#{unknown.map { |v| "{#{v}}" }.join(", ")}. Known: #{PUBLISH_EACH_VARS.map { |v| "{#{v}}" }.join(", ")}.",
+        )
+      end
+
+      required = %w[leaf basename key]
+      return if used_vars.any? { |v| required.include?(v) }
+
+      raise UsageError.new(
+        "entry '#{@key}': publish_each must reference at least one of {leaf}, {basename}, or {key} " \
+        "(else every leaf would clobber the same target).",
+      )
+    end
+
+    def resolve_format!(declared)
+      ext = File.extname(@path)
+      inferred = Manifest::EXT_TO_FORMAT[ext]
+
+      if declared.nil?
+        return inferred if inferred
+        # No extension: nested defaults to markdown, leaf with no ext also markdown.
+        return "markdown" if ext == "" && @nested
+        return "markdown" if ext == ""
+      else
+        raise UsageError.new("entry '#{@key}': unknown format #{declared.inspect}") unless Manifest::EXT_TO_FORMAT.values.include?(declared)
+        # If the path has an extension, the declared format must match.
+        if ext != "" && inferred && inferred != declared
+          raise UsageError.new(
+            "entry '#{@key}': path extension #{ext.inspect} does not match declared format #{declared.inspect}",
+          )
+        end
+        return declared
+      end
+
+      "markdown"
+    end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    def validate_format_matrix!
+      ext = File.extname(@path)
+
+      case @format
+      when "markdown"
+        # .md, or no extension (will be appended). Anything else is a mismatch caught above.
+        raise UsageError.new("entry '#{@key}': markdown format requires '.md' path (got #{ext.inspect})") if ext != "" && ext != ".md"
+      when "json"
+        if @nested
+          # nested json: path is a directory; ext must be empty.
+          raise UsageError.new("entry '#{@key}': nested json path must not have an extension") if ext != ""
+        elsif ext != ".json"
+          raise UsageError.new("entry '#{@key}': json format requires '.json' path (got #{ext.inspect})")
+        end
+      when "yaml"
+        if @nested
+          raise UsageError.new("entry '#{@key}': nested yaml path must not have an extension") if ext != ""
+        elsif ext != ".yaml" && ext != ".yml"
+          raise UsageError.new("entry '#{@key}': yaml format requires '.yaml' or '.yml' path (got #{ext.inspect})")
+        end
+      when "text"
+        if @nested
+          raise UsageError.new("entry '#{@key}': nested text path must not have an extension") if ext != ""
+        elsif ext != ".txt" && ext != ""
+          raise UsageError.new("entry '#{@key}': text format requires '.txt' or no extension (got #{ext.inspect})")
+        end
+      end
+
+      # Schema rules.
+      raise UsageError.new("entry '#{@key}': text format must not declare a schema") if @format == "text" && !@schema.nil?
+
+      # Template-required-for-derived rules. Skipped for entries materialized by an
+      # external generator: command (those produce the bytes themselves).
+      if derived? && @template.nil? && @generator.nil? &&
+         (@format == "markdown" || @format == "text") && !@nested
+        raise UsageError.new("entry '#{@key}': derived #{@format} entries require a template")
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+    def parse_source!(src)
+      src ||= {}
+      @fetcher = src["fetcher"]
+      @fetcher_config = src["config"] || {}
+      @ttl = src["ttl"]
+    end
+
+    def reject_legacy!(raw)
+      src = raw["source"] || {}
+      if src.key?("parse") || src.key?("from")
+        raise UsageError.new(
+          "entry '#{@key}': source.parse/source.from removed in 0.2; " \
+          "use source.fetcher (+ source.config). See SPEC §5.4.",
+        )
+      end
+      if raw.key?("hooks")
+        raise UsageError.new(
+          "entry '#{@key}': 'hooks:' renamed to 'events:' in 0.2; " \
+          "remove on_ prefix from event names. See SPEC §5.10.",
+        )
+      end
+
+      @events.each_key do |evt|
+        next if ExtensionRegistry::EVENTS.include?(evt.to_sym)
+
+        raise UsageError.new(
+          "entry '#{@key}': unknown event '#{evt}' in events: block. " \
+          "Known events: #{ExtensionRegistry::EVENTS.join(", ")}.",
+        )
+      end
+    end
+  end
+end

data/lib/textus/migrate_keys.rb

@@ -0,0 +1,187 @@
+module Textus
+  # Run-once helper that renames files/directories whose basenames don't
+  # conform to the strict key grammar (§3 of plan-1.2). Only walks
+  # nested: true manifest entries — leaf entries with illegal declared
+  # keys are caught by Manifest load and must be fixed by hand.
+  module MigrateKeys
+    SEGMENT = /\A[a-z0-9][a-z0-9-]*\z/
+
+    module_function
+
+    # Returns the envelope hash described in plan-1.2 §3.
+    def run(store, write: false)
+      plan = build_plan(store)
+      collisions = plan[:collisions]
+      renames = plan[:renames]
+
+      ok = collisions.empty?
+      apply!(store, renames) if write && ok
+
+      {
+        "protocol" => Textus::PROTOCOL,
+        "mode" => write ? "write" : "dry-run",
+        "renames" => renames.map { |r| envelope_rename(r) },
+        "collisions" => collisions.map { |c| envelope_collision(c) },
+        "ok" => ok,
+      }
+    end
+
+    # ------------------------------------------------------------------
+    # Plan construction
+    # ------------------------------------------------------------------
+
+    # Returns { renames: [...], collisions: [...] }
+    # Each rename: { from:, to:, old_key:, new_key:, kind: :file|:dir }
+    # Each collision: { target:, sources: [...] }
+    def build_plan(store) # rubocop:disable Metrics/AbcSize
+      renames = []
+      target_buckets = Hash.new { |h, k| h[k] = [] } # target_path => [source_path, ...]
+
+      store.manifest.entries.each do |entry|
+        next unless entry.nested
+
+        base = File.join(store.root, "zones", entry.path)
+        next unless File.directory?(base)
+
+        # Walk depth-first. Order matters when computing the "new key"
+        # for files inside a renamed directory: we record renames bottom-up,
+        # so children are renamed before their parents on apply.
+        walk(base) do |abs_path, is_dir|
+          next if abs_path == base
+
+          basename = File.basename(abs_path)
+          stem = is_dir ? basename : basename.sub(/#{Regexp.escape(File.extname(basename))}\z/, "")
+          next if stem.match?(SEGMENT)
+
+          new_stem = normalize(stem)
+          # Skip if normalization yields the same stem (e.g. already-legal
+          # under a different lens). In practice match?(SEGMENT) catches that
+          # above; this is a safety net.
+          next if new_stem == stem
+
+          new_basename = is_dir ? new_stem : new_stem + File.extname(basename)
+          target = File.join(File.dirname(abs_path), new_basename)
+          target_buckets[target] << abs_path
+
+          renames << {
+            from: abs_path,
+            to: target,
+            kind: is_dir ? :dir : :file,
+            entry: entry,
+            base: base,
+          }
+        end
+      end
+
+      collisions = target_buckets.select { |_, srcs| srcs.length > 1 }
+                                 .map { |t, srcs| { target: t, sources: srcs.sort } }
+
+      # Drop colliding entries from renames (we won't apply any of them)
+      colliding_targets = collisions.to_set { |c| c[:target] }
+      renames.reject! { |r| colliding_targets.include?(r[:to]) }
+
+      # Sort renames bottom-up (deepest path first) so children move before parents.
+      renames.sort_by! { |r| -r[:from].count("/") }
+
+      { renames: renames, collisions: collisions }
+    end
+
+    # Yields [absolute_path, is_dir] for every entry under root. Depth-first.
+    def walk(root, &block)
+      Dir.each_child(root) do |name|
+        abs = File.join(root, name)
+        if File.directory?(abs)
+          walk(abs, &block)
+          yield abs, true
+        else
+          yield abs, false
+        end
+      end
+    end
+
+    # Deterministic transform per plan §3.
+    def normalize(s)
+      s = s.downcase
+      s = s.gsub(/[^a-z0-9-]/, "-") # ., _, and anything else become -
+      s = s.gsub(/-+/, "-")
+      s.sub(/\A-+/, "").sub(/-+\z/, "")
+    end
+
+    # ------------------------------------------------------------------
+    # Apply
+    # ------------------------------------------------------------------
+
+    def apply!(store, renames)
+      audit = AuditLog.new(store.root)
+      renames.each do |r|
+        # Bottom-up order means a child's ancestors haven't moved yet, so
+        # `from`/`to` are valid as-recorded. The audit `key` reflects the
+        # eventual full key once every rename in this batch has applied.
+        from = r[:from]
+        to = r[:to]
+        File.rename(from, to)
+        new_key = compute_new_key(r, renames)
+        audit.append(
+          role: "script",
+          verb: "migrate-keys",
+          key: new_key,
+          etag_before: nil,
+          etag_after: nil,
+          extras: { "from" => from, "to" => to },
+        )
+      end
+    end
+
+    # If an ancestor of `path` was renamed earlier in this batch, rewrite the path.
+    def resolve_current_path(path, renames)
+      out = path
+      renames.each do |r|
+        prefix = r[:from] + "/"
+        out = r[:to] + out[r[:from].length..] if out.start_with?(prefix)
+      end
+      out
+    end
+
+    # New full key after applying all renames up through this one.
+    def compute_new_key(rename, renames)
+      base = rename[:base]
+      entry = rename[:entry]
+      new_to = resolve_current_path(rename[:to], renames)
+
+      rel = new_to.sub(%r{\A#{Regexp.escape(base)}/?}, "")
+      stripped = rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "") unless rename[:kind] == :dir
+      stripped ||= rel
+      segs = stripped.split("/").reject(&:empty?)
+      (entry.key.split(".") + segs).join(".")
+    end
+
+    # ------------------------------------------------------------------
+    # Envelope helpers
+    # ------------------------------------------------------------------
+
+    def envelope_rename(r)
+      {
+        "from" => r[:from],
+        "to" => r[:to],
+        "old_key" => path_to_key(r[:from], r[:base], r[:entry], r[:kind]),
+        "new_key" => path_to_key(r[:to], r[:base], r[:entry], r[:kind]),
+      }
+    end
+
+    def envelope_collision(col)
+      { "target" => col[:target], "sources" => col[:sources] }
+    end
+
+    def path_to_key(path, base, entry, kind)
+      rel = path.sub(%r{\A#{Regexp.escape(base)}/?}, "")
+      stripped =
+        if kind == :dir
+          rel
+        else
+          rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "")
+        end
+      segs = stripped.split("/").reject(&:empty?)
+      (entry.key.split(".") + segs).join(".")
+    end
+  end
+end

data/lib/textus/mustache.rb

@@ -0,0 +1,117 @@
+module Textus
+  module Mustache
+    MAX_DEPTH = 8
+    TAG = %r{\{\{(?<sigil>[#^/!&]?)\s*(?<name>[\w.-]+)\s*\}\}}
+
+    def self.render(template, context, strict: false, depth: 0) # rubocop:disable Metrics/AbcSize
+      raise TemplateError.new("template recursion depth #{depth} exceeded #{MAX_DEPTH}") if depth > MAX_DEPTH
+
+      out = +""
+      pos = 0
+      while (m = template.match(TAG, pos))
+        out << template[pos...m.begin(0)]
+        case m[:sigil]
+        when "!"
+          # comment, skip
+        when "#"
+          section, new_pos = parse_section(template, m, m[:name])
+          value = lookup(context, m[:name])
+          out << render_section(section, value, context, strict, depth)
+          pos = new_pos
+          next
+        when "^"
+          section, new_pos = parse_section(template, m, m[:name])
+          value = lookup(context, m[:name])
+          if falsy?(value)
+            raise TemplateError.new("template recursion depth #{depth + 1} exceeded #{MAX_DEPTH}") if depth + 1 > MAX_DEPTH
+
+            out << render(section, context, strict: strict, depth: depth + 1)
+          end
+          pos = new_pos
+          next
+        when "/"
+          raise TemplateError.new("unexpected closing tag #{m[:name]}")
+        else
+          val = lookup(context, m[:name])
+          if val.nil?
+            raise TemplateError.new("missing variable: #{m[:name]}") if strict
+          else
+            out << val.to_s
+          end
+        end
+        pos = m.end(0)
+      end
+      out << template[pos..]
+      out
+    end
+
+    def self.parse_section(template, open_match, name)
+      open_re  = /\{\{#\s*#{Regexp.escape(name)}\s*\}\}|\{\{\^\s*#{Regexp.escape(name)}\s*\}\}/
+      close_re = %r{\{\{/\s*#{Regexp.escape(name)}\s*\}\}}
+      both = Regexp.union(open_re, close_re)
+      depth = 1
+      cursor = open_match.end(0)
+      while (m = template.match(both, cursor))
+        if m[0].start_with?("{{/")
+          depth -= 1
+          return [template[open_match.end(0)...m.begin(0)], m.end(0)] if depth.zero?
+        else
+          depth += 1
+        end
+        cursor = m.end(0)
+      end
+      raise TemplateError.new("unclosed section: #{name}")
+    end
+
+    def self.render_section(section, value, context, strict, depth)
+      raise TemplateError.new("template recursion depth #{depth + 1} exceeded #{MAX_DEPTH}") if depth + 1 > MAX_DEPTH
+
+      case value
+      when Array
+        value.map { |v| render(section, scope_for(context, v), strict: strict, depth: depth + 1) }.join
+      when Hash
+        render(section, merge(context, value), strict: strict, depth: depth + 1)
+      when true
+        render(section, context, strict: strict, depth: depth + 1)
+      when false, nil
+        # falsy in regular section: render nothing.
+        # render_section is only called for inverted sections when falsy? is true at the call site,
+        # so this branch is only hit for normal sections with falsy values.
+        ""
+      else
+        render(section, context, strict: strict, depth: depth + 1)
+      end || ""
+    end
+
+    def self.lookup(context, name)
+      # Implicit iterator: {{.}} refers to the current scope itself (used when
+      # iterating arrays of primitive values).
+      return context["."] if name == "." && context.is_a?(Hash) && context.key?(".")
+      return context[name] if context.is_a?(Hash) && context.key?(name)
+
+      name.split(".").reduce(context) do |acc, seg|
+        return nil unless acc.is_a?(Hash)
+
+        acc[seg]
+      end
+    end
+
+    # Build the rendering scope for one iteration of a section. Hash items
+    # merge into the outer context; primitive items (strings, numbers) bind
+    # to the implicit iterator under key ".".
+    def self.scope_for(context, item)
+      return merge(context, item) if item.is_a?(Hash)
+
+      base = context.is_a?(Hash) ? context : {}
+      base.merge("." => item)
+    end
+
+    def self.merge(base, override)
+      return base unless override.is_a?(Hash)
+
+      base.merge(override)
+    end
+
+    def self.falsy?(v) = v.nil? || v == false || v == [] || v == ""
+  end
+end