feat: enhanced user matcher

Author: coltenkrauter

.github/workflows/tests.yaml

@@ -35,3 +35,19 @@ jobs:
           with-test-data: true
       - name: Print Output
         run: echo "${{ steps.test-action.outputs.response }}"
+  test-action-2:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Test Action
+        uses: ./
+        with:
+          github-tokens: test, ${{ secrets.GH_TOKEN_GH_NOTIFIER }}
+          channels: C07L8EWB389
+          user-mappings: reviewer1:nassirougni
+          slack-token: ${{ secrets.SLACK_TOKEN_GH_NOTIFIER }}
+          with-test-data: true
+      - name: Print Output
+        run: echo "${{ steps.test-action.outputs.response }}"
+      

action.yaml

@@ -28,6 +28,16 @@ inputs:
   channels:
     required: true
     description: Comma-separated list of Slack channel IDs to post to.
+  user-mappings:
+    required: false
+    description: |
+      Comma-separated list of GitHub to Slack username mappings in the format "github:slack".
+      These mappings are PRIORITIZED over automatic matching between GitHub and Slack users.
+      If a mapping is defined but the Slack username doesn't exist, it will fall back to automatic matching.
+      The automatic matching tries to match by email and username when custom mapping fails.
+      Used specifically during Slack user lookup for @mentions and avatars in notifications.
+      Example: "octocat:slackcat,user1:slack1" would map GitHub username "octocat" to Slack username "slackcat".
+    default: ""
   with-test-data:
     description: Append some test data to the Slack post.
     required: false

dist/index.js

@@ -1,7 +1,7 @@
 {
   "name": "@krauters/github-notifier",
   "description": "GitHub Notifier by Krauters – Post Open Pull Requests to Slack",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "author": "Colten Krauter <coltenkrauter>",
   "type": "module",
   "homepage": "https://buymeacoffee.com/coltenkrauter",

dist/index.js.map

@@ -13,7 +13,7 @@ import type { Pull } from './utils/github/structures.js'
 import { PullState, RepositoryType } from './utils/github/structures.js'
 import { getFirstBlocks, getLastBlocks, getPullBlocks } from './utils/slack/blocks.js'
 import { SlackClient } from './utils/slack/client.js'
-import { getApprovedPullRequest } from './utils/test-data.js'
+import { getApprovedPullRequest, getChangesRequestedPullRequest } from './utils/test-data.js'
 import { parseInputs as getInputs } from './input-parser.js'
 
 const { homepage, name, version } = pkg
@@ -73,13 +73,12 @@ async function main(): Promise<void> {
 			throw new Error('All GitHub tokens failed to process')
 		}
 
-		console.log(`Successfully processed ${results.length} out of ${githubConfig.tokens.length} tokens`)
+		console.log(`Successfully processed [${results.length}] out of [${githubConfig.tokens.length}] tokens`)
 
 		await slack.enforceAppNamePattern(/.*github[\s-_]?notifier$/i)
 
 		const pulls: Pull[] = results.flatMap((result) => result.pulls)
-		console.log(`Found ${pulls.length} pulls`)
-		console.log(pulls)
+		console.log(`Found [${pulls.length}] pulls`)
 
 		// Multiple tokens may have overlapping repository access, deduplicate PRs by org/repo/number
 		const dedupedPulls = [...new Map(pulls.map((pull) => [`${pull.org}/${pull.repo}/${pull.number}`, pull]))].map(
@@ -95,13 +94,15 @@ async function main(): Promise<void> {
 		}
 
 		if (withTestData) {
-			console.log(`With test data: [${withTestData}]`)
-			const testDataPullRequest = getApprovedPullRequest()
+			console.log(`With test data [${withTestData}]`)
+			const test1 = getApprovedPullRequest()
 			for (let i = 1; i <= 2; i++) {
-				blocks = [
-					...blocks,
-					...(await getPullBlocks({ ...testDataPullRequest, number: i }, slack, withUserMentions)),
-				]
+				blocks = [...blocks, ...(await getPullBlocks({ ...test1, number: i }, slack, withUserMentions))]
+			}
+
+			const test2 = getChangesRequestedPullRequest()
+			for (let i = 1; i <= 2; i++) {
+				blocks = [...blocks, ...(await getPullBlocks({ ...test2, number: i }, slack, withUserMentions))]
 			}
 		}
 

package-lock.json

@@ -2,6 +2,7 @@ import { debug, getBooleanInput, getInput } from '@actions/core'
 import { stringToArray } from '@krauters/utils'
 
 import type { InputProps } from './structures.js'
+import type { UserMapping } from './utils/slack/structures.js'
 
 /**
  * Parses and validates all inputs required for the GitHub Notifier.
@@ -21,6 +22,18 @@ export function parseInputs(): InputProps {
 	const withUserMentions = getBooleanInput('with-user-mentions')
 	const repositoryFilter = stringToArray(getInput('repository-filter'))
 
+	const userMappings = stringToArray(getInput('user-mappings'))
+		.map((entry) => {
+			const [github, slack] = entry.split(':').map((part) => part?.trim())
+
+			return github && slack ? { githubUsername: github, slackUsername: slack } : null
+		})
+		.filter((mapping): mapping is UserMapping => mapping !== null)
+
+	if (userMappings.length > 0) {
+		debug(`Parsed [${userMappings.length}] GitHub to Slack user mappings`)
+	}
+
 	// https://github.com/actions/github-script/issues/436
 	const baseUrl = getInput('base-url') || process.env.GITHUB_API_URL
 
@@ -35,6 +48,7 @@ export function parseInputs(): InputProps {
 		slackConfig: {
 			channels,
 			token: slackToken,
+			userMappings,
 		},
 		withArchived,
 		withDrafts,

package.json

@@ -4,26 +4,31 @@ import type { Bot } from '@slack/web-api/dist/types/response/BotsInfoResponse.js
 import type { Member } from '@slack/web-api/dist/types/response/UsersListResponse.js'
 import type { User } from '@slack/web-api/dist/types/response/UsersLookupByEmailResponse.js'
 
+import { debug } from '@actions/core'
 import { getBatches } from '@krauters/utils'
 import { WebClient } from '@slack/web-api'
 
-import { type GetUser, SlackAppUrl, type SlackConfig } from './structures.js'
+import { type GetUser, SlackAppUrl, type SlackConfig, type UserMapping } from './structures.js'
+import { createUserMatchers, logFailedMatches, type MatchParams } from './user-matchers.js'
 
 export class SlackClient {
 	public bot?: Bot
 	private channels: string[]
 	private client: WebClient
+	private userMappings: UserMapping[]
 	private users: undefined | User[]
 
 	/**
 	 * Slack client for interacting with the Slack API.
 	 *
 	 * @param token Slack token.
 	 * @param channels Slack channel IDs for posting messages in.
+	 * @param userMappings User mappings for the Slack client.
 	 */
-	constructor({ channels, token }: SlackConfig) {
+	constructor({ channels, token, userMappings = [] }: SlackConfig) {
 		this.client = new WebClient(token)
 		this.channels = channels
+		this.userMappings = userMappings
 	}
 
 	/**
@@ -101,59 +106,35 @@ export class SlackClient {
 	 * @param [botId] The botId for the bot to find.
 	 */
 	async getUser({ email, userId, username }: GetUser): Promise<Member | undefined> {
-		console.log(`Getting Slack UserId for email [${email}], username [${username}], and userId [${userId}]...`)
+		debug(`Getting Slack UserId for email [${email}], username [${username}], and userId [${userId}]...`)
 
 		const users = this.users ?? (await this.getAllusers())
+		const matchParams: MatchParams = { email, userId, userMappings: this.userMappings, username }
+		const matchers = createUserMatchers(matchParams)
 
-		// Define matching functions for better readability and extensibility
-		const matchById = (user: Member) => userId && user.id === userId
-		const matchByEmail = (user: Member) => email && user.profile?.email === email
-		const matchByEmailContainsUsername = (user: Member) =>
-			username && String(user.profile?.email ?? '').includes(username)
-		const matchByDisplayName = (user: Member) => username && user.profile?.display_name === username
-		const matchByRealName = (user: Member) => username && user.profile?.real_name === username
-
-		const user = users.find((user: Member) => {
-			const idMatch = matchById(user)
-			const emailMatch = matchByEmail(user)
-			const emailContainsUsernameMatch = matchByEmailContainsUsername(user)
-			const displayNameMatch = matchByDisplayName(user)
-			const realNameMatch = matchByRealName(user)
-
-			// Log the first match attempt that succeeds for debugging
-			if (idMatch && userId) console.log(`Match found by userId [${userId}] with Slack userId [${user.id}]`)
-			else if (emailMatch && email)
-				console.log(`Match found by email [${email}] with Slack email [${user.profile?.email}]`)
-			else if (emailContainsUsernameMatch && username)
-				console.log(`Match found by username [${username}] contained in Slack email [${user.profile?.email}]`)
-			else if (displayNameMatch && username)
-				console.log(
-					`Match found by username [${username}] matching Slack display_name [${user.profile?.display_name}]`,
-				)
-			else if (realNameMatch && username)
-				console.log(
-					`Match found by username [${username}] matching Slack real_name [${user.profile?.real_name}]`,
-				)
+		// Find the first user that matches any of our criteria
+		const matchedUser = users.find((slackUser) => {
+			// Find a matching criteria for this Slack user, if any
+			const matchedCriteria = matchers.find((criteria) => criteria.check(slackUser))
+
+			// If we found a match, log it
+			if (matchedCriteria) {
+				matchedCriteria.log(slackUser)
 
-			// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
-			return idMatch || emailMatch || emailContainsUsernameMatch || displayNameMatch || realNameMatch
+				return true
+			}
+
+			return false
 		})
 
-		if (user) {
-			console.log(`User found with userId [${user.id}]`)
+		if (matchedUser) {
+			debug(`User found with userId [${matchedUser.id}]`)
 
-			return user
+			return matchedUser
 		}
 
-		console.log(`No user match found after checking against [${users.length}] users`)
-		if (userId) console.log(`Tried to match userId [${userId}] against Slack user.id fields`)
-		if (email) console.log(`Tried to match email [${email}] against Slack user.profile.email fields`)
-		if (username)
-			console.log(
-				`Tried to match username [${username}] against Slack user.profile.email (contains), display_name and real_name fields`,
-			)
-
-		console.log(`Since no Slack user match found, unable to @mention user or use their profile image`)
+		// No match found, log the failure
+		logFailedMatches(matchParams, users.length)
 	}
 
 	/**

src/app.ts

@@ -1,6 +1,6 @@
 export enum SlackAppUrl {
 	Prefix = 'https://api.slack.com/apps',
-	SuffixDisplayInfo = 'general#display_info_form',
+	SuffixDisplayInfo = 'general',
 }
 
 export interface GetUser {
@@ -12,4 +12,10 @@ export interface GetUser {
 export interface SlackConfig {
 	channels: string[]
 	token: string
+	userMappings?: UserMapping[]
+}
+
+export interface UserMapping {
+	githubUsername: string
+	slackUsername: string
 }