update usage.md

docs/project-scan-file.yml

@@ -0,0 +1,79 @@
+# 前置知识：
+#    我们将所有的运行时类分为三种：application class（用户期望直接扫描的重点类），library class（依赖的三方库，增加分析精度）, phantom class（class not found，可能没编译可能没有三方库）
+# 一般的程序的语义分析都需要显式或者隐式地给出 入口函数/方法 即分析目标，入口函数位置应该在用户部分的代码（application classes）中。
+# 如果分析入口包含了库代码则会导致分析目标过多而大量消耗资源，无法高效地扫描我们关心的代码。
+
+# 使用方法
+## 添加参数: --output ${output} 在 corax 分析参数 --extra-args 前
+## 添加参数: --project-scan-config project-scan-config.yml 在命令最后
+
+# 其他
+# 可以前往 https://regex101.com 测试正则，并选择 FLAVOR 为 java
+#  注意 "\." 是匹配 "." , 而单个 "." 是匹配任何字符（行终止符除外）
+
+# class 的分类规则
+process-class-regex: #                            class包名的正则。注意匹配时候是从上到下有序匹配的，请注意顺序
+    - (-)\.R\$\w+$                                    # 如 com.android.R$id
+    - (+)org\.owasp\.benchmark\.testcode              # 如 org.owasp.benchmark.testcode.Test001, org.owasp.benchmark.testcode.xss.Xss001
+    - (+)org\.owasp\.benchmark(-)org\.owasp\.benchmark\.utils # 扫描(Process) org.owasp.benchmark下且非org.owasp.benchmark.utils下的类。
+                                                      # 支持任意数量的正则并使用(+)or(-)连接
+    - (-)org\.owasp(+)org\.owasp\.benchmark           # 排除(Skip) org.owasp下且非org.owasp.benchmark的所有的类， 如 org.owasp.comp.Test会被排除(Skip)，但是如org.owasp.benchmark和org.foo不会被排除(继续下面的规则)
+
+    # ⇲ 请在这里加上您需要扫描的包名正则 ↙
+    - (+)org\.example
+
+    - (-others) # 完全等价 (-).+ ，表示不扫描上面正则没有涵盖到的类，或者[+others], 不写的话保持原来的分类（Keep）（--process和--auto-app-classes指向的是application classes， --class-path指向的是library class）。
+
+# 资源文件的分类规则
+process-res-regex: #                              资源文件路径的正则
+    - (+)/.+_jsp.java$                                # 如 build/jsp-classes/org/**/View_jsp.java 会被AST解析或纯文本的扫描
+                                                      # 但是将此正则放在 (-)/build/ 后会导致 build/**/*_jsp.java 永远无法被AST解析或纯文本的扫描
+    # files                                       资源路径的正则
+    - (-)/\.R\.java$                                  # 如 com/android/.R.java
+
+    # directories                                 资源目录的正则。注意匹配时候是从上到下有序匹配的，请注意顺序
+    - (-)/out/
+    - (-)/output/
+    - (-)/tmp/
+    - (-)/temp/
+    - (-)/log/                                        # 路径正则尽量加上"/", 表示为文件夹路径, 否则所有名子包含log的文件也会被排除
+    - (-)/logs/
+    - (-)/build/
+    - (-)/target/
+    - (-)/\.git/
+    - (-)/\.idea/
+    - (-)/\.gradle/
+    - (-)/\.mvn
+    - (-)/\.run/
+
+    - (+others) # 完全等价 (+).+ ，表示扫描上面正则没有涵盖到的资源，或者[-others], 不写的话则保持原来的分类（Keep），原来--source-path和--auto-app-classes指向的资源会被扫描。
+
+
+
+# 本配置文件实际的筛选分类信息可以在分析完成后打开 ${output}/scan-classifier-info.yml 查看
+# ScanAction有如下几种：
+#    Process：表示会被扫描
+#    Keep: 保持原状
+#    Skip：表示不会被作为入口重点扫描，但是Skip标记的类如果可以被过程间调用到，那么这部分方法仍然会被依赖扫描分析
+
+# 比如：
+# - "library -> Process: com.example.JavaAnnotationTest" 表示原分类为library class（不会被直接分析）的com.example.JavaAnnotationTest经过project-scan-config.yml文件中的正则匹配后被标记为Process，将会被直接分析。
+# - "application -> Skip: com.foo.Test" 表示原分类为application class（会被直接分析）的com.foo.Test经过正则匹配后被标记为Skip，将不会被直接的分析
+# - "phantom -> Skip: com.not.exists.Test" 原分类为phantom class（表示被分析依赖的但是分析器只能获取到类名字无法获得类文件的类）的com.not.exists.Test，无论如何改变其ScanAction也无法被分析，因为它不存在。需要检查--auto-app-classes,--process,--class-path这几个参数的指向位置是否包含完整的类
+
+# 所以您需要扫描的类如 com.example.foo.ApplicationTest 出现以下任意下情形均表示参数和配置或输入资源出现问题：
+# - "library -> Keep: com.example.foo.ApplicationTest"               原因：project-scan-config.yml中没有涵盖到该类 并且 <该类存在于--class-path而不存在于--process，或者--auto-app-classes指向的路径的类没有对应源码（会被分类为library class）>
+# - "application -> Skip: com.example.foo.ApplicationTest"           原因：被project-scan-config.yml中(-)后的正则错误地排除掉了，请检查您的正则
+# - "phantom -> Process|Keep|Skip: com.example.foo.ApplicationTest"  原因：class not found!，是否没有编译，是否没有被--auto-app-classes,--process,--class-path指定
+#   正确的是：
+# - "library -> Process: com.example.foo.ApplicationTest"
+# - "application -> Process|Keep: com.example.foo.ApplicationTest"
+
+# 所以您不希望被直接扫描的类(如三方库，非目标项目的代码的类)如 org.spring.AbstractRequest 出现以下任意下情形均表示参数和配置或输入资源出现问题：
+# - "library -> Process: org.spring.AbstractRequest"                原因：被project-scan-config.yml中(+)后的正则错误地包含了，请检查您的正则
+# - "application -> Keep: org.spring.AbstractRequest"               原因：project-scan-config.yml中没有关于此类的正则，请检查您的正则
+# - "application -> Process: org.spring.AbstractRequest"            原因：被project-scan-config.yml中(+)后的正则错误地包含了，并且--auto-app-classes,--process指向了该类
+# - "phantom -> Process|Keep|Skip: org.spring.AbstractRequest"      原因：class not found!，是否没有编译，是否没有被--auto-app-classes,--process,--class-path指定
+#   正确的是：
+# - "library -> Skip|Keep: org.spring.AbstractRequest"
+# - "application -> Skip: org.spring.AbstractRequest"

docs/usage.md

@@ -303,25 +303,19 @@ flag option。 此选项默认关闭以保证分析精度
 
 ### --project-scan-config
 
-在 **ApplicationClasses** 和 资源文件（比如source file, config files） 对象中 进一步筛选要分析的目标，参考 [命令行参数](#命令行参数) 中的图示。
-
-> 作用：选取项目中部分代码和资源文件进行分析
+> 用于告知分析器分析的重点及期望分析和不希望分析的 类或者文件
 
 eg：
 
 ```
---project-scan-config JavaScanFilter.yml
+--project-scan-config project-scan-config.yml
 ```
 
-获取详细内容请查看此文件 [JavaScanFilter.yml](JavaScanFilter.yml)
-
-
+获取详细内容请查看此文件 [project-scan-file.yml](project-scan-file.yml)
 
-请注意正确的转义，比如这里的 `\.` 是正则的转义。如果想要知道该配置产生的影响，可以查看 output 目录中的这两个文件
+请注意正确的转义，比如yml中的 `\.` 是正则非yaml的转义。如果想要知道该配置产生的影响，可以查看 output 目录中的 `scan-classifier-info.yml` 文件
 
-`${output}/analyzeSkip/classSkipList.txt `（过滤掉的类）
 
-`${output}/analyzeSkip/sourceFileSkipList.txt `（过滤掉的资源文件）
 
 ### --serialize-cg
 flag option。 此选项默认关闭