spine-rigc 0.4.0 → 0.6.0

package/src/emit.ts

@@ -0,0 +1,88 @@
+/**
+ * Writing the compiled atlas to disk with its pages copied alongside it — the
+ * step behind `build --copy-images` (issue #217).
+ *
+ * `compile()` never touches the filesystem for output; it only reads inputs and
+ * assembles text (see its own header). A page's name in that text is
+ * `relative(outDir, absPath)` — the PNG's path *as seen from the atlas file* — so
+ * it points at wherever the source art already lives, which is very often
+ * outside `outDir` (`../parts/torso.png`). That is the right default for a build
+ * that sits beside the project that owns the art, and it is exactly what makes
+ * `--out` non-self-contained the moment the directory is zipped, committed or
+ * handed to someone who does not have that project.
+ *
+ * `copyAtlasImages` is the opt-in other half: copy every referenced page PNG
+ * into the output directory and hand back the atlas text with page names
+ * rewritten to match. Nothing here runs unless `cli.ts` calls it, so the default
+ * emit (`buildAtlasText` in [`src/compile.ts`](compile.ts)) is untouched.
+ */
+import { copyFileSync, mkdirSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import { buildAtlasText } from './compile.ts';
+import type { CompiledImage } from './types.ts';
+
+/** One page's source and where `--copy-images` put it. */
+export interface CopiedPage {
+  region: string;
+  /** Absolute path the page was read from. */
+  from: string;
+  /** Filename inside the output directory — also the atlas's new page name. */
+  to: string;
+}
+
+export interface CopyImagesResult {
+  /** The atlas text, with every page name rewritten to its `to` filename. */
+  atlasText: string;
+  pages: CopiedPage[];
+}
+
+/**
+ * Copy every image `compile()` referenced into `outDir` and return the atlas
+ * text rewritten to match.
+ *
+ * ## Naming and collisions
+ *
+ * A page's filename in `outDir` is its source basename, unchanged. That is safe
+ * because rigc already enforces a stronger invariant upstream: a region name IS
+ * the PNG basename (`compile.ts`'s `addImage`), and two images sharing a region
+ * are refused at compile time — so within one compile, no two entries of
+ * `images` can legitimately carry the same basename already.
+ *
+ * The check below exists anyway. "The caller already prevents this" stops being
+ * true the moment the caller changes, and a case-insensitive filesystem (the
+ * macOS default) can still collide two basenames the region check saw as
+ * distinct (`Torso.png` vs `torso.png` are different regions, one destination
+ * file). On a genuine collision, the second and later claimants of a name get
+ * `-2`, `-3`, … inserted before the extension, assigned in the order `images`
+ * lists them — the same order the atlas itself is written in, so the mapping is
+ * identical on every run of the same compile. The rewritten atlas is the record
+ * of it: reading a page name back out says exactly which file it is, with no
+ * side table to fall out of sync.
+ */
+export function copyAtlasImages(images: CompiledImage[], outDir: string): CopyImagesResult {
+  mkdirSync(outDir, { recursive: true });
+
+  const claimedBy = new Map<string, string>(); // destination filename -> absPath holding it
+  const pages: CopiedPage[] = [];
+
+  for (const img of images) {
+    const original = basename(img.absPath);
+    let name = original;
+    if (claimedBy.has(name) && claimedBy.get(name) !== img.absPath) {
+      const ext = extname(original);
+      const stem = original.slice(0, original.length - ext.length);
+      let n = 2;
+      do {
+        name = `${stem}-${n}${ext}`;
+        n++;
+      } while (claimedBy.has(name) && claimedBy.get(name) !== img.absPath);
+    }
+    claimedBy.set(name, img.absPath);
+    pages.push({ region: img.region, from: img.absPath, to: name });
+  }
+
+  for (const page of pages) copyFileSync(page.from, join(outDir, page.to));
+
+  const rewritten: CompiledImage[] = images.map((img, i) => ({ ...img, page: pages[i].to }));
+  return { atlasText: buildAtlasText(rewritten), pages };
+}

package/src/json-position.ts

@@ -0,0 +1,253 @@
+/**
+ * Best-effort line/column for a `JSON.parse` failure.
+ *
+ * Bun's `JSON.parse` (JavaScriptCore) names the fault — `JSON Parse error:
+ * Property name must be a string literal` — and never a position, so a caller
+ * only ever learns which file was bad, not where inside it. This module fills
+ * that gap without a dependency: it re-walks the text through a minimal,
+ * hand-written JSON grammar and stops at the first place that grammar
+ * disagrees with the text.
+ *
+ * ⚠️ This is not a JSON parser used to parse anything — `JSON.parse` still owns
+ * every successful parse and every error MESSAGE. `locateJsonError` only ever
+ * runs after `JSON.parse` has already thrown, purely to attribute a position to
+ * the failure it already found. That is why it does not have to be a complete,
+ * spec-perfect grammar: for the ordinary mistakes (an unquoted key, a trailing
+ * comma, a missing colon, an unterminated string) the two parsers diverge at
+ * the same character, so the position is exact. Wherever this scanner is
+ * looser or stricter than `JSON.parse` in some corner, the position can be
+ * early rather than exactly the runtime's own stopping point — which is why
+ * it is documented, and named, as best-effort rather than exact.
+ */
+
+export interface JsonPosition {
+  /** 1-based, like every editor and every compiler diagnostic. */
+  line: number;
+  column: number;
+}
+
+/** Thrown internally the moment the grammar walk disagrees with the text. */
+class ScanStopped {
+  constructor(readonly position: JsonPosition) {}
+}
+
+class Cursor {
+  private i = 0;
+  private line = 1;
+  private column = 1;
+
+  constructor(private readonly text: string) {}
+
+  get done(): boolean {
+    return this.i >= this.text.length;
+  }
+
+  peek(): string | undefined {
+    return this.text[this.i];
+  }
+
+  startsWith(s: string): boolean {
+    return this.text.startsWith(s, this.i);
+  }
+
+  advance(): void {
+    if (this.text[this.i] === '\n') {
+      this.line++;
+      this.column = 1;
+    } else {
+      this.column++;
+    }
+    this.i++;
+  }
+
+  position(): JsonPosition {
+    return { line: this.line, column: this.column };
+  }
+}
+
+function isDigit(c: string | undefined): boolean {
+  return c !== undefined && c >= '0' && c <= '9';
+}
+
+function isHexDigit(c: string | undefined): boolean {
+  return c !== undefined && ((c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F'));
+}
+
+function isWhitespace(c: string | undefined): boolean {
+  return c === ' ' || c === '\t' || c === '\n' || c === '\r';
+}
+
+function stop(cur: Cursor): never {
+  throw new ScanStopped(cur.position());
+}
+
+function skipWhitespace(cur: Cursor): void {
+  while (!cur.done && isWhitespace(cur.peek())) cur.advance();
+}
+
+function skipLiteral(cur: Cursor, length: number): void {
+  for (let k = 0; k < length; k++) cur.advance();
+}
+
+const STRING_ESCAPES = new Set(['"', '\\', '/', 'b', 'f', 'n', 'r', 't']);
+
+function scanString(cur: Cursor): void {
+  cur.advance(); // opening quote
+  for (;;) {
+    if (cur.done) stop(cur);
+    const c = cur.peek()!;
+    if (c === '"') {
+      cur.advance();
+      return;
+    }
+    if (c === '\\') {
+      cur.advance();
+      const esc = cur.peek();
+      if (esc !== undefined && STRING_ESCAPES.has(esc)) {
+        cur.advance();
+        continue;
+      }
+      if (esc === 'u') {
+        cur.advance();
+        for (let k = 0; k < 4; k++) {
+          if (!isHexDigit(cur.peek())) stop(cur);
+          cur.advance();
+        }
+        continue;
+      }
+      stop(cur); // unknown escape
+    }
+    if (c.charCodeAt(0) < 0x20) stop(cur); // raw control character in a string
+    cur.advance();
+  }
+}
+
+function scanNumber(cur: Cursor): void {
+  if (cur.peek() === '-') cur.advance();
+  if (cur.peek() === '0') {
+    cur.advance();
+  } else if (isDigit(cur.peek())) {
+    while (isDigit(cur.peek())) cur.advance();
+  } else {
+    stop(cur);
+  }
+  if (cur.peek() === '.') {
+    cur.advance();
+    if (!isDigit(cur.peek())) stop(cur);
+    while (isDigit(cur.peek())) cur.advance();
+  }
+  if (cur.peek() === 'e' || cur.peek() === 'E') {
+    cur.advance();
+    if (cur.peek() === '+' || cur.peek() === '-') cur.advance();
+    if (!isDigit(cur.peek())) stop(cur);
+    while (isDigit(cur.peek())) cur.advance();
+  }
+}
+
+function scanValue(cur: Cursor): void {
+  skipWhitespace(cur);
+  if (cur.done) stop(cur);
+  const c = cur.peek();
+  if (c === '{') return scanObject(cur);
+  if (c === '[') return scanArray(cur);
+  if (c === '"') return scanString(cur);
+  if (c === '-' || isDigit(c)) return scanNumber(cur);
+  if (cur.startsWith('true')) return skipLiteral(cur, 4);
+  if (cur.startsWith('false')) return skipLiteral(cur, 5);
+  if (cur.startsWith('null')) return skipLiteral(cur, 4);
+  stop(cur);
+}
+
+function scanObject(cur: Cursor): void {
+  cur.advance(); // '{'
+  skipWhitespace(cur);
+  if (cur.peek() === '}') {
+    cur.advance();
+    return;
+  }
+  for (;;) {
+    skipWhitespace(cur);
+    // The classic unquoted-key mistake stops here — this is
+    // "Property name must be a string literal" in JavaScriptCore's own words.
+    if (cur.peek() !== '"') stop(cur);
+    scanString(cur);
+    skipWhitespace(cur);
+    if (cur.peek() !== ':') stop(cur);
+    cur.advance();
+    scanValue(cur);
+    skipWhitespace(cur);
+    const c = cur.peek();
+    if (c === ',') {
+      cur.advance();
+      continue;
+    }
+    if (c === '}') {
+      cur.advance();
+      return;
+    }
+    stop(cur);
+  }
+}
+
+function scanArray(cur: Cursor): void {
+  cur.advance(); // '['
+  skipWhitespace(cur);
+  if (cur.peek() === ']') {
+    cur.advance();
+    return;
+  }
+  for (;;) {
+    scanValue(cur);
+    skipWhitespace(cur);
+    const c = cur.peek();
+    if (c === ',') {
+      cur.advance();
+      skipWhitespace(cur);
+      continue;
+    }
+    if (c === ']') {
+      cur.advance();
+      return;
+    }
+    stop(cur);
+  }
+}
+
+/**
+ * Where, in `text`, a strict JSON parse first disagrees with it. Best-effort:
+ * see the module doc for what that means and why.
+ */
+export function locateJsonError(text: string): JsonPosition {
+  const cur = new Cursor(text);
+  try {
+    scanValue(cur);
+    skipWhitespace(cur);
+    if (!cur.done) stop(cur); // trailing content after the one top-level value
+  } catch (err) {
+    if (err instanceof ScanStopped) return err.position;
+    throw err;
+  }
+  // The grammar walk above found nothing wrong, even though `JSON.parse` did —
+  // this scanner is looser than the runtime parser in whatever way this file's
+  // fault is. Rather than claim a location it did not actually find, it points
+  // at the end of the file.
+  return cur.position();
+}
+
+/**
+ * `JSON.parse`, with a `(line N, column N)` suffix appended to the message
+ * whenever it throws a `SyntaxError` — the runtime's own message, positioned.
+ * Any other error (a non-JSON exception `JSON.parse` never actually throws,
+ * kept here only for type safety) passes through unchanged.
+ */
+export function parseJsonWithPosition(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    if (err instanceof SyntaxError) {
+      const { line, column } = locateJsonError(text);
+      throw new SyntaxError(`${err.message} (line ${line}, column ${column})`);
+    }
+    throw err;
+  }
+}

package/src/png.ts

@@ -1,10 +1,18 @@
 /**
  * PNG header reader.
  *
- * The only thing rigc needs from a part PNG is its true pixel size and whether
- * it carries an alpha channel, and both live in the IHDR chunk that every PNG
- * puts first. Parsing 26 bytes keeps the compiler dependency-free: no image
- * library, and nothing on the module path but rigc itself.
+ * The only things rigc needs from a part PNG are its true pixel size and whether
+ * it can draw a transparent pixel. The size is in the IHDR chunk that every PNG
+ * puts first; transparency is in the IHDR's colour type OR in a `tRNS` chunk a
+ * little further in, so the reader walks the file's small leading chunks and
+ * stops at the pixel data. That keeps the compiler dependency-free — no image
+ * library, and nothing on the module path but rigc itself — while still reading
+ * every place the answer can be written down.
+ *
+ * ⚠️ It reads a header, not an image: "can this file draw a transparent pixel",
+ * never "does it". Whether the art actually has a transparent margin is a
+ * question about pixels, and the tools that measure pixels decode the whole file
+ * ([`tools/plate.ts`](../tools/plate.ts)).
  *
  * Measuring instead of trusting is the whole point: an atlas `size:` that
  * disagrees with the file loads clean and collapses the UVs silently.
@@ -13,21 +21,72 @@ import { readFileSync } from 'node:fs';
 
 const SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
 
-/** PNG colour types that carry a per-pixel alpha channel. */
+/**
+ * PNG colour types that carry a per-pixel alpha channel.
+ *
+ * ⭐ False here does NOT mean opaque, and reading it that way is what #215 was:
+ * types 0, 2 and 3 can all carry a `tRNS` chunk instead — a palette alpha table
+ * for indexed art, one invisible colour for the other two — and indexed+tRNS is
+ * the ordinary output of ImageMagick, Photoshop's PNG-8 export, GIMP's indexed
+ * mode, aseprite and pngquant. `hasTransparency` is the field to judge art by;
+ * this one answers the narrower question of where the alpha is stored.
+ */
 const COLOUR_TYPE_HAS_ALPHA: Record<number, boolean> = {
   0: false, // greyscale
   2: false, // truecolour
-  3: false, // indexed (may have tRNS, but not a straight alpha channel)
+  3: false, // indexed (transparency, if any, is in tRNS)
   4: true, // greyscale + alpha
   6: true, // truecolour + alpha
 };
 
+/** The spec's name for each colour type, for messages that have to name one. */
+const COLOUR_TYPE_NAMES: Record<number, string> = {
+  0: 'greyscale',
+  2: 'truecolour',
+  3: 'indexed',
+  4: 'greyscale + alpha',
+  6: 'truecolour + alpha',
+};
+
+/** How to say a colour type out loud. Unknown types print as themselves. */
+export function colourTypeName(colourType: number): string {
+  return COLOUR_TYPE_NAMES[colourType] ?? 'unrecognised';
+}
+
 export interface PngInfo {
   width: number;
   height: number;
   bitDepth: number;
   colourType: number;
+  /** A per-pixel alpha channel in the pixel data: colour types 4 and 6, and only those. */
   hasAlpha: boolean;
+  /** A `tRNS` chunk: a palette alpha table (type 3), or one invisible colour (types 0 and 2). */
+  hasTrns: boolean;
+  /** Either of the above — the file is able to draw a transparent pixel. */
+  hasTransparency: boolean;
+}
+
+/**
+ * Walk the chunk list looking for `tRNS`, stopping where it can no longer appear.
+ *
+ * The spec orders `tRNS` after `PLTE` and before the first `IDAT`, so this reads
+ * only the file's small leading chunks and never touches the compressed bulk. A
+ * length that would run past the end of the file ends the walk rather than
+ * throwing: a truncated PNG is A17 and A06's business, and answering "no tRNS"
+ * about a file nobody can open is the same answer either way.
+ */
+function scanForTrns(buf: Buffer): boolean {
+  let at = 8; // past the signature; the first chunk is IHDR
+  while (at + 8 <= buf.length) {
+    const length = buf.readUInt32BE(at);
+    const type = buf.toString('latin1', at + 4, at + 8);
+    if (type === 'tRNS') return true;
+    if (type === 'IDAT' || type === 'IEND') return false;
+    const next = at + 12 + length; // 4 length + 4 type + body + 4 CRC
+    if (next <= at || next > buf.length) return false;
+    at = next;
+  }
+  return false;
 }
 
 export function readPngInfo(path: string): PngInfo {
@@ -40,11 +99,17 @@ export function readPngInfo(path: string): PngInfo {
     throw new Error(`PNG does not start with IHDR: ${path}`);
   }
   const colourType = buf.readUInt8(25);
+  const hasAlpha = COLOUR_TYPE_HAS_ALPHA[colourType] ?? false;
+  // A file with an alpha channel cannot also carry tRNS, so the scan is skipped
+  // for the types that already answered — which is every PNG rigc itself writes.
+  const hasTrns = hasAlpha ? false : scanForTrns(buf);
   return {
     width: buf.readUInt32BE(16),
     height: buf.readUInt32BE(20),
     bitDepth: buf.readUInt8(24),
     colourType,
-    hasAlpha: COLOUR_TYPE_HAS_ALPHA[colourType] ?? false,
+    hasAlpha,
+    hasTrns,
+    hasTransparency: hasAlpha || hasTrns,
   };
 }