Improve overall escaping (#2651)

Backports 43d70b5 to
the v2 release line.

Co-authored-by: oran-s <oran@koi.ai>
Assisted-by: Claude Mythos

Author: ericcornelissen

CHANGELOG.md

@@ -9,7 +9,10 @@ Versioning].
 
 ## Unreleased
 
-- _No changes yet_
+- Correct escaping of `(` and `)` for CMD. ([#2651])
+- Correct escaping of `~` for Dash and Zsh. ([#2651])
+- Correct escaping of `^`, `~`, and `#` for Zsh with `EXTENDED_GLOB`. ([#2651])
+- Optimize flag protection implementation. ([#2651])
 
 ## 2.1.13 (2026-06-13)
 
@@ -421,6 +424,7 @@ Versioning].
 [#2490]: https://github.com/ericcornelissen/shescape/pull/2490
 [#2520]: https://github.com/ericcornelissen/shescape/pull/2520
 [#2534]: https://github.com/ericcornelissen/shescape/pull/2534
+[#2651]: https://github.com/ericcornelissen/shescape/pull/2651
 [552e8ea]: https://github.com/ericcornelissen/shescape/commit/552e8eab56861720b1d4e5474fb65741643358f9
 [keep a changelog]: https://keepachangelog.com/en/1.0.0/
 [semantic versioning]: https://semver.org/spec/v2.0.0.html

config/eslint.js

@@ -716,7 +716,7 @@ export default [
       "no-magic-numbers": [
         "error",
         {
-          ignore: [0, 1, 0xa0],
+          ignore: [0, 1, 2, 0xa0],
         },
       ],
       "no-misleading-character-class": ["error"],

src/internal/compose.js

@@ -27,12 +27,17 @@ export function compose({ escapeFn, flagFn, quoteFn }) {
   }
 
   return (arg) => {
-    let [preFlag, , ...rest] = flagFn(arg);
-    while (rest.length > 0 && escapeFn(preFlag) === "") {
-      arg = rest.join("");
-      [preFlag, , ...rest] = rest;
+    const fragments = flagFn(arg);
+
+    let idx = 0;
+    for (; idx < fragments.length - 2; idx += 2) {
+      const escapedFragment = escapeFn(fragments[idx]);
+      if (escapedFragment !== "") {
+        break;
+      }
     }
 
+    arg = fragments.slice(idx).join("");
     return escape(arg);
   };
 }

src/internal/unix/dash.js

@@ -16,7 +16,7 @@ export function getEscapeFunction() {
   const newlines = new RegExp(/\n/g);
   const backslashes = new RegExp(/\\/g);
   const comments = new RegExp(/(^|\s)#/g);
-  const home = new RegExp(/(^|\s)~/g);
+  const home = new RegExp(/(^|[\s:=])~/g);
   const specials = new RegExp(/(["$&'()*;<>?[\]`|])/g);
   const whitespace = new RegExp(/([\t ])/g);
   return (arg) =>

src/internal/unix/zsh.js

@@ -15,17 +15,15 @@ export function getEscapeFunction() {
   const controls = new RegExp(/[\0\u0008\r\u001B\u009B]/g);
   const newlines = new RegExp(/\n/g);
   const backslashes = new RegExp(/\\/g);
-  const comments = new RegExp(/(^|\s)#/g);
-  const expansions = new RegExp(/(^|\s)([=~])/g);
-  const specials = new RegExp(/(["$&'()*;<>?[\]`{|}])/g);
+  const expansions = new RegExp(/(^|[\s:=])=/g);
+  const specials = new RegExp(/(["#$&'()*;<>?[\]^`{|}~])/g);
   const whitespace = new RegExp(/([\t ])/g);
   return (arg) =>
     arg
       .replace(controls, "")
       .replace(newlines, " ")
       .replace(backslashes, "\\\\")
-      .replace(comments, "$1\\#")
-      .replace(expansions, "$1\\$2")
+      .replace(expansions, "$1\\=")
       .replace(specials, "\\$1")
       .replace(whitespace, "\\$1");
 }

src/internal/win/cmd.js

@@ -14,7 +14,7 @@ import RegExp from "../regexp.cjs";
 export function getEscapeFunction() {
   const controls = new RegExp(/[\0\u0008\r\u001B\u009B]/g);
   const newlines = new RegExp(/\n/g);
-  const specials = new RegExp(/([%&<>^|])/g);
+  const specials = new RegExp(/([%&()<>^|])/g);
   const quotes = new RegExp(/"/g);
   const backslashes = new RegExp(/(^|[^\\])(\\*)\0/g);
   return (arg) =>