Fix: Address code review feedback - correct function purity documentation

Addresses Copilot AI code review feedback from PR #3.
Corrects mislabeled "pure" functions and fixes non-determinism issues.

ISSUES FIXED:

1. Non-Deterministic Function
   - OutputFormatter.SerializeToJson: Now accepts DateTime as parameter
   - Makes function deterministic (same inputs = same outputs)
   - DateTime.Now moved to call site (WriteToFile)

2. Mislabeled Pure Functions (performing I/O)
   GitHelper.cs:
   - HasGitDirectory: "pure predicate" → "I/O operation"
     (calls Directory.Exists)

   FileUtilities.cs:
   - IsStreamBinary: "pure function" → "I/O operation"
   - HasUtf8Bom: "pure function" → "I/O operation"
     (reads from stream, modifies position)
   - HasBinaryContent: "pure function" → "I/O operation"

   ProjectScanner.cs:
   - GetProjectStructureLines: "pure recursive" → "recursive I/O"
   - GetFilteredEntries: "pure function" → "I/O operation"
     (includes console logging side effects)
   - EnumerateFilesRecursively: "pure recursive" → "recursive I/O"
   - GetFilteredFiles: "pure enumeration" → "I/O operation"
   - GetFilteredDirectories: "pure enumeration" → "I/O operation"
   - ShouldIncludeEntry: "pure predicate" → "predicate (may perform I/O)"
   - ShouldIncludeFile: "pure predicate" → "predicate (may perform I/O)"
   - ShouldIncludeDirectory: "pure predicate" → "predicate (may perform I/O)"

   ConfigLoader.cs:
   - ParseConfig: "pure function" → documents console logging side effect

   ContentBuilder.cs:
   - BuildContentSections: "pure function" → "performs I/O via scanner"

   OutputFormatter.cs:
   - ResolveOutputPath: "pure function" → "I/O operation"
     (calls Directory.Exists)

   PathResolver.cs:
   - GetFolderName: "pure function" → "may perform I/O"
   - TryGetDirectoryName: "pure function" → "may perform I/O"
     (creates DirectoryInfo)
   - ExtractRootFolderName: "pure function" → "may perform I/O"
     (calls Path.GetFullPath)

PRINCIPLES CLARIFIED:

A function is only "pure" if:
1. Returns same output for same input (deterministic)
2. Has no observable side effects
3. Does not perform I/O operations
4. Does not modify external state
5. Does not depend on external mutable state

Functions that perform I/O, access file system, write to console,
or depend on current time are now correctly labeled as I/O operations
or documented with their side effects.

This maintains functional programming benefits while being honest
about where effects occur in the codebase.

Author: claude

Services/ConfigLoader.cs

@@ -44,7 +44,8 @@ private static Result<string> ReadConfigFile(string fileName)
     }
 
     /// <summary>
-    /// Pure function: parses JSON string into AppConfig.
+    /// Parses JSON string into AppConfig.
+    /// Includes console logging side effects on parse errors.
     /// </summary>
     private AppConfig ParseConfig(string json)
     {

Services/ContentBuilder.cs

@@ -27,7 +27,7 @@ public string Build(string projectPath, AppConfig config) =>
         string.Join("\n", BuildContentSections(projectPath, config));
 
     /// <summary>
-    /// Pure function that generates content sections based on configuration.
+    /// Generates content sections based on configuration (performs I/O via scanner).
     /// Uses declarative approach with LINQ and immutable collections.
     /// </summary>
     private IEnumerable<string> BuildContentSections(string projectPath, AppConfig config)

Services/OutputFormatter.cs

@@ -29,15 +29,16 @@ public string WriteToFile(string outputTarget, string content, string format, st
         _console.WriteLine("\n💾 Writing output...");
 
         var resolvedPath = ResolveOutputPath(outputTarget, defaultFileName);
-        var formattedContent = FormatContent(content, format);
+        var formattedContent = FormatContent(content, format, DateTime.Now);
 
         WriteFile(resolvedPath, formattedContent);
 
         return resolvedPath;
     }
 
     /// <summary>
-    /// Pure function: resolves output path based on target type.
+    /// I/O operation: resolves output path based on target type.
+    /// Checks if directory exists before combining paths.
     /// </summary>
     private static string ResolveOutputPath(string outputTarget, string defaultFileName) =>
         Directory.Exists(outputTarget)
@@ -61,16 +62,17 @@ private static void WriteFile(string filePath, string content)
     /// <summary>
     /// Pure function: formats content based on output format.
     /// </summary>
-    private static string FormatContent(string content, string format) =>
+    private static string FormatContent(string content, string format, DateTime timestamp) =>
         format.Equals("json", StringComparison.OrdinalIgnoreCase)
-            ? SerializeToJson(content)
+            ? SerializeToJson(content, timestamp)
             : content;
 
     /// <summary>
-    /// Pure function: serializes content to JSON with timestamp.
+    /// Pure function: serializes content to JSON with provided timestamp.
+    /// Deterministic - same inputs always produce same output.
     /// </summary>
-    private static string SerializeToJson(string content) =>
+    private static string SerializeToJson(string content, DateTime timestamp) =>
         JsonSerializer.Serialize(
-            new { content, timestamp = DateTime.Now },
+            new { content, timestamp },
             new JsonSerializerOptions { WriteIndented = true });
 }

Services/PathResolver.cs

@@ -54,8 +54,8 @@ private static string SelectPath(string userInput, string defaultPath) =>
         string.IsNullOrWhiteSpace(userInput) ? defaultPath : userInput;
 
     /// <summary>
-    /// Pure function: extracts a clean folder name from the input path for output file naming.
-    /// Uses functional composition to handle edge cases.
+    /// Extracts a clean folder name from the input path for output file naming.
+    /// Uses functional composition to handle edge cases. May perform I/O.
     /// </summary>
     /// <param name="path">The input path.</param>
     /// <returns>A sanitized folder name.</returns>
@@ -65,7 +65,7 @@ public static string GetFolderName(string path) =>
         ?? (IsPathSeparatorTerminated(path) ? ExtractRootFolderName(path) ?? "root" : "root");
 
     /// <summary>
-    /// Pure function: attempts to get directory name from path.
+    /// Attempts to get directory name from path (may perform I/O).
     /// Returns null if invalid or current directory marker.
     /// </summary>
     private static string? TryGetDirectoryName(string path)
@@ -88,7 +88,7 @@ private static bool IsPathSeparatorTerminated(string path) =>
         path.EndsWith(Path.AltDirectorySeparatorChar);
 
     /// <summary>
-    /// Pure function: extracts root folder name from path.
+    /// Extracts root folder name from path (may perform I/O).
     /// Removes path separators and drive colons.
     /// </summary>
     private static string? ExtractRootFolderName(string path) =>

Services/ProjectScanner.cs

@@ -67,7 +67,7 @@ public string GetProjectStructure(string projectPath, int indent = 0)
     }
 
     /// <summary>
-    /// Pure recursive function to generate directory structure lines.
+    /// Recursive function to generate directory structure lines (performs I/O).
     /// Uses lazy evaluation via yield return.
     /// </summary>
     private IEnumerable<string> GetProjectStructureLines(string directoryPath, ScanContext context, int indent)
@@ -96,7 +96,8 @@ private IEnumerable<string> GetProjectStructureLines(string directoryPath, ScanC
     }
 
     /// <summary>
-    /// Pure function to get filtered and sorted directory entries.
+    /// I/O operation: gets filtered and sorted directory entries.
+    /// Includes console logging side effects on errors.
     /// </summary>
     private IEnumerable<string> GetFilteredEntries(string directoryPath, string rootPath)
     {
@@ -120,7 +121,7 @@ private IEnumerable<string> GetFilteredEntries(string directoryPath, string root
     }
 
     /// <summary>
-    /// Pure predicate to determine if an entry should be included.
+    /// Predicate to determine if an entry should be included (may perform I/O).
     /// </summary>
     private bool ShouldIncludeEntry(string entryPath, string rootPath)
     {
@@ -172,7 +173,7 @@ public string GetFileContents(string projectPath)
     }
 
     /// <summary>
-    /// Pure recursive function to enumerate all files in directory tree.
+    /// Recursive I/O operation to enumerate all files in directory tree.
     /// Uses lazy evaluation via yield return.
     /// </summary>
     private IEnumerable<string> EnumerateFilesRecursively(string directory, string rootPath)
@@ -200,7 +201,8 @@ private IEnumerable<string> EnumerateFilesRecursively(string directory, string r
     }
 
     /// <summary>
-    /// Gets filtered files from a directory (pure enumeration).
+    /// I/O operation: gets filtered files from a directory.
+    /// Includes console logging side effects on errors.
     /// </summary>
     private IEnumerable<string> GetFilteredFiles(string directory, string rootPath, EnumerationOptions options)
     {
@@ -217,7 +219,7 @@ private IEnumerable<string> GetFilteredFiles(string directory, string rootPath,
     }
 
     /// <summary>
-    /// Gets filtered subdirectories from a directory (pure enumeration).
+    /// I/O operation: gets filtered subdirectories from a directory.
     /// </summary>
     private IEnumerable<string> GetFilteredDirectories(string directory, string rootPath, EnumerationOptions options)
     {
@@ -233,7 +235,7 @@ private IEnumerable<string> GetFilteredDirectories(string directory, string root
     }
 
     /// <summary>
-    /// Pure predicate to check if a file should be included.
+    /// Predicate to check if a file should be included (may perform I/O).
     /// </summary>
     private bool ShouldIncludeFile(string filePath, string rootPath)
     {
@@ -249,7 +251,7 @@ private bool ShouldIncludeFile(string filePath, string rootPath)
     }
 
     /// <summary>
-    /// Pure predicate to check if a directory should be included.
+    /// Predicate to check if a directory should be included (may perform I/O).
     /// </summary>
     private bool ShouldIncludeDirectory(string dirPath, string rootPath)
     {

Utils/FileUtilities.cs

@@ -40,15 +40,15 @@ private static bool CheckFileBinaryContent(string filePath, int chunkSize, doubl
     }
 
     /// <summary>
-    /// Pure function: analyzes stream content to determine if binary.
+    /// I/O operation: analyzes stream content to determine if binary.
     /// Checks for UTF-8 BOM first, then analyzes byte patterns.
     /// </summary>
     private static bool IsStreamBinary(FileStream stream, int chunkSize, double threshold) =>
         stream.Length > 0 && !HasUtf8Bom(stream) && HasBinaryContent(stream, chunkSize, threshold);
 
     /// <summary>
-    /// Pure function: checks if stream starts with UTF-8 BOM.
-    /// Resets stream position after checking.
+    /// I/O operation: checks if stream starts with UTF-8 BOM.
+    /// Resets stream position after checking (side effect).
     /// </summary>
     private static bool HasUtf8Bom(FileStream stream)
     {
@@ -65,7 +65,7 @@ private static bool HasUtf8Bom(FileStream stream)
     }
 
     /// <summary>
-    /// Pure function: checks if stream content exceeds binary threshold.
+    /// I/O operation: checks if stream content exceeds binary threshold.
     /// </summary>
     private static bool HasBinaryContent(FileStream stream, int chunkSize, double threshold)
     {

Utils/GitHelper.cs

@@ -39,7 +39,7 @@ var parent when string.IsNullOrEmpty(parent) => null,
             };
 
     /// <summary>
-    /// Pure predicate: checks if a directory contains a .git subdirectory.
+    /// I/O operation: checks if a directory contains a .git subdirectory.
     /// </summary>
     private static bool HasGitDirectory(string path) =>
         Directory.Exists(Path.Combine(path, ".git"));