Merge pull request #7 from codefuse-ai/cyz_dev

Add project codespaces config

Author: ValKmjolnir

.devcontainer/devcontainer.json

@@ -0,0 +1,11 @@
+{
+    "image": "ghcr.io/lonrun/codefuse-query-tutorial:0.5",
+    "hostRequirements": {
+      "cpus": 4
+    },
+    "customizations": {
+      "codespaces": {
+        "openFiles": ["tutorial/README.md"]
+      }
+    }
+  }

tutorial/README.md

@@ -0,0 +1,13 @@
+## CodeQuery使用教程
+
+### 使用Github Codespaces 来体验CodeQuery分析能力 
+
+#### 步骤
+
+- 在项目主页切换到目标分支
+- 创建 Codespaces，依次点击 Code -> Codespaces，在当前分支创建一个 Codespaces
+- 创建后，打开该 Codespaces，加载完成后，切换至项目 tutorial/notebook 目录下
+- 选择示例下的 jupyter notebook 分析教程，即可开始体验
+
+#### 注意
+- 打开jupyter页面之后，如果是第一次加载容器，你还需要配置教程所使用的内核，在右上角 “选择内核”弹出框中，依次选择 “Juypter Kernel...” -> “Godel Kernel” 即可。

tutorial/notebook/go_analysis.ipynb

@@ -0,0 +1,207 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "这是一个使用CodeFuse-Query分析Go项目的教程。在教程中，你将体验到使用命令行工具对代码仓库进行数据化，然后使用Godel语言来分析这个仓库。"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "检查cli是否就绪"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "!which sparrow"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "STEP 0: 克隆要分析的仓库。我们以 [gorm](https://github.com/go-gorm/gorm.git) 项目为例。"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2023-11-22T08:30:58.387715Z",
+     "start_time": "2023-11-22T08:30:44.572634Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "!git clone https://github.com/go-gorm/gorm.git"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "STEP 1: 代码数据化。使用 `sparrow database create` 命令创建一个db文件，指定待分析的仓库地址（当前目录下的gorm子目录），分析的语言（go），以及db文件的存储路径（放置在当前目录下的/db/gorm）。执行该命令之后，竟会生成一份db文件，该文件存储着代码仓库的结构化数据，之后的分析就是针对这份数据进行。"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2023-11-23T03:46:32.220317Z",
+     "start_time": "2023-11-23T03:46:12.785705Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "!sparrow database create --source-root gorm --data-language-type go --output ./db/gorm"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "STEP 2: 使用Godel分析语言分析db文件。在本教程中，可以点击代码左侧的执行按钮，直接运行分析脚本。在命令行中，你可以使用 `sparrow query run` 命令来执行查询脚本，具体可以使用`sparrow query run -h` 来获取详细参数信息。"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "<b>示例</b> 查询 [gorm](https://github.com/go-gorm/gorm.git) 的文件代码复杂度信息。\n",
+    "\n",
+    "第一行通过内核魔法命令指定分析的db路径，后面写查询文件代码复杂度Godel脚本。"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%db ./db/gorm\n",
+    "// script\n",
+    "use coref::go::*\n",
+    "\n",
+    "fn default_db() -> GoDB {\n",
+    "    return GoDB::load(\"coref_go_src.db\")\n",
+    "}\n",
+    "\n",
+    "/**\n",
+    " * @param name: 文件名\n",
+    " * @param func: 函数名\n",
+    " * @param cmplx: 函数圈复杂度\n",
+    " * @param sl,el,sc,ec: 函数位置信息，依次为函数起始行，结束行\n",
+    " */\n",
+    "fn out(name: string, func: string, cmplx: int, sl: int, el: int) -> bool {\n",
+    "    for(f in GoFile(default_db()), function in Function(default_db())) {\n",
+    "        if ((!f.isAutoGenereatedFile()) &&\n",
+    "            f.key_eq(function.getBelongsFile()) &&\n",
+    "            name = f.getName() &&\n",
+    "            func = function.getName() &&\n",
+    "            cmplx = function.getCyclomaticComplexity() &&\n",
+    "            sl = function.getLocation().getStartLineNumber() &&\n",
+    "            el = function.getLocation().getEndLineNumber()) {\n",
+    "            return true\n",
+    "        }\n",
+    "    }\n",
+    "}\n",
+    "\n",
+    "fn main() {\n",
+    "    output(out())\n",
+    "}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "保存上一次运行的 query 结果保存到一个JSON文件"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%save_to ./query.json"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "STEP 3: 好了，你可以针对分析生成的结果，进行进一步的代码分析了，比如你可以结合pandas库，使用刚刚生成的 query.json 实现最大函数复杂度的排序查询："
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2023-11-23T03:54:56.998681Z",
+     "start_time": "2023-11-23T03:54:56.976694Z"
+    },
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "%%python\n",
+    "import pandas as pd\n",
+    "data = pd.read_json('./query.json')\n",
+    "data.sort_values('cmplx', ascending=False, inplace=True)\n",
+    "top_10 = data.head(10)\n",
+    "print(top_10)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "Enjoy！"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Godel kernel",
+   "language": "rust",
+   "name": "godel-jupyter"
+  },
+  "language_info": {
+   "file_extension": ".gdl",
+   "help_links": [
+    {
+     "text": "Godel kernel Magics",
+     "url": "https://sparrow.alipay.com"
+    }
+   ],
+   "mimetype": "text/rust",
+   "name": "rust",
+   "version": "0.0.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}