feat: PR description suggestion workflow

.cursorignore

@@ -0,0 +1,2 @@
+.env
+.env.example

apps/agent/src/constants/discord.ts

@@ -3,4 +3,5 @@ export const DISCORD_GITHUB_MAP = {
   vdhieu: '797044001579597846',
   'R-Jim': '797044001579597846',
   chinhld: '757540075159420948',
+  catngh: '319132138849173505',
 }

apps/agent/src/lib/type.d.ts

@@ -14,6 +14,7 @@ export interface PullRequest {
   reviewers: string[]
   hasComments: boolean
   hasReviews: boolean
+  body: string
 }
 
 interface Author {

apps/agent/src/mastra/agents/analyze-github-prs.ts

@@ -0,0 +1,45 @@
+import { openai } from '@ai-sdk/openai'
+import { Agent } from '@mastra/core/agent'
+
+// currently we are not reading the PR changes, so we can't auto generate the description
+export const suggestPRDescriptionAgent = new Agent({
+  name: 'agent suggest PR description',
+  instructions: `
+    You are an AI assistant tasked with reviewing multiple pull request (PR) descriptions. Your goal is to ensure they are clear enough.
+    A description needs improvement if it's empty, missing a clear problem statement, or lacks sufficient context about the changes.
+
+    Guidelines for good PR descriptions:
+    - Should explain the problem being solved or include an issue ticket url
+    - Should describe the solution approach
+
+    Input Format:
+    You will receive an array of PRs, each containing:
+    - url: PR url
+    - title: PR title
+    - body: PR description
+
+    Output Format:
+    Return a JSON array containing the PR numbers that need description improvements.
+    Example: ["https://github.com/dwarvesf/github-agent/pull/31", "https://github.com/dwarvesf/github-agent/pull/12"]
+
+    Example Input:
+    [
+      {
+        "url": "https://github.com/dwarvesf/github-agent/pull/31",
+        "title": "fix(auth): handle login errors",
+        "body": "I fixed the bug"
+      },
+      {
+        "url": "https://github.com/dwarvesf/github-agent/pull/12",
+        "title": "feat(api): add user endpoints",
+        "body": "This PR adds new user management endpoints with proper validation and error handling. Includes:\n- GET /users\n- POST /users\n- PUT /users/:id"
+      }
+    ]
+
+    Example Output:
+    ["https://github.com/dwarvesf/github-agent/pull/31"]
+
+    Only return the array of PR urls. No additional explanation needed.
+  `,
+  model: openai('gpt-4o-mini'),
+})

apps/agent/src/mastra/tools/github.ts

@@ -58,6 +58,7 @@ export const getTodayPRListTool = createTool({
         reviewers: pr.requested_reviewers.map((reviewer) => reviewer.login),
         hasComments: pr.comments > 0 || pr.review_comments > 0,
         hasReviews: pr.reviews && pr.reviews.length > 0,
+        body: pr.body,
       })),
     }
   },
@@ -115,6 +116,7 @@ export const getPullRequestTool = createTool({
         reviewers: pr.requested_reviewers.map((reviewer) => reviewer.login),
         hasComments: pr.comments > 0 || pr.review_comments > 0,
         hasReviews: pr.reviews && pr.reviews.length > 0,
+        body: pr.body,
       })),
     }
   },

apps/agent/src/mastra/workflows/github-notify-developer-about-pr-status.ts

@@ -5,6 +5,11 @@ import { discordClient } from '../../lib/discord'
 import { groupBy } from '../../utils/array'
 import { PullRequest } from '../../lib/type'
 import { DISCORD_GITHUB_MAP } from '../../constants/discord'
+import { suggestPRDescriptionAgent } from '../agents/analyze-github-prs'
+import {
+  convertNestedArrayToTreeList,
+  prTitleFormatValid,
+} from '../../utils/string'
 
 async function handleMergeConflicts(discordUserId: string, prs: PullRequest[]) {
   const hasMergedConflictsPRs = prs.filter(
@@ -60,6 +65,84 @@ async function handleWaitingForReview(
   }
 }
 
+async function handleUnconventionalTitleOrDescription(
+  discordUserId: string,
+  prs: PullRequest[],
+) {
+  const readyToCheckPRs = prs.filter((pr: PullRequest) => !pr.isWIP)
+
+  // Check all PR descriptions in one batch
+  let prsNeedingDescriptionImprovement: PullRequest[] = []
+
+  if (readyToCheckPRs.length > 0) {
+    try {
+      const agentResponse = await suggestPRDescriptionAgent.generate([
+        {
+          role: 'user',
+          content: JSON.stringify(
+            readyToCheckPRs.map((pr) => ({
+              url: pr.url,
+              title: pr.title,
+              body: pr.body,
+            })),
+          ),
+        },
+      ])
+
+      try {
+        const prsNeedingImprovement = JSON.parse(agentResponse.text) as string[]
+        if (Array.isArray(prsNeedingImprovement)) {
+          prsNeedingDescriptionImprovement = readyToCheckPRs.filter((pr) =>
+            prsNeedingImprovement.includes(pr.url),
+          )
+        } else {
+          console.error('Invalid response format from LLM:', agentResponse.text)
+        }
+      } catch (parseError) {
+        console.error('Failed to parse LLM response:', parseError)
+      }
+    } catch (agentError) {
+      console.error('Failed to get LLM suggestions:', agentError)
+    }
+  }
+
+  // Check for invalid titles
+  const invalidTitlePRs = readyToCheckPRs.filter(
+    (pr) => !prTitleFormatValid(pr.title),
+  )
+
+  // Combine both sets of PRs using Set to remove duplicates
+  const wrongConventionPRs = Array.from(
+    new Set([...invalidTitlePRs, ...prsNeedingDescriptionImprovement]),
+  )
+
+  if (wrongConventionPRs.length > 0) {
+    const notifyMessage =
+      '\n\n• Ensure title follows: `type(scope?): message`\n• Include a clear description of the problem and solution'
+
+    const listInText = wrongConventionPRs
+      .map((pr) => {
+        return `[#${pr.number}](${pr.url}) | ${pr.title}`
+      })
+      .join('\n')
+
+    const embed = {
+      title: `📝 Improve PR clarity`,
+      color: 15158332,
+      description: `${listInText}${notifyMessage}`,
+      inline: false,
+    }
+
+    await discordClient.sendMessageToUser({
+      userId: discordUserId,
+      message: '',
+      embed,
+    })
+  }
+
+  return wrongConventionPRs
+}
+
 const notifyDeveloperAboutPRStatus = new Workflow({
   name: 'Notify developer about PR status',
 })
@@ -75,18 +158,22 @@ const notifyDeveloperAboutPRStatus = new Workflow({
           getTodayPRListTool.id,
         )
 
-        const byAuthor = groupBy(output?.list || [], (pr) => pr.author)
+        const byAuthor = groupBy(
+          output?.list || [],
+          (pr: PullRequest) => pr.author,
+        )
 
         await Promise.all(
           Object.entries(byAuthor).map(async ([author, prs]) => {
             const discordUserId =
               DISCORD_GITHUB_MAP[author as keyof typeof DISCORD_GITHUB_MAP]
             if (discordUserId) {
-              // Notify developer if their PR has merge conflicts
-              await handleMergeConflicts(discordUserId, prs)
-
-              // Notify developer if their PR needs to tag for review
-              await handleWaitingForReview(discordUserId, prs)
+              await handleMergeConflicts(discordUserId, prs as PullRequest[])
+              await handleWaitingForReview(discordUserId, prs as PullRequest[])
+              await handleUnconventionalTitleOrDescription(
+                discordUserId,
+                prs as PullRequest[],
+              )
             }
           }),
         )

apps/agent/src/utils/__tests__/string.test.ts

@@ -3,6 +3,7 @@ import {
   convertArrayToMarkdownTableList,
   convertNestedArrayToTreeList,
   escapeSpecialCharactersForMarkdown,
+  prTitleFormatValid,
 } from '../string'
 
 describe('escapeSpecialCharactersForMarkdown', () => {
@@ -77,3 +78,32 @@ describe('convertNestedArrayToTreeList', () => {
     expect(convertNestedArrayToTreeList(input)).toBe(expected)
   })
 })
+
+describe('prTitleFormatValid', () => {
+  it('valid formats', () => {
+    expect(prTitleFormatValid('feat: add login feature')).toBe(true)
+    expect(prTitleFormatValid('fix(parser): resolve issue')).toBe(true)
+    expect(prTitleFormatValid('123(scope): numeric type')).toBe(true)
+    expect(prTitleFormatValid('fix(scope-123): special chars')).toBe(true)
+    expect(prTitleFormatValid('feat(verylongscope): long message')).toBe(true)
+  })
+
+  it('invalid formats', () => {
+    expect(prTitleFormatValid('feat add login feature')).toBe(false)
+    expect(prTitleFormatValid(': missing type')).toBe(false)
+    expect(prTitleFormatValid('feat(scope)missing colon')).toBe(false)
+    expect(prTitleFormatValid('feat() message')).toBe(false)
+    expect(prTitleFormatValid(' feat: leading space')).toBe(false)
+    expect(prTitleFormatValid('feat: trailing space ')).toBe(false)
+    expect(prTitleFormatValid('fix(scope) :space before colon')).toBe(false)
+    expect(prTitleFormatValid('')).toBe(false)
+    expect(prTitleFormatValid('feat:')).toBe(false)
+    expect(prTitleFormatValid('feat: ')).toBe(false)
+    expect(prTitleFormatValid('feat(): message')).toBe(false)
+    expect(prTitleFormatValid('(): message')).toBe(false)
+    expect(prTitleFormatValid('feat(scope with space): valid')).toBe(false)
+    expect(prTitleFormatValid('fix(scope!): invalid chars')).toBe(false)
+    expect(prTitleFormatValid('fix(scope): multi: colon')).toBe(false)
+    expect(prTitleFormatValid('fix(scope):')).toBe(false)
+  })
+})

apps/agent/src/utils/string.ts

@@ -53,3 +53,9 @@ export const getOneLineCommit = (originCommit: string): string => {
 
   return lines[0] || ''
 }
+
+export const prTitleFormatValid = (title: string): boolean => {
+  const titleFormatRegex =
+    /^[a-zA-Z0-9]+(\([a-zA-Z0-9\-_]+\))?: [a-zA-Z0-9]+(?: [a-zA-Z0-9]+)*$/
+  return titleFormatRegex.test(title)
+}