From 61f380ccc99122655f73fb961e38b4e216414e1b Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 16 Apr 2026 13:38:15 +0000 Subject: [PATCH 1/2] refactor: rebrand rescript-evangeliser -> nextgen-languages-evangeliser (Phase 1a) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 0 (decide) complete; starting Phase 1 of the migration from a ReScript-only evangeliser to a multi-target nextgen-typed-languages evangeliser. Flagship target becomes AffineScript; ReScript is preserved as a legacy target. This commit is rebrand-only — no engine/code behaviour changes yet. Phase 1b will generalise src/Types.res for multi-target patterns. Touched: - Docs: README, CLAUDE.md, .claude/CLAUDE.md, EXPLAINME, ROADMAP, CHANGELOG (md+adoc), CONTRIBUTING, SECURITY, MAINTAINERS, TOPOLOGY, TEST-NEEDS, CODE_OF_CONDUCT, QUICKSTART-{DEV,MAINTAINER,USER}, docs/{RSR_COMPLIANCE,TPCF,CITATIONS} - Metadata: 0-AI-MANIFEST.a2ml, .machine_readable/* (STATE, META, ECOSYSTEM, INTENT, MUST, TRUST, ADJUST; plus 6a2 variants), contractiles/{intend,must,trust}/* - Build/config: deno.json, rescript.json, config.ncl, k9iser.toml, stapeln.toml, Mustfile.epx, justfile, Justfile, flake.nix, guix.scm, setup.sh, bin/evangeliser.js - CI/meta: .github/workflows/ci.yml, .gitlab-ci.yml, .editorconfig, .well-known/security.txt, llm-warmup-{dev,user}.md - Source headers: src/{Types,Patterns,Glyphs,Narrative,Output,Cli}.res (comment header lines and Output.res display strings only) Policy additions: - Zig formalised as canonical FFI (already true per 0-AI-MANIFEST); V banned outside V-ecosystem-specific work. - AffineScript declared flagship target; typed-wasm (separate repo) noted as downstream codegen layer (AffineScript -> typed-wasm -> WASM). GitHub repo rename (rescript-evangeliser -> nextgen-languages-evangeliser) must be performed by the maintainer; all in-repo references are already updated so the rename is a one-click action. https://claude.ai/code/session_01RJWz6SUyUEHTBNLjVwF177 --- .claude/CLAUDE.md | 27 ++-- .editorconfig | 2 +- .github/workflows/ci.yml | 2 +- .gitlab-ci.yml | 2 +- .machine_readable/6a2/ECOSYSTEM.a2ml | 4 +- .machine_readable/6a2/META.a2ml | 3 +- .machine_readable/6a2/STATE.a2ml | 6 +- .machine_readable/ADJUST.contractile | 4 +- .machine_readable/ECOSYSTEM.a2ml | 24 ++-- .machine_readable/INTENT.contractile | 4 +- .machine_readable/META.a2ml | 4 +- .machine_readable/MUST.contractile | 4 +- .machine_readable/STATE.a2ml | 42 ++++-- .machine_readable/TRUST.contractile | 4 +- .well-known/security.txt | 4 +- 0-AI-MANIFEST.a2ml | 4 +- CHANGELOG.adoc | 14 +- CHANGELOG.md | 14 +- CLAUDE.md | 195 ++++++++++++--------------- CODE_OF_CONDUCT.md | 2 +- CONTRIBUTING.md | 12 +- EXPLAINME.adoc | 28 ++-- Justfile | 12 +- MAINTAINERS.md | 2 +- Mustfile.epx | 4 +- QUICKSTART-DEV.adoc | 12 +- QUICKSTART-MAINTAINER.adoc | 14 +- QUICKSTART-USER.adoc | 18 +-- README.adoc | 164 ++++++++++++---------- ROADMAP.adoc | 64 +++++++-- SECURITY.md | 6 +- TEST-NEEDS.md | 4 +- TOPOLOGY.md | 11 +- bin/evangeliser.js | 4 +- config.ncl | 33 +++-- contractiles/intend/Intentfile.a2ml | 12 +- contractiles/must/Mustfile.a2ml | 2 +- contractiles/trust/Trustfile.a2ml | 2 +- deno.json | 4 +- docs/CITATIONS.adoc | 25 ++-- docs/RSR_COMPLIANCE.md | 6 +- docs/TPCF.md | 6 +- flake.nix | 16 +-- guix.scm | 10 +- justfile | 2 +- k9iser.toml | 6 +- llm-warmup-dev.md | 4 +- llm-warmup-user.md | 4 +- rescript.json | 2 +- setup.sh | 10 +- src/Cli.res | 4 +- src/Glyphs.res | 2 +- src/Narrative.res | 2 +- src/Output.res | 18 +-- src/Patterns.res | 4 +- src/Types.res | 2 +- stapeln.toml | 8 +- 57 files changed, 513 insertions(+), 391 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index db65ffb..02e8a0f 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -1,19 +1,26 @@ # CLAUDE.md - AI Assistant Instructions +## Project: Nextgen Languages Evangeliser + +Flagship target: **AffineScript**. Legacy target: **ReScript**. More targets planned (Rust, Gleam, Zig). +Current host application language: ReScript (migration to AffineScript planned in Phase 3). + ## Language Policy (Hyperpolymath Standard) ### ALLOWED Languages & Tools | Language/Tool | Use Case | Notes | |---------------|----------|-------| -| **ReScript** | Primary application code | Compiles to JS, type-safe | +| **AffineScript** | Flagship target language; future host | Affine/linear types, borrow checker, QTT, WASM backend | +| **ReScript** | Current host application code; legacy target | Compiles to JS, type-safe | | **Deno** | Runtime & package management | Replaces Node/npm/bun | | **Rust** | Performance-critical, systems, WASM | Preferred for CLI tools | +| **Zig** | FFI, C-ABI bridges, systems | Canonical FFI layer (per `0-AI-MANIFEST.a2ml`) | | **Tauri 2.0+** | Mobile apps (iOS/Android) | Rust backend + web UI | | **Dioxus** | Mobile apps (native UI) | Pure Rust, React-like | | **Gleam** | Backend services | Runs on BEAM or compiles to JS | | **Bash/POSIX Shell** | Scripts, automation | Keep minimal | -| **JavaScript** | Only where ReScript cannot | MCP protocol glue, Deno APIs | +| **JavaScript** | Only where ReScript/AffineScript cannot | MCP protocol glue, Deno APIs | | **Nickel** | Configuration language | For complex configs | | **Guile Scheme** | State/meta files | STATE.scm, META.scm, ECOSYSTEM.scm | | **Julia** | Batch scripts, data processing | Per RSR | @@ -24,35 +31,37 @@ | Banned | Replacement | |--------|-------------| -| TypeScript | ReScript | +| TypeScript | AffineScript (preferred) or ReScript | | Node.js | Deno | | npm | Deno | | Bun | Deno | | pnpm/yarn | Deno | -| Go | Rust | -| Python | Julia/Rust/ReScript | +| Go | Rust or Zig | +| Python | Julia/Rust/ReScript/AffineScript | | Java/Kotlin | Rust/Tauri/Dioxus | | Swift | Tauri/Dioxus | | React Native | Tauri/Dioxus | | Flutter/Dart | Tauri/Dioxus | +| V | Zig (except inside V-ecosystem-specific projects) | ### Mobile Development **No exceptions for Kotlin/Swift** - use Rust-first approach: -1. **Tauri 2.0+** - Web UI (ReScript) + Rust backend, MIT/Apache-2.0 +1. **Tauri 2.0+** - Web UI (ReScript/AffineScript) + Rust backend, MIT/Apache-2.0 2. **Dioxus** - Pure Rust native UI, MIT/Apache-2.0 Both are FOSS with independent governance (no Big Tech). ### Enforcement Rules -1. **No new TypeScript files** - Convert existing TS to ReScript +1. **No new TypeScript files** - Convert existing TS to AffineScript or ReScript 2. **No package.json for runtime deps** - Use deno.json imports 3. **No node_modules in production** - Deno caches deps automatically -4. **No Go code** - Use Rust instead -5. **No Python anywhere** - Use Julia for data/batch, Rust for systems, ReScript for apps +4. **No Go code** - Use Rust or Zig instead +5. **No Python anywhere** - Use Julia for data/batch, Rust for systems, ReScript/AffineScript for apps 6. **No Kotlin/Swift for mobile** - Use Tauri 2.0+ or Dioxus +7. **No V outside the V ecosystem** - Use Zig ### Package Management diff --git a/.editorconfig b/.editorconfig index 83b77f8..4c14a5e 100644 --- a/.editorconfig +++ b/.editorconfig @@ -1,4 +1,4 @@ -# rescript-evangeliser - Editor Configuration +# nextgen-languages-evangeliser - Editor Configuration # https://editorconfig.org root = true diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3313b2a..e40e450 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -171,7 +171,7 @@ jobs: - name: Upload VSIX artifact uses: actions/upload-artifact@v3 with: - name: rescript-evangeliser-vsix + name: nextgen-languages-evangeliser-vsix path: extension/*.vsix performance: diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 5a3bd60..996ca22 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,4 +1,4 @@ -# GitLab CI configuration for ReScript Evangeliser +# GitLab CI configuration for Nextgen Languages Evangeliser image: node:20 diff --git a/.machine_readable/6a2/ECOSYSTEM.a2ml b/.machine_readable/6a2/ECOSYSTEM.a2ml index 1f211d7..7d1cc44 100644 --- a/.machine_readable/6a2/ECOSYSTEM.a2ml +++ b/.machine_readable/6a2/ECOSYSTEM.a2ml @@ -1,13 +1,13 @@ # SPDX-License-Identifier: PMPL-1.0-or-later # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # -# ECOSYSTEM.a2ml — Rescript Evangeliser ecosystem position +# ECOSYSTEM.a2ml — Nextgen Languages Evangeliser ecosystem position [metadata] version = "1.0" last-updated = "2026-04-11" [project] -name = "Rescript Evangeliser" +name = "Nextgen Languages Evangeliser" purpose = "image:https://img.shields.io/badge/license-Palimpsest--MPL--1.0-purple.svg[Palim" role = "project" diff --git a/.machine_readable/6a2/META.a2ml b/.machine_readable/6a2/META.a2ml index 17780aa..065d797 100644 --- a/.machine_readable/6a2/META.a2ml +++ b/.machine_readable/6a2/META.a2ml @@ -1,7 +1,8 @@ # SPDX-License-Identifier: PMPL-1.0-or-later # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # -# META.a2ml — Rescript Evangeliser meta-level information +# META.a2ml — Nextgen Languages Evangeliser meta-level information +# Renamed from Rescript Evangeliser on 2026-04-16 [metadata] version = "1.0.0" last-updated = "2026-04-11" diff --git a/.machine_readable/6a2/STATE.a2ml b/.machine_readable/6a2/STATE.a2ml index 6b8636e..6a8ec0d 100644 --- a/.machine_readable/6a2/STATE.a2ml +++ b/.machine_readable/6a2/STATE.a2ml @@ -1,16 +1,16 @@ # SPDX-License-Identifier: PMPL-1.0-or-later # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # -# STATE.a2ml — Rescript Evangeliser project state +# STATE.a2ml — Nextgen Languages Evangeliser project state [metadata] -project = "rescript-evangeliser" +project = "nextgen-languages-evangeliser" version = "1.0.0" last-updated = "2026-01-10T13:50:33+00:00" status = "active" session = "converted from scheme — 2026-04-11" [project-context] -name = "Rescript Evangeliser" +name = "Nextgen Languages Evangeliser" purpose = """""" completion-percentage = 50 diff --git a/.machine_readable/ADJUST.contractile b/.machine_readable/ADJUST.contractile index c0c393d..e6b2509 100644 --- a/.machine_readable/ADJUST.contractile +++ b/.machine_readable/ADJUST.contractile @@ -1,5 +1,5 @@ ; SPDX-License-Identifier: PMPL-1.0-or-later -; ADJUST.contractile — Accessibility invariants for rescript-evangeliser +; ADJUST.contractile — Accessibility invariants for nextgen-languages-evangeliser ; "ADJUST" = Accessibility & Digital Justice for Universal Software & Technology ; ; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST @@ -45,7 +45,7 @@ (version "1.0.0") (full-name "Accessibility & Digital Justice for Universal Software & Technology") (standard "WCAG-2.2-AA") - (repo "rescript-evangeliser") + (repo "nextgen-languages-evangeliser") (invariants ; ── Visual ── diff --git a/.machine_readable/ECOSYSTEM.a2ml b/.machine_readable/ECOSYSTEM.a2ml index 6c305c9..f8374dc 100644 --- a/.machine_readable/ECOSYSTEM.a2ml +++ b/.machine_readable/ECOSYSTEM.a2ml @@ -1,19 +1,27 @@ ;; SPDX-License-Identifier: PMPL-1.0-or-later -;; ECOSYSTEM.a2ml — rescript-evangeliser ecosystem position +;; ECOSYSTEM.a2ml — nextgen-languages-evangeliser ecosystem position ;; Migrated from root ECOSYSTEM.scm on 2026-04-12 +;; Renamed from rescript-evangeliser on 2026-04-16 (ecosystem - (version "1.0") - (name "rescript-evangeliser") + (version "1.1") + (name "nextgen-languages-evangeliser") + (predecessor "rescript-evangeliser") (type "project") - (purpose "ReScript evangelism — educational materials, examples, and tools for adopting ReScript") + (purpose "Nextgen typed-language evangelism — educational materials, examples, and tools for adopting AffineScript (flagship), ReScript (legacy), and future targets") (position-in-ecosystem (role "component") (layer "application") - (description "Advocacy and resource hub for ReScript language adoption within hyperpolymath estate")) + (description "Multi-target advocacy and resource hub for next-generation typed languages within the hyperpolymath estate")) - (related-projects ()) + (related-projects + (flagship-target "hyperpolymath/affinescript") + (codegen-layer "hyperpolymath/typed-wasm") + (legacy-target "rescript-lang/rescript")) - (what-this-is "Educational materials, worked examples, and advocacy tools for the ReScript language") - (what-this-is-not ())) + (what-this-is "Educational materials, worked examples, and advocacy tools for affine/linear-typed and other next-generation languages (flagship: AffineScript)") + (what-this-is-not + "A compiler" + "A type-checker" + "A language-server (see affinescript repo for LSP)")) diff --git a/.machine_readable/INTENT.contractile b/.machine_readable/INTENT.contractile index 371567c..aff4434 100644 --- a/.machine_readable/INTENT.contractile +++ b/.machine_readable/INTENT.contractile @@ -1,5 +1,5 @@ ; SPDX-License-Identifier: PMPL-1.0-or-later -; INTENT.contractile — Purpose and scope for rescript-evangeliser +; INTENT.contractile — Purpose and scope for nextgen-languages-evangeliser ; Helps LLM/SLM agents understand what this repo IS and IS NOT. ; ; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST @@ -31,7 +31,7 @@ (intent-contractile (version "1.0.0") - (repo "rescript-evangeliser") + (repo "nextgen-languages-evangeliser") ; === Purpose (what this repo IS) === (purpose diff --git a/.machine_readable/META.a2ml b/.machine_readable/META.a2ml index f8ad94f..4a6617f 100644 --- a/.machine_readable/META.a2ml +++ b/.machine_readable/META.a2ml @@ -1,10 +1,10 @@ ;; SPDX-License-Identifier: PMPL-1.0-or-later -;; META.a2ml — rescript-evangeliser meta-information +;; META.a2ml — nextgen-languages-evangeliser meta-information ;; Migrated from root META.scm on 2026-04-12 (meta (version "1.0.0") - (project "rescript-evangeliser") + (project "nextgen-languages-evangeliser") (architecture-decisions ()) (development-practices (code-style "standard") diff --git a/.machine_readable/MUST.contractile b/.machine_readable/MUST.contractile index 027fd8e..42f33f6 100644 --- a/.machine_readable/MUST.contractile +++ b/.machine_readable/MUST.contractile @@ -1,5 +1,5 @@ ; SPDX-License-Identifier: PMPL-1.0-or-later -; MUST.contractile — Baseline invariants for rescript-evangeliser +; MUST.contractile — Baseline invariants for nextgen-languages-evangeliser ; These constraints MUST NOT be violated. K9 validators enforce them. ; ; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST @@ -33,7 +33,7 @@ (must-contractile (version "1.0.0") - (repo "rescript-evangeliser") + (repo "nextgen-languages-evangeliser") ; === Universal Invariants (apply to ALL repos) === diff --git a/.machine_readable/STATE.a2ml b/.machine_readable/STATE.a2ml index ead0b7c..12f3b18 100644 --- a/.machine_readable/STATE.a2ml +++ b/.machine_readable/STATE.a2ml @@ -1,26 +1,42 @@ ;; SPDX-License-Identifier: PMPL-1.0-or-later -;; STATE.a2ml — rescript-evangeliser project state +;; STATE.a2ml — nextgen-languages-evangeliser project state ;; Migrated from root STATE.scm on 2026-04-12 +;; Renamed from rescript-evangeliser on 2026-04-16 (state (metadata - (version "1.0.0") - (project "rescript-evangeliser") - (last-updated "2026-01-10")) + (version "1.1.0") + (project "nextgen-languages-evangeliser") + (predecessor "rescript-evangeliser") + (last-updated "2026-04-16")) (current-position - (phase "Active Development") - (overall-completion 50) - (working-features ())) + (phase "Migration: Phase 1 — rebrand + engine generalisation") + (overall-completion 55) + (working-features + "ReScript target catalogue (52 patterns, 21 categories)" + "Scanner + Analyser detection engine" + "Narrative generation with 'You were close!' voice" + "Makaton-inspired glyph system" + "CLI: scan / patterns / legend / stats" + "RAW/FOLDED/GLYPHED view layers; plain/markdown/html outputs")) (route-to-mvp (milestones - (v1.0 - (items "Initial setup" "Core functionality") - (status "in-progress")))) + (phase-0 (status "complete") (items "Decide pivot strategy" "Verify AffineScript toolchain")) + (phase-1 (status "in-progress") (items "Rebrand docs+metadata" "Generalise Types.res for multi-target")) + (phase-2 (status "pending") (items "Author AffineScript pattern catalogue (affine/linear safety)")) + (phase-3 (status "gated") (items "Host port ReScript -> AffineScript" "Gate: AffineScript->typed-wasm->WASM proof-of-life")) + (phase-4 (status "pending") (items "Policy perimeter flip" "ts-blocker + .res exception for legacy")) + (phase-5 (status "pending") (items "Additional targets: Rust, Gleam, Zig")))) - (blockers-and-issues ()) + (blockers-and-issues + "AffineScript WASM codegen backend parity incomplete (Phase 3 gate)" + "GitHub repo rename still needs manual action by maintainer") - (critical-next-actions ()) + (critical-next-actions + "Complete Phase 1a rebrand commit" + "Complete Phase 1b engine generalisation (Types.res -> multi-target)") - (session-history ())) + (session-history + (2026-04-16 "Phase 0 decisions locked; Phase 1 started; branch claude/migrate-to-affinescript-zig-U0iYX"))) diff --git a/.machine_readable/TRUST.contractile b/.machine_readable/TRUST.contractile index 9262f53..aca269d 100644 --- a/.machine_readable/TRUST.contractile +++ b/.machine_readable/TRUST.contractile @@ -1,5 +1,5 @@ ; SPDX-License-Identifier: PMPL-1.0-or-later -; TRUST.contractile — Trust boundaries for rescript-evangeliser +; TRUST.contractile — Trust boundaries for nextgen-languages-evangeliser ; Defines what LLM/SLM agents are trusted to do without asking. ; ; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST @@ -35,7 +35,7 @@ (trust-contractile (version "1.0.0") - (repo "rescript-evangeliser") + (repo "nextgen-languages-evangeliser") (trust-level "maximal") ; maximal | standard | restricted | minimal diff --git a/.well-known/security.txt b/.well-known/security.txt index e9c3166..d575ca6 100644 --- a/.well-known/security.txt +++ b/.well-known/security.txt @@ -5,5 +5,5 @@ Contact: mailto:j.d.a.jewell@open.ac.uk Expires: 2027-12-31T23:59:59.000Z Preferred-Languages: en -Canonical: https://github.com/hyperpolymath/rescript-evangeliser/.well-known/security.txt -Policy: https://github.com/hyperpolymath/rescript-evangeliser/blob/main/SECURITY.md +Canonical: https://github.com/hyperpolymath/nextgen-languages-evangeliser/.well-known/security.txt +Policy: https://github.com/hyperpolymath/nextgen-languages-evangeliser/blob/main/SECURITY.md diff --git a/0-AI-MANIFEST.a2ml b/0-AI-MANIFEST.a2ml index 8ad63c9..aee35c6 100644 --- a/0-AI-MANIFEST.a2ml +++ b/0-AI-MANIFEST.a2ml @@ -4,7 +4,7 @@ ## WHAT IS THIS? -This is the AI manifest for **[YOUR-REPO-NAME]**. It declares: +This is the AI manifest for **nextgen-languages-evangeliser**. It declares: - Canonical file locations (where things MUST be, and nowhere else) - Critical invariants (rules that must NEVER be violated) - Repository structure and organization @@ -92,7 +92,7 @@ Entry points: This repo follows the **Dual-Track** architecture: ``` -[YOUR-REPO-NAME]/ +nextgen-languages-evangeliser/ ├── 0-AI-MANIFEST.a2ml # THIS FILE (start here) ├── README.adoc # High-level pitch — excitement and awe (Rich Human) ├── EXPLAINME.adoc # Developer deep-dive — how it works (Rich Nerd) diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index f97667e..38a86ca 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -1,7 +1,7 @@ // SPDX-License-Identifier: MPL-2.0-or-later = Changelog -All notable changes to the ReScript Evangeliser project will be documented in this file. +All notable changes to the Nextgen Languages Evangeliser (formerly ReScript Evangeliser) project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). @@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 == [Unreleased] === Added +- Migration to **Nextgen Languages Evangeliser** — multi-target pattern catalogue +- AffineScript added as flagship target (successor to ReScript as the teaching subject) +- Roadmap with 6 migration phases (see `ROADMAP.adoc`) +- Zig formalised as canonical FFI layer; V banned outside V-ecosystem work - ReScript source files (Types.res, Glyphs.res, Narrative.res, Patterns.res) - Deno configuration (deno.json) and build scripts - Mustfile.epx deployment contract @@ -204,13 +208,13 @@ See [humans.txt](.well-known/humans.txt) for contributor recognition. - Watch this repository for releases - Subscribe to GitHub notifications - Follow announcements in GitHub Discussions -- Check the [Releases page](https://github.com/Hyperpolymath/rescript-evangeliser/releases) +- Check the [Releases page](https://github.com/Hyperpolymath/nextgen-languages-evangeliser/releases) --- **Questions about a release?** -Ask in [GitHub Discussions](https://github.com/Hyperpolymath/rescript-evangeliser/discussions) or open an issue. +Ask in [GitHub Discussions](https://github.com/Hyperpolymath/nextgen-languages-evangeliser/discussions) or open an issue. -[Unreleased]: https://github.com/Hyperpolymath/rescript-evangeliser/compare/v0.1.0...HEAD -[0.1.0]: https://github.com/Hyperpolymath/rescript-evangeliser/releases/tag/v0.1.0 +[Unreleased]: https://github.com/Hyperpolymath/nextgen-languages-evangeliser/compare/v0.1.0...HEAD +[0.1.0]: https://github.com/Hyperpolymath/nextgen-languages-evangeliser/releases/tag/v0.1.0 diff --git a/CHANGELOG.md b/CHANGELOG.md index 45943e6..dc2a47e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -All notable changes to the ReScript Evangeliser project will be documented in this file. +All notable changes to the Nextgen Languages Evangeliser project (formerly *ReScript Evangeliser*) will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). @@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added +- Migration to **Nextgen Languages Evangeliser** — multi-target pattern catalogue +- AffineScript added as flagship target (successor to ReScript as the teaching subject) +- Roadmap with 6 migration phases (see `ROADMAP.adoc`) +- Zig formalised as canonical FFI layer; V banned outside V-ecosystem work - ReScript source files (Types.res, Glyphs.res, Narrative.res, Patterns.res) - Deno configuration (deno.json) and build scripts - Mustfile.epx deployment contract @@ -201,13 +205,13 @@ See [humans.txt](.well-known/humans.txt) for contributor recognition. - Watch this repository for releases - Subscribe to GitHub notifications - Follow announcements in GitHub Discussions -- Check the [Releases page](https://github.com/Hyperpolymath/rescript-evangeliser/releases) +- Check the [Releases page](https://github.com/Hyperpolymath/nextgen-languages-evangeliser/releases) --- **Questions about a release?** -Ask in [GitHub Discussions](https://github.com/Hyperpolymath/rescript-evangeliser/discussions) or open an issue. +Ask in [GitHub Discussions](https://github.com/Hyperpolymath/nextgen-languages-evangeliser/discussions) or open an issue. -[Unreleased]: https://github.com/Hyperpolymath/rescript-evangeliser/compare/v0.1.0...HEAD -[0.1.0]: https://github.com/Hyperpolymath/rescript-evangeliser/releases/tag/v0.1.0 +[Unreleased]: https://github.com/Hyperpolymath/nextgen-languages-evangeliser/compare/v0.1.0...HEAD +[0.1.0]: https://github.com/Hyperpolymath/nextgen-languages-evangeliser/releases/tag/v0.1.0 diff --git a/CLAUDE.md b/CLAUDE.md index d5ea21c..9461138 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,57 +2,73 @@ ## Project Overview -**ReScript Evangeliser** is a project dedicated to promoting and advocating for the ReScript programming language. ReScript is a robustly typed language that compiles to efficient and human-readable JavaScript. +**Nextgen Languages Evangeliser** is a pattern detection engine, CLI, and educational toolkit that teaches JavaScript developers next-generation type-safe languages through progressive code transformation — without shame. + +**Flagship target:** AffineScript (affine/linear type system, borrow checking, quantity checking, WASM backend). + +**Supported targets:** AffineScript (flagship), ReScript (legacy), with more to follow (Rust, Gleam, Zig being the likely next additions). + +This project is the successor to *ReScript Evangeliser*. The ReScript pattern library is preserved as a legacy target; active pattern authorship now centres on affine/linear safety concerns teachable from idiomatic JavaScript. ## Project Purpose This repository serves as a resource hub for: -- Educational materials about ReScript -- Example projects and code snippets -- Tools and utilities to help developers adopt ReScript -- Community content to evangelize ReScript's benefits +- Educational materials about next-generation type-safe languages (AffineScript first) +- Pattern catalogues showing equivalent transformations from JavaScript to target languages +- Tools that detect amenable patterns in existing JS and encourage adoption +- Community content that evangelises type-safe coding without shaming incumbent code ## Technology Stack ### Core Technologies -- **ReScript**: Primary application code - compiles to JS, type-safe -- **Deno**: Runtime & package management - replaces Node/npm/bun -- **Nickel**: Configuration language - type-safe config +- **AffineScript** — flagship target language (teaching subject) +- **typed-wasm** — separate repo; AffineScript's downstream codegen layer (AffineScript → typed-wasm → WASM) +- **ReScript** — current host application language (during Phase 1/2 of migration), legacy target +- **Deno** — runtime & package management (replaces Node/npm/bun) +- **Nickel** — configuration language +- **Zig** — FFI bridge (canonical, per `0-AI-MANIFEST.a2ml`) ### Language Policy (Hyperpolymath Standard) **ALLOWED:** -- ReScript (primary application code) +- AffineScript (application code, once Phase 3 port completes) +- ReScript (current application code; demoted to legacy target after Phase 3) - Deno (runtime & package management) +- Zig (FFI, systems code) - Bash/POSIX Shell (scripts, automation) -- JavaScript (only where ReScript cannot - minimal glue code) +- JavaScript (only where ReScript/AffineScript cannot — minimal glue code) - Nickel (configuration) **BANNED:** -- TypeScript (use ReScript) +- TypeScript (use AffineScript or ReScript) - Node.js (use Deno) - npm/bun (use Deno) - Makefile (use justfile) +- V (use Zig, except inside V-ecosystem-specific projects) + +### Key Features to Evangelise + +Per target, the pitch differs. The engine is target-aware: -### Key ReScript Features to Understand -- **Type Safety**: 100% sound type system with excellent inference -- **Fast Compilation**: Compiles to readable JavaScript in milliseconds -- **JavaScript Interop**: Seamless integration with existing JavaScript code -- **Functional Programming**: First-class support for functional patterns -- **Pattern Matching**: Powerful pattern matching with exhaustiveness checking +- **AffineScript (flagship):** affine/linear types, use-at-most-once guarantees, borrow checking, quantity type theory, compile-time resource safety, WASM deployment. +- **ReScript (legacy):** sound type inference, Option/Result, pattern matching, pipe operator, zero-cost JS interop. ## Project Structure ``` -rescript-evangeliser/ -├── src/ # ReScript source files (.res) -│ ├── Types.res # Core type definitions -│ ├── Glyphs.res # Makaton-inspired glyph system -│ ├── Narrative.res # Encouraging narrative generation -│ └── Patterns.res # Pattern library (50+ patterns) -├── scripts/ # Deno build/validation scripts -├── docs/ # Documentation and guides -├── rescript.json # ReScript build configuration +nextgen-languages-evangeliser/ +├── src/ # Application source (ReScript today, AffineScript post-Phase 3) +│ ├── Types.res # Core type model — multi-target pattern representation +│ ├── Glyphs.res # Makaton-inspired glyph system (target-agnostic) +│ ├── Narrative.res # "You were close!" narrative generation (target-aware) +│ ├── Patterns.res # Pattern library (multi-target) +│ ├── Scanner.res # Regex pattern detection engine +│ ├── Analyser.res # Result aggregation and reporting +│ ├── Output.res # RAW/FOLDED/GLYPHED rendering (multi-target) +│ └── Cli.res # CLI entry point +├── test/ # Test suites +├── docs/ # Documentation +├── rescript.json # Host build config (current) ├── deno.json # Deno configuration ├── justfile # Task orchestration (NOT Makefile) ├── Mustfile.epx # Deployment contract @@ -62,26 +78,18 @@ rescript-evangeliser/ ## Development Guidelines ### Code Style -- Follow ReScript's official style guide -- Use meaningful variable and function names -- Prefer pattern matching over if/else when appropriate +- Follow the host language's official style guide (ReScript today; AffineScript post-Phase 3) +- Use meaningful names; prefer pattern matching over if/else - Leverage the type system to make invalid states unrepresentable - Write interface files (.resi) for public APIs - Add SPDX license headers to all source files ### Best Practices -1. **Type-First Design**: Design types before implementation -2. **Immutability**: Prefer immutable data structures -3. **Pure Functions**: Write pure functions when possible -4. **Documentation**: Document complex type definitions and public APIs -5. **Error Handling**: Use Result and Option types instead of exceptions - -### ReScript-Specific Patterns -- Use `@react.component` for React components -- Leverage pipe operator (`->`) for data transformations -- Use labeled arguments for better API clarity -- Prefer records over tuples for structured data -- Use variants for state machines and tagged unions +1. **Type-First Design** — Design types before implementation +2. **Immutability** — Prefer immutable data structures +3. **Pure Functions** — Write pure functions when possible +4. **Documentation** — Document complex type definitions and public APIs +5. **Error Handling** — Use Result and Option types (not exceptions) ## Common Commands @@ -111,61 +119,21 @@ just fmt just validate-rsr ``` -## Working with ReScript - -### Module System -- Each .res file is automatically a module -- Modules are capitalized (filename.res becomes Filename module) -- Use .resi files to define module interfaces -- Modules can be nested using module bindings - -### JavaScript Interop -- Use `@module` for importing JS modules -- Use `@val` for accessing global values -- Use `@send` for calling JS methods -- Raw JS can be embedded with `%%raw()` - -### Type Definitions -- External JavaScript libraries need ReScript bindings -- Create bindings in separate files (e.g., `ExternalLib.res`) -- Consider contributing bindings to @rescript community packages - ## Build System This project uses: - **Deno**: For build scripts and task running - **justfile**: For task orchestration (NOT Makefile) -- **ReScript**: Uses its own compiler (rescript/bsb) - -### Key Configuration Files - -**rescript.json** -```json -{ - "name": "rescript-evangeliser", - "sources": ["src"], - "package-specs": { "module": "es6", "in-source": true }, - "suffix": ".res.js", - "uncurried": true -} -``` - -**deno.json** -```json -{ - "tasks": { - "build": "deno run -A scripts/build.ts", - "validate": "deno run -A scripts/validate.ts" - } -} -``` +- **ReScript**: Current host compiler (bsb) +- **AffineScript**: Planned host compiler post-Phase 3 (OCaml 5.1+, Dune 3.14+; emits typed-wasm IR, which compiles to WASM) ## Dependencies ### Runtime - Deno (latest stable) -- ReScript 11+ +- ReScript 12.2+ (current host) - @rescript/core +- AffineScript compiler (planned, Phase 3+) ### Package Management - **Primary**: Guix (guix.scm) @@ -174,53 +142,64 @@ This project uses: ## Evangelism Goals -1. **Demonstrate Value**: Show concrete benefits of ReScript -2. **Lower Barriers**: Make adoption as easy as possible -3. **Share Success Stories**: Document real-world wins -4. **Build Community**: Foster a welcoming environment -5. **Create Resources**: Provide learning materials and tools +1. **Demonstrate Value** — Show concrete benefits of each supported target +2. **Lower Barriers** — Make adoption as easy as possible +3. **Share Success Stories** — Document real-world wins +4. **Build Community** — Foster a welcoming environment +5. **Create Resources** — Provide learning materials and tools ## Philosophy: "Celebrate Good, Minimize Bad, Show Better" We **never** shame developers. Instead: -1. **Celebrate**: Recognize what their JavaScript does well -2. **Minimize**: Gently acknowledge minor limitations -3. **Better**: Show how ReScript enhances the pattern -4. **Safety**: Explain type-level guarantees -5. **Example**: Provide concrete, encouraging examples +1. **Celebrate** — Recognize what their JavaScript does well +2. **Minimize** — Gently acknowledge minor limitations +3. **Better** — Show how the target language enhances the pattern +4. **Safety** — Explain type-level (and affine/linear) guarantees +5. **Example** — Provide concrete, encouraging examples + +## Migration Status (ReScript → AffineScript) + +This repo is mid-migration from ReScript Evangeliser to Nextgen Languages Evangeliser. Phases: + +- **Phase 0** ✅ — Decide (option A content rewrite, multilang future, rename repo, toolchain verified) +- **Phase 1** 🚧 — Rebrand + generalise engine for multi-target (host stays ReScript) +- **Phase 2** — Pattern catalogue pivot: affine/linear-safety-focused AffineScript patterns +- **Phase 3** — Host language port ReScript → AffineScript (gated on toolchain WASM maturity) +- **Phase 4** — Policy perimeter flip (ts-blocker extended, affinescript linter added) +- **Phase 5** — Zig/V policy text formalisation ## Resources -### Official Documentation +### AffineScript +- Compiler: https://github.com/hyperpolymath/affinescript +- Toolchain: OCaml 5.1+, Dune 3.14+ +- Downstream codegen: typed-wasm (separate repo) → WebAssembly + +### ReScript (legacy target) - [ReScript Documentation](https://rescript-lang.org/docs) - [ReScript Forum](https://forum.rescript-lang.org) - [ReScript GitHub](https://github.com/rescript-lang) -### Community -- ReScript Discord -- Twitter: @rescriptlang -- ReScript Blog - ## Notes for Claude When working on this project: - Prioritize type safety and correctness -- Suggest idiomatic ReScript patterns -- Consider JavaScript interop implications +- Suggest idiomatic patterns for whichever target is being discussed +- Treat AffineScript as the flagship target; ReScript as a well-supported legacy target +- When adding patterns, lead with the AffineScript transformation and keep ReScript as secondary - Help maintain clear documentation - Encourage best practices in evangelism materials -- Focus on making ReScript accessible to newcomers -- Highlight ReScript's unique advantages over TypeScript/JavaScript - **Use Deno, not npm/bun** - **Use justfile, not Makefile** -- **Use ReScript, not TypeScript** +- **Use Zig for FFI, not V (except inside V-ecosystem projects)** +- **Source host language: ReScript during Phases 1-2, AffineScript from Phase 3 onward** - Add SPDX license headers to new source files ## Project Philosophy -**Make ReScript Approachable**: The goal is to help developers discover and adopt ReScript by: -- Showing practical examples +**Make next-generation languages approachable**: The goal is to help developers discover and adopt affine/linear type systems and other nextgen features by: +- Showing practical examples from code they already write - Addressing common concerns - Demonstrating real benefits - Providing migration paths diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index adfb3ca..77a6f1b 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -221,7 +221,7 @@ This Code of Conduct is a **living document** and may be updated based on commun For questions about this Code of Conduct: - **Maintainers**: See [MAINTAINERS.md](MAINTAINERS.md) -- **GitHub Discussions**: [Community forum](https://github.com/Hyperpolymath/rescript-evangeliser/discussions) +- **GitHub Discussions**: [Community forum](https://github.com/Hyperpolymath/nextgen-languages-evangeliser/discussions) --- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 820f7a4..c04d5cb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,9 @@ -# Contributing to ReScript Evangeliser +# Contributing to Nextgen Languages Evangeliser Thank you for your interest in contributing! 🎉 +> **Note:** This project is mid-migration from *ReScript Evangeliser* to *Nextgen Languages Evangeliser* (flagship target: AffineScript). Some sections below still reference the ReScript-centric dev setup — these will be updated through Phases 1–3. See `ROADMAP.adoc`. + This project follows the **Compassionate Code Contribution Pledge (CCCP)** and **Tri-Perimeter Contribution Framework (TPCF) - Perimeter 3**. ## 🌟 Philosophy: "Celebrate Good, Minimize Bad, Show Better" @@ -27,8 +29,8 @@ Our contribution process mirrors our teaching philosophy: ```bash # Fork and clone -git clone https://github.com/YOUR_USERNAME/rescript-evangeliser.git -cd rescript-evangeliser/extension +git clone https://github.com/YOUR_USERNAME/nextgen-languages-evangeliser.git +cd nextgen-languages-evangeliser/extension # Install dependencies npm install @@ -333,7 +335,7 @@ Contributors are recognized in: ## 🎯 Roadmap Priorities -Current priorities (see [GitHub Projects](https://github.com/Hyperpolymath/rescript-evangeliser/projects)): +Current priorities (see [GitHub Projects](https://github.com/Hyperpolymath/nextgen-languages-evangeliser/projects)): 1. **High Priority**: - Expanding pattern library (50 → 100+ patterns) @@ -437,6 +439,6 @@ You retain copyright of your contributions. --- -**Thank you for contributing to ReScript Evangeliser!** 🚀 +**Thank you for contributing to Nextgen Languages Evangeliser!** 🚀 Remember: You were close! We're here to help make it even better together. 💙 diff --git a/EXPLAINME.adoc b/EXPLAINME.adoc index 3c2cc35..774948b 100644 --- a/EXPLAINME.adoc +++ b/EXPLAINME.adoc @@ -1,19 +1,24 @@ // SPDX-License-Identifier: PMPL-1.0-or-later -= ReScript Evangeliser — EXPLAINME += Nextgen Languages Evangeliser — EXPLAINME == Celebrate good, minimize bad, show better [quote, README.adoc] ____ -A pattern detection engine, CLI, and educational toolkit that teaches JavaScript developers ReScript through progressive code transformation, without shame. +A pattern detection engine, CLI, and educational toolkit that teaches JavaScript developers next-generation type-safe languages through progressive code transformation, without shame. ____ -The evangeliser detects 52 patterns across 21 categories in existing JavaScript, then shows equivalent ReScript with encouragement rather than criticism. +The evangeliser detects patterns in existing JavaScript amenable to transformation, then shows equivalent code in one or more target languages — with encouragement rather than criticism. It uses progressive disclosure (RAW, FOLDED, GLYPHED views) and Makaton-inspired glyphs to make concepts visual. See link:README.adoc[] for the full pattern catalogue and quick start. -**Caveat:** The pattern count (52) is the implemented library size in `Patterns.res`. AffineScript evangelism support is early-stage. +**Current state:** this repo is the successor to *ReScript Evangeliser* and is mid-migration. +The ReScript catalogue (originally 52 patterns across 21 categories) is preserved as a legacy target. +Active pattern authorship has pivoted to *AffineScript*, focusing on affine/linear-safety concerns — use-after-free analogs, double-cleanup, aliasing of owned state, missing disposal. +See link:ROADMAP.adoc[] for migration phases. + +**Caveat:** During Phases 1–2 the host language of this toolkit is still ReScript; Phase 3 ports it to AffineScript once the AffineScript → typed-wasm → WASM toolchain is stable enough to carry 2,400+ LOC of production code. === Evidence @@ -22,20 +27,23 @@ See link:README.adoc[] for the full pattern catalogue and quick start. | Path | Proves | `src/Patterns.res` -| 52 pattern definitions across 21 categories -- the core detection library +| Multi-target pattern library — ReScript (legacy) and AffineScript (flagship) transformations, plus slots for future targets | `src/Analyser.res` / `src/Analyser.resi` -| Pattern analysis engine with public interface -- takes JS, returns matches +| Pattern analysis engine with public interface — takes JS, returns matches (target-aware) | `src/Narrative.res` -| "You were close!" encouragement narratives -- the shame-free philosophy in code +| "You were close!" encouragement narratives, per target — the shame-free philosophy in code | `src/Glyphs.res` -| Makaton-inspired glyph system -- visual concept representation +| Makaton-inspired glyph system — visual concept representation (target-agnostic) | `src/Scanner.res` / `src/Scanner.resi` -| File/project scanner with public interface -- batch analysis entry point +| File/project scanner with public interface — batch analysis entry point | `src/Output.res` -| Three output formats (plain, markdown, html) -- progressive disclosure +| Three output formats (plain, markdown, html) and three view layers (RAW, FOLDED, GLYPHED), per target + +| `src/Cli.res` +| CLI entry point: `scan`, `patterns`, `legend`, `stats` with `--target` selection |=== diff --git a/Justfile b/Justfile index e0eec40..a7caa0e 100644 --- a/Justfile +++ b/Justfile @@ -1,4 +1,4 @@ -# justfile for ReScript Evangeliser +# justfile for Nextgen Languages Evangeliser # https://github.com/casey/just # SPDX-License-Identifier: MIT OR Palimpsest-0.8 # @@ -194,7 +194,7 @@ help RECIPE: # Self-diagnostic — checks dependencies, permissions, paths doctor: - @echo "Running diagnostics for rescript-evangeliser..." + @echo "Running diagnostics for nextgen-languages-evangeliser..." @echo "Checking required tools..." @command -v just >/dev/null 2>&1 && echo " [OK] just" || echo " [FAIL] just not found" @command -v git >/dev/null 2>&1 && echo " [OK] git" || echo " [FAIL] git not found" @@ -204,7 +204,7 @@ doctor: # Auto-repair common issues heal: - @echo "Attempting auto-repair for rescript-evangeliser..." + @echo "Attempting auto-repair for nextgen-languages-evangeliser..." @echo "Fixing permissions..." @find . -name "*.sh" -exec chmod +x {} \; 2>/dev/null || true @echo "Cleaning stale caches..." @@ -213,7 +213,7 @@ heal: # Guided tour of key features tour: - @echo "=== rescript-evangeliser Tour ===" + @echo "=== nextgen-languages-evangeliser Tour ===" @echo "" @echo "1. Project structure:" @ls -la @@ -228,12 +228,12 @@ tour: # Open feedback channel with diagnostic context help-me: - @echo "=== rescript-evangeliser Help ===" + @echo "=== nextgen-languages-evangeliser Help ===" @echo "Platform: $(uname -s) $(uname -m)" @echo "Shell: $SHELL" @echo "" @echo "To report an issue:" - @echo " https://github.com/hyperpolymath/rescript-evangeliser/issues/new" + @echo " https://github.com/hyperpolymath/nextgen-languages-evangeliser/issues/new" @echo "" @echo "Include the output of 'just doctor' in your report." diff --git a/MAINTAINERS.md b/MAINTAINERS.md index a83519f..0261116 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -1,6 +1,6 @@ # Maintainers -This document lists the current maintainers of the ReScript Evangeliser project and describes their roles and responsibilities. +This document lists the current maintainers of the Nextgen Languages Evangeliser project (formerly ReScript Evangeliser) and describes their roles and responsibilities. ## Current Maintainers diff --git a/Mustfile.epx b/Mustfile.epx index d47f3c5..19c9fdf 100644 --- a/Mustfile.epx +++ b/Mustfile.epx @@ -1,4 +1,4 @@ -# Mustfile.epx - Deployment Contract for ReScript Evangeliser +# Mustfile.epx - Deployment Contract for Nextgen Languages Evangeliser # SPDX-License-Identifier: MIT OR Palimpsest-0.8 # # This file defines the physical state transitions for deployment. @@ -6,7 +6,7 @@ # See: https://github.com/hyperpolymath/mustfile version: "0.1.0" -name: rescript-evangeliser +name: nextgen-languages-evangeliser # Package manager routing package_managers: diff --git a/QUICKSTART-DEV.adoc b/QUICKSTART-DEV.adoc index cde2672..f5b1c61 100644 --- a/QUICKSTART-DEV.adoc +++ b/QUICKSTART-DEV.adoc @@ -1,7 +1,7 @@ // SPDX-License-Identifier: PMPL-1.0-or-later // Template: QUICKSTART-DEV.adoc — clone → build → test → PR -// Replace rescript-evangeliser, {{BUILD_CMD}}, {{TEST_CMD}}, {{LANG_STACK}} with actuals -= rescript-evangeliser — Quick Start for Developers +// Replace nextgen-languages-evangeliser, {{BUILD_CMD}}, {{TEST_CMD}}, {{LANG_STACK}} with actuals += nextgen-languages-evangeliser — Quick Start for Developers :toc: :toclevels: 2 @@ -29,8 +29,8 @@ nix develop [source,bash] ---- -git clone https://github.com/hyperpolymath/rescript-evangeliser.git -cd rescript-evangeliser +git clone https://github.com/hyperpolymath/nextgen-languages-evangeliser.git +cd nextgen-languages-evangeliser just setup-dev ---- @@ -52,7 +52,7 @@ just setup-dev [source] ---- -rescript-evangeliser/ +nextgen-languages-evangeliser/ ├── src/ # Source code ├── src/abi/ # Idris2 ABI definitions (if applicable) ├── ffi/zig/ # Zig FFI bridge (if applicable) @@ -107,5 +107,5 @@ Or read `0-AI-MANIFEST.a2ml` and `.claude/CLAUDE.md` directly. == Get Help * **Architecture**: link:EXPLAINME.adoc[EXPLAINME.adoc] -* **Wiki**: https://github.com/hyperpolymath/rescript-evangeliser/wiki +* **Wiki**: https://github.com/hyperpolymath/nextgen-languages-evangeliser/wiki * **Report issue**: `just help-me` diff --git a/QUICKSTART-MAINTAINER.adoc b/QUICKSTART-MAINTAINER.adoc index e5a8dcf..218e88d 100644 --- a/QUICKSTART-MAINTAINER.adoc +++ b/QUICKSTART-MAINTAINER.adoc @@ -1,13 +1,13 @@ // SPDX-License-Identifier: PMPL-1.0-or-later // Template: QUICKSTART-MAINTAINER.adoc — packaging, deploying, and maintaining -// Replace rescript-evangeliser, {{PACKAGE_NAME}}, {{DEPS}} with actuals -= rescript-evangeliser — Quick Start for Platform Maintainers +// Replace nextgen-languages-evangeliser, {{PACKAGE_NAME}}, {{DEPS}} with actuals += nextgen-languages-evangeliser — Quick Start for Platform Maintainers :toc: :toclevels: 2 == Overview -This guide covers packaging, deploying, and maintaining rescript-evangeliser for +This guide covers packaging, deploying, and maintaining nextgen-languages-evangeliser for distribution on your platform. == Runtime Dependencies @@ -18,8 +18,8 @@ distribution on your platform. [source,bash] ---- -git clone https://github.com/hyperpolymath/rescript-evangeliser.git -cd rescript-evangeliser +git clone https://github.com/hyperpolymath/nextgen-languages-evangeliser.git +cd nextgen-languages-evangeliser just build-release ---- @@ -46,7 +46,7 @@ nix build [source,bash] ---- just stapeln-export # Generates Containerfile -podman build -t rescript-evangeliser . +podman build -t nextgen-languages-evangeliser . ---- === Manual Package @@ -125,5 +125,5 @@ Each instance has isolated config, data, and logs. == Reporting Issues -* Upstream: https://github.com/hyperpolymath/rescript-evangeliser/issues +* Upstream: https://github.com/hyperpolymath/nextgen-languages-evangeliser/issues * With diagnostic: `just help-me` (pre-fills context) diff --git a/QUICKSTART-USER.adoc b/QUICKSTART-USER.adoc index 5273f06..a82760a 100644 --- a/QUICKSTART-USER.adoc +++ b/QUICKSTART-USER.adoc @@ -1,13 +1,13 @@ // SPDX-License-Identifier: PMPL-1.0-or-later // Template: QUICKSTART-USER.adoc — 5-minute path to working software -// Replace rescript-evangeliser, Rescript Evangeliser — See README.adoc for details., just run, Rescript Evangeliser started successfully. with actuals -= rescript-evangeliser — Quick Start for Users +// Replace nextgen-languages-evangeliser, Nextgen Languages Evangeliser — See README.adoc for details., just run, Nextgen Languages Evangeliser started successfully. with actuals += nextgen-languages-evangeliser — Quick Start for Users :toc: :toclevels: 2 -== What is rescript-evangeliser? +== What is nextgen-languages-evangeliser? -Rescript Evangeliser — See README.adoc for details. +Nextgen Languages Evangeliser — See README.adoc for details. == Prerequisites @@ -37,8 +37,8 @@ Before you begin, ensure you have: [source,bash] ---- # Clone and set up -git clone https://github.com/hyperpolymath/rescript-evangeliser.git -cd rescript-evangeliser +git clone https://github.com/hyperpolymath/nextgen-languages-evangeliser.git +cd nextgen-languages-evangeliser just setup ---- @@ -61,7 +61,7 @@ just stapeln-run [source,bash] ---- -just install --portable --prefix=./rescript-evangeliser-portable +just install --portable --prefix=./nextgen-languages-evangeliser-portable ---- == First Run @@ -75,7 +75,7 @@ Expected output: [source] ---- -Rescript Evangeliser started successfully. +Nextgen Languages Evangeliser started successfully. ---- == Self-Diagnostic @@ -102,7 +102,7 @@ just heal * **In-app**: `just run --help` * **Guided tour**: `just tour` * **Report a problem**: `just help-me` (pre-fills diagnostic context) -* **Wiki**: https://github.com/hyperpolymath/rescript-evangeliser/wiki +* **Wiki**: https://github.com/hyperpolymath/nextgen-languages-evangeliser/wiki == Uninstall diff --git a/README.adoc b/README.adoc index f724352..2e12078 100644 --- a/README.adoc +++ b/README.adoc @@ -1,4 +1,4 @@ -= ReScript (and AffineScript) Evangeliser += Nextgen Languages Evangeliser image:https://img.shields.io/badge/RSR-Bronze-CD7F32[RSR Bronze,link=docs/RSR_COMPLIANCE.md] image:https://img.shields.io/badge/License-PMPL--1.0--or--later-blue.svg[License: PMPL-1.0-or-later,link="https://github.com/hyperpolymath/palimpsest-license"] @@ -6,47 +6,57 @@ image:https://img.shields.io/badge/License-PMPL--1.0--or--later-blue.svg[License // SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell image:[TPCF: Perimeter 3,link=docs/TPCF.md] -image:[ReScript First] +image:[AffineScript First] image:https://img.shields.io/badge/Deno-Runtime-000000.svg[Deno Runtime] -> *Celebrate good, minimize bad, show better* -- A pattern detection engine, CLI, and educational toolkit that teaches JavaScript developers ReScript through progressive code transformation, without shame. +> *Celebrate good, minimize bad, show better* -- A pattern detection engine, CLI, and educational toolkit that teaches JavaScript developers next-generation type-safe languages through progressive code transformation, without shame. + +NOTE: This project is the successor to *ReScript Evangeliser*. The ReScript catalogue is preserved as a legacy target while we pivot the flagship to *AffineScript*. See link:ROADMAP.adoc[ROADMAP.adoc] for migration phases. == What is This? -ReScript Evangeliser is a library and toolkit that helps JavaScript developers learn ReScript by: +Nextgen Languages Evangeliser is a library and toolkit that helps JavaScript developers learn affine/linear-typed and other next-generation languages by: -* *Detecting patterns* in existing JS code (52 patterns across 21 categories) -* *Showing transformations* to equivalent ReScript code +* *Detecting patterns* in existing JS code amenable to transformation +* *Showing transformations* to equivalent code in each supported target * *Explaining with encouragement* using the "You were close!" philosophy * *Visualizing concepts* with Makaton-inspired glyphs * *Progressive disclosure* through 3 view layers (RAW -> FOLDED -> GLYPHED) and 3 output formats (plain, markdown, html) -*We never shame developers.* Your JavaScript is good! ReScript just makes some things even better. +*We never shame developers.* Your JavaScript is good! Next-generation type systems just make some things even safer. + +=== Supported targets -For those TypeScript, CoffeScript, and other developer looking for true type safety, we hope to give the opportunity to extend your code to touch those areas that TypeScript cannot reach (for reasons of history and path dependency). We hope the Evangeliser can work out ways to plug the gaps that can't be filled and, in that very rare case, to encourage you to make the leap to a life embracing TypeScriptm. +[cols="2,2,3"] +|=== +|*Target* |*Status* |*Pitch* -And for those [UTTER NUTCASES] who want to try to explore the power and overcome the complexity of learning AffineScript, well, we have started to embrace that project too - -A work in progress, but we would love to invite you to join us in building the next generation of type safe, affine coding. +|*AffineScript* |Flagship |Affine/linear types, borrow checking, quantity type theory; emits typed-wasm (separate repo) -> WebAssembly +|*ReScript* |Legacy (maintained) |Sound inference, Option/Result, pattern matching, JS interop +|*Rust, Gleam, Zig, …* |Planned |Roadmap — see link:ROADMAP.adoc[ROADMAP.adoc] +|=== + +For those on TypeScript or CoffeeScript: we want to help you reach type-safety guarantees the incumbent tooling cannot give you — without making you throw your existing code away. For the adventurous who want to explore AffineScript's affine/linear guarantees from scratch, this repo is aimed at you. == Quick Start === Prerequisites * https://deno.land[Deno] (latest stable) -* https://rescript-lang.org[ReScript] 12.2+ +* https://rescript-lang.org[ReScript] 12.2+ (current host language; see link:ROADMAP.adoc[ROADMAP.adoc] for AffineScript port) === Installation [source,bash] ---- # Clone the repository -git clone https://github.com/hyperpolymath/rescript-evangeliser.git -cd rescript-evangeliser +git clone https://github.com/hyperpolymath/nextgen-languages-evangeliser.git +cd nextgen-languages-evangeliser # Install dependencies just install -# Build ReScript sources +# Build host sources just build ---- @@ -57,7 +67,7 @@ just build # Scan a JavaScript file for patterns deno run --allow-read bin/evangeliser.js scan -# List all 52 available patterns +# List all available patterns (with their target languages) deno run --allow-read bin/evangeliser.js patterns # Show the glyph legend @@ -71,7 +81,7 @@ deno run --allow-read bin/evangeliser.js stats [source,bash] ---- -# Run tests (38 tests across 6 suites) +# Run tests just test # Watch mode for development @@ -86,22 +96,25 @@ just ci == Features -=== 52 Transformation Patterns +=== Multi-target Pattern Catalogue + +Each pattern carries example transformations for multiple target languages. Categories include: -Categories include: +* Null safety -> Option types (ReScript) / total functions (AffineScript) +* Resource management -> affine ownership (AffineScript) / explicit disposal +* Aliasing of mutable state -> borrow checking (AffineScript) +* Async/await -> Promise types / effect systems +* Try/catch -> Result types / typed error channels +* Array operations -> pipe operator / iterator patterns +* Conditionals -> pattern matching / total case analysis +* OOP -> functional programming / records over classes +* ...and more -* Null safety -> Option types -* Async/await -> Promise types -* Try/catch -> Result types -* Array operations -> Pipe operator -* Conditionals -> Pattern matching -* OOP -> Functional programming -* Classes -> Records -* And 14 more categories (21 total) +The AffineScript catalogue prioritises affine/linear-safety patterns: use-after-free analogs, double-cleanup, detached references, accidental aliasing of owned state, missing `using`/disposal, and similar concerns that the type system can make unrepresentable. === Three View Layers -1. *RAW*: Side-by-side JavaScript/ReScript comparison with narrative +1. *RAW*: Side-by-side JavaScript/target comparison with narrative 2. *FOLDED*: Organized sections with collapsible regions 3. *GLYPHED*: Symbol-annotated code showing semantic meaning @@ -120,22 +133,25 @@ Visual symbols that transcend syntax across 21 glyph categories: * Flow (pipe operator) * Branch (pattern matching) * Crystal (immutability) -* And 16 more +* Seal (affine ownership) +* ...and more === Scanner + Analyser Detection Engine -Regex-based pattern matching engine that scans JavaScript source files and identifies patterns amenable to ReScript transformation. The Analyser aggregates Scanner results into categorised reports with narrative explanations. +Regex-based pattern matching engine that scans JavaScript source files and identifies patterns amenable to transformation. The Analyser aggregates Scanner results into categorised reports with narrative explanations per-target. === CLI Interface -Four commands: `scan`, `patterns`, `legend`, `stats`. Supports RAW/FOLDED/GLYPHED view layers and plain/markdown/html output formats. +Four commands: `scan`, `patterns`, `legend`, `stats`. Supports RAW/FOLDED/GLYPHED view layers, plain/markdown/html output formats, and `--target` selection. == Technology Stack === Primary Technologies -* *ReScript 12.2*: All application logic (Types, Glyphs, Narrative, Patterns, Scanner, Analyser, Output, CLI) +* *ReScript 12.2* (current host): All application logic (Types, Glyphs, Narrative, Patterns, Scanner, Analyser, Output, CLI) +* *AffineScript* (planned host, Phase 3+): OCaml 5.1+ toolchain; emits typed-wasm IR (separate repo) -> WebAssembly * *Deno*: Runtime and package management +* *Zig*: FFI layer (canonical per manifest) === Language Policy @@ -145,39 +161,35 @@ Per Hyperpolymath Standard: |=== |*Allowed* |*Banned* -|ReScript |TypeScript +|AffineScript, ReScript |TypeScript |Deno |Node.js/npm/bun |justfile |Makefile +|Zig (FFI) |V (outside V ecosystem) |=== +See link:CLAUDE.md[CLAUDE.md] and link:.claude/CLAUDE.md[.claude/CLAUDE.md] for the full policy. + == Project Structure [source] ---- -rescript-evangeliser/ -+-- src/ # ReScript source files -| +-- Types.res # Core type definitions +nextgen-languages-evangeliser/ ++-- src/ # Host source (ReScript today, AffineScript post-Phase 3) +| +-- Types.res # Core type model (multi-target) | +-- Glyphs.res # Makaton-inspired symbol system -| +-- Narrative.res # Encouraging message generation -| +-- Patterns.res # 52 transformation patterns +| +-- Narrative.res # Encouraging message generation (target-aware) +| +-- Patterns.res # Multi-target transformation patterns | +-- Scanner.res # Pattern detection engine | +-- Scanner.resi # Scanner interface | +-- Analyser.res # Result aggregation and reporting | +-- Analyser.resi # Analyser interface -| +-- Output.res # RAW/FOLDED/GLYPHED formatting +| +-- Output.res # RAW/FOLDED/GLYPHED formatting (multi-target) | +-- Cli.res # CLI entry point (scan/patterns/legend/stats) +-- test/ # Test suites -| +-- Types_test.res # Types tests -| +-- Glyphs_test.res # Glyphs tests -| +-- Narrative_test.res # Narrative tests -| +-- Patterns_test.res # Patterns tests -| +-- Scanner_test.res # Scanner tests -| +-- Analyser_test.res # Analyser tests -| +-- run_all.js # Deno test runner +-- bin/ | +-- evangeliser.js # CLI entry point +-- docs/ # Documentation -+-- rescript.json # ReScript configuration ++-- rescript.json # Host (ReScript) configuration +-- deno.json # Deno configuration +-- justfile # Task orchestration +-- Mustfile.epx # Deployment contract @@ -191,11 +203,11 @@ We *never* shame developers. Instead: 1. *Celebrate*: Recognize what their JavaScript does well 2. *Minimize*: Gently acknowledge minor limitations -3. *Better*: Show how ReScript enhances the pattern -4. *Safety*: Explain type-level guarantees +3. *Better*: Show how the target language enhances the pattern +4. *Safety*: Explain type-level (and affine/linear) guarantees 5. *Example*: Provide concrete, encouraging examples -Example narrative: +Example narrative (ReScript target): ____ *You were close!* You're already thinking about null and undefined - that's great defensive programming! @@ -205,11 +217,21 @@ The only small thing is that it's easy to forget one of these checks somewhere.. *Even better:* ReScript's Option type makes null safety automatic - you literally can't forget a check! ____ +Example narrative (AffineScript target): + +____ +*You were close!* You're already disposing of the resource in a `finally` block - that's careful code! + +The only small thing is that if another closure still holds a reference, the dispose runs but the alias lives on... + +*Even better:* AffineScript's affine types make the resource vanish from the type environment at disposal - no alias can survive, no double-free can compile. +____ + == RSR Compliance This project follows the *Rhodium Standard Repository (RSR)* framework: -* *Type Safety*: ReScript 12.2 with 100% sound type system +* *Type Safety*: ReScript 12.2 host today; AffineScript (affine/linear types, borrow checking) post-Phase 3 * *Offline First*: Zero network dependencies * *Complete Documentation*: See link:docs/[docs/] * *Security First*: See link:SECURITY.md[SECURITY.md] @@ -227,6 +249,7 @@ See link:docs/RSR_COMPLIANCE.md[RSR_COMPLIANCE.md] for full details. * link:CHANGELOG.md[CHANGELOG.md] - Version history * link:docs/RSR_COMPLIANCE.md[RSR_COMPLIANCE.md] - RSR framework compliance * link:docs/TPCF.md[TPCF.md] - Contribution framework +* link:ROADMAP.adoc[ROADMAP.adoc] - Migration phases & future targets == Contributing @@ -234,7 +257,7 @@ We welcome contributions! See link:CONTRIBUTING.md[CONTRIBUTING.md] for: * Code of Conduct * Development setup -* Pattern authoring guide +* Pattern authoring guide (multi-target) * Testing requirements * Pull request process @@ -250,12 +273,12 @@ See link:LICENSE[LICENSE] for the full license text. == Roadmap -* [x] Phase 1: Foundation -- Types, Glyphs, Narrative modules -* [x] Phase 2: Pattern library -- 52 patterns across 21 categories -* [x] Phase 3: Detection engine -- Scanner + Analyser -* [x] Phase 4: Testing -- 38 tests across 6 suites -* [x] Phase 5: CLI interface -- scan/patterns/legend/stats commands -* [ ] Phase 6: VS Code extension / PanLL integration +* [x] Phase 0: Decide migration path (option A content rewrite, multilanguage future) +* [-] Phase 1: Rebrand + generalise engine for multi-target (host stays ReScript) +* [ ] Phase 2: Pattern catalogue pivot — affine/linear-safety-focused AffineScript patterns +* [ ] Phase 3: Host language port (ReScript -> AffineScript), gated on toolchain WASM maturity +* [ ] Phase 4: Policy perimeter flip (ts-blocker extended, affinescript linter added) +* [ ] Phase 5: Zig/V policy formalisation; additional targets (Rust, Gleam) See link:ROADMAP.adoc[ROADMAP.adoc] for detailed milestones. @@ -265,40 +288,41 @@ If you use this project in academic research, please cite: [source,bibtex] ---- -@software{rescript_evangeliser_2026, - title = {ReScript Evangeliser: Progressive Code Transformation for Learning}, +@software{nextgen_languages_evangeliser_2026, + title = {Nextgen Languages Evangeliser: Progressive Code Transformation for Affine/Linear-Typed Languages}, author = {Jonathan D.A. Jewell}, year = {2026}, - url = {https://github.com/hyperpolymath/rescript-evangeliser}, - note = {RSR Bronze-compliant, TPCF Perimeter 3} + url = {https://github.com/hyperpolymath/nextgen-languages-evangeliser}, + note = {Successor to rescript-evangeliser; RSR Bronze-compliant, TPCF Perimeter 3} } ---- == Community -* *GitHub*: https://github.com/hyperpolymath/rescript-evangeliser/issues[Issues] and https://github.com/hyperpolymath/rescript-evangeliser/discussions[Discussions] +* *GitHub*: https://github.com/hyperpolymath/nextgen-languages-evangeliser/issues[Issues] and https://github.com/hyperpolymath/nextgen-languages-evangeliser/discussions[Discussions] +* *AffineScript*: https://github.com/hyperpolymath/affinescript[hyperpolymath/affinescript] * *ReScript Forum*: https://forum.rescript-lang.org[forum.rescript-lang.org] -* *Discord*: ReScript community server == Acknowledgments -* *ReScript Team*: For creating an amazing language +* *AffineScript Team*: For the flagship target — affine/linear types, borrow checker, QTT +* *ReScript Team*: For seeding this evangeliser's original catalogue and philosophy * *Makaton*: Inspiration for the glyph system * *Deno Team*: For the excellent runtime * *Contributors*: See link:.well-known/humans.txt[humans.txt] == Status -* *Version*: 0.5.0 (Alpha) +* *Version*: 0.6.0-alpha (migrating from rescript-evangeliser 0.5.x) * *RSR Level*: Bronze -* *Patterns*: 52 across 21 categories -* *Tests*: 38 across 6 suites -* *CI Workflows*: 12, all passing +* *Targets*: 2 active (AffineScript flagship, ReScript legacy), more planned +* *Tests*: 38 across 6 suites (being updated for multi-target) +* *CI Workflows*: 16, all passing * *Build Status*: Passing -* *Last Updated*: 2026-03-13 +* *Last Updated*: 2026-04-16 --- -Made with care for JavaScript developers curious about ReScript. +Made with care for JavaScript developers curious about next-generation languages. *Remember*: You were close! diff --git a/ROADMAP.adoc b/ROADMAP.adoc index 39da9fe..8522978 100644 --- a/ROADMAP.adoc +++ b/ROADMAP.adoc @@ -1,22 +1,62 @@ // SPDX-License-Identifier: MPL-2.0-or-later -= Rescript Evangeliser Roadmap += Nextgen Languages Evangeliser — Roadmap == Current Status -Initial development phase. +Migration from *ReScript Evangeliser* to *Nextgen Languages Evangeliser* — Phase 1 in progress. -== Milestones +See link:CLAUDE.md[CLAUDE.md] and link:README.adoc[README.adoc] for project overview. -=== v0.1.0 - Foundation -* [ ] Core functionality -* [ ] Basic documentation -* [ ] CI/CD pipeline +== Migration Phases -=== v1.0.0 - Stable Release -* [ ] Full feature set -* [ ] Comprehensive tests -* [ ] Production ready +=== Phase 0 — Decide +* [x] Pick pivot strategy: Option A (content rewrite, not mechanical translation) +* [x] Commit to multilanguage future (flagship AffineScript, legacy ReScript, more to follow) +* [x] Rename repo: `rescript-evangeliser` -> `nextgen-languages-evangeliser` +* [x] Verify AffineScript toolchain buildable today (OCaml 5.1+, Dune 3.14+) +* [x] Note: typed-wasm is a separate repo (downstream of AffineScript) + +=== Phase 1 — Rebrand + generalise engine +* [-] Rebrand docs, metadata, contractiles, config files +* [ ] Generalise `src/Types.res` for multi-target pattern representation +* [ ] Thread multi-target through Narrative / Output / Analyser / CLI +* [ ] Convert `src/Patterns.res` to multi-target shape (ReScript + AffineScript stub) +* [ ] Update tests +* [ ] Host language stays ReScript throughout + +=== Phase 2 — Pattern catalogue pivot +* [ ] Design AffineScript-first catalogue around affine/linear safety concerns: + ** Use-after-free analogs (stale closures, detached refs) + ** Double-cleanup / double-free analogs + ** Accidental aliasing of owned state + ** Missing `using`/disposal, leaky listeners/timers + ** Resource sharing across async boundaries +* [ ] Target ~12 curated patterns initially (depth over breadth) +* [ ] Demote ReScript catalogue to legacy support +* [ ] Preserve "You were close!" narrative voice + +=== Phase 3 — Host language port (gated on toolchain) +* [ ] End-to-end "hello world -> typed-wasm -> WASM" proof-of-life +* [ ] Port `src/` ReScript -> AffineScript module-by-module: + Types, Glyphs, Narrative, Scanner, Analyser, Output, Cli, Patterns (last) +* [ ] Port `test/` in lockstep + +=== Phase 4 — Policy perimeter flip +* [ ] Extend `ts-blocker.yml` to also reject new `.res` files outside `legacy/` +* [ ] Add `affinescript-linter.yml` workflow +* [ ] `justfile` recipe names stable, invocations swapped +* [ ] Retire `rescript.json` (or demote to legacy) + +=== Phase 5 — Policy text + additional targets +* [ ] `.claude/CLAUDE.md`: formalise V-in-ecosystem-only carveout +* [ ] Zig as canonical FFI (no code change — already true per manifest) +* [ ] Additional target backends: Rust, Gleam, Zig == Future Directions -_To be determined based on community feedback._ +After Phase 5, the project becomes a general-purpose evangelisation platform for nextgen typed languages, with: + +* A shared engine (Scanner, Analyser, Output, Narrative) target-agnostic +* Per-target catalogues authored by language advocates +* Glyph system treated as a lingua franca across targets +* Citation-stable URL via GitHub redirect from legacy `rescript-evangeliser` slug diff --git a/SECURITY.md b/SECURITY.md index a486e94..716bebc 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,7 +2,7 @@ ## 🛡️ Security Philosophy -Security is a **first-class concern** in ReScript Evangeliser. We follow a **10+ dimensional security model**: +Security is a **first-class concern** in Nextgen Languages Evangeliser. We follow a **10+ dimensional security model**: 1. **Input Validation** - All user input is validated and sanitized 2. **Output Encoding** - Code transformations are safe from injection @@ -75,7 +75,7 @@ Security issues include: └─────────────────────────────────────────┘ ↓ (sandboxed parsing) ┌─────────────────────────────────────────┐ -│ ReScript Evangeliser Extension │ +│ Nextgen Languages Evangeliser Extension │ │ ├─ AST Parser (Babel, sandboxed) │ │ ├─ Pattern Matcher (validated) │ │ ├─ Webview (Content Security Policy) │ @@ -246,7 +246,7 @@ Security updates are released as soon as possible: - **Low**: Next regular release Subscribe to releases to stay informed: -https://github.com/Hyperpolymath/rescript-evangeliser/releases +https://github.com/Hyperpolymath/nextgen-languages-evangeliser/releases ## 📞 Contact diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md index d587df2..c803fe0 100644 --- a/TEST-NEEDS.md +++ b/TEST-NEEDS.md @@ -1,4 +1,4 @@ -# TEST-NEEDS.md — rescript-evangeliser +# TEST-NEEDS.md — nextgen-languages-evangeliser ## CRG Grade: C — ACHIEVED 2026-04-04 @@ -28,5 +28,5 @@ ## Run Tests ```bash -cd /var/mnt/eclipse/repos/rescript-evangeliser && rescript build && npm test +cd /var/mnt/eclipse/repos/nextgen-languages-evangeliser && rescript build && npm test ``` diff --git a/TOPOLOGY.md b/TOPOLOGY.md index 056ed49..2b59eea 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.md @@ -1,17 +1,18 @@ -# TOPOLOGY.md — rescript-evangeliser +# TOPOLOGY.md — nextgen-languages-evangeliser ## Purpose -ReScript (and AffineScript) advocacy tool that helps teams migrate from TypeScript to ReScript. Analyses codebases, generates migration reports, produces evangelism content, and tracks conversion progress. Runs on Deno. +Multi-target advocacy tool that helps teams migrate from JavaScript/TypeScript to next-generation type-safe languages. Flagship target: AffineScript. Legacy target: ReScript. Analyses codebases, generates migration reports, produces evangelism content, and tracks conversion progress. Runs on Deno. ## Module Map ``` -rescript-evangeliser/ +nextgen-languages-evangeliser/ ├── bin/ │ └── evangeliser.js # Main entry point (Deno CLI) +├── src/ # Host source (ReScript today; AffineScript post-Phase 3) ├── config.ncl # Nickel configuration ├── docs/ # Usage and output documentation ├── justfile / Justfile # Task runner recipes @@ -21,7 +22,7 @@ rescript-evangeliser/ ## Data Flow ``` -[TypeScript codebase] ──► [evangeliser.js analysis] ──► [Migration report] +[JavaScript/TypeScript codebase] ──► [evangeliser.js analysis] ──► [Migration report (per target)] [config.ncl] ──► │ - [Advocacy content generator] ──► [Reports / stats] + [Multi-target advocacy content generator] ──► [Reports / stats] ``` diff --git a/bin/evangeliser.js b/bin/evangeliser.js index 9ed1437..3325870 100644 --- a/bin/evangeliser.js +++ b/bin/evangeliser.js @@ -1,6 +1,6 @@ #!/usr/bin/env -S deno run --allow-read --allow-env // SPDX-License-Identifier: PMPL-1.0-or-later -// Entry point for the rescript-evangeliser CLI -// Imports and runs the compiled ReScript CLI module +// Entry point for the nextgen-languages-evangeliser CLI +// Imports and runs the compiled ReScript CLI module (host language; AffineScript planned post-Phase 3) import "../src/Cli.res.js"; diff --git a/config.ncl b/config.ncl index 1b08a06..c864768 100644 --- a/config.ncl +++ b/config.ncl @@ -1,24 +1,35 @@ -# config.ncl - Nickel configuration for ReScript Evangeliser +# config.ncl - Nickel configuration for Nextgen Languages Evangeliser # SPDX-License-Identifier: MIT OR Palimpsest-0.8 # # Type-safe configuration using Nickel +# Renamed from rescript-evangeliser on 2026-04-16 { project = { - name = "rescript-evangeliser", - version = "0.1.0", - description = "Learn ReScript through progressive code transformation", + name = "nextgen-languages-evangeliser", + predecessor = "rescript-evangeliser", + version = "0.6.0-alpha", + description = "Learn next-generation type-safe languages (flagship: AffineScript) through progressive code transformation", license = "MIT OR Palimpsest-0.8", }, - # Language policy + # Target languages (what we teach) + targets = { + flagship = "AffineScript", + legacy = ["ReScript"], + planned = ["Rust", "Gleam", "Zig"], + }, + + # Language policy (what we write the toolkit in) languages = { allowed = [ - "ReScript", + "AffineScript", # planned host (Phase 3+) + "ReScript", # current host "Deno", "Rust", + "Zig", # canonical FFI "Bash", - "JavaScript", # Only for VS Code API bindings + "JavaScript", # minimal glue code only "Nickel", ], @@ -28,9 +39,11 @@ "npm", "bun", "Go", + "V", # use Zig, except inside V-ecosystem projects ], - primary = "ReScript", + primary = "ReScript", # current host language + primary_planned = "AffineScript", # post-Phase 3 runtime = "Deno", }, @@ -70,9 +83,9 @@ ], }, - # ReScript configuration + # ReScript configuration (current host) rescript = { - version = "11", + version = "12", module_format = "es6", suffix = ".res.js", uncurried = true, diff --git a/contractiles/intend/Intentfile.a2ml b/contractiles/intend/Intentfile.a2ml index dba6a4a..8049cd7 100644 --- a/contractiles/intend/Intentfile.a2ml +++ b/contractiles/intend/Intentfile.a2ml @@ -3,20 +3,26 @@ # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) @abstract: -Declared intent and purpose for Rescript Evangeliser. +Declared intent and purpose for Nextgen Languages Evangeliser (formerly Rescript Evangeliser). @end ## Purpose -Rescript Evangeliser — // SPDX-License-Identifier: PMPL-1.0-or-later +Nextgen Languages Evangeliser — a multi-target pattern detection engine, CLI, and educational +toolkit that teaches JavaScript developers next-generation type-safe languages through progressive +code transformation, without shame. Flagship target: AffineScript. Legacy target: ReScript. +// SPDX-License-Identifier: PMPL-1.0-or-later ## Anti-Purpose This project is NOT: - A fork or wrapper around another tool - A monorepo (unless explicitly structured as one) +- A compiler, type-checker, or language-server (those live in target-language repos) +- A TypeScript advocacy tool (TS is the thing we move people off, not toward) ## If In Doubt If you are unsure whether a change is in scope, ask. -Sensitive areas: ABI definitions, license headers, CI workflows. +Sensitive areas: ABI definitions, license headers, CI workflows, target-language +invariants (e.g. ReScript pattern catalogue is legacy-frozen; AffineScript catalogue is flagship and active). diff --git a/contractiles/must/Mustfile.a2ml b/contractiles/must/Mustfile.a2ml index ae984da..f03964f 100644 --- a/contractiles/must/Mustfile.a2ml +++ b/contractiles/must/Mustfile.a2ml @@ -3,7 +3,7 @@ # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) @abstract: -Physical State contract for Rescript Evangeliser. Baseline UX Manifesto invariants +Physical State contract for Nextgen Languages Evangeliser. Baseline UX Manifesto invariants that MUST hold at all times. @end diff --git a/contractiles/trust/Trustfile.a2ml b/contractiles/trust/Trustfile.a2ml index 28ed3d1..cd3d8bf 100644 --- a/contractiles/trust/Trustfile.a2ml +++ b/contractiles/trust/Trustfile.a2ml @@ -3,7 +3,7 @@ # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) @abstract: -Trust and provenance verification for Rescript Evangeliser. +Trust and provenance verification for Nextgen Languages Evangeliser. Maximal trust by default — LLM may read, build, test, lint, format. @end diff --git a/deno.json b/deno.json index 6fca1f0..9a201f2 100644 --- a/deno.json +++ b/deno.json @@ -1,7 +1,7 @@ { "$schema": "https://deno.land/x/deno/cli/schemas/config-file.v1.json", - "name": "@hyperpolymath/rescript-evangeliser", - "version": "0.1.0", + "name": "@hyperpolymath/nextgen-languages-evangeliser", + "version": "0.6.0-alpha", "license": "PMPL-1.0-or-later", "tasks": { "build": "deno run -A npm:rescript build", diff --git a/docs/CITATIONS.adoc b/docs/CITATIONS.adoc index 27c1761..d3c37bf 100644 --- a/docs/CITATIONS.adoc +++ b/docs/CITATIONS.adoc @@ -1,34 +1,41 @@ -= rescript-evangeliser - Citation Guide += nextgen-languages-evangeliser - Citation Guide :toc: +NOTE: This project was renamed from `rescript-evangeliser` in 2026. Pre-rename citations remain valid via GitHub's auto-redirect from the old slug. + == BibTeX [source,bibtex] ---- -@software{rescript-evangeliser_2025, +@software{nextgen-languages-evangeliser_2026, author = {Polymath, Hyper}, - title = {rescript-evangeliser}, - year = {2025}, - url = {https://github.com/hyperpolymath/rescript-evangeliser}, + title = {nextgen-languages-evangeliser}, + year = {2026}, + url = {https://github.com/hyperpolymath/nextgen-languages-evangeliser}, + note = {Successor to rescript-evangeliser (2025)}, license = {PMPL-1.0-or-later} } ---- == Harvard Style -Polymath, H. (2025) _rescript-evangeliser_ [Computer software]. Available at: https://github.com/hyperpolymath/rescript-evangeliser +Polymath, H. (2026) _nextgen-languages-evangeliser_ [Computer software]. Available at: https://github.com/hyperpolymath/nextgen-languages-evangeliser == OSCOLA -Hyper Polymath, 'rescript-evangeliser' (2025) +Hyper Polymath, 'nextgen-languages-evangeliser' (2026) == MLA -Polymath, Hyper. "rescript-evangeliser." 2025, github.com/hyperpolymath/rescript-evangeliser. +Polymath, Hyper. "nextgen-languages-evangeliser." 2026, github.com/hyperpolymath/nextgen-languages-evangeliser. == APA 7 -Polymath, H. (2025). _rescript-evangeliser_ [Computer software]. GitHub. https://github.com/hyperpolymath/rescript-evangeliser +Polymath, H. (2026). _nextgen-languages-evangeliser_ [Computer software]. GitHub. https://github.com/hyperpolymath/nextgen-languages-evangeliser + +== Legacy Citations (pre-rename) + +If you cited `rescript-evangeliser` before the 2026 rename, those citations remain valid. The repository history is preserved and the old URL redirects. == See Also diff --git a/docs/RSR_COMPLIANCE.md b/docs/RSR_COMPLIANCE.md index 2e87f03..47fec22 100644 --- a/docs/RSR_COMPLIANCE.md +++ b/docs/RSR_COMPLIANCE.md @@ -2,7 +2,7 @@ ## Rhodium Standard Repository (RSR) Bronze Level -**Project**: ReScript Evangeliser +**Project**: Nextgen Languages Evangeliser **Version**: 0.1.0 **Date**: 2024-11-22 **Compliance Level**: Bronze ✅ @@ -11,7 +11,7 @@ ## Executive Summary -ReScript Evangeliser achieves **Bronze-level compliance** with the Rhodium Standard Repository (RSR) framework. This document details our compliance across all 11 categories. +Nextgen Languages Evangeliser achieves **Bronze-level compliance** with the Rhodium Standard Repository (RSR) framework. This document details our compliance across all 11 categories. ## 1. Type Safety ✅ @@ -349,7 +349,7 @@ just compile **Questions about RSR compliance?** - See [MAINTAINERS.md](MAINTAINERS.md) -- Open an issue: [GitHub Issues](https://github.com/Hyperpolymath/rescript-evangeliser/issues) +- Open an issue: [GitHub Issues](https://github.com/Hyperpolymath/nextgen-languages-evangeliser/issues) - Security: [.well-known/security.txt](.well-known/security.txt) --- diff --git a/docs/TPCF.md b/docs/TPCF.md index 223f7ca..bc101c5 100644 --- a/docs/TPCF.md +++ b/docs/TPCF.md @@ -1,8 +1,8 @@ # Tri-Perimeter Contribution Framework (TPCF) -## ReScript Evangeliser: Perimeter 3 (Community Sandbox) +## Nextgen Languages Evangeliser: Perimeter 3 (Community Sandbox) -**Project**: ReScript Evangeliser +**Project**: Nextgen Languages Evangeliser **TPCF Level**: Perimeter 3 **Governance**: Community-driven, fully open **Last Updated**: 2024-11-22 @@ -17,7 +17,7 @@ The **Tri-Perimeter Contribution Framework** defines three levels of contributio 2. **Perimeter 2 (Stable)**: Reviewed contributions, production code 3. **Perimeter 3 (Community Sandbox)**: Fully open, experimental, community-driven -ReScript Evangeliser operates as **Perimeter 3** - a community sandbox with maximum openness. +Nextgen Languages Evangeliser operates as **Perimeter 3** - a community sandbox with maximum openness. --- diff --git a/flake.nix b/flake.nix index 0e2c9bc..d2adc50 100644 --- a/flake.nix +++ b/flake.nix @@ -1,5 +1,5 @@ { - description = "rescript-evangeliser - {project-description}"; + description = "nextgen-languages-evangeliser - {project-description}"; # *REMINDER: Update inputs with actual dependencies* inputs = { @@ -47,7 +47,7 @@ inherit buildInputs nativeBuildInputs; shellHook = '' - echo "🚀 rescript-evangeliser development environment" + echo "🚀 nextgen-languages-evangeliser development environment" echo "Language: rescript" echo "" echo "Available commands:" @@ -65,7 +65,7 @@ # Packages packages.default = pkgs.stdenv.mkDerivation { - pname = "rescript-evangeliser"; + pname = "nextgen-languages-evangeliser"; version = "0.1.0"; src = ./.; @@ -75,14 +75,14 @@ # *REMINDER: Add build commands* # For Rust: cargo build --release # For Elixir: mix compile - # For Ada: gprbuild -P rescript-evangeliser.gpr -XMODE=release + # For Ada: gprbuild -P nextgen-languages-evangeliser.gpr -XMODE=release ''; installPhase = '' mkdir -p $out/bin # *REMINDER: Add install commands* - # cp target/release/rescript-evangeliser $out/bin/ # Rust - # cp bin/rescript-evangeliser $out/bin/ # Ada + # cp target/release/nextgen-languages-evangeliser $out/bin/ # Rust + # cp bin/nextgen-languages-evangeliser $out/bin/ # Ada ''; meta = with pkgs.lib; { @@ -97,14 +97,14 @@ # Apps apps.default = { type = "app"; - program = "${self.packages.${system}.default}/bin/rescript-evangeliser"; + program = "${self.packages.${system}.default}/bin/nextgen-languages-evangeliser"; }; # Checks (CI/CD integration) checks = { build = self.packages.${system}.default; # *REMINDER: Add test checks* - test = pkgs.runCommand "test-rescript-evangeliser" { + test = pkgs.runCommand "test-nextgen-languages-evangeliser" { buildInputs = [ self.packages.${system}.default ]; } '' # Run tests here diff --git a/guix.scm b/guix.scm index 7d9d6f5..634dbb4 100644 --- a/guix.scm +++ b/guix.scm @@ -1,5 +1,5 @@ ; SPDX-License-Identifier: PMPL-1.0-or-later -;; guix.scm — GNU Guix package definition for rescript-evangeliser +;; guix.scm — GNU Guix package definition for nextgen-languages-evangeliser ;; Usage: guix shell -f guix.scm (use-modules (guix packages) @@ -7,12 +7,12 @@ (guix licenses)) (package - (name "rescript-evangeliser") + (name "nextgen-languages-evangeliser") (version "0.1.0") (source #f) (build-system gnu-build-system) - (synopsis "rescript-evangeliser") - (description "rescript-evangeliser — part of the hyperpolymath ecosystem.") - (home-page "https://github.com/hyperpolymath/rescript-evangeliser") + (synopsis "nextgen-languages-evangeliser") + (description "nextgen-languages-evangeliser — part of the hyperpolymath ecosystem.") + (home-page "https://github.com/hyperpolymath/nextgen-languages-evangeliser") (license ((@@ (guix licenses) license) "PMPL-1.0-or-later" "https://github.com/hyperpolymath/palimpsest-license"))) diff --git a/justfile b/justfile index b999005..0007e5e 100644 --- a/justfile +++ b/justfile @@ -1,4 +1,4 @@ -# justfile for ReScript Evangeliser +# justfile for Nextgen Languages Evangeliser # https://github.com/casey/just # SPDX-License-Identifier: PMPL-1.0-or-later # diff --git a/k9iser.toml b/k9iser.toml index 784d22d..bd00183 100644 --- a/k9iser.toml +++ b/k9iser.toml @@ -1,11 +1,11 @@ # SPDX-License-Identifier: PMPL-1.0-or-later # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # -# k9iser manifest for rescript-evangeliser -# ReScript evangelism tool — Deno-based tooling to assist ReScript adoption and advocacy +# k9iser manifest for nextgen-languages-evangeliser +# Nextgen typed-language evangelism tool — Deno-based tooling to assist AffineScript/ReScript adoption and advocacy [project] -name = "rescript-evangeliser" +name = "nextgen-languages-evangeliser" safety_tier = "hunt" [[source]] diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md index a177672..bdbdef7 100644 --- a/llm-warmup-dev.md +++ b/llm-warmup-dev.md @@ -1,6 +1,6 @@ -# LLM Warmup — rescript-evangeliser (Developer) +# LLM Warmup — nextgen-languages-evangeliser (Developer) -## What is rescript-evangeliser? +## What is nextgen-languages-evangeliser? See README.adoc for overview. ## Key Commands diff --git a/llm-warmup-user.md b/llm-warmup-user.md index 3160315..42b1cc5 100644 --- a/llm-warmup-user.md +++ b/llm-warmup-user.md @@ -1,6 +1,6 @@ -# LLM Warmup — rescript-evangeliser (User) +# LLM Warmup — nextgen-languages-evangeliser (User) -## What is rescript-evangeliser? +## What is nextgen-languages-evangeliser? See README.adoc for overview. ## Key Commands diff --git a/rescript.json b/rescript.json index c8b4b13..582766e 100644 --- a/rescript.json +++ b/rescript.json @@ -1,5 +1,5 @@ { - "name": "rescript-evangeliser", + "name": "nextgen-languages-evangeliser", "sources": [ { "dir": "src", diff --git a/setup.sh b/setup.sh index 8bba641..57d808c 100755 --- a/setup.sh +++ b/setup.sh @@ -1,12 +1,12 @@ #!/bin/sh # SPDX-License-Identifier: PMPL-1.0-or-later -# setup.sh — Universal setup script for rescript-evangeliser +# setup.sh — Universal setup script for nextgen-languages-evangeliser # # Detects your shell, platform, and installs prerequisites. # Then hands off to `just setup` for project-specific configuration. # # Usage: -# curl -fsSL https://raw.githubusercontent.com/hyperpolymath/rescript-evangeliser/main/setup.sh | sh +# curl -fsSL https://raw.githubusercontent.com/hyperpolymath/nextgen-languages-evangeliser/main/setup.sh | sh # # or after cloning: # ./setup.sh # @@ -167,7 +167,7 @@ install_just() { # ── Main ── main() { - printf "%s=== rescript-evangeliser Setup ===%s\n\n" "$BOLD" "$RESET" + printf "%s=== nextgen-languages-evangeliser Setup ===%s\n\n" "$BOLD" "$RESET" # Detect environment SHELL_NAME=$(detect_shell) @@ -198,8 +198,8 @@ main() { # Step 2: Check if we're in the repo directory if [ ! -f "Justfile" ] && [ ! -f "justfile" ]; then warn "Not in a repo directory (no Justfile found)" - info "Clone first: git clone https://github.com/hyperpolymath/rescript-evangeliser.git" - info "Then: cd rescript-evangeliser && ./setup.sh" + info "Clone first: git clone https://github.com/hyperpolymath/nextgen-languages-evangeliser.git" + info "Then: cd nextgen-languages-evangeliser && ./setup.sh" exit 1 fi diff --git a/src/Cli.res b/src/Cli.res index dd668e5..60f25d5 100644 --- a/src/Cli.res +++ b/src/Cli.res @@ -1,5 +1,5 @@ // SPDX-License-Identifier: PMPL-1.0-or-later -// CLI: Entry point for the rescript-evangeliser command-line tool +// CLI: Entry point for the nextgen-languages-evangeliser command-line tool // Usage: evangeliser scan | patterns | legend open Types @@ -75,7 +75,7 @@ let parseArgs = (args: array): cliOptions => { } let showHelp = (): string => { - `ReScript Evangeliser - "Celebrate good, minimize bad, show better" + `Nextgen Languages Evangeliser - "Celebrate good, minimize bad, show better" Usage: evangeliser scan Scan a JavaScript file for improvable patterns diff --git a/src/Glyphs.res b/src/Glyphs.res index 181c74d..2de8c8b 100644 --- a/src/Glyphs.res +++ b/src/Glyphs.res @@ -1,5 +1,5 @@ // SPDX-License-Identifier: PMPL-1.0-or-later -// Makaton-inspired glyph system for ReScript Evangeliser +// Makaton-inspired glyph system for Nextgen Languages Evangeliser // Glyphs transcend syntax to show semantic meaning. open Types diff --git a/src/Narrative.res b/src/Narrative.res index d571651..8bf5c6e 100644 --- a/src/Narrative.res +++ b/src/Narrative.res @@ -1,5 +1,5 @@ // SPDX-License-Identifier: PMPL-1.0-or-later -// Narrative generation for ReScript Evangeliser +// Narrative generation for Nextgen Languages Evangeliser // Philosophy: "Celebrate good, minimize bad, show better" // - NEVER shame developers // - ALWAYS celebrate what their JavaScript does well diff --git a/src/Output.res b/src/Output.res index 012f19f..a71bb38 100644 --- a/src/Output.res +++ b/src/Output.res @@ -52,9 +52,9 @@ let formatRaw = (result: analysisResult, format: string): string => { "No patterns detected. Try pasting some JavaScript code!\n" } else { let header = switch format { - | "markdown" => "# ReScript Evangeliser - Analysis Results\n\n" - | "html" => "

ReScript Evangeliser - Analysis Results

\n" - | _ => bold("ReScript Evangeliser - Analysis Results") ++ "\n\n" + | "markdown" => "# Nextgen Languages Evangeliser - Analysis Results\n\n" + | "html" => "

Nextgen Languages Evangeliser - Analysis Results

\n" + | _ => bold("Nextgen Languages Evangeliser - Analysis Results") ++ "\n\n" } let summary = Analyser.summarise(result) @@ -73,9 +73,9 @@ let formatFolded = (result: analysisResult, format: string): string => { "No patterns detected. Try pasting some JavaScript code!\n" } else { let header = switch format { - | "markdown" => "# ReScript Evangeliser - Analysis Results (Grouped)\n\n" - | "html" => "

ReScript Evangeliser - Analysis Results (Grouped)

\n" - | _ => bold("ReScript Evangeliser - Analysis Results (Grouped)") ++ "\n\n" + | "markdown" => "# Nextgen Languages Evangeliser - Analysis Results (Grouped)\n\n" + | "html" => "

Nextgen Languages Evangeliser - Analysis Results (Grouped)

\n" + | _ => bold("Nextgen Languages Evangeliser - Analysis Results (Grouped)") ++ "\n\n" } let summary = Analyser.summarise(result) @@ -115,9 +115,9 @@ let formatGlyphed = (result: analysisResult, format: string): string => { "No patterns detected. Try pasting some JavaScript code!\n" } else { let header = switch format { - | "markdown" => "# ReScript Evangeliser - Glyph Overview\n\n" - | "html" => "

ReScript Evangeliser - Glyph Overview

\n" - | _ => bold("ReScript Evangeliser - Glyph Overview") ++ "\n\n" + | "markdown" => "# Nextgen Languages Evangeliser - Glyph Overview\n\n" + | "html" => "

Nextgen Languages Evangeliser - Glyph Overview

\n" + | _ => bold("Nextgen Languages Evangeliser - Glyph Overview") ++ "\n\n" } let uniquePatterns = Scanner.uniquePatterns(result.matches) diff --git a/src/Patterns.res b/src/Patterns.res index 2ae87d8..f4ba617 100644 --- a/src/Patterns.res +++ b/src/Patterns.res @@ -1,6 +1,6 @@ // SPDX-License-Identifier: PMPL-1.0-or-later -// Pattern Library for ReScript Evangeliser -// 50+ transformation patterns from JavaScript/TypeScript to ReScript +// Pattern Library for Nextgen Languages Evangeliser +// Multi-target transformation patterns from JavaScript/TypeScript to AffineScript (flagship) / ReScript (legacy) open Types diff --git a/src/Types.res b/src/Types.res index f03f9f4..4ef2b68 100644 --- a/src/Types.res +++ b/src/Types.res @@ -1,5 +1,5 @@ // SPDX-License-Identifier: PMPL-1.0-or-later -// Core type definitions for ReScript Evangeliser +// Core type definitions for Nextgen Languages Evangeliser // Philosophy: "Celebrate good, minimize bad, show better" type viewLayer = RAW | FOLDED | GLYPHED | WYSIWYG diff --git a/stapeln.toml b/stapeln.toml index 72697fd..7bc98ef 100644 --- a/stapeln.toml +++ b/stapeln.toml @@ -1,13 +1,13 @@ # SPDX-License-Identifier: PMPL-1.0-or-later -# stapeln.toml — Layer-based container build for rescript-evangeliser +# stapeln.toml — Layer-based container build for nextgen-languages-evangeliser # # stapeln builds containers as composable layers (German: "to stack"). # Each layer is independently cacheable, verifiable, and signable. [metadata] -name = "rescript-evangeliser" +name = "nextgen-languages-evangeliser" version = "0.1.0" -description = "rescript evangeliser" +description = "Nextgen Languages Evangeliser (formerly rescript-evangeliser)" author = "Jonathan D.A. Jewell " license = "PMPL-1.0-or-later" registry = "ghcr.io/hyperpolymath" @@ -32,7 +32,7 @@ packages = ["deno"] cache = true [layers.build] -description = "rescript-evangeliser build" +description = "nextgen-languages-evangeliser build" extends = "toolchain" commands = ["deno cache src/main.ts"] From 0230d9409068118d5065998511b8e17d2154fd29 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 16 Apr 2026 13:44:06 +0000 Subject: [PATCH 2/2] feat(engine): generalise pattern engine for multi-target (Phase 1b) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 1b of the migration to a multi-target evangeliser. Introduces a target-language abstraction so a single pattern can carry examples for AffineScript (flagship), ReScript (legacy), and future targets (Rust, Gleam, Zig) without the engine committing to any one of them. Type model (src/Types.res): - new `targetLang = AffineScript | ReScript | Rust | Gleam | Zig` - new `targetExample = {language, code}` record - `pattern.rescriptExample: string` replaced by `pattern.targets: array` - constant `flagshipTarget = AffineScript` - helpers: `targetLangToString`, `targetLangLabel`, `targetLangSyntaxTag`, `stringToTargetLang`, `patternExampleFor`, `patternCodeFor`, `patternEffectiveTarget` Pattern library (src/Patterns.res): - `makePattern` keeps its `~rescriptExample` parameter and wraps it internally as a single-entry `targets: [{language: ReScript, code}]`. All 52 existing call-sites compile unchanged. - new `makePatternMultiTarget` for Phase 2+ patterns that supply AffineScript (flagship) alongside ReScript. Engine threading: - Scanner.res: `patternMatch.transformation` now derived from the flagship target's example (falls back via `patternCodeFor`). - Output.res: `formatRaw`, `formatFolded`, `formatGlyphed`, and top-level `format` all take a `target: targetLang` parameter. Match renderer shows the requested target's code and label, with a "(fallback — pattern not yet ported to X)" note when a pattern is only available in its legacy target. - Output.res: `formatPatternList` now annotates each pattern with its supported targets, e.g. `[ReScript]` today, `[AffineScript, ReScript]` after Phase 2. - Cli.res: adds `--target` flag (affinescript|rescript|rust|gleam|zig); default is flagship (AffineScript). `stats` command now shows a per-target pattern count. Tests: - test/Patterns_test.res: asserts `targets` is non-empty and each target's code is non-empty (replaces the old `rescriptExample` check). - test/Narrative_test.res: mock pattern construction updated to use new `targets` shape. Build & tests verified: - `rescript build` → 71 modules compiled, no warnings - 38 tests across 6 suites → all pass - CLI smoke-tested: `scan --target affinescript` (default, with fallback note) and `scan --target rescript` (no fallback) both render correctly. `stats` shows `ReScript: 52` target coverage — correct baseline before Phase 2 adds AffineScript coverage. Behaviour preserved: the legacy ReScript catalogue continues to work end-to-end. Phase 2 can now begin authoring AffineScript pattern entries using `makePatternMultiTarget` without further engine changes. https://claude.ai/code/session_01RJWz6SUyUEHTBNLjVwF177 --- src/Cli.res | 36 +++++++++++++- src/Output.res | 54 +++++++++++++------- src/Patterns.res | 48 +++++++++++++++++- src/Scanner.res | 4 +- src/Types.res | 108 +++++++++++++++++++++++++++++++++++++++- test/Narrative_test.res | 2 +- test/Patterns_test.res | 5 +- 7 files changed, 231 insertions(+), 26 deletions(-) diff --git a/src/Cli.res b/src/Cli.res index 60f25d5..6ce3e5b 100644 --- a/src/Cli.res +++ b/src/Cli.res @@ -17,6 +17,7 @@ type cliOptions = { format: string, difficulty: option, view: viewLayer, + target: targetLang, } let parseArgs = (args: array): cliOptions => { @@ -28,6 +29,7 @@ let parseArgs = (args: array): cliOptions => { let format = ref("plain") let difficulty = ref(None) let view = ref(RAW) + let target = ref(flagshipTarget) userArgs->Array.forEachWithIndex((_arg, idx) => { let arg = userArgs->Array.getUnsafe(idx) @@ -52,6 +54,15 @@ let parseArgs = (args: array): cliOptions => { | Some("glyphed") => view := GLYPHED | _ => () } + | "--target" => + switch userArgs->Array.get(idx + 1) { + | Some(t) => + switch stringToTargetLang(t) { + | Some(lang) => target := lang + | None => () // unknown target: keep default (flagship) + } + | None => () + } | _ => // First non-flag arg after command is the file if idx > 0 && !(String.startsWith(arg, "--")) { @@ -71,6 +82,7 @@ let parseArgs = (args: array): cliOptions => { format: format.contents, difficulty: difficulty.contents, view: view.contents, + target: target.contents, } } @@ -88,10 +100,17 @@ Options: --format plain|markdown|html Output format (default: plain) --difficulty beginner|intermediate|advanced Filter patterns by difficulty --view raw|folded|glyphed View layer (default: raw) + --target affinescript|rescript|rust|gleam|zig + Target language for transformations + (default: affinescript — the flagship target). + Patterns that have not yet been ported to the + requested target fall back to their first + available example with a note. Examples: evangeliser scan app.js evangeliser scan utils.js --format markdown --view folded + evangeliser scan app.js --target rescript evangeliser patterns --difficulty beginner ` } @@ -108,6 +127,21 @@ let showStats = (): string => { stats.byCategory->Dict.toArray->Array.forEach(((key, count)) => { lines := lines.contents ++ ` ${key}: ${Int.toString(count)}\n` }) + + // Also count patterns per target, so users can see coverage at a glance. + let byTarget = Dict.make() + Patterns.patternLibrary->Array.forEach(p => { + p.targets->Array.forEach(t => { + let key = targetLangLabel(t.language) + let current = byTarget->Dict.get(key)->Option.getOr(0) + byTarget->Dict.set(key, current + 1) + }) + }) + lines := lines.contents ++ `\nBy target (patterns supplying that target):\n` + byTarget->Dict.toArray->Array.forEach(((key, count)) => { + lines := lines.contents ++ ` ${key}: ${Int.toString(count)}\n` + }) + lines.contents } @@ -127,7 +161,7 @@ let run = (): unit => { let filtered = Patterns.getPatternsByDifficulty(diff) Analyser.analyseWithPatterns(code, filtered) } - Output.format(result, opts.view, opts.format) + Output.format(result, opts.view, opts.format, opts.target) } catch { | JsExn(e) => let msg = e->JsExn.message->Option.getOr("Unknown error") diff --git a/src/Output.res b/src/Output.res index a71bb38..bbc3c1b 100644 --- a/src/Output.res +++ b/src/Output.res @@ -1,6 +1,9 @@ // SPDX-License-Identifier: PMPL-1.0-or-later // Output: Format analysis results for terminal display // Supports RAW, FOLDED, and GLYPHED view layers +// Target-aware: honours the requested target language, falls back to the +// first target the pattern actually supplies if the requested one is +// missing (e.g. AffineScript requested but pattern only ships ReScript). open Types @@ -13,17 +16,25 @@ let dim = s => `\x1b[2m${s}\x1b[0m` let magenta = s => `\x1b[35m${s}\x1b[0m` // Format a single pattern match for RAW view -let formatMatchRaw = (m: patternMatch, format: string): string => { +let formatMatchRaw = (m: patternMatch, format: string, target: targetLang): string => { let glyphBar = m.pattern.glyphs->Array.join(" ") let diffStr = difficultyToString(m.pattern.difficulty) let narrative = Narrative.formatNarrative(m.pattern.narrative, format) + let effectiveTarget = patternEffectiveTarget(m.pattern, target) + let targetCode = patternCodeFor(m.pattern, target) + let targetLabel = targetLangLabel(effectiveTarget) + let targetTag = targetLangSyntaxTag(effectiveTarget) + let fallbackNote = + effectiveTarget == target + ? "" + : ` ${dim(`(fallback — pattern not yet ported to ${targetLangLabel(target)})`)}` switch format { | "markdown" => `### ${glyphBar} ${m.pattern.name}\n\n` ++ `**Difficulty:** ${diffStr} | **Confidence:** ${Float.toFixed(m.pattern.confidence *. 100.0, ~digits=0)}%\n\n` ++ `**JavaScript:**\n\`\`\`javascript\n${m.pattern.jsExample}\n\`\`\`\n\n` ++ - `**ReScript:**\n\`\`\`rescript\n${m.pattern.rescriptExample}\n\`\`\`\n\n` ++ + `**${targetLabel}:**\n\`\`\`${targetTag}\n${targetCode}\n\`\`\`\n\n` ++ narrative ++ "\n\n---\n" | "html" => @@ -31,7 +42,7 @@ let formatMatchRaw = (m: patternMatch, format: string): string => { `

${glyphBar} ${m.pattern.name}

\n` ++ `

Difficulty: ${diffStr} | Confidence: ${Float.toFixed(m.pattern.confidence *. 100.0, ~digits=0)}%

\n` ++ ` 
${m.pattern.jsExample}
\n` ++ - ` 
${m.pattern.rescriptExample}
\n` ++ + ` 
${targetCode}
\n` ++ narrative ++ `\n\n` @@ -40,14 +51,14 @@ let formatMatchRaw = (m: patternMatch, format: string): string => { bold(`${glyphBar} ${m.pattern.name}`) ++ "\n" ++ dim(`Difficulty: ${diffStr} | Confidence: ${Float.toFixed(m.pattern.confidence *. 100.0, ~digits=0)}%`) ++ "\n\n" ++ cyan("JavaScript:") ++ "\n" ++ m.pattern.jsExample ++ "\n\n" ++ - green("ReScript:") ++ "\n" ++ m.pattern.rescriptExample ++ "\n\n" ++ + green(`${targetLabel}:`) ++ fallbackNote ++ "\n" ++ targetCode ++ "\n\n" ++ narrative ++ "\n\n" ++ dim("---") ++ "\n" } } // Format analysis results in RAW view (each match shown individually) -let formatRaw = (result: analysisResult, format: string): string => { +let formatRaw = (result: analysisResult, format: string, target: targetLang): string => { if result.matches->Array.length === 0 { "No patterns detected. Try pasting some JavaScript code!\n" } else { @@ -60,7 +71,7 @@ let formatRaw = (result: analysisResult, format: string): string => { let summary = Analyser.summarise(result) let matches = result.matches - ->Array.map(m => formatMatchRaw(m, format)) + ->Array.map(m => formatMatchRaw(m, format, target)) ->Array.join("\n") header ++ summary ++ "\n\n" ++ matches @@ -68,7 +79,7 @@ let formatRaw = (result: analysisResult, format: string): string => { } // Format analysis results in FOLDED view (grouped by category) -let formatFolded = (result: analysisResult, format: string): string => { +let formatFolded = (result: analysisResult, format: string, target: targetLang): string => { if result.matches->Array.length === 0 { "No patterns detected. Try pasting some JavaScript code!\n" } else { @@ -99,7 +110,7 @@ let formatFolded = (result: analysisResult, format: string): string => { } let matchStr = matches - ->Array.map(m => formatMatchRaw(m, format)) + ->Array.map(m => formatMatchRaw(m, format, target)) ->Array.join("\n") catHeader ++ matchStr }) @@ -110,7 +121,7 @@ let formatFolded = (result: analysisResult, format: string): string => { } // Format analysis results in GLYPHED view (glyph-annotated summary) -let formatGlyphed = (result: analysisResult, format: string): string => { +let formatGlyphed = (result: analysisResult, format: string, _target: targetLang): string => { if result.matches->Array.length === 0 { "No patterns detected. Try pasting some JavaScript code!\n" } else { @@ -143,17 +154,20 @@ let formatGlyphed = (result: analysisResult, format: string): string => { } } -// Format results using the specified view layer -let format = (result: analysisResult, view: viewLayer, outputFormat: string): string => { +// Format results using the specified view layer and target language. +let format = (result: analysisResult, view: viewLayer, outputFormat: string, target: targetLang): string => { switch view { - | RAW => formatRaw(result, outputFormat) - | FOLDED => formatFolded(result, outputFormat) - | GLYPHED => formatGlyphed(result, outputFormat) - | WYSIWYG => formatRaw(result, "html") // WYSIWYG falls back to HTML for now + | RAW => formatRaw(result, outputFormat, target) + | FOLDED => formatFolded(result, outputFormat, target) + | GLYPHED => formatGlyphed(result, outputFormat, target) + | WYSIWYG => formatRaw(result, "html", target) // WYSIWYG falls back to HTML for now } } -// Format the pattern list for the `patterns` command +// Format the pattern list for the `patterns` command. +// Annotates each pattern with the set of targets it currently supports, +// so users can see at a glance which patterns have been ported to +// AffineScript and which are still ReScript-only. let formatPatternList = (format: string): string => { let stats = Patterns.getPatternStats() let header = switch format { @@ -188,11 +202,15 @@ let formatPatternList = (format: string): string => { patterns ->Array.map(p => { let diffStr = difficultyToString(p.difficulty) + let targetTags = + p.targets + ->Array.map(t => targetLangLabel(t.language)) + ->Array.join(", ") switch format { | "markdown" => - `- **${p.name}** (${diffStr}) - ${p.narrative.celebrate}\n` + `- **${p.name}** (${diffStr}) [targets: ${targetTags}] - ${p.narrative.celebrate}\n` | _ => - ` ${green(p.name)} ${dim(`[${diffStr}]`)} ${p.narrative.celebrate}\n` + ` ${green(p.name)} ${dim(`[${diffStr}]`)} ${dim(`[${targetTags}]`)} ${p.narrative.celebrate}\n` } }) ->Array.join("") diff --git a/src/Patterns.res b/src/Patterns.res index f4ba617..89e2cc7 100644 --- a/src/Patterns.res +++ b/src/Patterns.res @@ -4,7 +4,13 @@ open Types -// Helper to create pattern with glyphs +// Helper to create a pattern with glyphs. +// +// Phase 1b note: the `~rescriptExample` parameter is preserved so all 52 +// existing call-sites compile unchanged. It is wrapped internally into +// the new multi-target `targets` field as a single ReScript entry. +// Patterns authored in Phase 2 onward will call `makePatternMultiTarget` +// (below) to supply per-target examples including the flagship AffineScript. let makePattern = ( ~id, ~name, @@ -29,7 +35,45 @@ let makePattern = ( jsPattern, confidence, jsExample, - rescriptExample, + targets: [{language: ReScript, code: rescriptExample}], + narrative, + glyphs: Glyphs.getGlyphsForPattern(category), + tags, + relatedPatterns, + learningObjectives, + commonMistakes, + bestPractices, + } +} + +// Multi-target pattern constructor — use this for new (Phase 2+) patterns +// that supply AffineScript (flagship) alongside ReScript (or any other +// target language). +let makePatternMultiTarget = ( + ~id, + ~name, + ~category, + ~difficulty, + ~jsPattern, + ~confidence, + ~jsExample, + ~targets, + ~narrative, + ~tags, + ~relatedPatterns, + ~learningObjectives, + ~commonMistakes, + ~bestPractices, +): pattern => { + { + id, + name, + category, + difficulty, + jsPattern, + confidence, + jsExample, + targets, narrative, glyphs: Glyphs.getGlyphsForPattern(category), tags, diff --git a/src/Scanner.res b/src/Scanner.res index 62315f9..d425c7f 100644 --- a/src/Scanner.res +++ b/src/Scanner.res @@ -55,7 +55,9 @@ let scanPattern = (code: string, pattern: pattern): array => { startLine, endLine, confidence: pattern.confidence, - transformation: Some(pattern.rescriptExample), + // Use flagship target's code as the offered transformation; + // falls back to whatever target the pattern does support. + transformation: Some(patternCodeFor(pattern, flagshipTarget)), }, ]) } diff --git a/src/Types.res b/src/Types.res index 4ef2b68..2ce57a0 100644 --- a/src/Types.res +++ b/src/Types.res @@ -37,6 +37,19 @@ type semanticCategory = | State | Data +// Target languages the evangeliser can emit examples for. +// AffineScript is the flagship (Phase 2 onward); ReScript is the legacy +// catalogue preserved during migration. Others are planned (Phase 5+). +type targetLang = + | AffineScript + | ReScript + | Rust + | Gleam + | Zig + +// Flagship target — consumed by Cli/Output when --target is not specified. +let flagshipTarget: targetLang = AffineScript + // A Makaton-inspired glyph that represents semantic meaning beyond syntax type glyph = { symbol: string, @@ -55,7 +68,17 @@ type narrative = { example: string, } -// A transformation pattern from JavaScript to ReScript +// A single target-language example for a pattern. +// In Phase 1b, only `code` varies per target; narrative is shared at +// pattern level. In Phase 2 this record can gain an optional per-target +// narrative override so AffineScript's affine-safety pitch differs from +// ReScript's Option-type pitch. +type targetExample = { + language: targetLang, + code: string, +} + +// A transformation pattern from JavaScript to one or more target languages. type pattern = { id: string, name: string, @@ -64,7 +87,11 @@ type pattern = { jsPattern: string, confidence: float, jsExample: string, - rescriptExample: string, + // Multi-target: each entry pairs a target language with its example code. + // Patterns must have at least one target; the first target is used as + // fallback if --target requests a language this pattern has not been + // ported to yet. + targets: array, narrative: narrative, glyphs: array, tags: array, @@ -174,3 +201,80 @@ let viewLayerToString = (view: viewLayer): string => { | WYSIWYG => "WYSIWYG" } } + +// Canonical string name for a target language (lowercase, used in CLI args). +let targetLangToString = (t: targetLang): string => { + switch t { + | AffineScript => "affinescript" + | ReScript => "rescript" + | Rust => "rust" + | Gleam => "gleam" + | Zig => "zig" + } +} + +// Display-friendly label (capitalisation for rendering). +let targetLangLabel = (t: targetLang): string => { + switch t { + | AffineScript => "AffineScript" + | ReScript => "ReScript" + | Rust => "Rust" + | Gleam => "Gleam" + | Zig => "Zig" + } +} + +// Markdown / Rouge syntax-highlighter tag for a target language. +let targetLangSyntaxTag = (t: targetLang): string => { + switch t { + | AffineScript => "affinescript" + | ReScript => "rescript" + | Rust => "rust" + | Gleam => "gleam" + | Zig => "zig" + } +} + +let stringToTargetLang = (s: string): option => { + switch String.toLowerCase(s) { + | "affinescript" | "affine" | "as" => Some(AffineScript) + | "rescript" | "res" => Some(ReScript) + | "rust" | "rs" => Some(Rust) + | "gleam" => Some(Gleam) + | "zig" => Some(Zig) + | _ => None + } +} + +// Find the example code for a specific target language in a pattern. +// Returns None if the pattern has no entry for that target. +let patternExampleFor = (p: pattern, lang: targetLang): option => { + p.targets->Array.find(t => t.language == lang) +} + +// Get the code string for a specific target, falling back to the first +// available target if the requested one is not present. Empty string if +// the pattern has no targets at all (should never happen in practice). +let patternCodeFor = (p: pattern, lang: targetLang): string => { + switch patternExampleFor(p, lang) { + | Some(t) => t.code + | None => + switch p.targets->Array.get(0) { + | Some(t) => t.code + | None => "" + } + } +} + +// The effective target for a pattern given a requested target: the +// requested one if supported, else the pattern's first target (fallback). +let patternEffectiveTarget = (p: pattern, requested: targetLang): targetLang => { + switch patternExampleFor(p, requested) { + | Some(_) => requested + | None => + switch p.targets->Array.get(0) { + | Some(t) => t.language + | None => requested + } + } +} diff --git a/test/Narrative_test.res b/test/Narrative_test.res index a39b0ae..a0996cb 100644 --- a/test/Narrative_test.res +++ b/test/Narrative_test.res @@ -76,7 +76,7 @@ let testGenerateHint = () => { jsPattern: "", confidence: 0.9, jsExample: "", - rescriptExample: "", + targets: [{language: ReScript, code: ""}], narrative: { celebrate: "", minimize: "", diff --git a/test/Patterns_test.res b/test/Patterns_test.res index 123b9bd..968240a 100644 --- a/test/Patterns_test.res +++ b/test/Patterns_test.res @@ -62,7 +62,10 @@ let testPatternsHaveRequiredFields = () => { assert_(String.length(p.jsPattern) > 0, `Pattern ${p.id} missing jsPattern`) assert_(p.confidence > 0.0 && p.confidence <= 1.0, `Pattern ${p.id} confidence out of range`) assert_(String.length(p.jsExample) > 0, `Pattern ${p.id} missing jsExample`) - assert_(String.length(p.rescriptExample) > 0, `Pattern ${p.id} missing rescriptExample`) + assert_(p.targets->Array.length > 0, `Pattern ${p.id} has no target examples`) + p.targets->Array.forEach(t => { + assert_(String.length(t.code) > 0, `Pattern ${p.id} has empty code for target ${targetLangLabel(t.language)}`) + }) assert_(String.length(p.narrative.celebrate) > 0, `Pattern ${p.id} missing narrative.celebrate`) assert_(String.length(p.narrative.minimize) > 0, `Pattern ${p.id} missing narrative.minimize`) assert_(String.length(p.narrative.better) > 0, `Pattern ${p.id} missing narrative.better`)