readme-assert 6.0.3 → 7.0.0

package/src/run.js

@@ -0,0 +1,268 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { extractBlocks } from "./extract.js";
+import { generate } from "./generate.js";
+import { commentToAssert } from "./comment-to-assert.js";
+
+const tmpFiles = new Set();
+
+function cleanupTmpFiles() {
+  for (const f of tmpFiles) {
+    try { fs.unlinkSync(f); } catch {}
+  }
+  tmpFiles.clear();
+}
+
+process.on("exit", cleanupTmpFiles);
+
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.once(signal, () => {
+    cleanupTmpFiles();
+    process.kill(process.pid, signal);
+  });
+}
+
+/**
+ * Process a markdown file into executable code units.
+ *
+ * @param {string} filePath
+ * @param {{ auto?: boolean, all?: boolean, main?: string }} options
+ * @returns {Promise<Array<{ code: string, name: string }>>}
+ */
+export async function processMarkdown(filePath, options = {}) {
+  const markdown = fs.readFileSync(filePath, "utf-8");
+  const extracted = extractBlocks(markdown, {
+    auto: options.auto,
+    all: options.all,
+  });
+
+  if (extracted.blocks.length === 0) {
+    throw new Error("README has no test code blocks");
+  }
+
+  const { units } = generate(extracted);
+
+  // Resolve package info for import renaming
+  let packageName, localPath;
+  const pkgPath = findPackageJson(path.dirname(filePath));
+  if (pkgPath) {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    if (pkg.name) {
+      const mainEntry = options.main || pkg.main || pkg.exports?.["."] || "./index.js";
+      packageName = pkg.name;
+      localPath = path.resolve(path.dirname(pkgPath), mainEntry);
+    }
+  }
+
+  const results = [];
+  for (const unit of units) {
+    let code = unit.code;
+
+    if (packageName) {
+      code = renameImports(code, packageName, localPath);
+    }
+
+    const transformed = commentToAssert(code, {
+      filename: filePath,
+      typescript: unit.hasTypescript,
+    });
+    code = transformed.code;
+
+    if (unit.hasTypescript) {
+      const esbuild = await import("esbuild");
+      const result = await esbuild.transform(code, {
+        loader: "ts",
+        sourcemap: false,
+      });
+      code = result.code;
+    }
+
+    results.push({ code, name: unit.name });
+  }
+
+  return results;
+}
+
+/**
+ * Run a markdown file as a test.
+ *
+ * Each code block (or group) is written to a temp file and executed
+ * sequentially. Stops on first failure.
+ *
+ * @param {string} filePath
+ * @param {{ auto?: boolean, all?: boolean, main?: string }} options
+ * @returns {Promise<{ exitCode: number, stdout: string, stderr: string, results: Array }>}
+ */
+export async function run(filePath, options = {}) {
+  const units = await processMarkdown(filePath, options);
+  const dir = path.dirname(filePath);
+  let allStdout = "";
+  let allStderr = "";
+  const results = [];
+
+  const useRequire = options.require?.length > 0;
+
+  for (const unit of units) {
+    let code = unit.code;
+
+    // --require hooks only work with CJS, so downgrade dynamic import to require
+    if (useRequire && code.includes("await import(")) {
+      code = code.replace(
+        'const { default: assert } = await import("node:assert/strict");',
+        'const assert = require("node:assert/strict");',
+      );
+    }
+
+    const isESM = /^import\s/m.test(code) || /^export\s/m.test(code) || code.includes("await import(");
+    const ext = isESM ? ".mjs" : ".cjs";
+    const tmpFile = path.join(dir, `.readme-assert-${randomUUID().slice(0, 8)}${ext}`);
+    tmpFiles.add(tmpFile);
+    fs.writeFileSync(tmpFile, code);
+
+    try {
+      const nodeArgs = [];
+      for (const r of options.require || []) nodeArgs.push("--require", r);
+      for (const i of options.import || []) nodeArgs.push("--import", i);
+      nodeArgs.push(tmpFile);
+      const result = await exec("node", nodeArgs, dir, filePath);
+      allStdout += result.stdout;
+      allStderr += result.stderr;
+      results.push({ name: unit.name, ...result });
+
+      if (result.exitCode !== 0) {
+        return { exitCode: result.exitCode, stdout: allStdout, stderr: allStderr, results };
+      }
+    } finally {
+      try { fs.unlinkSync(tmpFile); } catch {}
+      tmpFiles.delete(tmpFile);
+    }
+  }
+
+  return { exitCode: 0, stdout: allStdout, stderr: allStderr, results };
+}
+
+function exec(cmd, args, cwd, mdPath) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.on("data", (d) => (stdout += d));
+    child.stderr.on("data", (d) => (stderr += d));
+
+    child.on("close", (exitCode) => {
+      // Rewrite temp file paths to the markdown file path
+      const tmpFile = args[args.length - 1];
+      stderr = stderr.replaceAll(tmpFile, mdPath);
+      stdout = stdout.replaceAll(tmpFile, mdPath);
+
+      if (exitCode !== 0) {
+        stderr = formatError(stderr, mdPath);
+      }
+
+      resolve({ exitCode, stdout, stderr });
+    });
+  });
+}
+
+function formatError(stderr, mdPath) {
+  // Extract location from stack trace
+  const locMatch = stderr.match(new RegExp(`${escapeRegExp(mdPath)}:(\\d+):(\\d+)`));
+  const line = locMatch ? parseInt(locMatch[1]) : null;
+
+  // Extract actual/expected from the error object dump
+  const actualMatch = stderr.match(/actual: (.+)/);
+  const expectedMatch = stderr.match(/expected: (.+)/);
+  const operatorMatch = stderr.match(/operator: '(.+)'/);
+
+  // Extract the error message line
+  const msgMatch = stderr.match(/AssertionError.*?:\s*(.+)/);
+  // Also catch non-assertion errors (ReferenceError, TypeError, etc.)
+  const genericMatch = !msgMatch && stderr.match(/(\w*Error.*)/);
+
+  const parts = [];
+
+  // Location header
+  const relPath = path.relative(process.cwd(), mdPath);
+  if (line) {
+    parts.push(`\n  FAIL  ${relPath}:${line}\n`);
+  } else {
+    parts.push(`\n  FAIL  ${relPath}\n`);
+  }
+
+  // Source context from the markdown
+  if (line) {
+    try {
+      const mdLines = fs.readFileSync(mdPath, "utf-8").split("\n");
+      const start = Math.max(0, line - 3);
+      const end = Math.min(mdLines.length, line + 2);
+      for (let i = start; i < end; i++) {
+        const lineNum = String(i + 1).padStart(4);
+        const marker = i + 1 === line ? " > " : "   ";
+        parts.push(`${marker}${lineNum} | ${mdLines[i]}`);
+      }
+      parts.push("");
+    } catch {
+      // ignore read errors
+    }
+  }
+
+  // Actual vs expected
+  if (actualMatch && expectedMatch) {
+    parts.push(`  expected: ${expectedMatch[1].replace(/,\s*$/, "")}`);
+    parts.push(`  received: ${actualMatch[1].replace(/,\s*$/, "")}`);
+    parts.push("");
+  } else if (msgMatch) {
+    parts.push(`  ${msgMatch[0]}`);
+    parts.push("");
+  } else if (genericMatch) {
+    parts.push(`  ${genericMatch[1]}`);
+    parts.push("");
+  } else {
+    // Fallback: strip Node internals and return cleaned stderr
+    parts.push(
+      stderr
+        .split("\n")
+        .filter((l) => !l.match(/^\s*(at [a-z].*\(node:|node:internal|Node\.js v|triggerUncaught|\^$)/i))
+        .join("\n")
+        .trim(),
+    );
+    parts.push("");
+  }
+
+  return parts.join("\n");
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function renameImports(code, packageName, localPath) {
+  const escaped = packageName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return code
+    .replace(
+      new RegExp(`(from\\s+['"])${escaped}(['"])`, "g"),
+      `$1${localPath}$2`,
+    )
+    .replace(
+      new RegExp(`(from\\s+['"])${escaped}/`, "g"),
+      `$1${path.dirname(localPath)}/`,
+    )
+    .replace(
+      new RegExp(`(require\\s*\\(\\s*['"])${escaped}(['"]\\s*\\))`, "g"),
+      `$1${localPath}$2`,
+    );
+}
+
+function findPackageJson(dir) {
+  let current = path.resolve(dir);
+  while (true) {
+    const candidate = path.join(current, "package.json");
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}

package/cli.js

@@ -1,9 +0,0 @@
-#!/usr/bin/env node
-/* eslint-disable */
-if (process.version.match(/v(\d+)\./)[1] < 8) {
-  console.error(
-    "readme-assert: Node 8 or greater is required. `readme-assert` did not run."
-  );
-} else {
-  require("./lib/cli.js");
-}

package/lib/cli.js

@@ -1,62 +0,0 @@
-"use strict";
-
-var _yargs = _interopRequireDefault(require("yargs"));
-
-var _ = _interopRequireDefault(require("."));
-
-var _package = require("../package.json");
-
-var _fs = _interopRequireDefault(require("fs"));
-
-var _path = _interopRequireDefault(require("path"));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
-
-var argv = _yargs["default"].usage("\nRun readme as test\n\nUsage: $0 [options]").option("auto", {
-  alias: "a",
-  description: "Auto discover test code block",
-  type: "boolean"
-}).option("all", {
-  alias: "l",
-  description: "Run all supported code blocks",
-  type: "boolean"
-}).option("babel", {
-  description: "Use babelrc when transpiling",
-  "default": false,
-  type: "boolean"
-}).option("file", {
-  alias: "f",
-  description: "readme.md file to read"
-}).option("main", {
-  alias: "m",
-  description: "Points to the entry point of the module",
-  type: "string"
-}).option("print-code", {
-  alias: "p",
-  description: "Print the transformed code",
-  type: "boolean"
-}).option("require", {
-  alias: "r",
-  description: "Require a given module",
-  type: "array"
-}).alias("h", "help").version(_package.version).help().argv;
-
-function resolve(file) {
-  try {
-    _fs["default"].statSync(_path["default"].join(process.cwd(), file));
-
-    return _path["default"].resolve(file);
-  } catch (err) {
-    return undefined;
-  }
-}
-
-var filename = argv.file ? _path["default"].resolve(argv.file) : resolve("README.md") || resolve("readme.md");
-
-if (filename == null) {
-  console.log(_fs["default"].statSync(_path["default"].join(process.cwd(), "README.md")));
-  console.error("could not locate readme.md");
-  process.exit(1);
-}
-
-(0, _["default"])(argv.main, argv.require || [], argv["print-code"], argv.babel, argv.file ? _path["default"].resolve(argv.file) : resolve("README.md") || resolve("readme.md"), argv.auto, argv.all);

package/lib/extract.js

@@ -1,74 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports["default"] = extractCode;
-
-var _gfmCodeBlocks = _interopRequireDefault(require("gfm-code-blocks"));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
-
-function _toConsumableArray(arr) { return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _nonIterableSpread(); }
-
-function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance"); }
-
-function _iterableToArray(iter) { if (Symbol.iterator in Object(iter) || Object.prototype.toString.call(iter) === "[object Arguments]") return Array.from(iter); }
-
-function _arrayWithoutHoles(arr) { if (Array.isArray(arr)) { for (var i = 0, arr2 = new Array(arr.length); i < arr.length; i++) { arr2[i] = arr[i]; } return arr2; } }
-
-function isSupportedLang(block) {
-  var lang = block.lang.split(" ")[0];
-  return lang === "javascript" || lang === "js" || lang === "typescript" || lang === "ts";
-}
-
-function isTypescript(block) {
-  var lang = block.lang.split(" ")[0];
-  return lang === "typescript" || lang === "ts";
-}
-
-function isTest(block) {
-  var tag = block.lang.split(" ")[1];
-  return tag === "test" || tag === "should";
-}
-
-var arrowRegex = /\/(\/|\*)\s?(=>|→|throws)/;
-
-function isAutomaticTest(block) {
-  return block.code.match(arrowRegex);
-}
-
-function extractCode(markdown) {
-  var _ref = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {},
-      _ref$auto = _ref.auto,
-      auto = _ref$auto === void 0 ? false : _ref$auto,
-      _ref$all = _ref.all,
-      all = _ref$all === void 0 ? false : _ref$all;
-
-  var hasTypescript = false;
-  var code = new Array(markdown.length).fill(" ");
-  var newline = /\n/gm;
-  var result;
-
-  while (result = newline.exec(markdown)) {
-    code[result.index] = "\n";
-  }
-
-  var blocks = (0, _gfmCodeBlocks["default"])(markdown).filter(all ? function () {
-    return true;
-  } : auto ? isAutomaticTest : isTest).filter(isSupportedLang);
-
-  if (blocks.length === 0) {
-    console.error("\nREADME has no test code blocks\n");
-    process.exit(1);
-  }
-
-  blocks.forEach(function (block) {
-    hasTypescript = hasTypescript || isTypescript(block);
-    code.splice.apply(code, [block.start, block.end - block.start].concat(_toConsumableArray(block.code.padStart(block.end - block.start, " ").split(""))));
-  });
-  return {
-    code: code.join(""),
-    hasTypescript: hasTypescript
-  };
-}

package/lib/global-assert.js

@@ -1,144 +0,0 @@
-"use strict";
-
-var _assert = _interopRequireWildcard(require("assert"));
-
-var _tapYaml = require("tap-yaml");
-
-var _stackUtils = _interopRequireWildcard(require("stack-utils"));
-
-function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { var desc = Object.defineProperty && Object.getOwnPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : {}; if (desc.get || desc.set) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } } newObj["default"] = obj; return newObj; } }
-
-function _toConsumableArray(arr) { return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _nonIterableSpread(); }
-
-function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance"); }
-
-function _iterableToArray(iter) { if (Symbol.iterator in Object(iter) || Object.prototype.toString.call(iter) === "[object Arguments]") return Array.from(iter); }
-
-function _arrayWithoutHoles(arr) { if (Array.isArray(arr)) { for (var i = 0, arr2 = new Array(arr.length); i < arr.length; i++) { arr2[i] = arr[i]; } return arr2; } }
-
-console.log("TAP version 13");
-var tests = 0;
-var passes = 0;
-var failures = 0;
-var stackUtils = new _stackUtils["default"]({
-  internals: [].concat(_toConsumableArray((0, _stackUtils.nodeInternals)()), [/\/readme-assert\/lib\//])
-});
-
-function printObject(obj) {
-  console.log("  ---");
-  console.log((0, _tapYaml.stringify)(obj, 4).replace(/^/gm, "  "));
-  console.log("  ...");
-}
-
-function test(message, fn) {
-  var _arguments = arguments;
-  return function () {
-    var args = Array.prototype.slice.call(_arguments);
-    tests++;
-
-    try {
-      fn.apply(_assert["default"], [args]);
-      console.log("ok ".concat(tests, " ").concat(message || ""));
-      passes++;
-    } catch (err) {
-      console.log("not ok ".concat(tests, " ").concat(message || ""));
-      failures++;
-
-      if ("actual" in err && "expected" in err && "operator" in err) {
-        printObject({
-          operator: err.operator,
-          actual: err.actual,
-          expected: err.expected,
-          stack: stackUtils.clean(err.stack).split("\n").slice(1).join("\n")
-        });
-      } else {
-        printObject(err);
-      }
-    }
-  }();
-}
-
-var assert = function assert(value, message) {
-  return test(message, function () {
-    return (0, _assert["default"])(value, message);
-  });
-};
-
-assert.deepEqual = function (actual, expected, message) {
-  test(message, function () {
-    return (0, _assert.deepEqual)(actual, expected, message);
-  });
-};
-
-assert.deepStrictEqual = function (actual, expected, message) {
-  test(message, function () {
-    return (0, _assert.deepStrictEqual)(actual, expected, message);
-  });
-};
-
-assert.doesNotThrow = function (block, error, message) {
-  test(message, function () {
-    return (0, _assert.doesNotThrow)(block, error, message);
-  });
-};
-
-assert.equal = function (actual, expected, message) {
-  test(message, function () {
-    return (0, _assert.equal)(actual, expected, message);
-  });
-};
-
-assert.fail = function (actual, expected, message, operator) {
-  test(message, function () {
-    return (0, _assert.fail)(actual, expected, message, operator);
-  });
-};
-
-assert.ifError = function (value) {
-  test("", function () {
-    return (0, _assert.ifError)(value);
-  });
-};
-
-assert.notDeepEqual = function (actual, expected, message) {
-  test(message, function () {
-    return (0, _assert.notDeepEqual)(actual, expected, message);
-  });
-};
-
-assert.notDeepStrictEqual = function (actual, expected, message) {
-  test(message, function () {
-    return (0, _assert.notDeepStrictEqual)(actual, expected, message);
-  });
-};
-
-assert.ok = function (value, message) {
-  test(message, function () {
-    return (0, _assert.ok)(value, message);
-  });
-};
-
-assert["throws"] = function (block, error, message) {
-  test(message, function () {
-    return (0, _assert["throws"])(block, error, message);
-  });
-};
-
-process.on("uncaughtException", function (err) {
-  console.log("Bail out! Uncaught exception ".concat(err.name));
-  printObject(err);
-  process.exit(1);
-});
-process.on("exit", function (code) {
-  if (code === 0) {
-    console.log("1..".concat(tests));
-    console.log("# tests ".concat(tests));
-    console.log("# pass ".concat(passes));
-    console.log("# fail ".concat(failures));
-
-    if (failures > 0) {
-      process.reallyExit(1);
-    }
-  }
-});
-global.assert = assert;

package/lib/index.js

@@ -1,111 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports["default"] = run;
-
-var babel = _interopRequireWildcard(require("@babel/core"));
-
-var _pluginTransformTypescript = _interopRequireDefault(require("@babel/plugin-transform-typescript"));
-
-var _presetEnv = _interopRequireDefault(require("@babel/preset-env"));
-
-var _babelPluginTransformCommentToAssert = _interopRequireDefault(require("babel-plugin-transform-comment-to-assert"));
-
-var _babelPluginTransformRenameImport = _interopRequireDefault(require("babel-plugin-transform-rename-import"));
-
-var _sourceMapSupport = _interopRequireDefault(require("source-map-support"));
-
-var _fs = _interopRequireDefault(require("fs"));
-
-var _path = _interopRequireDefault(require("path"));
-
-var _pkgUp = _interopRequireDefault(require("pkg-up"));
-
-var _extract2 = _interopRequireDefault(require("./extract"));
-
-var _runInThisContext = require("./runInThisContext");
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
-
-function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { var desc = Object.defineProperty && Object.getOwnPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : {}; if (desc.get || desc.set) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } } newObj["default"] = obj; return newObj; } }
-
-function _toConsumableArray(arr) { return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _nonIterableSpread(); }
-
-function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance"); }
-
-function _iterableToArray(iter) { if (Symbol.iterator in Object(iter) || Object.prototype.toString.call(iter) === "[object Arguments]") return Array.from(iter); }
-
-function _arrayWithoutHoles(arr) { if (Array.isArray(arr)) { for (var i = 0, arr2 = new Array(arr.length); i < arr.length; i++) { arr2[i] = arr[i]; } return arr2; } }
-
-function run(main, req, shouldPrintCode, babelrc, filePath, auto, all) {
-  var sourceMaps = !shouldPrintCode;
-  var sourceMapsFile = shouldPrintCode ? _path["default"].join(_path["default"].dirname(filePath), "readme.md.js") : filePath;
-  req.forEach(function (f) {
-    require(require.resolve(f, {
-      paths: [process.cwd()]
-    }));
-  });
-
-  var mdDirname = _path["default"].dirname(filePath);
-
-  process.chdir(mdDirname);
-  var mdText = read(filePath);
-
-  var rootPkg = _pkgUp["default"].sync();
-
-  var pkg = JSON.parse(read(rootPkg));
-
-  var _extract = (0, _extract2["default"])(mdText, {
-    auto: auto,
-    all: all
-  }),
-      code = _extract.code,
-      hasTypescript = _extract.hasTypescript;
-
-  var transformed = babel.transform(code, {
-    babelrc: babelrc,
-    sourceMaps: sourceMaps,
-    plugins: [].concat(_toConsumableArray(hasTypescript ? [_pluginTransformTypescript["default"]] : []), [_babelPluginTransformCommentToAssert["default"], rootPkg ? [_babelPluginTransformRenameImport["default"], {
-      replacement: main || process.cwd(),
-      original: pkg.name
-    }] : undefined]),
-    presets: [_presetEnv["default"]],
-    filename: sourceMapsFile
-  });
-
-  if (sourceMaps) {
-    _sourceMapSupport["default"].install({
-      retrieveSourceMap: function retrieveSourceMap(request) {
-        if (request === filePath) {
-          return {
-            url: sourceMapsFile,
-            map: transformed.map
-          };
-        }
-
-        return null;
-      }
-    });
-  }
-
-  if (shouldPrintCode) {
-    printCode(transformed.code, sourceMapsFile);
-  }
-
-  require("./global-assert");
-
-  (0, _runInThisContext.runInThisContext)(transformed.code, sourceMapsFile);
-}
-
-function read(file) {
-  return _fs["default"].readFileSync(_path["default"].join(file), "utf-8");
-}
-
-function printCode(code, sourceMapsFile) {
-  console.log("\n# ", sourceMapsFile);
-  code.split("\n").forEach(function (l, i) {
-    return console.log("# ".concat(String(i + 1).padEnd(3, " "), " ").concat(l));
-  });
-}