catenary 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f94eb928dc59f5fe189c9c5e9b70a6fc1cb88cbc2fa2caf01af772afb2391738
+  data.tar.gz: ed2f22e05213d1cbd0667a3c5f0236e9aaa7d8b15bce247291c5857b882e52e0
+SHA512:
+  metadata.gz: dea6b99eaf6e5760211cb2d4e2354a1777b84bae0e4b13f16eef185f7e3f543c28964ff492d746e350fba6992c11a74882294db8bd7d6cb560f0dfbd74ec7f94
+  data.tar.gz: 0e39aad88087cfda04fe801d7577b88b3fd54d33c6d0ff9a75da477a9bca21ab3b60c65b8c0e83477f0c9c4b68649cc753aac3b5b6ec0f4524982c1e278975ac

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-16
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Catenary
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,22 @@
+# Catenary
+
+Selective, translation-validated lowered-Ruby generator for Rails 8.1+ apps on Ruby 4.0+.
+
+## Installation
+
+```bash
+gem install catenary
+```
+
+```bash
+bundle exec ruby exe/catenary check fixtures/blog
+bundle exec ruby exe/catenary build fixtures/blog --out tmp/blog_out
+bundle exec ruby exe/catenary validate tmp/blog_out
+bundle exec ruby exe/catenary bench tmp/blog_out
+```
+
+- One target: lowered Ruby on CRuby. Rails retained as runtime library in v1.
+- Acceptance is Doctor Yellow (`validation_report.json`), not differential comparison (dev-only, `corpus/run_differential.rb`).
+- Platform floor is absolute: Ruby >= 4.0, Rails >= 8.1; below-floor fails `unsupported_platform`.
+- Snapshot schema v1: `lib/catenary/snapshot/schema.rb`; Rubydex cross-check (runtime wins, disagreement demotes only): `lib/catenary/static/rubydex_graph.rb`; independent validator (no lowering code): `lib/catenary/validation/doctor_yellow.rb`.
+- Factory/ownership: `FACTORY.md`. Blog fixture accounting/bench: `fixtures/blog/ACCOUNTING.md`, `fixtures/blog/BENCH.md`. Lobsters: `corpus/lobsters/recon.md`, `corpus/lobsters/ACCOUNTING.md`.

data/exe/catenary

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "catenary/cli"
+exit Catenary::CLI.new(ARGV).run

data/lib/catenary/cli.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "../catenary"
+require_relative "snapshot/schema"
+require_relative "snapshot/classification"
+require_relative "staging/boot_runner"
+require_relative "static/rubydex_graph"
+require_relative "report/bench"
+
+module Catenary
+  class CLI
+    def initialize(argv)
+      @argv = argv.dup
+    end
+
+    def run
+      Platform.check_catenary_ruby!
+      cmd = @argv.shift
+      case cmd
+      when "build" then cmd_build
+      when "check" then cmd_check
+      when "validate" then cmd_validate
+      when "bench" then cmd_bench
+      when nil, "help", "--help", "-h"
+        puts usage
+        0
+      else
+        fail_json("unknown_command", "Unknown command: #{cmd}")
+      end
+    rescue Error => e
+      warn JSON.generate(e.to_h)
+      puts JSON.generate(e.to_h)
+      1
+    rescue StandardError => e
+      err = Error.new("internal_error", "#{e.class}: #{e.message}", { "backtrace" => Array(e.backtrace).first(10) })
+      warn JSON.generate(err.to_h)
+      puts JSON.generate(err.to_h)
+      1
+    end
+
+    private
+
+    def usage
+      "Usage:\n  catenary build <app_path> [--config catenary.yml] [--out DIR]\n  catenary check <app_path> [--config catenary.yml]\n  catenary validate <build_dir>\n  catenary bench <build_dir>\n"
+    end
+
+    def parse_opts(args)
+      opts = {}
+      parser = OptionParser.new do |o|
+        o.on("--config PATH") { |v| opts[:config] = v }
+        o.on("--out DIR") { |v| opts[:out] = v }
+      end
+      rest = parser.parse(args)
+      [rest, opts]
+    end
+
+    def fail_json(code, msg)
+      err = Error.new(code, msg)
+      puts JSON.generate(err.to_h)
+      1
+    end
+
+    # Shared pipeline: staging (double boot) + rubydex + crosscheck + inventory
+    def snapshot_pipeline(app_path, config)
+      runner = Staging::BootRunner.new(config)
+      snapshot = runner.run_snapshot
+      graph = Static::RubydexGraph.new(app_path)
+      crosscheck = graph.cross_check(snapshot)
+      # double-run crosscheck determinism
+      graph2 = Static::RubydexGraph.new(app_path)
+      crosscheck2 = graph2.cross_check(snapshot)
+      if Snapshot::Schema.canonical_json(crosscheck) != Snapshot::Schema.canonical_json(crosscheck2)
+        raise Error.new("nondeterministic_crosscheck", "crosscheck.json differs between runs")
+      end
+
+      snapshot["static_crosscheck"] = { "hash" => crosscheck["hash"], "entries" => crosscheck["entries"], "declaration_count" => crosscheck["declarations"].size, "constant_reference_count" => crosscheck["constant_references"].size }
+      items = Snapshot::Classification.build_inventory(snapshot, config: config)
+      snapshot["inventory"] = items.map(&:to_h)
+      snapshot["manifest"]["snapshot_id"] = nil # placeholder removed below
+      snapshot["manifest"].delete("snapshot_id")
+      sid = Snapshot::Schema.snapshot_id(snapshot)
+      snapshot["manifest"]["snapshot_id"] = sid
+      [snapshot, crosscheck, items, sid, graph]
+    end
+
+    def cmd_check
+      rest, opts = parse_opts(@argv)
+      app_path = rest[0] or return fail_json("missing_argument", "check requires <app_path>")
+      config = Config.load(app_path, opts[:config])
+      snapshot, crosscheck, items, sid, _graph = snapshot_pipeline(app_path, config)
+      # strict gate on static_only / ancestor_mismatch unresolved
+      if config.strict
+        bad = crosscheck["entries"].select { |e| %w[static_only ancestor_mismatch].include?(e["type"]) }
+        # static_only already surfaces as reject inventory; let assert_complete raise, but give explicit code first if only ancestor
+        Snapshot::Classification.assert_complete!(items, strict: true) unless bad.any? { |e| e["type"] == "ancestor_mismatch" }
+        if bad.any? { |e| e["type"] == "ancestor_mismatch" }
+          raise Error.new("ancestor_mismatch", "Ancestor mismatch demotes to Retain; strict check reports entries", { "entries" => bad })
+        end
+        Snapshot::Classification.assert_complete!(items, strict: true)
+      else
+        Snapshot::Classification.assert_complete!(items, strict: false)
+      end
+      acct = Snapshot::Classification.accounting(items)
+      puts JSON.generate({ "snapshot_id" => sid, "accounting" => acct, "static_crosscheck_hash" => crosscheck["hash"] })
+      puts "Inventory: #{acct['total']} items #{acct['counts'].map { |k, v| "#{k}=#{v}" }.join(' ')} snapshot=#{sid}"
+      0
+    end
+
+    def cmd_build
+      rest, opts = parse_opts(@argv)
+      app_path = rest[0] or return fail_json("missing_argument", "build requires <app_path>")
+      out = opts[:out] or return fail_json("missing_argument", "build requires --out DIR")
+      config = Config.load(app_path, opts[:config])
+      snapshot, crosscheck, items, sid, graph = snapshot_pipeline(app_path, config)
+      Snapshot::Classification.assert_complete!(items, strict: config.strict)
+
+      require_relative "lowering/generator"
+      require_relative "validation/doctor_yellow"
+      FileUtils.mkdir_p(out)
+      File.write(File.join(out, "snapshot.json"), Snapshot::Schema.canonical_json(snapshot))
+      File.write(File.join(out, "crosscheck.json"), Snapshot::Schema.canonical_json(crosscheck))
+
+      generator = Lowering::Generator.new(snapshot: snapshot, snapshot_id: sid, app_path: app_path, out_dir: out, config: config, rubydex_graph: graph)
+      generated = generator.generate(items)
+
+      validator = Validation::DoctorYellow.new(snapshot: snapshot, crosscheck: crosscheck, original_app_path: app_path, build_dir: out)
+      report = validator.run
+      demotions = []
+      if report["verdict"] == "fail"
+        # Demote failed expand/preserve items to retain once and regenerate
+        failed_ids = report["findings"].map { |f| f["item"] }.uniq
+        items.each do |item|
+          if failed_ids.any? { |fid| fid.to_s.include?(item.name.to_s) } && %w[expand preserve].include?(item.classification)
+            item.classification = "retain"
+            demotions << { "item" => item.id, "from" => "generated", "to" => "retain" }
+          end
+        end
+        snapshot["inventory"] = items.map(&:to_h)
+        # regenerate once
+        generator2 = Lowering::Generator.new(snapshot: snapshot, snapshot_id: sid, app_path: app_path, out_dir: out, config: config, rubydex_graph: graph)
+        generated = generator2.generate(items)
+        File.write(File.join(out, "snapshot.json"), Snapshot::Schema.canonical_json(snapshot))
+        report = Validation::DoctorYellow.new(snapshot: snapshot, crosscheck: crosscheck, original_app_path: app_path, build_dir: out).run
+        if report["verdict"] == "fail"
+          # Only fail build if failed items are still expand/preserve
+          still = report["findings"].select { |f| items.any? { |i| i.id == f["item"] && %w[expand preserve].include?(i.classification) } }
+          raise Error.new("validation_failed", "Doctor Yellow failed after one demotion cycle", { "findings" => report["findings"] }) unless still.empty?
+        end
+      end
+      report["demotions"] = demotions
+      report["generator_demotions"] = Array(generator.demotions)
+      File.write(File.join(out, "validation_report.json"), JSON.pretty_generate(report))
+      File.write(File.join(out, "build_report.json"), JSON.pretty_generate({ "snapshot_id" => sid, "generated_files" => generated, "demotions" => report["demotions"], "generator_demotions" => report["generator_demotions"], "validation" => report["verdict"], "modified_retained_config" => ["config/boot.rb (shim)"] }))
+      # verify generated ruby parses
+      generated.each do |rel|
+        next if rel.include?("(shim)")
+
+        path = File.join(out, rel)
+        next unless File.exist?(path) && path.end_with?(".rb")
+
+        out_c, err_c, st = Open3.capture3("ruby", "-c", path)
+        raise Error.new("generated_syntax_error", "#{rel}: #{err_c}") unless st.success?
+      end
+      puts JSON.generate({ "snapshot_id" => sid, "out" => out, "generated_files" => generated, "validation" => report["verdict"], "demotions" => report["demotions"] })
+      report["verdict"] == "pass" ? 0 : 1
+    end
+
+    def cmd_validate
+      rest, opts = parse_opts(@argv)
+      build_dir = rest[0] or return fail_json("missing_argument", "validate requires <build_dir>")
+      snap_path = File.join(build_dir, "snapshot.json")
+      cross_path = File.join(build_dir, "crosscheck.json")
+      return fail_json("missing_build", "snapshot.json not found in #{build_dir}") unless File.exist?(snap_path)
+
+      snapshot = JSON.parse(File.read(snap_path))
+      cross = File.exist?(cross_path) ? JSON.parse(File.read(cross_path)) : {}
+      original = snapshot.dig("manifest", "app_path") || build_dir
+      require_relative "validation/doctor_yellow"
+      report = Validation::DoctorYellow.new(snapshot: snapshot, crosscheck: cross, original_app_path: original, build_dir: build_dir).run
+      File.write(File.join(build_dir, "validation_report.json"), JSON.pretty_generate(report))
+      puts JSON.generate(report)
+      report["verdict"] == "pass" ? 0 : 1
+    end
+
+    def cmd_bench
+      rest, _opts = parse_opts(@argv)
+      build_dir = rest[0] or return fail_json("missing_argument", "bench requires <build_dir>")
+      snap_path = File.join(build_dir, "snapshot.json")
+      original = File.exist?(snap_path) ? JSON.parse(File.read(snap_path)).dig("manifest", "app_path") : nil
+      result = Report::Bench.new(original_path: original, build_dir: build_dir).run
+      puts JSON.pretty_generate(result)
+      File.write(File.join(build_dir, "bench.json"), JSON.pretty_generate(result))
+      0
+    end
+  end
+end

data/lib/catenary/lowering/generator.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "digest"
+require_relative "source_recovery"
+require_relative "rules/base"
+require_relative "rules/v1"
+
+module Catenary
+  module Lowering
+    class Generator
+      attr_reader :generated_files, :demotions
+
+      def initialize(snapshot:, snapshot_id:, app_path:, out_dir:, config:, rubydex_graph: nil)
+        @snapshot = snapshot
+        @snapshot_id = snapshot_id
+        @app_path = File.expand_path(app_path)
+        @out = out_dir
+        @config = config
+        @graph = rubydex_graph
+        @generated_files = []
+        @demotions = []
+        @recovery = SourceRecovery.new(@app_path, rubydex_graph: rubydex_graph)
+      end
+
+      def generate(inventory)
+        FileUtils.mkdir_p(@out)
+        copy_app_tree
+        sid = @snapshot_id
+        header = ->(rule, src) { "# catenary snapshot:#{sid} rule:#{rule} source:#{src}\n" }
+
+        # RouteDispatch + RouteHelpers (standalone modules, never reopen retained classes)
+        rd = Rules::RouteDispatch.new
+        rh = Rules::RouteHelpers.new
+        route_item = Struct.new(:kind).new("route")
+        emit_file("catenary_generated/routes_dispatch.rb", header.call("RouteDispatch", "snapshot:routes") + rd.emit(route_item, @snapshot))
+        emit_file("catenary_generated/route_helpers.rb", header.call("RouteHelpers", "snapshot:routes") + rh.emit(route_item, @snapshot))
+
+        # Templates
+        # Templates: only emit when compiled ERB parses; block-form templates demote to Retain
+        require "prism"
+        erb_rule = Rules::ErbTemplate.new(app_path: @app_path)
+        inventory.select { |i| i.kind == "template" && i.classification == "expand" }.each do |item|
+          out_rel = File.join("catenary_generated/templates", File.basename(item.name.gsub("/", "_")) + ".rb")
+          content = header.call("ErbTemplate", item.name) + erb_rule.emit(item, @snapshot)
+          if Prism.parse(content).success?
+            emit_file(out_rel, content)
+          else
+            @demotions << { "item" => item.id, "reason" => "erb_compile_unparseable_block_form" }
+          end
+        end
+
+        # Per-owner file-level partition (file-scoped): replacement uses only methods defined in the owner's app file.
+        by_owner = inventory.select { |i| i.kind == "method" }.group_by(&:owner)
+        preserve_rule = Rules::PreserveMethod.new(recovery: @recovery)
+        emitted_rel = {}
+        file_of = lambda do |owner|
+          klass = Array(@snapshot["classes"]).find { |c| c["name"] == owner }
+          next nil unless klass
+
+          m = Array(klass["methods"]).find { |mm| mm["app_defined"] && mm["source_location"] }
+          m && m["source_location"][0]
+        end
+        loc_of = ->(item) { (item.extra || {})["source_location"]&.first }
+        by_owner.each do |owner, items|
+          next if owner.nil?
+
+          file = file_of.call(owner)
+          next if file.nil? || file.start_with?("app/models/")
+
+          file_methods = items.select { |i| loc_of.call(i) == file }
+          other_retained = items.count { |i| !file_methods.include?(i) && i.classification == "retain" }
+          @demotions << { "item" => "class:#{owner}", "kind" => "info", "reason" => "framework_owned_methods_retained_not_in_file:#{other_retained}" } if other_retained.positive?
+          next if file_methods.empty?
+          next if file_methods.any? { |i| i.classification == "retain" || i.classification == "reject" }
+          next unless file.start_with?("app/")
+
+          failing = file_methods.find { |item| !preserve_rule.applies?(item, @snapshot) }
+          if failing
+            @demotions << { "item" => failing.id, "reason" => preserve_rule.preconditions(failing, @snapshot).join("; ") }
+            next
+          end
+          next if emitted_rel[file]
+
+          orig_path = File.join(@app_path, file)
+          next unless File.exist?(orig_path)
+
+          content = header.call("PreserveMethod", file) + File.read(orig_path)
+          content += "\n" unless content.end_with?("\n")
+          if Prism.parse(content).success?
+            emit_file(file, content)
+            emitted_rel[file] = true
+          else
+            @demotions << { "item" => "class:#{owner}", "reason" => "preserve_emit_unparseable" }
+          end
+        end
+
+        # ModelDefinitions: emit real model class to original app/models path
+        model_rule = Rules::ModelDefinitions.new
+        inventory.select { |i| i.kind == "model" }.each do |item|
+          model_entry = Array(@snapshot["models"]).find { |m| m["name"] == item.owner }
+          next unless model_entry && model_entry["app_defined"]
+
+          methods = by_owner[item.owner] || []
+          file = file_of.call(item.owner)
+          model_file = if file && file.start_with?("app/models/")
+                         file
+                       else
+                         derived = "app/models/#{item.owner.to_s.split('::').map { |s| s.gsub(/([A-Z]+)([A-Z][a-z])/, '\\1_\\2').gsub(/([a-z0-9])([A-Z])/, '\\1_\\2').downcase }.join('/')}.rb"
+                         File.exist?(File.join(@app_path, derived)) ? derived : file
+                       end
+          next unless model_file && model_file.start_with?("app/models/")
+
+          file_methods = methods.select { |i| loc_of.call(i) == model_file }
+          next if file_methods.any? { |i| i.classification == "retain" || i.classification == "reject" }
+
+          failing = file_methods.select { |i| i.classification == "preserve" }.find { |i| !preserve_rule.applies?(i, @snapshot) }
+          if failing
+            @demotions << { "item" => failing.id, "reason" => preserve_rule.preconditions(failing, @snapshot).join("; ") }
+            next
+          end
+          if (reason = model_rule.ineligible_reason(item, @snapshot))
+            @demotions << { "item" => item.id, "reason" => reason }
+            next
+          end
+          next if emitted_rel[model_file]
+
+          content = header.call("ModelDefinitions", "snapshot:models") + model_rule.emit(item, @snapshot)
+          if Prism.parse(content).success?
+            emit_file(model_file, content)
+            emitted_rel[model_file] = true
+          else
+            @demotions << { "item" => item.id, "reason" => "model_emit_unparseable" }
+          end
+        end
+
+        # Runtime support + boot shim (only retained config modification, listed in report)
+        runtime_src = File.expand_path("../../../runtime/catenary_runtime.rb", __dir__)
+        if File.exist?(runtime_src)
+          FileUtils.mkdir_p(File.join(@out, "catenary_generated"))
+          FileUtils.cp(runtime_src, File.join(@out, "catenary_generated/catenary_runtime.rb"))
+          @generated_files << "catenary_generated/catenary_runtime.rb"
+        end
+        write_boot_shim(header)
+        @generated_files
+      end
+
+      private
+
+      def emit_file(rel, content)
+        path = File.join(@out, rel)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, content)
+        @generated_files << rel
+      end
+
+      def copy_app_tree
+        FileUtils.mkdir_p(@out)
+        Dir[File.join(@app_path, "**/*")].each do |src|
+          rel = src.sub("#{@app_path}/", "")
+          next if rel.start_with?(".git", "tmp/", "log/", "node_modules/", "vendor/bundle")
+          next if rel == ".git"
+
+          dest = File.join(@out, rel)
+          if File.directory?(src)
+            FileUtils.mkdir_p(dest)
+          else
+            FileUtils.mkdir_p(File.dirname(dest))
+            FileUtils.cp(src, dest)
+          end
+        end
+      end
+
+      def write_boot_shim(header)
+        boot = File.join(@out, "config/boot.rb")
+        return unless File.exist?(boot)
+
+        original = File.read(boot)
+        shim = header.call("RetainedRuntime", "config/boot.rb") + original + "\nENV[\"CATENARY_GENERATED\"] = \"1\"\nbegin; require_relative \"../catenary_generated/catenary_runtime\"; rescue LoadError; end\n"
+        File.write(boot, shim)
+        @generated_files << "config/boot.rb (shim)"
+      end
+    end
+  end
+end

data/lib/catenary/lowering/rules/base.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Catenary
+  module Lowering
+    module Rules
+      class Base
+        def applies?(_item, _snapshot) = false
+        def preconditions(_item, _snapshot) = []
+        def emit(_item, _snapshot) = raise NotImplementedError
+        def self.rule_name = name.split("::").last
+      end
+    end
+  end
+end