Improved single input help search

rocketbot/cogs/basecog.py

@@ -75,7 +75,7 @@ class BaseCog(Cog):
 		"""
 		return [
 			bcog
-			for bcog in self.bot.cogs.values()
+			for bcog in sorted(self.bot.cogs.values(), key=lambda c: c.qualified_name)
 			if isinstance(bcog, BaseCog)
 		]
 

rocketbot/cogs/helpcog.py

@@ -1,14 +1,31 @@
+"""Provides help commands for getting info on using other commands and configuration."""
 import re
 from typing import Union, Optional
 
 from discord import Interaction, Permissions, AppCommandType
 from discord.app_commands import Group, Command, autocomplete, guild_only, command, Choice
+from discord.ext.commands import cog
 
 from config import CONFIG
 from rocketbot.bot import Rocketbot
 from rocketbot.cogs.basecog import BaseCog
 from rocketbot.utils import MOD_PERMISSIONS, dump_stacktrace
 
+HelpTopic = Union[Command, Group, BaseCog]
+
+def choice_from_obj(obj: HelpTopic, include_full_command: bool = False) -> Choice:
+	if isinstance(obj, BaseCog):
+		return Choice(name=f'⚙ {obj.qualified_name}', value=f'cog:{obj.qualified_name}')
+	if isinstance(obj, Group):
+		return Choice(name=f'/{obj.name}', value=f'cmd:{obj.name}')
+	if isinstance(obj, Command):
+		if obj.parent:
+			if include_full_command:
+				return Choice(name=f'/{obj.parent.name} {obj.name}', value=f'subcmd:{obj.parent.name}.{obj.name}')
+			return Choice(name=f'{obj.name}', value=f'subcmd:{obj.name}')
+		return Choice(name=f'/{obj.name}', value=f'cmd:{obj.name}')
+	return Choice(name='', value='')
+
 async def command_autocomplete(interaction: Interaction, current: str) -> list[Choice[str]]:
 	"""Autocomplete handler for top-level command names."""
 	choices: list[Choice] = []
@@ -31,22 +48,21 @@ async def subcommand_autocomplete(interaction: Interaction, current: str) -> lis
 	"""Autocomplete handler for subcommand names. Command taken from previous command token."""
 	try:
 		current = current.lower().strip()
-		cmd_name = interaction.namespace['topic']
+		cmd_name = interaction.namespace.get('topic', None)
 		cmd = HelpCog.shared.object_for_help_symbol(cmd_name)
-		if not isinstance(cmd, Group):
+		if isinstance(cmd, Command):
+			# No subcommands
 			return []
 		user_permissions = interaction.permissions
 		if cmd is None or not isinstance(cmd, Group):
-			print(f'No command found named {cmd_name}')
 			return []
 		grp = cmd
 		subcmds = HelpCog.shared.get_subcommand_list(grp, user_permissions)
 		if subcmds is None:
-			print(f'Subcommands for {cmd_name} was None')
 			return []
 		return [
-			Choice(name=f'{subcmd_name} subcommand', value=f'subcmd:{cmd.name}.{subcmd_name}')
-			for subcmd_name in sorted(subcmds.keys())
+			choice_from_obj(subcmd)
+			for subcmd_name, subcmd in sorted(subcmds.items())
 			if len(current) == 0 or current in subcmd_name
 		][:25]
 	except BaseException as e:
@@ -58,7 +74,7 @@ async def cog_autocomplete(interaction: Interaction, current: str) -> list[Choic
 	try:
 		current = current.lower().strip()
 		return [
-			Choice(name=f'⚙ {cog.qualified_name} module', value=f'cog:{cog.qualified_name}')
+			choice_from_obj(cog)
 			for cog in sorted(HelpCog.shared.bot.cogs.values(), key=lambda c: c.qualified_name)
 			if isinstance(cog, BaseCog) and
 			   can_use_cog(cog, interaction.permissions) and
@@ -80,6 +96,21 @@ async def subtopic_autocomplete(interaction: Interaction, current: str) -> list[
 	subcommand_choices = await subcommand_autocomplete(interaction, current)
 	return subcommand_choices[:25]
 
+async def search_autocomplete(interaction: Interaction, current: str) -> list[Choice[str]]:
+	try:
+		if len(current) == 0:
+			return [
+				choice_from_obj(obj, include_full_command=True)
+				for obj in HelpCog.shared.all_accessible_objects(interaction.permissions)
+			]
+		return [
+			choice_from_obj(obj, include_full_command=True)
+			for obj in HelpCog.shared.objects_for_keywords(current, interaction.permissions)
+		]
+	except BaseException as e:
+		dump_stacktrace(e)
+		return []
+
 class HelpCog(BaseCog, name='Help'):
 	shared: Optional['HelpCog'] = None
 
@@ -99,8 +130,8 @@ class HelpCog(BaseCog, name='Help'):
 		"""
 		if getattr(self, 'obj_index', None) is not None:
 			return
-		self.obj_index: dict[str, Union[Command, Group, BaseCog]] = {}
-		self.keyword_index: dict[str, set[Union[Command, Group, BaseCog]]] = {}
+		self.obj_index: dict[str, HelpTopic] = {}
+		self.keyword_index: dict[str, set[HelpTopic]] = {}
 
 		def add_text_to_index(obj, text: str):
 			words = [
@@ -113,9 +144,7 @@ class HelpCog(BaseCog, name='Help'):
 				matches.add(obj)
 				self.keyword_index[word] = matches
 
-		# PyCharm not interpreting conditional return type correctly.
-		# noinspection PyTypeChecker
-		cmds: list[Union[Command, Group]] = self.bot.tree.get_commands(type=AppCommandType.chat_input)
+		cmds = self.all_commands()
 		for cmd in cmds:
 			key = f'cmd:{cmd.name}'
 			self.obj_index[key] = cmd
@@ -126,6 +155,7 @@ class HelpCog(BaseCog, name='Help'):
 				for subcmd in cmd.commands:
 					key = f'subcmd:{cmd.name}.{subcmd.name}'
 					self.obj_index[key] = subcmd
+					add_text_to_index(subcmd, cmd.name)
 					add_text_to_index(subcmd, subcmd.name)
 					if subcmd.description:
 						add_text_to_index(subcmd, subcmd.description)
@@ -138,14 +168,99 @@ class HelpCog(BaseCog, name='Help'):
 			if cog.description:
 				add_text_to_index(cog, cog.description)
 
-	def object_for_help_symbol(self, symbol: str) -> Optional[Union[Command, Group, BaseCog]]:
+	def object_for_help_symbol(self, symbol: str) -> Optional[HelpTopic]:
 		self.__create_help_index()
 		return self.obj_index.get(symbol, None)
 
+	def all_commands(self) -> list[Union[Command, Group]]:
+		# PyCharm not interpreting conditional return type correctly.
+		# noinspection PyTypeChecker
+		cmds: list[Union[Command, Group]] = self.bot.tree.get_commands(type=AppCommandType.chat_input)
+		return sorted(cmds, key=lambda cmd: cmd.name)
+
+	def all_accessible_commands(self, permissions: Optional[Permissions]) -> list[Union[Command, Group]]:
+		return [
+			cmd
+			for cmd in self.all_commands()
+			if can_use_command(cmd, permissions)
+		]
+
+	def all_accessible_subcommands(self, permissions: Optional[Permissions]) -> list[Command]:
+		cmds = self.all_accessible_commands(permissions)
+		subcmds: list[Command] = []
+		for cmd in cmds:
+			if isinstance(cmd, Group):
+				for subcmd in sorted(cmd.commands, key=lambda cmd: cmd.name):
+					if can_use_command(subcmd, permissions):
+						subcmds.append(subcmd)
+		return subcmds
+
+	def all_accessible_cogs(self, permissions: Optional[Permissions]) -> list[BaseCog]:
+		return [
+			cog
+			for cog in self.basecogs
+			if can_use_cog(cog, permissions)
+		]
+
+	def all_accessible_objects(self, permissions: Optional[Permissions], *,
+							   include_cogs: bool = True,
+							   include_commands: bool = True,
+							   include_subcommands: bool = True) -> list[HelpTopic]:
+		objs = []
+		if include_cogs:
+			objs += self.all_accessible_cogs(permissions)
+		if include_commands:
+			objs += self.all_accessible_commands(permissions)
+		if include_subcommands:
+			objs += self.all_accessible_subcommands(permissions)
+		return objs
+
+	def objects_for_keywords(self, search: str, permissions: Optional[Permissions]) -> list[HelpTopic]:
+		self.__create_help_index()
+
+		# Break into words (or word fragments)
+		words: list[str] = [
+			word.lower()
+			for word in re.split(r"[^a-zA-Z']+", search)
+			# if len(word) > 1 and word not in trivial_words
+		]
+
+		# FIXME: This is a super weird way of doing this. Converting word fragments
+		# to known indexed keywords, then collecting those associated results. Should
+		# just keep corpuses of searchable, normalized text for each topic and do a
+		# direct `in` test.
+		matching_objects_set = None
+		for word in words:
+			word_matches = set()
+			for k in self.keyword_index.keys():
+				if word in k:
+					objs = self.keyword_index.get(k, None)
+					if objs is not None:
+						word_matches.update(objs)
+			if matching_objects_set is None:
+				matching_objects_set = word_matches
+			else:
+				matching_objects_set = matching_objects_set & word_matches
+
+		# Filter by accessibility
+		accessible_objects = [
+			obj
+			for obj in matching_objects_set or {}
+			if ((isinstance(obj, Command) or isinstance(obj, Group)) and can_use_command(obj, permissions)) or \
+			   (isinstance(obj, BaseCog) and can_use_cog(obj, permissions))
+		]
+
+		# Sort and return
+		return sorted(accessible_objects, key=lambda obj: (
+			isinstance(obj, Command),
+			isinstance(obj, BaseCog),
+			obj.qualified_name if isinstance(obj, BaseCog) else obj.name
+		))
+
 	@command(name='help')
 	@guild_only()
-	@autocomplete(topic=topic_autocomplete, subtopic=subtopic_autocomplete)
-	async def help_command(self, interaction: Interaction, topic: Optional[str] = None, subtopic: Optional[str] = None) -> None:
+	@autocomplete(search=search_autocomplete)
+	async def help_command(self, interaction: Interaction, search: Optional[str]) -> None:
 		"""
 		Shows help for using commands and subcommands and configuring modules.
 
@@ -164,47 +279,20 @@ class HelpCog(BaseCog, name='Help'):
 		Parameters
 		----------
 		interaction: Interaction
-		topic: Optional[str]
-			optional command, module, or keywords to get specific help for
-		subtopic: Optional[str]
-			optional subcommand to get specific help for
+		search: Optional[str]
+			search terms
 		"""
-		print(f'help_command(interaction, {topic}, {subtopic})')
-
-		# General help
-		if topic is None:
+		if search is None:
 			await self.__send_general_help(interaction)
 			return
-
-		# Specific object reference
-		obj = self.object_for_help_symbol(subtopic) if subtopic else self.object_for_help_symbol(topic)
+		obj = self.object_for_help_symbol(search)
 		if obj:
 			await self.__send_object_help(interaction, obj)
 			return
+		matches = self.objects_for_keywords(search, interaction.permissions)
+		await self.__send_keyword_help(interaction, matches)
 
-		# Text search
-		keywords = [
-			word
-			for word in re.split(r"[^a-zA-Z']+", topic.lower())
-			if len(word) > 0 and word not in trivial_words
-		]
-		matching_objects_set = None
-		for keyword in keywords:
-			objs = self.keyword_index.get(keyword, None)
-			if objs is not None:
-				if matching_objects_set is None:
-					matching_objects_set = objs
-				else:
-					matching_objects_set = matching_objects_set & objs
-		accessible_objects = [
-			obj
-			for obj in matching_objects_set or {}
-			if ((isinstance(obj, Command) or isinstance(obj, Group)) and can_use_command(obj, interaction.permissions)) or \
-			   (isinstance(obj, BaseCog) and can_use_cog(obj, interaction.permissions))
-		]
-		await self.__send_keyword_help(interaction, accessible_objects)
-
-	async def __send_object_help(self, interaction: Interaction, obj: Union[Command, Group, BaseCog]) -> None:
+	async def __send_object_help(self, interaction: Interaction, obj: HelpTopic) -> None:
 		if isinstance(obj, Command):
 			if obj.parent:
 				await self.__send_subcommand_help(interaction, obj.parent, obj)
@@ -217,7 +305,7 @@ class HelpCog(BaseCog, name='Help'):
 		if isinstance(obj, BaseCog):
 			await self.__send_cog_help(interaction, obj)
 			return
-		print(f'No help for object {obj}')
+		self.log(interaction.guild, f'No help for object {obj}')
 		await interaction.response.send_message(
 			f'{CONFIG["failure_emoji"]} Failed to get help info.',
 			ephemeral=True,
@@ -273,7 +361,7 @@ class HelpCog(BaseCog, name='Help'):
 			ephemeral=True,
 		)
 
-	async def __send_keyword_help(self, interaction: Interaction, matching_objects: Optional[list[Union[Command, Group, BaseCog]]]) -> None:
+	async def __send_keyword_help(self, interaction: Interaction, matching_objects: Optional[list[HelpTopic]]) -> None:
 		matching_commands = [
 			cmd
 			for cmd in matching_objects or []
@@ -314,8 +402,6 @@ class HelpCog(BaseCog, name='Help'):
 		)
 
 	async def __send_command_help(self, interaction: Interaction, command_or_group: Union[Command, Group], addendum: Optional[str] = None) -> None:
-		if isinstance(command_or_group, Command):
-			print(f"Doc:\n{command_or_group.callback.__doc__}")
 		text = ''
 		if addendum is not None:
 			text += addendum + '\n\n'
@@ -375,7 +461,6 @@ class HelpCog(BaseCog, name='Help'):
 				if setting.name == 'enabled':
 					continue
 				text += f'\n- `/get` or `/set {cog.config_prefix}_{setting.name}` - {setting.brief}'
-		print(text)
 		await interaction.response.send_message(
 			text,
 			ephemeral=True,