Metadata-Version: 2.4
Name: codesci
Version: 0.0.1
Summary: A lightweight Code Property Graph generator based on Tree-Sitter
Author: CodeSCI Contributors
License: MIT
Project-URL: Homepage, https://github.com/PrinOrange/codesci
Project-URL: Repository, https://github.com/PrinOrange/codesci
Project-URL: Issues, https://github.com/PrinOrange/codesci/issues
Keywords: code-property-graph,cpg,ast,cfg,dfg,tree-sitter,program-analysis,static-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tree-sitter>=0.21.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: isort>=5.12; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

<img src="./assets/banner.png" style="width:100%" />

**A lightweight Code Property Graph Generator**

Program analysis commonly relies on tools such as [Joern](https://github.com/joernio/joern) and [CodeQL](https://codeql.github.com/) to generate Code Property Graphs (CPGs). However, these tools are often heavyweight and require complex configurations, making them less user-friendly. In particular, they are difficult to scale for processing large-scale datasets in software engineering and machine learning research. 

To address this limitation, we propose CodeSCI, a lightweight code property graph generator based on Tree-Sitter as science research infrastructure.

> This project is under the development. \
> WELCOME TO PR!

## Getting Start

Here are supports across languages and graphs.

| Language | Supported Graphs | Maturity |
| -------- | ---------------- | -------- |
| C        | AST,CFG,DFG      |          |
| C++      | AST,CFG,DFG      |          |

### How it works

CodeSCI first parses source code into an Abstract Syntax Tree (AST) with the [Tree-Sitter](https://tree-sitter.github.io/tree-sitter/) and decomposes it into fine-grained syntactic elements (tokens). Based on lightweight static analysis rules, CodeSCI further aggregates and transforms these elements to infer program relationships and construct the final Code Property Graph (CPG).


### Limitations

CodeSCI is designed for analyzing individual code snippets and currently does NOT support repository-level or multi-file program analysis.

Of course, depending on practical needs and future development, we may consider adding support for repository-level and multi-file code analysis in future versions if possible.

In addition, CodeSCI focuses solely on syntactic parsing. It can process any syntactically valid code, regardless of whether the underlying program logic is semantically correct.

### Usage

CodeSCI is designed as a lightweight program analysis library that exposes a programming API for integration into downstream applications.

Install the CodeSCI,

```bash
pip install codesci
```

For convenience and lightweight purposes, CodeSCI only accepts code strings as input. All generated program property graphs are networkx graph objects, which you can serialize into text format or deserialize into networkx objects. Here is the bubble sort code in C language, and transform it into different CPGs.

```python
from codesci import toAST, toCFG, toDFG
sourceCode = """
#include <stdio.h>
int main() {
  int a[] = {5,2,8,1,9}, n = 5;
  for (int i = 0; i < n-1; i++)
      for (int j = 0; j < n-1-i; j++)
          if (a[j] > a[j+1]) {
              int t = a[j];
              a[j] = a[j+1];
              a[j+1] = t;
          }
  for (int i = 0; i < n; i++) printf("%d ", [i]);
  return 0;
}
"""
# Here, the following ast, cfg, dfg are networkx objects.
ast = toAST(code=sourceCode, language="c") # abstract syntax tree
cfg = toCFG(code=sourceCode, language="c") # control flow graph
dfg = toDFG(code=sourceCode, language="c") # data flow graph
```

## Contribution

Contributions are always welcome! We appreciate constructive contributions of all kinds, such as adding support for new programming languages, implementing additional graph types, or improving existing features.

## License

This project is under the MIT license.
