alternative stack trace approach

[davidjgoss]

🤔 What's changed?

Stop using stack-chain to temporarily modify stack trace behaviour in a V8-specific manner, for when we filter stack traces (i.e. with --backtrace option). Pivot to parsing the stack with error-stack-parser without modifying how it's created, and filtering from that.

Also add some documentation around source maps.

⚡️ What's your motivation?

This started with me digging around to try and understand this aspect of our codebase better, but I wanted to run with this approach and see if it's viable.

Hooking into V8's stack trace API in the way that stack-chain does in order to filter the stack trace for display seems like a bit of a sledgehammer to me. It also doesn't fail gracefully - in a non-V8 environment it will throw and exit, and this happens as soon as you import stack-chain, not just when you call methods on it. This is the only reason we can't do a live demo with StackBlitz, for example, and also seems likely to be a hindrance as we look to become less Node.js-centric and work with e.g. Deno and Bun.

On the flipside, parsing the stack trace is inevitably less scientific and more error-prone, and there will be some edge cases that go weird. For example https://github.com/stacktracejs/error-stack-parser/issues/62 which contributed to us to moving away from the stacktrace.js libraries before (I've raised a fix for this now). I think it would be worthwhile though.

This change has also fixed an issue I was seeing when creating an example TypeScript+ESM project, where source references and stack traces were coming out with wrong locations that didn't correspond to either the source or transpiled JavaScript.

This area isn't very well covered by tests, so I'm going to try and flesh some out before I mark this as ready.

🏷️ What kind of change is this?

• :bank: Refactoring/debt/DX (improvement to code design, tooling, documentation etc. without changing behaviour)
• 🐛 Bug fix (non-breaking change which fixes a defect)

📋 Checklist:

• [x] I agree to respect and uphold the Cucumber Community Code of Conduct
• [x] I've changed the behaviour of the code
  • [ ] I have added/updated tests to cover my changes.
• [ ] My change requires a change to the documentation.
  • [ ] I have updated the documentation accordingly.
• [ ] Users should know about my change
  • [ ] I have added an entry to the "Unreleased" section of the CHANGELOG, linking to this pull request.

---

This text was originally generated from a template, then edited by hand. You can modify the template here.

[coveralls]

Coverage decreased (-0.004%) to 98.252% when pulling ef19e776ec298b1bf70099290c14727081ad12f7 on feat/nodejs-source-maps into e88c691444b8d88bca67bd464ac30fd89a981b8b on main.

[davidjgoss]

This was released in 8.8.0 https://github.com/cucumber/cucumber-js/releases/tag/v8.8.0