From 7fce353ac51e2cded5ae002d949fc6a029abb964 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:23:02 +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 | 90 +++++++++++++++++++----------------- llm-warmup-dev.adoc | 19 ++++++++ llm-warmup-dev.md | 16 ------- llm-warmup-user.adoc | 19 ++++++++ llm-warmup-user.md | 16 ------- 12 files changed, 223 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 (58%) create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md rename TOPOLOGY.md => TOPOLOGY.adoc (69%) 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 58% rename from SECURITY.md rename to SECURITY.adoc index 61a179d..10bbc16 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 julianiser CLI tool and its generated artifacts. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..f4cbb2d --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,30 @@ +== TEST-NEEDS.md — julianiser + +=== 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 4ff8e64..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,27 +0,0 @@ -# TEST-NEEDS.md — julianiser - -## 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 69% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 6629c55..b4e88d7 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,26 +1,28 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Julianiser — Repository Topology +== SPDX-License-Identifier: CC-BY-SA-4.0 -## Purpose +== Julianiser — Repository Topology + +=== Purpose Julianiser analyses Python and R data science code, identifies known -pandas/numpy/scipy/dplyr/ggplot2-style calls, and generates equivalent Julia -modules via the Rust codegen pipeline (`src/codegen/`). Julia's LLVM JIT is -well-documented to deliver large speedups on this class of workload; julianiser -generates benchmark scaffolding so users can measure that for their own -pipeline, but does not itself measure or claim a speedup number today. +pandas/numpy/scipy/dplyr/ggplot2-style calls, and generates equivalent +Julia modules via the Rust codegen pipeline (`+src/codegen/+`). Julia’s +LLVM JIT is well-documented to deliver large speedups on this class of +workload; julianiser generates benchmark scaffolding so users can +measure that for their own pipeline, but does not itself measure or +claim a speedup number today. -**Honesty note (see README.md for full detail):** the Idris2 ABI -(`src/interface/abi/`) and Zig FFI (`src/interface/ffi/`) below are +*Honesty note (see README.md for full detail):* the Idris2 ABI +(`+src/interface/abi/+`) and Zig FFI (`+src/interface/ffi/+`) below are scaffolding — source files exist, but the Zig implementation is TODO-stubbed and the Rust CLI never links or calls into it. The operational translation pipeline today is the Rust codegen -(`src/codegen/parser.rs` + `src/codegen/julia_gen.rs`), invoked directly -by `src/main.rs`. +(`+src/codegen/parser.rs+` + `+src/codegen/julia_gen.rs+`), invoked +directly by `+src/main.rs+`. -## Module Map +=== Module Map -``` +.... julianiser/ ├── src/ # Rust CLI + orchestration │ ├── main.rs # CLI entry point (init, validate, generate, build, run, info) @@ -56,11 +58,11 @@ julianiser/ ├── policies/ # Maintenance axes and checklists ├── contractiles/ # k9, must, trust, dust, lust └── integrations/ # proven, verisimdb, vexometer, feedback-o-tron -``` +.... -## Data Flow (operational today) +=== Data Flow (operational today) -``` +.... julianiser.toml ──→ Manifest Parser ──→ Source Parser (line-based Python/R scan) (src/manifest/) (src/codegen/parser.rs) │ @@ -77,34 +79,38 @@ julianiser.toml ──→ Manifest Parser ──→ Source Parser (line-based Py Benchmark scaffold generator (src/codegen/benchmark.rs — emits scripts for the user to run and record timings) -``` +.... -## Data Flow (planned, not yet wired) +=== Data Flow (planned, not yet wired) -The Idris2 ABI (`src/interface/abi/`) and Zig FFI (`src/interface/ffi/`) -are intended to eventually sit between source parsing and Julia codegen -as a formally-verified, compiled bridge. Today they are source-only -scaffolding: the Idris2 proofs are not built or checked by `cargo -build`/`cargo test`, and the Zig implementation's exported functions -are TODO stubs that the Rust CLI never calls. +The Idris2 ABI (`+src/interface/abi/+`) and Zig FFI +(`+src/interface/ffi/+`) are intended to eventually sit between source +parsing and Julia codegen as a formally-verified, compiled bridge. Today +they are source-only scaffolding: the Idris2 proofs are not built or +checked by `+cargo build+`/`+cargo test+`, and the Zig implementation’s +exported functions are TODO stubs that the Rust CLI never calls. -## Key Dependencies +=== Key Dependencies -| Dependency | Purpose | -|------------|---------| -| `clap` | CLI argument parsing | -| `serde` + `toml` | Manifest deserialization | -| `anyhow` + `thiserror` | Error handling | -| `handlebars` | Template-based Julia code generation | -| `walkdir` | Source file discovery | +[cols=",",options="header",] +|=== +|Dependency |Purpose +|`+clap+` |CLI argument parsing +|`+serde+` + `+toml+` |Manifest deserialization +|`+anyhow+` + `+thiserror+` |Error handling +|`+handlebars+` |Template-based Julia code generation +|`+walkdir+` |Source file discovery +|=== -## Integration Points +=== Integration Points -| System | Role | -|--------|------| -| **iseriser** | Meta-framework that can scaffold new -iser projects | -| **proven** | Shared Idris2 verified library for formal proofs | -| **typell** | Type theory engine used by ABI layer | -| **PanLL** | Panel integration for interactive workflows | -| **BoJ-server** | Cartridge for remote julianiser execution | -| **VeriSimDB** | Storage for benchmark results and regression tracking | +[width="100%",cols="58%,42%",options="header",] +|=== +|System |Role +|*iseriser* |Meta-framework that can scaffold new -iser projects +|*proven* |Shared Idris2 verified library for formal proofs +|*typell* |Type theory engine used by ABI layer +|*PanLL* |Panel integration for interactive workflows +|*BoJ-server* |Cartridge for remote julianiser execution +|*VeriSimDB* |Storage for benchmark results and regression tracking +|=== diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..63d2aba --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — julianiser (Developer) + +=== What is julianiser? + +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 968ce96..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — julianiser (Developer) - -## What is julianiser? -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..5d1c970 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — julianiser (User) + +=== What is julianiser? + +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 cee32b4..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — julianiser (User) - -## What is julianiser? -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