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 7744fdc..cde9226 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 mylangiser CLI tool and its generated artifacts. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..dc3261a --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,30 @@ +== TEST-NEEDS.md — mylangiser + +=== 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 bce9286..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,27 +0,0 @@ -# TEST-NEEDS.md — mylangiser - -## 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 67% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index f267bb7..67d20e3 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,14 +1,19 @@ - - -# TOPOLOGY.md — mylangiser +== TOPOLOGY.md — mylangiser -## Purpose +=== Purpose -mylangiser generates progressive-disclosure interfaces for complex APIs via My-Lang. It analyses API complexity, scores each endpoint, and assigns disclosure levels (beginner / intermediate / expert), then generates layered wrapper code with smart defaults for omitted parameters. The goal is to make any API learnable by newcomers while remaining fully expressive for experts. mylangiser targets library and API authors who want to reduce the cognitive load on users without sacrificing power. +mylangiser generates progressive-disclosure interfaces for complex APIs +via My-Lang. It analyses API complexity, scores each endpoint, and +assigns disclosure levels (beginner / intermediate / expert), then +generates layered wrapper code with smart defaults for omitted +parameters. The goal is to make any API learnable by newcomers while +remaining fully expressive for experts. mylangiser targets library and +API authors who want to reduce the cognitive load on users without +sacrificing power. -## Module Map +=== Module Map -``` +.... mylangiser/ ├── src/ │ ├── main.rs # CLI entry point (clap): init, validate, generate, build, run, info @@ -20,11 +25,11 @@ mylangiser/ ├── verification/ # Proof harnesses ├── container/ # Stapeln container ecosystem └── .machine_readable/ # A2ML metadata -``` +.... -## Data Flow +=== Data Flow -``` +.... mylangiser.toml manifest │ ┌────▼────┐ @@ -39,4 +44,4 @@ mylangiser.toml manifest ┌────▼────┐ │ Codegen │ emit generated/mylangiser/ (layered wrappers with smart defaults) └─────────┘ -``` +.... diff --git a/docs/architecture/TOPOLOGY.md b/docs/architecture/TOPOLOGY.adoc similarity index 79% rename from docs/architecture/TOPOLOGY.md rename to docs/architecture/TOPOLOGY.adoc index 3bd3c2c..702d4e7 100644 --- a/docs/architecture/TOPOLOGY.md +++ b/docs/architecture/TOPOLOGY.adoc @@ -1,17 +1,15 @@ - - +== Mylangiser Topology -# Mylangiser Topology +=== Overview -## Overview +Mylangiser is a progressive-disclosure interface generator. It analyses +complex API surfaces, assigns cognitive-load complexity scores, and +generates layered wrappers at three disclosure levels (@beginner, +@intermediate, @expert). -Mylangiser is a progressive-disclosure interface generator. It analyses complex -API surfaces, assigns cognitive-load complexity scores, and generates layered -wrappers at three disclosure levels (@beginner, @intermediate, @expert). +=== Module Map -## Module Map - -``` +.... mylangiser/ ├── CLI Layer (Rust) │ ├── src/main.rs # Entry point: init, validate, generate, build, run, info @@ -44,11 +42,11 @@ mylangiser/ ├── .machine_readable/policies/ ├── .machine_readable/contractiles/ └── .machine_readable/bot_directives/ -``` +.... -## Data Flow +=== Data Flow -``` +.... mylangiser.toml │ ▼ @@ -100,36 +98,38 @@ mylangiser/ ▼ Layered Wrapper (drop-in library) -``` +.... -## Complexity Scoring Formula +=== Complexity Scoring Formula -``` +.... score = (required_params * 3) + (optional_params * 1) + (type_depth * 5) + (error_surface * 2) Clamped to [0, 100]. -``` +.... -Thresholds (configurable in mylangiser.toml): -- 0-33: @beginner -- 34-66: @intermediate -- 67-100: @expert +Thresholds (configurable in mylangiser.toml): - 0-33: @beginner - 34-66: +@intermediate - 67-100: @expert -## Layer Parameter Visibility +=== Layer Parameter Visibility -| Level | Parameters visible | Error messages | -|----------------|----------------------------|---------------------| -| @beginner | Required only | Human-readable | -| @intermediate | Required + half optional | Typed with context | -| @expert | All (required + optional) | Raw codes + stack | +[cols=",,",options="header",] +|=== +|Level |Parameters visible |Error messages +|@beginner |Required only |Human-readable +|@intermediate |Required + half optional |Typed with context +|@expert |All (required + optional) |Raw codes + stack +|=== -## Key Invariants +=== Key Invariants -1. **Layer ordering**: Beginner < Intermediate < Expert (never reversed) -2. **Parameter monotonicity**: beginner_params <= intermediate_params <= expert_params -3. **Score bounds**: 0 <= complexity_score <= 100 -4. **Default safety**: smart defaults satisfy parameter type constraints -5. **Determinism**: same manifest always produces same output +[arabic] +. *Layer ordering*: Beginner < Intermediate < Expert (never reversed) +. *Parameter monotonicity*: beginner_params <= intermediate_params <= +expert_params +. *Score bounds*: 0 <= complexity_score <= 100 +. *Default safety*: smart defaults satisfy parameter type constraints +. *Determinism*: same manifest always produces same output diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..2c97f97 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — mylangiser (Developer) + +=== What is mylangiser? + +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 796b47c..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — mylangiser (Developer) - -## What is mylangiser? -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..fc4562b --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — mylangiser (User) + +=== What is mylangiser? + +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 d27d994..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — mylangiser (User) - -## What is mylangiser? -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