Allow submodule version aliases for import paths (#202)

* Allow submodule version aliases for import paths

Closes #195

Add a `remark` plugin that lets a docs author include an `import`
statement that points to a directory in the current version submodule of
the docs site. This makes it possible to import the path of a static
asset or, with the `!!raw-loader!` directive, the full content, using an
`import` statement, without having to know which versioned submodule an
asset is in at a given time.

To use this, add the string `@version` to the start of an import path,
e.g.,:

```jsx
import PNGPath from '@version/docs/img/myimg.png'
```

In a `gravitational/teleport` clone at the current default version of
the docs site, the new plugin would add the following:

```jsx
import PNGPath from '@site/content/17.x/docs/img/myimg.png'
```

Note that we currently use a workaround in which we place some static
assets in the `/static` directory, which exists outside the submodule
directory tree. This is approach is cumbersome since it requires a
change to `docs-website` for every asset we want to include using an
`import` statement.

The `@site` alias is a Docusaurus feature that the docs engine replaces
with the root path of the Docusaurus project. The plugin fills in the
path of the current `gravitational/teleport` submodule.

To import the content of a text asset, rather than the file path, you
would use the `!!raw-loader` syntax as you would for any Docusaurus
asset:

```jsx
import PNGPath from '!!raw-loader!@version/docs/img/myimg.png'
```

* Fix dependency configurations

Revert unnecessary dependency changes. Remove @types/estree. Also remove
an extraneous `mdast-util-mdxjs-esm` mention in `package.json`.

Add swc/core to the list of dependencies with allowed licenses for the
dependency review workflow. While the package uses the Apache 2.0
license, which is already configured as allowed in the workflow, the
workflow also detects an unknown license that does not appear to be
present in the package's code repository.

Author: ptgott

.github/workflows/dependency-review.yaml

@@ -12,7 +12,12 @@ jobs:
     with:
       allow-additional-licenses: >
         LicenseRef-scancode-public-domain AND Unlicense
+      # @swc/core@1.11.24 uses Apache-2.0, but
+      # LicenseRef-scancode-unknown-license-reference is also detected.
+      # https://www.npmjs.com/package/@swc/core/v/1.11.24?activeTab=code
+      # https://scancode-licensedb.aboutcode.org/unknown-license-reference.html
       allow-dependencies-licenses: >
+        pkg:npm/swc/core,
         pkg:npm/%40inkeep/cxkit-color-mode,
         pkg:npm/%40inkeep/cxkit-primitives,
         pkg:npm/%40inkeep/cxkit-react,

docusaurus.config.ts

@@ -12,6 +12,7 @@ import {
 import remarkUpdateAssetPaths from "./server/remark-update-asset-paths";
 import remarkIncludes from "./server/remark-includes";
 import remarkVariables from "./server/remark-variables";
+import remarkVersionAlias from "./server/remark-version-alias";
 import remarkCodeSnippet from "./server/remark-code-snippet";
 import { fetchVideoMeta } from "./server/youtube-meta";
 import { getRedirects } from "./server/redirects";
@@ -214,6 +215,7 @@ const config: Config = {
         versions: getDocusaurusConfigVersionOptions(),
         // Our custom plugins need to be before default plugins
         beforeDefaultRemarkPlugins: [
+          [remarkVersionAlias, latestVersion],
           [
             remarkIncludes,
             {

package.json

@@ -66,6 +66,7 @@
     "nanoid": "^5.1.0",
     "postcss-preset-env": "^10.1.6",
     "prism-react-renderer": "^2.3.0",
+    "raw-loader": "^4.0.2",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-loadable": "^5.5.0",
@@ -139,4 +140,4 @@
   "engines": {
     "node": ">=18.0"
   }
-}
+}

server/remark-version-alias.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from "@jest/globals";
+import { VFile, VFileOptions } from "vfile";
+import { remark } from "remark";
+import mdx from "remark-mdx";
+import remarkVersionAlias from "./remark-version-alias";
+import remarkFrontmatter from "remark-frontmatter";
+
+const transformer = (vfileOptions: VFileOptions) => {
+  const file: VFile = new VFile(vfileOptions);
+
+  return remark()
+    .use(mdx as any)
+    .use(remarkFrontmatter) // Test cases use frontmatter
+    .use(remarkVersionAlias as any, "15.x")
+    .processSync(file as any);
+};
+
+describe("server/remark-version-alias", () => {
+  interface testCase {
+    description: string;
+    input: string;
+    expected: string;
+    path: string;
+  }
+
+  const testCases: Array<testCase> = [
+    {
+      description: "import statement in latest-version docs path",
+      input: `---
+title: My page
+description: My page
+---
+
+import CodeExample from "@version/examples/access-plugin-minimal/config.go"
+
+This is a paragraph.`,
+      expected: `---
+title: My page
+description: My page
+---
+
+import CodeExample from '@site/content/15.x/examples/access-plugin-minimal/config.go'
+
+This is a paragraph.
+`,
+      path: "docs/mypage.mdx",
+    },
+    {
+      description: "import statement in non-latest docs path",
+      input: `---
+title: My page
+description: My page
+---
+
+import CodeExample from "@version/examples/access-plugin-minimal/config.go"
+
+This is a paragraph.`,
+      expected: `---
+title: My page
+description: My page
+---
+
+import CodeExample from '@site/content/16.x/examples/access-plugin-minimal/config.go'
+
+This is a paragraph.
+`,
+      path: "versioned_docs/version-16.x/mypage.mdx",
+    },
+{
+      description: "raw loader",
+      input: `---
+title: My page
+description: My page
+---
+
+import CodeExample from "!!raw-loader!@version/examples/access-plugin-minimal/config.go"
+
+This is a paragraph.`,
+      expected: `---
+title: My page
+description: My page
+---
+
+import CodeExample from '!!raw-loader!@site/content/16.x/examples/access-plugin-minimal/config.go'
+
+This is a paragraph.
+`,
+      path: "versioned_docs/version-16.x/mypage.mdx",
+    },
+  ];
+
+  test.each(testCases)("$description", (tc) => {
+    const result = transformer({
+      value: tc.input,
+      path: tc.path,
+    }).toString();
+
+    expect(result).toEqual(tc.expected);
+  });
+});

server/remark-version-alias.ts

@@ -0,0 +1,54 @@
+import type { MdxjsEsm } from "mdast-util-mdxjs-esm";
+import type { Root, Paragraph, Literal } from "mdast";
+import type { VFile } from "vfile";
+import type { Transformer } from "unified";
+import type { Node } from "unist";
+import { visit, CONTINUE, SKIP } from "unist-util-visit";
+
+const versionedDocsPattern = `versioned_docs/version-([0-9]+\\.x)/`;
+
+export default function remarkVersionAlias(latestVersion: string): Transformer {
+  return (root: Root, vfile: VFile) => {
+    visit(root, (node: Node) => {
+      if (node.type != "mdxjsEsm") {
+        return CONTINUE;
+      }
+
+      // Only process import statements that import an identifier from a default
+      // export.
+      const esm = node as unknown as MdxjsEsm;
+      if (
+        !esm.data ||
+        !esm.data.estree ||
+        esm.data.estree.body.length !== 1 ||
+        esm.data.estree.body[0]["type"] != "ImportDeclaration" ||
+        esm.data.estree.body[0].specifiers.length !== 1 ||
+        esm.data.estree.body[0].specifiers[0].type != "ImportDefaultSpecifier"
+      ) {
+        return CONTINUE;
+      }
+
+      let version: string = latestVersion;
+      const versionedPathParts = vfile.path.match(versionedDocsPattern);
+      if (versionedPathParts) {
+        version = versionedPathParts[1];
+      }
+
+      const decl = esm.data.estree.body[0];
+
+      const newPath = (decl.source.value as string).replace(
+        "@version",
+        `@site/content/${version}`,
+      );
+
+      esm.value = `import ${esm.data.estree.body[0].specifiers[0].local.name} from '${newPath}'`;
+      decl.source = {
+        type: "Literal",
+        value: newPath,
+        raw: `"${newPath}"`,
+      };
+
+      return SKIP;
+    });
+  };
+}