textrun-npm 0.2.1 → 0.3.0

package/README.md

@@ -1,15 +1,12 @@
 # Text-Runner Actions for npm
 
-hello
-
 This package provides [Text-Runner](https://github.com/kevgo/text-runner)
 actions for verifying the documentation of npm packages.
 
 ### Installation
 
 To use these actions, add this package as a development dependency by running
-<code type="npm/install">npm i -D textrun-npm</code> or
-<code type="npm/install">yarn i -D textrun-npm</code>.
+<code type="npm/install">npm i -D textrun-npm</code>.
 
 ## Verify installation instructions
 
@@ -27,23 +24,22 @@ other things:
 
 </a>
 
-<a type="workspace/new-file">
+<a type="workspace/new-file" filename="README.md">
 
-In the documentation of this npm package, for example its **README.md** file, we
-want to document how to install this package. It would contain a section that
-looks something like this:
+In the documentation of this npm package, we want to document how to install
+this package. It would contain a section that looks something like this:
 
 ```md
 Install the foobar package by running:
 
 <pre type="npm/install">
-$ npm install foobar
+npm install foobar
 </pre>
 
 or with Yarn:
 
 <pre type="npm/install">
-$ yarn add foobar
+yarn add foobar
 </pre>
 ```
 
@@ -59,10 +55,10 @@ of the npm package.
 ## Verify exported binaries
 
 The <b type="action/name-full">npm/exported-executable</b> action verifies
-documentation of exported binaries of npm packages. Let's say the source code of
-our `foobar` package contains an executable file
-<b type="bundled-executable">bin/foo</b>, which is listed as a binary in its
-<a type="workspace/new-file">**package.json** file:
+documentation of exported binaries of npm packages. Let's say our `foobar`
+package provides an executable file <b type="bundled-executable">bin/foo</b>,
+which is listed as a binary in the <a type="workspace/new-file">**package.json**
+file:
 
 ```js
 {
@@ -75,28 +71,26 @@ our `foobar` package contains an executable file
 
 </a>
 
-<a type="workspace/additional-file-content">
+<a type="workspace/new-file" filename="README.md">
 
-The **README.md** file for the "foobar" package would document this binary
-something like this:
+The documentation for the "foobar" package would document this binary like this:
 
 ```md
 After you install the "foobar" package, you can run the
 <code type="npm/exported-executable">foo</code> command in the terminal.
 ```
 
-<a type="extension/run-textrunner">
-</a>
+<a type="extension/run-textrunner"></a>
 
 ### Verify installed binaries
 
 The <b type="action/name-full">npm/installed-executable</b> action verifies
-binaries installed by other npm packages. Let's say you developer instructions
-for a codebase that uses the <code type="create-npm-executable">cucumber</code>
-command provided by the npm [cucumber](https://www.npmjs.com/package/cucumber)
-package:
+binaries installed by other npm packages. Let's say you develop technical
+documentation for a codebase that uses the
+<code type="create-npm-executable">cucumber</code> command provided by the npm
+[cucumber](https://www.npmjs.com/package/@cucumber/cucumber) package:
 
-<a type="extension/runnable-region">
+<a type="workspace/new-file" filename="README.md">
 
 ```html
 To run the end-to-end tests, run
@@ -104,3 +98,69 @@ To run the end-to-end tests, run
 ```
 
 </a>
+
+<a type="extension/run-textrunner"></a>
+
+### Verify script names defined in package.json
+
+The <b type="action/name-full">npm/script-name</b> action verifies that you
+document scripts that your `package.json` file defines correctly.
+
+Let's say your npm package has this
+<a type="workspace/new-file">**package.json** file:
+
+```json
+{
+  "name": "foobar",
+  "scripts": {
+    "lint": "echo linting"
+  }
+}
+```
+
+</a>
+
+<a type="workspace/new-file" filename="README.md">
+
+And your documentation says:
+
+```html
+To run the linters, please run the
+<code type="npm/script-name">lint</code> script.
+```
+
+</a>
+
+<a type="extension/run-textrunner"></a>
+
+### Verify calls of scripts defined in package.json
+
+The <b type="action/name-full">npm/script-call</b> action verifies that you
+document calls of scripts defined in your `package.json` file correctly.
+
+Let's say your npm package has this
+<a type="workspace/new-file">**package.json** file:
+
+```json
+{
+  "name": "foobar",
+  "scripts": {
+    "lint": "echo linting"
+  }
+}
+```
+
+</a>
+
+<a type="workspace/new-file" filename="README.md">
+
+And your documentation says:
+
+```html
+To run the linters, please execute
+<code type="npm/script-call">npm run lint</code>.
+```
+
+</a>
+
+<a type="extension/run-textrunner"></a>

package/dist/actions/exported-executable.js

@@ -10,7 +10,10 @@ export async function exportedExecutable(action) {
     const packageJsonPath = action.configuration.sourceDir.joinStr("package.json");
     const pkgText = await fs.readFile(packageJsonPath, "utf-8");
     const pkgData = JSON.parse(pkgText);
-    if (!Object.keys(pkgData.bin).includes(commandName)) {
+    if (!pkgData.bin) {
+        throw new Error(`package.json does not export commands`);
+    }
+    if (!Object.keys(pkgData === null || pkgData === void 0 ? void 0 : pkgData.bin).includes(commandName)) {
         throw new Error(`package.json does not export a "${commandName}" command`);
     }
 }

package/dist/actions/installed-executable.js

@@ -1,7 +1,7 @@
 import * as color from "colorette";
 import { promises as fsp } from "fs";
 import * as path from "path";
-import * as textRunner from "text-runner-core";
+import * as textRunner from "text-runner-engine";
 import { trimDollar } from "../helpers/trim-dollar.js";
 export async function installedExecutable(action) {
     const commandName = trimDollar(action.region.text().trim());

package/dist/actions/script-call.js

@@ -0,0 +1,22 @@
+import * as color from "colorette";
+import { promises as fs } from "fs";
+import { startsWithNpmRun } from "../helpers/starts-with-npm-run.js";
+import { trimNpmRun } from "../helpers/trim-npm-run.js";
+export async function scriptCall(action) {
+    const call = action.region.text().trim();
+    if (call === "") {
+        throw new Error("No script call specified");
+    }
+    if (!startsWithNpmRun(call)) {
+        throw new Error(`Does not start with "npm run": ${call}`);
+    }
+    const want = trimNpmRun(call);
+    action.name(`verify call of npm package script ${color.cyan(want)}`);
+    const packageJsonPath = action.configuration.sourceDir.joinStr("package.json");
+    const pkgText = await fs.readFile(packageJsonPath, "utf-8");
+    const pkgData = JSON.parse(pkgText);
+    if (!Object.keys(pkgData.scripts).includes(want)) {
+        throw new Error(`package.json does not contain a "${want}" script`);
+    }
+}
+//# sourceMappingURL=script-call.js.map

package/dist/actions/script-name.js

@@ -0,0 +1,16 @@
+import * as color from "colorette";
+import { promises as fs } from "fs";
+export async function scriptName(action) {
+    const want = action.region.text().trim();
+    if (want === "") {
+        throw new Error("No script name specified");
+    }
+    action.name(`npm package has script ${color.cyan(want)}`);
+    const packageJsonPath = action.configuration.sourceDir.joinStr("package.json");
+    const pkgText = await fs.readFile(packageJsonPath, "utf-8");
+    const pkgData = JSON.parse(pkgText);
+    if (!Object.keys(pkgData.scripts).includes(want)) {
+        throw new Error(`package.json does not have a "${want}" script`);
+    }
+}
+//# sourceMappingURL=script-name.js.map

package/dist/helpers/starts-with-npm-run.js

@@ -0,0 +1,4 @@
+export function startsWithNpmRun(text) {
+    return text.startsWith("npm run ");
+}
+//# sourceMappingURL=starts-with-npm-run.js.map

package/dist/helpers/trim-npm-run.js

@@ -0,0 +1,4 @@
+export function trimNpmRun(call) {
+    return call.substring(8);
+}
+//# sourceMappingURL=trim-npm-run.js.map

package/dist/index.js

@@ -1,9 +1,13 @@
 import { exportedExecutable } from "./actions/exported-executable.js";
 import { install } from "./actions/install.js";
 import { installedExecutable } from "./actions/installed-executable.js";
+import { scriptCall } from "./actions/script-call.js";
+import { scriptName } from "./actions/script-name.js";
 export const textrunActions = {
     exportedExecutable,
     install,
     installedExecutable,
+    scriptCall,
+    scriptName
 };
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "textrun-npm",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "license": "ISC",
   "type": "module",
   "exports": "./dist/index.js",
@@ -10,23 +10,23 @@
   "scripts": {
     "build": "tsc -p tsconfig-build.json",
     "clean": "rm -rf dist",
-    "cuke": "cucumber-js --format=progress",
-    "doc": "text-run static --format=summary && text-run dynamic --format=progress",
-    "fix": "eslint --fix --ignore-pattern=dist/ . && prettier --write .",
-    "lint": "prettier -l . && eslint --ignore-pattern=dist/ . && depcheck --config=../.depcheckrc",
-    "unit": "env NODE_NO_WARNINGS=1 mocha --reporter=dot 'src/**/*.test.ts'"
+    "cuke": "yarn run build && cucumber-js --format=progress",
+    "doc": "yarn run build && text-runner --format=dot",
+    "fix": "eslint --fix --ignore-pattern=dist/ . && dprint fmt && sort-package-json --quiet",
+    "lint": "dprint check && sort-package-json --check --quiet && eslint --ignore-pattern=dist/ . && depcheck --config=../.depcheckrc",
+    "unit": "node --test --import tsx 'src/**/*.test.ts'"
   },
   "dependencies": {
     "colorette": "2.0.20",
-    "text-runner-core": "6.0.1"
+    "text-runner-engine": "7.1.0"
   },
   "devDependencies": {
     "shared-cucumber-steps": "*",
-    "text-runner": "6.0.1",
-    "textrun-action": "0.2.1",
-    "textrun-extension": "0.2.1",
-    "textrun-workspace": "0.2.1",
+    "text-runner": "7.1.0",
+    "textrun-action": "0.3.0",
+    "textrun-extension": "0.3.0",
+    "textrun-workspace": "0.3.0",
     "tsx": "4.19.3"
   },
-  "gitHead": "e479ff08fba71c7b2f6d1e3e14001b7818a38e12"
+  "gitHead": "bdf119a8e549f679af14f88952f7353648b50759"
 }