lambda-graphs 0.1.4__py3-none-any.whl

lambda_graphs-0.1.4.dist-info/METADATA

@@ -0,0 +1,380 @@
+Metadata-Version: 2.4
+Name: lambda-graphs
+Version: 0.1.4
+Summary: Generate combined multi-code view graphs
+Home-page: https://github.com/PrinOrange/lambda-graphs
+License: Apache-2.0
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: networkx==2.6.3
+Requires-Dist: tree-sitter>=0.22
+Requires-Dist: tree-sitter-c
+Requires-Dist: tree-sitter-cpp
+Requires-Dist: tree-sitter-java
+Requires-Dist: deepdiff>=7.0.0
+Requires-Dist: pydot==1.4.1
+Requires-Dist: typer>=0.9.0
+Requires-Dist: loguru==0.6.0
+Requires-Dist: setuptools>=69.0; python_version >= "3.12"
+Provides-Extra: dev
+Requires-Dist: tqdm; extra == "dev"
+Requires-Dist: pqdm; extra == "dev"
+Requires-Dist: loguru; extra == "dev"
+Requires-Dist: GitPython; extra == "dev"
+Requires-Dist: pandas; extra == "dev"
+Dynamic: license-file
+
+# lambda-graphs: Multi-View Code Representation Tool for C, C++ and Java Source Programs
+
+lambda-graphs aims to generate combined multi-code view graphs that can be used with various types of machine learning models (sequence models, graph neural networks, etc).
+
+Tool Demonstration link: [https://youtu.be/50DvEbenp14](https://youtu.be/50DvEbenp14)
+
+## Overview
+
+`lambda-graphs` is a CLI tool for generating customized source code representations from C and C++ programs. Currently, `lambda-graphs` generates codeviews for C and C++, supporting both method-level and file-level code snippets. `lambda-graphs` can be used to generate over 7 possible combinations of codeviews for both languages, including:
+
+- **AST** (Abstract Syntax Tree)
+- **CFG** (Control Flow Graph)
+- **DFG** (Data Flow Graph)
+- **Combined graphs** (any combination of the above)
+
+`lambda-graphs` is designed to be easily extendable to various programming languages. This is primarily because we use [tree-sitter](https://tree-sitter.github.io/tree-sitter/), a highly efficient incremental parser that supports over 40 languages.
+
+---
+## Setup
+
+There are two ways to set up lambda-graphs: using Docker (recommended for quick usage) or using a Python virtual environment (recommended for development).
+
+### Option 1: Docker Setup (Recommended for Quick Usage)
+
+Docker provides an isolated environment with all dependencies pre-installed.
+
+**1. Build the Docker image:**
+```console
+docker build -t lambda-graphs .
+```
+
+That's it! You're ready to generate graphs using Docker.
+
+### Option 2: Virtual Environment Setup (Recommended for Development)
+
+**1. Create a new virtual environment:**
+```console
+python -m venv .venv
+```
+
+**2. Activate the environment:**
+```console
+source .venv/bin/activate  # On Linux/Mac
+# or
+.venv\Scripts\activate  # On Windows
+```
+
+**3. Install the package in development mode:**
+```console
+pip install -e .
+```
+
+**4. Install GraphViz (Optional - for visualization):**
+
+GraphViz is only required if you want to generate DOT or PNG output files.
+
+**Ubuntu/Debian:**
+```console
+sudo apt install graphviz
+```
+
+**MacOS:**
+```console
+brew install graphviz
+```
+
+**Windows:**
+Download from [graphviz.org](https://graphviz.org/download/)
+
+---
+## Generating Graphs
+
+There are two ways to generate graphs: using Docker or using the CLI directly (after virtual environment setup).
+
+### Option 1: Using Docker
+
+Docker commands mount your current directory to `/work` inside the container, so output files appear in your working directory.
+
+**Single File Analysis:**
+```console
+docker run --rm -v "$(pwd):/work" -w /work lambda-graphs \
+    --lang cpp \
+    --code-file ./examples/single/test_single.cpp \
+    --graphs "ast,cfg,dfg" \
+    --output all
+```
+
+**Folder Analysis (Multi-file Projects):**
+```console
+docker run --rm -v "$(pwd):/work" -w /work lambda-graphs \
+    --lang c \
+    --code-folder ./examples/multi \
+    --combined-name "multi_file_example" \
+    --graphs "cfg,dfg" \
+    --output all
+```
+
+**With Additional Options:**
+```console
+# Generate only JSON output
+docker run --rm -v "$(pwd):/work" -w /work lambda-graphs \
+    --lang c \
+    --code-file ./examples/single/test_single.c \
+    --graphs cfg \
+    --output json
+
+# With collapsed nodes and last-def tracking
+docker run --rm -v "$(pwd):/work" -w /work lambda-graphs \
+    --lang c \
+    --code-file ./examples/single/test_single.c \
+    --graphs "ast,dfg" \
+    --collapsed \
+    --last-def \
+    --output all
+```
+
+### Option 2: Using Example Scripts
+
+The `examples/scripts/` folder contains ready-to-use bash scripts that automatically build the Docker image and run lambda-graphs on a target file or folder, generating CFG, DFG, and AST outputs. Each script handles the build, graph generation, and output file renaming in one step.
+
+To run a script, make it executable and execute it from the repository root:
+
+```console
+chmod +x examples/scripts/single_test_single.sh
+./examples/scripts/single_test_single.sh
+```
+
+Output files will appear in the `output/` directory, named after the source file and view (e.g. `test_single_cfg.png`, `test_single_dfg.json`).
+
+---
+
+### Option 3: Using CLI Directly
+
+After setting up via virtual environment, use the `lambda-graphs` command directly.
+
+**Output Location:** All generated files (JSON, DOT, PNG) are saved to the `output/` directory in your current working directory. The directory is created automatically if it doesn't exist.
+
+The attributes and options supported by the CLI are well documented and can be viewed by running:
+```console
+lambda-graphs --help
+```
+
+**Single File Analysis:**
+
+Generate a combined CFG and DFG graph for a C++ file:
+```console
+lambda-graphs --lang "cpp" --code-file ./test.cpp --graphs "cfg,dfg"
+```
+
+Generate an AST for a C file with output in JSON format:
+```console
+lambda-graphs --lang "c" --code-file ./example.c --graphs "ast" --output "json"
+```
+
+**Folder Analysis (Multi-file Projects):**
+
+lambda-graphs can analyze entire projects by combining multiple source files from a folder:
+
+```console
+lambda-graphs --lang "c" --code-folder ./project/src --graphs "cfg,dfg" --output "json"
+```
+
+This will:
+1. Recursively scan the folder for all `.c` and `.h` files
+2. Combine them into a single temporary file (preserving includes, declarations, definitions)
+3. Generate the requested codeviews from the combined source
+4. Output results to the `output/` directory
+
+You can customize the combined output file name:
+```console
+lambda-graphs --lang "cpp" --code-folder ./mylib --combined-name "myproject" --graphs "ast,cfg"
+```
+
+**Inline Code Analysis:**
+
+You can also analyze code snippets directly without a file:
+```console
+lambda-graphs --lang "c" --code "int main() { int x = 5; return x; }" --graphs "ast,cfg"
+```
+
+**Additional CLI Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--output` | Output format: `json`, `dot`, or `all` (dot also generates PNG). Default: `dot` |
+| `--collapsed` | Collapse duplicate variable nodes into a single node in AST |
+| `--last-def` | Add last definition information to DFG edges (shows where variables were last defined) |
+| `--blacklisted` | Comma-separated list of AST node types to exclude from the graph |
+
+**Flag-Codeview Compatibility:**
+
+| Flag | AST | CFG | DFG |
+|------|:---:|:---:|:---:|
+| `--collapsed` | ✓ | ✗ | ✗ |
+| `--blacklisted` | ✓ | ✗ | ✗ |
+| `--last-def` | ✗ | ✗ | ✓ |
+| `--last-use` | ✗ | ✗ | ✓ |
+
+**Examples:**
+
+```console
+# Generate all output formats (DOT, JSON, PNG)
+lambda-graphs --lang "c" --code-file test.c --graphs "cfg" --output "all"
+
+# Collapse duplicate variable nodes in DFG
+lambda-graphs --lang "cpp" --code-file test.cpp --graphs "ast" --collapsed
+
+# Add last definition tracking to DFG
+lambda-graphs --lang "c" --code-file test.c --graphs "dfg" --last-def
+
+# Exclude specific AST node types
+lambda-graphs --lang "c" --code-file test.c --graphs "ast,cfg" --blacklisted "comment,string_literal"
+```
+
+---
+## Limitations
+
+While `lambda-graphs` provides _method-level_ and _file-level_ support for both C and C++, it's important to note the following limitations and known issues:
+
+### General Limitations
+- **Syntax Errors in Code**: To ensure accurate codeviews, the input code must be free of syntax errors. Code with syntax errors may not be correctly parsed and displayed in the generated codeviews. Note that the code does not need to be compilable, only syntactically valid.
+
+### C++ Specific Limitations
+In addition to the general limitations, the tool has the following limitations specific to C++:
+
+- **Limited Template Metaprogramming Support**: Complex template metaprogramming patterns may not be fully captured in the generated codeviews.
+
+- **Partial Preprocessor Directive Support**: Preprocessor directives (e.g., `#define`, `#ifdef`) are parsed but not fully processed. Conditional compilation may not be accurately reflected in the codeviews.
+
+- **Limited Support for Advanced C++ Features**: Some advanced C++ features such as:
+  - Complex inheritance hierarchies
+  - Multiple inheritance with virtual functions
+  - Template specializations
+  - SFINAE patterns
+  - Concepts (C++20)
+
+  may not be fully represented in the generated codeviews.
+
+---
+
+## Output Examples
+
+### Example 1: C++ Function Pointers and Control Flow
+
+**CLI Command**:
+
+```bash
+lambda-graphs --lang "cpp" --code-file paper_assets/function_pointers.cpp --graphs "cfg,dfg"
+```
+---
+
+**C++ Code Snippet** ([function_pointers.cpp](paper_assets/function_pointers.cpp)):
+
+```cpp
+#include <iostream>
+void f1(int times) {
+    if(!times)
+        return;
+    std::cout << "In f1()\n";
+    f1(times-1);
+}
+void f2() {
+    std::cout << "In f2()\n";
+}
+int main() {
+    void (*fptr_1)(int);
+    void (*fptr_2)(void);
+    fptr_1 = &f1;
+    fptr_2 = &f2;
+
+    int var = 0;
+    std::cin >> var;
+    (var > 0) ? fptr_1(3) : fptr_2();
+}
+```
+---
+
+**Generated Codeview**:
+
+![C++ Function Pointers Example](paper_assets/function_pointers_cfg_dfg.png)
+
+---
+
+### Example 2: C++ Class with Pass-by-Reference
+
+**CLI Command**:
+
+```bash
+lambda-graphs --lang "cpp" --code-file paper_assets/pass_by_reference.cpp --graphs "cfg,dfg"
+```
+---
+
+**C++ Code Snippet** ([pass_by_reference.cpp](paper_assets/pass_by_reference.cpp)):
+
+```cpp
+#include <iostream>
+
+class TestClass {
+public:
+    int x;
+    TestClass(int _x) {
+        x = _x + 20;
+    }
+    void f1(int& a) {
+        a += 100;
+        a -= x;
+    }
+};
+int main() {
+    TestClass obj(30);
+    int k = 0;
+    obj.f1(k);
+    std::cout << k; // prints 50
+    return 0;
+}
+```
+---
+
+**Generated Codeview**:
+
+![C++ Class Example](paper_assets/pass_by_reference_cfg_dfg.png)
+
+---
+
+## Code Organization
+
+The code is structured in the following way:
+
+1. **Preprocessing** (`src/lambda_graphs/utils/`): The `multi_file_merger.py` module combines multiple source files from a folder into a single file for analysis.
+
+2. **Parsing** (`src/lambda_graphs/tree_parser/`): For each code-view, first the source code is parsed using the tree-sitter parser. The Parser and ParserDriver are implemented with various functionalities commonly required by all code-views. Language-specific features are further developed in the language-specific parsers (`c_parser.py`, `cpp_parser.py`).
+
+3. **Codeview Generation** (`src/lambda_graphs/codeviews/`): This directory contains the core logic for the various codeviews:
+   - `AST/` - Abstract Syntax Tree (language-agnostic)
+   - `CFG/` - Control Flow Graph (language-specific: `CFG_c.py`, `CFG_cpp.py`)
+   - `DFG/` - Data Flow Graph (language-agnostic)
+   - `combined_graph/` - Combines multiple codeviews into a single graph
+
+4. **CLI Entry Point** (`src/lambda_graphs/cli.py`): The CLI implementation using Typer. The drivers can also be directly imported and used as a Python package.
+
+5. **Node Definitions** (`src/lambda_graphs/utils/`): `c_nodes.py` and `cpp_nodes.py` define AST node type categorizations used throughout the codebase.
+
+---
+
+## Acknowledgments
+
+This tool builds upon the tree-sitter parsing framework and is inspired by research on source code representation learning for AI-driven software engineering tasks.

lambda_graphs-0.1.4.dist-info/RECORD

@@ -0,0 +1,45 @@
+lambda_graphs/__init__.py,sha256=S2v6SCVa7xEjnOZQneNVt1DyVOya1CBRAxz2bxJfqkg,503
+lambda_graphs/__main__.py,sha256=pqqaM3Xr6Ypfhy0Y8xUxkPT-hKy9L_Erl9X08cZHT3o,106
+lambda_graphs/cli.py,sha256=HsUd68wBhuYkGaqZNJnIpBRmDGyeFCnMy_MzTjGOKm0,5557
+lambda_graphs/codeviews/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lambda_graphs/codeviews/AST/AST.py,sha256=1CQyadl9_3lRK5qkX-UzBdmzn_6Q9fahdluGELZrLAQ,4270
+lambda_graphs/codeviews/AST/AST_driver.py,sha256=rmhodB78EeUhq04o0Vy81fY93FwT4vS7UgiF0JOWClw,1138
+lambda_graphs/codeviews/AST/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lambda_graphs/codeviews/CFG/CFG.py,sha256=odnnX7UXu1-iTmJoZ6V_76tU3Dw4qi9cwxws4x744sc,1528
+lambda_graphs/codeviews/CFG/CFG_c.py,sha256=4styP_yI9SmHROER_PKCPcK4FiNJpXm5cySGtYxVFlA,48545
+lambda_graphs/codeviews/CFG/CFG_cpp.py,sha256=_0gXWOJtTgIHw64Mav2k5WVNle-9P55m01UdSxFMZBE,252466
+lambda_graphs/codeviews/CFG/CFG_driver.py,sha256=iYqxFwdob634qm0CDjXZM19W6veFB7n03ErzXaolDtQ,1334
+lambda_graphs/codeviews/CFG/CFG_java.py,sha256=2DZBiwdev8MpCb1Eu6NGmnIpweRM_ZpeiPzWwQBF5f0,85722
+lambda_graphs/codeviews/CFG/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lambda_graphs/codeviews/CST/CST_driver.py,sha256=1LLax-qYbl_63DDnCnQo8qeLOoFDc5PqjXuIFINa-bs,2387
+lambda_graphs/codeviews/CST/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lambda_graphs/codeviews/DFG/DFG_driver.py,sha256=iLi2H94TQFN-trXxpfaVcz7NzMeGc-zq3vdHs1L9rGs,1333
+lambda_graphs/codeviews/DFG/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lambda_graphs/codeviews/SDFG/SDFG.py,sha256=fvIhr6uUuYBmUkrFae7x8b88H-tuuZGINaundZab10E,4304
+lambda_graphs/codeviews/SDFG/SDFG_c.py,sha256=2SXLh4flQ_7aHFAqvE6xdMqZ8HY07aqmDNNMADqvBVE,80365
+lambda_graphs/codeviews/SDFG/SDFG_cpp.py,sha256=PsQcTVNyFziXEKgAosiL2Uq6rHORBUSr-LwVLTGhSZU,158990
+lambda_graphs/codeviews/SDFG/SDFG_java.py,sha256=ug2IHsd0D5dfIvQsCuS2PROft703b65AJeyUyYC0_zw,67012
+lambda_graphs/codeviews/SDFG/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lambda_graphs/codeviews/combined_graph/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lambda_graphs/codeviews/combined_graph/combined_driver.py,sha256=e_GjoRfl5IcEcQ56JGp3Jn71sJkI2S4CKysyS70lH5M,5490
+lambda_graphs/tree_parser/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lambda_graphs/tree_parser/c_parser.py,sha256=ekvA_LTZjalNvzW7LyG27hZOLRh6zzIo-ypR8kCmyrg,21926
+lambda_graphs/tree_parser/cpp_parser.py,sha256=CZ6q0_O5t09HAIBtlfPp1MhUQwbwW49rmaoMCuN0lek,15617
+lambda_graphs/tree_parser/custom_parser.py,sha256=NBS7ZvBh-RAG3RNUlm4iYFWIOggeDQNsPGvGcGuIwvw,2118
+lambda_graphs/tree_parser/java_parser.py,sha256=R7La6BBZfhn7gRNRzwOC2MP1gpnInC0SIi7UenR5MZI,10835
+lambda_graphs/tree_parser/parser_driver.py,sha256=tsDpef6KgWeEpsqoou3vHf9y_ivprULV7SWJX4rLC9Y,1792
+lambda_graphs/utils/DFG_utils.py,sha256=ESVGnmci7fE4vuuoCYI4KViW5ODZrvNLSZxOt8W26o0,1647
+lambda_graphs/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lambda_graphs/utils/c_nodes.py,sha256=_01qu1oRMS_bdsl9KNTfl89doQ21qqZdyXNz8yBaFpU,14754
+lambda_graphs/utils/cpp_nodes.py,sha256=1LhL78EOHjGyDQnCi1Tb6bPfpUEAFb_TGJU_GVfh7vg,49242
+lambda_graphs/utils/java_nodes.py,sha256=mx3zlhMzZTv0vDvvxKWOagfL1YcopMWXga-OEiJHS_s,27637
+lambda_graphs/utils/multi_file_merger.py,sha256=w4n5YpO9-m87wT8vX93L47mDnqW2pGHo_MxV7E2Vhqw,15623
+lambda_graphs/utils/postprocessor.py,sha256=wVdKWhZ1EyFJjkiRm4V9i2ToOLsiz0hEbqudKRAbPKQ,2583
+lambda_graphs/utils/preprocessor.py,sha256=tNNvCqBrXkfIEt4dj31Zv3eYrWcdxA4d0emdi0BBJeQ,1991
+lambda_graphs/utils/src_parser.py,sha256=KI8jp1rGy92FDU6ZSAyvAlTXIqRvwaBU8Nyk1_PLQc0,630
+lambda_graphs-0.1.4.dist-info/licenses/LICENSE,sha256=A4IQBtKltZRdmeznEO-WkeUNgar9pYrAnnqgwuPM7eo,1078
+lambda_graphs-0.1.4.dist-info/METADATA,sha256=lsLn3OI8ztoYrjIUkmtcH60WMdXeKuN_uoGwWMsY8ww,12293
+lambda_graphs-0.1.4.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+lambda_graphs-0.1.4.dist-info/entry_points.txt,sha256=hELYD6w17o_ccUXd3p97Dx8-aBj123HLc1to4otGONo,56
+lambda_graphs-0.1.4.dist-info/top_level.txt,sha256=BeOCfsbh498OkGRd1Bc8Z5HnUp_C3KfpOJ7u_dbd9Qk,14
+lambda_graphs-0.1.4.dist-info/RECORD,,

lambda_graphs-0.1.4.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

lambda_graphs-0.1.4.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lambda-graphs = lambda_graphs.cli:app

lambda_graphs-0.1.4.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaid Monwar Chowdhury
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lambda_graphs-0.1.4.dist-info/top_level.txt

@@ -0,0 +1 @@
+lambda_graphs