chore: a tiny bit safer approach

src/generators/legacy-html/index.mjs

@@ -1,6 +1,6 @@
 'use strict';
 
-import { readFile, rm, writeFile, mkdir } from 'node:fs/promises';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import HTMLMinifier from '@minify-html/node';
@@ -176,11 +176,6 @@ export default {
       // Define the output folder for API docs assets
       const assetsFolder = join(output, 'assets');
 
-      // Removes the current assets directory to copy the new assets
-      // and prevent stale assets from existing in the output directory
-      // If the path does not exists, it will simply ignore and continue
-      await rm(assetsFolder, { recursive: true, force: true, maxRetries: 10 });
-
       // Creates the assets folder if it does not exist
       await mkdir(assetsFolder, { recursive: true });
 

src/generators/legacy-html/utils/__tests__/safeCopy.test.mjs

@@ -0,0 +1,126 @@
+'use strict';
+
+import assert from 'node:assert';
+import { mkdir, readFile, rm, utimes, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, it } from 'node:test';
+
+import { safeCopy } from '../safeCopy.mjs';
+
+describe('safeCopy', () => {
+  const testDir = join(import.meta.dirname, 'test-safe-copy');
+  const srcDir = join(testDir, 'src');
+  const targetDir = join(testDir, 'target');
+
+  beforeEach(async () => {
+    // Create test directories
+    await mkdir(srcDir, { recursive: true });
+    await mkdir(targetDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    // Clean up test directories
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  it('should copy new files that do not exist in target', async () => {
+    // Create a file in source
+    await writeFile(join(srcDir, 'file1.txt'), 'content1');
+
+    await safeCopy(srcDir, targetDir);
+
+    // Verify file was copied
+    const content = await readFile(join(targetDir, 'file1.txt'), 'utf-8');
+    assert.strictEqual(content, 'content1');
+  });
+
+  it('should copy multiple files', async () => {
+    // Create multiple files in source
+    await writeFile(join(srcDir, 'file1.txt'), 'content1');
+    await writeFile(join(srcDir, 'file2.txt'), 'content2');
+    await writeFile(join(srcDir, 'file3.txt'), 'content3');
+
+    await safeCopy(srcDir, targetDir);
+
+    // Verify all files were copied
+    const content1 = await readFile(join(targetDir, 'file1.txt'), 'utf-8');
+    const content2 = await readFile(join(targetDir, 'file2.txt'), 'utf-8');
+    const content3 = await readFile(join(targetDir, 'file3.txt'), 'utf-8');
+
+    assert.strictEqual(content1, 'content1');
+    assert.strictEqual(content2, 'content2');
+    assert.strictEqual(content3, 'content3');
+  });
+
+  it('should skip files with same size and older modification time', async () => {
+    // Create file in source with specific size
+    const content = 'same content';
+    await writeFile(join(srcDir, 'file1.txt'), content);
+
+    // Make source file old
+    const oldTime = new Date(Date.now() - 10000);
+    await utimes(join(srcDir, 'file1.txt'), oldTime, oldTime);
+
+    // Create target file with same size but different content and newer timestamp
+    await writeFile(join(targetDir, 'file1.txt'), 'other things');
+
+    await safeCopy(srcDir, targetDir);
+
+    // Verify file was not overwritten (source is older)
+    const targetContent = await readFile(join(targetDir, 'file1.txt'), 'utf-8');
+    assert.strictEqual(targetContent, 'other things');
+  });
+
+  it('should copy files when source has newer modification time', async () => {
+    // Create files in both directories
+    await writeFile(join(srcDir, 'file1.txt'), 'new content');
+    await writeFile(join(targetDir, 'file1.txt'), 'old content');
+
+    // Make target file older
+    const oldTime = new Date(Date.now() - 10000);
+    await utimes(join(targetDir, 'file1.txt'), oldTime, oldTime);
+
+    await safeCopy(srcDir, targetDir);
+
+    // Verify file was updated
+    const content = await readFile(join(targetDir, 'file1.txt'), 'utf-8');
+    assert.strictEqual(content, 'new content');
+  });
+
+  it('should copy files when sizes differ', async () => {
+    // Create files with different sizes
+    await writeFile(join(srcDir, 'file1.txt'), 'short');
+    await writeFile(join(targetDir, 'file1.txt'), 'much longer content');
+
+    await safeCopy(srcDir, targetDir);
+
+    // Verify file was updated
+    const content = await readFile(join(targetDir, 'file1.txt'), 'utf-8');
+    assert.strictEqual(content, 'short');
+  });
+
+  it('should handle empty source directory', async () => {
+    // Don't create any files in source
+    await safeCopy(srcDir, targetDir);
+
+    // Verify no error occurred and target is still empty
+    const files = await readFile(targetDir).catch(() => []);
+    assert.ok(Array.isArray(files) || files === undefined);
+  });
+
+  it('should copy files with same size but different content when mtime is newer', async () => {
+    // Create files with same size but different content
+    await writeFile(join(srcDir, 'file1.txt'), 'abcde');
+    await writeFile(join(targetDir, 'file1.txt'), 'fghij');
+
+    // Make target older
+    const oldTime = new Date(Date.now() - 10000);
+    await utimes(join(targetDir, 'file1.txt'), oldTime, oldTime);
+
+    await safeCopy(srcDir, targetDir);
+
+    // Verify file was updated with source content
+    const content = await readFile(join(targetDir, 'file1.txt'), 'utf-8');
+    assert.strictEqual(content, 'abcde');
+  });
+});

src/generators/legacy-html/utils/safeCopy.mjs

@@ -1,11 +1,12 @@
 'use strict';
 
-import { readFile, writeFile, stat, readdir } from 'node:fs/promises';
+import { copyFile, readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 
 /**
  * Safely copies files from source to target directory, skipping files that haven't changed
- * based on file stats (size and modification time)
+ * based on file stats (size and modification time). Uses native fs.copyFile which handles
+ * concurrent operations gracefully.
  *
  * @param {string} srcDir - Source directory path
  * @param {string} targetDir - Target directory path
@@ -31,8 +32,8 @@ export async function safeCopy(srcDir, targetDir) {
       continue;
     }
 
-    const fileContent = await readFile(sourcePath);
-
-    await writeFile(targetPath, fileContent);
+    // Use copyFile with COPYFILE_FICLONE flag for efficient copying
+    // This is atomic and handles concurrent operations better than manual read/write
+    await copyFile(sourcePath, targetPath);
   }
 }