From 2bdc63eab74758d3fb7608dec91fea29351f9201 Mon Sep 17 00:00:00 2001 From: coah <100182500+coah80@users.noreply.github.com> Date: Fri, 9 Oct 2026 12:57:16 -0500 Subject: [PATCH] fix(checker): enforce section coverage and strict assembly inventory (#1351) --- .github/workflows/build.yml | 3 +- AGENTS.md | 5 +- tools/check_decomp_complete.py | 55 +++++++--- .../completion-sections-attempts.md | 36 +++++++ tools/test_workflow_guards.py | 102 +++++++++++++++++- 5 files changed, 184 insertions(+), 17 deletions(-) create mode 100644 tools/decomp-assist/completion-sections-attempts.md diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 7f0f4c91..ec6e95fd 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -6,7 +6,7 @@ on: workflow_dispatch: inputs: require_complete: - description: Fail unless 43U code, data, functions, units, and links are all 100% + description: Fail unless 43U binary matches completely and source inventory is complete required: false default: false type: boolean @@ -79,6 +79,7 @@ jobs: python tools/check_decomp_complete.py \ build/${{ matrix.version }}/report.json \ --dol build/${{ matrix.version }}/main.dol + python tools/check_asm_inventory.py # Upload map files - name: Upload map diff --git a/AGENTS.md b/AGENTS.md index 93f2ba55..971cf2b9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -94,10 +94,11 @@ The final completion assertion is machine-checkable: ``` python3 tools/check_decomp_complete.py build/43U/report.json \ --dol build/43U/main.dol +python3 tools/check_asm_inventory.py ``` -It must pass before claiming full completion. GitHub Actions runs the same -assertion when manually dispatched with `require_complete=true`. +Both checks must pass before claiming full completion. GitHub Actions runs the same +assertions when manually dispatched with `require_complete=true`. Normal push and pull-request builds publish progress without failing on the current incomplete state. Use the manual `require_complete=true` dispatch for the terminal all-100% gate. diff --git a/tools/check_decomp_complete.py b/tools/check_decomp_complete.py index 6c8ceee3..80fabd84 100644 --- a/tools/check_decomp_complete.py +++ b/tools/check_decomp_complete.py @@ -15,6 +15,10 @@ EXPECTED_TOTAL_DATA = 1832684 EXPECTED_TOTAL_FUNCTIONS = 12563 INTEGER_PATTERN = re.compile(r"-?(0|[1-9][0-9]*)\Z") CODE_SECTIONS = frozenset({".text", ".init"}) +DATA_SECTIONS = frozenset({ + ".bss", "extab", "extabindex", ".ctors", ".ctors$10", ".dtors", + ".rodata", ".data", ".sdata2", ".sbss2", ".sdata", ".sbss", +}) # objdiff accumulates the aggregate fuzzy_match_percent in 32-bit floats over every code byte, # so a fully matched report can read 99.9998 instead of 100.0. Aggregates are accepted within # this tolerance only when every code byte is counted as matched; units, sections and functions @@ -132,6 +136,43 @@ def check_complete_measures(measures, label, failures, aggregate=False): percent(measures, "fuzzy_match_percent", f"{label} fuzzy_match_percent", failures) +def check_sections(sections, measures, name, failures): + if not isinstance(sections, list): + failures.append(f"{name}: missing sections") + return + sizes = {"code": 0, "data": 0} + names = set() + for section in sections: + if not isinstance(section, dict): + failures.append(f"{name}: invalid section entry") + continue + section_name = section.get("name") + label = f"{name} section {section_name}" + if not isinstance(section_name, str) or section_name not in CODE_SECTIONS | DATA_SECTIONS: + failures.append(f"{label}: unknown section name") + continue + if section_name in names: + failures.append(f"{label}: duplicate section") + names.add(section_name) + # Protobuf JSON omits a zero-valued size. objdiff counts data sections in + # full, but code measures exclude ignored/deduplicated function symbols. + size = count({"size": section.get("size", 0)}, "size", label, failures) + if size is not None: + sizes["code" if section_name in CODE_SECTIONS else "data"] += size + if "fuzzy_match_percent" in section: + percent(section, "fuzzy_match_percent", label, failures) + elif section_name in CODE_SECTIONS: + failures.append(f"{label}: missing fuzzy_match_percent") + for kind in ("code", "data"): + total = count({f"total_{kind}": measures.get(f"total_{kind}", 0)}, + f"total_{kind}", name, failures) + if total is not None and ( + sizes[kind] < total if kind == "code" else sizes[kind] != total + ): + relation = "<" if kind == "code" else "!=" + failures.append(f"{name} section {kind} coverage: {sizes[kind]} {relation} {total}") + + def key_for(value): return type(value).__name__, repr(value) @@ -215,19 +256,7 @@ def check_report(report): equal(unit_measures, "matched_functions", "total_functions", f"{name} function match", failures) percent(unit_measures, "matched_functions_percent", f"{name} function percent", failures) - sections = unit.get("sections") - if not isinstance(sections, list): - failures.append(f"{name}: missing sections") - else: - for section in sections: - if not isinstance(section, dict): - failures.append(f"{name}: invalid section entry") - continue - section_name = section.get("name", "") - if "fuzzy_match_percent" in section: - percent(section, "fuzzy_match_percent", f"{name} section {section_name}", failures) - elif isinstance(section_name, str) and section_name in CODE_SECTIONS: - failures.append(f"{name} section {section_name}: missing fuzzy_match_percent") + check_sections(unit.get("sections"), unit_measures, name, failures) functions = unit.get("functions", []) if total_functions is not None and total_functions > 0: diff --git a/tools/decomp-assist/completion-sections-attempts.md b/tools/decomp-assist/completion-sections-attempts.md new file mode 100644 index 00000000..ad07a9a3 --- /dev/null +++ b/tools/decomp-assist/completion-sections-attempts.md @@ -0,0 +1,36 @@ +# Strict completion section coverage + +Base: c3dd1c08c04a38975b63dded77a7aef6fce385f3 (rebased from aed62d8530993250fe0237e5adfd3b5a4d811020). +No source or build inputs changed by this candidate. + +Schema evidence: locally available objdiff source at c02eb31dbbf9dd33577aead353bb2db62933b2af, +`objdiff-cli/src/cmd/report.rs:250-325`, emits full section sizes, sums Data/Bss +section sizes into total_data, but sums only retained function symbols into +total_code. Hidden, ignored, zero-size and previously seen global/weak symbols +are excluded from code totals. `objdiff-core/protos/report.proto` declares +ReportItem.size as proto3 uint64; a missing JSON scalar size represents zero. +43U section classification comes from `config/43U/splits.txt`; `.ctors$10` +is a constructor subsection present in the generated report. + +Consequently section data bytes must equal total_data; section code bytes must +cover total_code, not necessarily equal it. In the current report msghndlr has +28 .text bytes but only 16 counted code bytes. No unit-specific exception is +needed. Unknown/duplicate section names and malformed sizes fail closed. +A structural check cannot authenticate a report against deliberately forged +sizes/names; original report generation and the independent DOL gate remain +required. Truly zero-byte records contribute no measurable coverage. + +Validation repeated after rebasing, using an unchanged copy of the parent-generated +c3dd1c08 main 43U report and DOL, without building main: + +- All 23 preexisting guards pass; 12 new guards bring the total to 35, no skips. +- Actual report and main DOL: DECOMPLETE_OK. +- All section lists emptied only in memory: 1,695 coverage failures. +- Each of the 2,676 section records deleted individually in memory: rejected. +- Data-only and protobuf zero-sized sections accepted; deduplicated code-size + slack accepted; code/data deficits, excess data and invalid records rejected. +- Strict combined report/DOL plus live inventory: exit 1, as required. + Inventory reports 166 functions / 168 bodies, 162 ORIGINAL and 4 PLACEHOLDER: + TMCJPEGDEC_err_restart, CNTCACHEClear, Manager::hasChannel, System::warning_run. +- CI inventory command is conditional on workflow_dispatch require_complete; + ordinary progress builds do not acquire a source-completion requirement. diff --git a/tools/test_workflow_guards.py b/tools/test_workflow_guards.py index ff5b171b..0fd44380 100644 --- a/tools/test_workflow_guards.py +++ b/tools/test_workflow_guards.py @@ -9,7 +9,7 @@ from pathlib import Path sys.path.insert(0, str(Path(__file__).resolve().parent)) -from check_decomp_complete import check_dol, check_report, exact +from check_decomp_complete import check_dol, check_report, check_sections, exact from check_asm_inventory import check_inventory @@ -138,6 +138,69 @@ void inactive() { asm("sync"); } self.assertTrue(any("inventory:" in failure for failure in self.check()[2])) +class SectionCoverageTests(unittest.TestCase): + def check(self, sections, **measures): + failures = [] + check_sections(sections, measures, "fixture", failures) + return failures + + def test_code_and_data_coverage_pass(self): + sections = [ + {"name": ".init", "size": "16", "fuzzy_match_percent": 100.0}, + {"name": ".data", "size": "8", "fuzzy_match_percent": 100.0}, + ] + self.assertEqual(self.check(sections, total_code="16", total_data="8"), []) + + def test_data_only_and_proto_zero_sizes_pass(self): + self.assertEqual(self.check([{"name": ".sbss", "size": "64"}], total_data="64"), []) + self.assertEqual(self.check([], total_code=0, total_data=0), []) + self.assertEqual(self.check([ + {"name": ".text", "fuzzy_match_percent": 100.0}, + {"name": ".bss"}, + ], total_code=0, total_data=0), []) + + def test_deduplicated_code_is_not_required_to_equal_section_size(self): + sections = [{"name": ".text", "size": "28", "fuzzy_match_percent": 100.0}] + self.assertEqual(self.check(sections, total_code="16"), []) + self.assertEqual(self.check(sections, total_code=0), []) + + def test_deleted_or_truncated_sections_fail(self): + for sections in ([], [{"name": ".text", "size": "12", "fuzzy_match_percent": 100.0}]): + with self.subTest(sections=sections): + failures = self.check(sections, total_code="16", total_data="8") + self.assertTrue(any("section code coverage" in item for item in failures)) + self.assertTrue(any("section data coverage" in item for item in failures)) + + def test_excess_data_is_not_hidden_by_code_slack(self): + failures = self.check([ + {"name": ".text", "size": "28", "fuzzy_match_percent": 100.0}, + {"name": ".bss", "size": "12"}, + ], total_code="16", total_data="8") + self.assertIn("fixture section data coverage: 12 != 8", failures) + + def test_invalid_section_sizes_fail(self): + for size in (-1, "-1", True, 1.5, "1.5", None): + with self.subTest(size=size): + self.assertTrue(self.check([{"name": ".data", "size": size}], total_data=0)) + + def test_invalid_and_duplicate_section_names_fail(self): + for name in (None, [], "", ".unknown"): + with self.subTest(name=name): + self.assertTrue(self.check([{"name": name, "size": "8"}], total_data="8")) + section = {"name": ".data", "size": "4"} + self.assertIn("fixture section .data: duplicate section", self.check([section, section], total_data="8")) + + def test_section_scores_remain_strict(self): + for section in ( + {"name": ".text", "size": "16"}, + {"name": ".text", "size": "16", "fuzzy_match_percent": 99.9999}, + {"name": ".data", "size": "8", "fuzzy_match_percent": 99.9999}, + ): + with self.subTest(section=section): + failures = self.check([section], total_code="16", total_data="8") + self.assertTrue(any("fixture section " + section["name"] in item for item in failures)) + + class WorkflowGuardTests(unittest.TestCase): def test_exact_percent_is_strict(self): self.assertTrue(exact(100.0)) @@ -233,6 +296,43 @@ class WorkflowGuardTests(unittest.TestCase): def test_complete_report_schema_passes(self): self.assertEqual(check_report(self.complete_report()), []) + def test_empty_section_arrays_cannot_claim_completion(self): + report = self.complete_report() + for unit in report["units"]: + unit["sections"] = [] + failures = check_report(report) + self.assertTrue(any("section code coverage" in failure for failure in failures)) + self.assertTrue(any("section data coverage" in failure for failure in failures)) + + def test_deleting_one_code_or_data_section_fails(self): + for kind, section_name in (("code", ".text"), ("data", ".sbss")): + with self.subTest(kind=kind): + report = self.complete_report() + unit = next(unit for unit in report["units"] + if any(section["name"] == section_name for section in unit["sections"])) + unit["sections"] = [section for section in unit["sections"] if section["name"] != section_name] + self.assertTrue(any(f"{unit['name']} section {kind} coverage" in failure + for failure in check_report(report))) + + def test_every_current_section_is_required_for_coverage(self): + for unit in self.complete_report()["units"]: + for index, section in enumerate(unit["sections"]): + with self.subTest(unit=unit["name"], section=section["name"]): + remaining = unit["sections"][:index] + unit["sections"][index + 1:] + failures = [] + check_sections(remaining, unit["measures"], unit["name"], failures) + self.assertTrue(any("coverage" in failure for failure in failures), failures) + + def test_inventory_gate_is_only_in_strict_completion_step(self): + workflow = (Path(__file__).resolve().parents[1] / ".github/workflows/build.yml").read_text(encoding="utf-8") + steps = workflow.split(" - name: ") + inventory_steps = [step for step in steps if "python tools/check_asm_inventory.py" in step] + self.assertEqual(len(inventory_steps), 1) + step = inventory_steps[0] + self.assertTrue(step.startswith("Enforce completion gate\n")) + self.assertIn("if: matrix.version == '43U' && github.event_name == 'workflow_dispatch' && inputs.require_complete == true", step) + self.assertIn("python tools/check_decomp_complete.py", step) + def test_aggregate_fuzzy_float_rounding_passes_only_when_fully_matched(self): report = self.complete_report() report["measures"]["fuzzy_match_percent"] = 99.999886