ace-support-nav 0.28.6 → 0.28.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1948cb2b1085585f1a3ccd40d9fddd0dd130bad2ede2991bb7922ee3dba68143
-  data.tar.gz: 4d822e1cb78a2b43fe641d1a963cc68df74b97cda80004ce87a7520851793cef
+  metadata.gz: ecc4d7ddedfa6c6bb842df8618779d87b1099c1cdb3898749a8d18c77fd47095
+  data.tar.gz: 64cf17332d9eb5a76ccd945d4aef71c57d3b6a428b34dabe924ad532fb3205cc
 SHA512:
-  metadata.gz: 98e6c2d42e54a1b6f272689238ffe9371256446127e22c26120489043e850b036d8438164b3fd4b64caa871391caddda8b6d2fb87222e6a485a6c02e8479902e
-  data.tar.gz: 0b937920845694bf9268b5591793e8f73d51a01fe5f1590fdd26c1e62d5c2437e869a951f012bf37f0ff8bda2a780cf6ef74084d2d07435089affa0df496776f
+  metadata.gz: 1227aa081c832c78abaf75b1ccd0113495f8f103d2530f108e0e5024d331ae79cac87cfbd61a74dfee1ddfaedcd4e40b13cb1991525688acd5b529fd2588834e
+  data.tar.gz: 9ca8ba354761276bfc7b449ed702a5e2f175a4af82127922129671fa1d393897733af48f2a51f1141ee453ebe597a9316c222d7494453af72df4da58c8fadbcb

data/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.28.7] - 2026-09-27
+
+### Technical
+- Resolve temporary test paths through symlinks.
+
+### Added
+- `ace-nav resolve <uri> --why` prints every duplicate candidate in resolution order with its source, priority, and origin, marks the winner, and states the source-priority rule, making override precedence observable without planting probe files.
+
 
 ## [0.28.6] - 2026-09-02
 

data/lib/ace/support/nav/cli/commands/resolve.rb

@@ -39,6 +39,9 @@ module Ace
                 # Display content
                 $ ace-nav resolve wfi://setup --content
 
+                # Explain precedence: all candidates + the rule that picked the winner
+                $ ace-nav resolve wfi://setup --why
+
                 # Wildcard patterns auto-route to list
                 $ ace-nav resolve wfi://*
 
@@ -57,6 +60,8 @@ module Ace
 
                 By default, displays resolved path
                 Use --content to display resource content
+                Use --why to print all candidates in resolution order plus the
+                rule that picked the winner (useful when duplicates exist)
                 Exit codes: 0 (success), 1 (error)
             DESC
 
@@ -71,6 +76,7 @@ module Ace
 
             option :path, type: :boolean, desc: "Display resource path"
             option :content, type: :boolean, desc: "Display resource content"
+            option :why, type: :boolean, desc: "Explain precedence: print all candidates in resolution order and the winner"
             option :tree, type: :boolean, desc: "Display resources in tree format (passed through to cmd protocols)"
             option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
             option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
@@ -103,11 +109,18 @@ module Ace
               if @uri.include?("://")
                 protocol = @uri.split("://").first
                 if @engine.cmd_protocol?(protocol)
+                  if @options[:why]
+                    raise Ace::Support::Cli::Error.new("--why is not available for cmd protocols (#{protocol} delegates to an external command; there are no local candidates)")
+                  end
                   delegator = Organisms::CommandDelegator.new
                   return delegator.delegate(@uri, @options)
                 end
               end
 
+              if @options[:why]
+                return print_explanation(@engine.explain(@uri))
+              end
+
               result = @engine.resolve(@uri, content: @options[:content], verbose: @options[:verbose])
 
               if result.nil?
@@ -127,6 +140,28 @@ module Ace
 
             private
 
+            # Print a precedence explanation produced by NavigationEngine#explain
+            def print_explanation(explanation)
+              if explanation[:candidates].empty?
+                raise Ace::Support::Cli::Error.new("Resource not found: #{@uri}")
+              end
+
+              if @options[:verbose]
+                require "json"
+                puts JSON.pretty_generate(explanation)
+                return
+              end
+
+              puts "uri: #{explanation[:uri]}"
+              puts "rule: #{explanation[:rule]}"
+              puts "candidates (resolution order):"
+              explanation[:candidates].each do |candidate|
+                origin = candidate[:origin] || candidate[:source_type]
+                puts "  #{candidate[:position]}. [priority #{candidate[:priority]}] #{candidate[:source]} (#{origin}) → #{candidate[:path]}"
+                puts "     ← winner" if candidate[:winner]
+              end
+            end
+
             # Normalize bare protocol names (e.g., "wfi") to protocol:// format
             # This allows users to type "ace-nav wfi" instead of "ace-nav wfi://"
             def normalize_protocol_shorthand(uri)

data/lib/ace/support/nav/organisms/navigation_engine.rb

@@ -17,6 +17,15 @@ module Ace
             @path_normalizer = path_normalizer || Atoms::PathNormalizer.new
           end
 
+          # Resolution rule applied when multiple sources register the same resource.
+          # Sources are ordered by ascending priority (lower number = higher precedence)
+          # and the first source containing the resource wins.
+          RESOLUTION_RULE = "Candidates are tried in ascending source-priority order " \
+            "(lower priority number wins); the first source containing the resource is " \
+            "the winner and remaining duplicates are ignored. Registration defaults: " \
+            "project sources 10, user sources 50, gem defaults 100 - individual source " \
+            "registrations may pin other values.".freeze
+
           # Resolve a single resource URI to a path
           def resolve(uri_string, options = {})
             resource = @resource_resolver.resolve(uri_string)
@@ -31,6 +40,28 @@ module Ace
             end
           end
 
+          # Explain resolution precedence for a URI
+          # Returns every candidate in resolution order plus the rule that picked the winner
+          def explain(uri_string)
+            candidates = @resource_resolver.resolve_pattern(uri_string)
+
+            {
+              uri: uri_string,
+              rule: RESOLUTION_RULE,
+              candidates: candidates.each_with_index.map do |resource, index|
+                {
+                  position: index + 1,
+                  winner: index.zero?,
+                  path: resource.path,
+                  source: resource.source.alias_name,
+                  source_type: resource.source.type.to_s,
+                  priority: resource.source.priority,
+                  origin: resource.source.respond_to?(:origin) ? resource.source.origin : nil
+                }
+              end
+            }
+          end
+
           # List resources matching a pattern
           def list(uri_pattern, options = {})
             resources = @resource_resolver.resolve_pattern(uri_pattern)

data/lib/ace/support/nav/version.rb

@@ -3,7 +3,7 @@
 module Ace
   module Support
     module Nav
-      VERSION = "0.28.6"
+      VERSION = "0.28.7"
     end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-support-nav
 version: !ruby/object:Gem::Version
-  version: 0.28.6
+  version: 0.28.7
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-05 00:00:00.000000000 Z
+date: 2026-09-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli