During extension development, the default error output can provide too little information
I am writing an Antora extension. Sometimes, I've made a typo in the extension and Antora rightly complains. However, the full error context is not provided making the task of tracking down the problem more difficult than it needs to be.
For example:
$ npx antora --stacktrace --fetch antora-playbook.yml
[09:47:06.209] FATAL (antora): Missing initializer in const declaration
type: "Error"
Since my extension has several hundred const
declarations, this message is unhelpful.
When I edit the user-require-helper, like so:
const userRequire = (request, context) => {
try {
return require(userResolve(request, context))
} catch (err) {
console.log('Encountered userRequire error!', err)
}
}
I see the error context that identifies the exact problem:
npx antora --stacktrace --fetch antora-playbook.yml
Encountered userRequire error! /Users/eedwards/repos/docs-dev/poc/extensions/antora/myExtension.js:108
const skip (word) => {
^^^^
SyntaxError: Missing initializer in const declaration
at internalCompileFunction (node:internal/vm:73:18)
at wrapSafe (node:internal/modules/cjs/loader:1195:20)
at Module._compile (node:internal/modules/cjs/loader:1239:27)
at Module._extensions..js (node:internal/modules/cjs/loader:1329:10)
at Module.load (node:internal/modules/cjs/loader:1133:32)
at Module._load (node:internal/modules/cjs/loader:972:12)
at Module.require (node:internal/modules/cjs/loader:1157:19)
at require (node:internal/modules/helpers:119:18)
at userRequire (/Users/eedwards/repos/docs-dev/node_modules/@antora/user-require-helper/lib/index.js:43:12)
at /Users/eedwards/repos/docs-dev/node_modules/@antora/site-generator/lib/generator-context.js:145:30
[09:54:42.751] FATAL (antora): Cannot destructure property 'register' of 'userRequire(...)' as it is undefined.
type: "Error"
I don't know whether my interim solution is the desired way to gather the context, given all of the other require handling in the helper.
I think it would be good to provide additional context for such errors in the "Antora way". I'd be happy to contribute an MR to implement a proper solution after a discussion that defines "proper".