Merge branch '28930-add-project-reference-filter' into 'master'

Resolve "GFM : provide 'project' reference in comment"

Closes #28930

See merge request gitlab-org/gitlab-ce!20285

app/models/project.rb

@@ -470,6 +470,24 @@ class Project < ActiveRecord::Base
       }x
     end
+    def reference_postfix
+      '>'
+    end
+
+    def reference_postfix_escaped
+      '&gt;'
+    end
+
+    # Pattern used to extract `namespace/project>` project references from text.
+    # '>' or its escaped form ('&gt;') are checked for because '>' is sometimes escaped
+    # when the reference comes from an external source.
+    def markdown_reference_pattern
+      %r{
+        #{reference_pattern}
+        (#{reference_postfix}|#{reference_postfix_escaped})
+      }x
+    end
+
     def trending
       joins('INNER JOIN trending_projects ON projects.id = trending_projects.project_id')
         .reorder('trending_projects.id ASC')
@@ -908,6 +926,10 @@ class Project < ActiveRecord::Base
     end
   end
+  def to_reference_with_postfix
+    "#{to_reference(full: true)}#{self.class.reference_postfix}"
+  end
+
   # `from` argument can be a Namespace or Project.
   def to_reference(from = nil, full: false)
     if full || cross_namespace_reference?(from)

changelogs/unreleased/28930-add-project-reference-filter.yml

+---
+title: Add the ability to reference projects in comments and other markdown text.
+merge_request: 20285
+author: Reuben Pereira
+type: added

doc/user/markdown.md

@@ -259,6 +259,7 @@ GFM will recognize the following:
 | `@user_name`               | specific user                   |
 | `@group_name`              | specific group                  |
 | `@all`                     | entire team                     |
+| `namespace/project>`       | project                         |
 | `#12345`                   | issue                           |
 | `!123`                     | merge request                   |
 | `$123`                     | snippet                         |

lib/banzai/filter/project_reference_filter.rb

+module Banzai
+  module Filter
+    # HTML filter that replaces project references with links.
+    class ProjectReferenceFilter < ReferenceFilter
+      self.reference_type = :project
+
+      # Public: Find `namespace/project>` project references in text
+      #
+      #   ProjectReferenceFilter.references_in(text) do |match, project|
+      #     "<a href=...>#{project}></a>"
+      #   end
+      #
+      # text - String text to search.
+      #
+      # Yields the String match, and the String project name.
+      #
+      # Returns a String replaced with the return of the block.
+      def self.references_in(text)
+        text.gsub(Project.markdown_reference_pattern) do |match|
+          yield match, "#{$~[:namespace]}/#{$~[:project]}"
+        end
+      end
+
+      def call
+        ref_pattern = Project.markdown_reference_pattern
+        ref_pattern_start = /\A#{ref_pattern}\z/
+
+        nodes.each do |node|
+          if text_node?(node)
+            replace_text_when_pattern_matches(node, ref_pattern) do |content|
+              project_link_filter(content)
+            end
+          elsif element_node?(node)
+            yield_valid_link(node) do |link, inner_html|
+              if link =~ ref_pattern_start
+                replace_link_node_with_href(node, link) do
+                  project_link_filter(link, link_content: inner_html)
+                end
+              end
+            end
+          end
+        end
+
+        doc
+      end
+
+      # Replace `namespace/project>` project references in text with links to the referenced
+      # project page.
+      #
+      # text - String text to replace references in.
+      # link_content - Original content of the link being replaced.
+      #
+      # Returns a String with `namespace/project>` references replaced with links. All links
+      # have `gfm` and `gfm-project` class names attached for styling.
+      def project_link_filter(text, link_content: nil)
+        self.class.references_in(text) do |match, project_path|
+          cached_call(:banzai_url_for_object, match, path: [Project, project_path.downcase]) do
+            if project = projects_hash[project_path.downcase]
+              link_to_project(project, link_content: link_content) || match
+            else
+              match
+            end
+          end
+        end
+      end
+
+      # Returns a Hash containing all Project objects for the project
+      # references in the current document.
+      #
+      # The keys of this Hash are the project paths, the values the
+      # corresponding Project objects.
+      def projects_hash
+        @projects ||= Project.eager_load(:route, namespace: [:route])
+                             .where_full_path_in(projects)
+                             .index_by(&:full_path)
+                             .transform_keys(&:downcase)
+      end
+
+      # Returns all projects referenced in the current document.
+      def projects
+        refs = Set.new
+
+        nodes.each do |node|
+          node.to_html.scan(Project.markdown_reference_pattern) do
+            refs << "#{$~[:namespace]}/#{$~[:project]}"
+          end
+        end
+
+        refs.to_a
+      end
+
+      private
+
+      def urls
+        Gitlab::Routing.url_helpers
+      end
+
+      def link_class
+        reference_class(:project)
+      end
+
+      def link_to_project(project, link_content: nil)
+        url = urls.project_url(project, only_path: context[:only_path])
+        data = data_attribute(project: project.id)
+        content = link_content || project.to_reference_with_postfix
+
+        link_tag(url, data, content, project.name)
+      end
+
+      def link_tag(url, data, link_content, title)
+        %(<a href="#{url}" #{data} class="#{link_class}" title="#{escape_once(title)}">#{link_content}</a>)
+      end
+    end
+  end
+end

lib/banzai/pipeline/gfm_pipeline.rb

@@ -36,6 +36,7 @@ module Banzai
       def self.reference_filters
         [
           Filter::UserReferenceFilter,
+          Filter::ProjectReferenceFilter,
           Filter::IssueReferenceFilter,
           Filter::ExternalIssueReferenceFilter,
           Filter::MergeRequestReferenceFilter,

lib/banzai/reference_parser/project_parser.rb

+module Banzai
+  module ReferenceParser
+    class ProjectParser < BaseParser
+      include Gitlab::Utils::StrongMemoize
+
+      self.reference_type = :project
+
+      def references_relation
+        Project
+      end
+
+      private
+
+      # Returns an Array of Project ids that can be read by the given user.
+      #
+      # user - The User for which to check the projects
+      def readable_project_ids_for(user)
+        @project_ids_by_user ||= {}
+        @project_ids_by_user[user] ||=
+          Project.public_or_visible_to_user(user).where("projects.id IN (?)", @projects_for_nodes.values.map(&:id)).pluck(:id)
+      end
+
+      def can_read_reference?(user, ref_project, node)
+        readable_project_ids_for(user).include?(ref_project.try(:id))
+      end
+    end
+  end
+end

spec/lib/banzai/filter/project_reference_filter_spec.rb

+require 'spec_helper'
+
+describe Banzai::Filter::ProjectReferenceFilter do
+  include FilterSpecHelper
+
+  def invalidate_reference(reference)
+    "#{reference.reverse}"
+  end
+
+  def get_reference(project)
+    project.to_reference_with_postfix
+  end
+
+  let(:project)   { create(:project, :public) }
+  subject { project }
+  let(:subject_name) { "project" }
+  let(:reference) { get_reference(project) }
+
+  it_behaves_like 'user reference or project reference'
+
+  it 'ignores invalid projects' do
+    exp = act = "Hey #{invalidate_reference(reference)}"
+
+    expect(reference_filter(act).to_html).to eq(CGI.escapeHTML(exp))
+  end
+
+  it 'allows references with text after the > character' do
+    doc = reference_filter("Hey #{reference}foo")
+    expect(doc.css('a').first.attr('href')).to eq urls.project_url(subject)
+  end
+
+  %w(pre code a style).each do |elem|
+    it "ignores valid references contained inside '#{elem}' element" do
+      exp = act = "<#{elem}>Hey #{CGI.escapeHTML(reference)}</#{elem}>"
+      expect(reference_filter(act).to_html).to eq exp
+    end
+  end
+
+  it 'includes default classes' do
+    doc = reference_filter("Hey #{reference}")
+    expect(doc.css('a').first.attr('class')).to eq 'gfm gfm-project has-tooltip'
+  end
+
+  context 'in group context' do
+    let(:group) { create(:group) }
+    let(:project) { create(:project, group: group) }
+
+    let(:nested_group) { create(:group, :nested) }
+    let(:nested_project) { create(:project, group: nested_group) }
+
+    it 'supports mentioning a project' do
+      reference = get_reference(project)
+      doc = reference_filter("Hey #{reference}")
+
+      expect(doc.css('a').first.attr('href')).to eq urls.project_url(project)
+    end
+
+    it 'supports mentioning a project in a nested group' do
+      reference = get_reference(nested_project)
+      doc = reference_filter("Hey #{reference}")
+
+      expect(doc.css('a').first.attr('href')).to eq urls.project_url(nested_project)
+    end
+  end
+
+  describe '#projects_hash' do
+    it 'returns a Hash containing all Projects' do
+      document = Nokogiri::HTML.fragment("<p>#{get_reference(project)}</p>")
+      filter = described_class.new(document, project: project)
+
+      expect(filter.projects_hash).to eq({ project.full_path => project })
+    end
+  end
+
+  describe '#projects' do
+    it 'returns the projects mentioned in a document' do
+      document = Nokogiri::HTML.fragment("<p>#{get_reference(project)}</p>")
+      filter = described_class.new(document, project: project)
+
+      expect(filter.projects).to eq([project.full_path])
+    end
+  end
+end

spec/lib/banzai/filter/user_reference_filter_spec.rb

@@ -3,9 +3,17 @@ require 'spec_helper'
 describe Banzai::Filter::UserReferenceFilter do
   include FilterSpecHelper
+  def get_reference(user)
+    user.to_reference
+  end
+
   let(:project)   { create(:project, :public) }
   let(:user)      { create(:user) }
-  let(:reference) { user.to_reference }
+  subject { user }
+  let(:subject_name) { "user" }
+  let(:reference) { get_reference(user) }
+
+  it_behaves_like 'user reference or project reference'
   it 'requires project context' do
     expect { described_class.call('') }.to raise_error(ArgumentError, /:project/)
@@ -66,45 +74,6 @@ describe Banzai::Filter::UserReferenceFilter do
     end
   end
-  context 'mentioning a user' do
-    it_behaves_like 'a reference containing an element node'
-
-    it 'links to a User' do
-      doc = reference_filter("Hey #{reference}")
-      expect(doc.css('a').first.attr('href')).to eq urls.user_url(user)
-    end
-
-    it 'links to a User with a period' do
-      user = create(:user, name: 'alphA.Beta')
-
-      doc = reference_filter("Hey #{user.to_reference}")
-      expect(doc.css('a').length).to eq 1
-    end
-
-    it 'links to a User with an underscore' do
-      user = create(:user, name: 'ping_pong_king')
-
-      doc = reference_filter("Hey #{user.to_reference}")
-      expect(doc.css('a').length).to eq 1
-    end
-
-    it 'links to a User with different case-sensitivity' do
-      user = create(:user, username: 'RescueRanger')
-
-      doc = reference_filter("Hey #{user.to_reference.upcase}")
-      expect(doc.css('a').length).to eq 1
-      expect(doc.css('a').text).to eq(user.to_reference)
-    end
-
-    it 'includes a data-user attribute' do
-      doc = reference_filter("Hey #{reference}")
-      link = doc.css('a').first
-
-      expect(link).to have_attribute('data-user')
-      expect(link.attr('data-user')).to eq user.namespace.owner_id.to_s
-    end
-  end
-
   context 'mentioning a group' do
     it_behaves_like 'a reference containing an element node'
@@ -154,36 +123,6 @@ describe Banzai::Filter::UserReferenceFilter do
     expect(doc.css('a').first.attr('class')).to eq 'gfm gfm-project_member has-tooltip'
   end
-  it 'supports an :only_path context' do
-    doc = reference_filter("Hey #{reference}", only_path: true)
-    link = doc.css('a').first.attr('href')
-
-    expect(link).not_to match %r(https?://)
-    expect(link).to eq urls.user_path(user)
-  end
-
-  context 'referencing a user in a link href' do
-    let(:reference) { %Q{<a href="#{user.to_reference}">User</a>} }
-
-    it 'links to a User' do
-      doc = reference_filter("Hey #{reference}")
-      expect(doc.css('a').first.attr('href')).to eq urls.user_url(user)
-    end
-
-    it 'links with adjacent text' do
-      doc = reference_filter("Mention me (#{reference}.)")
-      expect(doc.to_html).to match(%r{\(<a.+>User</a>\.\)})
-    end
-
-    it 'includes a data-user attribute' do
-      doc = reference_filter("Hey #{reference}")
-      link = doc.css('a').first
-
-      expect(link).to have_attribute('data-user')
-      expect(link.attr('data-user')).to eq user.namespace.owner_id.to_s
-    end
-  end
-
   context 'when a project is not specified' do
     let(:project) { nil }
@@ -227,7 +166,7 @@ describe Banzai::Filter::UserReferenceFilter do
     end
     it 'supports mentioning a single user' do
-      reference = group_member.to_reference
+      reference = get_reference(group_member)
       doc = reference_filter("Hey #{reference}", context)
       expect(doc.css('a').first.attr('href')).to eq urls.user_url(group_member)
@@ -243,7 +182,7 @@ describe Banzai::Filter::UserReferenceFilter do
   describe '#namespaces' do
     it 'returns a Hash containing all Namespaces' do
-      document = Nokogiri::HTML.fragment("<p>#{user.to_reference}</p>")
+      document = Nokogiri::HTML.fragment("<p>#{get_reference(user)}</p>")
       filter = described_class.new(document, project: project)
       ns = user.namespace
@@ -253,7 +192,7 @@ describe Banzai::Filter::UserReferenceFilter do
   describe '#usernames' do
     it 'returns the usernames mentioned in a document' do
-      document = Nokogiri::HTML.fragment("<p>#{user.to_reference}</p>")
+      document = Nokogiri::HTML.fragment("<p>#{get_reference(user)}</p>")
       filter = described_class.new(document, project: project)
       expect(filter.usernames).to eq([user.username])

spec/lib/banzai/reference_parser/project_parser_spec.rb

+require 'spec_helper'
+
+describe Banzai::ReferenceParser::ProjectParser do
+  include ReferenceParserHelpers
+
+  let(:project) { create(:project, :public) }
+  let(:user) { create(:user) }
+  subject { described_class.new(Banzai::RenderContext.new(project, user)) }
+  let(:link) { empty_html_link }
+
+  describe '#referenced_by' do
+    describe 'when the link has a data-project attribute' do
+      context 'using an existing project ID' do
+        it 'returns an Array of projects' do
+          link['data-project'] = project.id.to_s
+
+          expect(subject.gather_references([link])).to eq([project])
+        end
+      end
+
+      context 'using a non-existing project ID' do
+        it 'returns an empty Array' do
+          link['data-project'] = ''
+
+          expect(subject.gather_references([link])).to eq([])
+        end
+      end
+
+      context 'using a private project ID' do
+        it 'returns an empty Array when unauthorized' do
+          private_project = create(:project, :private)
+
+          link['data-project'] = private_project.id.to_s
+
+          expect(subject.gather_references([link])).to eq([])
+        end
+
+        it 'returns an Array when authorized' do
+          private_project = create(:project, :private, namespace: user.namespace)
+
+          link['data-project'] = private_project.id.to_s
+
+          expect(subject.gather_references([link])).to eq([private_project])
+        end
+      end
+    end
+  end
+end

spec/models/project_spec.rb

@@ -364,6 +364,15 @@ describe Project do
     it { is_expected.to delegate_method(:name).to(:owner).with_prefix(true).with_arguments(allow_nil: true) }
   end
+  describe '#to_reference_with_postfix' do
+    it 'returns the full path with reference_postfix' do
+      namespace = create(:namespace, path: 'sample-namespace')
+      project = create(:project, path: 'sample-project', namespace: namespace)
+
+      expect(project.to_reference_with_postfix).to eq 'sample-namespace/sample-project>'
+    end
+  end
+
   describe '#to_reference' do
     let(:owner)     { create(:user, name: 'Gitlab') }
     let(:namespace) { create(:namespace, path: 'sample-namespace', owner: owner) }

spec/support/banzai/reference_filter_shared_examples.rb

@@ -11,3 +11,76 @@ shared_examples 'a reference containing an element node' do
     expect(doc.children.first.inner_html).to eq(inner_html)
   end
 end
+
+# Requires a reference, subject and subject_name:
+#   subject { create(:user) }
+#   let(:reference) { subject.to_reference }
+#   let(:subject_name) { 'user' }
+shared_examples 'user reference or project reference' do
+  shared_examples 'it contains a data- attribute' do
+    it 'includes a data- attribute' do
+      doc = reference_filter("Hey #{reference}")
+      link = doc.css('a').first
+
+      expect(link).to have_attribute("data-#{subject_name}")
+      expect(link.attr("data-#{subject_name}")).to eq subject.id.to_s
+    end
+  end
+
+  context 'mentioning a resource' do
+    it_behaves_like 'a reference containing an element node'
+    it_behaves_like 'it contains a data- attribute'
+
+    it "links to a resource" do
+      doc = reference_filter("Hey #{reference}")
+      expect(doc.css('a').first.attr('href')).to eq urls.send("#{subject_name}_url", subject)
+    end
+
+    it 'links to a resource with a period' do
+      subject = create(subject_name.to_sym, name: 'alphA.Beta')
+
+      doc = reference_filter("Hey #{get_reference(subject)}")
+      expect(doc.css('a').length).to eq 1
+    end
+
+    it 'links to a resource with an underscore' do
+      subject = create(subject_name.to_sym, name: 'ping_pong_king')
+
+      doc = reference_filter("Hey #{get_reference(subject)}")
+      expect(doc.css('a').length).to eq 1
+    end
+
+    it 'links to a resource with different case-sensitivity' do
+      subject = create(subject_name.to_sym, name: 'RescueRanger')
+      reference = get_reference(subject)
+
+      doc = reference_filter("Hey #{reference.upcase}")
+      expect(doc.css('a').length).to eq 1
+      expect(doc.css('a').text).to eq(reference)
+    end
+  end
+
+  it 'supports an :only_path context' do
+    doc = reference_filter("Hey #{reference}", only_path: true)
+    link = doc.css('a').first.attr('href')
+
+    expect(link).not_to match %r(https?://)
+    expect(link).to eq urls.send "#{subject_name}_path", subject
+  end
+
+  context 'referencing a resource in a link href' do
+    let(:reference) { %Q{<a href="#{get_reference(subject)}">Some text</a>} }
+
+    it_behaves_like 'it contains a data- attribute'
+
+    it 'links to the resource' do
+      doc = reference_filter("Hey #{reference}")
+      expect(doc.css('a').first.attr('href')).to eq urls.send "#{subject_name}_url", subject
+    end
+
+    it 'links with adjacent text' do
+      doc = reference_filter("Mention me (#{reference}.)")
+      expect(doc.to_html).to match(%r{\(<a.+>Some text</a>\.\)})
+    end
+  end
+end