paperlint 3.1.3 → 4.0.0

package/src/adapters/banal/index.ts

@@ -14,7 +14,8 @@ import type { Geometry, Provenance } from "../../domain/geometry.ts";
 import type { AbsolutePath } from "../../domain/paths.ts";
 import { err, ok } from "../../domain/result.ts";
 import type { MeasureGeometry } from "../../ports/measure-geometry.ts";
-import type { Ready, ToolInstaller } from "../../ports/tool-installer.ts";
+import { ready, type Ready } from "../../domain/ready.ts";
+import type { ToolInstaller } from "../../ports/tool-installer.ts";
 import { describe } from "./failure.ts";
 import { provenanceLabel, type BanalCandidate } from "./locate.ts";
 import { pinLabel, type BanalSource } from "./pin.ts";
@@ -65,12 +66,12 @@ export function banalMeasurer(
 }
 
 /** The one place banal's `Ready` is minted: from an `Installed`, whose `PinnedBanal` only run.ts mints. */
-const ready = (i: Installed): Ready =>
-  ({
-    where: i.banal.path as string,
+const readyOf = (i: Installed): Ready =>
+  ready({
+    where: i.banal.path,
     fresh: i.fresh,
     verified: "sha256 verified, and it measured a probe page",
-  }) as Ready;
+  });
 
 /**
  * banal as the `ToolInstaller` port: download at the pin, check the sha256, accept by measuring a
@@ -88,12 +89,12 @@ export function banalInstaller(
         ...(source ? { source } : {}),
         onDownload: report,
       });
-      return r.ok ? ok(ready(r.value)) : err(describe(r.error));
+      return r.ok ? ok(readyOf(r.value)) : err(describe(r.error));
     },
     check() {
       const r = checkBanal(d, s, source);
       return r.ok
-        ? ok(ready({ banal: r.value, fresh: false }))
+        ? ok(readyOf({ banal: r.value, fresh: false }))
         : err(describe(r.error));
     },
   };

package/src/adapters/banal/install.ts

@@ -15,14 +15,19 @@ export interface ShaMismatch {
   readonly got: Sha256;
 }
 
+// The brand's one owner: the predicate IS the pin check, so no assertion is needed to mint the type.
+const isPinned = (
+  bytes: Uint8Array,
+  source: BanalSource,
+): bytes is PinnedBytes => sha256Hex(bytes) === source.sha256;
+
 export function verifyPin(
   bytes: Uint8Array,
   source: BanalSource,
 ): Result<PinnedBytes, ShaMismatch> {
-  const got = sha256Hex(bytes);
-  return got === source.sha256
-    ? ok(bytes as PinnedBytes)
-    : err({ expected: source.sha256, got });
+  return isPinned(bytes, source)
+    ? ok(bytes)
+    : err({ expected: source.sha256, got: sha256Hex(bytes) });
 }
 
 /** What is installed, judged against the pin. */

package/src/adapters/banal/invocation.test.ts

@@ -11,15 +11,15 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll as after, test } from "vitest";
 import { nodeAdapters } from "../node/index.ts";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath } from "../../domain/paths.ts";
+import type { Scratch } from "../../ports/workspace.ts";
 import {
   banalCommand,
+  parseShQuoted,
   shQuote,
   stage,
   stageBanalInput,
-  type StagedInput,
 } from "./invocation.ts";
-import type { LocatedBanal } from "./locate.ts";
 import { XML_DIALECT } from "./xml.ts";
 
 test("the staging holds BOTH files: the XML and the -v stub answering the dialect paperlint writes", () => {
@@ -32,11 +32,14 @@ test("the staging holds BOTH files: the XML and the -v stub answering the dialec
 });
 
 test("banalCommand: perl runs banal on the staged .xml, with $PDFTOHTML quoted", () => {
-  const banal = {
-    path: "/b/banal" as AbsolutePath,
-    provenance: { kind: "cache" },
-  } as LocatedBanal;
-  const staged = { xml: "/s/paper.xml", stub: "/s d/pdftohtml" } as StagedInput;
+  // A scratch that places the two files in different directories, one with a space.
+  const scratch: Scratch = {
+    dir: absolutePath("/s"),
+    write: (name) =>
+      absolutePath(name === "paper.xml" ? "/s/paper.xml" : "/s d/pdftohtml"),
+  };
+  const staged = stage(scratch, stageBanalInput([]));
+  const banal = { path: absolutePath("/b/banal") };
   const c = banalCommand(banal, staged, { PATH: "/bin" });
   assert.deepEqual(
     [c.file, ...c.args],
@@ -50,8 +53,19 @@ test("shQuote survives a single quote", () => {
   assert.equal(shQuote("it's"), `'it'"'"'s'`);
 });
 
+test("parseShQuoted refuses a word the shell would split or expand", () => {
+  assert.equal(parseShQuoted(`'a b'`), `'a b'`);
+  assert.throws(() => parseShQuoted("a b"), /not one single-quoted shell word/);
+  assert.throws(
+    () => parseShQuoted(`'a'b'`),
+    /not one single-quoted shell word/,
+  );
+});
+
 const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-stage-test-")));
-after(() => rmSync(root, { recursive: true, force: true }));
+after(() => {
+  rmSync(root, { recursive: true, force: true });
+});
 
 test("🔴 stage: on a real scratch directory the stub answers `-v` through the shell, from a path with a space and a quote", () => {
   const awkward = join(root, "it's a dir");

package/src/adapters/banal/invocation.ts

@@ -7,13 +7,13 @@
  * (`Error: Failed to run pdftohtml`, measured); told a version below 0.85 it applies a larger
  * correction and every font size moves. So `$PDFTOHTML` (banal's own override, line 166) points at a
  * stub that answers `-v` with `XML_DIALECT.version` — the pdftohtml whose XML `xml.ts` writes — and
- * refuses anything else. `test/e2e/banal.mjs` shows both failures with the real banal.
+ * refuses anything else. `test/e2e/banal.ts` shows both failures with the real banal.
  */
 import type { Opaque } from "ts-essentials";
 import type { AbsolutePath } from "../../domain/paths.ts";
 import type { Command } from "../../ports/process.ts";
 import type { Scratch } from "../../ports/workspace.ts";
-import type { LocatedBanal } from "./locate.ts";
+import type { BanalCandidate } from "./locate.ts";
 import type { PageLayout } from "../../domain/page-layout.ts";
 import { pdf2xml, XML_DIALECT } from "./xml.ts";
 
@@ -23,9 +23,19 @@ export const BANAL_RUN_MS = 120_000;
 /** A path quoted for `/bin/sh`. Minted by `shQuote` only. */
 export type ShQuoted = Opaque<string, "ShQuoted">;
 
+// One single-quoted word: any run of non-quotes, each quote spelled `'"'"'`. What `shQuote` writes.
+const SH_QUOTED = /^'(?:[^']|'"'"')*'$/;
+const isShQuoted = (s: string): s is ShQuoted => SH_QUOTED.test(s);
+
+/** A word already quoted for `/bin/sh`, checked; anything else throws. */
+export function parseShQuoted(s: string): ShQuoted {
+  if (!isShQuoted(s)) throw new Error(`not one single-quoted shell word: ${s}`);
+  return s;
+}
+
 /** banal interpolates `$PDFTOHTML` into a shell command unquoted — so the value is quoted here. */
 export const shQuote = (s: string): ShQuoted =>
-  `'${s.replace(/'/g, `'"'"'`)}'` as ShQuoted;
+  parseShQuoted(`'${s.replace(/'/g, `'"'"'`)}'`);
 
 /** The stub standing in for `pdftohtml`: it answers `-v` and refuses to convert anything. */
 export const PDFTOHTML_STUB = [
@@ -64,11 +74,15 @@ export const stageBanalInput = (
   ],
 });
 
+// Not exported: only `stage` can write the property, so only it can make a StagedInput.
+const STAGED = Symbol("StagedInput");
+
 /** The staging written to disk. Minted by `stage` only: both files written, or nothing returned. */
-export type StagedInput = Opaque<
-  { readonly xml: AbsolutePath; readonly stub: AbsolutePath },
-  "StagedInput"
->;
+export interface StagedInput {
+  readonly xml: AbsolutePath;
+  readonly stub: AbsolutePath;
+  readonly [STAGED]: true;
+}
 
 /** Write a staging into a scratch directory, the stub executable. The only minter of `StagedInput`. */
 export function stage(s: Scratch, staging: BanalStaging): StagedInput {
@@ -76,12 +90,13 @@ export function stage(s: Scratch, staging: BanalStaging): StagedInput {
   return {
     xml: s.write(xml.name, xml.content, xml.mode),
     stub: s.write(stub.name, stub.content, stub.mode),
-  } as StagedInput;
+    [STAGED]: true,
+  };
 }
 
 /** `perl banal -no-time -json <xml>`, with `$PDFTOHTML` quoted by construction. */
 export function banalCommand(
-  banal: LocatedBanal,
+  banal: Pick<BanalCandidate, "path">,
   staged: StagedInput,
   baseEnv: Readonly<Record<string, string>>,
 ): Command {

package/src/adapters/banal/locate.test.ts

@@ -1,13 +1,13 @@
 import assert from "node:assert/strict";
 import { test } from "vitest";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath } from "../../domain/paths.ts";
 import { err } from "../../domain/result.ts";
 import { installedBanal, lookupOrder, pickBanal } from "./locate.ts";
 import { BANAL_PIN } from "./pin.ts";
 import { parseBanalSettings } from "./settings.ts";
 
 const dirs = { home: "/h", tmp: "/t", cwd: "/w" };
-const project = "/p" as AbsolutePath;
+const project = absolutePath("/p");
 const cache = `/h/.cache/paperlint/banal/${BANAL_PIN.commit.slice(0, 12)}/banal`;
 const on =
   (...files: string[]) =>

package/src/adapters/banal/locate.ts

@@ -3,9 +3,7 @@
  * `$BANAL` (an explicit choice — if it names nothing, there is NO fallback), `<project>/vendor/banal`
  * (a project that vendors its own copy), then the one `paperlint toolchain` installed.
  */
-import { join } from "node:path";
-import type { Opaque } from "ts-essentials";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { joinPath, type AbsolutePath } from "../../domain/paths.ts";
 import { err, ok, type Result } from "../../domain/result.ts";
 import { BANAL_PIN } from "./pin.ts";
 import type { BanalSettings } from "./settings.ts";
@@ -20,14 +18,20 @@ export interface BanalCandidate {
   readonly provenance: Provenance;
 }
 
-/** A candidate the `Files` port confirmed is a file. Minted by `pickBanal` only. */
-export type LocatedBanal = Opaque<BanalCandidate, "LocatedBanal">;
+// Not exported: only this module can write the property, so only `locate` can make a LocatedBanal.
+const LOCATED = Symbol("LocatedBanal");
 
-/**
- * `paperlint toolchain`'s banal after its bytes hashed to the pin AND it measured the probe page. Minted by
- * `ensureBanal` / `checkBanal` only (`./index.ts`): a "ready" line cannot be printed without one.
- */
-export type PinnedBanal = Opaque<BanalCandidate, "PinnedBanal">;
+/** A candidate the `Files` port confirmed is a file. Minted by `pickBanal` (through `locate`) only. */
+export type LocatedBanal = BanalCandidate & { readonly [LOCATED]: true };
+
+/** `path` as a banal to run — when the `Files` port says it is a file, else null. */
+function locate(
+  path: AbsolutePath,
+  kind: Provenance["kind"],
+  isFile: (p: AbsolutePath) => boolean,
+): LocatedBanal | null {
+  return isFile(path) ? { path, provenance: { kind }, [LOCATED]: true } : null;
+}
 
 /** Why there is no banal to run. */
 export type BanalMissing =
@@ -47,7 +51,7 @@ export type LookupOrder =
 
 /** Where `paperlint toolchain` puts the pinned banal: one directory per HotCRP commit. */
 export const installedBanal = (s: BanalSettings): AbsolutePath =>
-  join(s.cacheDir, BANAL_PIN.commit.slice(0, 12), "banal") as AbsolutePath;
+  joinPath(s.cacheDir, BANAL_PIN.commit.slice(0, 12), "banal");
 
 export function lookupOrder(
   s: BanalSettings,
@@ -56,25 +60,27 @@ export function lookupOrder(
   if (s.explicit) return { kind: "explicit", path: s.explicit };
   return {
     kind: "search",
-    vendor: join(projectRoot, "vendor", "banal") as AbsolutePath,
+    vendor: joinPath(projectRoot, "vendor", "banal"),
     cache: installedBanal(s),
   };
 }
 
-const located = (path: AbsolutePath, kind: Provenance["kind"]) =>
-  ok({ path, provenance: { kind } } as LocatedBanal);
-
 export function pickBanal(
   order: LookupOrder,
   isFile: (p: AbsolutePath) => boolean,
 ): Result<LocatedBanal, BanalMissing> {
-  if (order.kind === "explicit")
-    return isFile(order.path)
-      ? located(order.path, "env")
+  if (order.kind === "explicit") {
+    const own = locate(order.path, "env", isFile);
+    return own
+      ? ok(own)
       : err({ kind: "explicit-not-found", path: order.path });
-  if (isFile(order.vendor)) return located(order.vendor, "vendor");
-  if (isFile(order.cache)) return located(order.cache, "cache");
-  return err({ kind: "not-installed", installed: order.cache });
+  }
+  const found =
+    locate(order.vendor, "vendor", isFile) ??
+    locate(order.cache, "cache", isFile);
+  return found
+    ? ok(found)
+    : err({ kind: "not-installed", installed: order.cache });
 }
 
 /** Which rule found it, as a person reads it. */

package/src/adapters/banal/output.test.ts

@@ -1,6 +1,6 @@
 /**
  * `output.ts` — every way a banal run can end, as a table of `ProcessExit` → `Result`, and the
- * measurement → geometry projection. Pure: no perl, no disk. The real banal is `test/e2e/banal.mjs`.
+ * measurement → geometry projection. Pure: no perl, no disk. The real banal is `test/e2e/banal.ts`.
  */
 import assert from "node:assert/strict";
 import { test } from "vitest";

package/src/adapters/banal/run.test.ts

@@ -1,7 +1,7 @@
 /**
  * `adapters/banal/run.ts` — running and installing banal, on in-memory ports: which `Command` it builds, what it stages,
  * what it downloads and writes, and what it concludes. No perl, no disk, no network: the adapters
- * record, and each assertion reads the record. Real perl and the real banal are `test/e2e/banal.mjs`;
+ * record, and each assertion reads the record. Real perl and the real banal are `test/e2e/banal.ts`;
  * the adapters' own behaviour is `src/adapters/node/*.test.ts`.
  */
 import assert from "node:assert/strict";
@@ -18,7 +18,7 @@ import { checkBanal, ensureBanal, measureGeometry } from "./run.ts";
 import { sha256Hex } from "../../domain/sha256.ts";
 import { installedBanal } from "./locate.ts";
 import { parseBanalSettings } from "./settings.ts";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath } from "../../domain/paths.ts";
 import type { Command, ProcessExit } from "../../ports/process.ts";
 
 const s = parseBanalSettings(
@@ -29,7 +29,7 @@ const noExplicit = parseBanalSettings(
   { PATH: "/bin" },
   { home: "/h", tmp: "/t", cwd: "/w" },
 );
-const project = "/p" as AbsolutePath;
+const project = absolutePath("/p");
 /** What banal prints for the one-page probe. */
 const MEASURED = '{"bodyfontsize": 10.3, "columns": 1, "pages": [{}]}';
 const banalAnswers = (e: ProcessExit) =>
@@ -45,10 +45,10 @@ test("measureGeometry: perl runs the found banal on the staged XML, and the geom
   });
   const g = measureGeometry(io, s, project, []);
   assert.equal(g.source, "banal");
-  assert.equal(g.source === "banal" && g.geometry.bodyPt, 10.3);
+  assert.equal(g.geometry.bodyPt, 10.3);
   const [c] = run.calls;
   assert.equal(c?.file, "perl");
-  assert.equal(c?.args.at(-1), "/scratch/paper.xml");
+  assert.equal(c.args.at(-1), "/scratch/paper.xml");
   // Guards: both files staged, once, and the scratch scope ended normally (cleanup ran).
   assert.deepEqual(
     workspace.written.map((w) => [w.name, w.mode]),

package/src/adapters/banal/run.ts

@@ -44,8 +44,6 @@ import {
   lookupOrder,
   pickBanal,
   type BanalCandidate,
-  type LocatedBanal,
-  type PinnedBanal,
 } from "./locate.ts";
 import {
   geometryOf,
@@ -89,11 +87,14 @@ export type BanalOutcome =
       readonly tried: BanalCandidate | null;
     };
 
-/** Run `banal` on `pages` in a scratch directory that is gone when this returns. */
+/**
+ * Run `banal` on `pages` in a scratch directory that is gone when this returns. It needs the path
+ * only: `measureGeometry` passes the banal `pickBanal` located, `probe` the one whose bytes it verified.
+ */
 function runBanal(
   d: BanalDeps,
   s: BanalSettings,
-  banal: LocatedBanal,
+  banal: Pick<BanalCandidate, "path">,
   pages: readonly PageLayout[],
 ): Result<BanalMeasurement, BanalFailure> {
   return d.workspace.within("paperlint-banal-", (scratch) =>
@@ -148,6 +149,15 @@ function perlRuns(d: BanalDeps, s: BanalSettings): boolean {
   return r.kind === "exited" && r.status === 0;
 }
 
+// Not exported: only `probe` below can write the property, so only it can make a PinnedBanal.
+const PINNED = Symbol("PinnedBanal");
+
+/**
+ * `paperlint toolchain`'s banal after its bytes hashed to the pin AND it measured the probe page. Minted by
+ * `probe` only, for `ensureBanal` / `checkBanal` (`./index.ts`): a "ready" line cannot be printed without one.
+ */
+export type PinnedBanal = BanalCandidate & { readonly [PINNED]: true };
+
 /**
  * Does the installed, pin-verified banal RUN — accepted by measuring the probe page, not by a
  * download's exit code. The one place a `PinnedBanal` is minted; callers verified the bytes first.
@@ -157,13 +167,9 @@ function probe(
   s: BanalSettings,
   path: AbsolutePath,
 ): Result<PinnedBanal, BanalFailure> {
-  const at: BanalCandidate = { path, provenance: { kind: "cache" } };
-  const r = andThen(
-    runBanal(d, s, at as LocatedBanal, [PROBE_PAGE]),
-    acceptProbe,
-  );
+  const r = andThen(runBanal(d, s, { path }, [PROBE_PAGE]), acceptProbe);
   return r.ok
-    ? ok(at as PinnedBanal)
+    ? ok({ path, provenance: { kind: "cache" }, [PINNED]: true })
     : err({ kind: "does-not-run", path, why: r.error });
 }
 

package/src/adapters/banal/settings.ts

@@ -9,7 +9,7 @@ import {
   type Environment,
   type HostDirs,
 } from "../../domain/host.ts";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath, type AbsolutePath } from "../../domain/paths.ts";
 
 /** An explicit banal to use instead of paperlint's (a path to the script). */
 export const BANAL_ENV = "BANAL";
@@ -29,7 +29,7 @@ export interface BanalSettings {
 
 /** `resolve` with an absolute base never consults the process's cwd. */
 const absolute = (cwd: string, p: string): AbsolutePath =>
-  resolve(cwd, p) as AbsolutePath;
+  absolutePath(resolve(cwd, p));
 
 /** An unset variable and an empty one mean the same: not set. */
 const set = (v: string | undefined): string | null => (v ? v : null);

package/src/adapters/banal/xml.test.ts

@@ -4,7 +4,7 @@
  *
  * Every page here is written by hand. The real-PDF half — pdf.js boxes of a committed fixture,
  * written as XML, measured by the real banal and compared with banal on real pdftohtml — is
- * `test/e2e/banal.mjs`, which runs where `paperlint toolchain` has installed banal.
+ * `test/e2e/banal.ts`, which runs where `paperlint toolchain` has installed banal.
  */
 import assert from "node:assert/strict";
 import { test } from "vitest";

package/src/adapters/curl/download.test.ts

@@ -15,16 +15,18 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { afterAll as after, test } from "vitest";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath, joinPath } from "../../domain/paths.ts";
 import { curlDownload, curlFailure } from "./download.io.ts";
 import type { ProcessExit } from "../../ports/process.ts";
 import { spawnProcess } from "../node/index.ts";
 
-const root = realpathSync(
-  mkdtempSync(join(tmpdir(), "paperlint-download-test-")),
+const root = absolutePath(
+  realpathSync(mkdtempSync(join(tmpdir(), "paperlint-download-test-"))),
 );
-after(() => rmSync(root, { recursive: true, force: true }));
-const at = (...p: string[]) => join(root, ...p) as AbsolutePath;
+after(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+const at = (...p: string[]) => joinPath(root, ...p);
 
 const dl = (env: Record<string, string>) => {
   const tmp = at("dl-tmp");
@@ -45,7 +47,7 @@ test("Download: a URL that does not answer is a failure with curl's words", () =
   const { d } = dl({ PATH: "/usr/bin:/bin" });
   const r = d.fetch(pathToFileURL(at("missing")).href, 10_000);
   assert.equal(r.ok, false);
-  assert.ok(!r.ok && r.error.detail.length > 0);
+  assert.ok(r.error.detail.length > 0);
 });
 
 test("🔴 Download: no curl on PATH is named as that, not as a failed URL", () => {

package/src/adapters/memory/index.ts

@@ -2,7 +2,7 @@
  * In-memory adapters for the app layer's tests: every port, no disk, no processes, no network.
  * Each one RECORDS what it was asked, so a test asserts on the calls instead of on side effects.
  */
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath } from "../../domain/paths.ts";
 import type { Download } from "../../ports/download.ts";
 import type { Files } from "../../ports/files.ts";
 import type { Command, ProcessExit, RunProcess } from "../../ports/process.ts";
@@ -69,11 +69,12 @@ export interface MemoryWorkspace extends Workspace {
 export function memoryWorkspace(dir = "/scratch"): MemoryWorkspace {
   const written: MemoryWorkspace["written"] = [];
   const ended: ("returned" | "threw")[] = [];
+  const at = absolutePath(dir);
   const scratch: Scratch = {
-    dir: dir as AbsolutePath,
+    dir: at,
     write(name, content, mode) {
       written.push({ name, content, mode });
-      return `${dir}/${name}` as AbsolutePath;
+      return absolutePath(`${dir}/${name}`);
     },
   };
   return {

package/src/adapters/node/files.io.ts

@@ -10,10 +10,10 @@ import {
 import { dirname } from "node:path";
 import type { AbsolutePath } from "../../domain/paths.ts";
 import type { Files } from "../../ports/files.ts";
+import { codeOf } from "../../domain/text.ts";
 
 /** An error's errno code; anything thrown that is not an Error has none. */
-export const errorCode = (e: unknown): unknown =>
-  e instanceof Error ? (e as NodeJS.ErrnoException).code : undefined;
+export const errorCode = (e: unknown): unknown => codeOf(e);
 
 export const nodeFiles: Files = {
   isFile(p: AbsolutePath): boolean {

package/src/adapters/node/files.test.ts

@@ -4,12 +4,16 @@ import { existsSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll as after, test } from "vitest";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath, joinPath } from "../../domain/paths.ts";
 import { errorCode, nodeFiles } from "./files.io.ts";
 
-const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-files-test-")));
-after(() => rmSync(root, { recursive: true, force: true }));
-const at = (...p: string[]) => join(root, ...p) as AbsolutePath;
+const root = absolutePath(
+  realpathSync(mkdtempSync(join(tmpdir(), "paperlint-files-test-"))),
+);
+after(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+const at = (...p: string[]) => joinPath(root, ...p);
 
 test("Files: a missing file reads as null and is not a file", () => {
   assert.equal(nodeFiles.readBytes(at("nope")), null);

package/src/adapters/node/process.io.ts

@@ -3,6 +3,7 @@
  * it — `error`, `status`, `signal`, all nullable — and turns it into a `ProcessExit`, so no caller
  * re-derives "what happened" from three fields.
  */
+import { codeOf, printed } from "../../domain/text.ts";
 import {
   spawnSync,
   type SpawnSyncOptionsWithStringEncoding,
@@ -10,17 +11,24 @@ import {
 } from "node:child_process";
 import type { Command, ProcessExit, RunProcess } from "../../ports/process.ts";
 
-/** Node's `spawnSync`, or a stand-in with its shape (a harness records the calls through one). */
-export type SpawnSync = typeof spawnSync;
+/**
+ * Node's `spawnSync` — the one overload this file calls, text in and text out — or a stand-in with its
+ * shape (a harness records the calls through one).
+ */
+export type SpawnSync = (
+  file: string,
+  args: readonly string[],
+  options: SpawnSyncOptionsWithStringEncoding,
+) => SpawnSyncReturns<string>;
 
 const errno = (r: SpawnSyncReturns<string>): string | undefined =>
-  (r.error as NodeJS.ErrnoException | undefined)?.code;
+  codeOf(r.error);
 
 /** What a finished `spawnSync` came to. ENOENT is the executable itself: `c.file` was not found. */
 export function exitOf(r: SpawnSyncReturns<string>, c: Command): ProcessExit {
   const out = {
-    stdout: String(r.stdout ?? ""),
-    stderr: String(r.stderr ?? ""),
+    stdout: printed(r.stdout),
+    stderr: printed(r.stderr),
   };
   const code = errno(r);
   if (code === "ENOENT") return { kind: "not-found", file: c.file };

package/src/adapters/node/process.test.ts

@@ -5,7 +5,7 @@
  */
 import assert from "node:assert/strict";
 import { test } from "vitest";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath } from "../../domain/paths.ts";
 import type { Command } from "../../ports/process.ts";
 import { spawnProcess } from "./process.io.ts";
 
@@ -58,23 +58,23 @@ test("a program killed by a signal is `signalled`, with what it printed first",
 test("output past maxOutputBytes is a spawn failure, named by Node's own message", () => {
   const r = run.run({ ...sh("head -c 100000 /dev/zero"), maxOutputBytes: 10 });
   assert.equal(r.kind, "spawn-failed");
-  assert.match(r.kind === "spawn-failed" ? r.message : "", /ENOBUFS/);
+  assert.match(r.message, /ENOBUFS/);
 });
 
 test("cwd is the Command's when it names one", () => {
-  const r = run.run({ ...sh("pwd"), cwd: "/" as AbsolutePath });
+  const r = run.run({ ...sh("pwd"), cwd: absolutePath("/") });
   assert.deepEqual(r.kind === "exited" && r.stdout, "/\n");
 });
 
 test("a spawn that reports no status, no signal and no error reads as exit 1, not success", () => {
-  const silent = spawnProcess((() => ({
+  const silent = spawnProcess(() => ({
     pid: 0,
     output: [],
     stdout: "",
     stderr: "",
     status: null,
     signal: null,
-  })) as never);
+  }));
   assert.deepEqual(silent.run(sh("true")), {
     kind: "exited",
     status: 1,

package/src/adapters/node/workspace.io.ts

@@ -10,14 +10,18 @@ import {
   writeFileSync,
 } from "node:fs";
 import { join } from "node:path";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import {
+  absolutePath,
+  joinPath,
+  type AbsolutePath,
+} from "../../domain/paths.ts";
 import type { NotAPromise, Scratch, Workspace } from "../../ports/workspace.ts";
 
 function scratchIn(dir: AbsolutePath): Scratch {
   return {
     dir,
     write(name, content, mode): AbsolutePath {
-      const at = join(dir, name) as AbsolutePath;
+      const at = joinPath(dir, name);
       writeFileSync(at, content);
       if (mode === "exec") chmodSync(at, 0o755);
       return at;
@@ -29,9 +33,10 @@ function scratchIn(dir: AbsolutePath): Scratch {
 export function tmpWorkspace(tmpDir: string): Workspace {
   return {
     within<T>(prefix: string, use: (s: Scratch) => NotAPromise<T>): T {
-      const dir = realpathSync(mkdtempSync(join(tmpDir, prefix)));
+      // `realpath` answers with an absolute path, whatever `tmpDir` was.
+      const dir = absolutePath(realpathSync(mkdtempSync(join(tmpDir, prefix))));
       try {
-        return use(scratchIn(dir as AbsolutePath));
+        return use(scratchIn(dir));
       } finally {
         rmSync(dir, { recursive: true, force: true });
       }