archsight 0.3.3 → 0.4.1

data/lib/archsight/import/handler.rb

@@ -3,6 +3,7 @@
 require "digest"
 require "fileutils"
 require "json"
+require "pathname"
 require "yaml"
 require "archsight/import"
 require_relative "progress"
@@ -12,7 +13,14 @@ require_relative "progress"
 # Subclasses must implement the #execute method to perform the actual import.
 # Use the helper methods to read configuration, validate environment, and write output.
 class Archsight::Import::Handler
-  attr_reader :import_resource, :database, :resources_dir, :progress, :shared_writer
+  attr_reader :import_resource, :database, :resources_dir, :progress, :shared_writer, :owned_outputs
+
+  # Whether the handler generates child imports (`import_yaml`). An import that depends on a pattern
+  # (`import/dependsOn: Import:Repo:*`) waits for such a handler on its first run, before it has a `generates` record
+  # that tells which imports it creates. Override in handlers that generate imports.
+  def self.generates_imports?
+    false
+  end
 
   # @param import_resource [Archsight::Resources::Import] The import resource to execute
   # @param database [Archsight::Database] The database instance
@@ -26,6 +34,15 @@ class Archsight::Import::Handler
     @progress = progress || Archsight::Import::Progress.new
     @shared_writer = shared_writer
     @tracked_resources = []
+    @owned_outputs = []
+  end
+
+  # The directory the git-based handlers clone repositories into (`import/config/cacheRoot`, else `import.cache_root`
+  # of the user configuration or ARCHSIGHT_IMPORT_CACHE_ROOT, else ~/.cache/archsight/git), so an importer of the
+  # resources repository finds the same clones
+  # @return [String] absolute path
+  def cache_root
+    File.expand_path(Archsight::Import.cache_root(config("cacheRoot")))
   end
 
   # Execute the import. Must be implemented by subclasses.
@@ -74,23 +91,55 @@ class Archsight::Import::Handler
   end
 
   # Generate a marker Import for this handler with generated/at timestamp and config hash
-  # Used for caching - call at end of execute() to persist the execution timestamp
+  # Used for caching - call at end of execute() to persist the execution timestamp. It also records the hash of the
+  # files in `import/config/inputs` and the files written with #write_file, so call it after writing them.
   # @return [Hash] Import resource hash ready for YAML serialization
   def self_marker
+    annotations = {
+      "generated/at" => Time.now.utc.iso8601,
+      "generated/configHash" => compute_config_hash
+    }
+    inputs_hash = Archsight::Import.inputs_hash(import_resource, resources_dir)
+    annotations["generated/inputsHash"] = inputs_hash if inputs_hash
+    annotations["generated/outputs"] = owned_outputs.uniq.sort.join(",") if owned_outputs.any?
     {
       "apiVersion" => "architecture/v1alpha1",
       "kind" => "Import",
       "metadata" => {
         "name" => import_resource.name,
-        "annotations" => {
-          "generated/at" => Time.now.utc.iso8601,
-          "generated/configHash" => compute_config_hash
-        }
+        "annotations" => annotations
       },
       "spec" => {}
     }
   end
 
+  # Write a whole file that belongs to this import alone, such as a page (Markdown) next to the generated YAML.
+  # The file is recorded in the self marker (`generated/outputs`): the cache is invalid while it is missing, and a
+  # file of an earlier run that is not written again is deleted.
+  # @param rel_path [String] path relative to the resources directory
+  # @param content [String]
+  # @return [String] the absolute path
+  # @raise [ArgumentError] for a path outside the resources directory
+  def write_file(rel_path, content)
+    full_path = Archsight::Import.resources_path(resources_dir, rel_path)
+    raise ArgumentError, "#{rel_path} is outside the resources directory" unless full_path
+
+    FileUtils.mkdir_p(File.dirname(full_path))
+    File.write(full_path, content)
+    record_output(rel_path)
+    full_path
+  end
+
+  # Record a file this import wrote by other means (a command, a library) as its own output (see #write_file)
+  # @param rel_path [String] path relative to the resources directory
+  # @raise [ArgumentError] for a path outside the resources directory
+  def record_output(rel_path)
+    full_path = Archsight::Import.resources_path(resources_dir, rel_path)
+    raise ArgumentError, "#{rel_path} is outside the resources directory" unless full_path
+
+    @owned_outputs << Pathname.new(full_path).relative_path_from(File.expand_path(resources_dir)).to_s
+  end
+
   # Write YAML content to the output path
   # @param content [String] YAML content to write
   # @param filename [String, nil] Output filename (overrides import/outputPath filename)

data/lib/archsight/import/handler_loader.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "archsight/import"
+
+# Loads import handlers: the built-in ones shipped with the gem, and the handlers of the resources repository that an
+# Import declares with `import/handlerPath` (a Ruby file relative to the resources directory, like
+# `import/outputPath`). Used by `archsight import`, `lint` and `web`, so every command knows the same handler names.
+module Archsight::Import::HandlerLoader
+  BUILTIN_DIR = File.expand_path("handlers", __dir__)
+
+  # A problem with a local handler file, reported by the linter and by `archsight import`
+  Problem = Struct.new(:import, :message) do
+    def to_s
+      "#{import.path_ref}: Import '#{import.name}' #{message}"
+    end
+  end
+
+  class << self
+    # Require the built-in handlers. Idempotent; registers them again when a test cleared the registry.
+    def load_builtin!
+      Dir.glob(File.join(BUILTIN_DIR, "*.rb")).each { |file| require file }
+      Archsight::Import::Registry.restore_builtin!
+    end
+
+    # Load the built-in handlers and every handler file the Imports of the database declare
+    # @param database [Archsight::Database]
+    # @param resources_dir [String] directory `import/handlerPath` is relative to
+    # @return [Array<Problem>] files that are missing, outside the resources directory, fail to load or do not register
+    #   the handler named in `import/handler`
+    def load(database, resources_dir: database.path)
+      load_builtin!
+      imports = database.instances_by_kind("Import")&.values || []
+      imports.select { |imp| imp.annotations["import/handlerPath"] }.flat_map { |imp| load_for(imp, resources_dir) }
+    end
+
+    # Absolute path of the handler file of an Import, nil when it points outside the resources directory
+    def handler_file(import, resources_dir)
+      Archsight::Import.resources_path(resources_dir, import.annotations["import/handlerPath"])
+    end
+
+    private
+
+    def load_for(import, resources_dir)
+      file = handler_file(import, resources_dir)
+      return [Problem.new(import, "has import/handlerPath '#{import.annotations["import/handlerPath"]}' outside the resources directory")] unless file
+      return [Problem.new(import, "has import/handlerPath '#{import.annotations["import/handlerPath"]}' that does not exist")] unless File.file?(file)
+
+      problem = require_file(import, file)
+      return [problem] if problem
+
+      name = import.annotations["import/handler"]
+      return [] if name.nil? || Archsight::Import::Registry[name]
+
+      [Problem.new(import, "loads #{import.annotations["import/handlerPath"]}, which does not register the handler '#{name}'")]
+    end
+
+    def require_file(import, file)
+      require file
+      nil
+    rescue ScriptError, StandardError => e
+      Problem.new(import, "cannot load #{import.annotations["import/handlerPath"]}: #{e.class}: #{e.message.lines.first&.strip}")
+    end
+  end
+end

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

@@ -6,18 +6,41 @@
 # the current API listing, so a renamed, moved, or deleted repo doesn't
 # leave a stale clone behind that a later importer could still resolve
 # against under its old name.
+#
+# A listing can be incomplete (throttled or empty API pages) and clones may be
+# in progress, so pruning is conservative: entries touched within MIN_AGE are
+# kept, and nothing is removed when it would wipe out most of the cache.
 module Archsight::Import::Handlers::CachePruner
+  MIN_AGE = 3600 # seconds; younger directories may be a clone in progress
+  MAX_STALE_ABSOLUTE = 10 # always allowed, whatever the cache size
+  MAX_STALE_FRACTION = 0.2 # larger share of the cache is treated as a bad listing
+
   def prune_stale_cache_entries(target_dir, current_names)
     return unless File.directory?(target_dir)
 
-    Dir.children(target_dir).each do |entry|
-      next if current_names.include?(entry)
-
-      stale_path = File.join(target_dir, entry)
-      next unless File.directory?(stale_path)
+    known = current_names.to_set
+    dirs = Dir.children(target_dir).select { |entry| File.directory?(File.join(target_dir, entry)) }
+    stale = dirs.reject { |entry| known.include?(entry) }
+    return if stale.empty?
 
-      progress.warn("Pruning stale cache entry: #{entry} (repo renamed, moved, or removed)")
-      FileUtils.rm_rf(stale_path)
+    limit = [MAX_STALE_ABSOLUTE, (dirs.size * MAX_STALE_FRACTION).floor].max
+    if stale.size > limit
+      progress.warn("Not pruning #{stale.size} of #{dirs.size} cache entries in #{target_dir}: " \
+                    "the project listing looks incomplete")
+      return
     end
+
+    stale.each { |entry| prune_cache_entry(File.join(target_dir, entry), entry) }
+  end
+
+  private
+
+  def prune_cache_entry(path, name)
+    return if Time.now - File.mtime(path) < MIN_AGE
+
+    progress.warn("Pruning stale cache entry: #{name} (repo renamed, moved, or removed)")
+    FileUtils.rm_rf(path)
+  rescue Errno::ENOENT
+    nil
   end
 end

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "open3"
+require "shellwords"
+require "tmpdir"
+require "yaml"
+require_relative "../handler"
+require_relative "../registry"
+
+# Command handler - runs a program of the resources repository as an import, in any language. The program writes its
+# resources itself (usually to ARCHSIGHT_OUTPUT_PATH); archsight adds the self marker, so caching, `import/dependsOn`,
+# `-f` and `-n` work as for any other import.
+#
+# The program runs in the root of the repository that holds the resources directory (the resources directory when it
+# is not in a git repository), with a clean environment: PATH, HOME, LANG and the variables below, plus the variables
+# listed in `import/config/env` (credentials, for example).
+#
+#   ARCHSIGHT_RESOURCES_DIR - the resources directory
+#   ARCHSIGHT_CACHE_DIR     - where the git-based imports clone repositories
+#   ARCHSIGHT_IMPORT_NAME   - the name of the Import
+#   ARCHSIGHT_OUTPUT_PATH   - a file for the YAML resources the program generates; archsight writes them unchanged to
+#                             import/outputPath (generated/<name>.yaml without one), followed by the import's marker
+#
+# The output file belongs to the import: it is replaced on every run and removed when outputPath changes. Documents
+# are not marked as generated; a program that wants that sets `generated/script: <import name>` itself (only on kinds
+# that have the `generated` annotations), while documents that add relations to hand-written resources stay unmarked.
+#
+# Configuration:
+#   import/config/command - the command line (split like a shell does, but run without one; use `sh -c '...'` for
+#                           pipes); a relative program path is relative to the working directory
+#   import/config/env     - names of further environment variables to pass, comma separated
+#   import/config/outputs - files the program writes besides the output path, glob patterns relative to the
+#                           resources directory, comma separated; recorded like Handler#write_file
+#   import/config/workdir - working directory relative to the resources directory (default: the repository root)
+class Archsight::Import::Handlers::Command < Archsight::Import::Handler
+  PASSED_ENV = %w[PATH HOME LANG LC_ALL TMPDIR].freeze
+
+  def execute
+    command = Shellwords.split(config("command").to_s)
+    raise "Missing required config: command" if command.empty?
+
+    Dir.mktmpdir("archsight-command") do |tmp|
+      output_path = File.join(tmp, "output.yaml")
+      progress.update("Running #{command.first}")
+      out, err, status = Open3.capture3(environment(output_path), *command, chdir: working_directory, unsetenv_others: true)
+      raise "Command failed (exit #{status.exitstatus}): #{last_lines(err.empty? ? out : err)}" unless status.success?
+
+      record_declared_outputs
+      write_output(program_output(output_path))
+    end
+  rescue Errno::ENOENT => e
+    raise "Command not found: #{e.message}"
+  end
+
+  private
+
+  # What the program wrote to ARCHSIGHT_OUTPUT_PATH (a temporary file), as written: it must be YAML documents that
+  # are mappings, and stays byte for byte as it is (comments, order, no added annotations)
+  def program_output(output_path)
+    return "" unless File.file?(output_path)
+
+    text = File.read(output_path)
+    YAML.load_stream(text).compact.each do |document|
+      raise "#{import_resource.name}: the command wrote a document that is not a resource" unless document.is_a?(Hash)
+    end
+    text.end_with?("\n") || text.empty? ? text : "#{text}\n"
+  rescue Psych::SyntaxError => e
+    raise "The command wrote invalid YAML: #{e.message}"
+  end
+
+  # The output file is the import's own: written whole (not through the shared writer, which would drop the
+  # unmarked documents when another import flushes the file) and recorded as an output, so a changed outputPath
+  # removes the old file. Recorded before the marker is built, so the marker lists it.
+  def write_output(text)
+    rel_path = Archsight::Import.output_path(import_resource)
+    record_output(rel_path)
+    write_file(rel_path, text + YAML.dump(self_marker))
+  end
+
+  def environment(output_path)
+    passed = PASSED_ENV + config("env").to_s.split(",").map(&:strip).reject(&:empty?)
+    env = passed.to_h { |name| [name, ENV.fetch(name, nil)] }.compact
+    env.merge(
+      "ARCHSIGHT_RESOURCES_DIR" => File.expand_path(resources_dir),
+      "ARCHSIGHT_CACHE_DIR" => cache_root,
+      "ARCHSIGHT_IMPORT_NAME" => import_resource.name,
+      "ARCHSIGHT_OUTPUT_PATH" => File.expand_path(output_path)
+    )
+  end
+
+  def working_directory
+    workdir = config("workdir")
+    if workdir
+      root = File.expand_path(resources_dir)
+      path = File.expand_path(workdir, root)
+      return path if path == root || path.start_with?("#{root}/")
+
+      raise "workdir #{workdir} is outside the resources directory"
+    end
+
+    toplevel, _, status = Open3.capture3("git", "rev-parse", "--show-toplevel", chdir: resources_dir)
+    status.success? ? toplevel.strip : File.expand_path(resources_dir)
+  rescue Errno::ENOENT
+    File.expand_path(resources_dir)
+  end
+
+  def record_declared_outputs
+    patterns = config("outputs").to_s.split(",").map(&:strip).reject(&:empty?)
+    root = File.expand_path(resources_dir)
+    patterns.flat_map { |pattern| Dir.glob(pattern, base: root) }.uniq.each do |file|
+      record_output(file) if File.file?(File.join(root, file))
+    end
+  end
+
+  def last_lines(text)
+    text.to_s.lines.last(5).join.strip
+  end
+end
+
+Archsight::Import::Registry.register("command", Archsight::Import::Handlers::Command)

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

@@ -35,6 +35,9 @@ require_relative "cache_pruner"
 # the API (e.g. a repo that was renamed or deleted), so stale clones don't
 # linger and get picked up by later importers.
 class Archsight::Import::Handlers::Github < Archsight::Import::Handler
+  # generates child imports (see Handler.generates_imports?)
+  def self.generates_imports? = true
+
   include Archsight::Import::Handlers::CachePruner
 
   PER_PAGE = 100
@@ -49,7 +52,7 @@ class Archsight::Import::Handlers::Github < Archsight::Import::Handler
     @repo_output_path = config("repoOutputPath")
     @child_cache_time = config("childCacheTime")
     @default_visibility = config("defaultVisibility", default: "internal")
-    cache_root = config("cacheRoot", default: File.join(Dir.home, ".cache", "archsight", "git"))
+    cache_root = Archsight::Import.cache_root(config("cacheRoot"))
     @target_dir = File.join(cache_root, "github", @org)
 
     # Fetch all repositories with pagination

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

@@ -38,6 +38,9 @@ require_relative "cache_pruner"
 # API (e.g. a project that was renamed, moved, or deleted), so stale clones
 # don't linger and get picked up by later importers.
 class Archsight::Import::Handlers::Gitlab < Archsight::Import::Handler
+  # generates child imports (see Handler.generates_imports?)
+  def self.generates_imports? = true
+
   include Archsight::Import::Handlers::CachePruner
 
   def execute
@@ -51,7 +54,7 @@ class Archsight::Import::Handlers::Gitlab < Archsight::Import::Handler
     @child_cache_time = config("childCacheTime")
     @default_visibility = config("defaultVisibility", default: "internal")
 
-    cache_root = config("cacheRoot", default: File.join(Dir.home, ".cache", "archsight", "git"))
+    cache_root = Archsight::Import.cache_root(config("cacheRoot"))
     @target_dir = File.join(cache_root, "gitlab")
     @explore_groups = config("exploreGroups") == "true"
     @per_page = config("perPage", default: "100").to_i

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

@@ -20,13 +20,19 @@ require_relative "../registry"
 #
 # Configuration:
 #   import/config/path - Path to the Go repository root (same as GoGrapher)
+#   import/config/artifact - Repository artifact the modules belong to; names the component when two repositories
+#                            declare the same module path (see GoModuleParser#owned_component_name)
 class Archsight::Import::Handlers::GoDepResolver < Archsight::Import::Handler
   include Archsight::Import::Handlers::GoModuleParser
 
   def execute
     @path = config_path("path")
     raise "Missing required config: path" unless @path
-    raise "Directory not found: #{@path}" unless File.directory?(@path)
+
+    unless File.directory?(@path)
+      progress.warn("Skipping, repository not cloned: #{@path}")
+      return
+    end
 
     import_resource.annotations["import/outputPath"] ||= "generated/relationships.yaml"
 
@@ -37,11 +43,13 @@ class Archsight::Import::Handlers::GoDepResolver < Archsight::Import::Handler
     output = +""
 
     modules.each do |rel_dir, mod_name|
+      next if non_runtime_module?(rel_dir) || copied_module?(rel_dir, mod_name, config("artifact"))
+
       mod_dir = rel_dir == "." ? @path : File.join(@path, rel_dir)
       dep_names = compute_deps(mod_dir, mod_name, existing_components)
       next if dep_names.empty?
 
-      comp_name = component_name(mod_name)
+      comp_name = owned_component_name(mod_name, config("artifact"))
       existing = existing_components[comp_name]
       next unless existing
 

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

@@ -23,8 +23,18 @@ require_relative "../registry"
 #   import/config/nodesep              - Vertical gap between nodes in a column (default: 0.15)
 #   import/config/interface_visibility - Visibility prefix for detected interfaces (default: Private)
 class Archsight::Import::Handlers::GoGrapher < Archsight::Import::Handlers::Grapher
+  # generates child imports (see Handler.generates_imports?)
+  def self.generates_imports? = true
+
   include Archsight::Import::Handlers::GoModuleParser
 
+  # Directories not scanned for Go packages
+  PACKAGE_SKIP_DIRS = %w[vendor testdata node_modules].freeze
+  # Packages below these directories are not meant to be imported by other modules
+  NON_LIBRARY_DIRS = %w[internal cmd hack tools examples example e2e test tests].freeze
+  MAX_ENTRYPOINTS = 10
+  IGNORED_BUILD = %r{^(//go:build\s+ignore\b|//\s*\+build\s+ignore\b)}
+
   OPENAPI_FILENAMES = %w[openapi.yaml openapi.yml openapi.json swagger.yaml swagger.yml swagger.json].freeze
   OPENAPI_SUBDIRS   = %w[api docs spec].freeze
 
@@ -55,7 +65,14 @@ class Archsight::Import::Handlers::GoGrapher < Archsight::Import::Handlers::Grap
     output = +""
 
     modules.each do |rel_dir, mod_name|
-      comp_name = component_name(mod_name)
+      next if non_runtime_module?(rel_dir)
+
+      if copied_module?(rel_dir, mod_name, artifact_name)
+        progress.warn("Skipping copied go.mod at #{rel_dir}: module #{mod_name} belongs to another repository")
+        next
+      end
+
+      comp_name = owned_component_name(mod_name, artifact_name)
       next unless comp_name
 
       mod_dir = rel_dir == "." ? path : File.join(path, rel_dir)
@@ -64,6 +81,9 @@ class Archsight::Import::Handlers::GoGrapher < Archsight::Import::Handlers::Grap
       interface_names = specs.filter_map { |s| interface_name_from_spec(s, visibility: visibility) }
                              .select { |n| existing_interfaces.key?(n) }
 
+      existing = database&.instances_by_kind("ApplicationComponent")&.[](comp_name)
+      facts = curated_component_type?(existing) ? {} : component_facts(path, rel_dir, mod_name)
+
       comp_spec = { "realizedThrough" => { "technologyArtifacts" => [artifact_name] } }
       comp_spec["exposes"] = { "applicationInterfaces" => interface_names } if interface_names.any?
 
@@ -73,7 +93,8 @@ class Archsight::Import::Handlers::GoGrapher < Archsight::Import::Handlers::Grap
       component = untracked_resource_yaml(
         kind: "ApplicationComponent",
         name: comp_name,
-        spec: comp_spec
+        spec: comp_spec,
+        annotations: component_annotations(facts, existing_tags: existing&.annotations&.[]("architecture/tags"))
       )
       output << YAML.dump(component)
     end
@@ -85,7 +106,7 @@ class Archsight::Import::Handlers::GoGrapher < Archsight::Import::Handlers::Grap
     output << YAML.dump(import_yaml(
                           name: resolver_name,
                           handler: "go-dep-resolver",
-                          config: { "path" => path }
+                          config: { "path" => path, "artifact" => artifact_name }
                         ))
 
     output
@@ -130,7 +151,83 @@ class Archsight::Import::Handlers::GoGrapher < Archsight::Import::Handlers::Grap
 
   # ── OpenAPI detection ─────────────────────────────────────────────────────
 
-  def untracked_resource_yaml(kind:, name:, spec: {})
+  # A component type another source set (a person or an earlier import) is kept; this import's own earlier
+  # output is regenerated.
+  def curated_component_type?(existing)
+    return false unless existing&.annotations&.key?("component/type")
+
+    existing.annotations["generated/script"] != import_resource.name
+  end
+
+  # Classify a go.mod module from its packages: with `package main` it is an executable, without it a library,
+  # and a module with both main packages and importable packages is a module.
+  def component_facts(repo_root, rel_dir, _mod_name)
+    mod_dir = rel_dir == "." ? repo_root : File.join(repo_root, rel_dir)
+    mains, libraries = scan_go_packages(mod_dir)
+    type = if mains.empty?
+             "library"
+           elsif libraries.empty?
+             "executable"
+           else
+             "module"
+           end
+
+    { type: type,
+      tags: %w[ecosystem:go packaging:go-module], entrypoints: mains.first(MAX_ENTRYPOINTS) }
+  end
+
+  # @return [Array<Array<String>>] [main package dirs, importable library package dirs], relative to mod_dir
+  def scan_go_packages(mod_dir)
+    mains = []
+    libraries = []
+
+    Find.find(mod_dir) do |path|
+      if File.directory?(path)
+        Find.prune if path != mod_dir && skip_go_dir?(path)
+        next
+      end
+      next unless go_source?(path)
+
+      name = go_package_name(path)
+      next unless name
+
+      dir = File.dirname(path).delete_prefix(mod_dir).delete_prefix("/")
+      dir = "." if dir.empty?
+      if name == "main"
+        mains << dir
+      elsif !dir.split("/").intersect?(NON_LIBRARY_DIRS)
+        libraries << dir
+      end
+    end
+
+    [mains.uniq.sort, libraries.uniq.sort]
+  end
+
+  # Hidden and vendored directories, and nested modules (they are components of their own)
+  def skip_go_dir?(path)
+    base = File.basename(path)
+    PACKAGE_SKIP_DIRS.include?(base) || base.start_with?(".") || File.exist?(File.join(path, "go.mod"))
+  end
+
+  def go_source?(path)
+    path.end_with?(".go") && !path.end_with?("_test.go")
+  end
+
+  # Package name of a Go file, nil for a file that is excluded from normal builds (`//go:build ignore`)
+  def go_package_name(path)
+    head = File.foreach(path, encoding: "utf-8").first(40)
+    return nil if head.any? { |line| line.match?(IGNORED_BUILD) }
+
+    head.each do |line|
+      match = line.match(/\Apackage\s+(\w+)/)
+      return match[1] if match
+    end
+    nil
+  rescue SystemCallError, ArgumentError
+    nil
+  end
+
+  def untracked_resource_yaml(kind:, name:, spec: {}, annotations: {})
     {
       "apiVersion" => "architecture/v1alpha1",
       "kind" => kind,
@@ -139,7 +236,7 @@ class Archsight::Import::Handlers::GoGrapher < Archsight::Import::Handlers::Grap
         "annotations" => {
           "generated/script" => import_resource.name,
           "generated/at" => Time.now.utc.iso8601
-        }
+        }.merge(annotations)
       },
       "spec" => spec
     }

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

@@ -7,6 +7,13 @@ require "find"
 # Provides go.mod discovery, module name reading, require parsing, and the
 # component_name convention (strip SCM host, join path segments with ":").
 module Archsight::Import::Handlers::GoModuleParser
+  # Directories whose nested modules hold code that never runs in production: tests, pinned tooling, examples and
+  # benchmarks. Whole path segments only, so `pkg/latest` is not a test directory.
+  NON_RUNTIME_MODULE_DIRS = %w[
+    hack tools examples example bench benchmarks
+    test tests e2e e2etest e2etests systemtest systemtests integrationtest integrationtests fullstack
+  ].freeze
+
   # Discover all Go modules in a repository root.
   # Handles go.work workspaces, single-module repos, and multi-module monorepos
   # (root go.mod plus subdirectory go.mod files without go.work).
@@ -141,4 +148,85 @@ module Archsight::Import::Handlers::GoModuleParser
     parts.shift
     parts.join(":") unless parts.empty?
   end
+
+  # The name of the component that the module of one repository gets. Two repositories may declare the same module
+  # path (a prototype and its successor, a fork, a copy of the module); without care both would emit the same
+  # component and the loader would merge them into one. The repository that owns the plain name is the one the module
+  # path names (see #module_path_of_repository?), then the one that is not archived, then the first by name; the others
+  # get the repository appended (`alice:shop@acme:shop-prototype`).
+  #
+  # The other repositories are found through the existing component of the plain name, so a collision is resolved on
+  # the import after both repositories were imported once. A component without `generated/script` is curated: a
+  # person deliberately lists several repositories, and it keeps the plain name.
+  # @return [String, nil]
+  def owned_component_name(mod_name, artifact_name)
+    base = component_name(mod_name)
+    return base unless base && artifact_name
+
+    others = colliding_artifacts(base, artifact_name)
+    return base if others.empty?
+
+    owner = ([artifact_name] + others).min_by do |name|
+      [module_path_of_repository?(mod_name, name) ? 0 : 1, archived_artifact?(name) ? 1 : 0, name]
+    end
+    owner == artifact_name ? base : "#{base}@#{artifact_name.delete_prefix("Repo:")}"
+  end
+
+  # Whether the module path names the repository: the repository is the module itself or a module below it.
+  # `github.com/acme/library` and `github.com/acme/library/v2/client` belong to `Repo:acme:library` (and to
+  # `Repo:library`, an artifact named after its directory), not to `Repo:acme:app-poc`. The segments the artifact name
+  # and the module path both have must agree, so `github.com/alice/shop` does not name `Repo:acme:shop`.
+  # @return [Boolean]
+  def module_path_of_repository?(mod_name, artifact_name)
+    repo = artifact_name.delete_prefix("Repo:").split(":").reject(&:empty?)
+    path = module_path_segments(mod_name)
+    return false if repo.empty? || path.empty?
+
+    path.each_index.any? do |i|
+      next false if i.zero? && path.length > 1 # the first segment is the owner, never the repository
+
+      overlap = [repo.length, i + 1].min
+      repo.last(overlap) == path[(i + 1 - overlap)..i]
+    end
+  end
+
+  # A module in a subdirectory of `artifact_name` that is a copy of another repository's module: its path does not
+  # name this repository, but it names another repository of the database. It gets no component; the repository it
+  # was copied from has it.
+  # @return [Boolean]
+  def copied_module?(rel_dir, mod_name, artifact_name)
+    return false if rel_dir == "." || artifact_name.nil? || module_path_of_repository?(mod_name, artifact_name)
+
+    artifacts = database&.instances_by_kind("TechnologyArtifact") || {}
+    artifacts.keys.any? { |name| name.start_with?("Repo:") && name != artifact_name && module_path_of_repository?(mod_name, name) }
+  end
+
+  # A nested module below a test, tool, example or benchmark directory (`test/e2e`, `build/tools`,
+  # `internal/systemtest`). It gets no component, since nothing realizes it or depends on it; its packages stay in
+  # the module graph of the repository. `cmd/<name>` and `internal/` hold runtime code and are not matched.
+  # @return [Boolean]
+  def non_runtime_module?(rel_dir)
+    return false if rel_dir == "."
+
+    rel_dir.split("/").intersect?(NON_RUNTIME_MODULE_DIRS)
+  end
+
+  # Path segments of a module without the host and without a major version suffix (`/v2`)
+  def module_path_segments(mod_name)
+    mod_name.split("/").drop(1).grep_v(/\Av\d+\z/)
+  end
+
+  # Repository artifacts other than `artifact_name` that a generated component of this name is realized through
+  def colliding_artifacts(base, artifact_name)
+    existing = database&.instances_by_kind("ApplicationComponent")&.[](base)
+    return [] unless existing&.annotations&.key?("generated/script")
+
+    artifacts = Array(existing.raw.dig("spec", "realizedThrough", "technologyArtifacts"))
+    artifacts.select { |name| name.start_with?("Repo:") && name != artifact_name }.uniq
+  end
+
+  def archived_artifact?(name)
+    artifact = database&.instances_by_kind("TechnologyArtifact")&.[](name)
+    artifact&.annotations&.[]("activity/status") == "archived"
+  end
 end