readme-assert 6.0.3 → 7.1.0

package/src/generate.js

@@ -0,0 +1,96 @@
+/**
+ * Assemble extracted code blocks into runnable JS modules.
+ *
+ * Each block becomes its own module unless blocks share a group name,
+ * in which case they are merged into a single module.
+ *
+ * @param {{ blocks: Block[], hasTypescript: boolean }} extracted
+ * @returns {{ units: Array<{ code: string, name: string, hasTypescript: boolean }> }}
+ */
+export function generate({ blocks }) {
+  if (blocks.length === 0) return { units: [] };
+
+  // Group blocks: blocks with a group name are merged, others are standalone
+  const groups = new Map();
+  const units = [];
+
+  for (const block of blocks) {
+    if (block.group) {
+      if (!groups.has(block.group)) {
+        const entry = { blocks: [], name: block.group };
+        groups.set(block.group, entry);
+        units.push(entry);
+      }
+      groups.get(block.group).blocks.push(block);
+    } else {
+      units.push({ blocks: [block], name: block.tag || `line ${block.startLine}` });
+    }
+  }
+
+  return {
+    units: units.map((unit) => ({
+      code: assembleUnit(unit.blocks),
+      name: unit.name,
+      hasTypescript: unit.blocks.some((b) => b.lang === "typescript" || b.lang === "ts"),
+    })),
+  };
+}
+
+function assembleUnit(blocks) {
+  // Find the last line number we need to cover
+  const maxLine = Math.max(...blocks.map((b) => b.endLine));
+
+  // Build a line array filled with empty strings
+  const lines = new Array(maxLine).fill("");
+
+  // Place each block's code at its source position
+  for (const block of blocks) {
+    const codeLines = block.code.replace(/\n$/, "").split("\n");
+    for (let i = 0; i < codeLines.length; i++) {
+      lines[block.startLine - 1 + i] = codeLines[i];
+    }
+  }
+
+  // Separate import/export lines from body lines
+  const imports = [];
+  const bodyLines = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trimStart();
+    if (isImportOrExport(trimmed)) {
+      imports.push(lines[i]);
+      bodyLines.push(""); // keep line padding
+    } else {
+      bodyLines.push(lines[i]);
+    }
+  }
+
+  const hasESM = imports.length > 0;
+  const hasCJS = /\brequire\s*\(/.test(bodyLines.join("\n"));
+
+  // Place assert import on line 0 (before markdown line 1) so line numbers
+  // in the generated code match the original markdown positions exactly.
+  let assertLine;
+  if (hasESM) {
+    assertLine = 'import assert from "node:assert/strict";';
+  } else if (hasCJS) {
+    assertLine = 'const assert = require("node:assert/strict");';
+  } else {
+    assertLine = 'const { default: assert } = await import("node:assert/strict");';
+  }
+
+  // imports go on line 0 too (they're already removed from bodyLines).
+  // Each piece is its own statement, so a single space between them is
+  // enough; joining with "; " produced a double semicolon like ";; ".
+  const header = [assertLine, ...imports].join(" ");
+  bodyLines[0] = header;
+  return bodyLines.join("\n") + "\n";
+}
+
+function isImportOrExport(line) {
+  return (
+    /^import\s/.test(line) ||
+    /^import\(/.test(line) ||
+    /^export\s/.test(line)
+  );
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export { extractBlocks } from "./extract.js";
+export { commentToAssert } from "./comment-to-assert.js";
+export { generate } from "./generate.js";
+export { processMarkdown, run } from "./run.js";

package/src/run.js

@@ -0,0 +1,320 @@
+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) {
+    const err = new Error(`No test code blocks found in ${filePath}`);
+    err.code = "NO_TEST_BLOCKS";
+    throw err;
+  }
+
+  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 || resolveMainEntry(pkg) || "./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, {
+      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.
+ *
+ * When `options.stream` is true, each child's stdout chunk is written
+ * to `process.stdout` as it arrives so long-running blocks don't look
+ * stalled. Captured stdout is still returned in the result for
+ * programmatic callers.
+ *
+ * @param {string} filePath
+ * @param {{ auto?: boolean, all?: boolean, main?: string, stream?: boolean }} 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;
+  const stream = options.stream ?? false;
+
+  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, stream);
+      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, stream) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.on("data", (chunk) => {
+      if (stream) process.stdout.write(chunk);
+      stdout += chunk;
+    });
+    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;
+  }
+}
+
+/**
+ * Resolve a package's main entry point from its package.json.
+ *
+ * Handles `main`, plus the various shapes of `exports`:
+ *   - string:          "exports": "./lib/main.js"
+ *   - subpath map:     "exports": { ".": "./lib/main.js" }
+ *   - conditional:     "exports": { "import": "./esm.js", "require": "./cjs.js" }
+ *   - nested:          "exports": { ".": { "import": "./esm.js" } }
+ *
+ * Returns null if no entry can be determined.
+ */
+export function resolveMainEntry(pkg) {
+  if (pkg.main) return pkg.main;
+
+  const exp = pkg.exports;
+  if (!exp) return null;
+  if (typeof exp === "string") return exp;
+  if (typeof exp !== "object") return null;
+
+  // If any key starts with ".", this is a subpath map and the root export
+  // lives at "."; otherwise the object itself is the conditional map.
+  const isSubpathMap = Object.keys(exp).some((k) => k.startsWith("."));
+  const root = isSubpathMap ? exp["."] : exp;
+
+  return resolveExportCondition(root);
+}
+
+function resolveExportCondition(node) {
+  if (node == null) return null;
+  if (typeof node === "string") return node;
+  if (typeof node !== "object") return null;
+
+  // Prefer import > default > require
+  for (const key of ["import", "default", "require"]) {
+    if (key in node) {
+      const resolved = resolveExportCondition(node[key]);
+      if (resolved) return resolved;
+    }
+  }
+  return null;
+}

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
-  };
-}