feat(core): one spelling for a store holding one byte

`Cpu(model, fill=0)` everywhere. Three of the four clocked members did
not have it and each needed a different keyword for the same request, so
a check written against any one of them reported the other three as
broken. That is what the family's own check hit when it started asking
every member for a part it could run a few dozen instructions on.

The rule the family holds is unchanged and now stated more precisely: the
default is never a cleared store, because no machine hands one over. What
changes is that asking for one is possible and has to be written down.
Two members said outright that there was no way to ask, which was already
untrue of them: an image of zeroes did it, less legibly.

The readme runner now reports an example as skipped rather than broken
when the member itself says why it cannot run here, which two members
need because their part runs a program they are not allowed to carry, and
which changes nothing for the fourteen that publish no such reason.

Author: gufranco

README.md

@@ -23,7 +23,7 @@
   <a href="https://github.com/gufranco/sony-spc700-python/issues">Issues</a>
 </p>
 
-**256** opcodes · **256,000** conformance cases and **1,182,940** cycles compared, **0** failures · every cycle count checked against **Nintendo's own tables** · **655** tests · **100%** statement and branch coverage · no dependencies
+**256** opcodes · **256,000** conformance cases and **1,182,940** cycles compared, **0** failures · every cycle count checked against **Nintendo's own tables** · **670** tests · **100%** statement and branch coverage · no dependencies
 
 ```python
 from spc700 import Cpu, SparseMemory

conformance/family.test.py

@@ -188,26 +188,6 @@ def store_attribute() -> str:
     return found[0]
 
 
-def a_store_of_zeroes() -> Any:
-    """A store the part will run through rather than halt in.
-
-    Taken off a part the member built and written through the part, so no store
-    type has to be named and no constructor keyword has to be guessed. Left in
-    scrambled memory a part reaches an undocumented opcode within a few dozen
-    instructions and stops, which is correct behaviour and useless for testing a
-    limit.
-
-    A page is enough: the checks that use this run a few dozen instructions from
-    address zero, and zeroing the whole space on a part with a sixteen megabyte
-    one costs seconds for nothing.
-    """
-    part = PACKAGE.Cpu(PACKAGE.DEFAULT_MODEL)
-    held = getattr(part, store_attribute())
-    for address in range(0x100):
-        part.write8(address, 0x00)
-    return held
-
-
 def accounts_for_one_interrupt(node: Any) -> bool:
     """Whether a record says anything about the part having one interrupt line.
 
@@ -239,11 +219,14 @@ def at_the_start(part: Any) -> None:
 def a_running_part() -> Part:
     """A part pointed at a field of no-operations, so a bound is what is tested.
 
-    Left in scrambled memory a part reaches an undocumented opcode within a few
-    dozen instructions and halts, which is correct behaviour and useless for
-    testing a limit.
+    `fill` is the one spelling across this family for a store holding one byte
+    everywhere. It exists for exactly this: left in scrambled memory a part
+    reaches an undocumented opcode within a few dozen instructions and stops,
+    which is correct behaviour and useless for testing a limit. Three of the four
+    clocked members did not have it and each needed a different keyword, so a
+    check written against any one of them reported the other three as broken.
     """
-    part = PACKAGE.Cpu(PACKAGE.DEFAULT_MODEL, a_store_of_zeroes())
+    part = PACKAGE.Cpu(PACKAGE.DEFAULT_MODEL, fill=0)
     at_the_start(part)
     checked: Part = part
     return checked

conformance/readme.test.py

@@ -9,20 +9,80 @@
 Each example runs in a fresh interpreter rather than in this one. An example that
 only works because a test already imported something is not an example a reader
 can paste, and running it here in-process would hide that.
+
+An example that cannot run at all here is reported as skipped rather than as
+broken, and only when the member itself says why. Two members model a part that
+runs a program their repository is not allowed to carry, so on a machine without
+one every example that builds a part refuses. That refusal is the package working
+correctly, and counting it as a broken example would make a bare checkout look
+like a defect while hiding real ones behind it.
+
+What decides is the member's own `why_not`, which is the same sentence its doctor
+prints. A member that publishes none skips nothing, and on a machine that has the
+files nothing is skipped either, so the check keeps its teeth exactly where it
+had them.
 """
 
 from __future__ import annotations
 
+import importlib
 import re
 import subprocess
 import sys
 import unittest
 from pathlib import Path
+from types import ModuleType
 
 ROOT = Path(__file__).resolve().parent.parent
 
 README = ROOT / "README.md"
 
+
+def packages() -> list[str]:
+    """The importable package in this repository, which is the member itself.
+
+    The conformance directory is one too and is not the member, so it is left
+    out by name rather than by position.
+    """
+    return sorted(
+        found.name
+        for found in ROOT.iterdir()
+        if (found / "__init__.py").is_file() and found.name != "conformance"
+    )
+
+
+def cannot_run_here(named: list[str] | None = None) -> str | None:
+    """Why this member cannot build its part on this machine, or nothing.
+
+    Read off the package rather than guessed from a traceback, so the sentence
+    an example is excused by is the sentence the member itself publishes.
+
+    The names are a parameter so this can be driven against a member that
+    publishes a reason from a member that does not, and the other way round.
+    Nine of the sixteen publish nothing, and a branch only two of them reach is
+    a branch nobody has seen work.
+    """
+    if str(ROOT) not in sys.path:
+        sys.path.insert(0, str(ROOT))
+    for name in packages() if named is None else named:
+        asked = getattr(importlib.import_module(name), "why_not", None)
+        if callable(asked):
+            answer = asked()
+            return str(answer) if answer else None
+    return None
+
+
+def excused(failure: str, reason: str | None = None) -> bool:
+    """Whether that failure is the member saying it has no file to run.
+
+    Matched on a run of the member's own sentence rather than on an exception
+    name, because the name differs per member and the sentence is the thing the
+    member publishes for exactly this purpose.
+    """
+    said = cannot_run_here() if reason is None else reason
+    return bool(said) and str(said)[:40] in failure
+
+
 BLOCK = re.compile(r"^```(\w*)\n(.*?)^```$", re.M | re.S)
 
 
@@ -61,29 +121,38 @@ def ran(source: str) -> subprocess.CompletedProcess[str]:
     )
 
 
-def broken(found: list[tuple[str, str | None]]) -> list[str]:
+def broken(found: list[tuple[str, str | None]], reason: str | None = None) -> list[str]:
     """The last line of the traceback of every example that will not run.
 
     A process can exit non-zero and print nothing, so the reason falls back to
     the exit code rather than indexing an empty list. A checker that raises
     while collecting a fault reports neither that fault nor any after it.
     """
     failed = []
+    reason = cannot_run_here() if reason is None else reason
     for source, _ in found:
         finished = ran(source)
-        if finished.returncode != 0:
-            said = finished.stderr.strip().splitlines()
-            failed.append(said[-1] if said else f"exited {finished.returncode} in silence")
+        if finished.returncode == 0:
+            continue
+        if excused(finished.stderr, reason):
+            continue
+        said = finished.stderr.strip().splitlines()
+        failed.append(said[-1] if said else f"exited {finished.returncode} in silence")
     return failed
 
 
-def mismatched(found: list[tuple[str, str | None]]) -> list[tuple[str, str]]:
+def mismatched(
+    found: list[tuple[str, str | None]], reason: str | None = None
+) -> list[tuple[str, str]]:
     """What the readme claims each example prints, beside what it printed."""
     wrong = []
+    reason = cannot_run_here() if reason is None else reason
     for source, expected in found:
         if expected is None:
             continue
         finished = ran(source)
+        if finished.returncode != 0 and excused(finished.stderr, reason):
+            continue
         if finished.stdout != expected:
             wrong.append((expected.strip(), finished.stdout.strip()))
     return wrong
@@ -137,6 +206,72 @@ def test_and_a_later_example_is_still_checked_after_an_earlier_one_failed(self)
 
         self.assertEqual(mismatched(examples(readme)), [("2", "1")])
 
+    def test_a_member_that_can_run_everything_excuses_nothing(self) -> None:
+        """The teeth stay where they were on every member that ships its own part."""
+        self.assertFalse(excused("anything at all", None if cannot_run_here() else "x" * 60))
+
+    def test_a_failure_the_member_says_it_expects_is_excused(self) -> None:
+        reason = "no firmware image was found: this backend runs the part's own microcode"
+
+        self.assertTrue(excused(f"Traceback\nNoFirmware: {reason}", reason))
+
+    def test_and_any_other_failure_is_not(self) -> None:
+        """Driven against the shape that would otherwise slip through."""
+        reason = "no firmware image was found: this backend runs the part's own microcode"
+
+        self.assertFalse(excused("Traceback\nZeroDivisionError: division by zero", reason))
+
+    def test_and_a_member_that_publishes_no_reason_excuses_nothing(self) -> None:
+        self.assertFalse(excused("Traceback\nNoFirmware: anything", ""))
+
+    def test_an_example_that_only_this_machine_can_run_is_reported_as_broken(self) -> None:
+        """So the excuse cannot be claimed by an example that simply does not work."""
+        readme = "```python\nraise ValueError('nope')\n```\n"
+
+        self.assertEqual(broken(examples(readme)), ["ValueError: nope"])
+
+    def test_an_example_the_member_says_it_cannot_run_is_not_reported_as_broken(self) -> None:
+        readme = "```python\nraise SystemExit('no image is here')\n```\n"
+
+        self.assertEqual(broken(examples(readme), "no image is here"), [])
+
+    def test_and_its_stated_output_is_not_compared_either(self) -> None:
+        """An example that never ran produced no output to compare."""
+        readme = "```python\nraise SystemExit('no image is here')\n```\n\n```\n7\n```\n"
+
+        self.assertEqual(mismatched(examples(readme), "no image is here"), [])
+
+    def test_a_member_that_publishes_a_reason_is_read(self) -> None:
+        """Driven against a stand-in, because nine of the sixteen publish none."""
+        speaking = ModuleType("speaking")
+        speaking.why_not = lambda: "no image is here"  # type: ignore[attr-defined]
+        sys.modules["speaking"] = speaking
+        try:
+            self.assertEqual(cannot_run_here(["speaking"]), "no image is here")
+        finally:
+            del sys.modules["speaking"]
+
+    def test_and_one_that_publishes_nothing_to_say_says_nothing(self) -> None:
+        quiet = ModuleType("quiet")
+        quiet.why_not = lambda: None  # type: ignore[attr-defined]
+        sys.modules["quiet"] = quiet
+        try:
+            self.assertIsNone(cannot_run_here(["quiet"]))
+        finally:
+            del sys.modules["quiet"]
+
+    def test_and_one_that_publishes_no_such_call_is_passed_over(self) -> None:
+        silent = ModuleType("silent")
+        sys.modules["silent"] = silent
+        try:
+            self.assertIsNone(cannot_run_here(["silent"]))
+        finally:
+            del sys.modules["silent"]
+
+    def test_the_member_this_repository_holds_is_found_by_name(self) -> None:
+        """So the sweep cannot start reading the conformance directory instead."""
+        self.assertNotIn("conformance", packages())
+
     def test_an_example_with_no_stated_output_is_only_run(self) -> None:
         readme = "```python\nprint(1)\n```\n"
 

spc700/__init__.py

@@ -36,15 +36,27 @@
 
 
 def Cpu(  # noqa: N802
-    model: str = DEFAULT_MODEL, memory: Any = None, **options: Any
+    model: str = DEFAULT_MODEL,
+    memory: Any = None,
+    fill: int | None = None,
+    **options: Any,
 ) -> Any:
     """A processor of the named model, sharing one interface across the family.
 
     The model comes first because it is the thing a caller always knows and
     memory is the thing they often do not care about yet. Omitting it hands back
     a part with memory of its own, scrambled rather than cleared, which is what a
     board holds before anything has written to it.
+
+    `fill` is the one way across this family to ask for a store holding one byte
+    everywhere. It is not what a board hands over and it is not the default: a
+    caller asking for zeroes is asking for something no machine does, so they
+    have to say so. What it is for is a run that has to get through a few dozen
+    instructions without meeting an opcode that stops the part, which is what
+    every check of a cycle budget needs and what scrambled memory cannot give.
     """
+    if fill is not None and memory is None:
+        memory = Memory(fill=fill)
     return describe(model).build(SparseMemory() if memory is None else memory, **options)
 
 

spc700/models.test.py

@@ -66,5 +66,48 @@ def test_a_model_the_family_does_not_have_is_refused_at_construction(self) -> No
             spc700.Cpu("6502", Memory(fill=0))
 
 
+class QuietStoreTest(unittest.TestCase):
+    """`fill`, which is the one spelling across this family for a store of one byte.
+
+    Not what a board hands over and not the default: a caller asking for zeroes
+    is asking for something no machine does, so they have to say so. What it is
+    for is a run that has to get through a few dozen instructions without meeting
+    an opcode that stops the part, which is what every check of a cycle budget
+    needs and what scrambled memory cannot give.
+    """
+
+    def test_a_fill_puts_that_byte_everywhere(self) -> None:
+        part = spc700.Cpu(spc700.DEFAULT_MODEL, fill=0)
+
+        self.assertEqual({part.memory.read8(address) for address in range(0x40)}, {0})
+
+    def test_and_any_byte_works_rather_than_only_zero(self) -> None:
+        part = spc700.Cpu(spc700.DEFAULT_MODEL, fill=0xAA)
+
+        self.assertEqual({part.memory.read8(address) for address in range(0x40)}, {0xAA})
+
+    def test_without_one_the_store_is_scrambled_rather_than_cleared(self) -> None:
+        """The default has to stay the thing a machine actually hands over.
+
+        Read address by address rather than off the store's own bytes, because
+        the default store allocates nothing until it is asked and has no bytes
+        to read.
+        """
+        part = spc700.Cpu(spc700.DEFAULT_MODEL)
+
+        held = {part.memory.read8(address) for address in range(0x40)}
+
+        self.assertNotEqual(held, {0})
+
+    def test_and_a_store_handed_in_is_left_alone(self) -> None:
+        """So `fill` cannot quietly replace memory a caller already built."""
+        own = spc700.Memory(fill=0xAA)
+
+        part = spc700.Cpu(spc700.DEFAULT_MODEL, own, fill=0)
+
+        self.assertIs(part.memory, own)
+        self.assertEqual({part.memory.read8(address) for address in range(0x40)}, {0xAA})
+
+
 if __name__ == "__main__":
     unittest.main()