# ScubaTrace
[](https://pypi.org/project/scubatrace/)
[](https://sunbk201.github.io/ScubaTrace/)
[](https://github.com/SunBK201/ScubaTrace/actions/workflows/test.yml)
[](https://github.com/SunBK201/ScubaTrace/actions/workflows/github-code-scanning/codeql)
[](https://github.com/SunBK201/ScubaTrace/blob/master/LICENSE)
Source level code analysis toolkit.
<br>
<img src="https://sunbk201.oss-cn-beijing.aliyuncs.com/img/ScubaTrace.png" width="61.8%">
ScubaTrace is a code analysis toolkit that leverages tree-sitter and LSP (Language Server Protocol) to provide parsing, analysis, and context extraction capabilities for multiple programming languages.
Unlike most traditional static analysis tools that rely on compilation to extract Intermediate Representation (IR) for code analysis, ScubaTrace delivers analysis capabilities even when code repositories are incomplete or unable to compile. This resilience makes it particularly valuable for scenarios where traditional analysis approaches would fail, enabling developers and security researchers to gain insights from code that might otherwise be inaccessible to conventional static analysis methodologies.
ScubaTrace serves as a portable analysis solution for IDE development, AI-powered coding tools, and SAST (Static Application Security Testing).
# Features
- **Multi-Language Support**
- **No Need To Compile**
- **Statement-Based AST Abstraction**
- **Call Graph**
- **Control Flow Graph**
- **Data/Control Dependency Graph**
- **References Inference**
- **CPG Based Multi-Granularity Slicing**
- **Built on Tree-sitter and LSP**
# Install
```bash
pip install scubatrace
```
> [!NOTE]
> If you encounter a `pygraphviz` installation failure during `pip install`, you need to install the Graphviz development package. You can install it using the following command:
>
> ```bash
> # For Debian/Ubuntu
> apt install libgraphviz-dev
> # For macOS, Ref: https://pygraphviz.github.io/documentation/stable/install.html#homebrew
> brew install graphviz
> ```
# Supported Languages
ScubaTrace supports multiple programming languages, including:
| Language | Language Server | Tree-sitter Parser | Maturity |
| ---------- | -------------------------- | ---------------------- | -------- |
| C/C++ | clangd | tree-sitter-cpp | High |
| Java | Eclipse JDT LS | tree-sitter-java | High |
| Python | Pyright | tree-sitter-python | High |
| JavaScript | typescript-language-server | tree-sitter-javascript | Medium |
| Go | gopls | tree-sitter-go | Medium |
| Rust | Rust Analyzer | tree-sitter-rust | Medium |
| Ruby | Solargraph | tree-sitter-ruby | Low |
| Swift | SourceKit-LSP | tree-sitter-swift | Low |
| C# | OmniSharp | tree-sitter-c-sharp | Low |
| PHP | phpactor | tree-sitter-php | Low |
# Usage
```python
import scubatrace
# Initialize a ScubaTrace Project
# language can be set to one of the following:
# scubatrace.language.[C, JAVA, PYTHON, JAVASCRIPT, GO, RUST, RUBY, PHP, CSHARP, SWIFT]
project = scubatrace.Project.create("path/to/your/codebase", language=scubatrace.language.C)
```
> [!NOTE]
> Incomplete or broken codebases may cause parsing errors that could result in inaccurate analysis results.
```python
# Get a file from the project
file = project.files["relative/path/to/your/file.c"]
# Get a function from the file
function = file.functions[0]
print(f"Function Name: {function.name}")
print(f"Source Code: {function.text}")
# Get the function's callers and print their names and callsites
callers = function.callers
for caller, callsites in callers.items():
print(f"Caller: {caller.name}")
for callsite in callsites:
print(f" Callsite: {callsite.text}")
# Get the first statement in file line
statement = file.statements_by_line(10)[0]
# Find the pre/post statements in control flow
pre_statements_in_control_flow = statement.pre_controls
post_statements_in_control_flow = statement.post_controls
# Get the first variable in statement
variable = statement.variables[0]
print(f"Variable: {variable.name}")
# Find the definitions/references of a variable
definitions = variable.definitions
references = variable.references
# Find the pre/post data dependencies of a variable
pre_data_dependencies = variable.pre_data_dependents
post_data_dependencies = variable.post_data_dependents
# Perform slicing in a function based on specified lines
# Configure the slicing with control depth and data-dependent depth
criteria_lines = [10, 12, 18]
sliced_statements = function.slice_by_lines(
lines=criteria_lines, control_depth=5, data_dependent_depth=8
)
# Get tree-sitter node in a file/function/statement
file_node = file.node
function_node = function.node
statement_node = statement.node
```
For more detailed information, refer to the [Documentation](https://sunbk201.github.io/ScubaTrace/).
Raw data
{
"_id": null,
"home_page": null,
"name": "scubatrace",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "codebase, parsing, ast, analysis",
"author": null,
"author_email": "SunBK201 <sunbk201gm@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/2e/21/fffc1bb0db9b49649325cc45e1acfe10bd3d6cd24bea5dbd2fa99a4c192e/scubatrace-1.0.2.tar.gz",
"platform": null,
"description": "# ScubaTrace\n\n[](https://pypi.org/project/scubatrace/)\n[](https://sunbk201.github.io/ScubaTrace/)\n[](https://github.com/SunBK201/ScubaTrace/actions/workflows/test.yml)\n[](https://github.com/SunBK201/ScubaTrace/actions/workflows/github-code-scanning/codeql)\n[](https://github.com/SunBK201/ScubaTrace/blob/master/LICENSE)\n\nSource level code analysis toolkit.\n\n<br>\n<img src=\"https://sunbk201.oss-cn-beijing.aliyuncs.com/img/ScubaTrace.png\" width=\"61.8%\">\n\nScubaTrace is a code analysis toolkit that leverages tree-sitter and LSP (Language Server Protocol) to provide parsing, analysis, and context extraction capabilities for multiple programming languages.\n\nUnlike most traditional static analysis tools that rely on compilation to extract Intermediate Representation (IR) for code analysis, ScubaTrace delivers analysis capabilities even when code repositories are incomplete or unable to compile. This resilience makes it particularly valuable for scenarios where traditional analysis approaches would fail, enabling developers and security researchers to gain insights from code that might otherwise be inaccessible to conventional static analysis methodologies.\n\nScubaTrace serves as a portable analysis solution for IDE development, AI-powered coding tools, and SAST (Static Application Security Testing).\n\n# Features\n\n- **Multi-Language Support**\n- **No Need To Compile**\n- **Statement-Based AST Abstraction**\n- **Call Graph**\n- **Control Flow Graph**\n- **Data/Control Dependency Graph**\n- **References Inference**\n- **CPG Based Multi-Granularity Slicing**\n- **Built on Tree-sitter and LSP**\n\n# Install\n\n```bash\npip install scubatrace\n```\n\n> [!NOTE]\n> If you encounter a `pygraphviz` installation failure during `pip install`, you need to install the Graphviz development package. You can install it using the following command:\n>\n> ```bash\n> # For Debian/Ubuntu\n> apt install libgraphviz-dev\n> # For macOS, Ref: https://pygraphviz.github.io/documentation/stable/install.html#homebrew\n> brew install graphviz\n> ```\n\n# Supported Languages\n\nScubaTrace supports multiple programming languages, including:\n\n| Language | Language Server | Tree-sitter Parser | Maturity |\n| ---------- | -------------------------- | ---------------------- | -------- |\n| C/C++ | clangd | tree-sitter-cpp | High |\n| Java | Eclipse JDT LS | tree-sitter-java | High |\n| Python | Pyright | tree-sitter-python | High |\n| JavaScript | typescript-language-server | tree-sitter-javascript | Medium |\n| Go | gopls | tree-sitter-go | Medium |\n| Rust | Rust Analyzer | tree-sitter-rust | Medium |\n| Ruby | Solargraph | tree-sitter-ruby | Low |\n| Swift | SourceKit-LSP | tree-sitter-swift | Low |\n| C# | OmniSharp | tree-sitter-c-sharp | Low |\n| PHP | phpactor | tree-sitter-php | Low |\n\n# Usage\n\n```python\nimport scubatrace\n\n# Initialize a ScubaTrace Project\n# language can be set to one of the following:\n# scubatrace.language.[C, JAVA, PYTHON, JAVASCRIPT, GO, RUST, RUBY, PHP, CSHARP, SWIFT]\nproject = scubatrace.Project.create(\"path/to/your/codebase\", language=scubatrace.language.C)\n```\n\n> [!NOTE]\n> Incomplete or broken codebases may cause parsing errors that could result in inaccurate analysis results.\n\n```python\n# Get a file from the project\nfile = project.files[\"relative/path/to/your/file.c\"]\n\n# Get a function from the file\nfunction = file.functions[0]\nprint(f\"Function Name: {function.name}\")\nprint(f\"Source Code: {function.text}\")\n\n# Get the function's callers and print their names and callsites\ncallers = function.callers\nfor caller, callsites in callers.items():\n print(f\"Caller: {caller.name}\")\n for callsite in callsites:\n print(f\" Callsite: {callsite.text}\")\n\n# Get the first statement in file line\nstatement = file.statements_by_line(10)[0]\n\n# Find the pre/post statements in control flow\npre_statements_in_control_flow = statement.pre_controls\npost_statements_in_control_flow = statement.post_controls\n\n# Get the first variable in statement\nvariable = statement.variables[0]\nprint(f\"Variable: {variable.name}\")\n\n# Find the definitions/references of a variable\ndefinitions = variable.definitions\nreferences = variable.references\n\n# Find the pre/post data dependencies of a variable\npre_data_dependencies = variable.pre_data_dependents\npost_data_dependencies = variable.post_data_dependents\n\n# Perform slicing in a function based on specified lines\n# Configure the slicing with control depth and data-dependent depth\ncriteria_lines = [10, 12, 18]\nsliced_statements = function.slice_by_lines(\n lines=criteria_lines, control_depth=5, data_dependent_depth=8\n)\n\n# Get tree-sitter node in a file/function/statement\nfile_node = file.node\nfunction_node = function.node\nstatement_node = statement.node\n```\n\nFor more detailed information, refer to the [Documentation](https://sunbk201.github.io/ScubaTrace/).\n",
"bugtrack_url": null,
"license": null,
"summary": "Next-generation codebase analysis toolkit.",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://sunbk201.github.io/ScubaTrace",
"Issues": "https://github.com/SunBK201/ScubaTrace/issues"
},
"split_keywords": [
"codebase",
" parsing",
" ast",
" analysis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "995bf178229713abb2dc9097fcafa63437ca6c9b3b42c3fe327edf3f19793c6d",
"md5": "a19805eaf118741bfd6d58d1a93accb8",
"sha256": "795d42695bf00fbd13618ad6f7e67f3f0d6c0d51906c748cfe01afa0cb75dacc"
},
"downloads": -1,
"filename": "scubatrace-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a19805eaf118741bfd6d58d1a93accb8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 67307,
"upload_time": "2025-08-01T18:46:43",
"upload_time_iso_8601": "2025-08-01T18:46:43.498622Z",
"url": "https://files.pythonhosted.org/packages/99/5b/f178229713abb2dc9097fcafa63437ca6c9b3b42c3fe327edf3f19793c6d/scubatrace-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2e21fffc1bb0db9b49649325cc45e1acfe10bd3d6cd24bea5dbd2fa99a4c192e",
"md5": "b79fea0a3aa6e3a8de52750033f96e9e",
"sha256": "05df07d09394c8c9685c4f8761c7bf0696d0d631127952c1edb5bbe6e5d17894"
},
"downloads": -1,
"filename": "scubatrace-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "b79fea0a3aa6e3a8de52750033f96e9e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 53016,
"upload_time": "2025-08-01T18:46:45",
"upload_time_iso_8601": "2025-08-01T18:46:45.014870Z",
"url": "https://files.pythonhosted.org/packages/2e/21/fffc1bb0db9b49649325cc45e1acfe10bd3d6cd24bea5dbd2fa99a4c192e/scubatrace-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-01 18:46:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SunBK201",
"github_project": "ScubaTrace",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "tree_sitter",
"specs": [
[
"==",
"0.24.0"
]
]
},
{
"name": "tree_sitter_cpp",
"specs": [
[
"==",
"0.23.4"
]
]
},
{
"name": "tree_sitter_java",
"specs": [
[
"==",
"0.23.5"
]
]
},
{
"name": "tree_sitter_python",
"specs": [
[
"==",
"0.23.6"
]
]
},
{
"name": "tree_sitter_javascript",
"specs": [
[
"==",
"0.23.1"
]
]
},
{
"name": "tree_sitter_c_sharp",
"specs": [
[
"==",
"0.23.1"
]
]
},
{
"name": "tree_sitter_go",
"specs": [
[
"==",
"0.23.4"
]
]
},
{
"name": "tree_sitter_php",
"specs": [
[
"==",
"0.23.11"
]
]
},
{
"name": "tree_sitter_ruby",
"specs": [
[
"==",
"0.23.1"
]
]
},
{
"name": "tree_sitter_rust",
"specs": [
[
"==",
"0.23.2"
]
]
},
{
"name": "tree_sitter_swift",
"specs": [
[
"==",
"0.0.1"
]
]
},
{
"name": "networkx",
"specs": [
[
">=",
"3.3"
]
]
},
{
"name": "pygraphviz",
"specs": [
[
">=",
"1.13"
]
]
},
{
"name": "pydot",
"specs": [
[
">=",
"3.0.3"
]
]
},
{
"name": "chardet",
"specs": [
[
">=",
"5.2.0"
]
]
},
{
"name": "scubalspy",
"specs": [
[
">=",
"0.0.19"
]
]
}
],
"lcname": "scubatrace"
}
JSON
