"""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', } 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), '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') 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}) self.assertFalse(any('.env' in n or 'private-notes' in n 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()) 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()