diff --git a/ABI-FFI-README.md b/ABI-FFI-README.adoc similarity index 74% rename from ABI-FFI-README.md rename to ABI-FFI-README.adoc index 8010527..04be86a 100644 --- a/ABI-FFI-README.md +++ b/ABI-FFI-README.adoc @@ -1,23 +1,22 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -49,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, AffineScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -81,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── affinescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -101,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -115,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -129,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -144,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -219,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -241,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -263,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -286,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -316,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -346,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 6d12be8..e7691df 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -1,180 +1,202 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Changelog +== Changelog All notable changes to this project will be documented in this file. -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -== [Unreleased] - -=== Planned -- TUI (Ada/SPARK) -- Language Server Protocol (LSP) -- Additional language bindings (Python, Ruby, Node.js) -- Plugin system - -== [1.0.0] - 2025-12-12 - -=== Added -- Zig FFI layer for stable C ABI across Rust compiler versions -- Complete Deno bindings using `Deno.dlopen` FFI -- Complete AffineScript bindings via C FFI -- Watch mode with file change detection (`bunsenite watch`) -- Interactive REPL (`bunsenite repl`) -- JSON Schema validation (`bunsenite schema`) -- miette 7.0 integration for beautiful error diagnostics - -=== Changed -- Upgraded nickel-lang-core to 0.9.1 (CBNCache moved to lazy module) -- CLI expanded from 3 commands to 6 commands -- Documentation updated for v1.0.0 release - -=== Fixed -- CBNCache import path for nickel-lang-core 0.9.1 compatibility - -=== Compliance -- RSR Bronze Tier: Verified -- TPCF Perimeter 3: Maintained -- No plain TypeScript, npm, or Python dependencies - -== [0.1.0] - 2025-11-22 - -=== Added -- 🎉 Initial release of Bunsenite! -- ✅ Rust core library with nickel-lang-core 0.9.1 integration -- ✅ `NickelLoader` API for parsing and evaluating Nickel configurations -- ✅ Comprehensive error handling with helpful error messages -- ✅ WebAssembly bindings for browser deployment (~95% native speed) -- ✅ Command-line interface with `parse`, `validate`, and `info` commands -- ✅ Zero `unsafe` code (enforced by compiler directive) -- ✅ Complete test suite (30+ tests, 100% pass rate) -- ✅ Full RSR Bronze Tier compliance: - - Type safety (Rust compile-time guarantees) - - Memory safety (ownership model, no unsafe) - - Offline-first (no network dependencies) - - Complete documentation set - - `.well-known/` directory (security.txt, ai.txt, humans.txt) - - Build system (Justfile, Guix flake) - - CI/CD pipeline (GitLab CI) -- ✅ TPCF Perimeter 3 (Community Sandbox) contribution model -- ✅ Dual MPL-2.0 + Palimpsest 0.8 licensing -- ✅ Comprehensive documentation: - - README.md with quick start and examples - - CLAUDE.md for AI assistants and developers - - SECURITY.md with vulnerability reporting - - CONTRIBUTING.md with development workflow - - CODE_OF_CONDUCT.md aligned with TPCF principles - - MAINTAINERS.md with governance structure -- ✅ API documentation with examples -- ✅ FFI binding infrastructure: - - Deno bindings (TypeScript) - - Rescript bindings - - C ABI via Zig (planned) - -=== Technical Details - -==== API Compatibility (nickel-lang-core 0.9.1) -- `Program::new_from_source()` with trace parameter -- `eval_full()` with no arguments -- Manual error conversion via `serde_json::to_value()` -- No deprecated `into_diagnostics()` usage - -==== Dependencies -- nickel-lang-core 0.9.1 (core parser) -- serde 1.0 (serialization) -- serde_json 1.0 (JSON conversion) -- anyhow 1.0 (error handling) -- thiserror 1.0 (error derive macros) -- clap 4.4 (CLI, optional) -- wasm-bindgen 0.2 (WASM bindings, target-specific) - -==== Build Artifacts -- CLI binary: `bunsenite` (~6.5MB optimized) -- Shared library: `libbunsenite.so/dylib/dll` (~6.1MB optimized) -- WASM module: `bunsenite.wasm` (size varies by optimization level) - -=== Security - -==== Memory Safety -- Zero `unsafe` code blocks (enforced by `#![deny(unsafe_code)]`) -- Rust ownership model prevents: - - Use-after-free - - Double-free - - Null pointer dereferences - - Buffer overflows - - Data races - -==== Supply Chain -- Minimal dependencies (only essential, well-audited crates) -- No network dependencies (offline-first design) -- Pinned dependency versions for reproducibility -- Regular `cargo audit` checks in CI - -=== Performance -- Native Rust: Baseline performance -- WebAssembly: ~95% native speed -- FFI bindings: ~90% native speed (minimal C ABI overhead) - -=== Known Limitations -- Nickel evaluation may consume significant memory/CPU for complex configs - - **Mitigation**: Plan to add configurable timeouts and memory limits -- File I/O respects OS permissions (no privilege escalation) -- WASM runs in browser sandbox (subject to browser security model) - -=== Breaking Changes -- N/A (initial release) - -=== Deprecations -- N/A (initial release) - -=== Fixed -- N/A (initial release) - -=== Contributors -- Campaign for Cooler Coding and Programming (@cccp) - Initial implementation - ---- - -== Version History - -=== Version Numbering - -We use [Semantic Versioning](https://semver.org/): - -[source,] ----- +The format is based on https://keepachangelog.com/en/1.0.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Planned + +* TUI (Ada/SPARK) +* Language Server Protocol (LSP) +* Additional language bindings (Python, Ruby, Node.js) +* Plugin system + +=== [1.0.0] - 2025-12-12 + +==== Added + +* Zig FFI layer for stable C ABI across Rust compiler versions +* Complete Deno bindings using `+Deno.dlopen+` FFI +* Complete AffineScript bindings via C FFI +* Watch mode with file change detection (`+bunsenite watch+`) +* Interactive REPL (`+bunsenite repl+`) +* JSON Schema validation (`+bunsenite schema+`) +* miette 7.0 integration for beautiful error diagnostics + +==== Changed + +* Upgraded nickel-lang-core to 0.9.1 (CBNCache moved to lazy module) +* CLI expanded from 3 commands to 6 commands +* Documentation updated for v1.0.0 release + +==== Fixed + +* CBNCache import path for nickel-lang-core 0.9.1 compatibility + +==== Compliance + +* RSR Bronze Tier: Verified +* TPCF Perimeter 3: Maintained +* No plain TypeScript, npm, or Python dependencies + +=== [0.1.0] - 2025-11-22 + +==== Added + +* 🎉 Initial release of Bunsenite! +* ✅ Rust core library with nickel-lang-core 0.9.1 integration +* ✅ `+NickelLoader+` API for parsing and evaluating Nickel +configurations +* ✅ Comprehensive error handling with helpful error messages +* ✅ WebAssembly bindings for browser deployment (~95% native speed) +* ✅ Command-line interface with `+parse+`, `+validate+`, and `+info+` +commands +* ✅ Zero `+unsafe+` code (enforced by compiler directive) +* ✅ Complete test suite (30+ tests, 100% pass rate) +* ✅ Full RSR Bronze Tier compliance: +** Type safety (Rust compile-time guarantees) +** Memory safety (ownership model, no unsafe) +** Offline-first (no network dependencies) +** Complete documentation set +** `+.well-known/+` directory (security.txt, ai.txt, humans.txt) +** Build system (Justfile, Guix flake) +** CI/CD pipeline (GitLab CI) +* ✅ TPCF Perimeter 3 (Community Sandbox) contribution model +* ✅ Dual MIT + Palimpsest 0.8 licensing +* ✅ Comprehensive documentation: +** README.md with quick start and examples +** CLAUDE.md for AI assistants and developers +** SECURITY.md with vulnerability reporting +** CONTRIBUTING.md with development workflow +** CODE_OF_CONDUCT.md aligned with TPCF principles +** MAINTAINERS.md with governance structure +* ✅ API documentation with examples +* ✅ FFI binding infrastructure: +** Deno bindings (TypeScript) +** Rescript bindings +** C ABI via Zig (planned) + +==== Technical Details + +===== API Compatibility (nickel-lang-core 0.9.1) + +* `+Program::new_from_source()+` with trace parameter +* `+eval_full()+` with no arguments +* Manual error conversion via `+serde_json::to_value()+` +* No deprecated `+into_diagnostics()+` usage + +===== Dependencies + +* nickel-lang-core 0.9.1 (core parser) +* serde 1.0 (serialization) +* serde_json 1.0 (JSON conversion) +* anyhow 1.0 (error handling) +* thiserror 1.0 (error derive macros) +* clap 4.4 (CLI, optional) +* wasm-bindgen 0.2 (WASM bindings, target-specific) + +===== Build Artifacts + +* CLI binary: `+bunsenite+` (~6.5MB optimized) +* Shared library: `+libbunsenite.so/dylib/dll+` (~6.1MB optimized) +* WASM module: `+bunsenite.wasm+` (size varies by optimization level) + +==== Security + +===== Memory Safety + +* Zero `+unsafe+` code blocks (enforced by `+#![deny(unsafe_code)]+`) +* Rust ownership model prevents: +** Use-after-free +** Double-free +** Null pointer dereferences +** Buffer overflows +** Data races + +===== Supply Chain + +* Minimal dependencies (only essential, well-audited crates) +* No network dependencies (offline-first design) +* Pinned dependency versions for reproducibility +* Regular `+cargo audit+` checks in CI + +==== Performance + +* Native Rust: Baseline performance +* WebAssembly: ~95% native speed +* FFI bindings: ~90% native speed (minimal C ABI overhead) + +==== Known Limitations + +* Nickel evaluation may consume significant memory/CPU for complex +configs +** *Mitigation*: Plan to add configurable timeouts and memory limits +* File I/O respects OS permissions (no privilege escalation) +* WASM runs in browser sandbox (subject to browser security model) + +==== Breaking Changes + +* N/A (initial release) + +==== Deprecations + +* N/A (initial release) + +==== Fixed + +* N/A (initial release) + +==== Contributors + +* Campaign for Cooler Coding and Programming (@cccp) - Initial +implementation + +''''' + +=== Version History + +==== Version Numbering + +We use https://semver.org/[Semantic Versioning]: + +.... MAJOR.MINOR.PATCH MAJOR: Incompatible API changes MINOR: Backwards-compatible new features PATCH: Backwards-compatible bug fixes -[source,] ----- +.... -=== Release Cadence +==== Release Cadence -- **Major releases**: As needed for breaking changes -- **Minor releases**: Monthly (if new features ready) -- **Patch releases**: As needed for critical bugs/security +* *Major releases*: As needed for breaking changes +* *Minor releases*: Monthly (if new features ready) +* *Patch releases*: As needed for critical bugs/security -=== Support Policy +==== Support Policy -| Version | Support Status | End of Life | -| ------- | ------------------- | -------------- | -| 0.1.x | ✅ Full support | TBD (current) | -| < 0.1.0 | ❌ Not supported | N/A | +[cols=",,",options="header",] +|=== +|Version |Support Status |End of Life +|0.1.x |✅ Full support |TBD (current) +|< 0.1.0 |❌ Not supported |N/A +|=== ---- +''''' -== Links +=== Links -- [Repository](https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite) -- [Issues](https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite/-/issues) -- [Releases](https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite/-/releases) -- [Crates.io](https://crates.io/crates/bunsenite) (coming soon) +* https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite[Repository] +* https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite/-/issues[Issues] +* https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite/-/releases[Releases] +* https://crates.io/crates/bunsenite[Crates.io] (coming soon) ---- +''''' -**Note**: This changelog is maintained according to [Keep a Changelog](https://keepachangelog.com/) principles and serves as a living document of the project's evolution. +*Note*: This changelog is maintained according to +https://keepachangelog.com/[Keep a Changelog] principles and serves as a +living document of the project’s evolution. diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 83cdb4e..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,180 +0,0 @@ - -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Planned -- TUI (Ada/SPARK) -- Language Server Protocol (LSP) -- Additional language bindings (Python, Ruby, Node.js) -- Plugin system - -## [1.0.0] - 2025-12-12 - -### Added -- Zig FFI layer for stable C ABI across Rust compiler versions -- Complete Deno bindings using `Deno.dlopen` FFI -- Complete AffineScript bindings via C FFI -- Watch mode with file change detection (`bunsenite watch`) -- Interactive REPL (`bunsenite repl`) -- JSON Schema validation (`bunsenite schema`) -- miette 7.0 integration for beautiful error diagnostics - -### Changed -- Upgraded nickel-lang-core to 0.9.1 (CBNCache moved to lazy module) -- CLI expanded from 3 commands to 6 commands -- Documentation updated for v1.0.0 release - -### Fixed -- CBNCache import path for nickel-lang-core 0.9.1 compatibility - -### Compliance -- RSR Bronze Tier: Verified -- TPCF Perimeter 3: Maintained -- No plain TypeScript, npm, or Python dependencies - -## [0.1.0] - 2025-11-22 - -### Added -- 🎉 Initial release of Bunsenite! -- ✅ Rust core library with nickel-lang-core 0.9.1 integration -- ✅ `NickelLoader` API for parsing and evaluating Nickel configurations -- ✅ Comprehensive error handling with helpful error messages -- ✅ WebAssembly bindings for browser deployment (~95% native speed) -- ✅ Command-line interface with `parse`, `validate`, and `info` commands -- ✅ Zero `unsafe` code (enforced by compiler directive) -- ✅ Complete test suite (30+ tests, 100% pass rate) -- ✅ Full RSR Bronze Tier compliance: - - Type safety (Rust compile-time guarantees) - - Memory safety (ownership model, no unsafe) - - Offline-first (no network dependencies) - - Complete documentation set - - `.well-known/` directory (security.txt, ai.txt, humans.txt) - - Build system (Justfile, Guix flake) - - CI/CD pipeline (GitLab CI) -- ✅ TPCF Perimeter 3 (Community Sandbox) contribution model -- ✅ Dual MIT + Palimpsest 0.8 licensing -- ✅ Comprehensive documentation: - - README.md with quick start and examples - - CLAUDE.md for AI assistants and developers - - SECURITY.md with vulnerability reporting - - CONTRIBUTING.md with development workflow - - CODE_OF_CONDUCT.md aligned with TPCF principles - - MAINTAINERS.md with governance structure -- ✅ API documentation with examples -- ✅ FFI binding infrastructure: - - Deno bindings (TypeScript) - - Rescript bindings - - C ABI via Zig (planned) - -### Technical Details - -#### API Compatibility (nickel-lang-core 0.9.1) -- `Program::new_from_source()` with trace parameter -- `eval_full()` with no arguments -- Manual error conversion via `serde_json::to_value()` -- No deprecated `into_diagnostics()` usage - -#### Dependencies -- nickel-lang-core 0.9.1 (core parser) -- serde 1.0 (serialization) -- serde_json 1.0 (JSON conversion) -- anyhow 1.0 (error handling) -- thiserror 1.0 (error derive macros) -- clap 4.4 (CLI, optional) -- wasm-bindgen 0.2 (WASM bindings, target-specific) - -#### Build Artifacts -- CLI binary: `bunsenite` (~6.5MB optimized) -- Shared library: `libbunsenite.so/dylib/dll` (~6.1MB optimized) -- WASM module: `bunsenite.wasm` (size varies by optimization level) - -### Security - -#### Memory Safety -- Zero `unsafe` code blocks (enforced by `#![deny(unsafe_code)]`) -- Rust ownership model prevents: - - Use-after-free - - Double-free - - Null pointer dereferences - - Buffer overflows - - Data races - -#### Supply Chain -- Minimal dependencies (only essential, well-audited crates) -- No network dependencies (offline-first design) -- Pinned dependency versions for reproducibility -- Regular `cargo audit` checks in CI - -### Performance -- Native Rust: Baseline performance -- WebAssembly: ~95% native speed -- FFI bindings: ~90% native speed (minimal C ABI overhead) - -### Known Limitations -- Nickel evaluation may consume significant memory/CPU for complex configs - - **Mitigation**: Plan to add configurable timeouts and memory limits -- File I/O respects OS permissions (no privilege escalation) -- WASM runs in browser sandbox (subject to browser security model) - -### Breaking Changes -- N/A (initial release) - -### Deprecations -- N/A (initial release) - -### Fixed -- N/A (initial release) - -### Contributors -- Campaign for Cooler Coding and Programming (@cccp) - Initial implementation - ---- - -## Version History - -### Version Numbering - -We use [Semantic Versioning](https://semver.org/): - -``` -MAJOR.MINOR.PATCH - -MAJOR: Incompatible API changes -MINOR: Backwards-compatible new features -PATCH: Backwards-compatible bug fixes -``` - -### Release Cadence - -- **Major releases**: As needed for breaking changes -- **Minor releases**: Monthly (if new features ready) -- **Patch releases**: As needed for critical bugs/security - -### Support Policy - -| Version | Support Status | End of Life | -| ------- | ------------------- | -------------- | -| 0.1.x | ✅ Full support | TBD (current) | -| < 0.1.0 | ❌ Not supported | N/A | - ---- - -## Links - -- [Repository](https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite) -- [Issues](https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite/-/issues) -- [Releases](https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite/-/releases) -- [Crates.io](https://crates.io/crates/bunsenite) (coming soon) - ---- - -**Note**: This changelog is maintained according to [Keep a Changelog](https://keepachangelog.com/) principles and serves as a living document of the project's evolution. diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..070c601 --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,175 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +our community a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +=== Our Standards + +==== Examples of behavior that contributes to a positive environment: + +* *Demonstrating empathy and kindness* toward other people +* *Being respectful* of differing opinions, viewpoints, and experiences +* *Giving and gracefully accepting* constructive feedback +* *Accepting responsibility* and apologizing to those affected by our +mistakes, and learning from the experience +* *Focusing on what is best* not just for us as individuals, but for the +overall community +* *Using welcoming and inclusive language* +* *Being patient* with new contributors and those learning +* *Celebrating successes* of others +* *Supporting emotional safety* and reversibility in development + +==== Examples of unacceptable behavior: + +* The use of sexualized language or imagery, and sexual attention or +advances of any kind +* Trolling, insulting or derogatory comments, and personal or political +attacks +* Public or private harassment +* Publishing others’ private information, such as a physical or email +address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a +professional setting +* *Dismissing or minimizing* concerns about emotional safety +* *Gatekeeping* or elitism based on technical skill level +* *Weaponizing vulnerability* or reversibility features + +=== Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our +standards of acceptable behavior and will take appropriate and fair +corrective action in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other +contributions that are not aligned to this Code of Conduct, and will +communicate reasons for moderation decisions when appropriate. + +=== Scope + +This Code of Conduct applies within all community spaces, and also +applies when an individual is officially representing the community in +public spaces. Examples of representing our community include using an +official e-mail address, posting via an official social media account, +or acting as an appointed representative at an online or offline event. + +=== Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported to the community leaders responsible for enforcement at: + +* *GitHub Issues*: +https://github.com/hyperpolymath/bunsenite/issues/new?labels=conduct[Report +a concern] +* *GitLab*: Confidential issue on the repository + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security +of the reporter of any incident. + +=== Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of +this Code of Conduct: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behavior +deemed unprofessional or unwelcome in the community. + +*Consequence*: A private, written warning from community leaders, +providing clarity around the nature of the violation and an explanation +of why the behavior was inappropriate. A public apology may be +requested. + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period of +time. This includes avoiding interactions in community spaces as well as +external channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behavior. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No +public or private interaction with the people involved, including +unsolicited interaction with those enforcing the Code of Conduct, is +allowed during this period. Violating these terms may lead to a +permanent ban. + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +=== Emotional Safety Principles + +In alignment with our values of emotional safety and reversibility: + +==== Encouragement Over Criticism + +* *Positive framing*: Frame feedback constructively +* *Assume good intent*: Mistakes are learning opportunities +* *Celebrate experimentation*: Failures are valuable when reversible +* *Support learning*: Everyone is learning, regardless of experience +level + +==== Reversibility in Community Interactions + +* *Mistakes can be fixed*: Technical mistakes are reversible through Git +* *Apologies matter*: Sincere apologies can repair social mistakes +* *Growth mindset*: People can change and improve +* *Second chances*: Unless patterns of harm persist + +==== Political Autonomy + +* *Technical decisions*: Based on merit, not politics +* *No gatekeeping*: Access based on conduct, not views +* *Respectful disagreement*: Disagree on ideas, not people +* *Community sovereignty*: This community makes its own decisions + +=== Attribution + +This Code of Conduct is adapted from the +https://www.contributor-covenant.org[Contributor Covenant], version 2.1, +available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. + +Community Impact Guidelines were inspired by +https://github.com/mozilla/diversity[Mozilla’s code of conduct +enforcement ladder]. + +For answers to common questions about this code of conduct, see the FAQ +at https://www.contributor-covenant.org/faq. Translations are available +at https://www.contributor-covenant.org/translations. + +''''' + +*Last updated*: 2025-11-22 *Version*: 1.0.0 (Aligned with RSR Framework +& TPCF principles) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 315cda0..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,129 +0,0 @@ - -# Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -## Our Standards - -### Examples of behavior that contributes to a positive environment: - -- **Demonstrating empathy and kindness** toward other people -- **Being respectful** of differing opinions, viewpoints, and experiences -- **Giving and gracefully accepting** constructive feedback -- **Accepting responsibility** and apologizing to those affected by our mistakes, and learning from the experience -- **Focusing on what is best** not just for us as individuals, but for the overall community -- **Using welcoming and inclusive language** -- **Being patient** with new contributors and those learning -- **Celebrating successes** of others -- **Supporting emotional safety** and reversibility in development - -### Examples of unacceptable behavior: - -- The use of sexualized language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Publishing others' private information, such as a physical or email address, without their explicit permission -- Other conduct which could reasonably be considered inappropriate in a professional setting -- **Dismissing or minimizing** concerns about emotional safety -- **Gatekeeping** or elitism based on technical skill level -- **Weaponizing vulnerability** or reversibility features - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at: - -- **GitHub Issues**: [Report a concern](https://github.com/hyperpolymath/bunsenite/issues/new?labels=conduct) -- **GitLab**: Confidential issue on the repository - -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -## Emotional Safety Principles - -In alignment with our values of emotional safety and reversibility: - -### Encouragement Over Criticism - -- **Positive framing**: Frame feedback constructively -- **Assume good intent**: Mistakes are learning opportunities -- **Celebrate experimentation**: Failures are valuable when reversible -- **Support learning**: Everyone is learning, regardless of experience level - -### Reversibility in Community Interactions - -- **Mistakes can be fixed**: Technical mistakes are reversible through Git -- **Apologies matter**: Sincere apologies can repair social mistakes -- **Growth mindset**: People can change and improve -- **Second chances**: Unless patterns of harm persist - -### Political Autonomy - -- **Technical decisions**: Based on merit, not politics -- **No gatekeeping**: Access based on conduct, not views -- **Respectful disagreement**: Disagree on ideas, not people -- **Community sovereignty**: This community makes its own decisions - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. - -Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC]. - -For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations]. - -[homepage]: https://www.contributor-covenant.org -[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html -[Mozilla CoC]: https://github.com/mozilla/diversity -[FAQ]: https://www.contributor-covenant.org/faq -[translations]: https://www.contributor-covenant.org/translations - ---- - -**Last updated**: 2025-11-22 -**Version**: 1.0.0 (Aligned with RSR Framework & TPCF principles) diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..dab29bd --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,3 @@ +== Contributing + +See CONTRIBUTING.adoc for full contribution guidelines. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 66fae77..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,7 +0,0 @@ - -# Contributing - -See [CONTRIBUTING.adoc](CONTRIBUTING.adoc) for full contribution guidelines. diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc index e41020d..9b836fb 100644 --- a/GOVERNANCE.adoc +++ b/GOVERNANCE.adoc @@ -1,162 +1,60 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell -= Governance Model -:toc: preamble +== Governance -This document describes the governance model for this repository. +=== Overview -== Overview +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. -This repository follows a **Sole Maintainer Governance Model**: +=== Roles and Responsibilities -* Single maintainer (@hyperpolymath) has full authority over the project -* All contributions are welcome and reviewed by the maintainer -* Decisions are made transparently through GitHub issues and discussions -* The project adheres to the hyperpolymath estate policies where applicable +==== Maintainers -== Core Principles +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support -[cols="1,2"] -|=== -| Principle | Description +==== Contributors -| **Benevolent Dictatorship** | Maintainer has final decision authority but seeks community input +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed -| **Meritocracy** | Contributions are judged on technical merit, not contributor identity +=== Decision Making -| **Transparency** | All significant decisions are documented publicly +==== Minor Changes -| **Consensus-Seeking** | Maintainer prefers consensus but will decide when necessary +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates -| **Open Contribution** | Anyone can contribute via fork and pull request +==== Major Changes -|=== +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers -== Roles and Permissions +==== Breaking Changes -[cols="1,2,2"] -|=== -| Role | Permissions | Assignment +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide -| **Maintainer** | Write access, merge rights, admin | @hyperpolymath -| **Contributors** | Read access, fork, submit PRs | All GitHub users -| **Users** | Use the software, report issues | All GitHub users +=== Code of Conduct -|=== +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. -== Decision Making Framework +=== Communication -=== Routine Decisions +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions -* Bug fixes -* Documentation improvements -* Minor feature additions -* Dependency updates +=== Licensing -**Process**: Maintainer reviews and merges PRs that meet quality standards. +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. -=== Significant Changes +''''' -* New major features -* API changes -* Architecture modifications -* Breaking changes - -**Process**: -. Open issue describing the change -. Discuss with community (minimum 72 hours) -. Maintainer makes final decision -. Document rationale in issue/PR - -=== Structural Decisions - -* Repository purpose/renaming -* License changes -* Ownership transfer -* Deprecation/archival - -**Process**: -. Extended discussion (minimum 1 week) -. Maintainer makes final decision -. Document in CHANGELOG and governance docs - -== Contribution Lifecycle - -[cols="1,2"] -|=== -| Stage | Process - -| **Ideation** | Open issue, discuss feasibility - -| **Development** | Fork, implement, test thoroughly - -| **Review** | Submit PR, maintainer reviews within 7 days - -| **Merge** | Maintainer merges or requests changes - -| **Release** | Maintainer publishes according to project conventions - -|=== - -== Conflict Resolution - -In case of disagreements: - -. Discuss in the relevant GitHub issue or PR -. Provide technical justification for positions -. Maintainer mediates and makes final decision -. Decision is documented and can be revisited later - -== Project Policies - -This repository adheres to hyperpolymath estate-wide policies: - -* **License**: MPL-2.0 for code, CC-BY-SA-4.0 for prose (per standards/LICENCE-POLICY.adoc) -* **Code of Conduct**: Follows hyperpolymath CODE_OF_CONDUCT.md -* **Security**: Follows hyperpolymath SECURITY.md -* **Contributing**: Follows hyperpolymath CONTRIBUTING.adoc conventions - -== Repository-Specific Conventions - -[cols="1,2"] -|=== -| Convention | Description - -| **Signing** | All commits must be signed (SSH or GPG) - -| **SPDX Headers** | All source files must have SPDX license identifiers - -| **Contractiles** | Mustfile, Trustfile, Intendfile, Adjustfile in root - -| **Machine Readable** | META.a2ml in .machine_readable/6a2/ - -| **CI/CD** | GitHub Actions workflows in .github/workflows/ - -|=== - -== Governance Evolution - -As the project grows, this governance model may evolve: - -* **Adding Co-Maintainers**: When contribution volume warrants it -* **Forming a Team**: For complex multi-maintainer projects -* **Adopting TPCF**: For large, multi-repository projects (see rhodium-standard-repositories) - -Changes to this document require the same process as Significant Changes above. - -== See Also - -* link:MAINTAINERS.adoc[Maintainers] -* link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:CONTRIBUTING.adoc[Contributing Guide] -* link:https://github.com/hyperpolymath/standards/blob/main/LICENCE-POLICY.adoc[Estate License Policy] -* link:https://github.com/hyperpolymath/standards[rhodium-standard-repositories (TPCF)] - -== Changelog - -[cols="1,1,1"] -|=== -| Date | Change | By - -| 2026-06-07 | Initial governance model established | @hyperpolymath -|=== +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/MAINTAINERS.adoc b/MAINTAINERS.adoc index aa23a55..bbf10ba 100644 --- a/MAINTAINERS.adoc +++ b/MAINTAINERS.adoc @@ -1,48 +1,227 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This document lists the maintainers of the Bunsenite project and +describes the maintenance structure. -== Current Maintainers +=== Current Maintainers -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact +==== Core Team (Perimeter 1) -| Jonathan D.A. Jewell -| Lead Maintainer -| https://github.com/hyperpolymath[@hyperpolymath] -|=== +These individuals have write access to the main repository and make +final decisions on merges and releases. -== Responsibilities +* *Campaign for Cooler Coding and Programming* (@cccp) +** Role: Lead Maintainer, Project Founder +** Contact: https://github.com/hyperpolymath/bunsenite/issues[GitHub +Issues] +** Focus: Overall architecture, releases, community -Maintainers are responsible for: +==== Trusted Contributors (Perimeter 2) -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +These individuals have demonstrated consistent quality contributions and +may have specialized access or responsibilities. -== Becoming a Maintainer +_(Currently none - invitations extended based on sustained +contributions)_ -Contributors who demonstrate: +=== Contribution Perimeters (TPCF) -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +This project uses the *Tri-Perimeter Contribution Framework*: -May be invited to become maintainers at the discretion of existing maintainers. +==== Perimeter 1: Core Maintainers -== Decision Making +* *Access*: Full write access +* *Responsibilities*: +** Review and merge PRs +** Release management +** Security response +** Community moderation +** Strategic direction +* *Membership*: By invitation, based on sustained commitment and +expertise -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +==== Perimeter 2: Trusted Contributors -== Contact +* *Access*: Some specialized permissions (e.g., CI configuration, docs) +* *Responsibilities*: +** Detailed code review +** Mentoring new contributors +** Area-specific expertise +** Triage issues +* *Membership*: By invitation from Perimeter 1, based on consistent +quality contributions -For questions about project governance, open an issue or contact the maintainers listed above. +==== Perimeter 3: Community Sandbox + +* *Access*: Open to all +* *Responsibilities*: +** Submit issues and PRs +** Participate in discussions +** Help other users +* *Membership*: Automatic for all contributors + +=== Areas of Responsibility + +==== Rust Core + +* *Lead*: Core Team +* *Focus*: `+src/lib.rs+`, `+src/loader.rs+`, `+src/error.rs+` +* *Reviewers*: Core Team + +==== WASM Bindings + +* *Lead*: Core Team +* *Focus*: `+src/wasm.rs+`, WASM build system +* *Reviewers*: Core Team + +==== FFI Bindings + +* *Lead*: Core Team (seeking volunteers) +* *Focus*: `+bindings/deno/+`, `+bindings/affinescript/+`, Zig layer +* *Reviewers*: Core Team + +==== CLI + +* *Lead*: Core Team +* *Focus*: `+src/main.rs+`, user experience +* *Reviewers*: Core Team + +==== Documentation + +* *Lead*: Core Team (help wanted!) +* *Focus*: README, CLAUDE.md, API docs, examples +* *Reviewers*: Any maintainer + +==== Infrastructure + +* *Lead*: Core Team +* *Focus*: CI/CD, Justfile, Guix flake, releases +* *Reviewers*: Core Team + +==== Security + +* *Lead*: Core Team +* *Contact*: +https://github.com/hyperpolymath/bunsenite/security/advisories/new[GitHub +Security Advisories] +* *Focus*: Vulnerability response, security audits, dependency audits +* *Reviewers*: Core Team only + +=== Maintenance Policies + +==== Code Review + +* *Required*: At least 1 maintainer approval for all PRs +* *Self-merge*: Core team may merge own PRs for minor changes (typos, +formatting) +* *Security*: Security PRs require 2 approvals +* *Breaking changes*: Require discussion and 2 approvals + +==== Release Process + +[arabic] +. *Version bump*: Update `+Cargo.toml+`, `+CHANGELOG.md+` +. *Testing*: All tests must pass +. *Documentation*: Update docs as needed +. *Tag*: Create git tag `+vX.Y.Z+` +. *Release*: Create GitLab release with notes +. *Publish*: Publish to crates.io +. *Announce*: Announce in discussions/issues + +==== Issue Triage + +* *Labeling*: Apply appropriate labels (`+bug+`, `+enhancement+`, +`+documentation+`, etc.) +* *Priority*: Assign priority (`+P0+`-`+P3+`) +* *Assignment*: Assign to maintainer or leave unassigned for community +* *Response time*: Aim for initial response within 1 week + +==== Security Response + +* *Initial response*: Within 48 hours +* *Triage*: Within 1 week +* *Fix*: According to severity (see SECURITY.md) +* *Disclosure*: Coordinated, typically 90 days after fix + +=== Becoming a Maintainer + +==== Path to Perimeter 2 (Trusted Contributor) + +We look for: + +* *Consistent contributions*: Regular, quality contributions over 3+ +months +* *Code quality*: Well-tested, documented, follows conventions +* *Community*: Helpful in discussions, reviews others’ PRs +* *Alignment*: Understands and embodies project values (reversibility, +emotional safety, political autonomy) + +*Process*: 1. Core team discusses potential invitation 2. Invitation +extended via private message 3. 1-month trial period 4. Full membership +if successful + +==== Path to Perimeter 1 (Core Maintainer) + +We look for: + +* *Sustained commitment*: 6+ months of active, quality participation +* *Deep expertise*: Domain knowledge in core areas +* *Leadership*: Mentors others, drives initiatives +* *Trust*: Demonstrated judgment and alignment with project values + +*Process*: 1. Nominated by existing core maintainer 2. Discussion among +core team 3. Unanimous approval required 4. Onboarding period with +gradual permission increase + +=== Stepping Down + +Maintainers may step down at any time: + +* *Voluntary*: No explanation needed, though appreciated +* *Inactive*: After 6 months of inactivity, we may reach out to confirm +status +* *Emeritus*: Former maintainers are honored and may be consulted + +*Process*: 1. Notify core team 2. Remove permissions 3. Update +MAINTAINERS.md 4. Thank you! 🎉 + +=== Conflict Resolution + +==== Technical Disagreements + +[arabic] +. *Discussion*: Discuss in issue/MR +. *Evidence*: Present evidence and rationale +. *Consensus*: Aim for consensus +. *Vote*: If no consensus, core team votes (simple majority) +. *Document*: Document decision and rationale + +==== Interpersonal Conflicts + +[arabic] +. *Direct*: Speak directly with the person (if safe) +. *Mediation*: Request mediation from another maintainer +. *Code of Conduct*: File CoC complaint if needed +. *Resolution*: Follow CoC enforcement guidelines + +=== Contact + +* *General*: https://github.com/hyperpolymath/bunsenite/issues[GitHub +Issues] +* *Security*: +https://github.com/hyperpolymath/bunsenite/security/advisories/new[GitHub +Security Advisories] +* *GitHub*: https://github.com/hyperpolymath[@hyperpolymath] +* *GitLab*: https://gitlab.com/hyperpolymath[@hyperpolymath] + +=== Acknowledgments + +Thank you to all contributors, whether Perimeter 1, 2, or 3. Every +contribution matters! + +Special thanks to: - Nickel language team (nickel-lang-core) - RSR +Framework contributors - TPCF community - All early adopters and testers + +''''' + +*Last updated*: 2025-11-22 *Version*: 1.0.0 diff --git a/MAINTAINERS.md b/MAINTAINERS.md deleted file mode 100644 index 34e1b5f..0000000 --- a/MAINTAINERS.md +++ /dev/null @@ -1,211 +0,0 @@ - -# Maintainers - -This document lists the maintainers of the Bunsenite project and describes the maintenance structure. - -## Current Maintainers - -### Core Team (Perimeter 1) - -These individuals have write access to the main repository and make final decisions on merges and releases. - -- **Campaign for Cooler Coding and Programming** (@cccp) - - Role: Lead Maintainer, Project Founder - - Contact: [GitHub Issues](https://github.com/hyperpolymath/bunsenite/issues) - - Focus: Overall architecture, releases, community - -### Trusted Contributors (Perimeter 2) - -These individuals have demonstrated consistent quality contributions and may have specialized access or responsibilities. - -*(Currently none - invitations extended based on sustained contributions)* - -## Contribution Perimeters (TPCF) - -This project uses the **Tri-Perimeter Contribution Framework**: - -### Perimeter 1: Core Maintainers -- **Access**: Full write access -- **Responsibilities**: - - Review and merge PRs - - Release management - - Security response - - Community moderation - - Strategic direction -- **Membership**: By invitation, based on sustained commitment and expertise - -### Perimeter 2: Trusted Contributors -- **Access**: Some specialized permissions (e.g., CI configuration, docs) -- **Responsibilities**: - - Detailed code review - - Mentoring new contributors - - Area-specific expertise - - Triage issues -- **Membership**: By invitation from Perimeter 1, based on consistent quality contributions - -### Perimeter 3: Community Sandbox -- **Access**: Open to all -- **Responsibilities**: - - Submit issues and PRs - - Participate in discussions - - Help other users -- **Membership**: Automatic for all contributors - -## Areas of Responsibility - -### Rust Core -- **Lead**: Core Team -- **Focus**: `src/lib.rs`, `src/loader.rs`, `src/error.rs` -- **Reviewers**: Core Team - -### WASM Bindings -- **Lead**: Core Team -- **Focus**: `src/wasm.rs`, WASM build system -- **Reviewers**: Core Team - -### FFI Bindings -- **Lead**: Core Team (seeking volunteers) -- **Focus**: `bindings/deno/`, `bindings/affinescript/`, Zig layer -- **Reviewers**: Core Team - -### CLI -- **Lead**: Core Team -- **Focus**: `src/main.rs`, user experience -- **Reviewers**: Core Team - -### Documentation -- **Lead**: Core Team (help wanted!) -- **Focus**: README, CLAUDE.md, API docs, examples -- **Reviewers**: Any maintainer - -### Infrastructure -- **Lead**: Core Team -- **Focus**: CI/CD, Justfile, Guix flake, releases -- **Reviewers**: Core Team - -### Security -- **Lead**: Core Team -- **Contact**: [GitHub Security Advisories](https://github.com/hyperpolymath/bunsenite/security/advisories/new) -- **Focus**: Vulnerability response, security audits, dependency audits -- **Reviewers**: Core Team only - -## Maintenance Policies - -### Code Review - -- **Required**: At least 1 maintainer approval for all PRs -- **Self-merge**: Core team may merge own PRs for minor changes (typos, formatting) -- **Security**: Security PRs require 2 approvals -- **Breaking changes**: Require discussion and 2 approvals - -### Release Process - -1. **Version bump**: Update `Cargo.toml`, `CHANGELOG.md` -2. **Testing**: All tests must pass -3. **Documentation**: Update docs as needed -4. **Tag**: Create git tag `vX.Y.Z` -5. **Release**: Create GitLab release with notes -6. **Publish**: Publish to crates.io -7. **Announce**: Announce in discussions/issues - -### Issue Triage - -- **Labeling**: Apply appropriate labels (`bug`, `enhancement`, `documentation`, etc.) -- **Priority**: Assign priority (`P0`-`P3`) -- **Assignment**: Assign to maintainer or leave unassigned for community -- **Response time**: Aim for initial response within 1 week - -### Security Response - -- **Initial response**: Within 48 hours -- **Triage**: Within 1 week -- **Fix**: According to severity (see SECURITY.md) -- **Disclosure**: Coordinated, typically 90 days after fix - -## Becoming a Maintainer - -### Path to Perimeter 2 (Trusted Contributor) - -We look for: - -- **Consistent contributions**: Regular, quality contributions over 3+ months -- **Code quality**: Well-tested, documented, follows conventions -- **Community**: Helpful in discussions, reviews others' PRs -- **Alignment**: Understands and embodies project values (reversibility, emotional safety, political autonomy) - -**Process**: -1. Core team discusses potential invitation -2. Invitation extended via private message -3. 1-month trial period -4. Full membership if successful - -### Path to Perimeter 1 (Core Maintainer) - -We look for: - -- **Sustained commitment**: 6+ months of active, quality participation -- **Deep expertise**: Domain knowledge in core areas -- **Leadership**: Mentors others, drives initiatives -- **Trust**: Demonstrated judgment and alignment with project values - -**Process**: -1. Nominated by existing core maintainer -2. Discussion among core team -3. Unanimous approval required -4. Onboarding period with gradual permission increase - -## Stepping Down - -Maintainers may step down at any time: - -- **Voluntary**: No explanation needed, though appreciated -- **Inactive**: After 6 months of inactivity, we may reach out to confirm status -- **Emeritus**: Former maintainers are honored and may be consulted - -**Process**: -1. Notify core team -2. Remove permissions -3. Update MAINTAINERS.md -4. Thank you! 🎉 - -## Conflict Resolution - -### Technical Disagreements - -1. **Discussion**: Discuss in issue/MR -2. **Evidence**: Present evidence and rationale -3. **Consensus**: Aim for consensus -4. **Vote**: If no consensus, core team votes (simple majority) -5. **Document**: Document decision and rationale - -### Interpersonal Conflicts - -1. **Direct**: Speak directly with the person (if safe) -2. **Mediation**: Request mediation from another maintainer -3. **Code of Conduct**: File CoC complaint if needed -4. **Resolution**: Follow CoC enforcement guidelines - -## Contact - -- **General**: [GitHub Issues](https://github.com/hyperpolymath/bunsenite/issues) -- **Security**: [GitHub Security Advisories](https://github.com/hyperpolymath/bunsenite/security/advisories/new) -- **GitHub**: [@hyperpolymath](https://github.com/hyperpolymath) -- **GitLab**: [@hyperpolymath](https://gitlab.com/hyperpolymath) - -## Acknowledgments - -Thank you to all contributors, whether Perimeter 1, 2, or 3. Every contribution matters! - -Special thanks to: -- Nickel language team (nickel-lang-core) -- RSR Framework contributors -- TPCF community -- All early adopters and testers - ---- - -**Last updated**: 2025-11-22 -**Version**: 1.0.0 diff --git a/PACKAGING.adoc b/PACKAGING.adoc new file mode 100644 index 0000000..a2c2235 --- /dev/null +++ b/PACKAGING.adoc @@ -0,0 +1,148 @@ +== Bunsenite Packaging Guide + +This document describes how to package and distribute Bunsenite for +various package managers. + +=== Package Managers + +==== Linux + +[cols=",,",options="header",] +|=== +|Manager |Distro |Config Location +|pacman |Arch Linux |`+packaging/arch/PKGBUILD+` +|apt |Debian/Ubuntu |`+packaging/debian/+` +|dnf |Fedora/RHEL |`+packaging/rpm/bunsenite.spec+` +|zypper |openSUSE |`+packaging/rpm/bunsenite.spec+` +|flatpak |Universal |`+packaging/flatpak/+` +|=== + +==== macOS + +[cols=",",options="header",] +|=== +|Manager |Config Location +|Homebrew |`+packaging/homebrew/bunsenite.rb+` +|MacPorts |`+packaging/macports/Portfile+` +|=== + +==== Windows + +[cols=",",options="header",] +|=== +|Manager |Config Location +|Scoop |`+packaging/scoop/bunsenite.json+` +|Chocolatey |`+packaging/chocolatey/bunsenite.nuspec+` +|winget |`+packaging/winget/bunsenite.yaml+` +|=== + +==== Language Package Managers + +[cols=",,",options="header",] +|=== +|Manager |Language |Location +|cargo |Rust |`+Cargo.toml+` (publish to crates.io) +|npm |Node.js |`+bindings/affinescript/package.json+` +|deno.land/x |Deno |`+bindings/deno/+` (publish to deno.land) +|=== + +=== Build Requirements + +All packaging scripts assume: + +[arabic] +. *Rust 1.70+* - For the core library +. *Zig 0.11+* - For the FFI layer +. *Git* - For source fetching + +=== Building Release Artifacts + +[source,bash] +---- +# Build with all features +cargo build --release --features full + +# Build Zig FFI layer +cd zig && zig build -Doptimize=ReleaseFast + +# Run tests +cargo test --release +---- + +=== Release Artifacts + +Each release should include: + +==== Linux (x86_64, aarch64) + +* `+bunsenite-VERSION-x86_64-unknown-linux-gnu.tar.gz+` +* `+bunsenite-VERSION-aarch64-unknown-linux-gnu.tar.gz+` + +==== macOS (x86_64, aarch64) + +* `+bunsenite-VERSION-x86_64-apple-darwin.tar.gz+` +* `+bunsenite-VERSION-aarch64-apple-darwin.tar.gz+` + +==== Windows (x86_64) + +* `+bunsenite-VERSION-x86_64-pc-windows-msvc.zip+` + +==== Source + +* `+bunsenite-VERSION.tar.gz+` + +=== Publishing Checklist + +==== crates.io (Rust) + +[source,bash] +---- +cargo publish --dry-run +cargo publish +---- + +==== npm (Node.js bindings) + +[source,bash] +---- +cd bindings/affinescript +npm publish --access public +---- + +==== Homebrew + +[arabic] +. Fork homebrew-core +. Update `+bunsenite.rb+` with new version and sha256 +. Submit PR + +==== Arch Linux (AUR) + +[arabic] +. Update PKGBUILD with new version +. Generate .SRCINFO: `+makepkg --printsrcinfo > .SRCINFO+` +. Push to AUR + +==== Flatpak (Flathub) + +[arabic] +. Fork flathub/com.campaignforcoolercoding.bunsenite +. Update manifest with new version +. Submit PR + +=== CI/CD Integration + +The `+.github/workflows/release.yml+` workflow automates: - Building +release binaries for all platforms - Creating GitHub releases with +artifacts - Publishing to crates.io + +=== RSR Compliance Notes + +All packages must include: - LICENSE-MPL-2.0 - LICENSE-PALIMPSEST (if +applicable) - README.md with RSR tier disclosure + +Package descriptions should include: + +.... +RSR Compliance: Bronze Tier | TPCF Perimeter: 3 +.... diff --git a/PACKAGING.md b/PACKAGING.md deleted file mode 100644 index 8997108..0000000 --- a/PACKAGING.md +++ /dev/null @@ -1,129 +0,0 @@ - -# Bunsenite Packaging Guide - -This document describes how to package and distribute Bunsenite for various package managers. - -## Package Managers - -### Linux - -| Manager | Distro | Config Location | -|---------|--------|-----------------| -| pacman | Arch Linux | `packaging/arch/PKGBUILD` | -| apt | Debian/Ubuntu | `packaging/debian/` | -| dnf | Fedora/RHEL | `packaging/rpm/bunsenite.spec` | -| zypper | openSUSE | `packaging/rpm/bunsenite.spec` | -| flatpak | Universal | `packaging/flatpak/` | - -### macOS - -| Manager | Config Location | -|---------|-----------------| -| Homebrew | `packaging/homebrew/bunsenite.rb` | -| MacPorts | `packaging/macports/Portfile` | - -### Windows - -| Manager | Config Location | -|---------|-----------------| -| Scoop | `packaging/scoop/bunsenite.json` | -| Chocolatey | `packaging/chocolatey/bunsenite.nuspec` | -| winget | `packaging/winget/bunsenite.yaml` | - -### Language Package Managers - -| Manager | Language | Location | -|---------|----------|----------| -| cargo | Rust | `Cargo.toml` (publish to crates.io) | -| npm | Node.js | `bindings/affinescript/package.json` | -| deno.land/x | Deno | `bindings/deno/` (publish to deno.land) | - -## Build Requirements - -All packaging scripts assume: - -1. **Rust 1.70+** - For the core library -2. **Zig 0.11+** - For the FFI layer -3. **Git** - For source fetching - -## Building Release Artifacts - -```bash -# Build with all features -cargo build --release --features full - -# Build Zig FFI layer -cd zig && zig build -Doptimize=ReleaseFast - -# Run tests -cargo test --release -``` - -## Release Artifacts - -Each release should include: - -### Linux (x86_64, aarch64) -- `bunsenite-VERSION-x86_64-unknown-linux-gnu.tar.gz` -- `bunsenite-VERSION-aarch64-unknown-linux-gnu.tar.gz` - -### macOS (x86_64, aarch64) -- `bunsenite-VERSION-x86_64-apple-darwin.tar.gz` -- `bunsenite-VERSION-aarch64-apple-darwin.tar.gz` - -### Windows (x86_64) -- `bunsenite-VERSION-x86_64-pc-windows-msvc.zip` - -### Source -- `bunsenite-VERSION.tar.gz` - -## Publishing Checklist - -### crates.io (Rust) -```bash -cargo publish --dry-run -cargo publish -``` - -### npm (Node.js bindings) -```bash -cd bindings/affinescript -npm publish --access public -``` - -### Homebrew -1. Fork homebrew-core -2. Update `bunsenite.rb` with new version and sha256 -3. Submit PR - -### Arch Linux (AUR) -1. Update PKGBUILD with new version -2. Generate .SRCINFO: `makepkg --printsrcinfo > .SRCINFO` -3. Push to AUR - -### Flatpak (Flathub) -1. Fork flathub/com.campaignforcoolercoding.bunsenite -2. Update manifest with new version -3. Submit PR - -## CI/CD Integration - -The `.github/workflows/release.yml` workflow automates: -- Building release binaries for all platforms -- Creating GitHub releases with artifacts -- Publishing to crates.io - -## RSR Compliance Notes - -All packages must include: -- LICENSE-MPL-2.0 -- LICENSE-PALIMPSEST (if applicable) -- README.md with RSR tier disclosure - -Package descriptions should include: -``` -RSR Compliance: Bronze Tier | TPCF Perimeter: 3 -``` diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..2cd88d9 --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,41 @@ +== Proof Requirements + +=== Current state + +* `+src/abi/Types.idr+` — Nickel parser types +* `+src/abi/Layout.idr+` — Memory layout +* `+src/abi/Foreign.idr+` — FFI declarations +* No dangerous patterns in ABI layer +* Claims: type safety, memory safety, "`zero `+unsafe+` blocks`" + +=== What needs proving + +* *Parser correctness*: Prove the Nickel parser accepts exactly the +Nickel grammar (no over-acceptance of malformed input) +* *Round-trip fidelity*: Prove parse-then-serialize produces +semantically equivalent output (no silent data loss) +* *FFI memory safety*: Prove the Zig FFI layer correctly manages +ownership across the Rust-Zig-Deno/WASM boundary (no dangling pointers, +no double-free) +* *Zero-unsafe claim*: Verify (via tooling or proof) that no `+unsafe+` +blocks exist in the Rust core and that all FFI crossing points are safe + +=== Recommended prover + +* *Idris2* — For parser grammar conformance and FFI boundary properties +* *Lean4* — For algebraic properties of the parse/serialize round-trip +if modeled functorially + +=== Priority + +* *MEDIUM* — The "`zero unsafe blocks`" and type safety claims are +strong marketing. Parser correctness matters for any tool in the +configuration pipeline, but Bunsenite is not safety-critical +infrastructure. + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +\{\{PROJECT}}/\{\{AUTHOR}} placeholders and no domain-specific proofs. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index f451a66..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,31 +0,0 @@ - -# Proof Requirements - -## Current state -- `src/abi/Types.idr` — Nickel parser types -- `src/abi/Layout.idr` — Memory layout -- `src/abi/Foreign.idr` — FFI declarations -- No dangerous patterns in ABI layer -- Claims: type safety, memory safety, "zero `unsafe` blocks" - -## What needs proving -- **Parser correctness**: Prove the Nickel parser accepts exactly the Nickel grammar (no over-acceptance of malformed input) -- **Round-trip fidelity**: Prove parse-then-serialize produces semantically equivalent output (no silent data loss) -- **FFI memory safety**: Prove the Zig FFI layer correctly manages ownership across the Rust-Zig-Deno/WASM boundary (no dangling pointers, no double-free) -- **Zero-unsafe claim**: Verify (via tooling or proof) that no `unsafe` blocks exist in the Rust core and that all FFI crossing points are safe - -## Recommended prover -- **Idris2** — For parser grammar conformance and FFI boundary properties -- **Lean4** — For algebraic properties of the parse/serialize round-trip if modeled functorially - -## Priority -- **MEDIUM** — The "zero unsafe blocks" and type safety claims are strong marketing. Parser correctness matters for any tool in the configuration pipeline, but Bunsenite is not safety-critical infrastructure. - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved {{PROJECT}}/{{AUTHOR}} placeholders and no domain-specific proofs. diff --git a/PROVEN-INTEGRATION.adoc b/PROVEN-INTEGRATION.adoc new file mode 100644 index 0000000..4a4ff2a --- /dev/null +++ b/PROVEN-INTEGRATION.adoc @@ -0,0 +1,120 @@ +== Proven Library Integration Plan + +This document outlines how the +https://github.com/hyperpolymath/proven[proven] library’s formally +verified modules integrate with Bunsenite. + +=== Applicable Modules + +==== High Priority + +[cols=",,",options="header",] +|=== +|Module |Use Case |Formal Guarantee +|`+SafeSchema+` |Nickel config validation |Type-safe configurations +|`+SafeFFI+` |FFI boundary safety |ABI contract verification +|`+SafeBuffer+` |Config parsing buffer |Bounded memory usage +|=== + +==== Medium Priority + +[cols=",,",options="header",] +|=== +|Module |Use Case |Formal Guarantee +|`+SafeString+` |Config interpolation |Injection prevention +|`+SafeTree+` |Config tree navigation |ValidPath proofs +|`+SafeResource+` |File handle lifecycle |Valid state transitions +|=== + +=== Integration Points + +==== 1. Config Schema Validation (SafeSchema) + +[source,nickel] +---- +# Nickel config +{ + name = "my-app", + port = 8080, + features = ["auth", "logging"] +} +---- + +.... +parse → SafeSchema.validate → typed NickelConfig +.... + +SafeSchema ensures: - Required fields are present - Field types match +declarations - Contract constraints are satisfied + +==== 2. FFI Boundary Safety (SafeFFI) + +Bunsenite’s C ABI boundary is where safety is most critical: + +.... +Rust → SafeFFI.marshal → C ABI → SafeFFI.unmarshal → Deno/AffineScript +.... + +SafeFFI guarantees: - Memory ownership is correctly transferred - +Buffers are correctly sized and aligned - Error codes are properly +propagated - No use-after-free or double-free + +==== 3. Parsing Buffer Management (SafeBuffer) + +.... +config_file → SafeBuffer.BoundedBuffer → parse → result +.... + +Prevents: - Stack overflow on deeply nested configs - OOM on maliciously +large inputs - Buffer overflows in string handling + +=== FFI Contract Proofs + +Bunsenite’s C ABI can be formally specified: + +[source,c] +---- +// include/bebop_v_ffi.h +struct BunseniteResult { + uint32_t status; // SafeFFI.ResultCode + void* data; // SafeFFI.OwnedPtr + size_t len; // SafeFFI.BoundedSize +}; +---- + +SafeFFI proves: - `+status == OK+` ⟹ `+data != NULL ∧ len > 0+` - +`+status == ERROR+` ⟹ `+data+` contains error message - Caller owns +`+data+` and must free it + +=== Language Binding Integration + +[cols=",,",options="header",] +|=== +|Binding |FFI Layer |proven Module +|Deno |Deno.dlopen |SafeFFI +|AffineScript |External FFI |SafeFFI +|WASM |Wasm bindgen |SafeBuffer +|=== + +=== Implementation Notes + +For Rust core integration: + +[source,rust] +---- +// src/lib.rs +#[cfg(feature = "proven")] +mod proven_bindings { + // SafeSchema validation before returning to FFI + pub fn validate_config(input: &str) -> Result { + SafeSchema::validate(input)? + } +} +---- + +=== Status + +* [ ] Add SafeSchema for Nickel config validation +* [ ] Integrate SafeFFI for ABI contract verification +* [ ] Implement SafeBuffer for bounded parsing +* [ ] Generate proofs for C ABI contract diff --git a/PROVEN-INTEGRATION.md b/PROVEN-INTEGRATION.md deleted file mode 100644 index 6d4ce1c..0000000 --- a/PROVEN-INTEGRATION.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Proven Library Integration Plan - -This document outlines how the [proven](https://github.com/hyperpolymath/proven) library's formally verified modules integrate with Bunsenite. - -## Applicable Modules - -### High Priority - -| Module | Use Case | Formal Guarantee | -|--------|----------|------------------| -| `SafeSchema` | Nickel config validation | Type-safe configurations | -| `SafeFFI` | FFI boundary safety | ABI contract verification | -| `SafeBuffer` | Config parsing buffer | Bounded memory usage | - -### Medium Priority - -| Module | Use Case | Formal Guarantee | -|--------|----------|------------------| -| `SafeString` | Config interpolation | Injection prevention | -| `SafeTree` | Config tree navigation | ValidPath proofs | -| `SafeResource` | File handle lifecycle | Valid state transitions | - -## Integration Points - -### 1. Config Schema Validation (SafeSchema) - -```nickel -# Nickel config -{ - name = "my-app", - port = 8080, - features = ["auth", "logging"] -} -``` - -``` -parse → SafeSchema.validate → typed NickelConfig -``` - -SafeSchema ensures: -- Required fields are present -- Field types match declarations -- Contract constraints are satisfied - -### 2. FFI Boundary Safety (SafeFFI) - -Bunsenite's C ABI boundary is where safety is most critical: - -``` -Rust → SafeFFI.marshal → C ABI → SafeFFI.unmarshal → Deno/AffineScript -``` - -SafeFFI guarantees: -- Memory ownership is correctly transferred -- Buffers are correctly sized and aligned -- Error codes are properly propagated -- No use-after-free or double-free - -### 3. Parsing Buffer Management (SafeBuffer) - -``` -config_file → SafeBuffer.BoundedBuffer → parse → result -``` - -Prevents: -- Stack overflow on deeply nested configs -- OOM on maliciously large inputs -- Buffer overflows in string handling - -## FFI Contract Proofs - -Bunsenite's C ABI can be formally specified: - -```c -// include/bebop_v_ffi.h -struct BunseniteResult { - uint32_t status; // SafeFFI.ResultCode - void* data; // SafeFFI.OwnedPtr - size_t len; // SafeFFI.BoundedSize -}; -``` - -SafeFFI proves: -- `status == OK` ⟹ `data != NULL ∧ len > 0` -- `status == ERROR` ⟹ `data` contains error message -- Caller owns `data` and must free it - -## Language Binding Integration - -| Binding | FFI Layer | proven Module | -|---------|-----------|---------------| -| Deno | Deno.dlopen | SafeFFI | -| AffineScript | External FFI | SafeFFI | -| WASM | Wasm bindgen | SafeBuffer | - -## Implementation Notes - -For Rust core integration: - -```rust -// src/lib.rs -#[cfg(feature = "proven")] -mod proven_bindings { - // SafeSchema validation before returning to FFI - pub fn validate_config(input: &str) -> Result { - SafeSchema::validate(input)? - } -} -``` - -## Status - -- [ ] Add SafeSchema for Nickel config validation -- [ ] Integrate SafeFFI for ABI contract verification -- [ ] Implement SafeBuffer for bounded parsing -- [ ] Generate proofs for C ABI contract diff --git a/PUBLISHING.adoc b/PUBLISHING.adoc new file mode 100644 index 0000000..64a3810 --- /dev/null +++ b/PUBLISHING.adoc @@ -0,0 +1,155 @@ +== Publishing Bunsenite + +This guide walks through publishing bunsenite to all package managers. + +=== Prerequisites + +You’ll need accounts and tokens for: - *crates.io* - Rust package +registry - *npm* - Node.js package registry - *GitHub* - For releases +and Homebrew tap + +=== Step 1: Configure GitHub Secrets + +Go to your repo → Settings → Secrets and variables → Actions → New +repository secret + +[width="100%",cols="47%,53%",options="header",] +|=== +|Secret Name |How to Get It +|`+CARGO_REGISTRY_TOKEN+` |https://crates.io/settings/tokens → New Token + +|`+NPM_TOKEN+` |https://www.npmjs.com/settings/tokens → Generate New +Token (Automation) +|=== + +=== Step 2: Create and Push a Tag + +[source,bash] +---- +# Create the v1.0.0 tag +git tag -a v1.0.0 -m "Release v1.0.0" + +# Push the tag (this triggers the release workflow) +git push origin v1.0.0 +---- + +This automatically: - Builds binaries for Linux, macOS, Windows - +Creates a GitHub Release with all artifacts - Publishes to crates.io - +Publishes to npm + +=== Step 3: Homebrew (Manual) + +Option A: *Create your own tap* (recommended for new packages): + +[source,bash] +---- +# Create a new repo: hyperpolymath/homebrew-tap +# Then add the formula + +mkdir -p homebrew-tap/Formula +cp packaging/homebrew/bunsenite.rb homebrew-tap/Formula/ + +# Update the sha256 from the GitHub release +# Then users install with: +# brew tap hyperpolymath/tap +# brew install bunsenite +---- + +Option B: *Submit to homebrew-core* (after package is established): + +[source,bash] +---- +# Fork homebrew/homebrew-core +# Add Formula/bunsenite.rb +# Submit PR +---- + +=== Step 4: Arch Linux (AUR) + +[source,bash] +---- +# Clone your AUR package (first time: create it) +git clone ssh://aur@aur.archlinux.org/bunsenite.git aur-bunsenite +cd aur-bunsenite + +# Copy PKGBUILD +cp ../packaging/arch/PKGBUILD . + +# Update checksums +updpkgsums + +# Generate .SRCINFO +makepkg --printsrcinfo > .SRCINFO + +# Commit and push +git add PKGBUILD .SRCINFO +git commit -m "Update to v1.0.0" +git push +---- + +=== Step 5: Other Package Managers + +==== Flatpak (Flathub) + +[arabic] +. Fork https://github.com/flathub/flathub +. Create `+com.campaignforcoolercoding.bunsenite/+` directory +. Copy `+packaging/flatpak/com.campaignforcoolercoding.bunsenite.yml+` +. Submit PR + +==== Scoop (Windows) + +[arabic] +. Fork https://github.com/ScoopInstaller/Main (or create own bucket) +. Add `+bucket/bunsenite.json+` +. Submit PR + +==== Chocolatey (Windows) + +[source,bash] +---- +cd packaging/chocolatey +# Update bunsenite.nuspec with correct URLs +choco pack +choco push bunsenite.1.0.0.nupkg --source https://push.chocolatey.org/ +---- + +==== winget (Windows) + +[arabic] +. Fork https://github.com/microsoft/winget-pkgs +. Create `+manifests/c/CampaignForCoolerCoding/Bunsenite/1.0.0/+` +. Copy and split manifest files +. Submit PR + +=== Quick Start Commands + +[source,bash] +---- +# Step 1: Add secrets to GitHub (do this in browser) + +# Step 2: Tag and release +git tag -a v1.0.0 -m "Release v1.0.0" +git push origin v1.0.0 + +# Step 3: Wait for CI, then verify +# - Check GitHub Actions for build status +# - Check https://crates.io/crates/bunsenite +# - Check https://www.npmjs.com/package/bunsenite +---- + +=== Verification + +After publishing, verify each registry: + +[source,bash] +---- +# Cargo +cargo install bunsenite + +# npm +npm info bunsenite + +# GitHub Release +gh release view v1.0.0 +---- diff --git a/PUBLISHING.md b/PUBLISHING.md deleted file mode 100644 index d6716b9..0000000 --- a/PUBLISHING.md +++ /dev/null @@ -1,143 +0,0 @@ - -# Publishing Bunsenite - -This guide walks through publishing bunsenite to all package managers. - -## Prerequisites - -You'll need accounts and tokens for: -- **crates.io** - Rust package registry -- **npm** - Node.js package registry -- **GitHub** - For releases and Homebrew tap - -## Step 1: Configure GitHub Secrets - -Go to your repo → Settings → Secrets and variables → Actions → New repository secret - -| Secret Name | How to Get It | -|-------------|---------------| -| `CARGO_REGISTRY_TOKEN` | https://crates.io/settings/tokens → New Token | -| `NPM_TOKEN` | https://www.npmjs.com/settings/tokens → Generate New Token (Automation) | - -## Step 2: Create and Push a Tag - -```bash -# Create the v1.0.0 tag -git tag -a v1.0.0 -m "Release v1.0.0" - -# Push the tag (this triggers the release workflow) -git push origin v1.0.0 -``` - -This automatically: -- Builds binaries for Linux, macOS, Windows -- Creates a GitHub Release with all artifacts -- Publishes to crates.io -- Publishes to npm - -## Step 3: Homebrew (Manual) - -Option A: **Create your own tap** (recommended for new packages): - -```bash -# Create a new repo: hyperpolymath/homebrew-tap -# Then add the formula - -mkdir -p homebrew-tap/Formula -cp packaging/homebrew/bunsenite.rb homebrew-tap/Formula/ - -# Update the sha256 from the GitHub release -# Then users install with: -# brew tap hyperpolymath/tap -# brew install bunsenite -``` - -Option B: **Submit to homebrew-core** (after package is established): - -```bash -# Fork homebrew/homebrew-core -# Add Formula/bunsenite.rb -# Submit PR -``` - -## Step 4: Arch Linux (AUR) - -```bash -# Clone your AUR package (first time: create it) -git clone ssh://aur@aur.archlinux.org/bunsenite.git aur-bunsenite -cd aur-bunsenite - -# Copy PKGBUILD -cp ../packaging/arch/PKGBUILD . - -# Update checksums -updpkgsums - -# Generate .SRCINFO -makepkg --printsrcinfo > .SRCINFO - -# Commit and push -git add PKGBUILD .SRCINFO -git commit -m "Update to v1.0.0" -git push -``` - -## Step 5: Other Package Managers - -### Flatpak (Flathub) -1. Fork https://github.com/flathub/flathub -2. Create `com.campaignforcoolercoding.bunsenite/` directory -3. Copy `packaging/flatpak/com.campaignforcoolercoding.bunsenite.yml` -4. Submit PR - -### Scoop (Windows) -1. Fork https://github.com/ScoopInstaller/Main (or create own bucket) -2. Add `bucket/bunsenite.json` -3. Submit PR - -### Chocolatey (Windows) -```bash -cd packaging/chocolatey -# Update bunsenite.nuspec with correct URLs -choco pack -choco push bunsenite.1.0.0.nupkg --source https://push.chocolatey.org/ -``` - -### winget (Windows) -1. Fork https://github.com/microsoft/winget-pkgs -2. Create `manifests/c/CampaignForCoolerCoding/Bunsenite/1.0.0/` -3. Copy and split manifest files -4. Submit PR - -## Quick Start Commands - -```bash -# Step 1: Add secrets to GitHub (do this in browser) - -# Step 2: Tag and release -git tag -a v1.0.0 -m "Release v1.0.0" -git push origin v1.0.0 - -# Step 3: Wait for CI, then verify -# - Check GitHub Actions for build status -# - Check https://crates.io/crates/bunsenite -# - Check https://www.npmjs.com/package/bunsenite -``` - -## Verification - -After publishing, verify each registry: - -```bash -# Cargo -cargo install bunsenite - -# npm -npm info bunsenite - -# GitHub Release -gh release view v1.0.0 -``` diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..776e45e --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,235 @@ +== Security Policy + +=== Supported Versions + +We take security seriously and provide security updates for the +following versions: + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|1.0.x |:white_check_mark: |Current stable release +|< 1.0.0 |:x: |Pre-release, not supported +|=== + +=== Security Guarantees + +Bunsenite provides the following security guarantees: + +==== Memory Safety + +* *Zero `+unsafe+` blocks*: Enforced by `+#![deny(unsafe_code)]+` +compiler directive +* *Rust ownership model*: Prevents use-after-free, double-free, and +memory leaks +* *No null pointer dereferences*: Rust’s type system eliminates this +class of bugs +* *Bounds checking*: All array/vector accesses are bounds-checked + +==== Type Safety + +* *Compile-time guarantees*: Type errors are caught before runtime +* *No implicit conversions*: Explicit type conversions required +* *Strong typing*: Prevents type confusion vulnerabilities + +==== Dependency Security + +* *Minimal dependencies*: Only essential, well-audited crates +* *No network dependencies*: Offline-first design eliminates network +attack surface +* *Pinned versions*: Dependencies locked to specific versions for +reproducibility +* *Regular audits*: Dependencies audited using `+cargo audit+` + +==== Supply Chain Security + +* *Reproducible builds*: Guix flake provides bit-for-bit reproducibility +* *Signed releases*: All releases are cryptographically signed (planned) +* *Transparent development*: All changes tracked in public Git +repository +* *SBOM generation*: Software Bill of Materials available (planned) + +=== Reporting a Vulnerability + +*Please do NOT report security vulnerabilities through public +GitHub/GitLab issues.* + +==== Preferred Method + +Report security vulnerabilities via: + +[arabic] +. *GitHub Security Advisories*: +https://github.com/hyperpolymath/bunsenite/security/advisories/new[Create +a new security advisory] (preferred) +. *GitLab Confidential Issue*: Use GitLab’s confidential issue feature + +==== What to Include + +Please include: + +* *Description*: Clear description of the vulnerability +* *Impact*: What an attacker could achieve +* *Reproduction*: Step-by-step instructions to reproduce +* *Affected versions*: Which versions are affected +* *Proposed fix*: If you have one (optional) +* *Disclosure timeline*: Your preferred disclosure timeline + +==== Response Timeline + +* *Initial response*: Within 48 hours +* *Triage*: Within 1 week +* *Fix development*: Depends on severity (critical: days, low: weeks) +* *Public disclosure*: Coordinated with reporter, typically 90 days +after fix + +==== Severity Levels + +We use the following severity classifications: + +===== Critical (CVSS 9.0-10.0) + +* Remote code execution +* Privilege escalation to admin/root +* Authentication bypass + +*Response*: Patch within 48 hours, immediate release + +===== High (CVSS 7.0-8.9) + +* SQL injection (not applicable to Bunsenite) +* Information disclosure of sensitive data +* Denial of service affecting availability + +*Response*: Patch within 1 week, expedited release + +===== Medium (CVSS 4.0-6.9) + +* Cross-site scripting (XSS) (browser/WASM context) +* Information disclosure of non-sensitive data +* Low-impact denial of service + +*Response*: Patch within 2 weeks, next regular release + +===== Low (CVSS 0.1-3.9) + +* Minor information leaks +* Best practice violations +* Theoretical attacks with no known exploit + +*Response*: Patch within 30 days, next regular release + +=== Security Best Practices + +==== For Users + +[arabic] +. *Keep updated*: Always use the latest stable version +. *Verify signatures*: Check release signatures (when available) +. *Audit dependencies*: Run `+cargo audit+` regularly +. *Minimal permissions*: Run with least privilege necessary +. *Air-gapped environments*: Bunsenite works offline by design + +==== For Developers + +[arabic] +. *No `+unsafe+` code*: Never use `+unsafe+` blocks (enforced by +compiler) +. *Input validation*: Validate all external input +. *Error handling*: Use `+Result+` types, avoid `+unwrap()+` in library +code +. *Dependency review*: Review new dependencies carefully +. *Security testing*: Include security tests in test suite + +=== Known Limitations + +==== By Design + +[arabic] +. *Nickel evaluation*: Bunsenite evaluates Nickel code, which could +contain: +* Infinite loops (resource exhaustion) +* Large memory allocations +* Consider: Run evaluation in sandboxed environment for untrusted input +. *File I/O*: File reading follows OS permissions +* Does NOT escalate privileges +* Respects filesystem boundaries +. *WASM sandbox*: Browser WASM runs in sandbox, but: +* Subject to browser security model +* Can consume memory/CPU (denial of service) + +==== Mitigations + +We provide: + +* *Timeouts*: (Planned) Configurable evaluation timeouts +* *Memory limits*: (Planned) Configurable memory limits for evaluation +* *Resource monitoring*: (Planned) Track resource usage + +=== Security Audits + +[cols=",,,,",options="header",] +|=== +|Date |Auditor |Scope |Findings |Status +|2025-Q2 |Planned |Full codebase |N/A |Scheduled +|=== + +=== Cryptography + +Bunsenite does NOT implement cryptography. For cryptographic needs: + +* Use established libraries (e.g., `+ring+`, `+sodiumoxide+`) +* Never roll your own crypto +* Follow NIST/IETF recommendations + +=== Compliance + +* *OWASP Top 10*: N/A (not a web application) +* *CWE Top 25*: Memory safety issues prevented by Rust +* *GDPR*: No personal data collection +* *CCPA*: No personal data collection + +=== Security Tooling + +We use: + +* *`+cargo audit+`*: Check for known vulnerabilities in dependencies +* *`+cargo clippy+`*: Lint for security anti-patterns +* *`+cargo deny+`*: Check licenses and security advisories +* *GitLab Security Scanner*: Automated SAST in CI/CD +* *Dependabot*: (Planned) Automated dependency updates + +=== Contact + +* *GitHub Security Advisories*: +https://github.com/hyperpolymath/bunsenite/security/advisories/new[Report +a vulnerability] +* *Security.txt*: See `+.well-known/security.txt+` (RFC 9116 compliant) + +=== Attribution + +We believe in responsible disclosure and will credit security +researchers who: + +* Report vulnerabilities responsibly +* Allow coordinated disclosure +* Follow our security policy + +Credits will be listed in: - CHANGELOG.md - Release notes - SECURITY.md +(this file) + +=== Legal + +Security research conducted in good faith will not result in legal +action, provided: + +* You respect our disclosure timeline +* You do not exploit vulnerabilities beyond proof-of-concept +* You do not access user data or disrupt service +* You comply with applicable laws + +We support security researchers and the white-hat community. + +''''' + +*Last updated*: 2025-12-18 *Version*: 1.0.2 diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index f75ee6d..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,218 +0,0 @@ - -# Security Policy - -## Supported Versions - -We take security seriously and provide security updates for the following versions: - -| Version | Supported | Notes | -| ------- | ------------------ | ------------------------ | -| 1.0.x | :white_check_mark: | Current stable release | -| < 1.0.0 | :x: | Pre-release, not supported | - -## Security Guarantees - -Bunsenite provides the following security guarantees: - -### Memory Safety - -- **Zero `unsafe` blocks**: Enforced by `#![deny(unsafe_code)]` compiler directive -- **Rust ownership model**: Prevents use-after-free, double-free, and memory leaks -- **No null pointer dereferences**: Rust's type system eliminates this class of bugs -- **Bounds checking**: All array/vector accesses are bounds-checked - -### Type Safety - -- **Compile-time guarantees**: Type errors are caught before runtime -- **No implicit conversions**: Explicit type conversions required -- **Strong typing**: Prevents type confusion vulnerabilities - -### Dependency Security - -- **Minimal dependencies**: Only essential, well-audited crates -- **No network dependencies**: Offline-first design eliminates network attack surface -- **Pinned versions**: Dependencies locked to specific versions for reproducibility -- **Regular audits**: Dependencies audited using `cargo audit` - -### Supply Chain Security - -- **Reproducible builds**: Guix flake provides bit-for-bit reproducibility -- **Signed releases**: All releases are cryptographically signed (planned) -- **Transparent development**: All changes tracked in public Git repository -- **SBOM generation**: Software Bill of Materials available (planned) - -## Reporting a Vulnerability - -**Please do NOT report security vulnerabilities through public GitHub/GitLab issues.** - -### Preferred Method - -Report security vulnerabilities via: - -1. **GitHub Security Advisories**: [Create a new security advisory](https://github.com/hyperpolymath/bunsenite/security/advisories/new) (preferred) -2. **GitLab Confidential Issue**: Use GitLab's confidential issue feature - -### What to Include - -Please include: - -- **Description**: Clear description of the vulnerability -- **Impact**: What an attacker could achieve -- **Reproduction**: Step-by-step instructions to reproduce -- **Affected versions**: Which versions are affected -- **Proposed fix**: If you have one (optional) -- **Disclosure timeline**: Your preferred disclosure timeline - -### Response Timeline - -- **Initial response**: Within 48 hours -- **Triage**: Within 1 week -- **Fix development**: Depends on severity (critical: days, low: weeks) -- **Public disclosure**: Coordinated with reporter, typically 90 days after fix - -### Severity Levels - -We use the following severity classifications: - -#### Critical (CVSS 9.0-10.0) - -- Remote code execution -- Privilege escalation to admin/root -- Authentication bypass - -**Response**: Patch within 48 hours, immediate release - -#### High (CVSS 7.0-8.9) - -- SQL injection (not applicable to Bunsenite) -- Information disclosure of sensitive data -- Denial of service affecting availability - -**Response**: Patch within 1 week, expedited release - -#### Medium (CVSS 4.0-6.9) - -- Cross-site scripting (XSS) (browser/WASM context) -- Information disclosure of non-sensitive data -- Low-impact denial of service - -**Response**: Patch within 2 weeks, next regular release - -#### Low (CVSS 0.1-3.9) - -- Minor information leaks -- Best practice violations -- Theoretical attacks with no known exploit - -**Response**: Patch within 30 days, next regular release - -## Security Best Practices - -### For Users - -1. **Keep updated**: Always use the latest stable version -2. **Verify signatures**: Check release signatures (when available) -3. **Audit dependencies**: Run `cargo audit` regularly -4. **Minimal permissions**: Run with least privilege necessary -5. **Air-gapped environments**: Bunsenite works offline by design - -### For Developers - -1. **No `unsafe` code**: Never use `unsafe` blocks (enforced by compiler) -2. **Input validation**: Validate all external input -3. **Error handling**: Use `Result` types, avoid `unwrap()` in library code -4. **Dependency review**: Review new dependencies carefully -5. **Security testing**: Include security tests in test suite - -## Known Limitations - -### By Design - -1. **Nickel evaluation**: Bunsenite evaluates Nickel code, which could contain: - - Infinite loops (resource exhaustion) - - Large memory allocations - - Consider: Run evaluation in sandboxed environment for untrusted input - -2. **File I/O**: File reading follows OS permissions - - Does NOT escalate privileges - - Respects filesystem boundaries - -3. **WASM sandbox**: Browser WASM runs in sandbox, but: - - Subject to browser security model - - Can consume memory/CPU (denial of service) - -### Mitigations - -We provide: - -- **Timeouts**: (Planned) Configurable evaluation timeouts -- **Memory limits**: (Planned) Configurable memory limits for evaluation -- **Resource monitoring**: (Planned) Track resource usage - -## Security Audits - -| Date | Auditor | Scope | Findings | Status | -| ---------- | ------- | ------------- | -------- | ---------- | -| 2025-Q2 | Planned | Full codebase | N/A | Scheduled | - -## Cryptography - -Bunsenite does NOT implement cryptography. For cryptographic needs: - -- Use established libraries (e.g., `ring`, `sodiumoxide`) -- Never roll your own crypto -- Follow NIST/IETF recommendations - -## Compliance - -- **OWASP Top 10**: N/A (not a web application) -- **CWE Top 25**: Memory safety issues prevented by Rust -- **GDPR**: No personal data collection -- **CCPA**: No personal data collection - -## Security Tooling - -We use: - -- **`cargo audit`**: Check for known vulnerabilities in dependencies -- **`cargo clippy`**: Lint for security anti-patterns -- **`cargo deny`**: Check licenses and security advisories -- **GitLab Security Scanner**: Automated SAST in CI/CD -- **Dependabot**: (Planned) Automated dependency updates - -## Contact - -- **GitHub Security Advisories**: [Report a vulnerability](https://github.com/hyperpolymath/bunsenite/security/advisories/new) -- **Security.txt**: See `.well-known/security.txt` (RFC 9116 compliant) - -## Attribution - -We believe in responsible disclosure and will credit security researchers who: - -- Report vulnerabilities responsibly -- Allow coordinated disclosure -- Follow our security policy - -Credits will be listed in: -- CHANGELOG.md -- Release notes -- SECURITY.md (this file) - -## Legal - -Security research conducted in good faith will not result in legal action, provided: - -- You respect our disclosure timeline -- You do not exploit vulnerabilities beyond proof-of-concept -- You do not access user data or disrupt service -- You comply with applicable laws - -We support security researchers and the white-hat community. - ---- - -**Last updated**: 2025-12-18 -**Version**: 1.0.2 diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..036072c --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,58 @@ +== Test & Benchmark Requirements + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current State + +* Unit tests: NONE verified (Cargo.toml exists but cargo not available +in this repo due to .tool-versions mismatch) +* Integration tests: 1 Zig integration test (template) +* E2E tests: NONE +* Benchmarks: 1 file exists (unverified) +* panic-attack scan: NEVER RUN + +=== What’s Missing + +==== Point-to-Point (P2P) + +* 11 Rust source files — test count unknown (cannot build) +* 5 Zig source files — only template integration test +* 3 Idris2 ABI files — no verification tests +* 4 AffineScript files — no tests +* 3 TypeScript files — no tests + +==== End-to-End (E2E) + +* Core functionality workflow not tested +* Integration between Rust, Zig, and AffineScript layers not tested + +==== Aspect Tests + +* [ ] Security (depends on what bunsenite does) +* [ ] Performance (benchmark file exists but unverified) +* [ ] Concurrency (if applicable) +* [ ] Error handling (graceful degradation) +* [ ] Accessibility (if UI exists) + +==== Build & Execution + +* [ ] cargo build — BLOCKED (.tool-versions mismatch) +* [ ] cargo test — BLOCKED +* [ ] zig build — not verified +* [ ] Self-diagnostic — none + +==== Benchmarks Needed + +* Verify existing benchmark file runs +* Specific benchmarks depend on functionality + +==== Self-Tests + +* [ ] panic-attack assail on own repo +* [ ] Fix .tool-versions to allow cargo to run + +=== Priority + +* *MEDIUM* — 11 Rust + 5 Zig + 4 AffineScript + 3 TS files. Cannot even +build due to tooling mismatch, which itself is a problem. Fix +.tool-versions first, then assess test needs. diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 297a4d8..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,49 +0,0 @@ - -# Test & Benchmark Requirements -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current State -- Unit tests: NONE verified (Cargo.toml exists but cargo not available in this repo due to .tool-versions mismatch) -- Integration tests: 1 Zig integration test (template) -- E2E tests: NONE -- Benchmarks: 1 file exists (unverified) -- panic-attack scan: NEVER RUN - -## What's Missing -### Point-to-Point (P2P) -- 11 Rust source files — test count unknown (cannot build) -- 5 Zig source files — only template integration test -- 3 Idris2 ABI files — no verification tests -- 4 AffineScript files — no tests -- 3 TypeScript files — no tests - -### End-to-End (E2E) -- Core functionality workflow not tested -- Integration between Rust, Zig, and AffineScript layers not tested - -### Aspect Tests -- [ ] Security (depends on what bunsenite does) -- [ ] Performance (benchmark file exists but unverified) -- [ ] Concurrency (if applicable) -- [ ] Error handling (graceful degradation) -- [ ] Accessibility (if UI exists) - -### Build & Execution -- [ ] cargo build — BLOCKED (.tool-versions mismatch) -- [ ] cargo test — BLOCKED -- [ ] zig build — not verified -- [ ] Self-diagnostic — none - -### Benchmarks Needed -- Verify existing benchmark file runs -- Specific benchmarks depend on functionality - -### Self-Tests -- [ ] panic-attack assail on own repo -- [ ] Fix .tool-versions to allow cargo to run - -## Priority -- **MEDIUM** — 11 Rust + 5 Zig + 4 AffineScript + 3 TS files. Cannot even build due to tooling mismatch, which itself is a problem. Fix .tool-versions first, then assess test needs. diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 87% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index b4a3431..eeb8c78 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,15 +1,8 @@ - - - +== Bunsenite — Project Topology -# Bunsenite — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ CONSUMERS │ │ (Deno, AffineScript, Browser, CLI) │ @@ -44,11 +37,11 @@ Copyright (c) Jonathan D.A. Jewell │ Justfile / Guix .machine_readable/ │ │ RSR Compliance .well-known/ │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE & CLI @@ -69,25 +62,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████████ 100% v0.1.0 Production Ready -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Nickel Core ──────► Bunsenite Rust ──────► Zig FFI ──────► Deno/TS │ ▼ wasm-bindgen ───► Browser -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). diff --git a/bindings/deno/README.adoc b/bindings/deno/README.adoc new file mode 100644 index 0000000..02d91a1 --- /dev/null +++ b/bindings/deno/README.adoc @@ -0,0 +1,247 @@ +== Bunsenite Deno Bindings + +image:https://img.shields.io/badge/License-MPL–2.0-blue.svg[License: +MPL-2.0,link="`https://github.com/hyperpolymath/palimpsest-license`"] + +TypeScript bindings for +https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite[Bunsenite] +using Deno’s native FFI. + +=== Installation + +[arabic] +. Build the Bunsenite native library: + +[source,bash] +---- +cd ../.. +cargo build --release +---- + +[arabic, start=2] +. Import the bindings in your Deno code: + +[source,typescript] +---- +import { parseNickel } from "https://raw.githubusercontent.com/example/bunsenite/main/bindings/deno/bunsenite.ts"; +---- + +Or use local path: + +[source,typescript] +---- +import { parseNickel } from "./bunsenite.ts"; +---- + +=== Usage + +==== Basic Parsing + +[source,typescript] +---- +import { parseNickel } from "./bunsenite.ts"; + +const config = parseNickel( + `{ + name = "my-app", + version = "1.0.0", + port = 8080, + }`, + "config.ncl" +); + +console.log(config.port); // 8080 +---- + +==== Parse File + +[source,typescript] +---- +import { parseFile } from "./bunsenite.ts"; + +const config = await parseFile("./config.ncl"); +console.log(config); +---- + +==== Validation + +[source,typescript] +---- +import { validateNickel } from "./bunsenite.ts"; + +try { + validateNickel('{ foo = 42 }', "config.ncl"); + console.log("Valid!"); +} catch (e) { + console.error("Invalid:", e.message); +} +---- + +==== Library Info + +[source,typescript] +---- +import { getVersion, getRSRTier, getTPCFPerimeter } from "./bunsenite.ts"; + +console.log("Version:", getVersion()); +console.log("RSR Tier:", getRSRTier()); +console.log("TPCF Perimeter:", getTPCFPerimeter()); +---- + +=== API Reference + +==== `+parseNickel(source: string, name: string): unknown+` + +Parse and evaluate a Nickel configuration string. + +* `+source+`: The Nickel configuration source code +* `+name+`: A name for this configuration (used in error messages) +* Returns: Parsed configuration as a JavaScript object +* Throws: Error if parsing or evaluation fails + +==== `+validateNickel(source: string, name: string): boolean+` + +Validate a Nickel configuration without evaluating it. + +* `+source+`: The Nickel configuration source code +* `+name+`: A name for this configuration (used in error messages) +* Returns: `+true+` if valid +* Throws: Error if validation fails + +==== `+parseFile(path: string): Promise+` + +Parse a Nickel configuration file. + +* `+path+`: Path to the Nickel configuration file +* Returns: Parsed configuration as a JavaScript object +* Throws: Error if file cannot be read or parsing fails + +==== `+validateFile(path: string): Promise+` + +Validate a Nickel configuration file. + +* `+path+`: Path to the Nickel configuration file +* Returns: `+true+` if valid +* Throws: Error if file cannot be read or validation fails + +==== `+getVersion(): string+` + +Get Bunsenite library version. + +* Returns: Version string (e.g., "`0.1.0`") + +==== `+getRSRTier(): string+` + +Get RSR compliance tier. + +* Returns: RSR tier (e.g., "`bronze`") + +==== `+getTPCFPerimeter(): number+` + +Get TPCF perimeter number. + +* Returns: Perimeter number (3 for Community Sandbox) + +=== Permissions + +Deno requires the following permissions: + +* `+--allow-ffi+`: To load the native library +* `+--allow-read+`: To read configuration files (if using `+parseFile+`) + +Example: + +[source,bash] +---- +deno run --allow-ffi --allow-read example.ts +---- + +=== Examples + +See link:./example.ts[example.ts] for comprehensive examples. + +Run the example: + +[source,bash] +---- +# Make sure bunsenite is built first +cd ../.. +cargo build --release + +# Run example +cd bindings/deno +deno run --allow-ffi --allow-read example.ts +---- + +=== Platform Support + +[cols=",,",options="header",] +|=== +|Platform |Library Name |Status +|Linux |`+libbunsenite.so+` |✅ +|macOS |`+libbunsenite.dylib+` |✅ +|Windows |`+bunsenite.dll+` |✅ +|=== + +The bindings automatically detect your platform and load the correct +library. + +=== Architecture + +.... +┌─────────────────┐ +│ Deno Runtime │ +│ (TypeScript) │ +└────────┬────────┘ + │ FFI + ▼ + ┌──────────┐ + │ Zig FFI │ + │ (C ABI) │ + └─────┬────┘ + │ + ▼ +┌─────────────────┐ +│ Rust Core │ +│ (lib.rs) │ +│ │ +│ nickel-lang-core│ +│ 0.9.1 │ +└─────────────────┘ +.... + +=== Performance + +~90% of native Rust performance (minimal C ABI overhead). + +=== Security + +* *Memory Safety*: Rust ownership model prevents memory errors +* *Type Safety*: Full type checking via Nickel + Rust +* *No `+unsafe+`*: Zero unsafe code blocks in Bunsenite core +* *Offline-First*: No network dependencies + +=== License + +Dual MPL-2.0 + MPL-2.0 v0.8 + +See link:../../LICENSE[LICENSE] for details. + +=== Contributing + +See link:../../CONTRIBUTING.md[CONTRIBUTING.md] for development +guidelines. + +=== Support + +* *Issues*: +https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite/-/issues[GitLab +Issues] +* *Discussions*: +https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite/-/issues[GitLab +Discussions] +* *Documentation*: link:../../README.md[Main README] + +''''' + +Made with ❤️ by the Campaign for Cooler Coding and Programming diff --git a/bindings/deno/README.md b/bindings/deno/README.md deleted file mode 100644 index d00b0bc..0000000 --- a/bindings/deno/README.md +++ /dev/null @@ -1,230 +0,0 @@ - -# Bunsenite Deno Bindings -image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: MPL-2.0,link="https://github.com/hyperpolymath/palimpsest-license"] - - - -TypeScript bindings for [Bunsenite](https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite) using Deno's native FFI. - -## Installation - -1. Build the Bunsenite native library: - -```bash -cd ../.. -cargo build --release -``` - -2. Import the bindings in your Deno code: - -```typescript -import { parseNickel } from "https://raw.githubusercontent.com/example/bunsenite/main/bindings/deno/bunsenite.ts"; -``` - -Or use local path: - -```typescript -import { parseNickel } from "./bunsenite.ts"; -``` - -## Usage - -### Basic Parsing - -```typescript -import { parseNickel } from "./bunsenite.ts"; - -const config = parseNickel( - `{ - name = "my-app", - version = "1.0.0", - port = 8080, - }`, - "config.ncl" -); - -console.log(config.port); // 8080 -``` - -### Parse File - -```typescript -import { parseFile } from "./bunsenite.ts"; - -const config = await parseFile("./config.ncl"); -console.log(config); -``` - -### Validation - -```typescript -import { validateNickel } from "./bunsenite.ts"; - -try { - validateNickel('{ foo = 42 }', "config.ncl"); - console.log("Valid!"); -} catch (e) { - console.error("Invalid:", e.message); -} -``` - -### Library Info - -```typescript -import { getVersion, getRSRTier, getTPCFPerimeter } from "./bunsenite.ts"; - -console.log("Version:", getVersion()); -console.log("RSR Tier:", getRSRTier()); -console.log("TPCF Perimeter:", getTPCFPerimeter()); -``` - -## API Reference - -### `parseNickel(source: string, name: string): unknown` - -Parse and evaluate a Nickel configuration string. - -- `source`: The Nickel configuration source code -- `name`: A name for this configuration (used in error messages) -- Returns: Parsed configuration as a JavaScript object -- Throws: Error if parsing or evaluation fails - -### `validateNickel(source: string, name: string): boolean` - -Validate a Nickel configuration without evaluating it. - -- `source`: The Nickel configuration source code -- `name`: A name for this configuration (used in error messages) -- Returns: `true` if valid -- Throws: Error if validation fails - -### `parseFile(path: string): Promise` - -Parse a Nickel configuration file. - -- `path`: Path to the Nickel configuration file -- Returns: Parsed configuration as a JavaScript object -- Throws: Error if file cannot be read or parsing fails - -### `validateFile(path: string): Promise` - -Validate a Nickel configuration file. - -- `path`: Path to the Nickel configuration file -- Returns: `true` if valid -- Throws: Error if file cannot be read or validation fails - -### `getVersion(): string` - -Get Bunsenite library version. - -- Returns: Version string (e.g., "0.1.0") - -### `getRSRTier(): string` - -Get RSR compliance tier. - -- Returns: RSR tier (e.g., "bronze") - -### `getTPCFPerimeter(): number` - -Get TPCF perimeter number. - -- Returns: Perimeter number (3 for Community Sandbox) - -## Permissions - -Deno requires the following permissions: - -- `--allow-ffi`: To load the native library -- `--allow-read`: To read configuration files (if using `parseFile`) - -Example: - -```bash -deno run --allow-ffi --allow-read example.ts -``` - -## Examples - -See [example.ts](./example.ts) for comprehensive examples. - -Run the example: - -```bash -# Make sure bunsenite is built first -cd ../.. -cargo build --release - -# Run example -cd bindings/deno -deno run --allow-ffi --allow-read example.ts -``` - -## Platform Support - -| Platform | Library Name | Status | -| -------- | ------------------- | ------ | -| Linux | `libbunsenite.so` | ✅ | -| macOS | `libbunsenite.dylib`| ✅ | -| Windows | `bunsenite.dll` | ✅ | - -The bindings automatically detect your platform and load the correct library. - -## Architecture - -``` -┌─────────────────┐ -│ Deno Runtime │ -│ (TypeScript) │ -└────────┬────────┘ - │ FFI - ▼ - ┌──────────┐ - │ Zig FFI │ - │ (C ABI) │ - └─────┬────┘ - │ - ▼ -┌─────────────────┐ -│ Rust Core │ -│ (lib.rs) │ -│ │ -│ nickel-lang-core│ -│ 0.9.1 │ -└─────────────────┘ -``` - -## Performance - -~90% of native Rust performance (minimal C ABI overhead). - -## Security - -- **Memory Safety**: Rust ownership model prevents memory errors -- **Type Safety**: Full type checking via Nickel + Rust -- **No `unsafe`**: Zero unsafe code blocks in Bunsenite core -- **Offline-First**: No network dependencies - -## License - -Dual MPL-2.0 + MPL-2.0 v0.8 - -See [LICENSE](../../LICENSE) for details. - -## Contributing - -See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines. - -## Support - -- **Issues**: [GitLab Issues](https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite/-/issues) -- **Discussions**: [GitLab Discussions](https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite/-/issues) -- **Documentation**: [Main README](../../README.md) - ---- - -Made with ❤️ by the Campaign for Cooler Coding and Programming diff --git a/bindings/rescript/README.adoc b/bindings/rescript/README.adoc new file mode 100644 index 0000000..248c571 --- /dev/null +++ b/bindings/rescript/README.adoc @@ -0,0 +1,267 @@ +== Bunsenite Rescript Bindings + +image:https://img.shields.io/badge/License-PMPL–1.0-blue.svg[License: +MPL-2.0,link="`https://github.com/hyperpolymath/palimpsest-license`"] + +Type-safe Rescript bindings for +https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite[Bunsenite] +via C FFI. + +=== Installation + +[arabic] +. Build the Bunsenite native library: + +[source,bash] +---- +cd ../.. +cargo build --release +---- + +[arabic, start=2] +. Add Bunsenite bindings to your Rescript project: + +[source,bash] +---- +# Copy bindings to your project +cp bindings/affinescript/Bunsenite.res src/ +---- + +[arabic, start=3] +. Configure FFI in your `+bsconfig.json+`: + +[source,json] +---- +{ + "name": "your-project", + "sources": [ + { + "dir": "src", + "subdirs": true + } + ], + "bs-dependencies": [], + "external-stdlibs": ["bunsenite"] +} +---- + +=== Usage + +==== Basic Parsing + +[source,affinescript] +---- +open Bunsenite + +let config = parseNickel( + "{ + name = \"my-app\", + version = \"1.0.0\", + port = 8080, + }", + "config.ncl" +) + +switch config { +| Ok(json) => Js.log(json) +| Error(err) => Js.log2("Error:", errorToString(err)) +} +---- + +==== Parse File + +[source,affinescript] +---- +open Bunsenite + +let config = parseFile("./config.ncl") + +switch config { +| Ok(json) => { + // Access nested values + let port = getConfigValue(json, list{"server", "port"}) + Js.log2("Server port:", port) + } +| Error(err) => Js.log2("Error:", errorToString(err)) +} +---- + +==== Validation + +[source,affinescript] +---- +open Bunsenite + +let result = validateNickel("{foo = 42}", "config.ncl") + +switch result { +| Ok() => Js.log("Valid!") +| Error(err) => Js.log2("Invalid:", errorToString(err)) +} +---- + +==== Library Info + +[source,affinescript] +---- +open Bunsenite + +Js.log2("Version:", getVersion()) +Js.log2("RSR Tier:", getRSRTier()) +Js.log2("TPCF Perimeter:", getTPCFPerimeter()) +---- + +=== API Reference + +==== Types + +[source,affinescript] +---- +type result<'a, 'e> = Ok('a) | Error('e) + +type error = + | ParseError(string) + | ValidationError(string) + | InvalidInput(string) + +type parseResult = result +type validateResult = result +---- + +==== Functions + +===== `+parseNickel(source: string, name: string): parseResult+` + +Parse and evaluate a Nickel configuration string. + +* `+source+`: The Nickel configuration source code +* `+name+`: A name for this configuration (used in error messages) +* Returns: `+Ok(Js.Json.t)+` on success, `+Error(error)+` on failure + +===== `+validateNickel(source: string, name: string): validateResult+` + +Validate a Nickel configuration without evaluating it. + +* `+source+`: The Nickel configuration source code +* `+name+`: A name for this configuration (used in error messages) +* Returns: `+Ok()+` if valid, `+Error(error)+` if invalid + +===== `+parseFile(path: string): parseResult+` + +Parse a Nickel configuration file. + +* `+path+`: Path to the Nickel configuration file +* Returns: `+Ok(Js.Json.t)+` on success, `+Error(error)+` on failure + +===== `+validateFile(path: string): validateResult+` + +Validate a Nickel configuration file. + +* `+path+`: Path to the Nickel configuration file +* Returns: `+Ok()+` if valid, `+Error(error)+` if invalid + +===== `+getVersion(): string+` + +Get Bunsenite library version. + +* Returns: Version string (e.g., "`0.1.0`") + +===== `+getRSRTier(): string+` + +Get RSR compliance tier. + +* Returns: RSR tier (e.g., "`bronze`") + +===== `+getTPCFPerimeter(): int+` + +Get TPCF perimeter number. + +* Returns: Perimeter number (3 for Community Sandbox) + +==== Helper Functions + +===== `+getConfigValue(json: Js.Json.t, path: list): option+` + +Get a value from a configuration object by key path. + +Example: + +[source,affinescript] +---- +let port = getConfigValue(config, list{"server", "port"}) +---- + +===== `+errorToString(err: error): string+` + +Convert an error to a string for display. + +=== Architecture + +.... +┌─────────────────┐ +│ Rescript │ +│ (Type-safe) │ +└────────┬────────┘ + │ FFI + ▼ + ┌──────────┐ + │ Zig FFI │ + │ (C ABI) │ + └─────┬────┘ + │ + ▼ +┌─────────────────┐ +│ Rust Core │ +│ (lib.rs) │ +│ │ +│ nickel-lang-core│ +│ 0.9.1 │ +└─────────────────┘ +.... + +=== Performance + +~90% of native Rust performance (minimal C ABI overhead). + +=== Type Safety + +Rescript provides: - *Compile-time type checking*: Catch errors before +runtime - *Sound type system*: No `+null+` or `+undefined+` surprises - +*Pattern matching*: Exhaustive error handling via `+result+` type - +*Immutability*: Default immutability prevents bugs + +Combined with Bunsenite’s Rust core: - *Memory safety*: Rust ownership +model - *Type safety*: Nickel + Rust type checking - *No runtime +errors*: Caught at compile time + +=== Security + +* *Memory Safety*: Rust ownership model prevents memory errors +* *Type Safety*: Rescript + Nickel + Rust triple type checking +* *No `+unsafe+`*: Zero unsafe code blocks in Bunsenite core +* *Offline-First*: No network dependencies + +=== License + +Dual MPL-2.0 + MPL-2.0 v0.8 + +See link:../../LICENSE[LICENSE] for details. + +=== Contributing + +See link:../../CONTRIBUTING.md[CONTRIBUTING.md] for development +guidelines. + +=== Support + +* *Issues*: +https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite/-/issues[GitLab +Issues] +* *Discussions*: +https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite/-/issues[GitLab +Discussions] +* *Documentation*: link:../../README.md[Main README] + +''''' + +Made with ❤️ by the Campaign for Cooler Coding and Programming diff --git a/bindings/rescript/README.md b/bindings/rescript/README.md deleted file mode 100644 index ffd63a9..0000000 --- a/bindings/rescript/README.md +++ /dev/null @@ -1,253 +0,0 @@ - -# Bunsenite Rescript Bindings -image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: MPL-2.0,link="https://github.com/hyperpolymath/palimpsest-license"] - - - -Type-safe Rescript bindings for [Bunsenite](https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite) via C FFI. - -## Installation - -1. Build the Bunsenite native library: - -```bash -cd ../.. -cargo build --release -``` - -2. Add Bunsenite bindings to your Rescript project: - -```bash -# Copy bindings to your project -cp bindings/affinescript/Bunsenite.res src/ -``` - -3. Configure FFI in your `bsconfig.json`: - -```json -{ - "name": "your-project", - "sources": [ - { - "dir": "src", - "subdirs": true - } - ], - "bs-dependencies": [], - "external-stdlibs": ["bunsenite"] -} -``` - -## Usage - -### Basic Parsing - -```affinescript -open Bunsenite - -let config = parseNickel( - "{ - name = \"my-app\", - version = \"1.0.0\", - port = 8080, - }", - "config.ncl" -) - -switch config { -| Ok(json) => Js.log(json) -| Error(err) => Js.log2("Error:", errorToString(err)) -} -``` - -### Parse File - -```affinescript -open Bunsenite - -let config = parseFile("./config.ncl") - -switch config { -| Ok(json) => { - // Access nested values - let port = getConfigValue(json, list{"server", "port"}) - Js.log2("Server port:", port) - } -| Error(err) => Js.log2("Error:", errorToString(err)) -} -``` - -### Validation - -```affinescript -open Bunsenite - -let result = validateNickel("{foo = 42}", "config.ncl") - -switch result { -| Ok() => Js.log("Valid!") -| Error(err) => Js.log2("Invalid:", errorToString(err)) -} -``` - -### Library Info - -```affinescript -open Bunsenite - -Js.log2("Version:", getVersion()) -Js.log2("RSR Tier:", getRSRTier()) -Js.log2("TPCF Perimeter:", getTPCFPerimeter()) -``` - -## API Reference - -### Types - -```affinescript -type result<'a, 'e> = Ok('a) | Error('e) - -type error = - | ParseError(string) - | ValidationError(string) - | InvalidInput(string) - -type parseResult = result -type validateResult = result -``` - -### Functions - -#### `parseNickel(source: string, name: string): parseResult` - -Parse and evaluate a Nickel configuration string. - -- `source`: The Nickel configuration source code -- `name`: A name for this configuration (used in error messages) -- Returns: `Ok(Js.Json.t)` on success, `Error(error)` on failure - -#### `validateNickel(source: string, name: string): validateResult` - -Validate a Nickel configuration without evaluating it. - -- `source`: The Nickel configuration source code -- `name`: A name for this configuration (used in error messages) -- Returns: `Ok()` if valid, `Error(error)` if invalid - -#### `parseFile(path: string): parseResult` - -Parse a Nickel configuration file. - -- `path`: Path to the Nickel configuration file -- Returns: `Ok(Js.Json.t)` on success, `Error(error)` on failure - -#### `validateFile(path: string): validateResult` - -Validate a Nickel configuration file. - -- `path`: Path to the Nickel configuration file -- Returns: `Ok()` if valid, `Error(error)` if invalid - -#### `getVersion(): string` - -Get Bunsenite library version. - -- Returns: Version string (e.g., "0.1.0") - -#### `getRSRTier(): string` - -Get RSR compliance tier. - -- Returns: RSR tier (e.g., "bronze") - -#### `getTPCFPerimeter(): int` - -Get TPCF perimeter number. - -- Returns: Perimeter number (3 for Community Sandbox) - -### Helper Functions - -#### `getConfigValue(json: Js.Json.t, path: list): option` - -Get a value from a configuration object by key path. - -Example: -```affinescript -let port = getConfigValue(config, list{"server", "port"}) -``` - -#### `errorToString(err: error): string` - -Convert an error to a string for display. - -## Architecture - -``` -┌─────────────────┐ -│ Rescript │ -│ (Type-safe) │ -└────────┬────────┘ - │ FFI - ▼ - ┌──────────┐ - │ Zig FFI │ - │ (C ABI) │ - └─────┬────┘ - │ - ▼ -┌─────────────────┐ -│ Rust Core │ -│ (lib.rs) │ -│ │ -│ nickel-lang-core│ -│ 0.9.1 │ -└─────────────────┘ -``` - -## Performance - -~90% of native Rust performance (minimal C ABI overhead). - -## Type Safety - -Rescript provides: -- **Compile-time type checking**: Catch errors before runtime -- **Sound type system**: No `null` or `undefined` surprises -- **Pattern matching**: Exhaustive error handling via `result` type -- **Immutability**: Default immutability prevents bugs - -Combined with Bunsenite's Rust core: -- **Memory safety**: Rust ownership model -- **Type safety**: Nickel + Rust type checking -- **No runtime errors**: Caught at compile time - -## Security - -- **Memory Safety**: Rust ownership model prevents memory errors -- **Type Safety**: Rescript + Nickel + Rust triple type checking -- **No `unsafe`**: Zero unsafe code blocks in Bunsenite core -- **Offline-First**: No network dependencies - -## License - -Dual MPL-2.0 + MPL-2.0 v0.8 - -See [LICENSE](../../LICENSE) for details. - -## Contributing - -See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines. - -## Support - -- **Issues**: [GitLab Issues](https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite/-/issues) -- **Discussions**: [GitLab Discussions](https://gitlab.com/campaign-for-cooler-coding-and-programming/bunsenite/-/issues) -- **Documentation**: [Main README](../../README.md) - ---- - -Made with ❤️ by the Campaign for Cooler Coding and Programming diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..61b0fac --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,67 @@ +== Tech-Debt Audit — bunsenite — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+MEDIUM+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+MPL-2.0+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |331 +|`+docs/+` files |2 +|`+docs/+` LoC |154 +|CHANGELOG.md |Y +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +331 lines has likely grown to do the work of `+docs/+` — split it into a +thin README + `+docs/architecture.md+`, `+docs/usage.md+`, etc. +Heavy-wiki exemplars to copy from: `+affinescript+`, `+boj-server+`, +`+echidna+`, `+hypatia+`. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index cd41799..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,54 +0,0 @@ - -# Tech-Debt Audit — bunsenite — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `MEDIUM`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `MPL-2.0` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 331 | -| `docs/` files | 2 | -| `docs/` LoC | 154 | -| CHANGELOG.md | Y | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 331 lines has likely grown to do the work of `docs/` — split it into a thin README + `docs/architecture.md`, `docs/usage.md`, etc. Heavy-wiki exemplars to copy from: `affinescript`, `boj-server`, `echidna`, `hypatia`. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/docs/wiki-home.md b/docs/wiki-home.adoc similarity index 56% rename from docs/wiki-home.md rename to docs/wiki-home.adoc index 1f73317..ef7e966 100644 --- a/docs/wiki-home.md +++ b/docs/wiki-home.adoc @@ -1,18 +1,17 @@ - -# Bunsenite +== Bunsenite -**Nickel configuration file parser with multi-language FFI bindings** +*Nickel configuration file parser with multi-language FFI bindings* -[![RSR Bronze](https://img.shields.io/badge/RSR-Bronze-cd7f32)](https://github.com/hyperpolymath/rsr) -[![TPCF Perimeter 3](https://img.shields.io/badge/TPCF-Perimeter%203-blue)]() -[![License](https://img.shields.io/badge/license-PMPL--1.0%20%7C%20Palimpsest-green)]() +https://github.com/hyperpolymath/rsr[image:https://img.shields.io/badge/RSR-Bronze-cd7f32[RSR +Bronze]] +link:[image:https://img.shields.io/badge/TPCF-Perimeter%203-blue[TPCF +Perimeter 3]] +link:[image:https://img.shields.io/badge/license-PMPL--1.0%20%7C%20Palimpsest-green[License]] -## Quick Start +=== Quick Start -```bash +[source,bash] +---- # Install from crates.io cargo install bunsenite @@ -27,22 +26,24 @@ bunsenite repl # Watch mode bunsenite watch config.ncl -``` +---- -## Features +=== Features -| Feature | Description | -|---------|-------------| -| **Parse** | Parse Nickel configs to JSON | -| **Validate** | Validate without full evaluation | -| **Watch** | Auto-reload on file changes | -| **REPL** | Interactive Nickel evaluation | -| **Schema** | JSON Schema validation | -| **FFI** | Stable C ABI via Zig | +[cols=",",options="header",] +|=== +|Feature |Description +|*Parse* |Parse Nickel configs to JSON +|*Validate* |Validate without full evaluation +|*Watch* |Auto-reload on file changes +|*REPL* |Interactive Nickel evaluation +|*Schema* |JSON Schema validation +|*FFI* |Stable C ABI via Zig +|=== -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────┐ │ Consumers │ ├─────────────┬─────────────┬─────────────┤ @@ -65,58 +66,62 @@ bunsenite watch config.ncl │ miette error diagnostics │ │ serde serialization │ └─────────────────────────────────────────┘ -``` +.... -## Bindings +=== Bindings -### Deno (JavaScript/TypeScript) +==== Deno (JavaScript/TypeScript) -```typescript +[source,typescript] +---- import { parseNickel, validateNickel } from "./bunsenite.ts"; const config = parseNickel('{ port = 8080 }', "config.ncl"); console.log(config.port); // 8080 -``` +---- -### AffineScript +==== AffineScript -```affinescript +[source,affinescript] +---- let config = Bunsenite.parse("{ port = 8080 }", "config.ncl") Js.log(config) -``` +---- -### WebAssembly +==== WebAssembly -```javascript +[source,javascript] +---- import init, { parse } from './bunsenite.js'; await init(); const config = parse('{ port = 8080 }', 'config.ncl'); -``` +---- -## RSR Compliance +=== RSR Compliance -Bunsenite follows the **Rhodium Standard Repository** (RSR) Bronze tier: +Bunsenite follows the *Rhodium Standard Repository* (RSR) Bronze tier: -- ✅ **Type Safety**: Compile-time (Rust) -- ✅ **Memory Safety**: Rust ownership model -- ✅ **Offline-First**: No network dependencies -- ✅ **No TypeScript**: Deno FFI uses `.ts` but calls `Deno.dlopen` -- ✅ **No npm/bun**: AffineScript `package.json` is for npm publishing only -- ✅ **No Python**: Clean -- ✅ **Justfile**: All builds via Justfile +* ✅ *Type Safety*: Compile-time (Rust) +* ✅ *Memory Safety*: Rust ownership model +* ✅ *Offline-First*: No network dependencies +* ✅ *No TypeScript*: Deno FFI uses `+.ts+` but calls `+Deno.dlopen+` +* ✅ *No npm/bun*: AffineScript `+package.json+` is for npm publishing +only +* ✅ *No Python*: Clean +* ✅ *Justfile*: All builds via Justfile -## Pages +=== Pages -- [[Installation]] -- [[CLI Reference]] -- [[API Reference]] -- [[FFI Guide]] -- [[Examples]] -- [[Contributing]] +* [[Installation]] +* [[CLI Reference]] +* [[API Reference]] +* [[FFI Guide]] +* [[Examples]] +* [[Contributing]] -## Links +=== Links -- [GitHub Repository](https://github.com/hyperpolymath/bunsenite) -- [crates.io](https://crates.io/crates/bunsenite) -- [Documentation](https://docs.rs/bunsenite) +* https://github.com/hyperpolymath/bunsenite[GitHub Repository] +* https://crates.io/crates/bunsenite[crates.io] +* https://docs.rs/bunsenite[Documentation] diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..b46c552 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — bunsenite (Developer) + +=== What is bunsenite? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index 2b31321..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — bunsenite (Developer) - -## What is bunsenite? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..b152ccc --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — bunsenite (User) + +=== What is bunsenite? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index 3ef92b7..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — bunsenite (User) - -## What is bunsenite? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/zig/README.adoc b/zig/README.adoc new file mode 100644 index 0000000..63b7f35 --- /dev/null +++ b/zig/README.adoc @@ -0,0 +1,90 @@ +== Bunsenite Zig FFI Layer + +image:https://img.shields.io/badge/License-MPL–2.0-blue.svg[License: +MPL-2.0,link="`https://github.com/hyperpolymath/palimpsest-license`"] + +This directory contains the Zig wrapper that provides a stable C ABI for +the Rust core library. + +=== Purpose + +The Zig layer isolates consumers (Deno, AffineScript) from Rust ABI +changes across compiler versions, providing: + +* *Stable C ABI*: Guaranteed binary compatibility +* *Cross-platform*: Builds for Linux, macOS, Windows +* *Small overhead*: Thin wrapper, minimal performance impact + +=== Architecture + +.... +Deno/AffineScript → Zig (stable C ABI) → Rust (native) +.... + +=== Prerequisites + +[arabic] +. *Rust toolchain*: `+rustup install stable+` +. *Zig compiler*: `+zig version+` (0.11.0 or later recommended) + +=== Building + +[source,bash] +---- +# Build Rust library first +cargo build --release + +# Build Zig FFI layer +cd zig +zig build -Doptimize=ReleaseFast +---- + +Output libraries: - Linux: `+zig-out/lib/libbunsenite.so+` - macOS: +`+zig-out/lib/libbunsenite.dylib+` - Windows: +`+zig-out/lib/bunsenite.dll+` + +=== Exported Symbols + +[width="100%",cols="21%,28%,21%,30%",options="header",] +|=== +|Symbol |Parameters |Returns |Description +|`+parse_nickel+` |`+(source, name)+` |`+char*+` |Parse Nickel to JSON + +|`+validate_nickel+` |`+(source, name)+` |`+int+` |Validate config +(0=ok) + +|`+free_string+` |`+(ptr)+` |`+void+` |Free allocated string + +|`+version+` |`+()+` |`+char*+` |Library version + +|`+rsr_tier+` |`+()+` |`+char*+` |RSR compliance tier + +|`+tpcf_perimeter+` |`+()+` |`+u8+` |TPCF perimeter number +|=== + +=== Testing + +[source,bash] +---- +# Run Zig tests (requires Rust library) +cargo build --release +cd zig && zig build test +---- + +=== Integration + +==== Deno + +The Zig library is used by `+bindings/deno/bunsenite.ts+` via +`+Deno.dlopen()+`. + +==== AffineScript + +The Zig library is used by `+bindings/affinescript/Bunsenite.res+` via C +FFI. + +=== RSR Compliance + +This FFI layer maintains RSR Bronze tier compliance: - Type safety +through Zig’s type system - Memory safety with explicit +allocation/deallocation - No network dependencies diff --git a/zig/README.md b/zig/README.md deleted file mode 100644 index ce9f9f5..0000000 --- a/zig/README.md +++ /dev/null @@ -1,81 +0,0 @@ - -# Bunsenite Zig FFI Layer -image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: MPL-2.0,link="https://github.com/hyperpolymath/palimpsest-license"] - - - -This directory contains the Zig wrapper that provides a stable C ABI for the Rust core library. - -## Purpose - -The Zig layer isolates consumers (Deno, AffineScript) from Rust ABI changes across compiler versions, providing: - -- **Stable C ABI**: Guaranteed binary compatibility -- **Cross-platform**: Builds for Linux, macOS, Windows -- **Small overhead**: Thin wrapper, minimal performance impact - -## Architecture - -``` -Deno/AffineScript → Zig (stable C ABI) → Rust (native) -``` - -## Prerequisites - -1. **Rust toolchain**: `rustup install stable` -2. **Zig compiler**: `zig version` (0.11.0 or later recommended) - -## Building - -```bash -# Build Rust library first -cargo build --release - -# Build Zig FFI layer -cd zig -zig build -Doptimize=ReleaseFast -``` - -Output libraries: -- Linux: `zig-out/lib/libbunsenite.so` -- macOS: `zig-out/lib/libbunsenite.dylib` -- Windows: `zig-out/lib/bunsenite.dll` - -## Exported Symbols - -| Symbol | Parameters | Returns | Description | -|--------|------------|---------|-------------| -| `parse_nickel` | `(source, name)` | `char*` | Parse Nickel to JSON | -| `validate_nickel` | `(source, name)` | `int` | Validate config (0=ok) | -| `free_string` | `(ptr)` | `void` | Free allocated string | -| `version` | `()` | `char*` | Library version | -| `rsr_tier` | `()` | `char*` | RSR compliance tier | -| `tpcf_perimeter` | `()` | `u8` | TPCF perimeter number | - -## Testing - -```bash -# Run Zig tests (requires Rust library) -cargo build --release -cd zig && zig build test -``` - -## Integration - -### Deno - -The Zig library is used by `bindings/deno/bunsenite.ts` via `Deno.dlopen()`. - -### AffineScript - -The Zig library is used by `bindings/affinescript/Bunsenite.res` via C FFI. - -## RSR Compliance - -This FFI layer maintains RSR Bronze tier compliance: -- Type safety through Zig's type system -- Memory safety with explicit allocation/deallocation -- No network dependencies