SDK 파라미터 작성 간소화 (#717)

.npmrc

@@ -1 +1,2 @@
 node-options=--max-old-space-size=6144
+side-effects-cache=false

app.config.ts

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 
+import remarkParamTree from "@portone-io/remark-param-tree";
 import yaml from "@rollup/plugin-yaml";
 import rehypeShiki, { type RehypeShikiOptions } from "@shikijs/rehype";
 import { transformerMetaHighlight } from "@shikijs/transformers";
@@ -44,7 +45,7 @@ export default defineConfig({
           jsx: true,
           jsxImportSource: "solid-js",
           providerImportSource: "solid-mdx",
-          remarkPlugins: [remarkFrontmatter, remarkGfm],
+          remarkPlugins: [remarkFrontmatter, remarkGfm, remarkParamTree],
           rehypePlugins: [
             rehypeSlug,
             [

eslint.config.js

@@ -47,6 +47,7 @@ export default [
       "**/routes/(root)/docs/**/*",
       ".vinxi",
       ".output",
+      "packages/**/dist",
     ],
   },
   {

package.json

@@ -5,15 +5,17 @@
 	"license": "AGPL-3.0-or-later",
 	"repository": "https://github.com/portone-io/developers.portone.io",
 	"scripts": {
-		"dev": "concurrently -k \"vinxi dev\" \"pnpm gen-collections watch\"",
-		"build": "pnpm gen-collections && vinxi build",
+		"dev": "pnpm build:deps && concurrently -k \"vinxi dev\" \"pnpm gen-collections watch\"",
+		"build": "pnpm gen-collections && pnpm build:deps && vinxi build",
+		"build:deps": "pnpm --filter @portone-io/remark-param-tree build",
 		"start": "vinxi start",
 		"version": "vinxi version",
 		"check": "pnpm lint",
 		"gen-collections": "tsx src/genCollections.ts",
 		"lint:fix": "NODE_OPTIONS=\"$NODE_OPTIONS --loader ts-node/esm\" eslint --fix .",
 		"lint": "NODE_OPTIONS=\"$NODE_OPTIONS --loader ts-node/esm\" eslint .",
-		"eslint": "NODE_OPTIONS=\"$NODE_OPTIONS --loader ts-node/esm\" eslint"
+		"eslint": "NODE_OPTIONS=\"$NODE_OPTIONS --loader ts-node/esm\" eslint",
+		"postinstall": "pnpm build:deps"
 	},
 	"imports": {
 		"#content": "./src/content/__generated__/index.ts",
@@ -35,6 +37,7 @@
 		"@parcel/watcher": "^2.4.1",
 		"@portone-io/lint-local-links-valid": "workspace:^",
 		"@portone-io/lint-no-jamo": "workspace:^",
+		"@portone-io/remark-param-tree": "workspace:^",
 		"@portone/browser-sdk": "^0.0.10",
 		"@rollup/plugin-yaml": "^4.1.2",
 		"@shikijs/rehype": "^1.11.0",

packages/remark-param-tree/README.md

@@ -0,0 +1 @@
+## @portone-io/remark-param-tree

packages/remark-param-tree/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@portone-io/remark-param-tree",
+  "version": "0.0.1",
+  "repository": "https://github.com/portone-io/developers.portone.io",
+  "type": "module",
+  "private": true,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "test": "vitest",
+    "build": "rm -rf dist && rollup -c"
+  },
+  "dependencies": {
+    "mdast-util-from-markdown": "^2.0.1",
+    "mdast-util-to-string": "^4.0.0",
+    "ts-pattern": "^5.1.1",
+    "unified": "^11.0.5",
+    "unist-builder": "^4.0.0",
+    "unist-util-visit": "^5.0.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^20.12.7",
+    "@vitest/ui": "^1.5.3",
+    "fast-glob": "^3.3.2",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.0",
+    "remark-mdx": "^3.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-stringify": "^11.0.0",
+    "rollup": "^4.29.1",
+    "string-width": "^5.1.2",
+    "vfile": "^6.0.3",
+    "vite-tsconfig-paths": "^4.3.2",
+    "vitest": "^1.5.3"
+  }
+}

packages/remark-param-tree/rollup.config.js

@@ -0,0 +1,13 @@
+import typescript from "@rollup/plugin-typescript";
+import { defineConfig } from "rollup";
+
+export default defineConfig({
+  input: "src/index.ts",
+  output: [
+    {
+      format: "esm",
+      file: "dist/index.js",
+    },
+  ],
+  plugins: [typescript()],
+});

packages/remark-param-tree/scripts/migration.ts

@@ -0,0 +1,167 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import fastGlob from "fast-glob";
+import type {
+  Heading,
+  ListItem,
+  Paragraph,
+  PhrasingContent,
+  Root,
+} from "mdast";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { toString } from "mdast-util-to-string";
+import remarkFrontmatter from "remark-frontmatter";
+import remarkGfm from "remark-gfm";
+import remarkMdx from "remark-mdx";
+import remarkParse from "remark-parse";
+import remarkStringify from "remark-stringify";
+import stringWidth from "string-width";
+import { match, P } from "ts-pattern";
+import { unified } from "unified";
+import { SKIP, visit } from "unist-util-visit";
+
+type TypeDefinition = {
+  name: string;
+  type: string;
+  optional: boolean;
+};
+
+function migration() {
+  return function (tree: Root) {
+    visit(tree, "mdxJsxFlowElement", (node) => {
+      if (node.name === "ParamTree") {
+        const isNonEmptyTextNode = (child: PhrasingContent) =>
+          match(child)
+            .with(
+              {
+                type: "text",
+                value: P.when((value) => value.trim() === ""),
+              },
+              () => false,
+            )
+            .otherwise(() => true);
+        const generateTypeDefinition = (node: Paragraph | Heading) =>
+          match(node)
+            .with(
+              {
+                children: [
+                  { type: P.not(P.union("inlineCode", "strong")) },
+                  ...P.array(),
+                ],
+              },
+              () => null,
+            )
+            .with(
+              {
+                children: [
+                  { type: P.union("inlineCode", "strong") },
+                  {
+                    type: "mdxJsxTextElement",
+                    name: "mark",
+                  },
+                ],
+              },
+              (typeDefinition) => {
+                return {
+                  name: toString(typeDefinition.children[0]),
+                  type: toString(typeDefinition.children[1]),
+                  optional: true,
+                } satisfies TypeDefinition;
+              },
+            )
+            .with(
+              {
+                children: [
+                  { type: P.union("inlineCode", "strong") },
+                  {
+                    type: "mdxJsxTextElement",
+                    name: "mark",
+                  },
+                  {
+                    type: "mdxJsxTextElement",
+                    name: "mark",
+                  },
+                ],
+              },
+              (typeDefinition) => {
+                return {
+                  name: toString(typeDefinition.children[0]),
+                  type: toString(typeDefinition.children[2]),
+                  optional: false,
+                } satisfies TypeDefinition;
+              },
+            )
+            .otherwise(() => {
+              // console.log(workingFile, toString(listItem.children[0]));
+              return null;
+            });
+        const transformNode = (node: ListItem | Heading) => {
+          match(node)
+            .with(
+              {
+                type: "listItem",
+                children: [{ type: "paragraph" }, ...P.array()],
+              },
+              (node) => {
+                node.children[0].children =
+                  node.children[0].children.filter(isNonEmptyTextNode);
+                const typeDefinition = generateTypeDefinition(node.children[0]);
+                if (typeDefinition) {
+                  node.children[0] = fromMarkdown(
+                    `${typeDefinition.name}${typeDefinition.optional ? "?" : ""}: ${typeDefinition.type}`,
+                    "utf-8",
+                  ).children[0] as Paragraph;
+                }
+              },
+            )
+            .with({ type: "heading" }, (node) => {
+              node.children = node.children.filter(isNonEmptyTextNode);
+              const typeDefinition = generateTypeDefinition(node);
+              if (typeDefinition) {
+                node.children = fromMarkdown(
+                  `${typeDefinition.name}${typeDefinition.optional ? "?" : ""}: ${typeDefinition.type}`,
+                  "utf-8",
+                ).children as PhrasingContent[];
+              }
+            })
+            .otherwise(() => null);
+          if (!node) {
+            return;
+          }
+        };
+        visit(node, "listItem", transformNode);
+        visit(node, "heading", transformNode);
+        return SKIP;
+      }
+      return;
+    });
+  };
+}
+
+const files = await fastGlob("**/*.mdx", {
+  cwd: path.resolve(import.meta.dirname, "../../../src/routes/(root)"),
+  absolute: true,
+  onlyFiles: true,
+});
+
+const processor = unified()
+  .use(remarkParse)
+  .use(remarkFrontmatter)
+  .use(remarkMdx)
+  .use(remarkGfm, { tableCellPadding: false, stringLength: stringWidth })
+  .use(migration)
+  .use(remarkStringify)
+  .data("settings", {
+    bullet: "-",
+    rule: "-",
+    emphasis: "_",
+  });
+
+await Promise.all(
+  files.map(async (file) => {
+    const content = await fs.readFile(file, "utf-8");
+    const vFile = await processor.process(content);
+    await fs.writeFile(file, vFile.toString());
+  }),
+);