feat(bib,notebooks): cfr locator jump URLs + live eCFR links in CY2027 notebook (closes #641)

notebooks/cy2027_pfs_proposed_rule.py

@@ -66,6 +66,17 @@ def _():
     def q(sql):
         return con.execute(sql).pl()
 
+    def cfr_md(ref, text=""):
+        """eCFR jump link as markdown (P41, #641) — deterministic
+        cite→URL transform, no store needed; degrades to plain text on
+        a malformed cite so the notebook never breaks."""
+        try:
+            from bib import cfrlink
+
+            return cfrlink.md_link(ref, text=text)
+        except Exception:
+            return text or ref
+
     def fr_md(ref, text=""):
         """FR web jump link as markdown (P40, #638) — page, ¶-ordinal,
         or quote refs resolve against the bib anchor map; degrades to
@@ -88,6 +99,7 @@ def _():
         TEAL,
         alt,
         con,
+        cfr_md,
         for_payment_year,
         fr_md,
         pfs_payment,
@@ -903,7 +915,7 @@ def _(gpci_2027p, mo, pfs_payment, pl, proposed_for, q):
 
 
 @app.cell(hide_code=True)
-def _(mo, q):
+def _(cfr_md, mo, q):
     pcs_codes = q("""
         SELECT hcpcs_code AS hcpcs, trim(description) AS pcs_description
         FROM cms.primary_care_service_code
@@ -916,8 +928,8 @@ def _(mo, q):
     ## 4. Primary Care Services — the ACO Attribution Set
 
     The **{pcs_codes.height} designated primary care service codes**
-    used for Medicare Shared Savings Program beneficiary assignment (42
-    CFR § 425.400(c)), read live from
+    used for Medicare Shared Savings Program beneficiary assignment
+    ({cfr_md("42 CFR 425.400(c)")}), read live from
     `cms.primary_care_service_code` — the attribution reference list
     published to the lake from the aco module. These are the services
     whose billing patterns decide which ACO a beneficiary is attributed
@@ -1371,7 +1383,7 @@ def _(QPP, mo):
 
 
 @app.cell(hide_code=True)
-def _(alt, apm_thresholds, fr_md, mo):
+def _(alt, apm_thresholds, cfr_md, fr_md, mo):
     _df = apm_thresholds.to_pandas()
     _df["apm_incentive_pct"] = _df["apm_incentive_pct"].fillna(0.0)
     _df["status"] = _df["apm_incentive_pct"].apply(lambda v: "Paid" if v > 0 else "None under current law")
@@ -1404,7 +1416,7 @@ def _(alt, apm_thresholds, fr_md, mo):
             The Consolidated Appropriations Act, 2026 (CAA 2026, Pub.
             L. 119-75) then **revives a 3.1% incentive for payment
             year 2028 only** — CMS-1848-P proposes to codify that
-            revival into 42 CFR 414.1450(b)(1)
+            revival into {cfr_md("42 CFR 414.1450(b)(1)")}
             ({fr_md("91 FR 44218")}-44219, {fr_md("91 FR 44286")}).
             Payment year 2029 (`QPP[2027]`, the year this
             notebook's own CF walk applies to) reverts to **no**
@@ -1524,8 +1536,8 @@ def _(alt, mo, proposed_for, qp_differential):
 
 
 @app.cell(hide_code=True)
-def _(mo):
-    mo.md("""
+def _(cfr_md, mo):
+    mo.md(f"""
     ## 6. Provenance & Comment-Period Status
 
     Ingest-log entries (`cms.ingest_log`) for every FR-ingested table
@@ -1536,7 +1548,7 @@ def _(mo):
     attribution list) is a reference table published from the aco
     module's CCLF/attribution data, not an FR ingest, so it carries no
     ingest-log row; its provenance is the MSSP assignment
-    specification (42 CFR § 425.400(c)).
+    specification ({cfr_md("42 CFR 425.400(c)")}).
     """)
     return
 

src/bib/pincite.py

@@ -68,12 +68,22 @@ class Pincite(BaseModel):
     note: str = ""
 
     def jump_url(self, store: Store) -> str:
-        """Deep federalregister.gov link for FR-typed locators (#636).
+        """Deep web link for FR-typed (#636) and CFR-typed (#641)
+        locators.
 
-        Returns ``""`` for non-FR locators and whenever resolution
-        fails (no anchor map grabbed, page out of range, …) — graph
-        and docs rendering must degrade to no-URL, never raise.
+        Returns ``""`` for other locator types and whenever resolution
+        fails (no anchor map grabbed, page out of range, titleless CFR
+        cite, …) — graph and docs rendering must degrade to no-URL,
+        never raise.
         """
+        if self.locator_type == "cfr":
+            # Deterministic eCFR transform — needs no store data.
+            try:
+                from bib import cfrlink
+
+                return cfrlink.url(cfrlink.parse_cite(self.locator))
+            except Exception:  # noqa: BLE001 — degrade to no-URL by contract
+                return ""
         if self.locator_type not in ("fr", "fr_para", "fr_anchor"):
             return ""
         try:

tests/bib/test_pincite.py

@@ -582,3 +582,29 @@ class TestGraphJumpUrl:
         edge = next(e for e in g.edges if e.source == "mod.fn")
         assert edge.jump_url == "https://example.test/doc#p-2"
         s.close()
+
+
+class TestCfrJumpUrl:
+    def test_cfr_locator_resolves_store_free(self) -> None:
+        s = Store(":memory:")
+        p = Pincite(
+            fn_path="mod.fn",
+            item_key="AAAA2222",
+            locator="42 CFR 425.400(c)",
+            locator_type="cfr",
+        )
+        assert p.jump_url(s) == (
+            "https://www.ecfr.gov/current/title-42/section-425.400#p-425.400(c)"
+        )
+        s.close()
+
+    def test_titleless_section_locator_stays_empty(self) -> None:
+        s = Store(":memory:")
+        p = Pincite(
+            fn_path="mod.fn",
+            item_key="AAAA2222",
+            locator="§3.2",
+            locator_type="section",
+        )
+        assert p.jump_url(s) == ""
+        s.close()