From c741dc2df4547aa9b4ad8f7159d8b26d17ff86ee Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 07:52:29 +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 --------- README.adoc | 272 +++++++++++++++++++++++++++++++++++ README.md | 255 -------------------------------- SECURITY.md => SECURITY.adoc | 21 +-- TEST-NEEDS.adoc | 34 +++++ TEST-NEEDS.md | 31 ---- TOPOLOGY.md => TOPOLOGY.adoc | 14 +- llm-warmup-dev.adoc | 19 +++ llm-warmup-dev.md | 16 --- llm-warmup-user.adoc | 19 +++ llm-warmup-user.md | 16 --- 14 files changed, 457 insertions(+), 428 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 create mode 100644 README.adoc delete mode 100644 README.md rename SECURITY.md => SECURITY.adoc (58%) create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md rename TOPOLOGY.md => TOPOLOGY.adoc (97%) 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..dd089ae --- /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 `+guix 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 90e87dc..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 `guix 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/README.adoc b/README.adoc new file mode 100644 index 0000000..782fbf3 --- /dev/null +++ b/README.adoc @@ -0,0 +1,272 @@ +https://github.com/sponsors/hyperpolymath[image:https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github[Sponsor]] + +== What Is Alloyiser? + +Alloyiser takes *API specifications* (OpenAPI 3.x, GraphQL schemas, gRPC +`+.proto+` files) and extracts their entity relationships into *Alloy 6 +formal models* — then runs the https://alloytools.org[Alloy Analyzer] to +find design bugs _before any implementation code exists_. + +https://en.wikipedia.org/wiki/Alloy_(specification_language)[Alloy] is a +lightweight formal modelling language created by Daniel Jackson at MIT. +It uses *relational logic* and *SAT solving* to exhaustively search for +counterexamples to declared invariants. If your API spec says "`every +order must have a customer`" but there exists a reachable state where an +orphaned order can appear, Alloy will find it and show you the concrete +scenario. + +Alloyiser makes this power accessible: you point it at your spec files, +declare invariants in `+alloyiser.toml+`, and get a counterexample +report — no Alloy expertise required. + +Part of the https://github.com/hyperpolymath/iseriser[-iser family] of +acceleration frameworks. + +== Key Value + +* *Find API design bugs before writing code* — race conditions, +impossible states, orphaned resources +* *Database schema verification* — detect unreachable states and +constraint violations +* *Protocol state machine validation* — verify handshakes, transitions, +and liveness properties +* *Microservice contract checking* — prove that service A’s expectations +match service B’s guarantees +* *CI/CD gate* — fail a pull request if Alloy finds a counterexample in +the spec + +== Architecture + +.... + alloyiser pipeline + ================== + + ┌──────────────┐ ┌─────────────┐ ┌───────────────────┐ + │ OpenAPI 3.x │ │ GraphQL │ │ gRPC .proto │ + │ spec.yaml │ │ schema.gql │ │ service.proto │ + └──────┬───────┘ └──────┬──────┘ └────────┬──────────┘ + │ │ │ + └───────────┬───────┘────────────────────┘ + │ + ▼ + ┌───────────────────────┐ + │ Spec Parser │ Rust: extract entities, fields, + │ (src/core/) │ relationships, constraints + └───────────┬───────────┘ + │ + ▼ + ┌───────────────────────┐ + │ Relation Extractor │ entities → Alloy signatures + │ (src/bridges/) │ fields → Alloy relations + └───────────┬───────────┘ constraints → Alloy facts + │ + ▼ + ┌───────────────────────┐ + │ Idris2 ABI │ Proves: model extraction + │ (src/interface/abi/)│ preserves spec semantics + └───────────┬───────────┘ + │ + ▼ + ┌───────────────────────┐ + │ Alloy Codegen │ Generates .als files with: + │ (src/codegen/) │ sig, field, fact, pred, assert + └───────────┬───────────┘ + │ + ▼ + ┌───────────────────────┐ + │ Alloy Analyzer │ SAT solving via Kodkod/SAT4J + │ (alloy6.jar) │ bounded model checking + └───────────┬───────────┘ + │ + ▼ + ┌───────────────────────┐ + │ Counterexample │ Human-readable violation report + │ Report │ with concrete state instances + └───────────────────────┘ +.... + +== Alloy Concepts (Quick Reference) + +Alloyiser generates these Alloy constructs from your API specs: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Alloy Construct |What It Means |Extracted From +|`+sig+` (Signature) |An entity type — like a class or table |OpenAPI +schema objects, GraphQL types, protobuf messages + +|`+field+` |A relation between signatures |Object properties, field +types, foreign keys + +|`+fact+` |An invariant that must always hold |Required fields, +uniqueness constraints, enum restrictions + +|`+pred+` (Predicate) |A reusable named constraint |API operation +pre/post conditions + +|`+assert+` (Assertion) |A property to verify |User-declared invariants +in `+alloyiser.toml+` + +|`+check+` |Run SAT solver to find counterexamples to an assertion +|Automatic: one check per assertion + +|`+run+` |Generate a satisfying instance |Automatic: used to visualise +valid states +|=== + +== How It Works + +=== 1. Create a manifest + +[source,toml] +---- +# alloyiser.toml — point at your spec, declare what to verify + +[workload] +name = "pet-store-api" +entry = "specs/petstore.yaml" +strategy = "openapi" + +[data] +input-type = "OpenAPI3" +output-type = "AlloyModel" + +[invariants] +# Declare properties your API should satisfy: +no-orphaned-pets = "all p: Pet | some p.owner" +unique-pet-ids = "all disj p1, p2: Pet | p1.id != p2.id" +valid-status = "all p: Pet | p.status in Available + Pending + Sold" + +[options] +scope = 5 # Check up to 5 instances of each entity +alloy-jar = "lib/alloy6.jar" +output-dir = "generated/alloy" +---- + +=== 2. Generate and check + +[source,bash] +---- +# Initialise a new manifest in the current directory +alloyiser init + +# Validate the manifest +alloyiser validate -m alloyiser.toml + +# Generate Alloy models from the spec +alloyiser generate -m alloyiser.toml -o generated/alloy + +# Run the Alloy Analyzer (finds counterexamples) +alloyiser run -m alloyiser.toml + +# Show manifest summary +alloyiser info -m alloyiser.toml +---- + +=== 3. Read the report + +Alloyiser produces a counterexample report showing concrete states that +violate your invariants. For example: + +.... +VIOLATION: no-orphaned-pets + Counterexample found (scope 5): + Pet$0 = { id: 1, name: "Fido", status: Available, owner: none } + Explanation: + The OpenAPI spec allows creating a Pet without an owner field + (owner is not in the `required` array). This violates the invariant + that every Pet must have an owner. + Fix: Add "owner" to the required fields in the Pet schema. +.... + +== Use Cases + +*Microservice contract verification* + +Two services agree on a shared schema. Alloyiser checks that the +producer’s guarantees satisfy the consumer’s expectations — catching +mismatches before integration testing. + +*Database schema consistency* + +Extract entity-relationship constraints from your migration files or ORM +definitions. Verify referential integrity, cardinality constraints, and +state machine transitions. + +*Protocol state machine validation* + +Model a multi-step protocol (OAuth flow, payment processing, order +lifecycle) as an Alloy state machine. Check liveness ("`the order +eventually reaches a terminal state`") and safety ("`a refund cannot +exceed the original charge`"). + +*API evolution safety* + +When adding fields or endpoints, regenerate the Alloy model and +re-check. Alloyiser detects regressions: "`adding optional field X +breaks invariant Y.`" + +== CLI Commands + +[width="100%",cols="50%,50%",options="header",] +|=== +|Command |Description +|`+alloyiser+` `+init+` |Create a new `+alloyiser.toml+` manifest in the +current directory + +|`+alloyiser+` `+validate+` |Parse and validate the manifest (checks +structure, not semantics) + +|`+alloyiser+` `+generate+` |Extract entities from the spec and generate +`+.als+` Alloy model files + +|`+alloyiser+` `+build+` |Compile generated artifacts (Alloy model + Zig +FFI bridge) + +|`+alloyiser+` `+run+` |Run the Alloy Analyzer against the generated +models + +|`+alloyiser+` `+info+` |Display a summary of the manifest configuration +|=== + +== Building + +[source,bash] +---- +# Build +cargo build --release + +# Test +cargo test + +# Full quality check (format + lint + test) +just quality + +# Pre-commit scan +just assail +---- + +Requires: + +* *Rust* (nightly, via asdf) +* *Alloy 6* JAR for analyzer integration (Phase 3+) +* *Idris2* for ABI proofs (Phase 5+) +* *Zig* for FFI bridge (Phase 5+) + +== Status + +*Pre-alpha (scaffold phase).* The CLI skeleton, manifest parser, and +project structure are in place. Code generation and Alloy Analyzer +integration are pending — see link:ROADMAP.adoc[ROADMAP] for the +implementation plan. + +What exists today: + +* Rust CLI with `+init+`, `+validate+`, `+generate+`, `+build+`, +`+run+`, `+info+` subcommands +* TOML manifest parser and validator +* Codegen stub (ready for Alloy `+.als+` generation) +* Idris2 ABI type definitions (template — being specialised for Alloy +model types) +* Full RSR infrastructure: 17 CI/CD workflows, Containerfile, Justfile, +governance docs + +== License + +SPDX-License-Identifier: CC-BY-SA-4.0 diff --git a/README.md b/README.md deleted file mode 100644 index ba544ef..0000000 --- a/README.md +++ /dev/null @@ -1,255 +0,0 @@ - - -[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/hyperpolymath) - -# What Is Alloyiser? - -Alloyiser takes **API specifications** (OpenAPI 3.x, GraphQL schemas, -gRPC `.proto` files) and extracts their entity relationships into -**Alloy 6 formal models** — then runs the [Alloy -Analyzer](https://alloytools.org) to find design bugs *before any -implementation code exists*. - -[Alloy](https://en.wikipedia.org/wiki/Alloy_(specification_language)) is -a lightweight formal modelling language created by Daniel Jackson at -MIT. It uses **relational logic** and **SAT solving** to exhaustively -search for counterexamples to declared invariants. If your API spec says -"every order must have a customer" but there exists a reachable state -where an orphaned order can appear, Alloy will find it and show you the -concrete scenario. - -Alloyiser makes this power accessible: you point it at your spec files, -declare invariants in `alloyiser.toml`, and get a counterexample report -— no Alloy expertise required. - -Part of the [-iser family](https://github.com/hyperpolymath/iseriser) of -acceleration frameworks. - -# Key Value - -- **Find API design bugs before writing code** — race conditions, - impossible states, orphaned resources - -- **Database schema verification** — detect unreachable states and - constraint violations - -- **Protocol state machine validation** — verify handshakes, - transitions, and liveness properties - -- **Microservice contract checking** — prove that service A’s - expectations match service B’s guarantees - -- **CI/CD gate** — fail a pull request if Alloy finds a counterexample - in the spec - -# Architecture - - alloyiser pipeline - ================== - - ┌──────────────┐ ┌─────────────┐ ┌───────────────────┐ - │ OpenAPI 3.x │ │ GraphQL │ │ gRPC .proto │ - │ spec.yaml │ │ schema.gql │ │ service.proto │ - └──────┬───────┘ └──────┬──────┘ └────────┬──────────┘ - │ │ │ - └───────────┬───────┘────────────────────┘ - │ - ▼ - ┌───────────────────────┐ - │ Spec Parser │ Rust: extract entities, fields, - │ (src/core/) │ relationships, constraints - └───────────┬───────────┘ - │ - ▼ - ┌───────────────────────┐ - │ Relation Extractor │ entities → Alloy signatures - │ (src/bridges/) │ fields → Alloy relations - └───────────┬───────────┘ constraints → Alloy facts - │ - ▼ - ┌───────────────────────┐ - │ Idris2 ABI │ Proves: model extraction - │ (src/interface/abi/)│ preserves spec semantics - └───────────┬───────────┘ - │ - ▼ - ┌───────────────────────┐ - │ Alloy Codegen │ Generates .als files with: - │ (src/codegen/) │ sig, field, fact, pred, assert - └───────────┬───────────┘ - │ - ▼ - ┌───────────────────────┐ - │ Alloy Analyzer │ SAT solving via Kodkod/SAT4J - │ (alloy6.jar) │ bounded model checking - └───────────┬───────────┘ - │ - ▼ - ┌───────────────────────┐ - │ Counterexample │ Human-readable violation report - │ Report │ with concrete state instances - └───────────────────────┘ - -# Alloy Concepts (Quick Reference) - -Alloyiser generates these Alloy constructs from your API specs: - -| Alloy Construct | What It Means | Extracted From | -|----|----|----| -| `sig` (Signature) | An entity type — like a class or table | OpenAPI schema objects, GraphQL types, protobuf messages | -| `field` | A relation between signatures | Object properties, field types, foreign keys | -| `fact` | An invariant that must always hold | Required fields, uniqueness constraints, enum restrictions | -| `pred` (Predicate) | A reusable named constraint | API operation pre/post conditions | -| `assert` (Assertion) | A property to verify | User-declared invariants in `alloyiser.toml` | -| `check` | Run SAT solver to find counterexamples to an assertion | Automatic: one check per assertion | -| `run` | Generate a satisfying instance | Automatic: used to visualise valid states | - -# How It Works - -## 1. Create a manifest - -```toml -# alloyiser.toml — point at your spec, declare what to verify - -[workload] -name = "pet-store-api" -entry = "specs/petstore.yaml" -strategy = "openapi" - -[data] -input-type = "OpenAPI3" -output-type = "AlloyModel" - -[invariants] -# Declare properties your API should satisfy: -no-orphaned-pets = "all p: Pet | some p.owner" -unique-pet-ids = "all disj p1, p2: Pet | p1.id != p2.id" -valid-status = "all p: Pet | p.status in Available + Pending + Sold" - -[options] -scope = 5 # Check up to 5 instances of each entity -alloy-jar = "lib/alloy6.jar" -output-dir = "generated/alloy" -``` - -## 2. Generate and check - -```bash -# Initialise a new manifest in the current directory -alloyiser init - -# Validate the manifest -alloyiser validate -m alloyiser.toml - -# Generate Alloy models from the spec -alloyiser generate -m alloyiser.toml -o generated/alloy - -# Run the Alloy Analyzer (finds counterexamples) -alloyiser run -m alloyiser.toml - -# Show manifest summary -alloyiser info -m alloyiser.toml -``` - -## 3. Read the report - -Alloyiser produces a counterexample report showing concrete states that -violate your invariants. For example: - - VIOLATION: no-orphaned-pets - Counterexample found (scope 5): - Pet$0 = { id: 1, name: "Fido", status: Available, owner: none } - Explanation: - The OpenAPI spec allows creating a Pet without an owner field - (owner is not in the `required` array). This violates the invariant - that every Pet must have an owner. - Fix: Add "owner" to the required fields in the Pet schema. - -# Use Cases - -**Microservice contract verification** -Two services agree on a shared schema. Alloyiser checks that the -producer’s guarantees satisfy the consumer’s expectations — catching -mismatches before integration testing. - -**Database schema consistency** -Extract entity-relationship constraints from your migration files or ORM -definitions. Verify referential integrity, cardinality constraints, and -state machine transitions. - -**Protocol state machine validation** -Model a multi-step protocol (OAuth flow, payment processing, order -lifecycle) as an Alloy state machine. Check liveness ("the order -eventually reaches a terminal state") and safety ("a refund cannot -exceed the original charge"). - -**API evolution safety** -When adding fields or endpoints, regenerate the Alloy model and -re-check. Alloyiser detects regressions: "adding optional field X breaks -invariant Y." - -# CLI Commands - -| Command | Description | -|----|----| -| `alloyiser` `init` | Create a new `alloyiser.toml` manifest in the current directory | -| `alloyiser` `validate` | Parse and validate the manifest (checks structure, not semantics) | -| `alloyiser` `generate` | Extract entities from the spec and generate `.als` Alloy model files | -| `alloyiser` `build` | Compile generated artifacts (Alloy model + Zig FFI bridge) | -| `alloyiser` `run` | Run the Alloy Analyzer against the generated models | -| `alloyiser` `info` | Display a summary of the manifest configuration | - -# Building - -```bash -# Build -cargo build --release - -# Test -cargo test - -# Full quality check (format + lint + test) -just quality - -# Pre-commit scan -just assail -``` - -Requires: - -- **Rust** (nightly, via asdf) - -- **Alloy 6** JAR for analyzer integration (Phase 3+) - -- **Idris2** for ABI proofs (Phase 5+) - -- **Zig** for FFI bridge (Phase 5+) - -# Status - -**Pre-alpha (scaffold phase).** The CLI skeleton, manifest parser, and -project structure are in place. Code generation and Alloy Analyzer -integration are pending — see [ROADMAP](ROADMAP.adoc) for the -implementation plan. - -What exists today: - -- Rust CLI with `init`, `validate`, `generate`, `build`, `run`, `info` - subcommands - -- TOML manifest parser and validator - -- Codegen stub (ready for Alloy `.als` generation) - -- Idris2 ABI type definitions (template — being specialised for Alloy - model types) - -- Full RSR infrastructure: 17 CI/CD workflows, Containerfile, Justfile, - governance docs - -# License - -SPDX-License-Identifier: CC-BY-SA-4.0 diff --git a/SECURITY.md b/SECURITY.adoc similarity index 58% rename from SECURITY.md rename to SECURITY.adoc index ddc591a..6119c75 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 alloyiser CLI tool and its generated artifacts. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..119d327 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,34 @@ +== TEST-NEEDS.md — alloyiser + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[cols=",,",options="header",] +|=== +|Category |Count |Notes +|Test directories |2 |Location(s): /tests, /verification/tests +|CI workflows |22 |Running tests on GitHub Actions +|Unit tests |Built-in |Rust/cargo test framework +|Integration tests |Configured |Via integration/ directory +|=== + +=== What’s Covered + +* [x] Rust unit test suite (cargo test) +* [x] Documentation tests +* [x] Example programs with tests + +=== Still Missing (for CRG B+) + +* [ ] Code coverage reports (codecov integration) +* [ ] Detailed test documentation in CONTRIBUTING.md +* [ ] Integration tests beyond unit tests +* [ ] Performance benchmarking suite + +=== Run Tests + +[source,bash] +---- +cargo test +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index c09ed8e..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,31 +0,0 @@ -# TEST-NEEDS.md — alloyiser - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Test directories | 2 | Location(s): /tests, /verification/tests | -| CI workflows | 22 | Running tests on GitHub Actions | -| Unit tests | Built-in | Rust/cargo test framework | -| Integration tests | Configured | Via integration/ directory | - -## What's Covered - -- [x] Rust unit test suite (cargo test) -- [x] Documentation tests -- [x] Example programs with tests - -## Still Missing (for CRG B+) - -- [ ] Code coverage reports (codecov integration) -- [ ] Detailed test documentation in CONTRIBUTING.md -- [ ] Integration tests beyond unit tests -- [ ] Performance benchmarking suite - -## Run Tests - -```bash -cargo test -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 97% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index b0ad591..6aa968e 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,8 +1,6 @@ - - -# TOPOLOGY.md — alloyiser repository structure +== TOPOLOGY.md — alloyiser repository structure -``` +.... alloyiser/ ├── 0-AI-MANIFEST.a2ml # AI agent entry point (read first) ├── Cargo.toml # Rust crate manifest @@ -121,11 +119,11 @@ alloyiser/ ├── .gitignore # Git ignore rules ├── .guix-channel # Guix channel config └── .tool-versions # asdf tool versions -``` +.... -## Data Flow +=== Data Flow -``` +.... User writes alloyiser.toml │ ▼ @@ -148,4 +146,4 @@ Alloy Analyzer SAT solving finds counterexamples │ ▼ Counterexample Report human-readable + JSON output -``` +.... diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..8e5b298 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — alloyiser (Developer) + +=== What is alloyiser? + +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 546b5a3..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — alloyiser (Developer) - -## What is alloyiser? -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..236d4d6 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — alloyiser (User) + +=== What is alloyiser? + +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 ff76b99..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — alloyiser (User) - -## What is alloyiser? -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