Add option to resolve issues

Author: sebromero

Diff for: .vscode/launch.json

@@ -24,7 +24,7 @@
                 "<node_internals>/**"
             ],
             "program": "${workspaceFolder}/index.js",
-            "args": ["${userHome}/Repositories/sebromero/Arduino_NiclaLamon/src", "-f"]
+            "args": ["${userHome}/Repositories/arduino-libraries/Arduino_UnifiedStorage/src/UFile.h", "-f", "-r"]
         }
     ]
 }

Diff for: index.js

@@ -4,50 +4,19 @@ import moxygen from "moxygen";
 import assign from "object-assign";
 import { program } from "commander";
 import fs from "fs";
-import doxygen from "doxygen";
+import DoxygenRunner from "./doxygen-runner.js";
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
 import path from "path";
+import IssueResolver from "./issue-resolver.js";
+import { createDirectories } from "./helpers.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 const TEMPLATES_FOLDER = path.join(__dirname, "templates/cpp")
-const XML_FOLDER = "./build/xml/"
 const PROGRAMMING_LANGUAGE = "cpp"
-const DOXYGEN_FILE_PATH = "./doxygen.config"
-
-/**
- * Creates directories if they do not exist.
- * @param {string[]} dirs - An array of directory paths.
- */
-const createDirectories = (dirs) => {
-    for (const dir of dirs) {
-        if (!fs.existsSync(dir)) {
-            fs.mkdirSync(dir, { recursive: true })
-        }
-    }
-}
-
-/**
- * Cleans the specified directory by removing all files and subdirectories recursively.
- * @param {string} dir - The directory path to be cleaned.
- */
-const cleanDirectory = (dir) => {
-    if (fs.existsSync(dir)) {
-        const files = fs.readdirSync(dir)
-        for (const file of files) {
-            const path = dir + "/" + file
-            const stat = fs.statSync(path)
-            if (stat && stat.isDirectory()) {
-                cleanDirectory(path)
-                fs.rmdirSync(path)
-            } else {
-                fs.unlinkSync(path)
-            }
-        }
-    }
-}
+const XML_FOLDER = "./build/xml/"
 
 // Extract the command version from the package.json file
 const version = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.json'))).version;
@@ -65,6 +34,7 @@ program.option('-c, --include-cpp', 'Process .cpp files when rendering the docum
 program.option('-a, --access-level <string>', 'Minimum access level to be considered (public, private)', "public")
 program.option('-f, --fail-on-warnings', 'Fail when undocumented code is found', false)
 program.option('-d, --debug', 'Enable debugging mode with additional output.', false)
+program.option('-r, --resolve-issues', 'Automatically fix issues in the documentation', false)
 
 if (process.argv.length < 2) {
     program.help();
@@ -83,95 +53,37 @@ if (includeCppFiles) {
     fileExtensions.push("*.cpp")
 }
 
-if(outputXML){
-    cleanDirectory("./build")
-    createDirectories(["./build"])
-}
-
-// Check if output path exists. If not, create it.
-if(outputFile){
-    const outputFolder = path.dirname(outputFile)
-    createDirectories([outputFolder])
-}
-
-if(!doxygen.isDoxygenExecutableInstalled()) {
-    console.log(`Doxygen is not installed. Downloading ...`)
-    const success = await doxygen.downloadVersion();
-    if (!success) {
-        console.error("Failed to download Doxygen")
-        process.exit(1)
+try {    
+    const options = {
+        "outputXML": outputXML,
+        "xmlFolder": XML_FOLDER,
+        "sourceFolder": sourceFolder,
+        "fileExtensions": fileExtensions,
+        "exclude": commandOptions.exclude,
+        "accessLevel": commandOptions.accessLevel,
+        "failOnWarnings": commandOptions.failOnWarnings,
+        "debug": commandOptions.debug
     }
-}
-
-// The configuration options for Doxygen
-const doxyFileOptions = {
-    INPUT: sourceFolder,
-    RECURSIVE: "YES",
-    GENERATE_HTML: "NO",
-    GENERATE_LATEX: "NO",
-    GENERATE_XML: outputXML ? "YES" : "NO", // XML output is required for moxygen
-    XML_OUTPUT: XML_FOLDER,
-    CASE_SENSE_NAMES: "NO", // Creates case insensitive links compatible with GitHub
-    INCLUDE_FILE_PATTERNS: fileExtensions.join(" "),
-    EXCLUDE_PATTERNS: commandOptions.exclude ? commandOptions.exclude : "",
-    EXTRACT_PRIVATE: commandOptions.accessLevel === "private" ? "YES" : "NO",
-    EXTRACT_STATIC: "NO",
-    QUIET: commandOptions.debug ? "NO" : "YES",
-    WARN_NO_PARAMDOC: "YES", // Warn if a parameter is not documented
-    WARN_AS_ERROR: commandOptions.failOnWarnings ? "FAIL_ON_WARNINGS" : "NO", // Treat warnings as errors. Continues if warnings are found.
-}
-
-if(commandOptions.debug) console.log(`🔧 Creating Doxygen config file ${DOXYGEN_FILE_PATH} ...`)
-doxygen.createConfig(doxyFileOptions, DOXYGEN_FILE_PATH)
+    const doxygenRunner = new DoxygenRunner(options)
+    await doxygenRunner.run()
 
-try {
-    if(commandOptions.debug) console.log("🏃 Running Doxygen ...")
-    if(doxyFileOptions.GENERATE_XML === "YES") {
-        console.log(`🔨 Generating XML documentation at ${XML_FOLDER} ...`)
-    }
-    doxygen.run(DOXYGEN_FILE_PATH)
 } catch (error) {
-    // Replace all "\n  " with " " to meld the error messages into one line        
-    let errorMessages = error.stderr.toString().replace(/\n  /g, " ").split("\n")
-
-    // Filter out empty messages and allow only warnings related to documentation issues
-    const filteredMessages = errorMessages.filter(message => {
-        const warningMessageRegex = /^(?:[^:\n]+):(?:\d+): warning: (?:.+)$/
-        return message.match(warningMessageRegex)
-    })
-
-    if(commandOptions.debug){
-        // Print messages that were not filtered out and are not empty
-        const remainingMessages = errorMessages.filter(message => {
-            return !filteredMessages.includes(message) && message !== ""
-        })
-        for (const message of remainingMessages) {
-            console.warn(`🤔 ${message}`)
-        }
-    }
+    const validationMessages = error.messages
 
-    if(filteredMessages.length > 0 && commandOptions.failOnWarnings) {
+    if(validationMessages && commandOptions.failOnWarnings) {
         console.error("❌ Issues in the documentation were found.")
-        for (const message of filteredMessages) {
+        if(commandOptions.resolveIssues){
+            console.log("🔨 Resolving issues ...")
+            const resolver = new IssueResolver(validationMessages, "<key>")
+            await resolver.resolve()
+        }
+        for (const message of validationMessages) {
             console.warn(`😬 ${message}`)
         }
         process.exit(1)
     }
 }
 
-if(outputXML){
-    const xmlFiles = fs.readdirSync(XML_FOLDER)
-    if (xmlFiles.length === 0) {
-        console.error(`❌ No XML files found in ${XML_FOLDER}.`)
-        process.exit(1)
-    } else if(commandOptions.debug){
-        console.log(`✅ Found ${xmlFiles.length} XML files.`)
-        for (const file of xmlFiles) {
-            console.log(`📄 ${file}`)
-        }
-    }
-}
-
 // The configuration options for moxygen
 const moxygenOptions = {
     quiet: true,                /** Do not output anything to the console **/
@@ -201,6 +113,13 @@ const finalMoxygenOptions = assign({}, moxygen.defaultOptions, {
 });
 
 if(outputXML){
+    // Check if output path exists. If not, create it.
+    if(outputFile){
+        const outputFolder = path.dirname(outputFile)
+        if(commandOptions.debug) console.log(`🔧 Creating output directory ${outputFolder} ...`)
+        createDirectories([outputFolder])
+    }
+    
     moxygen.logger.init(finalMoxygenOptions);
     console.log("🔨 Generating markdown documentation...")
     moxygen.run(finalMoxygenOptions);

Diff for: issue-resolver.js

@@ -0,0 +1,68 @@
+import fs from "fs"
+import path from "path"
+import OpenAI from 'openai'
+
+class IssueResolver {
+    constructor(messages, apiKey = process.env["OPENAI_API_KEY"]) {
+        this.openai = new OpenAI({
+            apiKey: apiKey
+        });
+
+        this.messages = this.groupMessagesByFile(messages)
+    }
+    
+    groupMessagesByFile(messages){
+        return messages.reduce((accumulator, message) => {
+            // Messages are in the format "file:line: warning: message"
+            const [file, line, warning, ...rest] = message.split(":")
+            const key = `${file}`
+            if(!accumulator[key]) accumulator[key] = []
+            accumulator[key].push(`${line}: ${rest.join(":").trim()}`)
+            return accumulator
+        }, {})
+    }
+
+    constructPrompt(file, messages){
+        console.log(`📄 Constructing prompt for file ${file}`)
+        const fileContents = fs.readFileSync(file).toString()
+        const filename = path.basename(file)
+        const promptIntro = `There are some issues with the documentation in a C++ file (${filename}). Here is the code:\n\n\`\`\`cpp\n${fileContents}\n\`\`\``
+        const promptWarnings = `The following are the warnings generated by doxygen. They are in the format 'line: warning': \n\n\`\`\`\n${messages.join("\n")}\n\`\`\``
+        const promptOutro = `Could you please fix the issues? Please print the whole file including those fixes as a code block without any extra text or explanations.`
+        const constructedPrompt = `${promptIntro}\n\n${promptWarnings}\n\n${promptOutro}`
+        return constructedPrompt
+    }
+
+    async getResolvedFile(file){
+        const messages = this.messages[file]        
+        const prompt = this.constructPrompt(file, messages)
+        try {
+            const chatCompletion = await this.openai.chat.completions.create({
+                messages: [{ role: 'user', content: prompt }],
+                model: 'gpt-3.5-turbo',
+            });
+            console.log(chatCompletion)
+            const response = chatCompletion.data.choices[0].text
+            return response
+        } catch (error) {
+            console.error(`❌ Error resolving issues. ${error.message}`)
+            return null
+        }
+    }
+
+    async resolve() {
+        let result = true
+        
+        for (const file of Object.keys(this.messages)) {
+            const resolvedFile = await this.getResolvedFile(file)
+            if(resolvedFile){
+                fs.writeFileSync(file, resolvedFile)
+            } else {
+                result = false
+            }
+        }
+        return result
+    }
+}
+
+export default IssueResolver