Merge remote-tracking branch 'origin/main' into support-traceresolution

.github/workflows/continuous-integration.yml

@@ -48,7 +48,7 @@ jobs:
       matrix:
         os: [ubuntu, windows]
         # Don't forget to add all new flavors to this list!
-        flavor: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+        flavor: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
         include:
           # Node 12.15
           # TODO Add comments about why we test 12.15; I think git blame says it's because of an ESM behavioral change that happened at 12.16
@@ -94,32 +94,68 @@ jobs:
             typescript: next
             typescriptFlag: next
           # Node 16
+          # Node 16.11.1
+          # Earliest version that supports old ESM Loader Hooks API: https://github.com/TypeStrong/ts-node/pull/1522
           - flavor: 8
+            node: 16.11.1
+            nodeFlag: 16_11_1
+            typescript: latest
+            typescriptFlag: latest
+          - flavor: 9
             node: 16
             nodeFlag: 16
             typescript: latest
             typescriptFlag: latest
             downgradeNpm: true
-          - flavor: 9
+          - flavor: 10
             node: 16
             nodeFlag: 16
             typescript: 2.7
             typescriptFlag: 2_7
             downgradeNpm: true
-          - flavor: 10
+          - flavor: 11
             node: 16
             nodeFlag: 16
             typescript: next
             typescriptFlag: next
             downgradeNpm: true
+          # Node nightly
+          - flavor: 12
+            node: nightly
+            nodeFlag: nightly
+            typescript: latest
+            typescriptFlag: latest
+            downgradeNpm: true
     steps:
       # checkout code
       - uses: actions/checkout@v2
       # install node
       - name: Use Node.js ${{ matrix.node }}
+        if: matrix.node != 'nightly'
         uses: actions/setup-node@v1
         with:
           node-version: ${{ matrix.node }}
+      - name: Use Node.js 16, will be subsequently overridden by download of nightly
+        if: matrix.node == 'nightly'
+        uses: actions/setup-node@v1
+        with:
+          node-version: 16
+      - name: Download Node.js nightly
+        if: matrix.node == 'nightly' && matrix.os == 'ubuntu'
+        run: |
+          export N_PREFIX=$(pwd)/n
+          npm install -g n
+          n nightly
+          sudo cp "${N_PREFIX}/bin/node" "$(which node)"
+          node --version
+      - name: Download Node.js nightly
+        if: matrix.node == 'nightly' && matrix.os == 'windows'
+        run: |
+          $version = (Invoke-WebRequest https://nodejs.org/download/nightly/index.json | ConvertFrom-json)[0].version
+          $url = "https://nodejs.org/download/nightly/$version/win-x64/node.exe"
+          $targetPath = (Get-Command node.exe).Source
+          Invoke-WebRequest -Uri $url -OutFile $targetPath
+          node --version
       # lint, build, test
         # Downgrade from npm 7 to 6 because 7 still seems buggy to me
       - if: ${{ matrix.downgradeNpm }}

.github/workflows/website.yml

@@ -17,8 +17,7 @@ jobs:
         with:
           node-version: 14
       # Render typedoc
-      # Using custom branch to workaround: https://github.com/TypeStrong/typedoc/issues/1585
-      - run: npm install && git clone --depth 1 https://github.com/cspotcode/typedoc --branch patch-2 && pushd typedoc && npm install && npm run build || true && popd && ./typedoc/bin/typedoc
+      - run: npm install && npx typedoc
       # Render docusaurus and deploy website
       - run: |
           set -euo pipefail

.prettierignore

@@ -10,3 +10,4 @@ tests/main-realpath/symlink/tsconfig.json
 tests/throw error.ts
 tests/throw error react tsx.tsx
 tests/esm/throw error.ts
+tests/legacy-source-map-support-interop/index.ts

.vscode/launch.json

@@ -0,0 +1,16 @@
+{
+  "configurations": [
+    {
+      "name": "Debug AVA test file",
+      "type": "node",
+      "request": "launch",
+      "preLaunchTask": "npm: pre-debug",
+      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/ava",
+      "program": "${file}",
+      "outputCapture": "std",
+      "skipFiles": [
+        "<node_internals>/**/*.js"
+      ],
+    }
+  ],
+}

.vscode/tasks.json

@@ -0,0 +1,13 @@
+{
+  "tasks": [
+    {
+      "type": "npm",
+      "script": "pre-debug",
+      "problemMatcher": [
+        "$tsc"
+      ],
+      "label": "npm: pre-debug",
+      "detail": "npm run build-tsc && npm run build-pack"
+    }
+  ]
+}

CONTRIBUTING.md

@@ -19,6 +19,32 @@ compiled code in `dist`.
 
 `dist-raw` is for larger chunks of code which are not compiled nor linted because they have been copy-pasted from `node`'s source code.
 
+## Tests
+
+Test cases are declared in `src/test/*.spec.ts`, and test fixtures live in `./tests`.  They can be run with `npm run test-local`.
+
+Tests are run with AVA, but using a custom wrapper API to enable some TS-friendly features and grouped test suites.
+
+The tests `npm pack` ts-node into a tarball and `npm install` it into `./tests/node_modules`.  This makes `./tests` a better testing environment
+because it more closely matches the end-user's environment.  Complex `require()` / `import` / `--require` / `--loader` invocations behave
+the way they would in a users's project.
+
+Historically, it has been difficult to test ts-node in-process because it mutates the node environment: installing require hooks, stack trace formatters, etc.
+`nyc`, `ava`, and `ts-node` all mutate the node environment, so it is tricky to setup and teardown individual tests in isolation, because ts-node's hooks need to be
+reset without disturbing `nyc` or `ava` hooks.  For this reason, many tests are integration style, spawning ts-node's CLI in an external process, asking it to
+execute one of the fixture projects in `./tests`.
+
+Over time, I've gradually added setup and teardown logic so that more components can be tested in-process.
+
+We have a debug configuration for VSCode.
+
+1. Open a `*.spec.ts` so it is the active/focused file.
+2. (optional) set breakpoints.
+3. Invoke debugger with F5.
+
+Note that some tests might misbehave in the debugger.  REPL tests in particular.  I'm not sure why, but I think it is related to how `console` does not write to
+stdout when in a debug session.
+
 ## Documentation
 
 Documentation is written in markdown in `website/docs` and rendered into a website by Docusaurus.  The README is also generated from these markdown files.