fix ts-jest flaky runs (NomicFoundation#1129)

we have been having random test failures both locally and CI, which
present in failure to load TypeScript definitions ([recent one for
example](https://github.com/NomicFoundation/slang/actions/runs/11456261626/job/31874008248)).

This essentially comes down to cache bugs in `ts-jest`, which we can
just avoid by asking it to skip type checking during test running. It is
redundant since we already verify that using `infra check tsc`.

.vscode/settings.json

@@ -25,6 +25,8 @@
   ],
   "rust-analyzer.server.path": "${workspaceFolder}/scripts/bin/rust-analyzer",
   "search.exclude": {
+    // Git Submodules
+    "submodules/**": true,
     // Packages and Dependencies
     "**/.hermit/": true,
     "**/node_modules/": true,

crates/testlang/outputs/npm/tests/src/public-api.test.mts

@@ -0,0 +1,19 @@
+import * as slang from "@slang-private/testlang-npm-package";
+import { NonterminalKind, TerminalKind } from "@slang-private/testlang-npm-package/cst";
+import { Parser } from "@slang-private/testlang-npm-package/parser";
+
+test("use namespace imports of the API", () => {
+  expect(slang.cst.NonterminalKind.SourceUnit).toEqual("SourceUnit");
+  expect(slang.cst.NonterminalKind.TreeNode).toEqual("TreeNode");
+  expect(slang.cst.TerminalKind.Identifier).toEqual("Identifier");
+});
+
+test("use nested imports of the API", () => {
+  expect(NonterminalKind.SourceUnit).toEqual("SourceUnit");
+  expect(NonterminalKind.TreeNode).toEqual("TreeNode");
+  expect(TerminalKind.Identifier).toEqual("Identifier");
+});
+
+test("language exposes a root kind", () => {
+  expect(Parser.rootKind()).toEqual(NonterminalKind.SourceUnit);
+});

documentation/public/user-guide/npm-package/using-queries.md

@@ -13,7 +13,7 @@ You can create a `Query` object using `Query.parse`, which accepts a string valu
 You can pass multiple queries to a cursor to and efficiently traverse the tree looking for matches. They will be executed concurrently, returning matches in the order they appear in input.
 
 ```{ .ts }
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-queries.mts:creating-a-query"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-queries.test.mts:creating-a-query"
 ```
 
 ## Iterating over node patterns
@@ -27,15 +27,15 @@ Let's use this to list all the contract definitions in the source file:
 ```
 
 ```{ .ts }
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-queries.mts:visiting-contracts"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-queries.test.mts:visiting-contracts"
 ```
 
 ### Multiple patterns simultaneously
 
 We can also intersperse multiple patterns in a single query, which will return all the matches for each pattern. This can be useful when you want to match multiple types of nodes in a single pass.
 
 ```{ .ts }
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-queries.mts:multiple-patterns"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-queries.test.mts:multiple-patterns"
 ```
 
 ## Matching on node's label
@@ -49,7 +49,7 @@ To do so, we use `[label: _]` syntax. Here, we also use `_` to allow matching an
 ```
 
 ```{ .ts }
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-queries.mts:matching-on-label"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-queries.test.mts:matching-on-label"
 ```
 
 ## Matching on node's literal content
@@ -63,7 +63,7 @@ Let's say we prefer our code to be explicit and prefer using `uint256` instead o
 ```
 
 ```{ .ts }
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-queries.mts:matching-on-literal-value"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-queries.test.mts:matching-on-literal-value"
 ```
 
 ## Example: Finding `tx.origin` patterns
@@ -79,5 +79,5 @@ Let's use the motivating example from [https://soliditylang.org](https://docs.so
 Now, we can above features to write a query that matches all `tx.origin` patterns:
 
 ```{ .ts }
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-queries.mts:tx-origin"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-queries.test.mts:tx-origin"
 ```

documentation/public/user-guide/npm-package/using-the-ast.md

@@ -11,26 +11,26 @@ to create the CST type. Since it is a node of kind `FunctionDefinition`, we are
 the AST type of the same name to analyze it:
 
 ```{ .ts }
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-ast.mts:imports"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-ast.test.mts:imports"
 
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-ast.mts:parse-input"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-ast.test.mts:parse-input"
 ```
 
 The `FunctionDefinition` type has named fields to access all its children.
 For example, we can check the name of the function:
 
 ```{ .ts }
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-ast.mts:create-node"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-ast.test.mts:create-node"
 ```
 
 We can also list its parameters:
 
 ```{ .ts }
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-ast.mts:list-parameters"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-ast.test.mts:list-parameters"
 ```
 
 Or attributes:
 
 ```{ .ts }
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-ast.mts:list-attributes"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-ast.test.mts:list-attributes"
 ```

documentation/public/user-guide/npm-package/using-the-cursor.md

@@ -8,17 +8,17 @@ Let's start with this source file, that contains three contracts:
 ```
 
 ```{ .ts }
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-cursor.mts:imports"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-cursor.test.mts:imports"
 
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-cursor.mts:parse-input"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-cursor.test.mts:parse-input"
 ```
 
 ## Listing Contract Names
 
 The below example uses a cursor to list the names of all contracts in a source file:
 
 ```{ .ts }
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-cursor.mts:listing-contract-names"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-cursor.test.mts:listing-contract-names"
 ```
 
 ## Visiting Only a Sub-tree
@@ -32,7 +32,7 @@ which cheaply creates a new cursor that starts at the given node, without copyin
 This lets us visit the sub-tree of each contract, without modifying the original cursor:
 
 ```{ .ts }
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-cursor.mts:visiting-sub-tree"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-cursor.test.mts:visiting-sub-tree"
 ```
 
 ## Accessing Node Positions
@@ -41,5 +41,5 @@ The `Cursor` API also tracks the position and range of the current node it is vi
 Here is an example that records the source range of each contract, along with its text:
 
 ```{ .ts }
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-cursor.mts:accessing-node-positions"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-cursor.test.mts:accessing-node-positions"
 ```

documentation/public/user-guide/npm-package/using-the-parser.md

@@ -14,35 +14,35 @@ We begin by creating a `Parser` object with a specified version. This is an entr
 Then we can use it to parse the source file, specifying the top-level nonterminal to parse:
 
 ```{ .ts }
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-parser.mts:imports"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-parser.test.mts:imports"
 
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-parser.mts:parse-input"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-parser.test.mts:parse-input"
 ```
 
 ## Checking for Syntax Errors
 
 If the file has errors, we can get them from the `ParseOutput` type, and print them out:
 
 ```{ .ts }
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-parser.mts:print-errors"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-parser.test.mts:print-errors"
 ```
 
 Otherwise, we can check if input is valid using this helpful utility:
 
 ```{ .ts }
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-parser.mts:assert-is-valid"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-parser.test.mts:assert-is-valid"
 ```
 
 ## Inspecting the Parse Tree
 
 Now, let's try to inspect the resulting CST, and iterate on its children:
 
 ```{ .ts }
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-parser.mts:inspect-tree"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-parser.test.mts:inspect-tree"
 ```
 
 Additionally, we can convert the CST node back into the input string:
 
 ```{ .ts }
---8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-parser.mts:unparse-node"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/using-the-parser.test.mts:unparse-node"
 ```

jest.config.ts

@@ -1,11 +1,39 @@
 import type { Config } from "jest";
 
-const config: Config = {
-  projects: [
-    // List all directories with package-level "jest.config.ts" files:
-    "<rootDir>/crates/solidity/outputs/npm/tests/",
-    "<rootDir>/crates/testlang/outputs/npm/tests/",
+export default {
+  testMatch: ["<rootDir>/**/*.test.mts"],
+
+  testPathIgnorePatterns: [".*/\\.hermit/", ".*/node_modules/", ".*/submodules/", ".*/target/"],
+
+  moduleFileExtensions: [
+    /*  Plain: */ ["js", "ts"],
+    /*  ESM:   */ ["mjs", "mts"],
+    /*  CJS:   */ ["cjs", "cts"],
+    /*  JSX:   */ ["jsx", "tsx"],
+    /*  Other: */ ["json", "node", "wasm"],
+  ].flat(),
+
+  extensionsToTreatAsEsm: [
+    // ".mjs" is already included.
+    ".mts",
   ],
-};
 
-export default config;
+  cacheDirectory: "<rootDir>/target/jest/cache",
+
+  slowTestThreshold: 5,
+
+  clearMocks: true,
+  resetMocks: true,
+
+  resolver: "ts-jest-resolver",
+
+  transform: {
+    "^.+\\.m?[tj]sx?$": [
+      "ts-jest",
+      {
+        isolatedModules: true,
+        useESM: true,
+      },
+    ],
+  },
+} satisfies Config;