refactor!: Clarify build-time–run-time distinction (#104)

This PR modifies the public API in an attempt to clarify the distinction between the build-time and the run-time parts of Userscripter. This should help users not accidentally import a build-time module in run-time code, which results in a completely incomprehensible wall of error messages since #96 (v3.0.0).

Consumers will have to adapt as follows:

  * ```diff
    -import … from "userscripter/build";
    +import … from "userscripter/build-time";
    ```

  * ```diff
    -import … from "userscripter/lib/foo";
    +import … from "userscripter/run-time/foo";
    ```

This command should make the required changes in a typical Git-tracked userscript:

```bash
for f in $(git ls-files "$(git rev-parse --show-toplevel)"); do
  sed -i 's#userscripter/build#userscripter/build-time#g' $f
  sed -i 's#userscripter/lib#userscripter/run-time#g' $f
done
```

💡 `git show --color-words='build-time|\w+|.'`

.eslintignore

@@ -1,3 +1,3 @@
 # Compiled files:
-/build/
-/lib/
+/build-time/
+/run-time/

.gitignore

@@ -1,5 +1,5 @@
 node_modules/
-lib/**
-build/**
+run-time/**
+build-time/**
 *.tgz
 *.html

README.md

@@ -73,7 +73,7 @@ USERSCRIPTER_MODE=production USERSCRIPTER_VERBOSE=true npm run build
 You can also customize the object _returned_ from `createWebpackConfig` in `webpack.config.ts`:
 
 ```typescript
-import { createWebpackConfig } from 'userscripter/build';
+import { createWebpackConfig } from 'userscripter/build-time';
 
 const webpackConfig = createWebpackConfig({
     // …

__tests__/api.test.ts

@@ -1,11 +1,11 @@
 import * as fs from "fs";
 import * as path from "path";
 
-import * as index from "../src/lib";
-import * as environment from "../src/lib/environment";
-import * as errors from "../src/lib/errors";
-import * as operations from "../src/lib/operations";
-import * as stylesheets from "../src/lib/stylesheets";
+import * as index from "../src/run-time";
+import * as environment from "../src/run-time/environment";
+import * as errors from "../src/run-time/errors";
+import * as operations from "../src/run-time/operations";
+import * as stylesheets from "../src/run-time/stylesheets";
 
 it("exposes the intended API", () => {
   const a: environment.Condition = environment.ALWAYS;
@@ -27,8 +27,8 @@ it("exposes the intended API", () => {
   expect(stylesheets.disable).toBeDefined();
 });
 
-it("exposes everything in lib in index.ts", async () => {
-  const filenames = await fs.promises.readdir(path.resolve(__dirname, "..", "src", "lib"));
+it("exposes everything in run-time in index.ts", async () => {
+  const filenames = await fs.promises.readdir(path.resolve(__dirname, "..", "src", "run-time"));
   expect(filenames).toEqual([
     "environment.ts",
     "errors.ts",

__tests__/operations.test.ts

@@ -1,14 +1,14 @@
-import { operations } from "../src/lib";
+import { operations } from "../src/run-time";
 import {
   ALWAYS,
   DOMCONTENTLOADED,
-} from "../src/lib/environment";
-import { failureDescriber } from "../src/lib/errors";
+} from "../src/run-time/environment";
+import { failureDescriber } from "../src/run-time/errors";
 import {
   Operation,
   OperationAndFailure,
   operation,
-} from "../src/lib/operations";
+} from "../src/run-time/operations";
 
 const mockConsole = {
   log: (message: string) => void message,

__tests__/sass.test.ts

@@ -1,7 +1,7 @@
 import sass from "sass";
 
-import { getGlobalFrom, withDartSassEncodedParameters } from "../src/build/internal/sass";
-import { DEFAULT_BUILD_CONFIG } from "../src/build/internal/webpack";
+import { getGlobalFrom, withDartSassEncodedParameters } from "../src/build-time/internal/sass";
+import { DEFAULT_BUILD_CONFIG } from "../src/build-time/internal/webpack";
 
 import * as CONFIG from "./config-example";
 

package.json

@@ -22,48 +22,48 @@
   "bugs": {
     "url": "https://github.com/simonalling/userscripter/issues"
   },
-  "main": "lib/index",
+  "main": "run-time/index",
   "exports": {
     ".": {
-      "import": "./lib/index.mjs",
-      "require": "./lib/index.js"
+      "import": "./run-time/index.mjs",
+      "require": "./run-time/index.js"
     },
-    "./build": {
-      "import": "./build/index.mjs",
-      "require": "./build/index.js"
+    "./build-time": {
+      "import": "./build-time/index.mjs",
+      "require": "./build-time/index.js"
     },
-    "./lib/*": {
-      "import": "./lib/*.mjs",
-      "require": "./lib/*.js"
+    "./run-time/*": {
+      "import": "./run-time/*.mjs",
+      "require": "./run-time/*.js"
     }
   },
   "typesVersions": {
     "*": {
-      "build": [
-        "./build/index.d.ts"
+      "build-time": [
+        "./build-time/index.d.ts"
       ],
-      "lib/*": [
-        "./lib/*.d.ts"
+      "run-time/*": [
+        "./run-time/*.d.ts"
       ],
       "*": [
         "This prevents imports of internal modules from compiling in TypeScript."
       ]
     }
   },
   "files": [
-    "build/*",
-    "lib/*"
+    "build-time/*",
+    "run-time/*"
   ],
   "scripts": {
     "build-cjs": "npm run clean && npm run compile-cjs",
     "build-esm": "npm run clean && npm run compile-esm",
     "compile-cjs": "tsc -d --module CommonJS -p .",
     "compile-esm": "tsc -d -p .",
     "build": "npm run clean && npm run compile-esm && npm run rename && npm run compile-cjs",
-    "clean": "rimraf lib build",
+    "clean": "rimraf run-time build-time",
     "lint": "eslint . --ext .ts",
     "prepublishOnly": "npm run verify && cli-confirm 'Publish?'",
-    "rename": "renamer --force --find \"/\\.js$/\" --replace \".mjs\" \"lib/**\" \"build/**\"",
+    "rename": "renamer --force --find \"/\\.js$/\" --replace \".mjs\" \"run-time/**\" \"build-time/**\"",
     "test": "npm run lint && npm run jest",
     "jest": "jest --config ./jest.config.mjs",
     "verify": "npm ci && repository-check-dirty && npm run build && npm test && npm pack"