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

[jorgitin02]

Refs: #43397

Summary

• remove the parser heuristic added in the previous revision for -e -<text>
• document the supported form for leading-hyphen eval expressions: --eval=<script> (for example --eval=-42)
• add/adjust tests in test/parallel/test-cli-eval.js to cover --eval=-42, --eval=-0, and keep -e -p as a missing-argument error

Testing

• python3 tools/test.py test/parallel/test-cli-eval.js
• python3 tools/test.py --repeat=5 test/parallel/test-cli-eval.js
• python3 tools/test.py test/parallel/test-cli-bad-options.js
• make lint-js NODE=/opt/homebrew/bin/node
• make doc-only NODE=/opt/homebrew/bin/node
• make lint-md LINT_MD_TARGETS=doc/api/cli.md NODE=/opt/homebrew/bin/node

[mcollina]

lgtm

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/71431/

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.77%. Comparing base (da5efc4) to head (ad880ae).
⚠️ Report is 21 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #61962      +/-   ##
==========================================
+ Coverage   88.84%   89.77%   +0.93%     
==========================================
  Files         674      674              
  Lines      204957   205613     +656     
  Branches    39309    39424     +115     
==========================================
+ Hits       182087   184598    +2511     
+ Misses      15088    13266    -1822     
+ Partials     7782     7749      -33     

see 187 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[addaleax]

From the ticket:

For users who prefer setting mandatory option arguments rather than positional arguments, node --print --eval=-42 already works. :)

I think that's the right solution here. Adding behavior that depends on the specific text passed to the flag is going to be dangerous; now you cannot know anymore whether node -e -<text> will work or throw, it's going to depend on the specific value of text (i.e. the behavior is less consistent now, not more).

[jorgitin02]

Thanks for the review feedback. I pushed a follow-up that removes the -e -<text> parser heuristic entirely and aligns with the suggested approach from the issue discussion: documenting and testing --eval=<script> for leading-hyphen expressions (for example --eval=-42).

I also kept the safety behavior for -e -p (still a missing-argument error).

Could you please take another look when you have a moment?

[jorgitin02]

Heads up: all GitHub Actions workflows for this latest push are currently in action_required state (0s), so no CI jobs have actually started yet.

I don't have permissions to rerun/approve those runs from my fork. Could a maintainer please click Approve and run workflows?

For local verification on my side, I ran:

• python3 tools/test.py test/parallel/test-cli-eval.js
• python3 tools/test.py --repeat=5 test/parallel/test-cli-eval.js
• python3 tools/test.py test/parallel/test-cli-bad-options.js
• make lint-js NODE=/opt/homebrew/bin/node
• make doc-only NODE=/opt/homebrew/bin/node
• make lint-md LINT_MD_TARGETS=doc/api/cli.md NODE=/opt/homebrew/bin/node

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/71448/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/71456/