rubylens 0.1.0 → 0.2.1

data/lib/rubylens/clip_generator.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "artifact_marker"
+require_relative "atomic_output"
+require_relative "default_output"
+require_relative "showcase_generator"
+require_relative "clip/renderer"
+require_relative "clip/toolchain"
+
+module RubyLens
+  ClipResult = Data.define(:output_path, :showcase_path, :counts, :warnings) do
+    def to_payload = { output: output_path, showcase: showcase_path, counts: counts, warnings: warnings }
+  end
+
+  # Generates a shareable MP4 of a project's showcase. The showcase HTML is
+  # written first (it is the render input and stays useful on its own), then
+  # headless Chrome and ffmpeg turn it into one seamless 1080p camera loop.
+  # The toolchain is checked before any indexing so a missing browser or
+  # ffmpeg fails in under a second with install guidance.
+  class ClipGenerator
+    DEFAULT_CLIP_NAME = "rubylens-clip.mp4"
+    # faststart parks the metadata (and so the marker) right behind ftyp, so
+    # every clip RubyLens writes matches within this head window.
+    MARKER_SCAN_HEAD_BYTES = 512 * 1024
+
+    def initialize(path: Dir.pwd, output: nil, lockfile: nil, details: false, progress: nil, renderer: nil)
+      @path = path
+      @output = output
+      @lockfile = lockfile
+      @details = details
+      @progress = progress
+      @renderer = renderer
+    end
+
+    def call
+      renderer = @renderer || build_renderer
+      root = File.realpath(@path)
+      output, showcase_output = resolve_outputs(root)
+      showcase_result = ShowcaseGenerator.new(
+        path: @path, output: showcase_output, lockfile: @lockfile, details: @details,
+      ).call
+      render_atomically(renderer, showcase_result.output_path, output)
+
+      ClipResult.new(
+        output_path: output,
+        showcase_path: showcase_result.output_path,
+        counts: showcase_result.counts,
+        warnings: showcase_result.warnings,
+      )
+    rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP => error
+      raise Error, error.message
+    end
+
+    private
+
+    def build_renderer
+      Clip::Renderer.new(
+        chrome: Clip::Toolchain.chrome_path,
+        ffmpeg: Clip::Toolchain.ffmpeg_path,
+        progress: @progress,
+      )
+    end
+
+    # With no --output, both artifacts use their default names, Git-excluded
+    # locally, and an existing default clip is only replaced if it is ours.
+    # With --output FILE.mp4, the MP4 is written exactly where requested, like
+    # other custom output paths; the derived FILE.html companion was never
+    # named by the user, so an unrelated existing file there is refused.
+    def resolve_outputs(root)
+      if @output.nil?
+        default = DefaultOutput.resolve(root: root, name: DEFAULT_CLIP_NAME, description: "clip") do |existing|
+          ArtifactMarker.present?(existing, Clip::Renderer::MARKER_COMMENT, head_bytes: MARKER_SCAN_HEAD_BYTES)
+        end
+        return [default, nil]
+      end
+
+      # Expanded once here so the guard, the writer, and the reported result
+      # all refer to the same real paths.
+      output = File.expand_path(@output)
+      companion = showcase_companion_path(output)
+      if File.exist?(companion) && !ArtifactMarker.present?(companion, ShowcaseWriter::MARKER)
+        raise Error, "clip companion path #{companion} already exists and is not a RubyLens showcase"
+      end
+
+      [output, companion]
+    end
+
+    def showcase_companion_path(output)
+      base = output.sub(/\.mp4\z/i, "")
+      base = output if base.empty?
+      "#{base}.html"
+    end
+
+    def render_atomically(renderer, showcase_html, output)
+      AtomicOutput.replace(output) do |temporary|
+        renderer.render(showcase_html: showcase_html, output: temporary)
+      rescue Error => error
+        raise Error, "#{error.message} (the showcase HTML was still written to #{showcase_html})"
+      end
+    end
+  end
+end

data/lib/rubylens/default_output.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "git_repository"
+
+module RubyLens
+  # Safety policy shared by every generator's default output path: an existing
+  # file is only replaced when the given check recognizes it as our own kind of
+  # artifact, and the path plus its temporary-file pattern are added to the
+  # repository's local Git excludes.
+  module DefaultOutput
+    module_function
+
+    def resolve(root:, name:, description:)
+      output = File.join(root, name)
+      if File.exist?(output) && !yield(output)
+        raise Error, "default #{description} path already exists and is not a RubyLens #{description}"
+      end
+
+      GitRepository.new(root).exclude_local(output, description: description)
+      output
+    end
+  end
+end

data/lib/rubylens/generator.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
+require_relative "artifact_marker"
+require_relative "default_output"
+
 module RubyLens
-  Result = Data.define(:output_path, :counts, :warnings)
+  Result = Data.define(:output_path, :counts, :warnings) do
+    def to_payload = { output: output_path, counts: counts, warnings: warnings }
+  end
 
   class GenerationPipeline
     def initialize(root:, lockfile: nil)
@@ -32,17 +37,11 @@ module RubyLens
 
     def call
       root = File.realpath(@path)
-      report_writer = ReportWriter.new
-      output = @output
-      if output.nil?
-        output = File.join(root, DEFAULT_REPORT_NAME)
-        if File.exist?(output) && !report_writer.rubylens_report?(output)
-          raise Error, "default report path already exists and is not a RubyLens report"
-        end
-        GitRepository.new(root).exclude_local(output)
+      output = @output || DefaultOutput.resolve(root: root, name: DEFAULT_REPORT_NAME, description: "report") do |existing|
+        ArtifactMarker.present?(existing, ReportWriter::MARKER)
       end
       model, warnings = GenerationPipeline.new(root:, lockfile: @lockfile).call
-      output_path = report_writer.write(model, output: output)
+      output_path = ReportWriter.new.write(model, output: output)
 
       RubyLens::Result.new(output_path: output_path, counts: model.fetch("totals").freeze, warnings:)
     rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP => error

data/lib/rubylens/git_repository.rb

@@ -22,19 +22,25 @@ module RubyLens
     end
 
     def selected_files
-      output, status = capture("ls-files", "-z", "--cached", "--others", "--exclude-standard")
+      arguments = ["ls-files", "-z", "--cached", "--others", "--exclude-standard"]
+      unless @target_root == @git_root
+        relative_target = @target_root.relative_path_from(@git_root)
+        arguments.concat(["--", ":(literal)#{relative_target}"])
+      end
+      output, status = capture(*arguments)
       raise GitError, "failed to enumerate tracked and unignored files" unless status.success?
 
+      git_root = @git_root.to_s
+      target_root = @target_root.to_s
       output.split("\0").filter_map do |relative_to_git|
         next unless INDEXABLE_EXTENSIONS.include?(File.extname(relative_to_git))
 
-        absolute = @git_root.join(relative_to_git).cleanpath
-        next unless Paths.inside?(absolute, @target_root)
-        next unless absolute.file?
-        resolved = absolute.realpath
-        next unless Paths.inside?(resolved, @target_root.realpath)
+        absolute = File.join(git_root, relative_to_git)
+        next unless File.file?(absolute)
+        resolved = File.realpath(absolute)
+        next unless Paths.inside?(resolved, target_root)
 
-        resolved.to_s
+        resolved
       rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP
         nil
       end.sort

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

data/lib/rubylens/index/declaration_collector.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require "rubydex"
+require_relative "../model/dependency_aggregation"
+
+module RubyLens
+  module Index
+    # Streams Rubydex's declarations once and splits them into the three
+    # populations the snapshot needs: workspace namespaces that become scene
+    # points, Ruby construct tallies per category, and dependency declaration
+    # rows aggregated per package.
+    #
+    # It is a single pass because Rubydex materializes a new wrapper for every
+    # accessor call, so revisiting the stream costs as much as producing it.
+    class DeclarationCollector
+      # Shapes shared with the other collectors. A site key is a definition's
+      # location flattened for comparison and grouping; a definition range is a
+      # namespace's span within one file, tagged with the namespace's ordinal.
+      #
+      # @rbs!
+      #   type site_key = [String, Integer, Integer, Integer, Integer]
+      #   type definition_range = [Integer, Integer, Integer, Integer, Integer]
+      #   type dependency_package = { ruby_counts: Array[Integer], declarations: Array[Array[Integer]] }
+
+      # A workspace namespace that earned a scene point, with the canonical
+      # definition sites that decide where its constant references land.
+      Namespace = Data.define(
+        :declaration, #: Rubydex::Namespace
+        :name, #: String
+        :definition_sites, #: Integer
+        :scope, #: Integer
+      )
+
+      Result = Data.define(
+        :namespaces, #: Array[Namespace]
+        :definition_ranges, #: Hash[String, Array[definition_range]]
+        :category_stats, #: Hash[String, Array[Integer]]
+        :dependency_packages, #: Array[dependency_package]
+        :dependency_signal_maxima, #: Array[Integer]
+        :dependency_ordinal_by_name, #: Hash[String, Integer]
+      )
+
+      CLASS = 0
+      MODULE = 1
+      METHOD = 2
+      CONSTANT = 3
+      OTHER_KIND = 2
+      MIXED_SCOPE = 2
+
+      #: (manifest: untyped, locations: LocationIndex) -> void
+      def initialize(manifest:, locations:)
+        @manifest = manifest
+        @locations = locations
+      end
+
+      #: (Enumerable[Rubydex::Declaration]) -> Result
+      def call(declarations)
+        namespaces = []
+        category_stats = { "core" => Array.new(4, 0), "tests" => Array.new(4, 0) }
+        aggregation = Model::DependencyAggregation.new(package_count: @manifest.packages.length)
+        definition_ranges = Hash.new { |ranges, uri| ranges[uri] = [] }
+        dependency_positions = {}
+
+        declarations.each do |declaration|
+          name = declaration.name
+          next unless eligible?(declaration, name)
+
+          namespace = declaration.is_a?(Rubydex::Namespace)
+          construct = construct_index(declaration)
+          # Destructured immediately rather than wrapped: this runs once per
+          # declaration in the largest loop RubyLens has, and the names below
+          # are the only place these five values are ever read.
+          workspace_count, tests_only, site_keys, canonical_scope, package_site_keys =
+            summarize(declaration, namespace)
+
+          if site_keys
+            site_keys = site_keys.uniq if site_keys.length > 1
+            ordinal = namespaces.length
+            site_keys.each do |uri, start_line, start_column, end_line, end_column|
+              definition_ranges[uri] << [start_line, start_column, end_line, end_column, ordinal]
+            end
+            namespaces << Namespace.new(
+              declaration: declaration,
+              name: name,
+              definition_sites: site_keys.length,
+              scope: canonical_scope,
+            )
+          end
+          if construct && workspace_count.positive?
+            category_stats.fetch(tests_only ? "tests" : "core")[construct] += 1
+          end
+          if package_site_keys
+            collect_dependency(
+              aggregation, dependency_positions, declaration, name, namespace, construct, package_site_keys
+            )
+          end
+        end
+
+        Result.new(
+          namespaces: namespaces,
+          definition_ranges: definition_ranges,
+          category_stats: category_stats,
+          dependency_packages: aggregation.packages,
+          dependency_signal_maxima: aggregation.signal_maxima,
+          dependency_ordinal_by_name: global_dependency_ordinals(aggregation.packages, dependency_positions),
+        )
+      end
+
+      # Rubydex reports synthetic declarations RubyLens never draws: anonymous
+      # namespaces, Todo placeholders standing in for unresolved constants, and
+      # singleton classes attached to either.
+      #
+      #: (Rubydex::Declaration, ?String?) -> bool
+      def eligible?(declaration, name = declaration.name)
+        return false if name.nil? || name.empty? || name.include?("<anonymous>")
+        return false if declaration.is_a?(Rubydex::Todo)
+        return true unless declaration.is_a?(Rubydex::SingletonClass)
+
+        attached = declaration.attached_class
+        !attached.is_a?(Rubydex::SingletonClass) && !attached.is_a?(Rubydex::Todo)
+      end
+
+      #: (Rubydex::Declaration) -> Integer?
+      def construct_index(declaration)
+        case declaration
+        when Rubydex::SingletonClass then nil
+        when Rubydex::Class then CLASS
+        when Rubydex::Module then MODULE
+        when Rubydex::Method then METHOD
+        when Rubydex::Constant, Rubydex::ConstantAlias then CONSTANT
+        end
+      end
+
+      private
+
+      # One pass over a declaration's definitions, so each definition's location
+      # and its per-URI workspace, scope, and package answers are read once.
+      # Returns [workspace_count, tests_only, canonical_site_keys,
+      # canonical_scope, package_site_keys]; the site-key collections stay nil
+      # until a definition contributes one, since most declarations contribute
+      # neither a canonical namespace site nor a package site.
+      #
+      #: (Rubydex::Declaration, bool) -> [Integer, bool, Array[site_key]?, Integer, Hash[Integer, Array[site_key]]?]
+      def summarize(declaration, namespace)
+        workspace_count = 0
+        tests_seen = false
+        core_seen = false
+        canonical_tests_seen = false
+        canonical_core_seen = false
+        canonical_site_keys = nil
+        package_site_keys = nil
+
+        declaration.definitions.each do |definition|
+          location = definition.location
+          site_key = nil
+          if @locations.workspace?(location)
+            workspace_count += 1
+            scope = @locations.scope_for(location.uri)
+            if scope == LocationIndex::TEST
+              tests_seen = true
+            elsif scope
+              core_seen = true
+            end
+            if namespace && canonical_definition?(declaration, definition)
+              (canonical_site_keys ||= []) << (site_key = location.comparable_values)
+              if scope == LocationIndex::TEST
+                canonical_tests_seen = true
+              elsif scope
+                canonical_core_seen = true
+              end
+            end
+          end
+          package_index = @locations.package_index_for(location)
+          if package_index
+            ((package_site_keys ||= {})[package_index] ||= []) << (site_key || location.comparable_values)
+          end
+        end
+
+        [
+          workspace_count,
+          tests_seen && !core_seen,
+          canonical_site_keys,
+          canonical_scope(canonical_tests_seen, canonical_core_seen),
+          package_site_keys,
+        ]
+      end
+
+      #: (bool, bool) -> Integer
+      def canonical_scope(tests_seen, core_seen)
+        return LocationIndex::CORE unless tests_seen
+
+        core_seen ? MIXED_SCOPE : LocationIndex::TEST
+      end
+
+      # A declaration reopened across packages is attributed to the one holding
+      # the most of its definitions, ties going to the earliest package.
+      #
+      #: (Model::DependencyAggregation, Hash[String, [Integer, Integer]], Rubydex::Declaration, String, bool, Integer?, Hash[Integer, Array[site_key]]) -> void
+      def collect_dependency(aggregation, positions, declaration, name, namespace, construct, package_site_keys)
+        package_index = nil
+        site_keys = nil
+        package_site_keys.each do |index, keys|
+          if site_keys.nil? || keys.length > site_keys.length ||
+              (keys.length == site_keys.length && index < package_index)
+            package_index = index
+            site_keys = keys
+          end
+        end
+
+        sites = site_keys.length > 1 ? site_keys.uniq.length : site_keys.length
+        references = length_of(declaration, :references)
+        row = [
+          namespace_kind(declaration),
+          namespace ? [declaration.ancestors.count - 1, 0].max : 0,
+          sites,
+          [sites - 1, 0].max,
+          namespace ? [declaration.descendants.count - 1, 0].max : 0,
+          references,
+          namespace ? length_of(declaration, :members) : 0,
+        ].freeze
+        local_index = aggregation.add(package_index: package_index, row: row, construct_index: construct)
+        if references.positive? && constant_reference_target?(declaration, namespace)
+          positions[name] = [package_index, local_index]
+        end
+      end
+
+      # Dependency stars are addressed by a single ordinal spanning every
+      # package, so per-package positions are rebased onto that flat sequence.
+      #
+      #: (Array[dependency_package], Hash[String, [Integer, Integer]]) -> Hash[String, Integer]
+      def global_dependency_ordinals(packages, positions)
+        offsets = []
+        offset = 0
+        packages.each do |package|
+          offsets << offset
+          offset += package.fetch(:declarations).length
+        end
+        positions.transform_values! do |package_index, local_index|
+          offsets.fetch(package_index) + local_index
+        end
+        positions.freeze
+      end
+
+      #: (Rubydex::Declaration) -> Integer
+      def namespace_kind(declaration)
+        case declaration
+        when Rubydex::Class then CLASS
+        when Rubydex::Module then MODULE
+        else OTHER_KIND
+        end
+      end
+
+      #: (Rubydex::Declaration, bool) -> bool
+      def constant_reference_target?(declaration, namespace)
+        namespace ||
+          declaration.is_a?(Rubydex::Constant) ||
+          declaration.is_a?(Rubydex::ConstantAlias)
+      end
+
+      #: (Rubydex::Declaration, Rubydex::Definition) -> bool
+      def canonical_definition?(declaration, definition)
+        (declaration.is_a?(Rubydex::Class) && definition.is_a?(Rubydex::ClassDefinition)) ||
+          (declaration.is_a?(Rubydex::Module) && definition.is_a?(Rubydex::ModuleDefinition))
+      end
+
+      # Rubydex collections expose size on some shapes and only count on others,
+      # and this pre-1.0 interface can raise from either. A dependency star that
+      # cannot report a signal is still a real declaration, so an unreadable
+      # count degrades to zero rather than losing the row.
+      #
+      #: (untyped, Symbol) -> Integer
+      def length_of(object, name)
+        records = object.public_send(name)
+        size = records.size
+        size.nil? ? count_of(records) : size
+      rescue StandardError
+        count_of(records)
+      end
+
+      #: (untyped) -> Integer
+      def count_of(records)
+        records ? records.count : 0
+      rescue StandardError
+        0
+      end
+    end
+  end
+end