feat(search-lit): add East Asian name + CollectiveName heuristics to parse_pubmed (#35)

Adds two anti-hallucination heuristics to
skills/search-lit/references/parse_pubmed.py:

1. East Asian name reverse encoding (LastName / ForeName swapped)
   PubMed XML occasionally encodes East Asian author names with the
   given name in <LastName> and the family name in <ForeName>. Naive
   parsers then emit BibTeX entries with the wrong first-author surname,
   which downstream /verify-refs first-author cross-check flags as a
   mismatch. The parser now detects this pattern (LastName ≥3 alpha
   chars + ForeName 1-2 alpha chars with no period) and prints a
   "% [VERIFY] East Asian name order suspected" comment above the
   BibTeX entry plus an inline ⚠ note in efetch markdown output. The
   author order is preserved verbatim — the script never silently
   swaps fields it isn't certain about.

2. CollectiveName (corporate / consortium guideline) handling
   AuthorList elements may contain <CollectiveName> instead of
   LastName / ForeName (KDIGO, AHA/ACC, WHO guideline patterns).
   Previously these authors were silently dropped, leaving the BibTeX
   entry with an empty author field. The parser now:
   - Emits the corporate name as {{Group Name}} (double-brace) so
     BibTeX styles do not try to split on commas/spaces.
   - Switches the BibTeX entry type from @Article to @misc when the
     AuthorList contains only CollectiveName entries (matches the
     /manuscript-references corporate-author convention).
   - Includes the corporate name in the cite-key surname slot.

Both heuristics share an _extract_authors() helper that returns
bib_authors, display_authors, first_author_last, suspicions, and a
has_collective_only flag, used by both parse_efetch and generate_bibtex.

Smoke-tested against synthetic XML with the Fu 2024 reverse-encoded
case and a KDIGO Working Group CollectiveName case. Both produce
correct output with the appropriate ⚠ / % [VERIFY] notes.

Author: Yoojin-nam

skills/search-lit/references/parse_pubmed.py

@@ -18,11 +18,96 @@
 
 import sys
 import json
+import re
 import xml.etree.ElementTree as ET
 from datetime import date
 from textwrap import shorten
 
 
+# Heuristic for East Asian name reverse-encoding in PubMed XML.
+# Cases observed: <LastName>Qiaoling</LastName><ForeName>Fu</ForeName> where
+# Fu is the actual family name. Pattern: LastName looks like a long given
+# name (≥3 alpha chars, no spaces) AND ForeName looks like a short surname
+# fragment (1-2 chars, no period). The naive test catches the common reverse
+# encoding without flagging legitimate short-surname authors.
+_EAST_ASIAN_REVERSE_THRESHOLD = 3  # LastName length lower bound for suspicion
+
+
+def _looks_east_asian_reversed(last: str, fore: str) -> bool:
+    """Return True if (LastName, ForeName) look swapped per PubMed encoding bug."""
+    if not last or not fore:
+        return False
+    # ForeName should look like a surname (1-2 chars, no spaces, no period)
+    # AND LastName should look like a multi-char given name.
+    return (
+        1 <= len(fore) <= 2
+        and fore.isalpha()
+        and "." not in fore
+        and len(last) >= _EAST_ASIAN_REVERSE_THRESHOLD
+        and last.isalpha()
+    )
+
+
+def _extract_authors(author_list_el):
+    """Walk an <AuthorList> element. Return (bib_authors, display_authors,
+    first_author_last, suspicions, has_collective_only).
+
+    - bib_authors: list of "Family, Given" strings for BibTeX `author = {...}`.
+      Corporate (<CollectiveName>) authors are double-braced.
+    - display_authors: list of "Last First" strings for human-readable output.
+    - first_author_last: surname of the first listed author (used for cite key).
+    - suspicions: list of human-readable warning strings (East Asian reverse
+      encoding, missing LastName, etc.).
+    - has_collective_only: True if AuthorList contains only <CollectiveName>
+      entries (no individual <LastName>). Caller should consider emitting
+      `@misc` instead of `@article` (guideline / consortium pattern).
+    """
+    bib_authors: list[str] = []
+    display_authors: list[str] = []
+    first_author_last = ""
+    suspicions: list[str] = []
+    individual_count = 0
+    collective_count = 0
+
+    if author_list_el is None:
+        return bib_authors, display_authors, "", suspicions, False
+
+    for au in author_list_el.findall("Author"):
+        last = au.findtext("LastName", "") or ""
+        fore = au.findtext("ForeName", "") or ""
+        collective = au.findtext("CollectiveName", "") or ""
+
+        if collective:
+            collective_count += 1
+            # Double-brace to prevent BibTeX from splitting on the comma /
+            # spaces inside the corporate name.
+            bib_authors.append("{" + collective + "}")
+            display_authors.append(collective)
+            if not first_author_last:
+                first_author_last = re.sub(r"[^A-Za-z]+", "", collective.split()[0]) or "Group"
+            continue
+
+        if last:
+            individual_count += 1
+            if _looks_east_asian_reversed(last, fore):
+                suspicions.append(
+                    f"East Asian name order suspected for '{last} {fore}' — "
+                    "PubMed XML may have LastName/ForeName swapped"
+                )
+            bib_authors.append(f"{last}, {fore}")
+            display_authors.append(f"{last} {fore}".strip())
+            if not first_author_last:
+                first_author_last = last
+            continue
+
+        # Author element with neither <LastName> nor <CollectiveName>: rare
+        # but possible. Record as suspicion, otherwise skip.
+        suspicions.append("Author element with no LastName and no CollectiveName")
+
+    has_collective_only = collective_count > 0 and individual_count == 0
+    return bib_authors, display_authors, first_author_last, suspicions, has_collective_only
+
+
 def parse_esearch(data: str) -> None:
     """Parse esearch JSON response, print PMIDs and count."""
     result = json.loads(data)
@@ -103,15 +188,9 @@ def parse_efetch(data: str) -> None:
         # Pages
         pages = art.findtext("Pagination/MedlinePgn", "")
 
-        # Authors
+        # Authors (handles East Asian reverse encoding + CollectiveName)
         author_list = art.find("AuthorList")
-        authors = []
-        if author_list is not None:
-            for au in author_list.findall("Author"):
-                last = au.findtext("LastName", "")
-                fore = au.findtext("ForeName", "")
-                if last:
-                    authors.append(f"{last} {fore}".strip())
+        _, authors, _, suspicions, _ = _extract_authors(author_list)
 
         # DOI
         doi = ""
@@ -137,6 +216,8 @@ def parse_efetch(data: str) -> None:
         print(f"**DOI**: {doi}")
         if abstract:
             print(f"**Abstract**: {shorten(abstract, width=500, placeholder='...')}")
+        for note in suspicions:
+            print(f"> ⚠ {note}")
         print()
 
 
@@ -177,21 +258,23 @@ def generate_bibtex(data: str) -> None:
                 doi = aid.text or ""
 
         author_list = art.find("AuthorList")
-        bib_authors = []
-        first_author_last = ""
-        if author_list is not None:
-            for au in author_list.findall("Author"):
-                last = au.findtext("LastName", "")
-                fore = au.findtext("ForeName", "")
-                if last:
-                    bib_authors.append(f"{last}, {fore}")
-                    if not first_author_last:
-                        first_author_last = last
+        bib_authors, _, first_author_last, suspicions, has_collective_only = \
+            _extract_authors(author_list)
 
         # Generate citation key
         key = f"{first_author_last}_{year}_{pmid}" if first_author_last else f"PMID_{pmid}"
 
-        print(f"@article{{{key},")
+        # Corporate / consortium guideline (e.g., KDIGO, AHA/ACC) — emit as
+        # @misc so BibTeX styles render the body of the entry without trying
+        # to format a personal author. Vancouver / AMA CSL handle both
+        # @article and @misc with author = {{Organization Name}}.
+        entry_type = "misc" if has_collective_only else "article"
+
+        # Prepend suspicion comments so they survive .bib copy/paste audits.
+        for note in suspicions:
+            print(f"% [VERIFY] {note}")
+
+        print(f"@{entry_type}{{{key},")
         print(f"  author    = {{{' and '.join(bib_authors)}}},")
         print(f"  title     = {{{title}}},")
         print(f"  journal   = {{{journal_full}}},")