forge-ci 0.1.0

data/lib/forge_ci/errors.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "psych"
+
+module ForgeCI
+  # Raised only when the YAML text cannot be parsed at all.
+  # Every other problem (unknown keys, bad references, cycles, ...) is
+  # reported as an entry in the errors array returned by Compiler.compile,
+  # so callers get actionable feedback instead of exceptions.
+  class Error < StandardError; end
+
+  # Maps a key path (e.g. ["jobs", "build", "steps"]) back to the line number
+  # of that key in the original YAML document, so error messages can point
+  # at the user's YAML. Built from the Psych AST; tolerant of anchors and
+  # merge keys.
+  class LineIndex
+    def initialize(document)
+      @root = document.root
+      @anchors = {}
+      index_anchors(@root)
+    end
+
+    # Returns the 1-based line number of the key at the end of +path+,
+    # or nil when it cannot be located (e.g. after alias expansion).
+    # Integer path elements index into YAML sequences (step lists, etc.).
+    def line_for(*path)
+      node = @root
+      key_node = nil
+      path.each do |key|
+        node = resolve(node)
+        if node.is_a?(Psych::Nodes::Sequence) && key.is_a?(Integer)
+          key_node = node.children[key]
+          node = key_node
+          next
+        end
+        return nil unless node.is_a?(Psych::Nodes::Mapping)
+
+        i = mapping_key_index(node, key.to_s)
+        return nil if i.nil?
+
+        key_node = node.children[i]
+        node = node.children[i + 1]
+      end
+      key_node ? key_node.start_line + 1 : nil
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    def index_anchors(node)
+      return unless node.respond_to?(:children)
+
+      @anchors[node.anchor] = node if node.respond_to?(:anchor) && node.anchor
+      children = node.children
+      return if children.nil?
+
+      children.each { |child| index_anchors(child) }
+    end
+
+    def resolve(node)
+      node.is_a?(Psych::Nodes::Alias) ? (@anchors[node.anchor] || node) : node
+    end
+
+    def mapping_key_index(map, key)
+      map.children.each_slice(2).with_index do |(k, _v), i|
+        k = resolve(k)
+        return i * 2 if k.is_a?(Psych::Nodes::Scalar) && k.value == key
+      end
+      nil
+    end
+  end
+
+  # Collects validation errors as structured entries and renders them as
+  # actionable strings: "line 12: jobs.build: <message>".
+  class ErrorCollector
+    Entry = Struct.new(:path, :line, :message, keyword_init: true)
+
+    def initialize(line_index = nil)
+      @line_index = line_index
+      @entries = []
+    end
+
+    def add(path, message)
+      path = Array(path)
+      line = @line_index&.line_for(*path)
+      @entries << Entry.new(path: path.join("."), line: line, message: message)
+    end
+
+    def any? = @entries.any?
+    def empty? = @entries.empty?
+    def size = @entries.size
+
+    def to_a
+      @entries.map do |e|
+        loc = e.line ? "line #{e.line}: " : ""
+        "#{loc}#{e.path}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/forge_ci/interpolator.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module ForgeCI
+  # Pure string-substitution pass for CircleCI-style template references:
+  #
+  #   << parameters.deploy_env >>      pipeline parameter (top-level `parameters:`)
+  #   << pipeline.git.branch >>       supplied via pipeline_params["branch"]
+  #   << pipeline.number >>           supplied via pipeline_params["number"]
+  #   << matrix.node_version >>       only while desugaring matrix jobs
+  #
+  # Anything else is an error (collected, not raised). When the whole string
+  # is a single reference, the native Ruby value is preserved (so booleans
+  # and integers survive); embedded references are stringified.
+  #
+  # Two scoping knobs exist because references resolve in stages:
+  # - only: allowlist of full reference strings (e.g. a command's own
+  #   parameter names); anything else is left untouched for a later pass.
+  # - skip_prefixes: denylist of reference prefixes left untouched
+  #   (e.g. "matrix." during the global pass; matrix jobs resolve them later).
+  module Interpolator
+    REF = /<<\s*([^<>]+?)\s*>>/
+    FULL_REF = /\A#{REF.source}\z/
+
+    module_function
+
+    # context is a Hash with string keys: "parameters", "pipeline", "matrix".
+    def interpolate(obj, context, errors, path, only: nil, skip_prefixes: [], on_missing: nil)
+      case obj
+      when String
+        interpolate_string(obj, context, errors, path, only: only, skip_prefixes: skip_prefixes, on_missing: on_missing)
+      when Array
+        obj.map.with_index { |item, i| interpolate(item, context, errors, path + [i], only: only, skip_prefixes: skip_prefixes, on_missing: on_missing) }
+      when Hash
+        obj.each_with_object({}) do |(k, v), out|
+          new_key = k.is_a?(String) ? interpolate_string(k, context, errors, path, only: only, skip_prefixes: skip_prefixes, on_missing: on_missing) : k
+          out[new_key] = interpolate(v, context, errors, path + [k], only: only, skip_prefixes: skip_prefixes, on_missing: on_missing)
+        end
+      else
+        obj
+      end
+    end
+
+    def interpolate_string(str, context, errors, path, only: nil, skip_prefixes: [], on_missing: nil)
+      return str unless str.match?(REF)
+
+      if (m = str.match(FULL_REF))
+        ref = m[1].strip
+        return str if passthrough?(ref, only, skip_prefixes)
+
+        found, value = resolve(ref, context)
+        return value if found
+        return on_missing.call(ref, path) if on_missing && pipeline_ref?(ref)
+
+        errors.add(path, "unknown interpolation reference \"<< #{ref} >>\"; " \
+                         "expected parameters.<name>, pipeline.git.branch, pipeline.number, or matrix.<name>")
+        return str
+      end
+
+      str.gsub(REF) do
+        ref = Regexp.last_match(1).strip
+        if passthrough?(ref, only, skip_prefixes)
+          "<< #{ref} >>"
+        else
+          found, value = resolve(ref, context)
+          if found
+            value.to_s
+          elsif on_missing && pipeline_ref?(ref)
+            on_missing.call(ref, path)
+          else
+            errors.add(path, "unknown interpolation reference \"<< #{ref} >>\"; " \
+                             "expected parameters.<name>, pipeline.git.branch, pipeline.number, or matrix.<name>")
+            "<< #{ref} >>"
+          end
+        end
+      end
+    end
+
+    # Returns [found, value]. Unknown references return [false, nil].
+    def resolve(ref, context)
+      case ref
+      when /\Aparameters\.(.+)\z/
+        params = context["parameters"] || {}
+        name = Regexp.last_match(1)
+        return [true, params[name]] if params.key?(name)
+
+        [false, nil]
+      when "pipeline.git.branch"
+        pipeline = context["pipeline"] || {}
+        return [true, pipeline["branch"]] unless pipeline["branch"].nil?
+
+        [false, nil]
+      when "pipeline.number"
+        pipeline = context["pipeline"] || {}
+        return [true, pipeline["number"]] unless pipeline["number"].nil?
+
+        [false, nil]
+      when /\Amatrix\.(.+)\z/
+        matrix = context["matrix"] || {}
+        name = Regexp.last_match(1)
+        return [true, matrix[name]] if matrix.key?(name)
+
+        [false, nil]
+      else
+        [false, nil]
+      end
+    end
+
+    # All "<< ... >>" references still present in the object (after passes
+    # that intentionally left some unresolved).
+    def unresolved_refs(obj)
+      refs = []
+      walk = lambda do |o|
+        case o
+        when String then o.scan(REF) { refs << Regexp.last_match(1).strip }
+        when Array then o.each { |item| walk.call(item) }
+        when Hash then o.each { |k, v| walk.call(k); walk.call(v) }
+        end
+      end
+      walk.call(obj)
+      refs.uniq
+    end
+
+    def passthrough?(ref, only, skip_prefixes)
+      return true if skip_prefixes.any? { |prefix| ref.start_with?(prefix) }
+      return true if only && !only.include?(ref)
+
+      false
+    end
+
+    # << pipeline.git.branch >> / << pipeline.number >> are valid references
+    # even when no value was supplied; the compiler leaves them unresolved
+    # with a warning instead of erroring.
+    def pipeline_ref?(ref)
+      ref == "pipeline.git.branch" || ref == "pipeline.number"
+    end
+  end
+end

data/lib/forge_ci/ir.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module ForgeCI
+  # Normalizes the validated, expanded, interpolated config into the
+  # intermediate representation (IR): plain Ruby hashes with symbol keys,
+  # JSON-serializable, ready for a scheduler/runner to consume.
+  #
+  # Only called when validation produced no errors, so normalization can
+  # assume well-formed input and focus on shaping.
+  module IR
+    module_function
+
+    def document(version, workflows, warnings)
+      {
+        version: version.to_s,
+        workflows: workflows,
+        meta: { warnings: warnings }
+      }
+    end
+
+    def workflow(name, jobs)
+      { name: name, jobs: jobs }
+    end
+
+    def job(name, job_def, requires = [])
+      {
+        name: name,
+        # Pruned `requires` edges for this job instance (topological scheduler
+        # seam for the control plane): names of jobs in the same workflow that
+        # must complete successfully before this job may run.
+        requires: Array(requires).map(&:to_s),
+        executor: executor(job_def),
+        working_directory: job_def["working_directory"],
+        steps: Array(job_def["steps"]).map { |s| step(s) }
+      }
+    end
+
+    def executor(job_def)
+      images = Array(job_def["docker"])
+      primary = images.first || {}
+      {
+        type: "docker",
+        image: primary["image"],
+        name: primary["name"],
+        entrypoint: primary["entrypoint"],
+        command: primary["command"],
+        environment: merged_environment(primary["environment"], job_def["environment"]),
+        secondary_images: images.drop(1).map do |img|
+          {
+            image: img["image"],
+            name: img["name"],
+            entrypoint: img["entrypoint"],
+            command: img["command"],
+            environment: img["environment"] || {}
+          }
+        end,
+        resource_class: job_def["resource_class"]
+      }
+    end
+
+    def merged_environment(image_env, job_env)
+      merged = {}
+      merged.merge!(image_env) if image_env.is_a?(Hash)
+      merged.merge!(job_env) if job_env.is_a?(Hash)
+      merged
+    end
+
+    def step(step)
+      type, cfg = step.first
+      cfg = {} if cfg.nil?
+      type = type.to_s
+
+      base =
+        case type
+        when "when", "unless"
+          # Conditional wrappers are evaluated at compile time; by the time
+          # the IR is built only the surviving steps remain. Reaching here
+          # means a bug in the compiler.
+          raise Error, "internal error: unevaluated #{type}: step reached IR normalization"
+        when "checkout"
+          { type: "checkout", path: cfg["path"] }
+        when "run"
+          {
+            type: "run",
+            name: cfg["name"] || cfg["command"],
+            command: cfg["command"],
+            shell: cfg["shell"],
+            background: cfg.fetch("background", false),
+            when: cfg.fetch("when", "on_success")
+          }
+        when "save_cache"
+          { type: "save_cache", keys: cache_keys(cfg), paths: cfg["paths"] || [] }
+        when "restore_cache"
+          { type: "restore_cache", keys: cache_keys(cfg) }
+        when "persist_to_workspace"
+          { type: "persist_to_workspace", root: cfg["root"], paths: cfg["paths"] || [] }
+        when "attach_workspace"
+          { type: "attach_workspace", at: cfg["at"] }
+        when "store_artifacts"
+          { type: "store_artifacts", path: cfg["path"], destination: cfg["destination"] }
+        when "store_test_results"
+          { type: "store_test_results", path: cfg["path"] }
+        when "add_ssh_keys"
+          { type: "add_ssh_keys", fingerprints: cfg["fingerprints"] || [] }
+        else
+          raise Error, "internal error: unknown step type #{type.inspect} reached IR normalization"
+        end
+      base
+    end
+
+    def cache_keys(cfg)
+      return cfg["keys"] if cfg["keys"].is_a?(Array)
+
+      [cfg["key"]].compact
+    end
+  end
+end