feat: read a search list as one need

A core that loads the first of several names (yabause: saturn_bios.bin,
sega_101.bin, mpr-17933.bin) needs one of them. Profiles wrote this as
required on the first name and optional on the others, so verify and
the gap report called saturn_bios.bin a missing required file while
sega_101.bin was held, and a set held only through a name marked
optional read as a need met by an optional file.

Model: an explicit group on the file entry, mirroring the platform
field. priority was not reused: it is a rank, read by slot.py, region.py
and truth.py inside a (system, region) slot, and that slot is not the
set. px68k-sdl ranks its IPL list and its font list each from 1 in one
system, pom2 ranks one list per machine model, DuckStation ranks 105
images across every region and takes any of them. A rank cannot say
where one list ends. priority stays the order inside a group.

Readers, through alternatives.settle_sets:
- verify --emulator and the emulator pack: a held member fills the
  set, the others leave the report, a set nobody holds is one gap
  under its first member naming the others.
- find_undeclared_files (verify platform, core complement of packs and
  manifests): same rule, a platform declaration or launcher counts as
  answering the set.
- cross_reference: excused members are set aside as other versions.
- slot.py: ranks compare members of one set only.
- archive members: a required set inside an archive is met by one.
- truth: a member gives no requirement of its own, one_of and
  one_of_required carry the set, and the exporters and the diff leave
  such a line's required as the platform wrote it.
- validate_schemas: members of a group share required.

scripts/cross_reference.py

@@ -23,6 +23,7 @@ from collections import Counter
 from pathlib import Path
 
 sys.path.insert(0, os.path.dirname(__file__))
+from alternatives import set_keys, settle_sets
 from common import (
     platform_arg,
     ProfileSelectionError,
@@ -797,6 +798,9 @@ def _cross_reference_profile(
     # the profile's entries in their order, so a position names one entry.
     position = {id(f): i for view, _ in layouts for i, f in enumerate(view.get("files", []))}
     fates: dict[int, str] = {}
+    # Grouped entries met, as (set keys, entry, fills, the list holding
+    # its row, the row): settled once the profile is read.
+    set_records: list[tuple[tuple, dict, bool, list | None, dict | None]] = []
 
     def fate(f: dict, what: str) -> None:
         key = position[id(f)]
@@ -834,15 +838,18 @@ def _cross_reference_profile(
 
         # Collect unsourceable files separately (documented, not a gap)
         unsourceable_reason = f.get("unsourceable", "")
+        keys = set_keys((emu_name, is_standalone), f)
         if unsourceable_reason:
             seen_files.add(seen_key)
             fate(f, "unsourceable")
-            unsourceable_list.append({
+            row = {
                 "name": fname,
                 "required": f.get("required", False),
                 "reason": unsourceable_reason,
                 "source_ref": f.get("source_ref", ""),
-            })
+            }
+            unsourceable_list.append(row)
+            set_records.append((keys, f, False, unsourceable_list, row))
             continue
 
         if outside_gap_scope(f, is_standalone):
@@ -863,6 +870,7 @@ def _cross_reference_profile(
         if in_platform:
             seen_files.add(seen_key)
             fate(f, "declared")
+            set_records.append((keys, f, True, None, None))
             covered.append({
                 "name": fname,
                 "path": effective_path,
@@ -955,6 +963,21 @@ def _cross_reference_profile(
                 (emu_name, is_standalone, f, probe, entry)
             )
         gaps.append(entry)
+        set_records.append((keys, f, in_repo, gaps, entry))
+
+    # One need per set: a member another one fills is not a gap, and a set
+    # nobody holds is one gap under its first member (alternatives.py), as
+    # verify and the packs count it.
+    grouped = [r for r in set_records if r[0]]
+    excused, standing = settle_sets([(keys, f, fills) for keys, f, fills, _l, _r in grouped])
+    for at, (_keys, member, _fills, rows, set_row) in enumerate(grouped):
+        if set_row is None or rows is None:
+            continue
+        if at in standing:
+            set_row["alternatives"] = standing[at]
+        if at in excused:
+            rows.remove(set_row)
+            fates[position[id(member)]] = "other_versions"
 
     for ag in sorted(archive_gaps.values(), key=lambda e: e["name"]):
         gaps.append(ag)
@@ -1333,6 +1356,8 @@ def print_report(
                 fc = g.get("archive_file_count", 0)
                 rc = g.get("archive_required_count", 0)
                 archive_info = f" ({fc} files, {rc} required)"
+            if g.get("alternatives") and not g.get("in_repo"):
+                archive_info += f" (or {', '.join(g['alternatives'])})"
             print(f"    {req} {g['name']} [{src}]{archive_info}{note}")
 
         total_gaps += gaps