Skip to content

The design language that makes your AI harness better at design.

JavaScript
13.8 KB
Raw Blame
/**
 * Corpus for the comp-fidelity verbs: `comp-spec`, `comp-diff`, `font-match`,
 * `build-phase`. Only the deterministic, browser-free paths are exercised here
 * (the font-match browser ranking and the comp-diff artifact PNGs vary by
 * Chrome/encoder and are covered by Rust tests instead).
 *
 * Workspace tests/oracle/workspaces/comp-basic:
 *   comp.png       a 768x512 comp fixture (from crates/comp/tests/fixtures)
 *   build.png      a recolored build capture of the same composition
 *   regions.json   three regions (chrome / plate / text) with allowUncovered
 *   spec.json      a pre-measured spec of comp.png+regions.json (the fixture the
 *                  print / diff / measure cases read; the regions case rewrites
 *                  its own under .impeccable/build/)
 *
 * ISO timestamps in stdout and in the written spec/state are masked by the
 * harness, so the createdAt/startedAt fields never make a golden run-dependent.
 */

import fs from 'node:fs';
import path from 'node:path';
import crypto from 'node:crypto';

const WS = 'comp-basic';

const write = (ws, rel, body) => {
  const abs = path.join(ws, rel);
  fs.mkdirSync(path.dirname(abs), { recursive: true });
  fs.writeFileSync(abs, body);
};

// The comp verbs emit no staleness/update directives, but pin the catalog and
// skill-dir overrides so a recording machine's env never leaks a font-index
// path or a native reference into the output.
const BASE_ENV = {
  IMPECCABLE_CATALOG_DIR: null,
  IMPECCABLE_SKILL_DIR: null,
  IMPECCABLE_SELF: null,
  IMPECCABLE_BROWSER: null,
  PUPPETEER_EXECUTABLE_PATH: null,
  CHROME_PATH: null,
  CI: null,
};
const env = (extra = {}) => ({ ...BASE_ENV, ...extra });

const cases = [
  // comp-spec: grid readout (stdout only), full measure (writes spec.json), print.
  { id: 'comp-spec-grid', verb: 'comp-spec', workspace: WS, args: ['--comp', 'comp.png', '--grid'], env: env() },
  {
    id: 'comp-spec-regions', verb: 'comp-spec', workspace: WS,
    args: ['--comp', 'comp.png', '--regions', 'regions.json'],
    files: ['.impeccable/build/spec.json'], env: env(),
  },
  { id: 'comp-spec-print', verb: 'comp-spec', workspace: WS, args: ['--print', '--spec', 'spec.json'], env: env() },
  { id: 'comp-spec-plate-prompt', verb: 'comp-spec', workspace: WS, args: ['--plate-prompt', 'art', '--spec', 'spec.json'], env: env() },
  { id: 'comp-spec-usage', verb: 'comp-spec', workspace: WS, args: [], env: env() },
  {
    id: 'comp-spec-excluded-reference', verb: 'comp-spec', workspace: WS,
    setup: (ws) => write(ws, 'excluded.json', JSON.stringify({ comp: 'comp.png', regions: [
      { id: 'art', kind: 'plate', medium: 'raster', px: { x: 0, y: 0, w: 32, h: 32 } },
      { id: 'nav', kind: 'chrome', px: { x: 0, y: 0, w: 32, h: 32 } },
    ] })),
    args: ['--crop', 'art', '--spec', 'excluded.json', '--out', 'excluded.png'], env: env(),
  },
  {
    id: 'comp-spec-refuses-painted-chrome', verb: 'comp-spec', workspace: WS,
    setup: (ws) => write(ws, 'bad.json', JSON.stringify({ allowUncovered: true, regions: [{ id: 'x', kind: 'chrome', grid: 'A0:B1', note: 'an exploded diagram illustration' }] })),
    args: ['--comp', 'comp.png', '--regions', 'bad.json'], env: env(),
  },

  // comp-diff: with a spec (region rows) and without (derived bands).
  { id: 'comp-diff-json', verb: 'comp-diff', workspace: WS, args: ['--comp', 'comp.png', '--build', 'build.png', '--spec', 'spec.json', '--no-files', '--json'], env: env() },
  { id: 'comp-diff-text', verb: 'comp-diff', workspace: WS, args: ['--comp', 'comp.png', '--build', 'build.png', '--spec', 'spec.json', '--no-files'], env: env() },
  { id: 'comp-diff-no-spec', verb: 'comp-diff', workspace: WS, args: ['--comp', 'comp.png', '--build', 'build.png', '--no-files', '--json'], env: env() },
  { id: 'comp-diff-threshold-below', verb: 'comp-diff', workspace: WS, args: ['--comp', 'comp.png', '--build', 'build.png', '--spec', 'spec.json', '--no-files', '--threshold', '0.95'], env: env() },
  { id: 'comp-diff-usage', verb: 'comp-diff', workspace: WS, args: ['--comp', 'comp.png'], env: env() },

  // font-match: MEASURE (pure; writes type onto the region). RANK is skipped
  // here because it needs a browser; the no-browser catalog fallback needs the
  // moat's font-index, which is not present in this repo's oracle env.
  { id: 'font-match-measure', verb: 'font-match', workspace: WS, args: ['--measure', 'body', '--spec', 'spec.json'], files: ['spec.json'], env: env() },
  { id: 'font-match-usage', verb: 'font-match', workspace: WS, args: [], env: env() },

  // build-phase: start (reads comp dims) then status, sharing one workspace.
  {
    id: 'build-phase-start-status', verb: 'build-phase', workspace: WS,
    files: ['.impeccable/build/state.json'], env: { ...env(), IMPECCABLE_SESSION_ID: 'oracle-build' },
    steps: [{ args: ['start', '--comp', 'comp.png'] }, { args: ['status'] }],
  },
  { id: 'build-phase-usage', verb: 'build-phase', workspace: WS, args: [], env: env() },

  // The direction round's chosen comp is option one of the comp round: start
  // records it, the comps gate counts it from .impeccable/mocks/decision/ (an
  // unrelated decision comp never counts), and an approval on it closes the
  // gate with the decision path as the approved comp. --decision-comp with
  // --comp, or naming a missing file, is refused.
  {
    id: 'build-phase-decision-comp-option-one', verb: 'build-phase', workspace: WS,
    files: ['.impeccable/build/state.json', '.impeccable/build/approved-comp.json'], env: env(),
    setup: (ws) => {
      fs.mkdirSync(path.join(ws, '.impeccable/mocks/decision'), { recursive: true });
      fs.copyFileSync(path.join(ws, 'comp.png'), path.join(ws, '.impeccable/mocks/decision/assigned.png'));
      write(ws, '.impeccable/mocks/decision/assigned.png.json', JSON.stringify({ prompt: 'assigned' }));
      fs.copyFileSync(path.join(ws, 'build.png'), path.join(ws, '.impeccable/mocks/decision/pick.png'));
      write(ws, '.impeccable/mocks/decision/pick.png.json', JSON.stringify({ prompt: 'pick', approved: true }));
    },
    steps: [
      { args: ['start', '--comp', 'comp.png', '--decision-comp', '.impeccable/mocks/decision/assigned.png'] },
      { args: ['start', '--direction', 'seed', '--decision-comp', '.impeccable/mocks/decision/missing.png'] },
      { args: ['start', '--direction', 'seed', '--decision-comp', '.impeccable/mocks/decision/assigned.png'] },
      { args: ['advance'] },
      {
        setup: (ws) => {
          for (const n of [2, 3]) {
            fs.copyFileSync(path.join(ws, 'build.png'), path.join(ws, `.impeccable/mocks/comp-${n}.png`));
            write(ws, `.impeccable/mocks/comp-${n}.png.json`, JSON.stringify({ prompt: `variation ${n}` }));
          }
          write(ws, '.impeccable/mocks/decision/assigned.png.json', JSON.stringify({ prompt: 'assigned', approved: true }));
        },
        args: ['advance'],
      },
    ],
  },

  // The approved comp is a fixed reference: start keeps a copy, comp-spec binds
  // the same pixels, and once the comp is edited (build.png copied over it, the
  // shape of compositing plates into it) the gate, a re-measure and comp-diff
  // all refuse before measuring. restore-comp puts the approved pixels back and
  // the spec gate measures again (its own readings, not the refusal).
  {
    id: 'build-phase-approved-comp-edited', verb: 'build-phase', workspace: WS,
    files: ['.impeccable/build/approved-comp.json'], env: env(),
    steps: [
      { args: ['start', '--comp', 'comp.png'] },
      { verb: 'comp-spec', args: ['--comp', 'comp.png', '--regions', 'regions.json'] },
      { setup: (ws) => fs.copyFileSync(path.join(ws, 'build.png'), path.join(ws, 'comp.png')), args: ['advance'] },
      { verb: 'comp-spec', args: ['--comp', 'comp.png', '--regions', 'regions.json'] },
      { verb: 'comp-diff', args: ['--comp', 'comp.png', '--build', 'build.png', '--spec', '.impeccable/build/spec.json', '--no-files'] },
      { args: ['restore-comp'] },
      { args: ['advance'] },
    ],
  },

  // build-phase responsive (workspace comp-responsive: a menu column ending in a
  // sign-off line; spec.json and a state at the responsive phase are staged
  // under .impeccable/build/, which git ignores in fixtures). A desktop capture whose
  // column grew pushes the sign-off 40px down past the first viewport: the gate
  // calls it displaced, prints the repair crops, and on the third failed attempt
  // leads with the route to the user. A capture without the line calls it missing.
  {
    id: 'build-phase-responsive-displaced', verb: 'build-phase', workspace: 'comp-responsive',
    setup: (ws) => {
      fs.mkdirSync(path.join(ws, '.impeccable/review'), { recursive: true });
      fs.mkdirSync(path.join(ws, '.impeccable/build'), { recursive: true });
      fs.copyFileSync(path.join(ws, 'spec.json'), path.join(ws, '.impeccable/build/spec.json'));
      fs.copyFileSync(path.join(ws, 'state.json'), path.join(ws, '.impeccable/build/state.json'));
      fs.copyFileSync(path.join(ws, 'desktop-pushed.png'), path.join(ws, '.impeccable/review/desktop.png'));
      fs.copyFileSync(path.join(ws, 'mobile.png'), path.join(ws, '.impeccable/review/mobile.png'));
    },
    env: env(),
    steps: [{ args: ['advance', '--min', '0.1'] }, { args: ['advance', '--min', '0.1'] }, { args: ['advance', '--min', '0.1'] }],
  },
  {
    id: 'build-phase-responsive-missing', verb: 'build-phase', workspace: 'comp-responsive',
    setup: (ws) => {
      fs.mkdirSync(path.join(ws, '.impeccable/review'), { recursive: true });
      fs.mkdirSync(path.join(ws, '.impeccable/build'), { recursive: true });
      fs.copyFileSync(path.join(ws, 'spec.json'), path.join(ws, '.impeccable/build/spec.json'));
      fs.copyFileSync(path.join(ws, 'state.json'), path.join(ws, '.impeccable/build/state.json'));
      fs.copyFileSync(path.join(ws, 'desktop-gone.png'), path.join(ws, '.impeccable/review/desktop.png'));
      fs.copyFileSync(path.join(ws, 'mobile.png'), path.join(ws, '.impeccable/review/mobile.png'));
    },
    args: ['advance', '--min', '0.1'], env: env(),
  },

  // build-phase after a native ship: the finish binds every file the final
  // capture read (captureInputs), so a later font edit, entry bytes unchanged,
  // voids it. status prints the NEXT line for each state; completion lists the
  // changed paths. A review-phase status prints the review NEXT.
  {
    id: 'build-phase-shipped-then-edited', verb: 'build-phase', workspace: WS,
    env: env(),
    steps: [
      {
        setup: (ws) => {
          const sha = (rel) => crypto.createHash('sha256').update(fs.readFileSync(path.join(ws, rel))).digest('hex');
          write(ws, 'index.html', '<main><h1>Shipped</h1></main>\n');
          write(ws, 'fonts/face.ttf', 'font v1');
          const phases = Object.fromEntries(['comps', 'spec', 'plates', 'hero', 'sections', 'motion', 'responsive', 'review']
            .map((p) => [p, { status: 'closed', attempts: 1, gate: { ok: true, summary: 'oracle' } }]));
          write(ws, '.impeccable/build/state.json', JSON.stringify({
            tool: 'build-phase', version: 2, startedAt: '2026-10-04T00:00:00.000Z', comp: 'comp.png', breakpoint: '768x512',
            artifact: 'index.html', phase: 'review', capturePolicy: 'native-html-v1', sessionId: 'oracle-build', phases,
            finish: { disposition: 'ship', at: '2026-10-04T00:00:00.000Z', phaseAtFinish: 'review', artifactSha256: sha('index.html'),
              captureInputs: [{ path: 'index.html', sha256: sha('index.html') }, { path: 'fonts/face.ttf', sha256: sha('fonts/face.ttf') }] },
          }, null, 2));
        },
        args: ['status'],
      },
      { setup: (ws) => write(ws, 'fonts/face.ttf', 'font v2'), args: ['status'] },
      { args: ['completion', '--session-id', 'oracle-build'] },
    ],
  },
  {
    id: 'build-phase-review-next-native', verb: 'build-phase', workspace: WS,
    setup: (ws) => write(ws, '.impeccable/build/state.json', JSON.stringify({
      tool: 'build-phase', version: 2, startedAt: '2026-10-04T00:00:00.000Z', comp: 'comp.png', breakpoint: '768x512',
      artifact: 'index.html', phase: 'review', capturePolicy: 'native-html-v1', phases: {},
    }, null, 2)),
    args: ['status'], env: env(),
  },

  // component-review plan: the v3 packet derives from the measured spec. The
  // spec fixture has one plate region (art), one non-container chrome (top,
  // a plan item) and one text region (body, a code region).
  { id: 'component-review-usage', verb: 'component-review', workspace: WS, args: [], env: env() },
  {
    id: 'component-review-plan-missing-plates', verb: 'component-review', workspace: WS,
    setup: (ws) => write(ws, '.impeccable/build/spec.json', fs.readFileSync(path.join(ws, 'spec.json'))),
    args: ['plan'], env: env(),
  },
  {
    id: 'component-review-plan', verb: 'component-review', workspace: WS,
    setup: (ws) => {
      write(ws, '.impeccable/build/spec.json', fs.readFileSync(path.join(ws, 'spec.json')));
      write(ws, 'assets/plates/art.png', fs.readFileSync(path.join(ws, 'comp.png')));
    },
    args: ['plan'], files: ['.impeccable/review/components.json'], env: env(),
  },
  // Absolute paths inside the project and backslashed ones come back project-relative
  // with forward slashes (comp-spec may record either).
  {
    id: 'component-review-plan-absolute-paths', verb: 'component-review', workspace: WS,
    setup: (ws) => {
      const spec = JSON.parse(fs.readFileSync(path.join(ws, 'spec.json'), 'utf8'));
      spec.comp = path.join(fs.realpathSync(ws), 'comp.png');
      for (const r of spec.regions) if (r.id === 'art') r.plate = 'assets\\plates\\art.png';
      write(ws, '.impeccable/build/spec.json', JSON.stringify(spec));
      write(ws, 'assets/plates/art.png', fs.readFileSync(path.join(ws, 'comp.png')));
    },
    args: ['plan'], files: ['.impeccable/review/components.json'], env: env(),
    // The spec names the staged workspace, so its digest is run-dependent.
    normalize: [['("specSha256": ")[0-9a-f]{64}', 'g', '$1<SHA256>']],
  },
];

export default cases;