carton-tools 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9b5a58923b272d6d481087138eb847495d2503c428c3007ea31a924831ed6d9
-  data.tar.gz: f24945c590b134e414688a81276b674daef32fdb9f36771c4f8c9317ee7d6840
+  metadata.gz: 3ae3c3331c46059824d9cfee8857d5db202c219b1559af6d9d8ef9f5c97ebc37
+  data.tar.gz: 3ea2079bd6ce6e8796bbe0d6285dfcccd910c89f47392eccabf5d31d13e3b053
 SHA512:
-  metadata.gz: feb37915b5d2f255568c3200f6ef947202a90345ab7bf2705db14dc50de4461cf63ac8a62d79dc652a3edd6c9d4aff2b9feb9328366e54a376478f208a030e32
-  data.tar.gz: b93e8b603de790feed455047fa6edc20aa0d5d009b21f706f85c84c8bc42d9f4ab626bcd307c23bfbed607c212a2893fb3832043bb5204e89b1182fde87607ff
+  metadata.gz: 2015b0648a2f087ea87fa9a8aa930afad24b36aa3ff5d4f1058ef6bde8d55fc95eee356d7476365177ed5ffa453f35043398d91a19b6a6789aa7d1331b3804a3
+  data.tar.gz: ad3864182e38083ed977bc231c9d8db3882c7e8289138f57036d06f62a5975880231a30ae2621965e5aabe7d9bc158e0eeed0549d0ceb2a61e5be43bf39d7a64

data/README.md

@@ -1,8 +1,8 @@
 # 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`.
+The `carton` command for [Carton](../README.md) apps with explicit imports and exports. 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 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:
@@ -17,6 +17,6 @@ gem 'carton-tools', group: :development
 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.
+carton-tools is released with carton and depends on exactly the same version. See [Types and checks](https://carton.dtcristo.com/guides/types-and-checks/) for what each command does.
 
 Available as open source under the [MIT License](https://opensource.org/licenses/MIT).

data/lib/carton/tools/bindings.rb

@@ -10,7 +10,7 @@ module Carton
     # 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)
+      Binding = Data.define(:name, :local, :carton, :file, :line, :uses)
 
       # One Reference to a binding, and the file it is in.
       Use = Data.define(:file, :reference)
@@ -21,15 +21,32 @@ module Carton
         @project = project
         @by_key = {}
         @all = []
+        @defined = Hash.new { |hash, box| hash[box] = {} }
+        @project.files.each_value do |file|
+          (file.definitions.keys + file.constants.keys).each do |name|
+            @defined[box_of(file.path)][name] = true
+          end
+        end
         bind_imports
         collect_uses
       end
 
       # Imports matched directly against a pattern, `import('math') => { add: }`,
-      # as [call, unit] pairs.
+      # as [call, carton] pairs.
       def patterns
         @project.edges.filter_map do |edge|
-          [edge.call, edge.unit] if edge.unit && edge.call.pattern
+          [edge.call, edge.carton] if edge.carton && edge.call.pattern
+        end
+      end
+
+      # Definitions that open an imported value or a constant beneath it,
+      # as [path, definition, binding] triples. A definition is a use, too.
+      def reopenings
+        @project.files.each_value.flat_map do |file|
+          file.definition_sites.filter_map do |site|
+            binding = reopened_binding(file.path, site)
+            [file.path, site, binding] if binding
+          end
         end
       end
 
@@ -39,18 +56,19 @@ module Carton
         clashing = {}
         @project.edges.each do |edge|
           call = edge.call
-          next unless edge.unit
+          next unless edge.carton
 
           key = binding_key(call)
           next unless key
 
           existing = @by_key[key]
-          clashing[key] = true if existing && existing.unit != edge.unit
+          clashing[key] = true if existing && existing.carton != edge.carton
           next if existing
 
           @by_key[key] = Binding.new(
             name: call.constant || call.local,
-            unit: edge.unit,
+            local: !call.local.nil?,
+            carton: edge.carton,
             file: call.file,
             line: call.line,
             uses: [],
@@ -83,25 +101,47 @@ module Carton
       def lookup(path, reference)
         return @by_key[[:local, path, reference.name]] if reference.local
 
+        constant(path, reference.name, reference.scope)
+      end
+
+      def constant(path, name, scope)
         box = box_of(path)
-        candidates(reference).each do |name|
-          binding = @by_key[[:constant, box, name]]
+        candidates(name, scope).each do |candidate|
+          binding = @by_key[[:constant, box, candidate]]
           return binding if binding
+          return nil if @defined[box][candidate]
         end
         nil
       end
 
-      def candidates(reference)
-        name = reference.name
+      def candidates(name, scope)
         return [name.delete_prefix('::')] if name.start_with?('::')
 
-        parts = reference.scope.to_s.split('::')
+        parts = scope.to_s.split('::')
         [
           *parts.size.downto(1).map { |n| [*parts.first(n), name].join('::') },
           name,
         ]
       end
 
+      def reopened_binding(path, site)
+        # `module Local; class Billing` defines Local::Billing, even if an
+        # outer scope imported Billing. Qualified parents resolve lexically.
+        unless site.name.include?('::')
+          name = [site.scope, site.name].compact.join('::')
+          return @by_key[[:constant, box_of(path), name]]
+        end
+
+        parts = site.name.split('::')
+        parts
+          .size
+          .downto(1) do |size|
+            binding = constant(path, parts.first(size).join('::'), site.scope)
+            return binding if binding
+          end
+        nil
+      end
+
       # Files loaded in the same Box share constants: the app's, or one
       # Carton's.
       def box_of(path) = @project.owner(path)&.entrypoint

data/lib/carton/tools/checks.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 require_relative 'bindings'
-require 'carton/namespace_methods'
-require 'carton/namespace'
 require_relative 'project'
 
 module Carton
@@ -19,6 +17,7 @@ module Carton
       def initialize(project)
         @project = project
         @bindings = Bindings.new(project)
+        @reopenings = @bindings.reopenings
       end
 
       def problems
@@ -29,9 +28,11 @@ module Carton
           *requires_into_cartons,
           *undeclared_gems,
           *export_problems,
-          *bare_collisions,
+          *missing_export_declarations,
           *missing_exports,
           *private_constant_references,
+          *unused_imports,
+          *reopened_classes,
         ].sort_by { |problem| [problem.file, problem.line, problem.message] }
       end
 
@@ -78,11 +79,11 @@ module Carton
         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
+          graph[from.entrypoint] << edge if from && edge.carton
         end
         find_cycles(graph).map do |cycle|
           first = cycle.first.call
-          names = [cycle.last.unit, *cycle.map(&:unit)].map(&:name)
+          names = [cycle.last.carton, *cycle.map(&:carton)].map(&:name)
           message = "import cycle: #{names.join(' -> ')}"
           if cycle.any? { |edge| edge.call.lazy }
             warning(
@@ -105,15 +106,16 @@ module Carton
         end
         cycles
           .sort_by { |cycle| cycle.count { |edge| edge.call.lazy } }
-          .uniq { |cycle| cycle.map { |edge| edge.unit.entrypoint } }
+          .uniq { |cycle| cycle.map { |edge| edge.carton.entrypoint } }
       end
 
       def walk(graph, start, node, path, cycles)
         graph[node].each do |edge|
-          target = edge.unit.entrypoint
+          target = edge.carton.entrypoint
           if target == start
             cycles << [*path, edge]
-          elsif target > start && path.none? { |e| e.unit.entrypoint == target }
+          elsif target > start &&
+                path.none? { |e| e.carton.entrypoint == target }
             walk(graph, start, target, [*path, edge], cycles)
           end
         end
@@ -124,28 +126,28 @@ module Carton
       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)
+          carton = @project.carton_containing(path) or next
+          next if carton == @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",
+            "#{call.kind} '#{call.path}' loads a second copy of the #{carton.name} " \
+              "Carton's #{path == carton.entrypoint ? 'Entrypoint' : 'file'}: import it instead",
           )
         end
       end
 
-      # A gem Carton's gemspec is its manifest: every other gem it imports or
+      # 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 []
+        @project.cartons.each_value.flat_map do |carton|
+          spec = @project.gem_for(carton.entrypoint) or next []
           declared = [spec.name, *spec.runtime_dependencies.map(&:name)]
-          calls = unit.files.flat_map { |path| loads(path) }
+          calls = carton.files.flat_map { |path| loads(path) }
           calls.filter_map do |call|
             path = @project.target(call) or next
             used = @project.gem_for(path) or next
@@ -212,30 +214,16 @@ module Carton
         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
+      # Only imported Entrypoints must export. The presence of a call is
+      # checked without proving that every path through the file reaches it.
+      def missing_export_declarations
+        @project.cartons.each_value.filter_map do |carton|
+          unless @project.files.fetch(carton.entrypoint).export_lines.empty?
+            next
           end
-        end
-      end
 
-      def collision(name)
-        "a top-level method named #{name} would hide " \
-          "Carton::Namespace##{name}: rename it, or export a module"
+          error(carton.entrypoint, 1, 'an imported Entrypoint must call export')
+        end
       end
 
       # A `fetch` of a key a Carton's exported Hash does not have, which
@@ -245,7 +233,7 @@ module Carton
       def missing_exports
         from_bindings =
           @bindings.all.flat_map do |binding|
-            names = hash_keys(binding.unit) or next []
+            names = hash_keys(binding.carton) or next []
             binding.uses.filter_map do |use|
               reference = use.reference
               next unless raises?(reference)
@@ -257,7 +245,7 @@ module Carton
                 missing_message(
                   "#{reference.name}.fetch(:#{reference.member})",
                   reference.member,
-                  binding.unit,
+                  binding.carton,
                   names,
                 ),
               )
@@ -267,8 +255,8 @@ module Carton
       end
 
       def missing_pattern_keys
-        @bindings.patterns.flat_map do |call, unit|
-          names = hash_keys(unit)
+        @bindings.patterns.flat_map do |call, carton|
+          names = hash_keys(carton)
           next [] unless names && call.pattern.kind == :fetch
 
           (call.pattern.keys - ['**'] - names).map do |key|
@@ -278,7 +266,7 @@ module Carton
               missing_message(
                 "#{call.kind}('#{call.path}') => { #{key}: }",
                 key,
-                unit,
+                carton,
                 names,
               ),
             )
@@ -305,15 +293,15 @@ module Carton
         caught.intersect?([*raised, 'StandardError', 'Exception'])
       end
 
-      def missing_message(code, name, unit, names)
-        "#{code}: the #{unit.name} Carton's export has no key #{name} " \
+      def missing_message(code, name, carton, names)
+        "#{code}: the #{carton.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
+      def hash_keys(carton)
+        exports = @project.files.fetch(carton.entrypoint).exports
         exports.first.keys&.keys if exports.size == 1
       end
 
@@ -321,33 +309,79 @@ module Carton
       # `Billing` makes `Tax` private, raises NameError.
       def private_constant_references
         @bindings.all.flat_map do |binding|
-          default = default_export(binding.unit) or next []
+          constant = exported_constant(binding.carton) or next []
           privates =
-            binding.unit.files.flat_map do |path|
+            binding.carton.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 unless privates.include?("#{constant}::#{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",
+                "of the #{binding.carton.name} Carton",
             )
           end
         end
       end
 
       # The constant a Carton exports, or nil.
-      def default_export(unit)
-        exports = @project.files.fetch(unit.entrypoint).exports
+      def exported_constant(carton)
+        exports = @project.files.fetch(carton.entrypoint).exports
         exports.first.value if exports.size == 1
       end
 
+      # A binding with no reads may be dead code. Constants on a Carton's
+      # Public Surface are also used implicitly by its Importers.
+      def unused_imports
+        @bindings.all.filter_map do |binding|
+          next unless binding.uses.empty?
+          next if public_binding?(binding)
+          next if @reopenings.any? { |_, _, used| used.equal?(binding) }
+
+          warning(
+            binding.file,
+            binding.line,
+            "#{binding.name} is bound to an import of the #{binding.carton.name} " \
+              'Carton but never used',
+          )
+        end
+      end
+
+      def public_binding?(binding)
+        return false if binding.local
+
+        carton = @project.owner(binding.file) or return false
+        exports = @project.files.fetch(carton.entrypoint).exports
+
+        exports.any? do |export|
+          name = export.value&.delete_prefix('::')
+          name &&
+            (binding.name == name || binding.name.start_with?("#{name}::"))
+        end
+      end
+
+      # Classes and modules returned by Imports are shared objects. Opening
+      # one, or defining a constant beneath it, mutates that shared object.
+      def reopened_classes
+        @reopenings.filter_map do |path, site, binding|
+          next if binding.carton == @project.owner(path)
+
+          warning(
+            path,
+            site.line,
+            "#{site.kind} #{site.name} opens #{binding.name} from the " \
+              "#{binding.carton.name} Carton, changing a shared class or module: " \
+              'subclass it or use a refinement instead',
+          )
+        end
+      end
+
       def display(path) = Project.relative(path)
 
       def error(file, line, message) = Problem.new(:error, file, line, message)

data/lib/carton/tools/cli.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'fileutils'
+require 'json'
 require 'optparse'
 require_relative 'checks'
 require_relative 'signatures'
@@ -81,28 +82,64 @@ module Carton
 
       def check(args)
         strict = false
+        format = 'text'
         project =
           project(args, 'check') do |o|
             o.on('--strict', 'Fail on warnings too, not only errors') do
               strict = true
             end
+            o.on(
+              '--format FORMAT',
+              %w[text json],
+              'text (default) or json',
+            ) { |value| format = value }
           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"
+        summary = {
+          files: project.files.size,
+          cartons: project.cartons.size,
+          errors:,
+          warnings: problems.size - errors,
+        }
+        if format == 'json'
+          print_json(problems, summary)
+        else
+          print_text(problems, summary)
+        end
         failures = strict ? problems.size : errors
         failures.zero? ? 0 : 1
       end
 
+      def print_text(problems, summary)
+        problems.each do |problem|
+          @out.puts "#{Project.relative(problem.file)}:#{problem.line}: " \
+                      "#{problem.level}: #{relative_message(problem.message)}"
+        end
+        @out.puts "#{summary[:files]} files, #{summary[:cartons]} Cartons, " \
+                    "#{summary[:errors]} errors, #{summary[:warnings]} warnings"
+      end
+
+      def print_json(problems, summary)
+        list =
+          problems.map do |problem|
+            {
+              level: problem.level,
+              file: Project.relative(problem.file),
+              line: problem.line,
+              message: relative_message(problem.message),
+            }
+          end
+        @out.puts JSON.pretty_generate(problems: list, **summary)
+      end
+
+      def relative_message(message)
+        pwd = File.realpath(Dir.pwd)
+        message.gsub("#{pwd}/", '').gsub(pwd, '.')
+      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

data/lib/carton/tools/project.rb

@@ -9,23 +9,23 @@ module Carton
     # 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
+    # Importer'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 =
+      # A Carton: its Entrypoint, its files (the Entrypoint plus its Interior),
+      # and the `lib/` an Import of a Gem-shaped Directory adds to its load
+      # path.
+      Carton =
         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
+      # One import call and what it resolved to: a Carton, 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)
+      Edge = Data.define(:call, :carton, :error, :unfound)
 
-      attr_reader :files, :units, :edges
+      attr_reader :files, :cartons, :edges
 
       # `path` relative to the current directory, for messages and comments.
       def self.relative(path)
@@ -37,8 +37,8 @@ module Carton
         @load_path = load_path
         @specs = specs
         @files = {}
-        @units = {}
-        @unit_by_file = {}
+        @cartons = {}
+        @carton_by_file = {}
         ruby_files(paths).each { |path| parse(path) }
         discover
         @edges = imports.map { |call| resolve(call) }
@@ -51,7 +51,7 @@ module Carton
           return locate(call)
         end
 
-        @edge_by_call[call]&.unit&.entrypoint
+        @edge_by_call[call]&.carton&.entrypoint
       end
 
       # The gem whose require paths hold `path`, or nil.
@@ -62,8 +62,8 @@ module Carton
           &.last
       end
 
-      # The Unit `file` belongs to, or nil for the app, which runs in Main.
-      def owner(file) = @unit_by_file[file]
+      # The Carton `file` belongs to, or nil for the app, which runs in Main.
+      def owner(file) = @carton_by_file[file]
 
       def imports = @files.values.flat_map(&:imports)
 
@@ -86,9 +86,9 @@ module Carton
         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)]
+      # The Carton whose files include `path`, if that Carton is imported.
+      def carton_containing(path)
+        @carton_by_file[path] || @cartons[Resolver.entrypoint_for(path)]
       end
 
       private
@@ -122,26 +122,26 @@ module Carton
           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) }
+          found = imports.filter_map { |call| resolve(call).carton }
+          fresh = found.reject { |carton| @cartons.key?(carton.entrypoint) }
           break if required.empty? && fresh.empty?
 
           required.each { |path| parse(path) }
-          fresh.each { |unit| add_unit(unit) }
+          fresh.each { |carton| add_carton(carton) }
         end
       end
 
-      def add_unit(unit)
-        @units[unit.entrypoint] = unit
-        unit.files.each do |file|
-          @unit_by_file[file] ||= unit
+      def add_carton(carton)
+        @cartons[carton.entrypoint] = carton
+        carton.files.each do |file|
+          @carton_by_file[file] ||= carton
           parse(file)
         end
       end
 
       def resolve(call)
         unless call.path
-          return Edge.new(call:, unit: nil, error: nil, unfound: false)
+          return Edge.new(call:, carton: nil, error: nil, unfound: false)
         end
 
         base_dir = File.dirname(call.file) if call.relative?
@@ -152,24 +152,24 @@ module Carton
             base_dir:,
           )
         unless File.absolute_path?(target.feature)
-          return Edge.new(call:, unit: nil, error: nil, unfound: true)
+          return Edge.new(call:, carton: nil, error: nil, unfound: true)
         end
 
-        Edge.new(call:, unit: unit_for(target), error: nil, unfound: false)
+        Edge.new(call:, carton: carton_for(target), error: nil, unfound: false)
       rescue ImportError, LoadError => e
-        Edge.new(call:, unit: nil, error: e.message, unfound: false)
+        Edge.new(call:, carton: nil, error: e.message, unfound: false)
       end
 
-      def unit_for(target)
+      def carton_for(target)
         entrypoint = File.realpath(target.feature)
-        @units.fetch(entrypoint) do
+        @cartons.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(
+          Carton.new(
             entrypoint:,
             files: [entrypoint, *files],
             load_path: target.load_path,

data/lib/carton/tools/signatures.rb

@@ -7,8 +7,6 @@ module Carton
     # 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.
@@ -16,11 +14,10 @@ module Carton
 
       def initialize(project)
         @project = project
-        @names = namespace_names
       end
 
       def to_s
-        [HEADER, kernel, *namespaces, *constants].compact.join("\n")
+        [HEADER, kernel, *constants].compact.join("\n")
       end
 
       private
@@ -33,10 +30,10 @@ module Carton
         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
+              edges_by_path(kind).filter_map do |path, cartons|
+                next unless cartons.uniq.size == 1
 
-                type = type_of(units.first)
+                type = type_of(cartons.first)
                 "(#{path.inspect} path) -> #{type}" unless type == 'untyped'
               end
             next if types.empty?
@@ -59,45 +56,12 @@ module Carton
       def edges_by_path(kind)
         @project
           .edges
-          .select { |edge| edge.unit && edge.call.kind == kind }
+          .select { |edge| edge.carton && edge.call.kind == kind }
           .group_by { |edge| edge.call.path }
-          .transform_values { |edges| edges.map(&:unit) }
+          .transform_values { |edges| edges.map(&:carton) }
           .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.
@@ -105,36 +69,31 @@ module Carton
         bindings =
           @project
             .edges
-            .select { |edge| edge.unit && edge.call.constant }
+            .select { |edge| edge.carton && edge.call.constant }
             .group_by { |edge| edge.call.constant }
-            .transform_values { |edges| edges.map(&:unit).uniq }
-            .select { |_, units| units.size == 1 }
+            .transform_values { |edges| edges.map(&:carton).uniq }
+            .select { |_, cartons| cartons.size == 1 }
         lines =
-          bindings.sort.filter_map do |constant, (unit)|
-            type = type_of(unit)
+          bindings.sort.filter_map do |constant, (carton)|
+            type = type_of(carton)
             next if type == "singleton(::#{constant})"
 
-            alias_of(constant, unit, type) || "#{constant}: #{type}"
+            alias_of(constant, carton, type) || "#{constant}: #{type}"
           end
         return if lines.empty?
 
         ['# Constants bound to imports', *lines, ''].join("\n")
       end
 
-      def alias_of(constant, unit, type)
+      def alias_of(constant, carton, type)
         target = type[/\Asingleton\((.+)\)\z/, 1] or return
-        return "module #{constant} = #{target}" if @names.key?(unit)
 
-        kind = definition_kind(unit, target.delete_prefix('::'))
+        kind = definition_kind(carton, 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
+      def type_of(carton)
+        exports = file(carton.entrypoint).exports
         return 'untyped' unless exports.size == 1
 
         export = exports.first
@@ -145,76 +104,15 @@ module Carton
         "{ #{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|
+      def definition_kind(carton, name)
+        carton.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

data/lib/carton/tools/source_file.rb

@@ -38,6 +38,10 @@ module Carton
       Reference =
         Data.define(:name, :local, :scope, :kind, :member, :line, :rescued)
 
+      # A class or module definition, with its name as written and the
+      # enclosing namespace, before entering its body.
+      Definition = Data.define(:name, :scope, :kind, :line)
+
       # A hash pattern matched directly against an import: its Reference
       # `kind` (:fetch for `=>`, :lookup for `in`) and the keys it reads, with
       # `'**'` for a rest pattern.
@@ -61,9 +65,6 @@ module Carton
           end
         end
 
-      # A top-level method and its RBS method type.
-      Def = Data.define(:name, :type, :line)
-
       IMPORTS = %i[import import_relative].freeze
       REQUIRES = %i[require require_relative].freeze
 
@@ -71,10 +72,11 @@ module Carton
                   :imports,
                   :requires,
                   :exports,
-                  :methods,
+                  :export_lines,
                   :constants,
                   :definitions,
                   :references,
+                  :definition_sites,
                   :private_constants,
                   :local_writes,
                   :errors
@@ -86,12 +88,15 @@ module Carton
         @imports = []
         @requires = []
         @exports = []
-        # Top-level methods by name, and RBS types of top-level constants.
-        @methods = {}
+        # Every possible export call, including ones whose execution or type
+        # cannot be inferred, so missing-export checks stay conservative.
+        @export_lines = []
+        # RBS types of top-level constants.
         @constants = {}
         # Every class and module defined, by full name: :class or :module.
         @definitions = {}
         @references = []
+        @definition_sites = []
         # Full names made private with `private_constant`.
         @private_constants = []
         # How many times each local variable is assigned, so a local bound to
@@ -116,12 +121,6 @@ module Carton
         end
       end
 
-      # The rbs-inline `#: TYPE` annotation on `line`, if any.
-      def annotation(line)
-        text = @annotations[line]
-        text[2..].strip if text&.start_with?('#:')
-      end
-
       # The RBS type of a literal value node, or `untyped`.
       def self.literal_type(node)
         case node
@@ -150,36 +149,6 @@ module Carton
         end
       end
 
-      # An RBS method type with untyped parameters matching a `def`.
-      def self.method_type(parameters)
-        return '() -> untyped' unless parameters
-
-        params = parameters.requireds.map { |node| positional(node) }
-        parameters.optionals.each { |node| params << "?untyped #{node.name}" }
-        if parameters.rest.is_a?(Prism::RestParameterNode)
-          params << "*untyped #{parameters.rest.name}".strip
-        end
-        parameters.posts.each { |node| params << positional(node) }
-        parameters.keywords.each do |node|
-          optional = node.is_a?(Prism::OptionalKeywordParameterNode)
-          params << "#{'?' if optional}#{node.name}: untyped"
-        end
-        block = parameters.block ? ' ?{ (?) -> untyped }' : ''
-        case parameters.keyword_rest
-        when Prism::KeywordRestParameterNode
-          params << "**untyped #{parameters.keyword_rest.name}".strip
-        when Prism::ForwardingParameterNode
-          params.push('*untyped', '**untyped')
-          block = ' ?{ (?) -> untyped }'
-        end
-        "(#{params.join(', ')})#{block} -> untyped"
-      end
-
-      def self.positional(node)
-        node.respond_to?(:name) ? "untyped #{node.name}" : 'untyped'
-      end
-      private_class_method :positional
-
       # Walks the tree once, tracking the class and module nesting and whether
       # code runs at load time.
       class Visitor < Prism::Visitor
@@ -243,6 +212,10 @@ module Carton
         end
 
         def visit_call_node(node)
+          if node.name == :export &&
+               (node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode))
+            @file.export_lines << node.location.start_line
+          end
           record_call(node) if node.receiver.nil?
           record_use(node) if bindable?(node.receiver)
           super
@@ -295,16 +268,7 @@ module Carton
           match(node.value, node.pattern, :lookup) { super }
         end
 
-        def visit_def_node(node)
-          if top_level? && node.receiver.nil?
-            line = node.location.start_line
-            type =
-              @file.annotation(line - 1) ||
-                SourceFile.method_type(node.parameters)
-            @file.methods[node.name.to_s] = Def.new(node.name.to_s, type, line)
-          end
-          nest(:@defs) { super }
-        end
+        def visit_def_node(node) = nest(:@defs) { super }
 
         def visit_block_node(node) = nest(:@blocks) { super }
 
@@ -360,9 +324,7 @@ module Carton
         def visit_constant_write_node(node)
           name = qualify(node.name.to_s)
           if top_level?
-            @file.constants[name] = @file.annotation(
-              node.location.start_line,
-            ) || SourceFile.literal_type(node.value)
+            @file.constants[name] = SourceFile.literal_type(node.value)
           end
           binding(:@constant, name, node.value) { super }
         end
@@ -584,6 +546,13 @@ module Carton
           name = constant_name(node.constant_path)
           return nest(:@defs, 0, &) unless name
 
+          @file.definition_sites << Definition.new(
+            name:,
+            scope: @namespace.last,
+            kind:,
+            line: node.location.start_line,
+          )
+
           name = qualify(name)
           @file.definitions[name] ||= kind
           @namespace.push(name)

data/lib/carton/tools/version.rb

@@ -4,6 +4,6 @@ module Carton
   module Tools
     # Always the same as Carton::VERSION: carton-tools reads Carton's
     # internals, so each release depends on exactly its own carton.
-    VERSION = '0.3.0'
+    VERSION = '0.4.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carton-tools
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - David Cristofaro
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.4.0
 - !ruby/object:Gem::Dependency
   name: prism
   requirement: !ruby/object:Gem::Requirement
@@ -37,7 +37,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.8'
-description: The carton command for Carton, the package system Ruby has been missing.
+description: The carton command for Carton apps with explicit imports and exports.
   carton check reports import and export problems and carton rbs writes RBS for what
   each import returns, reading code with Prism without running it. Requires Ruby 4.0.7+.
 email: