rubylens 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d79e23df4b2738a967167958385f2ef8b6c8dd6bd333f70a96690ed3c6f35823
-  data.tar.gz: '09f0c64309ee0427d3b3cf326187d9aaf9e6cf3d3b6766fd7951c3ba4fccd5e0'
+  metadata.gz: abf1b3d5b3080d2f7a6715fe84c770cdd184ab1c164da45e9d9b4f0c3c1c44f6
+  data.tar.gz: 966f347550c546b49bfa70def65d375f3cb5675c804ed52cd2328b182c45dd82
 SHA512:
-  metadata.gz: e1edf50d830b80dd72f9d033f6d1f9a74a51a90a559c6cc37329701b3762891145fe2e86a4b9f412224af2092a3c4b5c128473b0d453a19d83a689ff9c0570b0
-  data.tar.gz: 22e667b3baec097b8bb30c48ba9aa1c8fcd4817993479c0680b45f1605880ff8351f8ee0355e9ac3e06a3a3cc588471a0fd8953ea1561628e3fa411880d0961b
+  metadata.gz: fdb436f8272c226cbb020851269c04de5c3b713d0eb640b05580ef8a4f7930c5bee8c0df9da0d3185877da452895a2e94e47683f9cb8bf33d884ec80d21d7990
+  data.tar.gz: 27f66613b7207f462d180333f8da247574c7b46064bc44715e3d3914c6b1b25c38f46cda2f5434b1940c64280b7f54c67d4fcc61a9514aec90ead2fa326cd337

data/README.md

@@ -28,11 +28,11 @@ Three levels of disclosure:
 > [!IMPORTANT]
 > Nothing is uploaded and no source code is embedded. Outputs still describe your project: they name it, can name classes and gems, and reveal some relationship topology. See [Privacy and sharing](#privacy-and-sharing).
 
-https://github.com/user-attachments/assets/43570623-6d98-46c9-9303-7faa4035b2a7
+https://github.com/user-attachments/assets/ec8d9357-c726-463b-bbde-0fd6eca25d2c
 
-*The Explorer on Rails: search, fly to a class, expand a gem cloud.*
+*The Explorer on Discourse: search, fly to a class, expand a gem cloud.*
 
-https://github.com/user-attachments/assets/bb266de5-bbd7-4ccd-814b-15961b45bd39
+https://github.com/user-attachments/assets/972a15b9-d863-4a52-85e1-af7bc92c0459
 
 *A `--details` clip: what your team sees.*
 

data/lib/rubylens/art_model_builder.rb

@@ -6,113 +6,202 @@ require_relative "morphology_classifier"
 
 module RubyLens
   class ArtModelBuilder
+    SCHEMA = "rubylens.art.v13"
     SIGNAL_FIELDS = %w[ancestorDepth definitionSites reopenings descendants references members].freeze
+    # Namespace row columns carrying the six signals, aligned with SIGNAL_FIELDS.
+    NAMESPACE_SIGNAL_COLUMNS = (3..8).freeze
 
+    # `order` lists snapshot ordinals in draw order and is the single authority
+    # for each shuffle; the snapshot-ordinal-to-draw-position inverse is derived
+    # where it is needed rather than stored beside it.
+    Namespaces = Data.define(
+      :order, #: Array[Integer]
+      :rows, #: Array[Array[Integer]]
+      :names, #: Array[String]
+      :reference_rows, #: Array[[Integer, Integer]]
+    ) do
+      # Link endpoints past the namespace block address dependency stars, which
+      # the snapshot numbers from zero after the namespaces.
+      #
+      #: () -> Array[Integer]
+      def referenced_dependency_ordinals
+        reference_rows.map { |_referring_index, referenced_index| referenced_index - order.length }
+      end
+
+      #: () -> Array[Integer]
+      def draw_positions
+        positions = Array.new(order.length)
+        order.each_with_index { |old_index, new_index| positions[old_index] = new_index }
+        positions
+      end
+    end
+
+    Packages = Data.define(
+      :order, #: Array[Integer]
+      :rows, #: Array[Array[Integer]]
+      :names, #: Array[String]
+      :morphologies, #: Array[Array[Integer]]
+      :systems, #: Array[Array[Integer]]
+    )
+
+    # Unlike the other two, this index is not an inverse of any stored order:
+    # a dependency star's snapshot ordinal is only known for rows travel
+    # targets, and is captured as the shuffled rows are emitted.
+    Dependencies = Data.define(
+      :rows, #: Array[Array[Integer]]
+      :index, #: Hash[Integer, Integer]
+    )
+
+    #: (?seed: Integer) -> void
     def initialize(seed: 0x51A7_E11A)
       @seed = seed
     end
 
+    # Draw order is shuffled so neighbouring stars come from unrelated parts of
+    # the codebase: adjacent points would otherwise share a package or a name
+    # prefix and read as structure the galaxy does not mean to show. Every
+    # ordinal the snapshot used is therefore remapped onto the shuffled order.
+    #: (Hash[String, untyped]) -> Hash[String, untyped]
     def build(snapshot)
       random = Random.new(@seed)
-      morphology = MorphologyClassifier.new(snapshot).call
-      namespace_order = (0...snapshot.fetch("namespaces").length).to_a.shuffle(random: random)
-      namespace_index = Array.new(namespace_order.length)
-      namespace_order.each_with_index { |old_index, new_index| namespace_index[old_index] = new_index }
-      constant_reference_rows = valid_constant_reference_rows(snapshot)
-      namespaces = namespace_order.map do |index|
-        row = snapshot.fetch("namespaces").fetch(index)
-        [random.rand(0..0xffff_ffff), *row]
-      end
-      namespace_names = namespace_order.map { |index| snapshot.fetch("namespace_names").fetch(index) }
-      package_order = (0...snapshot.fetch("packages").length).to_a.shuffle(random: random)
-      package_index = package_order.each_with_index.to_h
-      dependency_systems, dependency_system_index = build_dependency_systems(snapshot, package_index)
-      package_morphologies = []
-      packages = package_order.map do |old_index|
-        package = snapshot.fetch("packages").fetch(old_index)
-        package_seed = random.rand(0..0xffff_ffff)
-        package_morphology = MorphologyClassifier.new(package:, phase_seed: package_seed).call
-        package_morphologies << [package_morphology.fetch("family"), *package_morphology.fetch("knobs")]
+      namespaces = build_namespaces(snapshot, random)
+      packages = build_packages(snapshot, random)
+      dependencies = build_dependencies(snapshot, packages, namespaces, random)
+
+      {
+        "schema" => SCHEMA,
+        "projectName" => snapshot.fetch("project_name"),
+        "morphology" => morphology_row(MorphologyClassifier.new(snapshot).call),
+        "totals" => {
+          "namespaces" => namespaces.rows.length,
+          "packages" => packages.rows.length,
+          "dependencyStars" => dependencies.rows.length,
+        },
+        "domains" => signal_domains(namespaces.rows, snapshot.fetch("dependency_signal_maxima")),
+        "categoryStats" => snapshot.fetch("category_stats"),
+        "namespaceNames" => namespaces.names,
+        "namespaces" => namespaces.rows,
+        "constantReferenceLinks" => build_constant_reference_links(
+          namespaces.reference_rows,
+          namespaces.draw_positions,
+          dependencies.index,
+        ),
+        "packageNames" => packages.names,
+        "packages" => packages.rows,
+        "packageMorphologies" => packages.morphologies,
+        "dependencySystems" => packages.systems,
+        "dependencyStars" => dependencies.rows,
+        "dependencyWarnings" => allowed_dependency_warnings(snapshot),
+        "warningCounts" => snapshot.fetch("warning_counts"),
+      }
+    end
+
+    private
+
+    #: (Hash[String, untyped], Random) -> Namespaces
+    def build_namespaces(snapshot, random)
+      rows = snapshot.fetch("namespaces")
+      names = snapshot.fetch("namespace_names")
+      order = (0...rows.length).to_a.shuffle(random: random)
+      Namespaces.new(
+        order: order,
+        rows: order.map { |old_index| [random.rand(0..0xffff_ffff), *rows.fetch(old_index)] },
+        names: order.map { |old_index| names.fetch(old_index) },
+        reference_rows: valid_constant_reference_rows(snapshot),
+      )
+    end
+
+    #: (Hash[String, untyped], Random) -> Packages
+    def build_packages(snapshot, random)
+      snapshot_packages = snapshot.fetch("packages")
+      order = (0...snapshot_packages.length).to_a.shuffle(random: random)
+      systems, system_index = build_dependency_systems(snapshot, order.each_with_index.to_h)
+      morphologies = []
+
+      rows = order.map do |old_index|
+        package = snapshot_packages.fetch(old_index)
+        seed = random.rand(0..0xffff_ffff)
+        morphologies << morphology_row(MorphologyClassifier.new(package: package, phase_seed: seed).call)
         [
-          package_seed,
+          seed,
           package.fetch("role"),
           package.fetch("location"),
           package.fetch("declarations").length,
           *package.fetch("ruby_counts"),
-          dependency_system_index.fetch(old_index, -1),
+          system_index.fetch(old_index, -1),
         ]
       end
-      package_names = package_order.map { |old_index| snapshot.fetch("packages").fetch(old_index).fetch("name") }
-      dependency_offsets = []
-      dependency_count = 0
-      snapshot.fetch("packages").each do |package|
-        dependency_offsets << dependency_count
-        dependency_count += package.fetch("declarations").length
-      end
-      dependency_target_rows = {}.compare_by_identity
-      constant_reference_rows.each do |_referring_index, referenced_index|
-        dependency_ordinal = referenced_index - namespace_order.length
-        next if dependency_ordinal.negative? || dependency_ordinal >= dependency_count
-
-        next_package_index = dependency_offsets.bsearch_index { |offset| offset > dependency_ordinal }
-        old_package_index = (next_package_index || dependency_offsets.length) - 1
-        package = snapshot.fetch("packages").fetch(old_package_index)
-        local_index = dependency_ordinal - dependency_offsets.fetch(old_package_index)
-        dependency_target_rows[package.fetch("declarations").fetch(local_index)] = dependency_ordinal
-      end
-      dependencies = []
-      dependency_index = {}
-      package_order.each do |old_index|
+
+      Packages.new(
+        order: order,
+        rows: rows,
+        names: order.map { |old_index| snapshot_packages.fetch(old_index).fetch("name") },
+        morphologies: morphologies,
+        systems: systems,
+      )
+    end
+
+    # Dependency stars are emitted package by package in shuffled order, so a
+    # snapshot ordinal is only recoverable for the rows travel actually targets.
+    # Those rows are identified before the shuffle and tracked by object
+    # identity, since equal declaration rows are common and interchangeable.
+    #: (Hash[String, untyped], Packages, Namespaces, Random) -> Dependencies
+    def build_dependencies(snapshot, packages, namespaces, random)
+      targeted = travel_target_rows(snapshot, namespaces.referenced_dependency_ordinals)
+      rows = []
+      index = {}
+      packages.order.each_with_index do |old_index, new_index|
         package = snapshot.fetch("packages").fetch(old_index)
-        declarations = package.fetch("declarations").sort.shuffle(random: random)
-        declarations.each do |declaration|
-          original_ordinal = dependency_target_rows[declaration]
-          dependency_index[original_ordinal] = dependencies.length if original_ordinal
-          dependencies << [
-            random.rand(0..0xffff_ffff),
-            package_index.fetch(old_index),
-            *declaration.drop(1),
-          ]
+        package.fetch("declarations").sort.shuffle(random: random).each do |declaration|
+          original_ordinal = targeted[declaration]
+          index[original_ordinal] = rows.length if original_ordinal
+          rows << [random.rand(0..0xffff_ffff), new_index, *declaration.drop(1)]
         end
       end
-      constant_reference_links = build_constant_reference_links(
-        constant_reference_rows,
-        namespace_index,
-        dependency_index,
-      )
-      {
-        "schema" => "rubylens.art.v13",
-        "projectName" => snapshot.fetch("project_name"),
-        "morphology" => [morphology.fetch("family"), *morphology.fetch("knobs")],
-        "totals" => {
-          "namespaces" => namespaces.length,
-          "packages" => packages.length,
-          "dependencyStars" => dependencies.length,
-        },
-        "domains" => signal_domains(namespaces, snapshot.fetch("dependency_signal_maxima")),
-        "categoryStats" => snapshot.fetch("category_stats"),
-        "namespaceNames" => namespace_names,
-        "namespaces" => namespaces,
-        "constantReferenceLinks" => constant_reference_links,
-        "packageNames" => package_names,
-        "packages" => packages,
-        "packageMorphologies" => package_morphologies,
-        "dependencySystems" => dependency_systems,
-        "dependencyStars" => dependencies,
-        "dependencyWarnings" => snapshot.fetch("dependency_warnings", []).filter_map do |warning|
-          name = warning.fetch("name")
-          reason = warning.fetch("reason")
-          next unless name.is_a?(String) && DependencyWarning::NAME_PATTERN.match?(name)
-          next unless reason.is_a?(String) && DependencyWarning::ALLOWED_REASONS.include?(reason)
-
-          { "name" => name, "reason" => reason }
-        end,
-        "warningCounts" => snapshot.fetch("warning_counts"),
-      }
+      Dependencies.new(rows: rows, index: index)
     end
 
-    private
+    #: (Hash[String, untyped], Array[Integer]) -> Hash[Array[Integer], Integer]
+    def travel_target_rows(snapshot, dependency_ordinals)
+      offsets = []
+      total = 0
+      snapshot.fetch("packages").each do |package|
+        offsets << total
+        total += package.fetch("declarations").length
+      end
 
+      targeted = {}.compare_by_identity
+      dependency_ordinals.each do |ordinal|
+        next if ordinal.negative? || ordinal >= total
+
+        next_package = offsets.bsearch_index { |offset| offset > ordinal }
+        package_index = (next_package || offsets.length) - 1
+        declarations = snapshot.fetch("packages").fetch(package_index).fetch("declarations")
+        targeted[declarations.fetch(ordinal - offsets.fetch(package_index))] = ordinal
+      end
+      targeted
+    end
+
+    #: (Hash[String, untyped]) -> Array[Integer]
+    def morphology_row(morphology)
+      [morphology.fetch("family"), *morphology.fetch("knobs")]
+    end
+
+    # Warnings reach the artifact only if they match the closed vocabulary, so a
+    # tampered snapshot cannot smuggle arbitrary text into a shareable page.
+    #: (Hash[String, untyped]) -> Array[Hash[String, String]]
+    def allowed_dependency_warnings(snapshot)
+      snapshot.fetch("dependency_warnings", []).filter_map do |warning|
+        name = warning.fetch("name")
+        reason = warning.fetch("reason")
+        next unless name.is_a?(String) && DependencyWarning::NAME_PATTERN.match?(name)
+        next unless reason.is_a?(String) && DependencyWarning::ALLOWED_REASONS.include?(reason)
+
+        { "name" => name, "reason" => reason }
+      end
+    end
+
+    #: (Hash[String, untyped]) -> Array[[Integer, Integer]]
     def valid_constant_reference_rows(snapshot)
       rows = snapshot.fetch("constant_reference_links", [])
       return [] unless rows.is_a?(Array)
@@ -122,6 +211,7 @@ module RubyLens
       end
     end
 
+    #: (Array[[Integer, Integer]], Array[Integer], Hash[Integer, Integer]) -> Array[[Integer, Integer]]
     def build_constant_reference_links(rows, namespace_index, dependency_index)
       snapshot_namespace_count = namespace_index.length
       candidates = rows.filter_map do |row|
@@ -141,6 +231,7 @@ module RubyLens
       candidates.shuffle(random: Random.new(@seed ^ 0xC057_A17E))
     end
 
+    #: (Hash[String, untyped], Hash[Integer, Integer]) -> [Array[Array[Integer]], Hash[Integer, Integer]]
     def build_dependency_systems(snapshot, package_index)
       system_random = Random.new(@seed ^ 0xD3E5_157E)
       package_system_index = {}
@@ -156,17 +247,16 @@ module RubyLens
       [systems, package_system_index]
     end
 
-    def signal_domains(namespaces, dependency_maxima)
-      namespace_columns = [3, 4, 5, 6, 7, 8]
-      namespace_domains = namespace_columns.map { |column| maximum(namespaces, column) }
+    # Each signal is scaled against the larger of its workspace and dependency
+    # maxima, so the two populations stay comparable in the same scene.
+    #: (Array[Array[Integer]], Array[Integer]) -> Hash[String, Integer]
+    def signal_domains(namespace_rows, dependency_maxima)
+      namespace_domains = NAMESPACE_SIGNAL_COLUMNS.map do |column|
+        namespace_rows.map { |row| row[column].to_i }.max || 0
+      end
       SIGNAL_FIELDS.each_with_index.to_h do |field, index|
         [field, [namespace_domains[index], dependency_maxima[index]].max]
       end
     end
-
-    def maximum(rows, column)
-      rows.map { |row| row[column].to_i }.max || 0
-    end
-
   end
 end

data/lib/rubylens/index/constant_reference_collector.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "rubydex"
+require "set"
+
+module RubyLens
+  module Index
+    # Turns Rubydex's resolved constant references into two different things:
+    # the complete inbound reference count for every workspace namespace, and a
+    # bounded sample of directed links the renderer animates as travel.
+    #
+    # The two have deliberately different contracts. Counts are exact. Links
+    # stop at the limits below and are never ranked, so they are a visual
+    # sample and must not be read as a complete relationship or call graph.
+    class ConstantReferenceCollector
+      LINK_LIMIT = 1_024
+      ATTRIBUTION_LIMIT = LINK_LIMIT * 2
+
+      # `inbound_counts` is keyed by namespace ordinal, absent meaning zero;
+      # each link is [referring namespace ordinal, referenced endpoint ordinal].
+      Summary = Data.define(
+        :inbound_counts, #: Hash[Integer, Integer]
+        :links, #: Array[[Integer, Integer]]
+      )
+
+      #: (locations: LocationIndex) -> void
+      def initialize(locations:)
+        @locations = locations
+      end
+
+      # `namespaces` are the collector's workspace namespaces in ordinal order;
+      # `ordinal_by_name` and `dependency_ordinal_by_name` address link
+      # endpoints, with dependency ordinals offset past the namespace block.
+      #
+      #: (graph: Rubydex::Graph, namespaces: Array[DeclarationCollector::Namespace], definition_ranges: Hash[String, Array[DeclarationCollector::definition_range]], ordinal_by_name: Hash[String, Integer], dependency_ordinal_by_name: Hash[String, Integer], namespace_count: Integer) -> Summary
+      def call(graph:, namespaces:, definition_ranges:, ordinal_by_name:, dependency_ordinal_by_name:, namespace_count:)
+        Summary.new(
+          inbound_counts: inbound_counts(namespaces),
+          links: links(graph, definition_ranges, ordinal_by_name, dependency_ordinal_by_name, namespace_count),
+        )
+      end
+
+      private
+
+      # Asking each namespace for its own references is bounded by the
+      # namespaces actually drawn, unlike scanning the global reference stream.
+      #
+      #: (Array[DeclarationCollector::Namespace]) -> Hash[Integer, Integer]
+      def inbound_counts(namespaces)
+        counts = Hash.new(0)
+        namespaces.each_with_index do |namespace, index|
+          namespace.declaration.references.each do |reference|
+            location = begin
+              reference.location
+            rescue StandardError
+              next
+            end
+            counts[index] += 1 if @locations.workspace?(location)
+          end
+        end
+        counts.freeze
+      end
+
+      #: (Rubydex::Graph, Hash[String, Array[DeclarationCollector::definition_range]], Hash[String, Integer], Hash[String, Integer], Integer) -> Array[[Integer, Integer]]
+      def links(graph, definition_ranges, ordinal_by_name, dependency_ordinal_by_name, namespace_count)
+        links = []
+        retained = Set.new
+        attributions = 0
+
+        graph.constant_references.each do |reference|
+          break if links.length >= LINK_LIMIT || attributions >= ATTRIBUTION_LIMIT
+          next unless reference.is_a?(Rubydex::ResolvedConstantReference)
+
+          name = referenced_name(reference)
+          next unless name
+
+          namespace_ordinal = ordinal_by_name[name]
+          dependency_ordinal = dependency_ordinal_by_name[name] unless namespace_ordinal
+          next unless namespace_ordinal || dependency_ordinal
+
+          location = begin
+            reference.location
+          rescue StandardError
+            next
+          end
+          next unless @locations.workspace?(location)
+
+          attributions += 1
+          endpoint = namespace_ordinal || namespace_count + dependency_ordinal
+
+          values = begin
+            location.comparable_values
+          rescue StandardError
+            next
+          end
+          origin = enclosing_namespace_ordinal(values, definition_ranges)
+          next unless origin
+          next if endpoint == origin
+
+          link = [origin, endpoint]
+          next unless retained.add?(link)
+
+          links << link
+        end
+
+        links.freeze
+      end
+
+      #: (Rubydex::ResolvedConstantReference) -> String?
+      def referenced_name(reference)
+        reference.declaration.name
+      rescue StandardError
+        nil
+      end
+
+      # A reference belongs to the innermost namespace definition containing it.
+      # Two definitions sharing the exact same span cannot be told apart, so the
+      # reference is dropped rather than attributed to an arbitrary one.
+      #
+      #: (DeclarationCollector::site_key, Hash[String, Array[DeclarationCollector::definition_range]]) -> Integer?
+      def enclosing_namespace_ordinal(location_values, ranges_by_uri)
+        uri, start_line, start_column, end_line, end_column = location_values
+        best = nil
+        ambiguous = false
+        ranges_by_uri.fetch(uri, []).each do |range|
+          range_start_line, range_start_column, range_end_line, range_end_column, ordinal = range
+          next if compare(range_start_line, range_start_column, start_line, start_column).positive?
+          next if compare(range_end_line, range_end_column, end_line, end_column).negative?
+
+          start_comparison = best ? compare(range_start_line, range_start_column, best[0], best[1]) : 1
+          end_comparison = best && start_comparison.zero? ? compare(range_end_line, range_end_column, best[2], best[3]) : 0
+          if start_comparison.positive? || (start_comparison.zero? && end_comparison.negative?)
+            best = range
+            ambiguous = false
+          elsif start_comparison.zero? && end_comparison.zero? && ordinal != best[4]
+            ambiguous = true
+          end
+        end
+
+        ambiguous ? nil : best&.fetch(4)
+      end
+
+      #: (Integer, Integer, Integer, Integer) -> Integer
+      def compare(left_line, left_column, right_line, right_column)
+        line_comparison = left_line <=> right_line
+        line_comparison.zero? ? left_column <=> right_column : line_comparison
+      end
+    end
+  end
+end