feat: each citation names the code that asks

A profile that reads a libretro core and the original emulator cited both trees alike, and readers could not tell whether the core or the emulator asked for a file. A cited path now opens with source or upstream, the repository its lines are in. Emulator code a port carries is attributed upstream when the original holds the same value on the cited line.

profile_sync --attribute-refs writes the words from where the lines are found and follows a word already written. The site links each citation to that repository's pin, labels it libretro core or upstream emulator, and says on each file card whose code asks for it. A recale keeps the word, and mame_ref_audit reads the tree it names.

tests/test_profile_sync.py

@@ -4288,5 +4288,57 @@ class ARecaleKeepsTheRepositoryWord(unittest.TestCase):
                 self.assertEqual(profile_sync._rendered_part(result), expected)
 
 
+class EachCitationNamesTheCodeThatAsks(unittest.TestCase):
+    """A profile reading a libretro core and the original emulator cited both
+    trees alike, and readers could not tell which code asked for a file."""
+
+    setUp = TestBuildReport.setUp
+    tearDown = TestBuildReport.tearDown
+    MD5 = "0123456789abcdef0123456789abcdef"
+    TEXT = (
+        'emulator: T\n'
+        'source: "https://github.com/libretro/a5200"\n'
+        'upstream: "https://github.com/alekmaul/a5200"\n'
+        'source_commit: "pins"\n'
+        'upstream_commit: "pinu"\n'
+        'files:\n'
+        '  - name: 5200.rom\n'
+        f'    md5: {MD5}\n'
+        '    source_ref: "{ref}"\n'
+    )
+
+    def _attribute(self, ref: str) -> str:
+        trees = {
+            "libretro/a5200": {"emu/memory.c": ["x", f"rom {self.MD5}"],
+                               "libretro.c": [f"load {self.MD5}"]},
+            "alekmaul/a5200": {"emu/memory.c": ["y", f"rom {self.MD5}"]},
+        }
+        profile_sync.upstream.fetch_file = (
+            lambda repo, sha, path, cache_dir, offline=False:
+            trees.get(repo.slug, {}).get(path)
+        )
+        profile_sync.upstream.list_tree = (
+            lambda repo, sha, cache_dir, offline=False: (sorted(trees[repo.slug]), False)
+        )
+        profile_sync.upstream.resolve_head = (
+            lambda repo, cache_dir, offline=False, branch=None:
+            "pins" if repo.owner == "libretro" else "pinu"
+        )
+        path = Path(self.dir) / "t.yml"
+        path.write_text(self.TEXT.replace("{ref}", ref), encoding="utf-8")
+        profile = yaml.safe_load(path.read_text(encoding="utf-8"))
+        with contextlib.redirect_stderr(io.StringIO()):
+            report = build_report("t", profile, self.dir, text=path.read_text())
+        profile_sync.attribute_refs(path, report, profile)
+        return yaml.safe_load(path.read_text(encoding="utf-8"))["files"][0]["source_ref"]
+
+    def test_emulator_code_the_port_carries_is_the_emulators(self):
+        self.assertEqual(self._attribute("emu/memory.c:2, libretro.c:1"),
+                         "upstream emu/memory.c:2, source libretro.c:1")
+
+    def test_a_written_role_is_followed(self):
+        self.assertEqual(self._attribute("source emu/memory.c:2"), "source emu/memory.c:2")
+
+
 if __name__ == "__main__":
     unittest.main()

tests/test_site_exports.py

@@ -728,5 +728,33 @@ class ProseCitationsLinkToThePin(unittest.TestCase):
         self.assertEqual(link_prose_citations(two, "src/a.c:5"), "src/a.c:5")
 
 
+class ACitationSaysWhoseCodeItIs(unittest.TestCase):
+    """Readers could not tell whether the libretro core or the emulator asked
+    for a file: both trees were cited alike, and left unlinked."""
+
+    PROFILE = {"type": "libretro", "source": "https://github.com/libretro/a5200",
+               "upstream": "https://github.com/alekmaul/a5200",
+               "source_commit": "a" * 40, "upstream_commit": "b" * 40}
+
+    def test_each_part_links_to_its_repository_with_its_label(self):
+        from sitesources import _source_ref_markdown, requested_by
+
+        ref = "source libretro.c:5, upstream emu/memory.c:46, 50-52"
+        text = _source_ref_markdown(self.PROFILE, ref)
+        self.assertIn("libretro/a5200/blob/" + "a" * 40 + "/libretro.c#L5) (libretro core)", text)
+        self.assertIn("alekmaul/a5200/blob/" + "b" * 40 + "/emu/memory.c#L50-L52) (upstream emulator)",
+                      text)
+        self.assertEqual(requested_by(self.PROFILE, ref), "libretro core and upstream emulator")
+        self.assertEqual(requested_by(self.PROFILE, "upstream emu/memory.c:46"),
+                         "upstream emulator")
+
+    def test_a_role_without_a_pin_links_nowhere_else(self):
+        from sitesources import _source_ref_markdown
+
+        profile = {**self.PROFILE, "upstream_commit": ""}
+        self.assertEqual(_source_ref_markdown(profile, "upstream emu/memory.c:46"),
+                         "`emu/memory.c:46` (upstream emulator)")
+
+
 if __name__ == "__main__":
     unittest.main()