ggen 0.2.1

ggen is a deterministic, language-agnostic code generation framework that treats software artifacts as projections of knowledge graphs.
Documentation

Table of Contents

ggen - Graph-Aware Code Generation Framework

GitHub Pages Rust License

ggen is a deterministic, language-agnostic code generation framework that treats software artifacts as projections of RDF knowledge graphs. Generate reproducible, multi-language code from a single semantic ontology using template-based generation with SPARQL queries.

📚 Full Documentation

Features

  • 🎯 Deterministic Generation - Byte-identical output with fixed seeds
  • 🌐 Language-Agnostic - Generate code in any language from the same ontology
  • 🔗 RDF Knowledge Graphs - Embed semantic metadata with SPARQL queries
  • 📦 Marketplace Integration - Reusable template packages (rpacks) with versioning
  • 🧪 Template-Based - YAML frontmatter with Tera templating engine
  • 🔄 Injection Support - Modify existing files with idempotent updates
  • 🚀 GitHub Integration - Built-in GitHub Pages and Actions API support
  • 🔐 Post-Quantum Security (v1.0.0) - ML-DSA (Dilithium3) signatures for quantum-resistant package integrity
  • ⚡ Performance SLOs - Fast builds, low memory, reproducible outputs

Quick Start

Installation

Homebrew (macOS/Linux):

brew tap seanchatmangpt/tap
brew install ggen

From Source:

git clone https://github.com/seanchatmangpt/ggen
cd ggen
cargo make build-release

Basic Usage

# Generate from a template
ggen gen templates/rust-module.tmpl --vars name=my_module

# Search marketplace for templates
ggen search "rust cli"

# Add a template pack
ggen add io.rgen.rust.cli-subcommand

# List available templates
ggen list

# Check GitHub Pages status
ggen github pages-status

Template Example

---
to: "src/{{name}}.rs"
vars:
  name: "example"
  author: "ggen"
prefixes:
  ex: "http://example.org/"
rdf_inline:
  - "@prefix ex: <http://example.org/> . ex:{{name}} a ex:Module ."
sparql:
  get_type: "SELECT ?type WHERE { ex:{{name}} a ?type }"
determinism: 42
---
//! {{name}} module
//! Generated by {{author}}

pub struct {{name | capitalize}} {
    // Module implementation
}

impl {{name | capitalize}} {
    pub fn new() -> Self {
        Self {}
    }
}

Architecture

ggen/
├── cli/           # Clap CLI with subcommands
├── ggen-core/     # Core generation engine
│   ├── pipeline.rs   # Template rendering pipeline
│   ├── template.rs   # Frontmatter + body parsing
│   ├── graph.rs      # RDF graph with SPARQL caching
│   ├── generator.rs  # Generation orchestration
│   ├── registry.rs   # Marketplace client
│   └── github.rs     # GitHub API integration
├── utils/         # Configuration, logging, errors
└── templates/     # Built-in templates

Key Capabilities

Deterministic Generation

Generate byte-identical output with fixed seeds:

---
determinism: 42  # Fixed RNG seed
---

RDF + SPARQL Integration

Embed semantic knowledge and query it:

---
prefixes:
  foaf: "http://xmlns.com/foaf/0.1/"
rdf_inline:
  - "@prefix foaf: <http://xmlns.com/foaf/0.1/> . :person foaf:name \"{{name}}\" ."
sparql:
  get_name: "SELECT ?name WHERE { :person foaf:name ?name }"
---
Name from RDF: {{ sparql(query="get_name") }}

Injection Modes

Modify existing files idempotently:

---
to: "src/lib.rs"
inject:
  mode: "after"
  pattern: "pub mod"
  skip_if: "pub mod {{name}}"
---
pub mod {{name}};

GitHub Integration

Built-in GitHub API commands:

# Check Pages deployment status
ggen github pages-status

# View workflow runs
ggen github workflow-status

# Trigger workflow
ggen github trigger-workflow

Development

CRITICAL: Always use cargo make commands, never direct cargo commands.

# Quick development workflow
cargo make quick      # Format and test
cargo make dev        # Format, lint, test

# Testing
cargo make test                 # All tests
cargo make deterministic        # Fixed seeds + single-threaded
cargo make test-coverage        # Coverage report

# Code quality
cargo make fmt                  # Format
cargo make lint                 # Strict clippy
cargo make audit                # Security scan

# Build
cargo make build-release        # Release build
cargo make ci                   # Full CI workflow

# GitHub/Pages
cargo make docs-build           # Build documentation
cargo make gh-pages-status      # Check Pages status

Marketplace (rpacks)

Rpacks are versioned, reusable template packages:

# Search for rpacks
ggen search "rust"

# View categories
ggen categories

# Add an rpack
ggen add io.rgen.rust.cli-subcommand

# List installed rpacks
ggen packs

# Update rpacks
ggen update

Documentation

Performance SLOs

  • First build: ≤ 15s
  • Incremental build: ≤ 2s
  • RDF processing: ≤ 5s for 1k+ triples
  • Generation memory: ≤ 100MB
  • CLI scaffolding: ≤ 3s end-to-end
  • 100% reproducible outputs

Contributing

  1. Follow the guidelines in CLAUDE.md
  2. Always use cargo make commands
  3. Ensure cargo make ci passes before submitting
  4. Add tests for new features
  5. Update documentation

License

MIT License - see LICENSE for details.

Repository

Source: https://github.com/seanchatmangpt/ggen

Homebrew Tap:

tap "seanchatmangpt/tap"
brew "ggen"

Built with ❤️ using Rust, RDF, and SPARQL