"""Exercise simulator-install and source-release boundaries without real ROMs. Copyright (c) 2026 Brian K. Holman. Original test contributions: BSD-3-Clause; see LICENSES/. """ import hashlib import io import json from pathlib import Path import subprocess import sys import tarfile import tempfile import unittest from unittest.mock import patch import zipfile REPOSITORY = Path(__file__).resolve().parents[1] sys.path.insert(0, str(REPOSITORY / 'tools')) import bootstrap import release def digest(path): return hashlib.sha256(path.read_bytes()).hexdigest() class SimulatorInstallGuards(unittest.TestCase): def setUp(self): self.temporary = tempfile.TemporaryDirectory(dir=REPOSITORY / 'build') self.addCleanup(self.temporary.cleanup) self.base = Path(self.temporary.name) def archive(self, *, include_runtime=True): archive = self.base / 'simulator.tgz' members = { 'oss-cad-suite/bin/iverilog.exe': b'fake compiler fixture', 'oss-cad-suite/share/readme.txt': b'fixture support data', } if include_runtime: members['oss-cad-suite/bin/vvp.exe'] = b'fake runtime fixture' with tarfile.open(archive, 'w:gz') as tar: for name, data in members.items(): entry = tarfile.TarInfo(name) entry.size = len(data) tar.addfile(entry, io.BytesIO(data)) return archive, members def test_existing_incomplete_install_is_preserved_and_rejected(self): archive, _ = self.archive() folder = self.base / 'installed' folder.mkdir() sentinel = folder / 'partial-user-file' sentinel.write_bytes(b'preserve prior incomplete evidence') with self.assertRaisesRegex(RuntimeError, 'Incomplete/legacy simulator'): bootstrap.install_simulator(archive, folder, digest(archive)) self.assertEqual(sentinel.read_bytes(), b'preserve prior incomplete evidence') self.assertEqual(list(folder.iterdir()), [sentinel]) self.assertFalse(folder.with_name('installed.partial').exists()) def test_complete_extraction_is_published_then_corruption_is_rejected(self): archive, members = self.archive() folder = self.base / 'installed' archive_hash = digest(archive) bootstrap.install_simulator(archive, folder, archive_hash) self.assertTrue(folder.is_dir()) self.assertFalse(folder.with_name('installed.partial').exists()) marker = json.loads((folder / '.coco3plus-install.json').read_text()) self.assertEqual(marker['archive_sha256'], archive_hash) self.assertEqual(set(marker['files']), set(members)) for name, data in members.items(): self.assertEqual((folder / name).read_bytes(), data) self.assertEqual(marker['files'][name]['sha256'], digest(folder / name)) # A healthy rerun verifies the installed tree. A same-length mutation # must also be rejected; checking existence or length alone is inadequate. bootstrap.install_simulator(archive, folder, archive_hash) executable = folder / 'oss-cad-suite/bin/vvp.exe' mutated = bytearray(executable.read_bytes()) mutated[-1] ^= 1 executable.write_bytes(mutated) with self.assertRaisesRegex(RuntimeError, 'installation incomplete/changed'): bootstrap.install_simulator(archive, folder, archive_hash) self.assertEqual(executable.read_bytes(), bytes(mutated)) def test_failed_extraction_never_publishes_a_complete_directory(self): archive, _ = self.archive(include_runtime=False) folder = self.base / 'installed' with self.assertRaisesRegex(RuntimeError, 'Missing simulator executable'): bootstrap.install_simulator(archive, folder, digest(archive)) self.assertFalse(folder.exists()) partial = folder.with_name('installed.partial') self.assertTrue(partial.is_dir()) self.assertFalse((partial / '.coco3plus-install.json').exists()) class PublicSourceReleaseGuards(unittest.TestCase): def setUp(self): self.temporary = tempfile.TemporaryDirectory(dir=REPOSITORY / 'build') self.addCleanup(self.temporary.cleanup) self.root = Path(self.temporary.name) / 'repository' self.root.mkdir() self.hooks = Path(self.temporary.name) / 'empty-hooks' self.hooks.mkdir() files = { '.gitignore': b'/build/\n/dist/\n', '.gitattributes': b'* -text\n', 'NOTICE.md': b'Fixture notice only.\n', 'LICENSING.md': b'Fixture component terms.\n', 'COPYRIGHT.md': b'Fixture attribution.\n', 'LICENSES/Fixture.txt': b'Fixture license text.\n', 'rtl/ssc/LICENSE': b'Fixture SSC notice only; no ROM contents.\n', 'rtl/example.sv': b'module example; endmodule\n', 'tools/project_inputs.json': json.dumps({'files': [ '.gitignore', 'README.md', 'changes.txt', 'rtl/example.sv' ]}).encode(), 'releases/old.rbf': b'Historic binary fixture; not source payload', 'docs/old.pdf': b'Historic PDF fixture; not source payload', 'docs/old.docx': b'Historic Office fixture; not source payload', 'unused.bin': b'Historic binary fixture; not source payload', } for name, data in files.items(): path = self.root / name path.parent.mkdir(parents=True, exist_ok=True) path.write_bytes(data) self.git('init', '--quiet') self.git('add', '--', *files) self.git('-c', 'user.name=Tooling Test', '-c', 'user.email=tooling-test@example.invalid', '-c', 'commit.gpgsign=false', 'commit', '--quiet', '-m', 'Create isolated fixture') self.tracked = set(files) self.revision = self.git('rev-parse', 'HEAD').decode().strip() self.build = self.root / 'build/fpga' rbf = self.build / 'project/output_files/CoCo3.rbf' rbf.parent.mkdir(parents=True) rbf.write_bytes(b'FAKE RBF FOR RELEASE TEST ONLY') record = { 'passed': True, 'rbf_bytes': rbf.stat().st_size, 'rbf_sha256': digest(rbf), 'project_inventory_sha256': digest(self.root / 'tools/project_inputs.json'), 'inputs': {'rtl/example.sv': digest(self.root / 'rtl/example.sv')}, } (self.build / 'build.json').write_text(json.dumps(record)) self.output = self.root / 'dist/public-release' self.root_patch = patch.object(release, 'ROOT', self.root) self.root_patch.start() self.addCleanup(self.root_patch.stop) def git(self, *arguments): return subprocess.check_output( ['git', '-c', 'core.autocrlf=false', '-c', 'core.hooksPath=' + str(self.hooks), *arguments], cwd=self.root, stderr=subprocess.STDOUT) def package(self): # Neither input directory exists. Public packaging must not read ROMs. return release.make_release( self.output, self.build, self.root / 'missing-boot-roms', self.root / 'missing-ssc-roms', public=True) def test_untracked_private_files_do_not_enter_public_release(self): (self.root / '.env').write_text('fixture-private-value=not-for-export\n') (self.root / 'private-notes.txt').write_text('private fixture notes\n') (self.root / 'LICENSES/private-notice.txt').write_text('PRIVATE NOTICE FIXTURE MUST NOT LEAK\n') untracked = self.git('ls-files', '--others', '--exclude-standard').decode() self.assertIn('.env', untracked) self.assertIn('private-notes.txt', untracked) record = self.package() self.assertTrue(record['public_package']) self.assertFalse(record['ssc_included']) self.assertTrue(record['roms_required_separately']) self.assertEqual(record['source_revision'], self.revision) fat_files = {p.relative_to(self.output / 'fat').as_posix() for p in (self.output / 'fat').rglob('*') if p.is_file()} self.assertFalse(any(Path(n).suffix.lower() in ('.rom', '.bin', '.ccc') for n in fat_files)) self.assertIn('_Computer/.coco3plus/' + record['rbf_sha256'][:12] + '/coco3plus.rbf', fat_files) self.assertEqual(set(record['files']), fat_files) with zipfile.ZipFile(self.output / 'corresponding-source.zip') as archive: source_files = {n for n in archive.namelist() if not n.endswith('/')} self.assertEqual(source_files, {'coco3plus/' + n for n in self.tracked if release.source_member(n)}) self.assertFalse(any('.env' in n or 'private-notes' in n for n in source_files)) self.assertNotIn('coco3plus/LICENSES/private-notice.txt', source_files) self.assertFalse(any(n.endswith(('.rbf', '.pdf', '.docx', '.bin')) for n in source_files)) with zipfile.ZipFile(self.output.with_name('public-release.zip')) as archive: self.assertNotIn('.env', archive.namelist()) self.assertNotIn('private-notes.txt', archive.namelist()) self.assertNotIn('fat/games/coco3plus/licenses/private-notice.txt', archive.namelist()) for name in archive.namelist(): self.assertNotIn(b'PRIVATE NOTICE FIXTURE MUST NOT LEAK', archive.read(name)) checkout = archive.read('SOURCE-CHECKOUT.txt').decode() self.assertIn('git clone ' + release.SOURCE_REPOSITORY, checkout) self.assertIn('git checkout --detach ' + self.revision, checkout) self.assertIn('ZIP alone is not a standalone build checkout', checkout) self.assertEqual(record['project_inventory_sha256'], digest(self.root / 'tools/project_inputs.json')) self.assertNotIn('games/coco3plus/licenses/private-notice.txt', record['files']) def rewrite_receipt(self, transform): receipt = self.build / 'build.json' record = json.loads(receipt.read_text()) transform(record) receipt.write_text(json.dumps(record)) def assert_rejected_without_output(self, pattern): with self.assertRaisesRegex(RuntimeError, pattern): self.package() self.assertFalse(self.output.exists()) self.assertFalse(self.output.with_name('public-release.zip').exists()) def test_legacy_receipt_is_rejected_without_backfilling_evidence(self): self.rewrite_receipt(lambda r: r.pop('project_inventory_sha256')) original = (self.build / 'build.json').read_bytes() self.assert_rejected_without_output('Legacy FPGA receipt lacks') self.assertEqual((self.build / 'build.json').read_bytes(), original) def test_stale_inventory_identity_is_rejected(self): self.rewrite_receipt(lambda r: r.update(project_inventory_sha256='0' * 64)) self.assert_rejected_without_output('does not qualify the current') def test_subset_input_receipt_is_rejected(self): self.rewrite_receipt(lambda r: r['inputs'].pop('rtl/example.sv')) self.assert_rejected_without_output('exact current project input set') def test_extra_input_receipt_is_rejected(self): self.rewrite_receipt(lambda r: r['inputs'].update({'NOTICE.md': digest(self.root / 'NOTICE.md')})) self.assert_rejected_without_output('exact current project input set') def test_matching_set_with_changed_input_bytes_is_rejected(self): self.rewrite_receipt(lambda r: r['inputs'].update({'rtl/example.sv': '0' * 64})) self.assert_rejected_without_output('Source differs from built input') def test_dirty_tracked_source_rejects_before_output_creation(self): notice = self.root / 'NOTICE.md' notice.write_bytes(notice.read_bytes() + b'Unreviewed tracked change.\n') self.assertTrue(self.git('status', '--porcelain', '--untracked-files=no')) with self.assertRaisesRegex(RuntimeError, 'Commit reviewed changes'): self.package() self.assertFalse(self.output.exists()) self.assertFalse(self.output.with_name('public-release.zip').exists()) if __name__ == '__main__': unittest.main()