diff --git a/ABI-FFI-README.adoc b/ABI-FFI-README.adoc new file mode 100644 index 000000000..980688726 --- /dev/null +++ b/ABI-FFI-README.adoc @@ -0,0 +1,409 @@ +\{\{~ Aditionally delete this line and fill out the template below ~}} + +== developer-ecosystem ABI/FFI Documentation + +=== Overview + +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 + +=== Architecture + +.... +┌─────────────────────────────────────────────┐ +│ ABI Definitions (Idris2) │ +│ src/abi/ │ +│ - Types.idr (Type definitions) │ +│ - Layout.idr (Memory layout proofs) │ +│ - Foreign.idr (FFI declarations) │ +└─────────────────┬───────────────────────────┘ + │ + │ generates (at compile time) + ▼ +┌─────────────────────────────────────────────┐ +│ C Headers (auto-generated) │ +│ generated/abi/{{project}}.h │ +└─────────────────┬───────────────────────────┘ + │ + │ imported by + ▼ +┌─────────────────────────────────────────────┐ +│ FFI Implementation (Zig) │ +│ ffi/zig/src/main.zig │ +│ - Implements C-compatible functions │ +│ - Zero-cost abstractions │ +│ - Memory-safe by default │ +└─────────────────┬───────────────────────────┘ + │ + │ compiled to lib{{project}}.so/.a + ▼ +┌─────────────────────────────────────────────┐ +│ Any Language via C ABI │ +│ - Rust, ReScript, Julia, Python, etc. │ +└─────────────────────────────────────────────┘ +.... + +=== Directory Structure + +.... +{{project}}/ +├── src/ +│ ├── abi/ # ABI definitions (Idris2) +│ │ ├── Types.idr # Core type definitions with proofs +│ │ ├── Layout.idr # Memory layout verification +│ │ └── Foreign.idr # FFI function declarations +│ └── lib/ # Core library (any language) +│ +├── ffi/ +│ └── zig/ # FFI implementation (Zig) +│ ├── build.zig # Build configuration +│ ├── build.zig.zon # Dependencies +│ ├── src/ +│ │ └── main.zig # C-compatible FFI implementation +│ ├── test/ +│ │ └── integration_test.zig +│ └── include/ +│ └── {{project}}.h # C header (optional, can be generated) +│ +├── generated/ # Auto-generated files +│ └── abi/ +│ └── {{project}}.h # Generated from Idris2 ABI +│ +└── bindings/ # Language-specific wrappers (optional) + ├── rust/ + ├── rescript/ + └── julia/ +.... + +=== Why Idris2 for ABI? + +==== 1. *Formal Verification* + +Idris2’s dependent types allow proving properties about the ABI at +compile-time: + +[source,idris] +---- +-- Prove struct size is correct +public export +exampleStructSize : HasSize ExampleStruct 16 + +-- Prove field alignment is correct +public export +fieldAligned : Divides 8 (offsetOf ExampleStruct.field) + +-- Prove ABI is platform-compatible +public export +abiCompatible : Compatible (ABI 1) (ABI 2) +---- + +==== 2. *Type Safety* + +Encode invariants that C/Zig cannot express: + +[source,idris] +---- +-- Non-null pointer guaranteed at type level +data Handle : Type where + MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle + +-- Array with length proof +data Buffer : (n : Nat) -> Type where + MkBuffer : Vect n Byte -> Buffer n +---- + +==== 3. *Platform Abstraction* + +Platform-specific types with compile-time selection: + +[source,idris] +---- +CInt : Platform -> Type +CInt Linux = Bits32 +CInt Windows = Bits32 + +CSize : Platform -> Type +CSize Linux = Bits64 +CSize Windows = Bits64 +---- + +==== 4. *Safe Evolution* + +Prove that new ABI versions are backward-compatible: + +[source,idris] +---- +-- Compiler enforces compatibility +abiUpgrade : ABI 1 -> ABI 2 +abiUpgrade old = MkABI2 { + -- Must preserve all v1 fields + v1_compat = old, + -- Can add new fields + new_features = defaults +} +---- + +=== Why Zig for FFI? + +==== 1. *C ABI Compatibility* + +Zig exports C-compatible functions naturally: + +[source,zig] +---- +export fn library_function(param: i32) i32 { + return param * 2; +} +---- + +==== 2. *Memory Safety* + +Compile-time safety without runtime overhead: + +[source,zig] +---- +// Null check enforced at compile time +const handle = init() orelse return error.InitFailed; +defer free(handle); +---- + +==== 3. *Cross-Compilation* + +Built-in cross-compilation to any platform: + +[source,bash] +---- +zig build -Dtarget=x86_64-linux +zig build -Dtarget=aarch64-macos +zig build -Dtarget=x86_64-windows +---- + +==== 4. *Zero Dependencies* + +No runtime, no libc required (unless explicitly needed): + +[source,zig] +---- +// Minimal binary size +pub const lib = @import("std"); +// Only includes what you use +---- + +=== Building + +==== Build FFI Library + +[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 + +[source,bash] +---- +cd src/abi +idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h +---- + +==== Cross-Compile + +[source,bash] +---- +cd ffi/zig + +# Linux x86_64 +zig build -Dtarget=x86_64-linux + +# macOS ARM64 +zig build -Dtarget=aarch64-macos + +# Windows x86_64 +zig build -Dtarget=x86_64-windows +---- + +=== Usage + +==== From C + +[source,c] +---- +#include "{{project}}.h" + +int main() { + void* handle = {{project}}_init(); + if (!handle) return 1; + + int result = {{project}}_process(handle, 42); + if (result != 0) { + const char* err = {{project}}_last_error(); + fprintf(stderr, "Error: %s\n", err); + } + + {{project}}_free(handle); + return 0; +} +---- + +Compile with: + +[source,bash] +---- +gcc -o example example.c -l{{project}} -L./zig-out/lib +---- + +==== From Idris2 + +[source,idris] +---- +import developer-ecosystem.ABI.Foreign + +main : IO () +main = do + Just handle <- init + | Nothing => putStrLn "Failed to initialize" + + Right result <- process handle 42 + | Left err => putStrLn $ "Error: " ++ errorDescription err + + free handle + putStrLn "Success" +---- + +==== From Rust + +[source,rust] +---- +#[link(name = "{{project}}")] +extern "C" { + fn {{project}}_init() -> *mut std::ffi::c_void; + fn {{project}}_free(handle: *mut std::ffi::c_void); + fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; +} + +fn main() { + unsafe { + let handle = {{project}}_init(); + assert!(!handle.is_null()); + + let result = {{project}}_process(handle, 42); + assert_eq!(result, 0); + + {{project}}_free(handle); + } +} +---- + +==== From Julia + +[source,julia] +---- +const lib{{project}} = "lib{{project}}" + +function init() + handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) + handle == C_NULL && error("Failed to initialize") + handle +end + +function process(handle, input) + result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) + result +end + +function cleanup(handle) + ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) +end + +# Usage +handle = init() +try + result = process(handle, 42) + println("Result: $result") +finally + cleanup(handle) +end +---- + +=== Testing + +==== Unit Tests (Zig) + +[source,bash] +---- +cd ffi/zig +zig build test +---- + +==== Integration Tests + +[source,bash] +---- +cd ffi/zig +zig build test-integration +---- + +==== ABI Verification (Idris2) + +[source,idris] +---- +-- Compile-time verification +%runElab verifyABI + +-- Runtime checks +main : IO () +main = do + verifyLayoutsCorrect + verifyAlignmentsCorrect + putStrLn "ABI verification passed" +---- + +=== Contributing + +When modifying the ABI/FFI: + +[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 + +PMPL-1.0-or-later + +=== See Also + +* 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/ABI-FFI-README.md b/ABI-FFI-README.md deleted file mode 100644 index 145ec3526..000000000 --- a/ABI-FFI-README.md +++ /dev/null @@ -1,385 +0,0 @@ -{{~ Aditionally delete this line and fill out the template below ~}} - -# developer-ecosystem ABI/FFI Documentation - -## Overview - -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 - -## Architecture - -``` -┌─────────────────────────────────────────────┐ -│ ABI Definitions (Idris2) │ -│ src/abi/ │ -│ - Types.idr (Type definitions) │ -│ - Layout.idr (Memory layout proofs) │ -│ - Foreign.idr (FFI declarations) │ -└─────────────────┬───────────────────────────┘ - │ - │ generates (at compile time) - ▼ -┌─────────────────────────────────────────────┐ -│ C Headers (auto-generated) │ -│ generated/abi/{{project}}.h │ -└─────────────────┬───────────────────────────┘ - │ - │ imported by - ▼ -┌─────────────────────────────────────────────┐ -│ FFI Implementation (Zig) │ -│ ffi/zig/src/main.zig │ -│ - Implements C-compatible functions │ -│ - Zero-cost abstractions │ -│ - Memory-safe by default │ -└─────────────────┬───────────────────────────┘ - │ - │ compiled to lib{{project}}.so/.a - ▼ -┌─────────────────────────────────────────────┐ -│ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ -└─────────────────────────────────────────────┘ -``` - -## Directory Structure - -``` -{{project}}/ -├── src/ -│ ├── abi/ # ABI definitions (Idris2) -│ │ ├── Types.idr # Core type definitions with proofs -│ │ ├── Layout.idr # Memory layout verification -│ │ └── Foreign.idr # FFI function declarations -│ └── lib/ # Core library (any language) -│ -├── ffi/ -│ └── zig/ # FFI implementation (Zig) -│ ├── build.zig # Build configuration -│ ├── build.zig.zon # Dependencies -│ ├── src/ -│ │ └── main.zig # C-compatible FFI implementation -│ ├── test/ -│ │ └── integration_test.zig -│ └── include/ -│ └── {{project}}.h # C header (optional, can be generated) -│ -├── generated/ # Auto-generated files -│ └── abi/ -│ └── {{project}}.h # Generated from Idris2 ABI -│ -└── bindings/ # Language-specific wrappers (optional) - ├── rust/ - ├── rescript/ - └── julia/ -``` - -## Why Idris2 for ABI? - -### 1. **Formal Verification** - -Idris2's dependent types allow proving properties about the ABI at compile-time: - -```idris --- Prove struct size is correct -public export -exampleStructSize : HasSize ExampleStruct 16 - --- Prove field alignment is correct -public export -fieldAligned : Divides 8 (offsetOf ExampleStruct.field) - --- Prove ABI is platform-compatible -public export -abiCompatible : Compatible (ABI 1) (ABI 2) -``` - -### 2. **Type Safety** - -Encode invariants that C/Zig cannot express: - -```idris --- Non-null pointer guaranteed at type level -data Handle : Type where - MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle - --- Array with length proof -data Buffer : (n : Nat) -> Type where - MkBuffer : Vect n Byte -> Buffer n -``` - -### 3. **Platform Abstraction** - -Platform-specific types with compile-time selection: - -```idris -CInt : Platform -> Type -CInt Linux = Bits32 -CInt Windows = Bits32 - -CSize : Platform -> Type -CSize Linux = Bits64 -CSize Windows = Bits64 -``` - -### 4. **Safe Evolution** - -Prove that new ABI versions are backward-compatible: - -```idris --- Compiler enforces compatibility -abiUpgrade : ABI 1 -> ABI 2 -abiUpgrade old = MkABI2 { - -- Must preserve all v1 fields - v1_compat = old, - -- Can add new fields - new_features = defaults -} -``` - -## Why Zig for FFI? - -### 1. **C ABI Compatibility** - -Zig exports C-compatible functions naturally: - -```zig -export fn library_function(param: i32) i32 { - return param * 2; -} -``` - -### 2. **Memory Safety** - -Compile-time safety without runtime overhead: - -```zig -// Null check enforced at compile time -const handle = init() orelse return error.InitFailed; -defer free(handle); -``` - -### 3. **Cross-Compilation** - -Built-in cross-compilation to any platform: - -```bash -zig build -Dtarget=x86_64-linux -zig build -Dtarget=aarch64-macos -zig build -Dtarget=x86_64-windows -``` - -### 4. **Zero Dependencies** - -No runtime, no libc required (unless explicitly needed): - -```zig -// Minimal binary size -pub const lib = @import("std"); -// Only includes what you use -``` - -## Building - -### Build FFI Library - -```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 - -```bash -cd src/abi -idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` - -### Cross-Compile - -```bash -cd ffi/zig - -# Linux x86_64 -zig build -Dtarget=x86_64-linux - -# macOS ARM64 -zig build -Dtarget=aarch64-macos - -# Windows x86_64 -zig build -Dtarget=x86_64-windows -``` - -## Usage - -### From C - -```c -#include "{{project}}.h" - -int main() { - void* handle = {{project}}_init(); - if (!handle) return 1; - - int result = {{project}}_process(handle, 42); - if (result != 0) { - const char* err = {{project}}_last_error(); - fprintf(stderr, "Error: %s\n", err); - } - - {{project}}_free(handle); - return 0; -} -``` - -Compile with: -```bash -gcc -o example example.c -l{{project}} -L./zig-out/lib -``` - -### From Idris2 - -```idris -import developer-ecosystem.ABI.Foreign - -main : IO () -main = do - Just handle <- init - | Nothing => putStrLn "Failed to initialize" - - Right result <- process handle 42 - | Left err => putStrLn $ "Error: " ++ errorDescription err - - free handle - putStrLn "Success" -``` - -### From Rust - -```rust -#[link(name = "{{project}}")] -extern "C" { - fn {{project}}_init() -> *mut std::ffi::c_void; - fn {{project}}_free(handle: *mut std::ffi::c_void); - fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; -} - -fn main() { - unsafe { - let handle = {{project}}_init(); - assert!(!handle.is_null()); - - let result = {{project}}_process(handle, 42); - assert_eq!(result, 0); - - {{project}}_free(handle); - } -} -``` - -### From Julia - -```julia -const lib{{project}} = "lib{{project}}" - -function init() - handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) - handle == C_NULL && error("Failed to initialize") - handle -end - -function process(handle, input) - result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) - result -end - -function cleanup(handle) - ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) -end - -# Usage -handle = init() -try - result = process(handle, 42) - println("Result: $result") -finally - cleanup(handle) -end -``` - -## Testing - -### Unit Tests (Zig) - -```bash -cd ffi/zig -zig build test -``` - -### Integration Tests - -```bash -cd ffi/zig -zig build test-integration -``` - -### ABI Verification (Idris2) - -```idris --- Compile-time verification -%runElab verifyABI - --- Runtime checks -main : IO () -main = do - verifyLayoutsCorrect - verifyAlignmentsCorrect - putStrLn "ABI verification passed" -``` - -## 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 - -PMPL-1.0-or-later - -## 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) diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 000000000..1c0a7a697 --- /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 607e3d8cd..000000000 --- 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 new file mode 100644 index 000000000..9481df2b0 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,48 @@ +== Changelog + +All notable changes to `+developer-ecosystem+` will be documented in +this file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Fixed + +* fix(licence): developer-ecosystem — clear scaffold-placeholder leak +(superproject) (#76) +* fix(affine): migrate record literal to #\{ } (affinescript#218) (#73) +* fix(ci): bump a2ml/k9-validate-action pins to canonical (#68) +* fix(ci): sync hypatia-scan.yml to canonical (#67) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) + +==== CI + +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#72) +* ci: fix nonexistent actions/upload-artifact SHA pin (Refs +standards#48) (#66) + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 6ec72dc3f..000000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,45 +0,0 @@ - - -# Changelog - -All notable changes to `developer-ecosystem` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Fixed - -- fix(licence): developer-ecosystem — clear scaffold-placeholder leak (superproject) (#76) -- fix(affine): migrate record literal to #{ } (affinescript#218) (#73) -- fix(ci): bump a2ml/k9-validate-action pins to canonical (#68) -- fix(ci): sync hypatia-scan.yml to canonical (#67) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) - -### CI - -- ci: redistribute concurrency-cancel guard to read-only check workflows (#72) -- ci: fix nonexistent actions/upload-artifact SHA pin (Refs standards#48) (#66) - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..bd2a83cb8 --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c6d..000000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 000000000..c9bf5d4fd --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/developer-ecosystem.git cd +developer-ecosystem + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create developer-ecosystem-dev toolbox enter +developer-ecosystem-dev # Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +developer-ecosystem/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # +Library code (Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) +├── plugins/ # Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter 2) +├── docs/ # Documentation (Perimeter 3) │ ├── architecture/ # ADRs, +specs (Perimeter 2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ +# Examples (Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ +# Test suite (Perimeter 2-3) ├── .well-known/ # Protocol files +(Perimeter 1-3) ├── .github/ # GitHub config (Perimeter 1) │ ├── +ISSUE_TEMPLATE/ │ └── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── LICENSE ├── +MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.nix # Nix flake +(Perimeter 1) └── Justfile # Task runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/developer-ecosystem/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/developer-ecosystem/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/developer-ecosystem/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/developer-ecosystem/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 694bcf6a1..000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/developer-ecosystem.git -cd developer-ecosystem - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create developer-ecosystem-dev -toolbox enter developer-ecosystem-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -developer-ecosystem/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/developer-ecosystem/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/developer-ecosystem/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/developer-ecosystem/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/developer-ecosystem/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc index e41020d3b..9b836fb28 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 e27364c75..000000000 --- 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/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 000000000..7d5132fbb --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,12 @@ +== PROOF-NEEDS.md + +=== 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. + +When this project needs formal ABI verification, create domain-specific +Idris2 proofs following the pattern in repos like `+typed-wasm+`, +`+proven+`, `+echidna+`, or `+boj-server+`. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index 895032028..000000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,10 +0,0 @@ -# PROOF-NEEDS.md - -## 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. - -When this project needs formal ABI verification, create domain-specific Idris2 proofs -following the pattern in repos like `typed-wasm`, `proven`, `echidna`, or `boj-server`. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 000000000..b0574dfd2 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,24 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|main |:white_check_mark: +|< main |:x: +|=== + +=== Reporting a Vulnerability + +Please report security vulnerabilities through GitHub private +vulnerability reporting: 1. Go to the *Security* tab 2. Click *Report a +vulnerability* 3. Fill out the form + +We respond within 48 hours. + +=== Security Measures + +* Dependabot for dependency updates +* CodeQL for code scanning +* Secret scanning and push protection diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 159a0b7af..000000000 --- a/SECURITY.md +++ /dev/null @@ -1,25 +0,0 @@ - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| main | :white_check_mark: | -| < main | :x: | - -## Reporting a Vulnerability - -Please report security vulnerabilities through GitHub private vulnerability reporting: -1. Go to the **Security** tab -2. Click **Report a vulnerability** -3. Fill out the form - -We respond within 48 hours. - -## Security Measures - -- Dependabot for dependency updates -- CodeQL for code scanning -- Secret scanning and push protection - diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 000000000..4d7d11355 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,118 @@ +== Test & Benchmark Requirements + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +All CRG C categories represented in `+opm-canonicalizer+` (the primary +testable sub-project): - Unit: 22 tests (null, bool, int, string, object +sorting, escaping, error cases) - Smoke: duplicate key rejection, float +rejection - P2P/property: 5 proptest properties (idempotence, +no-whitespace, key sorting, array order, negative int roundtrip) - +E2E/reflexive: canonicalize-twice idempotency, whitespace stripping - +Contract: output format invariants (no spaces between tokens, negative +ints preserved) - Aspect: empty string, control char escaping, deep +nesting (50 levels), malformed input - Benchmarks: 5 Criterion +benchmarks (null, simple object, nested object, array, escapes) + +*Ecosystem-wide*: 2248 test files across 29+ sub-ecosystems (includes +rescript-ecosystem compiler tests, Zig integration tests, +robot-vacuum-cleaner Julia tests, etc.) + +=== Current State + +* Unit tests: ~5 Rust test files + ~4 TS test files + ~54 Zig test files +— partial coverage +* Integration tests: partial (some Zig integration tests across +ecosystem packages) +* E2E tests: NONE +* Benchmarks: ~738 benchmark files (mostly V-lang ecosystem benchmarks) +* panic-attack scan: NEVER RUN + +=== What’s Missing + +==== Point-to-Point (P2P) + +This is a massive monorepo (29+ sub-ecosystems) with extreme variation +in test coverage: + +*Source file counts:* - ReScript: 3,446 files — likely bulk of code, +ZERO test files identified - Julia: 635 files — ZERO test files +identified - Idris2: 323 files — ZERO test files identified - V: 201 +files — ZERO dedicated test files (benchmarks exist) - Zig: 180 files — +54 test files (BEST coverage ratio) - Rust: 90 files — 5 test files - +Haskell: 77 files — ZERO test files - Elixir: 54 files — ZERO test files +- JavaScript: 557 files — ZERO test files - TypeScript: 25 files — 4 +test files - Shell: 300 files — ZERO test files + +===== Sub-ecosystems with tests: + +* zig-ecosystem/ — 54 Zig test files (reasonable for 180 source files) +* deno-ecosystem/ — 4 TS test files (inadequate for ecosystem size) +* Some Rust components — 5 test files + +===== Sub-ecosystems with ZERO tests: + +* *rescript-ecosystem/* (3,446 files) — completely untested +* *julia-ecosystem/* (635 files) — completely untested +* *idris2-ecosystem/* (323 files) — completely untested +* *v-ecosystem/* (201 files) — benchmarks only, no correctness tests +* *haskell ecosystem* (77 files) — completely untested +* *ada-ecosystem/* — completely untested +* *coq-ecosystem/* — no test files found +* *well-known-ecosystem/* — no test files found +* *package-publishers/* — no test files found +* *techstack-enforcer/* — no test files found + +==== End-to-End (E2E) + +* Ecosystem package build and test cycle per language +* Cross-ecosystem dependency resolution +* Package publishing workflow per ecosystem +* Satellite submodule synchronization +* Tool version enforcement + +==== Aspect Tests + +* [ ] Security (package supply chain, dependency confusion, malicious +packages) +* [ ] Performance (build time per ecosystem, package resolution speed) +* [ ] Concurrency (parallel builds across ecosystems) +* [ ] Error handling (missing tools, version conflicts, broken +satellites) +* [ ] Accessibility (N/A) + +==== Build & Execution + +* [ ] Per-ecosystem builds — not systematically verified +* [ ] Satellite submodule integrity — not verified +* [ ] Package publishing dry-run — not verified +* [ ] Self-diagnostic — none + +==== Benchmarks Needed + +* Per-ecosystem build times +* Package resolution performance +* Cross-ecosystem integration latency +* Verify 738 existing benchmark files actually run (likely V-lang +benchmarks) + +==== Self-Tests + +* [ ] panic-attack assail on own repo +* [ ] Per-ecosystem health check + +=== Priority + +* *HIGH* — Staggeringly large monorepo (3,446 ReScript + 635 Julia + 557 +JS + 323 Idris2 + 300 Shell + 201 V + 180 Zig + 90 Rust + 77 Haskell + +54 Elixir files). The ReScript ecosystem alone has 3,446 source files +with ZERO tests. Only the Zig ecosystem has reasonable test coverage. +The 738 "`benchmark`" files are likely V-lang ecosystem benchmarks, not +project-level performance tests. + +=== FAKE-FUZZ ALERT + +* `+tests/fuzz/placeholder.txt+` is a scorecard placeholder inherited +from rsr-template-repo — it does NOT provide real fuzz testing +* Replace with an actual fuzz harness (see +rsr-template-repo/tests/fuzz/README.adoc) or remove the file +* Priority: P2 — creates false impression of fuzz coverage diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 2bc5c135c..000000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,94 +0,0 @@ -# Test & Benchmark Requirements - -## CRG Grade: C — ACHIEVED 2026-04-04 - -All CRG C categories represented in `opm-canonicalizer` (the primary testable sub-project): -- Unit: 22 tests (null, bool, int, string, object sorting, escaping, error cases) -- Smoke: duplicate key rejection, float rejection -- P2P/property: 5 proptest properties (idempotence, no-whitespace, key sorting, array order, negative int roundtrip) -- E2E/reflexive: canonicalize-twice idempotency, whitespace stripping -- Contract: output format invariants (no spaces between tokens, negative ints preserved) -- Aspect: empty string, control char escaping, deep nesting (50 levels), malformed input -- Benchmarks: 5 Criterion benchmarks (null, simple object, nested object, array, escapes) - -**Ecosystem-wide**: 2248 test files across 29+ sub-ecosystems (includes rescript-ecosystem compiler tests, Zig integration tests, robot-vacuum-cleaner Julia tests, etc.) - -## Current State -- Unit tests: ~5 Rust test files + ~4 TS test files + ~54 Zig test files — partial coverage -- Integration tests: partial (some Zig integration tests across ecosystem packages) -- E2E tests: NONE -- Benchmarks: ~738 benchmark files (mostly V-lang ecosystem benchmarks) -- panic-attack scan: NEVER RUN - -## What's Missing -### Point-to-Point (P2P) -This is a massive monorepo (29+ sub-ecosystems) with extreme variation in test coverage: - -**Source file counts:** -- ReScript: 3,446 files — likely bulk of code, ZERO test files identified -- Julia: 635 files — ZERO test files identified -- Idris2: 323 files — ZERO test files identified -- V: 201 files — ZERO dedicated test files (benchmarks exist) -- Zig: 180 files — 54 test files (BEST coverage ratio) -- Rust: 90 files — 5 test files -- Haskell: 77 files — ZERO test files -- Elixir: 54 files — ZERO test files -- JavaScript: 557 files — ZERO test files -- TypeScript: 25 files — 4 test files -- Shell: 300 files — ZERO test files - -#### Sub-ecosystems with tests: -- zig-ecosystem/ — 54 Zig test files (reasonable for 180 source files) -- deno-ecosystem/ — 4 TS test files (inadequate for ecosystem size) -- Some Rust components — 5 test files - -#### Sub-ecosystems with ZERO tests: -- **rescript-ecosystem/** (3,446 files) — completely untested -- **julia-ecosystem/** (635 files) — completely untested -- **idris2-ecosystem/** (323 files) — completely untested -- **v-ecosystem/** (201 files) — benchmarks only, no correctness tests -- **haskell ecosystem** (77 files) — completely untested -- **ada-ecosystem/** — completely untested -- **coq-ecosystem/** — no test files found -- **well-known-ecosystem/** — no test files found -- **package-publishers/** — no test files found -- **techstack-enforcer/** — no test files found - -### End-to-End (E2E) -- Ecosystem package build and test cycle per language -- Cross-ecosystem dependency resolution -- Package publishing workflow per ecosystem -- Satellite submodule synchronization -- Tool version enforcement - -### Aspect Tests -- [ ] Security (package supply chain, dependency confusion, malicious packages) -- [ ] Performance (build time per ecosystem, package resolution speed) -- [ ] Concurrency (parallel builds across ecosystems) -- [ ] Error handling (missing tools, version conflicts, broken satellites) -- [ ] Accessibility (N/A) - -### Build & Execution -- [ ] Per-ecosystem builds — not systematically verified -- [ ] Satellite submodule integrity — not verified -- [ ] Package publishing dry-run — not verified -- [ ] Self-diagnostic — none - -### Benchmarks Needed -- Per-ecosystem build times -- Package resolution performance -- Cross-ecosystem integration latency -- Verify 738 existing benchmark files actually run (likely V-lang benchmarks) - -### Self-Tests -- [ ] panic-attack assail on own repo -- [ ] Per-ecosystem health check - -## Priority -- **HIGH** — Staggeringly large monorepo (3,446 ReScript + 635 Julia + 557 JS + 323 Idris2 + 300 Shell + 201 V + 180 Zig + 90 Rust + 77 Haskell + 54 Elixir files). The ReScript ecosystem alone has 3,446 source files with ZERO tests. Only the Zig ecosystem has reasonable test coverage. The 738 "benchmark" files are likely V-lang ecosystem benchmarks, not project-level performance tests. - -## FAKE-FUZZ ALERT - -- `tests/fuzz/placeholder.txt` is a scorecard placeholder inherited from rsr-template-repo — it does NOT provide real fuzz testing -- Replace with an actual fuzz harness (see rsr-template-repo/tests/fuzz/README.adoc) or remove the file -- Priority: P2 — creates false impression of fuzz coverage diff --git a/TOPOLOGY.adoc b/TOPOLOGY.adoc new file mode 100644 index 000000000..77fa300d4 --- /dev/null +++ b/TOPOLOGY.adoc @@ -0,0 +1,98 @@ +== Developer Ecosystem — Project Topology + +=== System Architecture + +.... + ┌─────────────────────────────────────────┐ + │ DEVELOPER UX │ + │ (IDE, Dashboard, CLI) │ + └───────────────────┬─────────────────────┘ + │ + ▼ + ┌─────────────────────────────────────────┐ + │ DEVELOPER ECOSYSTEM HUB │ + │ │ + │ ┌───────────┐ ┌───────────────────┐ │ + │ │ Git Tools │ │ Repo Management │ │ + │ │ (Forges, │ │ (Automaton, │ │ + │ │ Sync) │ │ Vacuum, Grim) │ │ + │ └─────┬─────┘ └────────┬──────────┘ │ + │ │ │ │ + │ ┌─────▼─────┐ ┌────────▼──────────┐ │ + │ │Scaffolding│ │ Developer UX │ │ + │ │(Scaffoldia│ │ (Evangeliser, │ │ + │ │ Standard)│ │ Recon-silly) │ │ + │ └─────┬─────┘ └───────────────────┘ │ + └────────│────────────────────────────────┘ + │ + ▼ + ┌─────────────────────────────────────────┐ + │ SATELLITE REPOSITORIES │ + │ ┌───────────┐ ┌───────────┐ ┌───────┐│ + │ │ git-hud │ │ oikos │ │ nickel││ + │ └───────────┘ └───────────┘ └───────┘│ + │ ┌───────────┐ ┌───────────┐ ┌───────┐│ + │ │ gitloom │ │ grim-repo │ │ pssh ││ + │ └───────────┘ └───────────┘ └───────┘│ + └───────────────────┬─────────────────────┘ + │ + ▼ + ┌─────────────────────────────────────────┐ + │ UPSTREAM STANDARDS │ + │ (RSR, CCCP Language Policy) │ + └─────────────────────────────────────────┘ + + ┌─────────────────────────────────────────┐ + │ REPO INFRASTRUCTURE │ + │ Justfile .machine_readable/ │ + │ Aggregate Libs Techstack Filter │ + └─────────────────────────────────────────┘ +.... + +=== Completion Dashboard + +.... +COMPONENT STATUS NOTES +───────────────────────────────── ────────────────── ───────────────────────────────── +CORE ECOSYSTEM + Git Tools (Hub) ██████████ 100% Forge management stable + Repo Management ████████░░ 80% Automaton logic refining + Scaffolding (scaffoldia) ██████████ 100% Modular templates active + Developer UX ██████░░░░ 60% VS Code extension in progress + +ECOSYSTEM SATELLITES + idris2-ecosystem ██████████ 100% Unbreakable libs verified + zig-ecosystem ██████████ 100% FFI bridge standards stable + rescript-ecosystem ██████████ 100% SafeDOM integration verified + deno-ecosystem ████████░░ 80% Runtime security refined + +REPO INFRASTRUCTURE + Justfile ██████████ 100% Full build automation + .machine_readable/ ██████████ 100% STATE.a2ml tracking + Techstack Filterlist ██████████ 100% CCCP compliance active + +───────────────────────────────────────────────────────────────────────────── +OVERALL: █████████░ ~90% Central developer hub operational +.... + +=== Key Dependencies + +.... +CCCP Policy ───► RSR Standard ───► Developer Hub ───► Satellites + │ │ │ │ + ▼ ▼ ▼ ▼ +Language Check ──► Compliance ─────► Scaffolding ───► Git Forge +.... + +=== Update Protocol + +This file is maintained by both humans and AI agents. When updating: + +[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). diff --git a/TOPOLOGY.md b/TOPOLOGY.md deleted file mode 100644 index a725ef78a..000000000 --- a/TOPOLOGY.md +++ /dev/null @@ -1,101 +0,0 @@ - - - - -# Developer Ecosystem — Project Topology - -## System Architecture - -``` - ┌─────────────────────────────────────────┐ - │ DEVELOPER UX │ - │ (IDE, Dashboard, CLI) │ - └───────────────────┬─────────────────────┘ - │ - ▼ - ┌─────────────────────────────────────────┐ - │ DEVELOPER ECOSYSTEM HUB │ - │ │ - │ ┌───────────┐ ┌───────────────────┐ │ - │ │ Git Tools │ │ Repo Management │ │ - │ │ (Forges, │ │ (Automaton, │ │ - │ │ Sync) │ │ Vacuum, Grim) │ │ - │ └─────┬─────┘ └────────┬──────────┘ │ - │ │ │ │ - │ ┌─────▼─────┐ ┌────────▼──────────┐ │ - │ │Scaffolding│ │ Developer UX │ │ - │ │(Scaffoldia│ │ (Evangeliser, │ │ - │ │ Standard)│ │ Recon-silly) │ │ - │ └─────┬─────┘ └───────────────────┘ │ - └────────│────────────────────────────────┘ - │ - ▼ - ┌─────────────────────────────────────────┐ - │ SATELLITE REPOSITORIES │ - │ ┌───────────┐ ┌───────────┐ ┌───────┐│ - │ │ git-hud │ │ oikos │ │ nickel││ - │ └───────────┘ └───────────┘ └───────┘│ - │ ┌───────────┐ ┌───────────┐ ┌───────┐│ - │ │ gitloom │ │ grim-repo │ │ pssh ││ - │ └───────────┘ └───────────┘ └───────┘│ - └───────────────────┬─────────────────────┘ - │ - ▼ - ┌─────────────────────────────────────────┐ - │ UPSTREAM STANDARDS │ - │ (RSR, CCCP Language Policy) │ - └─────────────────────────────────────────┘ - - ┌─────────────────────────────────────────┐ - │ REPO INFRASTRUCTURE │ - │ Justfile .machine_readable/ │ - │ Aggregate Libs Techstack Filter │ - └─────────────────────────────────────────┘ -``` - -## Completion Dashboard - -``` -COMPONENT STATUS NOTES -───────────────────────────────── ────────────────── ───────────────────────────────── -CORE ECOSYSTEM - Git Tools (Hub) ██████████ 100% Forge management stable - Repo Management ████████░░ 80% Automaton logic refining - Scaffolding (scaffoldia) ██████████ 100% Modular templates active - Developer UX ██████░░░░ 60% VS Code extension in progress - -ECOSYSTEM SATELLITES - idris2-ecosystem ██████████ 100% Unbreakable libs verified - zig-ecosystem ██████████ 100% FFI bridge standards stable - rescript-ecosystem ██████████ 100% SafeDOM integration verified - deno-ecosystem ████████░░ 80% Runtime security refined - -REPO INFRASTRUCTURE - Justfile ██████████ 100% Full build automation - .machine_readable/ ██████████ 100% STATE.a2ml tracking - Techstack Filterlist ██████████ 100% CCCP compliance active - -───────────────────────────────────────────────────────────────────────────── -OVERALL: █████████░ ~90% Central developer hub operational -``` - -## Key Dependencies - -``` -CCCP Policy ───► RSR Standard ───► Developer Hub ───► Satellites - │ │ │ │ - ▼ ▼ ▼ ▼ -Language Check ──► Compliance ─────► Scaffolding ───► Git Forge -``` - -## 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 - -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). diff --git a/ada-ecosystem/ada-loom-registry/ABI-FFI-README.adoc b/ada-ecosystem/ada-loom-registry/ABI-FFI-README.adoc new file mode 100644 index 000000000..961ca5559 --- /dev/null +++ b/ada-ecosystem/ada-loom-registry/ABI-FFI-README.adoc @@ -0,0 +1,409 @@ +\{\{~ Aditionally delete this line and fill out the template below ~}} + +== ada-loom-registry ABI/FFI Documentation + +=== Overview + +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 + +=== Architecture + +.... +┌─────────────────────────────────────────────┐ +│ ABI Definitions (Idris2) │ +│ src/abi/ │ +│ - Types.idr (Type definitions) │ +│ - Layout.idr (Memory layout proofs) │ +│ - Foreign.idr (FFI declarations) │ +└─────────────────┬───────────────────────────┘ + │ + │ generates (at compile time) + ▼ +┌─────────────────────────────────────────────┐ +│ C Headers (auto-generated) │ +│ generated/abi/{{project}}.h │ +└─────────────────┬───────────────────────────┘ + │ + │ imported by + ▼ +┌─────────────────────────────────────────────┐ +│ FFI Implementation (Zig) │ +│ ffi/zig/src/main.zig │ +│ - Implements C-compatible functions │ +│ - Zero-cost abstractions │ +│ - Memory-safe by default │ +└─────────────────┬───────────────────────────┘ + │ + │ compiled to lib{{project}}.so/.a + ▼ +┌─────────────────────────────────────────────┐ +│ Any Language via C ABI │ +│ - Rust, ReScript, Julia, Python, etc. │ +└─────────────────────────────────────────────┘ +.... + +=== Directory Structure + +.... +{{project}}/ +├── src/ +│ ├── abi/ # ABI definitions (Idris2) +│ │ ├── Types.idr # Core type definitions with proofs +│ │ ├── Layout.idr # Memory layout verification +│ │ └── Foreign.idr # FFI function declarations +│ └── lib/ # Core library (any language) +│ +├── ffi/ +│ └── zig/ # FFI implementation (Zig) +│ ├── build.zig # Build configuration +│ ├── build.zig.zon # Dependencies +│ ├── src/ +│ │ └── main.zig # C-compatible FFI implementation +│ ├── test/ +│ │ └── integration_test.zig +│ └── include/ +│ └── {{project}}.h # C header (optional, can be generated) +│ +├── generated/ # Auto-generated files +│ └── abi/ +│ └── {{project}}.h # Generated from Idris2 ABI +│ +└── bindings/ # Language-specific wrappers (optional) + ├── rust/ + ├── rescript/ + └── julia/ +.... + +=== Why Idris2 for ABI? + +==== 1. *Formal Verification* + +Idris2’s dependent types allow proving properties about the ABI at +compile-time: + +[source,idris] +---- +-- Prove struct size is correct +public export +exampleStructSize : HasSize ExampleStruct 16 + +-- Prove field alignment is correct +public export +fieldAligned : Divides 8 (offsetOf ExampleStruct.field) + +-- Prove ABI is platform-compatible +public export +abiCompatible : Compatible (ABI 1) (ABI 2) +---- + +==== 2. *Type Safety* + +Encode invariants that C/Zig cannot express: + +[source,idris] +---- +-- Non-null pointer guaranteed at type level +data Handle : Type where + MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle + +-- Array with length proof +data Buffer : (n : Nat) -> Type where + MkBuffer : Vect n Byte -> Buffer n +---- + +==== 3. *Platform Abstraction* + +Platform-specific types with compile-time selection: + +[source,idris] +---- +CInt : Platform -> Type +CInt Linux = Bits32 +CInt Windows = Bits32 + +CSize : Platform -> Type +CSize Linux = Bits64 +CSize Windows = Bits64 +---- + +==== 4. *Safe Evolution* + +Prove that new ABI versions are backward-compatible: + +[source,idris] +---- +-- Compiler enforces compatibility +abiUpgrade : ABI 1 -> ABI 2 +abiUpgrade old = MkABI2 { + -- Must preserve all v1 fields + v1_compat = old, + -- Can add new fields + new_features = defaults +} +---- + +=== Why Zig for FFI? + +==== 1. *C ABI Compatibility* + +Zig exports C-compatible functions naturally: + +[source,zig] +---- +export fn library_function(param: i32) i32 { + return param * 2; +} +---- + +==== 2. *Memory Safety* + +Compile-time safety without runtime overhead: + +[source,zig] +---- +// Null check enforced at compile time +const handle = init() orelse return error.InitFailed; +defer free(handle); +---- + +==== 3. *Cross-Compilation* + +Built-in cross-compilation to any platform: + +[source,bash] +---- +zig build -Dtarget=x86_64-linux +zig build -Dtarget=aarch64-macos +zig build -Dtarget=x86_64-windows +---- + +==== 4. *Zero Dependencies* + +No runtime, no libc required (unless explicitly needed): + +[source,zig] +---- +// Minimal binary size +pub const lib = @import("std"); +// Only includes what you use +---- + +=== Building + +==== Build FFI Library + +[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 + +[source,bash] +---- +cd src/abi +idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h +---- + +==== Cross-Compile + +[source,bash] +---- +cd ffi/zig + +# Linux x86_64 +zig build -Dtarget=x86_64-linux + +# macOS ARM64 +zig build -Dtarget=aarch64-macos + +# Windows x86_64 +zig build -Dtarget=x86_64-windows +---- + +=== Usage + +==== From C + +[source,c] +---- +#include "{{project}}.h" + +int main() { + void* handle = {{project}}_init(); + if (!handle) return 1; + + int result = {{project}}_process(handle, 42); + if (result != 0) { + const char* err = {{project}}_last_error(); + fprintf(stderr, "Error: %s\n", err); + } + + {{project}}_free(handle); + return 0; +} +---- + +Compile with: + +[source,bash] +---- +gcc -o example example.c -l{{project}} -L./zig-out/lib +---- + +==== From Idris2 + +[source,idris] +---- +import ada-loom-registry.ABI.Foreign + +main : IO () +main = do + Just handle <- init + | Nothing => putStrLn "Failed to initialize" + + Right result <- process handle 42 + | Left err => putStrLn $ "Error: " ++ errorDescription err + + free handle + putStrLn "Success" +---- + +==== From Rust + +[source,rust] +---- +#[link(name = "{{project}}")] +extern "C" { + fn {{project}}_init() -> *mut std::ffi::c_void; + fn {{project}}_free(handle: *mut std::ffi::c_void); + fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; +} + +fn main() { + unsafe { + let handle = {{project}}_init(); + assert!(!handle.is_null()); + + let result = {{project}}_process(handle, 42); + assert_eq!(result, 0); + + {{project}}_free(handle); + } +} +---- + +==== From Julia + +[source,julia] +---- +const lib{{project}} = "lib{{project}}" + +function init() + handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) + handle == C_NULL && error("Failed to initialize") + handle +end + +function process(handle, input) + result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) + result +end + +function cleanup(handle) + ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) +end + +# Usage +handle = init() +try + result = process(handle, 42) + println("Result: $result") +finally + cleanup(handle) +end +---- + +=== Testing + +==== Unit Tests (Zig) + +[source,bash] +---- +cd ffi/zig +zig build test +---- + +==== Integration Tests + +[source,bash] +---- +cd ffi/zig +zig build test-integration +---- + +==== ABI Verification (Idris2) + +[source,idris] +---- +-- Compile-time verification +%runElab verifyABI + +-- Runtime checks +main : IO () +main = do + verifyLayoutsCorrect + verifyAlignmentsCorrect + putStrLn "ABI verification passed" +---- + +=== Contributing + +When modifying the ABI/FFI: + +[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 + +PMPL-1.0-or-later + +=== See Also + +* 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/ada-ecosystem/ada-loom-registry/ABI-FFI-README.md b/ada-ecosystem/ada-loom-registry/ABI-FFI-README.md deleted file mode 100644 index 59a9e2d58..000000000 --- a/ada-ecosystem/ada-loom-registry/ABI-FFI-README.md +++ /dev/null @@ -1,385 +0,0 @@ -{{~ Aditionally delete this line and fill out the template below ~}} - -# ada-loom-registry ABI/FFI Documentation - -## Overview - -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 - -## Architecture - -``` -┌─────────────────────────────────────────────┐ -│ ABI Definitions (Idris2) │ -│ src/abi/ │ -│ - Types.idr (Type definitions) │ -│ - Layout.idr (Memory layout proofs) │ -│ - Foreign.idr (FFI declarations) │ -└─────────────────┬───────────────────────────┘ - │ - │ generates (at compile time) - ▼ -┌─────────────────────────────────────────────┐ -│ C Headers (auto-generated) │ -│ generated/abi/{{project}}.h │ -└─────────────────┬───────────────────────────┘ - │ - │ imported by - ▼ -┌─────────────────────────────────────────────┐ -│ FFI Implementation (Zig) │ -│ ffi/zig/src/main.zig │ -│ - Implements C-compatible functions │ -│ - Zero-cost abstractions │ -│ - Memory-safe by default │ -└─────────────────┬───────────────────────────┘ - │ - │ compiled to lib{{project}}.so/.a - ▼ -┌─────────────────────────────────────────────┐ -│ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ -└─────────────────────────────────────────────┘ -``` - -## Directory Structure - -``` -{{project}}/ -├── src/ -│ ├── abi/ # ABI definitions (Idris2) -│ │ ├── Types.idr # Core type definitions with proofs -│ │ ├── Layout.idr # Memory layout verification -│ │ └── Foreign.idr # FFI function declarations -│ └── lib/ # Core library (any language) -│ -├── ffi/ -│ └── zig/ # FFI implementation (Zig) -│ ├── build.zig # Build configuration -│ ├── build.zig.zon # Dependencies -│ ├── src/ -│ │ └── main.zig # C-compatible FFI implementation -│ ├── test/ -│ │ └── integration_test.zig -│ └── include/ -│ └── {{project}}.h # C header (optional, can be generated) -│ -├── generated/ # Auto-generated files -│ └── abi/ -│ └── {{project}}.h # Generated from Idris2 ABI -│ -└── bindings/ # Language-specific wrappers (optional) - ├── rust/ - ├── rescript/ - └── julia/ -``` - -## Why Idris2 for ABI? - -### 1. **Formal Verification** - -Idris2's dependent types allow proving properties about the ABI at compile-time: - -```idris --- Prove struct size is correct -public export -exampleStructSize : HasSize ExampleStruct 16 - --- Prove field alignment is correct -public export -fieldAligned : Divides 8 (offsetOf ExampleStruct.field) - --- Prove ABI is platform-compatible -public export -abiCompatible : Compatible (ABI 1) (ABI 2) -``` - -### 2. **Type Safety** - -Encode invariants that C/Zig cannot express: - -```idris --- Non-null pointer guaranteed at type level -data Handle : Type where - MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle - --- Array with length proof -data Buffer : (n : Nat) -> Type where - MkBuffer : Vect n Byte -> Buffer n -``` - -### 3. **Platform Abstraction** - -Platform-specific types with compile-time selection: - -```idris -CInt : Platform -> Type -CInt Linux = Bits32 -CInt Windows = Bits32 - -CSize : Platform -> Type -CSize Linux = Bits64 -CSize Windows = Bits64 -``` - -### 4. **Safe Evolution** - -Prove that new ABI versions are backward-compatible: - -```idris --- Compiler enforces compatibility -abiUpgrade : ABI 1 -> ABI 2 -abiUpgrade old = MkABI2 { - -- Must preserve all v1 fields - v1_compat = old, - -- Can add new fields - new_features = defaults -} -``` - -## Why Zig for FFI? - -### 1. **C ABI Compatibility** - -Zig exports C-compatible functions naturally: - -```zig -export fn library_function(param: i32) i32 { - return param * 2; -} -``` - -### 2. **Memory Safety** - -Compile-time safety without runtime overhead: - -```zig -// Null check enforced at compile time -const handle = init() orelse return error.InitFailed; -defer free(handle); -``` - -### 3. **Cross-Compilation** - -Built-in cross-compilation to any platform: - -```bash -zig build -Dtarget=x86_64-linux -zig build -Dtarget=aarch64-macos -zig build -Dtarget=x86_64-windows -``` - -### 4. **Zero Dependencies** - -No runtime, no libc required (unless explicitly needed): - -```zig -// Minimal binary size -pub const lib = @import("std"); -// Only includes what you use -``` - -## Building - -### Build FFI Library - -```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 - -```bash -cd src/abi -idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` - -### Cross-Compile - -```bash -cd ffi/zig - -# Linux x86_64 -zig build -Dtarget=x86_64-linux - -# macOS ARM64 -zig build -Dtarget=aarch64-macos - -# Windows x86_64 -zig build -Dtarget=x86_64-windows -``` - -## Usage - -### From C - -```c -#include "{{project}}.h" - -int main() { - void* handle = {{project}}_init(); - if (!handle) return 1; - - int result = {{project}}_process(handle, 42); - if (result != 0) { - const char* err = {{project}}_last_error(); - fprintf(stderr, "Error: %s\n", err); - } - - {{project}}_free(handle); - return 0; -} -``` - -Compile with: -```bash -gcc -o example example.c -l{{project}} -L./zig-out/lib -``` - -### From Idris2 - -```idris -import ada-loom-registry.ABI.Foreign - -main : IO () -main = do - Just handle <- init - | Nothing => putStrLn "Failed to initialize" - - Right result <- process handle 42 - | Left err => putStrLn $ "Error: " ++ errorDescription err - - free handle - putStrLn "Success" -``` - -### From Rust - -```rust -#[link(name = "{{project}}")] -extern "C" { - fn {{project}}_init() -> *mut std::ffi::c_void; - fn {{project}}_free(handle: *mut std::ffi::c_void); - fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; -} - -fn main() { - unsafe { - let handle = {{project}}_init(); - assert!(!handle.is_null()); - - let result = {{project}}_process(handle, 42); - assert_eq!(result, 0); - - {{project}}_free(handle); - } -} -``` - -### From Julia - -```julia -const lib{{project}} = "lib{{project}}" - -function init() - handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) - handle == C_NULL && error("Failed to initialize") - handle -end - -function process(handle, input) - result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) - result -end - -function cleanup(handle) - ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) -end - -# Usage -handle = init() -try - result = process(handle, 42) - println("Result: $result") -finally - cleanup(handle) -end -``` - -## Testing - -### Unit Tests (Zig) - -```bash -cd ffi/zig -zig build test -``` - -### Integration Tests - -```bash -cd ffi/zig -zig build test-integration -``` - -### ABI Verification (Idris2) - -```idris --- Compile-time verification -%runElab verifyABI - --- Runtime checks -main : IO () -main = do - verifyLayoutsCorrect - verifyAlignmentsCorrect - putStrLn "ABI verification passed" -``` - -## 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 - -PMPL-1.0-or-later - -## 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) diff --git a/ada-ecosystem/ada-loom-registry/CHANGELOG.adoc b/ada-ecosystem/ada-loom-registry/CHANGELOG.adoc index 234c1b8b5..d627efbe3 100644 --- a/ada-ecosystem/ada-loom-registry/CHANGELOG.adoc +++ b/ada-ecosystem/ada-loom-registry/CHANGELOG.adoc @@ -1,28 +1,33 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Changelog +== Changelog -All notable changes to Spindle (Nickel Configuration Parser) will be documented in this file. +All notable changes to Spindle (Nickel Configuration Parser) 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). +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] +=== [Unreleased] -=== Planned -- Enhanced error reporting -- Additional configuration validation -- Support for more complex Nickel structures +==== Planned -== [0.1.0] - 2024-11-20 +* Enhanced error reporting +* Additional configuration validation +* Support for more complex Nickel structures -=== Added -- Initial Haskell project structure -- Nickel file parser using hnickel library -- JSON conversion via Aeson -- Basic Config type definition -- Comprehensive README documentation -- Dual PMPL-1.0 + Palimpsest licensing -- Cabal build configuration +=== [0.1.0] - 2024-11-20 -=== Note -- Project directory renamed from misleading `ada-loom-registry` to reflect actual Haskell/Nickel parser purpose +==== Added + +* Initial Haskell project structure +* Nickel file parser using hnickel library +* JSON conversion via Aeson +* Basic Config type definition +* Comprehensive README documentation +* Dual MIT + Palimpsest licensing +* Cabal build configuration + +==== Note + +* Project directory renamed from misleading `+ada-loom-registry+` to +reflect actual Haskell/Nickel parser purpose diff --git a/ada-ecosystem/ada-loom-registry/CHANGELOG.md b/ada-ecosystem/ada-loom-registry/CHANGELOG.md deleted file mode 100644 index ba027aabd..000000000 --- a/ada-ecosystem/ada-loom-registry/CHANGELOG.md +++ /dev/null @@ -1,27 +0,0 @@ -# Changelog - -All notable changes to Spindle (Nickel Configuration Parser) 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 -- Enhanced error reporting -- Additional configuration validation -- Support for more complex Nickel structures - -## [0.1.0] - 2024-11-20 - -### Added -- Initial Haskell project structure -- Nickel file parser using hnickel library -- JSON conversion via Aeson -- Basic Config type definition -- Comprehensive README documentation -- Dual MIT + Palimpsest licensing -- Cabal build configuration - -### Note -- Project directory renamed from misleading `ada-loom-registry` to reflect actual Haskell/Nickel parser purpose diff --git a/ada-ecosystem/ada-loom-registry/CODE_OF_CONDUCT.adoc b/ada-ecosystem/ada-loom-registry/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..bd2a83cb8 --- /dev/null +++ b/ada-ecosystem/ada-loom-registry/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/ada-ecosystem/ada-loom-registry/CODE_OF_CONDUCT.md b/ada-ecosystem/ada-loom-registry/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c6d..000000000 --- a/ada-ecosystem/ada-loom-registry/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/ada-ecosystem/ada-loom-registry/CONTRIBUTING.adoc b/ada-ecosystem/ada-loom-registry/CONTRIBUTING.adoc index 529b766f3..c9bf5d4fd 100644 --- a/ada-ecosystem/ada-loom-registry/CONTRIBUTING.adoc +++ b/ada-ecosystem/ada-loom-registry/CONTRIBUTING.adoc @@ -1,367 +1,109 @@ -= Contributing to ada-loom-registry -:toc: macro +== Clone the repository -[abstract] --- -Contribution guidelines for ada-loom-registry. Rhodium Standard 0.5, Pillar 4, Section 4.1. --- +git clone https://github.com/hyperpolymath/developer-ecosystem.git cd +developer-ecosystem -toc::[] +== Using Nix (recommended for reproducibility) -== Welcome +nix develop -Thank you for considering contributing to ada-loom-registry! This package registry welcomes contributions to code, registry entries, and documentation. +== Or using toolbox/distrobox -== Code of Conduct +toolbox create developer-ecosystem-dev toolbox enter +developer-ecosystem-dev # Install dependencies manually -* Be respectful and professional -* Welcome newcomers -* Focus on constructive feedback -* Assume good intentions -* **Respect registry integrity** +== Verify setup -**Enforcement:** conduct@example.com +just check # or: cargo check / mix compile / etc. just test # Run test +suite -== Quick Start +.... -=== Contributing Code +### Repository Structure +.... -[source,bash] ----- -# 1. Fork and clone -git clone https://github.com/YOUR_USERNAME/ada-loom-registry.git -cd ada-loom-registry +developer-ecosystem/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # +Library code (Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) +├── plugins/ # Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter 2) +├── docs/ # Documentation (Perimeter 3) │ ├── architecture/ # ADRs, +specs (Perimeter 2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ +# Examples (Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ +# Test suite (Perimeter 2-3) ├── .well-known/ # Protocol files +(Perimeter 1-3) ├── .github/ # GitHub config (Perimeter 1) │ ├── +ISSUE_TEMPLATE/ │ └── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── LICENSE ├── +MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.nix # Nix flake +(Perimeter 1) └── Justfile # Task runner (Perimeter 1) -# 2. Install dependencies -cabal update -cabal build --only-dependencies +.... -# 3. Build -cabal build - -# 4. Run tests -cabal test - -# 5. Create PR -git checkout -b feature/your-feature -git commit -m "feat: description" -git push origin feature/your-feature ----- - -=== Contributing Packages - -[source,bash] ----- -# 1. Prepare package -just package-prepare my-package-1.0.0 - -# 2. Validate entry -just registry-validate-entry my-package-1.0.0 - -# 3. Submit to staging -just registry-publish-staging my-package-1.0.0 - -# 4. Test from staging -just registry-query my-package - -# 5. Submit PR for mainnet -# Include: package validation output, testing evidence ----- - -== Development Setup - -See link:ONBOARDING.adoc[ONBOARDING.adoc] for detailed setup. - -**Required:** -* GHC 9.6.3+ -* Cabal 3.10+ -* Nickel 1.x -* Git +--- -== Code Style +## How to Contribute -**Haskell formatting:** -[source,bash] ----- -ormolu --mode inplace src/**/*.hs ----- +### Reporting Bugs -**Key conventions:** -* Type signatures required -* Newtypes for domain types -* Pure functions preferred -* Clear naming +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects -**Example:** -[source,haskell] ----- -{-# LANGUAGE OverloadedStrings #-} +**When reporting**: -module Registry.Package where +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: -import Crypto.Hash (SHA256, Digest) -import qualified Data.Text as T +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction -newtype PackageName = PackageName T.Text -newtype PackageVersion = PackageVersion T.Text -newtype PackageHash = PackageHash (Digest SHA256) +### Suggesting Features -data PackageEntry = PackageEntry - { packageName :: PackageName - , packageVersion :: PackageVersion - , packageHash :: PackageHash - , packageMetadata :: Metadata - } +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to --- | Validate package entry -validateEntry :: PackageEntry -> Either ValidationError () -validateEntry entry = do - validateName (packageName entry) - validateVersion (packageVersion entry) - validateHash (packageHash entry) ----- +**When suggesting**: -== Package Submission Guidelines +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: -**Before submitting:** -* [ ] Package builds successfully -* [ ] Tests pass -* [ ] Documentation complete -* [ ] License declared (SPDX identifier) -* [ ] No known security vulnerabilities -* [ ] Version follows semver -* [ ] Package name available (not reserved) +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects -**Reserved names:** -* `ada`, `core`, `std`, `system`, `internal` +### Your First Contribution -**Package naming:** -* Lowercase -* Hyphens allowed -* 3-64 characters -* Alphanumeric + hyphens only +Look for issues labelled: -== Security +- [`good first issue`](https://github.com/hyperpolymath/developer-ecosystem/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/developer-ecosystem/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/developer-ecosystem/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/developer-ecosystem/labels/perimeter-3) — Community sandbox scope -**Critical: Registry is a trusted source.** +--- -**Report security issues:** -See link:SECURITY.adoc[SECURITY.adoc] for reporting process. +## Development Workflow -**⚠️ NEVER submit malicious packages.** +### Branch Naming +.... -**Registry security:** -* All packages cryptographically signed -* Hash verification automatic -* Namespace protection enforced -* Rate limiting on submissions -* Content scanning for malicious patterns +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) -== Testing Requirements - -**Coverage:** 80%+ +.... -**Test structure:** -[source,haskell] ----- --- test/Registry/PackageSpec.hs -module Registry.PackageSpec where +### Commit Messages -import Test.Hspec -import Registry.Package - -spec :: Spec -spec = do - describe "validateEntry" $ do - it "accepts valid package entry" $ do - let entry = PackageEntry {...} - validateEntry entry `shouldBe` Right () - - it "rejects reserved package name" $ do - let entry = PackageEntry { packageName = PackageName "core", ... } - validateEntry entry `shouldSatisfy` isLeft ----- - -**Registry integrity tests:** -[source,bash] ----- -# Validate entire registry -just registry-validate - -# Check for malicious patterns -just scan-registry - -# Verify all signatures -just verify-signatures ----- - -== Nickel Schema Guidelines - -**Registry entry schema:** -[source,nickel] ----- -{ - # Required fields - name | String - | doc "Package name (lowercase, hyphens)", - - version | String - | doc "Semver version (e.g., 1.0.0)", - - description | String - | doc "Brief package description", - - license | String - | doc "SPDX license identifier", - - # Optional fields - homepage | String | optional - | doc "Project homepage URL", - - repository | String | optional - | doc "Source repository URL", - - dependencies | Array String | default = [] - | doc "Package dependencies", -} ----- - -**Schema validation:** -[source,bash] ----- -nickel typecheck schemas/registry.ncl ----- - -== Commit Messages - -**Conventional Commits:** -``` -: - - - -