Description
Now that we use ESLint for linting TypeScript declaration files, one of the most significant gaps in our linting processes is linting examples displayed in TypeScript declaration documentation. This is a common source of documentation bugs particularly in new contributor PRs and imposes an additional burden on reviewers to cross check all docs against corresponding JavaScript doc examples. This is particularly problematic for more complex declarations involving overloads, etc, and is not ideal.
This RFC proposes extending doctesting to TypeScript declaration files. It will require a separate ESLint rule (e.g., @stdlib/_tools/eslint/rules/doctest-typescript) which deviates from the doctesting approach found in https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/%40stdlib/_tools/eslint/rules/doctest/lib/main.js. In particular, for JS files, we simply load the source code into a VM with some source transformations, putting all variables within the module scope into the VM context, and then evaluating examples in turn. That won't quite work here.
Instead, we'll need to modify the approach to make a package's main export available to the VM context. After which, the same approach of parsing examples should work.
Time estimate without AI: 5h 30min
Time estimate with AI: 5h