carton-tools 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a9b5a58923b272d6d481087138eb847495d2503c428c3007ea31a924831ed6d9
+  data.tar.gz: f24945c590b134e414688a81276b674daef32fdb9f36771c4f8c9317ee7d6840
+SHA512:
+  metadata.gz: feb37915b5d2f255568c3200f6ef947202a90345ab7bf2705db14dc50de4461cf63ac8a62d79dc652a3edd6c9d4aff2b9feb9328366e54a376478f208a030e32
+  data.tar.gz: b93e8b603de790feed455047fa6edc20aa0d5d009b21f706f85c84c8bc42d9f4ab626bcd307c23bfbed607c212a2893fb3832043bb5204e89b1182fde87607ff

data/LICENSE.txt

@@ -0,0 +1,19 @@
+The MIT License (MIT)
+
+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 @@
+# carton-tools
+
+The `carton` command for [Carton](../README.md). It reads code with Prism and never runs it, so it needs no `RUBY_BOX=1`.
+
+- `carton check main.rb` reports import and export problems: missing imports, cycles, `require` calls that reach into a Carton, missing keys of an exported Hash, and gems a gem Carton uses without declaring them.
+- `carton rbs main.rb` writes `sig/generated/carton.rbs`, so [Steep](https://github.com/soutaro/steep) knows what each import returns.
+
+Add it next to `carton`, in the group your checks run in:
+
+```ruby
+# Gemfile
+gem 'carton'
+gem 'carton-tools', group: :development
+```
+
+```sh
+bundle exec carton check main.rb
+```
+
+carton-tools is released with carton and depends on exactly the same version. See [Types and checks](../docs/usage.md#types-and-checks) for what each command does.
+
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).

data/exe/carton

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/carton/tools'
+
+exit Carton::Tools::CLI.start(ARGV)

data/lib/carton/tools/bindings.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative 'project'
+
+module Carton
+  module Tools
+    # The names in a Project bound to imports, `CONST = import ...` or
+    # `local = import ...`, and every use of each. A constant binding is seen
+    # by every file loaded in the same Box (the app's files, or one Carton's);
+    # a local binding only in its own file, and only when nothing reassigns it.
+    class Bindings
+      # A name bound to an imported Carton, with each Use of it.
+      Binding = Data.define(:name, :unit, :file, :line, :uses)
+
+      # One Reference to a binding, and the file it is in.
+      Use = Data.define(:file, :reference)
+
+      attr_reader :all
+
+      def initialize(project)
+        @project = project
+        @by_key = {}
+        @all = []
+        bind_imports
+        collect_uses
+      end
+
+      # Imports matched directly against a pattern, `import('math') => { add: }`,
+      # as [call, unit] pairs.
+      def patterns
+        @project.edges.filter_map do |edge|
+          [edge.call, edge.unit] if edge.unit && edge.call.pattern
+        end
+      end
+
+      private
+
+      def bind_imports
+        clashing = {}
+        @project.edges.each do |edge|
+          call = edge.call
+          next unless edge.unit
+
+          key = binding_key(call)
+          next unless key
+
+          existing = @by_key[key]
+          clashing[key] = true if existing && existing.unit != edge.unit
+          next if existing
+
+          @by_key[key] = Binding.new(
+            name: call.constant || call.local,
+            unit: edge.unit,
+            file: call.file,
+            line: call.line,
+            uses: [],
+          )
+        end
+        clashing.each_key { |key| @by_key.delete(key) }
+        @all = @by_key.values
+      end
+
+      def binding_key(call)
+        if call.constant
+          [:constant, box_of(call.file), call.constant]
+        elsif call.local &&
+              @project.files[call.file].local_writes[call.local] == 1
+          [:local, call.file, call.local]
+        end
+      end
+
+      def collect_uses
+        @project.files.each_value do |file|
+          file.references.each do |reference|
+            binding = lookup(file.path, reference)
+            binding&.uses&.push(Use.new(file: file.path, reference:))
+          end
+        end
+      end
+
+      # A constant resolves lexically: in `module App`, `MathTools` may be
+      # `App::MathTools` or `::MathTools`.
+      def lookup(path, reference)
+        return @by_key[[:local, path, reference.name]] if reference.local
+
+        box = box_of(path)
+        candidates(reference).each do |name|
+          binding = @by_key[[:constant, box, name]]
+          return binding if binding
+        end
+        nil
+      end
+
+      def candidates(reference)
+        name = reference.name
+        return [name.delete_prefix('::')] if name.start_with?('::')
+
+        parts = reference.scope.to_s.split('::')
+        [
+          *parts.size.downto(1).map { |n| [*parts.first(n), name].join('::') },
+          name,
+        ]
+      end
+
+      # Files loaded in the same Box share constants: the app's, or one
+      # Carton's.
+      def box_of(path) = @project.owner(path)&.entrypoint
+    end
+  end
+end

data/lib/carton/tools/checks.rb

@@ -0,0 +1,360 @@
+# frozen_string_literal: true
+
+require_relative 'bindings'
+require 'carton/namespace_methods'
+require 'carton/namespace'
+require_relative 'project'
+
+module Carton
+  module Tools
+    # Problems `carton check` finds in a Project without running it. An error
+    # is certain to fail or misbehave when the code runs. A warning is
+    # something a dynamic program could still get right.
+    class Checks
+      Problem =
+        Data.define(:level, :file, :line, :message) do
+          def error? = level == :error
+        end
+
+      def initialize(project)
+        @project = project
+        @bindings = Bindings.new(project)
+      end
+
+      def problems
+        [
+          *parse_errors,
+          *import_problems,
+          *cycles,
+          *requires_into_cartons,
+          *undeclared_gems,
+          *export_problems,
+          *bare_collisions,
+          *missing_exports,
+          *private_constant_references,
+        ].sort_by { |problem| [problem.file, problem.line, problem.message] }
+      end
+
+      private
+
+      def parse_errors
+        @project.files.each_value.flat_map do |file|
+          file.errors.map { |line, message| error(file.path, line, message) }
+        end
+      end
+
+      # Missing paths and files inside a Carton raise at runtime. A name not on
+      # the load path may come from a gem activated at runtime, and a path
+      # built at runtime cannot be followed. `# carton:dynamic` on an import
+      # says either is intended, such as plugin discovery.
+      def import_problems
+        @project.edges.filter_map do |edge|
+          call = edge.call
+          if edge.error
+            error(call.file, call.line, edge.error)
+          elsif @project.files.fetch(call.file).dynamic_marker?(call.line)
+            next
+          elsif edge.unfound
+            warning(
+              call.file,
+              call.line,
+              "cannot find #{call.path} on the load path: pass -I DIR, " \
+                'or run under bundle exec',
+            )
+          elsif call.path.nil?
+            warning(
+              call.file,
+              call.line,
+              "#{call.kind} path is not a literal, so it is not checked",
+            )
+          end
+        end
+      end
+
+      # An import cycle raises `Carton::ImportError` when every import in it
+      # runs while its file loads. An import inside a method or block may run
+      # after the other Carton has loaded.
+      def cycles
+        graph = Hash.new { |hash, key| hash[key] = [] }
+        @project.edges.each do |edge|
+          from = @project.owner(edge.call.file)
+          graph[from.entrypoint] << edge if from && edge.unit
+        end
+        find_cycles(graph).map do |cycle|
+          first = cycle.first.call
+          names = [cycle.last.unit, *cycle.map(&:unit)].map(&:name)
+          message = "import cycle: #{names.join(' -> ')}"
+          if cycle.any? { |edge| edge.call.lazy }
+            warning(
+              first.file,
+              first.line,
+              "#{message} (an import runs lazily, so it may load)",
+            )
+          else
+            error(first.file, first.line, message)
+          end
+        end
+      end
+
+      # Each elementary cycle once, starting from its smallest Entrypoint. Of
+      # parallel imports between the same Cartons, the eager one counts.
+      def find_cycles(graph)
+        cycles = []
+        graph.each_key.to_a.each do |start|
+          walk(graph, start, start, [], cycles)
+        end
+        cycles
+          .sort_by { |cycle| cycle.count { |edge| edge.call.lazy } }
+          .uniq { |cycle| cycle.map { |edge| edge.unit.entrypoint } }
+      end
+
+      def walk(graph, start, node, path, cycles)
+        graph[node].each do |edge|
+          target = edge.unit.entrypoint
+          if target == start
+            cycles << [*path, edge]
+          elsif target > start && path.none? { |e| e.unit.entrypoint == target }
+            walk(graph, start, target, [*path, edge], cycles)
+          end
+        end
+      end
+
+      # A `require` of an imported Carton's file from outside it loads a second
+      # copy into the requiring Box, which the runtime cannot detect.
+      def requires_into_cartons
+        @project.requires.filter_map do |call|
+          path = @project.locate(call) or next
+          unit = @project.unit_containing(path) or next
+          next if unit == @project.owner(call.file)
+
+          error(
+            call.file,
+            call.line,
+            "#{call.kind} '#{call.path}' loads a second copy of the #{unit.name} " \
+              "Carton's #{path == unit.entrypoint ? 'Entrypoint' : 'file'}: import it instead",
+          )
+        end
+      end
+
+      # A gem Carton's gemspec is its manifest: every other gem it imports or
+      # requires must be a runtime dependency there. Under a bundled app it
+      # still loads today, since the Carton sees the app's whole lockfile, but
+      # it fails wherever the gem is installed without that dependency. Default
+      # gems and Carton itself load in every Box.
+      def undeclared_gems
+        @project.units.each_value.flat_map do |unit|
+          spec = @project.gem_for(unit.entrypoint) or next []
+          declared = [spec.name, *spec.runtime_dependencies.map(&:name)]
+          calls = unit.files.flat_map { |path| loads(path) }
+          calls.filter_map do |call|
+            path = @project.target(call) or next
+            used = @project.gem_for(path) or next
+            next if used.default_gem? || used.name == 'carton'
+            next if declared.include?(used.name)
+
+            error(
+              call.file,
+              call.line,
+              "#{call.kind} '#{call.path}' loads the #{used.name} gem, which " \
+                "#{spec.name}'s gemspec does not declare: add " \
+                "spec.add_dependency '#{used.name}'",
+            )
+          end
+        end
+      end
+
+      def loads(path)
+        file = @project.files.fetch(path)
+        file.imports + file.requires
+      end
+
+      def export_problems
+        @project.files.each_value.flat_map do |file|
+          next [] if file.exports.empty?
+
+          if Resolver.entrypoint_for(file.path) == file.path
+            declaration_problems(file)
+          else
+            file.exports.map do |export|
+              warning(
+                file.path,
+                export.line,
+                'export outside an Entrypoint does nothing: ' \
+                  "this file is inside the Carton #{display(Resolver.entrypoint_for(file.path))}",
+              )
+            end
+          end
+        end
+      end
+
+      # The same rules `Carton::ExportError` enforces at runtime, for calls
+      # that can both run: calls in different branches of one `if` or `case`
+      # never do.
+      def declaration_problems(file)
+        file.exports.each_with_index.flat_map do |export, index|
+          problems = []
+          if export.symbol
+            problems << error(
+              file.path,
+              export.line,
+              'export takes the value to export, not a name: ' \
+                'export a module, or keywords for a Hash',
+            )
+          end
+          if file.exports.first(index).any? { |e| !e.exclusive?(export) }
+            problems << error(
+              file.path,
+              export.line,
+              'export may be called only once per Entrypoint',
+            )
+          end
+          problems
+        end
+      end
+
+      # A Bare Carton's top-level methods become `Carton::Namespace` methods,
+      # so the same names collide.
+      def bare_collisions
+        @project.units.each_value.flat_map do |unit|
+          next [] unless @project.files.fetch(unit.entrypoint).exports.empty?
+
+          unit.files.flat_map do |path|
+            @project
+              .files
+              .fetch(path)
+              .methods
+              .each_value
+              .filter_map do |method|
+                next unless Namespace.reserved?(method.name)
+
+                error(path, method.line, collision(method.name))
+              end
+          end
+        end
+      end
+
+      def collision(name)
+        "a top-level method named #{name} would hide " \
+          "Carton::Namespace##{name}: rename it, or export a module"
+      end
+
+      # A `fetch` of a key a Carton's exported Hash does not have, which
+      # raises KeyError. `[]`, `key?`, and `in` patterns return nil or false
+      # instead. Only keyword and Hash literal exports are checked, since
+      # other exports' members are not declared in one place.
+      def missing_exports
+        from_bindings =
+          @bindings.all.flat_map do |binding|
+            names = hash_keys(binding.unit) or next []
+            binding.uses.filter_map do |use|
+              reference = use.reference
+              next unless raises?(reference)
+              next if names.include?(reference.member)
+
+              error(
+                use.file,
+                reference.line,
+                missing_message(
+                  "#{reference.name}.fetch(:#{reference.member})",
+                  reference.member,
+                  binding.unit,
+                  names,
+                ),
+              )
+            end
+          end
+        from_bindings + missing_pattern_keys
+      end
+
+      def missing_pattern_keys
+        @bindings.patterns.flat_map do |call, unit|
+          names = hash_keys(unit)
+          next [] unless names && call.pattern.kind == :fetch
+
+          (call.pattern.keys - ['**'] - names).map do |key|
+            error(
+              call.file,
+              call.line,
+              missing_message(
+                "#{call.kind}('#{call.path}') => { #{key}: }",
+                key,
+                unit,
+                names,
+              ),
+            )
+          end
+        end
+      end
+
+      # A `fetch` or `=>` pattern raises unless an enclosing `rescue` catches
+      # what it raises.
+      def raises?(reference)
+        return false unless reference.kind == :fetch
+
+        raised = %w[
+          KeyError
+          IndexError
+          NoMatchingPatternKeyError
+          NoMatchingPatternError
+        ]
+        !rescued?(reference, raised)
+      end
+
+      def rescued?(reference, raised)
+        caught = reference.rescued.map { |name| name.delete_prefix('::') }
+        caught.intersect?([*raised, 'StandardError', 'Exception'])
+      end
+
+      def missing_message(code, name, unit, names)
+        "#{code}: the #{unit.name} Carton's export has no key #{name} " \
+          "(it has #{names.join(', ')})"
+      end
+
+      # The keys of the Hash a Carton exports, or nil when it exports
+      # something else or its keys cannot be read statically.
+      def hash_keys(unit)
+        exports = @project.files.fetch(unit.entrypoint).exports
+        exports.first.keys&.keys if exports.size == 1
+      end
+
+      # `Billing::Tax`, where the billing Carton exports `Billing` and
+      # `Billing` makes `Tax` private, raises NameError.
+      def private_constant_references
+        @bindings.all.flat_map do |binding|
+          default = default_export(binding.unit) or next []
+          privates =
+            binding.unit.files.flat_map do |path|
+              @project.files.fetch(path).private_constants
+            end
+          binding.uses.filter_map do |use|
+            reference = use.reference
+            next unless reference.kind == :const
+            next unless privates.include?("#{default}::#{reference.member}")
+            next if rescued?(reference, %w[NameError])
+
+            error(
+              use.file,
+              reference.line,
+              "#{reference.name}::#{reference.member} is a private constant " \
+                "of the #{binding.unit.name} Carton",
+            )
+          end
+        end
+      end
+
+      # The constant a Carton exports, or nil.
+      def default_export(unit)
+        exports = @project.files.fetch(unit.entrypoint).exports
+        exports.first.value if exports.size == 1
+      end
+
+      def display(path) = Project.relative(path)
+
+      def error(file, line, message) = Problem.new(:error, file, line, message)
+
+      def warning(file, line, message)
+        Problem.new(:warning, file, line, message)
+      end
+    end
+  end
+end

data/lib/carton/tools/cli.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'optparse'
+require_relative 'checks'
+require_relative 'signatures'
+
+module Carton
+  module Tools
+    # `carton rbs` and `carton check`. Both read code with Prism and never run
+    # it, so neither needs `RUBY_BOX=1`.
+    class CLI
+      USAGE = <<~TEXT
+        Usage: carton COMMAND [options] PATH...
+
+        Commands:
+          rbs    Write RBS for what each import returns
+          check  Report import and export problems without running code
+
+        PATH is a Ruby file or a directory of them, such as main.rb or app.
+        Imports are followed into every Carton they reach.
+      TEXT
+
+      RBS_OUTPUT = 'sig/generated/carton.rbs'
+
+      def self.start(argv, out: $stdout, err: $stderr)
+        new(out:, err:).run(argv)
+      end
+
+      def initialize(out:, err:)
+        @out = out
+        @err = err
+      end
+
+      # Returns the exit status: 0 on success, 1 when `check` finds errors,
+      # and 2 for a usage error.
+      def run(argv)
+        command, *args = argv
+        case command
+        when 'rbs'
+          rbs(args)
+        when 'check'
+          check(args)
+        when '-h', '--help'
+          @out.puts USAGE
+          0
+        else
+          @err.puts "carton: unknown command #{command}\n\n" if command
+          @err.puts USAGE
+          2
+        end
+      rescue OptionParser::ParseError, Errno::ENOENT => e
+        @err.puts "carton: #{e.message}"
+        2
+      end
+
+      private
+
+      def rbs(args)
+        output = RBS_OUTPUT
+        project =
+          project(args, 'rbs') do |o|
+            o.on(
+              '-o',
+              '--output FILE',
+              "Where to write the RBS (default #{RBS_OUTPUT}, - for stdout)",
+            ) { |file| output = file }
+          end
+        return 2 unless project
+
+        rbs = Signatures.new(project).to_s
+        if output == '-'
+          @out.print rbs
+        else
+          FileUtils.mkdir_p(File.dirname(output))
+          File.write(output, rbs)
+          @out.puts "Wrote #{output}"
+        end
+        0
+      end
+
+      def check(args)
+        strict = false
+        project =
+          project(args, 'check') do |o|
+            o.on('--strict', 'Fail on warnings too, not only errors') do
+              strict = true
+            end
+          end
+        return 2 unless project
+
+        problems = Checks.new(project).problems
+        pwd = File.realpath(Dir.pwd)
+        problems.each do |problem|
+          file = Project.relative(problem.file)
+          message = problem.message.gsub("#{pwd}/", '').gsub(pwd, '.')
+          @out.puts "#{file}:#{problem.line}: #{problem.level}: #{message}"
+        end
+        errors = problems.count(&:error?)
+        @out.puts "#{project.files.size} files, #{project.units.size} Cartons, " \
+                    "#{errors} errors, #{problems.size - errors} warnings"
+        failures = strict ? problems.size : errors
+        failures.zero? ? 0 : 1
+      end
+
+      # Parse options shared by every command, then scan PATHs. Named imports
+      # resolve against `-I` directories, then this process's `$LOAD_PATH`,
+      # which includes the bundle's gems under `bundle exec`, and files belong
+      # to the gems RubyGems knows: the bundle's, or every installed gem.
+      def project(args, command)
+        includes = []
+        parser =
+          OptionParser.new do |o|
+            o.banner = "Usage: carton #{command} [options] PATH..."
+            o.on(
+              '-I',
+              '--include DIR',
+              'Add DIR to the load path for named imports',
+            ) { |dir| includes << File.expand_path(dir) }
+            yield o if block_given?
+          end
+        paths = parser.parse(args)
+        if paths.empty?
+          @err.puts parser
+          return
+        end
+
+        Project.new(paths, load_path: includes + $LOAD_PATH)
+      end
+    end
+
+    private_constant :Checks, :Project, :Signatures, :SourceFile
+  end
+end