report: modify getReport() to return an Object

It's likely that anyone using `process.report.getReport()` will be
processing the return value thereafter (e.g., filtering fields or
redacting secrets). This change eliminates boilerplate by calling
`JSON.parse()` on the return value.
Also modified the `validateContent()` and `validate()` test helpers in
`test/common/report.js` to be somewhat more obvious and helpful. Of
note, a report failing validation will now be easier (though still not
_easy_) to read when prepended to the stack trace.
- Refs: nodejs/diagnostics#315
PR-URL: #28630
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Jiawen Geng <technicalcute@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Rich Trott <rtrott@gmail.com>

Author: boneskull

doc/api/process.md

@@ -1726,14 +1726,19 @@ added: v11.8.0
 -->
 
 *`err` {Error} A custom error used for reporting the JavaScript stack.
-* Returns: {string}
+* Returns: {Object}
 
-Returns a JSON-formatted diagnostic report for the running process. The report's
-JavaScript stack trace is taken from `err`, if present.
+Returns a JavaScript Object representation of a diagnostic report for the
+running process. The report's JavaScript stack trace is taken from `err`, if
+present.
 
 ```js
 constdata=process.report.getReport();
-console.log(data);
+console.log(data.header.nodeJsVersion);
+
+// Similar to process.report.writeReport()
+constfs=require('fs');
+fs.writeFileSync(util.inspect(data), 'my-report.log', 'utf8');
 ```
 
 Additional documentation is available in the [report documentation][].

doc/api/report.md

@@ -463,20 +463,23 @@ try {
 // Any other code
 ```
 
-The content of the diagnostic report can be returned as a JSON-compatible object
+The content of the diagnostic report can be returned as a JavaScript Object
 via an API call from a JavaScript application:
 
 ```js
 constreport=process.report.getReport();
-console.log(report);
+console.log(typeof report ==='object'); // true
+
+// Similar to process.report.writeReport() output
+console.log(JSON.stringify(report, null, 2));
 ```
 
 This function takes an optional additional argument `err` - an `Error` object
 that will be used as the context for the JavaScript stack printed in the report.
 
 ```js
 constreport=process.report.getReport(newError('custom error'));
-console.log(report);
+console.log(typeofreport==='object'); // true
 ```
 
 The API versions are useful when inspecting the runtime state from within
@@ -498,7 +501,7 @@ Node.js report completed
 >
 ```
 
-When a report is triggered, start and end messages are issued to stderr
+When a report is written, start and end messages are issued to stderr
 and the filename of the report is returned to the caller. The default filename
 includes the date, time, PID and a sequence number. The sequence number helps
 in associating the report dump with the runtime state if generated multiple

lib/internal/process/report.js

@@ -5,6 +5,7 @@ const {
 }=require('internal/errors').codes;
 const{ validateSignalName, validateString }=require('internal/validators');
 constnr=internalBinding('report');
+const{JSON}=primordials;
 constreport={
 writeReport(file,err){
 if(typeoffile==='object'&&file!==null){
@@ -26,7 +27,7 @@ const report = {
 elseif(err===null||typeoferr!=='object')
 thrownewERR_INVALID_ARG_TYPE('err','Object',err);
 
-returnnr.getReport(err.stack);
+returnJSON.parse(nr.getReport(err.stack));
 },
 getdirectory(){
 returnnr.getDirectory();

test/addons/worker-addon/test.js

@@ -31,7 +31,7 @@ switch (process.argv[2]) {
 }
 
 // Use process.report to figure out if we might be running under musl libc.
-constglibc=JSON.parse(process.report.getReport()).header.glibcVersionRuntime;
+constglibc=process.report.getReport().header.glibcVersionRuntime;
 assert(typeofglibc==='string'||glibc===undefined,glibc);
 
 constlibcMayBeMusl=common.isLinux&&glibc===undefined;

test/common/README.md

@@ -859,19 +859,20 @@ functionality.
 Returns an array of diagnotic report file names found in `dir`. The files should
 have been generated by a process whose PID matches `pid`.
 
-### validate(report)
+### validate(filepath)
 
-*`report`[<string>] Diagnostic report file name to validate.
+*`filepath`[<string>] Diagnostic report filepath to validate.
 
 Validates the schema of a diagnostic report file whose path is specified in
-`report`. If the report fails validation, an exception is thrown.
+`filepath`. If the report fails validation, an exception is thrown.
 
-### validateContent(data)
+### validateContent(report)
 
-*`data`[<string>] Contents of a diagnostic report file.
+*`report`[<Object|string>] JSON contents of a diagnostic report file, the
+parsed Object thereof, or the result of `process.report.getReport()`.
 
 Validates the schema of a diagnostic report whose content is specified in
-`data`. If the report fails validation, an exception is thrown.
+`report`. If the report fails validation, an exception is thrown.
 
 ## tick Module
 

test/common/report.js

@@ -4,6 +4,7 @@ const assert = require('assert');
 constfs=require('fs');
 constos=require('os');
 constpath=require('path');
+constutil=require('util');
 
 functionfindReports(pid,dir){
 // Default filenames are of the form
@@ -21,24 +22,31 @@ function findReports(pid, dir) {
 returnresults;
 }
 
-functionvalidate(report){
-constdata=fs.readFileSync(report,'utf8');
-
-validateContent(data);
+functionvalidate(filepath){
+validateContent(JSON.parse(fs.readFileSync(filepath,'utf8')));
 }
 
-functionvalidateContent(data){
+functionvalidateContent(report){
+if(typeofreport==='string'){
+try{
+report=JSON.parse(report);
+}catch{
+thrownewTypeError(
+'validateContent() expects a JSON string or JavaScript Object');
+}
+}
 try{
-_validateContent(data);
+_validateContent(report);
 }catch(err){
-err.stack+=`\n------\nFailing Report:\n${data}`;
+try{
+err.stack+=util.format('\n------\nFailing Report:\n%O',report);
+}catch{}
 throwerr;
 }
 }
 
-function_validateContent(data){
+function_validateContent(report){
 constisWindows=process.platform==='win32';
-constreport=JSON.parse(data);
 
 // Verify that all sections are present as own properties of the report.
 constsections=['header','javascriptStack','nativeStack',

test/report/test-report-uv-handles.js

@@ -43,7 +43,7 @@ if (process.argv[2] === 'child') {
 constserver=http.createServer((req,res)=>{
 req.on('end',()=>{
 // Generate the report while the connection is active.
-console.log(process.report.getReport());
+console.log(JSON.stringify(process.report.getReport(),null,2));
 child_process.kill();
 
 res.writeHead(200,{'Content-Type': 'text/plain'});