tape-six-proc 0.12.0

package/.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2

package/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "wiki"]
+	path = wiki
+	url = git@github.com:uhop/tape-six-proc.wiki

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "printWidth": 100,
+  "singleQuote": true,
+  "bracketSpacing": false,
+  "arrowParens": "avoid",
+  "trailingComma": "none"
+}

package/LICENSE

@@ -0,0 +1,11 @@
+Copyright 2005-2024 Eugene Lazutkin
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,27 @@
+# tape-six-proc [![NPM version][npm-img]][npm-url]
+
+[npm-img]:      https://img.shields.io/npm/v/tape-six-proc.svg
+[npm-url]:      https://npmjs.org/package/tape-six-proc
+
+`tape-six-proc` is a helper for [tape-six](https://www.npmjs.com/package/tape-six)
+to run tests in separate processes.
+
+## Docs
+
+The documentation can be found in the [wiki](https://github.com/uhop/tape-six-proc/wiki).
+`tape-six` has its own [wiki](https://github.com/uhop/tape-six/wiki).
+
+`tape-six-proc` uses the same test configuration as `tape-six`. The utility `test6-proc`
+has the same usage as `tape6`.
+
+### Command-line utilities
+
+* [tape6-proc](https://github.com/uhop/tape-six-proc/wiki/Utility-%E2%80%90-tape6-proc) — the main utility of this package to run tests in different environments.
+
+## Release notes
+
+The most recent releases:
+
+* 0.12.0 *Initial release.*
+
+For more info consult full [release notes](https://github.com/uhop/tape-six-proc/wiki/Release-notes).

package/bin/tape6-proc-node.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+
+'use strict';
+
+import process from 'node:process';
+import {fileURLToPath} from 'node:url';
+
+import {resolveTests, resolvePatterns} from 'tape-six/utils/config.js';
+
+import {getReporter, setReporter} from 'tape-six/test.js';
+import State, {StopTest} from 'tape-six/State.js';
+import TapReporter from 'tape-six/TapReporter.js';
+import {selectTimer} from 'tape-six/utils/timer.js';
+
+import TestWorker from '../src/TestWorker.js';
+
+const options = {},
+  rootFolder = process.cwd();
+
+let flags = '',
+  parallel = '',
+  runFileArgs = [],
+  files = [];
+
+const showSelf = () => {
+  const self = new URL(import.meta.url);
+  if (self.protocol === 'file:') {
+    console.log(fileURLToPath(self));
+  } else {
+    console.log(self);
+  }
+  process.exit(0);
+};
+
+const config = () => {
+  if (process.argv.includes('--self')) showSelf();
+
+  const optionNames = {
+    f: 'failureOnly',
+    t: 'showTime',
+    b: 'showBanner',
+    d: 'showData',
+    o: 'failOnce',
+    n: 'showAssertNumber',
+    c: 'hasColors'
+  };
+
+  let flagIsSet = false,
+    parIsSet = false;
+
+  for (let i = 2; i < process.argv.length; ++i) {
+    const arg = process.argv[i];
+    if (arg == '-f' || arg == '--flags') {
+      if (++i < process.argv.length) {
+        flags = process.argv[i];
+        flagIsSet = true;
+      }
+      continue;
+    }
+    if (arg == '-p' || arg == '--par') {
+      if (++i < process.argv.length) {
+        parallel = process.argv[i];
+        parIsSet = true;
+        if (!parallel || isNaN(parallel)) {
+          parallel = '';
+          parIsSet = false;
+        }
+      }
+      continue;
+    }
+    if (arg == '-r' || arg == '--runFileArgs') {
+      if (++i < process.argv.length) {
+        runFileArgs.push(process.argv[i]);
+      }
+      continue;
+    }
+    files.push(arg);
+  }
+
+  if (!flagIsSet) {
+    flags = process.env.TAPE6_FLAGS || flags;
+  }
+  for (let i = 0; i < flags.length; ++i) {
+    const option = flags[i].toLowerCase(),
+      name = optionNames[option];
+    if (typeof name == 'string') options[name] = option !== flags[i];
+  }
+
+  if (!parIsSet) {
+    parallel = process.env.TAPE6_PAR || parallel;
+  }
+  if (parallel) {
+    parallel = Math.max(0, +parallel);
+    if (parallel === Infinity) parallel = 0;
+  } else {
+    parallel = 0;
+  }
+  if (!parallel) parallel = navigator.hardwareConcurrency;
+
+  options.runFileArgs = runFileArgs;
+};
+
+const init = async () => {
+  let reporter = getReporter();
+  if (!reporter) {
+    if (process.env.TAPE6_JSONL) {
+      const JSONLReporter = (await import('tape-six/JSONLReporter.js')).default,
+        jsonlReporter = new JSONLReporter(options);
+      reporter = jsonlReporter.report.bind(jsonlReporter);
+    } else if (!process.env.TAPE6_TAP) {
+      const TTYReporter = (await import('tape-six/TTYReporter.js')).default,
+        ttyReporter = new TTYReporter(options);
+      ttyReporter.testCounter = -2;
+      ttyReporter.technicalDepth = 1;
+      reporter = ttyReporter.report.bind(ttyReporter);
+    }
+    if (!reporter) {
+      const tapReporter = new TapReporter({useJson: true});
+      reporter = tapReporter.report.bind(tapReporter);
+    }
+    setReporter(reporter);
+  }
+
+  if (files.length) {
+    files = await resolvePatterns(rootFolder, files);
+  } else {
+    let type = 'node';
+    if (typeof Deno == 'object') {
+      type = 'deno';
+    } else if (typeof Bun == 'object') {
+      type = 'bun';
+    }
+    files = await resolveTests(rootFolder, type);
+  }
+};
+
+const safeEmit = rootState => event => {
+  try {
+    rootState.emit(event);
+  } catch (error) {
+    if (!(error instanceof StopTest)) throw error;
+  }
+};
+
+const main = async () => {
+  config();
+  await init();
+  await selectTimer();
+
+  process.on('uncaughtException', (error, origin) =>
+    console.error('UNHANDLED ERROR:', origin, error)
+  );
+
+  const rootState = new State(null, {callback: getReporter(), failOnce: options.failOnce}),
+    worker = new TestWorker(safeEmit(rootState), parallel, options);
+
+  rootState.emit({type: 'test', test: 0, time: rootState.timer.now()});
+
+  await new Promise(resolve => {
+    worker.done = () => resolve();
+    worker.execute(files);
+  });
+
+  rootState.emit({
+    type: 'end',
+    test: 0,
+    time: rootState.timer.now(),
+    fail: rootState.failed > 0,
+    data: rootState
+  });
+
+  process.exit(rootState.failed > 0 ? 1 : 0);
+};
+
+main().catch(error => console.error('ERROR:', error));

package/bin/tape6-proc.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+import process from 'node:process';
+import {fileURLToPath} from 'node:url';
+
+if (process.argv.includes('--self')) {
+  const self = new URL(import.meta.url);
+  if (self.protocol === 'file:') {
+    console.log(fileURLToPath(self));
+  } else {
+    console.log(self);
+  }
+} else {
+  await import('./tape6-proc-node.js');
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "tape-six-proc",
+  "version": "0.12.0",
+  "description": "Helper for TAP the test harness for the modern JavaScript (ES6) to run tests in separate processes.",
+  "type": "module",
+  "bin": {
+    "tape6-proc": "bin/tape6-proc.js"
+  },
+  "keywords": [
+    "tap",
+    "test",
+    "harness",
+    "assert",
+    "process"
+  ],
+  "author": "Eugene Lazutkin <eugene.lazutkin@gmail.com> (https://www.lazutkin.com)",
+  "funding": "https://github.com/sponsors/uhop",
+  "license": "BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uhop/tape-six-proc.git"
+  },
+  "bugs": {
+    "url": "https://github.com/uhop/tape-six-proc/issues"
+  },
+  "homepage": "https://github.com/uhop/tape-six-proc#readme",
+  "dependencies": {
+    "dollar-shell": "^1.1.0",
+    "tape-six": "^1.0.1"
+  }
+}

package/src/TestWorker.js

@@ -0,0 +1,67 @@
+import process from 'node:process';
+import {sep} from 'node:path';
+import {pathToFileURL, fileURLToPath} from 'node:url';
+
+import {spawn, currentExecPath, runFileArgs} from 'dollar-shell';
+
+import {StopTest} from 'tape-six/State.js';
+import EventServer from 'tape-six/utils/EventServer.js';
+
+import lines from './chain/lines.js';
+import parse from './chain/jsonl-parse.js';
+
+const baseName = pathToFileURL(process.cwd() + sep);
+
+export default class TestWorker extends EventServer {
+  constructor(reporter, numberOfTasks = navigator.hardwareConcurrency, options) {
+    super(reporter, numberOfTasks, options);
+    this.counter = 0;
+    this.idToWorker = {};
+  }
+  makeTask(fileName) {
+    const testName = new URL(fileName, baseName),
+      id = String(++this.counter),
+      worker = spawn(
+        [
+          currentExecPath(),
+          ...runFileArgs.concat((this.options.runFileArgs || []).filter(x => x)),
+          fileURLToPath(testName)
+        ],
+        {
+          stdin: 'ignore',
+          stdout: 'pipe',
+          stderr: 'inherit',
+          env: {...process.env, TAPE6_TEST: id, TAPE6_JSONL: 'Y'}
+        }
+      );
+    this.idToWorker[id] = worker;
+    const self = this;
+    worker.stdout
+      .pipeThrough(new TextDecoderStream())
+      .pipeThrough(lines())
+      .pipeThrough(parse())
+      .pipeTo(
+        new WritableStream({
+          write(msg) {
+            try {
+              self.report(id, msg);
+            } catch (error) {
+              if (!(error instanceof StopTest)) throw error;
+            }
+            if (msg.type === 'end' && msg.test === 0) {
+              self.close(id);
+              return;
+            }
+          }
+        })
+      );
+    return id;
+  }
+  destroyTask(id) {
+    const worker = this.idToWorker[id];
+    if (worker) {
+      // worker.kill();
+      delete this.idToWorker[id];
+    }
+  }
+}

package/src/chain/jsonl-parse.js

@@ -0,0 +1,17 @@
+'use strict';
+
+export const parse = () =>
+  new TransformStream({
+    transform(line, controller) {
+      try {
+        const value = JSON.parse(line);
+        if (value && typeof value == 'object') {
+          controller.enqueue(value);
+        }
+      } catch (_) {
+        // squelch
+      }
+    }
+  });
+
+export default parse;

package/src/chain/lines.js

@@ -0,0 +1,21 @@
+'use strict';
+
+export const lines = () => {
+  let rest = '';
+  return new TransformStream({
+    transform(chunk, controller) {
+      const lines = chunk.split(/\r?\n/g);
+      rest += lines[0];
+      if (lines.length < 2) return;
+      lines[0] = rest;
+      rest = lines.pop();
+      for (const line of lines) controller.enqueue(line);
+    },
+    flush(controller) {
+      controller.enqueue(rest);
+      rest = '';
+    }
+  });
+};
+
+export default lines;

package/wiki/Home.md

@@ -0,0 +1,29 @@
+<!-- markdownlint-disable-next-line first-line-heading -->
+`tape-six-proc` is a helper for [tape-six](https://www.npmjs.com/package/tape-six)
+to run tests in separate processes.
+
+Please consult the [tape-six wiki](https://github.com/uhop/tape-six/wiki) for more information.
+
+# How to use
+
+1. Install `tape-six-proc` in your project: `npm i -D tape-six-proc`.
+2. Write tests.
+3. Configure your tests: [set-up tests](https://github.com/uhop/tape-six/wiki/Set-up-tests).
+4. Run tests: `npm test`.
+
+# Available utilities
+
+Test files are directly executable with `node` or `deno` or `bun` or in a browser.
+[tape-six](https://www.npmjs.com/package/tape-six) helps to organize tests. This package
+provides a utility to run tests in isolated processes:
+
+* [tape6-proc](./Utility-‐-tape6‐proc) to run tests in separate processes.
+
+# Formalities
+
+The project is distributed under the 3-clause BSD license.
+
+Other pertinent information:
+
+* [Release notes](./Release-notes).
+* [Working on this project](./Working-on-this-project).

package/wiki/Release-notes.md

@@ -0,0 +1,3 @@
+# The current version: 0.12.x
+
+* 0.12.0 *Initial release.*

package/wiki/Utility-/342/200/220-tape6/342/200/220proc.md

@@ -0,0 +1,65 @@
+<!-- markdownlint-disable-next-line first-line-heading -->
+The main utility of the package is `tape6-proc`.
+
+# Usage
+
+Assuming that the tests are properly configured
+(see [Set-up tests](https://github.com/uhop/tape-six/wiki/Set-up-tests)),
+it can be invoked without arguments:
+
+```bash
+npx tape6-proc
+```
+
+`tape6-proc` is modelled after [tape6](https://github.com/uhop/tape-six/wiki/Utility-%E2%80%90-tape6)
+and can be used the same way.
+
+# Configuring `tape6-proc`
+
+`tape6-proc` supports the same configuration as
+[tape6](https://github.com/uhop/tape-six/wiki/Utility-%E2%80%90-tape6).
+
+Additionally it supports the following flags:
+
+* `--runFileArgs ARGS` &mdash; sets the arguments to pass to the test file.
+  * Shortcut: `-r ARGS`.
+  * This flag can be used multiple times.
+
+This flag is used mostly with Deno to supply additional arguments to the test file.
+
+For example, we want to add `-A` (`--allow-all` permissions) to run a test file:
+
+```bash
+deno run -A `npx tape6-proc --self` --runFileArgs -A
+```
+
+# Implementation details
+
+Technically, `tape6-proc` is an executable command-line utility, which is set to be executed with
+the current Node. If you want to use it in different environments, you can use the `--self` flag:
+
+Example of `package.json`:
+
+```jsonc
+{
+  "scripts": {
+    "test": "tape6-proc --flags FO",
+    "test:node": "tape6-proc --flags FO",
+    "test:bun": "bun run `npx tape6-proc --self` --flags FO",
+    "test:deno": "deno run -A `npx tape6-proc --self` --flags FO --runFileArgs -A"
+  }
+}
+```
+
+With scripts like above you can test your project in different environments:
+
+```bash
+npm test
+npm run test:bun
+npm run test:deno
+```
+
+## Test environment
+
+All environments spawn child processes to run tests using
+[dollar-shell](https://www.npmjs.com/package/dollar-shell).

package/wiki/Working-on-this-project.md

@@ -0,0 +1,22 @@
+<!-- markdownlint-disable-next-line first-line-heading -->
+This project uses git submodules, so the correct way to get it is:
+
+```bash
+git clone --recursive git@github.com:uhop/tape-six-proc.git
+cd tape-six-proc
+```
+
+For older versions of `git`:
+
+```bash
+git clone git@github.com:uhop/tape-six-proc.git
+cd tape-six-proc
+git submodule update --init --recursive
+```
+
+Don't forget to install dependencies and run a build:
+
+```bash
+npm install
+npm run build
+```