Comments queries
===============

Helper that turns a comments table into a threaded list query for one
``(resource, row)``.  Returns a SQLAlchemy :class:`~sqlalchemy.Select`
and registers nothing on metadata — run it directly against a
connection and feed the rows to
:func:`fsh_lib.comments.build_comment_thread` to nest them.

Pair with :class:`fsh_lib.comments.CommentMixin` for the storage
columns (``resource_type``, ``resource_id``, ``parent_comment_id``,
``body``, ``author_id``).

What is exposed
---------------

One function, re-exported at :mod:`codegen_database.ext.comments`:

- :func:`~codegen_database.ext.comments.construct_comments_thread_query`

How to use
----------

.. code-block:: python

   from sqlalchemy import create_engine
   from codegen_database.ext.comments import construct_comments_thread_query
   from fsh_lib.comments import build_comment_thread

   engine = create_engine(DATABASE_URL)
   with engine.connect() as conn:
       rows = conn.execute(
           construct_comments_thread_query(
               Comment.__table__,
               resource_type="category",
               resource_id=str(category.id),
           )
       ).scalars().all()
       tree = build_comment_thread(rows)

The query filters to the one ``(resource_type, resource_id)`` and
orders top-level comments (``parent_comment_id IS NULL``) ahead of
replies, each group by ``created_at``.
:func:`fsh_lib.comments.build_comment_thread` nests the flat stream
from an id-keyed dict, so the only ordering that matters for the tree
is the order of a parent's replies — which the sort keeps
chronological.  No recursive CTE for the common one-level-deep thread
shape; add one if arbitrary-depth nesting is needed.

Full signature lives in the :doc:`api` reference.