Nextgen Languages Evangeliser

image:[TPCF: Perimeter 3,link=docs/TPCF.md] image:[AffineScript First]

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 ROADMAP.adoc for migration phases.

What is This?

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 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! Next-generation type systems just make some things even safer.

Supported targets

Target	Status	Pitch
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 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

• Deno (latest stable)

• ReScript 12.2+ (current host language; see ROADMAP.adoc for AffineScript port)

Installation

# Clone the repository
git clone https://github.com/hyperpolymath/nextgen-languages-evangeliser.git
cd nextgen-languages-evangeliser

# Install dependencies
just install

# Build host sources
just build

Usage

# Scan a JavaScript file for patterns
deno run --allow-read bin/evangeliser.js scan <file.js>

# List all available patterns (with their target languages)
deno run --allow-read bin/evangeliser.js patterns

# Show the glyph legend
deno run --allow-read bin/evangeliser.js legend

# Display detection statistics
deno run --allow-read bin/evangeliser.js stats

Development

# Run tests
just test

# Watch mode for development
just watch

# Format code
just fmt

# Full CI simulation
just ci

Features

Multi-target Pattern Catalogue

Each pattern carries example transformations for multiple target languages. 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

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/target comparison with narrative

2. FOLDED: Organized sections with collapsible regions

3. GLYPHED: Symbol-annotated code showing semantic meaning

Three Output Formats

• Plain text: Terminal-friendly output

• Markdown: For documentation and READMEs

• HTML: For web integration and reports

Makaton-Inspired Glyphs

Visual symbols that transcend syntax across 21 glyph categories:

• Shield (null safety)

• Transform (data transformation)

• Flow (pipe operator)

• Branch (pattern matching)

• Crystal (immutability)

• Seal (affine ownership)

• …​and more

Scanner + Analyser Detection Engine

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, plain/markdown/html output formats, and --target selection.

Technology Stack

Primary Technologies

• 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

Per Hyperpolymath Standard:

Allowed	Banned
AffineScript, ReScript	TypeScript
Deno	Node.js/npm/bun
justfile	Makefile
Zig (FFI)	V (outside V ecosystem)

See CLAUDE.md and .claude/CLAUDE.md for the full policy.

Project Structure

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 (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 (multi-target)
|   +-- Cli.res             # CLI entry point (scan/patterns/legend/stats)
+-- test/                   # Test suites
+-- bin/
|   +-- evangeliser.js      # CLI entry point
+-- docs/                   # Documentation
+-- rescript.json           # Host (ReScript) configuration
+-- deno.json               # Deno configuration
+-- Justfile                # Task orchestration
+-- Mustfile.epx            # Deployment contract
+-- config.ncl              # Nickel configuration
+-- CLAUDE.md               # AI context

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 the target language enhances the pattern

4. Safety: Explain type-level (and affine/linear) guarantees

5. Example: Provide concrete, encouraging examples

Example narrative (ReScript target):

You were close! You’re already thinking about null and undefined - that’s great defensive programming!

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 host today; AffineScript (affine/linear types, borrow checking) post-Phase 3

• Offline First: Zero network dependencies

• Complete Documentation: See docs/

• Security First: See SECURITY.md

• Open Governance: TPCF Perimeter 3 (Community Sandbox)

• Licensed: PMPL-1.0-or-later

• Build Reproducibility: Deno + Justfile

See RSR_COMPLIANCE.md for full details.

Documentation

• CONTRIBUTING.md - How to contribute

• CODE_OF_CONDUCT.md - Community guidelines

• SECURITY.md - Security policies

• CHANGELOG.md - Version history

• RSR_COMPLIANCE.md - RSR framework compliance

• TPCF.md - Contribution framework

• ROADMAP.adoc - Migration phases & future targets

Contributing

We welcome contributions! See CONTRIBUTING.md for:

• Code of Conduct

• Development setup

• Pattern authoring guide (multi-target)

• Testing requirements

• Pull request process

This is a TPCF Perimeter 3 project - all contributions are welcome!

License

This project is licensed under the Palimpsest License (PMPL-1.0-or-later).

See LICENSE for the full license text.

Roadmap

• ✓ 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 ROADMAP.adoc for detailed milestones.

Citations

If you use this project in academic research, please cite:

@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/nextgen-languages-evangeliser},
  note = {Successor to rescript-evangeliser; RSR Bronze-compliant, TPCF Perimeter 3}
}

Community

• GitHub: Issues and Discussions

• AffineScript: hyperpolymath/affinescript

• ReScript Forum: forum.rescript-lang.org

Acknowledgments

• 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 humans.txt

Status

• Version: 0.6.0-alpha (migrating from rescript-evangeliser 0.5.x)

• RSR Level: Bronze

• 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-04-16

---

Made with care for JavaScript developers curious about next-generation languages.

Remember: You were close!