debugger: add --help to node inspect and improve docs

- Add `--help` / `-h` to `node inspect` covering both interactive and
non-interactive probe modes. The help text is printed when
`--help`/`-h` appears before any positional argument to avoid
hijacking `--help` passed to a child script.
- Improve the documentation of probe mode and add examples, explain
same-location probe coalescing, TDZ caveat for let/const bindings,
basename matching and exit code behavior. Also move it to a
section parallel to interactive mode. Remove recommendation of
evaluating structured expressions as that is prone to missing
info in JSON mode.
Drive-by: When probe mode exits due to invalid arguments, exit with
`kInvalidCommandLineArgument` (9) instead of `kGenericUserError` (1).
Signed-off-by: Joyee Cheung <joyeec9h3@gmail.com>
PR-URL: #63201
Reviewed-By: Jan Martin <jan.krems@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Aviv Keller <me@aviv.sh>

Author: joyeecheung

doc/api/debugger.md

@@ -27,10 +27,11 @@ const {
 constInspectClient=require('internal/debugger/inspect_client');
 const{
  launchChildProcess,
-writeUsageAndExit,
+writeInspectUsageAndExit,
 }=require('internal/debugger/inspect_helpers');
 const{
- startProbeMode,
+ parseProbeTokens,
+ runProbeMode,
 }=require('internal/debugger/inspect_probe');
 constcreateRepl=require('internal/debugger/inspect_repl');
 
@@ -39,6 +40,7 @@ const debuglog = util.debuglog('inspect');
 const{
 exitCodes: {
  kGenericUserError,
+ kInvalidCommandLineArgument,
  kNoFailure,
 },
 }=internalBinding('errors');
@@ -220,7 +222,7 @@ class NodeInspector {
 }
 }
 
-functionparseArgv(args){
+functionparseInteractiveArgs(args){
 consttarget=ArrayPrototypeShift(args);
 lethost='127.0.0.1';
 letport=9229;
@@ -264,20 +266,83 @@ function parseArgv(args) {
 };
 }
 
+constkInspectArgOptions={
+__proto__: null,
+expr: {type: 'string'},
+help: {type: 'boolean',short: 'h'},
+json: {type: 'boolean'},
+// Port and timeout use type 'string' because parseArgs has no
+// numeric type; the values are parsed to integers by parseProbeTokens().
+port: {type: 'string'},
+preview: {type: 'boolean'},
+probe: {type: 'string'},
+timeout: {type: 'string'},
+};
+
+// Parses args once and decides whether the user wants the inspect help, probe
+// mode, or interactive mode. The mode is determined by the first option,
+// option-terminator, or positional token in the input.
+//
+// Returns one of:
+// { mode: 'help' }
+// { mode: 'probe', tokens, args }
+// { mode: 'interactive' }
+functionparseInspectMode(args){
+const{ tokens }=util.parseArgs({
+ args,
+allowPositionals: true,
+options: kInspectArgOptions,
+strict: false,
+tokens: true,
+});
+
+for(consttokenoftokens){
+if(token.kind==='option'){
+if(token.name==='help')return{mode: 'help'};
+if(token.name==='probe'){
+// `--probe --help` / `--probe -h` (no value) consumes the help flag
+// as the probe's "value"; surface help instead of a probe error.
+if(!token.inlineValue&&
+(token.value==='--help'||token.value==='-h')){
+return{mode: 'help'};
+}
+return{mode: 'probe', tokens, args };
+}
+}
+if(token.kind==='option-terminator'||token.kind==='positional'){
+break;
+}
+}
+return{mode: 'interactive'};
+}
+
 functionstartInspect(argv=ArrayPrototypeSlice(process.argv,2),
 stdin=process.stdin,
 stdout=process.stdout){
 constinvokedAs=`${process.argv0}${process.argv[1]}`;
 
 if(argv.length<1){
-writeUsageAndExit(invokedAs);
+writeInspectUsageAndExit(invokedAs,undefined,kInvalidCommandLineArgument);
 }
 
-if(startProbeMode(invokedAs,argv,stdout)){
+constparsed=parseInspectMode(argv);
+
+if(parsed.mode==='help'){
+writeInspectUsageAndExit(invokedAs);
+}
+
+if(parsed.mode==='probe'){
+letprobeOptions;
+try{
+probeOptions=parseProbeTokens(parsed.tokens,parsed.args);
+}catch(error){
+writeInspectUsageAndExit(invokedAs,error.message,kInvalidCommandLineArgument);
+}
+runProbeMode(stdout,probeOptions);
 return;
 }
 
-constoptions=parseArgv(argv);
+constoptions=parseInteractiveArgs(argv);
 constinspector=newNodeInspector(options,stdin,stdout);
 
 stdin.resume();

lib/internal/debugger/inspect.js

@@ -61,21 +61,67 @@ function ensureTrailingNewline(text) {
 returnStringPrototypeEndsWith(text,'\n') ? text : `${text}\n`;
 }
 
-functionwriteUsageAndExit(invokedAs,message,exitCode=kInvalidCommandLineArgument){
+functionwriteInspectUsageAndExit(invokedAs,message,exitCode){
+constcode=exitCode??(message ? kInvalidCommandLineArgument : 0);
+constout=code===0 ? process.stdout : process.stderr;
 if(message){
-process.stderr.write(`${message}\n`);
+out.write(`${message}\n`);
 }
-consttext=
-`Usage: ${invokedAs} script.js\n`+
-` ${invokedAs} <host>:<port>\n`+
-` ${invokedAs} --port=<port> Use 0 for random port assignment\n`+
-` ${invokedAs} -p <pid>\n`+
-` ${invokedAs} [--json] [--timeout=<ms>] [--port=<port>] `+
-`--probe <file>:<line>[:<col>] --expr <expr> `+
-`[--probe <file>:<line>[:<col>] --expr <expr> ...] `+
-`[--] [<node-option> ...] <script.js> [args...]\n`;
-process.stderr.write(text);
-process.exit(exitCode);
+out.write(`Usage: ${invokedAs} [--port=<port>] [<node-option> ...]
+ [<script> [<script-args>] | <host>:<port> | -p <pid>]
+${invokedAs} --probe <file>:<line>[:<col>] --expr <expr>
+ [--probe <file>:<line>[:<col>] --expr <expr> ...]
+ [--json] [--preview] [--timeout=<ms>] [--port=<port>]
+ [--] [<node-option> ...] <script> [<script-args> ...]
+
+Interactive mode: Starts a live debugging session.
+
+Example:
+ $ node inspect script.js
+
+Options:
+ --port=<port> Inspector port for the debuggee (default: 9229)
+ <script> The script to launch and debug.
+ <host>:<port> Remote debugger to connect to.
+ -p <pid> Attach to a running Node.js process by PID
+
+Semantics:
+* If neither a script nor a host:port nor -p is provided, node inspect starts
+ the REPL.
+
+Non-interactive probe mode: Evaluates expressions whenever execution reaches
+specified source locations and prints all the evaluation results to stdout.
+
+Example:
+ $ node inspect --probe app.js:10 --expr "user"
+ --probe src/utils.js:5:15 --expr "config.options"
+ --json --preview -- --no-warnings app.js --arg-for-app=foo
+
+Options:
+ --probe <file>:<line>[:<col>]
+ Source location of the probe (1-based, col defaults
+ to 1). Matches by file basename, use a fuller path to
+ disambiguate. Must be immediately followed by --expr.
+ --expr <expr> Expression to evaluate in the lexical scope of the
+ preceding --probe each time execution reaches it.
+ Avoid probing let/const-bound variables at their
+ declaration site or a ReferenceError may be thrown.
+ --json Output JSON if specified, otherwise human-readable text.
+ --preview Include V8 object previews in JSON output.
+ --timeout <ms> Global session timeout (default: 30000).
+ --port <port> Inspector port for the debuggee (default: 0 = random).
+
+Semantics:
+* Multiple --probe/--expr pairs are allowed. Same-location --probes share
+ a pause and scope, their --exprs are evaluated in command-line order.
+* Use -- before any Node.js flags intended for the child process.
+* Target errors are surfaced in the report as a terminal 'error' event.
+ The probing process exits 0 unless it encounters an error itself.
+
+See https://nodejs.org/api/debugger.html for details, including the
+probe output schema.
+`);
+process.exit(code);
 }
 
 asyncfunctionlaunchChildProcess(childArgs,inspectHost,inspectPort,
@@ -128,5 +174,5 @@ async function launchChildProcess(childArgs, inspectHost, inspectPort,
 module.exports={
  ensureTrailingNewline,
  launchChildProcess,
-writeUsageAndExit,
+writeInspectUsageAndExit,
 };

lib/internal/debugger/inspect_helpers.js

@@ -23,14 +23,12 @@ const {
 }=primordials;
 
 const{ clearTimeout, setTimeout }=require('timers');
-constutil=require('util');
 const{ SideEffectFreeRegExpPrototypeSymbolReplace }=require('internal/util');
 
 constInspectClient=require('internal/debugger/inspect_client');
 const{
  ensureTrailingNewline,
  launchChildProcess,
- writeUsageAndExit,
 }=require('internal/debugger/inspect_helpers');
 
 const{ERR_DEBUGGER_STARTUP_ERROR}=require('internal/errors').codes;
@@ -46,17 +44,6 @@ const kProbeVersion = 1;
 constkProbeDisconnectSentinel='Waiting for the debugger to disconnect...';
 constkDigitsRegex=/^\d+$/;
 constkInspectPortRegex=/^--inspect-port=(\d+)$/;
-constkProbeArgOptions={
-__proto__: null,
-expr: {type: 'string'},
-json: {type: 'boolean'},
-// Port and timeout use type 'string' because parseArgs has no
-// numeric type; the values are parsed to integers in parseProbeArgv().
-port: {type: 'string'},
-preview: {type: 'boolean'},
-probe: {type: 'string'},
-timeout: {type: 'string'},
-};
 
 functionparseUnsignedInteger(value,name,allowZero=false){
 if(typeofvalue!=='string'||RegExpPrototypeExec(kDigitsRegex,value)===null){
@@ -274,29 +261,7 @@ function buildProbeTextReport(report) {
 returnensureTrailingNewline(ArrayPrototypeJoin(lines,'\n'));
 }
 
-functionhasTopLevelProbeOption(args){
-const{ tokens }=util.parseArgs({
- args,
-allowPositionals: true,
-options: kProbeArgOptions,
-strict: false,
-tokens: true,
-});
-
-for(consttokenoftokens){
-if(token.kind==='option'&&token.name==='probe'){
-returntrue;
-}
-
-if(token.kind==='option-terminator'||token.kind==='positional'){
-returnfalse;
-}
-}
-
-returnfalse;
-}
-
-functionparseProbeArgv(args){
+functionparseProbeTokens(tokens,args){
 letport=0;
 letpreview=false;
 lettimeout=kProbeDefaultTimeout;
@@ -307,14 +272,6 @@ function parseProbeArgv(args) {
 letexpectedExprIndex=-1;
 constprobes=[];
 
-const{ tokens }=util.parseArgs({
- args,
-allowPositionals: true,
-options: kProbeArgOptions,
-strict: false,
-tokens: true,
-});
-
 for(consttokenoftokens){
 if(token.kind==='option-terminator'){
 sawSeparator=true;
@@ -764,22 +721,7 @@ async function runProbeMode(stdout, probeOptions) {
 }
 }
 
-functionstartProbeMode(invokedAs,args,stdout){
-if(!hasTopLevelProbeOption(args)){
-returnfalse;
-}
-
-letprobeOptions;
-try{
-probeOptions=parseProbeArgv(args);
-}catch(error){
-writeUsageAndExit(invokedAs,error.message,kGenericUserError);
-}
-
-runProbeMode(stdout,probeOptions);
-returntrue;
-}
-
 module.exports={
- startProbeMode,
+ parseProbeTokens,
+ runProbeMode,
 };

lib/internal/debugger/inspect_probe.js

@@ -0,0 +1,34 @@
+// Tests that --help / -h are forwarded to the debuggee when a script is
+// also passed, instead of being hijacked as the inspect help flag.
+
+import{skipIfInspectorDisabled}from'../common/index.mjs';
+
+skipIfInspectorDisabled();
+
+import*asfixturesfrom'../common/fixtures.mjs';
+importstartCLIfrom'../common/debugger.js';
+
+importassertfrom'assert';
+
+asyncfunctiongetEvaluatedArgv(flag){
+constscript=fixtures.path('debugger','empty.js');
+constcli=startCLI([script,flag]);
+try{
+awaitcli.waitForInitialBreak();
+awaitcli.waitForPrompt();
+awaitcli.command('exec process.argv');
+returncli.output;
+}finally{
+awaitcli.quit();
+}
+}
+
+asyncfunctioncheckForwardedHelp(flag){
+constoutput=awaitgetEvaluatedArgv(flag);
+assert(output.includes(`'${flag}'`),
+`expected debuggee process.argv to include "${flag}", got:\n${output}`);
+assert.doesNotMatch(output,/Usage:.+inspect/);
+}
+
+awaitcheckForwardedHelp('--help');
+awaitcheckForwardedHelp('-h');

test/parallel/test-debugger-inspect-help-forwarding.mjs

@@ -0,0 +1,37 @@
+'use strict';
+
+// Tests that `node inspect` help text is printed when
+// `--help` / `-h` is passed and there is no script,
+// or when there are no additional arguments.
+constcommon=require('../common');
+common.skipIfInspectorDisabled();
+
+const{
+ spawnSyncAndAssert,
+ spawnSyncAndExit,
+}=require('../common/child_process');
+
+constusageRegex=/^Usage:.+inspect.*debugger\.html/ms;
+
+// --help / -h prints the usage to stdout and exits with code 0,
+// for both interactive and probe-mode invocations.
+consthelpArgs=[
+['inspect','--help'],
+['inspect','-h'],
+['inspect','--probe','--help'],
+['inspect','--probe','-h'],
+];
+
+for(constargsofhelpArgs){
+spawnSyncAndAssert(process.execPath,args,{
+stdout: usageRegex,
+});
+}
+
+// `node inspect` with no args prints the usage to stderr and exits
+// with kInvalidCommandLineArgument (9).
+spawnSyncAndExit(process.execPath,['inspect'],{
+status: 9,
+signal: null,
+stderr: usageRegex,
+});

test/parallel/test-debugger-inspect-help.js

@@ -13,7 +13,7 @@ spawnSyncAndExit(process.execPath, [
 probeScript,
 ],{
 signal: null,
-status: 1,
+status: 9,
 stderr: /Each--probemustbefollowedimmediatelyby--expr/,
 trim: true,
 });