incanto 0.68.0 → 0.70.0

package/bin/incanto-verify.mjs

@@ -19,23 +19,20 @@
  * what to arrange, and says so in the summary.
  */
 import { spawnSync } from 'node:child_process';
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, statSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { readJson } from './_read-json.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
-const { ladderText, ladderVerdict } = await import(
+const { firstLine, ladderText, ladderVerdict, saysRung } = await import(
   pathToFileURL(join(PKG, 'dist', 'test.js')).href
 );
 
 const argv = process.argv.slice(2);
 const asJson = argv.includes('--json');
-const flag = (name) => {
-  const i = argv.indexOf(name);
-  return i >= 0 ? argv[i + 1] : null;
-};
 if (argv.includes('--help') || argv.includes('-h')) {
-  console.log(`Usage: incanto verify [scene.json] [--behaviors FILE] [--json]
+  console.log(`Usage: incanto verify [scene.json] [--behaviors FILE[,FILE...]] [--json]
 
 Walks the whole ladder and tells you the ONE thing to do next:
 
@@ -111,7 +108,26 @@ const { scene, candidates } = findScene();
 if (!scene) {
   const report = ladderVerdict([], { candidates });
   console.log(asJson ? JSON.stringify(report, null, 2) : ladderText(report));
-  process.exit(0);
+  /*
+   * Exit 2, not 0.
+   *
+   * "Unmeasured is not a failure" is the rule for a RUNG — the game is fine and
+   * a question could not be asked. This is different: nothing was measured at
+   * ALL, and a CI step whose whole job is `incanto-verify` went green having
+   * looked at nothing:
+   *
+   *   2 scenes here, and guessing between them would verify the wrong one:
+   *     src/game.scene.json
+   *     src/title.scene.json
+   *   $ echo $?
+   *   0
+   *
+   * A distinct code rather than 1, so a script can still tell "your game is
+   * broken" from "tell me WHICH game" — and `verdict.measured` says the same
+   * thing to anything reading `--json`. Multi-scene is the shape of almost
+   * every real game, so this is not an edge case for long.
+   */
+  process.exit(2);
 }
 if (!existsSync(scene) || !statSync(scene).isFile()) {
   console.error(`no such scene: ${scene}`);
@@ -129,8 +145,20 @@ if (!existsSync(scene) || !statSync(scene).isFile()) {
  * path to a file sitting right next to the scene it had already found.
  */
 function findBehaviors(sceneFile) {
-  const named = flag('--behaviors');
-  if (named) return { file: named, guessed: false };
+  /*
+   * Every `--behaviors`, not the first one.
+   *
+   * The flag is repeatable in the bins this spawns, and reading only
+   * `argv.indexOf` would have silently dropped every file after the first —
+   * the CLI accepting an argument and then not using it, which is the shape
+   * this round keeps finding. Joined with commas, which is the other form the
+   * children take.
+   */
+  const named = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--behaviors' && argv[i + 1]) named.push(argv[++i]);
+  }
+  if (named.length > 0) return { file: named.join(','), guessed: false };
   const near = dirname(sceneFile);
   for (const dir of [near, join(near, '..'), process.cwd(), join(process.cwd(), 'src')]) {
     for (const base of ['behaviors', 'behaviours']) {
@@ -275,31 +303,62 @@ if (rungs[0].status === 'pass') {
           .join(', ') +
         ')' +
         (won > 0 ? ` — ${won} did finish it` : ''),
+      // The throw itself, not a command to go and find it. This rung used to
+      // say "read the throw: incanto-playtest …" — sending its reader to
+      // another tool for a line this JSON already carries.
+      notes: (out?.errorMessages ?? []).slice(0, 3),
       fix:
         tally('error') > 0
-          ? `read the throw: \`incanto-playtest ${scene}${behaviors ? ` --behaviors ${behaviors}` : ''}\`, and \`engine.stats().errors\` in your own harness`
+          ? `fix the script named above, then re-run \`incanto-verify ${scene}${behaviors ? ` --behaviors ${behaviors}` : ''}\``
           : tally('fell') > 0
             ? `the player left the world with nothing catching them — give the level a floor, walls, or a respawn (\`incanto-playtest ${scene}${behaviors ? ` --behaviors ${behaviors}` : ''}\` prints where)`
             : `nothing moved — check the input map and the controller: \`incanto-playtest ${scene}${behaviors ? ` --behaviors ${behaviors}` : ''}\``,
     });
-  } else if (r.status === 0) {
+  } else if (won > 0) {
+    /*
+     * `r.status === 0` used to stand in for "it finished the game", and the
+     * exit code stopped meaning that: `incanto-playtest` now exits 0 for a
+     * scene with nobody to drive, because never being asked is not a failure.
+     * This rung read that 0 and reported
+     *
+     *   ✓ plays — 0 of 8 seeded runs finished it
+     *
+     * on a scene with no character in it, right where it had been careful to
+     * say `? plays — nothing here is drivable`. The report has `runs`; ask it
+     * what happened rather than asking the child how it felt about it.
+     */
     rungs.push({
       name: 'plays',
       status: 'pass',
       summary: `${won} of ${total} seeded runs finished it`,
     });
   } else if (undrivable) {
+    /*
+     * "Nobody to move" was said about games the bot had PLAYED.
+     *
+     * The driver has driven the mouse for a while, and this rung only ever
+     * asked whether a character could walk — so a flip puzzle whose every tile
+     * the bot clicked, whose `clicked` wires all fired and whose board changed
+     * state, was told to add a character controller. A whole class of games —
+     * match-3, tower defense, cards, point-and-click, RTS, board games — has no
+     * character to add, and the advice was to add one anyway.
+     */
+    const clicks = (out?.runs ?? []).reduce((n, r) => n + (r.clicks ?? 0), 0);
     rungs.push({
       name: 'plays',
       status: 'unmeasured',
       summary:
-        out?.hasPlayer === false
-          ? `nothing here is drivable — ${total} runs had nobody to move`
-          : `${total} runs went nowhere, and your behaviours were not loaded — that is most of what moves a character`,
+        clicks > 0
+          ? `played with the MOUSE — ${clicks} click(s) across ${total} runs, and no win to reach`
+          : out?.hasPlayer === false
+            ? `nothing here is drivable — ${total} runs had nobody to move and nothing to click`
+            : `${total} runs went nowhere, and your behaviours were not loaded — that is most of what moves a character`,
       fix:
-        out?.hasPlayer === false
-          ? 'give the player a character controller, the `player` group, or the name Player — otherwise no seeded run can play this'
-          : `name them: \`incanto-verify ${scene} --behaviors src/behaviors.ts\``,
+        clicks > 0
+          ? 'a mouse game is played, not walked — emit `won`/`lost` and this rung can pass'
+          : out?.hasPlayer === false
+            ? 'give the player a character controller, the `player` group, or the name Player — or `Clickable` on what the cursor drives'
+            : `name them: \`incanto-verify ${scene} --behaviors src/behaviors.ts\``,
     });
   } else if (noGoal) {
     rungs.push({
@@ -317,9 +376,22 @@ if (rungs[0].status === 'pass') {
     rungs.push({
       name: 'plays',
       status: 'unmeasured',
+      // The parenthetical is only worth printing when it has something in it.
+      // It listed `lost` and `unfinished` and nothing else, so a game whose
+      // runs all ended at a SCENE SWAP — every tally zero — reported
+      // `8 runs played without reaching a win ()`, an empty bracket where the
+      // reason should be. `swapped` IS the reason, and it is the one outcome
+      // here that explains itself.
       summary:
         `${total} runs played without reaching a win` +
-        ` (${[count(tally('lost'), 'lost'), count(tally('unfinished'), 'ran out the clock')].filter(Boolean).join(', ')})`,
+        (() => {
+          const why = [
+            count(tally('lost'), 'lost'),
+            count(tally('unfinished'), 'ran out the clock'),
+            count(tally('swapped'), 'changed scene, where this bot stops measuring'),
+          ].filter(Boolean);
+          return why.length > 0 ? ` (${why.join(', ')})` : '';
+        })(),
       fix: 'nothing here is broken — a win that takes skill or a sequence is out of reach of random play. Judge it with a scripted run: `bun run verify`, or `runScript` from `incanto/test`',
     });
   }
@@ -363,13 +435,36 @@ if (rungs[0].status === 'pass') {
     // arithmetic that cannot be true: `✓ feels — 12 of 9 fired`. The number has
     // to add up with the `silent` list beside it.
     const firedDeclared = declaredPaths.length - silent.length;
+    /*
+     * A rung that exists because "wired but never triggered plays perfectly and
+     * feels dead, and every other rung here calls it healthy" — and which then
+     * called it healthy itself. `fired.size === 0` failed and ANYTHING else
+     * passed, so the flagship starter reported
+     *
+     *   ✓ feels — 13 of 26 fired — silent: /Game/Ward1/ChimeSfx …
+     *
+     * A tick next to thirteen emitters nobody heard is the same claim the rung
+     * was written to stop.
+     *
+     * It is not a FAILURE either: a random bot does not light three wards, so a
+     * win chime it never reached is not a broken wire. That is exactly what
+     * `unmeasured` means in this ladder — the tool did not get to look — and it
+     * is the one status that cannot be read as approval.
+     */
     rungs.push({
       name: 'feels',
-      status: 'pass',
-      summary:
-        silent.length === 0
-          ? `every one of the ${declared} sound/effect nodes fired`
-          : `${firedDeclared} of ${declared} fired — silent: ${silent.slice(0, 3).join(', ')}${silent.length > 3 ? ` +${silent.length - 3}` : ''}`,
+      ...(silent.length === 0
+        ? { status: 'pass', summary: `every one of the ${declared} sound/effect nodes fired` }
+        : {
+            status: 'unmeasured',
+            summary:
+              `${firedDeclared} of ${declared} fired — silent: ${silent.slice(0, 3).join(', ')}` +
+              `${silent.length > 3 ? ` +${silent.length - 3}` : ''}`,
+            fix:
+              'a silent emitter is either a broken wire or a moment random play never ' +
+              'reached — the two look identical from here. Reach it in a scripted run ' +
+              '(`runScript` from `incanto/test`), and this rung can tell you which.',
+          }),
     });
   }
 }
@@ -381,7 +476,7 @@ if (rungs[0].status === 'pass') {
 {
   const isMultiplayer = (() => {
     try {
-      const doc = JSON.parse(readFileSync(scene, 'utf-8'));
+      const doc = readJson(scene);
       return Boolean(doc?.multiplayer);
     } catch {
       return false;
@@ -449,6 +544,30 @@ if (rungs[0].status === 'pass') {
         ? 'bring the preview window to the front — a hidden tab does not render, and a frame is captured inside a render'
         : 'start your dev server, open the page, and run this again — the pixels are in the browser',
     });
+  } else if (report.hidden) {
+    /*
+     * A hidden page is UNMEASURED, not passed.
+     *
+     * A browser stops animating a page it considers hidden — a window merely
+     * covered by another counts — and the back buffer keeps whatever it last
+     * drew. Measured at one instant, same page:
+     *
+     *   incanto-frame --do   the page is hidden … a frozen game    (exit 1)
+     *   incanto-logs         frame rate not measurable — hidden
+     *   incanto-frame        subject fills 17.5% of frame
+     *   incanto-verify       ✓ draws — subject fills 17.5%
+     *
+     * Two of six rungs reported ✓ off a stale buffer while the engine already
+     * knew, and said elsewhere, that the page was drawing nothing. The skills
+     * state the rule: an unmeasured rung is not a failure, and this is exactly
+     * the unmeasured case.
+     */
+    rungs.push({
+      name: 'draws',
+      status: 'unmeasured',
+      summary: 'the page is HIDDEN — those pixels are whatever it last drew',
+      fix: 'bring the window to the front (one covered by another counts as hidden) and run this again',
+    });
   } else if (report.black) {
     rungs.push({
       name: 'draws',
@@ -464,10 +583,26 @@ if (rungs[0].status === 'pass') {
       fix: 'check the camera: `incanto-frame --out shot.png` and look at what it is aimed at',
     });
   } else {
+    /*
+     * A rung that PASSED can still have something to say, and this one was
+     * dropping it. `incanto-frame` prints `CLIPPED by the frame edge` and
+     * `the subject fills almost nothing` — real observations about a shot that
+     * is technically non-black — and the ladder replaced all of it with one
+     * coverage number. The `loads` rung has carried its tool's warnings since
+     * the day a scene described as "It will render black" came back green.
+     */
+    const notes = [];
+    if (report.subject.clipped) {
+      notes.push('the subject is CLIPPED by the frame edge — part of it is off screen');
+    }
+    if (report.uniform) {
+      notes.push('one flat colour — the camera may be inside geometry, or only the sky is drawn');
+    }
     rungs.push({
       name: 'draws',
       status: 'pass',
       summary: `subject fills ${(report.subject.coverage * 100).toFixed(1)}% of the frame`,
+      ...(notes.length > 0 ? { notes } : {}),
     });
   }
 }
@@ -488,21 +623,11 @@ if (rungs[0].status === 'pass') {
       summary: firstLine(r.stderr) ?? 'no page to ask',
       fix: 'open the preview page and run this again — the log buffer is in the browser',
     });
-  } else if (report.ok) {
-    rungs.push({ name: 'says', status: 'pass', summary: 'no errors, no failed assets' });
   } else {
-    const asset = report.assetErrors?.[0];
-    rungs.push({
-      name: 'says',
-      status: 'fail',
-      // A game whose grass and water are fine still fails here when its player
-      // never loaded — which is the case this rung exists for, and the one
-      // `draws` calls healthy.
-      summary: asset
-        ? `asset ${asset.ref} never loaded: ${asset.error}`
-        : (report.worst?.message ?? `${report.stats?.errors ?? 0} errors were swallowed`),
-      fix: 'read it in full: `incanto-logs`',
-    });
+    // What it MEANS lives in `verify-ladder` with the rest of the pure half —
+    // this rung was reading `ok` and dropping every warning the page reported,
+    // and there was nowhere to test that without a browser.
+    rungs.push(saysRung(report));
   }
 }
 
@@ -516,10 +641,6 @@ function safeJson(text) {
     return null;
   }
 }
-function firstLine(text) {
-  const line = (text ?? '').split('\n').find((l) => l.trim());
-  return line ? line.trim() : null;
-}
 
 const verdict = ladderVerdict(rungs);
 if (asJson) {
@@ -536,4 +657,4 @@ if (asJson) {
 // asynchronously, and exiting discards whatever has not flushed. A --json
 // report read by another program came back truncated — silently, and only
 // when piped, which is the only way a program reads it.
-process.exitCode = verdict.ok ? 0 : 1;
+process.exitCode = verdict.measured ? (verdict.ok ? 0 : 1) : 2;

package/bin/incanto.mjs

@@ -23,9 +23,10 @@
  * the SAME runtime that started this one, which matters because `--behaviors`
  * loads your TypeScript and bun and node disagree about what they can import.
  */
-import { readFileSync } from 'node:fs';
+
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { readJson } from './_read-json.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -40,6 +41,7 @@ const COMMANDS = {
   feel: ['incanto-feel.mjs', 'measure jump height, run speed, facing'],
   frame: ['incanto-frame.mjs', 'what the running page is drawing right now'],
   logs: ['incanto-logs.mjs', 'what the running page has been saying'],
+  serve: ['incanto-serve.mjs', 'serve a BUILT game so the tools can measure it'],
   editor: ['incanto-editor.mjs', 'the visual scene composer'],
   model: ['incanto-model.mjs', "a GLB's real bounds, animations and rig"],
   assets: ['incanto-assets.mjs', 'the built-in art and audio catalog'],
@@ -49,7 +51,7 @@ const COMMANDS = {
 
 function version() {
   try {
-    const pkg = JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf-8'));
+    const pkg = readJson(join(HERE, '..', 'package.json'));
     return pkg.version ?? 'unknown';
   } catch {
     return 'unknown';