archsight 0.3.3 → 0.4.1

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

@@ -35,6 +35,11 @@ class Archsight::Import::Handlers::Grapher < Archsight::Import::Handler
     []
   end
 
+  # Namespaces of the machine tags (namespace:value) that importers write into architecture/tags.
+  # `entrypoint` is no longer written (see component/entrypoints) but stays listed so a re-import
+  # removes the tags of earlier runs.
+  MACHINE_TAG_NAMESPACES = %w[ecosystem packaging entrypoint linkage].freeze
+
   PALETTE = [
     { fill: "#ddeeff", edge: "#2266cc" },
     { fill: "#ddffd8", edge: "#2a8a1e" },
@@ -51,7 +56,13 @@ class Archsight::Import::Handlers::Grapher < Archsight::Import::Handler
   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)
+      # The clone is the repository import's job (it reports its own failure);
+      # no marker is written, so this runs again once the clone exists.
+      progress.warn("Skipping, repository not cloned: #{@path}")
+      return
+    end
 
     # Consolidate all grapher output into a single shared file unless an
     # explicit output path is already set (e.g. via grapherOutputPath on the
@@ -123,6 +134,34 @@ class Archsight::Import::Handlers::Grapher < Archsight::Import::Handler
     raise NotImplementedError, "#{self.class}#collect_packages must be implemented"
   end
 
+  # Hook: subclasses that emit ApplicationComponents describe each module here.
+  # @param _repo_root [String] Absolute path to the repository root
+  # @param _rel_dir [String] Directory of the module relative to the root ("." for the root)
+  # @param _mod_name [String] Module name from discover_modules
+  # @return [Hash] { type: "executable|library|module|...", tags: ["ecosystem:go", ...],
+  #   entrypoints: ["cmd/api", ...] }, empty when unknown
+  def component_facts(_repo_root, _rel_dir, _mod_name)
+    {}
+  end
+
+  # component/type, component/entrypoints and the machine tags (namespace:value) in architecture/tags for the
+  # facts of component_facts.
+  # The tags a person set stay; machine tags of the importer's namespaces from an earlier run are replaced.
+  def component_annotations(facts, existing_tags: nil)
+    annotations = {}
+    annotations["component/type"] = facts[:type] if facts[:type]
+    annotations["component/entrypoints"] = facts[:entrypoints].join(",") if facts[:entrypoints]&.any?
+    annotations["architecture/tags"] = merge_machine_tags(existing_tags, facts[:tags]).join(",") if facts[:tags]&.any?
+    annotations
+  end
+
+  def merge_machine_tags(existing_tags, machine_tags)
+    kept = existing_tags.to_s.split(",").map(&:strip).reject(&:empty?).reject do |tag|
+      MACHINE_TAG_NAMESPACES.include?(tag.split(":", 2).first) && tag.include?(":")
+    end
+    (kept + Array(machine_tags)).uniq
+  end
+
   # ── Module coloring ───────────────────────────────────────────────────────
 
   def build_module_colors(modules)

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

@@ -22,6 +22,9 @@ require_relative "../team_matcher"
 #   import/config/corporateAffixes - Optional comma-separated corporate username affixes for team matching (e.g., "ionos,1and1")
 #   import/config/grapherOutputPath - Optional output path for language-grapher child imports
 class Archsight::Import::Handlers::Repository < Archsight::Import::Handler
+  # generates child imports (see Handler.generates_imports?)
+  def self.generates_imports? = true
+
   def execute
     @path = config_path("path")
     @git_url = config("gitUrl")

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

@@ -43,6 +43,9 @@ require_relative "../registry"
 #     ]
 #   }
 class Archsight::Import::Handlers::RestApiIndex < Archsight::Import::Handler
+  # generates child imports (see Handler.generates_imports?)
+  def self.generates_imports? = true
+
   VALID_GATES = %w[General-Availability Early-Access Development GA EA DEV].freeze
   GATE_TOKEN_RE = /\b(ga|ea|dev)\b/i
 

data/lib/archsight/import/registry.rb

@@ -8,13 +8,25 @@ require "archsight/import"
 # The executor looks up handlers by name to instantiate and execute them.
 module Archsight::Import::Registry
   @handlers = {}
+  @builtin = {}
 
   class << self
     # Register a handler class with a name
     # @param name [String, Symbol] Handler name (matches import/handler annotation)
     # @param handler_class [Class] Handler class that extends Handler
+    # @raise [DuplicateHandlerError] if another class already registered the name
     def register(name, handler_class)
-      @handlers[name.to_s] = handler_class
+      name = name.to_s
+      existing = @handlers[name] || @builtin[name]
+      raise Archsight::Import::DuplicateHandlerError, "Import handler '#{name}' is registered twice (#{existing} and #{handler_class})" if existing && existing != handler_class
+
+      @handlers[name] = handler_class
+      @builtin[name] = handler_class if builtin_caller?(caller_locations(1, 1)&.first)
+    end
+
+    # Register the built-in handlers again after `clear!` (they are only required once per process)
+    def restore_builtin!
+      @handlers = @builtin.merge(@handlers)
     end
 
     # Look up a handler class by name
@@ -70,8 +82,17 @@ module Archsight::Import::Registry
     def clear!
       @handlers = {}
     end
+
+    private
+
+    def builtin_caller?(location)
+      location && File.expand_path(location.path).start_with?("#{File.expand_path("handlers", __dir__)}/")
+    end
   end
 end
 
 # Error raised when an unknown handler is requested
 class Archsight::Import::UnknownHandlerError < StandardError; end
+
+# Error raised when two handler classes register the same name
+class Archsight::Import::DuplicateHandlerError < StandardError; end

data/lib/archsight/import.rb

@@ -1,14 +1,102 @@
 # frozen_string_literal: true
 
+require "fileutils"
+
 # Define import module namespaces
 module Archsight
   module Import
     module Handlers
     end
+
+    # Where the git-based handlers clone repositories: the handler's own `cacheRoot` setting, else `import.cache_root`
+    # of the user configuration (or ARCHSIGHT_IMPORT_CACHE_ROOT), else ~/.cache/archsight/git
+    # @param override [String, nil] a handler's own setting
+    # @return [String] the directory as configured (a `~` stays, so generated child imports keep the portable form;
+    #   expand it before use)
+    def self.cache_root(override = nil)
+      require "archsight/user_config"
+      override || Archsight::UserConfig.setting("import", "cache_root")&.to_s || File.join(cache_dir, "git")
+    end
+
+    # The cache directory of Archsight, ~/.cache/archsight
+    def self.cache_dir = File.join(Dir.home, ".cache", "archsight")
+
+    # Tells Spotlight (macOS) not to index this
+    NEVER_INDEX = ".metadata_never_index"
+
+    # Makes sure the clones are not indexed by Spotlight: the marker file in ~/.cache/archsight, or in the cache root
+    # itself when it is somewhere else. Run before every import; a directory that cannot be written is left alone,
+    # the import does not depend on it.
+    # @param root [String] the cache root (Handler#cache_root)
+    # @return [String, nil] the marker file, nil if it could not be written
+    def self.never_index(root)
+      dir = File.expand_path(root)
+      dir = cache_dir if dir.start_with?("#{cache_dir}/")
+      marker = File.join(dir, NEVER_INDEX)
+      return marker if File.exist?(marker)
+
+      FileUtils.mkdir_p(dir)
+      FileUtils.touch(marker)
+      marker
+    rescue SystemCallError
+      nil
+    end
+
+    # The entries of `import/dependsOn`: import names and glob patterns
+    # @return [Array<String>]
+    def self.declared_dependencies(import)
+      import.annotations["import/dependsOn"].to_s.split(",").map(&:strip).reject(&:empty?)
+    end
+
+    # Absolute path of a file below the resources directory, nil when the path leaves it
+    def self.resources_path(resources_dir, rel_path)
+      root = File.expand_path(resources_dir)
+      path = File.expand_path(rel_path.to_s, root)
+      path.start_with?("#{root}/") ? path : nil
+    end
+
+    # The file an import writes its resources to, relative to the resources directory: `import/outputPath`, else
+    # generated/<name>.yaml (see Handler#write_yaml)
+    def self.output_path(import)
+      import.annotations["import/outputPath"] || File.join("generated", "#{import.name.gsub(/[^a-zA-Z0-9_-]/, "_")}.yaml")
+    end
+
+    # The files an import wrote, relative to the resources directory: its output path and the `generated/outputs`
+    # of its last run. Tells which import a resource of a generated file comes from.
+    def self.output_files(import)
+      [output_path(import), *import.annotations["generated/outputs"].to_s.split(",").map(&:strip)].reject(&:empty?).uniq
+    end
+
+    # Hash of the files `import/config/inputs` matches (glob patterns relative to the resources directory, comma
+    # separated): their paths, sizes and modification times. nil when the import declares no inputs.
+    # @return [String, nil]
+    def self.inputs_hash(import, resources_dir)
+      patterns = import.annotations["import/config/inputs"].to_s.split(",").map(&:strip).reject(&:empty?)
+      return nil if patterns.empty?
+
+      root = File.expand_path(resources_dir)
+      files = patterns.flat_map { |pattern| Dir.glob(pattern, base: root) }.uniq.sort
+      stats = files.filter_map do |file|
+        stat = File.stat(File.join(root, file))
+        "#{file}:#{stat.size}:#{stat.mtime.to_f}" if stat.file?
+      end
+      require "digest"
+      Digest::SHA256.hexdigest(stats.join("\n"))[0, 16]
+    end
+
+    # Whether a `import/dependsOn` entry is a glob pattern (`Import:Repo:*`)
+    def self.pattern?(entry)
+      entry.match?(/[*?\[]/)
+    end
+
+    # Whether an import name matches a `import/dependsOn` entry
+    def self.dependency_match?(entry, name)
+      pattern?(entry) ? File.fnmatch?(entry, name, File::FNM_EXTGLOB) : entry == name
+    end
   end
 end
 
 require_relative "import/registry"
 require_relative "import/handler"
 require_relative "import/executor"
-# Handlers are loaded by CLI's require_import_handlers method
+require_relative "import/handler_loader"

data/lib/archsight/linter/structure.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module Archsight
+  class Linter
+    # Structural checks over the declared relations, the rules of "Choosing the Kind" and "Choosing the Kind:
+    # Infrastructure" in the modeling guide. All findings are warnings: they point at modeling decisions to review and
+    # have legitimate exceptions (internal services, capabilities that no product carries yet).
+    class Structure
+      # Network types that run over another network and need one that serves them
+      OVERLAY_TYPES = %w[overlay vpn].freeze
+      NETWORK_DEVICE_TYPES = %w[switch router].freeze
+
+      def initialize(database)
+        @database = database
+      end
+
+      # Findings in a stable order, each starting with the path reference of the resource
+      def warnings
+        [
+          component_in_several_services,
+          artifact_in_several_components,
+          service_with_same_named_component,
+          product_without_service,
+          service_reached_from_nothing,
+          capability_without_product,
+          generated_component_in_several_repositories,
+          link_not_between_two_facilities,
+          overlay_without_underlay,
+          facility_without_location,
+          equipment_without_facility,
+          device_without_facility,
+          device_connected_to_itself,
+          network_device_realizing_no_network,
+          device_served_apart_from_its_equipment
+        ].flatten.sort
+      end
+
+      private
+
+      def instances(kind)
+        @database.instances_by_kind(kind).values
+      end
+
+      def targets(instance, verb, key)
+        instance.relations(verb, key)
+      end
+
+      def warning(instance, message)
+        "#{instance.path_ref}: #{instance.klass} '#{instance.name}' #{message}"
+      end
+
+      def names(list)
+        list.map { |item| "'#{item.name}'" }.join(", ")
+      end
+
+      # { target => [owners that list it under verb/key] } for the instances of `kind`
+      def owners_by_target(kind, verb, key)
+        owners = Hash.new { |hash, target| hash[target] = [] }
+        instances(kind).each { |owner| targets(owner, verb, key).each { |target| owners[target] << owner } }
+        owners
+      end
+
+      def component_in_several_services
+        shared("ApplicationService", :realizedThrough, :applicationComponents, "services")
+      end
+
+      def artifact_in_several_components
+        shared("ApplicationComponent", :realizedThrough, :technologyArtifacts, "components")
+      end
+
+      def shared(kind, verb, key, plural)
+        owners_by_target(kind, verb, key).filter_map do |target, owners|
+          next if owners.length < 2
+
+          warning(target, "is realized by #{owners.length} #{plural}: #{names(owners.sort_by(&:name))}")
+        end
+      end
+
+      def service_with_same_named_component
+        instances("ApplicationService").filter_map do |service|
+          components = targets(service, :realizedThrough, :applicationComponents)
+          next unless components.length == 1 && components.first.name == service.name
+
+          warning(service, "has one component with the same name")
+        end
+      end
+
+      def product_without_service
+        instances("BusinessProduct").filter_map do |product|
+          next unless targets(product, :servedBy, :applicationServices).empty?
+
+          warning(product, "is served by no ApplicationService")
+        end
+      end
+
+      # A service is reached when a product or process is served by it, directly or through services that depend on it
+      def service_reached_from_nothing
+        reached = reached_services
+        instances("ApplicationService").filter_map do |service|
+          next if reached.include?(service)
+
+          warning(service, "is not served to any product or process")
+        end
+      end
+
+      def reached_services
+        reached = []
+        queue = (instances("BusinessProduct") + instances("BusinessProcess")).flat_map { |item| targets(item, :servedBy, :applicationServices) }
+        until queue.empty?
+          service = queue.shift
+          next if reached.include?(service)
+
+          reached << service
+          queue.concat(targets(service, :dependsOn, :applicationServices))
+        end
+        reached
+      end
+
+      def capability_without_product
+        realized = owners_by_target("BusinessProduct", :realizes, :strategyCapabilities)
+        instances("StrategyCapability").filter_map do |capability|
+          next if realized.key?(capability)
+
+          warning(capability, "is realized by no product")
+        end
+      end
+
+      # A generated component realized by several repositories is two components merged into one: the repositories
+      # declare the same module path. A re-import gives each its own name (GoModuleParser#owned_component_name).
+      def generated_component_in_several_repositories
+        instances("ApplicationComponent").filter_map do |component|
+          next unless component.annotations.key?("generated/script")
+
+          repositories = targets(component, :realizedThrough, :technologyArtifacts).select { |a| a.name.start_with?("Repo:") }
+          next if repositories.length < 2
+
+          warning(component, "is generated from #{repositories.length} repositories with the same module path: " \
+                             "#{names(repositories.sort_by(&:name))}")
+        end
+      end
+
+      # ---- infrastructure
+
+      def link_not_between_two_facilities
+        instances("TechnologyEquipment").filter_map do |equipment|
+          next unless equipment.annotations["equipment/type"] == "link"
+
+          count = targets(equipment, :locatedAt, :technologyFacilities).length
+          next if count == 2
+
+          warning(equipment, "is a link located at #{count} #{count == 1 ? "facility" : "facilities"}, not 2")
+        end
+      end
+
+      def overlay_without_underlay
+        instances("TechnologyCommunicationNetwork").filter_map do |network|
+          type = network.annotations["network/type"]
+          next unless OVERLAY_TYPES.include?(type)
+          next unless targets(network, :servedBy, :technologyCommunicationNetworks).empty?
+
+          warning(network, "is #{type == "overlay" ? "an" : "a"} #{type} network served by no network")
+        end
+      end
+
+      # Only the outermost facility needs a location; nested halls inherit it from their campus
+      def facility_without_location
+        nested = owners_by_target("TechnologyFacility", :composedOf, :technologyFacilities)
+        instances("TechnologyFacility").filter_map do |facility|
+          next if nested.key?(facility) || targets(facility, :locatedAt, :locations).any?
+
+          warning(facility, "is located at no Location")
+        end
+      end
+
+      # TechnologyEquipment that is part of other equipment is placed through its whole, and a whole (a backbone) through its
+      # parts (the links)
+      def equipment_without_facility
+        parts = owners_by_target("TechnologyEquipment", :composedOf, :technologyEquipment)
+        instances("TechnologyEquipment").filter_map do |equipment|
+          next if parts.key?(equipment) || targets(equipment, :composedOf, :technologyEquipment).any?
+          next if targets(equipment, :locatedAt, :technologyFacilities).any?
+
+          warning(equipment, "is located at no TechnologyFacility")
+        end
+      end
+
+      # A device that is part of equipment (a rack) or of another device (a virtual chassis) is placed through its
+      # whole, and a chassis through its members
+      def device_without_facility
+        parts = owners_by_target("TechnologyDevice", :composedOf, :technologyDevices)
+        racked = owners_by_target("TechnologyEquipment", :composedOf, :technologyDevices)
+        instances("TechnologyDevice").filter_map do |device|
+          next if parts.key?(device) || racked.key?(device) || targets(device, :composedOf, :technologyDevices).any?
+          next if targets(device, :locatedAt, :technologyFacilities).any?
+
+          warning(device, "is located at no TechnologyFacility")
+        end
+      end
+
+      def device_connected_to_itself
+        instances("TechnologyDevice").filter_map do |device|
+          next unless targets(device, :connectedTo, :technologyDevices).include?(device)
+
+          warning(device, "is connectedTo itself")
+        end
+      end
+
+      # The members of a virtual chassis or stack realize the network through the chassis
+      def network_device_realizing_no_network
+        realized = owners_by_target("TechnologyCommunicationNetwork", :realizedBy, :technologyDevices)
+        members = owners_by_target("TechnologyDevice", :composedOf, :technologyDevices)
+        instances("TechnologyDevice").filter_map do |device|
+          type = device.annotations["device/type"]
+          next unless NETWORK_DEVICE_TYPES.include?(type)
+          next if realized.key?(device) || members.key?(device)
+
+          warning(device, "is a #{type} that realizes no TechnologyCommunicationNetwork")
+        end
+      end
+
+      # A device in a partition (equipment servedBy a team) serves that team; one that names another team has been
+      # handed over without moving it. A device that names no team is served through its equipment.
+      def device_served_apart_from_its_equipment
+        holders = owners_by_target("TechnologyEquipment", :composedOf, :technologyDevices)
+        instances("TechnologyDevice").filter_map do |device|
+          teams = targets(device, :servedBy, :businessActors)
+          equipment_teams = holders.fetch(device, []).flat_map { |equipment| targets(equipment, :servedBy, :businessActors) }
+          next if teams.empty? || equipment_teams.empty?
+
+          others = teams - equipment_teams
+          next if others.empty?
+
+          warning(device, "is servedBy #{names(others.sort_by(&:name))}, not by the team of its equipment " \
+                          "(#{names(equipment_teams.uniq.sort_by(&:name))})")
+        end
+      end
+    end
+  end
+end