Merge pull request #27 from codefuse-ai/coref-api

[doc] Deploy COREF API documents

Author: zhouang777

.devcontainer/devcontainer.json

@@ -0,0 +1,22 @@
+{
+    "image": "ghcr.io/lonrun/codefuse-query-tutorial:0.6",
+    "hostRequirements": {
+        "cpus": 4
+    },
+    "customizations": {
+        "codespaces": {
+            "openFiles": [
+                "tutorial/README.md"
+            ]
+        },
+        // Configure properties specific to VS Code.
+        "vscode": {
+            // Add the IDs of extensions you want installed when the container is created.
+            "extensions": [
+                "ms-toolsai.jupyter",
+                "MS-CEINTL.vscode-language-pack-zh-hans",
+                "CodeFuse-Query.codefuse-query-extension"
+            ]
+        }
+    }
+}

.github/workflows/pages.yml

@@ -43,6 +43,8 @@ jobs:
           bundler-cache: true # runs 'bundle install' and caches installed gems automatically
           cache-version: 0 # Increment this number if you need to re-download cached gems
           working-directory: '${{ github.workspace }}/doc'
+      - name: Generate COREF API Documents
+        run: python3 tools/build.py
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v3

README.md

@@ -16,6 +16,12 @@
     <a href="https://github.com/codefuse-ai/CodeFuse-Query/issues">
       <img alt="Open Issues" src="https://img.shields.io/github/issues-raw/codefuse-ai/CodeFuse-Query" />
     </a>
+    <a href="https://github.com/codefuse-ai/CodeFuse-Query/releases">
+      <img alt="Release Download" src="https://img.shields.io/github/downloads/codefuse-ai/CodeFuse-Query/total" />
+    </a>
+    <a href="https://marketplace.visualstudio.com/items?itemName=CodeFuse-Query.codefuse-query-extension">
+      <img alt="VSCode Plugin" src="https://img.shields.io/visual-studio-marketplace/i/CodeFuse-Query.codefuse-query-extension?style=social&logo=visualstudiocode&logoColor=%23007ACC" />
+    </a>
 </p>
 
 ## 什么是CodeFuse-Query？
@@ -54,7 +60,7 @@ CodeFuse-Query 包括**Sparrow CLI **和CodeFuse-Query**在线服务Query中心*
 注：以上语言状态的成熟程度判断标准是根据COREF包含的信息种类和实际落地情况来进行判定，除了OC/C++外，所有语言均支持了完整的AST信息和Documentation信息，以Java为例，COREF for Java还支持了ASG、Call Graph、Class Hierarchy、以及部分CFG信息。
 ## 使用场景
 ### 查询代码特征
-小开发同学想知道 Repo A 里面使用了哪些 String 型的变量，所以他写了一个 Godel 如下，交给 CodeFuse-Query 系统给他返回了结果。
+小开发同学想知道 Repo A 里面使用了哪些 String 型的变量，所以他写了一个 Gödel 如下，交给 CodeFuse-Query 系统给他返回了结果。
 ```rust
 // script
 use coref::java::*
@@ -76,7 +82,7 @@ fn main() {
 小 TL 同学发现团队总是写出很多类似的 Bug A，**他想针对 Bug A 制定一个代码规则和其检查器**，并在 CodeReview 阶段做个卡点。小 TL 通过在 CodeFuse-Query 平台上面编写了一段分析 Query，在平台上面测试符合要求，把这段分析 Query 固化下来作为一个代码规则，并上线到了 CodeReview/CI 阶段。从此这个 Bug 再也没发生过了。
 类似需求：编写静态缺陷扫描规则进行代码风险拦截。
 ### 获取统计数据
-小研究发现传统的代码复杂度指标很难准确地衡量代码的复杂情况，通过学习国际先进经验加上自我灵光一闪，设计了一套复杂度指标和算法。通过 Godel 实现出来以后，**发现不怎么优化就已经性能非常高了**，很快就应用到了 10 几种语言，11+万个仓库当中去了。马上就对代码仓库整体的复杂度有了深入的了解。相比较以前需要自己解析代码，分析语法树，对接系统，**不知道方便了多少。**
+小研究发现传统的代码复杂度指标很难准确地衡量代码的复杂情况，通过学习国际先进经验加上自我灵光一闪，设计了一套复杂度指标和算法。通过 Gödel 实现出来以后，**发现不怎么优化就已经性能非常高了**，很快就应用到了 10 几种语言，11+万个仓库当中去了。马上就对代码仓库整体的复杂度有了深入的了解。相比较以前需要自己解析代码，分析语法树，对接系统，**不知道方便了多少。**
 类似需求：代码统计，代码度量，算法设计，学术研究。
 
 ## 应用领域 
@@ -110,14 +116,18 @@ CodeFuse-Query为CodeFuse代码大模型提供了以下数据清洗能力：
 - [引言](./doc/1_abstract.md)
 - [概述](./doc/2_introduction.md)
 - [安装、配置、运行](./doc/3_install_and_run.md)
-- [Godel查询语言介绍](./doc/4_godelscript_language.md)
+- [Gödel查询语言介绍](./doc/4_godelscript_language.md)
 - [VSCode开发插件](./doc/5_toolchain.md)
 
+## 教程 (tutorial)
+- [在线教程](./tutorial/README.md)
+
 ## 目录结构说明
 - `cli`：命令行工具的入口，提供统一的命令行接口，调用其他模块完成具体功能
 - `language`：各语言的数据化核心（extractor）和数据建模（lib）。关于开放度的问题，请参见《关于开源范围的一些说明》章节
 - `doc`：参考文档
-- `examples`：Godel 查询语言示例
+- `examples`：Gödel 查询语言示例
+- `tutorial`：CodeFuse-Query 开发容器使用教程
 
 ## 关于开源范围的一些说明
 截止目前，从源码**不能**构建出可执行的程序，原因在于本次开源并没有开放所有的模块，缺少的模块会在之后的一年陆续开源。尽管如此，为保障完整的体验，我们开放了**完整的安装包**下载，请见Release页面。
@@ -134,3 +144,9 @@ CodeFuse-Query为CodeFuse代码大模型提供了以下数据清洗能力：
 | SQL | N | N | BETA |
 | Swift | N | N | BETA |
 | Properties | N | N | BETA |
+
+## 联系我们
+![微信用户群图片](./assets/wechat_qrcode_1214.JPG)
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=codefuse-ai/CodeFuse-Query&type=Date)](https://star-history.com/#codefuse-ai/CodeFuse-Query&Date)

assets/wechat_qrcode_1214.JPG

@@ -31,11 +31,11 @@ def __init__(self):
 
 
 def cfamily_extractor_cmd(source_root, database, options):
-    cmd = list()
-    cmd += [str(Extractor.cfamily_extractor)]
-    cmd += ["--compile-commands=", str(source_root)]
-    cmd += ["--output-db-path=", str(database)]
-    return cmd
+    return [
+        str(Extractor.cfamily_extractor),
+        f"--compile-commands={source_root}",
+        f"--output-db-path={database}"
+    ]
 
 
 def go_extractor_cmd(source_root, database, options):

cli/extractor/extractor.py

@@ -1,7 +1,9 @@
 随着大规模软件开发的普及，对可扩展且易于适应的静态代码分析技术的需求正在加大。传统的静态分析工具，如 Clang Static Analyzer (CSA) 或 PMD，在检查编程规则或样式问题方面已经展现出了良好的效果。然而，这些工具通常是为了满足特定的目标而设计的，往往无法满足现代软件开发环境中多变和多元化的需求。这些需求可以涉及服务质量 (QoS)、各种编程语言、不同的算法需求，以及各种性能需求。例如，安全团队可能需要复杂的算法，如上下文敏感的污点分析，来审查较小的代码库，而项目经理可能需要一种相对较轻的算法，例如计算圈复杂度的算法，以在较大的代码库上测量开发人员的生产力。
+
 这些多元化的需求，加上大型组织中常见的计算资源限制，构成了一项重大的挑战。由于传统工具采用的是问题特定的计算方式，往往无法在这种环境中实现扩展。因此，我们推出了 CodeQuery，这是一个专为大规模静态分析设计的集中式数据平台。
 在 CodeQuery 的实现中，我们把源代码和分析结果看作数据，把执行过程看作大数据处理，这与传统的以工具为中心的方法有着显著的不同。我们利用大型组织中的常见系统，如数据仓库、MaxCompute 和 Hive 等数据计算设施、OSS 对象存储和 Kubernetes 等灵活计算资源，让 CodeQuery 能够无缝地融入这些系统中。这种方法使 CodeQuery 高度可维护和可扩展，能够支持多元化的需求，并有效应对不断变化的需求。此外，CodeQuery 的开放架构鼓励各种内部系统之间的互操作性，实现了无缝的交互和数据交换。这种集成和交互能力不仅提高了组织内部的自动化程度，也提高了效率，降低了手动错误的可能性。通过打破信息孤岛，推动更互联、更自动化的环境，CodeQuery 显著提高了软件开发过程的整体生产力和效率。
 此外，CodeQuery 的以数据为中心的方法在处理静态源代码分析的领域特定挑战时具有独特的优势。例如，源代码通常是一个高度结构化和互联的数据集，与其他代码和配置文件有强烈的信息和连接。将代码视为数据，CodeQuery 可以巧妙地处理这些问题，这使得它特别适合在大型组织中使用，其中代码库持续但逐步地进行演变，大部分代码在每天进行微小的改动同时保持稳定。 CodeQuery 还支持如基于代码数据的商业智能 (BI) 这类用例，能生成报告和仪表板，协助监控和决策过程。此外，CodeQuery 在分析大型语言模型 (LLM) 的训练数据方面发挥了重要作用，提供了增强这些模型整体效果的深入见解。
+
 在当前的静态分析领域，CodeQuery 带来了一种新的范式。它不仅满足了大规模、复杂的代码库分析需求，还能适应不断变化和多元化的静态分析场景。CodeQuery 的以数据为中心的方法，使得其在处理大数据环境中的代码分析问题时具有独特优势。CodeQuery 的设计，旨在解决大规模软件开发环境中的静态分析问题。它能够将源代码和分析结果视作数据，使得其可以灵活地融入大型组织的各种系统中。这种方法不仅可以有效地处理大规模的代码库，还可以应对各种复杂的分析需求，从而使得静态分析工作变得更加高效和准确。
 
 CodeQuery 的特点和优势可以概括为以下几点：