Allow debug mode to be enabled

[hubgit]

When evaluating Schematron rules it's useful to see the line that caused an error.

This can be enabled (at the expense of some efficiency) by passing debug: true as one of the options when calling fontoxpath's evaluateXPath* methods.

https://github.com/FontoXML/fontoxpath#debugging

[wvbe]

Hey @hubgit, thank you for this input! Would you say that this debug information is only interesting for the evaluated expressions that are sourced from the schematron file (eg. report@test, let@value, name@path)? Or, by contrast, also the XPath expressions that node-schematron runs to find the context nodes etc. (eg. the evaluateXPath call made in Schema.ts)?

The reason I'm asking is that I'd like to have debug mode an as small as possible impact on the API of relevant classes, and if there's an error inside node-schematron I'd rather throw a descriptive error (although currently I probably don't) than an XPath error.

[hubgit]

I think the most useful information is for the expressions in the schematron, to find out what caused the error.

This is an example of the output:

 1: . = $allowed-disp-subj
       ^^^^^^^^^^^^^^^^^^^^^^

    Error: Atomizing array(*) is not implemented.
      at <equalOp>:1:1 - 1:23

[hubgit]

It might even make sense to change fontoxpath so that debugging can be enabled in a more global way?

[hubgit]

This is probably getting outside the scope of this issue, but it would be even better if this sort of error could be caught, contained within the scope of the specific test that caused it, and reported as an error (or "unsupported expression") while continuing with the rest of the tests.

[wvbe]

FYI I've put some code on the debug-mode branch but I'm not quite finished with a CLI option for this mode, and the "continue on XPath error" opt-in setting. It is my intention to finish both :)

[wvbe]

Well... better late than never? I forgot all about this issue, sorry!

I've made some changes on the tsdx branch together with a bunch of other refactor work. Specifically for debugging though:

• Breaking: the 2nd argument to Schema#validateString and Schema#validateDocument is now an object { debug?: boolean; phaseId?: string } instead of phaseId?: string
• Not breaking: the command-line has a new option --debug, or -D for short

Setting either to truthy will use debug mode in fontoxpath. For example, the output of the demo CLI script with -D:

info init Locating files matching "test/xml/simple-document.xml"
info init Reading schema from "test/xml/simple-schematron.xml"
info init Starting validation
fail test/xml/simple-document.xml
f-er  ▼  1: . = $allowed-disp-subj
f-er  ▼         ^^^^^^^^^^^^^^^^^^
f-er  ▼
f-er  ▼  Error: XPST0008, The variable allowed-disp-subj is not in scope.
f-er  ▼    at <varRef>:1:5 - 1:23
f-er  ▼    at <equalOp>:1:1 - 1:23
ERR! 1 documents could not be validated
info 1 documents passed
info 0 documents failed
ERR! Not all documents passed, exiting with non-zero code

Because it's a breaking change, even a small one, I want to let it stew a short while before publishing this to npm. I realise I said that last time as well, so this time I'm making a PR for myself, as a reminder

[wvbe]

Integrated! Now available as node-schematron@2.0.0

[hubgit]

Thanks @wvbe!