Track Specification: Bootstrap gencpp Python Bindings Project

Overview

Create a new standalone Python project to build CFFI bindings for gencpp (C/C++ staged metaprogramming library). This will eventually provide richer C++ AST understanding than tree-sitter (full type information, operators, specifiers) but is a longer-term effort. This track bootstraps the project structure and initial bindings.

Current State Audit

gencpp Analysis (from research)

gencpp: C++ library for staged metaprogramming with built-in C/C++ parser
Parser: Non-standards-compliant single-pass parser for declarations/definitions
NOT execution-aware: Does NOT parse expressions or statements (only declarations)
AST Types: Code_Class, Code_Struct, Code_Function, Code_Enum, Code_Typedef, etc.
Available bindings: Odin (82KB binding file demonstrates scope)
Repository: https://github.com/Ed94/gencpp

What gencpp Can Extract

Function declarations and definitions (signatures only)
Class/struct/enum/union definitions
Type aliases (typedef)
Template declarations (partial)
Access specifiers
Operators (overload resolution)
Preprocessor includes/defines

What gencpp CANNOT Do

Parse function bodies/implementations
Expression evaluation
Template instantiation

Goals

Create new Python project structure for gencpp bindings
Set up CFFI to interface with gencpp C library
Build minimal viable bindings for declaration extraction
Create Python API matching existing mcp_client patterns
Document future expansion path

Functional Requirements

Project Setup

Create new repository/project: gencpp-python-bindings (or pygencpp)
Use CFFI for C library binding (pure Python, no C extension compilation required for basic use)
Structure: Python package with CFFI-based wrapper

Core API (Phase 1)

Function	Description
`parse_c_file(path) -> List[Declaration]`	Parse C file, return declarations
`parse_cpp_file(path) -> List[Declaration]`	Parse C++ file, return declarations
`Declaration` dataclass	name, type, line_number, node_type

Declaration Types to Bind

Code_Function / Code_Function_Fwd
Code_Struct / Code_Struct_Fwd
Code_Enum / Code_Enum_Fwd
Code_Union / Code_Union_Fwd
Code_Typedef
Code_Class (C++)
Code_Namespace (C++)

Integration Points (Future)

Design Python API to match mcp_client patterns for easy integration
Allow language parameter: parse_file(path, language: str)
Return structured data suitable for skeleton generation

Non-Functional Requirements

Pure Python with CFFI (no compiled extensions required at install time)
Must work on Windows (gencpp provides win64 precompiled library)
Follow existing 1-space indentation code style
Include type hints for all public APIs

Architecture Reference

gencpp C library: Precompiled gencpp_c11.lib (Windows) or source compilation
CFFI pattern: Use cffi.FFI().set_source() to wrap C library
Odin bindings reference: https://github.com/Ed94/gencpp-odin (shows AST type scope)
Existing mcp_client pattern: src/mcp_client.py tool dispatch

Out of Scope (This Track)

Full AST traversal (only top-level declarations)
Expression parsing
Template instantiation analysis
Integration into Manual Slop (future track)
macOS/Linux support (Windows first)

Relationship to Tree-Sitter Track

This is a SEPARATE long-term effort. The tree-sitter track provides immediate C/C++ support. The gencpp bindings track is for future richer functionality:

Aspect	tree-sitter (Track 1)	gencpp (This Track)
Scope	Per-file syntax	Per-file declarations
Types	Syntax nodes only	Named types, operators
Timeline	Immediate	Months
Effort	1-2 weeks	Ongoing

The tools will be named ts_c_* / ts_cpp_* for tree-sitter to leave namespace open for gencpp_* tools in the future.

4.0 KiB Raw Blame History