From 39f6c21e5b5fb0b929696268d322276f871a5ad6 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:32:42 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- CODE_OF_CONDUCT.adoc | 24 +++++++ CODE_OF_CONDUCT.md | 27 ------- CONTRIBUTING.adoc | 71 +++++++++++++++++++ CONTRIBUTING.md | 66 ----------------- SECURITY.md => SECURITY.adoc | 21 +++--- TEST-NEEDS.adoc | 37 ++++++++++ TEST-NEEDS.md | 30 -------- TOPOLOGY.md => TOPOLOGY.adoc | 26 ++++--- .../{TOPOLOGY.md => TOPOLOGY.adoc} | 62 +++++++++------- llm-warmup-dev.adoc | 19 +++++ llm-warmup-dev.md | 16 ----- llm-warmup-user.adoc | 19 +++++ llm-warmup-user.md | 16 ----- 13 files changed, 234 insertions(+), 200 deletions(-) create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md rename SECURITY.md => SECURITY.adoc (57%) create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md rename TOPOLOGY.md => TOPOLOGY.adoc (71%) rename docs/architecture/{TOPOLOGY.md => TOPOLOGY.adoc} (83%) create mode 100644 llm-warmup-dev.adoc delete mode 100644 llm-warmup-dev.md create mode 100644 llm-warmup-user.adoc delete mode 100644 llm-warmup-user.md diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /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 caeda1c..0000000 --- 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 0000000..858f44f --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,71 @@ +== Contributing + +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+nix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 80ecdac..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,66 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `nix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). diff --git a/SECURITY.md b/SECURITY.adoc similarity index 57% rename from SECURITY.md rename to SECURITY.adoc index 3e438ed..51a04f4 100644 --- a/SECURITY.md +++ b/SECURITY.adoc @@ -1,21 +1,24 @@ -# Security Policy +== Security Policy -## Supported Versions +=== Supported Versions -| Version | Supported | -|---------|-----------| -| 0.1.x | ✅ | +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |✅ +|=== -## Reporting a Vulnerability +=== Reporting a Vulnerability Please report security vulnerabilities to: j.d.a.jewell@open.ac.uk Do NOT open a public issue for security vulnerabilities. -## Response Time +=== Response Time -We aim to respond within 48 hours and provide a fix within 7 days for critical issues. +We aim to respond within 48 hours and provide a fix within 7 days for +critical issues. -## Scope +=== Scope This policy covers the otpiser CLI tool and its generated artifacts. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..2d52fc5 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,37 @@ +== TEST-NEEDS.md — otpiser + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[width="100%",cols="42%,29%,29%",options="header",] +|=== +|Category |Count |Notes +|Integration tests (Rust) |2 |`+tests/integration_test.rs+` compiled +binaries + +|Verification tests |Unit-level |`+verification/tests/+` directory +present + +|FFI tests |Present |`+src/interface/ffi/test/+` +|=== + +=== What’s Covered + +* [x] Dual integration test builds (debug + release) +* [x] FFI verification layer +* [x] Cargo test harness + +=== Still Missing (for CRG B+) + +* [ ] Property-based testing (proptest) +* [ ] Fuzzing targets +* [ ] Benchmarking suite +* [ ] CI integration tests + +=== Run Tests + +[source,bash] +---- +cd /var/mnt/eclipse/repos/otpiser && cargo test +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 425bcb6..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,30 +0,0 @@ -# TEST-NEEDS.md — otpiser - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Integration tests (Rust) | 2 | `tests/integration_test.rs` compiled binaries | -| Verification tests | Unit-level | `verification/tests/` directory present | -| FFI tests | Present | `src/interface/ffi/test/` | - -## What's Covered - -- [x] Dual integration test builds (debug + release) -- [x] FFI verification layer -- [x] Cargo test harness - -## Still Missing (for CRG B+) - -- [ ] Property-based testing (proptest) -- [ ] Fuzzing targets -- [ ] Benchmarking suite -- [ ] CI integration tests - -## Run Tests - -```bash -cd /var/mnt/eclipse/repos/otpiser && cargo test -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 71% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index b08d65d..88605f2 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,14 +1,18 @@ - - -# TOPOLOGY.md — otpiser +== TOPOLOGY.md — otpiser -## Purpose +=== Purpose -otpiser generates fault-tolerant OTP supervision trees for Erlang/Elixir systems. It reads a service topology description from an `otpiser.toml` manifest and emits Erlang/Elixir modules with correctly structured supervisor trees, child specifications, restart strategies, and Zig FFI bridges for native integration. otpiser targets engineers who want the reliability guarantees of the OTP supervision model without hand-authoring the boilerplate of nested supervisors and child specs. +otpiser generates fault-tolerant OTP supervision trees for Erlang/Elixir +systems. It reads a service topology description from an +`+otpiser.toml+` manifest and emits Erlang/Elixir modules with correctly +structured supervisor trees, child specifications, restart strategies, +and Zig FFI bridges for native integration. otpiser targets engineers +who want the reliability guarantees of the OTP supervision model without +hand-authoring the boilerplate of nested supervisors and child specs. -## Module Map +=== Module Map -``` +.... otpiser/ ├── src/ │ ├── main.rs # CLI entry point (clap): init, validate, generate, build, run, info @@ -20,11 +24,11 @@ otpiser/ ├── verification/ # Proof harnesses ├── container/ # Stapeln container ecosystem └── .machine_readable/ # A2ML metadata -``` +.... -## Data Flow +=== Data Flow -``` +.... otpiser.toml manifest │ ┌────▼────┐ @@ -43,4 +47,4 @@ otpiser.toml manifest ┌────▼────┐ │ OTP VM │ run fault-tolerant supervision hierarchy on BEAM └─────────┘ -``` +.... diff --git a/docs/architecture/TOPOLOGY.md b/docs/architecture/TOPOLOGY.adoc similarity index 83% rename from docs/architecture/TOPOLOGY.md rename to docs/architecture/TOPOLOGY.adoc index 3c64676..0919e07 100644 --- a/docs/architecture/TOPOLOGY.md +++ b/docs/architecture/TOPOLOGY.adoc @@ -1,10 +1,8 @@ - - -# otpiser — TOPOLOGY +== otpiser — TOPOLOGY -## Module Map +=== Module Map -``` +.... otpiser/ ├── src/ │ ├── main.rs # CLI entry point (clap subcommands) @@ -48,11 +46,11 @@ otpiser/ │ ├── attribution/ # Citations, maintainers │ └── legal/ # License exhibits └── .machine_readable/ # All machine-readable metadata (6a2, policies, etc.) -``` +.... -## Data Flow +=== Data Flow -``` +.... otpiser.toml (user manifest) │ ▼ @@ -87,13 +85,13 @@ otpiser.toml (user manifest) ├──► config/config.exs (Application config) ├──► mix.exs (Project definition) └──► test/**/*_test.exs (ExUnit test scaffolding) -``` +.... -## Supervision Tree Model +=== Supervision Tree Model OTPiser generates trees following this hierarchy: -``` +.... Application └── RootSupervisor (strategy from manifest) ├── ServiceGroupSupervisor_A (one_for_all — tightly coupled) @@ -108,21 +106,35 @@ Application │ └── (workers spawned on demand) ├── Task.Supervisor: AsyncJobs └── GenServer: HealthMonitor -``` +.... -## Key Interfaces +=== Key Interfaces -| Interface | Location | Purpose | -|-----------|----------|---------| -| CLI → Manifest | `main.rs` → `manifest/mod.rs` | Parse `otpiser.toml` | -| Manifest → Codegen | `manifest::Manifest` struct | Validated service description | -| Codegen → Elixir | `codegen/mod.rs` → templates | Generate `.ex` files | -| Idris2 ABI → Zig FFI | `Types.idr` → `main.zig` | Verified type bridge | -| Zig FFI → BEAM NIF | `main.zig` → Erlang NIF API | Performance-critical paths | +[width="100%",cols="37%,33%,30%",options="header",] +|=== +|Interface |Location |Purpose +|CLI → Manifest |`+main.rs+` → `+manifest/mod.rs+` |Parse +`+otpiser.toml+` -## Cross-iser Integration Points +|Manifest → Codegen |`+manifest::Manifest+` struct |Validated service +description -- **iseriser**: Can scaffold new otpiser-style projects -- **chapeliser**: Distributed computing — otpiser supervises Chapel workers -- **verisimiser**: Database layer — otpiser supervises VeriSimDB connections -- **Burble**: Voice platform — otpiser generates supervision trees for call handling +|Codegen → Elixir |`+codegen/mod.rs+` → templates |Generate `+.ex+` +files + +|Idris2 ABI → Zig FFI |`+Types.idr+` → `+main.zig+` |Verified type +bridge + +|Zig FFI → BEAM NIF |`+main.zig+` → Erlang NIF API |Performance-critical +paths +|=== + +=== Cross-iser Integration Points + +* *iseriser*: Can scaffold new otpiser-style projects +* *chapeliser*: Distributed computing — otpiser supervises Chapel +workers +* *verisimiser*: Database layer — otpiser supervises VeriSimDB +connections +* *Burble*: Voice platform — otpiser generates supervision trees for +call handling diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..d27ce46 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — otpiser (Developer) + +=== What is otpiser? + +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 f1eff7d..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — otpiser (Developer) - -## What is otpiser? -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..b824d5d --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — otpiser (User) + +=== What is otpiser? + +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 7a3d649..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — otpiser (User) - -## What is otpiser? -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