archsight 0.3.2 → 0.4.0

data/lib/archsight/helpers/embeds.rb

@@ -4,26 +4,37 @@ require "erb"
 
 module Archsight
   module Helpers
-    # Replaces `![[View/Name]]` and `![[Analysis/Name]]` in rendered HTML by a placeholder for the live content of
-    # that view or analysis. The frontend turns each placeholder into the result list or the analysis result (it
-    # loads and runs them itself, so rendering a page never executes a query or a script):
+    # Replaces `![[Kind/Name]]` in rendered HTML by a placeholder for the content of that resource: the result list of
+    # a View, the result of an Analysis, the description of any other resource (a goal, a capability, ...). The
+    # frontend turns each placeholder into that content (it loads and runs it itself, so rendering a page never
+    # executes a query or a script):
     #
     #   <div class="kind-embed" data-kind="View" data-name="View:Services"><a href="/kinds/View/instances/...">...</a></div>
     #
     # The link inside is what API and MCP consumers (and a browser without script) get. A reference that does not
-    # name an existing View or Analysis renders as a `broken-link` marker. Code (`<pre>`, `<code>`) is left alone.
+    # name an existing resource (or names a page) renders as a `broken-link` marker. Code (`<pre>`, `<code>`) is
+    # left alone.
     class Embeds
-      KINDS = %w[View Analysis].freeze
+      # Embeds with live content; every other kind shows its description
+      LIVE_KINDS = %w[View Analysis].freeze
+      # Pages and menus are not resources with a description
+      NOT_EMBEDDABLE = %w[Page PageMenu].freeze
       PATTERN = /!\[\[([^\]|]+)\]\]/
       PARAGRAPH = %r{<p>\s*(#{PATTERN.source})\s*</p>}
       CODE = %r{(<pre\b.*?</pre>|<code\b.*?</code>)}m
 
       REASONS = {
-        kind: "only #{KINDS.join(" and ")} can be embedded, written View/Name or Analysis/Name",
+        kind: "embed a resource as Kind/Name (a View, an Analysis or the description of any other resource); " \
+              "pages cannot be embedded",
         missing: "no such resource",
         ambiguous: "ambiguous reference"
       }.freeze
 
+      # Whether `![[kind/...]]` can be embedded: a known kind that is not a page
+      def self.embeddable_kind?(kind)
+        !Archsight::Resources[kind].nil? && !NOT_EMBEDDABLE.include?(Archsight::Resources.canonical(kind))
+      end
+
       def initialize(database, resolver: ResourceResolver.new(database))
         @database = database
         @resolver = resolver
@@ -66,7 +77,7 @@ module Archsight
       # @return [Array(Array(String, String), Symbol)] kind and name, and the problem (nil if it is embeddable)
       def check(reference)
         kind, name = reference.split("/", 2)
-        return [[kind, name], :kind] unless name && KINDS.include?(kind)
+        return [[kind, name], :kind] unless name && self.class.embeddable_kind?(kind)
 
         problem = @resolver.call(reference)
         [[kind, name], problem.is_a?(Symbol) ? problem : nil]

data/lib/archsight/helpers/resource_resolver.rb

@@ -32,6 +32,31 @@ module Archsight
         matches.first
       end
 
+      # What an annotation that names another resource (`lifecycle/replacedBy`) refers to. A bare `Name` is a
+      # resource of the same kind as the annotated one, another kind needs `Kind/Name`.
+      # @param value [String] the annotation value
+      # @param kind [String] the kind of the annotated resource
+      # @return [Array(String, String), Symbol] `[kind, name]`, or `:missing`
+      def find_annotated(value, kind)
+        reference = value.to_s.strip
+        found = find(reference.include?("/") ? reference : "#{kind}/#{reference}")
+        found.is_a?(Array) ? found : :missing
+      end
+
+      # Where the annotations of a resource that name another resource point to:
+      # `{ key => page path }`, `nil` for a reference that does not resolve.
+      # @param kind [String] the kind of the annotated resource, which knows the annotation formats
+      # @param annotations [Hash]
+      def annotation_links(kind, annotations)
+        klass = Archsight::Resources[kind]
+        annotations.each_with_object({}) do |(key, value), links|
+          next unless klass&.annotation_format(key) == :resource
+
+          found = find_annotated(value, kind)
+          links[key] = found.is_a?(Array) ? path(*found) : nil
+        end
+      end
+
       private
 
       def in_kind(kind, name)

data/lib/archsight/import/executor.rb

@@ -38,7 +38,9 @@ class Archsight::Import::Executor
   # @param output [IO] Output stream for progress (default: $stdout)
   # @param filter [String, nil] Regex pattern to match import names
   # @param force [Boolean] Whether to bypass cache and re-run all imports
-  def initialize(database:, resources_dir:, verbose: false, max_concurrent: MAX_CONCURRENT, output: $stdout, filter: nil, force: false)
+  # @param deps [Boolean] With a filter, also run the imports the matched ones depend on (false: only the matched ones)
+  def initialize(database:, resources_dir:, verbose: false, max_concurrent: MAX_CONCURRENT, output: $stdout, filter: nil, force: false,
+                 deps: true)
     @database = database
     @resources_dir = resources_dir
     @verbose = verbose
@@ -47,7 +49,10 @@ class Archsight::Import::Executor
     @filter = filter
     @filter_regex = Regexp.new(filter, Regexp::IGNORECASE) if filter
     @force = force
+    @deps = deps
     @executed_this_run = Set.new
+    @ran_this_run = Set.new
+    @handler_problems = {}
     @iteration = 0
     @mutex = Mutex.new
   end
@@ -154,18 +159,24 @@ class Archsight::Import::Executor
     sorted = topological_sort(filtered_imports)
 
     @output.puts "Filter: #{@filter}" if @filter
+    @output.puts "Dependencies: not run (--no-deps)" if only_matches?
 
     sorted.each_with_index do |imp, idx|
       enabled = import_enabled?(imp)
       deps = import_dependency_names(imp)
       deps_str = deps.empty? ? "(no dependencies)" : "depends on: #{deps.join(", ")}"
       enabled_str = enabled ? "" : " [DISABLED]"
-      @output.puts "  #{idx + 1}. #{imp.name}#{enabled_str} #{deps_str}"
+      @output.puts "  #{idx + 1}. #{imp.name}#{enabled_str} #{deps_str}#{unmatched_patterns_note(imp)}"
     end
 
     sorted
   end
 
+  # Names of the imports that executed in this run (not served from the cache)
+  def ran_imports
+    @mutex.synchronize { @ran_this_run.to_a.sort }
+  end
+
   private
 
   # Set up signal handlers for graceful shutdown
@@ -222,7 +233,13 @@ class Archsight::Import::Executor
     @imports_to_run.include?(import.name)
   end
 
-  # Compute the full set of imports to run: filtered imports + all their dependencies
+  # Whether only the imports matching the filter run (`-f` with `--no-deps`)
+  def only_matches?
+    !@deps && !@filter_regex.nil?
+  end
+
+  # Compute the full set of imports to run: filtered imports + all their dependencies (only the filtered ones with
+  # `--no-deps`)
   def compute_imports_to_run
     all_imports = database.instances_by_kind("Import")&.values || []
     imports_by_name = all_imports.to_h { |imp| [imp.name, imp] }
@@ -230,6 +247,7 @@ class Archsight::Import::Executor
     # Start with imports matching the filter
     matching = all_imports.select { |imp| @filter_regex.match?(imp.name) }.map(&:name)
     to_run = Set.new(matching)
+    return to_run unless @deps
 
     # Recursively add dependencies
     queue = matching.dup
@@ -249,9 +267,12 @@ class Archsight::Import::Executor
     to_run
   end
 
-  # Check if all dependencies of an import are satisfied (executed successfully this run)
+  # Check if all dependencies of an import are satisfied (executed successfully this run).
+  # A parent that can never run (no handler or disabled, e.g. the repository was
+  # deleted upstream and only its generated `generates` entry is left) is not
+  # waited for, otherwise its children would deadlock the run.
   def dependencies_satisfied?(import)
-    dep_names = import_dependency_names(import)
+    dep_names = runnable_dependency_names(import)
     return true if dep_names.empty?
 
     @mutex.synchronize do
@@ -261,30 +282,81 @@ class Archsight::Import::Executor
     end
   end
 
-  # Get dependency names for an import by finding parents that generate this import
-  # Dependencies are derived from the inverse of `generates` - if Import A generates Import B,
-  # then B depends on A
+  # With `--no-deps` a dependency outside the run is not waited for: it does not run, so the import uses the model
+  # as it is
+  def runnable_dependency_names(import)
+    imports_by_name = (database.instances_by_kind("Import")&.values || []).to_h { |imp| [imp.name, imp] }
+    import_dependency_names(import).select do |dep_name|
+      parent = imports_by_name[dep_name]
+      parent && import_enabled?(parent) && (!only_matches? || import_matches_filter?(parent))
+    end
+  end
+
+  # Get dependency names for an import: the parents that generate it (the inverse of `generates` - if Import A
+  # generates Import B, then B depends on A) and the imports it declares in `import/dependsOn`
   def import_dependency_names(import)
-    # Find all imports that have this import in their generates.imports
     all_imports = database.instances_by_kind("Import")&.values || []
     parent_imports = all_imports.select do |parent|
-      generated = parent.relations(:generates, :imports)
-      generated&.any? { |gen| (gen.is_a?(String) ? gen : gen.name) == import.name }
+      generated_import_names(parent).include?(import.name)
+    end
+    (parent_imports.map(&:name) + declared_dependency_names(import, all_imports)).uniq
+  end
+
+  # The imports `import/dependsOn` names or matches. For a pattern this also includes the imports that may still
+  # generate a matching import in this run: one whose last run generated a match, and one that never ran but whose
+  # handler generates imports. So `Import:Repo:*` waits for the GitHub import and then for the repositories it found.
+  def declared_dependency_names(import, all_imports = database.instances_by_kind("Import")&.values || [])
+    entries = Archsight::Import.declared_dependencies(import)
+    return [] if entries.empty?
+
+    others = all_imports.reject { |imp| imp.name == import.name }
+    entries.flat_map do |entry|
+      matches = others.select { |imp| Archsight::Import.dependency_match?(entry, imp.name) }
+      matches += others.select { |imp| may_generate_match?(imp, entry) } if Archsight::Import.pattern?(entry)
+      matches.map(&:name)
+    end.uniq
+  end
+
+  # Whether an import generated a match of the pattern in its last run, or may do so on its first one
+  def may_generate_match?(import, pattern)
+    generated = generated_import_names(import)
+    return generated.any? { |name| Archsight::Import.dependency_match?(pattern, name) } if generated.any?
+
+    handler = Archsight::Import::Registry[import.annotations["import/handler"]]
+    !import.annotations["generated/at"] && handler.respond_to?(:generates_imports?) && handler.generates_imports?
+  end
+
+  def generated_import_names(import)
+    (import.relations(:generates, :imports) || []).map { |gen| gen.is_a?(String) ? gen : gen.name }
+  end
+
+  # For the plan: patterns of `import/dependsOn` that match no import yet
+  def unmatched_patterns_note(import)
+    all_names = (database.instances_by_kind("Import")&.keys || []) - [import.name]
+    unmatched = Archsight::Import.declared_dependencies(import).select do |entry|
+      Archsight::Import.pattern?(entry) && all_names.none? { |name| Archsight::Import.dependency_match?(entry, name) }
     end
-    parent_imports.map(&:name)
+    unmatched.empty? ? "" : " (#{unmatched.join(", ")} matches no import yet)"
   end
 
-  # Reload database without verbose output
+  # Reload database without verbose output, and load the handlers the imports declare (`import/handlerPath`)
   def reload_database_quietly!
     original_verbose = database.verbose
     database.verbose = false
     database.reload!
+    load_local_handlers
     # Reset filter cache since new imports may have been discovered
     @imports_to_run = nil if @filter_regex
   ensure
     database.verbose = original_verbose
   end
 
+  # A handler file that does not load fails the imports that use it, not the whole run
+  def load_local_handlers
+    problems = Archsight::Import::HandlerLoader.load(database, resources_dir: resources_dir)
+    @handler_problems = problems.to_h { |problem| [problem.import.name, problem.message] }
+  end
+
   # Reload database and update progress total for newly discovered imports
   def reload_and_update_total!
     reload_database_quietly!
@@ -315,6 +387,8 @@ class Archsight::Import::Executor
           result = execute_single_import(imp, slot_progress)
           if result == :cached
             slot_progress.complete("Cached")
+          elsif result.is_a?(String)
+            slot_progress.complete(result)
           else
             @mutex.synchronize { @total_executed += 1 }
             slot_progress.complete("Done")
@@ -339,7 +413,7 @@ class Archsight::Import::Executor
   end
 
   # Execute a single import (called from thread)
-  # @return [Symbol] :executed, :cached, or raises on error
+  # @return [Symbol, String] :executed, :cached, a message for a skipped import, or raises on error
   def execute_single_import(import, import_progress)
     # Check if import is still fresh based on generated/at and import/cacheTime
     if import_fresh?(import)
@@ -347,6 +421,18 @@ class Archsight::Import::Executor
       return :cached
     end
 
+    problem = @handler_problems[import.name]
+    raise Archsight::Import::UnknownHandlerError, problem if problem
+
+    missing = missing_environment(import)
+    if missing.any?
+      message = "missing environment variable#{"s" if missing.length > 1} #{missing.join(", ")} (import/config/requiredEnv)"
+      raise Archsight::Import::ImportError, message unless import.annotations["import/config/optional"] == "true"
+
+      import_progress.warn("Skipped: #{message}")
+      return "Skipped"
+    end
+
     # Execute the import
     handler_class = Archsight::Import::Registry.handler_for(import)
     handler = handler_class.new(
@@ -357,12 +443,30 @@ class Archsight::Import::Executor
       shared_writer: @shared_writer
     )
     handler.execute
+    remove_stale_outputs(import, handler.owned_outputs)
+    @mutex.synchronize { @ran_this_run.add(import.name) }
     :executed
   end
 
+  # Variables of `import/config/requiredEnv` that are not set (or blank)
+  def missing_environment(import)
+    names = import.annotations["import/config/requiredEnv"].to_s.split(",").map(&:strip).reject(&:empty?)
+    names.select { |name| ENV[name].to_s.strip.empty? }
+  end
+
+  # Delete the files an earlier run of the import wrote (`generated/outputs`) that this run did not write again
+  def remove_stale_outputs(import, written)
+    previous = import.annotations["generated/outputs"].to_s.split(",").map(&:strip).reject(&:empty?)
+    (previous - written).each do |rel_path|
+      path = Archsight::Import.resources_path(resources_dir, rel_path)
+      FileUtils.rm_f(path) if path && File.file?(path)
+    end
+  end
+
   # Check if import is still fresh (cached)
-  # Uses generated/at annotation and import/cacheTime to determine freshness
-  # Also validates that output file exists (if specified) and source file hasn't changed
+  # Uses generated/at annotation and import/cacheTime to determine freshness. The cache is also invalid when the
+  # output file or a recorded output (`generated/outputs`) is missing, the configuration or the files of
+  # `import/config/inputs` changed, or an import it declares in `import/dependsOn` executed in this run.
   def import_fresh?(import)
     # Honor force flag - always re-run when forced
     return false if @force
@@ -377,6 +481,11 @@ class Archsight::Import::Executor
       return false unless File.exist?(full_path)
     end
 
+    return false unless recorded_outputs_exist?(import)
+    return false if dependency_ran?(import)
+    return false if import.annotations["import/config/inputs"] &&
+                    import.annotations["generated/inputsHash"] != Archsight::Import.inputs_hash(import, resources_dir)
+
     generated_at = import.annotations["generated/at"]
     return false if generated_at.nil? || generated_at.empty?
 
@@ -399,6 +508,20 @@ class Archsight::Import::Executor
     false
   end
 
+  def recorded_outputs_exist?(import)
+    import.annotations["generated/outputs"].to_s.split(",").map(&:strip).reject(&:empty?).all? do |rel_path|
+      path = Archsight::Import.resources_path(resources_dir, rel_path)
+      path && File.exist?(path)
+    end
+  end
+
+  # Whether an import declared in `import/dependsOn` executed (not just came from the cache) in this run. The
+  # generated imports of a parent are not affected: they keep their own cache time when the parent runs.
+  def dependency_ran?(import)
+    names = declared_dependency_names(import)
+    @mutex.synchronize { names.any? { |name| @ran_this_run.include?(name) } }
+  end
+
   def parse_duration(str)
     return nil if str.nil?
 

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