archsight 0.2.3 → 0.2.5

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

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+require "find"
+require_relative "grapher"
+require_relative "../registry"
+
+# JavaGrapher handler - analyses a Java repository and generates a GraphViz DOT
+# graph of its package/module structure, stored as architecture/modules on the
+# TechnologyArtifact so it can be rendered in the frontend.
+#
+# Understands Maven (pom.xml) single and multi-module projects as well as
+# Gradle (build.gradle / settings.gradle) layouts. Scanning is pure Ruby —
+# no JDK or build tool installation required.
+#
+# Configuration:
+#   import/config/path     - Path to the Java 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::JavaGrapher < Archsight::Import::Handlers::Grapher
+  def self.language_name = "java"
+
+  def self.applicable?(path)
+    File.exist?(File.join(path, "pom.xml")) ||
+      File.exist?(File.join(path, "build.gradle")) ||
+      File.exist?(File.join(path, "build.gradle.kts")) ||
+      Dir.glob(File.join(path, "*/pom.xml")).any?
+  end
+
+  SKIP_DIRS = %w[test tests generated target build .git node_modules .gradle resources].freeze
+
+  # Cap relative package depth at 2 levels to keep the graph readable.
+  # Packages deeper than this are folded into their depth-2 ancestor.
+  MAX_PKG_DEPTH = 2
+
+  private
+
+  def wrap_single_module?
+    true
+  end
+
+  # Always render package nodes: Java packages with direct files should remain
+  # visible even when their label matches the enclosing cluster label.
+  def show_root_package_node?
+    true
+  end
+
+  # Only suppress edges to structural ancestors (paths not in pkg_set).
+  # Java packages with both direct files and sub-packages must keep their edges.
+  def suppress_edge_to?(dep, pkg_set, has_children)
+    has_children.include?(dep) && !pkg_set.include?(dep)
+  end
+
+  # ── Module discovery ─────────────────────────────────────────────────────
+
+  def discover_modules(repo_root)
+    discover_maven_modules(repo_root) ||
+      discover_gradle_modules(repo_root) ||
+      discover_source_fallback(repo_root) ||
+      []
+  end
+
+  def discover_maven_modules(repo_root)
+    root_pom = File.join(repo_root, "pom.xml")
+    return unless File.exist?(root_pom)
+
+    sub_dirs = maven_submodule_dirs(root_pom)
+    if sub_dirs.any?
+      modules = sub_module_list(repo_root, sub_dirs)
+      return modules if modules.any?
+    end
+
+    single_module_from_root(repo_root)
+  end
+
+  def discover_gradle_modules(repo_root)
+    settings = ["settings.gradle", "settings.gradle.kts"]
+               .map { |f| File.join(repo_root, f) }
+               .find { |f| File.exist?(f) }
+    return unless settings
+
+    includes = gradle_includes(settings)
+    if includes.any?
+      modules = sub_module_list(repo_root, includes)
+      return modules if modules.any?
+    end
+
+    single_module_from_root(repo_root)
+  end
+
+  def discover_source_fallback(repo_root)
+    single_module_from_root(repo_root)
+  end
+
+  def sub_module_list(repo_root, rel_dirs)
+    rel_dirs.filter_map do |rel|
+      abs = File.join(repo_root, rel)
+      next unless File.directory?(abs)
+
+      src = find_source_dir(abs)
+      next unless src
+
+      pkg_prefix = common_java_prefix(src)
+      next unless pkg_prefix
+
+      [rel, pkg_prefix]
+    end
+  end
+
+  def single_module_from_root(repo_root)
+    src = find_source_dir(repo_root)
+    return unless src
+
+    pkg_prefix = common_java_prefix(src)
+    return unless pkg_prefix
+
+    [[".", pkg_prefix]]
+  end
+
+  # ── Package collection ────────────────────────────────────────────────────
+
+  def collect_packages(repo_root, modules, _prefix)
+    all_pkgs = {}
+    modules.each do |rel_dir, mod_name|
+      mod_dir = rel_dir == "." ? repo_root : File.join(repo_root, rel_dir)
+      src = find_source_dir(mod_dir)
+      next unless src
+
+      scan_java_packages(src, mod_name).each do |pkg, deps|
+        all_pkgs[pkg] = (all_pkgs[pkg] || []) + deps
+      end
+    end
+
+    # Retain only internal dependencies (drop java.*, org.springframework, etc.)
+    all_pkg_set = all_pkgs.keys.to_set
+    all_pkgs.transform_values! { |deps| deps.select { |d| all_pkg_set.include?(d) }.uniq }
+
+    # Add a synthetic "main" node for any detected entry point classes
+    entry_pkgs = detect_main_packages(repo_root, modules)
+    if entry_pkgs.any?
+      all_pkgs["main"] ||= []
+      all_pkgs["main"].concat(entry_pkgs.select { |p| all_pkg_set.include?(p) })
+      all_pkgs.delete("main") if all_pkgs["main"].empty?
+    end
+
+    all_pkgs
+  end
+
+  # ── Build system helpers ──────────────────────────────────────────────────
+
+  def maven_submodule_dirs(pom_path)
+    content = File.read(pom_path)
+    m = content.match(%r{<modules>(.*?)</modules>}m)
+    return [] unless m
+
+    m[1].scan(%r{<module>(.*?)</module>}).flatten.map(&:strip).reject(&:empty?)
+  end
+
+  def gradle_includes(settings_path)
+    content = File.read(settings_path)
+    content.scan(/include\s*[('":]+([^'"):\s,]+)/).flatten.map do |name|
+      name.tr(":", "/").delete_prefix("/")
+    end.reject(&:empty?)
+  end
+
+  # ── Source directory helpers ──────────────────────────────────────────────
+
+  def find_source_dir(mod_dir)
+    [
+      File.join(mod_dir, "src", "main", "java"),
+      File.join(mod_dir, "src", "java"),
+      File.join(mod_dir, "src"),
+      mod_dir
+    ].find { |d| File.directory?(d) }
+  end
+
+  # Returns the common Java package prefix (as a "/"-path) for all .java files
+  # under src_dir, or nil if no .java files are found.
+  def common_java_prefix(src_dir)
+    prefixes = []
+    Find.find(src_dir) do |path|
+      Find.prune if File.directory?(path) && SKIP_DIRS.include?(File.basename(path))
+      next unless path.end_with?(".java")
+
+      File.foreach(path) do |line|
+        if (m = line.match(/^\s*package\s+([\w.]+)\s*;/))
+          prefixes << m[1].split(".")
+          break
+        end
+      end
+    end
+    return nil if prefixes.empty?
+
+    common = prefixes.first.dup
+    prefixes.drop(1).each do |parts|
+      common = common.zip(parts).take_while { |a, b| a == b }.map(&:first)
+    end
+    return nil if common.empty?
+
+    common.join("/")
+  end
+
+  # Walk src_dir and return { pkg_path => [import_pkg_paths] } for all packages
+  # whose package declaration starts with mod_name (using "/" separators).
+  # Packages deeper than MAX_PKG_DEPTH relative levels are folded into their
+  # depth-capped ancestor to keep the graph readable.
+  def scan_java_packages(src_dir, mod_name)
+    pkgs = {}
+    Find.find(src_dir) do |path|
+      if File.directory?(path)
+        Find.prune if SKIP_DIRS.include?(File.basename(path))
+        next
+      end
+      next unless path.end_with?(".java")
+
+      pkg_name = nil
+      imports = []
+      File.foreach(path) do |line|
+        if (m = line.match(/^\s*package\s+([\w.]+)\s*;/))
+          pkg_name = cap_depth(m[1].tr(".", "/"), mod_name)
+        elsif (m = line.match(/^\s*import\s+(?:static\s+)?([\w.]+(?:\.\*)?)\s*;/))
+          imp = strip_class_suffix(m[1].delete_suffix(".*").tr(".", "/"))
+          imports << cap_depth(imp, mod_name) unless imp.empty?
+        end
+      end
+
+      next unless pkg_name
+      next unless pkg_name == mod_name || pkg_name.start_with?("#{mod_name}/")
+
+      pkgs[pkg_name] ||= []
+      pkgs[pkg_name].concat(imports)
+    end
+
+    pkgs.transform_values(&:uniq)
+  end
+
+  # Drop trailing path components that begin with an uppercase letter (class names).
+  def strip_class_suffix(slash_path)
+    parts = slash_path.split("/")
+    parts.pop while parts.last&.match?(/\A[A-Z]/)
+    parts.join("/")
+  end
+
+  # Fold a package path deeper than MAX_PKG_DEPTH (from mod_name) into its
+  # depth-capped ancestor. Paths not under mod_name are returned unchanged.
+  def cap_depth(pkg, mod_name)
+    rel = pkg.delete_prefix("#{mod_name}/")
+    return pkg if rel == pkg
+
+    parts = rel.split("/")
+    return pkg if parts.length <= MAX_PKG_DEPTH
+
+    "#{mod_name}/#{parts.first(MAX_PKG_DEPTH).join("/")}"
+  end
+
+  # Scan source directories for Java entry point classes and return their
+  # (depth-capped) package paths. Detects: traditional main methods,
+  # @SpringBootApplication, and @QuarkusMain.
+  def detect_main_packages(repo_root, modules)
+    entry_pkgs = []
+    modules.each do |rel_dir, mod_name|
+      mod_dir = rel_dir == "." ? repo_root : File.join(repo_root, rel_dir)
+      src = find_source_dir(mod_dir)
+      next unless src
+
+      Find.find(src) do |path|
+        if File.directory?(path)
+          Find.prune if SKIP_DIRS.include?(File.basename(path))
+          next
+        end
+        next unless path.end_with?(".java")
+
+        content = File.read(path, encoding: "utf-8", invalid: :replace)
+        next unless content.match?(/public\s+static\s+void\s+main\s*\(/) ||
+                    content.match?(/@SpringBootApplication\b/) ||
+                    content.match?(/@QuarkusMain\b/)
+
+        if (m = content.match(/^\s*package\s+([\w.]+)\s*;/))
+          entry_pkgs << cap_depth(m[1].tr(".", "/"), mod_name)
+        end
+      end
+    end
+    entry_pkgs.uniq
+  end
+end
+
+Archsight::Import::Registry.register("java-grapher", Archsight::Import::Handlers::JavaGrapher)

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

@@ -0,0 +1,340 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require_relative "grapher"
+require_relative "../registry"
+
+# JavaScriptGrapher — analyses a JavaScript or TypeScript repository and generates
+# a GraphViz DOT graph of its package/module structure, stored as
+# architecture/javascript/modules on the TechnologyArtifact.
+#
+# Covers .js, .mjs, .cjs, .ts, .tsx, .jsx (single grapher for both JS and TS).
+#
+# Supported project layouts:
+#   - Single package (package.json at root)
+#   - NPM / Yarn workspaces ("workspaces" key in root package.json)
+#   - PNPM workspaces (pnpm-workspace.yaml)
+#   - Lerna (lerna.json)
+#   - Nx / Turborepo (nx.json / turbo.json — scan direct subdirs)
+#
+# Import resolution:
+#   - Relative imports (./foo, ../bar)
+#   - TypeScript tsconfig.json path aliases (@/utils → src/utils)
+#   - Cross-workspace package imports (@company/shared → module root)
+#   - "import type" lines are ignored (no runtime dependency)
+#
+# Configuration:
+#   import/config/path     - Path to the 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::JavaScriptGrapher < Archsight::Import::Handlers::Grapher
+  def self.language_name = "javascript"
+
+  def self.applicable?(path)
+    File.exist?(File.join(path, "package.json")) ||
+      Dir.glob(File.join(path, "*/package.json")).any?
+  end
+
+  def wrap_single_module?
+    true
+  end
+
+  SKIP_DIRS = %w[node_modules dist build .next .nuxt out .turbo .nx .cache
+                 coverage .git test tests __tests__ __mocks__ e2e cypress
+                 playwright .storybook storybook-static fixtures temp tmp].freeze
+
+  SOURCE_EXTS = %w[.ts .tsx .js .jsx .mjs .cjs].freeze
+
+  # Packages with more than this many path components are folded into their ancestor.
+  # Two levels gives mod_name/feature — matching Java and Ruby conventions.
+  MAX_PKG_DEPTH = 2
+
+  FROM_RE    = /\bfrom\s+["']([^"'\n]+)["']/
+  REQUIRE_RE = /\brequire\s*\(\s*["']([^"'\n]+)["']\s*\)/
+  DYNAMIC_RE = /\bimport\s*\(\s*["']([^"'\n]+)["']\s*\)/
+  TYPE_RE    = /\bimport\s+type\b/
+
+  private
+
+  # ── Module discovery ─────────────────────────────────────────────────────
+
+  def discover_modules(repo_root)
+    # PNPM workspaces
+    pnpm_ws = File.join(repo_root, "pnpm-workspace.yaml")
+    if File.exist?(pnpm_ws)
+      modules = workspace_modules_from_globs(repo_root, pnpm_workspace_patterns(pnpm_ws))
+      return modules if modules.any?
+    end
+
+    root_pkg = read_package_json(repo_root)
+
+    # NPM / Yarn workspaces ("workspaces" key in package.json)
+    ws_globs = workspace_globs_from_package(root_pkg)
+    if ws_globs.any?
+      modules = workspace_modules_from_globs(repo_root, ws_globs)
+      return modules if modules.any?
+    end
+
+    # Lerna
+    lerna_path = File.join(repo_root, "lerna.json")
+    if File.exist?(lerna_path)
+      lerna = safe_json(lerna_path)
+      if lerna
+        lerna_globs = Array(lerna["packages"])
+        lerna_globs = ["packages/*"] if lerna_globs.empty?
+        modules = workspace_modules_from_globs(repo_root, lerna_globs)
+        return modules if modules.any?
+      end
+    end
+
+    # Nx / Turborepo — scan direct subdirs
+    if File.exist?(File.join(repo_root, "nx.json")) || File.exist?(File.join(repo_root, "turbo.json"))
+      modules = scan_subdir_modules(repo_root)
+      return modules if modules.any?
+    end
+
+    # No root package.json but subdirectory packages exist (e.g. a repo with a frontend/ subdir)
+    if root_pkg.nil?
+      modules = scan_subdir_modules(repo_root)
+      return modules if modules.any?
+    end
+
+    # Single module fallback
+    name = root_pkg&.dig("name") || File.basename(repo_root)
+    [[".", name]]
+  end
+
+  # ── Package collection ────────────────────────────────────────────────────
+
+  def collect_packages(repo_root, modules, _prefix)
+    workspace_names = build_workspace_name_map(modules)
+    all_pkgs = {}
+
+    modules.each do |rel_dir, mod_name|
+      mod_dir = rel_dir == "." ? repo_root : File.join(repo_root, rel_dir)
+      src_root = locate_src_root(mod_dir)
+      tsconfig_paths = load_tsconfig_paths(mod_dir)
+
+      scan_source_files(src_root, mod_name, tsconfig_paths, workspace_names, all_pkgs)
+    end
+
+    all_pkgs
+  end
+
+  # ── File scanning ─────────────────────────────────────────────────────────
+
+  def scan_source_files(src_root, mod_name, tsconfig_paths, workspace_names, all_pkgs)
+    glob = File.join(src_root, "**", "*{#{SOURCE_EXTS.join(",")}}")
+    safe_glob(glob).each do |source_file|
+      rel_parts = source_file.delete_prefix("#{src_root}/").split("/")
+      next if rel_parts.any? { |p| SKIP_DIRS.include?(p) }
+
+      pkg = cap_depth(file_to_pkg(source_file, src_root, mod_name), mod_name)
+      all_pkgs[pkg] ||= []
+
+      extract_imports(source_file).each do |req|
+        dep = resolve_import(req, source_file, src_root, mod_name, tsconfig_paths, workspace_names)
+        next unless dep
+
+        dep = cap_depth(dep, mod_name)
+        next if dep == pkg || all_pkgs[pkg].include?(dep)
+
+        all_pkgs[pkg] << dep
+      end
+    end
+  end
+
+  # ── Import extraction ─────────────────────────────────────────────────────
+
+  def extract_imports(source_file)
+    content = File.read(source_file, encoding: "utf-8")
+    deps = []
+
+    content.each_line do |line|
+      next if line.match?(TYPE_RE)
+
+      line.scan(FROM_RE) { |(m)| deps << m }
+    end
+
+    content.scan(REQUIRE_RE) { |(m)| deps << m }
+    content.scan(DYNAMIC_RE) { |(m)| deps << m }
+
+    deps.uniq
+  rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError
+    []
+  end
+
+  # ── Import resolution ─────────────────────────────────────────────────────
+
+  def resolve_import(req, source_file, src_root, mod_name, tsconfig_paths, workspace_names)
+    return resolve_relative(req, source_file, src_root, mod_name) if req.start_with?("./", "../")
+
+    dep = resolve_alias(req, tsconfig_paths, src_root, mod_name)
+    return dep if dep
+
+    resolve_workspace_import(req, workspace_names)
+  end
+
+  def resolve_relative(req, source_file, src_root, mod_name)
+    clean = req.sub(/\.(js|ts|jsx|tsx|mjs|cjs)$/, "")
+    expanded = File.expand_path(clean, File.dirname(source_file))
+    return nil unless expanded.start_with?(src_root)
+
+    if Dir.exist?(expanded)
+      rel = expanded.delete_prefix("#{src_root}/")
+      rel == "." ? mod_name : "#{mod_name}/#{rel}"
+    else
+      file_to_pkg("#{expanded}.ts", src_root, mod_name)
+    end
+  end
+
+  def resolve_alias(req, tsconfig_paths, src_root, mod_name)
+    tsconfig_paths.each do |prefix, target_dir|
+      next unless req.start_with?(prefix)
+
+      rest = req.delete_prefix(prefix)
+      expanded = rest.empty? ? target_dir : File.join(target_dir, rest)
+      next unless expanded.start_with?(src_root)
+
+      return file_to_pkg("#{expanded}.ts", src_root, mod_name)
+    end
+    nil
+  end
+
+  def resolve_workspace_import(req, workspace_names)
+    workspace_names.each do |pkg_name, mod_name|
+      return mod_name if req == pkg_name
+      next unless req.start_with?("#{pkg_name}/")
+
+      sub = req.delete_prefix("#{pkg_name}/")
+      return "#{mod_name}/#{sub.split("/").first}"
+    end
+    nil
+  end
+
+  # ── Package path helpers ──────────────────────────────────────────────────
+
+  # Maps a source file to a package path: mod_name/dir where dir is the
+  # file's directory within src_root. Files at the src_root level map to mod_name.
+  def file_to_pkg(abs_path, src_root, mod_name)
+    rel = abs_path.delete_prefix("#{src_root}/")
+    dir = File.dirname(rel)
+    dir == "." ? mod_name : "#{mod_name}/#{dir}"
+  end
+
+  def cap_depth(pkg, mod_name)
+    # Cross-module packages (e.g. workspace deps) are returned unchanged.
+    return pkg if pkg != mod_name && !pkg.start_with?("#{mod_name}/")
+
+    suffix = pkg.delete_prefix("#{mod_name}/")
+    return mod_name if suffix == pkg # pkg IS the module root
+
+    parts = suffix.split("/")
+    return pkg if parts.length <= MAX_PKG_DEPTH - 1
+
+    "#{mod_name}/#{parts.first(MAX_PKG_DEPTH - 1).join("/")}"
+  end
+
+  # ── Source root detection ─────────────────────────────────────────────────
+
+  def locate_src_root(mod_dir)
+    %w[src lib app].each do |subdir|
+      candidate = File.join(mod_dir, subdir)
+      return candidate if Dir.exist?(candidate)
+    end
+    mod_dir
+  end
+
+  # ── tsconfig path loading ─────────────────────────────────────────────────
+
+  def load_tsconfig_paths(mod_dir)
+    paths = {}
+    %w[tsconfig.json tsconfig.base.json].each do |fname|
+      tsconfig_file = File.join(mod_dir, fname)
+      next unless File.exist?(tsconfig_file)
+
+      data = safe_json(tsconfig_file)
+      break unless data
+
+      raw_paths = data.dig("compilerOptions", "paths") || {}
+      base_url  = data.dig("compilerOptions", "baseUrl") || "."
+      base_dir  = File.expand_path(File.join(mod_dir, base_url))
+
+      raw_paths.each do |pattern, targets|
+        next if targets.empty?
+
+        # Extract the literal prefix before the wildcard: "@/*" → "@/", "shared" → "shared"
+        prefix     = pattern.sub(/\*.*$/, "")
+        target_dir = File.expand_path(File.join(base_dir, targets.first.sub(/\*.*$/, "")))
+        paths[prefix] = target_dir
+      end
+      break
+    end
+    paths
+  end
+
+  # ── Workspace helpers ─────────────────────────────────────────────────────
+
+  def workspace_globs_from_package(pkg)
+    return [] unless pkg
+
+    ws = pkg["workspaces"]
+    Array(ws.is_a?(Hash) ? ws["packages"] : ws)
+  end
+
+  def pnpm_workspace_patterns(pnpm_ws_path)
+    data = begin
+      YAML.safe_load(File.read(pnpm_ws_path, encoding: "utf-8"))
+    rescue StandardError
+      {}
+    end
+    Array(data&.dig("packages")).reject { |p| p.to_s.start_with?("!") }
+  end
+
+  def workspace_modules_from_globs(repo_root, globs)
+    globs.flat_map do |glob|
+      Dir.glob(File.join(repo_root, glob)).filter_map do |dir|
+        next unless File.directory?(dir) && File.exist?(File.join(dir, "package.json"))
+
+        rel = dir.delete_prefix("#{repo_root}/")
+        next if rel.split("/").any? { |part| SKIP_DIRS.include?(part) }
+
+        pkg      = read_package_json(dir)
+        mod_name = pkg&.dig("name") || File.basename(dir)
+        [rel, mod_name]
+      end
+    end.uniq
+  end
+
+  def scan_subdir_modules(repo_root)
+    modules = Dir.each_child(repo_root).filter_map do |entry|
+      dir = File.join(repo_root, entry)
+      next unless File.directory?(dir) && !SKIP_DIRS.include?(entry) && !entry.start_with?(".")
+      next unless File.exist?(File.join(dir, "package.json"))
+
+      pkg      = read_package_json(dir)
+      mod_name = pkg&.dig("name") || entry
+      [entry, mod_name]
+    end
+    modules.sort_by { |rel, _| rel }
+  end
+
+  def build_workspace_name_map(modules)
+    modules.each_with_object({}) do |(_rel_dir, mod_name), map|
+      map[mod_name] = mod_name
+    end
+  end
+
+  def read_package_json(dir)
+    safe_json(File.join(dir, "package.json"))
+  end
+
+  def safe_json(path)
+    JSON.parse(File.read(path, encoding: "utf-8"))
+  rescue JSON::ParserError, Errno::ENOENT, Encoding::InvalidByteSequenceError
+    nil
+  end
+end
+
+Archsight::Import::Registry.register("javascript-grapher", Archsight::Import::Handlers::JavaScriptGrapher)