Start v2.0.0 (#963)

A quite significant rewrite of the library, but fundamentally the same in terms of functionality. The API has changed only slight (now requiring initialize before use), default behavior has changed all around, and overall the implementation is now safer by default. Key drivers for the changes in this release are: - Update runtime dependencies. - Bump the minimum supported Node.js version. - Safety by default. - Better performance on re-use. All changes were driven by these points. The vast majority or changes are refactoring to accomodate these points OR refactoring as a result of changes because of these points. A full list of (user-facing) changes can be found in the `CHANGELOG.md`. This commit was preceded by three release candidates(/pre-releases) that did not result in any problems being reported. Still, this changeset might not be perfect....
ericcornelissen · Sep 7, 2023 · 85a0743 · 85a0743
1 parent 4ae03a6
commit 85a0743
Show file tree

Hide file tree

Showing 105 changed files with 6,309 additions and 5,253 deletions.
diff --git a/.c8/compat.json b/.c8/compat.json
@@ -1,6 +1,6 @@
 {
   "all": true,
-  "include": ["index.cjs"],
+  "include": ["src/", "index.js"],
   "exclude": [],
   "check-coverage": false,
   "reports-dir": "_reports/coverage/compat",

diff --git a/.c8/integration-unix.json b/.c8/integration-unix.json
@@ -2,8 +2,7 @@
   "all": true,
   "include": ["src/", "index.js", "testing.js"],
   "exclude": ["src/win/", "src/win.js"],
-  "check-coverage": true,
-  "functions": 100,
+  "check-coverage": false,
   "reports-dir": "_reports/coverage/integration",
   "reporter": ["lcov", "text"]
 }
diff --git a/.c8/integration-win.json b/.c8/integration-win.json
@@ -2,8 +2,7 @@
   "all": true,
   "include": ["src/", "index.js", "testing.js"],
   "exclude": ["src/unix/", "src/unix.js"],
-  "check-coverage": true,
-  "functions": 100,
+  "check-coverage": false,
   "reports-dir": "_reports/coverage/integration",
   "reporter": ["lcov", "text"]
 }
diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml
@@ -227,10 +227,8 @@ jobs:
       fail-fast: false
       matrix:
         node-version:
-          - 10.13.0
-          - 12.0.0
-          - 14.0.0
-          - 16.0.0
+          - 14.18.0
+          - 16.13.0
           - 18.0.0
           - 19.0.0
           - 20.0.0
@@ -343,12 +341,13 @@ jobs:
       - name: Harden runner
         uses: step-security/harden-runner@8ca2b8b2ece13480cda6dacd3511b49857a23c09 # v2.5.1
         with:
-          disable-sudo: true
+          disable-sudo: false
           egress-policy: block
           allowed-endpoints: >
             actions-results-receiver-production.githubapp.com:443
             api.github.com:443
             artifactcache.actions.githubusercontent.com:443
+            azure.archive.ubuntu.com:80
             codecov.io:443
             github.com:443
             gitlab.com:443
@@ -366,6 +365,12 @@ jobs:
           node-version-file: .nvmrc
       - name: Install dependencies
         run: npm clean-install
+      - name: Install Zsh
+        if: ${{ matrix.name == 'Ubuntu' }}
+        run: sudo apt-get --assume-yes install zsh
+      - name: Install csh
+        if: ${{ matrix.name == 'Ubuntu' }}
+        run: sudo apt-get --assume-yes install csh
       - name: Run integration tests
         run: npm run coverage:integration
       - name: Upload coverage to Codecov
@@ -429,12 +434,13 @@ jobs:
       - name: Harden runner
         uses: step-security/harden-runner@8ca2b8b2ece13480cda6dacd3511b49857a23c09 # v2.5.1
         with:
-          disable-sudo: true
+          disable-sudo: false
           egress-policy: block
           allowed-endpoints: >
             actions-results-receiver-production.githubapp.com:443
             api.github.com:443
             artifactcache.actions.githubusercontent.com:443
+            azure.archive.ubuntu.com:80
             github.com:443
             gitlab.com:443
             nodejs.org:443
@@ -456,6 +462,10 @@ jobs:
             mutation-integration-
       - name: Install dependencies
         run: npm clean-install
+      - name: Install Zsh
+        run: sudo apt-get --assume-yes install zsh
+      - name: Install csh
+        run: sudo apt-get --assume-yes install csh
       - name: Run mutation tests
         run: npm run mutation:integration
       - name: Upload mutation report

diff --git a/.github/workflows/fuzz-no-shell.yml b/.github/workflows/fuzz-no-shell.yml
@@ -4,15 +4,15 @@ on:
     paths:
       - .github/workflows/fuzz-no-shell.yml
       - .github/workflows/reusable-fuzz.yml
-      - src/unix/dash.js
-      - src/win/cmd.js
+      - src/unix/no-shell.js
+      - src/win/no-shell.js
       - test/fuzz/**
   push:
     paths:
       - .github/workflows/fuzz-no-shell.yml
       - .github/workflows/reusable-fuzz.yml
-      - src/unix/dash.js
-      - src/win/cmd.js
+      - src/unix/no-shell.js
+      - src/win/no-shell.js
       - test/fuzz/**
     branches:
       - main
@@ -30,12 +30,12 @@ jobs:
       duration: 600 # seconds == 10 minutes
       os: ubuntu-22.04
       shell: "false"
-      targets: '["exec", "exec-file", "fork", "spawn"]'
+      targets: '["exec-file", "fork", "spawn"]'
   fuzz-windows:
     name: Fuzz Windows
     uses: ericcornelissen/shescape/.github/workflows/reusable-fuzz.yml@main
     with:
       duration: 600 # seconds == 10 minutes
       os: windows-2022
       shell: "false"
-      targets: '["exec", "exec-file", "fork", "spawn"]'
+      targets: '["exec-file", "fork", "spawn"]'
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,7 +7,16 @@ Versioning].
 
 ## [Unreleased]
 
-- _No changes yet_
+- BREAKING CHANGE: Change main API from an object to a class. ([#963])
+- BREAKING CHANGE: Drop support for Node.js `^10.13.0`, `^12`, `14.0.0` through
+  `14.18.0`, and `16.0.0` through `16.13.0`. ([#963])
+- BREAKING CHANGE: Drop the `interpolation` option. ([#963])
+- BREAKING CHANGE: Enable the `flagProtection` option by default. ([#963])
+- BREAKING CHANGE: Reject non-array inputs to `escapeAll` & `quoteAll`. ([#963])
+- BREAKING CHANGE: Reject unresolved shells. ([#963])
+- BREAKING CHANGE: Reject unsupported shells. ([#963])
+- Bump dependency `which` from v2 to v3. ([#963])
+- Don't resolve default shell when `shell` option is falsy. ([#963])
 
 ## [1.7.4] - 2023-08-21
 
@@ -285,6 +294,7 @@ Versioning].
 [#908]: https://github.com/ericcornelissen/shescape/pull/908
 [#909]: https://github.com/ericcornelissen/shescape/pull/909
 [#936]: https://github.com/ericcornelissen/shescape/pull/936
+[#963]: https://github.com/ericcornelissen/shescape/pull/963
 [#969]: https://github.com/ericcornelissen/shescape/pull/969
 [#982]: https://github.com/ericcornelissen/shescape/pull/982
 [#983]: https://github.com/ericcornelissen/shescape/pull/983

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -350,10 +350,6 @@ compatibility tests on all applicable Node.js versions. In the project's
 continuous integration the compatibility tests are run for all supported Node.js
 versions as well.
 
-Because compatibility tests need to run on all Node.js version back to v10.13.0,
-compatibility tests are written in CommonJS and run using [Mocha] v9 with the
-Node.js [assert package].
-
 ### Writing Tests
 
 Tests can be written in different ways and using different strategies. This
@@ -590,7 +586,6 @@ const john = "John Doe";
 ```
 
 [actionlint]: https://github.com/rhysd/actionlint
-[assert package]: https://nodejs.org/api/assert.html
 [ava]: https://github.com/avajs/ava
 [cc by-sa 4.0]: https://creativecommons.org/licenses/by-sa/4.0/
 [bug report]: https://github.com/ericcornelissen/shescape/issues/new?labels=bug&template=bug_report.md
@@ -609,7 +604,6 @@ const john = "John Doe";
 [markdown]: https://en.wikipedia.org/wiki/Markdown
 [markdownlint]: https://github.com/DavidAnson/markdownlint
 [mit license]: https://opensource.org/license/mit/
-[mocha]: https://mochajs.org/
 [mutation testing]: https://en.wikipedia.org/wiki/Mutation_testing
 [node.js]: https://nodejs.org/en/
 [npm]: https://www.npmjs.com/

diff --git a/README.md b/README.md
@@ -45,10 +45,16 @@ opening [an issue].
 2. Import `shescape`:
 
    ```javascript
-   import * as shescape from "shescape";
+   import { Shescape } from "shescape";
    ```
 
-3. Use `shescape`.
+3. Initialize `Shescape`.
+
+   ```javascript
+   const shescape = new Shescape(/* options */);
+   ```
+
+4. Use `shescape`.
 
 ### Recipes
 

diff --git a/bench/bench.js b/bench/bench.js
@@ -14,6 +14,7 @@ import {
   binZsh,
 } from "../test/_constants.js";
 
+import { noShell } from "../src/options.js";
 import * as unix from "../src/unix.js";
 import * as win from "../src/win.js";
 
@@ -27,88 +28,44 @@ const suite = new Benchmark.Suite("escapeShellArg", {
   },
 });
 
-suite.add(`unix, ${binBash}, ${sampleArg}`, () => {
-  const escapeShellArg = unix.getEscapeFunction(binBash, {
-    interpolation: true,
-  });
-  escapeShellArg(sampleArg);
+const escapeShellArgNoShellUnix = unix.getEscapeFunction(noShell);
+suite.add(`unix, no shell, ${sampleArg}`, () => {
+  escapeShellArgNoShellUnix(sampleArg);
 });
 
-const escapeShellArgBashNew = unix.getEscapeFunction(binBash, {
-  interpolation: true,
-});
-suite.add(`unix (new), ${binBash}, ${sampleArg}`, () => {
-  escapeShellArgBashNew(sampleArg);
+const escapeShellArgBash = unix.getEscapeFunction(binBash);
+suite.add(`unix, ${binBash}, ${sampleArg}`, () => {
+  escapeShellArgBash(sampleArg);
 });
 
+const escapeShellArgCsh = unix.getEscapeFunction(binCsh);
 suite.add(`unix, ${binCsh}, ${sampleArg}`, () => {
-  const escapeShellArg = unix.getEscapeFunction(binCsh, {
-    interpolation: true,
-  });
-  escapeShellArg(sampleArg);
-});
-
-const escapeShellArgCshNew = unix.getEscapeFunction(binCsh, {
-  interpolation: true,
-});
-suite.add(`unix (new), ${binCsh}, ${sampleArg}`, () => {
-  escapeShellArgCshNew(sampleArg);
+  escapeShellArgCsh(sampleArg);
 });
 
+const escapeShellArgDash = unix.getEscapeFunction(binDash);
 suite.add(`unix, ${binDash}, ${sampleArg}`, () => {
-  const escapeShellArg = unix.getEscapeFunction(binDash, {
-    interpolation: true,
-  });
-  escapeShellArg(sampleArg);
-});
-
-const escapeShellArgDashNew = unix.getEscapeFunction(binDash, {
-  interpolation: true,
-});
-suite.add(`unix (new), ${binDash}, ${sampleArg}`, () => {
-  escapeShellArgDashNew(sampleArg);
+  escapeShellArgDash(sampleArg);
 });
 
+const escapeShellArgZsh = unix.getEscapeFunction(binZsh);
 suite.add(`unix, ${binZsh}, ${sampleArg}`, () => {
-  const escapeShellArg = unix.getEscapeFunction(binZsh, {
-    interpolation: true,
-  });
-  escapeShellArg(sampleArg);
+  escapeShellArgZsh(sampleArg);
 });
 
-const escapeShellArgZshNew = unix.getEscapeFunction(binZsh, {
-  interpolation: true,
-});
-suite.add(`unix (new), ${binZsh}, ${sampleArg}`, () => {
-  escapeShellArgZshNew(sampleArg);
+const escapeShellArgNoShellWin = win.getEscapeFunction(noShell);
+suite.add(`win, no shell, ${sampleArg}`, () => {
+  escapeShellArgNoShellWin(sampleArg);
 });
 
+const escapeShellArgCmd = win.getEscapeFunction(binCmd);
 suite.add(`win, ${binCmd}, ${sampleArg}`, () => {
-  const escapeShellArg = win.getEscapeFunction(binCmd, {
-    interpolation: true,
-  });
-  escapeShellArg(sampleArg);
-});
-
-const escapeShellArgCmdNew = win.getEscapeFunction(binCmd, {
-  interpolation: true,
-});
-suite.add(`win (new), ${binCmd}, ${sampleArg}`, () => {
-  escapeShellArgCmdNew(sampleArg);
+  escapeShellArgCmd(sampleArg);
 });
 
+const escapeShellArgPowerShell = win.getEscapeFunction(binPowerShell);
 suite.add(`win, ${binPowerShell}, ${sampleArg}`, () => {
-  const escapeShellArg = win.getEscapeFunction(binPowerShell, {
-    interpolation: true,
-  });
-  escapeShellArg(sampleArg);
-});
-
-const escapeShellArgPowerShellNew = win.getEscapeFunction(binPowerShell, {
-  interpolation: true,
-});
-suite.add(`win (new), ${binPowerShell}, ${sampleArg}`, () => {
-  escapeShellArgPowerShellNew(sampleArg);
+  escapeShellArgPowerShell(sampleArg);
 });
 
 suite.run();