fix: file modified issue

Author: devvaannsh

build/api-docs-generator.js

@@ -2,24 +2,49 @@ const fs = require('fs').promises;
 const path = require('path');
 const glob = require('glob');
 const util = require('util');
+const crypto = require('crypto');
 const exec = util.promisify(require('child_process').exec);
 
+// Promisify the glob function to enable async/await usage
+const globPromise = util.promisify(glob);
+
+// Constants
 const SRC_DIR = './src';
 const BUILD_DIR = './build';
 const TEMP_DIR = path.join(BUILD_DIR, 'temp');
 const MD_FILES_DIR = path.join('./docs', 'API-Reference');
+const TEMP_CHECK_DIR = path.join(BUILD_DIR, 'check_copy');
+const BATCH_SIZE = 12;
+
+
+/**
+ * Create directory
+ * @param {string} dirPath - The path where the directory will be created
+ */
+async function createDir(dirPath) {
+    await fs.mkdir(dirPath, { recursive: true });
+}
+
+
+/**
+ * Remove directory
+ * @param {string} dirPath - The path to the directory to remove
+ */
+async function removeDir(dirPath) {
+    await fs.rm(dirPath, { recursive: true, force: true });
+}
 
-const globPromise = util.promisify(glob);
 
 /**
  * Responsible to get the JS Files that are to be included in API DOCS
- * @returns {Promise<string[]>} Promise resolving to list of JS Files for API Docs
+ * @returns {Promise<string[]>} Promise resolving,list of JS Files for API Docs
  */
 async function getJsFiles() {
     const allJsFiles = await globPromise(`${SRC_DIR}/**/*.js`);
     const requiredJSfiles = [];
 
     await Promise.all(allJsFiles.map(async (file) => {
+        // Check if the path points to a valid file
         const stats = await fs.stat(file);
         if (stats.isFile()) {
             const content = await fs.readFile(file, 'utf-8');
@@ -32,32 +57,18 @@ async function getJsFiles() {
     return requiredJSfiles;
 }
 
-/**
- * Creates a directory
- * @param {string} dirPath creates dir at the given path
- */
-async function createDir(dirPath) {
-    await fs.mkdir(dirPath, { recursive: true });
-}
-
-/**
- * Deletes a directory
- * @param {string} dirPath deletes dir from the given path
- */
-async function removeDir(dirPath) {
-    await fs.rm(dirPath, { recursive: true, force: true });
-}
 
 /**
  * Adjusts JavaScript content for compatibility with jsdoc-to-markdown
  * @param {string} content The content to be modified
- * @param {string} fileName To replace the define block with this name
  * @returns {string} Updated content
  */
-function modifyJs(content, fileName) {
+function modifyJs(content) {
     if (content.includes('\n(function () {')) {
         content = content.replace(/\(function \(\) \{/, '');
+
         if (content.trim().endsWith('}());')) {
+            // Remove trailing IIFE closing
             content = content.trim().slice(0, -5);
         }
 
@@ -67,35 +78,42 @@ function modifyJs(content, fileName) {
                 bracketCount++;
             } else if (content[indx] === '}') {
                 bracketCount--;
-                if (bracketCount < 0) {
-                    let tempIndx = indx;
-                    while (content[indx] && content[indx] !== ')') {
-                        indx--;
-                    }
-                    content = content.slice(0, indx) + content.slice(tempIndx + 1);
-                    bracketCount++;
-                    break;
+            }
+
+            // Remove any unmatched closing brackets
+            if (bracketCount < 0) {
+                let tempIndx = indx;
+                while (content[indx] && content[indx] !== ')') {
+                    indx--;
                 }
+                content = content.slice(0, indx) + content.slice(tempIndx + 1);
+                bracketCount++;
+                break;
             }
         }
     } else if (content.includes('define(function')) {
         content = content.replace(/define\(function\s*\([^)]*\)\s*{/, '');
         if (content.trim().endsWith('});')) {
+            // Remove AMD-style wrapper
             content = content.trim().slice(0, -3);
         }
     }
     return content;
 }
 
+
 /**
- * Modifies markdown content for compatibility with docusaurus
- * @param {string} content markdown file content
- * @param {string} relativePath Relative path of the file from MD_FILES_DIR
- * @returns {string} updated markdown file content
+ * Adjusts markdown content for compatibility with Docusaurus
+ * Adds import examples and fixes formatting issues
+ * @param {string} content - Original markdown content
+ * @param {string} relativePath - Relative path to the JS file
+ * @returns {string} - Modified markdown content
  */
 function modifyMarkdown(content, relativePath) {
     const anchorIndex = content.indexOf('<a name');
     if (anchorIndex !== -1) {
+        // Remove every content that appears before anchor tag
+        // as non-required content might get generated
         content = content.slice(anchorIndex);
     }
 
@@ -104,13 +122,47 @@ function modifyMarkdown(content, relativePath) {
         path.basename(relativePath, '.md')
     ).replace(/\\/g, '/');
 
-    const importStatement = '### Import :\n' +
-        `\`\`\`js\nconst ${path.basename(relativePath, '.md')} = ` +
+    const importStatement = `### Import :\n` +
+        `\`\`\`js\n` +
+        `const ${path.basename(relativePath, '.md')} = ` +
         `brackets.getModule("${modulePath}")\n\`\`\`\n\n`;
 
+    // brackets~getModule is wrong
+    // brackets.getModule
     return importStatement + content.replace(/~/g, '.');
 }
 
+
+/**
+ * Normalizes line endings to LF (\n)
+ * to ensure consistent comparisons between files
+ * @param {string} content - Content with potentially mixed line endings
+ * @returns {string} - Content with normalized line endings
+ */
+function normalizeLineEndings(content) {
+    return content.replace(/\r\n|\r/g, '\n');
+}
+
+
+/**
+ * Compare two files based on their MD5 hash values
+ * @param {string} file1 - Path to the first file
+ * @param {string} file2 - Path to the second file
+ * @returns {Promise<boolean>} - True if files are different, false otherwise
+ */
+async function areFilesDifferent(file1, file2) {
+    const [content1, content2] = await Promise.all([
+        fs.readFile(file1, 'utf-8').then(normalizeLineEndings),
+        fs.readFile(file2, 'utf-8').then(normalizeLineEndings)
+    ]);
+
+    const hash1 = crypto.createHash('md5').update(content1).digest('hex');
+    const hash2 = crypto.createHash('md5').update(content2).digest('hex');
+
+    return hash1 !== hash2;
+}
+
+
 /**
  * Generates markdown documentation for a given JavaScript file
  * @param {string} file Path to the JavaScript file
@@ -127,15 +179,50 @@ async function generateMarkdown(file, relativePath) {
     await createDir(outputDir);
 
     const outputFileName = path.join(outputDir, `${fileName}.md`);
-    await exec(`npx jsdoc-to-markdown ${file} > ${outputFileName}`);
+    const tempOutputFileName = path.join(
+        TEMP_CHECK_DIR, `${fileName}_temp.md`
+    );
+
+    await createDir(TEMP_CHECK_DIR);
+
+    // Generate markdown to a temporary file
+    await exec(`npx jsdoc-to-markdown ${file} > ${tempOutputFileName}`);
+
+    let markdownContent = await fs.readFile(tempOutputFileName, 'utf-8');
+    const updatedMarkdownContent = modifyMarkdown(
+        markdownContent, path.join(relativePath, fileName)
+    );
+
+    await fs.writeFile(tempOutputFileName, updatedMarkdownContent, 'utf-8');
+
+    const fileExists = await fs.access(outputFileName).then(() => true).catch(
+        () => false
+    );
+
+    const shouldUpdate = !fileExists || await areFilesDifferent(
+        outputFileName, tempOutputFileName
+    );
 
-    const markdownContent = await fs.readFile(outputFileName, 'utf-8');
-    const updatedMarkdownContent = modifyMarkdown(markdownContent, path.join(relativePath, fileName));
-    await fs.writeFile(outputFileName, updatedMarkdownContent, 'utf-8');
+    if (shouldUpdate) {
+        await fs.rename(tempOutputFileName, outputFileName);
+        console.log(`Updated ${outputFileName}`);
+    } else {
+        await fs.unlink(tempOutputFileName);
+        console.log(`No changes in ${outputFileName}`);
+    }
 }
 
+
+/**
+ * Cleans up temp directories
+ */
+async function cleanupTempDir() {
+    await removeDir(TEMP_CHECK_DIR);
+}
+
+
 /**
- * Handles the execution and control flow of the program
+ * Driver function
  */
 async function driver() {
     try {
@@ -146,12 +233,12 @@ async function driver() {
         await createDir(TEMP_DIR);
         await createDir(MD_FILES_DIR);
 
-        // Process files in batches to avoid overwhelming the system
-        const BATCH_SIZE = 12;
         for (let i = 0; i < jsFiles.length; i += BATCH_SIZE) {
             const batch = jsFiles.slice(i, i + BATCH_SIZE);
             await Promise.all(batch.map(async (file) => {
-                const relativePath = path.relative(SRC_DIR, path.dirname(file));
+                const relativePath = path.relative(
+                    SRC_DIR, path.dirname(file)
+                );
                 const tempDirPath = path.join(TEMP_DIR, relativePath);
                 await createDir(tempDirPath);
 
@@ -165,11 +252,12 @@ async function driver() {
         }
 
         await removeDir(TEMP_DIR);
+        await cleanupTempDir();
         console.log("All files processed successfully!");
     } catch (error) {
         console.error("An error occurred:", error);
-        // Cleanup temp directory in case of error
         await removeDir(TEMP_DIR).catch(() => { });
+        await cleanupTempDir().catch(() => { });
     }
 }