refactor: enhance category and channel positioning logic for template application

- Improved the logic for updating category and channel positions to ensure they align with their intended order in the YAML configuration.
- Implemented smart positioning checks to prevent unnecessary updates, enhancing performance and reducing potential errors.
- Updated related comments for clarity and consistency in the codebase.

Author: evolvewithevan

src/gitcord/cogs/admin.py

@@ -252,6 +252,8 @@ async def git_command(self, ctx: commands.Context, *args):
                     await ctx.send(embed=warning_embed)
 
                 try:
+                    # Always apply template to ensure Discord matches the template
+                    # (Even if git says "up to date", Discord might not match the template)
                     result_msgs = await self._apply_template_from_dir(ctx.guild, meta["local_path"], ctx=ctx)
 
                     # Convert to git-style diff
@@ -534,8 +536,11 @@ async def _apply_template_from_dir(
                 category = existing_category
                 msg = f"ℹ️ Category '{category_name}' already exists. Will update channels."
 
-                # Update category position based on order
-                if category.position != category_index:
+                # Check if category is in correct relative order (smart positioning)
+                guild_categories = sorted(guild.categories, key=lambda cat: cat.position)
+                current_relative_index = guild_categories.index(category)
+                
+                if current_relative_index != category_index:
                     try:
                         await category.edit(position=category_index)
                         msg += f" Moved to position {category_index}."
@@ -592,9 +597,15 @@ async def _apply_template_from_dir(
                     ):
                         update_kwargs["nsfw"] = channel_config.get("nsfw", False)
 
-                    # Update position based on channel order in YAML
-                    if hasattr(existing_channel, "position") and existing_channel.position != channel_index:
-                        update_kwargs["position"] = channel_index
+                    # Check if channel is in correct relative order (smart positioning)
+                    if hasattr(existing_channel, "position"):
+                        # Get all channels in category sorted by position
+                        category_channels = sorted(category.channels, key=lambda ch: ch.position)
+                        current_relative_index = category_channels.index(existing_channel)
+                        
+                        # Only move if the channel is not at the correct relative position
+                        if current_relative_index != channel_index:
+                            update_kwargs["position"] = channel_index
 
                     if update_kwargs:
                         await existing_channel.edit(**update_kwargs)
@@ -732,12 +743,15 @@ async def _apply_monolithic_template(self, guild, template_path, ctx=None, inter
                 category = existing_category
                 msg = f"ℹ️ Category '{category_name}' already exists. Will update channels."
 
-                # Update category position based on YAML order
-                desired_position = category_index
-                if category.position != desired_position:
+                # Check if category is in correct relative order
+                desired_yaml_index = category_index
+                guild_categories = sorted(guild.categories, key=lambda cat: cat.position)
+                current_relative_index = guild_categories.index(category)
+                
+                if current_relative_index != desired_yaml_index:
                     try:
-                        await category.edit(position=desired_position)
-                        msg += f" Moved to position {desired_position}."
+                        await category.edit(position=desired_yaml_index)
+                        msg += f" Moved to position {desired_yaml_index}."
                     except (discord.Forbidden, discord.HTTPException) as e:
                         self.logger.warning(f"Failed to update category position: {e}")
             else:
@@ -779,15 +793,21 @@ async def _apply_monolithic_template(self, guild, template_path, ctx=None, inter
                     ):
                         update_kwargs["nsfw"] = channel_config.get("nsfw", False)
 
-                    # Update position based on YAML order
-                    desired_position = channel_index
-                    if hasattr(existing_channel, "position") and existing_channel.position != desired_position:
-                        update_kwargs["position"] = desired_position
+                    # Check if channel is in correct relative order (smart positioning)
+                    desired_yaml_index = channel_index
+                    if hasattr(existing_channel, "position"):
+                        # Get all channels in category sorted by position
+                        category_channels = sorted(category.channels, key=lambda ch: ch.position)
+                        current_relative_index = category_channels.index(existing_channel)
+                        
+                        # Only move if the channel is not at the correct relative position
+                        if current_relative_index != desired_yaml_index:
+                            update_kwargs["position"] = desired_yaml_index
 
                     if update_kwargs:
                         await existing_channel.edit(**update_kwargs)
                         updated += 1
-                        position_msg = f" (position {desired_position})" if "position" in update_kwargs else ""
+                        position_msg = f" (position {desired_yaml_index})" if "position" in update_kwargs else ""
                         msg = f"🔄 Updated channel: {existing_channel.name} in {category_name}{position_msg}"
                     else:
                         skipped += 1

src/gitcord/utils/category_helpers.py

@@ -47,22 +47,25 @@ async def process_existing_category(
         existing_category, yaml_channel_names, category_config["name"]
     )
 
-    # Update category position if needed
+    # Update category position if needed (smart positioning)
     category_updated = False
-    if (
-        category_position is not None
-        and existing_category.position != category_position
-    ):
-        try:
-            await existing_category.edit(position=category_position)
-            logger.info(
-                "Updated category '%s' position to %d",
-                category_config["name"],
-                category_position,
-            )
-            category_updated = True
-        except (discord.Forbidden, discord.HTTPException) as e:
-            logger.warning("Failed to update category position: %s", e)
+    if category_position is not None:
+        # Get all categories in guild sorted by position
+        guild_categories = sorted(guild.categories, key=lambda cat: cat.position)
+        current_relative_index = guild_categories.index(existing_category)
+        
+        # Only move if the category is not at the correct relative position
+        if current_relative_index != category_position:
+            try:
+                await existing_category.edit(position=category_position)
+                logger.info(
+                    "Updated category '%s' position to %d",
+                    category_config["name"],
+                    category_position,
+                )
+                category_updated = True
+            except (discord.Forbidden, discord.HTTPException) as e:
+                logger.warning("Failed to update category position: %s", e)
 
     # Process channels in the category
     created_channels, updated_channels, skipped_channels = (
@@ -188,14 +191,19 @@ async def _update_existing_channel(
         update_kwargs["nsfw"] = channel_config.get("nsfw", False)
         channel_updated = True
 
-    # Check if position needs updating based on YAML order
+    # Check if position needs updating based on YAML order (smart positioning)
     if (
         channel_position is not None
         and hasattr(existing_channel, "position")
-        and existing_channel.position != channel_position
     ):
-        update_kwargs["position"] = channel_position
-        channel_updated = True
+        # Get all channels in category sorted by position  
+        category_channels = sorted(existing_channel.category.channels, key=lambda ch: ch.position)
+        current_relative_index = category_channels.index(existing_channel)
+        
+        # Only move if the channel is not at the correct relative position
+        if current_relative_index != channel_position:
+            update_kwargs["position"] = channel_position
+            channel_updated = True
 
     if channel_updated:
         try: