call_map 0.1.0

data/lib/call_map/cli.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "source_index"
+require_relative "analyzer"
+require_relative "formatters/text_tree"
+
+module CallMap
+  # Command-line entry point: parses the target and options, builds the
+  # index, and prints the call tree.
+  #
+  #   call_map OrdersController#destroy --depth=3 --include-comments
+  class CLI
+    DEFAULT_DEPTH = 3
+
+    def self.start(argv)
+      new.start(argv)
+    end
+
+    def start(argv)
+      options = parse_options!(argv)
+      target = argv.first
+      validate_target!(target)
+
+      tree = build_tree(target, options)
+      puts Formatters::TextTree.format(tree, include_comments: options.fetch(:include_comments, false))
+    end
+
+    private
+
+    def build_tree(target, options)
+      owner, method_name = target.split("#", 2)
+      index = SourceIndex.build(root: options.fetch(:root, Dir.pwd))
+      definition = index.find_instance_method(owner, method_name)
+      abort "Error: definition not found for '#{target}'." unless definition
+
+      Analyzer.new(index).build_call_tree(definition, depth: options.fetch(:depth, DEFAULT_DEPTH))
+    end
+
+    def parse_options!(argv)
+      options = {}
+      option_parser(options).parse!(argv)
+      options
+    rescue OptionParser::ParseError => e
+      warn "Error: #{e.message}"
+      exit 1
+    end
+
+    def option_parser(options)
+      OptionParser.new do |opts|
+        opts.on("--depth=N", Integer, "Maximum traversal depth (default: #{DEFAULT_DEPTH})") { |n| options[:depth] = n }
+        opts.on("--include-comments", "Show method leading comments in the tree") { options[:include_comments] = true }
+        opts.on("--root=PATH", "Application root to index (default: cwd)") { |path| options[:root] = path }
+      end
+    end
+
+    def validate_target!(target)
+      return if valid_class_name_method_format?(target)
+
+      warn "Error: Invalid target format '#{target}'. Expected ClassName#method_name."
+      exit 1
+    end
+
+    def valid_class_name_method_format?(target)
+      /\A[A-Z][A-Za-z0-9_]*(::[A-Z][A-Za-z0-9_]*)*#[a-z_][A-Za-z0-9_]*[!?=]?\z/.match?(target)
+    end
+  end
+end

data/lib/call_map/definition.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module CallMap
+  # A single class / module / method definition.
+  #
+  # This is a plain value object and must NOT depend on the parser (Prism).
+  # Building a Definition from an AST is the job of the parser boundary class,
+  # so that parser-specific code stays in one place.
+  class Definition
+    KINDS = %i[class module instance_method class_method].freeze
+
+    # @param kind [Symbol] one of KINDS
+    # @param name [String] method name, or qualified constant name for class/module
+    # @param path [String] file path where the definition is written
+    # @param line [Integer] starting line number of the definition
+    # @param owner [String, nil] qualified constant name of the enclosing class/module (for methods)
+    # @param lexical_nesting [Array<String>, nil] lexical scope stack at the definition site, outermost first
+    # @param superclass [String, nil] superclass constant name as written (for :class definitions)
+    # @param visibility [Symbol] :public / :private / :protected (instance methods)
+    def initialize(kind:, name:, path:, line:, owner: nil, lexical_nesting: nil, superclass: nil, visibility: :public)
+      raise ArgumentError, "unknown kind: #{kind}" unless KINDS.include?(kind)
+
+      @kind = kind
+      @name = name
+      @owner = owner
+      @path = path
+      @line = line
+      @lexical_nesting = lexical_nesting
+      @superclass = superclass
+      @visibility = visibility
+      # Free-form metadata; :comments holds the method's leading comment lines.
+      @metadata = {}
+    end
+
+    attr_reader :kind, :name, :owner, :path, :line, :lexical_nesting, :superclass
+    # Writable so `private :foo`-style post-declarations can adjust it.
+    attr_accessor :visibility
+
+    def public_method?
+      visibility == :public
+    end
+    attr_accessor :metadata
+
+    # Leading comment lines attached at collection time ("#" stripped).
+    def comments
+      metadata[:comments] || []
+    end
+
+    def class_or_module?
+      %i[class module].include?(kind)
+    end
+
+    def method?
+      %i[instance_method class_method].include?(kind)
+    end
+
+    # Human-readable qualified name used for lookups and tree output.
+    #
+    # - class / module:    "Admin::ReportsController"
+    # - instance method:   "OrdersController#destroy"
+    # - class method:      "OrderDeleteService.execute"
+    def qualified_name
+      case kind
+      when :instance_method then "#{owner}##{name}"
+      when :class_method then "#{owner}.#{name}"
+      else name
+      end
+    end
+  end
+end

data/lib/call_map/definition_collector.rb

@@ -0,0 +1,348 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "definition"
+
+module CallMap
+  # The single boundary that touches Prism.
+  #
+  # Prism node types (ClassNode / ModuleNode / DefNode ...) are referenced only
+  # here. Everything else in the codebase works with Definition, so the parser
+  # can be swapped out later by replacing just this class.
+  class DefinitionCollector < Prism::Visitor
+    # Parse `source` and return the list of definitions found in it.
+    #
+    # @param source [String] Ruby source code
+    # @param path [String] file path the source came from (kept on each Definition)
+    # @return [Array<Definition>]
+    def self.collect(source, path:)
+      new(path).collect(source)
+    end
+
+    def initialize(path)
+      super()                # Prism::Visitor#initialize takes no args
+      @path = path
+      @namespace = []        # stack of enclosing class/module names (for qualified naming)
+      @singletons = []       # per-scope singleton owner (nil / String / :unresolved)
+      @lexical_scopes = []   # syntactic scope stack of FULL names (mirrors Module.nesting)
+      @visibilities = [:public] # per-scope visibility state toggled by private/protected/public
+      @inline_visibility = nil  # for the `private def foo` inline form
+      @definitions = []
+    end
+
+    def collect(source)
+      # Prism.parse returns a ParseResult; .value is the root (ProgramNode).
+      # accept(self) starts the visitor traversal from the root.
+      result = Prism.parse(source)
+      @comment_lines = pure_comment_lines(source, result.comments)
+      result.value.accept(self)
+      @definitions
+    end
+
+    # Called when the traversal reaches a `class` definition.
+    def visit_class_node(node)
+      enter_namespace(node.constant_path) do
+        @definitions << build_definition(:class, current_namespace, node, superclass: superclass_name(node))
+        super # descend into the class body (its methods etc.)
+      end
+    end
+
+    # Called when the traversal reaches a `module` definition.
+    def visit_module_node(node)
+      enter_namespace(node.constant_path) do
+        @definitions << build_definition(:module, current_namespace, node)
+        super
+      end
+    end
+
+    # Called for `class << self`, `class << SomeConstant`, and `class << obj`.
+    def visit_singleton_class_node(node)
+      within_singleton(singleton_owner(node.expression)) do
+        super
+      end
+    end
+
+    # Called for every `def` — `def foo`, `def self.foo`, and `def Foo.bar`.
+    def visit_def_node(node)
+      info = method_kind_and_owner(node.receiver)
+      # info is nil when the method belongs to an unresolvable receiver
+      # (e.g. `class << obj`); such defs are skipped rather than mis-registered.
+      # No super in either case — do not recurse into method bodies. Nested
+      # defs inside a method are runtime-only and should not appear in the index.
+      return unless info
+
+      definition = build_definition(info[:kind], node.name.to_s, node, owner: info[:owner])
+      comments = leading_comments(node.location.start_line)
+      definition.metadata[:comments] = comments if comments.any?
+      @definitions << definition
+    end
+
+    # Track `private` / `protected` / `public` visibility directives at the
+    # class-body level (bare toggle, `private def foo`, and `private :foo`).
+    def visit_call_node(node)
+      directive = visibility_directive(node)
+      return super unless directive
+
+      args = node.arguments&.arguments
+      return with_inline_visibility(directive) { super } if args&.any? && args.all?(Prism::DefNode)
+
+      apply_visibility(directive, args)
+      super
+    end
+
+    private
+
+    # Decide the (kind, owner) of a method from its `def` receiver.
+    # Returns nil to signal "do not register this def".
+    #
+    # - no receiver (`def foo`): depends on the enclosing scope
+    #     - inside `class << self` / `class << Const`  -> class method on that owner
+    #     - inside `class << obj` (unresolvable)        -> nil (skip)
+    #     - otherwise                                    -> instance method on the current namespace
+    # - self receiver     (`def self.foo`) -> class method on the current namespace
+    # - constant receiver (`def Foo.bar`)  -> class method owned by that constant
+    def method_kind_and_owner(receiver)
+      case receiver
+      when nil
+        singleton_scope_kind_and_owner
+      when Prism::SelfNode
+        { kind: :class_method, owner: current_namespace }
+      when Prism::ConstantReadNode, Prism::ConstantPathNode
+        { kind: :class_method, owner: qualified_constant(receiver) }
+      end
+    end
+
+    # Interpret the innermost singleton scope for a bodyless `def`.
+    def singleton_scope_kind_and_owner
+      owner = current_singleton_owner
+      case owner
+      when nil then { kind: :instance_method, owner: current_namespace }
+      when :unresolved then nil
+      else { kind: :class_method, owner: owner }
+      end
+    end
+
+    # The superclass constant as written; an absolute path keeps its leading
+    # "::" so downstream resolution can skip the namespace fallback.
+    def superclass_name(node)
+      name = constant_name(node.superclass)
+      return name unless name && absolute_constant?(node.superclass)
+
+      "::#{name}"
+    end
+
+    def build_definition(kind, name, node, owner: nil, superclass: nil)
+      nesting = %i[instance_method class_method].include?(kind) ? lexical_nesting : outer_nesting
+      visibility = kind == :instance_method ? current_visibility : :public
+      Definition.new(kind: kind, name: name, owner: owner, path: @path, line: node.location.start_line,
+                     lexical_nesting: nesting, superclass: superclass, visibility: visibility)
+    end
+
+    # Map of line number → comment text, limited to whole-line comments.
+    # A trailing comment after code (`x = 1 # setup`) must not be mistaken
+    # for a leading comment of the following def.
+    def pure_comment_lines(source, comments)
+      lines = source.lines
+      comments.each_with_object({}) do |comment, map|
+        line = comment.location.start_line
+        map[line] = comment.slice.sub(/\A#\s?/, "") if lines[line - 1]&.strip&.start_with?("#")
+      end
+    end
+
+    # Contiguous comment lines directly above the given line, in source order.
+    # A blank line breaks contiguity, so file-top magic comments are not
+    # attached to the first method.
+    def leading_comments(line)
+      collected = []
+      cursor = line - 1
+      while @comment_lines.key?(cursor)
+        collected.unshift(@comment_lines[cursor])
+        cursor -= 1
+      end
+      collected
+    end
+
+    def visibility_directive(node)
+      return nil unless node.receiver.nil? && %i[public private protected].include?(node.name)
+
+      node.name
+    end
+
+    def apply_visibility(directive, args)
+      if args.nil? || args.empty?
+        @visibilities[-1] = directive
+      else
+        mark_named_visibility(directive, args)
+      end
+    end
+
+    def current_visibility
+      @inline_visibility || @visibilities.last
+    end
+
+    def with_inline_visibility(directive)
+      @inline_visibility = directive
+      yield
+    ensure
+      @inline_visibility = nil
+    end
+
+    # `private :foo, :bar` — adjust already-collected definitions by name.
+    def mark_named_visibility(directive, args)
+      names = args.filter_map { |a| a.value if a.is_a?(Prism::SymbolNode) }
+      @definitions.each do |d|
+        d.visibility = directive if d.kind == :instance_method && d.owner == current_namespace && names.include?(d.name)
+      end
+    end
+
+    # The lexical scope stack at the definition site, outermost first, where
+    # each entry is the scope's FULL qualified name (mirroring Module.nesting,
+    # which is purely syntactic). E.g. inside `module Admin; class Admin::Foo`
+    # the stack is ["Admin", "Admin::Foo"] — resolution tries each entry as a
+    # prefix from innermost outward, so both Admin::Foo::X and Admin::X are
+    # searched, but never a double-prefixed Admin::Admin::X.
+    def lexical_nesting
+      return nil if @lexical_scopes.empty?
+
+      @lexical_scopes.dup
+    end
+
+    # For class/module definitions: the scope stack OUTSIDE the definition
+    # itself. A superclass expression (`class Foo < Bar`) is evaluated in
+    # this outer scope, not inside the class body.
+    def outer_nesting
+      return nil if @lexical_scopes.size <= 1
+
+      @lexical_scopes[0..-2]
+    end
+
+    # Route to absolute or relative namespace handling based on the constant node.
+    def enter_namespace(constant_node, &)
+      name = constant_name(constant_node)
+      ns = current_namespace
+
+      if absolute_constant?(constant_node) || already_qualified?(name, ns)
+        within_absolute_namespace(name, &)
+      else
+        within_namespace(name, &)
+      end
+    end
+
+    # A constant path like `Admin::ReportsController` inside `module Admin`
+    # already contains the enclosing namespace — pushing it would produce
+    # `Admin::Admin::ReportsController`.
+    def already_qualified?(name, namespace)
+      return false if namespace.empty? || name.nil?
+
+      name == namespace || name.start_with?("#{namespace}::")
+    end
+
+    # Push `name` while the block runs, then always pop it back off.
+    # Entering a named class/module also pushes a nil singleton owner, so a
+    # normal class nested inside `class << self` is not mistaken for a singleton.
+    def within_namespace(name)
+      @namespace.push(name)
+      @singletons.push(nil)
+      push_scope(current_namespace)
+      yield
+    ensure
+      @namespace.pop
+      @singletons.pop
+      pop_scope
+    end
+
+    # For absolute constant paths (`class ::Foo::Bar`) and already-qualified
+    # compact-style names, replace the NAMING stack with just the constant's
+    # own segments. The lexical scope stack still gains the new scope while
+    # keeping the outer ones — Module.nesting is syntactic, so enclosing
+    # modules remain part of constant lookup even for such definitions.
+    def within_absolute_namespace(name)
+      saved = [@namespace, @singletons]
+      @namespace = [name]
+      @singletons = [nil]
+      push_scope(name)
+      yield
+    ensure
+      @namespace, @singletons = saved
+      pop_scope
+    end
+
+    # Visibility state and the syntactic scope stack move together whenever a
+    # class/module scope is entered.
+    def push_scope(lexical_name)
+      @visibilities.push(:public)
+      @lexical_scopes.push(lexical_name)
+    end
+
+    def pop_scope
+      @visibilities.pop
+      @lexical_scopes.pop
+    end
+
+    # Track the class-method owner implied by the current singleton scope.
+    # owner is a String ("class << Foo"), or :unresolved ("class << obj").
+    def within_singleton(owner)
+      @singletons.push(owner)
+      @visibilities.push(:public)
+      yield
+    ensure
+      @singletons.pop
+      @visibilities.pop
+    end
+
+    def current_singleton_owner
+      @singletons.last
+    end
+
+    # Resolve the owner for a `class << expression` header.
+    # - self             -> the enclosing class/module
+    # - a constant        -> that (namespace-qualified) constant
+    # - anything else     -> :unresolved (a runtime object we can't name statically)
+    def singleton_owner(expression)
+      case expression
+      when Prism::SelfNode then current_namespace
+      when Prism::ConstantReadNode, Prism::ConstantPathNode then qualified_constant(expression)
+      else :unresolved
+      end
+    end
+
+    # Best-effort qualification of a constant receiver with the current
+    # namespace. Full Ruby constant resolution is out of scope for the MVP;
+    # a relative constant is simply prefixed with the enclosing namespace.
+    def qualified_constant(node)
+      name = constant_name(node)
+      ns = current_namespace
+      return name if name.nil? || ns.empty? || absolute_constant?(node)
+      return ns if name == ns || ns.end_with?("::#{name}")
+
+      "#{ns}::#{name}"
+    end
+
+    # A ConstantPathNode whose root parent is nil represents an absolute
+    # constant path (e.g. `::Reports::Generator`). Such constants should
+    # not be prefixed with the enclosing namespace.
+    def absolute_constant?(node)
+      return false unless node.is_a?(Prism::ConstantPathNode)
+
+      root = node
+      root = root.parent while root.parent.is_a?(Prism::ConstantPathNode)
+      root.parent.nil?
+    end
+
+    def current_namespace
+      @namespace.join("::")
+    end
+
+    # Build a qualified name string from a constant node.
+    # - ConstantReadNode  (`Foo`)        -> "Foo"
+    # - ConstantPathNode  (`Admin::Foo`) -> "Admin::Foo"
+    def constant_name(node)
+      case node
+      when Prism::ConstantReadNode
+        node.name.to_s
+      when Prism::ConstantPathNode
+        [constant_name(node.parent), node.name.to_s].compact.join("::")
+      end
+    end
+  end
+end

data/lib/call_map/formatters/text_tree.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module CallMap
+  module Formatters
+    # Renders a CallNode tree as a text tree using box-drawing characters,
+    # suitable for pasting into Notion or pull requests.
+    #
+    #   OrdersController#destroy
+    #   ├─ before_action set_order
+    #   │  └─ Order.find
+    #   └─ OrderDeleteService.execute
+    #      └─ OrderDeleteService#execute
+    #
+    # With include_comments: true, a resolved node's leading comment is
+    # appended as an inline annotation (opt-in — comments are reading aid,
+    # not call-graph structure):
+    #
+    #   └─ OrderDeleteService#execute  # Destroys the order.
+    class TextTree
+      # Only the first comment line is shown, truncated to keep the tree scannable.
+      MAX_COMMENT_LENGTH = 60
+
+      # @param root [CallNode]
+      # @param include_comments [Boolean] append leading comments to resolved nodes
+      # @return [String]
+      def self.format(root, include_comments: false)
+        new(include_comments: include_comments).format(root)
+      end
+
+      def initialize(include_comments: false)
+        @include_comments = include_comments
+      end
+
+      def format(root)
+        lines = [node_label(root)]
+        append_children(lines, root.children, "")
+        "#{lines.join("\n")}\n"
+      end
+
+      private
+
+      def append_children(lines, children, prefix)
+        children.each_with_index do |child, index|
+          last = index == children.size - 1
+          connector = last ? "└─ " : "├─ "
+          lines << "#{prefix}#{connector}#{node_label(child)}"
+          child_prefix = prefix + (last ? "   " : "│  ")
+          append_children(lines, child.children, child_prefix)
+        end
+      end
+
+      def node_label(node)
+        label = node.label
+        return label unless @include_comments
+
+        comment = node.definition&.comments&.first
+        return label unless comment
+
+        "#{label}  # #{truncate(comment)}"
+      end
+
+      def truncate(text)
+        return text if text.length <= MAX_COMMENT_LENGTH
+
+        "#{text[0, MAX_COMMENT_LENGTH]}…"
+      end
+    end
+  end
+end

data/lib/call_map/method_call.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module CallMap
+  # A single method call extracted from a method body.
+  #
+  # This is a plain value object and must NOT depend on the parser (Prism).
+  # Building a MethodCall from an AST is the job of CallExtractor.
+  class MethodCall
+    # Common Rails methods that appear as bare calls inside controllers and
+    # models. A bare call that stays unresolved and matches this list is
+    # displayed as a framework leaf.
+    KNOWN_FRAMEWORK_METHODS = %w[
+      redirect_to redirect_back render render_to_string head respond_to respond_with
+      params request response session cookies flash logger helpers url_for
+      current_user authenticate_user! sign_in sign_out authorize policy_scope
+      raise puts pp
+    ].freeze
+
+    # @param receiver [String, nil] receiver expression ("OrderDeleteService", "self", nil for bare calls)
+    # @param method_name [String] name of the called method
+    # @param line [Integer] line number of the call site
+    # @param dynamic [Boolean] true for send/public_send style calls
+    # @param absolute [Boolean] true for ::Foo style absolute constant paths
+    # @param callback [String, nil] callback type (e.g. "before_action") if this call originates from a DSL callback
+    def initialize(receiver:, method_name:, line:, dynamic: false, absolute: false, callback: nil)
+      @receiver = receiver
+      @method_name = method_name
+      @line = line
+      @dynamic = dynamic
+      @absolute = absolute
+      @callback = callback
+    end
+
+    attr_reader :receiver, :method_name, :line, :callback
+
+    def dynamic?
+      @dynamic
+    end
+
+    def absolute?
+      @absolute
+    end
+
+    def callback?
+      !@callback.nil?
+    end
+
+    def bare?
+      receiver.nil?
+    end
+
+    # Whether this call, IF it stays unresolved, should be shown as a
+    # framework leaf. An explicit receiver that did not resolve points
+    # outside the indexed app code; a bare call (including a callback filter
+    # like Devise's `before_action :authenticate_user!`) is framework-ish
+    # only when it matches the known Rails method list — an unlisted bare
+    # call may just be an analysis miss, so it gets no suffix instead.
+    def framework_leaf?
+      return false if dynamic?
+      return KNOWN_FRAMEWORK_METHODS.include?(method_name) if bare?
+
+      true
+    end
+
+    # Human-readable label for tree output.
+    def label
+      base = receiver ? "#{receiver}.#{method_name}" : method_name
+      return "#{callback} #{base}" if callback?
+      return "#{base} [dynamic]" if dynamic?
+
+      base
+    end
+  end
+end