revise linter messages/QUALITY

Author: Gerit Wagner

docs/source/dev_docs/_autosummary/search_query.serializer_structured.rst

@@ -14,3 +14,4 @@ search\_query.serializer\_structured
    .. autosummary::
 
       to_string_structured
+      to_string_structured_2

docs/source/index.rst

@@ -80,11 +80,11 @@ Note how the syntax is translated and how the search for :literal:`Title/Abstrac
    from search_query.parser import parse
 
    query_string = '("digital health"[Title/Abstract]) AND ("privacy"[Title/Abstract])'
-   query = parse(query_string, platform="pubmed")
-   wos_query = query.translate(target_syntax="wos")
+   pubmed_query = parse(query_string, platform="pubmed")
+   wos_query = pubmed_query.translate(target_syntax="wos")
    print(wos_query.to_string())
    # Output:
-   # ((AB="digital health" OR TI="digital health") AND (AB="privacy" OR TI="privacy"))
+   # (AB="digital health" OR TI="digital health") AND (AB="privacy" OR TI="privacy")
 
 Demo
 ============

docs/source/lint/QUALITY_0004.rst

@@ -0,0 +1,24 @@
+.. _QUALITY_0004:
+
+QUALITY_0004 — unnecessary-parentheses
+======================================
+
+**Error Code**: QUALITY_0004
+
+**Message**: ``Unnecessary parentheses in queries``
+
+**Problematic query**:
+
+.. code-block:: text
+
+    ("digital health" OR "eHealth") OR ("remote monitoring" OR "telehealth")
+
+**Recommended query**:
+
+.. code-block:: text
+
+    "digital health" OR "eHealth" OR "remote monitoring" OR "telehealth
+
+**Explanation**: Parentheses are unnecessary when all operators used are **associative and have equal precedence** (like a series of ORs or a series of ANDs). In such cases, the grouping does not influence the evaluation result and adds unnecessary complexity.
+
+**Back to**: :ref:`lint`

docs/source/lint/QUALITY_0005.rst

@@ -0,0 +1,48 @@
+.. _QUALITY_0005:
+
+QUALITY_0005 — redundant-term
+=============================
+
+**Error Code**: QUALITY_0005
+
+**Message**: ``Redundant term in the query``
+
+**Problematic query (AND)**:
+
+.. code-block:: text
+
+    "digital health" AND "health"
+
+**Recommended query (AND)**:
+
+.. code-block:: text
+
+    "digital health"
+
+.. note::
+
+    The term "digital health" is more specific than "health".
+    The AND query will not retrieve results that match "health" but not "digital health".
+    Therefore, the more specific term ("digital health") is sufficient.
+
+**Problematic query (OR)**:
+
+.. code-block:: text
+
+    "digital health" OR "health"
+
+**Recommended query (OR)**:
+
+.. code-block:: text
+
+    "health"
+
+.. note::
+
+    The term "health" is broader than "digital health".
+    In the OR query, all results that match "digital health" will also match "health".
+    Therefore, the broader term ("health") is sufficient.
+
+**Typical fix**: Remove redundant terms that do not add value to the query.
+
+**Back to**: :ref:`lint`

docs/source/lint/errors_index.rst

@@ -131,3 +131,7 @@ Best practice qualities
    QUALITY_0002
 
    QUALITY_0003
+
+   QUALITY_0004
+
+   QUALITY_0005

search_query/constants.py

@@ -706,6 +706,71 @@ class QueryErrorCode(Enum):
 """,
     )
 
+    UNNECESSARY_PARENTHESES = (
+        "QUALITY_0004",
+        "unnecessary-parentheses",
+        "Unnecessary parentheses in queries",
+        """
+
+**Problematic query**:
+
+.. code-block:: text
+
+    ("digital health" OR "eHealth") OR ("remote monitoring" OR "telehealth")
+
+**Recommended query**:
+
+.. code-block:: text
+
+    "digital health" OR "eHealth" OR "remote monitoring" OR "telehealth
+
+**Explanation**: Parentheses are unnecessary when all operators used are **associative and have equal precedence** (like a series of ORs or a series of ANDs). In such cases, the grouping does not influence the evaluation result and adds unnecessary complexity.""",
+    )
+
+    REDUNDANT_TERM = (
+        "QUALITY_0005",
+        "redundant-term",
+        "Redundant term in the query",
+        """
+**Problematic query (AND)**:
+
+.. code-block:: text
+
+    "digital health" AND "health"
+
+**Recommended query (AND)**:
+
+.. code-block:: text
+
+    "digital health"
+
+.. note::
+
+    The term "digital health" is more specific than "health".
+    The AND query will not retrieve results that match "health" but not "digital health".
+    Therefore, the more specific term ("digital health") is sufficient.
+
+**Problematic query (OR)**:
+
+.. code-block:: text
+
+    "digital health" OR "health"
+
+**Recommended query (OR)**:
+
+.. code-block:: text
+
+    "health"
+
+.. note::
+
+    The term "health" is broader than "digital health".
+    In the OR query, all results that match "digital health" will also match "health".
+    Therefore, the broader term ("health") is sufficient.
+
+**Typical fix**: Remove redundant terms that do not add value to the query.""",
+    )
+
     # -------------------------------------------------------
     # Structural
     # -------------------------------------------------------

search_query/ebsco/linter.py

@@ -184,10 +184,16 @@ def check_invalid_token_sequences(self) -> None:
                 fatal=True,
             )
 
-        for i, token in enumerate(self.tokens):
+        i = -1
+        while i < len(self.tokens) - 1:
+            i += 1
             if i == 0:
                 continue
 
+            token = self.tokens[i]
+            token_type = token.type
+            prev_type = self.tokens[i - 1].type
+
             token_type = token.type
             prev_type = self.tokens[i - 1].type
 

search_query/ebsco/parser.py

@@ -150,6 +150,21 @@ def is_potential_term(token_str: str) -> bool:
                 # Reclassify the second field token as a TERM
                 next_token.type = TokenTypes.TERM
 
+        # Operator followed by a field token followed by a closing parenthesis
+        for i in range(len(self.tokens) - 2):
+            current = self.tokens[i]
+            next_token = self.tokens[i + 1]
+            next_next_token = self.tokens[i + 2]
+
+            if (
+                current.type
+                in [TokenTypes.LOGIC_OPERATOR, TokenTypes.PROXIMITY_OPERATOR]
+                and next_token.type == TokenTypes.FIELD
+                and next_next_token.type == TokenTypes.PARENTHESIS_CLOSED
+            ):
+                # Reclassify the field token as a TERM
+                next_token.type = TokenTypes.TERM
+
     def tokenize(self) -> None:
         """Tokenize the query_str."""
 
@@ -375,7 +390,10 @@ def _pre_tokenization_checks(self) -> None:
         self.linter.handle_suffix_in_query_str(self)
         self.linter.handle_prefix_in_query_str(
             self,
-            prefix_regex=re.compile(r"^EBSCOHost.*\:\s*|PsycInfo", flags=re.IGNORECASE),
+            prefix_regex=re.compile(
+                r"^EBSCOHost.*\:\s*|PsycInfo|ERIC|CINAHL with Full Text",
+                flags=re.IGNORECASE,
+            ),
         )
 
     def parse(self) -> Query: