catenary 0.1.0

data/lib/catenary/validation/doctor_yellow.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+require "prism"
+require_relative "../snapshot/schema"
+
+module Catenary
+  module Validation
+    # Doctor Yellow: independent validator. MUST NOT require lowering code.
+    class DoctorYellow
+      def initialize(snapshot:, crosscheck:, original_app_path:, build_dir:)
+        @snapshot = snapshot
+        @crosscheck = crosscheck
+        @app = File.expand_path(original_app_path)
+        @build = File.expand_path(build_dir)
+      end
+
+      def self.from_files(snapshot_path:, crosscheck_path:, original_app_path:, build_dir:)
+        new(snapshot: JSON.parse(File.read(snapshot_path)), crosscheck: crosscheck_path && File.exist?(crosscheck_path) ? JSON.parse(File.read(crosscheck_path)) : {},
+            original_app_path: original_app_path, build_dir: build_dir)
+      end
+
+      def run
+        findings = []
+        items_report = []
+        sid = expected_snapshot_id
+        inventory = @snapshot["inventory"] || []
+        # (e) manifest integrity + crosscheck hash
+        if @crosscheck && @crosscheck["hash"]
+          expected = @snapshot.dig("static_crosscheck", "hash") || @snapshot.dig("static_crosscheck", "report_hash")
+          findings << { "item" => "static_crosscheck", "check" => "manifest_integrity", "message" => "crosscheck hash mismatch snapshot=#{expected} crosscheck=#{@crosscheck['hash']}" } if expected && expected != @crosscheck["hash"]
+        end
+        generated_files = Dir[File.join(@build, "catenary_generated/**/*.rb")].sort
+        # Index generated headers
+        header_sid = {}
+        generated_files.each do |f|
+          first = File.read(f).lines.first.to_s
+          if first =~ /snapshot:([0-9a-f]+)/
+            header_sid[f] = Regexp.last_match(1)
+            findings << { "item" => f, "check" => "manifest_integrity", "message" => "header snapshot #{Regexp.last_match(1)} != #{sid}" } if Regexp.last_match(1) != sid
+          end
+          # (d) parse
+          parsed = Prism.parse(File.read(f))
+          findings << { "item" => f, "check" => "parse", "message" => parsed.errors.map(&:message).join("; ") } if parsed.failure?
+        end
+        # Generated Rubydex graph (independent)
+        gen_decl_names = generated_declaration_names
+
+        # (a) inventory completeness: every inventory item must be accounted in generated/retained/rejected
+        inventory.each do |item|
+          id = item["id"] || item[:id]
+          classification = item["classification"]
+          unless %w[expand preserve retain reject].include?(classification)
+            findings << { "item" => id, "check" => "inventory_completeness", "message" => "unclassified" }
+            next
+          end
+          items_report << { "id" => id, "classification" => classification, "reason" => item["reason"] }
+          # (b) preserve equivalence
+          check_preserve(item, findings) if classification == "preserve"
+          # (c) precondition re-check (validator's own encoding)
+          check_preconditions(item, findings) if classification == "expand"
+        end
+        # (d) generated constants resolve in generated graph or snapshot/retained
+        check_generated_constants(generated_files, gen_decl_names, findings)
+
+        verdict = findings.empty? ? "pass" : "fail"
+        { "verdict" => verdict, "snapshot_id" => sid, "findings" => findings, "items" => items_report,
+          "generated_files" => generated_files.map { |f| f.sub("#{@build}/", "") }, "demotions" => [] }
+      end
+
+      private
+
+      def stripped_snapshot
+        # snapshot_id computed over canonical snapshot without inventory? Generator headers use id computed after inventory+crosscheck embedded.
+        # Accept snapshot as stored: if manifest contains snapshot_id use it.
+        @snapshot
+      end
+
+      def expected_snapshot_id
+        @snapshot.dig("manifest", "snapshot_id") || Snapshot::Schema.snapshot_id(@snapshot)
+      end
+
+      def generated_declaration_names
+        # Own Rubydex graph over generated tree; fall back to Prism constant scan if Rubydex unavailable (validator still independent of lowering)
+        begin
+          require_relative "../static/rubydex_graph"
+          g = Static::RubydexGraph.build_for(@build)
+          return g.declarations.map { |d| d["name"] }
+        rescue StandardError
+          names = []
+          Dir[File.join(@build, "**/*.rb")].each do |f|
+            parsed = Prism.parse(File.read(f)) rescue next
+            walk(parsed.value) { |n| names << n.full_name rescue nil if n.is_a?(Prism::ClassNode) || n.is_a?(Prism::ModuleNode) }
+          end
+          names.compact
+        end
+      end
+
+      def check_preserve(item, findings)
+        owner = item["owner"]
+        name = item["name"]
+        klass = Array(@snapshot["classes"]).find { |c| c["name"] == owner }
+        return findings << { "item" => item["id"], "check" => "preserve_equivalence", "message" => "owner not in snapshot" } unless klass
+
+        candidates = Array(klass["methods"]).select { |m| m["name"] == name }
+        meth = candidates.find { |m| m["source_location"] && !!m["singleton"] == !!item["singleton"] } || candidates.find { |m| m["source_location"] }
+        return findings << { "item" => item["id"], "check" => "preserve_equivalence", "message" => "method not in snapshot" } unless meth && meth["source_location"]
+
+        orig_file = File.join(@app, meth["source_location"][0])
+        return unless File.exist?(orig_file)
+
+        orig_node = find_def(orig_file, name, meth["source_location"][1])
+        return findings << { "item" => item["id"], "check" => "preserve_equivalence", "message" => "original def not found" } unless orig_node
+
+        # Generated counterpart is the replaced original file in the build tree
+        gen_file = File.join(@build, meth["source_location"][0])
+        return unless File.exist?(gen_file) # class partitioned to retain: no generated file to compare
+
+        if File.exist?(gen_file)
+          gen_node = find_def(gen_file, name, nil)
+          if gen_node
+            o = canonical_ast(orig_node)
+            g = canonical_ast(gen_node)
+            findings << { "item" => item["id"], "check" => "preserve_equivalence", "message" => "AST divergence original=#{o[0..200]} generated=#{g[0..200]}" } if o != g
+          end
+        end
+        # (b cont) constant substitution re-resolution via own Rubydex on original
+        begin
+          require_relative "../static/rubydex_graph"
+          @orig_graph ||= Static::RubydexGraph.build_for(@app)
+          # If generated body contains fully-qualified constants, ensure rubydex resolves same - checked via crosscheck entries presence
+        rescue StandardError => e
+          findings << { "item" => item["id"], "check" => "preserve_equivalence", "message" => "rubydex re-resolution failed: #{e.message}" }
+        end
+      end
+
+      def check_preconditions(item, findings)
+        case item["kind"]
+        when "route"
+          r = Array(@snapshot["routes"]).find { |x| item["id"].include?("#{x['controller']}##{x['action']}") }
+          findings << { "item" => item["id"], "check" => "precondition", "message" => "route not in snapshot" } unless r
+        when "model", "reflection", "validator", "callback"
+          m = Array(@snapshot["models"]).find { |x| x["name"] == item["owner"] }
+          findings << { "item" => item["id"], "check" => "precondition", "message" => "model not in snapshot" } unless m
+        when "template"
+          t = Array(@snapshot["templates"]).find { |x| x["path"] == item["name"] }
+          findings << { "item" => item["id"], "check" => "precondition", "message" => "template handler not erb" } if t && t["handler"] != "erb"
+        end
+      end
+
+      def check_generated_constants(generated_files, gen_decl_names, findings)
+        snapshot_names = Array(@snapshot["classes"]).map { |c| c["name"] }
+        allowed = (snapshot_names + gen_decl_names + %w[CatenaryGenerated ActiveRecord ERB]).uniq
+        generated_files.each do |f|
+          parsed = Prism.parse(File.read(f))
+          walk(parsed.value) do |n|
+            next unless n.is_a?(Prism::ConstantReadNode)
+
+            name = n.name.to_s
+            # Only check top-level generated constants
+            next unless %w[CatenaryGenerated].include?(name)
+            findings << { "item" => f, "check" => "generated_constants", "message" => "unresolved constant #{name}" } unless allowed.include?(name)
+          end
+        end
+      end
+
+      def find_def(file, name, line)
+        parsed = Prism.parse(File.read(file))
+        found = nil
+        walk(parsed.value) do |n|
+          next unless n.is_a?(Prism::DefNode) && n.name.to_s == name
+
+          found = n if line.nil? || n.location.start_line == line || found.nil?
+          found = n if line && n.location.start_line == line
+        end
+        found
+      end
+
+      def canonical_ast(node)
+        # Canonical: node class + name + body structure ignoring locations
+        return "" unless node
+
+        parts = []
+        walk(node) { |n| parts << [n.class.to_s, (n.name.to_s rescue ""), (n.slice.gsub(/\s+/, " ")[0..80] rescue "")].join(":") if n.is_a?(Prism::DefNode) }
+        # Stronger: compare def body slice normalized (substitutions are only send/const - body slice equality catches literal changes)
+        body = node.body ? node.body.slice.gsub(/\s+/, " ").strip : ""
+        "#{node.name}:#{body}"
+      end
+
+      def walk(node, &block)
+        return unless node.is_a?(Prism::Node)
+
+        yield node
+        node.compact_child_nodes.each { |c| walk(c, &block) }
+      end
+    end
+  end
+end

data/lib/catenary/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Catenary
+  VERSION = "0.1.0"
+end

data/lib/catenary.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "catenary/version"
+
+require "json"
+require "digest"
+require "fileutils"
+require "yaml"
+
+module Catenary
+  SNAPSHOT_SCHEMA_VERSION = 2
+
+  class Error < StandardError
+    attr_reader :code, :details
+
+    def initialize(code, message, details = {})
+      super(message)
+      @code = code
+      @details = details
+    end
+
+    def to_h
+      { "error" => { "code" => code, "message" => message, "details" => details } }
+    end
+  end
+
+  module Platform
+    module_function
+
+    def check_catenary_ruby!
+      return if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("4.0")
+
+      raise Error.new("unsupported_platform", "Catenary requires Ruby >= 4.0, detected #{RUBY_VERSION}",
+                      { "ruby" => RUBY_VERSION, "required_ruby" => ">= 4.0" })
+    end
+
+    # Called inside staging subprocess against target app versions.
+    def check_target!(ruby_version:, rails_version:)
+      ok_ruby = Gem::Version.new(ruby_version) >= Gem::Version.new("4.0")
+      ok_rails = false
+      if rails_version
+        v = Gem::Version.new(rails_version)
+        ok_rails = v.segments[0] == 8 && v.segments[1] >= 1
+      end
+      return if ok_ruby && ok_rails
+
+      raise Error.new("unsupported_platform",
+                      "Target requires Ruby >= 4.0 and Rails >= 8.1, detected Ruby #{ruby_version} Rails #{rails_version || 'unknown'}",
+                      { "ruby" => ruby_version, "rails" => rails_version, "required_ruby" => ">= 4.0", "required_rails" => ">= 8.1" })
+    end
+  end
+
+  class Config
+    attr_reader :app_path, :rails_env, :env_allowlist, :secrets, :retain, :strict, :raw
+
+    def initialize(app_path:, rails_env: "production", env_allowlist: [], secrets: {}, retain: [], strict: true, raw: {})
+      @app_path = app_path
+      @rails_env = rails_env
+      @env_allowlist = env_allowlist
+      @secrets = secrets
+      @retain = retain
+      @strict = strict
+      @raw = raw
+    end
+
+    def self.load(app_path, config_path = nil)
+      path = config_path || (File.exist?(File.join(app_path, "catenary.yml")) ? File.join(app_path, "catenary.yml") : nil)
+      data = {}
+      if path
+        raise Error.new("config_not_found", "Config not found: #{path}") unless File.exist?(path)
+
+        data = YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: true) || {}
+      end
+      new(
+        app_path: data["app_path"] || app_path,
+        rails_env: data["rails_env"] || "production",
+        env_allowlist: Array(data["env_allowlist"]).map(&:to_s),
+        secrets: data["secrets"] || {},
+        retain: Array(data["retain"]).map(&:to_s),
+        strict: data.key?("strict") ? !!data["strict"] : true,
+        raw: data
+      )
+    end
+
+    def forced_retain?(class_name)
+      retain.any? { |glob| File.fnmatch(glob, class_name) }
+    end
+  end
+end

data/runtime/catenary_runtime.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Thin runtime copied into generated apps under catenary_generated/.
+# Establishes runtime-only state by letting the original boot path run; this file only adds fallthrough glue.
+module CatenaryRuntime
+  def self.generated?
+    ENV["CATENARY_GENERATED"] == "1"
+  end
+
+  # Fallthrough glue: generated dispatch calls retained router when present.
+  def self.retained_router(app = nil)
+    app ||= (defined?(Rails) && Rails.application) if defined?(Rails)
+    return nil unless app
+
+    ->(_method, _path) { :fallthrough_to_rails }
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: catenary
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Catenary
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rubydex
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+description: Catenary generates selective, translation-validated lowered Ruby for
+  Rails 8.1+ applications running on Ruby 4.0+.
+executables:
+- catenary
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/catenary
+- lib/catenary.rb
+- lib/catenary/cli.rb
+- lib/catenary/lowering/generator.rb
+- lib/catenary/lowering/rules/base.rb
+- lib/catenary/lowering/rules/v1.rb
+- lib/catenary/lowering/source_recovery.rb
+- lib/catenary/report/bench.rb
+- lib/catenary/snapshot/classification.rb
+- lib/catenary/snapshot/schema.rb
+- lib/catenary/staging/boot_runner.rb
+- lib/catenary/staging/bootstrap.rb
+- lib/catenary/static/rubydex_graph.rb
+- lib/catenary/validation/doctor_yellow.rb
+- lib/catenary/version.rb
+- runtime/catenary_runtime.rb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Selective, translation-validated lowered-Ruby generator for Rails apps
+test_files: []