python-app-rocketbot/rocketbot/cogs/helpcog.py

"""Provides help commands for getting info on using other commands and configuration."""
import re
import time
from typing import Optional, TypedDict

from discord import AppCommandType, Interaction, Permissions
from discord.app_commands import (
	Choice,
	Command,
	Group,
	autocomplete,
	command,
	guild_only,
)
from discord.errors import DiscordException

from config import CONFIG
from rocketbot.bot import Rocketbot
from rocketbot.cogs.basecog import BaseCog
from rocketbot.ui.pagedcontent import paginate, update_paged_content
from rocketbot.utils import MOD_PERMISSIONS, dump_stacktrace

HelpTopic = Command | Group | BaseCog
class HelpMeta(TypedDict):
	id: str
	text: str
	topic: HelpTopic

# Potential place to break text neatly in large help content
PAGE_BREAK = '\f'

def choice_from_topic(topic: HelpTopic, include_full_command: bool = False) -> Choice:
	if isinstance(topic, BaseCog):
		return Choice(name=f'⚙ {topic.qualified_name}', value=f'cog:{topic.qualified_name}')
	if isinstance(topic, Group):
		return Choice(name=f'/{topic.name}', value=f'cmd:{topic.name}')
	if isinstance(topic, Command):
		if topic.parent:
			if include_full_command:
				return Choice(name=f'/{topic.parent.name} {topic.name}', value=f'subcmd:{topic.parent.name}.{topic.name}')
			return Choice(name=f'{topic.name}', value=f'subcmd:{topic.name}')
		return Choice(name=f'/{topic.name}', value=f'cmd:{topic.name}')
	return Choice(name='', value='')

async def search_autocomplete(interaction: Interaction, current: str) -> list[Choice[str]]:
	try:
		if len(current) == 0:
			return [
				choice_from_topic(topic, include_full_command=True)
				for topic in HelpCog.shared.all_accessible_topics(interaction.permissions)
			]
		return [
			choice_from_topic(topic, include_full_command=True)
			for topic in HelpCog.shared.topics_for_keywords(current, interaction.permissions)
		][:25]
	except DiscordException as e:
		dump_stacktrace(e)
		return []

class HelpCog(BaseCog, name='Help'):
	shared: Optional['HelpCog'] = None

	def __init__(self, bot: Rocketbot):
		super().__init__(
			bot,
			config_prefix='help',
			short_description='Provides help on using this bot.'
		)
		HelpCog.shared = self

	def __create_help_index(self) -> None:
		"""
		Populates self.id_to_topic and self.keyword_index. Bails if already
		populated. Intended to be run on demand so all cogs and commands have
		had time to get set up and synced.
		"""
		if getattr(self, 'id_to_topic', None) is not None:
			return
		self.id_to_topic: dict[str, HelpTopic] = {}
		self.topics: list[HelpMeta] = []

		def process_text(t: str) -> str:
			return ' '.join([
				word
				for word in re.split(r"[^a-z']+", t.lower())
				if word not in trivial_words
			]).strip()

		cmds = self.all_commands()
		for cmd in cmds:
			key = f'cmd:{cmd.name}'
			self.id_to_topic[key] = cmd
			self.id_to_topic[f'/{cmd.name}'] = cmd
			text = cmd.name
			if cmd.description:
				text += f' {cmd.description}'
			if cmd.extras.get('long_description', None):
				text += f' {cmd.extras["long_description"]}'
			self.topics.append({ 'id': key, 'text': process_text(text), 'topic': cmd })
			if isinstance(cmd, Group):
				for subcmd in cmd.commands:
					key = f'subcmd:{cmd.name}.{subcmd.name}'
					self.id_to_topic[key] = subcmd
					self.id_to_topic[f'/{cmd.name} {subcmd.name}'] = subcmd
					text = cmd.name
					text += f' {subcmd.name}'
					if subcmd.description:
						text += f' {subcmd.description}'
					if subcmd.extras.get('long_description', None):
						text += f' {subcmd.extras["long_description"]}'
					self.topics.append({ 'id': key, 'text': process_text(text), 'topic': subcmd })
		for cog_qname, cog in self.bot.cogs.items():
			if not isinstance(cog, BaseCog):
				continue
			key = f'cog:{cog_qname}'
			self.id_to_topic[key] = cog
			text = cog.qualified_name
			if cog.short_description:
				text += f' {cog.short_description}'
			if cog.long_description:
				text += f' {cog.long_description}'
			self.topics.append({ 'id': key, 'text': process_text(text), 'topic': cog })

	def topic_for_help_symbol(self, symbol: str) -> HelpTopic | None:
		self.__create_help_index()
		return self.id_to_topic.get(symbol, None)

	def all_commands(self) -> list[Command | Group]:
		# PyCharm not interpreting conditional return type correctly.
		# noinspection PyTypeChecker
		cmds: list[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: Permissions | None) -> list[Command | Group]:
		return [
			cmd
			for cmd in self.all_commands()
			if can_use_command(cmd, permissions)
		]

	def all_accessible_subcommands(self, permissions: Permissions | None) -> 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: Permissions | None) -> list[BaseCog]:
		return [
			cog
			for cog in self.basecogs
			if can_use_cog(cog, permissions)
		]

	def all_accessible_topics(self, permissions: Permissions | None, *,
							  include_cogs: bool = True,
							  include_commands: bool = True,
							  include_subcommands: bool = True) -> list[HelpTopic]:
		topics = []
		if include_cogs:
			topics += self.all_accessible_cogs(permissions)
		if include_commands:
			topics += self.all_accessible_commands(permissions)
		if include_subcommands:
			topics += self.all_accessible_subcommands(permissions)
		return topics

	def topics_for_keywords(self, search: str, permissions: Permissions | None) -> list[HelpTopic]:
		start_time = time.perf_counter()
		self.__create_help_index()

		# Break into words (or word fragments)
		words: list[str] = [
			word
			for word in re.split(r"[^a-z']+", search.lower())
		]

		# Find matches
		def topic_matches(meta: HelpMeta) -> bool:
			for word in words:
				if word not in meta['text']:
					return False
			return True
		matching_topics: list[HelpTopic] = [ topic['topic'] for topic in self.topics if topic_matches(topic) ]

		# Filter by accessibility
		accessible_topics = [
			topic
			for topic in matching_topics
			if ((isinstance(topic, (Command, Group))) and can_use_command(topic, permissions)) or \
			   (isinstance(topic, BaseCog) and can_use_cog(topic, permissions))
		]

		# Sort and return
		result = sorted(accessible_topics, key=lambda topic: (
			isinstance(topic, Command),
			isinstance(topic, BaseCog),
			topic.qualified_name if isinstance(topic, BaseCog) else topic.name
		))
		duration = time.perf_counter() - start_time
		if duration > 0.01:
			self.log(None, f'search "{search}" took {duration} seconds')
		return result

	@command(
		name='help',
		description='Shows help for using commands and module configuration.',
		extras={
			'long_description': '`/help` will show a list of top-level topics.\n'
								'\n'
								"`/help /<command_name>` will show help about a specific command or list a command's subcommands.\n"
								'\n'
								'`/help /<command_name> <subcommand_name>` will show help about a specific subcommand.\n'
								'\n'
								'`/help <module_name>` will show help about configuring a module.\n'
								'\n'
								'`/help <keywords>` will do a text search for topics.',
		}
	)
	@guild_only()
	@autocomplete(search=search_autocomplete)
	async def help_command(self, interaction: Interaction, search: str | None) -> None:
		"""
		Shows help for using commands and subcommands and configuring modules.

		Parameters
		----------
		interaction: Interaction
		search: Optional[str]
			search terms
		"""
		self.log(interaction.guild, f'{interaction.user.name} used /help {search}')
		if search is None:
			await self.__send_general_help(interaction)
			return
		topic = self.topic_for_help_symbol(search)
		if topic:
			await self.__send_topic_help(interaction, topic)
			return
		matches = self.topics_for_keywords(search, interaction.permissions)
		await self.__send_keyword_help(interaction, matches)

	async def __send_topic_help(self, interaction: Interaction, topic: HelpTopic) -> None:
		if isinstance(topic, Command):
			await self.__send_command_help(interaction, topic)
			return
		if isinstance(topic, Group):
			await self.__send_command_help(interaction, topic)
			return
		if isinstance(topic, BaseCog):
			await self.__send_cog_help(interaction, topic)
			return
		self.log(interaction.guild, f'No help for topic object {topic}')
		await interaction.response.send_message(
			f'{CONFIG["failure_emoji"]} Failed to get help info.',
			ephemeral=True,
			delete_after=10,
		)

	def get_command_list(self, permissions: Permissions | None = None) -> dict[str, Command | Group]:
		return { cmd.name: cmd for cmd in self.bot.tree.get_commands() if can_use_command(cmd, permissions) }

	def get_subcommand_list(self, cmd: Group, permissions: Permissions | None = None) -> dict[str, Command]:
		return {
			subcmd.name: subcmd
			for subcmd in cmd.commands
			if can_use_command(subcmd, permissions)
		} if can_use_command(cmd, permissions) else {}

	async def __send_general_help(self, interaction: Interaction) -> None:
		user_permissions: Permissions = interaction.permissions
		all_commands = sorted(self.get_command_list(user_permissions).items())
		all_cog_tuples: list[tuple[str, BaseCog]] = [
			cog_tuple
			for cog_tuple in sorted(self.basecog_map.items())
			if can_use_cog(cog_tuple[1], user_permissions) and \
			   (len(cog_tuple[1].settings) > 0)
		]

		text = '## :information_source: Help'
		if len(all_commands) + len(all_cog_tuples) == 0:
			text = 'Nothing available for your permissions!'

		if len(all_commands) > 0:
			text += '\n### Commands'
			text += '\nType `/help /commandname` for more information.'
			for cmd_name, cmd in sorted(self.get_command_list(user_permissions).items()):
				text += f'\n- `/{cmd_name}`: {cmd.description}'
				if isinstance(cmd, Group):
					subcommand_count = len(cmd.commands)
					text += f' ({subcommand_count} subcommands)'
			text += PAGE_BREAK

		if len(all_cog_tuples) > 0:
			text += '\n### Module Configuration'
			for cog_name, cog in all_cog_tuples:
				has_enabled = next((s for s in cog.settings if s.name == 'enabled'), None) is not None
				text += f'\n- **{cog_name}**: {cog.short_description}'
				if has_enabled:
					text += f'\n   - `/enable {cog.config_prefix}` or `/disable {cog.config_prefix}`'
				for setting in cog.settings:
					if setting.name == 'enabled':
						continue
					text += f'\n   - `/get` or `/set {cog.config_prefix}_{setting.name}`'
				text += PAGE_BREAK

		await self.__send_paged_help(interaction, text)

	async def __send_keyword_help(self, interaction: Interaction, matching_topics: list[HelpTopic] | None) -> None:
		matching_commands = [
			cmd
			for cmd in matching_topics or []
			if isinstance(cmd, (Command, Group))
		]
		matching_cogs = [
			cog
			for cog in matching_topics or []
			if isinstance(cog, BaseCog)
		]
		if len(matching_commands) + len(matching_cogs) == 0:
			await interaction.response.send_message(
				f'{CONFIG["failure_emoji"]} No available help topics found.',
				ephemeral=True,
				delete_after=10,
			)
			return
		if len(matching_topics) == 1:
			topic = matching_topics[0]
			await self.__send_topic_help(interaction, topic)
			return

		text = '## :information_source: Matching Help Topics'
		if len(matching_commands) > 0:
			text += '\n### Commands'
			for cmd in matching_commands:
				if cmd.parent:
					text += f'\n- `/{cmd.parent.name} {cmd.name}`'
				else:
					text += f'\n- `/{cmd.name}`'
		if len(matching_cogs) > 0:
			text += '\n### Modules'
			for cog in matching_cogs:
				text += f'\n- {cog.qualified_name}'

		await self.__send_paged_help(interaction, text)

	async def __send_command_help(self, interaction: Interaction, command_or_group: Command | Group, addendum: str | None = None) -> None:
		text = ''
		if addendum is not None:
			text += addendum + '\n\n'
		if command_or_group.parent:
			text += '## :information_source: Subcommand Help'
			text += f'\n`/{command_or_group.parent.name} {command_or_group.name}`'
		else:
			text += '## :information_source: Command Help'
			if isinstance(command_or_group, Group):
				text += f'\n`/{command_or_group.name} subcommand_name`'
			else:
				text += f'\n`/{command_or_group.name}`'
		if isinstance(command_or_group, Command):
			optional_nesting = 0
			for param in command_or_group.parameters:
				text += '  '
				if not param.required:
					text += '['
					optional_nesting += 1
				escaped_param_name = param.name.replace('_', '\\_')
				text += f'_{escaped_param_name}_'
			if optional_nesting > 0:
				text += ']' * optional_nesting
		text += f'\n\n{command_or_group.description}'
		if command_or_group.extras.get('long_description'):
			text += f'\n\n{command_or_group.extras["long_description"]}'
		if isinstance(command_or_group, Group):
			subcmds: dict[str, Command] = self.get_subcommand_list(command_or_group, permissions=interaction.permissions)
			if len(subcmds) > 0:
				text += '\n### Subcommands:'
				for subcmd_name, subcmd in sorted(subcmds.items()):
					text += f'\n- `{subcmd_name}`: {subcmd.description}'
				text += f'\n-# To use a subcommand, type it after the command. e.g. `/{command_or_group.name} subcommand_name`'
				text += f'\n-# Get help on a subcommand by typing `/help /{command_or_group.name} subcommand_name`'
		else:
			params = command_or_group.parameters
			if len(params) > 0:
				text += '\n### Parameters:'
				for param in params:
					text += f'\n- `{param.name}`: {param.description}'
					if not param.required:
						text += ' (optional)'

		await self.__send_paged_help(interaction, text)

	async def __send_cog_help(self, interaction: Interaction, cog: BaseCog) -> None:
		text = '## :information_source: Module Help'
		text += f'\n**{cog.qualified_name}** module'
		if cog.short_description is not None:
			text += f'\n\n{cog.short_description}'
		if cog.long_description is not None:
			text += f'\n\n{cog.long_description}'

		cmds = [
			cmd
			for cmd in sorted(cog.get_app_commands(), key=lambda c: c.name)
			if can_use_command(cmd, interaction.permissions)
		]
		if len(cmds) > 0:
			text += '\n### Commands:'
			for cmd in cmds:
				text += f'\n- `/{cmd.name}` - {cmd.description}'
				if isinstance(cmd, Group):
					subcmds = [ subcmd for subcmd in cmd.commands if can_use_command(subcmd, interaction.permissions) ]
					if len(subcmds) > 0:
						text += f' ({len(subcmds)} subcommands)'

		settings = cog.settings
		if len(settings) > 0:
			text += '\n### Configuration'
			enabled_setting = next((s for s in settings if s.name == 'enabled'), None)
			if enabled_setting is not None:
				text += f'\n- `/enable {cog.config_prefix}` or `/disable {cog.config_prefix}`'
			for setting in sorted(settings, key=lambda s: s.name):
				if setting.name == 'enabled':
					continue
				text += f'\n- `/get` or `/set {cog.config_prefix}_{setting.name}` - {setting.brief}'

		await self.__send_paged_help(interaction, text)

	async def __send_paged_help(self, interaction: Interaction, text: str) -> None:
		pages = paginate(text)
		await update_paged_content(interaction, None, 0, pages, delete_after=60)

# Exclusions from keyword indexing
trivial_words = {
	'a', 'an', 'and', 'are', "aren't", 'as', 'by', 'can', 'for', 'have', 'if', 'in',
	'is', 'it', 'its', "it's", 'not', 'of', 'on', 'or', 'than', 'that', 'the', 'then',
	'there', 'them', 'they', "they're", 'this', 'to', 'when', 'with',
}

def can_use_command(cmd: Group | Command, user_permissions: Permissions | None) -> bool:
	if user_permissions is None:
		return False
	if cmd.parent and not can_use_command(cmd.parent, user_permissions):
		return False
	return cmd.default_permissions is None or cmd.default_permissions.is_subset(user_permissions)

def can_use_cog(cog: BaseCog, user_permissions: Permissions | None) -> bool:
	# "Using" a cog for now means configuring it, and only mods can configure cogs.
	return user_permissions is not None and MOD_PERMISSIONS.is_subset(user_permissions)