call_map 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '07679b146de8490eecbaab5863ba5658cb8a5f94deb9509573dec80012f15a42'
+  data.tar.gz: c8ffb63ed36c006eb6bfe736682e83279ea48e74e94037e332b04f249412993b
+SHA512:
+  metadata.gz: b3ed3a5485192ef21cd7f42bbc1c86401ec918c9caac0553ee38c6e1c906f355e2e4531923ae14568116e53655a1b0d06d97d59ed3755c74cccc871d810a4411
+  data.tar.gz: d462c5c4b7671caa14617056bd8821cd7904c201eb035abb5a31d9edf0de235ac12d7b6f40b0c239224ef5724c249d85856b3f20b8746481dfd2424c091880c9

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 bumpfuji10
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,131 @@
+# CallMap
+
+Rails アプリケーションのメソッド呼び出しチェーンを静的解析して、text tree として出力する gem です。
+
+controller action を起点に「この action は何を呼び、その先で何が起きるのか」を、Notion や PR にそのまま貼れる形で可視化します。コードリーディングの補助ツールであり、完全な静的解析器ではありません。
+
+## 目的
+
+Rails アプリで処理の流れを追うとき、`destroy` action からサービス、モデル、notifier へと手でコードを辿りながらメモを書くことがあります。CallMap はその「呼び出しツリーのメモ」を自動生成します。
+
+- framework 内部ではなく、**自分たちのアプリケーションコード**に集中する
+- 出力は安定していて、ドキュメントや PR に貼れる
+- `before_action` などの Rails DSL も処理経路として表示する
+
+## インストール
+
+現時点では RubyGems には公開していません。GitHub から直接インストールしてください。
+
+```ruby
+# Gemfile
+gem "call_map", github: "bumpfuji10/call_map"
+```
+
+```bash
+bundle install
+```
+
+## 使い方
+
+Rails アプリのルートディレクトリで、`ClassName#method_name` 形式の起点を指定して実行します。
+
+```bash
+bundle exec call_map OrdersController#destroy --depth=3
+```
+
+### 出力例
+
+```text
+OrdersController#destroy
+├─ before_action authenticate_user!
+├─ before_action set_order
+│  ├─ Order.find [framework]
+│  └─ params.[] [framework]
+├─ authorize [framework]
+├─ OrderDeleteService.execute
+│  └─ OrderDeleteService#execute
+│     └─ @order.destroy! [framework]
+└─ OrderNotifier.notify_deletion
+   └─ OrderNotifier#send_notification
+      ├─ OrderNotifier#deliver
+      └─ @order.user [framework]
+```
+
+### オプション
+
+| オプション | 説明 |
+|---|---|
+| `--depth=N` | 探索の深さ制限（デフォルト: 3） |
+| `--include-comments` | メソッド直上のコメントをツリーに表示する |
+| `--root=PATH` | 解析対象のアプリケーションルート（デフォルト: カレントディレクトリ。`app/**/*.rb` を索引します） |
+
+```bash
+bundle exec call_map OrdersController#destroy --depth=2 --include-comments
+```
+
+### ラベルの意味
+
+| ラベル | 意味 |
+|---|---|
+| `before_action foo` | `before_action` 由来の呼び出し（action 本体より前に表示） |
+| `foo [framework]` | 自分のコード内に定義が見つからず、Rails / gem 側と思われる呼び出し。ここで探索を止めます |
+| `foo [dynamic]` | `send` / `public_send` などの動的呼び出し。解決せず葉として表示します |
+| `Foo#bar [circular]` | 探索パス上で同じメソッドに再訪した（循環）。ここで探索を止めます |
+| suffix なしの未解決呼び出し | 自クラス等への呼び出しに見えるが定義を発見できなかったもの。解析漏れの可能性があるため、誤ったラベルを付けません |
+
+## 正確性についてのスタンス
+
+**CallMap は完全な静的解析器ではありません。** Ruby は動的な言語であり、静的解析で実行時の挙動を完全に再現することはできません。CallMap は「コードを読む人が手で書くメモ」の精度を目標にしており、以下を意図的に選択しています。
+
+- 解決できない呼び出しは、誤って潜るのではなく**葉として止める**
+- 確信の持てない呼び出しに誤ったラベルを付けない
+- Rails 内部・Ruby 標準ライブラリ・gem 内部には**潜らない**（`[framework]` として表示して止まります）
+
+## MVP で対応している呼び出しパターン
+
+- 同一クラス内の bare call / private method（継承チェーン込み）
+- `SomeService.execute` — class method
+- `SomeClass.new(...).execute` / `self.new.perform` — instance method
+- `self.foo` — 呼び出し元のコンテキスト（instance / class method）に応じて解決
+- namespace 内の相対定数（`Reports::Runner` から `Generator.build` → `Reports::Generator.build`）、絶対定数（`::Foo`）
+- 継承: 親クラスのメソッド・親クラス配下のネスト定数・superclass の lexical 解決
+- `before_action` / `skip_before_action`（`only:` / `except:`（値は symbol / 文字列 / 配列）、複数指定、継承、reopen、skip 後の再追加。callback 名は symbol 指定のみ対応 — `before_action "audit"` のような文字列指定の filter 名は未対応）
+- メソッド直上コメントの保持と表示（`--include-comments`）
+
+## Known limitations
+
+- `around_action` / `after_action` には対応していません
+- `include` / `extend` された concern / module のメソッド解決には対応していません
+- メタプログラミング（`define_method`、`method_missing`、動的な定数参照など）は解決できません
+- 同名メソッドが複数ある場合、Ruby の実行時ディスパッチと異なる解決をすることがあります
+- 索引対象は `app/**/*.rb` のみです（`lib/` などは対象外）
+- `[framework]` 判定はヒューリスティックです（receiver 付き未解決、または既知の Rails メソッド名リスト）
+
+設計上のトレードオフの詳細は [docs/initial_design.md](docs/initial_design.md) を参照してください。
+
+## バージョン方針
+
+[Semantic Versioning](https://semver.org/) に従います。現在は `0.1.0`（MVP）で、`0.x` の間は出力形式や API に破壊的変更が入る可能性があります。RubyGems への公開は `1.0.0` を目安に検討します。
+
+## License
+
+[MIT License](LICENSE.txt)
+
+## Development
+
+```bash
+bin/setup          # 依存のインストール
+bundle exec rspec  # テスト
+bundle exec rubocop
+bin/console        # 対話プロンプト
+```
+
+fixture の Rails アプリ（`spec/fixtures/rails_app`）に対して手元で実行できます:
+
+```bash
+ruby -Ilib exe/call_map "OrdersController#destroy" --root=spec/fixtures/rails_app
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/bumpfuji10/call_map.

data/exe/call_map

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "call_map"
+require "call_map/cli"
+
+CallMap::CLI.start(ARGV)

data/lib/call_map/analyzer.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "prism"
+require "set" # rubocop:disable Lint/RedundantRequireStatement -- explicit for clarity; Set autoloads only on 3.2+
+require_relative "call_extractor"
+require_relative "callback_extractor"
+require_relative "resolver"
+require_relative "call_node"
+
+module CallMap
+  # Builds a call tree from a starting method definition by recursively
+  # extracting calls and resolving them against the SourceIndex.
+  class Analyzer
+    # @param index [SourceIndex]
+    def initialize(index)
+      @index = index
+      @resolver = Resolver.new(index)
+    end
+
+    # Build a call tree rooted at the given definition.
+    #
+    # @param definition [Definition] the starting method
+    # @param depth [Integer] maximum recursion depth (0 = no children)
+    # @return [CallNode]
+    def build_call_tree(definition, depth: 3)
+      visited = Set.new
+      build_node(definition, nil, depth, visited, entry: true)
+    end
+
+    private
+
+    def build_node(definition, method_call, remaining_depth, visited, entry: false)
+      key = node_key(definition)
+      circular = definition.method? && visited.include?(key)
+      children = if remaining_depth.positive? && definition.method? && !circular
+                   build_children(definition, remaining_depth, visited | [key], entry: entry)
+                 else
+                   []
+                 end
+
+      CallNode.new(definition: definition, method_call: method_call, children: children, circular: circular)
+    end
+
+    def build_children(definition, remaining_depth, visited, entry: false)
+      callback_nodes = if entry && action_entry?(definition)
+                         build_callback_nodes(definition, remaining_depth, visited)
+                       else
+                         []
+                       end
+      call_nodes = extract_calls(definition).map do |call|
+        resolve_and_build(call, definition, remaining_depth, visited)
+      end
+      callback_nodes + call_nodes
+    end
+
+    # before_action only runs before a controller action — a public instance
+    # method. Private/protected helpers used as an entry point get no callbacks.
+    def action_entry?(definition)
+      definition.kind == :instance_method && definition.public_method?
+    end
+
+    # Callback filter symbols are invoked via normal method lookup on the
+    # controller instance — Resolver walks the superclass chain from the
+    # action's class, so a child override wins over the parent's method.
+    def build_callback_nodes(definition, remaining_depth, visited)
+      extract_callbacks(definition).map do |call|
+        resolved = @resolver.resolve(call, context_owner: definition.owner)
+        build_resolved_node(resolved, call, remaining_depth, visited)
+      end
+    end
+
+    def resolve_and_build(call, parent_definition, remaining_depth, visited)
+      resolved = @resolver.resolve(call,
+                                   context_owner: parent_definition.owner,
+                                   context_kind: parent_definition.kind,
+                                   lexical_nesting: parent_definition.lexical_nesting)
+      build_resolved_node(resolved, call, remaining_depth, visited)
+    end
+
+    def build_resolved_node(resolved, call, remaining_depth, visited)
+      if resolved
+        build_node(resolved, call, remaining_depth - 1, visited)
+      else
+        CallNode.new(method_call: call)
+      end
+    end
+
+    # Collect callbacks for the action by replaying before_action /
+    # skip_before_action declarations in inheritance order (parent first) and
+    # declaration order, as Rails does. A skip removes only the callbacks
+    # accumulated so far — a callback re-added afterwards runs again.
+    def extract_callbacks(definition)
+      return [] unless definition.kind == :instance_method
+
+      events = @index.ancestor_chain(definition.owner).reverse.flat_map do |owner|
+        callback_events_on(owner, definition.name)
+      end
+      replay_callback_events(events)
+    end
+
+    def replay_callback_events(events)
+      events.each_with_object([]) do |event, active|
+        case event[:type]
+        when :add then active << event[:call]
+        when :skip then active.reject! { |call| call.method_name == event[:name] }
+        end
+      end
+    end
+
+    def callback_events_on(owner, action_name)
+      @index.find_class_definitions(owner).map(&:path).uniq.flat_map do |path|
+        CallbackExtractor.extract(File.read(path), action_name, owner: owner)
+      end
+    end
+
+    def extract_calls(definition)
+      source = File.read(definition.path)
+      def_node = find_def_node(source, definition)
+      return [] unless def_node
+
+      CallExtractor.extract(def_node)
+    end
+
+    def find_def_node(source, definition)
+      root = Prism.parse(source).value
+      find_def_at_line(root, definition.name, definition.line)
+    end
+
+    def find_def_at_line(node, name, line)
+      return node if node.is_a?(Prism::DefNode) && node.name.to_s == name && node.location.start_line == line
+
+      node.child_nodes.compact.each do |child|
+        result = find_def_at_line(child, name, line)
+        return result if result
+      end
+      nil
+    end
+
+    def node_key(definition)
+      "#{definition.path}:#{definition.line}:#{definition.qualified_name}"
+    end
+  end
+end

data/lib/call_map/call_extractor.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "method_call"
+
+module CallMap
+  # Extracts method calls from a method body's AST.
+  #
+  # Like DefinitionCollector, this is a Prism boundary class — Prism node
+  # types are referenced only here.
+  class CallExtractor < Prism::Visitor
+    DYNAMIC_METHODS = %w[send public_send __send__].freeze
+
+    # Extract calls from a DefNode's body.
+    #
+    # @param def_node [Prism::DefNode] the method definition node
+    # @return [Array<MethodCall>]
+    def self.extract(def_node)
+      extractor = new
+      def_node.body&.accept(extractor)
+      extractor.calls
+    end
+
+    def initialize
+      super
+      @calls = []
+    end
+
+    attr_reader :calls
+
+    def visit_call_node(node)
+      @calls << build_call(node)
+      # Walk arguments and block, but not the receiver itself (it is already
+      # captured in the receiver label). However, walk the receiver chain's
+      # arguments/blocks so that calls like `SomeClass.new(build_order).execute`
+      # still extract `build_order`.
+      node.arguments&.accept(self)
+      node.block&.accept(self)
+      walk_receiver_args(node.receiver)
+    end
+
+    # Do not recurse into nested def bodies — they are not executed
+    # as part of the enclosing method's call path.
+    def visit_def_node(_node); end
+
+    private
+
+    # Walk the receiver chain's arguments/blocks without registering the
+    # receiver CallNodes themselves as separate calls.
+    def walk_receiver_args(receiver)
+      return unless receiver.is_a?(Prism::CallNode)
+
+      receiver.arguments&.accept(self)
+      receiver.block&.accept(self)
+      walk_receiver_args(receiver.receiver)
+    end
+
+    def build_call(node)
+      receiver_str = receiver_label(node.receiver)
+      method_name = node.name.to_s
+      dynamic = DYNAMIC_METHODS.include?(method_name)
+
+      MethodCall.new(
+        receiver: receiver_str,
+        method_name: dynamic ? dynamic_target(node) : method_name,
+        line: node.location.start_line,
+        dynamic: dynamic,
+        absolute: absolute_constant?(node.receiver)
+      )
+    end
+
+    def absolute_constant?(node)
+      case node
+      when Prism::ConstantPathNode
+        current = node
+        current = current.parent while current.is_a?(Prism::ConstantPathNode)
+        current.nil?
+      when Prism::CallNode
+        absolute_constant?(node.receiver)
+      else
+        false
+      end
+    end
+
+    def receiver_label(receiver)
+      case receiver
+      when nil then nil
+      when Prism::SelfNode then "self"
+      when Prism::ConstantReadNode, Prism::InstanceVariableReadNode
+        receiver.name.to_s
+      when Prism::ConstantPathNode then constant_path_name(receiver)
+      when Prism::CallNode then call_chain_label(receiver)
+      else "[expr]"
+      end
+    end
+
+    def constant_path_name(node)
+      parts = []
+      current = node
+      while current.is_a?(Prism::ConstantPathNode)
+        parts.unshift(current.name.to_s)
+        current = current.parent
+      end
+      parts.unshift(current.name.to_s) if current.is_a?(Prism::ConstantReadNode)
+      parts.join("::")
+    end
+
+    def call_chain_label(node)
+      receiver_str = receiver_label(node.receiver)
+      method = node.name.to_s
+      receiver_str ? "#{receiver_str}.#{method}" : method
+    end
+
+    # Best-effort extraction of the target method name from send/public_send.
+    def dynamic_target(node)
+      first_arg = node.arguments&.arguments&.first
+      case first_arg
+      when Prism::SymbolNode then first_arg.value
+      when Prism::StringNode then first_arg.unescaped
+      else "[dynamic]"
+      end
+    end
+  end
+end

data/lib/call_map/call_node.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module CallMap
+  # A node in the call tree. Holds the definition (if resolved), the original
+  # method call, and child nodes representing calls made from within this method.
+  class CallNode
+    # @param definition [Definition, nil] resolved definition, nil for unresolved leaves
+    # @param method_call [MethodCall, nil] the call site that led here (nil for the root)
+    # @param children [Array<CallNode>]
+    # @param circular [Boolean] true when this node revisits a definition already on the current path
+    def initialize(definition: nil, method_call: nil, children: [], circular: false)
+      @definition = definition
+      @method_call = method_call
+      @children = children
+      @circular = circular
+    end
+
+    attr_reader :definition, :method_call, :children
+
+    def resolved?
+      !definition.nil?
+    end
+
+    def circular?
+      @circular
+    end
+
+    # Human-readable label for this node. A callback-originated node keeps its
+    # callback label (e.g. "before_action set_order") even when resolved, so
+    # tree output can distinguish it from a plain call. An unresolved call
+    # that points outside the indexed app code is marked as a framework leaf.
+    def label
+      base = base_label
+      return "#{base} [circular]" if circular?
+      return "#{base} [framework]" if !resolved? && method_call&.framework_leaf?
+
+      base
+    end
+
+    private
+
+    def base_label
+      if definition && !method_call&.callback?
+        definition.qualified_name
+      elsif method_call
+        method_call.label
+      else
+        "[unknown]"
+      end
+    end
+  end
+end

data/lib/call_map/callback_extractor.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "method_call"
+
+module CallMap
+  # Extracts before_action callbacks from a class body that apply to a given action.
+  #
+  # This is a Prism boundary class — Prism node types are referenced only here.
+  class CallbackExtractor < Prism::Visitor
+    # @param source [String] the file source
+    # @param action_name [String] the action method name
+    # @param owner [String] the class name to scope extraction to
+    # @return [Array<Hash>] callback events in declaration order:
+    #   { type: :add, call: MethodCall } for before_action,
+    #   { type: :skip, name: String } for skip_before_action.
+    #   Order matters — a callback re-added after a skip runs again.
+    def self.extract(source, action_name, owner:)
+      root = Prism.parse(source).value
+      class_bodies = find_class_bodies(root, owner)
+      return [] if class_bodies.empty?
+
+      extractor = new(action_name)
+      class_bodies.each { |body| body.accept(extractor) }
+      extractor.events
+    end
+
+    # Collect ALL class bodies matching the owner (a class may be reopened
+    # multiple times in the same file), in source order.
+    def self.find_class_bodies(node, owner)
+      collect_class_nodes(node, owner, []).filter_map(&:body)
+    end
+
+    def self.collect_class_nodes(node, owner, namespace)
+      return collect_within_class_or_module(node, owner, namespace) if class_or_module?(node)
+
+      node.child_nodes.compact.flat_map { |child| collect_class_nodes(child, owner, namespace) }
+    end
+
+    def self.class_or_module?(node)
+      node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode)
+    end
+
+    def self.collect_within_class_or_module(node, owner, namespace)
+      qualified = build_qualified_name(node, namespace)
+      matches = node.is_a?(Prism::ClassNode) && qualified == owner ? [node] : []
+
+      body_children = (node.body&.child_nodes || []).compact
+      matches + body_children.flat_map { |child| collect_class_nodes(child, owner, qualified.split("::")) }
+    end
+
+    def self.build_qualified_name(node, namespace)
+      const = node.constant_path
+      return const_path_to_string(const) if namespace.empty? || absolute_constant?(const)
+
+      name = const_path_to_string(const)
+      return name if already_qualified?(name, namespace)
+
+      "#{namespace.join('::')}::#{name}"
+    end
+
+    def self.absolute_constant?(const)
+      return false unless const.is_a?(Prism::ConstantPathNode)
+
+      current = const
+      current = current.parent while current.is_a?(Prism::ConstantPathNode)
+      current.nil?
+    end
+
+    def self.already_qualified?(name, namespace)
+      prefix = namespace.join("::")
+      name == prefix || name.start_with?("#{prefix}::")
+    end
+
+    def self.const_path_to_string(const)
+      case const
+      when Prism::ConstantReadNode then const.name.to_s
+      when Prism::ConstantPathNode then full_constant_path(const)
+      else const.to_s
+      end
+    end
+
+    def self.full_constant_path(node)
+      parts = []
+      current = node
+      while current.is_a?(Prism::ConstantPathNode)
+        parts.unshift(current.name.to_s)
+        current = current.parent
+      end
+      parts.unshift(current.name.to_s) if current.is_a?(Prism::ConstantReadNode)
+      parts.join("::")
+    end
+
+    private_class_method :find_class_bodies, :collect_class_nodes, :class_or_module?,
+                         :collect_within_class_or_module,
+                         :build_qualified_name, :absolute_constant?, :already_qualified?,
+                         :const_path_to_string, :full_constant_path
+
+    def initialize(action_name)
+      super()
+      @action_name = action_name
+      @events = []
+    end
+
+    attr_reader :events
+
+    def visit_call_node(node)
+      if node.name == :before_action && callback_applies?(node)
+        extract_callback_names(node).each do |name|
+          call = MethodCall.new(receiver: nil, method_name: name, line: node.location.start_line,
+                                callback: "before_action")
+          @events << { type: :add, call: call }
+        end
+      elsif node.name == :skip_before_action && callback_applies?(node)
+        extract_callback_names(node).each { |name| @events << { type: :skip, name: name } }
+      end
+      super
+    end
+
+    # Callbacks belong to the class they are declared in — do not descend into
+    # nested classes/modules or method bodies within the target class body.
+    def visit_class_node(_node); end
+    def visit_module_node(_node); end
+    def visit_singleton_class_node(_node); end
+    def visit_def_node(_node); end
+
+    private
+
+    def extract_callback_names(node)
+      return [] unless node.arguments
+
+      node.arguments.arguments.filter_map do |arg|
+        arg.value if arg.is_a?(Prism::SymbolNode)
+      end
+    end
+
+    def callback_applies?(node)
+      filter = find_scope_filter(node)
+      return true unless filter
+
+      key, value = filter
+      key == "only" ? action_in_list?(value) : !action_in_list?(value)
+    end
+
+    def find_scope_filter(node)
+      # Options arrive as a KeywordHashNode (`only: :show`) or a HashNode
+      # when written with explicit braces (`{ only: :show }`).
+      options = node.arguments&.arguments&.find do |a|
+        a.is_a?(Prism::KeywordHashNode) || a.is_a?(Prism::HashNode)
+      end
+      return nil unless options
+
+      assoc = scope_assoc(options)
+      assoc && [assoc.key.value, assoc.value]
+    end
+
+    def scope_assoc(keyword_hash)
+      keyword_hash.elements.find do |el|
+        el.is_a?(Prism::AssocNode) && el.key.is_a?(Prism::SymbolNode) && %w[only except].include?(el.key.value)
+      end
+    end
+
+    def action_in_list?(value_node)
+      case value_node
+      when Prism::ArrayNode
+        value_node.elements.any? { |el| action_name_matches?(el) }
+      else
+        action_name_matches?(value_node)
+      end
+    end
+
+    def action_name_matches?(node)
+      case node
+      when Prism::SymbolNode then node.value == @action_name
+      when Prism::StringNode then node.unescaped == @action_name
+      else false
+      end
+    end
+  end
+end