carton-tools 0.3.0

data/lib/carton/tools/project.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'carton/error'
+require 'carton/resolver'
+require_relative 'source_file'
+
+module Carton
+  module Tools
+    # The Cartons an app imports, found by following `import` and
+    # `import_relative` calls from the given files without running them.
+    # Name-based imports resolve against `load_path`, as they would against the
+    # importing Box's `$LOAD_PATH`. `specs` are the gems that files may belong
+    # to: under Bundler, the bundle's.
+    class Project
+      # A Carton: its Entrypoint, its files (the Entrypoint plus its namespace
+      # directory), and the `lib/` a gem-shaped directory import adds to its
+      # load path.
+      Unit =
+        Data.define(:entrypoint, :files, :load_path) do
+          def name = File.basename(entrypoint, '.rb')
+        end
+
+      # One import call and what it resolved to: a Unit, an error message, or
+      # a name not found on the load path, which a gem activated at runtime
+      # may still provide.
+      Edge = Data.define(:call, :unit, :error, :unfound)
+
+      attr_reader :files, :units, :edges
+
+      # `path` relative to the current directory, for messages and comments.
+      def self.relative(path)
+        pwd = File.realpath(Dir.pwd)
+        path.start_with?("#{pwd}/") ? path.delete_prefix("#{pwd}/") : path
+      end
+
+      def initialize(paths, load_path: [], specs: nil)
+        @load_path = load_path
+        @specs = specs
+        @files = {}
+        @units = {}
+        @unit_by_file = {}
+        ruby_files(paths).each { |path| parse(path) }
+        discover
+        @edges = imports.map { |call| resolve(call) }
+        @edge_by_call = @edges.to_h { |edge| [edge.call, edge] }
+      end
+
+      # The absolute path an import or require loads, or nil.
+      def target(call)
+        unless SourceFile::IMPORTS.include?(call.kind.to_sym)
+          return locate(call)
+        end
+
+        @edge_by_call[call]&.unit&.entrypoint
+      end
+
+      # The gem whose require paths hold `path`, or nil.
+      def gem_for(path)
+        gem_dirs
+          .select { |dir, _| path.start_with?("#{dir}/") }
+          .max_by { |dir, _| dir.length }
+          &.last
+      end
+
+      # The Unit `file` belongs to, or nil for the app, which runs in Main.
+      def owner(file) = @unit_by_file[file]
+
+      def imports = @files.values.flat_map(&:imports)
+
+      def requires = @files.values.flat_map(&:requires)
+
+      # Resolve a `require` or `require_relative` call as Ruby would, to an
+      # absolute path or nil.
+      def locate(call)
+        return unless call.path
+
+        base_dir = File.dirname(call.file) if call.relative?
+        feature =
+          Resolver.locate(
+            call.path,
+            load_path: load_path_for(call.file),
+            base_dir:,
+          ).feature
+        File.realpath(feature) if File.absolute_path?(feature)
+      rescue LoadError
+        nil
+      end
+
+      # The Unit whose files include `path`, if that Unit is imported.
+      def unit_containing(path)
+        @unit_by_file[path] || @units[Resolver.entrypoint_for(path)]
+      end
+
+      private
+
+      def gem_dirs
+        @gem_dirs ||=
+          (@specs || Gem::Specification.to_a).flat_map do |spec|
+            spec.full_require_paths.filter_map do |dir|
+              [File.realpath(dir), spec] if File.directory?(dir)
+            end
+          end
+      end
+
+      def ruby_files(paths)
+        files =
+          paths.flat_map do |path|
+            next [path] unless File.directory?(path)
+
+            Dir.glob('**/*.rb', base: path).sort.map { |f| File.join(path, f) }
+          end
+        files.map { |path| File.realpath(path) }
+      end
+
+      def parse(path) = @files[path] ||= SourceFile.parse(path)
+
+      # Follow imports and `require_relative` calls until no new files or
+      # Cartons turn up. A file's load path depends on the Carton it belongs
+      # to, which may be found after the file is read.
+      def discover
+        loop do
+          required =
+            requires.select(&:relative?).filter_map { |call| locate(call) }
+          required = required.grep(/\.rb\z/).reject { |path| @files.key?(path) }
+          found = imports.filter_map { |call| resolve(call).unit }
+          fresh = found.reject { |unit| @units.key?(unit.entrypoint) }
+          break if required.empty? && fresh.empty?
+
+          required.each { |path| parse(path) }
+          fresh.each { |unit| add_unit(unit) }
+        end
+      end
+
+      def add_unit(unit)
+        @units[unit.entrypoint] = unit
+        unit.files.each do |file|
+          @unit_by_file[file] ||= unit
+          parse(file)
+        end
+      end
+
+      def resolve(call)
+        unless call.path
+          return Edge.new(call:, unit: nil, error: nil, unfound: false)
+        end
+
+        base_dir = File.dirname(call.file) if call.relative?
+        target =
+          Resolver.resolve(
+            call.path,
+            load_path: load_path_for(call.file),
+            base_dir:,
+          )
+        unless File.absolute_path?(target.feature)
+          return Edge.new(call:, unit: nil, error: nil, unfound: true)
+        end
+
+        Edge.new(call:, unit: unit_for(target), error: nil, unfound: false)
+      rescue ImportError, LoadError => e
+        Edge.new(call:, unit: nil, error: e.message, unfound: false)
+      end
+
+      def unit_for(target)
+        entrypoint = File.realpath(target.feature)
+        @units.fetch(entrypoint) do
+          dir = entrypoint.delete_suffix('.rb')
+          files =
+            Dir
+              .glob('**/*.rb', base: dir)
+              .sort
+              .map { |file| File.realpath(File.join(dir, file)) }
+          Unit.new(
+            entrypoint:,
+            files: [entrypoint, *files],
+            load_path: target.load_path,
+          )
+        end
+      end
+
+      # Like the runtime, a gem-shaped Carton's `lib/` comes first in its Box.
+      def load_path_for(file)
+        [owner(file)&.load_path, *@load_path].compact
+      end
+    end
+  end
+end

data/lib/carton/tools/signatures.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require_relative 'project'
+
+module Carton
+  module Tools
+    # RBS for a Project's imports, so a type checker like Steep knows what each
+    # `import` returns. An exported constant names the Carton's own type,
+    # which the Carton's RBS declares, and a keyword export is a record type.
+    # Bare Cartons each get a module under `Carton::Namespace`, typed from
+    # rbs-inline `#:` annotations and literal values, or `untyped`.
+    class Signatures
+      HEADER = <<~RBS
+        # Generated by `carton rbs` from the app's imports. Do not edit.
+      RBS
+
+      def initialize(project)
+        @project = project
+        @names = namespace_names
+      end
+
+      def to_s
+        [HEADER, kernel, *namespaces, *constants].compact.join("\n")
+      end
+
+      private
+
+      # One `Kernel#import` overload per literal path that means the same
+      # Carton everywhere it is written. `import_relative` paths depend on the
+      # calling file, so one that resolves differently in two files is left to
+      # the untyped signature.
+      def kernel
+        overloads =
+          %w[import import_relative].filter_map do |kind|
+            types =
+              edges_by_path(kind).filter_map do |path, units|
+                next unless units.uniq.size == 1
+
+                type = type_of(units.first)
+                "(#{path.inspect} path) -> #{type}" unless type == 'untyped'
+              end
+            next if types.empty?
+
+            lines =
+              types.each_with_index.map do |type, index|
+                if index.zero?
+                  "  def #{kind}: #{type}"
+                else
+                  "#{' ' * (kind.size + 6)}| #{type}"
+                end
+              end
+            [*lines, "#{' ' * (kind.size + 6)}| ..."].join("\n")
+          end
+        return if overloads.empty?
+
+        ['module Kernel', '  private', *overloads, 'end', ''].join("\n")
+      end
+
+      def edges_by_path(kind)
+        @project
+          .edges
+          .select { |edge| edge.unit && edge.call.kind == kind }
+          .group_by { |edge| edge.call.path }
+          .transform_values { |edges| edges.map(&:unit) }
+          .sort
+      end
+
+      # Each Bare Carton as a module whose singleton methods and constants
+      # mirror its `Carton::Namespace`.
+      def namespaces
+        @names
+          .sort_by { |_, name| name }
+          .map do |unit, name|
+            members = surface(unit).map { |member| "  #{member}" }
+            [
+              "# #{Project.relative(unit.entrypoint)}",
+              "module Carton::Namespace::#{name}",
+              '  extend ::Carton::NamespaceMethods',
+              *members,
+              'end',
+              '',
+            ].join("\n")
+          end
+      end
+
+      # A Bare Carton's surface is what its files define at top level.
+      def surface(unit)
+        files = unit.files.map { |path| file(path) }
+        methods = files.flat_map { |f| f.methods.keys }.uniq
+        constants = files.flat_map { |f| f.constants.keys + top_definitions(f) }
+        [
+          *methods.map do |name|
+            "def self.#{name}: #{method_type(unit, name)}"
+          end,
+          *constants.uniq.map do |name|
+            "#{name}: #{constant_type(unit, name)}"
+          end,
+        ]
+      end
+
+      # `CONST = import ...` in any file, unless the Carton's own RBS already
+      # declares that name: `Billing = import 'billing'` for `export Billing`.
+      # A constant bound to two different Cartons is skipped.
+      def constants
+        bindings =
+          @project
+            .edges
+            .select { |edge| edge.unit && edge.call.constant }
+            .group_by { |edge| edge.call.constant }
+            .transform_values { |edges| edges.map(&:unit).uniq }
+            .select { |_, units| units.size == 1 }
+        lines =
+          bindings.sort.filter_map do |constant, (unit)|
+            type = type_of(unit)
+            next if type == "singleton(::#{constant})"
+
+            alias_of(constant, unit, type) || "#{constant}: #{type}"
+          end
+        return if lines.empty?
+
+        ['# Constants bound to imports', *lines, ''].join("\n")
+      end
+
+      def alias_of(constant, unit, type)
+        target = type[/\Asingleton\((.+)\)\z/, 1] or return
+        return "module #{constant} = #{target}" if @names.key?(unit)
+
+        kind = definition_kind(unit, target.delete_prefix('::'))
+        "#{kind} #{constant} = #{target}" if kind
+      end
+
+      def type_of(unit)
+        if @names.key?(unit)
+          return "singleton(::Carton::Namespace::#{@names[unit]})"
+        end
+
+        exports = file(unit.entrypoint).exports
+        return 'untyped' unless exports.size == 1
+
+        export = exports.first
+        return "singleton(::#{export.value})" if export.value
+        return 'untyped' unless export.keys&.any?
+
+        fields = export.keys.map { |key, type| "#{key}: #{type}" }
+        "{ #{fields.join(', ')} }"
+      end
+
+      def exported?(unit) = file(unit.entrypoint).exports.any?
+
+      def file(path) = @project.files.fetch(path)
+
+      def method_type(unit, name)
+        unit.files.each do |path|
+          definition = file(path).methods[name]
+          return definition.type if definition
+        end
+        '(?) -> untyped'
+      end
+
+      def constant_type(unit, name)
+        unit.files.each do |path|
+          type = file(path).constants[name]
+          return type if type
+        end
+        kind = definition_kind(unit, name)
+        kind ? "singleton(::#{name})" : 'untyped'
+      end
+
+      def definition_kind(unit, name)
+        unit.files.each do |path|
+          kind = file(path).definitions[name]
+          return kind if kind
+        end
+        nil
+      end
+
+      def top_definitions(entry)
+        entry.definitions.keys.reject { |name| name.include?('::') }
+      end
+
+      # A module name under `Carton::Namespace` for each Bare Carton: its
+      # Entrypoint's name, camelized, with parent directories prepended while
+      # two Cartons share a name.
+      def namespace_names
+        units =
+          @project
+            .edges
+            .filter_map(&:unit)
+            .uniq
+            .reject { |unit| exported?(unit) }
+        depth = units.to_h { |unit| [unit, 1] }
+        loop do
+          names = units.to_h { |unit| [unit, camelize(unit, depth[unit])] }
+          clashes = names.keys.group_by { |unit| names[unit] }.values
+          clashes = clashes.select { |group| group.size > 1 }.flatten
+          if clashes.empty? || clashes.none? { |unit| deeper?(unit, depth) }
+            return names
+          end
+
+          clashes.each { |unit| depth[unit] += 1 }
+        end
+      end
+
+      def deeper?(unit, depth) = depth[unit] < path_parts(unit).size
+
+      def camelize(unit, depth)
+        words = path_parts(unit).last(depth).join('_').split(/[^A-Za-z0-9]+/)
+        words.map { |word| word[0].upcase + word[1..] }.join
+      end
+
+      def path_parts(unit)
+        unit
+          .entrypoint
+          .delete_suffix('.rb')
+          .split('/')
+          .reject { |part| part.empty? || part == 'lib' }
+      end
+    end
+  end
+end