codesacan (Cocodedk)

CodeScan：集成Neo4j的Python静态代码分析器

网站

• 英语
• 波斯语

概述

scanner.py 是一个静态代码分析工具，旨在解析Python源代码，提取结构和调用图信息，并将其存储在Neo4j图数据库中。该工具可通过环境变量进行高度配置，旨在使用具有GraSS样式的Neo4j浏览器进行高级代码库探索、依赖性分析和可视化。

特性

• 基于AST的解析：使用Python ast 用于遍历和分析源代码文件的模块。
• 类和函数提取：标识所有类、独立函数和类方法，包括它们的文件位置和行号。
• 调用图构造：检测函数调用，包括参数名称/值，并创建 CALLS 图中的关系。
• 节点标签：为节点分配多个标签以进行高级可视化（例如。， :Function, :MainFunction, :ClassFunction, :ReferenceFunction).
• 参考节点处理：为扫描代码库中未定义的调用函数创建特殊节点。
• 测试检测和覆盖：自动识别测试组件并建立测试覆盖关系：

- 用适当的标记标记测试文件、函数和类(:Test, :TestFunction, :TestClass) - 创建 TESTS 测试代码与其测试的生产代码之间的关系 - 针对不同项目结构和测试框架的可配置测试模式

• 可配置的目录遍历：跳过指定的目录（例如virtualenvs， .git，测试文件夹）以实现高效扫描。
• 相对路径存储：存储相对于项目目录的文件路径，以提高可移植性。
• 基于环境的配置：从读取Neo4j连接和项目设置 .env 文件。
• GraSS兼容：专为与Neo4j浏览器的GraSS样式表一起使用而设计，用于自定义节点/关系着色。
• 进度可视化：使用tqdm进度条显示扫描进度和元素发现。
• 统计数据收集：收集并显示有关扫描代码库的详细统计信息。
• 详细程度控制：提供安静和详细的模式来控制输出细节。

设置您的环境

环境文件设置

CodeScan使用 .env 配置文件。按照以下步骤进行设置：

1. 复制示例环境文件以创建您自己的：

   cp example.env .env

1. 编辑 .env 文件并更新 PROJECT_DIR 变量指向要扫描的项目的路径：

   PROJECT_DIR=/absolute/path/to/your/project/

例如：

- Linux/macOS： PROJECT_DIR=/home/username/projects/my-python-project/ - 窗户： PROJECT_DIR=C:/Users/username/projects/my-python-project/

1. 根据需要调整其他设置：

- Neo4j连接详细信息（用户名、密码、端口） - 日志选项

环境文件的替代方案

而不是使用 .env 文件，您也可以在运行扫描程序时直接指定项目目录：

python scanner.py --project-dir /path/to/your/project

建筑

1.AST导线测量

• 这 CodeAnalyzer 类子类 ast.NodeVisitor.
• 访问 ClassDef 和 FunctionDef 节点以提取类/函数元数据。
• 访问 Call 节点，以提取调用关系和参数信息。

2.节点和关系创建

• 文件节点：已标记 :File，为特定文件类型添加额外标签：

- :TestFile 用于测试文件 - :ExampleFile 例如文件 - 物业包括 path, type, is_test, is_example

• 类节点：已标记 :Class，属性包括 name, file, line, end_line.
• 功能节点：已标记 :Function，带有附加标签：

- :MainFunction 对于名为的函数 main - :ClassFunction 类内部的方法 - :ReferenceFunction 用于已调用但未定义的函数 - 属性： name, file, line, end_line, is_reference, length

• 常量节点：已标记 :Constant，属性包括 name, value, type, file, line, end_line, scope
• 关系:

- CONTAINS：来自 File 到 Class, Function，或 Constant （文件内容） - CONTAINS：来自 Class 到 Function （班级成员资格） - CALLS：从调用者到被调用者，具有属性 line （呼叫站点）， args （参数名称/值）

3.参考节点处理

• 如果一个函数被调用但未在扫描的代码库中定义 :ReferenceFunction 节点已创建。
• 稍后定义函数时，所有 CALLS 与参考节点的关系被重定向到实际功能节点。

4.测试覆盖率检测

• 测试文件、函数和类根据可配置模式自动识别
• 测试组件收到适当的标签(:Test, :TestFunction, :TestClass)
• TESTS 通过以下方式在测试函数和生产代码之间创建关系：

- 命名模式：名为的测试函数 test_foo 可能测试功能 foo - 进口分析：测试函数通常导入它们测试的模块/函数 - 呼叫分析：测试函数调用的函数可能正在测试中

• 所有检测模式都可以针对不同的项目结构和框架进行配置

5.配置

• 所有连接和项目设置都是从 .env 文件使用 python-dotenv.
• 示例变量：

- NEO4J_USER, NEO4J_PASSWORD, NEO4J_HOST, NEO4J_PORT_BOLT, PROJECT_DIR

• 目录的忽略列表是硬编码的，但可以扩展。

6.使用方法

先决条件

• Python 3.8+
• Neo4j 5.x（推荐使用Docker）
• 安装依赖项：

  pip install -r requirements.txt

运行Neo4j

• 使用Docker Compose启动Neo4j：

  docker-compose up -d

• Neo4j浏览器将在 http://localhost:7400 （或按配置）。

运行扫描仪

• 确保您的 .env 文件已配置（请参阅“设置环境”部分）。
• 运行扫描仪：

  python scanner.py

• 脚本将：

- 清空Neo4j数据库 - 遍历项目目录 - 用类、函数和调用关系填充图形

输出控制

控制扫描仪输出的详细程度：

# Minimal output (only errors)
python scanner.py --quiet

# Detailed output showing all elements found
python scanner.py --verbose

在Neo4j浏览器中可视化

• 使用提供的 .grass 用于自定义节点/关系着色的文件。
• 示例查询：

- MATCH (n) RETURN n （所有节点） - MATCH (n)-[r]->(m) RETURN n, r, m （所有关系） - MATCH (f:Function) WHERE f.line > 100 RETURN f （按行功能） - MATCH ()-[r:CALLS {line: 42}]->() RETURN r （拨打特定线路） - MATCH (f:Function) RETURN f.name, f.file, f.length ORDER BY f.length DESC LIMIT 10 （查找最长函数） - MATCH (f:File)-[:CONTAINS]->(n) RETURN f.path, count(n) ORDER BY count(n) DESC LIMIT 10 （包含大多数元素的文件） - MATCH (f:File)-[:CONTAINS]->(n) WHERE n:Class OR n:Function RETURN f.path, labels(n), count(n) GROUP BY f.path, labels(n) ORDER BY f.path, labels(n) （按类型统计每个文件中的元素数）

高级详细信息

• 参数提取：扫描程序从函数调用中提取参数名和常量值，并将其作为字符串存储在 args 财产 CALLS 关系。
• Dunder方法跳过：特殊方法（例如。， __init__, __str__)为了清楚起见，忽略了。
• 内置和stdlib调用过滤：图中不包括对Python内置模块和标准库模块的调用。
• 错误处理：会报告并跳过语法错误和不可解码的文件。
• 可扩展性：忽略列表、节点/关系属性和标签逻辑可以很容易地扩展到更高级的用例中。

MCP服务器和游标集成

CodeScan包括一个MCP（模型上下文协议）服务器，用于高级代码图查询和与Cursor IDE等工具的集成。

MCP服务器(codescan_mcp_server.py)

此服务器通过MCP协议公开存储在Neo4j中的代码图，使其可供兼容的客户端访问。它提供了列出文件、函数、类、调用关系和未解析引用的工具。

可用工具

CodeScan通过MCP服务器提供各种代码分析工具：

• 基本代码结构

- list_files -列出代码库中的所有文件及其类型 - file_contents -列出特定文件中的所有类、函数和常量 - list_functions -列出特定文件中的函数 - list_classes -列出特定文件中的类

• 调用图分析

- callees -查找由特定函数调用的函数 - callers -查找调用特定函数的函数 - transitive_calls -查找函数之间的路径（一个函数是否最终调用另一个函数） - most_called_functions -列出调用最多的函数 - most_calling_functions -列出调用最多其他函数的函数

• 测试覆盖率分析

- untested_functions -列出未经测试的函数 - untested_classes -列出没有测试的类 - test_coverage_ratio -获取总体测试覆盖率统计数据 - functions_tested_by -列出特定测试文件测试的函数 - tests_for_function -列出特定功能的测试

• 其他分析

- recursive_functions -列出调用自己的函数 - classes_with_no_methods -列出没有任何方法的类 - classes_with_most_methods -列出方法最多的类 - function_call_arguments -列出调用特定函数时使用的参数 - repetitive_constants -查找在多个位置使用的具有相同值的常量 - repetitive_constant_names -查找在多个位置使用的具有相同名称但可能不同值的常量

运行MCP服务器

使用提供的shell脚本启动服务器（确保您的虚拟环境已激活并且Neo4j正在运行）：

./run_mcp_stdio_server.sh

这将使用stdio传输启动MCP服务器，准备与Cursor或其他MCP客户端集成。

游标IDE集成

要将CodeScan的MCP服务器与Cursor IDE一起使用，请将以下内容添加到您的 .cursor/mcp.json （根据需要调整路径）：

{
  "mcpServers": {
    "codescan_neo4j": {
      "command": "/path/to/codescan/run_mcp_stdio_server.sh",
      "args": []
    }
  }
}

配置后，重新启动Cursor并打开MCP工具面板。您应该看到CodeScan的工具（例如。， graph_summary, list_files, list_functions等等）可用于查询您的代码库。

故障排除

• 确保Neo4j正在运行，并且可以使用您的凭据访问 .env 文件。
• 如果工具未出现在Cursor中，请检查服务器日志是否有错误。
• 必须从项目根目录启动服务器，才能正确解析相对路径。

相关文件：

• codescan_mcp_server.py --MCP服务器实现
• run_mcp_stdio_server.sh --启动服务器的Shell脚本

码头工人

docker pull ghcr.io/cocodedk/codesacan:latest
docker run ghcr.io/cocodedk/codesacan:latest

作者

巴巴克·班佩 — cocode.dk | 领英 |

许可证

阿帕奇-2.0 |©2026 科科德 |创建者： 巴巴克·班佩