@invarn/cibuild 2.3.5 → 2.3.7

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

@@ -8,6 +8,16 @@
  *   1. Reads `.ci/inputs/params.json`
  *      ({ "screens": { "<ViewTypeName>": "<referenceFileBasename>" } });
  *      reference images live at `.ci/inputs/<basename>`.
+ *      Optional reference-provenance sidecar: `"render_locale": "<locale>"`
+ *      plus `"provenance": { "<ViewTypeName>": { figmaNode, locale, resolved,
+ *      exportedAt } }`. The gate arms per screen from provenance presence and
+ *      checks METADATA only (never pixels/OCR): an absent reference is FATAL
+ *      (status `unverifiable`, REFERENCE_ABSENT); `resolved == false` or
+ *      `locale != render_locale` downgrade ONLY the copy channel — the screen
+ *      renders and is judged on every non-copy channel, and the downgrade
+ *      rides as a per-screen `copy_advisory` (`copy_unverifiable` + reason).
+ *      Unprovenanced screens keep legacy behaviour (no NO_PROVENANCE arming
+ *      on iOS).
  *   2. Synthesizes a throwaway SwiftPM harness package that depends on the
  *      user's package and contains ONE executable target per screen, so a
  *      compile failure for one screen (unknown view type, unavailable init)
@@ -317,6 +327,77 @@ function setError(entry, code, message) {
   entry.error = { code: code, message: sanitizeMessage(message) };
 }
 
+// A reference the gate cannot honestly judge at all: a hard, mechanical
+// metadata verdict (never pixels/OCR), distinct from render_failed so a rotten
+// reference fails loud instead of producing a confident-but-false PASS.
+function setUnverifiable(entry, code, message) {
+  entry.status = 'unverifiable';
+  entry.error = { code: code, message: sanitizeMessage(message) };
+}
+
+// Inlined twins of src/yaml/steps/fidelity-reference-provenance.ts (this script
+// ships self-contained and cannot import it). The render-step integration tests
+// exercise BOTH against the same fixtures so they cannot silently drift. The
+// iOS gate arms ONLY from provenance presence — the step never refused
+// unprovenanced screens, so NO_PROVENANCE (an Android-legacy arming via
+// render_locale) is deliberately not wired here.
+
+// Provenance is only "present" when the fields the gate reasons over are there.
+// A partial object (e.g. a hand-dropped { figmaNode }) is treated as no
+// provenance — verifiable is earned only through the full export path.
+function hasReferenceProvenance(provenance) {
+  return (
+    provenance != null &&
+    typeof provenance === 'object' &&
+    typeof provenance.locale === 'string' &&
+    typeof provenance.resolved === 'boolean'
+  );
+}
+
+// Assesses one provenanced screen's reference. Returns { fault, copyAdvisory }:
+// a fatal fault makes the screen unverifiable; a copy advisory downgrades only
+// the copy channel (the screen still renders and is judged on every non-copy
+// channel). An absent reference wins over a downgrade — there is nothing to
+// judge against.
+function assessReferenceProvenance(screen, provenance, renderLocale, referenceExists) {
+  if (!referenceExists) {
+    return {
+      fault: {
+        code: 'REFERENCE_ABSENT',
+        message: 'reference image for ' + screen + ' is absent',
+      },
+      copyAdvisory: null,
+    };
+  }
+  if (provenance.resolved === false) {
+    return {
+      fault: null,
+      copyAdvisory: {
+        code: 'copy_unverifiable',
+        reason: 'unresolved_placeholders',
+        message:
+          'reference for ' + screen + ' carries unresolved copy placeholders ' +
+          '(resolved=false); copy comparisons are skipped — non-copy judging ' +
+          'still holds',
+      },
+    };
+  }
+  if (renderLocale !== null && provenance.locale !== renderLocale) {
+    return {
+      fault: null,
+      copyAdvisory: {
+        code: 'copy_unverifiable',
+        reason: 'locale_mismatch',
+        message:
+          'reference for ' + screen + ' is locale "' + provenance.locale +
+          '" but the render locale is "' + renderLocale + '"; copy comparisons ' +
+          'are skipped — non-copy judging still holds',
+      },
+    };
+  }
+  return { fault: null, copyAdvisory: null };
+}
+
 function outputTail(result) {
   var combined = ((result.stdout || '') + '\n' + (result.stderr || '')).trim();
   if (combined.length > 2000) combined = '...' + combined.slice(-2000);
@@ -488,12 +569,25 @@ function main() {
     return 1;
   }
 
+  // Reference-provenance sidecar (optional): per-screen export provenance plus
+  // the run's declared render locale. The gate arms per screen from provenance
+  // presence; the locale is only needed for the locale comparison itself.
+  var renderLocale =
+    typeof params.render_locale === 'string' && params.render_locale !== ''
+      ? params.render_locale
+      : null;
+  var provenanceMap =
+    params.provenance && typeof params.provenance === 'object' && !Array.isArray(params.provenance)
+      ? params.provenance
+      : {};
+
   var screens = Object.keys(params.screens);
   currentEntries = screens.map(function (screen) {
     return {
       screen: screen,
       status: 'render_failed',
       error: null,
+      copy_advisory: null,
       reference_image_path: null,
       rendered_image_path: null,
     };
@@ -536,7 +630,39 @@ function main() {
     } catch (statError) {
       sourceStat = null;
     }
-    if (!sourceStat || !sourceStat.isFile()) {
+    var referenceExists = !!(sourceStat && sourceStat.isFile());
+
+    var screenProvenance = provenanceMap[entry.screen];
+    if (hasReferenceProvenance(screenProvenance)) {
+      // Provenance assessment (armed by provenance presence): an absent
+      // reference is FATAL (unverifiable — never a silent PASS); unresolved
+      // placeholders and locale mismatches downgrade ONLY the copy channel —
+      // the screen renders and is judged on every non-copy channel, and the
+      // downgrade rides in the result as a structured copy_advisory.
+      var assessment = assessReferenceProvenance(
+        entry.screen,
+        screenProvenance,
+        renderLocale,
+        referenceExists
+      );
+      if (assessment.fault) {
+        setUnverifiable(entry, assessment.fault.code, assessment.fault.message);
+        return;
+      }
+      if (assessment.copyAdvisory) {
+        entry.copy_advisory = {
+          code: assessment.copyAdvisory.code,
+          reason: assessment.copyAdvisory.reason,
+          message: sanitizeMessage(assessment.copyAdvisory.message),
+        };
+        log(
+          entry.screen + ': copy channel downgraded (' +
+            assessment.copyAdvisory.reason + '), non-copy judging proceeds'
+        );
+      }
+    } else if (!referenceExists) {
+      // Legacy (no provenance for this screen): an absent reference stays a
+      // render_failed REFERENCE_MISSING, exactly as before.
       setError(
         entry,
         'REFERENCE_MISSING',

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

@@ -529,6 +529,7 @@ describe('render script runtime', () => {
                     screen: 'HomeView',
                     status: 'rendered',
                     error: null,
+                    copy_advisory: null,
                     reference_image_path: 'ui-fidelity/references/HomeView.png',
                     rendered_image_path: 'ui-fidelity/rendered/HomeView.png',
                     source_digest: expect.stringMatching(/^[0-9a-f]{64}$/),
@@ -537,6 +538,7 @@ describe('render script runtime', () => {
                     screen: 'SettingsView',
                     status: 'rendered',
                     error: null,
+                    copy_advisory: null,
                     reference_image_path: 'ui-fidelity/references/SettingsView.png',
                     rendered_image_path: 'ui-fidelity/rendered/SettingsView.png',
                     source_digest: expect.stringMatching(/^[0-9a-f]{64}$/),
@@ -927,6 +929,7 @@ describe('render script runtime (package_source: repo)', () => {
                     screen: 'HomeView',
                     status: 'rendered',
                     error: null,
+                    copy_advisory: null,
                     reference_image_path: 'ui-fidelity/references/HomeView.png',
                     rendered_image_path: 'ui-fidelity/rendered/HomeView.png',
                     source_digest: expect.stringMatching(/^[0-9a-f]{64}$/),
@@ -1107,6 +1110,7 @@ describe('render script runtime (package_source: inputs)', () => {
                     screen: 'HomeView',
                     status: 'rendered',
                     error: null,
+                    copy_advisory: null,
                     reference_image_path: 'ui-fidelity/references/HomeView.png',
                     rendered_image_path: 'ui-fidelity/rendered/HomeView.png',
                     source_digest: expect.stringMatching(/^[0-9a-f]{64}$/),
@@ -1121,6 +1125,7 @@ describe('render script runtime (package_source: inputs)', () => {
                     screen: 'SettingsView',
                     status: 'rendered',
                     error: null,
+                    copy_advisory: null,
                     reference_image_path: 'ui-fidelity/references/SettingsView.png',
                     rendered_image_path: 'ui-fidelity/rendered/SettingsView.png',
                     source_digest: expect.stringMatching(/^[0-9a-f]{64}$/),
@@ -1580,4 +1585,121 @@ describe('reference_source: repo', () => {
         expect(ghost?.error?.code).toBe('REFERENCE_MISSING');
     });
 });
+describe('render script runtime — reference provenance', () => {
+    const GOOD_PROV = {
+        figmaNode: '12:345',
+        locale: 'en',
+        resolved: true,
+        exportedAt: '2026-06-18T10:00:00Z',
+    };
+    test('a placeholder reference (resolved=false) renders and downgrades only the copy channel', async () => {
+        const project = makeProject({
+            screens: { HomeView: 'home.png' },
+            render_locale: 'en',
+            provenance: { HomeView: { ...GOOD_PROV, resolved: false } },
+        });
+        writeReference(project, 'home.png');
+        const run = runScript(project, await buildScript(project));
+        expect(run.status).toBe(0);
+        const home = readResult(project).screens[0];
+        expect(home.status).toBe('rendered');
+        expect(home.error).toBeNull();
+        expect(home.copy_advisory?.code).toBe('copy_unverifiable');
+        expect(home.copy_advisory?.reason).toBe('unresolved_placeholders');
+    });
+    test('the placeholder downgrade is identical without a render_locale (same input, same verdict)', async () => {
+        const project = makeProject({
+            screens: { HomeView: 'home.png' },
+            provenance: { HomeView: { ...GOOD_PROV, resolved: false } },
+        });
+        writeReference(project, 'home.png');
+        const run = runScript(project, await buildScript(project));
+        expect(run.status).toBe(0);
+        const home = readResult(project).screens[0];
+        expect(home.status).toBe('rendered');
+        expect(home.copy_advisory?.reason).toBe('unresolved_placeholders');
+    });
+    test('an Italian reference against an English render downgrades the copy channel', async () => {
+        const project = makeProject({
+            screens: { HomeView: 'home.png' },
+            render_locale: 'en',
+            provenance: { HomeView: { ...GOOD_PROV, locale: 'it' } },
+        });
+        writeReference(project, 'home.png');
+        const run = runScript(project, await buildScript(project));
+        expect(run.status).toBe(0);
+        const home = readResult(project).screens[0];
+        expect(home.status).toBe('rendered');
+        expect(home.copy_advisory?.reason).toBe('locale_mismatch');
+    });
+    test('locale comparison requires a declared render_locale — its absence skips only that', async () => {
+        const project = makeProject({
+            screens: { HomeView: 'home.png' },
+            provenance: { HomeView: { ...GOOD_PROV, locale: 'it' } },
+        });
+        writeReference(project, 'home.png');
+        const run = runScript(project, await buildScript(project));
+        expect(run.status).toBe(0);
+        const home = readResult(project).screens[0];
+        expect(home.status).toBe('rendered');
+        expect(home.copy_advisory ?? null).toBeNull();
+    });
+    test('an absent reference with provenance is fatal (REFERENCE_ABSENT, unverifiable)', async () => {
+        const project = makeProject({
+            screens: { HomeView: 'home.png' },
+            provenance: { HomeView: GOOD_PROV },
+        });
+        // No writeReference — the file is absent.
+        const run = runScript(project, await buildScript(project));
+        expect(run.status).not.toBe(0);
+        const home = readResult(project).screens[0];
+        expect(home.status).toBe('unverifiable');
+        expect(home.error?.code).toBe('REFERENCE_ABSENT');
+    });
+    test('a clean provenanced reference renders with no copy advisory', async () => {
+        const project = makeProject({
+            screens: { HomeView: 'home.png' },
+            render_locale: 'en',
+            provenance: { HomeView: GOOD_PROV },
+        });
+        writeReference(project, 'home.png');
+        const run = runScript(project, await buildScript(project));
+        expect(run.status).toBe(0);
+        const home = readResult(project).screens[0];
+        expect(home.status).toBe('rendered');
+        expect(home.copy_advisory ?? null).toBeNull();
+    });
+    test('an unprovenanced screen keeps its legacy behaviour even with a render_locale (no NO_PROVENANCE arming on iOS)', async () => {
+        // NO_PROVENANCE hard-arming is Android-legacy only; the iOS step never
+        // refused unprovenanced screens and must not start now.
+        const project = makeProject({
+            screens: { HomeView: 'home.png' },
+            render_locale: 'en',
+            provenance: {},
+        });
+        writeReference(project, 'home.png');
+        const run = runScript(project, await buildScript(project));
+        expect(run.status).toBe(0);
+        const home = readResult(project).screens[0];
+        expect(home.status).toBe('rendered');
+        expect(home.copy_advisory ?? null).toBeNull();
+    });
+    test('independent verdicts: a clean sibling carries no advisory while the placeholder state does', async () => {
+        const project = makeProject({
+            screens: { HomeView: 'home.png', SettingsView: 'settings.png' },
+            provenance: {
+                HomeView: GOOD_PROV,
+                SettingsView: { ...GOOD_PROV, resolved: false },
+            },
+        });
+        writeReference(project, 'home.png');
+        writeReference(project, 'settings.png');
+        const run = runScript(project, await buildScript(project));
+        expect(run.status).toBe(0);
+        const [home, settings] = readResult(project).screens;
+        expect(home.copy_advisory ?? null).toBeNull();
+        expect(settings.status).toBe('rendered');
+        expect(settings.copy_advisory?.reason).toBe('unresolved_placeholders');
+    });
+});
 //# sourceMappingURL=ui-fidelity-render.test.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invarn/cibuild",
-  "version": "2.3.5",
+  "version": "2.3.7",
   "description": "CI Build CLI — local pipeline orchestration and validation",
   "type": "module",
   "main": "dist/cli.cjs",