Prevent erroneous symbols from always raising stale warnings

Some doc symbols are improperly generated and never exist on the doc page
the inventory file defines them in, causing the stale warning to get raised
every time the page is parsed (at a maximum every week because of the redis
expire).

This can be prevented by keeping a counter in redis for the items which were
stale, every time the item is warned for the counter is incremented and set to
expire in 3 weeks.
Then a warning is only raised when the counter is below 3, resulting in the
unpreventable warning only being raised twice until it is fixed by the
maintainers after it expires in 3 weeks after the last increment.

2 files changed, 29 insertions, 7 deletions

diff --git a/bot/exts/info/doc/_batch_parser.py b/bot/exts/info/doc/_batch_parser.py
index 369bb462c..cadf1e121 100644
--- a/bot/exts/info/doc/_batch_parser.py
+++ b/bot/exts/info/doc/_batch_parser.py
@@ -16,6 +16,7 @@ from bot.constants import Channels
 from bot.utils import scheduling
 from . import _cog, doc_cache
 from ._parsing import get_symbol_markdown
+from ._redis_cache import StaleItemCounter
 
 log = logging.getLogger(__name__)
 
@@ -23,6 +24,8 @@ log = logging.getLogger(__name__)
 class StaleInventoryNotifier:
     """Handle sending notifications about stale inventories through `DocItem`s to dev log."""
 
+    symbol_counter = StaleItemCounter()
+
     def __init__(self):
         self._init_task = bot.instance.loop.create_task(
             self._init_channel(),
@@ -38,13 +41,16 @@ class StaleInventoryNotifier:
     async def send_warning(self, doc_item: _cog.DocItem) -> None:
         """Send a warning to dev log if one wasn't already sent for `item`'s url."""
         if doc_item.url not in self._warned_urls:
-            self._warned_urls.add(doc_item.url)
-            await self._init_task
-            embed = discord.Embed(
-                description=f"Doc item `{doc_item.symbol_id=}` present in loaded documentation inventories "
-                            f"not found on [site]({doc_item.url}), inventories may need to be refreshed."
-            )
-            await self._dev_log.send(embed=embed)
+            # Only warn if the item got less than 3 warnings
+            # or if it has been more than 3 weeks since the last warning
+            if await self.symbol_counter.increment_for(doc_item) < 3:
+                self._warned_urls.add(doc_item.url)
+                await self._init_task
+                embed = discord.Embed(
+                    description=f"Doc item `{doc_item.symbol_id=}` present in loaded documentation inventories "
+                                f"not found on [site]({doc_item.url}), inventories may need to be refreshed."
+                )
+                await self._dev_log.send(embed=embed)
 
 
 class QueueItem(NamedTuple):
diff --git a/bot/exts/info/doc/_redis_cache.py b/bot/exts/info/doc/_redis_cache.py
index 0c635bf6e..3fa3460ca 100644
--- a/bot/exts/info/doc/_redis_cache.py
+++ b/bot/exts/info/doc/_redis_cache.py
@@ -58,6 +58,22 @@ class DocRedisCache(RedisObject):
             return False
 
 
+class StaleItemCounter(RedisObject):
+    """Manage increment counters for stale `DocItem`s."""
+
+    @namespace_lock
+    async def increment_for(self, item: DocItem) -> int:
+        """
+        Increment the counter for `item` by 1, set it to expire in 3 weeks and return the new value.
+
+        If the counter didn't exist, initialize it with 1.
+        """
+        key = f"{self.namespace}:{item_key(item)}:{item.symbol_id}"
+        with await self._get_pool_connection() as connection:
+            await connection.expire(key, WEEK_SECONDS * 3)
+            return int(await connection.incr(key))
+
+
 def item_key(item: DocItem) -> str:
     """Get the redis redis key string from `item`."""
     return f"{item.package}:{item.relative_url_path.removesuffix('.html')}"