abi-forge 1.0.0__tar.gz

abi_forge-1.0.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: abi-forge
+Version: 1.0.0
+Summary: ABI governance and polyglot binding generator for C shared libraries
+Author-email: Vitaly Kuzyaev <vitkuz573@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/vitkuz573/abi-forge
+Project-URL: Repository, https://github.com/vitkuz573/abi-forge
+Project-URL: Issues, https://github.com/vitkuz573/abi-forge/issues
+Keywords: abi,codegen,bindings,ffi,interop
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# abi-forge
+
+**Reusable ABI governance and polyglot binding generator for C shared libraries.**
+
+From a single C header, abi-forge produces a versioned IDL snapshot and generates bindings for every language you need — with built-in breakage detection and governance.
+
+## What it does
+
+| Stage | What happens |
+|-------|-------------|
+| **Parse** | Clang-preprocesses your C header into a stable IDL JSON snapshot |
+| **Govern** | Diffs every new snapshot against the baseline; flags removals, signature changes, enum shifts as typed errors (ABI001–ABI007, SARIF-compatible) |
+| **Generate** | Runs your chosen language generators from the IDL: C#, Python, Rust, TypeScript, Go |
+| **Enforce** | CI fails on ABI regressions; waivers require explicit approval with TTL |
+
+## Language targets
+
+| Language | Output | Mechanism |
+|----------|--------|-----------|
+| **C# (.NET)** | P/Invoke + SafeHandle wrappers + async layer | Roslyn source generator (`generator_sdk/csharp/`) |
+| **Python** | ctypes module with IntEnum, OOP handles, CFUNCTYPE | `generator_sdk/python_bindings_generator.py` |
+| **Rust** | `#[repr(C)]` enums + `extern "C"` block | `generator_sdk/rust_ffi_generator.py` |
+| **TypeScript** | ffi-napi + OOP wrappers with `[Symbol.dispose]` | `generator_sdk/typescript_bindings_generator.py` |
+| **Go** | cgo package with struct wrappers and `runtime.SetFinalizer` | `generator_sdk/go_bindings_generator.py` |
+
+## Real-world example
+
+[LumenRTC](https://github.com/vitkuz573/LumenRTC) — a .NET wrapper over `libwebrtc` — uses abi-forge to govern its C ABI and generate all language bindings from a single IDL snapshot. See `abi/config.json` there for a complete production configuration.
+
+## Quick start
+
+### Requirements
+
+- Python 3.10+
+- clang (for header parsing)
+- .NET SDK 10+ (optional, only for C# bindings)
+
+### Bootstrap a new target
+
+```bash
+# Add abi-forge as a submodule
+git submodule add https://github.com/vitkuz573/abi-forge.git tools/abi_framework
+
+# Bootstrap: scaffolds abi/config.json + initial metadata
+python3 tools/abi_framework/abi_framework.py bootstrap \
+  --target mylib \
+  --header path/to/mylib.h \
+  --namespace MyLib \
+  --generate-python \
+  --generate-rust
+
+# Parse header → IDL snapshot
+python3 tools/abi_framework/abi_framework.py generate \
+  --config abi/config.json --skip-binary
+
+# Generate all bindings from IDL
+python3 tools/abi_framework/abi_framework.py codegen \
+  --config abi/config.json --skip-binary
+
+# Lock current IDL as baseline (first time)
+python3 tools/abi_framework/abi_framework.py generate-baseline --target mylib
+```
+
+### ABI governance in CI
+
+```bash
+# Fail on regressions
+python3 tools/abi_framework/abi_framework.py check \
+  --config abi/config.json --skip-binary
+
+# Full SARIF report for GitHub code scanning
+python3 tools/abi_framework/abi_framework.py check-all \
+  --config abi/config.json --skip-binary --sarif-out abi-report.sarif
+```
+
+### Health dashboard
+
+```bash
+python3 tools/abi_framework/abi_framework.py status --config abi/config.json
+```
+
+## Repository structure
+
+```
+abi-forge/
+├── abi_framework.py            # CLI entry point
+├── src/abi_framework_core/     # core: parse, diff, snapshot, policy, orchestration
+│   └── commands/               # subcommands: generate, codegen, check, release, status, …
+├── generator_sdk/              # language generators (Python, Rust, TypeScript, Go, C#-scaffold)
+│   └── plugin.manifest.json    # plugin declarations for all built-in generators
+├── abi_codegen_core/           # shared codegen primitives (native exports, required functions)
+├── abi_roslyn_codegen/         # Roslyn source generator for C# P/Invoke + managed API
+├── tests/                      # 99 tests covering orchestration, generators, governance
+└── schemas/                    # JSON schemas for IDL, config, managed_api
+```
+
+## Config overview (`abi/config.json`)
+
+```jsonc
+{
+  "targets": {
+    "mylib": {
+      "header": {
+        "path": "include/mylib.h",
+        "symbol_prefix": "mylib_",
+        "api_macro": "MYLIB_API"
+      },
+      "codegen": {
+        "idl_output": "abi/generated/mylib/mylib.idl.json"
+      },
+      "baseline_path": "abi/baselines/mylib.json",
+      "bindings": {
+        "generators": [
+          {
+            "manifest": "{repo_root}/tools/abi_framework/generator_sdk/plugin.manifest.json",
+            "plugins": [
+              "abi_framework.python_bindings",
+              "abi_framework.rust_ffi",
+              "abi_framework.typescript_bindings",
+              "abi_framework.go_bindings"
+            ]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+## ABI error types (SARIF rules)
+
+| Rule | Meaning |
+|------|---------|
+| `ABI001` | Function removed from public API |
+| `ABI002` | Function signature changed |
+| `ABI003` | Enum value added, removed, or renumbered |
+| `ABI004` | Struct layout changed |
+| `ABI005` | Bindings metadata mismatch |
+| `ABI006` | Version policy violation |
+| `ABI007` | Warning (non-breaking) |
+
+## License
+
+MIT

abi_forge-1.0.0/README.md

@@ -0,0 +1,144 @@
+# abi-forge
+
+**Reusable ABI governance and polyglot binding generator for C shared libraries.**
+
+From a single C header, abi-forge produces a versioned IDL snapshot and generates bindings for every language you need — with built-in breakage detection and governance.
+
+## What it does
+
+| Stage | What happens |
+|-------|-------------|
+| **Parse** | Clang-preprocesses your C header into a stable IDL JSON snapshot |
+| **Govern** | Diffs every new snapshot against the baseline; flags removals, signature changes, enum shifts as typed errors (ABI001–ABI007, SARIF-compatible) |
+| **Generate** | Runs your chosen language generators from the IDL: C#, Python, Rust, TypeScript, Go |
+| **Enforce** | CI fails on ABI regressions; waivers require explicit approval with TTL |
+
+## Language targets
+
+| Language | Output | Mechanism |
+|----------|--------|-----------|
+| **C# (.NET)** | P/Invoke + SafeHandle wrappers + async layer | Roslyn source generator (`generator_sdk/csharp/`) |
+| **Python** | ctypes module with IntEnum, OOP handles, CFUNCTYPE | `generator_sdk/python_bindings_generator.py` |
+| **Rust** | `#[repr(C)]` enums + `extern "C"` block | `generator_sdk/rust_ffi_generator.py` |
+| **TypeScript** | ffi-napi + OOP wrappers with `[Symbol.dispose]` | `generator_sdk/typescript_bindings_generator.py` |
+| **Go** | cgo package with struct wrappers and `runtime.SetFinalizer` | `generator_sdk/go_bindings_generator.py` |
+
+## Real-world example
+
+[LumenRTC](https://github.com/vitkuz573/LumenRTC) — a .NET wrapper over `libwebrtc` — uses abi-forge to govern its C ABI and generate all language bindings from a single IDL snapshot. See `abi/config.json` there for a complete production configuration.
+
+## Quick start
+
+### Requirements
+
+- Python 3.10+
+- clang (for header parsing)
+- .NET SDK 10+ (optional, only for C# bindings)
+
+### Bootstrap a new target
+
+```bash
+# Add abi-forge as a submodule
+git submodule add https://github.com/vitkuz573/abi-forge.git tools/abi_framework
+
+# Bootstrap: scaffolds abi/config.json + initial metadata
+python3 tools/abi_framework/abi_framework.py bootstrap \
+  --target mylib \
+  --header path/to/mylib.h \
+  --namespace MyLib \
+  --generate-python \
+  --generate-rust
+
+# Parse header → IDL snapshot
+python3 tools/abi_framework/abi_framework.py generate \
+  --config abi/config.json --skip-binary
+
+# Generate all bindings from IDL
+python3 tools/abi_framework/abi_framework.py codegen \
+  --config abi/config.json --skip-binary
+
+# Lock current IDL as baseline (first time)
+python3 tools/abi_framework/abi_framework.py generate-baseline --target mylib
+```
+
+### ABI governance in CI
+
+```bash
+# Fail on regressions
+python3 tools/abi_framework/abi_framework.py check \
+  --config abi/config.json --skip-binary
+
+# Full SARIF report for GitHub code scanning
+python3 tools/abi_framework/abi_framework.py check-all \
+  --config abi/config.json --skip-binary --sarif-out abi-report.sarif
+```
+
+### Health dashboard
+
+```bash
+python3 tools/abi_framework/abi_framework.py status --config abi/config.json
+```
+
+## Repository structure
+
+```
+abi-forge/
+├── abi_framework.py            # CLI entry point
+├── src/abi_framework_core/     # core: parse, diff, snapshot, policy, orchestration
+│   └── commands/               # subcommands: generate, codegen, check, release, status, …
+├── generator_sdk/              # language generators (Python, Rust, TypeScript, Go, C#-scaffold)
+│   └── plugin.manifest.json    # plugin declarations for all built-in generators
+├── abi_codegen_core/           # shared codegen primitives (native exports, required functions)
+├── abi_roslyn_codegen/         # Roslyn source generator for C# P/Invoke + managed API
+├── tests/                      # 99 tests covering orchestration, generators, governance
+└── schemas/                    # JSON schemas for IDL, config, managed_api
+```
+
+## Config overview (`abi/config.json`)
+
+```jsonc
+{
+  "targets": {
+    "mylib": {
+      "header": {
+        "path": "include/mylib.h",
+        "symbol_prefix": "mylib_",
+        "api_macro": "MYLIB_API"
+      },
+      "codegen": {
+        "idl_output": "abi/generated/mylib/mylib.idl.json"
+      },
+      "baseline_path": "abi/baselines/mylib.json",
+      "bindings": {
+        "generators": [
+          {
+            "manifest": "{repo_root}/tools/abi_framework/generator_sdk/plugin.manifest.json",
+            "plugins": [
+              "abi_framework.python_bindings",
+              "abi_framework.rust_ffi",
+              "abi_framework.typescript_bindings",
+              "abi_framework.go_bindings"
+            ]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+## ABI error types (SARIF rules)
+
+| Rule | Meaning |
+|------|---------|
+| `ABI001` | Function removed from public API |
+| `ABI002` | Function signature changed |
+| `ABI003` | Enum value added, removed, or renumbered |
+| `ABI004` | Struct layout changed |
+| `ABI005` | Bindings metadata mismatch |
+| `ABI006` | Version policy violation |
+| `ABI007` | Warning (non-breaking) |
+
+## License
+
+MIT

abi_forge-1.0.0/abi_codegen_core/src/abi_codegen_core/__init__.py

@@ -0,0 +1,13 @@
+from .common import load_json_object, write_if_changed
+from .native_exports import NativeExportRenderOptions, render_exports, render_impl_header
+from .required_functions import derive_required_functions, iter_strings
+
+__all__ = [
+    "NativeExportRenderOptions",
+    "derive_required_functions",
+    "iter_strings",
+    "load_json_object",
+    "render_exports",
+    "render_impl_header",
+    "write_if_changed",
+]

abi_forge-1.0.0/abi_codegen_core/src/abi_codegen_core/common.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import difflib
+import json
+from pathlib import Path
+from typing import Any
+
+
+def load_json_object(path: Path) -> dict[str, Any]:
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise SystemExit(f"JSON root in '{path}' must be an object")
+    return payload
+
+
+def write_if_changed(path: Path, content: str, check: bool, dry_run: bool) -> int:
+    existing = path.read_text(encoding="utf-8") if path.exists() else ""
+    if existing == content:
+        return 0
+    if check:
+        diff = difflib.unified_diff(
+            existing.splitlines(),
+            content.splitlines(),
+            fromfile=f"a/{path}",
+            tofile=f"b/{path}",
+            lineterm="",
+        )
+        print("\n".join(diff))
+        return 1
+    if not dry_run:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+    return 0

abi_forge-1.0.0/abi_codegen_core/src/abi_codegen_core/native_exports.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+def normalize_type(value: str) -> str:
+    return " ".join(value.replace("\t", " ").split())
+
+
+def render_params(parameters: list[dict[str, Any]]) -> str:
+    if not parameters:
+        return "void"
+    parts: list[str] = []
+    for index, param in enumerate(parameters):
+        name = str(param.get("name") or f"arg{index}")
+        c_type = normalize_type(str(param.get("c_type") or "void"))
+        if c_type == "...":
+            parts.append("...")
+            continue
+        parts.append(f"{c_type} {name}")
+    return ", ".join(parts)
+
+
+def render_arg_list(parameters: list[dict[str, Any]]) -> str:
+    if not parameters:
+        return ""
+    names: list[str] = []
+    for index, param in enumerate(parameters):
+        c_type = str(param.get("c_type") or "void")
+        if c_type == "...":
+            continue
+        name = str(param.get("name") or f"arg{index}")
+        names.append(name)
+    return ", ".join(names)
+
+
+@dataclass(frozen=True)
+class NativeExportRenderOptions:
+    header_include: str
+    impl_header_include: str
+    api_macro: str
+    call_macro: str
+    impl_prefix: str
+    symbol_prefix: str
+
+
+def build_impl_name(function_name: str, options: NativeExportRenderOptions) -> str:
+    if options.symbol_prefix and function_name.startswith(options.symbol_prefix):
+        return options.impl_prefix + function_name[len(options.symbol_prefix):]
+    return options.impl_prefix + function_name
+
+
+def render_impl_header(functions: list[dict[str, Any]], options: NativeExportRenderOptions) -> str:
+    lines: list[str] = []
+    lines.append("#pragma once")
+    lines.append("")
+    lines.append(f"#include \"{options.header_include}\"")
+    lines.append("")
+    lines.append("#ifdef __cplusplus")
+    lines.append("extern \"C\" {")
+    lines.append("#endif")
+    lines.append("")
+    for item in functions:
+        name = str(item.get("name") or "")
+        if not name:
+            continue
+        return_type = normalize_type(str(item.get("c_return_type") or "void"))
+        parameters = item.get("parameters")
+        if not isinstance(parameters, list):
+            parameters = []
+        signature = render_params(parameters)
+        impl_name = build_impl_name(name, options)
+        lines.append(f"{return_type} {options.call_macro} {impl_name}({signature});")
+    lines.append("")
+    lines.append("#ifdef __cplusplus")
+    lines.append("}")
+    lines.append("#endif")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def render_exports(
+    functions: list[dict[str, Any]],
+    options: NativeExportRenderOptions,
+    generator_path: str,
+) -> str:
+    lines: list[str] = []
+    lines.append("// <auto-generated />")
+    lines.append(f"// Generated by {generator_path}")
+    lines.append(f"#include \"{options.header_include}\"")
+    lines.append(f"#include \"{options.impl_header_include}\"")
+    lines.append("")
+    lines.append("#ifdef __cplusplus")
+    lines.append("extern \"C\" {")
+    lines.append("#endif")
+    lines.append("")
+    for item in functions:
+        name = str(item.get("name") or "")
+        if not name:
+            continue
+        return_type = normalize_type(str(item.get("c_return_type") or "void"))
+        parameters = item.get("parameters")
+        if not isinstance(parameters, list):
+            parameters = []
+        signature = render_params(parameters)
+        args = render_arg_list(parameters)
+        impl_name = build_impl_name(name, options)
+        lines.append(f"{options.api_macro} {return_type} {options.call_macro} {name}({signature}) {{")
+        if return_type == "void":
+            if args:
+                lines.append(f"    {impl_name}({args});")
+            else:
+                lines.append(f"    {impl_name}();")
+            lines.append("}")
+        else:
+            if args:
+                lines.append(f"    return {impl_name}({args});")
+            else:
+                lines.append(f"    return {impl_name}();")
+            lines.append("}")
+        lines.append("")
+    lines.append("#ifdef __cplusplus")
+    lines.append("}")
+    lines.append("#endif")
+    lines.append("")
+    return "\n".join(lines)

abi_forge-1.0.0/abi_codegen_core/src/abi_codegen_core/required_functions.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+def iter_strings(value: Any) -> list[str]:
+    if isinstance(value, str):
+        return [value]
+    result: list[str] = []
+    if isinstance(value, list):
+        for item in value:
+            result.extend(iter_strings(item))
+    elif isinstance(value, dict):
+        for item in value.values():
+            result.extend(iter_strings(item))
+    return result
+
+
+def _first_capture(match: re.Match[str]) -> str:
+    if match.lastindex:
+        for index in range(1, match.lastindex + 1):
+            value = match.group(index)
+            if value:
+                return value
+    return match.group(0)
+
+
+def derive_required_functions(
+    payload: dict[str, Any],
+    idl_names: set[str],
+    native_call_patterns: list[str],
+    function_name_pattern: str | None = None,
+) -> list[str]:
+    compiled_patterns: list[re.Pattern[str]] = []
+    for raw in native_call_patterns:
+        try:
+            compiled_patterns.append(re.compile(raw))
+        except re.error as exc:
+            raise SystemExit(f"Invalid native call regex pattern '{raw}': {exc}") from exc
+
+    function_filter: re.Pattern[str] | None = None
+    if function_name_pattern:
+        try:
+            function_filter = re.compile(function_name_pattern)
+        except re.error as exc:
+            raise SystemExit(f"Invalid function_name_pattern '{function_name_pattern}': {exc}") from exc
+
+    discovered: set[str] = set()
+    for text in iter_strings(payload):
+        for pattern in compiled_patterns:
+            for match in pattern.finditer(text):
+                candidate = _first_capture(match)
+                if function_filter and not function_filter.fullmatch(candidate):
+                    continue
+                if candidate in idl_names:
+                    discovered.add(candidate)
+    return sorted(discovered)