分析
概述
clice analyze 读取持久化索引并报告代码事实,供编程智能体(coding agent)据此作出重构决策。它从不执行构建或计时:只负责描述代码,由手握代码的智能体决定如何修改。与 clice query 一样,它读取 clice index 构建的索引,并向标准输出打印 JSON。
用法:clice analyze <analysis> [<view> [<target>...]] [--workspace <dir>] [--configuration <tag>] [options]
模块
clice analyze modules 描述程序各目录之间的依赖关系,作为将其划分为 C++20 具名模块(named modules)的输入依据:哪些循环依赖构成阻碍、每个循环依赖系于哪几个实体、哪些头文件应当归入他处,以及哪些代码结构无法靠机械改写直接迁移到模块中。
分析范围内的每个文件都归属一个模块,默认按所在目录划分。当一个模块中的文件按名引用了另一个模块的文件所提供的实体时,前者就依赖于后者:包括直接写出的名称、宏展开在该文件中产生的名称、模板实例化通过限定名调用的重载(如 ops::clamp(value),在模板定义处查找),以及显式特化所针对的原模板。提供某个实体的文件优先取定义它的头文件,其次取声明它的头文件(若有多个,取引用该实体的文件中包含最多的那个),最后取定义它的源文件。来自头文件的依赖是接口边,会变为对目标模块接口的导入;仅来自源文件的依赖是实现边,不会闭合出循环依赖,因为实现单元可以导入位于其上层的模块。.inc 和 .def 等文本片段算作包含它们的文件的一部分。仅供所属模块自身源文件(直接或经其他此类头文件间接)使用并包含的头文件属于内部分区,不被任何其他文件引用且仅由这些源文件包含的头文件同样如此:它不会向模块接口增添任何内容,其依赖也都不是接口边。
--scope <glob>仅分析与 glob 匹配的文件(按相对于项目根目录的路径匹配);重复指定可传入多个模式。默认分析项目根目录下除点号开头目录外的所有已索引文件。--dir-depth <n>用文件所在目录路径的前n段而非完整目录路径命名其默认模块。--partition <file>按 glob 模式分配模块,以首个匹配为准:{"modules": [{"name": "core", "files": ["src/support/**", "src/vfs/**"]}]}。未被任何 glob 认领的文件保留其目录模块。对于interface视图和模块化,"textual": true让模块保留为头文件,"external": true标记由现成模块充当的模块(标准库),"provides": "std.compat"指明导出某个模块中名称的模块(名称自--std <dir>指定的 libc++ 模块源码读取)。--move <path>=<module>和--merge <module>+<module>[+...]评估假设的调整而不实际修改文件;重复指定可同时评估多处调整。--move-entity <locator>=<header>评估将一条声明连同其成员及成员定义所引用的实体移至另一个(已有或新建)头文件的效果;重复指定可评估多处移动。定位符需写出声明的完整名称:同一作用域内某函数的各个重载会一起移动,而edge视图打印的定位符可单独选中其中一个;若多个作用域中都有同名声明,则会报错并列出所有候选。--annotation <file>和--churn-since <date>为按权重排序的视图结果加权;参见标注。- 紧跟在
modules后的单词指定视图,决定输出哪类结果;省略时输出概览。
| 视图 | 输出内容 |
|---|---|
| (不指定视图) | 按层级排列的模块、附带示例实体的边、循环依赖及打破各循环依赖所需移除的最轻边集、模块内部的头文件循环依赖、内部分区数量、最深导入链、重新构建总量、热点、移动候选与拆分候选,以及障碍计数 |
edge <from> <to> | 该边上的每个实体,及其定位符、所属文件和每处使用的 file:line |
module <module> | 按模块列出各文件的依赖项与依赖方、该模块的内部分区,以及按使用方模块分组的其余头文件——即目录拆分的天然分界线 |
file <path> | 按模块列出该文件引用的实体、引用该文件实体的文件,以及该文件的标注 |
obstacles | 下文列出的所有阻碍结构 |
macros | 按模块列出在定义文件之外被使用的宏:模块导入不传递宏,因此每个宏都需经文本头文件传给使用方 |
impact | 按头文件列出修改它在当前结构下与划分模块后分别需要重新构建的翻译单元,以及它是否为内部分区 |
interface [<module>] | 按模块列出为其头文件生成封装模块所需的信息:它导入的模块、入口头文件及其他模块包含它们时所写的路径、命名空间作用域名称及所在头文件、命名空间别名、需保留为文本的头文件、其头文件与其他封装模块共用的 TU 局部实体、导入方所需的宏,以及其头文件读取的其他模块的宏 |
概览中的热点、移动候选和拆分候选数量受 --limit 限制(默认为 20);模块、边和循环依赖始终完整列出。
移动候选是指使用方全部集中在另一个模块中的头文件,且它与实现它的源文件以及这些源文件实现的其他头文件合在一起(只要还不是整个模块),既不引用本模块的其他内容,也不被本模块的其他文件引用;这些关联文件也会列出,以便整体迁移。拆分候选是指其中实体可分成若干组、且没有任何消费方模块同时使用多组的头文件,每组按行号列出前十个实体(格式为 name:line),并用 count 给出总数。
障碍
- 索引中存有多个变体的头文件会因包含方不同而解析出不同内容;作为模块接口只编译一次时,它只能保留一种解析结果。
declarationsDiffer标记各变体声明了不同实体的情况(真正的配置依赖),概览中仅统计此类头文件;unstable列出仅在部分变体中被按名引用的实体,例如模板中的依赖调用(dependent call)在不同包含位置查找到的重载。 - 在预处理条件中检测某个宏却未包含其定义的头文件,单独编译时解析结果会悄然改变(
contextMacros);展开此类宏的头文件在补上包含其定义的头文件之前,无法单独编译通过(borrowedMacros)。 - 头文件中的
static实体或匿名命名空间实体若被其他文件使用,或被该头文件自身的内联代码使用,一旦头文件变为模块接口,就会局限于单个翻译单元内部。 - 在模块单元内部,对其他模块所提供实体的前置声明或友元声明实际声明的是另一个不同实体;对第三方实体作此类声明则会将其归属到错误的模块。
unused标记文件中从未引用过的前置声明,可直接删除;友元声明无论文件是否引用该实体都会授予访问权限,因此从不标为未使用。 - 声明位于一个模块的头文件中、定义却位于另一个模块的源文件中的实体,以及在多个头文件中定义的实体。
- 头文件定义的、供第三方头文件读取的配置宏(
configuringMacros),在全局模块片段中必须继续排在该第三方头文件的包含指令之前。 - 用非自身提供的实参类型特化第三方模板的头文件(
implicitProviders),会在每次实例化时被隐式使用而不会被按名引用,因此没有依赖边记录这些使用方;它必须留在所有实例化单元都能导入的位置。 - 对其他模块中模板的显式特化也会列出:这类特化语法合法,但只有在导入了特化所在模块的位置才可达。
重新构建估算
修改模块接口会重新编译所有直接或经其他接口间接导入它的模块的全部单元,因为编译后的模块接口会记录其所导入的每个接口的哈希值。impact 视图与概览中的总量以翻译单元为单位,将该数量与当前修改对应头文件会重新构建的单元数作对比。修改内部分区只会重新构建原先包含其头文件(改写后即导入该分区)的单元;修改源文件则无论哪种方式都只重新构建一个单元。估算偏保守,且仅统计程序自身的源文件。
标注
标注是为每个文件赋予的具名数值,用于对结果加权,正如性能剖析数据为优化器的决策加权一样;不提供任何标注时,各项结果本身依然有意义。
churn表示文件的变更频率:默认依据git log统计近六个月内触及该文件的提交次数(--churn-since <date>接受任意git log --since参数值;传空字符串则关闭该项)。热点和重新构建总量都会乘以该权重。compile_time表示重新构建一个翻译单元的开销。未提供时每个翻译单元均计为 1。
标注文件的格式为 {"name": "compile_time", "unit": "s", "values": {"src/main.cpp": 4.2}},路径相对于项目根目录;与自动计算的标注同名的标注文件会覆盖前者。
答案
每个回答都是一个 JSON 对象;若问题无法作答(未知的模块或文件、无效的 glob 模式),则输出 {"error": "...", "stale": [...]} 并以退出码 1 结束;若命令行参数无法解析,或无法读取项目及其索引(缺少索引、配置文件无法解析),则同样输出该对象并以退出码 2 结束;索引缺失部分翻译单元时也会失败,并在 stale 中列出缺失的单元。
示例
目录模块
默认每个目录对应一个模块,其依赖关系取决于目录内文件按名引用的实体。
目录模块
每个目录自成一个模块,文件按名引用其他模块的实体即形成依赖
头文件引用其他模块的实体会形成接口边,改写后将变为对目标模块接口的导入;仅源文件中的引用则形成实现边。在 git 仓库之外运行时会省略变更频率(churn)标注,并附带一条警告。
循环依赖
接口互相依赖的模块会形成循环依赖,结果中还会列出建议切断的边。
目录循环依赖
接口互相引用对方实体的模块会形成循环依赖,并列出移除后可打破循环依赖的最轻边集
此处 util 引用了 core 的两个实体,而 core 只引用了 util 的一个实体,因此应切断从 core 到 util 的边。core 的源文件调用了 feature,而 feature 的头文件引用了 core 的 Logger:源文件产生的是实现边,不会闭合出循环依赖。
边
edge 视图列出一个模块引用了另一个模块的哪些实体。
边上的实体
edge 视图列出一个模块所引用的另一个模块的每个实体,连同指代它的定位符、声明它的头文件以及每处使用位置
当引用方模块的头文件按名引用某个实体时,即构成接口使用,正如本例中 util/clock.h 同时引用了这两个实体。
按标注加权
标注文件可对分析结果加权,本例按编译耗时加权。
按编译耗时加权
标注文件按重新构建每个翻译单元的开销为其加权,此处采用以秒计的编译耗时
原先只有 app/main.cpp 包含 core/fast.h,但划分为模块后,所有源文件都会直接或通过 util 的接口导入 core:修改该文件会重新构建三个翻译单元,而非原先的一个。
