archspec 1.1.0 → 1.2.0

data/lib/archspec/facts/builder.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module ArchSpec
+  module Facts
+    # Framework-neutral facts, established by source semantics or by reflection.
+    # Locations retain the original evidence, even when it lives in a different
+    # file from the owner.
+    #
+    # Owners, sources, and targets can be graph ConstantNodes, constant names,
+    # or the runtime classes and modules themselves. Locations can be
+    # SourceLocations, <tt>[path, line]</tt> pairs such as
+    # <tt>Module#const_source_location</tt> returns, backtrace locations a macro
+    # recorded with +caller_locations+, or anything with a +source_location+:
+    #
+    #   facts.reference(source: Invoice, target: Customer, location: ["app/models/invoice.rb", 3])
+    #   facts.methods(owner: "Invoice", names: %w[customer customer=], location: declaration_site)
+    #
+    # Use #apply for an in-memory semantic pass, or #to_document and Facts.write
+    # for an explicit external producer. Both routes use the same validation and
+    # application code. Building facts never mutates the graph.
+    class Builder
+      MODULE_NAME = Module.instance_method(:name)
+
+      attr_reader :graph, :producer
+
+      def initialize(graph, producer:)
+        @graph = graph
+        @producer = producer.to_s
+        @entries = LIST_KEYS.to_h { |key| [key, []] }
+      end
+
+      def reference(source:, target:, location:)
+        location = location_of(location)
+        source = constant(source, location)
+        add('references', entry_for(source, location).merge('source' => source.name, 'target' => name_of(target)))
+      end
+
+      def methods(owner:, names:, location:, scope: :instance, visibility: :public,
+                  signatures: [], alias_target: nil, mode: :if_missing, installation: nil)
+        unless alias_target.nil? || alias_target.is_a?(String) || alias_target.is_a?(Symbol)
+          raise Error, 'alias target must be a String or Symbol'
+        end
+        location = location_of(location)
+        owner = constant(owner, location)
+        entry = entry_for(owner, location).merge('owner' => owner.name, 'names' => Array(names).map(&:to_s),
+          'scope' => scope.to_s, 'visibility' => visibility.to_s, 'mode' => mode.to_s,
+          'signatures' => signatures.map do |signature|
+            signature.to_h.transform_keys(&:to_s).transform_values do |value|
+              value.is_a?(Array) ? value.map(&:to_s) : value
+            end
+          end)
+        entry['alias_target'] = alias_target.to_s unless alias_target.nil?
+        entry['installation'] = location_for(location_of(installation)) if installation
+        add('methods', entry)
+      end
+
+      # Preserve a source definition's metadata while installing it on an owner.
+      # An installation site gives callback definitions their Ruby precedence:
+      # later local definitions win, earlier definitions are replaced.
+      def method_definition(owner:, definition:, installation: nil)
+        methods(owner: owner, names: [definition.name], scope: definition.scope, location: definition.location,
+          visibility: definition.visibility, signatures: definition.signatures, alias_target: definition.alias_target,
+          mode: installation ? :define : :append, installation: installation)
+      end
+
+      # Emit mixins in installation order, including singleton prepends.
+      def mixin(owner:, target:, kind:, location:)
+        location = location_of(location)
+        owner = constant(owner, location)
+        add('mixins', entry_for(owner, location).merge('owner' => owner.name,
+          'target' => name_of(target), 'kind' => kind.to_s))
+      end
+
+      # Bind an existing receiverless call without changing its lexical owner.
+      # Emit every consumer of a shared callback before applying the batch.
+      def bind_receiver(edge:, receiver:, scope:)
+        source = @graph.constants_named(edge.from_constant).find { |node| node.path == edge.from_path }
+        raise Error, 'receiver fact requires a call owned by an analyzed constant' unless source
+
+        add('receivers', entry_for(source, edge.location).merge('source' => source.name,
+          'name' => edge.to, 'receiver' => name_of(receiver), 'scope' => scope.to_s))
+      end
+
+      def expose_methods(source:, owner:, scope:)
+        source = constant(source, nil)
+        entry = entry_for(source, source.location).merge('source' => source.name,
+          'owner' => name_of(owner), 'scope' => scope.to_s)
+        owners = @graph.constants_named(name_of(owner)).map { |node| relative(node.path) }.uniq - [entry['source_path']]
+        entry['depends_on'] = owners.sort unless owners.empty?
+        add('exposures', entry)
+      end
+
+      def gap(source:, message:, location:)
+        location = location_of(location)
+        source = constant(source, location)
+        add('gaps', entry_for(source, location).merge('source' => source.name, 'message' => message))
+      end
+
+      # Settle a static analysis gap this producer observed, such as a
+      # conditional concern callback. The location is the gap's own location.
+      # Pass the +consumers+ you inspected when the gap is about a module's
+      # includers: their files are fingerprinted, and a check reports any
+      # includer added later instead of keeping the gap settled.
+      def resolve(source:, location:, message: nil, consumers: nil)
+        location = location_of(location)
+        source = constant(source, location)
+        entry = entry_for(source, location).merge('source' => source.name)
+        entry['message'] = message if message
+        if consumers
+          nodes = consumers.map { |consumer| constant(consumer, nil) }
+          entry['consumers'] = nodes.map(&:name).uniq.sort
+          paths = nodes.map { |node| relative(node.path) }.uniq - [entry['source_path'], entry['path']]
+          entry['depends_on'] = paths.sort unless paths.empty?
+        end
+        add('resolves', entry)
+      end
+
+      def apply
+        document = Document.new(@graph, facts, @producer)
+        Application.apply(@graph, [document.compile.with(producer: nil)])
+      end
+
+      # Validate before publication, so malformed evidence cannot replace a
+      # producer's previous snapshot. +inputs+ are global files whose change
+      # invalidates the whole document; +sources+ are patterns of analyzed
+      # files whose change invalidates the facts they cite. +env+ records
+      # environment variables that must match when a check sets them.
+      def to_document(facts_path: 'archspec_facts', inputs: DEFAULT_INPUTS, sources: [], env: {})
+        cited = @entries.values.flatten.flat_map do |entry|
+          [entry['path'], entry['source_path'], entry.dig('installation', 'path'), *entry['depends_on']]
+        end.compact.uniq.map { |path| File.expand_path(path, @graph.root) }
+        document = { 'version' => VERSION, 'producer' => @producer,
+                     'env' => env.to_h { |name, value| [name.to_s, value.to_s] },
+                     'inputs' => inputs.map(&:to_s), 'sources' => sources.map(&:to_s),
+                     'snapshot' => Facts.fingerprint(@graph, inputs: inputs, sources: sources, cited: cited,
+                                                     excluding: facts_path) }.merge(facts)
+        reader = Document.new(@graph, document, @producer)
+        Application.validate(@graph, [reader.compile])
+        document
+      end
+
+      def count(key)
+        @entries.fetch(key.to_s).size
+      end
+
+      private
+
+      def add(key, entry)
+        @entries[key] << entry
+        entry
+      end
+
+      def facts
+        { 'version' => VERSION, 'producer' => @producer }.merge(@entries.transform_values(&:uniq))
+      end
+
+      def constant(value, location)
+        return value if value.is_a?(ConstantNode)
+
+        name = name_of(value)
+        nodes = @graph.constants_named(name)
+        raise Error, "#{name} is not an analyzed constant" if nodes.empty?
+
+        candidates = [
+          nodes.select { |node| location && node.path == location.path },
+          nodes.reject(&:namespace_only),
+          nodes
+        ]
+        match = candidates.find(&:one?)
+        raise Error, "#{name} is defined in several files; pass its graph node instead" unless match
+
+        match.first
+      end
+
+      def name_of(value)
+        name = case value
+               when Module then MODULE_NAME.bind_call(value)
+               when ConstantNode then value.name
+               else value.to_s
+               end
+        raise Error, 'facts cannot name an anonymous class or module' if name.nil? || name.empty?
+
+        name.delete_prefix('::')
+      end
+
+      def location_of(value)
+        value = value.source_location if value.respond_to?(:source_location)
+        value = [value.path, value.lineno] if value.respond_to?(:lineno) && value.respond_to?(:path)
+        case value
+        when SourceLocation
+          value
+        when Array
+          path, line = value
+          raise Error, "invalid location #{value.inspect}" unless path && line.is_a?(Integer) && line.positive?
+
+          line_location(File.expand_path(path.to_s, @graph.root), line)
+        else
+          raise Error, "invalid location #{value.inspect}"
+        end
+      end
+
+      # A line given without columns spans its code, so diagnostics underline
+      # the declaration rather than the indentation before it.
+      def line_location(path, line)
+        text = File.file?(path) ? File.foreach(path).drop(line - 1).first.to_s.chomp : ''
+        start = (text.index(/\S/) || 0) + 1
+        SourceLocation.new(path, line, start, line, [text.rstrip.bytesize + 1, start].max)
+      end
+
+      def entry_for(source, location)
+        location_for(location).merge('source_path' => relative(source.path))
+      end
+
+      def location_for(location)
+        location.to_h.transform_keys(&:to_s).merge('path' => relative(location.path))
+      end
+
+      def relative(path)
+        Pathname(path).relative_path_from(Pathname(@graph.root)).to_s
+      end
+    end
+  end
+end

data/lib/archspec/facts/document.rb

@@ -0,0 +1,367 @@
+# frozen_string_literal: true
+
+module ArchSpec
+  module Facts
+    # Decodes a complete batch before any graph mutation. Both the in-memory
+    # builder and external YAML documents must satisfy this contract.
+    class Document
+      LOCATION_KEYS = %w[path line column end_line end_column].freeze
+      ENTRY_LOCATION_KEYS = LOCATION_KEYS + %w[source_path depends_on]
+      LEGACY_LIST_KEYS = %w[references methods gaps].freeze
+      LEGACY_ENVELOPE_KEYS = %w[version producer environment snapshot].freeze
+      ENVELOPE_KEYS = %w[version producer env inputs sources snapshot].freeze
+      METHOD_KEYS = %w[visibility signatures alias_target mode installation].freeze
+      SCOPES = %w[instance class].freeze
+
+      def initialize(graph, document, label)
+        @graph = graph
+        @document = document
+        @label = label
+        @lines = {}
+        @stale = Set.new
+        @removed = Set.new
+      end
+
+      # Compiles an imported document, or returns nil when it no longer
+      # describes the source. Stale files are reported and their facts skipped.
+      def compile_fresh(excluding:)
+        validate_envelope
+        invalid('version 2 facts require a snapshot') if @document['version'] != 1 && @document['snapshot'].nil?
+        reason = @document['version'] == 1 ? legacy_staleness(excluding) : staleness(excluding)
+        if reason
+          stale_diagnostic(@label, "#{producer} facts are out of date: #{reason}; run `archspec reflect`")
+          return
+        end
+
+        @stale.each do |path|
+          stale_diagnostic(path, "#{producer} facts are out of date for this file; run `archspec reflect`")
+        end
+        compile
+      end
+
+      def compile
+        validate_envelope
+        Operations.new(*LIST_KEYS.map do |key|
+          Array(@document[key]).reject { |entry| stale_entry?(entry) }
+                               .flat_map do |entry|
+                                 validate_dependencies(entry)
+                                 public_send("decode_#{key}", entry)
+                               end
+        end, producer)
+      end
+
+      def decode_references(entry)
+        validate_entry(entry, %w[source target])
+        Reference.new(source_for(entry, 'source'), constant_name(entry['target']), location_for(entry))
+      end
+
+      def decode_methods(entry)
+        validate_entry(entry, %w[owner scope names] + (@document['version'] == 1 ? [] : METHOD_KEYS))
+        owner = source_for(entry, 'owner')
+        location = location_for(entry)
+        scope = enum(entry['scope'], SCOPES, 'method scope')
+        names = string_list(entry['names'], 'method names', nonempty: true)
+        visibility = enum(entry.fetch('visibility', 'public'), %w[public protected private], 'method visibility')
+        mode = enum(entry.fetch('mode', 'if_missing'), %w[if_missing append define], 'method mode')
+        installation = entry['installation']
+        if mode == :define
+          invalid('define mode requires an installation location') unless installation.is_a?(Hash)
+          invalid('invalid installation fields') unless (installation.keys - LOCATION_KEYS).empty?
+          installation = location_for(installation)
+        elsif !installation.nil?
+          invalid('installation requires define mode')
+        end
+        signatures = entry.fetch('signatures', [])
+        invalid('expected a list of signatures') unless signatures.is_a?(Array)
+        signatures = signatures.map { |signature| signature_for(signature) }
+        alias_target = entry['alias_target']
+        string(alias_target, 'alias target') unless alias_target.nil?
+        names.map do |name|
+          definition = MethodDefinition.new(owner.name, name.to_sym, scope, location, visibility, signatures, alias_target&.to_sym)
+          Method.new(owner, definition, mode, installation)
+        end
+      end
+
+      def decode_mixins(entry)
+        validate_entry(entry, %w[owner target kind])
+        Mixin.new(source_for(entry, 'owner'), constant_name(entry['target']),
+          enum(entry['kind'], %w[include prepend extend singleton_prepend], 'mixin kind'), location_for(entry))
+      end
+
+      def decode_receivers(entry)
+        validate_entry(entry, %w[source name receiver scope])
+        source = source_for(entry, 'source')
+        name = string(entry['name'], 'call name')
+        location = location_for(entry)
+        unless receiverless_calls.include?([source.name, source.path, name, location])
+          invalid('receiver binding must identify an existing receiverless call with its complete source range')
+        end
+        Receiver.new(source, name, location, constant_name(entry['receiver']), enum(entry['scope'], SCOPES, 'receiver scope'))
+      end
+
+      def decode_exposures(entry)
+        validate_entry(entry, %w[source owner scope])
+        source = source_for(entry, 'source')
+        location_for(entry)
+        invalid('method exposure source must be a module') unless source.module?
+        owner = constant_name(entry['owner'])
+        invalid("method exposure owner #{owner} is not analyzed") if @graph.constants_named(owner).empty?
+        Exposure.new(source, owner, enum(entry['scope'], SCOPES, 'exposure scope'))
+      end
+
+      def decode_gaps(entry)
+        validate_entry(entry, %w[source message])
+        Gap.new(source_for(entry, 'source'), string(entry['message'], 'gap message'), location_for(entry))
+      end
+
+      def decode_resolves(entry)
+        validate_entry(entry, %w[source message consumers])
+        source = source_for(entry, 'source')
+        location = location_for(entry)
+        message = entry['message'].nil? ? nil : string(entry['message'], 'gap message')
+        return [] if new_consumers?(source, entry['consumers'])
+
+        unless @graph.edges.any? do |edge|
+          edge.type == :dynamic_feature && edge.from_constant == source.name && edge.from_path == source.path &&
+            edge.location == location && (message.nil? || edge.to == message)
+        end
+          invalid('a resolution must identify an existing analysis gap with its complete source range')
+        end
+        Resolve.new(source, message, location)
+      end
+
+      private
+
+      def producer
+        @document['producer']
+      end
+
+      def legacy_staleness(excluding)
+        return 'source or configuration changed' unless @document['snapshot'] == Facts.snapshot(@graph, excluding: excluding)
+
+        environment = @document['environment']
+        return unless environment && ENV['RAILS_ENV'] && ENV['RAILS_ENV'] != environment
+
+        "captured for RAILS_ENV=#{environment}, but RAILS_ENV is #{ENV['RAILS_ENV']}"
+      end
+
+      # Changes to global inputs, or to the recorded environment, invalidate
+      # the document. A changed, added, or removed analyzed file only
+      # invalidates the facts that cite it.
+      def staleness(excluding)
+        (@document['env'] || {}).each do |name, value|
+          current = ENV.fetch(name, nil)
+          return "captured with #{name}=#{value}, but it is #{current}" if current && current != value
+        end
+
+        recorded = @document['snapshot'] || {}
+        inputs = Facts.input_files(@graph, @document['inputs'] || [], excluding: excluding)
+        sources = Facts.source_files(@graph, @document['sources'] || [])
+        candidates = recorded.keys.map { |path| File.expand_path(path, @graph.root) } | inputs | sources
+        root = Pathname(@graph.root)
+        candidates.sort.each do |path|
+          relative = Pathname(path).relative_path_from(root).to_s
+          next if recorded[relative] == Facts.digest(path)
+          return "#{relative} changed" if inputs.include?(path) || input_pattern?(relative)
+
+          # A covered file that is gone takes its facts with it; one that
+          # changed reports them as stale.
+          (@graph.files.key?(path) ? @stale : @removed) << path
+        end
+        nil
+      end
+
+      def stale_diagnostic(path, message)
+        @graph.fact_diagnostics << Diagnostic.new(rule: STALE_RULE, message: message,
+          location: SourceLocation.point(File.expand_path(path), 1, 1),
+          evidence: Pathname(File.expand_path(@label)).relative_path_from(Pathname(@graph.root)).to_s)
+      end
+
+      def stale_entry?(entry)
+        return false if (@stale.empty? && @removed.empty?) || !entry.is_a?(Hash)
+
+        installation = entry['installation'].is_a?(Hash) ? entry['installation']['path'] : nil
+        dependencies = entry['depends_on'].is_a?(Array) ? entry['depends_on'] : []
+        [entry['path'], entry['source_path'], installation, *dependencies].any? do |path|
+          next false unless path.is_a?(String)
+
+          expanded = File.expand_path(path, @graph.root)
+          @stale.include?(expanded) || @removed.include?(expanded)
+        end
+      end
+
+      def input_pattern?(relative)
+        (@document['inputs'] || []).any? do |pattern|
+          File.fnmatch?(pattern, relative, File::FNM_PATHNAME | File::FNM_EXTGLOB | File::FNM_DOTMATCH)
+        end
+      end
+
+      # Files an entry depends on beyond its own location, such as the owner
+      # of an exposure. They must be fingerprinted so an edit is noticed.
+      def validate_dependencies(entry)
+        return unless entry.is_a?(Hash) && entry.key?('depends_on')
+
+        paths = string_list(entry['depends_on'], 'dependencies')
+        snapshot = @document['snapshot']
+        missing = snapshot && paths.find { |path| !snapshot.key?(path) }
+        invalid("the snapshot does not fingerprint #{missing}") if missing
+      end
+
+      # A resolution holds only for the consumers the producer inspected. A
+      # consumer added since then was never observed, so it is reported.
+      def new_consumers?(source, recorded)
+        return false if recorded.nil?
+
+        string_list(recorded, 'consumers')
+        added = @graph.consumers_of(source.name).reject { |node| recorded.include?(node.name) }
+        added.each do |node|
+          stale_diagnostic(node.path, "#{producer} facts have not observed this consumer of #{source.name}; " \
+                                      'run `archspec reflect`')
+        end
+        added.any?
+      end
+
+      # Only calls owned by constants that receiver facts name are indexed.
+      def receiverless_calls
+        @receiverless_calls ||= begin
+          sources = Array(@document['receivers']).filter_map { |entry| entry['source'].to_s.delete_prefix('::') if entry.is_a?(Hash) }.to_set
+          @graph.edges.each_with_object(Set.new) do |edge, calls|
+            next unless sources.include?(edge.from_constant) && edge.type == :calls_named_method && edge.receiver == :none
+
+            calls << [edge.from_constant, edge.from_path, edge.to, edge.location]
+          end
+        end
+      end
+
+      def validate_envelope
+        unless @document.is_a?(Hash) && @document['version'].is_a?(Integer) && [1, VERSION].include?(@document['version'])
+          invalid("expected version 1 or #{VERSION}")
+        end
+        legacy = @document['version'] == 1
+        lists = legacy ? LEGACY_LIST_KEYS : LIST_KEYS
+        keys = (legacy ? LEGACY_ENVELOPE_KEYS : ENVELOPE_KEYS) + lists
+        invalid('unknown document fields') unless (@document.keys - keys).empty?
+        string(@document['producer'], 'producer')
+        unless @document['environment'].nil? || @document['environment'].is_a?(String)
+          invalid('expected an environment string')
+        end
+        invalid('expected fact lists') unless lists.all? { |key| @document[key].nil? || @document[key].is_a?(Array) }
+        validate_freshness_fields unless legacy
+      end
+
+      def validate_freshness_fields
+        env = @document['env']
+        unless env.nil? || (env.is_a?(Hash) && env.all? { |key, value| key.is_a?(String) && value.is_a?(String) })
+          invalid('expected env to map variable names to strings')
+        end
+        %w[inputs sources].each do |key|
+          string_list(@document[key], "#{key} patterns") unless @document[key].nil?
+        end
+        snapshot = @document['snapshot']
+        return if snapshot.nil?
+
+        unless snapshot.is_a?(Hash) && snapshot.all? { |key, value| key.is_a?(String) && value.is_a?(String) }
+          invalid('expected a snapshot of file digests')
+        end
+      end
+
+      def signature_for(value)
+        unless value.is_a?(Hash) && (value.keys - MethodSignature.members.map(&:to_s)).empty?
+          invalid('invalid method signature fields')
+        end
+        counts = %w[required optional].to_h do |key|
+          number = value.fetch(key, 0)
+          invalid("invalid signature #{key}") unless number.is_a?(Integer) && number >= 0
+          [key.to_sym, number]
+        end
+        flags = %w[rest keyword_rest block forward].to_h do |key|
+          flag = value.fetch(key, false)
+          invalid("invalid signature #{key}") unless flag == true || flag == false
+          [key.to_sym, flag]
+        end
+        keywords = %w[keywords optional_keywords].to_h do |key|
+          [key.to_sym, string_list(value.fetch(key, []), "signature #{key}").map(&:to_sym)]
+        end
+        invalid('required and optional keywords overlap') unless (keywords[:keywords] & keywords[:optional_keywords]).empty?
+        MethodSignature.new(
+          counts.fetch(:required),
+          counts.fetch(:optional),
+          flags.fetch(:rest),
+          keywords.fetch(:keywords),
+          keywords.fetch(:optional_keywords),
+          flags.fetch(:keyword_rest),
+          flags.fetch(:block),
+          flags.fetch(:forward)
+        )
+      end
+
+      def validate_entry(entry, keys)
+        invalid('invalid entry fields') unless entry.is_a?(Hash) && (entry.keys - keys - ENTRY_LOCATION_KEYS).empty?
+      end
+
+      def enum(value, values, label)
+        invalid("invalid #{label}: expected #{values.join(', ')}") unless values.include?(value)
+        value.to_sym
+      end
+
+      def string(value, label)
+        invalid("expected a nonempty #{label}") unless value.is_a?(String) && !value.empty?
+        value
+      end
+
+      def string_list(value, label, nonempty: false)
+        unless value.is_a?(Array) && (!nonempty || !value.empty?) && value.all? { |item| item.is_a?(String) && !item.empty? }
+          invalid("invalid #{label}")
+        end
+        value
+      end
+
+      def source_for(entry, key)
+        name = constant_name(entry[key])
+        source_path = project_path(entry['source_path'] || entry['path'])
+        source = @graph.constants_named(name).find { |node| node.path == source_path }
+        invalid("#{name} is not defined in #{entry['source_path'] || entry['path']}") unless source
+        source
+      end
+
+      def constant_name(value)
+        unless value.is_a?(String) && /\A(?:::)?[[:upper:]][[:alnum:]_]*(?:::[[:upper:]][[:alnum:]_]*)*\z/.match?(value)
+          invalid('invalid constant name')
+        end
+        value.delete_prefix('::')
+      end
+
+      # Every cited file must be analyzed and, in a version 2 snapshot,
+      # fingerprinted, so a later edit to it is always detected.
+      def project_path(value)
+        invalid('invalid source path') unless value.is_a?(String) && !Pathname(value).absolute?
+        expanded = File.expand_path(value, @graph.root)
+        invalid("source path #{value} is not analyzed") unless @graph.files.key?(expanded)
+        snapshot = @document['snapshot']
+        if @document['version'] != 1 && snapshot && !snapshot.key?(value)
+          invalid("the snapshot does not fingerprint #{value}")
+        end
+        expanded
+      end
+
+      def location_for(entry)
+        source = project_path(entry['path'])
+        line = entry['line']
+        column = entry.fetch('column', 1)
+        end_line = entry.fetch('end_line', line)
+        end_column = entry.fetch('end_column', column)
+        lines = @lines[source] ||= File.readlines(source)
+        valid = [line, column, end_line, end_column].all? { |value| value.is_a?(Integer) && value.positive? }
+        valid &&= line <= lines.size && end_line <= lines.size &&
+                  ([line, column] <=> [end_line, end_column]) <= 0 &&
+                  column <= lines[line - 1].chomp.bytesize + 1 && end_column <= lines[end_line - 1].chomp.bytesize + 1
+        invalid('invalid source location') unless valid
+        SourceLocation.new(source, line, column, end_line, end_column)
+      end
+
+      def invalid(message)
+        raise Error, "invalid facts file #{@label}: #{message}"
+      end
+    end
+  end
+end