@invarn/cibuild 2.2.6 → 2.2.8

package/dist/src/yaml/fidelity-input-digest.d.ts

@@ -0,0 +1,37 @@
+export interface PackageFile {
+    /** POSIX, package-relative path. Part of the digest so a rename is a change. */
+    path: string;
+    /** File contents. */
+    bytes: Buffer;
+}
+/**
+ * Compute the input digest for one render package: its source files plus the
+ * reference image the screen is judged against. Files are folded in sorted by
+ * path so iteration order can't affect the result; each is folded in as its git
+ * blob id (see the module header) so the digest is reproducible from a Git Trees
+ * listing with no blob content. The path is length-prefixed and the blob id is
+ * fixed-width, so boundaries are unambiguous.
+ */
+export declare function sourceDigest(packageFiles: PackageFile[], referenceBytes: Buffer | null): string;
+/**
+ * True when a render package is self-contained — no Gradle script reaches
+ * outside the package root. Render packages are hermetic by construction; this
+ * guard fails a non-hermetic package OUT of the cacheable set (its digest is not
+ * emitted / not trusted for skip) so a change in an external module it depends
+ * on can never replay a stale verdict. Pure: a function of the package files
+ * only, so a dispatch-time caller can apply the identical check.
+ */
+export declare function isHermeticPackage(packageFiles: PackageFile[]): boolean;
+/**
+ * Runtime twin of {@link sourceDigest}, spliced into the self-contained render
+ * script that runs on the macOS runner (which cannot import this module). It
+ * walks the built package directory, reads the paired reference, and computes
+ * the identical digest — a parity test pins it to `sourceDigest` so the twin
+ * cannot drift.
+ *
+ * Exposes `computeSourceDigest(projectRoot, referencePath)`. Build outputs and
+ * VCS/tooling dirs are excluded so they never perturb the content key. Reads
+ * are best-effort: an unreadable reference folds in as "absent", never throws.
+ */
+export declare const RENDER_SCRIPT_SOURCE_DIGEST_STAGE: string;
+//# sourceMappingURL=fidelity-input-digest.d.ts.map

package/dist/src/yaml/fidelity-input-digest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fidelity-input-digest.d.ts","sourceRoot":"","sources":["../../../src/yaml/fidelity-input-digest.ts"],"names":[],"mappings":"AAiCA,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAuBD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,YAAY,EAAE,WAAW,EAAE,EAC3B,cAAc,EAAE,MAAM,GAAG,IAAI,GAC5B,MAAM,CAoBR;AAwBD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG,OAAO,CAOtE;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iCAAiC,EAAE,MAiF/C,CAAC"}

package/dist/src/yaml/fidelity-input-digest.js

@@ -0,0 +1,208 @@
+/**
+ * Deterministic per-package input digest.
+ *
+ * A content key over a render package's inputs — the committed wrapper source
+ * files plus the paired reference image — so a consumer can tell when a render
+ * would be byte-identical to one already produced and skip re-rendering. Pure:
+ * a function of the input bytes only, never of absolute paths, timestamps, or
+ * commit ids, so the same inputs yield the same digest on any machine or
+ * branch.
+ *
+ * Scope: package-local inputs. Render packages are self-contained by
+ * construction — a parameterless wrapper that reproduces one screen from
+ * hardcoded fixtures, shipped with every dependency version pinned inline and
+ * its own assets vendored — so the package IS its own dependency closure and a
+ * package-local content key already invalidates on anything that can shift the
+ * render. (A package that escapes its own root — an `includeBuild`, an external
+ * `project(":…")` dependency, or a shared version catalog — would break that
+ * property; such a package is not safely cacheable and is caught by a separate
+ * hermeticity guard rather than folded into this digest.)
+ *
+ * Digest basis: each file is folded in as its **git blob id**
+ * (`sha1("blob " + byteLength + "\0" + content)`) rather than its raw bytes.
+ * That is the exact id the GitHub Git Trees API returns for a committed file, so
+ * a caller holding only a tree listing — a webhook dispatch with no checkout —
+ * can reproduce this digest from `(path, blobSha)` pairs WITHOUT fetching any
+ * blob content. The framing is: sha256 over, for each file sorted by path,
+ * `len(path) ‖ path ‖ blobSha(content)`, then the reference folded last as
+ * `blobSha(reference)` (or a presence-distinct `len(0xffffffff)` marker when
+ * there is no reference). `blobSha` is a fixed 20 bytes, so file boundaries stay
+ * unambiguous with only the path length-prefixed.
+ */
+import { createHash } from 'crypto';
+/** 4-byte big-endian length prefix, so concatenated fields can't alias
+ *  (`["ab","c"]` must not hash equal to `["a","bc"]`). */
+function len(n) {
+    const b = Buffer.allocUnsafe(4);
+    b.writeUInt32BE(n >>> 0, 0);
+    return b;
+}
+/**
+ * Git blob object id for a file's content: `sha1("blob " + len + "\0" + bytes)`.
+ * The identical id the GitHub Git Trees API returns for the committed blob, so a
+ * dispatch-time caller can read it from a tree listing instead of hashing bytes
+ * it never fetched. Returned as 20 raw bytes (folded straight into the digest).
+ */
+function gitBlobSha(bytes) {
+    const h = createHash('sha1');
+    h.update(`blob ${bytes.length}\0`);
+    h.update(bytes);
+    return h.digest();
+}
+/**
+ * Compute the input digest for one render package: its source files plus the
+ * reference image the screen is judged against. Files are folded in sorted by
+ * path so iteration order can't affect the result; each is folded in as its git
+ * blob id (see the module header) so the digest is reproducible from a Git Trees
+ * listing with no blob content. The path is length-prefixed and the blob id is
+ * fixed-width, so boundaries are unambiguous.
+ */
+export function sourceDigest(packageFiles, referenceBytes) {
+    const sorted = [...packageFiles].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    const h = createHash('sha256');
+    for (const file of sorted) {
+        const pathBytes = Buffer.from(file.path, 'utf8');
+        h.update(len(pathBytes.length));
+        h.update(pathBytes);
+        h.update(gitBlobSha(file.bytes));
+    }
+    // Reference is folded in as its blob id, with a presence-distinct marker so
+    // "no reference" differs from "empty reference".
+    if (referenceBytes === null) {
+        h.update(len(0xffffffff));
+    }
+    else {
+        h.update(gitBlobSha(referenceBytes));
+    }
+    return h.digest('hex');
+}
+/**
+ * A Gradle build script — the only files that can reach outside the package
+ * root (source files and assets can mention `..` in prose without affecting the
+ * build graph).
+ */
+function isGradleScript(path) {
+    return path.endsWith('.gradle') || path.endsWith('.gradle.kts');
+}
+/**
+ * Tokens by which a Gradle script reaches outside its own package root and so
+ * breaks the "package is its own dependency closure" invariant this digest
+ * relies on:
+ *   - `includeBuild` — a composite/included build (another whole build).
+ *   - `projectDir`   — a module relocated to a directory outside the layout.
+ *   - `../`          — any parent-path reference (external file, script, or
+ *                      version catalog).
+ * Biased toward over-detection: a false positive only forces a re-render (safe),
+ * whereas a miss would let a shared external change replay a stale verdict.
+ */
+const GRADLE_ESCAPE = /includeBuild|projectDir|\.\.\//;
+/**
+ * True when a render package is self-contained — no Gradle script reaches
+ * outside the package root. Render packages are hermetic by construction; this
+ * guard fails a non-hermetic package OUT of the cacheable set (its digest is not
+ * emitted / not trusted for skip) so a change in an external module it depends
+ * on can never replay a stale verdict. Pure: a function of the package files
+ * only, so a dispatch-time caller can apply the identical check.
+ */
+export function isHermeticPackage(packageFiles) {
+    for (const file of packageFiles) {
+        if (isGradleScript(file.path) && GRADLE_ESCAPE.test(file.bytes.toString('utf8'))) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Runtime twin of {@link sourceDigest}, spliced into the self-contained render
+ * script that runs on the macOS runner (which cannot import this module). It
+ * walks the built package directory, reads the paired reference, and computes
+ * the identical digest — a parity test pins it to `sourceDigest` so the twin
+ * cannot drift.
+ *
+ * Exposes `computeSourceDigest(projectRoot, referencePath)`. Build outputs and
+ * VCS/tooling dirs are excluded so they never perturb the content key. Reads
+ * are best-effort: an unreadable reference folds in as "absent", never throws.
+ */
+export const RENDER_SCRIPT_SOURCE_DIGEST_STAGE = String.raw `
+// ---- source-digest stage: deterministic package input content key ----
+function __fidLen(n) {
+  var b = Buffer.allocUnsafe(4);
+  b.writeUInt32BE(n >>> 0, 0);
+  return b;
+}
+var __FID_SKIP_DIRS = { build: 1, '.gradle': 1, '.git': 1, '.idea': 1, 'node_modules': 1, DerivedData: 1 };
+function __fidCollectPackageFiles(root) {
+  var fs = require('fs');
+  var path = require('path');
+  var out = [];
+  function walk(dir, rel) {
+    var names;
+    try { names = fs.readdirSync(dir); } catch (e) { return; }
+    names.sort();
+    for (var i = 0; i < names.length; i++) {
+      var name = names[i];
+      var full = path.join(dir, name);
+      var relPath = rel ? rel + '/' + name : name;
+      var st;
+      try { st = fs.statSync(full); } catch (e) { continue; }
+      if (st.isDirectory()) {
+        if (__FID_SKIP_DIRS[name]) continue;
+        walk(full, relPath);
+      } else if (st.isFile()) {
+        out.push({ path: relPath, bytes: fs.readFileSync(full) });
+      }
+    }
+  }
+  walk(root, '');
+  return out;
+}
+function __fidBlobSha(bytes) {
+  var crypto = require('crypto');
+  var h = crypto.createHash('sha1');
+  h.update('blob ' + bytes.length + '\0');
+  h.update(bytes);
+  return h.digest();
+}
+function __fidSourceDigest(files, referenceBytes) {
+  var crypto = require('crypto');
+  var sorted = files.slice().sort(function (a, b) {
+    return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+  });
+  var h = crypto.createHash('sha256');
+  for (var i = 0; i < sorted.length; i++) {
+    var pathBytes = Buffer.from(sorted[i].path, 'utf8');
+    h.update(__fidLen(pathBytes.length));
+    h.update(pathBytes);
+    h.update(__fidBlobSha(sorted[i].bytes));
+  }
+  if (referenceBytes === null || referenceBytes === undefined) {
+    h.update(__fidLen(0xffffffff));
+  } else {
+    h.update(__fidBlobSha(referenceBytes));
+  }
+  return h.digest('hex');
+}
+function computeSourceDigest(projectRoot, referencePath) {
+  var fs = require('fs');
+  var files = __fidCollectPackageFiles(projectRoot);
+  var ref = null;
+  try { if (referencePath) ref = fs.readFileSync(referencePath); } catch (e) { ref = null; }
+  return __fidSourceDigest(files, ref);
+}
+// Twin of isHermeticPackage: a package is cacheable only when no Gradle script
+// reaches outside its own root (includeBuild / projectDir / a parent path).
+var __FID_GRADLE_ESCAPE = /includeBuild|projectDir|\.\.\//;
+function __fidIsGradleScript(p) {
+  return p.slice(-7) === '.gradle' || p.slice(-11) === '.gradle.kts';
+}
+function __fidIsHermetic(files) {
+  for (var i = 0; i < files.length; i++) {
+    if (__fidIsGradleScript(files[i].path) &&
+        __FID_GRADLE_ESCAPE.test(files[i].bytes.toString('utf8'))) {
+      return false;
+    }
+  }
+  return true;
+}
+`;
+//# sourceMappingURL=fidelity-input-digest.js.map

package/dist/src/yaml/fidelity-input-digest.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fidelity-input-digest.test.d.ts.map

package/dist/src/yaml/fidelity-input-digest.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fidelity-input-digest.test.d.ts","sourceRoot":"","sources":["../../../src/yaml/fidelity-input-digest.test.ts"],"names":[],"mappings":""}

package/dist/src/yaml/fidelity-input-digest.test.js

@@ -0,0 +1,167 @@
+/**
+ * Unit tests for the deterministic per-package input digest.
+ *
+ * The digest is the content key the dashboard matches on to decide whether a
+ * render would be identical to one it already has — so it must be a pure
+ * function of the package's input bytes (wrapper source + reference), stable
+ * across machines/branches, and never derived from paths-as-location, mtimes,
+ * or commit ids.
+ */
+import { describe, test, expect } from '@jest/globals';
+import { createHash } from 'crypto';
+import { createRequire } from 'module';
+import { sourceDigest, isHermeticPackage, RENDER_SCRIPT_SOURCE_DIGEST_STAGE, } from './fidelity-input-digest.js';
+function f(path, content) {
+    return { path, bytes: Buffer.from(content, 'utf8') };
+}
+/** Git blob object id: sha1('blob <len>\0<content>') — the SAME id the GitHub
+ *  Git Trees API returns for a committed file. The digest is defined over these
+ *  ids so a caller with only a tree listing (no blob content) can reproduce it. */
+function gitBlobSha(bytes) {
+    const h = createHash('sha1');
+    h.update(`blob ${bytes.length}\0`);
+    h.update(bytes);
+    return h.digest('hex');
+}
+/** 4-byte big-endian length prefix — mirrors the module-private `len`. */
+function len(n) {
+    const b = Buffer.allocUnsafe(4);
+    b.writeUInt32BE(n >>> 0, 0);
+    return b;
+}
+/** Extract the runner-side twin from the spliced stage source so a parity test
+ *  can pin it to the pure function. `require` is injected because the stage
+ *  runs in the runner's CJS scope, not this ESM test module. */
+const require = createRequire(import.meta.url);
+const twin = new Function('require', RENDER_SCRIPT_SOURCE_DIGEST_STAGE +
+    '\nreturn { __fidSourceDigest: __fidSourceDigest, __fidIsHermetic: __fidIsHermetic };')(require);
+describe('sourceDigest', () => {
+    test('is deterministic: identical inputs produce the same 64-hex digest', () => {
+        const files = [f('Proof.kt', 'fun Proof() {}'), f('build.gradle.kts', 'plugins {}')];
+        const ref = Buffer.from('reference-image-bytes');
+        const first = sourceDigest(files, ref);
+        expect(first).toMatch(/^[0-9a-f]{64}$/);
+        expect(sourceDigest(files, ref)).toBe(first);
+    });
+    test('changes when any package file byte changes', () => {
+        const ref = Buffer.from('ref');
+        const before = sourceDigest([f('Proof.kt', 'fun Proof() {}')], ref);
+        const after = sourceDigest([f('Proof.kt', 'fun Proof() { Box() }')], ref);
+        expect(after).not.toBe(before);
+    });
+    test('changes when only the reference image changes', () => {
+        const files = [f('Proof.kt', 'fun Proof() {}')];
+        const withA = sourceDigest(files, Buffer.from('reference-A'));
+        const withB = sourceDigest(files, Buffer.from('reference-B'));
+        expect(withB).not.toBe(withA);
+    });
+    test('is independent of file iteration order', () => {
+        const ref = Buffer.from('ref');
+        const a = f('a.kt', 'A');
+        const b = f('b.kt', 'B');
+        expect(sourceDigest([a, b], ref)).toBe(sourceDigest([b, a], ref));
+    });
+    test('is unambiguous across file boundaries (path/content cannot alias)', () => {
+        const ref = Buffer.from('ref');
+        // Same concatenated bytes, different split: must not collide.
+        const split = sourceDigest([f('ab', 'x'), f('', 'y')], ref);
+        const joined = sourceDigest([f('a', 'bxy')], ref);
+        expect(split).not.toBe(joined);
+    });
+    test('is reconstructible from git blob shas alone (dashboard tree-API parity)', () => {
+        // The dashboard computes this SAME digest at webhook time from a Git Trees
+        // API listing — which carries each committed file's blob sha but NOT its
+        // content. Pin the exact framing so that reconstruction (path + blob sha,
+        // no bytes) reproduces the digest byte-for-byte.
+        const files = [f('b.kt', 'B'), f('a.kt', 'A')];
+        const ref = Buffer.from('reference-image-bytes');
+        const sorted = [...files].sort((x, y) => (x.path < y.path ? -1 : x.path > y.path ? 1 : 0));
+        const h = createHash('sha256');
+        for (const file of sorted) {
+            const p = Buffer.from(file.path, 'utf8');
+            h.update(len(p.length));
+            h.update(p);
+            h.update(Buffer.from(gitBlobSha(file.bytes), 'hex'));
+        }
+        h.update(Buffer.from(gitBlobSha(ref), 'hex'));
+        expect(sourceDigest(files, ref)).toBe(h.digest('hex'));
+    });
+    test('matches the cross-consumer golden vector (pins the wire format)', () => {
+        // A fixed known-answer vector shared verbatim with the dashboard's
+        // dispatch-time digest, so the two implementations cannot drift apart
+        // silently. If this changes, the dashboard golden must change in lockstep.
+        const files = [f('a.kt', 'A'), f('proof/build.gradle.kts', 'plugins {}')];
+        expect(sourceDigest(files, Buffer.from('ref-bytes'))).toBe('7fc57f481eb011299d34824e0a506345d15e96946e345beac882f26adab47374');
+        expect(sourceDigest(files, null)).toBe('2596ecea7f591c23f9397707a92b008dabedbd1fd4acc0efb2440849e97ddd3c');
+    });
+    test('folds a null reference in with a presence-distinct marker (not a blob sha)', () => {
+        const files = [f('a.kt', 'A')];
+        const sorted = files;
+        const h = createHash('sha256');
+        for (const file of sorted) {
+            const p = Buffer.from(file.path, 'utf8');
+            h.update(len(p.length));
+            h.update(p);
+            h.update(Buffer.from(gitBlobSha(file.bytes), 'hex'));
+        }
+        h.update(len(0xffffffff));
+        expect(sourceDigest(files, null)).toBe(h.digest('hex'));
+    });
+});
+describe('isHermeticPackage', () => {
+    const hermetic = [
+        f('settings.gradle.kts', 'rootProject.name = "p"\ninclude(":proof")\n'),
+        f('build.gradle.kts', 'plugins { id("com.android.library") version "8.13.2" }'),
+        f('proof/build.gradle.kts', 'dependencies { implementation("androidx.compose.ui:ui") }'),
+        f('proof/src/main/kotlin/Proof.kt', 'fun Proof() {}'),
+    ];
+    test('accepts a self-contained package with everything pinned inline', () => {
+        expect(isHermeticPackage(hermetic)).toBe(true);
+    });
+    test('rejects a composite build (includeBuild reaches another build)', () => {
+        const files = [...hermetic, f('settings.gradle.kts', 'includeBuild("../design-system")')];
+        expect(isHermeticPackage(files)).toBe(false);
+    });
+    test('rejects a module relocated outside the root via projectDir', () => {
+        const files = [
+            f('settings.gradle.kts', 'include(":ds")\nproject(":ds").projectDir = file("../ds")'),
+        ];
+        expect(isHermeticPackage(files)).toBe(false);
+    });
+    test('rejects a parent-path escape (external file / version catalog)', () => {
+        const files = [
+            f('settings.gradle.kts', 'versionCatalogs { create("libs") { from(files("../gradle/libs.versions.toml")) } }'),
+        ];
+        expect(isHermeticPackage(files)).toBe(false);
+    });
+    test('ignores escape tokens outside Gradle scripts (only build scripts can escape)', () => {
+        // A source file or asset mentioning "../" is not a build-graph escape.
+        const files = [
+            f('settings.gradle.kts', 'include(":proof")'),
+            f('proof/src/main/kotlin/Doc.kt', '// see ../design-system for the original'),
+        ];
+        expect(isHermeticPackage(files)).toBe(true);
+    });
+});
+describe('runtime twin parity', () => {
+    const files = [f('Proof.kt', 'fun Proof() { Box() }'), f('build.gradle.kts', 'plugins {}')];
+    test('the spliced runner-side digest matches the pure sourceDigest (with reference)', () => {
+        const ref = Buffer.from('reference-image-bytes');
+        expect(twin.__fidSourceDigest(files, ref)).toBe(sourceDigest(files, ref));
+    });
+    test('the spliced runner-side digest matches the pure sourceDigest (no reference)', () => {
+        expect(twin.__fidSourceDigest(files, null)).toBe(sourceDigest(files, null));
+    });
+    test('the spliced runner-side hermeticity check matches isHermeticPackage', () => {
+        const hermetic = [
+            f('settings.gradle.kts', 'include(":proof")'),
+            f('proof/src/main/kotlin/Doc.kt', '// mentions ../elsewhere harmlessly'),
+        ];
+        const escaping = [f('settings.gradle', 'includeBuild("../other")')];
+        expect(twin.__fidIsHermetic(hermetic)).toBe(isHermeticPackage(hermetic));
+        expect(twin.__fidIsHermetic(escaping)).toBe(isHermeticPackage(escaping));
+        expect(twin.__fidIsHermetic(hermetic)).toBe(true);
+        expect(twin.__fidIsHermetic(escaping)).toBe(false);
+    });
+});
+//# sourceMappingURL=fidelity-input-digest.test.js.map

package/dist/src/yaml/steps/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAyCH;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAs5C7C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA4CH;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAq7C7C"}

package/dist/src/yaml/steps/index.js

@@ -24,8 +24,8 @@ import { BitriseSlackStepExecutor } from './bitrise-slack.js';
 import { BitriseApkInfoStepExecutor } from './bitrise-apk-info.js';
 import { GooglePlayDeployStepExecutor } from './google-play-deploy.js';
 import { AppStoreDeployStepExecutor } from './app-store-deploy.js';
-import { UiFidelityRenderStepExecutor, DEFAULT_RENDER_SIZE, DEFAULT_SCALE, DEFAULT_PACKAGE_SOURCE, } from './ui-fidelity-render.js';
-import { UiFidelityRenderAndroidStepExecutor, DEFAULT_GRADLE_TASK, } from './ui-fidelity-render-android.js';
+import { UiFidelityRenderStepExecutor, DEFAULT_RENDER_SIZE, DEFAULT_SCALE, DEFAULT_PACKAGE_SOURCE, DEFAULT_REFERENCE_SOURCE, } from './ui-fidelity-render.js';
+import { UiFidelityRenderAndroidStepExecutor, DEFAULT_GRADLE_TASK, DEFAULT_PACKAGE_SOURCE as DEFAULT_ANDROID_PACKAGE_SOURCE, DEFAULT_REFERENCE_SOURCE as DEFAULT_ANDROID_REFERENCE_SOURCE, } from './ui-fidelity-render-android.js';
 /**
  * Initializes the step registry with all available steps
  * This function should be called once at application startup
@@ -771,6 +771,13 @@ export function initializeStepRegistry() {
                 required: false,
                 default: DEFAULT_PACKAGE_SOURCE,
             },
+            reference_source: {
+                description: "Where each screen's reference image comes from: 'inputs' (default — a " +
+                    "basename in the run-inputs directory) or 'repo' (a repo-relative path to " +
+                    'a committed reference, resolved against the checkout)',
+                required: false,
+                default: DEFAULT_REFERENCE_SOURCE,
+            },
             package_path: {
                 description: "Path to the user's SwiftPM package containing the screens. " +
                     "Required when package_source is 'repo' (the default); ignored with 'inputs'",
@@ -804,6 +811,26 @@ export function initializeStepRegistry() {
             'via Roborazzi + Robolectric on the JVM (no device, no emulator)',
         platform: 'android',
         inputs: {
+            package_source: {
+                description: "Where the Gradle render project comes from: 'inputs' (default — " +
+                    "package.tar.gz shipped in the run-inputs directory) or 'repo' " +
+                    '(package_path in the checkout, rendered directly without an upload)',
+                required: false,
+                default: DEFAULT_ANDROID_PACKAGE_SOURCE,
+            },
+            reference_source: {
+                description: "Where each screen's reference image comes from: 'inputs' (default — a " +
+                    "basename in the run-inputs directory) or 'repo' (a repo-relative path to " +
+                    'a committed reference, resolved against the checkout)',
+                required: false,
+                default: DEFAULT_ANDROID_REFERENCE_SOURCE,
+            },
+            package_path: {
+                description: 'Repo-relative path to the committed Gradle render project. Required ' +
+                    "when package_source is 'repo'; ignored with 'inputs'",
+                required: false,
+                inputType: 'path',
+            },
             scale: {
                 description: 'Display scale factor used when reporting logical points; must match the ' +
                     'density qualifier the render test pins (xhdpi = 2)',

package/dist/src/yaml/steps/ui-fidelity-render-android.d.ts

@@ -70,6 +70,23 @@ export interface UiFidelityRenderAndroidInputs {
  * it in whichever subproject declares it.
  */
 export declare const DEFAULT_GRADLE_TASK = "recordRoborazziDebug";
+/** Valid values for the package_source input. */
+export declare const PACKAGE_SOURCES: readonly ["repo", "inputs"];
+export type PackageSource = (typeof PACKAGE_SOURCES)[number];
+/**
+ * Default package source: the Gradle project ships as package.tar.gz in the
+ * run-inputs directory (the agent-upload path). "repo" instead renders the
+ * committed project at package_path, for a triggered (agent-less) run.
+ */
+export declare const DEFAULT_PACKAGE_SOURCE: PackageSource;
+/** Valid values for the reference_source input. */
+export declare const REFERENCE_SOURCES: readonly ["repo", "inputs"];
+export type ReferenceSource = (typeof REFERENCE_SOURCES)[number];
+/**
+ * Default reference source: references arrive as run inputs (a plain basename
+ * under `.ci/inputs`), matching the agent-upload path.
+ */
+export declare const DEFAULT_REFERENCE_SOURCE: ReferenceSource;
 /** Basename of the shipped Gradle-project archive inside the run-inputs dir. */
 export declare const PACKAGE_ARCHIVE_BASENAME = "package.tar.gz";
 /** Renderer identifier recorded in protocol-result.json. */
@@ -84,10 +101,31 @@ export declare function isValidGradleTask(task: string): boolean;
 export interface AndroidRenderScriptConfig {
     scale: number;
     gradleTask: string;
+    /**
+     * Only present (and only ever "repo") when package_source was explicitly set
+     * to "repo". When absent, the project ships as package.tar.gz and is
+     * extracted/validated exactly as the default, byte-identical script.
+     */
+    packageSource?: PackageSource;
+    /**
+     * Repo-relative path to the committed Gradle project. Present (and required)
+     * only with packageSource "repo"; ignored otherwise.
+     */
+    packagePath?: string;
+    /**
+     * Only present (and only ever "repo") when reference_source was explicitly set
+     * to "repo". When absent, references are read from `.ci/inputs/<basename>` and
+     * the generated reference-sourcing code is byte-identical to the default.
+     */
+    referenceSource?: ReferenceSource;
 }
 /**
  * Generates the self-contained runtime node script for the step. Pure function
  * of its config — exported so tests can execute the script directly.
+ *
+ * When config.referenceSource is absent the reference block is byte-identical
+ * to the default (JSON.stringify drops the undefined key, and the unpatched
+ * runtime is used).
  */
 export declare function generateAndroidRenderScript(config: AndroidRenderScriptConfig): string;
 /**

package/dist/src/yaml/steps/ui-fidelity-render-android.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui-fidelity-render-android.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-render-android.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAKpE,sDAAsD;AACtD,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAE1D,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AAEzD,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB,0BAA0B,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,8EAA8E;AAC9E,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AA8xBD;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,yBAAyB,GAAG,MAAM,CAYrF;AAED;;;GAGG;AACH,qBAAa,mCAAoC,SAAQ,gBAAgB;IACvE,yBAAyB,CACvB,OAAO,EAAE,6BAA6B,EACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,EAAE,QAAQ,GAChB,qBAAqB,EAAE;IAepB,OAAO,CACX,MAAM,EAAE,6BAA6B,EACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,OAAO,CAAC;CAgBpB"}
+{"version":3,"file":"ui-fidelity-render-android.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-render-android.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAMpE,sDAAsD;AACtD,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAE1D,iDAAiD;AACjD,eAAO,MAAM,eAAe,6BAA8B,CAAC;AAC3D,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAAwB,CAAC;AAE9D,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,6BAA8B,CAAC;AAC7D,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,eAA0B,CAAC;AAElE,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AAEzD,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB,0BAA0B,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,8EAA8E;AAC9E,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AA26BD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,yBAAyB,GAAG,MAAM,CAqBrF;AAED;;;GAGG;AACH,qBAAa,mCAAoC,SAAQ,gBAAgB;IACvE,yBAAyB,CACvB,OAAO,EAAE,6BAA6B,EACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,EAAE,QAAQ,GAChB,qBAAqB,EAAE;IAepB,OAAO,CACX,MAAM,EAAE,6BAA6B,EACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,OAAO,CAAC;CA0EpB"}