doc,test: clarify --eval syntax for leading '-' scripts

If the script passed to --eval starts with a hyphen, the CLI parser
treats it as another option flag. Document the --eval=<script> form
as the workaround and add tests for --eval=-42, --eval=-0, and the
-e -p missing-argument error.

Co-authored-by: jorge guerrero <grrr.jrg@gmail.com>
Refs: #43397
Refs: #61962
PR-URL: #62244
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>

Author: 2 people

doc/api/cli.md

@@ -943,6 +943,9 @@ changes:
 Evaluate the following argument as JavaScript. The modules which are
 predefined in the REPL can also be used in `script`.
 
+If `script` starts with `-`, pass it using `=` (for example,
+`node --print --eval=-42`) so it is parsed as the value of `--eval`.
+
 On Windows, using `cmd.exe` a single quote will not work correctly because it
 only recognizes double `"` for quoting. In Powershell or Git bash, both `'`
 and `"` are usable.

test/parallel/test-cli-eval.js

@@ -115,6 +115,26 @@ child.exec(...common.escapePOSIXShell`"${process.execPath}" -p "\\-42"`, common.
   assert.strictEqual(stderr, '');
 }));
 
+// Eval expressions that start with '-' can be passed with '='.
+child.exec(...common.escapePOSIXShell`"${process.execPath}" --print --eval=-42`, common.mustSucceed((stdout, stderr) => {
+  assert.strictEqual(stdout, '-42\n');
+  assert.strictEqual(stderr, '');
+}));
+
+// Edge case: negative zero should preserve its sign when printed.
+child.exec(...common.escapePOSIXShell`"${process.execPath}" --print --eval=-0`, common.mustSucceed((stdout, stderr) => {
+  assert.strictEqual(stdout, '-0\n');
+  assert.strictEqual(stderr, '');
+}));
+
+// Nearby-path safety: option-looking values should still be rejected with -e.
+child.exec(...common.escapePOSIXShell`"${process.execPath}" -e -p`, common.mustCall((err, stdout, stderr) => {
+  assert.strictEqual(err.code, 9);
+  assert.strictEqual(stdout, '');
+  assert.strictEqual(stderr.trim(),
+                     `${process.execPath}: -e requires an argument`);
+}));
+
 // Long output should not be truncated.
 child.exec(...common.escapePOSIXShell`"${process.execPath}" -p "'1'.repeat(1e5)"`, common.mustSucceed((stdout, stderr) => {
   assert.strictEqual(stdout, `${'1'.repeat(1e5)}\n`);