wayfinding 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ad2f192ae238999788d4d63f9ae53e60f5897f76ea841c4d6a44292b181a7f5c
+  data.tar.gz: acd21e66e0788c34ed59b4e4f83239fa9d4f8a3004756b0d5bb7d2c0584c9ee0
+SHA512:
+  metadata.gz: cc7e58f174db34dd517d2e7aa7f1f90797f6de157ac0a2b8bce3a26d000ff9abf52358b0c27acb7fe1c6eccc55dd93d22515133d0cfc12fb50d20c18e85fbe02
+  data.tar.gz: 49161506abc7526fe2276ad34b329e0828a8c5f873b042590c1c2ddd3b91833138e61d8717814a6a012ab73f35f02340a74aa42f89d379182af64822336dcddb

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new(:rubocop)
+
+task default: %i[rubocop spec]

data/docs/README.md

@@ -0,0 +1,137 @@
+# Wayfinding
+
+Cross-application URL resolution.
+
+Wayfinding is a global registry of named destinations. It lets one component link to a route owned by
+another without depending on that component.
+
+Links are not functionality. No component should acquire a dependency because it renders an anchor tag.
+
+## Why
+
+Without a registry, a component that links to another component's page must reach into that engine's
+`url_helpers`, depend on the owner just for the link, or hardcode the path. Each option couples the caller
+to the route's current owner or location; a hardcoded path can also break silently.
+
+Wayfinding gives one accessor and one registration. Moving a route becomes a one-line change to the
+registration; every call site is untouched.
+
+## Registering
+
+Registration is configuration: every argument is a keyword, so order does not matter. Register from an
+initializer.
+
+```ruby
+Wayfinding.register(
+  name: :home,
+  engine: -> { Homes::Engine },
+  helper: :home_path
+)
+```
+
+`engine:` accepts a lambda or the constant. Prefer the lambda so the engine is resolved lazily.
+
+`helper:` is the common form. Wayfinding derives the corresponding `_url` helper for `url_for`.
+
+For anything that is not a bare helper call, pass a block. Within the block, `self` is the engine's
+`url_helpers` object. That lets the resolver call `results_path(...)` directly instead of repeating
+`Search::Engine.routes.url_helpers.results_path(...)`.
+
+```ruby
+Wayfinding.register(name: :search_results, engine: -> { Search::Engine }) do |query|
+  results_path(q: query)
+end
+```
+
+For `url_for`, calls ending in `_path` inside an engine-backed block are mapped to the corresponding
+`_url` helper. Wayfinding cannot convert an arbitrary path string after the block returns, so a block
+that supports both lookup forms must build its result from route helpers rather than hardcoding a path.
+
+Omit `engine:` for a destination that is not a Rails route. Wayfinding calls the block directly, and
+`path_for` and `url_for` both return its result.
+
+## Looking up
+
+```ruby
+Wayfinding.path_for(:home, home, tab: "activity")
+# => "/homes/17?tab=activity"
+
+Wayfinding.url_for(:home, home)
+# => "https://example.com/homes/17"
+```
+
+Looking up an unregistered destination raises `Wayfinding::UnregisteredDestination`, listing what is
+registered. There is no null object and no production fallback: a missing registration is a boot-state
+bug, not a runtime condition.
+
+## Kinds
+
+A kind is a named field contract. Applications define kinds; Wayfinding only enforces them.
+
+```ruby
+Wayfinding.define_kind(:report, requires: %i[label description action subject])
+
+Wayfinding.register(
+  name: :activity_report,
+  kind: :report,
+  engine: -> { Reports::Engine },
+  helper: :activity_reports_path,
+  action: :view_activity_report,
+  subject: -> { Account },
+  label: "Activity Report",
+  description: "Summarizes recent account activity"
+)
+
+Wayfinding.of_kind(:report).accessible_by(current_ability)
+```
+
+A destination without a kind is still resolvable by `path_for`, but is invisible to `of_kind`. Declaring
+a kind does not remove point lookup, so `path_for(:activity_report)` still works.
+
+`requires:` may name any field. Validation asserts presence only and never resolves callables, so a
+lazily registered `subject: -> { Account }` passes without autoloading the model.
+
+### Destination metadata
+
+Every keyword other than the routing structure is application metadata. Wayfinding does not give fields
+such as `label` or `description` special behavior. Metadata is stored without interpretation and read
+with `#[]`:
+
+```ruby
+destination = Wayfinding.fetch(:activity_report)
+destination[:label]
+destination[:data]
+```
+
+Resolve any callable field lazily with `#value_for`:
+
+```ruby
+destination.value_for(:subject)
+```
+
+`action` and `subject` are metadata with one additional invariant: if either is supplied, both must be.
+`accessible_by(ability)` reads that pair and calls `ability.can?(action, subject)`. Display policy, such as
+falling back from a missing description to a label, belongs to the consuming application.
+
+## Verifying
+
+Assert at boot that every expected destination is registered, so a dropped registration fails the boot
+rather than rendering a broken link.
+
+```ruby
+Wayfinding.verify!(%i[home activity_report])
+```
+
+## Testing
+
+```ruby
+require "wayfinding/rspec"
+```
+
+Each example runs inside `Wayfinding.preserve!`, so anything registered in a spec is rolled back. Use
+`stub_destination` rather than mocking Wayfinding itself.
+
+```ruby
+stub_destination(:home, "/homes/1")
+stub_destination(:home) { |home| "/homes/#{home.id}" }
+```

data/lib/wayfinding/destination.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Wayfinding
+  # A named, engine-scoped URL resolver with arbitrary application metadata.
+  # Metadata is stored without interpretation and read through #[]. Any field
+  # can be resolved lazily through #value_for.
+  class Destination
+    attr_reader :name, :kind, :attributes
+
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(name:, engine: nil, kind: nil, helper: nil, resolver: nil, **attributes)
+      @name = name.to_sym
+      @engine = engine
+      @kind = kind&.to_sym
+      @helper = helper&.to_sym
+      @resolver = resolver
+      @attributes = attributes.freeze
+      freeze
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    def action = self[:action]
+
+    def subject = value_for(:subject)
+
+    def [](key) = attributes[key.to_sym]
+
+    def value_for(key) = resolve(self[key])
+
+    def path(*, **params)
+      return resolver_result(:path, *, **params) unless @helper
+
+      url_helpers.public_send(@helper, *, **params)
+    end
+
+    def url(*, **params)
+      return resolver_result(:url, *, **params) unless @helper
+
+      unless @helper.to_s.end_with?("_path")
+        raise Error, "#{name.inspect} declares helper #{@helper.inspect}, which does not end in `_path`"
+      end
+
+      url_helpers.public_send(@helper.to_s.sub(/_path\z/, "_url"), *, **params)
+    end
+
+    def engine
+      @engine.is_a?(Proc) ? @engine.call : @engine
+    end
+
+  private
+
+    def resolver_result(mode, *, **)
+      return @resolver.call(*, **) unless @engine
+
+      context = mode == :url ? UrlResolverContext.new(url_helpers) : url_helpers
+      context.instance_exec(*, **, &@resolver)
+    end
+
+    def url_helpers
+      engine.routes.url_helpers
+    end
+
+    def resolve(value)
+      value.respond_to?(:call) ? value.call : value
+    end
+  end
+end

data/lib/wayfinding/destination_list.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Wayfinding
+  # The result of Wayfinding.of_kind. An Array of Destination with ability filtering.
+  class DestinationList < Array
+    # Destinations the given ability permits. Destinations without an action are
+    # excluded: there is nothing to authorize against.
+    def accessible_by(ability)
+      self.class.new(select do |destination|
+        destination.action && ability.can?(destination.action, destination.subject)
+      end)
+    end
+  end
+end

data/lib/wayfinding/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Wayfinding
+  Error = Class.new(StandardError)
+
+  # Raised when looking up a destination that was never registered.
+  UnregisteredDestination = Class.new(Error)
+
+  # Raised at registration when a destination is missing fields its kind requires,
+  # or when its resolution strategy is ambiguous or incomplete.
+  InvalidDestination = Class.new(Error)
+
+  # Raised when a destination declares a kind that was never defined.
+  UnknownKind = Class.new(Error)
+end

data/lib/wayfinding/kind.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Wayfinding
+  # A named field contract. Applications define kinds; Wayfinding only enforces them.
+  #
+  #   Wayfinding.define_kind(:report, requires: %i[label description action subject])
+  #
+  # +requires+ may name any field, whether or not Wayfinding gives it behavior.
+  # Validation asserts presence only and never resolves callables, so a lazily
+  # registered <tt>subject: -> { ProjectTask }</tt> passes without autoloading.
+  class Kind
+    attr_reader :name, :requires
+
+    def initialize(name:, requires: [])
+      @name = name.to_sym
+      @requires = Array(requires).map(&:to_sym).freeze
+      freeze
+    end
+
+    def validate!(destination_name, given)
+      missing = requires.reject { |field| given.key?(field) && !given[field].nil? }
+      return if missing.empty?
+
+      raise InvalidDestination,
+            "Destination #{destination_name.inspect} of kind #{name.inspect} " \
+            "is missing required #{missing.length == 1 ? 'field' : 'fields'}: #{missing.join(', ')}"
+    end
+  end
+end

data/lib/wayfinding/rspec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "wayfinding"
+
+module Wayfinding
+  # Spec helpers for applications consuming Wayfinding.
+  #
+  #   require "wayfinding/rspec"
+  #
+  # Each example runs inside Wayfinding.preserve!, so destinations registered in
+  # a spec are rolled back afterwards. Use #stub_destination rather than mocking
+  # Wayfinding itself.
+  module RSpecHelpers
+    # Register a destination that resolves to a fixed value, with no engine or
+    # route helpers involved.
+    #
+    #   stub_destination(:home, "/homes/1")
+    #   stub_destination(:home) { |home| "/homes/#{home.id}" }
+    def stub_destination(name, path = nil, **attributes, &resolver)
+      resolver ||= proc { |*, **| path }
+
+      Wayfinding.register(name: name, **attributes, &resolver)
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include Wayfinding::RSpecHelpers
+
+  config.around do |example|
+    Wayfinding.preserve! { example.run }
+  end
+end

data/lib/wayfinding/url_resolver_context.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Wayfinding
+  # Evaluates a destination block as a URL by delegating route helper calls to
+  # the registered engine and replacing a trailing `_path` with `_url`.
+  class UrlResolverContext
+    def initialize(url_helpers)
+      @url_helpers = url_helpers
+    end
+
+  private
+
+    def method_missing(name, ...)
+      @url_helpers.public_send(url_helper_name(name), ...)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @url_helpers.respond_to?(url_helper_name(name), include_private)
+    end
+
+    def url_helper_name(name)
+      name.to_s.sub(/_path\z/, "_url")
+    end
+  end
+end

data/lib/wayfinding/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Wayfinding
+  VERSION = "0.0.1"
+end

data/lib/wayfinding.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "wayfinding/errors"
+require "wayfinding/kind"
+require "wayfinding/url_resolver_context"
+require "wayfinding/destination"
+require "wayfinding/destination_list"
+require "wayfinding/version"
+
+# Cross-application URL resolution.
+#
+# Any component can link to any page without depending on the component that
+# owns the route. Registered destinations are data, so this module's public
+# surface never grows as destinations are added.
+#
+#   Wayfinding.register(
+#     name: :home,
+#     engine: -> { Projects::Engine },
+#     helper: :home_path
+#   )
+#
+#   Wayfinding.path_for(:home, home, current_tab: "Projects")
+module Wayfinding
+  class << self
+    # Declare a named field contract. See Wayfinding::Kind.
+    def define_kind(name, requires: [])
+      kind = Kind.new(name: name, requires: requires)
+      kinds[kind.name] = kind
+    end
+
+    def kinds = @kinds ||= {}
+
+    def register(name:, engine: nil, kind: nil, helper: nil, **attributes, &resolver)
+      validate_resolution!(name, engine, helper, resolver)
+      validate_all_or_none!(name, attributes, %i[action subject])
+      validate_kind!(name, kind, **attributes)
+
+      destinations[name.to_sym] = Destination.new(
+        name: name, engine: engine, kind: kind, helper: helper, resolver: resolver, **attributes
+      )
+    end
+
+    def path_for(name, *, **params) = fetch(name).path(*, **params)
+
+    def url_for(name, *, **params) = fetch(name).url(*, **params)
+
+    def of_kind(name)
+      name = name.to_sym
+      DestinationList.new(destinations.each_value.select { |destination| destination.kind == name })
+    end
+
+    def fetch(name)
+      destinations.fetch(name.to_sym) do
+        raise UnregisteredDestination,
+              "No destination registered for #{name.inspect}. Registered: #{registered_names.join(', ')}"
+      end
+    end
+
+    def registered?(name) = destinations.key?(name.to_sym)
+
+    def registered_names = destinations.keys.sort
+
+    # Assert every expected destination is registered. Call at the end of an
+    # initializer so a dropped registration fails the boot rather than rendering
+    # a broken link.
+    def verify!(expected)
+      missing = Array(expected).map(&:to_sym) - registered_names
+      return true if missing.empty?
+
+      raise UnregisteredDestination, "Missing destination registrations: #{missing.join(', ')}"
+    end
+
+    # Snapshot the registry, yield, then restore it. Used by the RSpec helper so
+    # a destination registered inside an example does not leak.
+    def preserve!
+      destinations_snapshot = destinations.dup
+      kinds_snapshot = kinds.dup
+      yield
+    ensure
+      @destinations = destinations_snapshot
+      @kinds = kinds_snapshot
+    end
+
+    def reset!
+      @destinations = {}
+      @kinds = {}
+    end
+
+  private
+
+    def destinations = @destinations ||= {}
+
+    def validate_resolution!(name, engine, helper, resolver)
+      raise InvalidDestination, "#{name.inspect} declares both `helper:` and a block; use one" if helper && resolver
+      raise InvalidDestination, "#{name.inspect} declares neither `helper:` nor a block" unless helper || resolver
+      raise InvalidDestination, "#{name.inspect} declares `helper:` without an `engine:`" if helper && engine.nil?
+    end
+
+    def validate_all_or_none!(name, attributes, fields)
+      supplied = fields.reject { |field| attributes[field].nil? }
+      return if supplied.empty? || supplied.length == fields.length
+
+      missing = fields - supplied
+      raise InvalidDestination,
+            "#{name.inspect} must declare #{fields.map { |field| "`#{field}:`" }.join(' and ')} together; " \
+            "missing #{missing.map { |field| "`#{field}:`" }.join(', ')}"
+    end
+
+    def validate_kind!(name, kind, **given)
+      return if kind.nil?
+
+      definition = kinds.fetch(kind.to_sym) do
+        raise UnknownKind, "#{name.inspect} declares unknown kind #{kind.inspect}. Defined: #{kinds.keys.join(', ')}"
+      end
+
+      definition.validate!(name, given)
+    end
+  end
+end

metadata

@@ -0,0 +1,192 @@
+--- !ruby/object:Gem::Specification
+name: wayfinding
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Nitro Developers
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.5.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: license_finder
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.10.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.10.1
+- !ruby/object:Gem::Dependency
+  name: rainbow
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.1.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.1.1
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.15.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.15.1
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.9.38
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.9.38
+description: A global registry of named destinations, so any component can link to
+  any page without depending on the component that owns the route.
+email:
+- dev@powerhrg.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Rakefile
+- docs/README.md
+- lib/wayfinding.rb
+- lib/wayfinding/destination.rb
+- lib/wayfinding/destination_list.rb
+- lib/wayfinding/errors.rb
+- lib/wayfinding/kind.rb
+- lib/wayfinding/rspec.rb
+- lib/wayfinding/url_resolver_context.rb
+- lib/wayfinding/version.rb
+homepage: https://github.com/powerhome/power-tools
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Cross-application URL resolution.
+test_files: []