Merge pull request #5016 from freelawproject/4977-if-a-citation-cannot-be-disambiguated-thats-ok-we-can-send-it-to-a-c-page-which-will-list-multiple-options

Link citations cannot be disambiguated

Author: grossir

cl/citations/annotate_citations.py

@@ -2,9 +2,13 @@
 import re
 from typing import Dict, List
 
+from django.urls import reverse
 from eyecite import annotate_citations, clean_text
 
-from cl.citations.match_citations import NO_MATCH_RESOURCE
+from cl.citations.match_citations import (
+    MULTIPLE_MATCHES_RESOURCE,
+    NO_MATCH_RESOURCE,
+)
 from cl.citations.types import MatchedResourceType, SupportedCitationType
 from cl.custom_filters.templatetags.text_filters import best_case_name
 from cl.lib.string_utils import trunc
@@ -55,25 +59,44 @@ def generate_annotations(
     :param citation_resolutions: A map of lists of citations in the opinion
     :return The new HTML containing citations
     """
+    from cl.opinion_page.views import make_citation_url_dict
+
     annotations: List[List] = []
     for opinion, citations in citation_resolutions.items():
         if opinion is NO_MATCH_RESOURCE:  # If unsuccessfully matched...
             annotation = [
                 '<span class="citation no-link">',
                 "</span>",
             ]
-        else:  # If successfully matched...
+            # Annotate all unmatched citations
+            annotations.extend([[c.span()] + annotation for c in citations])
+        elif opinion is MULTIPLE_MATCHES_RESOURCE:
+            # Multiple matches, can't disambiguate
+            for c in citations:
+                # Annotate all citations can't be disambiguated to citation
+                # lookup page
+                kwargs = make_citation_url_dict(**c.groups)
+                citation_url = reverse("citation_redirector", kwargs=kwargs)
+                annotation = [
+                    '<span class="citation multiple-matches">'
+                    f'<a href="{html.escape(citation_url)}">',
+                    "</a></span>",
+                ]
+                annotations.append([c.span()] + annotation)
+        else:
+            # Successfully matched citation
             case_name = trunc(best_case_name(opinion.cluster), 60, "...")
             safe_case_name = html.escape(case_name)
+            opinion_url = html.escape(opinion.cluster.get_absolute_url())
             annotation = [
                 f'<span class="citation" data-id="{opinion.pk}">'
-                f'<a href="{opinion.cluster.get_absolute_url()}"'
+                f'<a href="{opinion_url}"'
                 f' aria-description="Citation for case: {safe_case_name}"'
                 ">",
                 "</a></span>",
             ]
-        for c in citations:
-            annotations.append([c.span()] + annotation)
+            # Annotate all matched citations for the resource
+            annotations.extend([[c.span()] + annotation for c in citations])
     return annotations
 
 

cl/citations/match_citations.py

@@ -28,6 +28,11 @@
 
 
 NO_MATCH_RESOURCE = Resource(case_citation(source_text="UNMATCHED_CITATION"))
+MULTIPLE_MATCHES_RESOURCE = Resource(
+    case_citation(
+        source_text="MULTIPLE_MATCHES", page="999999", volume="999999"
+    )
+)
 
 
 def filter_by_matching_antecedent(
@@ -56,6 +61,11 @@ def resolve_fullcase_citation(
     if type(full_citation) is FullCaseCitation:
         db_search_results: list[Hit]
         db_search_results, _ = es_search_db_for_full_citation(full_citation)
+        # If there is more than one result, return a placeholder with the
+        # citation with multiple results
+        if len(db_search_results) > 1:
+            return MULTIPLE_MATCHES_RESOURCE
+
         # If there is one search result, try to return it
         if len(db_search_results) == 1:
             result_id = db_search_results[0]["id"]

cl/citations/match_citations_queries.py

@@ -214,9 +214,9 @@ def es_search_db_for_full_citation(
                 full_citation,
                 full_citation.citing_opinion,
             )
-            return results, citation_found
-    # Give up.
-    return [], citation_found
+
+    # Return all possible results
+    return results, citation_found
 
 
 def es_get_query_citation(
@@ -244,6 +244,7 @@ def es_get_query_citation(
             missing_citations.append(citation)
 
     if len(citations) == 1 and matches and len(matches) == 1:
-        # If more than one match, don't show the tip
+        # If only one match, show the tip
         return matches[0], missing_citations
-    return matches, missing_citations
+    # No exact match, don't show the tip
+    return None, missing_citations

cl/citations/tasks.py

@@ -18,6 +18,7 @@
     is_parenthetical_descriptive,
 )
 from cl.citations.match_citations import (
+    MULTIPLE_MATCHES_RESOURCE,
     NO_MATCH_RESOURCE,
     do_resolve_citations,
 )
@@ -165,6 +166,9 @@ def store_opinion_citations_and_update_parentheticals(
     # Put apart the unmatched citations
     unmatched_citations = citation_resolutions.pop(NO_MATCH_RESOURCE, [])
 
+    # Delete citations with multiple matches
+    citation_resolutions.pop(MULTIPLE_MATCHES_RESOURCE, None)
+
     # Increase the citation count for the cluster of each matched opinion
     # if that cluster has not already been cited by this opinion. First,
     # calculate a list of the IDs of every opinion whose cluster will need

cl/citations/tests.py

@@ -42,6 +42,7 @@
     get_representative_parenthetical,
 )
 from cl.citations.match_citations import (
+    MULTIPLE_MATCHES_RESOURCE,
     NO_MATCH_RESOURCE,
     do_resolve_citations,
     resolve_fullcase_citation,
@@ -512,6 +513,7 @@ def setUpTestData(cls) -> None:
         # Courts
         cls.court_scotus = CourtFactory(id="scotus")
         court_ca1 = CourtFactory(id="ca1")
+        cls.court_ca5 = CourtFactory(id="ca5")
 
         # Citation 1
         cls.citation1 = CitationWithParentsFactory.create(
@@ -588,6 +590,83 @@ def setUpTestData(cls) -> None:
                 ),
             ),
         )
+
+        cls.citation6 = CitationWithParentsFactory.create(
+            volume="114",
+            reporter="F.3d",
+            page="1182",
+            cluster=OpinionClusterFactoryWithChildrenAndParents(
+                docket=DocketFactory(court=cls.court_ca5),
+                case_name="Foo v. Bar",
+                date_filed=date(1997, 4, 10),
+            ),
+        )
+
+        cls.citation7 = CitationWithParentsFactory.create(
+            volume="114",
+            reporter="F.3d",
+            page="1182",
+            cluster=OpinionClusterFactoryWithChildrenAndParents(
+                docket=DocketFactory(court=cls.court_ca5),
+                case_name="Lorem v. Ipsum",
+                date_filed=date(1997, 4, 8),
+            ),
+        )
+
+        cls.citation8 = CitationWithParentsFactory.create(
+            volume="1",
+            reporter="U.S.",
+            page="1",
+            cluster=OpinionClusterFactoryWithChildrenAndParents(
+                docket=DocketFactory(court=cls.court_ca5),
+                case_name="John v. Doe",
+                date_filed=date(1997, 4, 9),
+                sub_opinions=RelatedFactory(
+                    OpinionWithChildrenFactory,
+                    factory_related_name="cluster",
+                    plain_text="""Lorem ipsum, 114 F.3d 1182""",
+                ),
+            ),
+        )
+
+        cls.citation9 = CitationWithParentsFactory.create(
+            volume="114",
+            reporter="F.3d",
+            page="1181",
+            cluster=OpinionClusterFactoryWithChildrenAndParents(
+                docket=DocketFactory(court=cls.court_ca5),
+                case_name="Lorem v. Ipsum",
+                date_filed=date(1997, 4, 8),
+            ),
+        )
+
+        cls.citation10 = CitationWithParentsFactory.create(
+            volume="114",
+            reporter="F.3d",
+            page="1181",
+            cluster=OpinionClusterFactoryWithChildrenAndParents(
+                docket=DocketFactory(court=cls.court_ca5),
+                case_name="Lorem v. Ipsum",
+                date_filed=date(1997, 4, 8),
+            ),
+        )
+
+        cls.citation11 = CitationWithParentsFactory.create(
+            volume="1",
+            reporter="U.S.",
+            page="1",
+            cluster=OpinionClusterFactoryWithChildrenAndParents(
+                docket=DocketFactory(court=cls.court_ca5),
+                case_name="Foo v. Bar",
+                date_filed=date(1997, 4, 9),
+                sub_opinions=RelatedFactory(
+                    OpinionWithChildrenFactory,
+                    factory_related_name="cluster",
+                    plain_text="""Lorem ipsum, 114 F.3d 1182, consectetur adipiscing elit, 114 F.3d 1181""",
+                ),
+            ),
+        )
+
         call_command(
             "cl_index_parent_and_child_docs",
             search_type=SEARCH_TYPES.OPINION,
@@ -906,6 +985,40 @@ def test_citation_matching_issue621(self) -> None:
         results = resolve_fullcase_citation(citation)
         self.assertEqual(NO_MATCH_RESOURCE, results)
 
+    def test_citation_multiple_matches(self) -> None:
+        """Make sure that we can identify multiple matches for a single citation"""
+        citation_str = "114 F.3d 1182"
+        citation = get_citations(citation_str, tokenizer=HYPERSCAN_TOKENIZER)[
+            0
+        ]
+        results = resolve_fullcase_citation(citation)
+        self.assertEqual(MULTIPLE_MATCHES_RESOURCE, results)
+
+        # Verify if the annotated citation is correct
+        opinion = self.citation8.cluster.sub_opinions.all().first()
+        get_and_clean_opinion_text(opinion)
+        citations = get_citations(
+            opinion.cleaned_text, tokenizer=HYPERSCAN_TOKENIZER
+        )
+        citation_resolutions = do_resolve_citations(citations, opinion)
+        new_html = create_cited_html(opinion, citation_resolutions)
+
+        expected_citation_annotation = '<pre class="inline">Lorem ipsum, </pre><span class="citation multiple-matches"><a href="/c/F.3d/114/1182/">114 F.3d 1182</a></span><pre class="inline"></pre>'
+        self.assertIn(expected_citation_annotation, new_html, msg="Failed!!")
+
+        # Verify if we can annotate multiple citations that can't be
+        # disambiguated
+        opinion = self.citation11.cluster.sub_opinions.all().first()
+        get_and_clean_opinion_text(opinion)
+        citations = get_citations(
+            opinion.cleaned_text, tokenizer=HYPERSCAN_TOKENIZER
+        )
+        self.assertEqual(len(citations), 2)
+        citation_resolutions = do_resolve_citations(citations, opinion)
+        new_html = create_cited_html(opinion, citation_resolutions)
+        expected_citation_annotation = '<pre class="inline">Lorem ipsum, </pre><span class="citation multiple-matches"><a href="/c/F.3d/114/1182/">114 F.3d 1182</a></span><pre class="inline">, consectetur adipiscing elit, </pre><span class="citation multiple-matches"><a href="/c/F.3d/114/1181/">114 F.3d 1181</a></span><pre class="inline"></pre>'
+        self.assertIn(expected_citation_annotation, new_html)
+
     def test_citation_increment(self) -> None:
         """Make sure that found citations update the increment on the cited
         opinion's citation count"""