tape-six-proc

Imported from uhop/tape-six-proc (AGENTS.md). Install upstream with npx skills add uhop/tape-six-proc. Copyright stays with the author.

AGENTS.md — tape-six-proc

tape-six-proc is a helper for tape-six that runs test files in separate processes (subprocesses) instead of worker threads. It works with Node, Deno, and Bun, and supports TypeScript natively without transpilation. The npm package name is tape-six-proc and the CLI command is tape6-proc.

Setup

This project uses a git submodule (wiki):

git clone --recursive https://github.com/uhop/tape-six-proc.git
cd tape-six-proc
npm install

There is no build step.

Commands

• Install: npm install
• Test (Node): npm test (runs tape6-proc --flags FO)
• Test (Bun): npm run test:bun
• Test (Deno): npm run test:deno
• Lint: npm run lint (Prettier check)
• Lint fix: npm run lint:fix (Prettier write)
• JS-check: npm run js-check (TypeScript-as-linter via tsconfig.check.json — checks .js sources for unused vars / undeclared refs)

Project structure

tape-six-proc/
├── package.json          # Package config; "tape6" section configures test discovery
├── tsconfig.check.json   # js-check config (TypeScript as linter for .js sources)
├── bin/
│   ├── tape6-proc.js     # CLI entry point (--self flag or delegates to tape6-proc-node.js)
│   └── tape6-proc-node.js # Main CLI: delegates to tape-six config utilities, runs TestWorker
├── src/                  # each module is a .js + .d.ts sidecar pair (types + JSDoc live in the .d.ts)
│   ├── TestWorker.js     # TestWorker class: spawns child processes, pipes stdout/stderr
│   └── streams/
│       ├── lines.js              # TransformStream: splits text into lines
│       ├── parse-prefixed-jsonl.js # TransformStream: parses prefixed JSONL from stdout
│       └── wrap-lines.js         # TransformStream: wraps plain lines as {type, name} objects
├── tests/                # Test files (test-*.js)
│   └── manual/           # Manual test files (hand-runnable demos; `tests/manual/test-chai.js` requires user-installed chai)
├── wiki/                 # GitHub wiki documentation (submodule)
├── .github/
│   ├── workflows/        # CI: separate jobs for Node × {ubuntu, windows, macOS} × {22, 24, 26}, Bun × OS, Deno × OS
│   └── dependabot.yml    # Tuned: grouped updates + `versioning-strategy: increase-if-necessary` (PRs only on out-of-range bumps)
├── ARCHITECTURE.md       # Internal layout & control flow (authoring-side doc)
├── README.md
└── LICENSE

Code style

• ES modules throughout ("type": "module" in package.json).
• No transpilation — code runs directly in all target runtimes. TypeScript test files (.ts) are also supported natively by modern Node, Deno, and Bun.
• Typed via .d.ts sidecars — every src/ module is a .js + .d.ts pair. The .d.ts carries the types and JSDoc as the sole source of truth (.js files carry no JSDoc); each .js starts with a // @ts-self-types="./<name>.d.ts" directive (honored by Deno; TypeScript resolves sidecars by adjacency). A new src/ module needs both files. package.json#types points at src/TestWorker.d.ts.
• Prettier for formatting (see .prettierrc).
• Semicolons — default Prettier behavior (see .prettierrc).
• Imports at the top of files, using import syntax.
• The package name is tape-six-proc but the CLI command is tape6-proc.

Architecture

• bin/tape6-proc.js is the CLI entry point. With --self it prints its own path (for cross-runtime usage). Otherwise it delegates to bin/tape6-proc-node.js.
• bin/tape6-proc-node.js delegates argument parsing, reporter setup, and file resolution to tape-six/utils/config.js (getOptions, initReporter, initFiles, showInfo). It adds --runFileArgs (-r), --info, --help (-h), and --version (-v) options, then runs tests via TestWorker.
• TestWorker (in src/TestWorker.js) extends EventServer from tape-six. It spawns each test file as a child process using dollar-shell, pipes stdout through a JSONL parser, pipes stderr as wrapped lines, and drives a stdin control channel.
• Each spawned process gets environment variables: TAPE6_FLAGS, TAPE6_TEST, TAPE6_TEST_FILE_NAME, TAPE6_JSONL=Y, TAPE6_JSONL_PREFIX (a UUID prefix for JSONL lines), TAPE6_CONTROL=Y (marks a controlled child), and TAPE6_GRACE_TIMEOUT (the drain budget).
• Stream pipeline per process: stdout → TextDecoder → lines → parse-prefixed-jsonl → report. stderr: stderr → TextDecoder → lines → wrap-lines → report. stdin carries the control plane (see below).
• Worker control channel. The child is spawned with stdin: 'pipe'. To stop a worker the parent writes a line-delimited terminate command and EOFs stdin; the child (the tape-six runtime, which opens the channel when TAPE6_CONTROL is set) drains a running test through reporter.terminate() — its t.signal fires and cleanup hooks run — then exits. This makes failOnce (flag O) actually stop in-flight workers (not just stop scheduling new files), and enables a per-worker wall-clock deadline (TAPE6_WORKER_TIMEOUT). Completion is keyed off reading the child's top-level end, not racing the child's own exit — which also fixes the Bun stdout-flush bug, since the child now exits parent-driven after end has been consumed. A child that won't drain within TAPE6_GRACE_TIMEOUT (default 5000 ms) is force-killed (SIGTERM); a premature exit with no end is still reported as an error. The child-side listener lives in tape-six itself (src/utils/control-channel.js), so this requires a tape-six that ships it.

Dependencies

• tape-six — the core test library. tape-six-proc imports: utils/config.js (getOptions, initFiles, initReporter, showInfo, printFlagOptions), test.js, utils/timer.js, State.js, utils/EventServer.js, utils/makeDeferred.js. The worker control channel also relies on tape-six's child-side listener (src/utils/control-channel.js, opened via TAPE6_CONTROL) and its getGraceTimeout / getWorkerTimeout config — so it needs a tape-six version that ships them.
• dollar-shell — cross-runtime process spawning (spawn, currentExecPath, runFileArgs).

Writing tests

Tests are standard tape-six tests. They are run in isolated processes by tape6-proc:

import test from 'tape-six';

test('example', t => {
  t.ok(true, 'truthy');
  t.equal(1 + 1, 2, 'math works');
});

• Test files should be directly executable: node tests/test-foo.js or node tests/test-foo.ts
• Test file naming convention: test-*.js, test-*.mjs, test-*.cjs, test-*.ts
• Tests are configured in package.json under the "tape6" section (same as tape-six).

Key conventions

• Do not add dependencies unless absolutely necessary.
• Do not modify or delete test expectations without understanding why they changed.
• No comments that narrate the code. Don't write a comment that restates what the code does. Allowed, each as the shortest possible marker: JSDoc when requested or required; a reference for a non-trivial algorithm; a non-trivial decision or constraint — why it's this way, including footgun/ordering caveats that have a real reason. The bar is why, never what. Strip narrating comments opportunistically in files you're already editing.
• The --self flag prints the path to tape6-proc.js for use in cross-runtime scripts (Bun, Deno).
• The --runFileArgs (-r) flag passes extra arguments to the spawned interpreter (mainly for Deno permissions).
• Wiki documentation lives in the wiki/ submodule.
• Environment variables use the TAPE6_ prefix (shared with tape-six). The control-channel tunables are TAPE6_GRACE_TIMEOUT (drain budget before force-kill, default 5000 ms) and TAPE6_WORKER_TIMEOUT (per-worker wall-clock deadline, default 0 = off); both are resolved by tape-six's config.js and inherited here via getOptions.
• Configuration is read from tape6.json or the "tape6" section of package.json (same as tape-six). Per-runtime subsections (tape6.node / tape6.bun / tape6.deno / tape6.cli / tape6.browser) are auto-resolved via tape-six's runtime.name detection — pin a test file to a specific runtime by globbing it under that key.
• BYO assertion / mock libraries. No third-party assertion lib ships as a devDep. CI smoke-tests for the AssertionError rendering path use node:assert (tests/test-assert.js). tests/manual/test-chai.js is retained as a hand-runnable visual demo for users who want to see chai integration; users npm install chai ad-hoc when exercising it.
• js-check tooling: tsconfig.check.json runs TypeScript-as-linter (checkJs + noUnusedLocals + noUnusedParameters) over .js sources in bin/ and src/; the .d.ts sidecars join the same program via import adjacency, so they are validated too. tape-six's EventServerOptions pass-through bags are any-indexed (since 1.14.1), so the keys the worker reads (flags, runFileArgs) type-check without a local augmentation and TestWorker.js stays cast-free under checkJs. Pure-Node-API only on the source side (@types/node is the only types entry); cross-runtime concerns are absorbed by the dollar-shell dependency and don't require @types/bun / @types/deno here.
• Dependabot is tuned to skip PRs when a new version satisfies the declared caret range (only major bumps fire) and to bundle all matching updates per ecosystem into one PR per cycle. Security advisories are a separate, always-on channel and continue to fire regardless.