refactor(cli): rename named-query to named-expression, add procedure-graph

Rename the CLI subcommand and underlying module from "named-query" to "named-expression" to reflect broader expression evaluation capability beyond just query execution.

Add new "named-procedure-graph" subcommand for visualizing procedure relationship graphs.

Update named_connection to pass output provider.

Author: vistart

docs/examples/chapter_12_named_procedure/diagram_demo.py

@@ -7,7 +7,7 @@
 2. 执行过程后生成实例图
 3. 将图嵌入文档
 """
-from rhosocial.activerecord.backend.named_query import (
+from rhosocial.activerecord.backend.named_expression import (
     Procedure,
     ProcedureContext,
     ProcedureRunner,

docs/examples/chapter_12_named_procedure/order_workflow.py

@@ -9,7 +9,7 @@
 - 静态图和实例图生成
 - PostgreSQL 特有的 NOWAIT, RETURNING 等特性
 """
-from rhosocial.activerecord.backend.named_query import (
+from rhosocial.activerecord.backend.named_expression import (
     Procedure,
     ProcedureContext,
     ParallelStep,
@@ -192,7 +192,7 @@ async def run(self, ctx: ProcedureContext) -> None:
 
 
 if __name__ == "__main__":
-    from rhosocial.activerecord.backend.named_query import ProcedureDiagram
+    from rhosocial.activerecord.backend.named_expression import ProcedureDiagram
 
     print("=== 静态流程图 ===")
     print(OrderProcessingProcedure.static_diagram("flowchart"))

src/rhosocial/activerecord/backend/impl/postgres/cli/__init__.py

@@ -5,7 +5,7 @@
 
 COMMAND_NAMES = [
     'info', 'query', 'introspect', 'status',
-    'named-query', 'named-procedure', 'named-connection',
+    'named-expression', 'named-procedure', 'named-procedure-graph', 'named-connection',
 ]
 
 
@@ -15,15 +15,17 @@ def register_commands(subparsers):
     from .query import create_parser as query_parser
     from .introspect import create_parser as introspect_parser
     from .status import create_parser as status_parser
-    from .named_query import create_parser as nq_parser
+    from .named_expression import create_parser as nq_parser
     from .named_procedure import create_parser as np_parser
+    from .named_procedure_graph import create_parser as npg_parser
     from .named_connection import create_parser as nc_parser
     info_parser(subparsers)
     query_parser(subparsers)
     introspect_parser(subparsers)
     status_parser(subparsers)
     nq_parser(subparsers)
     np_parser(subparsers)
+    npg_parser(subparsers)
     nc_parser(subparsers)
 
 

src/rhosocial/activerecord/backend/impl/postgres/cli/connection.py

@@ -70,7 +70,7 @@ def add_version_arg(parser):
 def create_connection_parent_parser():
     """Create a parent parser with connection and output arguments.
 
-    Used by shared CLI helpers (named-query, named-procedure) that
+    Used by shared CLI helpers (named-expression, named-procedure) that
     require a parent_parser containing connection parameters.
     """
     import argparse

src/rhosocial/activerecord/backend/impl/postgres/cli/named_connection.py

@@ -26,7 +26,12 @@ def handle(args):
     """Handle the named-connection subcommand."""
     from rhosocial.activerecord.backend.named_connection.cli import handle_named_connection as handle_nc
 
+    from .output import create_provider
+    output_fmt = getattr(args, "output", "table")
+    ascii_borders = getattr(args, "rich_ascii", False)
+    provider = create_provider(output_fmt, ascii_borders=ascii_borders)
+
     def named_connection_resolver_factory(name):
         return NamedConnectionResolver(name)
 
-    handle_nc(args, named_connection_resolver_factory)
+    handle_nc(args, named_connection_resolver_factory, provider)

…backend/impl/postgres/cli/named_query.py …nd/impl/postgres/cli/named_expression.pysrc/rhosocial/activerecord/backend/impl/postgres/cli/named_query.py renamed to src/rhosocial/activerecord/backend/impl/postgres/cli/named_expression.py src/rhosocial/activerecord/backend/impl/postgres/cli/named_query.py renamed to src/rhosocial/activerecord/backend/impl/postgres/cli/named_expression.py

@@ -1,7 +1,7 @@
-# src/rhosocial/activerecord/backend/impl/postgres/cli/named_query.py
-"""named-query subcommand - Adapter for shared CLI helper.
+# src/rhosocial/activerecord/backend/impl/postgres/cli/named_expression.py
+"""named-expression subcommand - Adapter for shared CLI helper.
 
-named-query requires connection arguments and output arguments.
+named-expression requires connection arguments and output arguments.
 """
 
 from rhosocial.activerecord.backend.impl.postgres import PostgresBackend, AsyncPostgresBackend
@@ -12,44 +12,38 @@
 
 
 def create_parser(subparsers):
-    """Create the named-query subcommand parser.
+    """Create the named-expression subcommand parser.
 
-    Reuses the shared create_named_query_parser, passing a parent parser
+    Reuses the shared create_named_expression_parser, passing a parent parser
     containing only connection and output arguments.
     """
-    from rhosocial.activerecord.backend.named_query.cli import create_named_query_parser
+    from rhosocial.activerecord.backend.named_expression.cli import create_named_expression_parser
     local_parent = create_connection_parent_parser()
+    parser = create_named_expression_parser(subparsers, local_parent)
+    parser.add_argument(
+        "--dialect-version",
+        default=None,
+        help="PostgreSQL dialect version for capability probing (e.g., 15.0.0, 14.0.0).",
+    )
+    return parser
 
-    nq_epilog = """Examples:
-  # Execute named query with connection parameters
-  %(prog)s myapp.queries.orders.high_value_pending --host localhost --database mydb --user postgres --password secret
-
-  # Override parameters
-  %(prog)s myapp.queries.orders.high_value_pending --host localhost --database mydb \\
-      --param threshold=5000 --param days=7
-
-  # Show signature without executing
-  %(prog)s myapp.queries.orders.high_value_pending --describe
-
-  # Preview SQL without executing
-  %(prog)s myapp.queries.orders.orders_by_status \\
-      --database mydb --param status=pending --dry-run
 
-  # List all named queries in a module
-  %(prog)s myapp.queries.orders --list
+def handle(args):
+    """Handle the named-expression subcommand."""
+    from rhosocial.activerecord.backend.named_expression.cli import handle_named_expression as handle_ne
 
-  # Using environment variables
-  export POSTGRES_HOST=localhost POSTGRES_DATABASE=mydb POSTGRES_USER=postgres POSTGRES_PASSWORD=secret
-  %(prog)s myapp.queries.orders --list
-"""
-    return create_named_query_parser(subparsers, local_parent, epilog=nq_epilog)
+    provider = create_provider(args.output, ascii_borders=args.rich_ascii)
 
+    from rhosocial.activerecord.backend.impl.postgres.dialect import PostgresDialect
 
-def handle(args):
-    """Handle the named-query subcommand."""
-    from rhosocial.activerecord.backend.named_query.cli import handle_named_query as handle_nq
+    def _get_requested_version():
+        ver = getattr(args, "dialect_version", None)
+        if ver:
+            return tuple(int(p) for p in ver.split("."))
+        return None
 
-    provider = create_provider(args.output, ascii_borders=args.rich_ascii)
+    def create_dialect():
+        return PostgresDialect(version=_get_requested_version())
 
     backend = None
 
@@ -59,6 +53,9 @@ def backend_factory():
         backend = PostgresBackend(connection_config=config)
         backend.connect()
         backend.introspect_and_adapt()
+        req_ver = _get_requested_version()
+        if req_ver:
+            backend._dialect.version = req_ver
         return backend
 
     def get_dialect(b):
@@ -91,7 +88,7 @@ async def disconnect_async():
             if async_backend and async_backend._connection:
                 await async_backend.disconnect()
 
-        handle_nq(
+        handle_ne(
             args,
             provider,
             backend_factory=backend_factory,
@@ -102,14 +99,16 @@ async def disconnect_async():
             get_dialect_async=get_dialect_async,
             execute_query_async=execute_query_async,
             disconnect_async=disconnect_async,
+            create_dialect=create_dialect,
         )
         return
 
-    handle_nq(
+    handle_ne(
         args,
         provider,
         backend_factory=backend_factory,
         get_dialect=get_dialect,
         execute_query=execute_query,
         disconnect=disconnect,
+        create_dialect=create_dialect,
     )

src/rhosocial/activerecord/backend/impl/postgres/cli/named_procedure.py

@@ -16,7 +16,7 @@ def create_parser(subparsers):
     Reuses the shared create_named_procedure_parser, passing a parent parser
     containing only connection and output arguments.
     """
-    from rhosocial.activerecord.backend.named_query.cli_procedure import create_named_procedure_parser
+    from rhosocial.activerecord.backend.named_expression.cli_procedure import create_named_procedure_parser
     local_parent = create_connection_parent_parser()
 
     np_epilog = """Examples:
@@ -43,7 +43,7 @@ def create_parser(subparsers):
 
 def handle(args):
     """Handle the named-procedure subcommand."""
-    from rhosocial.activerecord.backend.named_query.cli_procedure import handle_named_procedure as handle_np
+    from rhosocial.activerecord.backend.named_expression.cli_procedure import handle_named_procedure as handle_np
 
     provider = create_provider(args.output, ascii_borders=args.rich_ascii)
 

src/rhosocial/activerecord/backend/impl/postgres/cli/named_procedure_graph.py

@@ -0,0 +1,92 @@
+# src/rhosocial/activerecord/backend/impl/postgres/cli/named_procedure_graph.py
+"""named-procedure-graph subcommand - Adapter for shared CLI helper.
+
+named-procedure-graph requires connection arguments, output arguments, and --rich-ascii.
+
+Usage:
+    $ python -m rhosocial.activerecord.backend.impl.postgres named-procedure-graph run \
+        myapp.npg.monthly_report \
+        --params '{"month": "2026-04"}'
+
+    $ python -m rhosocial.activerecord.backend.impl.postgres named-procedure-graph list \
+        myapp.npg
+
+    $ python -m rhosocial.activerecord.backend.impl.postgres named-procedure-graph validate \
+        myapp.npg.monthly_report
+"""
+
+from rhosocial.activerecord.backend.impl.postgres import PostgresBackend
+
+from .connection import create_connection_parent_parser, resolve_connection_config_from_args
+from .output import create_provider
+
+
+def create_parser(subparsers):
+    """Create the named-procedure-graph subcommand parser.
+
+    Reuses the shared create_named_procedure_graph_parser, passing a parent parser
+    containing only connection and output arguments.
+    """
+    from rhosocial.activerecord.backend.named_expression.cli_procedure_graph import (
+        create_named_procedure_graph_parser,
+    )
+
+    local_parent = create_connection_parent_parser()
+    return create_named_procedure_graph_parser(subparsers, local_parent)
+
+
+def handle(args):
+    """Handle the named-procedure-graph subcommand."""
+    from rhosocial.activerecord.backend.named_expression.cli_procedure_graph import (
+        handle_named_procedure_graph as handle_npg,
+    )
+
+    provider = create_provider(args.output, ascii_borders=args.rich_ascii)
+
+    backend = None
+
+    def backend_factory():
+        nonlocal backend
+        config = resolve_connection_config_from_args(args)
+        backend = PostgresBackend(connection_config=config)
+        backend.connect()
+        backend.introspect_and_adapt()
+        return backend
+
+    def disconnect():
+        if backend and backend._connection:
+            backend.disconnect()
+
+    is_async = getattr(args, "is_async", False)
+
+    if is_async:
+        async_backend = None
+
+        def backend_async_factory():
+            nonlocal async_backend
+            from rhosocial.activerecord.backend.impl.postgres import AsyncPostgresBackend
+
+            config = resolve_connection_config_from_args(args)
+            async_backend = AsyncPostgresBackend(connection_config=config)
+            return async_backend
+
+        async def disconnect_async():
+            if async_backend and async_backend._connection:
+                await async_backend.disconnect()
+
+        handle_npg(
+            args,
+            provider,
+            backend_factory=backend_factory,
+            disconnect=disconnect,
+            backend_async_factory=backend_async_factory,
+            disconnect_async=disconnect_async,
+        )
+        return
+
+    handle_npg(
+        args,
+        provider,
+        backend_factory=backend_factory,
+        disconnect=disconnect,
+    )