# Arkguard
Arkguard 是Javascript和Typescript的源码混淆工具。

# 在DevEco Studio中的用法
Arkguard已经被集成了到SDK中。可以在DevEco Studio中很方便地使用。Arkguard只能用于Stage模型
(不支持FA模型)。目前Arkguard只提供名称混淆的能力(因为其它混淆能力会劣化性能)。
使用Arkguard可以混淆以下名称:
* 参数名和局部变量名
* 顶层作用域的名称
* 属性名称

Arkguard默认使能对参数名和局部变量名的混淆。顶层作用域名称和属性名称的混淆是默认关闭的，
因为默认打开可能会导致运行时错误。你可以通过[混淆选项](#混淆选项)来开启它们。

创建一个新工程的时候，配置文件`build-profile.json5`中会自动生成以下内容:
```
"arkOptions": {
  "obfuscation": {
    "ruleOptions": {
      "enable": true,
      "files": ["obfuscation-rules.txt"],
    }
  }
}
```
创建一个新的library的时候，还会额外生成`consumerFiles`属性:
```
"arkOptions": {
  "obfuscation": {
    "ruleOptions": {
      "enable": true,
      "files": ["obfuscation-rules.txt"],
    }
    "consumerFiles": ["consumer-rules.txt"]
  }
}
```

要想开启混淆，需要满足下面的条件:
* 属性`ruleOptions.enable`的值为`true`，并且所有依赖的library的`ruleOptions.enable`属性是`true`
* 在release模式构建

属性`ruleOptions.files`中指定的混淆配置文件会在构建HAP或HAR的时候被应用。

属性`consumerFiles`中指定的混淆配置文件会在构建依赖这个library的工程或library时被应用。
这些混淆配置文件的内容还会被合并到HAR包中的`obfuscation.txt`文件。

当构建HAP或者HAR的时候，最终的混淆规则是自身的`ruleOptions.files`属性，依赖的library的`consumerFiles`属性，
以及依赖的HAR包中的`obfuscation.txt`文件的合并。如果构建的是HAR，`obfuscation.txt`是自身的`consumerFiles`属性，
依赖的library的`consumerFiles`属性，以及依赖的HAR包中的`obfuscation.txt`文件的合并。
构建HAP不会生成`obfuscation.txt`。详细合并的策略可以查看[混淆规则合并策略](#混淆规则合并策略)。

## 配置混淆规则
在创建工程或library的时候，DevEco Studio会自动生成`obfuscation-rules.txt`和`consumer-rules.txt`文件，
但是它们默认不会包含任何混淆规则。你可以在这些文件中写混淆规则，或者也可以将规则写在其它文件，
然后将文件路径放到`ruleOptions.files`和`consumerFiles`中，如下面的例子所示。
```
"buildOption": {
  "arkOptions": {
    "obfuscation": {
      "ruleOptions": {
        "enable": true,
        "files": ["obfuscation-rules.txt", "myrules.txt"],
      }
      "consumerFiles": ["consumer-rules.txt", "my-consumer-rules.txt"]
    }
  }
}
```

在混淆规则文件中，你可以写[混淆选项](#混淆选项)和[保留选项](#保留选项)。

### 混淆选项

`-disable-obfuscation`

关闭所有混淆。如果你使用这个选项，那么构建出来的HAP或HAR将不会被混淆。默认情况下，
Arkguard只混淆参数名和局部变量名(通过将它们重新命名为随机的短名字)。

`-enable-property-obfuscation`

开启属性混淆。 如果你使用这个选项，那么所有的属性名都会被混淆，除了下面场景:
* 被`import/export`直接导入或导出的类或对象的属性名不会被混淆。比如下面例子中的属性名`data`不会被混淆。
    ```
    export class MyClass {
       data: string;
    }
    ```
    对于间接导出的场景，比如`export MyClass`和`let a = MyClass; export {a};`，如果你不想混淆它们的属性名，那么你需要使用[保留选项](#保留选项)来保留这些属性名。另外，对于直接导出的类或对象的属性的属性名，比如下面例子中的`name`和`age`, 如果你不想混淆它们，那么你也需要使用[保留选项](#保留选项)来保留这些属性名。
    ```
    export class MyClass {
       person = {name: "123", age: 100};
    }
    ```
* ArkUI组件中的属性名不会被混淆。比如下面例子中的`message`和`data`不会被混淆。
    ```
    @Component struct MyExample {
        @State message: string = "hello";
        data: number[] = [];
        ...
    }
    ```
* 被[保留选项](#保留选项)指定的属性名不会被混淆。
* 系统API列表中的属性名不会被混淆。系统API列表是构建时从SDK中自动提取出来的一个名称列表，其缓存文件为systemApiCache.json，路径为工程目录下build/cache/{...}/release/obfuscation中
* 在Native API场景中，在so的d.ts文件中声明的API不会被混淆。
* 字符串字面量属性名不会被混淆。比如下面例子中的`"name"`和`"age"`不会被混淆。
    ```
    let person = {"name": "abc"};
    person["age"] = 22;
    ```
    如果你想混淆字符串字面量属性名，你需要在该选项的基础上再使用`-enable-string-property-obfuscation`选项。比如
    ```
    -enable-property-obfuscation
    -enable-string-property-obfuscation
    ```
    **注意**：
    **1.** 如果代码里面有字符串属性名包含特殊字符(除了`a-z, A-Z, 0-9, _`之外的字符)，比如`let obj = {"\n": 123, "": 4, " ": 5}`，建议不要开启`-enable-string-property-obfuscation`选项，因为当不想混淆这些名字时，可能无法通过[保留选项](#保留选项)来指定保留这些名字。
    **2.** 系统API的属性白名单中不包含声明文件中使用的字符串常量值，比如示例中的字符串'ohos.want.action.home'不被包含在属性白名单中
    ```
    // 系统API文件@ohos.app.ability.wantConstant片段：
    export enum Params {
      ACTION_HOME = 'ohos.want.action.home'
    }
    // 开发者源码示例：
    let params = obj['ohos.want.action.home'];
    ```
    因此在开启了`-enable-string-property-obfuscation`选项时，如果想保留代码中使用的系统API字符串常量的属性不被混淆，比如obj['ohos.want.action.home'], 那么需要使用keep选项保留。

`-enable-toplevel-obfuscation`

开启顶层作用域名称混淆。如果你使用这个选项，那么所有的顶层作用域的名称都会被混淆，除了下面场景:
* 被`import/export`的名称不会被混淆。
* 当前文件找不到声明的名称不会被混淆。
* 被[保留选项](#保留选项)指定的顶层作用域名称不会被混淆。
* 系统API列表中的顶层作用域名称不会被混淆。

`-enable-filename-obfuscation`

开启文件/文件夹名称混淆。这个选项只在闭源HAR场景下生效，如果你使用这个选项，那么闭源HAR所有的文件/文件夹名称都会被混淆，除了下面场景:
* oh-package.json5文件中'main'、'types'字段配置的文件/文件夹名称不会被混淆。
* 模块内module.json5文件中'srcEntry'字段配置的文件/文件夹名称不会被混淆。
* 被[保留选项](#keep-file-name-link)指定的文件/文件夹名称不会被混淆。
* 非ECMAScript模块引用方式（ECMAScript模块示例：`import {foo} from './filename'`）
* 非路径引用方式，比如例子中的json5不会被混淆 `import module from 'json5'`

`-compact`

去除不必要的空格符和所有的换行符。如果使用这个选项，那么所有代码会被压缩到一行。
**注意**：release模式构建的应用栈信息仅包含代码行号，不包含列号，因此compact功能开启后无法依据报错栈中的行号定位到源码具体位置。

`-remove-log`

删除以下场景中对 console.* 语句的调用，要求console.*语句返回值未被调用。
1. 文件顶层的调用
2. 代码块Block中的调用
3. 模块Module中的调用
4. switch语句中的调用

`-print-namecache` filepath

将名称缓存保存到指定的文件路径。名称缓存包含名称混淆前后的映射。
注意：每次全量构建工程时都会生成新的namecache.json文件，因此您每次发布新版本时都要注意保存一个该文件的副本。

`-apply-namecache` filepath

复用指定的名称缓存文件。名字将会被混淆成缓存映射对应的名字，如果没有对应，将会被混淆成新的随机段名字。
该选项应该在增量编译场景中被使用。

默认情况下，DevEco Studio会在临时的缓存目录中保存缓存文件，并且在增量编译场景中自动应用该缓存文件。
缓存目录：build/cache/{...}/release/obfuscation

`-remove-comments`

删除文件中的所有注释，包括单行、多行，及JsDoc注释。以下场景除外：
声明文件中，在`-keep-comments`中配置的类、方法、struct、枚举等名称上方的JsDoc注释。
**注意**：编译生成的源码文件中的注释默认会被全部删除，不支持配置保留。
### 保留选项

#### `-keep-property-name` [,identifiers,...]
指定你想保留的属性名。比如下面的例子:
```
-keep-property-name
age
firstName
lastName
```
**注意**：该选项在开启`-enable-property-obfuscation`时生效

`-keep-comments`
保留声明文件中元素上方的JsDoc注释。比如想保留声明文件中Human类上方的JsDoc注释，可进行以下配置：
```
-keep-comments
Human
```
**注意**：
1. 该选项在开启`-remove-comments`时生效
2. 当声明文件中某个元素名称被混淆时，该元素上方的JsDoc注释无法通过`-keep-comments`保留。比如当在`-keep-comments`中配置了
exportClass时，如果下面的类名被混淆，其JsDoc注释无法被保留：
```
/**
** @class exportClass
*/
export class exportClass {}
```

**哪些属性名应该被保留?**

为了保障混淆的正确性，我们建议你保留所有不通过点语法访问的属性。

例子:
```
var obj = {x0: 0, x1: 0, x2: 0};
for (var i = 0; i <= 2; i++) {
    console.log(obj['x' + i]);  // x0, x1, x2 应该被保留
}

Object.defineProperty(obj, 'y', {});  // y 应该被保留
console.log(obj.y);

obj.s = 0;
let key = 's';
console.log(obj[key]);        // s 应该被保留

obj.u = 0;
console.log(obj.u);           // u 可以被正确地混淆

obj.t = 0;
console.log(obj['t']);        // 在开启字符串字面量属性名混淆时t和't'会被正确地混淆，但是我们建议保留

obj['v'] = 0;
console.log(obj['v']);        // 在开启字符串字面量属性名混淆时'v'会被正确地混淆，但是我们建议保留
```
在Native API场景中，没有在so的d.ts文件中声明的API，如果要在ets/ts/js文件中使用需要手动保留。


`-keep-global-name` [,identifiers,...]

指定要保留的顶层作用域的名称。比如，
```
-keep-global-name
Person
printPersonName
```

**哪些顶层作用域的名称应该被保留?**

在Javascript中全局变量是`globalThis`的属性。如果在代码中使用`globalThis`去访问全局变量，那么该变量名应该被保留。

例子:
```
var a = 0;
console.log(globalThis.a);  // a 应该被保留

function foo(){}
globalThis.foo();           // foo 应该被保留

var c = 0;
console.log(c);             // c 可以被正确地混淆

function bar(){}
bar();                      // bar 可以被正确地混淆

class MyClass {}
let d = new MyClass();      // MyClass 可以被正确地混淆
```

<a id="keep-file-name-link">`-keep-file-name` [,identifiers,...]</a>

指定要保留的文件/文件夹的名称(不需要写文件后缀)。比如，
```
-keep-file-name
index
entry
```
**哪些文件名应该被保留?**
```
const module1 = require('./file1')   // ARKTs不支持CommonJS语法，这种路径引用应该被保留
const moduleName = './file2'
const module2 = import(moduleName)    // 动态引用方式无法识别moduleName是否是路径，应该被保留
```

`-keep-dts` filepath

保留指定路径的`.d.ts`文件中的名称。这里的文件路径可以是一个目录，这种情况下目录中所有`.d.ts`文件中的名称都会被保留。
如果在构建HAR时使用了这个选项，那么文件中的名称会被合并到最后的`obfuscation.txt`文件中。

### 注释

可以使用`#`在混淆规则文件中进行注释。每行以`#`开头的文本会被当做是注释，比如下面的例子:
```
# white list for MainAbility.ets
-keep-global-name
MyComponent
GlobalFunction

-keep-property-name # white list for dynamic property names
firstName
lastName
age
```
构建HAR时，注释不会被合并到最后的`obfuscation.txt`文件中。

### 混淆规则合并策略
一个工程中经常会有许多混淆规则文件，这些文件来自于:
* 主工程的`ruleOptions.files` (这里主工程我们指的是正在构建的工程)
* 本地依赖的library中的`consumerFiles`选项中指定的文件
* 远程依赖的HAR包中的`obfuscate.txt`文件

当构建主工程的时候，这些文件中的混淆规则会按照下面的合并策略(伪代码)进行合并:
```
let `listRules` 表示上面提到的所有混淆规则文件的列表
let finalRule = {
    disableObfuscation: false,
    enablePropertyObfuscation: false,
    enableToplevelObfuscation: false,
    compact: false,
    removeLog: false,
    keepPropertyName: [],
    keepGlobalName: [],
    keepDts: [],
    printNamecache: string,
    applyNamecache: string
}
for each file in `listRules`:
    for each option in file:
        switch(option) {
            case -disable-obfuscation:
                finalRule.disableObfuscation = true;
                continue;
            case -enable-property-obfuscation:
                finalRule.enablePropertyObfuscation = true;
                continue;
            case -enable-toplevel-obfuscation:
                finalRule.enableToplevelObfuscation = true;
                continue;
            case -compact:
                finalRule.compact = true;
                continue;
            case -remove-log:
                finalRule.removeLog = true;
                continue;
            case -print-namecache:
                finalRule.printNamecache = #{指定的路径名};
                continue;
            case -apply-namecache:
                finalRule.applyNamecache = #{指定的路径名};
                continue;
            case -keep-property-name:
                finalRule.keepPropertyName.push(#{指定的名称});
                continue;
            case -keep-global-name:
                finalRule.keepGlobalName.push(#{指定的名称});
                continue;
            case -keep-dts:
                finalRule.keepDts.push(#{指定的路径});
                continue;
        }
    end-for
end-for
```
最后使用的混淆规则来自于对象`finalRule`。

如果构建的是HAR，那么最终的`obfuscate.txt`文件内容来自于主工程和本地依赖的library的`consumerFiles`选项，
以及依赖的HAR的`obfuscate.txt`文件的合并。合并策略和上面一样，除了以下的不同:
* `-keep-dts`选项会被转换成`-keep-global-name`和`-keep-property-name`。
* `-print-namecache`和`apply-namecache`选项会被忽略，不会出现在最后的`obfuscate.txt`文件中。

# Arkguard
Arkguard is a javascript and typescript obfuscation tool.
For Chinese version please read [README-cn.md](README-cn.md)
(中文版说明请查看[README-cn.md](README-cn.md)).

# Usage in DevEco Studio
Arkguard has been integrated into SDK. It is convenient to use Arkguard in DevEco Studio.
In DevEco Studio, Arkguard can be enabled only in Stage Model (FA Model is not supported).
For now only name obfuscations can be used in DevEco Studio (because other obfuscation
abilities of Arkguard may hurt execution performance).
You can obfuscate the following names:
* parameter names and local variable names
* names in global scope
* property names

We enable the obfuscation of parameter names and local variable names by default. However,
global names obfuscation and property names obfuscation are disabled by default, as they may
cause runtime error if they are enabled by default.
You can enable them by [obfuscation options](#obfuscation-options).

When you create a new project, the following config will be generated in `build-profile.json5`.
```
"arkOptions": {
  "obfuscation": {
    "ruleOptions": {
      "enable": true,
      "files": ["obfuscation-rules.txt"],
    }
  }
}
```
When you create a new library, additional property `consumerFiles` will be added.
```
"arkOptions": {
  "obfuscation": {
    "ruleOptions": {
      "enable": true,
      "files": ["obfuscation-rules.txt"],
    }
    "consumerFiles": ["consumer-rules.txt"]
  }
}
```

To enable obfuscation, the following conditions should be satisfied:
* the property `ruleOptions.enable` is `true` and the property `ruleOptions.enable` of every dependent library is `true`.
* build in release mode

The files in the property `ruleOptions.files` will be applied when you build HAP or HAR.

The files in the property `consumerFiles` will be applied when you build the project or library which
depends on this library. They will also be merged into a file `obfuscation.txt` in the resulting HAR.

When you are building HAP or HAR, the final obfucation rules are combination of self's `ruleOptions.files`
property, dependent libraries' `consumerFiles` properties and dependent HAR's `obfuscation.txt`.
If you are building HAR, the content of `obfuscation.txt` is the combination of self's `consumerFiles` property,
dependent libraries' `consumerFiles` properties and dependent HAR's `obfuscation.txt`. If you are building
HAP, `obfuscation.txt` will not be generated. For more details, please jump to
"[How Arkguard merges rules](#how-arkguard-merges-rules)".

## Write rules

The files `obfuscation-rules.txt` and `consumer-rules.txt` are created by DevEco Studio automatically, but they do not
contain any rule by default. You can write rules in these files or include rules from other files, as the following
example shows.
```
"buildOption": {
  "arkOptions": {
    "obfuscation": {
      "ruleOptions": {
        "enable": true,
        "files": ["obfuscation-rules.txt", "myrules.txt"],
      }
      "consumerFiles": ["consumer-rules.txt", "my-consumer-rules.txt"]
    }
  }
}
```

In rule files, you can write [obfuscation options](#obfuscation-options) and [keep options](#keep-options).

### Obfuscation options

`-disable-obfuscation`

Specifies to disable all obfuscations. If you use this option, the resulting HAP or HAR will not be obfuscated. By default,
Arkguard only obfuscates the parameter names and local variable names by assigning random short names to them.

`-enable-property-obfuscation`

Specifies to obfuscate the property names. If you use this option, all property names will be obfuscated except the
following:
* the property names of classes or objects directly imported or exported by `import/export` will be kept. For example, the property name `data` in
    ```
    export class MyClass {
       data: string;
    }
    ```
    will not be obfuscated.
For 'indirectly export' cases such as `export MyClass` and `let a = MyClass; export {a};`, if you do not want to obfuscate
their property names, you need to use [keep options](#keep-options) to keep them. Besides, for the property names of properties of directly exported classes or objects, like `name` and `age` in the following example, if you do not want to obfuscate them, then you also need [keep options](#keep-options) to keep them.
    ```
    export class MyClass {
       person = {name: "123", age: 100};
    }
    ```
* the property names defined in UI components. For example, the property names `message` and `data` in
    ```
    @Component struct MyExample {
        @State message: string = "hello";
        data: number[] = [];
        ...
    }
    ```
    will not be obfuscated.
* the property names that are specified by [keep options](#keep-options).
* the property names in system API list. System API list is a name set which is extracted from SDK automatically by default. The cache file is systemApiCache.json, and the path is build/cache/{...}/release/obfuscation in the module directory.
* in the Native API scenario, the APIs in the d.ts file of so library will not be obfuscated.
* the property names that are string literals. For example, the property names "name" and "age" in the following code will not be obfuscated.
    ```
    let person = {"name": "abc"};
    person["age"] = 22;
    ```
    If you want to obfuscate these string literal property names, you should addtionally use the option `-enable-toplevel-obfuscation`. For example,
    ```
    -enable-property-obfuscation
    -enable-string-property-obfuscation
    ```
    **Note**:
    **1.** If there are string literal property names which contain special characters (that is, all characters except
    `a-z, A-Z, 0-9, _`, for example `let obj = {"\n": 123, "": 4, " ": 5}` then we would not suggest to enable the
    option `-enable-string-property-obfuscation`, because [keep options](#keep-options) may not allow to keep these
    names when you do not want to obfuscate them.
    **2.** The property white list of the system API does not include the string constant in the declaration file. For example, the string `'ohos.want.action.home'` in the example is not included in the white list.
    ```
    // System Api @ohos.app.ability.wantConstant snippet:
    export enum Params {
      DLP_PARAM_SANDBOX = 'ohos.dlp.param.sandbox'
    }
    // Developer source example：
    let params = obj['ohos.want.action.home'];
    ```
    Therefore, when `-enable-string-property-obfuscation` is enabled, if you don't want to obfuscate the property like `'ohos.dlp.param.sandbox'`, which is a string constant in system api. you should keep it manually.

Specifies to obfuscate the names in the global scope. If you use this option, all global names will be obfuscated
except the following:
* the `import/export` global names.
* the global names that are not declared in the current file.
* the global names that are specified by [keep options](#keep-options).
* the global names in system API list.

`-enable-filename-obfuscation`

Specifies to obfuscate the file/folder names. This option only takes effect in OpenHarmony Archive(HAR) scenarios. If you use this option, all file/folder names will be obfuscated except the following:
* the file/folder names configured in the 'main' and 'types' fields in the oh-package.json5.
* the file/folder names configured in the 'srcEntry' field in the module.json5.
* the file/folder names that are specified by [keep options](#keep-file-name-link).
* non-ECMAScript module reference (ECMAScript module example: `import {foo} from './filename'`)
* non-path reference, such as json5 will not be obfuscated `import module from 'json5'`

`-compact`

Specifies to remove unnecessary blank spaces and all line feeds. If you use this option, all code will be compressed into
one line.
**Note**: The stack information in release mode only includes the line number of code, not the column number. Therefore, when the compact is enabled, the specific location of the source code cannot be located based on the line number of stack information.

`-remove-log`

Delete the expressions involving direct calls to console.* statements in the following scenarios:
1. Calls at the toplevel level of a file.
2. Calls within a block.
3. Calls within a module.
4. Calls within a switch statement.
and the return value of console.* should not be called

`-print-namecache` filepath

Specifies to print the name cache that contains the mapping from the old names to new names.
Note: The namecache.json file will be generated every time the module is fully built, so you should save a copy each time you publish a new version.

`-apply-namecache` filepath

Specifies to reuse the given cache file. The old names in the cache will receive the corresponding new names specified in
the cache. Other names will receive new random short names. This option should be used in incremental obfuscation.

By default, DevEco Studio will keep and update the namecache file in the temporary cache directory and apply the cache for
incremental compilation.
Cache directory: build/cache/{...}/release/obfuscation

`-remove-comments`

Remove all comments including single line, multi line and JsDoc comments, in a project except:
* Those names of JsDoc comments above class, function, struct, enum ... in declaration files are in `-keep-comments`.
**Note**: `-keep-comments` doesn't work for comments in generated source files, which will be deleted.
### Keep options

#### `-keep-property-name` [,identifiers,...]

Specifies property names that you want to keep. For example,
```
-keep-property-name
age
firstName
lastName
```
**Note**: This option is avaliable when `-enable-property-obfuscation` is enabled.

`-keep-comments`
To retain JsDoc comments above elements in declaration files, such as preserving the JsDoc comment above the Human class,
you can make the following configuration:
```
-keep-comments
Human
```
**Note**:
1. This option is avaliable when `-remove-comments` is enabled.
2. If the name of an element is obfuscated, the JsDoc comments
above that element cannot be kept using `-keep-comments`. For example, when you have exportClass in `-keep-comments`,
you should make sure that the following class will not be obfuscated, or the JsDoc comments above the class will still be removed:
```
/**
** @class exportClass
*/
export class exportClass {}
```

**What property names should be kept?**

For safety, we would suggest keeping all property names that are not accessed through dot syntax.

Example:
```
var obj = {x0: 0, x1: 0, x2: 0};
for (var i = 0; i <= 2; i++) {
  console.log(obj['x' + i]);  // x0, x1, x2 should be kept
}

Object.defineProperty(obj, 'y', {});  // y should be kept
console.log(obj.y);

obj.s = 0;
let key = 's';
console.log(obj[key]);        // s should be kept

obj.u = 0;
console.log(obj.u);           // u can be safely obfuscated

obj.t = 0;
console.log(obj['t']);        // t and 't' can be safely obfuscated when `-enable-string-property-obfuscation`, but we suggest keeping t

obj['v'] = 0;
console.log(obj['v']);        // 'v' can be safely obfuscated when `-enable-string-property-obfuscation`, but we suggest keeping v
```
In the native API scenario, if in the ets/ts/js file you want to use APIs that are not declared in d.ts file, you need to keep these APIs.

`-keep-global-name` [,identifiers,...]

Specifies names that you want to keep in the global scope. For example,
```
-keep-global-name
Person
printPersonName
```

**What global names should be kept?**

It is known that in javascript the variables in the global scope are properties of `globalThis`. So if in your code
you access a global variable as a property, then the global name should be kept.

Example:
```
var a = 0;
console.log(globalThis.a);  // a should be kept

function foo(){}
globalThis.foo();           // foo should be kept

var c = 0;
console.log(c);             // c can be safely obfuscated

function bar(){}
bar();                      // bar can be safely obfuscated

class MyClass {}
let d = new MyClass();      // MyClass can be safely obfuscated
```

<a id="keep-file-name-link">`-keep-file-name` [,identifiers,...]</a>

Specify the name of files/folders to keep (no need to write the file suffix). for example,
```
-keep-file-name
index
entry
```
**What file names should be kept?**
```
const module1 = require('./file1')   // ARKTs doesn't support CommonJS, this path reference should be kept.
const moduleName = './file2'
const module2 = import(moduleName)   // dynamic reference cannot identify whether moduleName is a path and should be retained.
```

`-keep-dts` filepath

Specifies to keep names in the given `.d.ts` file. Here filepath can be also a directory. If so, then the names in all
`d.ts` files under the given directory will be kept.
If your are building HAR with this option, then the kept names will be merged into the resulting `obfuscation.txt`.

### Comments

You can write comments in obfuscation rule file by using `#`. The line begins with `#` is treated as comment.
For example,
```
# white list for MainAbility.ets
-keep-global-name
MyComponent
GlobalFunction

-keep-property-name # white list for dynamic property names
firstName
lastName
age
```
If your are building HAR, comments will not be merged into the resulting `obfuscation.txt`.

### How Arkguard merges rules
Typically there may be serveral rule files in your project. These rule files come from:
* `ruleOptions.files` in main project (Here by main project we mean the project you are building)
* `consumerFiles` in local dependent libraries
* `obfuscate.txt` in remote dependent HARs
When building your main project, all these rules will be merged by the following strategy (in pseudo code):
```
let `listRules` be the list of all rule files that are mentioned above.
let finalRule = {
    disableObfuscation: false,
    enablePropertyObfuscation: false,
    enableToplevelObfuscation: false,
    compact: false,
    removeLog: false,
    keepPropertyName: [],
    keepGlobalName: [],
    keepDts: [],
    printNamecache: string,
    applyNamecache: string
}
for each file in `listRules`:
    for each option in file:
        switch(option) {
            case -disable-obfuscation:
                finalRule.disableObfuscation = true;
                continue;
            case -enable-property-obfuscation:
                finalRule.enablePropertyObfuscation = true;
                continue;
            case -enable-toplevel-obfuscation:
                finalRule.enableToplevelObfuscation = true;
                continue;
            case -compact:
                finalRule.compact = true;
                continue;
            case -remove-log:
                finalRule.removeLog = true;
                continue;
            case -print-namecache:
                finalRule.printNamecache = #{specified path};
                continue;
            case -apply-namecache:
                finalRule.applyNamecache = #{specified path};
                continue;
            case -keep-property-name:
                finalRule.keepPropertyName.push(#{specified names});
                continue;
            case -keep-global-name:
                finalRule.keepGlobalName.push(#{specified names});
                continue;
            case -keep-dts:
                finalRule.keepDts.push(#{specified file path});
                continue;
        }
    end-for
end-for
```
The final obfuscation rules are in the object `finalRule`.

If you are building HAR, the resulting `obfuscate.txt` are obtained by merging the rules from `consumerFiles` in main
project and local dependent libraries, and `obfuscate.txt` in remote dependent HARs. The merging strategy is the same
except:
* The `-keep-dts` option will be converted to `-keep-global-name` and `-keep-property-name` options in the resulting
`obfuscate.txt`.
* The options `-print-namecache` and `apply-namecache` will be omitted and will not appear in the resulting
`obfuscate.txt`.