prototype: annotate-twoslash

[SMotaal]

This is a prototype of the twoslash-inspired type-checking solution.

Tasks:

• Improve path resolution

  See: prototype: annotate-twoslash #1 (comment)

Considerations:

• Using framework snapshots (eg ava) for tests.
• Running tests against multiple typescript versions.
• Introducing type checking directives (eg using satisfies operator).

Motivation:

[SMotaal]

---

Additions:

• To run annotate-twoslash commands with a specified workspace:

  # Resolving paths ahead of time is the current design choice.
  # This ensures that platform specificity is in tact without additional dependencies.
  yarn workspace anno-type-test annotate-twoslash -al -o=output/temp $(realpath test/sources/examples/*.[tj]s)

  Note: Wildcards are handled by the interactive shell or by the package manager for package scripts, while the workspace package names and paths are always handled by the package manager itself.

• To run annotate-twoslash commands with package-root-relative paths:

  # …
  yarn annotate-twoslash -al -o=test/output/temp test/sources/examples/*.[tj]s

  Note: Bare paths are always resolved relative to the package root and will throw if this cannot be resolved.

• To run annotate-twoslash commands with working-directory-relative paths:

  # …
  yarn annotate-twoslash -al -o=../output/temp ./examples/*.[tj]s

  Note: Interactive shells commonly retain the . or .. in a command line input.

---

A section on path resolution would outline the design choices and clarify how they are intended to mitigate ambiguities with some practical use cases.

Based on what was encountered so far the following seems like a good starting point which can be revised down the road with enough testing in feedback:

1. An implicit or explicit root-path is used to simplify the resolution semantics with the following rules:
   1. any bare-specifier is expected to be package-root-relative.
   2. any relative-specifier is expected to be working-directory-relative.
   3. any absolute-specifier is expected to be nested relative to an implicit or explicit --root-path.
2. An implicit root-path will default to:
   1. the resolved package-root for a given bare-specifier or package-scoped-absolute-specifier.
   2. the specifier-relative-root for a given relative-specifier.
   3. the parent-directory for a non-package-scoped-absolute-specifier.
3. The package-root is always resolved once for each unique specifier using the require.resolve irrespective of package-scope.

   Note: Edge cases where the createRequire(packageRoot).resolve resolution is overridden are firmly out of scope. At this point, this is neither checked for nor restricted intentionally, however the normal path checking rules may still reject some paths without guarantees.

Those would then clarify what changes need to take place to iron out the obscurities in the implementation to make it stable enough to use.