readme-assert 6.0.3 → 7.1.0

package/package.json

@@ -1,54 +1,45 @@
 {
   "name": "readme-assert",
-  "version": "6.0.3",
-  "engines": {
-    "node": ">=4"
-  },
-  "description": "Run code blocks in your readme as test",
-  "main": "lib/index.js",
-  "jsnext:main": "src/index.js",
-  "bin": "cli.js",
-  "scripts": {
-    "build": "babel src/. -d lib/. --ignore=spec.js",
-    "test:readme": "babel-node src/cli.js -m ./src",
-    "test": "npm-run-all test:*",
-    "prettier": "prettier 'src/**/*'",
-    "prepublish": "npm run build"
+  "version": "7.1.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": {
+    "readme-assert": "./src/cli.js"
   },
+  "files": [
+    "src"
+  ],
+  "license": "MIT",
   "author": {
     "name": "Sigurd Fosseng",
     "email": "sigurd@fosseng.net",
     "url": "http://laat.io"
   },
-  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/laat/readme-assert.git"
   },
-  "dependencies": {
-    "@babel/core": "^7.0.0",
-    "@babel/plugin-syntax-typescript": "^7.3.3",
-    "@babel/plugin-transform-typescript": "^7.4.5",
-    "@babel/preset-env": "^7.0.0",
-    "babel-plugin-transform-comment-to-assert": "^4.1.0",
-    "babel-plugin-transform-rename-import": "^2.0.0",
-    "gfm-code-blocks": "^1.0.0",
-    "pkg-up": "^3.1.0",
-    "source-map-support": "^0.5.12",
-    "stack-utils": "^1.0.2",
-    "tap-yaml": "^1.0.0",
-    "yargs": "^13.2.4"
+  "engines": {
+    "node": ">=20.19.0 || >=22.12.0"
   },
-  "devDependencies": {
-    "@babel/cli": "7.4.4",
-    "@babel/node": "7.4.5",
-    "@babel/register": "7.4.4",
-    "npm-run-all": "4.1.5",
-    "prettier": "1.18.2",
-    "run-tests": "1.0.4"
+  "dependencies": {
+    "esbuild": "^0.27.0",
+    "magic-string": "^0.30.0",
+    "oxc-parser": "^0.123.0"
   },
-  "files": [
-    "lib",
-    "cli.js"
-  ]
-}
+  "scripts": {
+    "test": "node --test test/*.test.js && pnpm -r test"
+  }
+}

package/readme.md

@@ -1,37 +1,42 @@
-# readme-assert [![travis][travis-image]][travis-url] [![npm][npm-image]][npm-url]
+# readme-assert [![npm][npm-image]][npm-url]
 
-[travis-image]: https://travis-ci.org/laat/readme-assert.svg?branch=master
-[travis-url]: https://travis-ci.org/laat/readme-assert
 [npm-image]: https://img.shields.io/npm/v/readme-assert.svg?style=flat
 [npm-url]: https://npmjs.org/package/readme-assert
 
-> Run code blocks in your readme as test
+`README.md` files often become outdated because the code examples are
+not regularly tested. readme-assert extracts fenced code blocks from
+your readme and runs them as tests, using special comments as assertions.
 
-`README.md` files often become outdated over time because the code
-examples are not regulary tested. By commenting `javascript`
-codeblocks the `README.md` file with special comments we can create
-simple tests that ensures that the readme is still correct.
+## Install
+
+```
+npm install readme-assert
+```
 
 ## Usage
 
 ```
-Run readme as test
-
 Usage: readme-assert [options]
 
 Options:
-  --auto, -a        Auto discover test code block                      [boolean]
-  --all, -l         Run all supported code blocks                      [boolean]
-  --babel           Use babelrc when transpiling      [boolean] [default: false]
   --file, -f        readme.md file to read
-  --main, -m        Points to the entry point of the module             [string]
-  --print-code, -p  Print the transformed code                         [boolean]
-  --require, -r     Require a given module                               [array]
-  --version         Show version number                                [boolean]
-  -h, --help        Show help                                          [boolean]
+  --main, -m        Entry point of the module
+  --auto, -a        Auto discover test code blocks
+  --all, -l         Run all supported code blocks
+  --print-code, -p  Print the transformed code
+  --version, -v     Show version number
+  -h, --help        Show help
 ```
 
-Write a test in the readme with the special code-block tag `test`
+Run in the same folder as your readme:
+
+```
+$ readme-assert
+```
+
+## Writing Tests
+
+Tag your fenced code blocks with `test` or `should`:
 
 ````
 ```javascript test
@@ -39,88 +44,98 @@ Write a test in the readme with the special code-block tag `test`
 ```
 ````
 
-Run the test in the same folder as your readme:
+### Assertion Comments
 
-```
-$ readme-assert
+Use `//=>` to assert the value of an expression:
+
+```javascript test
+let a = 1;
+a; //=> 1
 ```
 
-output:
+The `// →` (unicode arrow) and `// ->` (ascii arrow) variants also work:
 
-```
-TAP version 13
-ok 1
-# tests 1
-# pass 1
-# fail 0
+```javascript test
+let b = 1;
+b; // → 1
 ```
 
-Printing the evaluated code, can be useful when debugging:
+### throws
 
-```
-$ readme-assert --print-code
+Assert that an expression throws using `// throws` with a regex pattern:
+
+```javascript test
+const b = () => {
+  throw new Error("fail");
+};
+b(); // throws /fail/
 ```
 
-output:
+### console.log
 
-```
-#  /path/to/module/readme.md.js
-# 1   "use strict";
-# 2
-# 3   assert.deepEqual(1 + 1, 2);
-TAP version 13
-ok 1
-1..1
-# tests 1
-# pass 1
-# fail 0
+Assert console output — the call is preserved and an assertion is added:
+
+```javascript test
+let a = { a: 1 };
+console.log(a); //=> { a: 1 }
 ```
 
-## Examples
+### Promises
 
-To see some examples of use see the [examples folder](https://github.com/laat/readme-assert/tree/master/examples) in the repository
+Assert that a promise resolves to a value with `//=> resolves to`:
 
-## Sample tests
+```javascript test
+Promise.resolve(true) //=> resolves to true
+```
 
-### simple
+Assert that a promise rejects with `// rejects`:
 
-```javascript should equal 1
-let a = 1;
-a; //=> 1
+```javascript test
+Promise.reject(new Error("no")) // rejects /no/
 ```
 
-### utf-8 arrow
+### TypeScript
 
-```javascript test utf8 arrow
-a; // → 1
+TypeScript code blocks are supported natively:
+
+```typescript should add two numbers
+const sum: number = 1 + 1;
+sum; //=> 2
 ```
 
-### console.log
+### Grouping blocks
 
-```javascript test console.log
-a = { a: 1 };
-console.log(a); //=> { a: 1 }
-```
+Each code block runs as its own file. To share variables across
+blocks, give them the same group name with `test:groupname`:
 
-### throws
+````
+```javascript test:math
+let x = 2;
+```
 
-```javascript test throws
-const b = () => {
-  throw new Error("fail");
-};
-b(); // throws /fail/
+```javascript test:math
+x; //=> 2
 ```
+````
 
-### TypesScript
+### Auto-discover mode
 
-```typescript should add two numbers with typescript
-const sum: number = 1 + 1;
-sum; //=> 2
-```
+With `--auto`, any code block containing `//=>`, `// →`, `// ->`,
+`// throws`, or `// rejects` is treated as a test — no `test` tag needed.
+
+### All mode
+
+With `--all`, every JavaScript and TypeScript code block is executed,
+regardless of tags.
+
+## How It Works
+
+1. Each fenced code block is extracted from the markdown
+2. Blocks with the same `test:group` name are merged; others run independently
+3. Assertion comments (`//=> value`) are transformed into `assert.deepEqual()` calls using [oxc-parser](https://oxc.rs) and [magic-string](https://github.com/rich-harris/magic-string)
+4. Imports of your package name are rewritten to point to your local source
+5. Each block is written to a temp file and executed with `node`
 
-## Projects using readme-assert
+## License
 
-- [fen-chess-board](https://github.com/laat/fen-chess-board)
-- [babel-plugin-transform-comment-to-assert](https://github.com/laat/babel-plugin-transform-comment-to-assert)
-- [babel-plugin-transform-rename-import](https://github.com/laat/babel-plugin-transform-rename-import)
-- [escape-invisibles](https://github.com/laat/escape-invisibles)
+MIT

package/src/cli.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import path from "node:path";
+import fs from "node:fs";
+
+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(`
+Run code blocks in your readme as tests
+
+Usage: readme-assert [options]
+
+Options:
+  --file, -f        readme.md file to read
+  --main, -m        Entry point of the module
+  --auto, -a        Auto discover test code blocks
+  --all, -l         Run all supported code blocks
+  --require, -r     Require a module before running          [array]
+  --import, -i      Import a module before running           [array]
+  --print-code, -p  Print the transformed code
+  --version, -v     Show version number
+  -h, --help        Show help
+`);
+  process.exit(0);
+}
+
+if (args.version) {
+  const pkgPath = new URL("../package.json", import.meta.url);
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+function findReadme() {
+  for (const name of ["README.md", "readme.md"]) {
+    const p = path.resolve(name);
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+const filePath = args.file ? path.resolve(args.file) : findReadme();
+
+if (!filePath) {
+  console.error("Could not locate readme.md");
+  process.exit(1);
+}
+
+const opts = {
+  auto: args.auto,
+  all: args.all,
+  main: args.main,
+  require: args.require,
+  import: args.import,
+};
+
+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;
+  }
+} 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;
+  }
+}

package/src/comment-to-assert.js

@@ -0,0 +1,138 @@
+import { parseSync } from "oxc-parser";
+import MagicString from "magic-string";
+
+/**
+ * Transform assertion comments into assert calls.
+ *
+ *   expr //=> value        → assert.deepEqual(expr, value)
+ *   expr // → value        → assert.deepEqual(expr, value)
+ *   expr // throws /pat/   → assert.throws(() => { expr }, /pat/)
+ *   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/)
+ *
+ * Uses oxc-parser for AST + comment extraction. Handles both JS and TS.
+ *
+ * @param {string} code - JavaScript or TypeScript source
+ * @param {{ typescript?: boolean }} options
+ * @returns {{ code: string }}
+ */
+export function commentToAssert(code, { typescript = false } = {}) {
+  const ext = typescript ? "test.ts" : "test.js";
+  const result = parseSync(ext, code);
+  const ast = result.program;
+  const comments = result.comments;
+
+  const s = new MagicString(code);
+  let changed = false;
+
+  for (const node of ast.body) {
+    if (node.type !== "ExpressionStatement") continue;
+
+    const comment = findTrailingComment(comments, node, code);
+    if (!comment) continue;
+
+    const match = comment.value.match(/^\s*(=>|→|->)\s*([\s\S]*)$/);
+    const throwsMatch = comment.value.match(/^\s*throws\s+([\s\S]*)$/);
+    const rejectsMatch = comment.value.match(/^\s*rejects\s+([\s\S]*)$/);
+
+    if (match) {
+      const rest = match[2].trim();
+      const resolvesMatch = rest.match(/^resolves\s+(?:to\s+)?([\s\S]*)$/);
+      changed = true;
+
+      if (resolvesMatch) {
+        // expr //=> resolves to value → assert.deepEqual(await expr, value)
+        const expected = resolvesMatch[1].trim();
+        const exprSource = code.slice(
+          node.expression.start,
+          node.expression.end,
+        );
+        s.overwrite(
+          node.start,
+          comment.end,
+          `assert.deepEqual(await ${exprSource}, ${expected});`,
+        );
+      } else if (isConsoleCall(node.expression)) {
+        // 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,
+        );
+        s.overwrite(
+          node.expression.end,
+          comment.end,
+          `; assert.deepEqual(${arg}, ${rest});`,
+        );
+      } else {
+        // expr //=> value → assert.deepEqual(expr, value)
+        const exprSource = code.slice(
+          node.expression.start,
+          node.expression.end,
+        );
+        s.overwrite(
+          node.start,
+          comment.end,
+          `assert.deepEqual(${exprSource}, ${rest});`,
+        );
+      }
+    } else if (throwsMatch) {
+      const pattern = throwsMatch[1].trim();
+      const exprSource = code.slice(
+        node.expression.start,
+        node.expression.end,
+      );
+      s.overwrite(
+        node.start,
+        comment.end,
+        `assert.throws(() => { ${exprSource}; }, ${pattern});`,
+      );
+      changed = true;
+    } else if (rejectsMatch) {
+      const pattern = rejectsMatch[1].trim();
+      const exprSource = code.slice(
+        node.expression.start,
+        node.expression.end,
+      );
+      s.overwrite(
+        node.start,
+        comment.end,
+        `await assert.rejects(() => ${exprSource}, ${pattern});`,
+      );
+      changed = true;
+    }
+  }
+
+  if (!changed) return { code };
+
+  return { code: s.toString() };
+}
+
+/**
+ * Find a trailing line comment for an expression statement.
+ * The comment must start after the expression and be on the same line.
+ */
+function findTrailingComment(comments, node, code) {
+  for (const c of comments) {
+    if (c.type !== "Line") continue;
+    if (c.start < node.expression.end) continue;
+
+    // Must be on the same line as the expression (no newline between)
+    const between = code.slice(node.expression.end, c.start);
+    if (between.includes("\n")) continue;
+
+    return c;
+  }
+  return null;
+}
+
+function isConsoleCall(expr) {
+  return (
+    expr.type === "CallExpression" &&
+    expr.callee.type === "MemberExpression" &&
+    expr.callee.object.type === "Identifier" &&
+    expr.callee.object.name === "console"
+  );
+}

package/src/extract.js

@@ -0,0 +1,66 @@
+/**
+ * Extract tagged code blocks from a markdown string.
+ *
+ * @param {string} markdown
+ * @param {{ auto?: boolean, all?: boolean }} options
+ * @returns {{ blocks: Block[], hasTypescript: boolean }}
+ *
+ * Block: { code, lang, tag, group, startLine, endLine }
+ *
+ * Tags: "test", "test:groupname", "should description", "should:groupname description"
+ * Blocks with the same group name are merged into a single execution unit.
+ * Blocks without a group name each run independently.
+ */
+export function extractBlocks(markdown, { auto = false, all = false } = {}) {
+  // Based on gfm-code-block-regex — the backreference \2 ensures a 4-backtick
+  // fence only closes with 4 backticks, so nested display fences are skipped.
+  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|rejects)/;
+
+  let hasTypescript = false;
+  const blocks = [];
+  let match;
+
+  while ((match = fenceRe.exec(markdown)) !== null) {
+    const infoString = match[3].trim();
+    const code = match[4].replace(/^\n/, "");
+    const blockStart = match.index;
+
+    // Parse language and tag from info string (e.g. "javascript test" or "ts test:group")
+    const parts = infoString.split(/\s+/);
+    const lang = parts[0] || "";
+    const tag = parts.slice(1).join(" ");
+
+    if (!supportedLangs.has(lang)) continue;
+
+    // Filter by mode
+    if (!all) {
+      if (auto) {
+        if (!assertRe.test(code)) continue;
+      } else {
+        const firstWord = tag.split(/\s+/)[0] || "";
+        const keyword = firstWord.split(":")[0];
+        if (keyword !== "test" && keyword !== "should") continue;
+      }
+    }
+
+    // Count lines before this block to get startLine (1-based)
+    const linesBeforeBlock = markdown.slice(0, blockStart).split("\n").length;
+    const startLine = linesBeforeBlock + 1; // +1 for the fence line itself
+    const codeLines = code.split("\n").length;
+    const endLine = startLine + codeLines - 1;
+
+    if (tsLangs.has(lang)) hasTypescript = true;
+
+    // Parse group from tag: "test:mygroup ..." or "should:mygroup ..."
+    const firstTagWord = tag.split(/\s+/)[0] || "";
+    const colonIdx = firstTagWord.indexOf(":");
+    const group = colonIdx !== -1 ? firstTagWord.slice(colonIdx + 1) : null;
+
+    blocks.push({ code, lang, tag, group, startLine, endLine });
+  }
+
+  return { blocks, hasTypescript };
+}