@invarn/cibuild 2.0.1 → 2.0.3

package/dist/src/yaml/steps/ui-fidelity-render.test.js

@@ -16,6 +16,7 @@
  */
 import { describe, test, expect, afterAll } from '@jest/globals';
 import { spawnSync } from 'node:child_process';
+import { gzipSync } from 'node:zlib';
 import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync, } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -29,25 +30,45 @@ const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 const FIXTURE_PACKAGE = resolve(dirname(fileURLToPath(import.meta.url)), '../../../test/fixtures/ui-fidelity-package');
 /**
  * Fake `swift` CLI. Mirrors the exact invocations the render script makes:
+ *   swift package --package-path <dir> dump-package
  *   swift build --package-path <dir> --target RenderProbe
  *   swift build --package-path <dir> --product Render_<Screen>
  *   swift run --package-path <dir> --skip-build Render_<Screen> <output.png>
+ * dump-package output is driven by FAKE_SWIFT_DUMP_PRODUCTS (comma-separated
+ * library product names; unset = "FixtureViews", empty = no products) and
+ * FAKE_SWIFT_DUMP_FAIL.
  */
 const FAKE_SWIFT_LINES = [
     '#!/bin/bash',
     '[ -n "$FAKE_SWIFT_LOG" ] && echo "$*" >> "$FAKE_SWIFT_LOG"',
     'cmd="$1"; shift',
     'case "$cmd" in',
+    '  package)',
+    '    if [ -n "$FAKE_SWIFT_DUMP_FAIL" ]; then',
+    '      echo "error: malformed Package.swift manifest" >&2',
+    '      exit 1',
+    '    fi',
+    '    products="${FAKE_SWIFT_DUMP_PRODUCTS-FixtureViews}"',
+    '    json=""',
+    '    IFS=","',
+    '    for p in $products; do',
+    '      [ -n "$json" ] && json="$json,"',
+    '      json="$json{\\"name\\":\\"$p\\",\\"type\\":{\\"library\\":[\\"automatic\\"]}}"',
+    '    done',
+    '    printf \'{"name":"shipped-package","products":[%s]}\\n\' "$json"',
+    '    exit 0 ;;',
     '  build)',
-    '    product=""; target=""; pkg=""',
+    '    product=""; target=""; pkg=""; showbin=""',
     '    while [ $# -gt 0 ]; do',
     '      case "$1" in',
     '        --product) product="$2"; shift 2 ;;',
     '        --target) target="$2"; shift 2 ;;',
     '        --package-path) pkg="$2"; shift 2 ;;',
+    '        --show-bin-path) showbin=1; shift ;;',
     '        *) shift ;;',
     '      esac',
     '    done',
+    '    if [ -n "$showbin" ]; then echo "$pkg/.build/debug"; exit 0; fi',
     '    name="${product:-$target}"',
     '    if [ "$name" = "RenderProbe" ]; then',
     '      if [ -n "$FAKE_SWIFT_PROBE_FAIL" ]; then',
@@ -90,6 +111,35 @@ const FAKE_SWIFT_LINES = [
     '    exit 0 ;;',
     'esac',
 ];
+/**
+ * PATH-shimmed fake `xcrun` covering `xcrun actool`. Logs its args to
+ * $FAKE_XCRUN_LOG, writes a stub Assets.car into the --compile directory,
+ * and fails (exit 1) when FAKE_ACTOOL_FAIL is set so the warn-and-continue
+ * path is exercisable.
+ */
+const FAKE_XCRUN_LINES = [
+    '#!/bin/bash',
+    '[ -n "$FAKE_XCRUN_LOG" ] && echo "$*" >> "$FAKE_XCRUN_LOG"',
+    'sub="$1"; shift',
+    'case "$sub" in',
+    '  actool)',
+    '    out=""',
+    '    while [ $# -gt 0 ]; do',
+    '      case "$1" in',
+    '        --compile) out="$2"; shift 2 ;;',
+    '        *) shift ;;',
+    '      esac',
+    '    done',
+    '    if [ -n "$FAKE_ACTOOL_FAIL" ]; then',
+    '      echo "error: actool: malformed asset catalog" >&2',
+    '      exit 1',
+    '    fi',
+    '    [ -n "$out" ] && mkdir -p "$out" && printf \'fake-car\' > "$out/Assets.car"',
+    '    exit 0 ;;',
+    '  *)',
+    '    exit 0 ;;',
+    'esac',
+];
 const tempDirs = [];
 afterAll(() => {
     for (const dir of tempDirs) {
@@ -112,6 +162,9 @@ function makeProject(params) {
     const swiftPath = join(binDir, 'swift');
     writeFileSync(swiftPath, FAKE_SWIFT_LINES.join('\n') + '\n');
     chmodSync(swiftPath, 0o755);
+    const xcrunPath = join(binDir, 'xcrun');
+    writeFileSync(xcrunPath, FAKE_XCRUN_LINES.join('\n') + '\n');
+    chmodSync(xcrunPath, 0o755);
     if (params !== undefined) {
         writeFileSync(join(dir, '.ci', 'inputs', 'params.json'), typeof params === 'string' ? params : JSON.stringify(params));
     }
@@ -136,6 +189,66 @@ function runScript(project, script, env = {}) {
         },
     });
 }
+function tarHeader(name, size, typeflag) {
+    const header = Buffer.alloc(512);
+    header.write(name, 0, 100, 'utf-8');
+    header.write('0000755\0', 100, 8, 'ascii'); // mode
+    header.write('0000000\0', 108, 8, 'ascii'); // uid
+    header.write('0000000\0', 116, 8, 'ascii'); // gid
+    header.write(size.toString(8).padStart(11, '0') + '\0', 124, 12, 'ascii');
+    header.write('00000000000\0', 136, 12, 'ascii'); // mtime
+    header.write('        ', 148, 8, 'ascii'); // checksum placeholder
+    header.write(typeflag, 156, 1, 'ascii');
+    header.write('ustar\0' + '00', 257, 8, 'ascii');
+    let checksum = 0;
+    for (const byte of header)
+        checksum += byte;
+    header.write(checksum.toString(8).padStart(6, '0') + '\0 ', 148, 8, 'ascii');
+    return header;
+}
+function makeTarGz(entries) {
+    const blocks = [];
+    for (const entry of entries) {
+        const isDir = entry.name.endsWith('/');
+        const content = Buffer.from(entry.content ?? '', 'utf-8');
+        blocks.push(tarHeader(entry.name, isDir ? 0 : content.length, isDir ? '5' : '0'));
+        if (!isDir && content.length > 0) {
+            const padded = Buffer.alloc(Math.ceil(content.length / 512) * 512);
+            content.copy(padded);
+            blocks.push(padded);
+        }
+    }
+    blocks.push(Buffer.alloc(1024)); // end-of-archive
+    return gzipSync(Buffer.concat(blocks));
+}
+const SHIPPED_MANIFEST = [
+    '// swift-tools-version:5.9',
+    'import PackageDescription',
+    'let package = Package(',
+    '    name: "shipped-package",',
+    '    platforms: [.macOS(.v13)],',
+    '    products: [.library(name: "FixtureViews", targets: ["FixtureViews"])],',
+    '    targets: [.target(name: "FixtureViews")]',
+    ')',
+].join('\n');
+/** Entries for a well-formed shipped package under the given root dir ('' = flat). */
+function shippedPackageEntries(root = 'pkg') {
+    const prefix = root === '' ? '' : root + '/';
+    const entries = root === '' ? [] : [{ name: prefix }];
+    entries.push({ name: prefix + 'Package.swift', content: SHIPPED_MANIFEST }, {
+        name: prefix + 'Sources/FixtureViews/HomeView.swift',
+        content: 'import SwiftUI\npublic struct HomeView: View { public init() {} public var body: some View { Text("home") } }\n',
+    });
+    return entries;
+}
+function stageArchive(project, archive) {
+    writeFileSync(join(project.dir, '.ci', 'inputs', 'package.tar.gz'), Buffer.isBuffer(archive) ? archive : makeTarGz(archive));
+}
+async function buildInputsScript(extra = {}) {
+    const executor = new UiFidelityRenderStepExecutor();
+    const step = await executor.execute({ package_source: 'inputs', ...extra }, {}, testConfig);
+    return step.script;
+}
 function readResult(project) {
     const resultPath = join(project.dir, '.ci', 'artifacts', 'protocol-result.json');
     expect(existsSync(resultPath)).toBe(true);
@@ -151,8 +264,9 @@ function isPng(filePath) {
 /**
  * Asserts that no error message in the result document contains an absolute
  * runner-filesystem path: not the project dir (the script's cwd), not the OS
- * temp dir (where harness packages live), in either symlinked
- * (/var/folders/...) or resolved (/private/var/...) form.
+ * temp dir (where harness packages and extracted shipped packages live), in
+ * either symlinked (/var/folders/...) or resolved (/private/var/...) form.
+ * Covers both per-screen errors and the build-level error object.
  */
 function expectNoAbsolutePathLeaks(project, result) {
     const forbidden = new Set();
@@ -165,8 +279,9 @@ function expectNoAbsolutePathLeaks(project, result) {
             // nonexistent — literal form only
         }
     }
-    for (const screen of result.screens) {
-        const message = screen.error?.message ?? '';
+    const messages = result.screens.map((screen) => screen.error?.message ?? '');
+    messages.push(result.error?.message ?? '');
+    for (const message of messages) {
         for (const dir of forbidden) {
             expect(message).not.toContain(dir);
         }
@@ -182,18 +297,38 @@ describe('registry integration', () => {
         const inputs = metadata?.inputs ?? {};
         expect(Object.keys(inputs).sort()).toEqual([
             'package_path',
+            'package_source',
             'render_size',
             'scale',
             'target',
         ]);
-        expect(inputs.package_path.required).toBe(true);
-        expect(inputs.target.required).toBe(true);
+        // package_path/target are enforced by the executor in repo mode (the
+        // default); a package_source:inputs config is valid without either, so
+        // neither is unconditionally required at the schema level.
+        expect(inputs.package_path.required).toBe(false);
+        expect(inputs.target.required).toBe(false);
+        expect(inputs.package_source.required).toBe(false);
+        expect(inputs.package_source.default).toBe('repo');
         expect(inputs.render_size.required).toBe(false);
         expect(inputs.render_size.default).toBe(DEFAULT_RENDER_SIZE);
         expect(inputs.scale.required).toBe(false);
         expect(inputs.scale.default).toBe(DEFAULT_SCALE);
     });
 });
+describe('v1 byte compatibility', () => {
+    // Snapshot of the script generated before package_source existed, captured
+    // from the executor with package_path './MyAppPackage' and target
+    // 'MyAppViews' (defaults for everything else). Omitting package_source must
+    // keep the generated script byte-identical to that snapshot, so existing
+    // protocols are provably untouched. Update the snapshot only for a
+    // deliberate, reviewed change to the v1 runtime.
+    const V1_SCRIPT_SNAPSHOT = resolve(dirname(fileURLToPath(import.meta.url)), '../../../test/fixtures/ui-fidelity-render-v1-script.txt');
+    test('omitting package_source generates a byte-identical script', async () => {
+        const executor = new UiFidelityRenderStepExecutor();
+        const step = await executor.execute({ package_path: './MyAppPackage', target: 'MyAppViews' }, {}, testConfig);
+        expect(step.script).toBe(readFileSync(V1_SCRIPT_SNAPSHOT, 'utf-8'));
+    });
+});
 describe('UiFidelityRenderStepExecutor', () => {
     test('returns a node StepDef', async () => {
         const executor = new UiFidelityRenderStepExecutor();
@@ -234,6 +369,52 @@ describe('UiFidelityRenderStepExecutor', () => {
         await expect(executor.execute({ package_path: './pkg', target: 'MyViews', render_size: 'huge' }, {}, testConfig)).rejects.toThrow(/render_size/);
     });
 });
+describe('package_source input', () => {
+    test('rejects an unknown package_source value', async () => {
+        const executor = new UiFidelityRenderStepExecutor();
+        await expect(executor.execute({ package_path: './pkg', target: 'MyViews', package_source: 'artifact' }, {}, testConfig)).rejects.toThrow(/package_source/);
+    });
+    test('omitting package_source bakes no packageSource into the script config', async () => {
+        const executor = new UiFidelityRenderStepExecutor();
+        const step = await executor.execute({ package_path: './pkg', target: 'MyViews' }, {}, testConfig);
+        expect(step.script).not.toContain('packageSource');
+    });
+    test('explicit repo keeps the v1 inputs required and records the source', async () => {
+        const executor = new UiFidelityRenderStepExecutor();
+        const step = await executor.execute({ package_path: './pkg', target: 'MyViews', package_source: 'repo' }, {}, testConfig);
+        expect(step.kind).toBe('node');
+        expect(step.script).toContain('"packageSource":"repo"');
+        expect(step.script).toContain('"packagePath":"./pkg"');
+        await expect(executor.execute({ target: 'MyViews', package_source: 'repo' }, {}, testConfig)).rejects.toThrow("Missing required input 'package_path'");
+        await expect(executor.execute({ package_path: './pkg', package_source: 'repo' }, {}, testConfig)).rejects.toThrow("Missing required input 'target'");
+    });
+    test('inputs mode requires neither package_path nor target', async () => {
+        const script = await buildInputsScript();
+        expect(script).toContain('"packageSource":"inputs"');
+        expect(script).toContain('"packagePath":null');
+        expect(script).toContain('"target":null');
+    });
+    test('inputs mode ignores package_path and honors an explicit target', async () => {
+        const script = await buildInputsScript({ package_path: './pkg', target: 'MyViews' });
+        expect(script).toContain('"packagePath":null');
+        expect(script).toContain('"target":"MyViews"');
+    });
+    test('inputs mode still rejects a malformed target', async () => {
+        const executor = new UiFidelityRenderStepExecutor();
+        await expect(executor.execute({ package_source: 'inputs', target: 'My Views' }, {}, testConfig)).rejects.toThrow(/target/i);
+    });
+    test('validation requirements branch on the package source', () => {
+        const executor = new UiFidelityRenderStepExecutor();
+        const v1Names = executor
+            .getValidationRequirements({ package_path: './pkg', target: 'MyViews' }, {}, testConfig)
+            .map((requirement) => requirement.name);
+        expect(v1Names).toEqual(['package_path', 'target', 'swift']);
+        const inputsNames = executor
+            .getValidationRequirements({ package_source: 'inputs' }, {}, testConfig)
+            .map((requirement) => requirement.name);
+        expect(inputsNames).toEqual(['swift', 'tar']);
+    });
+});
 describe('render size and scale parsing', () => {
     test('default render size is 393x852 device points', () => {
         expect(DEFAULT_RENDER_SIZE).toBe('393x852');
@@ -692,6 +873,429 @@ describe('render script runtime', () => {
         expect(readResult(project).screens[0].status).toBe('rendered');
     });
 });
+describe('render script runtime (package_source: repo)', () => {
+    test('explicit repo renders like v1 and records the package source', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        const script = await buildScript(project, { package_source: 'repo' });
+        const run = runScript(project, script);
+        expect(run.status).toBe(0);
+        expect(isPng(artifact(project, 'ui-fidelity/rendered/HomeView.png'))).toBe(true);
+        expect(readResult(project)).toEqual({
+            renderer: 'imagerenderer-spm',
+            package_source: 'repo',
+            error: null,
+            screens: [
+                {
+                    screen: 'HomeView',
+                    status: 'rendered',
+                    error: null,
+                    reference_image_path: 'ui-fidelity/references/HomeView.png',
+                    rendered_image_path: 'ui-fidelity/rendered/HomeView.png',
+                },
+            ],
+        });
+    });
+    test('compiles asset catalogs found in the package before rendering', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        // A catalog at the package root: SwiftPM ignores it, so the renderer must
+        // compile it with actool for Image("name") to resolve at render time.
+        const catalog = join(project.packageDir, 'Assets', 'Media.xcassets');
+        mkdirSync(catalog, { recursive: true });
+        writeFileSync(join(catalog, 'Contents.json'), '{}');
+        const script = await buildScript(project, { package_source: 'repo' });
+        const xcrunLog = join(project.dir, 'xcrun-invocations.log');
+        const run = runScript(project, script, { FAKE_XCRUN_LOG: xcrunLog });
+        expect(run.status).toBe(0);
+        expect(isPng(artifact(project, 'ui-fidelity/rendered/HomeView.png'))).toBe(true);
+        const xcrunCalls = readFileSync(xcrunLog, 'utf-8');
+        expect(xcrunCalls).toContain('actool');
+        expect(xcrunCalls).toContain('Media.xcassets');
+        expect(xcrunCalls).toContain('--compile');
+        expect(xcrunCalls).toContain('--platform macosx');
+    });
+    test('does not invoke actool when the package has no asset catalogs', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        const script = await buildScript(project, { package_source: 'repo' });
+        const xcrunLog = join(project.dir, 'xcrun-invocations.log');
+        const run = runScript(project, script, { FAKE_XCRUN_LOG: xcrunLog });
+        expect(run.status).toBe(0);
+        expect(isPng(artifact(project, 'ui-fidelity/rendered/HomeView.png'))).toBe(true);
+        expect(existsSync(xcrunLog)).toBe(false);
+    });
+    test('a failing asset-catalog compile warns but still renders (warn-and-continue)', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        const catalog = join(project.packageDir, 'Media.xcassets');
+        mkdirSync(catalog, { recursive: true });
+        writeFileSync(join(catalog, 'Contents.json'), '{}');
+        const script = await buildScript(project, { package_source: 'repo' });
+        const run = runScript(project, script, { FAKE_ACTOOL_FAIL: '1' });
+        expect(run.status).toBe(0);
+        expect(isPng(artifact(project, 'ui-fidelity/rendered/HomeView.png'))).toBe(true);
+        expect(run.stderr).toContain('asset-catalog compile failed');
+    });
+});
+describe('render script runtime (package_source: inputs)', () => {
+    test('renders every screen from a shipped archive with a single package root', async () => {
+        const project = makeProject({
+            screens: { HomeView: 'home.png', SettingsView: 'settings.png' },
+        });
+        writeReference(project, 'home.png');
+        writeReference(project, 'settings.png');
+        stageArchive(project, shippedPackageEntries('pkg'));
+        const script = await buildInputsScript({ target: 'FixtureViews' });
+        const logPath = join(project.dir, 'swift-invocations.log');
+        const run = runScript(project, script, {
+            FAKE_SWIFT_LOG: logPath,
+            UI_FIDELITY_KEEP_HARNESS: '1',
+        });
+        expect(run.status).toBe(0);
+        expect(isPng(artifact(project, 'ui-fidelity/rendered/HomeView.png'))).toBe(true);
+        expect(isPng(artifact(project, 'ui-fidelity/rendered/SettingsView.png'))).toBe(true);
+        expect(readResult(project)).toEqual({
+            renderer: 'imagerenderer-spm',
+            package_source: 'inputs',
+            error: null,
+            screens: [
+                {
+                    screen: 'HomeView',
+                    status: 'rendered',
+                    error: null,
+                    reference_image_path: 'ui-fidelity/references/HomeView.png',
+                    rendered_image_path: 'ui-fidelity/rendered/HomeView.png',
+                },
+                {
+                    screen: 'SettingsView',
+                    status: 'rendered',
+                    error: null,
+                    reference_image_path: 'ui-fidelity/references/SettingsView.png',
+                    rendered_image_path: 'ui-fidelity/rendered/SettingsView.png',
+                },
+            ],
+        });
+        // The synthesized harness depends on the EXTRACTED package, not on any
+        // path in the repo checkout.
+        const probeArgs = readFileSync(logPath, 'utf-8').trim().split('\n')[0].split(' ');
+        const harnessDir = probeArgs[probeArgs.indexOf('--package-path') + 1];
+        tempDirs.push(harnessDir);
+        const manifest = readFileSync(join(harnessDir, 'Package.swift'), 'utf-8');
+        expect(manifest).toMatch(/\.package\(path: "[^"]*ui-fidelity-package-[^"]*\/pkg"\)/);
+        expect(manifest).toContain('.product(name: "FixtureViews", package: "pkg")');
+        const extracted = manifest.match(/\.package\(path: "([^"]*)\/pkg"\)/);
+        if (extracted)
+            tempDirs.push(extracted[1]);
+    });
+    test('accepts Package.swift at the archive root', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        stageArchive(project, shippedPackageEntries(''));
+        const run = runScript(project, await buildInputsScript({ target: 'FixtureViews' }));
+        expect(run.status).toBe(0);
+        const result = readResult(project);
+        expect(result.error).toBeNull();
+        expect(result.screens[0].status).toBe('rendered');
+    });
+    test('ignores macOS junk entries when locating the package root', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        stageArchive(project, [
+            { name: '.DS_Store', content: 'junk' },
+            { name: '._pkg', content: 'apple-double junk' },
+            ...shippedPackageEntries('pkg'),
+        ]);
+        const run = runScript(project, await buildInputsScript({ target: 'FixtureViews' }));
+        expect(run.status).toBe(0);
+        expect(readResult(project).screens[0].status).toBe('rendered');
+    });
+    test('discovers the target from a single library product', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        stageArchive(project, shippedPackageEntries('pkg'));
+        const logPath = join(project.dir, 'swift-invocations.log');
+        const run = runScript(project, await buildInputsScript(), {
+            FAKE_SWIFT_LOG: logPath,
+            UI_FIDELITY_KEEP_HARNESS: '1',
+        });
+        expect(run.status).toBe(0);
+        expect(readResult(project).screens[0].status).toBe('rendered');
+        const invocations = readFileSync(logPath, 'utf-8').trim().split('\n');
+        expect(invocations[0]).toContain('dump-package');
+        const dumpArgs = invocations[0].split(' ');
+        tempDirs.push(dumpArgs[dumpArgs.indexOf('--package-path') + 1]);
+        // The discovered product is what the harness imports.
+        const probeArgs = invocations[1].split(' ');
+        const harnessDir = probeArgs[probeArgs.indexOf('--package-path') + 1];
+        tempDirs.push(harnessDir);
+        expect(readFileSync(join(harnessDir, 'Sources', 'Render_HomeView', 'Render.swift'), 'utf-8')).toContain('import FixtureViews');
+    });
+    test('an explicit target skips manifest discovery', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        stageArchive(project, shippedPackageEntries('pkg'));
+        const logPath = join(project.dir, 'swift-invocations.log');
+        const run = runScript(project, await buildInputsScript({ target: 'FixtureViews' }), { FAKE_SWIFT_LOG: logPath });
+        expect(run.status).toBe(0);
+        expect(readFileSync(logPath, 'utf-8')).not.toContain('dump-package');
+    });
+    test('cleans up the extraction scratch directory after rendering', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        stageArchive(project, shippedPackageEntries('pkg'));
+        const logPath = join(project.dir, 'swift-invocations.log');
+        const run = runScript(project, await buildInputsScript(), { FAKE_SWIFT_LOG: logPath });
+        expect(run.status).toBe(0);
+        // The dump-package invocation names the extracted package root.
+        const dumpArgs = readFileSync(logPath, 'utf-8').trim().split('\n')[0].split(' ');
+        const extractedRoot = dumpArgs[dumpArgs.indexOf('--package-path') + 1];
+        expect(extractedRoot).toContain('ui-fidelity-package-');
+        expect(existsSync(extractedRoot)).toBe(false);
+    });
+    test('missing archive yields PACKAGE_ARCHIVE_MISSING with every screen entry present', async () => {
+        const project = makeProject({
+            screens: { HomeView: 'home.png', SettingsView: 'settings.png' },
+        });
+        writeReference(project, 'home.png');
+        writeReference(project, 'settings.png');
+        const logPath = join(project.dir, 'swift-invocations.log');
+        const run = runScript(project, await buildInputsScript({ target: 'FixtureViews' }), {
+            FAKE_SWIFT_LOG: logPath,
+        });
+        expect(run.status).not.toBe(0);
+        const result = readResult(project);
+        expect(result.package_source).toBe('inputs');
+        expect(result.error?.code).toBe('PACKAGE_ARCHIVE_MISSING');
+        expect(result.error?.message).toContain('package.tar.gz');
+        // v1 invariant: every screen entry is present even on build-level
+        // failure, with the build error kept distinct from per-screen errors.
+        expect(result.screens).toHaveLength(2);
+        for (const screen of result.screens) {
+            expect(screen.status).toBe('render_failed');
+            expect(screen.error).toBeNull();
+            expect(screen.reference_image_path).not.toBeNull();
+            expect(screen.rendered_image_path).toBeNull();
+        }
+        // The harness never builds: swift is never invoked.
+        expect(existsSync(logPath)).toBe(false);
+        expectNoAbsolutePathLeaks(project, result);
+    });
+    test('a corrupt archive yields PACKAGE_ARCHIVE_INVALID', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        stageArchive(project, Buffer.from('definitely not a gzipped tarball'));
+        const run = runScript(project, await buildInputsScript({ target: 'FixtureViews' }));
+        expect(run.status).not.toBe(0);
+        const result = readResult(project);
+        expect(result.error?.code).toBe('PACKAGE_ARCHIVE_INVALID');
+        expect(result.screens).toHaveLength(1);
+        expect(result.screens[0].error).toBeNull();
+        expectNoAbsolutePathLeaks(project, result);
+    });
+    test('an archive with dot-dot or absolute members yields PACKAGE_ARCHIVE_INVALID', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        const script = await buildInputsScript({ target: 'FixtureViews' });
+        stageArchive(project, [
+            ...shippedPackageEntries('pkg'),
+            { name: 'pkg/../escape.swift', content: '// escape' },
+        ]);
+        let run = runScript(project, script);
+        expect(run.status).not.toBe(0);
+        let result = readResult(project);
+        expect(result.error?.code).toBe('PACKAGE_ARCHIVE_INVALID');
+        expect(result.error?.message).toContain('escape.swift');
+        stageArchive(project, [
+            ...shippedPackageEntries('pkg'),
+            { name: '/abs/escape.swift', content: '// escape' },
+        ]);
+        run = runScript(project, script);
+        expect(run.status).not.toBe(0);
+        result = readResult(project);
+        expect(result.error?.code).toBe('PACKAGE_ARCHIVE_INVALID');
+        expectNoAbsolutePathLeaks(project, result);
+    });
+    test('an empty archive yields PACKAGE_ARCHIVE_INVALID', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        stageArchive(project, []);
+        const run = runScript(project, await buildInputsScript({ target: 'FixtureViews' }));
+        expect(run.status).not.toBe(0);
+        expect(readResult(project).error?.code).toBe('PACKAGE_ARCHIVE_INVALID');
+    });
+    test('multiple top-level roots yield PACKAGE_ARCHIVE_INVALID', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        stageArchive(project, [
+            ...shippedPackageEntries('pkg-one'),
+            ...shippedPackageEntries('pkg-two'),
+        ]);
+        const run = runScript(project, await buildInputsScript({ target: 'FixtureViews' }));
+        expect(run.status).not.toBe(0);
+        const result = readResult(project);
+        expect(result.error?.code).toBe('PACKAGE_ARCHIVE_INVALID');
+        expect(result.error?.message).toContain('pkg-one');
+        expect(result.error?.message).toContain('pkg-two');
+        expectNoAbsolutePathLeaks(project, result);
+    });
+    test('a single top-level file yields PACKAGE_ARCHIVE_INVALID', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        stageArchive(project, [{ name: 'HomeView.swift', content: 'import SwiftUI\n' }]);
+        const run = runScript(project, await buildInputsScript({ target: 'FixtureViews' }));
+        expect(run.status).not.toBe(0);
+        expect(readResult(project).error?.code).toBe('PACKAGE_ARCHIVE_INVALID');
+    });
+    test('a package root without Package.swift yields PACKAGE_MANIFEST_MISSING', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        // The manifest exists, but only deeper than the single top-level root.
+        stageArchive(project, [
+            { name: 'pkg/' },
+            { name: 'pkg/Nested/Package.swift', content: SHIPPED_MANIFEST },
+            { name: 'pkg/Nested/Sources/FixtureViews/HomeView.swift', content: 'import SwiftUI\n' },
+        ]);
+        const run = runScript(project, await buildInputsScript({ target: 'FixtureViews' }));
+        expect(run.status).not.toBe(0);
+        const result = readResult(project);
+        expect(result.error?.code).toBe('PACKAGE_MANIFEST_MISSING');
+        expectNoAbsolutePathLeaks(project, result);
+    });
+    test('an extraction larger than the size bound yields PACKAGE_ARCHIVE_TOO_LARGE', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        stageArchive(project, shippedPackageEntries('pkg'));
+        const run = runScript(project, await buildInputsScript({ target: 'FixtureViews' }), {
+            UI_FIDELITY_MAX_PACKAGE_BYTES: '64',
+        });
+        expect(run.status).not.toBe(0);
+        const result = readResult(project);
+        expect(result.error?.code).toBe('PACKAGE_ARCHIVE_TOO_LARGE');
+        expect(result.error?.message).toContain('64');
+        expectNoAbsolutePathLeaks(project, result);
+    });
+    test('the default extraction bound is 32 MiB', async () => {
+        const script = await buildInputsScript({ target: 'FixtureViews' });
+        expect(script).toContain('32 * 1024 * 1024');
+    });
+    test('archive validation failures fail the step even with zero screens', async () => {
+        const project = makeProject({ screens: {} });
+        const run = runScript(project, await buildInputsScript({ target: 'FixtureViews' }));
+        expect(run.status).not.toBe(0);
+        const result = readResult(project);
+        expect(result.error?.code).toBe('PACKAGE_ARCHIVE_MISSING');
+        expect(result.screens).toEqual([]);
+    });
+    test('an empty screens object with a valid archive still exits zero', async () => {
+        const project = makeProject({ screens: {} });
+        stageArchive(project, shippedPackageEntries('pkg'));
+        const run = runScript(project, await buildInputsScript({ target: 'FixtureViews' }));
+        expect(run.status).toBe(0);
+        expect(readResult(project)).toEqual({
+            renderer: 'imagerenderer-spm',
+            package_source: 'inputs',
+            error: null,
+            screens: [],
+        });
+    });
+    test('absent params.json still records the package source with empty screens', async () => {
+        const project = makeProject();
+        stageArchive(project, shippedPackageEntries('pkg'));
+        const run = runScript(project, await buildInputsScript({ target: 'FixtureViews' }));
+        expect(run.status).not.toBe(0);
+        expect(readResult(project)).toEqual({
+            renderer: 'imagerenderer-spm',
+            package_source: 'inputs',
+            error: null,
+            screens: [],
+        });
+    });
+    test('zero library products yield PACKAGE_TARGET_UNRESOLVED', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        stageArchive(project, shippedPackageEntries('pkg'));
+        const run = runScript(project, await buildInputsScript(), {
+            FAKE_SWIFT_DUMP_PRODUCTS: '',
+        });
+        expect(run.status).not.toBe(0);
+        const result = readResult(project);
+        expect(result.error?.code).toBe('PACKAGE_TARGET_UNRESOLVED');
+        expect(result.error?.message).toContain('no library products');
+    });
+    test('multiple library products yield PACKAGE_TARGET_UNRESOLVED naming the candidates', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        stageArchive(project, shippedPackageEntries('pkg'));
+        const run = runScript(project, await buildInputsScript(), {
+            FAKE_SWIFT_DUMP_PRODUCTS: 'AlphaViews,BetaViews',
+        });
+        expect(run.status).not.toBe(0);
+        const result = readResult(project);
+        expect(result.error?.code).toBe('PACKAGE_TARGET_UNRESOLVED');
+        expect(result.error?.message).toContain('AlphaViews');
+        expect(result.error?.message).toContain('BetaViews');
+    });
+    test('a failing dump-package yields PACKAGE_TARGET_UNRESOLVED', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        stageArchive(project, shippedPackageEntries('pkg'));
+        const run = runScript(project, await buildInputsScript(), {
+            FAKE_SWIFT_DUMP_FAIL: '1',
+        });
+        expect(run.status).not.toBe(0);
+        const result = readResult(project);
+        expect(result.error?.code).toBe('PACKAGE_TARGET_UNRESOLVED');
+        expect(result.error?.message).toContain('malformed Package.swift manifest');
+        expectNoAbsolutePathLeaks(project, result);
+    });
+    test('a discovered product that is not a Swift identifier yields PACKAGE_TARGET_UNRESOLVED', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        stageArchive(project, shippedPackageEntries('pkg'));
+        const run = runScript(project, await buildInputsScript(), {
+            FAKE_SWIFT_DUMP_PRODUCTS: 'My-Views',
+        });
+        expect(run.status).not.toBe(0);
+        expect(readResult(project).error?.code).toBe('PACKAGE_TARGET_UNRESOLVED');
+    });
+    test('a broken screen fails alone in inputs mode', async () => {
+        const project = makeProject({
+            screens: { HomeView: 'home.png', MissingView: 'missing-view.png' },
+        });
+        writeReference(project, 'home.png');
+        writeReference(project, 'missing-view.png');
+        stageArchive(project, shippedPackageEntries('pkg'));
+        const run = runScript(project, await buildInputsScript({ target: 'FixtureViews' }), {
+            FAKE_SWIFT_COMPILE_FAIL: 'MissingView',
+        });
+        expect(run.status).not.toBe(0);
+        const result = readResult(project);
+        // Per-screen isolation is unchanged: the break is per-screen, the
+        // build-level error stays null.
+        expect(result.error).toBeNull();
+        const [home, missing] = result.screens;
+        expect(home.status).toBe('rendered');
+        expect(isPng(artifact(project, 'ui-fidelity/rendered/HomeView.png'))).toBe(true);
+        expect(missing.status).toBe('render_failed');
+        expect(missing.error?.code).toBe('VIEW_COMPILE_FAILED');
+        expectNoAbsolutePathLeaks(project, result);
+    });
+    test('a shipped package that does not build for macOS is sanitized to <package>', async () => {
+        const project = makeProject({ screens: { HomeView: 'home.png' } });
+        writeReference(project, 'home.png');
+        stageArchive(project, shippedPackageEntries('pkg'));
+        const run = runScript(project, await buildInputsScript({ target: 'FixtureViews' }), {
+            FAKE_SWIFT_PROBE_FAIL: '1',
+        });
+        expect(run.status).not.toBe(0);
+        const result = readResult(project);
+        expect(result.error).toBeNull();
+        expect(result.screens[0].error?.code).toBe('RENDER_UNSUPPORTED');
+        expect(result.screens[0].error?.message).toContain('<package>/pkg');
+        expectNoAbsolutePathLeaks(project, result);
+    });
+});
 describe('committed fixture package', () => {
     test('declares the FixtureViews library with the screens the example pipeline uses', () => {
         const manifest = readFileSync(join(FIXTURE_PACKAGE, 'Package.swift'), 'utf-8');