Support attribute-level dependencies on item collections

Author: denisdefreyne

nanoc-cli/lib/nanoc/cli/commands/show-data.rb

@@ -151,7 +151,17 @@ def describe_identifiable_collection_dependency(dep)
           outcome << 'matching any attribute'
         when Set
           dep.props.attributes.each do |elem|
-            outcome << "matching attribute #{elem.inspect}"
+            case elem
+            when Symbol
+              outcome << "matching attribute #{elem.inspect} (any value)"
+            when Array
+              outcome << "matching attribute pair #{elem[0].inspect} => #{elem[1].inspect}"
+            else
+              raise(
+                Nanoc::Core::Errors::InternalInconsistency,
+                "unexpected prop attribute element #{elem.inspect}",
+              )
+            end
           end
         else
           raise(

nanoc-core/lib/nanoc/core/dependency_props.rb

@@ -19,8 +19,18 @@ class DependencyProps
 
       C_ATTR =
         C::Or[
-          C::SetOf[Symbol],
-          C::ArrayOf[Symbol],
+          C::SetOf[
+            C::Or[
+              Symbol,          # any value
+              [Symbol, C::Any] # pair (specific value)
+            ],
+          ],
+          C::ArrayOf[
+            C::Or[
+              Symbol,          # any value
+              [Symbol, C::Any] # pair (specific value)
+            ],
+          ],
           C::Bool
         ]
 
@@ -66,6 +76,23 @@ def inspect
           s << (attributes? ? 'a' : '_')
           s << (compiled_content? ? 'c' : '_')
           s << (path? ? 'p' : '_')
+
+          if @raw_content.is_a?(Set)
+            @raw_content.each do |elem|
+              s << '; raw_content('
+              s << elem.inspect
+              s << ')'
+            end
+          end
+
+          if @attributes.is_a?(Set)
+            @attributes.each do |elem|
+              s << '; attr('
+              s << elem.inspect
+              s << ')'
+            end
+          end
+
           s << ')'
         end
       end
@@ -156,6 +183,15 @@ def active
         end
       end
 
+      def attribute_keys
+        case @attributes
+        when Enumerable
+          @attributes.map { |a| a.is_a?(Array) ? a.first : a }
+        else
+          []
+        end
+      end
+
       contract C::None => Hash
       def to_h
         {

nanoc-core/lib/nanoc/core/dependency_store.rb

@@ -15,6 +15,7 @@ class DependencyStore < ::Nanoc::Core::Store
       C_ATTR =
         C::Or[
           C::ArrayOf[Symbol],
+          C::HashOf[Symbol => C::Any],
           C::Bool
         ]
 
@@ -140,6 +141,11 @@ def record_dependency(src, dst, raw_content: false, attributes: false, compiled_
         src_ref = obj2ref(src)
         dst_ref = obj2ref(dst)
 
+        # Convert attributes into key-value pairs, if necessary
+        if attributes.is_a?(Hash)
+          attributes = attributes.to_a
+        end
+
         existing_props = @graph.props_for(dst_ref, src_ref)
         new_props = Nanoc::Core::DependencyProps.new(raw_content: raw_content, attributes: attributes, compiled_content: compiled_content, path: path)
         props = existing_props ? existing_props.merge(new_props) : new_props

nanoc-core/lib/nanoc/core/dependency_tracker.rb

@@ -23,6 +23,7 @@ class DependencyTracker
       C_ATTR =
         C::Or[
           C::ArrayOf[Symbol],
+          C::HashOf[Symbol => C::Any],
           C::Bool
         ]
 

nanoc-core/lib/nanoc/core/feature.rb

@@ -90,3 +90,5 @@ def self.all_outdated
     end
   end
 end
+
+Nanoc::Core::Feature.define('where', version: '4.12')

nanoc-core/lib/nanoc/core/identifiable_collection_view.rb

@@ -69,6 +69,34 @@ def find_all(arg = NOTHING, &block)
         @objects.find_all(arg).map { |i| view_class.new(i, @context) }
       end
 
+      # Finds all objects that have the given attribute key/value pair.
+      #
+      # @example
+      #
+      #     @items.where(kind: 'article')
+      #     @items.where(kind: 'article', year: 2020)
+      #
+      # @return [Enumerable]
+      def where(**hash)
+        unless Nanoc::Core::Feature.enabled?(Nanoc::Core::Feature::WHERE)
+          raise(
+            Nanoc::Core::TrivialError,
+            '#where is experimental, and not yet available unless the corresponding feature flag is enabled. Set NANOC_FEATURES=where or NANOC_FEATURES=all to enable its usage.',
+          )
+        end
+
+        @context.dependency_tracker.bounce(_unwrap, attributes: hash)
+
+        # IDEA: Nanoc could remember (from the previous compilation) how many
+        # times #where is called with a given attribute key, and memoize the
+        # key-to-identifiers list.
+        found_objects = @objects.select do |i|
+          hash.all? { |k, v| i.attributes[k] == v }
+        end
+
+        found_objects.map { |i| view_class.new(i, @context) }
+      end
+
       # @overload [](string)
       #
       #   Finds the object whose identifier matches the given string.

nanoc-core/lib/nanoc/core/outdatedness_checker.rb

@@ -187,7 +187,9 @@ def dependency_causes_outdatedness?(dependency)
           true
         when Nanoc::Core::ItemCollection, Nanoc::Core::LayoutCollection
           all_objects = dependency.from
-          raw_content_prop_causes_outdatedness?(all_objects, dependency.props.raw_content)
+
+          raw_content_prop_causes_outdatedness?(all_objects, dependency.props.raw_content) ||
+            attributes_prop_causes_outdatedness?(all_objects, dependency.props.attributes)
         else
           status = basic.outdatedness_status_for(dependency.from)
 
@@ -200,10 +202,12 @@ def dependency_causes_outdatedness?(dependency)
 
       def attributes_unaffected?(status, dependency)
         reason = status.reasons.find { |r| r.is_a?(Nanoc::Core::OutdatednessReasons::AttributesModified) }
-        reason && dependency.props.attributes.is_a?(Enumerable) && (dependency.props.attributes & reason.attributes).empty?
+        reason && dependency.props.attribute_keys.any? && (dependency.props.attribute_keys & reason.attributes).empty?
       end
 
       def raw_content_prop_causes_outdatedness?(objects, raw_content_prop)
+        return false unless raw_content_prop
+
         matching_objects =
           case raw_content_prop
           when true
@@ -236,6 +240,49 @@ def raw_content_prop_causes_outdatedness?(objects, raw_content_prop)
           status.reasons.any? { |r| Nanoc::Core::OutdatednessReasons::DocumentAdded == r }
         end
       end
+
+      def attributes_prop_causes_outdatedness?(objects, attributes_prop)
+        return false unless attributes_prop
+
+        unless attributes_prop.is_a?(Set)
+          raise 'not expected'
+        end
+
+        pairs = attributes_prop.select { |a| a.is_a?(Array) }.to_h
+
+        unless pairs.any?
+          raise 'not expected'
+        end
+
+        dep_checksums = pairs.transform_values { |value| Nanoc::Core::Checksummer.calc(value) }
+
+        objects.any? do |object|
+          # Find old and new attribute checksums for the object
+          old_object_checksums = checksum_store.attributes_checksum_for(object)
+          next false unless old_object_checksums
+
+          new_object_checksums = checksums.attributes_checksum_for(object)
+
+          # Ignore any attribute not mentioned in the dependency
+          old_object_checksums = old_object_checksums.select { |k, _v| dep_checksums.key?(k) }
+          new_object_checksums = new_object_checksums.select { |k, _v| dep_checksums.key?(k) }
+
+          dep_checksums.any? do |key, dep_value|
+            # Get old and new checksum for this particular attribute
+            old_value = old_object_checksums[key]
+            new_value = new_object_checksums[key]
+
+            # If either the old or new vale match the value in the dependency,
+            # then a potential change is relevant to us, and can cause
+            # outdatedness.
+            is_match = [old_value, new_value].include?(dep_value)
+
+            is_changed = old_value != new_value
+
+            is_match && is_changed
+          end
+        end
+      end
     end
   end
 end

nanoc-core/lib/nanoc/core/outdatedness_status.rb

@@ -22,6 +22,10 @@ def update(reason)
           props: @props.merge(reason.props),
         )
       end
+
+      def inspect
+        "<#{self.class} reasons=#{@reasons.inspect} props=#{@props.inspect}>"
+      end
     end
   end
 end

nanoc-core/spec/nanoc/core/outdatedness_checker_spec.rb

@@ -675,6 +675,56 @@
 
           it { is_expected.to be(false) }
         end
+
+        context 'dependency on specific new items (attribute)' do
+          before do
+            dependency_tracker = Nanoc::Core::DependencyTracker.new(dependency_store)
+            dependency_tracker.enter(item)
+            dependency_tracker.bounce(items, attributes: { kind: 'note' })
+            dependency_store.store
+          end
+
+          context 'nothing changed' do
+            it { is_expected.to be(false) }
+          end
+
+          context 'matching item added' do
+            let(:new_item) { Nanoc::Core::Item.new('stuff', { kind: 'note' }, '/new-note.md') }
+            let(:new_item_rep) { Nanoc::Core::ItemRep.new(new_item, :default) }
+
+            let(:action_sequences) do
+              super().merge({ new_item_rep => old_action_sequence_for_item_rep })
+            end
+
+            before do
+              reps << new_item_rep
+
+              dependency_store.items = Nanoc::Core::ItemCollection.new(config, items.to_a + [new_item])
+              dependency_store.load
+            end
+
+            it { is_expected.to be(true) }
+          end
+
+          context 'non-matching item added' do
+            before do
+              new_item = Nanoc::Core::Item.new('stuff', { kind: 'article' }, '/new-article.md')
+              dependency_store.items = Nanoc::Core::ItemCollection.new(config, items.to_a + [new_item])
+              dependency_store.load
+            end
+
+            it { is_expected.to be(false) }
+          end
+
+          context 'item removed' do
+            before do
+              dependency_store.items = Nanoc::Core::ItemCollection.new(config, [])
+              dependency_store.load
+            end
+
+            it { is_expected.to be(false) }
+          end
+        end
       end
     end
 

nanoc-core/spec/nanoc/core/support/identifiable_collection_view_examples.rb

@@ -328,4 +328,72 @@ def initialize; end
       end
     end
   end
+
+  describe '#where' do
+    around do |ex|
+      Nanoc::Core::Feature.enable('where') { ex.run }
+    end
+
+    let(:wrapped) do
+      collection_class.new(
+        config,
+        [
+          double(
+            :identifiable,
+            identifier: Nanoc::Core::Identifier.new('/bare.md'),
+            attributes: {},
+          ),
+          double(
+            :identifiable,
+            identifier: Nanoc::Core::Identifier.new('/note.md'),
+            attributes: { kind: 'note' },
+          ),
+          double(
+            :identifiable,
+            identifier: Nanoc::Core::Identifier.new('/note-2020.md'),
+            attributes: { kind: 'note', year: 2020 },
+          ),
+          double(
+            :identifiable,
+            identifier: Nanoc::Core::Identifier.new('/note-2021.md'),
+            attributes: { kind: 'note', year: 2021 },
+          ),
+        ],
+      )
+    end
+
+    context 'with one attribute' do
+      subject { view.where(kind: 'note') }
+
+      it 'creates dependency' do
+        expect(dependency_tracker).to receive(:bounce).with(wrapped, attributes: { kind: 'note' })
+        subject
+      end
+
+      it 'contains views' do
+        expect(subject.size).to be(3)
+        note = subject.find { |iv| iv.identifier == '/note.md' }
+        note2020 = subject.find { |iv| iv.identifier == '/note-2020.md' }
+        note2021 = subject.find { |iv| iv.identifier == '/note-2021.md' }
+        expect(note.class).to equal(view_class)
+        expect(note2020.class).to equal(view_class)
+        expect(note2021.class).to equal(view_class)
+      end
+    end
+
+    context 'with two attributes' do
+      subject { view.where(kind: 'note', year: 2020) }
+
+      it 'creates dependency' do
+        expect(dependency_tracker).to receive(:bounce).with(wrapped, attributes: { kind: 'note', year: 2020 })
+        subject
+      end
+
+      it 'contains views' do
+        expect(subject.size).to be(1)
+        note2020 = subject.find { |iv| iv.identifier == '/note-2020.md' }
+        expect(note2020.class).to equal(view_class)
+      end
+    end
+  end
 end