archsight 0.2.4 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3915931a74e1a99c1916113fb6a4002d35384aa3c7d40858c62ec7923b42bf83
-  data.tar.gz: eb585529128c07c269dec0bdea9bd48199d0fc55fc23753d52f53d4de4d87f0a
+  metadata.gz: e0c195f805808234600e39cd6a3f80cf2ee105c9aaec92d29aca78795f634c4e
+  data.tar.gz: c0ecdcd65b22cd03567fc3e28a03b5b7eb0607114ba5e5950e05b744b3dd7a5f
 SHA512:
-  metadata.gz: 9ebe5f64aab31b80c4d8f39280312850ab6c0f131be1fdcfc24355dc219506b1d2ffa597549dc2e3e453ab086b2c14bc4dd685bd850c7d72464845889b2e46f9
-  data.tar.gz: 267d143d4ecfc7e0d40580dec15fc0c208d51fcc4ebd2b65a3b81565d9a6613df7bf1b3e8da9cae0d7ccaa0505d93fe02bdba2729d624decf80314d3dc930815
+  metadata.gz: 5380e24d80507b0bb223f9351e5e0efc18cd3d9119dd0c34ee810404992da87714e7d444fd7a3d70f8dfa4dada77edb989018d4b21914100fb1782d5df4f8177
+  data.tar.gz: b88868e7b3656eb45920b92a7eed4ea7ae453bacff1b41a659b95bea52210d7c789f05184db51a3de9590b42f4a854b33a64f22f42fce4fc40519a8a18b89e99

data/lib/archsight/cli.rb

@@ -3,6 +3,70 @@
 require "thor"
 
 module Archsight
+  class ModuleCLI < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "graph PATH", "Print module dependency graph (DOT) for a repository to stdout"
+    option :language, aliases: "-l", type: :string, default: "auto",
+                      desc: "Language: go, python, java, or auto (default)"
+    option :ranksep, type: :numeric, default: 0.6, desc: "Horizontal gap between rank columns"
+    option :nodesep, type: :numeric, default: 0.15, desc: "Vertical gap between nodes"
+    def graph(path)
+      path = File.expand_path(path)
+      unless File.directory?(path)
+        warn "Error: not a directory: #{path}"
+        exit 1
+      end
+
+      load_handlers
+      handler_classes = resolve_handler(path, options[:language])
+      if handler_classes.empty?
+        warn "Could not detect language for #{path} — use --language go|python|java"
+        exit 1
+      end
+
+      require "archsight/import/progress"
+      stub = Struct.new(:name, :annotations, :path_ref).new("module-graph", {}, nil)
+      any_output = false
+      handler_classes.each do |handler_class|
+        progress = Archsight::Import::Progress.new(output: $stderr)
+        handler = handler_class.new(stub, database: nil, resources_dir: Dir.tmpdir,
+                                          progress: progress)
+        dot = handler.dot_graph(path: path, ranksep: options[:ranksep],
+                                nodesep: options[:nodesep])
+        next unless dot
+
+        puts "# #{handler_class.language_name} modules" if handler_classes.size > 1
+        puts dot
+        any_output = true
+      end
+      return if any_output
+
+      warn "No modules found in #{path}"
+      exit 1
+    end
+
+    private
+
+    def load_handlers
+      handlers_dir = File.expand_path("import/handlers", __dir__)
+      Dir.glob(File.join(handlers_dir, "*.rb")).each { |f| require f }
+    end
+
+    def resolve_handler(path, language)
+      require "archsight/import/registry"
+      if language == "auto" || language.nil?
+        Archsight::Import::Registry.handlers_for(path)
+      else
+        handler = Archsight::Import::Registry.handler_for_language(language)
+        warn "Unknown language: #{language}. Use go, python, or java." unless handler
+        [handler].compact
+      end
+    end
+  end
+
   class CLI < Thor
     def self.exit_on_failure?
       true
@@ -175,6 +239,9 @@ module Archsight
       puts "archsight #{Archsight::VERSION}"
     end
 
+    desc "module SUBCOMMAND", "Module analysis commands (e.g. module graph PATH)"
+    subcommand "module", ModuleCLI
+
     default_task :version
 
     private

data/lib/archsight/graph.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "stringio"
+
 module Archsight
   # Graphvis implements a graphviz abstraction
   class Graphvis
@@ -54,6 +56,14 @@ module Archsight
       val =~ /^<.*>$/ ? "<#{val}>" : val.inspect
     end
 
+    def defaults(type, attrs = {})
+      @file.print "  #{type} ["
+      attrs.each do |k, v|
+        @file.print " #{k.to_s.inspect} = #{value v}"
+      end
+      @file.puts " ];"
+    end
+
     def same_rank
       @file.puts "  { rank = same; "
       yield(self)

data/lib/archsight/import/executor.rb

@@ -305,6 +305,13 @@ class Archsight::Import::Executor
         slot_progress = @concurrent_progress.acquire_slot(imp.name)
 
         begin
+          # Skip work queued before the interrupt — let already-running imports finish
+          if @interrupted
+            @mutex.synchronize { @executed_this_run.delete(imp.name) }
+            slot_progress.complete("Skipped")
+            next
+          end
+
           result = execute_single_import(imp, slot_progress)
           if result == :cached
             slot_progress.complete("Cached")
@@ -313,11 +320,12 @@ class Archsight::Import::Executor
             slot_progress.complete("Done")
           end
         rescue StandardError => e
+          detail = [e.message, e.backtrace.first].compact.join(" @ ")
           @mutex.synchronize do
-            @failed_imports[imp.name] = e.message
-            @first_error ||= { name: imp.name, message: e.message }
+            @failed_imports[imp.name] = detail
+            @first_error ||= { name: imp.name, message: detail }
           end
-          slot_progress.error(e.message)
+          slot_progress.error(detail)
         ensure
           # Update overall progress and release slot
           @concurrent_progress.increment_completed

data/lib/archsight/import/handlers/cpp_grapher.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "find"
+require_relative "grapher"
+require_relative "../registry"
+
+# CppGrapher — analyses a C/C++ repository and generates a GraphViz DOT graph
+# of its directory/module structure, stored as architecture/cpp/modules on the
+# TechnologyArtifact.
+#
+# C/C++ has no formal module system, so directory structure is the de facto
+# module boundary. Quoted #include "..." statements express local dependencies;
+# angled #include <...> are system/external headers and are ignored.
+#
+# Supports single-project and multi-project (CMake add_subdirectory) layouts.
+# Pure static regex analysis — no compiler or CMake required.
+#
+# File-to-package mapping:
+#   src/engine/core.cpp   → project/engine/core → capped → project/engine
+#   include/engine/core.h → project/engine/core → capped → project/engine
+#   src/renderer.cpp      → project/renderer (depth 1, not capped)
+#   main.cpp              → dep extraction skipped (entry point)
+#
+# Configuration:
+#   import/config/path    - Path to the C/C++ repository root
+#   import/config/ranksep - Horizontal gap between rank columns (default: 0.6)
+#   import/config/nodesep - Vertical gap between nodes in a column (default: 0.15)
+class Archsight::Import::Handlers::CppGrapher < Archsight::Import::Handlers::Grapher
+  def self.language_name = "cpp"
+
+  def self.applicable?(path)
+    File.exist?(File.join(path, "CMakeLists.txt")) ||
+      File.exist?(File.join(path, "meson.build")) ||
+      Dir.glob(File.join(path, "*.{cpp,c,cc,cxx,h,hpp}")).any? ||
+      Dir.glob(File.join(path, "src/*.{cpp,c,cc,cxx}")).any? ||
+      Dir.glob(File.join(path, "include/*.{h,hpp,hh}")).any?
+  end
+
+  def wrap_single_module?
+    true
+  end
+
+  SKIP_DIRS = %w[build .build out .git third_party extern external vendor test tests
+                 googletest gtest CMakeFiles cmake .cache _deps generated].freeze
+  MAX_PKG_DEPTH = 2
+  SOURCE_EXTS = %w[.cpp .c .cc .cxx .h .hpp .hh .hxx].freeze
+  SRC_PREFIXES = %w[src/ include/ lib/ source/].freeze
+  INCLUDE_RE = /^\s*#\s*include\s+"([^"]+)"/
+  ENTRY_FILES = %w[main.cpp main.c Main.cpp Main.c].freeze
+  EXT_RE = /\.(cpp|c|cc|cxx|hpp|h|hh|hxx)\z/
+
+  private
+
+  # ── Module discovery ─────────────────────────────────────────────────────
+
+  def discover_modules(repo_root)
+    [[".", cmake_project_name(repo_root) || File.basename(repo_root)]]
+  end
+
+  def cmake_project_name(dir)
+    cmake = File.join(dir, "CMakeLists.txt")
+    return nil unless File.exist?(cmake)
+
+    content = File.read(cmake, encoding: "utf-8")
+    m = content.match(/^\s*project\s*\(\s*([^\s)]+)/i)
+    return nil unless m
+
+    m[1].gsub(/[^a-zA-Z0-9]/, "_").downcase
+  rescue StandardError
+    nil
+  end
+
+  # ── Package collection ────────────────────────────────────────────────────
+
+  def collect_packages(repo_root, modules, _prefix)
+    all_pkgs = {}
+    file_registry = build_file_registry(repo_root, modules)
+    scan_all_sources(repo_root, modules, file_registry, all_pkgs)
+    pkg_set = all_pkgs.keys.to_set
+    all_pkgs.each_value { |deps| deps.select! { |d| pkg_set.include?(d) } }
+    all_pkgs
+  end
+
+  def build_file_registry(repo_root, modules)
+    file_registry = {}
+    modules.each do |rel_dir, mod_name|
+      mod_dir = rel_dir == "." ? repo_root : File.join(repo_root, rel_dir)
+      register_files(mod_dir, mod_name, file_registry)
+    end
+    file_registry
+  end
+
+  def scan_all_sources(repo_root, modules, file_registry, all_pkgs)
+    modules.each do |rel_dir, mod_name|
+      mod_dir = rel_dir == "." ? repo_root : File.join(repo_root, rel_dir)
+      scan_sources(mod_dir, mod_name, file_registry, all_pkgs)
+    end
+  end
+
+  # ── File registry ─────────────────────────────────────────────────────────
+
+  # Registers multiple lookup keys per file so that both full-path includes
+  # (#include "engine/core.h") and short-form includes (#include "core.h")
+  # resolve to the correct package. First registration wins to avoid ambiguity
+  # when the same basename appears in multiple directories.
+  def register_files(mod_dir, mod_name, file_registry)
+    Find.find(mod_dir) do |path|
+      if File.directory?(path)
+        Find.prune if SKIP_DIRS.include?(File.basename(path))
+        next
+      end
+      next unless SOURCE_EXTS.include?(File.extname(path))
+
+      pkg = cap_depth(file_to_pkg(path, mod_dir, mod_name), mod_name)
+      rel_parts = path.delete_prefix("#{mod_dir}/").split("/")
+      rel_parts.length.times do |i|
+        file_registry[rel_parts[i..].join("/")] ||= pkg
+      end
+    end
+  end
+
+  # ── Source scanning ───────────────────────────────────────────────────────
+
+  def scan_sources(mod_dir, mod_name, file_registry, all_pkgs)
+    Find.find(mod_dir) do |path|
+      if File.directory?(path)
+        Find.prune if SKIP_DIRS.include?(File.basename(path))
+        next
+      end
+      next unless SOURCE_EXTS.include?(File.extname(path))
+
+      pkg = cap_depth(file_to_pkg(path, mod_dir, mod_name), mod_name)
+      all_pkgs[pkg] ||= []
+
+      # main.cpp / main.c are entry points — skipping their deps avoids a
+      # hub-spoke pattern where every module fans out from the invisible root.
+      next if ENTRY_FILES.include?(File.basename(path))
+
+      extract_includes(path, file_registry).each do |dep|
+        next if dep == pkg || all_pkgs[pkg].include?(dep)
+
+        all_pkgs[pkg] << dep
+      end
+    end
+  end
+
+  def extract_includes(path, file_registry)
+    deps = []
+    File.foreach(path, encoding: "utf-8") do |line|
+      m = line.match(INCLUDE_RE)
+      next unless m
+
+      dep = file_registry[m[1]]
+      deps << dep if dep
+    end
+    deps.uniq
+  rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError, ArgumentError
+    []
+  end
+
+  # ── Package path helpers ──────────────────────────────────────────────────
+
+  # Maps a source/header file to its package path. Standard source directory
+  # prefixes (src/, include/, lib/, source/) are stripped so that files in
+  # separate src/ and include/ trees map to the same package hierarchy.
+  def file_to_pkg(abs_path, mod_dir, mod_name)
+    rel = abs_path.delete_prefix("#{mod_dir}/").sub(EXT_RE, "")
+    SRC_PREFIXES.each do |p|
+      if rel.start_with?(p)
+        rel = rel.delete_prefix(p)
+        break
+      end
+    end
+    return mod_name if rel.empty?
+    return rel if rel.start_with?("#{mod_name}/")
+
+    "#{mod_name}/#{rel}"
+  end
+
+  def cap_depth(pkg, mod_name)
+    return pkg if pkg != mod_name && !pkg.start_with?("#{mod_name}/")
+
+    suffix = pkg.delete_prefix("#{mod_name}/")
+    return mod_name if suffix == pkg
+
+    parts = suffix.split("/")
+    return pkg if parts.length <= MAX_PKG_DEPTH - 1
+
+    "#{mod_name}/#{parts.first(MAX_PKG_DEPTH - 1).join("/")}"
+  end
+end
+
+Archsight::Import::Registry.register("cpp-grapher", Archsight::Import::Handlers::CppGrapher)

data/lib/archsight/import/handlers/crystal_grapher.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require_relative "grapher"
+require_relative "../registry"
+
+# CrystalGrapher — analyses a Crystal repository and generates a GraphViz DOT
+# graph of its shard/module structure, stored as architecture/crystal/modules
+# on the TechnologyArtifact.
+#
+# Supports single-shard projects (shard.yml at root) and multi-shard monorepos
+# (*/shard.yml). Uses pure static regex analysis of relative require statements
+# — no Crystal toolchain required.
+#
+# Only relative requires (./foo or ../bar) point to internal code; absolute
+# requires (require "shard_name") address installed shards in lib/ and are ignored.
+#
+# Configuration:
+#   import/config/path     - Path to the Crystal repository root
+#   import/config/ranksep  - Horizontal gap between rank columns (default: 0.6)
+#   import/config/nodesep  - Vertical gap between nodes in a column (default: 0.15)
+class Archsight::Import::Handlers::CrystalGrapher < Archsight::Import::Handlers::Grapher
+  def self.language_name = "crystal"
+
+  def self.applicable?(path)
+    File.exist?(File.join(path, "shard.yml")) ||
+      Dir.glob(File.join(path, "*/shard.yml")).any?
+  end
+
+  def wrap_single_module?
+    true
+  end
+
+  SKIP_DIRS = %w[lib spec .git bin .crystal tmp coverage].freeze
+
+  # MAX_PKG_DEPTH = 2: my_shard/feature is the natural depth for Crystal shards.
+  MAX_PKG_DEPTH = 2
+
+  # Only relative requires point to internal code; absolute requires are external shards.
+  REQUIRE_RE = %r{^\s*require\s+"(\.\.?/[^"]+)"}
+
+  private
+
+  # ── Module discovery ─────────────────────────────────────────────────────
+
+  def discover_modules(repo_root)
+    root_yml = File.join(repo_root, "shard.yml")
+
+    if File.exist?(root_yml) && parse_shard_name(root_yml)
+      mod_name = parse_shard_name(root_yml) ||
+                 src_top_dir(File.join(repo_root, "src")) ||
+                 File.basename(repo_root)
+      return [[".", mod_name]]
+    end
+
+    sub_shards = Dir.glob(File.join(repo_root, "*/shard.yml")).filter_map do |yml|
+      sub_dir = File.dirname(yml)
+      rel_dir = sub_dir.delete_prefix("#{repo_root}/")
+      next if SKIP_DIRS.any? { |d| rel_dir.split("/").include?(d) }
+
+      mod_name = parse_shard_name(yml) || File.basename(sub_dir)
+      [rel_dir, mod_name]
+    end
+
+    return sub_shards if sub_shards.any?
+
+    # Fallback: shard.yml exists but has no name
+    mod_name = src_top_dir(File.join(repo_root, "src")) || File.basename(repo_root)
+    [[".", mod_name]]
+  end
+
+  def parse_shard_name(shard_yml_path)
+    content = File.read(shard_yml_path, encoding: "utf-8")
+    content.match(/^name:\s*(\S+)/)[1]
+  rescue StandardError
+    nil
+  end
+
+  def src_top_dir(src_dir)
+    return nil unless Dir.exist?(src_dir)
+
+    dirs = Dir.children(src_dir).select { |e| File.directory?(File.join(src_dir, e)) }
+    dirs.length == 1 ? dirs.first : nil
+  end
+
+  # ── Package collection ────────────────────────────────────────────────────
+
+  def collect_packages(repo_root, modules, _prefix)
+    src_dirs = modules.each_with_object({}) do |(rel_dir, mod_name), h|
+      mod_dir = rel_dir == "." ? repo_root : File.join(repo_root, rel_dir)
+      src_dir = Dir.exist?(File.join(mod_dir, "src")) ? File.join(mod_dir, "src") : mod_dir
+      h[src_dir] = mod_name
+    end
+
+    all_pkgs = {}
+
+    src_dirs.each do |src_dir, mod_name|
+      scan_src_dir(src_dir, mod_name, src_dirs, all_pkgs)
+    end
+
+    # Drop deps that don't correspond to any scanned package (removes references to
+    # Crystal stdlib modules whose prefix happens to match an internal namespace).
+    pkg_set = all_pkgs.keys.to_set
+    all_pkgs.each_value { |deps| deps.select! { |d| pkg_set.include?(d) } }
+
+    all_pkgs
+  end
+
+  # ── Scanning ─────────────────────────────────────────────────────────────
+
+  def scan_src_dir(src_dir, mod_name, src_dirs, all_pkgs)
+    safe_glob(File.join(src_dir, "**", "*.cr")).each do |cr_file|
+      rel_parts = cr_file.delete_prefix("#{src_dir}/").split("/")
+      next if rel_parts.any? { |p| SKIP_DIRS.include?(p) }
+
+      pkg = cap_depth(file_to_pkg(cr_file, src_dir, mod_name), mod_name)
+      all_pkgs[pkg] ||= []
+
+      extract_deps(cr_file, src_dirs).each do |dep|
+        dep = cap_depth(dep, mod_name)
+        next if dep == pkg || all_pkgs[pkg].include?(dep)
+
+        all_pkgs[pkg] << dep
+      end
+    end
+  end
+
+  # ── Require extraction ────────────────────────────────────────────────────
+
+  def extract_deps(cr_file, src_dirs)
+    content = File.read(cr_file, encoding: "utf-8")
+    base_dir = File.dirname(cr_file)
+    deps = []
+
+    content.scan(REQUIRE_RE) do |(req)|
+      clean = req.delete_suffix(".cr")
+      expanded = File.expand_path(clean, base_dir)
+      dep = resolve_cr_path(expanded, src_dirs)
+      deps << dep if dep
+    end
+
+    deps.uniq
+  rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError
+    []
+  end
+
+  # Crystal convention: require "./foo" resolves as foo.cr OR foo/foo.cr (directory require).
+  def resolve_cr_path(expanded, src_dirs)
+    candidates = ["#{expanded}.cr", "#{expanded}/#{File.basename(expanded)}.cr"]
+    candidates.each do |candidate|
+      src_dirs.each do |src_dir, mod_name|
+        next unless candidate.start_with?("#{src_dir}/")
+
+        return file_to_pkg(candidate, src_dir, mod_name)
+      end
+    end
+    nil
+  end
+
+  # ── Package path helpers ──────────────────────────────────────────────────
+
+  # Uses full src-relative path (minus .cr extension). Prepends mod_name when the
+  # path doesn't already carry it — handles both layouts:
+  #   src/my_shard/feature.cr  (src_dir = src/)       → my_shard/feature
+  #   src/feature.cr           (src_dir = src/my_shard/) → my_shard/feature
+  def file_to_pkg(abs_path, src_dir, mod_name)
+    rel = abs_path.delete_prefix("#{src_dir}/").delete_suffix(".cr")
+    return mod_name if rel == mod_name
+    return rel if rel.start_with?("#{mod_name}/")
+
+    "#{mod_name}/#{rel}"
+  end
+
+  def cap_depth(pkg, mod_name)
+    return pkg if pkg != mod_name && !pkg.start_with?("#{mod_name}/")
+
+    suffix = pkg.delete_prefix("#{mod_name}/")
+    return mod_name if suffix == pkg
+
+    parts = suffix.split("/")
+    return pkg if parts.length <= MAX_PKG_DEPTH - 1
+
+    "#{mod_name}/#{parts.first(MAX_PKG_DEPTH - 1).join("/")}"
+  end
+end
+
+Archsight::Import::Registry.register("crystal-grapher", Archsight::Import::Handlers::CrystalGrapher)