Added support for attached vscode debugger

[BOTLANNER]

Use case: Debugging tooling that uses jsdoc-api causes

JSDOC_ERROR: Debugger attached

to be thrown, even when the jsdoc command executed succesfully. This prevents debugging past any jsdoc-api usage as it will always throw an exception when the debugger is attached.

This pull request checks the output of the jsdoc command and if it determines that it failed to parse the output due to the debugger being attached, it finds the start of the actual jsdoc output and attempts to reparse the output from that line.

Commit comment: Added support for attached vscode debugger

[75lb]

Hi, thanks for pointing this issue out.. One question, if the debugger is attached should jsdoc-api raise a JSDOC_ERROR exception as it does currently? Are there any scenarios in which it is valid to consider "debugger attached" an error? If not, could we update the PR to fix this please, so that jsdoc-api ignores "debugger attached" (rather than work around the issue as the current PR does)..

JSDOC_ERROR: Debugger attached

[BOTLANNER]

The problem is that it is not actually an error being thrown from jsdoc, there is just a number of additional verbose logging that occurs when there is a debugger attached, and the current implementation expects the only content in stdout to be a parseable json object.

That is why this PR searches the output for where the actual json object starts from the stdout in order to avoid attempting to parse the additional debug logging that occurs.

The reason it appears that there is an exception thrown when there is a debugger attached is how the JsdocCommand manages parse failures.

if (code > 0 || parseFailed) {
      const firstLineOfStdout = output.stdout.split(/\r?\n/)[0]
      const err = new Error(output.stderr.trim() || firstLineOfStdout || 'Jsdoc failed.')
      err.name = 'JSDOC_ERROR'
      throw err
  } else {
    return parsedOutput
  }

The current implementation makes use of the first line of the standard output, which happens to be "Debugger attached" because of all the verbose logging that occurred. Note that there are also other lines of verbose logging not just "Debugger attached", which is why the stdout needs to be searched line by line for the start of the actual object

[75lb]

You mentioned "debugging tooling" in your original post, could you do me a favour please and post some reproduction instructions? It would speed things up if I had some instructions I could follow to see the issue failing and debug it.

Which OS? Editor? Build tools? What is the command you use to start debugging? Cheers.