stable release 1.0.1

Author: Spexx

src/main/java/dev/spexx/configurationAPI/ConfigurationAPI.java

@@ -1,6 +1,7 @@
 package dev.spexx.configurationAPI;
 
 import dev.spexx.configurationAPI.config.YamlConfig;
+import dev.spexx.configurationAPI.difference.ConfigLineDiff;
 import dev.spexx.configurationAPI.events.ConfigReloadedEvent;
 import dev.spexx.configurationAPI.manager.ConfigManager;
 import org.bukkit.event.EventHandler;
@@ -60,6 +61,26 @@ public void onDisable() { }
      */
     @EventHandler
     public void onReload(@NotNull ConfigReloadedEvent event) {
+
+        for (ConfigLineDiff diff : event.getDiffs()) {
+
+            int delta = diff.getCharDelta();
+            String sign = delta > 0 ? "+" : "";
+
+            String type =
+                    diff.getOldLine().isEmpty() ? "ADDED" :
+                            diff.getNewLine().isEmpty() ? "REMOVED" :
+                                    diff.isOnlyWhitespaceChange() ? "WHITESPACE" :
+                                            "MODIFIED";
+
+            getLogger().info(() ->
+                    "[ConfigWatcher] file=" + event.getConfig().file().getName()
+                            + " line=" + diff.getLineNumber()
+                            + " type=" + type
+                            + " delta=" + sign + delta
+            );
+        }
+
         getLogger().info("Config reloaded: " +
                 event.getConfig().file().getName());
 

src/main/java/dev/spexx/configurationAPI/difference/ConfigLineDiff.java

@@ -71,6 +71,48 @@ public ConfigLineDiff(int lineNumber,
         this.charDelta = newLine.length() - oldLine.length();
     }
 
+    /**
+     * Determines whether the difference between the old and new line
+     * consists solely of whitespace changes.
+     *
+     * <p>This method ignores all whitespace characters (spaces, tabs,
+     * and other Unicode whitespace) and compares the normalized content
+     * of both lines.</p>
+     *
+     * <p>Examples:</p>
+     * <ul>
+     *     <li>{@code "value: 1"} vs {@code "value: 1   "} → {@code true}</li>
+     *     <li>{@code "value:    1"} vs {@code "value: 1"} → {@code true}</li>
+     *     <li>{@code "value: 1"} vs {@code "value: 2"} → {@code false}</li>
+     * </ul>
+     *
+     * @return {@code true} if only whitespace differs, {@code false} otherwise
+     *
+     * @apiNote
+     * This method performs a lightweight normalization by removing all
+     * whitespace characters before comparison.
+     *
+     * @implSpec
+     * The comparison is based on {@code String.replaceAll("\\s+", "")}.
+     *
+     * @implNote
+     * This method does not perform semantic or structural comparison.
+     * It is intended for quick detection of formatting-only changes.
+     *
+     * @since 1.0.1
+     */
+    public boolean isOnlyWhitespaceChange() {
+        return !oldLine.equals(newLine)
+                && normalize(oldLine).equals(normalize(newLine));
+    }
+
+    /**
+     * Normalizes a line by removing all whitespace characters.
+     */
+    private static @NotNull String normalize(@NotNull String input) {
+        return input.replaceAll("\\s+", "");
+    }
+
     /**
      * Returns the line number where the change occurred.
      *

src/main/java/dev/spexx/configurationAPI/events/ConfigReloadedEvent.java

@@ -6,6 +6,8 @@
 import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
+import java.util.ArrayList;
+import java.util.Collection;
 import java.util.List;
 
 /**
@@ -52,9 +54,9 @@ public final class ConfigReloadedEvent extends Event {
      * @param changedLines  number of modified lines
      * @param addedLines    number of added lines
      * @param removedLines  number of removed lines
-     * @param diffs         list of line-level differences
+     * @param diffs         list of line-level differences, must not be {@code null}
      *
-     * @since 1.0
+     * @since 1.0.0
      */
     public ConfigReloadedEvent(
             @NotNull YamlConfig config,
@@ -71,7 +73,7 @@ public ConfigReloadedEvent(
         this.changedLines = changedLines;
         this.addedLines = addedLines;
         this.removedLines = removedLines;
-        this.diffs = diffs;
+        this.diffs = List.copyOf(new ArrayList<>(diffs));
     }
 
     /**
@@ -143,14 +145,58 @@ public int getRemovedLines() {
     /**
      * Returns the list of detected line-level differences.
      *
-     * @return immutable diff list
+     * <p>The returned list is immutable and reflects the exact state at the time
+     * the event was created.</p>
      *
-     * @since 1.0
+     * @return immutable list of diffs, never {@code null}
+     *
+     * @apiNote
+     * The returned list is safe for concurrent iteration without additional synchronization.
+     *
+     * @implSpec
+     * Backed by {@link List#copyOf(Collection)} to guarantee immutability.
+     *
+     * @since 1.0.0
      */
     public @NotNull List<ConfigLineDiff> getDiffs() {
         return diffs;
     }
 
+    /**
+     * Indicates whether any changes were detected during the reload operation.
+     *
+     * <p>This is a convenience method that aggregates the individual change counters
+     * exposed by this event.</p>
+     *
+     * <p>A configuration is considered changed if at least one of the following is true:</p>
+     * <ul>
+     *     <li>One or more existing lines were modified</li>
+     *     <li>One or more lines were added</li>
+     *     <li>One or more lines were removed</li>
+     * </ul>
+     *
+     * @apiNote
+     * This method provides a fast and expressive way to determine whether meaningful
+     * changes occurred without inspecting individual counters.
+     *
+     * @implSpec
+     * This method returns {@code true} if any of the internal counters
+     * ({@code changedLines}, {@code addedLines}, {@code removedLines})
+     * is greater than zero.
+     *
+     * @implNote
+     * In normal operation, this method should always return {@code true} for fired events,
+     * as events are only emitted when a checksum difference is detected. It is provided
+     * for defensive usage and future extensibility.
+     *
+     * @return {@code true} if changes were detected, {@code false} otherwise
+     *
+     * @since 1.0.1
+     */
+    public boolean hasChanges() {
+        return changedLines > 0 || addedLines > 0 || removedLines > 0;
+    }
+
     @Override
     public @NotNull HandlerList getHandlers() {
         return HANDLERS;

src/main/java/dev/spexx/configurationAPI/watcher/YamlConfigWatcher.java

@@ -226,17 +226,42 @@ private void run() {
     }
 
     /**
-     * Performs checksum validation, computes a diff snapshot, and triggers
-     * a configuration reload if the file content has changed.
+     * Performs checksum validation and triggers a reload if the file content has changed.
      *
-     * <p>The reload operation is executed on the main server thread and followed
-     * by dispatching a {@link ConfigReloadedEvent} containing diff metadata.</p>
+     * <p>This method includes safeguards against transient file system states,
+     * such as temporary deletion or recreation of the file during write operations.</p>
+     *
+     * @apiNote
+     * If the file does not exist at the time of invocation, the reload is skipped
+     * to prevent unnecessary errors and log spam.
+     *
+     * @implSpec
+     * Reload is only performed if:
+     * <ul>
+     *     <li>The file exists</li>
+     *     <li>The computed checksum differs from the previous value</li>
+     * </ul>
+     *
+     * @implNote
+     * Some editors replace files atomically (delete + recreate). This guard prevents
+     * false-positive reload attempts during such operations.
+     *
+     * @since 1.0.1
      */
     private void reload() {
 
         File file = yamlConfig.file();
 
+        // 🔥 NEW: existence guard
+        if (!file.exists()) {
+            plugin.getLogger().fine(() ->
+                    "[ConfigWatcher] File missing, skipping reload: " + file.getName()
+            );
+            return;
+        }
+
         String newChecksum = FileChecksum.sha256(file);
+
         if (newChecksum.equals(lastChecksum)) return;
 
         String oldChecksum = lastChecksum;
@@ -276,6 +301,7 @@ private void reload() {
         lastChecksum = newChecksum;
         lastContent = newContent;
 
+        // snapshot values for lambda (effectively final)
         final int finalChanged = changed;
         final int finalAdded = added;
         final int finalRemoved = removed;
@@ -302,17 +328,34 @@ private void reload() {
     }
 
     /**
-     * Reads the full content of a file as a string.
+     * Reads the full content of the specified file as a string.
+     *
+     * <p>If an error occurs during reading, an empty string is returned and
+     * a warning is logged to the plugin logger.</p>
+     *
+     * @param file the file to read, must not be {@code null}
+     * @return file content as a string, or an empty string if reading fails
      *
-     * <p>If the file cannot be read, an empty string is returned.</p>
+     * @apiNote
+     * This method is intentionally fail-safe and does not propagate exceptions,
+     * as it is used within a file-watching context where stability is preferred.
      *
-     * @param file the file to read
-     * @return file content, or empty string if reading fails
+     * @implSpec
+     * File content is read using {@link Files#readString(Path)}.
+     *
+     * @implNote
+     * Returning an empty string ensures that diff computation can proceed
+     * without interruption, even if file access temporarily fails.
+     *
+     * @since 1.0.1
      */
-    private @NotNull String readContentSafe(File file) {
+    private @NotNull String readContentSafe(@NotNull File file) {
         try {
             return Files.readString(file.toPath());
         } catch (Exception e) {
+            plugin.getLogger().warning(
+                    "[ConfigWatcher] Failed to read config file: " + file.getAbsolutePath()
+            );
             return "";
         }
     }