Files
CoCo3_Plus_MiSTer/tests/test_tooling_guards.py
T

310 lines
15 KiB
Python

"""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
import os
from pathlib import Path
import shutil
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 ActualRepositoryExportPolicy(unittest.TestCase):
def test_actual_inherited_guest_disk_is_not_source(self):
revision = subprocess.check_output(
['git', 'rev-parse', 'HEAD'], cwd=REPOSITORY).decode().strip()
tree = release.committed_tree(revision)
# Inspect the real inherited Git object, not a fabricated .vhd filename.
# changes.txt identifies boot.vhd as mounted/autorun guest software.
self.assertIn('docs/Boot.vhd', tree)
self.assertEqual(len(release.committed_blob(tree['docs/Boot.vhd'])), 224016)
exported = {name for name in tree if release.source_member(name)}
self.assertNotIn('docs/Boot.vhd', exported)
self.assertEqual(release.SOURCE_SUFFIXES['docs'], {'.md'})
self.assertIn('rtl/CPU09/cpu09_119.vhd', exported)
def test_powershell_wrapper_passes_selected_and_default_build(self):
shell = shutil.which('pwsh') or shutil.which('powershell')
if not shell:
self.skipTest('PowerShell unavailable for native wrapper contract')
with tempfile.TemporaryDirectory(dir=REPOSITORY / 'build') as folder:
base = Path(folder)
capture = base / 'capture.json'
fake = base / 'capture-python.ps1'
fake.write_text('$args | ConvertTo-Json -Compress | Set-Content -LiteralPath $env:COCO3PLUS_WRAPPER_CAPTURE\n$global:LASTEXITCODE=0\n')
environment = os.environ.copy()
environment['COCO3PLUS_WRAPPER_CAPTURE'] = str(capture)
for selection in ([], ['-Build', 'build/fpga-qualified']):
with self.subTest(selection=selection):
subprocess.run(
[shell, '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File',
str(REPOSITORY / 'windows/Package-Release.ps1'),
'-Python', str(fake), '-Output', 'dist/qualified',
'-PublicPackage', *selection], cwd=REPOSITORY,
env=environment, check=True, capture_output=True)
arguments = json.loads(capture.read_text(encoding='utf-8-sig'))
index = arguments.index('--build')
self.assertEqual(arguments[index + 1],
selection[-1] if selection else 'build/fpga')
self.assertIn('--public', arguments)
self.assertEqual(arguments[arguments.index('--output') + 1],
'dist/qualified')
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', '[email protected]',
'-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()