23596933282

Committed 26 Mar 2026 01:29PM UTC coverage: 90.671% (+0.03%) from 90.643%

Build # 23596933282

Build Type

push

github

Committed by

web-flow

Commit Message

refactor: reduce cognitive complexity - bot batch 2 (#393)

* refactor: reduce cognitive complexity in ai, guilds, timeParser, grantRole

* style: fix Biome lint formatting

Coverage Stats

6549 of 7658 branches covered (85.52%)

Branch coverage included in aggregate %.

84 of 86 new or added lines in 4 files covered. (97.67%)

36 existing lines in 7 files now uncovered.

11150 of 11862 relevant lines covered (94.0%)

224.28 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

87.6

/src/modules/moderation.js

/**
 * Moderation Module
 * Shared logic for case management, DM notifications, mod log posting,
 * auto-escalation, and tempban scheduling.
 */

import { EmbedBuilder } from 'discord.js';
import { getPool } from '../db.js';
import { info, error as logError, warn as logWarn } from '../logger.js';
import { fetchChannelCached } from '../utils/discordCache.js';
import { parseDuration } from '../utils/duration.js';
import { mergeRoleIds } from '../utils/permissions.js';
import { safeSend } from '../utils/safeSend.js';
import { getConfig } from './config.js';
import { fireEvent } from './webhookNotifier.js';

/**
 * Color map for mod log embeds by action type.
 * @type {Record<string, number>}
 */
export const ACTION_COLORS = {
  warn: 0xfee75c,
  kick: 0xed4245,
  timeout: 0xe67e22,
  untimeout: 0x57f287,
  ban: 0xed4245,
  tempban: 0xed4245,
  unban: 0x57f287,
  softban: 0xed4245,
  purge: 0x5865f2,
  lock: 0xe67e22,
  unlock: 0x57f287,
  slowmode: 0x5865f2,
};

/**
 * Past-tense label for DM notifications by action type.
 * @type {Record<string, string>}
 */
const ACTION_PAST_TENSE = {
  warn: 'warned',
  kick: 'kicked',
  timeout: 'timed out',
  untimeout: 'had their timeout removed',
  ban: 'banned',
  tempban: 'temporarily banned',
  unban: 'unbanned',
  softban: 'soft-banned',
};

/**
 * Channel config key for each action type (maps to moderation.logging.channels.*).
 * @type {Record<string, string>}
 */
export const ACTION_LOG_CHANNEL_KEY = {
  warn: 'warns',
  kick: 'kicks',
  timeout: 'timeouts',
  untimeout: 'timeouts',
  ban: 'bans',
  tempban: 'bans',
  unban: 'bans',
  softban: 'bans',
  purge: 'purges',
  lock: 'locks',
  unlock: 'locks',
  slowmode: 'locks',
};

/** @type {ReturnType<typeof setInterval> | null} */
let schedulerInterval = null;

/** @type {boolean} */
let schedulerPollInFlight = false;

/**
 * Create a moderation case in the database.
 * Uses a per-guild advisory lock to atomically assign sequential case numbers.
 * @param {string} guildId - Discord guild ID
 * @param {Object} data - Case data
 * @param {string} data.action - Action type (warn, kick, ban, etc.)
 * @param {string} data.targetId - Target user ID
 * @param {string} data.targetTag - Target user tag
 * @param {string} data.moderatorId - Moderator user ID
 * @param {string} data.moderatorTag - Moderator user tag
 * @param {string} [data.reason] - Reason for action
 * @param {string} [data.duration] - Duration string (for timeout/tempban)
 * @param {Date} [data.expiresAt] - Expiration timestamp
 * @returns {Promise<Object>} Created case row
 */
export async function createCase(guildId, data) {
  const pool = getPool();
  const client = await pool.connect();

  try {
    await client.query('BEGIN');

    // Serialize case-number generation per guild to prevent race conditions.
    await client.query('SELECT pg_advisory_xact_lock(hashtext($1))', [guildId]);

    const { rows } = await client.query(
      `INSERT INTO mod_cases
        (
          guild_id,
          case_number,
          action,
          target_id,
          target_tag,
          moderator_id,
          moderator_tag,
          reason,
          duration,
          expires_at
        )
      VALUES (
        $1,
        COALESCE((SELECT MAX(case_number) FROM mod_cases WHERE guild_id = $1), 0) + 1,
        $2,
        $3,
        $4,
        $5,
        $6,
        $7,
        $8,
        $9
      )
      RETURNING *`,
      [
        guildId,
        data.action,
        data.targetId,
        data.targetTag,
        data.moderatorId,
        data.moderatorTag,
        data.reason || null,
        data.duration || null,
        data.expiresAt || null,
      ],
    );

    await client.query('COMMIT');

    const createdCase = rows[0];
    info('Moderation case created', {
      guildId,
      caseNumber: createdCase.case_number,
      action: data.action,
      target: data.targetTag,
      moderator: data.moderatorTag,
    });

    // Fire webhook notification — fire-and-forget, don't block case creation
    fireEvent('moderation.action', guildId, {
      action: data.action,
      caseNumber: createdCase.case_number,
      targetId: data.targetId,
      targetTag: data.targetTag,
      moderatorId: data.moderatorId,
      moderatorTag: data.moderatorTag,
      reason: data.reason || null,
    }).catch(() => {});

    return createdCase;
  } catch (err) {
    await client.query('ROLLBACK').catch(() => {});
    throw err;
  } finally {
    client.release();
  }
}

/**
 * Schedule a moderation action for future execution.
 * @param {string} guildId - Discord guild ID
 * @param {string} action - Action type (e.g. unban)
 * @param {string} targetId - Target user ID
 * @param {number|null} caseId - Related case ID (if any)
 * @param {Date} executeAt - When to execute the action
 * @returns {Promise<Object>} Created scheduled action row
 */
export async function scheduleAction(guildId, action, targetId, caseId, executeAt) {
  const pool = getPool();
  const { rows } = await pool.query(
    `INSERT INTO mod_scheduled_actions
      (guild_id, action, target_id, case_id, execute_at)
    VALUES ($1, $2, $3, $4, $5)
    RETURNING *`,
    [guildId, action, targetId, caseId || null, executeAt],
  );

  return rows[0];
}

/**
 * Send a DM notification to a member before a moderation action.
 * Silently fails if the user has DMs disabled.
 * @param {import('discord.js').GuildMember} member - Target member
 * @param {string} action - Action type
 * @param {string|null} reason - Reason for the action
 * @param {string} guildName - Server name
 */
export async function sendDmNotification(member, action, reason, guildName) {
  const pastTense = ACTION_PAST_TENSE[action] || action;
  const embed = new EmbedBuilder()
    .setColor(ACTION_COLORS[action] || 0x5865f2)
    .setTitle(`You have been ${pastTense} in ${guildName}`)
    .addFields({ name: 'Reason', value: reason || 'No reason provided' })
    .setTimestamp();

  try {
    await member.send({ embeds: [embed] });
  } catch {
    // User has DMs disabled — silently continue
  }
}

/**
 * Post a moderation log embed for a case to the configured logging channel.
 *
 * Attempts to send an embed describing the case to the channel determined by
 * the moderation logging configuration. On successful send it records the
 * sent message's ID on the case row (logging any storage failures) and returns
 * the sent message; if sending or channel resolution fails, returns `null`.
 *
 * @param {import('discord.js').Client} client - Discord client instance used to resolve channels.
 * @param {Object} config - Bot configuration object containing moderation.logging.channels.
 * @param {Object} caseData - Case object returned by createCase(), including at least `id`, `case_number`, `action`, `target_id`, `target_tag`, `moderator_id`, `moderator_tag`, and optional `reason`, `duration`, `created_at`.
 * @returns {import('discord.js').Message|null} The sent log message if delivered, `null` if no message was sent.
 */
export async function sendModLogEmbed(client, config, caseData) {
  const channels = config.moderation?.logging?.channels;
  if (!channels) return null;

  const actionKey = ACTION_LOG_CHANNEL_KEY[caseData.action];
  const channelId = channels[actionKey] || channels.default;
  if (!channelId) return null;

  const channel = await fetchChannelCached(client, channelId, caseData.guild_id);
  if (!channel) return null;

  const embed = new EmbedBuilder()
    .setColor(ACTION_COLORS[caseData.action] || 0x5865f2)
    .setTitle(`Case #${caseData.case_number} — ${caseData.action.toUpperCase()}`)
    .addFields(
      { name: 'Target', value: `<@${caseData.target_id}> (${caseData.target_tag})`, inline: true },
      {
        name: 'Moderator',
        value: `<@${caseData.moderator_id}> (${caseData.moderator_tag})`,
        inline: true,
      },
      { name: 'Reason', value: caseData.reason || 'No reason provided' },
    )
    .setTimestamp(caseData.created_at ? new Date(caseData.created_at) : new Date())
    .setFooter({ text: `Case #${caseData.case_number}` });

  if (caseData.duration) {
    embed.addFields({ name: 'Duration', value: caseData.duration, inline: true });
  }

  try {
    const sentMessage = await safeSend(channel, { embeds: [embed] });

    // Store log message ID for future editing
    try {
      const pool = getPool();
      await pool.query('UPDATE mod_cases SET log_message_id = $1 WHERE id = $2', [
        sentMessage.id,
        caseData.id,
      ]);
    } catch (err) {
      logError('Failed to store log message ID', {
        caseId: caseData.id,
        messageId: sentMessage.id,
        error: err.message,
      });
    }

    return sentMessage;
  } catch (err) {
    logWarn('Failed to send mod log embed', { error: err.message, channelId });
    return null;
  }
}

/**
 * Evaluate configured escalation thresholds for a guild target and apply the first matching escalation.
 *
 * If a threshold is met, performs the configured action (e.g., timeout or ban), creates a moderation case, and posts the mod-log for the escalation.
 *
 * @param {import('discord.js').Client} client - Discord client instance.
 * @param {string} guildId - ID of the guild where escalation is evaluated.
 * @param {string} targetId - ID of the target user being evaluated.
 * @param {string} moderatorId - ID used as the moderator for the escalation case (typically the bot).
 * @param {string} moderatorTag - Tag to record for the moderator in the created case.
 * @param {Object} config - Bot configuration containing moderation.escalation settings and thresholds.
 * @returns {Object|null} The created escalation case object when an escalation is applied, `null` if no thresholds triggered or on failure.
 */
/**
 * Count active warnings for a user within a threshold window.
 * Falls back to mod_cases if the warnings table doesn't exist yet.
 */
async function countActiveWarnings(pool, guildId, targetId, withinDays) {
  try {
    const { rows } = await pool.query(
      `SELECT COUNT(*)::integer AS count FROM warnings
       WHERE guild_id = $1 AND user_id = $2 AND active = TRUE
       AND (expires_at IS NULL OR expires_at > NOW())
       AND created_at > NOW() - INTERVAL '1 day' * $3`,
      [guildId, targetId, withinDays],
    );
    return rows[0]?.count || 0;
  } catch (err) {
    if (err.code === '42P01') {
      // 42P01 = undefined_table — fall back to mod_cases
      const { rows } = await pool.query(
        `SELECT COUNT(*)::integer AS count FROM mod_cases
         WHERE guild_id = $1 AND target_id = $2 AND action = 'warn'
         AND created_at > NOW() - INTERVAL '1 day' * $3`,
        [guildId, targetId, withinDays],
      );
      return rows[0]?.count || 0;
    }
    logError('Failed to count active warnings for escalation', {
      error: err.message,
      guildId,
      targetId,
    });
    throw err;
  }
}

/**
 * Execute a single escalation action (timeout or ban) and create the mod case.
 */
async function executeEscalationAction(
  client,
  config,
  guildId,
  targetId,
  moderatorId,
  moderatorTag,
  threshold,
  reason,
) {
  const guild = await client.guilds.fetch(guildId);
  const member = await guild.members.fetch(targetId).catch(() => null);

  if (threshold.action === 'timeout' && member) {
    const ms = parseDuration(threshold.duration);
    if (ms) {
      await member.timeout(ms, reason);
    }
  } else if (threshold.action === 'ban') {
    await guild.members.ban(targetId, { reason });
  }

  const escalationCase = await createCase(guildId, {
    action: threshold.action,
    targetId,
    targetTag: member?.user?.tag || targetId,
    moderatorId,
    moderatorTag,
    reason,
    duration: threshold.duration || null,
  });

  await sendModLogEmbed(client, config, escalationCase);
  return escalationCase;
}

export async function checkEscalation(
  client,
  guildId,
  targetId,
  moderatorId,
  moderatorTag,
  config,
) {
  if (!config.moderation?.escalation?.enabled) return null;

  const thresholds = config.moderation.escalation.thresholds;
  if (!thresholds?.length) return null;

  const pool = getPool();

  for (const threshold of thresholds) {
    const warnCount = await countActiveWarnings(pool, guildId, targetId, threshold.withinDays);
    if (warnCount < threshold.warns) continue;

    const reason = `Auto-escalation: ${warnCount} active warns in ${threshold.withinDays} days`;
    info('Escalation triggered', { guildId, targetId, warnCount, threshold });

    try {
      return await executeEscalationAction(
        client,
        config,
        guildId,
        targetId,
        moderatorId,
        moderatorTag,
        threshold,
        reason,
      );
    } catch (err) {
      logError('Escalation action failed', { error: err.message, guildId, targetId, threshold });
      return null;
    }
  }

  return null;
}

/**
 * Poll for expired tempbans and execute unbans.
 * @param {import('discord.js').Client} client - Discord client
 */
async function pollTempbans(client) {
  if (schedulerPollInFlight) {
    return;
  }

  schedulerPollInFlight = true;

  try {
    const pool = getPool();
    const { rows } = await pool.query(
      `SELECT * FROM mod_scheduled_actions
       WHERE executed = FALSE AND execute_at <= NOW()
       ORDER BY execute_at ASC
       LIMIT 50`,
    );

    for (const row of rows) {
      // Use a transaction to ensure atomicity:
      // 1. Lock the row with FOR UPDATE SKIP LOCKED
      // 2. Execute Discord unban
      // 3. Only mark executed after successful unban
      const txClient = await pool.connect();
      try {
        await txClient.query('BEGIN');

        // Lock the row - skip if already executed by another poll
        const { rows: lockRows } = await txClient.query(
          'SELECT id FROM mod_scheduled_actions WHERE id = $1 AND executed = FALSE FOR UPDATE SKIP LOCKED',
          [row.id],
        );
        if (lockRows.length === 0) {
          await txClient.query('ROLLBACK');
          continue; // Already handled by another poll
        }

        // Execute the Discord unban FIRST (before marking executed)
        // Track any error for logging, but don't throw - we still mark as executed
        // to prevent infinite retry on non-recoverable errors
        let unbanError = null;
        const guild = await client.guilds.fetch(row.guild_id);
        try {
          await guild.members.unban(row.target_id, 'Tempban expired');
        } catch (err) {
          unbanError = err;
          // Unknown Ban (code 10026) means already unbanned - not really an error
          const isAlreadyUnbanned = err?.code === 10026 || /Unknown Ban/i.test(err?.message || '');
          if (isAlreadyUnbanned) {
            info('Tempban target already unbanned; finalizing scheduled action', {
              id: row.id,
              guildId: row.guild_id,
              targetId: row.target_id,
            });
            unbanError = null; // Clear error - this is success
          }
        }

        // Mark executed regardless of unban outcome to prevent infinite retry
        await txClient.query('UPDATE mod_scheduled_actions SET executed = TRUE WHERE id = $1', [
          row.id,
        ]);
        await txClient.query('COMMIT');

        // Log unban failure AFTER successful commit (if there was a real error)
        if (unbanError) {
          logError('Failed to unban tempban target (marked as executed to prevent retry)', {
            error: unbanError.message,
            id: row.id,
            guildId: row.guild_id,
            targetId: row.target_id,
          });
        }
      } catch (err) {
        // Only reach here on transaction/DB errors (not unban errors)
        await txClient.query('ROLLBACK').catch(() => {});
        logError('Failed to process expired tempban', {
          error: err.message,
          id: row.id,
          guildId: row.guild_id,
          targetId: row.target_id,
        });
        // Action remains unexecuted (executed = FALSE) and will be retried on next poll
        txClient.release();
        continue; // Skip post-commit work since transaction failed
      }

      // Transaction succeeded - release client before post-commit work
      txClient.release();

      // Post-commit work (outside transaction): create case, send mod-log
      // These are non-critical - failures here don't affect the unban itself
      try {
        const targetUser = await client.users.fetch(row.target_id).catch(() => null);

        // Create unban case
        const config = getConfig(row.guild_id);
        const unbanCase = await createCase(row.guild_id, {
          action: 'unban',
          targetId: row.target_id,
          targetTag: targetUser?.tag || row.target_id,
          moderatorId: client.user?.id || 'system',
          moderatorTag: client.user?.tag || 'System',
          reason: `Tempban expired (case #${row.case_id ? row.case_id : 'unknown'})`,
        });

        await sendModLogEmbed(client, config, unbanCase);

        info('Tempban expired, user unbanned', {
          guildId: row.guild_id,
          targetId: row.target_id,
        });
      } catch (err) {
        // Log but don't retry - the unban itself succeeded, just the logging failed
        logError('Post-commit work failed for tempban (unban already executed)', {
          error: err.message,
          id: row.id,
          guildId: row.guild_id,
          targetId: row.target_id,
        });
      }
    }
  } catch (err) {
    logError('Tempban scheduler poll error', { error: err.message });
  } finally {
    schedulerPollInFlight = false;
  }
}

/**
 * Start the tempban scheduler polling interval.
 * Polls every 60 seconds for expired tempbans.
 * Runs an immediate check on startup to catch missed unbans.
 * @param {import('discord.js').Client} client - Discord client
 */
export function startTempbanScheduler(client) {
  if (schedulerInterval) return;

  // Immediate check on startup
  pollTempbans(client).catch((err) => {
    logError('Initial tempban poll failed', { error: err.message });
  });

  schedulerInterval = setInterval(() => {
    pollTempbans(client).catch((err) => {
      logError('Tempban poll failed', { error: err.message });
    });
  }, 60000);

  info('Tempban scheduler started');
}

/**
 * Stop the tempban scheduler.
 */
export function stopTempbanScheduler() {
  if (schedulerInterval) {
    clearInterval(schedulerInterval);
    schedulerInterval = null;
    info('Tempban scheduler stopped');
  }
}

/**
 * Determine whether a guild member is protected from moderation actions.
 * Protection is driven by the guild's live moderation.protectRoles settings (server owner, admin/moderator roles, and explicit role IDs).
 * @param {import('discord.js').GuildMember} target - Member to evaluate.
 * @param {import('discord.js').Guild} guild - Guild containing the member.
 * @returns {boolean} `true` if the member is protected from moderation actions, `false` otherwise.
 */
export function isProtectedTarget(target, guild) {
  // Fetch config per-invocation so live config edits take effect immediately.
  const config = getConfig(guild.id);
  /**
   * When the protectRoles block is missing from persisted configuration,
   * fall back to the intended defaults: protection enabled, include owner,
   * admins, and moderators (matches config.json defaults and web UI defaults).
   */
  const defaultProtectRoles = {
    enabled: true,
    includeAdmins: true,
    includeModerators: true,
    includeServerOwner: true,
    roleIds: [],
  };

  // Deep-merge defaults so a partial persisted object (e.g. only roleIds set)
  // never leaves enabled/include* as undefined/falsy.
  const protectRoles = { ...defaultProtectRoles, ...config.moderation?.protectRoles };
  if (!protectRoles.enabled) {
    return false;
  }

  // Server owner is always protected when enabled
  if (protectRoles.includeServerOwner && target.id === guild.ownerId) {
    return true;
  }

  // Resolve admin/moderator role ID arrays — mergeRoleIds handles the case where
  // defaults inject adminRoleIds:[] alongside a legacy adminRoleId guild override
  const adminRoleIds = mergeRoleIds(
    config.permissions?.adminRoleIds,
    config.permissions?.adminRoleId,
  );
  const moderatorRoleIds = mergeRoleIds(
    config.permissions?.moderatorRoleIds,
    config.permissions?.moderatorRoleId,
  );

  const protectedRoleIds = [
    ...(protectRoles.includeAdmins ? adminRoleIds : []),
    ...(protectRoles.includeModerators ? moderatorRoleIds : []),
    ...(Array.isArray(protectRoles.roleIds) ? protectRoles.roleIds : []),
  ].filter(Boolean);

  if (protectedRoleIds.length === 0) return false;

  const memberRoleIds = [...target.roles.cache.keys()];
  return protectedRoleIds.some((roleId) => memberRoleIds.includes(roleId));
}

/**
 * Check if the moderator (and optionally the bot) can moderate a target member.
 * @param {import('discord.js').GuildMember} moderator - The moderator
 * @param {import('discord.js').GuildMember} target - The target member
 * @param {import('discord.js').GuildMember|null} [botMember=null] - The bot's own guild member
 * @returns {string|null} Error message if cannot moderate, null if OK
 */
export function checkHierarchy(moderator, target, botMember = null) {
  if (target.roles.highest.position >= moderator.roles.highest.position) {
    return '❌ You cannot moderate a member with an equal or higher role than yours.';
  }
  if (botMember && target.roles.highest.position >= botMember.roles.highest.position) {
    return '❌ I cannot moderate this member — my role is not high enough.';
  }
  return null;
}

/**
 * Check if DM notification is enabled for an action type.
 * @param {Object} config - Bot configuration
 * @param {string} action - Action type
 * @returns {boolean} True if DM should be sent
 */
export function shouldSendDm(config, action) {
  return config.moderation?.dmNotifications?.[action] === true;
}

VolvoxLLC / volvox-bot / 23596933282

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous