schema: add first parent descendants

cylc/flow/data_messages.proto

@@ -245,6 +245,7 @@ message PbFamily {
     repeated string child_families = 9;
     optional string first_parent = 10;
     optional PbRuntime runtime = 11;
+    repeated string descendants = 12;
 }
 
 message PbFamilyProxy {

cylc/flow/data_messages_pb2.pyi

@@ -377,7 +377,7 @@ class PbTaskProxy(_message.Message):
     def __init__(self, stamp: _Optional[str] = ..., id: _Optional[str] = ..., task: _Optional[str] = ..., state: _Optional[str] = ..., cycle_point: _Optional[str] = ..., depth: _Optional[int] = ..., job_submits: _Optional[int] = ..., outputs: _Optional[_Mapping[str, PbOutput]] = ..., namespace: _Optional[_Iterable[str]] = ..., prerequisites: _Optional[_Iterable[_Union[PbPrerequisite, _Mapping]]] = ..., jobs: _Optional[_Iterable[str]] = ..., first_parent: _Optional[str] = ..., name: _Optional[str] = ..., is_held: bool = ..., edges: _Optional[_Iterable[str]] = ..., ancestors: _Optional[_Iterable[str]] = ..., flow_nums: _Optional[str] = ..., external_triggers: _Optional[_Mapping[str, PbTrigger]] = ..., xtriggers: _Optional[_Mapping[str, PbTrigger]] = ..., is_queued: bool = ..., is_runahead: bool = ..., flow_wait: bool = ..., runtime: _Optional[_Union[PbRuntime, _Mapping]] = ..., graph_depth: _Optional[int] = ...) -> None: ...
 
 class PbFamily(_message.Message):
-    __slots__ = ("stamp", "id", "name", "meta", "depth", "proxies", "parents", "child_tasks", "child_families", "first_parent", "runtime")
+    __slots__ = ("stamp", "id", "name", "meta", "depth", "proxies", "parents", "child_tasks", "child_families", "first_parent", "runtime", "descendants")
     STAMP_FIELD_NUMBER: _ClassVar[int]
     ID_FIELD_NUMBER: _ClassVar[int]
     NAME_FIELD_NUMBER: _ClassVar[int]
@@ -389,6 +389,7 @@ class PbFamily(_message.Message):
     CHILD_FAMILIES_FIELD_NUMBER: _ClassVar[int]
     FIRST_PARENT_FIELD_NUMBER: _ClassVar[int]
     RUNTIME_FIELD_NUMBER: _ClassVar[int]
+    DESCENDANTS_FIELD_NUMBER: _ClassVar[int]
     stamp: str
     id: str
     name: str
@@ -400,7 +401,8 @@ class PbFamily(_message.Message):
     child_families: _containers.RepeatedScalarFieldContainer[str]
     first_parent: str
     runtime: PbRuntime
-    def __init__(self, stamp: _Optional[str] = ..., id: _Optional[str] = ..., name: _Optional[str] = ..., meta: _Optional[_Union[PbMeta, _Mapping]] = ..., depth: _Optional[int] = ..., proxies: _Optional[_Iterable[str]] = ..., parents: _Optional[_Iterable[str]] = ..., child_tasks: _Optional[_Iterable[str]] = ..., child_families: _Optional[_Iterable[str]] = ..., first_parent: _Optional[str] = ..., runtime: _Optional[_Union[PbRuntime, _Mapping]] = ...) -> None: ...
+    descendants: _containers.RepeatedScalarFieldContainer[str]
+    def __init__(self, stamp: _Optional[str] = ..., id: _Optional[str] = ..., name: _Optional[str] = ..., meta: _Optional[_Union[PbMeta, _Mapping]] = ..., depth: _Optional[int] = ..., proxies: _Optional[_Iterable[str]] = ..., parents: _Optional[_Iterable[str]] = ..., child_tasks: _Optional[_Iterable[str]] = ..., child_families: _Optional[_Iterable[str]] = ..., first_parent: _Optional[str] = ..., runtime: _Optional[_Union[PbRuntime, _Mapping]] = ..., descendants: _Optional[_Iterable[str]] = ...) -> None: ...
 
 class PbFamilyProxy(_message.Message):
     __slots__ = ("stamp", "id", "cycle_point", "name", "family", "state", "depth", "first_parent", "child_tasks", "child_families", "is_held", "ancestors", "states", "state_totals", "is_held_total", "is_queued", "is_queued_total", "is_runahead", "is_runahead_total", "runtime", "graph_depth")

cylc/flow/data_store_mgr.py

@@ -642,6 +642,7 @@ def generate_definition_elements(self):
                     id=f_id,
                     name=name,
                     depth=len(ancestors[name]) - 1,
+                    descendants=list(descendants.get(name, [])),
                 )
                 famcfg = config.cfg['runtime'][name]
                 user_defined_meta = {}

cylc/flow/network/schema.py

@@ -1226,36 +1226,50 @@ class Meta:
     depth = Int()
     proxies = graphene.List(
         lambda: FamilyProxy,
-        description='Associated cycle point proxies.',
+        description='Associated family proxy instances.',
         args=PROXY_ARGS,
         strip_null=STRIP_NULL_DEFAULT,
         delta_store=DELTA_STORE_DEFAULT,
         delta_type=DELTA_TYPE_DEFAULT,
         resolver=get_nodes_by_ids)
     parents = graphene.List(
         lambda: Family,
-        description='Family definition parent.',
+        description='Families that this family directly inherits from.',
         args=DEF_ARGS,
         strip_null=STRIP_NULL_DEFAULT,
         delta_store=DELTA_STORE_DEFAULT,
         delta_type=DELTA_TYPE_DEFAULT,
         resolver=get_nodes_by_ids)
     child_tasks = graphene.List(
         Task,
-        description='Descendant definition tasks.',
+        description='Tasks that inherit from this family.',
         args=DEF_ARGS,
         strip_null=STRIP_NULL_DEFAULT,
         delta_store=DELTA_STORE_DEFAULT,
         delta_type=DELTA_TYPE_DEFAULT,
         resolver=get_nodes_by_ids)
     child_families = graphene.List(
         lambda: Family,
-        description='Descendant desc families.',
+        description='Families that inherit from this family.',
         args=DEF_ARGS,
         strip_null=STRIP_NULL_DEFAULT,
         delta_store=DELTA_STORE_DEFAULT,
         delta_type=DELTA_TYPE_DEFAULT,
         resolver=get_nodes_by_ids)
+    descendants = graphene.List(
+        String,
+        description=sstrip('''
+            Linearised first-parent descendants.
+
+            Inheritance in Cylc provides two functions:
+            * Allowing tasks to inherit common configurations.
+            * Defining a family/task hierarchy for visualisation purposes.
+              (the linearised first-parent hierarchy).
+
+            The visual hierarchy follows the first-parent of a family which
+            may differ from the full inheritance hierarchy.
+        '''),
+    )
     first_parent = Field(
         lambda: Family,
         description='Family first parent.',