Add unit tests for remark/rehype plugins

See #17

Migrate unit tests for our custom remark and rehype plugins from the
archived `gravitational/docs` repo. Convert these tests to Jest, which
unlike the uvu testing tool we used for `gravitational/docs`, is still
being maintained. Add a GitHub Actions workflow to run the tests on pull
requests.

This change does not add tests for `remark-includes`, which requires
some changes to how the site processes link paths.

.github/workflows/test.yaml

@@ -0,0 +1,11 @@
+name: Test
+on:
+  pull_request:
+
+jobs:
+  run-tests:
+    name: Run tests
+    runs-on: ubuntu-22.04-2core-arm64
+    steps:
+    - uses: actions/checkout@v4
+    - run: yarn && yarn test

jest.server.config.mjs

@@ -0,0 +1,17 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+const jestConfig = {
+  preset: "ts-jest/presets/default-esm",
+  testEnvironment: "node",
+  extensionsToTreatAsEsm: [".ts"],
+  transform: {
+    "^.+\\.[tj]s$": [
+      "ts-jest",
+      {
+        useESM: true,
+        tsconfig: "tsconfig.node.json",
+      },
+    ],
+  },
+  transformIgnorePatterns: ["<rootDir>/node_modules/*"],
+};
+export default jestConfig;

package.json

@@ -4,7 +4,7 @@
   "private": true,
   "scripts": {
     "spellcheck": "bash scripts/check-spelling.sh",
-    "build-remark": "rm -rf .remark-build && tsc --build tsconfig.node.json && tsc-esm-fix --target='.remark-build' --ext='.mjs'",
+    "build-remark": "tsc --build tsconfig.node.json && tsc-esm-fix --target='.remark-build' --ext='.mjs'",
     "git-update": "scripts/update_submodules.sh",
     "prepare-files": "npx vite-node ./scripts/prepare-files.mts",
     "prepare-sanity-data": "npx vite-node ./scripts/prepare-sanity-data.mts",
@@ -18,12 +18,12 @@
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
     "typecheck": "tsc --noEmit --skipLibCheck --incremental --tsBuildInfoFile node_modules/.cache/tsc/tsbuildinfo --project .",
-    "uvu-test": "loadr -- uvu uvu-tests",
     "base:eslint": "eslint --cache --cache-location node_modules/.cache/eslint '**/*.{js,jsx,ts,tsx}'",
     "base:prettier": "prettier '**/*.{js,jsx,ts,tsx,json}'",
     "lint": "yarn base:eslint --fix && yarn base:prettier --write -l",
     "lint-check": "yarn base:eslint && yarn base:prettier --check",
-    "markdown-lint": "yarn build-remark && remark --rc-path .remarkrc.mjs 'content/**/docs/pages/**/*.mdx' --quiet --frail --ignore-pattern '**/includes/**' --silently-ignore"
+    "markdown-lint": "yarn build-remark && remark --rc-path .remarkrc.mjs 'content/**/docs/pages/**/*.mdx' --quiet --frail --ignore-pattern '**/includes/**' --silently-ignore",
+    "test": "NODE_OPTIONS=\"$NODE_OPTIONS --trace-warnings --experimental-vm-modules\" jest --config ./jest.server.config.mjs server/*.test.ts"
   },
   "lint-staged": {
     "*.{js,jsx,ts,tsx}": [
@@ -43,7 +43,7 @@
     "@docusaurus/plugin-google-gtag": "3.6.3",
     "@docusaurus/plugin-sitemap": "^3.6.3",
     "@docusaurus/theme-classic": "^3.6.3",
-    "@inkeep/widgets": "^0.2.288",
+    "@inkeep/widgets": "^0.2.290",
     "@mdx-js/react": "^3.0.0",
     "classnames": "^2.3.1",
     "clsx": "^2.1.1",
@@ -66,6 +66,7 @@
     "ajv": "^8.16.0",
     "dotenv": "^16.4.5",
     "hast": "^1.0.0",
+    "jest": "^29.7.0",
     "js-yaml": "^4.1.0",
     "loadr": "^0.1.1",
     "mdast": "^3.0.0",
@@ -91,6 +92,7 @@
     "remark-rehype": "^10.1.0",
     "remark-validate-links": "^11.0.2",
     "to-vfile": "^8.0.0",
+    "ts-jest": "^29.2.5",
     "tsc-esm-fix": "^3.1.0",
     "tsm": "^2.3.0",
     "typescript": "~5.5.2",

server/fixtures/code-snippet-empty-line.mdx

@@ -0,0 +1,16 @@
+```code
+$ tsh request search --kind node
+Name                                 Hostname    Labels       Resource ID
+------------------------------------ ----------- ------------
+------------------------------------------------------
+b1168402-9340-421a-a344-af66a6675738 iot         test=test
+/teleport.example.com/node/b1168402-9340-421a-a344-af66a6675738
+bbb56211-7b54-4f9e-bee9-b68ea156be5f node        test=test
+/teleport.example.com/node/bbb56211-7b54-4f9e-bee9-b68ea156be5f
+
+To request access to these resources, run
+> tsh request create --resource
+> /teleport.example.com/node/b1168402-9340-421a-a344-af66a6675738 --resource
+> /teleport.example.com/node/bbb56211-7b54-4f9e-bee9-b68ea156be5f \
+>     --reason <request reason>
+```

server/fixtures/go-comment-var.mdx

@@ -0,0 +1,8 @@
+```go
+// This is a comment about the code below, which contains a 
+// <Var name="myvar" />. This comment also includes another 
+// <Var name="othervar" />. This is the end of the comment.
+func myfunc(attr string) error {
+  return nil
+}
+```

server/fixtures/hcl-addr-var.mdx

@@ -0,0 +1,29 @@
+1. Create a `main.tf` file containing this minimal Terraform code:
+
+   ```hcl
+   terraform {
+     required_providers {
+       teleport = {
+         source  = "terraform.releases.teleport.dev/gravitational/teleport"
+         version = "~> (=teleport.major_version=).0"
+       }
+     }
+   }
+   
+   provider "teleport" {
+     addr               = '<Var name="teleport.example.com:443" />'
+   }
+   ```
+
+1. Then, init your Terraform working directory to download the Teleport provider:
+
+   ```code
+   $ terraform init
+   Initializing the backend...
+   
+   Initializing provider plugins...
+   - Finding terraform.releases.teleport.dev/gravitational/teleport versions matching ...
+   ```
+
+1. Finally, run a Terraform plan:
+

server/fixtures/hcl-vars.mdx

@@ -0,0 +1,11 @@
+Assign <Var name="proxy" initial="teleport.example.com:443" /> to the address of
+your Teleport Proxy Service.
+
+```hcl
+provider "teleport" {
+  # Update addr to point to your Teleport Cloud tenant URL's host:port
+  addr               = "<Var name="proxy" />"
+  identity_file_path = "terraform-identity"
+}
+```
+

server/fixtures/includes/includes-code-snippet-heredoc-error.mdx

@@ -0,0 +1,18 @@
+## Header
+
+```code
+# Copy and Paste the below and run on the Teleport Auth server.
+$ cat > api-role.yaml <<ENDOFMESSAGE
+kind: role
+metadata:
+  name: api-role
+spec:
+  allow:
+    rules:
+      - resources: ['role']
+        verbs: ['read']
+  deny:
+    node_labels:
+      '*': '*'
+version: v3
+```

server/fixtures/includes/includes-code-snippet-heredoc.mdx

@@ -0,0 +1,24 @@
+## Header
+
+```code
+# Copy and Paste the below and run on the Teleport Auth server.
+$ cat > api-role.yaml <<ENDOFMESSAGE
+kind: role
+metadata:
+  name: api-role
+spec:
+  allow:
+    rules:
+      - resources: ['role']
+        verbs: ['read']
+  deny:
+    node_labels:
+      '*': '*'
+version: v3
+ENDOFMESSAGE
+
+# Create role
+$ tctl create -f api-role.yaml
+# Add user and login via web proxy
+$ tctl users add api-user --roles=api-role
+```

server/fixtures/includes/includes-code-snippet-multiline-error.mdx

@@ -0,0 +1,9 @@
+## Header
+
+```code
+$ curl \
+  --cacert /Users/alice/.tsh/keys/teleport.example.com/certs.pem \
+  --cert /Users/alice/.tsh/keys/teleport.example.com/alice-app/cluster-name/grafana-x509.pem \
+  --key /Users/alice/.tsh/keys/teleport.example.com/alice \
+  https://grafana.teleport.example.com:3080 \
+```

server/fixtures/includes/includes-code-snippet-multiline.mdx

@@ -0,0 +1,9 @@
+## Header
+
+```code
+$ curl \
+  --cacert /Users/alice/.tsh/keys/teleport.example.com/certs.pem \
+  --cert /Users/alice/.tsh/keys/teleport.example.com/alice-app/cluster-name/grafana-x509.pem \
+  --key /Users/alice/.tsh/keys/teleport.example.com/alice \
+  https://grafana.teleport.example.com:3080
+```

server/fixtures/includes/includes-code-snippet-output-to-file-mode.mdx

@@ -0,0 +1,24 @@
+## Header
+
+```code
+# Copy and Paste the below and run on the Teleport Auth server.
+$ cat > api-role.yaml << ENDOFMESSAGE > aws-issuer.yaml
+kind: role
+metadata:
+  name: api-role
+spec:
+  allow:
+    rules:
+      - resources: ['role']
+        verbs: ['read']
+  deny:
+    node_labels:
+      '*': '*'
+version: v3
+ENDOFMESSAGE
+
+# Create role
+$ tctl create -f api-role.yaml
+# Add user and login via web proxy
+$ tctl users add api-user --roles=api-role
+```

server/fixtures/includes/includes-code-snippet-simplest.mdx

@@ -0,0 +1,11 @@
+## Header
+
+```code
+$ tsh app config --format=uri
+# https://grafana-root.gravitational.io:3080
+```
+
+```bash
+$ tsh app config --format=uri
+# it's bash lang
+```

server/fixtures/includes/includes-var-after-commands.mdx

@@ -0,0 +1,11 @@
+## Header
+
+```code
+$ aws iam create-policy --policy-name<Var name="kube-iam-policy"/>
+# some comment
+"Policy": {
+  "PolicyName": "<Var name="kube-iam-policy"/>",
+  "PolicyId": "ANPAW2Y2Q2Y2Y2Y2Y2Y2Y",
+  "Arn": "arn:aws:iam::aws:policy/"<Var name="kube-iam-policy"/>
+}
+```

server/fixtures/includes/includes-var-in-block-var.mdx

@@ -0,0 +1,12 @@
+## Header
+
+```var
+teleport:
+  identitySecretName: "teleport-plugin-jira-identity"
+  address: <Var name="teleport-address"/>
+# /etc/teleport.yaml
+auth_service:
+  # ...
+  ca_key_params:
+    keyring: <Var name="keyring"/>
+```

server/fixtures/includes/includes-var-in-command.mdx

@@ -0,0 +1,5 @@
+## Header
+
+```code
+$ docker pull <Var name="folder" /> quay.io/gravitational/teleport:9 <Var name="domain name" isGlobal /> we recommend following our
+```

server/fixtures/includes/includes-var-in-multiline-command.mdx

@@ -0,0 +1,12 @@
+## Header
+
+```code
+$ tctl create <<EOF
+kind: <Var name="role" />
+version: v3
+metadata:
+  <Var name="field" />: <Var name="domain name" description="super domain name" isGlobal />
+EOF
+# create the role
+$ tsh db ls
+```

server/fixtures/powershell-var.mdx

@@ -0,0 +1,3 @@
+```powershell
+certutil -dspublish -f <Var name="user-ca.cer" /> NTAuthCA
+```

server/fixtures/result/code-snippet-empty-line.mdx

@@ -0,0 +1,61 @@
+<snippet>
+  <command>
+    <commandline data-content="$ ">
+      tsh request search --kind node
+    </commandline>
+  </command>
+
+  <codeline>
+    Name                                 Hostname    Labels       Resource ID
+  </codeline>
+
+  <codeline>
+    \------------------------------------ ----------- ------------
+  </codeline>
+
+  <codeline>
+    \------------------------------------------------------
+  </codeline>
+
+  <codeline>
+    b1168402-9340-421a-a344-af66a6675738 iot         test=test
+  </codeline>
+
+  <codeline>
+    /teleport.example.com/node/b1168402-9340-421a-a344-af66a6675738
+  </codeline>
+
+  <codeline>
+    bbb56211-7b54-4f9e-bee9-b68ea156be5f node        test=test
+  </codeline>
+
+  <codeline>
+    /teleport.example.com/node/bbb56211-7b54-4f9e-bee9-b68ea156be5f
+  </codeline>
+
+  <codeline>
+
+  </codeline>
+
+  <br />
+
+  <codeline>
+    To request access to these resources, run
+  </codeline>
+
+  <codeline>
+    \> tsh request create --resource
+  </codeline>
+
+  <codeline>
+    \> /teleport.example.com/node/b1168402-9340-421a-a344-af66a6675738 --resource
+  </codeline>
+
+  <codeline>
+    \> /teleport.example.com/node/bbb56211-7b54-4f9e-bee9-b68ea156be5f \
+  </codeline>
+
+  <codeline>
+    \>     --reason <request reason>
+  </codeline>
+</snippet>