Add comprehensive documentation for safety measures

- Document memory protection mechanisms in getFilesRecursive()
- Explain file count, path length, and recursion depth limits
- Improve code maintainability with clear safety constraints

Author: capricornusx

src/FSCommon.cpp

@@ -104,11 +104,36 @@ bool renameFile(const char *pathFrom, const char *pathTo)
 #define MAX_FILES_IN_MANIFEST 50 // Reduced to be more conservative with memory
 #define MAX_PATH_LENGTH 200      // Maximum allowed path length to prevent overflow
 
+/**
+ * @brief Helper function to validate and get file path for current platform
+ *
+ * @param file The file object
+ * @return const char* Valid path or nullptr if invalid
+ */
+static const char *getValidFilePath(File &file)
+{
+#ifdef ARCH_ESP32
+    const char *filePath = file.path();
+    return (filePath && strlen(filePath) < MAX_PATH_LENGTH) ? filePath : nullptr;
+#else
+    const char *fileName = file.name();
+    return (fileName && strlen(fileName) < MAX_PATH_LENGTH) ? fileName : nullptr;
+#endif
+}
+
 /**
  * @brief Get the list of files in a directory (internal recursive helper).
  *
+ * This function recursively lists files in the specified directory, subject to safety constraints
+ * to protect memory and stack usage:
+ * - Limits the total number of files collected to MAX_FILES_IN_MANIFEST (currently 50) to prevent memory overflow.
+ * - Limits the maximum allowed path length to MAX_PATH_LENGTH (currently 200) to prevent buffer overflow.
+ * - Limits recursion depth via the 'levels' parameter to avoid stack exhaustion.
+ *
+ * If any of these limits are reached, the function will stop collecting further files or recursing into subdirectories.
+ *
  * @param dirname The name of the directory.
- * @param levels The number of levels of subdirectories to list.
+ * @param levels The number of levels of subdirectories to list (recursion depth).
  * @param filenames Reference to vector to populate with file info.
  */
 static void getFilesRecursive(const char *dirname, uint8_t levels, std::vector<meshtastic_FileInfo> &filenames)
@@ -137,16 +162,10 @@ static void getFilesRecursive(const char *dirname, uint8_t levels, std::vector<m
 
         if (file.isDirectory() && !String(fileName).endsWith(".")) {
             if (levels > 0) { // Limit recursion depth
-#ifdef ARCH_ESP32
-                const char *filePath = file.path();
-                if (filePath && strlen(filePath) < MAX_PATH_LENGTH) {
-                    getFilesRecursive(filePath, levels - 1, filenames);
-                }
-#else
-                if (strlen(fileName) < MAX_PATH_LENGTH) {
-                    getFilesRecursive(fileName, levels - 1, filenames);
+                const char *validPath = getValidFilePath(file);
+                if (validPath) {
+                    getFilesRecursive(validPath, levels - 1, filenames);
                 }
-#endif
             }
             file.close();
         } else {

src/mesh/PhoneAPI.cpp

@@ -4,6 +4,7 @@
 #endif
 #ifdef ARCH_ESP32
 #include <esp_heap_caps.h>
+#define MIN_HEAP_FOR_FILE_MANIFEST 8192 // Minimum heap required before generating file manifest
 #endif
 
 #include "Channels.h"
@@ -72,7 +73,7 @@ void PhoneAPI::handleStartConfig()
     // Check available heap before getting files to prevent crash
 #ifdef ARCH_ESP32
     size_t freeHeap = ESP.getFreeHeap();
-    if (freeHeap < 8192) { // Require at least 8KB free heap
+    if (freeHeap < MIN_HEAP_FOR_FILE_MANIFEST) {
         LOG_WARN("Low memory (%d bytes), skipping file manifest", freeHeap);
         filesManifest.clear();
     } else {