Merge pull request #56 from open-rpc/fix/race

Fix/race

Author: zcstarr

.changeset/beige-hounds-jump.md

@@ -0,0 +1,6 @@
+---
+"@open-rpc/markdown-generator": patch
+"@open-rpc/docusaurus-plugin": patch
+---
+
+Fixes a race condition when running in active development mode. This set of changes now allows for incremental deletion and proper removal ordering

packages/docusaurus-plugin/src/index.ts

@@ -5,37 +5,22 @@ import type { LoadContext, Plugin } from "@docusaurus/types";
 import type { PluginContent } from "./types";
 import type { Options, PluginOptions } from "./options";
 import { normalizeOptions } from "./options";
-import { generateDocs } from "./lib";
+import { cleanUpExistingDocs, generateDocs } from "./lib";
 import fs from "fs/promises";
 import path from "path";
+import { parseOpenRPCDocument } from "@open-rpc/schema-utils-js";
+import { DereffedOpenrpcDocument } from "@open-rpc/markdown-generator";
 
 const PluginName = "@open-rpc/docusaurus-plugin";
 
-async function initDocs(
+async function rebuildDocs(
   specPath: string,
   outputDir: string,
   options: PluginOptions,
 ) {
-  if (!(await fs.stat(specPath)).isFile()) {
-    throw new Error(`OpenRPC spec file not found: ${specPath}`);
-  }
-
-  try {
-    const entries = await fs.readdir(outputDir, { withFileTypes: true });
-    await Promise.all(
-      entries
-        .filter((entry) => entry.name !== "index.md")
-        .map((entry) => {
-          const fullPath = `${outputDir}/${entry.name}`;
-          return fs.rm(fullPath, { recursive: true, force: true });
-        }),
-    );
-  } catch {
-    // Directory doesn't exist yet, that's fine
-  }
-
   try {
     await generateDocs(specPath, outputDir, options);
+    await cleanUpExistingDocs(specPath, outputDir);
   } catch (err) {
     logger.error(`[${PluginName}] generateDocs failed: ${err}`);
     logger.error(
@@ -61,7 +46,7 @@ export default async function openRPCDocusaurusPlugin(
     normalizedOptions.docOutputPath,
   );
 
-  await initDocs(specPath, outputDir, normalizedOptions);
+  await rebuildDocs(specPath, outputDir, normalizedOptions);
 
   return {
     name: PluginName,
@@ -95,7 +80,7 @@ export default async function openRPCDocusaurusPlugin(
      */
     async contentLoaded({ content, actions }): Promise<void> {
       logger.info(`[${PluginName}] contentLoaded called`);
-      await initDocs(specPath, outputDir, normalizedOptions);
+      await rebuildDocs(specPath, outputDir, normalizedOptions);
     },
 
     /**

packages/docusaurus-plugin/src/lib.ts

@@ -58,6 +58,39 @@ methodEdits.editMethod = (content, method) => {
   ] as OpenRPCMdContent[];
 };
 
+export async function cleanUpExistingDocs(specPath: string, outputDir: string) {
+  if (!(await fs.stat(specPath)).isFile()) {
+    throw new Error(`OpenRPC spec file not found: ${specPath}`);
+  }
+  const raw = await fs.readFile(specPath, "utf8");
+  const doc: DereffedOpenrpcDocument = (await parseOpenRPCDocument(
+    raw,
+  )) as DereffedOpenrpcDocument;
+
+  const methodFileNamesToGenerate = new Set(
+    doc.methods.map((method) => `${method.name}.mdx`),
+  );
+  const entries = await fs.readdir(outputDir, {
+    withFileTypes: true,
+    recursive: true,
+  });
+
+  const entriesToDelete = entries
+    .filter(
+      (entry) =>
+        entry.isFile() &&
+        methodFileNamesToGenerate.has(entry.name) === false &&
+        entry.name !== "index.md",
+    )
+    .map((entry) => `${entry.parentPath}/${entry.name}`);
+
+  await Promise.all(
+    entriesToDelete.map((entry) =>
+      fs.rm(entry, { recursive: true, force: true }),
+    ),
+  );
+}
+
 export async function generateDocs(
   inputPath: string,
   outputPath: string,

packages/example-site/docs/api-reference/index.md

@@ -2,7 +2,7 @@
 # GENERATED DOCUMENTATION - DO NOT EDIT THIS FILE
 title: "Ethereum JSON-RPC Specification"
 description: "A specification of the standard interface for Ethereum clients."
-slug: /api-reference
+
 
 ---
 

packages/example-site/docusaurus.config.ts

@@ -39,7 +39,6 @@ const config: Config = {
       openRPCSpecPath: `./error-group-openrpc.json`,
       docOutputPath: `./docs/api-reference`,
       showPoweredBy: true,
-      indexSlug: '/api-reference',
   }]],
   presets: [
     [