📝 Add docstrings to refactor/triage-prompt-rewrite

coderabbitai[bot] · web-flow · commit 010e460b8053 · 2026-03-05T19:47:06.000Z
Docstrings generation was requested by @BillChirico. The following files were modified: * `src/modules/triage-prompt.js` * `src/modules/triage-respond.js` * `web/src/components/dashboard/config-editor.tsx` * `web/src/components/dashboard/config-sections/ChallengesSection.tsx` * `web/src/components/dashboard/config-sections/CommunityFeaturesSection.tsx` * `web/src/components/dashboard/config-sections/GitHubSection.tsx` * `web/src/components/dashboard/config-sections/MemorySection.tsx` * `web/src/components/dashboard/config-sections/PermissionsSection.tsx` * `web/src/components/dashboard/config-sections/StarboardSection.tsx` * `web/src/components/dashboard/config-sections/TicketsSection.tsx` * `web/src/components/dashboard/config-sections/TriageSection.tsx` * `web/src/components/dashboard/config-sections/WelcomeSection.tsx` * `web/src/lib/config-normalization.ts` * `web/src/lib/config-updates.ts` These files were kept as they were: * `src/modules/triage.js` * `web/src/components/dashboard/config-sections/AiAutoModSection.tsx` * `web/src/components/dashboard/config-sections/AiSection.tsx` * `web/src/components/dashboard/config-sections/EngagementSection.tsx` * `web/src/components/dashboard/config-sections/ModerationSection.tsx` * `web/src/components/dashboard/config-sections/ReputationSection.tsx` These files were ignored: * `tests/modules/triage-prompt.test.js` * `tests/modules/triage.test.js` * `web/tests/components/dashboard/config-editor-autosave.test.tsx` * `web/tests/lib/config-normalization.test.ts` * `web/tests/lib/config-updates.test.ts` These file types are not supported: * `.github/workflows/maintain-docs.md` * `src/prompts/community-rules.md` * `src/prompts/search-guardrails.md` * `src/prompts/triage-classify-system.md` * `src/prompts/triage-classify.md` * `src/prompts/triage-respond-system.md` * `src/prompts/triage-respond.md`
diff --git a/src/modules/triage-prompt.js b/src/modules/triage-prompt.js
@@ -27,16 +27,13 @@ export function escapePromptDelimiters(text) {
 // ── Conversation text formatting ─────────────────────────────────────────────
 
 /**
- * Build conversation text with message IDs for prompts.
- * Splits output into <recent-history> (context) and <messages-to-evaluate> (buffer).
- * Includes timestamps and reply context when available.
+ * Build a structured conversation text for prompts including optional channel metadata.
  *
- * User-supplied content (message body and reply excerpts) is passed through
- * {@link escapePromptDelimiters} to neutralise prompt-injection attempts.
+ * Produces sections: an optional <channel-context> (Channel and optional Topic) taken from the first entry that contains channel metadata, a <recent-history> block for `context` messages (when present), and a <messages-to-evaluate> block for `buffer` messages. Each message line contains an optional timestamp, messageId, author, user mention, optional reply excerpt, and the message content. User-supplied content is escaped to neutralize XML-style delimiters and reduce prompt-injection risk.
  *
- * @param {Array} context - Historical messages fetched from Discord API
- * @param {Array} buffer - Buffered messages to evaluate
- * @returns {string} Formatted conversation text with section markers
+ * @param {Array} context - Historical messages to include in <recent-history>.
+ * @param {Array} buffer - Messages to include in <messages-to-evaluate>.
+ * @returns {string} The formatted conversation text containing the assembled sections.
  */
 export function buildConversationText(context, buffer) {
   const formatMsg = (m) => {
@@ -93,14 +90,16 @@ export function buildClassifyPrompt(context, snapshot, botUserId) {
 }
 
 /**
- * Build the responder prompt from the template.
- * @param {Array} context - Historical context messages
- * @param {Array} snapshot - Buffer snapshot (messages to evaluate)
- * @param {Object} classification - Parsed classifier output
- * @param {Object} config - Bot configuration
- * @param {string} [memoryContext] - Memory context for target users
- * @returns {string} Interpolated respond prompt
- */
+ * Construct the responder prompt by combining conversation text, community rules, the system prompt, classification results, optional memory context, and search guardrails.
+ * @param {Array} context - Historical context messages used to build conversation text.
+ * @param {Array} snapshot - Buffer snapshot containing messages to evaluate.
+ * @param {Object} classification - Classifier output containing decision details.
+ * @param {string} classification.classification - The classification label.
+ * @param {string} classification.reasoning - Explanatory reasoning for the classification.
+ * @param {Array<string>} classification.targetMessageIds - IDs of messages targeted by the classification.
+ * @param {Object} config - Bot configuration; `config.ai.systemPrompt` (if present) overrides the default system prompt.
+ * @param {string} [memoryContext] - Optional serialized memory context to include for target users.
+ * @returns {string} The fully interpolated responder prompt ready for the model. */
 export function buildRespondPrompt(context, snapshot, classification, config, memoryContext) {
   const conversationText = buildConversationText(context, snapshot);
   const communityRules = loadPrompt('community-rules');
diff --git a/src/modules/triage-respond.js b/src/modules/triage-respond.js
@@ -42,15 +42,19 @@ function logAssistantHistory(channelId, guildId, fallbackContent, sentMsg) {
 // ── Channel context fetching ─────────────────────────────────────────────────
 
 /**
- * Fetch recent messages from Discord's API to provide conversation context
- * beyond the buffer window. Called at evaluation time (not accumulation) to
- * minimize API calls.
+ * Retrieve recent channel messages to provide additional conversation context.
  *
- * @param {string} channelId - The channel to fetch history from
- * @param {import('discord.js').Client} client - Discord client
- * @param {Array} bufferSnapshot - Current buffer snapshot (to fetch messages before)
- * @param {number} [limit=15] - Maximum messages to fetch
- * @returns {Promise<Array>} Context messages in chronological order
+ * Returns an array of context message objects in chronological order. Each object contains:
+ * - `author`: display name (appended with " [BOT]" for bot accounts),
+ * - `content`: sanitized message text truncated to the context character limit,
+ * - `userId`, `messageId`, `timestamp`,
+ * - `isContext`: true,
+ * - `channelName`, `channelTopic`.
+ *
+ * @param {string} channelId - ID of the channel to fetch history from.
+ * @param {Array} bufferSnapshot - Current buffer snapshot; messages are fetched before the oldest entry if present.
+ * @param {number} [limit=15] - Maximum number of messages to fetch.
+ * @returns {Array<Object>} Context message objects in chronological order.
  */
 export async function fetchChannelContext(channelId, client, bufferSnapshot, limit = 15) {
   try {
diff --git a/web/src/components/dashboard/config-editor.tsx b/web/src/components/dashboard/config-editor.tsx
@@ -30,7 +30,11 @@ import {
 import { DiscardChangesButton } from './reset-defaults-button';
 
 /**
- * Generate a UUID with fallback for environments without crypto.randomUUID.
+ * Generate a UUID string.
+ *
+ * Produces a v4-style UUID; in environments with native support this will use the platform API.
+ *
+ * @returns A v4 UUID string.
  */
 function generateId(): string {
   if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
@@ -44,7 +48,12 @@ function generateId(): string {
 }
 
 /**
- * Type guard that checks whether a value is a guild configuration object returned by the API.
+ * Determines whether a value matches the expected GuildConfig shape returned by the API.
+ *
+ * Checks that `data` is a plain object that contains at least one known top-level config section
+ * and that any present known sections are objects (not `null`, not primitives, and not arrays).
+ *
+ * @returns `true` if `data` appears to be a GuildConfig, `false` otherwise.
  */
 function isGuildConfig(data: unknown): data is GuildConfig {
   if (typeof data !== 'object' || data === null || Array.isArray(data)) return false;
@@ -320,6 +329,13 @@ export function ConfigEditor() {
 
     const failedSections: string[] = [];
 
+    /**
+     * Applies a sequence of JSON Patch-like updates to the current guild's configuration via PATCH requests.
+     *
+     * @param sectionPatches - An ordered array of patch objects, each with a `path` (JSON pointer-like string) and `value` to send as the request body for a single PATCH operation.
+     *
+     * @throws Error - If the server responds with 401 (causes an abort and redirects to /login) or if any PATCH request returns a non-OK response; the error message contains the server-provided `error` field when available or the HTTP status.
+     */
     async function sendSection(sectionPatches: Array<{ path: string; value: unknown }>) {
       for (const patch of sectionPatches) {
         const res = await fetch(`/api/guilds/${encodeURIComponent(guildId)}/config`, {
diff --git a/web/src/components/dashboard/config-sections/ChallengesSection.tsx b/web/src/components/dashboard/config-sections/ChallengesSection.tsx
@@ -16,9 +16,15 @@ const inputClasses =
   'w-full rounded-md border bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50';
 
 /**
- * Daily Coding Challenges configuration section.
+ * Render the Daily Coding Challenges configuration card.
  *
- * Provides controls for auto-posting daily coding challenges with hint and solve tracking.
+ * Renders controls to enable/disable daily challenges and to edit channel ID, post time, and timezone.
+ *
+ * @param draftConfig - Current guild configuration draft containing `challenges` settings
+ * @param saving - Whether configuration changes are being saved; when true inputs are disabled
+ * @param onEnabledChange - Called with the new enabled state when the toggle is changed
+ * @param onFieldChange - Called with a field name and value when an input changes (channelId is sent as `null` when empty)
+ * @returns A React element containing the challenges configuration UI
  */
 export function ChallengesSection({
   draftConfig,
diff --git a/web/src/components/dashboard/config-sections/CommunityFeaturesSection.tsx b/web/src/components/dashboard/config-sections/CommunityFeaturesSection.tsx
@@ -35,9 +35,14 @@ const COMMUNITY_FEATURES = [
 ] as const;
 
 /**
- * Community Features configuration section.
+ * Render the Community Features configuration card with a toggle for each feature.
  *
- * Provides toggles for enabling/disabling various community commands per guild.
+ * Renders a titled card that lists community feature entries and a switch for enabling or disabling each feature for a guild.
+ *
+ * @param draftConfig - Guild draft configuration used to read each feature's `enabled` state (defaults to `false` when missing)
+ * @param saving - When `true`, all toggles are disabled to prevent user interaction during save
+ * @param onToggleChange - Callback invoked with the feature key and the new enabled state when a toggle changes
+ * @returns The JSX element for the Community Features configuration section
  */
 export function CommunityFeaturesSection({
   draftConfig,
diff --git a/web/src/components/dashboard/config-sections/GitHubSection.tsx b/web/src/components/dashboard/config-sections/GitHubSection.tsx
@@ -16,9 +16,14 @@ const inputClasses =
   'w-full rounded-md border bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50';
 
 /**
- * GitHub Activity Feed configuration section.
+ * Render the GitHub Activity Feed configuration panel inside a Card.
  *
- * Provides controls for GitHub feed channel and polling interval.
+ * Renders controls to enable/disable the feed, set the feed channel ID, and configure the poll interval.
+ *
+ * @param draftConfig - Current guild configuration draft containing optional `github.feed` values.
+ * @param saving - When true, disables all inputs to prevent interaction while saving.
+ * @param onFieldChange - Callback invoked with (`field`, `value`) when a control changes.
+ * @returns The JSX element for the GitHub Activity Feed configuration section.
  */
 export function GitHubSection({ draftConfig, saving, onFieldChange }: GitHubSectionProps) {
   const feed = draftConfig.github?.feed ?? {};
diff --git a/web/src/components/dashboard/config-sections/MemorySection.tsx b/web/src/components/dashboard/config-sections/MemorySection.tsx
@@ -17,9 +17,13 @@ const inputClasses =
   'w-full rounded-md border bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50';
 
 /**
- * Memory configuration section.
+ * Render the Memory configuration card for adjusting AI context memory and auto-extraction.
  *
- * Provides controls for AI context memory and auto-extraction settings.
+ * @param draftConfig - Current draft guild configuration containing memory settings
+ * @param saving - Whether a save operation is in progress; used to disable controls
+ * @param onEnabledChange - Called with the new enabled state when the Memory toggle is changed
+ * @param onFieldChange - Called with a field name and value when a configuration field is updated
+ * @returns The Card element containing controls for Max Context Memories and Auto-Extract
  */
 export function MemorySection({
   draftConfig,
diff --git a/web/src/components/dashboard/config-sections/PermissionsSection.tsx b/web/src/components/dashboard/config-sections/PermissionsSection.tsx
@@ -18,9 +18,11 @@ const inputClasses =
   'w-full rounded-md border bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50';
 
 /**
- * Permissions configuration section.
+ * Render a permissions configuration card with an enable toggle, admin/moderator role selectors, and a bot owners input.
  *
- * Provides controls for role-based access and bot owner overrides.
+ * The bot owners input shows a comma-separated list derived from the draft config and parses the input into an array of trimmed IDs on blur.
+ *
+ * @returns The rendered permissions configuration card element
  */
 export function PermissionsSection({
   draftConfig,
diff --git a/web/src/components/dashboard/config-sections/StarboardSection.tsx b/web/src/components/dashboard/config-sections/StarboardSection.tsx
@@ -16,10 +16,12 @@ const inputClasses =
   'w-full rounded-md border bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50';
 
 /**
- * Starboard configuration section.
+ * Render the Starboard configuration card with controls to edit starboard settings.
  *
- * Provides controls for pinning popular messages to a starboard channel,
- * including threshold, emoji settings, and ignored channels.
+ * @param draftConfig - Draft guild configuration whose `starboard` properties populate the form fields.
+ * @param saving - When true, form controls are disabled to prevent edits while persisting changes.
+ * @param onFieldChange - Callback invoked when a field changes; receives the field key (`'enabled' | 'channelId' | 'threshold' | 'emoji' | 'selfStarAllowed' | 'ignoredChannels'`) and the new value.
+ * @returns A JSX element containing inputs and toggles for configuring the starboard feature.
  */
 export function StarboardSection({ draftConfig, saving, onFieldChange }: StarboardSectionProps) {
   return (
diff --git a/web/src/components/dashboard/config-sections/TicketsSection.tsx b/web/src/components/dashboard/config-sections/TicketsSection.tsx
@@ -17,10 +17,17 @@ const inputClasses =
   'w-full rounded-md border bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50';
 
 /**
- * Tickets configuration section.
+ * Renders the Tickets configuration card for a guild configuration.
  *
- * Provides controls for ticket system mode, support roles, auto-close settings,
- * and transcript channel configuration.
+ * Displays an enable toggle and controls for ticket mode, support role ID,
+ * category channel ID, auto-close hours, max open tickets per user, and
+ * transcript channel ID. Inputs are disabled while `saving` is true and
+ * changes are propagated via the provided callbacks.
+ *
+ * @param draftConfig - Current draft of the guild configuration
+ * @param saving - Whether a save operation is in progress (disables inputs)
+ * @param onEnabledChange - Called with the new enabled state when the toggle changes
+ * @param onFieldChange - Called with field name and value when an input changes
  */
 export function TicketsSection({
   draftConfig,
diff --git a/web/src/components/dashboard/config-sections/TriageSection.tsx b/web/src/components/dashboard/config-sections/TriageSection.tsx
@@ -17,10 +17,18 @@ const inputClasses =
   'w-full rounded-md border bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50';
 
 /**
- * Triage configuration section.
+ * Render the Triage configuration UI for editing triage settings.
  *
- * Provides controls for message triage classifier, responder models,
- * budgets, intervals, and various feature toggles.
+ * Displays inputs and toggles for classifier and responder models, budgets,
+ * timing values, context/buffer sizes, streaming/moderation/debug options,
+ * status reactions, and moderation log channel. Renders nothing if
+ * `draftConfig.triage` is not present.
+ *
+ * @param draftConfig - Draft guild configuration containing `triage` settings
+ * @param saving - When true, disables interactions while changes are being saved
+ * @param onEnabledChange - Invoked when the top-level Triage enabled toggle changes
+ * @param onFieldChange - Invoked when a specific triage field changes; receives the field name and its new value
+ * @returns The rendered Triage section element, or `null` when triage is not configured
  */
 export function TriageSection({
   draftConfig,
diff --git a/web/src/components/dashboard/config-sections/WelcomeSection.tsx b/web/src/components/dashboard/config-sections/WelcomeSection.tsx
@@ -24,7 +24,9 @@ const inputClasses =
   'w-full rounded-md border bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50';
 
 /**
- * Generate a UUID with fallback for environments without crypto.randomUUID.
+ * Create a UUID string with a fallback for environments that lack native UUID generation.
+ *
+ * @returns A UUID-formatted string (RFC 4122 version 4 style)
  */
 function generateId(): string {
   if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
@@ -38,9 +40,22 @@ function generateId(): string {
 }
 
 /**
- * Welcome Messages configuration section.
+ * Render the "Welcome Messages" configuration UI for a guild.
+ *
+ * Presents controls for the welcome message template, rules/intro channel and verified role IDs,
+ * a configurable role-menu (add/remove/edit options), and an optional DM onboarding sequence.
  *
- * Provides controls for welcome messages, role menu, and DM sequence settings.
+ * @param draftConfig - Current draft GuildConfig containing welcome settings
+ * @param guildId - Guild identifier used by role lookups in the RoleSelector
+ * @param saving - When true, disables inputs to prevent edits during save operations
+ * @param dmStepsRaw - Raw multiline string representing DM steps (one step per line)
+ * @param onEnabledChange - Callback invoked when the welcome-enabled toggle changes
+ * @param onMessageChange - Callback invoked when the welcome message text changes
+ * @param onFieldChange - General callback for updating top-level welcome fields (e.g., rulesChannel, verifiedRole, introChannel)
+ * @param onRoleMenuChange - Callback for role menu updates; used for toggling enabled and replacing the options array
+ * @param onDmSequenceChange - Callback for DM sequence updates (e.g., enabling or replacing the steps array)
+ * @param onDmStepsRawChange - Callback invoked when the raw DM steps text changes
+ * @returns The rendered React element for the Welcome Messages configuration section
  */
 export function WelcomeSection({
   draftConfig,
diff --git a/web/src/lib/config-normalization.ts b/web/src/lib/config-normalization.ts
@@ -60,10 +60,10 @@ export function parseNumberInput(raw: string, min?: number, max?: number): numbe
 }
 
 /**
- * Normalize a threshold percentage (0-100) to a decimal (0-1).
+ * Convert a percentage (0–100) to a decimal in the range 0 to 1.
  *
- * @param percent - The percentage value (0-100)
- * @returns Clamped decimal value between 0 and 1
+ * @param percent - Percentage value to convert
+ * @returns `0` if `percent` is `NaN`, otherwise the input divided by 100 clamped to the range `0` to `1`
  */
 export function percentToDecimal(percent: number): number {
   if (Number.isNaN(percent)) return 0;
diff --git a/web/src/lib/config-updates.ts b/web/src/lib/config-updates.ts
