kaskd 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f251ae1063d05fd9ad9988102464e31b5f50908bcd47562b4c0797ed999efda0
+  data.tar.gz: 715b5710244662141b0ffa90cf1056e87ce1556cfeb5153313acf731090b07dc
+SHA512:
+  metadata.gz: 7f07e0c30b74aefeab1e1ed5f777d6f746169c149a459e5b92be5e29214c926a809612260fdcaf85c5a909f575552f5666ccd597588af114b318fb0049b497b5
+  data.tar.gz: 67374e08547105c3f47fb72a30b1beb216eb845d9c7044695ce600877e1c2992992c5b78a347d340f44156b15f09f7cf649659c80fad85affa874856175124f1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nildiert
+
+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,197 @@
+# kaskd
+
+Static analyzer for Ruby service dependency graphs and blast radius calculation.
+
+> **kaskd** = cascade — when a service changes, the ripple propagates.
+
+Kaskd scans your `app/services` and `packs/**/app/services` directories via static analysis, builds a full dependency graph, and answers two questions:
+
+1. **Which services are affected** if a given service changes? (blast radius)
+2. **Which test files should be run** as a result?
+
+Works with standard Rails layouts and [Packwerk](https://github.com/Shopify/packwerk)-based monorepos.
+
+---
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "kaskd", github: "nildiert/kaskd"
+```
+
+Or for development/CI only:
+
+```ruby
+group :development, :test do
+  gem "kaskd", github: "nildiert/kaskd"
+end
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+---
+
+## Usage
+
+### Full dependency graph
+
+```ruby
+result = Kaskd.analyze
+result[:services]     # Hash<class_name => metadata>
+result[:total]        # Integer
+result[:generated_at] # ISO 8601 String
+```
+
+### Blast radius
+
+```ruby
+radius = Kaskd.blast_radius("My::PayrollService")
+
+# Control traversal depth (default: 8, nil = unlimited)
+radius = Kaskd.blast_radius("My::PayrollService", max_depth: 3)
+
+radius[:target]            # => "My::PayrollService"
+radius[:max_depth]         # => 3
+radius[:max_depth_reached] # => 2
+
+# Results grouped by depth level
+radius[:by_depth] # => {
+#   1 => [
+#     { class_name: "My::InvoiceService", depth: 1, via: "My::PayrollService",
+#       file: "app/services/my/invoice_service.rb",
+#       dependencies: ["My::PayrollService", "My::TaxService"], parent: nil },
+#   ],
+#   2 => [
+#     { class_name: "My::ReportService", depth: 2, via: "My::InvoiceService",
+#       file: "app/services/my/report_service.rb",
+#       dependencies: ["My::InvoiceService"], parent: nil },
+#   ],
+# }
+
+# Flat array sorted by depth then name
+radius[:affected] # => [
+#   { class_name: "My::InvoiceService", depth: 1, via: "My::PayrollService",
+#     file: "...", dependencies: [...], parent: nil },
+#   { class_name: "My::ReportService",  depth: 2, via: "My::InvoiceService",
+#     file: "...", dependencies: [...], parent: nil },
+# ]
+```
+
+### ASCII tree view
+
+```ruby
+# Convenience method — runs blast_radius and renders in one call
+puts Kaskd.render_tree("My::PayrollService")
+puts Kaskd.render_tree("My::PayrollService", max_depth: 3)
+
+# Or render from an existing blast radius result
+radius = Kaskd.blast_radius("My::PayrollService")
+puts Kaskd::TreeRenderer.render(radius)
+```
+
+Example output:
+
+```
+My::PayrollService
+├── My::InvoiceService  [depth 1]  app/services/my/invoice_service.rb  (deps: My::PayrollService, My::TaxService)
+│   ├── My::ExportService  [depth 2]  app/services/my/export_service.rb
+│   └── My::ReportService  [depth 2]  app/services/my/report_service.rb
+└── My::NotifierService  [depth 1]  app/services/my/notifier_service.rb
+    └── My::AuditService  [depth 2]  app/services/my/audit_service.rb
+```
+
+Each node shows: class name, depth (gray), file path (cyan), and direct dependencies (gray).
+
+### Related tests
+
+```ruby
+tests = Kaskd.related_tests("My::PayrollService")
+
+# Also accepts max_depth to match the blast radius scope
+tests = Kaskd.related_tests("My::PayrollService", max_depth: 3)
+
+tests[:test_files] # => [
+#   { path: "test/services/my/payroll_service_test.rb", class_name: "My::PayrollService" },
+#   { path: "test/services/my/invoice_service_test.rb", class_name: "My::InvoiceService" },
+# ]
+```
+
+### Lower-level API
+
+```ruby
+# 1. Analyze
+result = Kaskd::Analyzer.new(root: "/path/to/project").analyze
+
+# 2. Blast radius
+radius = Kaskd::BlastRadius.new(result[:services]).compute("My::PayrollService", max_depth: 4)
+
+# 3. Tree
+puts Kaskd::TreeRenderer.render(radius)
+
+# 4. Tests
+affected_classes = radius[:affected].map { |a| a[:class_name] } + ["My::PayrollService"]
+tests = Kaskd::TestFinder.new(root: "/path/to/project").find_for(affected_classes, result[:services])
+```
+
+---
+
+## Configuration
+
+```ruby
+Kaskd.configure do |c|
+  # Override service glob patterns
+  c.service_globs = [
+    "app/services/**/*.rb",
+    "packs/**/app/services/**/*.rb",
+  ]
+
+  # Override test glob patterns
+  c.test_globs = [
+    "test/**/*_test.rb",
+    "spec/**/*_spec.rb",
+    "packs/**/test/**/*_test.rb",
+    "packs/**/spec/**/*_spec.rb",
+  ]
+end
+```
+
+---
+
+## How it works
+
+### Analyzer — two-pass static analysis
+
+**Pass 1** — collect all class names and metadata (file path, pack, parent class, description from preceding comment block). Handles module-nested classes (`module Foo / class Bar` → `Foo::Bar`).
+
+**Pass 2** — for each file, scan for references to known class names. The intersection of identifiers in the file with the set of known classes gives the dependency list.
+
+### BlastRadius — BFS on the reverse graph
+
+A reverse index maps each class to the services that depend on it. BFS traversal computes the full transitive blast radius with predecessor tracking (`via` field) for path reconstruction. Results are grouped by depth level in `by_depth` and also returned as a flat `affected` array.
+
+### TreeRenderer — ASCII tree from the `via` chain
+
+Reconstructs the parent-child relationships from the `via` field of each entry and renders them as an indented ASCII tree using `├──` / `└──` connectors.
+
+### TestFinder — two-heuristic matching
+
+1. **Naming convention** — strip `_test`/`_spec` suffix from the filename and match against the service name map.
+2. **Content scan** — search the test file body for direct references to any of the target class names.
+
+---
+
+## Used by
+
+- [`service_graph_dev`](https://github.com/nildiert/service_graph_dev) — mountable Rails engine that visualizes the dependency graph interactively. Uses `kaskd` as its analysis core via git submodule.
+
+---
+
+## License
+
+MIT

data/lib/kaskd/analyzer.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Kaskd
+  # Analyzes dependencies between Ruby service classes via two-pass static analysis.
+  #
+  # Pass 1 — collect class names and metadata from all matched files.
+  # Pass 2 — detect cross-references between known classes.
+  #
+  # Usage:
+  #   result = Kaskd::Analyzer.new.analyze
+  #   result[:services]     # => Hash<class_name => metadata>
+  #   result[:total]        # => Integer
+  #   result[:generated_at] # => ISO 8601 String
+  class Analyzer
+    # @param root [String, nil] project root directory. Defaults to Dir.pwd.
+    # @param globs [Array<String>, nil] override service glob patterns.
+    def initialize(root: nil, globs: nil)
+      @root  = root || Dir.pwd
+      @globs = globs || Kaskd.configuration.service_globs
+    end
+
+    # Run the full two-pass analysis.
+    # @return [Hash]
+    def analyze
+      all_files     = resolve_files
+      services      = {}
+      file_contents = {}
+
+      # Pass 1: collect class names and metadata
+      all_files.each do |path|
+        content = read_file(path)
+        file_contents[path] = content
+        class_name = extract_class_name(content)
+        next unless class_name
+
+        services[class_name] = {
+          class_name:   class_name,
+          file:         relative_path(path),
+          pack:         extract_pack(path),
+          description:  extract_description(content),
+          parent:       extract_parent(content),
+          dependencies: [],
+        }
+      end
+
+      known_classes = services.keys.to_set
+
+      # Pass 2: detect dependencies by intersecting references with known classes
+      all_files.each do |path|
+        content    = file_contents[path]
+        class_name = extract_class_name(content)
+        next unless class_name && services[class_name]
+
+        services[class_name][:dependencies] = extract_dependencies(content, known_classes, class_name)
+      end
+
+      {
+        services:     services,
+        generated_at: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        total:        services.size,
+      }
+    end
+
+    private
+
+    def resolve_files
+      @globs
+        .flat_map { |pattern| Dir.glob(File.join(@root, pattern)) }
+        .uniq
+    end
+
+    def read_file(path)
+      File.read(path, encoding: "utf-8", invalid: :replace, undef: :replace)
+    end
+
+    def relative_path(path)
+      path.delete_prefix("#{@root}/")
+    end
+
+    # Extracts the pack name from the file path.
+    #   packs/talent/evaluation_process/... => "talent/evaluation_process"
+    #   app/services/...                    => "app"
+    def extract_pack(path)
+      rel = relative_path(path)
+      return "app" unless rel.start_with?("packs/")
+
+      parts = rel.split("/")
+      parts[1..2].join("/")
+    end
+
+    # Extracts the fully qualified class name, handling module wrappers.
+    # E.g.: module Foo / class Bar => "Foo::Bar"
+    def extract_class_name(content)
+      modules = []
+      content.each_line do |line|
+        stripped = line.strip
+        if (m = stripped.match(/\Amodule\s+([\w:]+)/))
+          modules << m[1]
+        elsif (m = stripped.match(/\Aclass\s+([\w:]+)/))
+          return build_qualified_name(modules, m[1])
+        end
+      end
+      nil
+    end
+
+    def extract_parent(content)
+      content.each_line do |line|
+        stripped = line.strip
+        if (m = stripped.match(/\Aclass\s+[\w:]+\s*<\s*([\w:]+(?:::\w+)*)/))
+          return m[1]
+        end
+      end
+      nil
+    end
+
+    def build_qualified_name(modules, class_part)
+      return class_part if modules.empty?
+
+      full_module = modules.join("::")
+      class_part.start_with?("#{full_module}::") ? class_part : "#{full_module}::#{class_part}"
+    end
+
+    # Extracts description from the comment block preceding the class declaration.
+    # Ignores Sorbet/Rubocop directives and YARD tags like @param/@return.
+    def extract_description(content)
+      lines          = content.lines
+      class_line_idx = lines.find_index { |l| l.strip.match?(/\Aclass\s/) }
+      return "" unless class_line_idx
+
+      comments = []
+      (class_line_idx - 1).downto(0) do |i|
+        line = lines[i].strip
+        break if line.empty? && comments.any?
+        next  if line.empty?
+
+        if line.start_with?("#")
+          stripped = line.sub(/^#+\s?/, "").strip
+          next if stripped.start_with?("@")
+          next if stripped.match?(/\A(typed:|frozen_string_literal)/)
+
+          comments.unshift(stripped) unless stripped.empty?
+        else
+          break
+        end
+      end
+
+      comments.reject(&:empty?).join(" ").then { |s| s.empty? ? "" : s }
+    end
+
+    # Detects dependencies by finding references to known classes in the file content.
+    def extract_dependencies(content, known_classes, self_class)
+      references = content.scan(/\b([A-Z][A-Za-z0-9]*(?:::[A-Z][A-Za-z0-9]*)*)/).flatten.to_set
+      (references & known_classes - Set[self_class]).to_a.sort
+    end
+  end
+end

data/lib/kaskd/blast_radius.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Kaskd
+  # Computes the blast radius of a service change via BFS on the reverse dependency graph.
+  #
+  # Given a target service class name, it finds every other service that depends on it
+  # (directly or transitively) and groups results by depth level.
+  #
+  # Usage:
+  #   result = Kaskd::Analyzer.new.analyze
+  #   radius = Kaskd::BlastRadius.new(result[:services]).compute("My::ServiceClass", max_depth: 3)
+  #
+  #   radius[:target]  # => "My::ServiceClass"
+  #   radius[:by_depth] # => {
+  #     1 => [{ class_name: "A", via: "My::ServiceClass", file: "...", dependencies: [...], parent: "..." }, ...],
+  #     2 => [{ class_name: "B", via: "A",                file: "...", dependencies: [...], parent: nil  }, ...],
+  #   }
+  #   radius[:affected] # => flat array of all entries, sorted by depth then name
+  #   radius[:max_depth_reached] # => Integer — deepest level found (≤ max_depth)
+  class BlastRadius
+    DEFAULT_MAX_DEPTH = 8
+
+    # @param services [Hash] output of Kaskd::Analyzer#analyze — services keyed by class name.
+    def initialize(services)
+      @services = services
+    end
+
+    # Run BFS from the target service through the reverse dependency index.
+    #
+    # @param target    [String]  fully-qualified class name of the modified service.
+    # @param max_depth [Integer] maximum traversal depth (default: 6). nil = unlimited.
+    # @return [Hash]
+    def compute(target, max_depth: DEFAULT_MAX_DEPTH)
+      reverse_index = build_reverse_index
+
+      queue   = [[target, 0]]
+      visited = { target => { depth: 0, via: nil } }
+
+      while queue.any?
+        svc, depth = queue.shift
+        next if max_depth && depth >= max_depth
+
+        (reverse_index[svc] || []).each do |caller_svc|
+          next if visited.key?(caller_svc)
+
+          visited[caller_svc] = { depth: depth + 1, via: svc }
+          queue << [caller_svc, depth + 1]
+        end
+      end
+
+      entries = visited
+        .reject { |name, _| name == target }
+        .sort_by { |name, meta| [meta[:depth], name] }
+        .map do |name, meta|
+          {
+            class_name:   name,
+            depth:        meta[:depth],
+            via:          meta[:via],
+            file:         @services.dig(name, :file),
+            dependencies: @services.dig(name, :dependencies) || [],
+            parent:       @services.dig(name, :parent),
+          }
+        end
+
+      by_depth = entries.group_by { |e| e[:depth] }
+
+      {
+        target:           target,
+        max_depth:        max_depth,
+        max_depth_reached: entries.map { |e| e[:depth] }.max || 0,
+        by_depth:         by_depth,
+        affected:         entries,
+      }
+    end
+
+    private
+
+    # Builds a reverse index: given a service X, who depends on X?
+    # reverse_index["X"] => ["A", "B", ...]
+    def build_reverse_index
+      index = Hash.new { |h, k| h[k] = [] }
+      @services.each do |name, meta|
+        meta[:dependencies].each do |dep|
+          index[dep] << name
+        end
+      end
+      index
+    end
+  end
+end

data/lib/kaskd/configuration.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Kaskd
+  # Holds gem-wide configuration.
+  # Use Kaskd.configure { |c| c.service_globs = [...] } to override defaults.
+  class Configuration
+    # Glob patterns used to discover service files.
+    # Override if your project uses a non-standard layout.
+    attr_accessor :service_globs
+
+    # Glob patterns used to discover test files (Minitest and RSpec).
+    attr_accessor :test_globs
+
+    def initialize
+      @service_globs = [
+        "app/services/**/*.rb",
+        "packs/**/app/services/**/*.rb",
+      ]
+
+      @test_globs = [
+        "test/**/*_test.rb",
+        "spec/**/*_spec.rb",
+        "packs/**/test/**/*_test.rb",
+        "packs/**/spec/**/*_spec.rb",
+      ]
+    end
+  end
+end

data/lib/kaskd/test_finder.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Kaskd
+  # Finds test files related to a set of service class names.
+  #
+  # Strategy:
+  #   1. Scan all test files matched by the configured globs.
+  #   2. For each test file, extract the class name it likely tests using two heuristics:
+  #      a. Naming convention: strip _test / _spec suffix from the filename and map it
+  #         to a Ruby constant (e.g. my_service_test.rb => MyService).
+  #      b. Content scan: look for references to any of the target class names inside
+  #         the file body.
+  #   3. Return a deduplicated list of { path:, class_name: } for every match.
+  #
+  # Usage:
+  #   result  = Kaskd::Analyzer.new.analyze
+  #   radius  = Kaskd::BlastRadius.new(result[:services]).compute("My::ServiceClass")
+  #   targets = radius[:affected].map { |a| a[:class_name] } + ["My::ServiceClass"]
+  #   tests   = Kaskd::TestFinder.new.find_for(targets, result[:services])
+  #   tests[:test_files]  # => [{ path: "test/...", class_name: "My::ServiceClass" }, ...]
+  class TestFinder
+    # @param root  [String, nil] project root. Defaults to Dir.pwd.
+    # @param globs [Array<String>, nil] override test glob patterns.
+    def initialize(root: nil, globs: nil)
+      @root  = root || Dir.pwd
+      @globs = globs || Kaskd.configuration.test_globs
+    end
+
+    # @param target_classes [Array<String>] fully-qualified class names to search for.
+    # @param services       [Hash] services map from Kaskd::Analyzer#analyze (used for
+    #                              quick filename-to-class lookups).
+    # @return [Hash]
+    def find_for(target_classes, services = {})
+      target_set  = target_classes.to_set
+      all_tests   = resolve_test_files
+      found       = {}
+
+      # Build a reverse map: snake_case base name => class name (from services)
+      # so naming-convention matching can cover namespaced classes too.
+      name_map = build_name_map(services)
+
+      all_tests.each do |path|
+        rel     = relative_path(path)
+        matched = match_by_convention(rel, target_set, name_map)
+        matched ||= match_by_content(path, target_set)
+        next unless matched
+
+        # A test file may cover multiple targets — accumulate all
+        Array(matched).each do |class_name|
+          key = "#{rel}::#{class_name}"
+          found[key] = { path: rel, class_name: class_name }
+        end
+      end
+
+      {
+        target_classes: target_classes,
+        test_files:     found.values.sort_by { |t| [t[:path], t[:class_name]] },
+      }
+    end
+
+    private
+
+    def resolve_test_files
+      @globs
+        .flat_map { |pattern| Dir.glob(File.join(@root, pattern)) }
+        .uniq
+    end
+
+    def relative_path(path)
+      path.delete_prefix("#{@root}/")
+    end
+
+    # Builds a map from underscore base name to fully-qualified class names.
+    # e.g. "my_service" => ["My::ServiceClass"] where the file is my_service.rb
+    def build_name_map(services)
+      map = Hash.new { |h, k| h[k] = [] }
+      services.each do |class_name, meta|
+        base = File.basename(meta[:file].to_s, ".rb")
+        map[base] << class_name
+      end
+      map
+    end
+
+    # Heuristic 1 — naming convention (Rails-style path guard).
+    #
+    # Rails convention: the test file path mirrors the class namespace.
+    #   Talent::EmployeeEvaluations::Restore
+    #     => expected path fragment: "talent/employee_evaluations/restore"
+    #
+    # A test file matches a candidate class only when the full underscored
+    # namespace path (e.g. "talent/employee_evaluations/restore") is a
+    # substring of the test's relative path (ignoring the _test/_spec suffix).
+    # This is the same guard Rails autoload uses and eliminates false positives
+    # from generic leaf names like "restore" or "create" appearing in unrelated
+    # packs.
+    def match_by_convention(rel_path, target_set, name_map)
+      base = File.basename(rel_path, ".rb")
+                 .delete_suffix("_test")
+                 .delete_suffix("_spec")
+
+      # Normalise the test path for substring matching (drop extension suffix).
+      normalised_path = File.join(File.dirname(rel_path), base)
+
+      candidates = name_map[base] || []
+      matched    = candidates.select do |class_name|
+        next false unless target_set.include?(class_name)
+
+        # Build the expected path fragment from the fully-qualified class name.
+        expected_fragment = class_name.split("::").map { |p| underscore(p) }.join("/")
+        normalised_path.include?(expected_fragment)
+      end
+
+      matched.empty? ? nil : matched
+    end
+
+    # Minimal underscore — converts CamelCase to snake_case.
+    # e.g. "EmployeeEvaluations" => "employee_evaluations"
+    def underscore(str)
+      str
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .downcase
+    end
+
+    # Heuristic 2 — content scan.
+    # Read the file and look for direct references to any of the target class names.
+    # Returns matched class names or nil.
+    def match_by_content(path, target_set)
+      content = File.read(path, encoding: "utf-8", invalid: :replace, undef: :replace)
+      matched = target_set.select { |class_name| content.include?(class_name) }
+      matched.empty? ? nil : matched.to_a
+    rescue Errno::ENOENT, Errno::EACCES
+      nil
+    end
+  end
+end

data/lib/kaskd/tree_renderer.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Kaskd
+  # Renders a blast radius result as an ASCII tree.
+  #
+  # Usage:
+  #   radius = Kaskd.blast_radius("My::ServiceClass", root: Rails.root.to_s)
+  #   puts Kaskd::TreeRenderer.render(radius)
+  #
+  # Output example:
+  #   My::ServiceClass
+  #   ├── My::InvoiceService  [depth 1]  app/services/my/invoice_service.rb
+  #   │   ├── My::ReportService  [depth 2]  app/services/my/report_service.rb
+  #   │   └── My::ExportService  [depth 2]  app/services/my/export_service.rb
+  #   └── My::NotifierService  [depth 1]  app/services/my/notifier_service.rb
+  #       └── My::AuditService  [depth 2]  app/services/my/audit_service.rb
+  #
+  # Also available as a convenience method:
+  #   Kaskd.render_tree("My::ServiceClass", root: Rails.root.to_s)
+  class TreeRenderer
+    BRANCH = "├── "
+    LAST   = "└── "
+    PIPE   = "│   "
+    SPACE  = "    "
+
+    # @param radius [Hash] output of Kaskd::BlastRadius#compute or Kaskd.blast_radius
+    # @param io     [IO]   output target (default: returns String)
+    # @return [String]
+    def self.render(radius)
+      new(radius).render
+    end
+
+    def initialize(radius)
+      @target   = radius[:target]
+      @affected = radius[:affected]
+    end
+
+    def render
+      # Build adjacency: parent -> [children] using the :via field
+      children = Hash.new { |h, k| h[k] = [] }
+      @affected.each { |entry| children[entry[:via]] << entry }
+
+      # Sort each child list by class_name for deterministic output
+      children.each_value { |list| list.sort_by! { |e| e[:class_name] } }
+
+      lines = []
+      lines << @target
+      render_children(children[@target], children, "", lines)
+      lines.join("\n")
+    end
+
+    private
+
+    def render_children(nodes, children_map, prefix, lines)
+      return if nodes.nil? || nodes.empty?
+
+      nodes.each_with_index do |node, idx|
+        last = idx == nodes.size - 1
+
+        connector   = last ? LAST : BRANCH
+        child_prefix = prefix + (last ? SPACE : PIPE)
+
+        label = format_node(node)
+        lines << "#{prefix}#{connector}#{label}"
+
+        render_children(children_map[node[:class_name]], children_map, child_prefix, lines)
+      end
+    end
+
+    def format_node(node)
+      parts = [node[:class_name]]
+      parts << "\e[2m[depth #{node[:depth]}]\e[0m"
+      parts << "\e[36m#{node[:file]}\e[0m" if node[:file]
+      unless node[:dependencies].nil? || node[:dependencies].empty?
+        deps = node[:dependencies].join(", ")
+        parts << "\e[2m(deps: #{deps})\e[0m"
+      end
+      parts.join("  ")
+    end
+  end
+end

data/lib/kaskd/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Kaskd
+  VERSION = "0.1.0"
+end

data/lib/kaskd.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "kaskd/version"
+require_relative "kaskd/analyzer"
+require_relative "kaskd/blast_radius"
+require_relative "kaskd/test_finder"
+require_relative "kaskd/configuration"
+require_relative "kaskd/tree_renderer"
+
+module Kaskd
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    # Convenience entry point: analyze all services and return the full graph.
+    # Returns: { services: Hash, generated_at: String, total: Integer }
+    def analyze(root: nil)
+      Analyzer.new(root: root).analyze
+    end
+
+    # Compute blast radius for a given service class name.
+    #
+    # @param class_name [String] fully-qualified class name of the modified service.
+    # @param root       [String, nil] project root. Defaults to Dir.pwd.
+    # @param max_depth  [Integer, nil] max BFS traversal depth (default: 6). nil = unlimited.
+    #
+    # Returns:
+    #   {
+    #     target:            "My::ServiceClass",
+    #     max_depth:         3,
+    #     max_depth_reached: 2,
+    #     by_depth: {
+    #       1 => [{ class_name:, via:, file: }, ...],
+    #       2 => [{ class_name:, via:, file: }, ...],
+    #     },
+    #     affected: [ flat array sorted by depth then name ],
+    #   }
+    def blast_radius(class_name, root: nil, max_depth: BlastRadius::DEFAULT_MAX_DEPTH)
+      result = analyze(root: root)
+      BlastRadius.new(result[:services]).compute(class_name, max_depth: max_depth)
+    end
+
+    # Find test files related to a service and its blast radius.
+    # Returns: { target_classes:, test_files: Array<{ path:, class_name: }> }
+    def related_tests(class_name, root: nil, max_depth: BlastRadius::DEFAULT_MAX_DEPTH)
+      result   = analyze(root: root)
+      radius   = BlastRadius.new(result[:services]).compute(class_name, max_depth: max_depth)
+      affected = radius[:affected].map { |a| a[:class_name] } + [class_name]
+      TestFinder.new(root: root).find_for(affected, result[:services])
+    end
+
+    # Render the blast radius of a service as an ASCII tree.
+    # Combines blast_radius + TreeRenderer in one call.
+    #
+    # Example output:
+    #   My::ServiceClass
+    #   ├── My::InvoiceService  [depth 1]  app/services/my/invoice_service.rb
+    #   │   └── My::ReportService  [depth 2]  app/services/my/report_service.rb
+    #   └── My::NotifierService  [depth 1]  app/services/my/notifier_service.rb
+    #
+    # @param class_name [String]
+    # @param root       [String, nil]
+    # @param max_depth  [Integer, nil]
+    # @return [String]
+    def render_tree(class_name, root: nil, max_depth: BlastRadius::DEFAULT_MAX_DEPTH)
+      radius = blast_radius(class_name, root: root, max_depth: max_depth)
+      TreeRenderer.render(radius)
+    end
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: kaskd
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- nildiert
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Kaskd scans Ruby service files via static analysis, builds a dependency graph,
+  and answers two questions: (1) which services are affected if a given service changes
+  (blast radius), and (2) which test files should be run as a result.
+  Works with standard Rails layouts and Packwerk-based monorepos.
+email: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/kaskd.rb
+- lib/kaskd/analyzer.rb
+- lib/kaskd/blast_radius.rb
+- lib/kaskd/configuration.rb
+- lib/kaskd/test_finder.rb
+- lib/kaskd/tree_renderer.rb
+- lib/kaskd/version.rb
+homepage: https://github.com/nildiert/kaskd
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/nildiert/kaskd
+  source_code_uri: https://github.com/nildiert/kaskd
+  changelog_uri: https://github.com/nildiert/kaskd/releases
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Static analyzer for Ruby service dependency graphs and blast radius calculation.
+test_files: []