unexpectedly 1.0.0 → 3.0.3

package/README.md

@@ -11,13 +11,20 @@ npm install -g unexpectedly
 ## Usage
 
 ```
-unexpectedly [--defaultScript jsPattern] <...file|directory>
-  jsPattern (default: "../$<base>.js"): find the JS file relative to
-    the .tests file, replacing `$<base>` with the basename of the test file.
-    This may be specified multiple times, and modifies all files/directories
-    after.
-  file: a file that contains tests
-  directory (default: "."): a directory containing ".tests" files
+Usage: unexpectedly [options] [...file]
+
+Arguments:
+  ...file                           Files or directories to test (default:
+                                    "./test/")
+
+Options:
+  -V, --version                     output the version number
+  -d,--defaultScript <replacement>  Find the script from the file name.
+                                    Replace `$<base>` with the basename of the
+                                    file. (default: "../$<base>.js")
+  -f,--function <functionName>      Use this function for testing in the
+                                    associated script (default: "test")
+  -h, --help                        display help for command
 ```
 
 ## Example
@@ -63,8 +70,10 @@ unexpectedly tests/
 ```js
 import {suite} from 'unexpectedly';
 
-// returns a Promise
-suite(directoryOrFile, jsPattern).catch(console.error)
+await suite(directoryOrFile, {
+  defaultScript: '../$<base>.js',
+  function: 'test',
+}).catch(console.error)
 ```
 
 ## Test language
@@ -101,6 +110,9 @@ Special globals include:
    instead of the default
  - "timeout": If any test in the file takes longer than this (in ms),
    it fails.  Default: 2000
+ - "peggy": Treat the input as a compiled peggy grammar; look for a "parse"
+   function in the input script, provide better errors, and use the value
+   of the peggy global (if any) as the startRule.
 
 Environment variables can be set for the test code with `#!! name: value`.
 

package/bin/unexpectedly.js

@@ -1,23 +1,28 @@
 #!/usr/bin/env -S node --experimental-vm-modules --no-warnings
-/* eslint-disable no-console */
-
+import {Command} from 'commander';
 import {suite} from '../index.js';
+import {version} from '../version.js';
 
 let failures = 0;
 
 async function main() {
-  let defaultScript = undefined;
-  let nextDefault = false;
-  for (const arg of process.argv.slice(2)) {
-    if (nextDefault) {
-      defaultScript = arg;
-      nextDefault = false;
-    } else if (arg === '--defaultScript') {
-      nextDefault = true;
-    } else {
-      // eslint-disable-next-line require-atomic-updates
-      failures += await suite(arg, defaultScript);
-    }
+  const program = new Command();
+  const opts = program
+    .version(version)
+    .argument('[file...]', 'Files or directories to test', './test/')
+    .option('-d,--defaultScript <replacement>', 'Find the script from the file name.  Replace `$<base>` with the basename of the file.', '../$<base>.js')
+    .option('-f,--function <functionName>', 'Use this function for testing in the associated script', 'test')
+    .parse()
+    .opts();
+
+  const {args} = program;
+  if (args.length === 0) {
+    args.push('./test/');
+  }
+
+  for (const arg of args) {
+    // eslint-disable-next-line require-atomic-updates
+    failures += await suite(arg, opts);
   }
 }
 

package/eslint.config.js

@@ -0,0 +1,26 @@
+import base from '@cto.af/eslint-config';
+import mocha from '@cto.af/eslint-config/mocha.js';
+import mod from '@cto.af/eslint-config/module.js';
+
+export default [
+  {
+    ignores: [
+      'docs/**',
+      'coverage/**',
+      '**/*.peg.js',
+      '**/*.d.ts',
+      'test/pkg_bad/package.json',
+    ],
+  },
+  ...base,
+  ...mod,
+  ...mocha,
+  {
+    files: [
+      'test/**/*.js',
+    ],
+    rules: {
+      'n/no-top-level-await': 'off',
+    },
+  },
+];

package/index.js

@@ -1,6 +1,6 @@
+import {Runner, SKIPPED} from './runner.js';
 import {hexlify, mapObj} from './utils.js';
 import Mocha from 'mocha';
-import {Runner} from './runner.js';
 import assert from 'node:assert';
 import fs from 'node:fs/promises';
 import {parse} from './testFile.peg.js';
@@ -13,6 +13,9 @@ async function coerce(actual, pt, runner) {
   if (typeof actual === 'string') {
     return [actual, expected];
   }
+  if (actual === SKIPPED) {
+    return [SKIPPED, SKIPPED];
+  }
   if (actual && (typeof actual === 'object') && actual.constructor) {
     if (/^0x/.test(expected)) {
       const {name} = actual.constructor;
@@ -42,18 +45,30 @@ async function coerce(actual, pt, runner) {
   return [actual, def];
 }
 
+/**
+ * @typedef {object} SuiteOptions
+ * @property {string} [defaultScript='../$<base>.js'] Find the script from the
+ *   file name.  Replace `$<base>` with the basename of the file.  For
+ *   example, "foo.test" will use "../foo.js" by default.
+ * @property {string} [function='test'] Use this function for testing in the
+ *   associated script.
+ */
+
 /**
  * Run a test suite from a file or directory.
  *
  * @param {string} [target='.'] The file or directory to read.  If a
  *   directory, reads all files ending in `.tests`.
- * @param {string} [defaultScript='../$<base>.js'] Find the script from the
- *   file name.  Replace $1 with the basename of the file.  For example,
- *   "foo.test" will use "../foo.js" by default.
+ * @param {SuiteOptions} [options={}] Options for processing the suite.
  * @returns {Promise<number>} Promise fulfills on completion, with number of
  *   test failures.
  */
-export async function suite(target = '.', defaultScript = '../$<base>.js') {
+export async function suite(target = '.', options = {}) {
+  options = {
+    defaultScript: '../$<base>.js',
+    function: 'test',
+    ...options,
+  };
   let dir = path.resolve(target);
   let files = [dir];
   const mocha = new Mocha();
@@ -90,42 +105,61 @@ export async function suite(target = '.', defaultScript = '../$<base>.js') {
       throw er;
     }
 
-    const opts = {};
-    let text = '';
-    if (parsed.vars.inline) {
-      opts.filename = f;
-      text = parsed.vars.inline.value;
-      opts.lineOffset = parsed.vars.inline.line - 1;
-      opts.columnOffset = parsed.vars.inline.column;
-    } else {
-      opts.filename = parsed.vars.script ?
-        path.resolve(dir, parsed.vars.script.value) :
-        path.resolve(dir, f.replace(/(?<base>[^./]*)\.tests?$/, defaultScript));
-      text = await fs.readFile(opts.filename, 'utf8');
-    }
-    if (parsed.vars.timeout) {
-      msuite.timeout(parseInt(parsed.vars.timeout.value, 10));
-    }
-    opts.sandbox = mapObj(
-      Object.entries(parsed.vars).filter(([k, v]) => !v.env),
-      ([key, value]) => [key, value.value]
-    );
-    opts.env = mapObj(
-      Object.entries(parsed.vars).filter(([k, v]) => v.env),
-      ([key, value]) => [key, value.value]
-    );
-    const runner = new Runner(opts);
+    for (const pt of parsed) {
+      const opts = {
+        testFunction: options.function,
+      };
+      let text = '';
+      if (pt.vars.inline) {
+        opts.filename = f;
+        text = pt.vars.inline.value;
+        opts.lineOffset = pt.vars.inline.line - 1;
+        opts.columnOffset = pt.vars.inline.column;
+      } else {
+        if (pt.vars.script) {
+          opts.filename = path.resolve(dir, pt.vars.script.value);
+        } else {
+          // Avoid a previous ReDOS regexp.
+          const p = path.parse(f);
+          if (/^\.tests?$/.test(p.ext)) {
+            delete p.base;
+            delete p.ext;
+            p.name = p.name.replace(/^(?<base>.*)$/, options.defaultScript);
+            opts.filename = path.resolve(dir, path.format(p));
+          } else {
+            opts.filename = path.resolve(dir, f);
+          }
+        }
+        text = await fs.readFile(opts.filename, 'utf8');
+      }
+      if (pt.vars.timeout) {
+        msuite.timeout(parseInt(pt.vars.timeout.value, 10));
+      }
+      opts.context = mapObj(
+        Object.entries(pt.vars).filter(([_k, v]) => !v.env),
+        ([key, value]) => [key, value.value]
+      );
+      opts.env = mapObj(
+        Object.entries(pt.vars).filter(([_k, v]) => v.env),
+        ([key, value]) => [key, value.value]
+      );
 
-    for (const pt of parsed.tests) {
-      const firstLine = (pt.expected === EXCEPTION) ? '!' : pt.expected.split(/\n/)[0];
-      const t = new Mocha.Test(`line ${pt.line}: ${firstLine || '""'}`, async() => {
+      const runner = new Runner(opts);
+
+      const firstLine = (pt.expected === EXCEPTION) ? `! ${pt.inputs[0]}` : pt.expected.split(/\n/)[0];
+      const t = new Mocha.Test(`line ${pt.line}: ${firstLine || '""'}`, async () => {
         let actual = null;
         try {
           actual = await runner.run(text, {
             __expected: pt.expected,
             __line: pt.line,
             __column: pt.column,
+            __offset: pt.offset,
           }, ...pt.inputs);
+          if (actual === SKIPPED) {
+            t.skip('Node 20.8 required');
+            return;
+          }
         } catch (e) {
           if (pt.expected !== EXCEPTION) {
             throw e;
@@ -135,11 +169,12 @@ export async function suite(target = '.', defaultScript = '../$<base>.js') {
         assert.notStrictEqual(pt.expected, EXCEPTION);
         assert.deepEqual.apply(null, await coerce(actual, pt, runner));
       });
+
       msuite.addTest(t);
     }
   }
 
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve, _reject) => {
     mocha.run(resolve);
   });
 }

package/package.json

@@ -1,18 +1,9 @@
 {
   "name": "unexpectedly",
-  "version": "1.0.0",
+  "version": "3.0.3",
   "description": "Keep a bunch of test cases in a file, with their expected results",
   "main": "index.js",
   "type": "module",
-  "scripts": {
-    "build": "peggy -o testFile.peg.js --format es testFile.pegjs",
-    "pretest": "npm run build",
-    "test": "c8 npm run runtests",
-    "runtests": "mocha && bin/unexpectedly.js test test/pkg_mjs/test test/pkg_cjs/test",
-    "lint": "eslint --ext js,cjs,mjs . bin/*",
-    "ci": "npm run lint && npm run test",
-    "clean": "rimraf coverage testFile.peg.js"
-  },
   "bin": {
     "unexpectedly": "bin/unexpectedly.js"
   },
@@ -32,24 +23,11 @@
   },
   "license": "MPL-2.0",
   "dependencies": {
-    "mocha": "^10.2.0"
-  },
-  "devDependencies": {
-    "@cto.af/eslint-config": "3.0.2",
-    "c8": "8.0.1",
-    "eslint": "^8.54.0",
-    "eslint-config-standard": "^17.1.0",
-    "eslint-plugin-import": "^2.29.0",
-    "eslint-plugin-jsdoc": "46.9.0",
-    "eslint-plugin-n": "16.3.1",
-    "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-promise": "^6.1.1",
-    "eslint-plugin-standard": "^4.1.0",
-    "peggy": "^3.0.2",
-    "rimraf": "5.0.5",
-    "zx": "7.2.3"
+    "@peggyjs/from-mem": "3.1.1",
+    "commander": "14.0.0",
+    "mocha": "^11.7.1"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   }
 }

package/runner.js

@@ -1,38 +1,16 @@
-import {ModType} from './modtype.js';
-import {createRequire} from 'node:module';
-import {mapObj} from './utils.js';
+import GrammarLocation from './vendor/peggy/grammar-location.cjs';
+import fromMem from '@peggyjs/from-mem';
 import path from 'node:path';
-import vm from 'node:vm';
 
-const vmGlobals = new vm.Script('Object.getOwnPropertyNames(globalThis)')
-  .runInNewContext()
-  .filter(f => !f.startsWith('global'));
-vmGlobals.push('process', 'Buffer');
+const PREFIX_MJS = 'export default ';
+const PREFIX_CJS = 'module.exports = ';
+const PREFIX_MJS_LEN = PREFIX_MJS.length;
+const PREFIX_CJS_LEN = PREFIX_CJS.length;
 
-async function linker(specifier, referencingModule, cache) {
-  // Note: not convinced the cache actually does anything, due to timing.
-  if (cache?.has(specifier)) {
-    return cache.get(specifier);
-  }
-  const m = await import(specifier);
-  const exportNames = Object.keys(m);
-  const imported = new vm.SyntheticModule(
-    exportNames,
-    // eslint-disable-next-line func-names
-    function() {
-      // eslint-disable-next-line no-invalid-this
-      exportNames.forEach(key => this.setExport(key, m[key]));
-    },
-    {identifier: specifier, context: referencingModule.context}
-  );
-
-  cache?.set(specifier, imported);
-  return imported;
-}
+export const SKIPPED = Symbol('SKIPPED');
 
 /**
- * Fancy "eval".  This is NOT for adding security, even though we're using
- * node:vm.  This is about providing:
+ * Fancy "eval".  This is NOT for adding security. This is about providing:
  *
  * - Good backtraces with file/line/column information correct, even when the
  *   code was inlined into a test.
@@ -42,111 +20,122 @@ async function linker(specifier, referencingModule, cache) {
  */
 export class Runner {
   #columnOffset;
+  #context;
   #dirname;
   #env;
   #filename;
   #lineOffset;
-  #sandbox;
+  #testFunction;
   #type;
+  #skipped;
 
   constructor({
-    filename = null, // Resolved
+    filename = null, // Fully-qualified
     lineOffset = 0,
     columnOffset = 0,
-    sandbox = null,
+    context = {},
     env = {},
-    type = null,
+    testFunction = 'test',
+    type = 'guess',
   } = {}) {
+    if (typeof filename !== 'string') {
+      throw new TypeError('filename not specified');
+    }
     this.#filename = filename;
     this.#dirname = path.dirname(filename);
     this.#env = env;
-    this.#sandbox = sandbox;
+    this.#context = context;
     this.#columnOffset = columnOffset;
     this.#lineOffset = lineOffset;
+    this.#skipped = null;
     this.#type = type;
+    this.#testFunction = testFunction;
+  }
+
+  get skipped() {
+    return this.#skipped;
   }
 
   async parse(text, extra = {}) {
-    if (!this.#type) {
-      this.#type = await ModType.find(this.#filename);
+    const format = this.#type === 'guess' ?
+      await fromMem.guessModuleType(this.#filename) :
+      this.#type;
+
+    let columnOffset = this.#columnOffset;
+    if (format === 'es') {
+      if (text.indexOf('export') === -1) {
+        text = PREFIX_MJS + text; // Most common case
+        columnOffset -= PREFIX_MJS_LEN;
+      }
+    } else if (text.indexOf('exports') === -1) {
+      text = PREFIX_CJS + text; // Most common case
+      columnOffset -= PREFIX_CJS_LEN;
     }
-    // Find package.json relative to test, decide whether we're commonjs or
-    // module.
-    const exports = {};
-    const context = {
-      ...mapObj(vmGlobals, g => (
-        (typeof globalThis[g] === 'function') ?
-          globalThis[g] :
-          {...globalThis[g]}
-      )),
-      require: createRequire(this.#filename),
-      exports,
-      module: {
-        exports,
+
+    return await fromMem(text, {
+      filename: this.#filename,
+      format,
+      env: this.#env,
+      lineOffset: this.#lineOffset,
+      columnOffset,
+      context: {
         filename: this.#filename,
         id: this.#filename,
         path: this.#dirname,
+        ...this.#context,
+        ...extra,
       },
-      __filename: this.#filename,
-      __dirname: this.#dirname,
-      ...this.#sandbox,
-      ...extra,
-    };
-    context.process.env = this.#env;
-    context.global = context;
-    context.globalThis = context;
-    vm.createContext(context);
+    });
+  }
 
-    let f = null;
-    const imports = new Map();
+  async run(text, extra = {}, ...params) {
+    let f = await this.parse(text, extra);
+    if (f === SKIPPED) {
+      return f;
+    }
 
-    if (this.#type === 'module') {
-      if (text.indexOf('export') === -1) {
-        text = `export default ${text}`; // Most common case
-      }
+    const possibleFunctions = [
+      this.#context.function,
+      this.#testFunction,
+      'default',
+    ];
 
-      const mod = new vm.SourceTextModule(text, {
-        context,
-        id: this.#filename,
-        lineOffset: this.#lineOffset,
-        columnOffset: this.#columnOffset,
+    let source = null;
+    if ('peggy' in this.#context) {
+      source = new GrammarLocation(this.#filename, {
+        line: extra.__line,
+        column: extra.__column,
+        offset: extra.__offset,
       });
+      const popts = {
+        grammarSource: source,
+      };
+      if (this.#context.peggy?.length > 0) {
+        popts.startRule = this.#context.peggy;
+      }
+      params[1] = popts;
+      possibleFunctions.splice(1, 0, 'parse');
+    }
 
-      await mod.link((specifier, referencingModule) => {
-        if (path.isAbsolute(specifier) || !/^\.\.?\//.test(specifier)) {
-          return linker(specifier, referencingModule, imports);
+    if (f && (typeof f !== 'function')) {
+      for (const possible of possibleFunctions) {
+        if (possible && (typeof f[possible] === 'function')) {
+          f = f[possible];
+          break;
         }
-        return linker(
-          path.resolve(path.dirname(this.#filename), specifier),
-          referencingModule,
-          imports
-        );
-      });
-      await mod.evaluate();
-      f = mod.namespace;
-    } else {
-      if (text.indexOf('exports') === -1) {
-        text = `module.exports= ${text}`; // Most common case
       }
-
-      const script = new vm.Script(text, {
-        filename: this.#filename,
-        lineOffset: this.#lineOffset,
-        columnOffset: this.#columnOffset,
-      });
-      f = script.runInContext(context);
     }
-    return f;
-  }
-
-  async run(text, extra = {}, ...params) {
-    let f = await this.parse(text, extra);
     if (typeof f !== 'function') {
-      f = f?.test ?? f?.default;
-      if (typeof f !== 'function') {
-        throw new Error('Must export function or {test}');
+      throw new Error('Must export function or {test}');
+    }
+
+    try {
+      return f(...params);
+    } catch (er) {
+      if (source && (typeof er.format === 'function')) {
+        er.message = er.format([{source, text: params[0]}]);
       }
+      throw er;
     }
-    return f(...params);
   }
 }