@rig-c/core 2.62.0 → 2.64.0

package/src/cli/shared.ts

@@ -40,6 +40,7 @@ import { depthStepLevels, type FoldLimit, type TurnCeiling } from '../depth.ts';
 import { FOLDS_FILE } from '../folds.ts';
 import { DRAWN_ALPHA, PASS_THROUGH_FILE, PASS_THROUGH_RUN } from '../passthrough.ts';
 import { SEAM_FILE } from '../seam.ts';
+import { OVERLAPS_FILE } from '../overlaps.ts';
 import { readViewportBox, ViewportError } from '../viewportpin.ts';
 import { parseJsonWithPosition } from '../json-position.ts';
 import { RUNG_IDS } from '../ladder.ts';
@@ -69,6 +70,7 @@ import { RepackError } from '../repack.ts';
 import { SplitError } from '../meshsplit.ts';
 import { SpineRuntimeError, SPINE_SIDE_ABSENT } from '../spine_side.ts';
 import type { CompileResult, DroppedState } from '../types.ts';
+import { StdoutWriteError } from './write_whole.ts';
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 
@@ -146,7 +148,7 @@ export { PACKAGE_ROOT, readPackageMeta, readVersion };
  * needs a value` (issue #328). `CLI10`/`CLI11` in `selftest.ts` now hold the two
  * halves together by reading `--help` rather than by naming a flag.
  */
-const BOOLEAN_FLAGS = new Set(['all', 'all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'folds', 'accept-skeleton-differences', 'keep-pages', 'dim']);
+const BOOLEAN_FLAGS = new Set(['all', 'all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'folds', 'overlaps', 'accept-skeleton-differences', 'keep-pages', 'dim']);
 
 /**
  * The flags a command is allowed to spell more than once.
@@ -1052,6 +1054,14 @@ const FLAG_MEANINGS: Record<string, string> = {
     'world units, one texel of the coarser drawing to a step — each with the depth and the world box. One line per pair, and one per frame that passes through. ' +
     'The order is the declaration: the first name must draw over the second for a frame to be read. A reading, not a gate. ' +
     'An unknown slot, a slot that draws on no frame, a malformed list and a pair named twice are refused by name. Not with --slot/--hide',
+  overlaps:
+    `also read which slot each frame drew over which, and write ${OVERLAPS_FILE} into each frame directory: per frame, every pair ` +
+    `of slots where the slot drawn later covers pixels the earlier one drew (drawn at ${DRAWN_ALPHA} of 255 or more, on the frames' own ` +
+    'pixels), with the pixel count and the pixel box. One OVERLAP line per pair that covers anything — the frames, and the most pixels ' +
+    'and the frame of them — and one line counting the pairs that cover the same pixels on every frame (layering the motion does not move). ' +
+    'Each frame with a moving pair also gets an outline plate, overlaps-f<NNNN>.png: every slot in a moving pair as its contour in its own ' +
+    'colour, dashed where a slot drawn later covers it, named at its top. The render reports what was drawn; who should be in front is the ' +
+    "author's, and the draw-order key in the motion spec is the remedy. A reading, not a gate. Not with --slot/--hide",
   seam:
     `also read, for each <slot>:<slot> pair, where the two drawings stop meeting, and write ${SEAM_FILE} into each frame directory: ` +
     'per pair, the frames with a gap — background inside the hull of the band the two drawings share at the setup pose, carried to the frame by both — ' +
@@ -1409,8 +1419,12 @@ interface CommandDoc {
    * delegate's exit code is the command's. `flags` is empty for that reason:
    * rigc documents no flag of a program it does not own. A control that reads
    * a command's flag table off `--help` reads it off the commands without this.
+   *
+   * `bareTarget` and `subcommands` (issue #1486): a first argument that is none
+   * of `subcommands` and does not start with `-` is a target, handed over as
+   * `<bareTarget> <target> …` — the one rewrite the launcher makes.
    */
-  delegate?: { package: string; bin: string };
+  delegate?: { package: string; bin: string; bareTarget?: string; subcommands?: readonly string[] };
 }
 
 export const COMMANDS: CommandDoc[] = [
@@ -1733,10 +1747,11 @@ export const COMMANDS: CommandDoc[] = [
       'rigc render … --environment <schedule.json>   (the wind and gravity the physics answers, in time)',
       'rigc render … --pass-through <cloth>:<leg>[,…]   (the frames where a cloth drawn over a leg passes through it)',
       'rigc render … --seam <slot>:<slot>[,…]   (the frames where two slots that meet open a gap or show a ghost)',
+      'rigc render … --overlaps   (which slot each frame drew over which, by name, with an outline plate)',
       'rigc render … --angle-range <bone>:<relative-to>[,…]   (how far a bone turns against another, per animation)',
       'rigc render … --viewport <x,y,w,h> | --viewport-from <frames.json>   (a box given, not fitted: two renders on one pixel grid)',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'pass-through', 'seam', 'angle-range', 'environment', 'poser', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'pass-through', 'seam', 'overlaps', 'angle-range', 'environment', 'poser', 'out'],
     overrides: {
       out: { value: '<dir>', meaning: 'directory to write the frame series into (default `render/`)' },
       fps: {
@@ -1942,9 +1957,12 @@ export const COMMANDS: CommandDoc[] = [
     name: 'review',
     runtime: false,
     spineFormat: false,
-    delegate: { package: '@rig-c/review', bin: 'rig-review' },
+    // rig-review's own first words: every one of them, `--help`, `-h` and `--` (rig-review's way to its legacy bare
+    // form) pass through; anything else first is a build directory, handed over as `open <dir>` (issue #1486).
+    delegate: { package: '@rig-c/review', bin: 'rig-review', bareTarget: 'open', subcommands: ['open', 'check', 'feedback', 'control', 'strip', 'compare'] },
     usage: [
-      "rigc review <dir> [...]      (@rig-c/review's rig-review, installed beside: every argument handed over untouched, its exit code returned — `rigc review open <dir>` prints a loopback URL to give a person, `rigc review --help` is rig-review's own usage)",
+      "rigc review <dir> [--reference <video>] [--animation <name>] [--compare <dir>]   (rig-review open <dir> …: prints a loopback URL to give a person)",
+      "rigc review open|check|feedback|control|strip|compare|--help …   (@rig-c/review's rig-review, installed beside: every argument handed over untouched, its stdout and exit code returned; rigc never installs it)",
     ],
     flags: [],
   },
@@ -3168,6 +3186,12 @@ function refuse(err: unknown, command: string | undefined, USAGE: string, entry:
     console.error(`rigc skills install: ${err.message}`);
     process.exit(1);
   }
+  // A document the reader stopped taking (issue #1487): exit 1 like a lookup that could not answer, and the line
+  // says how many bytes went out of how many and why — a silent short write is what `writeWhole` exists to refuse.
+  if (err instanceof StdoutWriteError) {
+    console.error(`rigc ${command}: ${err.message}`);
+    process.exit(1);
+  }
   // A rule or section the guide does not have (issue #1397): exit 1 like a lookup that found nothing, and the
   // message names what was asked and the nearest real names — the usage under it would bury them.
   if (err instanceof GuideError) {

package/src/cli/write_whole.ts

@@ -0,0 +1,92 @@
+/**
+ * `writeWhole(fd, text)`: every byte of `text`, UTF-8, onto `fd`, or a named
+ * refusal — the writer a command uses for a document too large to trust to
+ * `console.log` (issue #1487).
+ *
+ * ⚖️ Why not `console.log`: on Bun 1.2.0, the declared minimum, one ~322 KB
+ * line with non-ASCII in it came out 330,634 bytes for 330,632, a stray
+ * `\xe2\x00` at a 64 KiB chunk boundary — to a file, a pipe and a slow pipe
+ * alike. And on a stdout whose pipe is non-blocking (a parent set `O_NONBLOCK`
+ * on it), it stopped near 64 KiB on 1.2.0 *and* 1.4.2 with exit 0.
+ *
+ * ⚖️ Why a loop and not one `writeSync(fd, text)`: on that non-blocking pipe
+ * `writeSync` returns a short count — 65,536 of 330,632 — and throws nothing,
+ * so a single call drops the rest in silence on both Buns. Each call here
+ * writes from where the last one stopped.
+ *
+ * ⚖️ Why not `process.stdout.write` and a wait for `drain`: whole on 1.4.2,
+ * but on 1.2.0 over the non-blocking pipe it wrote more bytes than it was
+ * given (397,312 and climbing, diverging at byte 69,633) and never exited.
+ *
+ * A pipe that is full answers `EAGAIN` (or a zero count): the loop waits —
+ * 1 ms, doubling to {@link STALL_WAIT_CAP_MS} — and tries again, and after
+ * {@link MAX_STALLS} answers in a row with no byte taken it refuses with
+ * {@link StdoutWriteError}. `EPIPE` — the reader closed its end, as `| head`
+ * does — stops the write quietly, which is what `console.log` did there (exit 0
+ * on both Buns, measured): the reader has what it asked for. Any other error
+ * (`EBADF`, `EIO`) refuses at once.
+ * The wait is `Atomics.wait` on a cell nothing notifies: a delay, not a reading
+ * of the clock — no value written depends on how long it lasted, and the bound
+ * is a count of attempts, so whether it refuses depends on the reader alone.
+ */
+import { writeSync } from 'node:fs';
+
+/** The answers in a row with no byte taken before the writer refuses — about a minute of waits at the cap. */
+export const MAX_STALLS = 1000;
+/** The longest single wait between two attempts on a full pipe, in milliseconds. */
+export const STALL_WAIT_CAP_MS = 64;
+
+/** A write the reader never took: what was written, of how many bytes, and why it stopped. */
+export class StdoutWriteError extends Error {
+  override name = 'StdoutWriteError';
+}
+
+/** `fs.writeSync`'s buffer form: bytes written, or a throw carrying `code`. */
+export type WriteFn = (fd: number, buffer: Uint8Array, offset: number, length: number) => number;
+
+/**
+ * The selftest's plants (issue #1487): `write` stands in for `fs.writeSync` so a
+ * short count or an `EAGAIN` can be forced, and `wait` for the delay so a plant
+ * runs without sleeping. Nothing outside the selftest passes either.
+ */
+export interface WriteWholePlants {
+  write?: WriteFn;
+  wait?: (ms: number) => void;
+}
+
+const STALL_CODES = new Set(['EAGAIN', 'EWOULDBLOCK', 'EINTR']);
+
+function sleep(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+export function writeWhole(fd: number, text: string, plants: WriteWholePlants = {}): void {
+  const write = plants.write ?? ((f: number, b: Uint8Array, o: number, l: number) => writeSync(f, b, o, l));
+  const wait = plants.wait ?? sleep;
+  const bytes = Buffer.from(text, 'utf8');
+  let offset = 0;
+  let stalls = 0;
+  while (offset < bytes.length) {
+    let taken = 0;
+    try {
+      taken = write(fd, bytes, offset, bytes.length - offset);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      // The reader closed its end (`| head`): it has what it asked for, and nobody is left to read the rest.
+      if (code === 'EPIPE') return;
+      if (code === undefined || !STALL_CODES.has(code)) {
+        throw new StdoutWriteError(`${offset} of ${bytes.length} byte(s) confirmed written to fd ${fd} before it stopped: ${code ?? String(err)} — the descriptor is not writable`);
+      }
+    }
+    if (taken > 0) {
+      offset += taken;
+      stalls = 0;
+      continue;
+    }
+    stalls += 1;
+    if (stalls > MAX_STALLS) {
+      throw new StdoutWriteError(`${offset} of ${bytes.length} byte(s) confirmed written to fd ${fd}, and the reader took nothing for ${MAX_STALLS} attempt(s) in a row — it stopped reading`);
+    }
+    wait(Math.min(2 ** (stalls - 1), STALL_WAIT_CAP_MS));
+  }
+}