Skip to content

prototype: annotate-twoslash #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
SMotaal wants to merge 11 commits into
base: main
Choose a base branch
from
Draft

prototype: annotate-twoslash #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
f4e6d08
initial prototype & test
SMotaal Jan 17, 2023
ca20434
add gitpkg-branch-consumer package
SMotaal Jan 17, 2023
b848713
fix: GroupCaptureRegExp types
SMotaal Jan 17, 2023
74181a0
feat: add separate `@errs` query parameter
SMotaal Jan 17, 2023
e88bba4
fix: annotated markdown formatting
SMotaal Jan 17, 2023
201c400
test: update assertions example
SMotaal Jan 18, 2023
7ae9c00
fix: improve error narrowing for mismatched lines
SMotaal Jan 18, 2023
8712a50
chore: add .gitignore
SMotaal Jan 18, 2023
798421c
refactor: types
SMotaal Jan 22, 2023
24e7528
test: add cases for assertion functions as function parameters
SMotaal Jan 22, 2023
f014797
feat: add independent `use-language-service` approach
SMotaal Feb 24, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,3 +133,10 @@ dist
.yarn/build-state.yml
.yarn/install-state.gz
.pnp.*

# local history
.history/

# smotaal's convenciences
/@*/
[[]trash[]]/
23 changes: 23 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,26 @@
# @outmark/anno-type

A twoslash-inspired developer-oriented type-checking solution.

## Getting Started

As of now, this is still a very early prototype with little to no documentation and unstable if not faulty code.

You may get some idea on how the tool works by checking out the package scripts in the test folder:

- To run all the examples at once:

```sh
# You can also just run this script in the test folder directly
yarn workspace anno-type-test annotate:examples
```

- To run a specific example with more verbose output:

```sh
# Adding 1 to 3 exclamation marks anywhere dumps the current state.
# In this example the !! comes at the end and so it will dump the final state.
yarn workspace anno-type-test annotate:twoslash:examples \!\!
```

> **Note**: Interactive shells often require escaping each `\!` in a command line input.

@SMotaal SMotaal Feb 26, 2023 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

24 changes: 24 additions & 0 deletions jsconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
{
"$schema": "https://json.schemastore.org/jsconfig",
"compilerOptions": {
"module": "ESNext",
"target": "ESNext",
"checkJs": true,
"moduleResolution": "NodeNext",
"keyofStringsOnly": true,
"strict": true,
"strictNullChecks": false,
"strictPropertyInitialization": false,
"noImplicitAny": false,
"noImplicitThis": false,
"noImplicitOverride": false,
"noImplicitReturns": false,
"suppressExcessPropertyErrors": true
},
"exclude": [
"node_modules",
"**/node_modules",
"**/[trash]/",
"test/**/output"
]
}
3 changes: 3 additions & 0 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,9 @@
"packages": [
"test",
"packages/*"
],
"tests": [
"test/packages/*"
]
}
}
Loading