HarmonyOS 鸿蒙Next编写代码检查规则的神器，解读CodeNavi语法结构

HarmonyOS 鸿蒙Next编写代码检查规则的神器，解读CodeNavi语法结构 摘要：检查规则是查找代码节点中符合缺陷模式的检查规则。本文主要介绍了用于编写代码检查规则的工具 CodeNavi 的语法结构，CodeNavi 可以基于 DSL 语言编写自定义规则进行代码扫描。

本文分享自华为云社区《CodeNavi 规则的语法结构》，作者：Uncle_Tom。

1. 代码和检查规则

1.1. 代码的构成

程序是由空格分隔的字符串组成的序列。在程序分析中，这一个个的字符串被称为"token"，是源代码中的最小语法单位，是构成编程语言语法的基本元素。

Token 可以分为多种类型，常见的有关键字（如 if、while）、标识符（变量名、函数名）、字面量（如数字、字符串）、运算符（如 +、-、*、/）、分隔符（如逗号 ,、分号 ;）等。

程序在编译过程中，词法分析器（Lexer）读取源代码并将其分解成一系列的 token。语法分析器（Parser）会使用这些 token 来构建一个抽象语法树（Abstract Syntax Tree, AST），这个树结构表示了代码的语法结构。这个时候每个 token 也可以称为抽象语法树的节点，树上某个节点的分支就是这个节点的子节点。每个节点都会有节点类型、属性、值。

这些是程序员非常容易理解的。

1.2. 检查规则

检查规则是查找代码节点中符合缺陷模式的检查规则。

通常静态分析工具的规则编写采用程序语言，这样开发人员除了要了解检查的问题本省，还需要理解静态分析理论，以及静态分析工具的框架，无形中增加了开发的难度。所以我们一直期望寻找到一种更适合编写静态分析规则的语言，让开发人员能够更好的专注于理解检查问题的本身，而不需要花更多的时间在如何实现上。

例如：

• 检查问题： 生产环境中不应该有调试代码。
• 问题检查条件：
  • 查找所有函数声明
  • 并且 (And)： 函数名以 “debug” 开头
  • 并且 (And)： 函数只有一个参数
  • 并且 (And)： 参数类型为 “java.util.List”

2. 规则语法结构

下面我们进一步给出这种用于编写代码检查规则的工具 CodeNavi 的语法结构。

2.1. 规则的语法

规则语句是以分号 (;) 结尾, 作为规则的终止符。

2.2. 语句结构

• 节点 (node)： 为待检测代码节点（token）
• as 别名： 给要查找的节点一个别名，便于后面的使用。as 可以省略。别名的命名规则如下：
  • 只能包含大小写英文字母和数字
  • 数字只能出现在末尾
  • 不能和规则内置的节点或属性同名
  • 例如：va1、fd、Field1 都是合法的别名，1fc、v2a 是非法别名

2.3. 节点和节点属性

• 节点 (node)： 是代码对应语法树的节点或子节点
• 属性 (attribute)： 是代码对应语法树的节点或子节点的属性
• . : 节点、子节点、属性之间的连接符

2.4. 条件表达式结构

• where: 条件表达式的标识
• and： 括号内的查询条件必须都为真
• or： 括号内的查询条件至少有一个为真
• not： 括号内的查询条件为假

逻辑的连接词是一种作用于查询条件的关键词。规则支持 and、or 和 not 三个关联词。

逻辑的连接词需要和括号一同使用，括号中为具体的查询条件。其中，and 和 or 可以作用于多个查询条件（即括号中可以包含多个查询条件，以逗号分隔开），not 只能作用于一个查询条件。

逻辑连接词是一类作用于查询条件的特殊运算符（普通的运算符作用于节点或属性）。

逻辑的连接词作用的查询条件也可以包含逻辑连接词。

2.5. 条件判断 (condition)

2.5.1. 运算符

查询条件通过运算符作用于具体的节点或属性从而完成节点筛选。

根据运算符作用的属性类别，我们可以将运算符分为:

• 通用运算符
• 算术运算符
• 字符串运算符
• 布尔运算符
• 节点运算符

运算符的左值为：节点或节点的属性。

2.5.1.1. 通用运算符 (==, contain)

• 等于（==）、不等于（!=）

  • 数字
    • 运算符右值为：整数或小数。
    • 例如：arguments.size() == 3
  • 字符串
    • 运算符右值为：字符串常量。
    • 例如：name == “foo”
  • 布尔
    • 运算符右值为：布尔常量: true 或 false。
    • 例如：isPublic == true
  • 节点
    • 运算符右值为：空常量 null。
    • 例如：initializer == null

• 包含（contain）、不包含（notContain）

  • 字符串
    • 运算符右值为：字符串，且包含时，返回真。
    • 例如：recordDeclaration where name contain “debug”;，返回函数名中包含 “debug” 时，返回真。
  • 节点
    • 运算符右值为：子查询条件，当子查询返回的节点满足时，返回真。
    • 例如：functionDeclaration where parameters contain param where param.name == “i1”;，返回包含名为 i1 参数的方法声明。

2.5.1.2. 算术运算符 (>)

• 算术运算符操作数字。
• 大于（>）、小于（<）、大于等于（>=）、小于等于（<=）
  • 数字
    • 运算符右值为：数字，且满足时，返回真。

2.5.1.3. 字符串运算符 (startWith, endWith, match)

• 字符串运算符操作字符串。
• 字符串的开始字符串（startWith）
  • 左值开始字符串等于右值字符串时，返回真。
  • 例如：functionDeclartion where name startWith “debug”;，筛选出名字以 debug 开头的方法声明。
• 字符串的结束字符串（endWith）
  • 左值结束字符串等于右值字符串时，返回真。
  • 例如：functionDeclartion where name endWith “hello”，筛选出名字以 hello 结尾的方法声明。
• 字符串匹配（match）
  • 左值符合右值的正则表达式时，返回真。
  • 例如：functionDeclaration where name match “.(login).”，筛选出名字匹配正则表达式.(login)..的方法声明。

2.5.1.4. 布尔运算符 (!)

• 逻辑运算符操作布尔值。
• 非（!）
  • 操作符位于布尔属性的左侧，表示布尔值为 false 时，返回真。
  • 例如：recordDeclaration where !isPublic 等价于 recordDelaration where isPublic == false。

2.5.1.5. 节点运算符 (contain, in, is)

• 节点运算符的左侧可以是节点属性 或 别名。

• 包含(contain)

  • 用于查询语法树结构上的子节点。
  • 例如: 筛选出方法体内调用了名为 foo 的无参方法的方法声明。

• 存在于(in)

  • 查询语法树结构上的父节点。
  • 例如: 筛选出位于赋值表达式中的数据成员访问节点。

• 是(is)

  • 右侧节点属性或别名相同时，返回真。
  • 例如：筛选出出现在赋值表达式左侧的变量访问节点，且赋值表达式的右侧为方法调用节点。规则中的 va 是节点 variableAccess 的别名。

3. CodeNavi 插件

在 Vscode 的插件中，查询: codenavi，并安装。