From bfb6830eac4220c004e82f4ac870b109aec40c57 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:30:58 +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 | 30 ++++++++++ TEST-NEEDS.md | 27 --------- TOPOLOGY.md => TOPOLOGY.adoc | 107 +++++++++++++++++++++-------------- llm-warmup-dev.adoc | 19 +++++++ llm-warmup-dev.md | 16 ------ llm-warmup-user.adoc | 19 +++++++ llm-warmup-user.md | 16 ------ 12 files changed, 240 insertions(+), 203 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 (54%) 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 7d146fc..3d21388 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 nimiser CLI tool and its generated artifacts. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..01b6d3b --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,30 @@ +== TEST-NEEDS.md — nimiser + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[cols=",,",options="header",] +|=== +|Category |Count |Notes +|Test files |2 |Current state +|=== + +=== What’s Covered + +* [x] 2 existing test file(s) +* [x] Rust integration tests + +=== Still Missing (for CRG B+) + +* [ ] Zig FFI tests (if applicable) +* [ ] CI/CD test automation +* [ ] Property-based tests +* [ ] Edge case coverage + +=== Run Tests + +[source,bash] +---- +cargo test --all +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index ad1d40e..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,27 +0,0 @@ -# TEST-NEEDS.md — nimiser - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Test files | 2 | Current state | - -## What's Covered - -- [x] 2 existing test file(s) -- [x] Rust integration tests - -## Still Missing (for CRG B+) - -- [ ] Zig FFI tests (if applicable) -- [ ] CI/CD test automation -- [ ] Property-based tests -- [ ] Edge case coverage - -## Run Tests - -```bash -cargo test --all -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 54% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index e653fe5..64c2843 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,10 +1,8 @@ - - -# Nimiser — Module Topology +== Nimiser — Module Topology -## Dependency Graph +=== Dependency Graph -``` +.... nimiser.toml (user manifest) │ ▼ @@ -52,40 +50,65 @@ nimiser.toml (user manifest) │ Zig FFI Bridge │ │ (nimiser_* fns) │ └──────────────────┘ -``` - -## Module Map - -| Module | Path | Purpose | -|--------|------|---------| -| CLI | `src/main.rs` | Clap-based CLI with 6 subcommands | -| Library | `src/lib.rs` | Public API for programmatic use | -| Manifest | `src/manifest/mod.rs` | Parse and validate `nimiser.toml` | -| Codegen | `src/codegen/mod.rs` | Generate Nim templates, macros, generics | -| ABI (Rust) | `src/abi/mod.rs` | Rust-side ABI types mirroring Idris2 | -| ABI (Idris2) | `src/interface/abi/Types.idr` | Formal type definitions: NimTemplate, NimMacro, CompileTimeAST, CBackend, NimObject | -| Layout (Idris2) | `src/interface/abi/Layout.idr` | Memory layout proofs for Nim objects exported as C structs | -| Foreign (Idris2) | `src/interface/abi/Foreign.idr` | FFI declarations: nimiser_init, nimiser_compile, nimiser_gen_template, etc. | -| FFI (Zig) | `src/interface/ffi/src/main.zig` | C-ABI implementation of nimiser_* functions | -| FFI Build | `src/interface/ffi/build.zig` | Zig build system for shared/static library | -| FFI Tests | `src/interface/ffi/test/integration_test.zig` | Integration tests verifying Zig FFI matches Idris2 ABI | - -## Data Flow - -1. **User** writes `nimiser.toml` describing library interface (types, functions, strategies) -2. **Manifest parser** (`src/manifest/`) validates and produces a `Manifest` struct -3. **Codegen** (`src/codegen/`) generates Nim source files: - - Templates for zero-cost generic abstractions - - Macros for AST-level compile-time transforms - - Generics for monomorphised type specialisation -4. **Nim compiler** (`nim c --app:lib --gc:arc`) compiles generated Nim to optimised C -5. **C library** (`.a`/`.so` + `.h`) is the primary output artefact -6. **Zig FFI** (`src/interface/ffi/`) provides a stable bridge for consumers -7. **Idris2 ABI** (`src/interface/abi/`) proves the C ABI is correct at compile time - -## Verification Seam - -``` +.... + +=== Module Map + +[width="100%",cols="35%,26%,39%",options="header",] +|=== +|Module |Path |Purpose +|CLI |`+src/main.rs+` |Clap-based CLI with 6 subcommands + +|Library |`+src/lib.rs+` |Public API for programmatic use + +|Manifest |`+src/manifest/mod.rs+` |Parse and validate `+nimiser.toml+` + +|Codegen |`+src/codegen/mod.rs+` |Generate Nim templates, macros, +generics + +|ABI (Rust) |`+src/abi/mod.rs+` |Rust-side ABI types mirroring Idris2 + +|ABI (Idris2) |`+src/interface/abi/Types.idr+` |Formal type definitions: +NimTemplate, NimMacro, CompileTimeAST, CBackend, NimObject + +|Layout (Idris2) |`+src/interface/abi/Layout.idr+` |Memory layout proofs +for Nim objects exported as C structs + +|Foreign (Idris2) |`+src/interface/abi/Foreign.idr+` |FFI declarations: +nimiser_init, nimiser_compile, nimiser_gen_template, etc. + +|FFI (Zig) |`+src/interface/ffi/src/main.zig+` |C-ABI implementation of +nimiser_* functions + +|FFI Build |`+src/interface/ffi/build.zig+` |Zig build system for +shared/static library + +|FFI Tests |`+src/interface/ffi/test/integration_test.zig+` |Integration +tests verifying Zig FFI matches Idris2 ABI +|=== + +=== Data Flow + +[arabic] +. *User* writes `+nimiser.toml+` describing library interface (types, +functions, strategies) +. *Manifest parser* (`+src/manifest/+`) validates and produces a +`+Manifest+` struct +. *Codegen* (`+src/codegen/+`) generates Nim source files: +* Templates for zero-cost generic abstractions +* Macros for AST-level compile-time transforms +* Generics for monomorphised type specialisation +. *Nim compiler* (`+nim c --app:lib --gc:arc+`) compiles generated Nim +to optimised C +. *C library* (`+.a+`/`+.so+` + `+.h+`) is the primary output artefact +. *Zig FFI* (`+src/interface/ffi/+`) provides a stable bridge for +consumers +. *Idris2 ABI* (`+src/interface/abi/+`) proves the C ABI is correct at +compile time + +=== Verification Seam + +.... Idris2 ABI Proofs ──────────── Zig FFI Implementation Types.idr (NimTemplate, main.zig (nimiser_init, NimMacro, CBackend) nimiser_compile, etc.) @@ -93,7 +116,7 @@ Idris2 ABI Proofs ──────────── Zig FFI Implementation struct layout proofs) Foreign.idr (FFI integration_test.zig function signatures) (verify ABI compliance) -``` +.... -The Idris2 ABI is the **specification**. The Zig FFI is the **implementation**. -Integration tests verify they agree. +The Idris2 ABI is the *specification*. The Zig FFI is the +*implementation*. Integration tests verify they agree. diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..96fded0 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — nimiser (Developer) + +=== What is nimiser? + +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 4793746..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — nimiser (Developer) - -## What is nimiser? -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..7ad0518 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — nimiser (User) + +=== What is nimiser? + +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 23b7265..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — nimiser (User) - -## What is nimiser? -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