Merge pull request #14 from pulsate-dev/feat/13-internal-spec-document

feat: 内部仕様のドキュメントを自動生成できるようにした

.gitignore

@@ -1,2 +1,3 @@
 build/
 theme/
+docs/

deno.jsonc

@@ -1,11 +1,13 @@
 {
-    "tasks": {
-        "build": "mdbook build",
-        "dev": "mdbook serve",
-        "watch": "mdbook watch",
-        "test": "mdbook test",
-        "clean": "mdbook clean",
-        "format": "deno fmt src/",
-        "format:check": "deno fmt --check src/"
-    }
+  "tasks": {
+    "build": "mdbook build",
+    "dev": "mdbook serve",
+    "watch": "mdbook watch",
+    "test": "mdbook test",
+    "clean": "mdbook clean",
+    "format": "deno fmt src/",
+    "format:check": "deno fmt --check src/",
+    "generate:doc": "deno run --allow-read --allow-write --allow-run scripts/generate.ts"
+  },
+  "imports": { "@std/fs": "jsr:@std/fs@^1.0.1" }
 }

scripts/generate.ts

@@ -0,0 +1,111 @@
+/*
+ * pulsate-dev/pulsate specification documentation generator
+ */
+import { walk } from "@std/fs";
+
+const viewCodePath =
+  "https://github.com/pulsate-dev/pulsate/tree/main" as const;
+const pathReplaceRegexp = new RegExp(/file:([a-zA-Z.0-9#;&]*?)"/, "g");
+// NOTE: basePath must set like this: "path/to/pkg/"
+const basePath = Deno.args[0];
+if (!basePath) {
+  throw new Error("ERROR: basePath is not set.");
+}
+
+const modules = [
+  "accounts",
+  "drive",
+  "notes",
+  "timeline",
+] as const;
+const packages = [
+  "adaptors",
+  "id/mod.ts",
+  "id/type.ts",
+  "intermodule",
+  "password",
+  "time",
+] as const;
+
+const moduleSourceDirs = [
+  "model",
+  "service",
+] as const;
+
+const sourcePaths = [
+  ...modules.map((module) => {
+    return moduleSourceDirs.map((dir) => {
+      return `${basePath}${module}/${dir}`;
+    });
+  }),
+  ...packages.map((pkg) => {
+    return `${basePath}${pkg}`;
+  }),
+];
+
+const command = await new Deno.Command("deno", {
+  args: [
+    "doc",
+    "--unstable-byonm",
+    "--unstable-sloppy-imports",
+    "--html",
+    "--name=pulsate",
+    ...sourcePaths.flat(),
+  ],
+}).output();
+console.log(new TextDecoder().decode(command.stderr));
+
+// remove *.test.ts files & directories
+const testFiles = [];
+for await (const v of walk("./docs", { includeSymlinks: false })) {
+  if (v.isFile) continue;
+  if (v.name.includes("test.ts")) {
+    testFiles.push(v.path);
+  }
+}
+
+for (const v of testFiles) {
+  Deno.removeSync(v, { recursive: true });
+}
+
+const replaceFileLink = async (path: string) => {
+  let file = await Deno.readTextFile(path);
+
+  const match = file.matchAll(pathReplaceRegexp);
+  if (!match) {
+    throw new Error("No match");
+  }
+
+  // file:以降を取得
+  const matchStrings = [...match].map((v) => v[1]);
+  const splited = matchStrings.map((v) => v.split("/"));
+
+  // pkg, module or package が連続していたらそれ以降を取得して結合
+  for (const [i, v] of splited.entries()) {
+    // pkgより後ろを取得
+    const last3 = v.slice(v.indexOf("pkg"));
+
+    // 前からpkg, module or packageが連続するかどうかをチェック
+    if (last3[0] !== "pkg") throw new Error("Not found pkg");
+    if (
+      !(modules.includes(last3[1] as typeof modules[number]) ||
+        packages.includes(last3[1] as typeof packages[number]))
+    ) {
+      // idの時は結合して合っているかを確かめる
+      const joined = last3.slice(1).join("/");
+      if (!packages.includes(joined as typeof packages[number])) {
+        throw new Error("Not found module or package");
+      }
+    }
+
+    const path = `${viewCodePath}/${last3.join("/")}`;
+
+    file = file.replaceAll(`file:${matchStrings[i]}`, path);
+  }
+  await Deno.writeTextFile(path, file, { append: false });
+};
+
+for await (const v of walk("./docs")) {
+  if (v.isDirectory) continue;
+  replaceFileLink(v.path);
+}