拓扑图
Topology graph — 将所选 Release 的已编译 IR 渲染为交互式图:边界和子系统容器(在另一个边界或子系统内声明的边界或子系统绘制在其内部)、按来源设置样式的边、平移和缩放、单击节点将其选中并双击打开其源文件,以及单击边以选中它所绘制的连接。

每个容器的标题除了分组之外还标明其种类,因此即使在两者都未声明的工作区中——否则两者会带有相同的名称——外层方框和内层方框也能区分开来。没有人声明的分组,即编译器为 Release 或 Aggregate 在顶层列出的组件创建的分组,其标题表明未声明任何分组,其方框的绘制方式也与已声明的分组不同——使用点状的中性边框——因此不会被读作具有该名称的分组;你声明的分组无论叫什么名字都保留其名称,包括 default。
每条边在其指向的一端带有箭头:边从消费方组件指向其目标,箭头以该边自身的颜色和虚线样式绘制。节点方框的大小通过测量其绘制的文本来确定,包括节点名称及其下方的组件,因此无论组件名称有多长,两者都不会超出边框。
左下角的图例按声明分组的文档为每个分组命名——边界按 Release,子系统按 Aggregate——并在绘图中存在时,说明容纳不属于任何分组的节点的方框及其内容;它说明边的哪一端是其目标;它还说明节点前缘的色条以及绘图赋予色条的每种颜色,并在旁边按标签的原样写出该颜色所代表的 component.aggrega.ai/type 值,如果存在没有该标签的节点,则另有一行表示它们。它也说明这些颜色不代表什么:颜色是在每次绘制图时分配的,因此它们在一张图内按类型对节点分组,而另一张图中的相同颜色并不代表相同类型。无论你对绘图做什么操作,图例都保持在原位,因此每当绘图适配面板时——首次绘制时,以及每次请求图时——它都会适配到面板中图例上方的部分:在面板的整个宽度和图例上方剩余的高度之内,水平居中,因此无论图例有多少行,都不会遮挡绘图的任何部分。如果面板太矮,图例上方没有任何空间,则绘图适配整个面板。
选中一个节点会打开一个面板,列出附加到该节点的内容:每个附加项的 Feature 及其解析后的版本、它填充的插槽或它不填充任何已声明插槽这一事实、在已编译图指明时实现它的 FeatureRecipe(含名称和版本)、它的来源、它声明的标签,以及其作者编写的值。写在组件某个连接上的附加项——在 Aggregate 或 Release 中某个 uses 条目的 features: 下——不在该列表中:它按照已编译图的记录绘制在其所属的连接上,并且当节点的连接带有附加项时,节点面板会予以说明。
单击一条边会选中它所绘制的连接并打开该连接的面板,面板标题为消费方组件及其目标,并注明 socket 和别名,该连接的附加项按与节点相同的方式显示——每个附加项的 Feature 及其解析后的版本、它填充的插槽、在已编译图指明时实现它的 FeatureRecipe,以及它的值——或者显示一句说明没有任何附加项的话。选中节点会清除已选中的连接,反之亦然;Escape 或面板的关闭按钮可清除任一选择,重绘时只要重建后的图仍然绘制该节点,或仍然绘制从同一组件经同一 socket、以同一别名发出的连接,选择就会保留。
在节点的附加项下方,面板在 May attach 下列出这样的 Features:在面板所示 Release 的图中,该节点的标签满足其声明的适用范围——即该 Release 读取的工作区文档所声明的 Features(只有其他 Releases 读取的 catalog 目录中的除外),以及该 Release 构建所依据的 catalog 目录中包含的 Features——每个都标明其种类,以及声明它的工作区文件或解析它所用的已配置 catalog。该列表是这些 Features 声明自己适用的对象,而不是附加其中一个就能构建成功的判定——当列表为空时,它表示没有任何 Feature 的声明适用范围与这些标签匹配,这比“没有任何东西可以附加”的说法范围更窄。语言服务器无法应答的请求会在列表的位置说明这一点,而不是留空。在通向工作区之外的链接后面声明的 Feature——指向工作区外部目录的链接,或命名得像 YAML 文件、却指向工作区外部文件的链接——不会被提供,因为语言服务器不会通过此类链接读取任何实体,尽管编辑器的文件树会显示该 Feature。当工作区包含此类链接时,列表下方(或代替空列表的那句话下方)会有一行予以说明:Features reached through this link are not offered, because it leads outside the Aggrega workspace:(通过此链接访问的 Features 不会被提供,因为它通向 Aggrega 工作区之外:)后跟该链接相对于工作区的路径——如有多个,则为 Features reached through these links are not offered, because each leads outside the Aggrega workspace:(通过这些链接访问的 Features 不会被提供,因为每个链接都通向 Aggrega 工作区之外:),指向目录的链接排在前面。它按面板所示 Release 的视角列出语言服务器报告的链接,就像 Catalog 面板按所选 Release 的视角列出一样。当无法读取该报告时,列表绘制时不带该行,原因写入 Aggrega 输出通道;无法生成的列表不带该行。

每一行都带有一个用于提交该行的 Attach 控件:系统会询问编译器哪个文档声明了所选组件,以及此类附加项应放在该文档中的什么位置,然后通过编辑器将条目写入该位置——因此它会进入撤销历史,落在你正在查看的缓冲区上,而不是最后保存到磁盘的版本上,并且其周围的注释和格式保持你编写时的样子。不会代你保存任何内容;该编辑与其他任何更改一样,编译器会像在任何编辑之后那样重新验证它。图会在你保存时重绘,因为拓扑是根据磁盘上文档的当前状态编译的,仍停留在缓冲区中的附加项尚不属于其中。附加项以 Feature 命名,附加一个已以该名称附加的 Feature 会被拒绝,而不会写入两次。在子系统内声明的组件与在顶层声明的组件通过同样的操作进行附加,两者都能工作的原因相同:图通过组件在已编译拓扑中的位置来识别组件,而该位置并不说明组件作者编写了哪些键,因此扩展会询问而不是自行重建——答复指明文档以及其中块的路径,两者都按收到时的原样带入编辑。当没有这样的位置可指明时——图中不带有的 id、图中没有为其记录文档的节点,或者其自身的块无法在其编写所在文档中指明的组件——面板显示的是编译器给出的原因,而不是本扩展自己的措辞。
所选连接的面板有自己的 May attach 部分:该连接的 socket 声明的槽位,按组件声明它们的顺序排列,每个槽位都注明是否必需、填充它的内容是否处理敏感材料、它允许的交付方式、它的选择器和描述;每个槽位下方列出语言服务器答复可以在该连接上填充它的 Features——即其声明的适用范围被消费方组件的标签满足、且其自身标签满足该槽位选择器的那些。在没有任何槽位可以填充的地方,面板以语言服务器的措辞说明原因——连接是由某个 Feature 绘制的、该 socket 不是组件声明的 socket,或者该 socket 没有声明槽位——并且不提供任何可附加的内容。在某个槽位下按 Attach,会以槽位的名称写入该 Feature,即一个 <slot>: 条目,其 type: 指明该 Feature,写在绘制该连接的文档中该连接的条目上:对于 Release 绘制的连接是 Release,否则是 Aggregate。通过 Aggrega: Attach a Feature to the connection at the cursor 从文档中的条目选择的连接,则改为写入该文档——对于 Aggregate 绘制的连接在 Release 中的自身条目,即写入 Release——此时面板在 May attach 下的那一行会说明,该 Feature 将写在运行该命令的文档中该连接的条目上。系统会询问编译器该条目在该文档中的位置,文档中尚未包含的路径部分会一并写入,编辑会像节点的编辑一样进入编辑器,处于未保存状态。图中已显示在该连接上被填充的槽位,会在询问任何内容之前被拒绝,而编译器给出的拒绝会以其原话显示。
编译器报告为敏感的值,语言服务器会在其发送的图中隐去,扩展在把图交给视图之前还会再次隐去,因此视图中根本没有这个值可供显示——面板会指明该字段并说明隐去的原因;如果某个附加项的敏感性标记采用面板无法识别的形式,面板会隐去所有值,而不是去猜测。绘制在连接上的附加项与绘制在节点上的附加项按完全相同的规则、在同一设置下被隐去。aggrega.graph.showSensitiveValues 可为需要回读自己所写内容的作者关闭隐去:只有在它开启时,图请求才会向语言服务器索取这些值,设置页面会说明这样会显示什么。
节点按 Release 各波次的启动顺序排布,因此声明了 syncWave: 的 boundary 会出现在等待它的 boundary 之前。将指针悬停在节点上,会显示其组件及解析后的版本、标签、声明的波次,以及目录实体自身的元数据——许可证、仓库、主页、关键词和维护者——只显示该实体实际声明的字段。
打开的图会在工作区中任何编写的文档保存时重新渲染,因此无需重新打开即可跟随你的编辑;它在保存时而不是每次按键时重绘,因为拓扑是从磁盘上的内容编译而来的。当所选 Release 的锁文件被写入时——通过 Aggrega: Pull、启用 Auto pull 的构建,或在终端中运行 aggrega pull——它也会重绘,因为图是固定在该锁文件上的;当语言服务器重新可以应答时它同样会重绘,因此在重启期间保持打开的图会自行恢复。
不是你请求的重绘会让视图保持在你放置的位置:无论重建后的拓扑是否不同,你原有的平移和缩放都会保留,因此重建后的布局放在原位置的节点仍位于面板的同一部分,而被放到别处的节点——新增的组件可能会挤动周围的组件——会在你保留的视图内移动,而不会带着视图一起移动。这也包括图位于另一个标签页之后时发生的重绘,你回来时它仍是离开时的样子。
Aggrega: Show topology graph 会重新将绘图适配到面板,这是放大某一部分之后回到整体形状的方式。大型拓扑会整体适配而不会被裁剪,因此大型拓扑显示得很小:你可以看到它的整体结构,再通过放大查看名称。在一个框中容纳的两个或更多分组排布后高大于宽的地方,它们会并排绘制,而不是堆叠成一列,因此大型拓扑会利用面板的宽度,首次适配时绘制得比单列所允许的更大。
编译器拒绝的重建会保留你原有的绘图,而不是将其清空——拓扑仍值得阅读,而且仍是你正在工作的地方——并将其变暗,这样不再是最新的绘图就不会被误认为是最新的;其上方的通知会给出编译器自己的原因。一旦构建出新的绘图,绘图就会恢复完整显示。布局在视图中计算;编译器只提供拓扑,从不提供坐标。