readme-assert 7.0.0 → 7.2.0

package/package.json

@@ -1,7 +1,18 @@
 {
   "name": "readme-assert",
-  "version": "7.0.0",
+  "version": "7.2.0",
   "description": "Run code blocks in your readme as tests",
+  "keywords": [
+    "readme",
+    "test",
+    "testing",
+    "documentation",
+    "doctest",
+    "assert",
+    "markdown",
+    "code-blocks",
+    "typescript"
+  ],
   "type": "module",
   "exports": "./src/index.js",
   "bin": {

package/readme.md

@@ -71,6 +71,15 @@ const b = () => {
 b(); // throws /fail/
 ```
 
+Or use `//=>` with an error name and optional message to match both:
+
+```javascript test
+const c = () => {
+  throw new TypeError("bad input");
+};
+c(); //=> TypeError: bad input
+```
+
 ### console.log
 
 Assert console output — the call is preserved and an assertion is added:
@@ -120,8 +129,8 @@ x; //=> 2
 
 ### Auto-discover mode
 
-With `--auto`, any code block containing `//=>`, `// →`, or `// throws`
-is treated as a test — no `test` tag needed.
+With `--auto`, any code block containing `//=>`, `// →`, `// ->`,
+`// throws`, or `// rejects` is treated as a test — no `test` tag needed.
 
 ### All mode
 

package/src/cli.js

@@ -3,20 +3,28 @@ import { parseArgs } from "node:util";
 import path from "node:path";
 import fs from "node:fs";
 
-const { values: args } = parseArgs({
-  options: {
-    file: { type: "string", short: "f" },
-    main: { type: "string", short: "m" },
-    auto: { type: "boolean", short: "a", default: false },
-    all: { type: "boolean", short: "l", default: false },
-    require: { type: "string", short: "r", multiple: true },
-    import: { type: "string", short: "i", multiple: true },
-    "print-code": { type: "boolean", short: "p", default: false },
-    help: { type: "boolean", short: "h", default: false },
-    version: { type: "boolean", short: "v", default: false },
-  },
-  strict: false,
-});
+let args;
+try {
+  ({ values: args } = parseArgs({
+    options: {
+      file: { type: "string", short: "f" },
+      main: { type: "string", short: "m" },
+      auto: { type: "boolean", short: "a", default: false },
+      all: { type: "boolean", short: "l", default: false },
+      require: { type: "string", short: "r", multiple: true },
+      import: { type: "string", short: "i", multiple: true },
+      "print-code": { type: "boolean", short: "p", default: false },
+      help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", short: "v", default: false },
+    },
+    strict: true,
+    allowPositionals: true,
+  }));
+} catch (err) {
+  console.error(err.message);
+  console.error("Run with --help to see supported options.");
+  process.exit(1);
+}
 
 if (args.help) {
   console.log(`
@@ -68,20 +76,31 @@ const opts = {
   import: args.import,
 };
 
-if (args["print-code"]) {
-  const { processMarkdown } = await import("./run.js");
-  const units = await processMarkdown(filePath, opts);
-  for (const unit of units) {
-    console.log(`# --- ${unit.name} ---`);
-    console.log(unit.code);
+try {
+  if (args["print-code"]) {
+    const { processMarkdown } = await import("./run.js");
+    const units = await processMarkdown(filePath, opts);
+    for (const unit of units) {
+      console.log(`# --- ${unit.name} ---`);
+      console.log(unit.code);
+    }
+  } else {
+    const { run } = await import("./run.js");
+    // stream: true pipes each child's stdout to process.stdout live so
+    // long-running blocks don't look stalled.
+    const { exitCode, stderr, results } = await run(filePath, { ...opts, stream: true });
+    if (stderr) process.stderr.write(stderr);
+    if (exitCode === 0) {
+      console.log(`All assertions passed. (${results.length} blocks)`);
+    }
+    process.exitCode = exitCode;
   }
-} else {
-  const { run } = await import("./run.js");
-  const { exitCode, stdout, stderr, results } = await run(filePath, opts);
-  if (stdout) process.stdout.write(stdout);
-  if (stderr) process.stderr.write(stderr);
-  if (exitCode === 0) {
-    console.log(`All assertions passed. (${results.length} blocks)`);
+} catch (err) {
+  if (err?.code === "NO_TEST_BLOCKS") {
+    const relPath = path.relative(process.cwd(), filePath);
+    console.error(`No test code blocks found in ${relPath}`);
+    process.exitCode = 1;
+  } else {
+    throw err;
   }
-  process.exitCode = exitCode;
 }

package/src/comment-to-assert.js

@@ -7,6 +7,7 @@ import MagicString from "magic-string";
  *   expr //=> value        → assert.deepEqual(expr, value)
  *   expr // → value        → assert.deepEqual(expr, value)
  *   expr // throws /pat/   → assert.throws(() => { expr }, /pat/)
+ *   expr //=> Error: msg   → assert.throws(() => { expr }, { message: "msg" })
  *   console.log(x) //=> v  → console.log(x); assert.deepEqual(x, v)
  *   expr //=> resolves to v → assert.deepEqual(await expr, v)
  *   expr // rejects /pat/  → assert.rejects(() => expr, /pat/)
@@ -14,10 +15,10 @@ import MagicString from "magic-string";
  * Uses oxc-parser for AST + comment extraction. Handles both JS and TS.
  *
  * @param {string} code - JavaScript or TypeScript source
- * @param {{ filename?: string, typescript?: boolean }} options
- * @returns {{ code: string, map: object }}
+ * @param {{ typescript?: boolean }} options
+ * @returns {{ code: string }}
  */
-export function commentToAssert(code, { filename, typescript = false } = {}) {
+export function commentToAssert(code, { typescript = false } = {}) {
   const ext = typescript ? "test.ts" : "test.js";
   const result = parseSync(ext, code);
   const ast = result.program;
@@ -41,6 +42,8 @@ export function commentToAssert(code, { filename, typescript = false } = {}) {
       const resolvesMatch = rest.match(/^resolves\s+(?:to\s+)?([\s\S]*)$/);
       changed = true;
 
+      const errorMatch = rest.match(/^((?:[A-Z]\w+)?Error)(?::\s*(.*))?$/);
+
       if (resolvesMatch) {
         // expr //=> resolves to value → assert.deepEqual(await expr, value)
         const expected = resolvesMatch[1].trim();
@@ -53,8 +56,27 @@ export function commentToAssert(code, { filename, typescript = false } = {}) {
           comment.end,
           `assert.deepEqual(await ${exprSource}, ${expected});`,
         );
+      } else if (errorMatch) {
+        // expr //=> TypeError: msg → assert.throws(() => { expr }, { name, message })
+        const errorName = errorMatch[1];
+        const errorMessage = errorMatch[2]?.trim();
+        const exprSource = code.slice(
+          node.expression.start,
+          node.expression.end,
+        );
+        const props = [`name: "${errorName}"`];
+        if (errorMessage) {
+          props.push(`message: "${errorMessage}"`);
+        }
+        s.overwrite(
+          node.start,
+          comment.end,
+          `assert.throws(() => { ${exprSource}; }, { ${props.join(", ")} });`,
+        );
       } else if (isConsoleCall(node.expression)) {
-        // console.log(expr) //=> value → keep log, add assertion after
+        // console.log(expr) //=> value → keep log, add assertion after.
+        // Stay on the same line so subsequent markdown line numbers are
+        // preserved for error reporting.
         const arg = code.slice(
           node.expression.arguments[0].start,
           node.expression.arguments[0].end,
@@ -62,7 +84,7 @@ export function commentToAssert(code, { filename, typescript = false } = {}) {
         s.overwrite(
           node.expression.end,
           comment.end,
-          `;\nassert.deepEqual(${arg}, ${rest});`,
+          `; assert.deepEqual(${arg}, ${rest});`,
         );
       } else {
         // expr //=> value → assert.deepEqual(expr, value)
@@ -103,12 +125,9 @@ export function commentToAssert(code, { filename, typescript = false } = {}) {
     }
   }
 
-  if (!changed) return { code, map: null };
+  if (!changed) return { code };
 
-  return {
-    code: s.toString(),
-    map: s.generateMap({ source: filename, hires: true }),
-  };
+  return { code: s.toString() };
 }
 
 /**

package/src/extract.js

@@ -17,7 +17,7 @@ export function extractBlocks(markdown, { auto = false, all = false } = {}) {
   const fenceRe = /^(([ \t]*`{3,4})([^\n]*)([\s\S]+?)(^[ \t]*\2))/gm;
   const supportedLangs = new Set(["javascript", "js", "typescript", "ts"]);
   const tsLangs = new Set(["typescript", "ts"]);
-  const assertRe = /\/[/*]\s*(=>|→|throws)/;
+  const assertRe = /\/[/*]\s*(=>|→|->|throws|rejects)/;
 
   let hasTypescript = false;
   const blocks = [];

package/src/generate.js

@@ -79,8 +79,10 @@ function assembleUnit(blocks) {
     assertLine = 'const { default: assert } = await import("node:assert/strict");';
   }
 
-  // imports go on line 0 too (they're already removed from bodyLines)
-  const header = [assertLine, ...imports].join("; ");
+  // 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";
 }

package/src/run.js

@@ -39,7 +39,9 @@ export async function processMarkdown(filePath, options = {}) {
   });
 
   if (extracted.blocks.length === 0) {
-    throw new Error("README has no test code blocks");
+    const err = new Error(`No test code blocks found in ${filePath}`);
+    err.code = "NO_TEST_BLOCKS";
+    throw err;
   }
 
   const { units } = generate(extracted);
@@ -50,7 +52,7 @@ export async function processMarkdown(filePath, options = {}) {
   if (pkgPath) {
     const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
     if (pkg.name) {
-      const mainEntry = options.main || pkg.main || pkg.exports?.["."] || "./index.js";
+      const mainEntry = options.main || resolveMainEntry(pkg) || "./index.js";
       packageName = pkg.name;
       localPath = path.resolve(path.dirname(pkgPath), mainEntry);
     }
@@ -65,7 +67,6 @@ export async function processMarkdown(filePath, options = {}) {
     }
 
     const transformed = commentToAssert(code, {
-      filename: filePath,
       typescript: unit.hasTypescript,
     });
     code = transformed.code;
@@ -91,8 +92,13 @@ export async function processMarkdown(filePath, options = {}) {
  * 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 }} options
+ * @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 = {}) {
@@ -103,6 +109,7 @@ export async function run(filePath, options = {}) {
   const results = [];
 
   const useRequire = options.require?.length > 0;
+  const stream = options.stream ?? false;
 
   for (const unit of units) {
     let code = unit.code;
@@ -126,7 +133,7 @@ export async function run(filePath, options = {}) {
       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);
+      const result = await exec("node", nodeArgs, dir, filePath, stream);
       allStdout += result.stdout;
       allStderr += result.stderr;
       results.push({ name: unit.name, ...result });
@@ -143,13 +150,16 @@ export async function run(filePath, options = {}) {
   return { exitCode: 0, stdout: allStdout, stderr: allStderr, results };
 }
 
-function exec(cmd, args, cwd, mdPath) {
+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", (d) => (stdout += d));
+    child.stdout.on("data", (chunk) => {
+      if (stream) process.stdout.write(chunk);
+      stdout += chunk;
+    });
     child.stderr.on("data", (d) => (stderr += d));
 
     child.on("close", (exitCode) => {
@@ -266,3 +276,45 @@ function findPackageJson(dir) {
     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;
+}