Skip to content
custom-computing-icPublic

About

No description, website, or topics provided.

Resources

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

Artisan

Artisan is a program analysis and transformation framework designed to make it easy to parse, query, instrument, and rewrite source code using a structured, language-aware representation.

At its core, Artisan treats textual source code as a graph of connected nodes using the libclang library. This enables powerful workflows such as:

  • Static analysis and querying of code structure
  • Source-to-source transformations
  • Program instrumentation and rewriting
  • Building research and production tooling on top of real-world codebases

Artisan is particularly well suited for compiler research, software engineering research, and advanced developer tooling.


Key Ideas

Code as a Graph

Artisan parses source files into a graph-based intermediate representation. Nodes correspond to syntactic and semantic entities (e.g. AST nodes, statements, expressions), and edges encode relationships such as containment, control flow, and data flow.

This representation makes it straightforward to:

  • Traverse code structurally
  • Match complex patterns
  • Apply local or global transformations

Query–Transform Workflow

A typical Artisan workflow looks like this:

  1. Load source code into an Artisan project
  2. Query the graph to find relevant code patterns
  3. Transform or instrument the matched nodes
  4. Unparse the modified graph back into source code

This model scales from small scripts to large multi-file projects.


Features

  • Language-aware parsing and unparsing
  • Graph-based program representation
  • Declarative and imperative querying APIs
  • Source-to-source transformation support
  • Instrumentation hooks
  • Command-line interface for batch processing
  • Designed for extensibility and research experimentation

Installation

Development environment

Create a conda development environment as follows:

conda env create -f environment.yml
# configure environment variables
bash conda/recipe/post-install.sh artisan

To activate the environment:

conda activate artisan

The environment installs Artisan in editable mode.

Use the published Conda package

On Linux x86-64, create an environment with the published package:

conda create -n my-artisan -c ckiddo74 -c conda-forge python=3.12 artisan
conda activate my-artisan

Alternatively, add artisan to your project's environment.yml with the ckiddo74 and conda-forge channels. Choose a Python version supported by the published builds.


Quick Start

Here is a minimal example showing the typical Artisan workflow:

from artisan import *

ast = Ast('hello-world.cpp')

# Query the code graph
for node in sm.query("Function"):
    print(node.name)

You can then apply transformations or instrumentation to the matched nodes and write the modified code back to disk.


Tutorials

Artisan comes with an extensive, hands-on tutorial series located in the tutorial/ directory:

  • intro/ – Core concepts and basic usage
  • intermediate/ – More advanced queries and transformations
  • workflow/ – End-to-end workflows and project structuring
  • runtime/ – Runtime instrumentation and execution support
  • advanced/ – Internal APIs, extensibility, and research use cases

Start here:

cd tutorial

and follow the README.md files in each section.


Tests

With the development environment activated, install pytest and run the tests from the repository root:

python -m pytest tests

The tutorial-based tests use libclang and clang-format. Integration tests also require make and g++; those checks are skipped when the respective tool is unavailable. See tests/README.md for details.


Project Structure

artisan/
├── artisan/              # Core Python package
│   ├── ast.py
│   ├── cnode.py
│   ├── query.py
│   ├── instrumentation.py
│   └── ...
├── tutorial/             # Step-by-step tutorials
├── conda/                # Conda build and environment files
├── pyproject.toml
└── README.md

Use Cases

  • Static analysis and program understanding
  • Automated refactoring tools
  • Code instrumentation for profiling or tracing
  • Research prototypes for compilers and program analysis
  • Teaching and experimentation with program representations

License

This project is licensed under the terms of the included LICENSE file.


Contributing

Contributions are welcome. The project is structured to encourage experimentation and extension—feel free to open issues or submit pull requests for bug fixes, improvements, or new ideas.


Acknowledgements

Artisan is designed as a research-friendly platform, drawing inspiration from compiler infrastructures and graph-based program analysis tools.

About

No description, website, or topics provided.

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages