trustfall_git_adapter

A Trustfall adapter for querying Git repositories using GraphQL-like syntax.

Overview

This crate provides a Trustfall adapter that allows you to query Git repositories using Trustfall's GraphQL-like query language. It acts as a bridge between Trustfall queries and Git repository data via the git2 crate.

Installation

Add this to your Cargo.toml:

[dependencies]
trustfall_git_adapter = "0.1.0"
git2 = "0.20"
trustfall = "0.8"

Usage

Basic Setup

use git2::Repository;
use trustfall_git_adapter::GitAdapter;
use std::sync::Arc;
use std::collections::BTreeMap;

// Open a Git repository
let repo = Repository::open(".")?;

// Create the adapter
let adapter = GitAdapter::new(&repo);

// Execute a query
let query = r#"{
  repository {
    name @output
    branches {
      name @output
    }
  }
}"#;

let variables = BTreeMap::new();
let results = trustfall::execute_query(
    adapter.schema(),
    Arc::new(&adapter),
    query,
    variables
)?;

// Process results
for result in results {
    println!("{:?}", result);
}

Query Examples

Repository name:

let query = r#"{
  repository {
    name @output
  }
}"#;

All branches:

let query = r#"{
  repository {
    branches {
      name @output
    }
  }
}"#;

Commits with messages:

let query = r#"{
  repository {
    commits {
      hash @output
      message @output
    }
  }
}"#;

Branches with their latest commits:

let query = r#"{
  repository {
    branches {
      name @output
      commit {
        hash @output
        message @output
      }
    }
  }
}"#;

Schema

The adapter implements the following GraphQL schema:

schema {
  query: RootSchemaQuery
}

type RootSchemaQuery {
    repository: Repository
}

type Repository {
    name: String!
    commits: [Commit!]!
    branches: [Branch!]!
}

type Commit {
    hash: String!
    message: String!
}

type Branch {
    name: String!
    commit: Commit!
}

Supported Operations

Repository queries: Access repository name and metadata
Branch enumeration: List all branches in the repository
Commit traversal: Iterate through commit history
Branch-to-commit relationships: Access the latest commit for each branch

Architecture

The adapter is built using Trustfall's derive macros and implements:

Vertices: Repository, Commit, Branch
Edges: Navigation between related Git objects
Properties: Data extraction from Git objects

Key Components

GitAdapter - Main adapter struct implementing the Trustfall adapter trait
Vertex - Enum representing different Git objects (Repository, Commit, Branch)
Edge resolution for navigating between Git objects
Property resolution for extracting data from Git objects

Performance Considerations

The adapter loads Git data on-demand during query execution
Large repositories with many commits/branches may take time to process
Consider using filters and limits in your Trustfall queries for better performance

Error Handling

The adapter handles common Git errors:

Repository not found or inaccessible
Invalid Git objects or references
I/O errors when reading Git data

Errors are propagated through Trustfall's error handling mechanism.

Development

Running Tests

cargo test -p trustfall_git_adapter

Testing with Different Repositories

# Test in a specific repository
cd /path/to/your/git/repo
cargo test -p trustfall_git_adapter

Adding New Query Capabilities

To extend the schema:

Update schema.graphql
Add new vertex types to vertex.rs
Implement edge resolution in edges.rs
Add property resolution in properties.rs
Update tests in tests/

Dependencies

git2 - Git repository access
trustfall - Query execution engine
trustfall_core - Core Trustfall functionality
trustfall_derive - Derive macros for adapter implementation

Examples

See the git-seek CLI tool for a complete example of how to use this adapter in a real application.

License

BSD-3-Clause

trustfall_git_adapter 1.1.0