From 697fd978f591af1cd5c4474c02883da628724a8e Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Fri, 15 May 2026 08:10:50 +0100 Subject: [PATCH] docs: clean up the three drift items flagged in #112 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follow-up to #112. Three items were flagged there as "not done — would expand scope". This commit addresses all three. 1. dune-project: relax OCaml constraint to match reality ------------------------------------------------------- `dune-project` declared `(ocaml (>= 5.1))`, but the current tree builds clean on 4.14.2 (209/209 tests green; verified in #112). The constraint was stricter than the actual code requires, so `opam install .` against a 4.14 switch failed for no real reason. Bumped down to `(ocaml (>= 4.14))`. `affinescript.opam` regenerated via `dune build` and the corresponding README note ("dune-project lists `>= 5.1` but ...") is no longer needed and has been dropped. If a 5.x-only feature is later introduced, bump the constraint at that point with a commit that links the offending source line. 2. AI.a2ml: fix .scm → .a2ml drift, align with on-disk reality -------------------------------------------------------------- `AI.a2ml` told agents to read `.machine_readable/STATE.scm`, `AGENTIC.scm`, etc., and to "read `.machine_readable/*.scm` files at session start". None of those files exist — the actual files are `.a2ml`, living under `.machine_readable/6a2/` (per the canonical rule that `.scm` is reserved for Guix: `guix.scm`, `.guix-channel`). Rewrote the file to reflect the actual on-disk layout, split into: - Core 6a2 metadata under `.machine_readable/6a2/` - Top-level contractile files (`*.contractile`, `CLADE.a2ml`, anchors) - Agent guidance (`agent_instructions/methodology.a2ml` etc.) Workflow steps now point at `STATE.a2ml` and `AGENTIC.a2ml` with the correct path prefix. 3. CONTRIBUTING.md: replace template placeholders, fix truncation ----------------------------------------------------------------- `CONTRIBUTING.md` was a half-rendered standards template: - Started with a bare `# Clone the repository` (no title, no intro, with a dangling closing ` ``` ` left over from a deleted fence). - Placeholders never substituted: `{{FORGE}}`, `{{OWNER}}`, `{{REPO}}`, `{{MAIN_BRANCH}}`. - Ended mid-sentence in the Conventional Commits format block (line 117 with an unclosed code fence and no closing sections — License / CoC pointers, PR workflow, etc.). - Suggested setup steps that don't apply here (`nix develop`, `toolbox`, `just check`) — affinescript builds with `dune`. Rewrote as a real contributor guide: - Title + intro pointing at README.adoc and STATE.a2ml. - Quick Start matching the README's opam + `eval $(opam env)` recipe. - Repository Structure that reflects what's actually on disk (lib/, bin/, stdlib/, packages/, .machine_readable/, js/ for the playground). - Real GitHub label URLs. - Branch naming + Conventional Commits + Required Checks + Pull Requests sections, all closed out properly. - License + Code of Conduct pointers at the bottom. Notably dropped: the "Perimeter 1/2/3" framework from the source template — it does not appear anywhere else in the affinescript tree (only in vendored sibling-repo `.github/` mirrors), so it was template baggage rather than project vocabulary. CODE_OF_CONDUCT.md is still a placeholder template — that's a separate pass (kept out of this PR to keep it reviewable). Verification ------------ $ dune build → exit 0 $ dune runtest → 209/209 green Co-Authored-By: Claude Opus 4.7 --- .build/dune-project | 2 +- AI.a2ml | 39 +++++++--- CONTRIBUTING.md | 174 +++++++++++++++++++++++++++----------------- README.adoc | 2 +- affinescript.opam | 2 +- 5 files changed, 137 insertions(+), 82 deletions(-) diff --git a/.build/dune-project b/.build/dune-project index 0c1ab610..34f3d847 100644 --- a/.build/dune-project +++ b/.build/dune-project @@ -25,7 +25,7 @@ (description "AffineScript combines Rust-style ownership (affine types), compile-time size verification (dependent types), extensible records (row polymorphism), and trackable side effects (extensible effects). It compiles to WebAssembly for efficient, portable execution.") (depends - (ocaml (>= 5.1)) + (ocaml (>= 4.14)) (dune (>= 3.14)) (menhir (>= 20231231)) (sedlex (>= 3.2)) diff --git a/AI.a2ml b/AI.a2ml index 11aa8031..e8ab0b19 100644 --- a/AI.a2ml +++ b/AI.a2ml @@ -2,21 +2,36 @@ # Machine-Readable Metadata -Project metadata and AI agent configuration files are located in `.machine_readable/`: +Project metadata and AI agent configuration files live under `.machine_readable/`. All metadata files use the `.a2ml` extension; the `.scm` extension is reserved for Guix (`guix.scm`, `.guix-channel`). -- **STATE.scm** - Current project state, progress, blockers, next actions -- **ECOSYSTEM.scm** - Position in ecosystem, relationships to other projects -- **META.scm** - Architecture decisions, governance, development practices -- **PLAYBOOK.scm** - Operational runbook, procedures, alerts -- **AGENTIC.scm** - AI agent interaction patterns and constraints -- **NEUROSYM.scm** - Neurosymbolic integration configuration +## Core 6a2 metadata (`.machine_readable/6a2/`) + +- **STATE.a2ml** - Current project state, progress, blockers, next actions, session notes +- **ECOSYSTEM.a2ml** - Position in ecosystem, relationships to sibling projects +- **META.a2ml** - Architecture decisions, governance, development practices +- **PLAYBOOK.a2ml** - Operational runbook, procedures, alerts +- **AGENTIC.a2ml** - AI agent interaction patterns and constraints +- **NEUROSYM.a2ml** - Neurosymbolic integration configuration + +## Top-level contractile files (`.machine_readable/`) + +- **ADJUST.contractile**, **INTENT.contractile**, **MUST.contractile**, **TRUST.contractile** - Trident-shape commitments +- **CLADE.a2ml** - Phylogenetic context within the estate +- **anchors/ANCHOR.a2ml** - Stable references for tooling + +## Agent guidance (`.machine_readable/agent_instructions/`) + +- **methodology.a2ml** - Required checks (dune build / dune runtest must pass; see for the full list) +- **coverage.a2ml**, **debt.a2ml** - Tracked metrics +- **README.adoc** - Human-readable summary of agent instructions **These files are the canonical source of truth for project metadata.** ## Workflow -1. Read `.machine_readable/*.scm` files at session start -2. Check STATE.scm for current phase, blockers, next actions -3. Follow patterns and constraints from AGENTIC.scm -4. Update STATE.scm after completing work -5. Sync to database: `~/sync-language-tracker.sh` +1. Read `.machine_readable/6a2/*.a2ml` files at session start +2. Check `STATE.a2ml` for current phase, blockers, next actions +3. Follow patterns and constraints from `AGENTIC.a2ml` +4. Follow methodology gates from `agent_instructions/methodology.a2ml` +5. Update `STATE.a2ml` after completing work +6. Sync to database: `~/sync-language-tracker.sh` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5457337d..9c0dd016 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,48 +1,59 @@ -# Clone the repository -git clone https://{{FORGE}}/{{OWNER}}/{{REPO}}.git -cd {{REPO}} +# Contributing to AffineScript -# Using Nix (recommended for reproducibility) -nix develop +Thank you for your interest in AffineScript — a practical language for resource-safe systems, compiling to typed WebAssembly. This guide covers how to set up a working tree, file useful bugs, and submit changes. -# Or using toolbox/distrobox -toolbox create {{REPO}}-dev -toolbox enter {{REPO}}-dev -# Install dependencies manually +For the language itself, start from [`README.adoc`](README.adoc). For project state, blockers, and next-actions, see [`.machine_readable/6a2/STATE.a2ml`](.machine_readable/6a2/STATE.a2ml). + +--- + +## Quick Start + +```bash +git clone https://github.com/hyperpolymath/affinescript.git +cd affinescript + +# Provision the OCaml toolchain (one-shot). See README.adoc "Getting Started" +# for the full list of opam packages and the `eval $(opam env)` note for +# non-interactive shells. +opam install -y \ + sedlex menhir ppx_deriving ppx_sexp_conv sexplib0 fmt cmdliner yojson \ + alcotest ocamlformat \ + js_of_ocaml js_of_ocaml-ppx js_of_ocaml-compiler +eval "$(opam env --switch=default --set-switch)" # Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite +dune build +dune runtest ``` +Tested on OCaml 4.14.2 (the constraint in `dune-project` is `>= 4.14`). + ### Repository Structure + ``` -{{REPO}}/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md +affinescript/ +├── lib/ # Compiler core (lexer, parser, typechecker, codegen, verifier) +├── bin/ # CLI driver — `_build/default/bin/main.exe` +├── stdlib/ # Standard library `.affine` modules +├── test/ # Alcotest suites (lexer, golden, e2e fixtures) +├── tests/ # Topic-grouped tests (borrow, codegen, effects, parser, …) +├── examples/ # Self-contained example programs +├── conformance/ # Conformance test corpus +├── docs/ # Specs, decisions, guides +├── packages/ # Aggregate JS/TS/ReScript binding packages +├── editors/ # Editor integrations +├── js/ # `js_of_ocaml` playground (built into `playground.bc.js`) +├── .machine_readable/ # Machine-readable metadata (`.a2ml`) — see AI.a2ml +├── .github/ # CI workflows, issue templates ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md +├── LICENSE / LICENSES # MIT OR AGPL-3.0-or-later +├── MAINTAINERS.adoc ├── README.adoc +├── ROADMAP.adoc ├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── justfile # Task runner (Perimeter 1) +├── dune-project +└── justfile ``` --- @@ -51,66 +62,95 @@ just test # Run test suite ### Reporting Bugs -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `{{MAIN_BRANCH}}` -3. Determine which perimeter the bug affects +**Before reporting:** +1. Search [existing issues](https://github.com/hyperpolymath/affinescript/issues). +2. Check that the bug reproduces against `main` (`git pull && dune build`). -**When reporting**: +**When reporting:** use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction +- Clear, descriptive title. +- Environment: OCaml version, opam switch, OS. +- Steps to reproduce, ideally as a minimal `.affine` file plus the exact `dune exec affinescript -- ` invocation. +- Expected vs actual behaviour (compiler output, generated Wasm, runtime trap, etc.). ### Suggesting Features -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: +**Before suggesting:** +1. Skim [`ROADMAP.adoc`](ROADMAP.adoc) and `.machine_readable/6a2/STATE.a2ml`. +2. Search existing issues and discussions. -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: +**When suggesting:** use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects +- Problem statement — what pain point does this solve? +- Proposed solution and any alternatives considered. +- Whether the change touches the core language, a face (frontend surface), a backend, or the stdlib. ### Your First Contribution Look for issues labelled: -- [`good first issue`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed -- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements -- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/perimeter-3) — Community sandbox scope +- [`good first issue`](https://github.com/hyperpolymath/affinescript/labels/good%20first%20issue) +- [`help wanted`](https://github.com/hyperpolymath/affinescript/labels/help%20wanted) +- [`documentation`](https://github.com/hyperpolymath/affinescript/labels/documentation) --- ## Development Workflow ### Branch Naming + ``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) +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 +ci/what-changed # CI / tooling ``` +Branch from `main` and target `main` in your PR. + ### Commit Messages We follow [Conventional Commits](https://www.conventionalcommits.org/): + ``` (): [optional body] -[optional footer] +[optional footer, e.g. closes #N or Co-Authored-By: ...] +``` + +Common types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `ci`. Common scopes: `lexer`, `parser`, `typecheck`, `codegen`, `verify`, `stdlib`, `cli`, `readme`. + +### Required Checks + +Before opening a PR, locally: + +```bash +dune build # must exit 0 +dune runtest # must be green +dune fmt # optional — auto-formats with ocamlformat +``` + +The `methodology.a2ml` file lists the canonical gate set. CI will rerun `build` + `runtest` plus the security, lint, and policy workflows in `.github/workflows/`. + +### Pull Requests + +1. Push your branch and open a PR against `main`. +2. Use a Conventional-Commit-shaped title. +3. In the body, summarise the change and link the issue it closes. +4. Keep PRs focused — split unrelated changes into separate PRs. +5. CI must be green. Maintainers squash-merge by default; commit message lineage is preserved in the PR body. + +--- + +## Code of Conduct + +This project follows the [Code of Conduct](CODE_OF_CONDUCT.md). By participating you agree to abide by it. + +## License + +By contributing you agree your contribution is licensed under the project's dual licence (MIT OR AGPL-3.0-or-later), as recorded in [`LICENSE`](LICENSE) and per-file SPDX headers. diff --git a/README.adoc b/README.adoc index 40278256..babeb003 100644 --- a/README.adoc +++ b/README.adoc @@ -387,7 +387,7 @@ Games are one place where the language’s properties are easy to demonstrate. T === Prerequisites -- OCaml 4.14.2+ (dune-project lists `>= 5.1`, but the current tree also builds clean on 4.14.2; the constraint is stricter than the actual code requires) +- OCaml 4.14.2+ - Dune 3.14+ - opam packages: `sedlex`, `menhir`, `ppx_deriving`, `ppx_sexp_conv`, `sexplib0`, `fmt`, `cmdliner`, `yojson`, `alcotest` (test), `ocamlformat` (test), `js_of_ocaml`, `js_of_ocaml-ppx`, `js_of_ocaml-compiler` diff --git a/affinescript.opam b/affinescript.opam index 85d72f72..002b5383 100644 --- a/affinescript.opam +++ b/affinescript.opam @@ -22,7 +22,7 @@ homepage: "https://github.com/hyperpolymath/affinescript" doc: "https://github.com/hyperpolymath/affinescript" bug-reports: "https://github.com/hyperpolymath/affinescript/issues" depends: [ - "ocaml" {>= "5.1"} + "ocaml" {>= "4.14"} "dune" {>= "3.14" & >= "3.14"} "menhir" {>= "20231231"} "sedlex" {>= "3.2"}