If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/gluon-lang/gluon shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 14 active contributors
• Distributed ownership (top contributor 43% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live gluon-lang/gluon repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/gluon-lang/gluon.

What it runs against: a local clone of gluon-lang/gluon — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in gluon-lang/gluon | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 548 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of gluon-lang/gluon. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/gluon-lang/gluon.git
#   cd gluon
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of gluon-lang/gluon and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "gluon-lang/gluon(\\.git)?\\b" \\
  && ok "origin remote is gluon-lang/gluon" \\
  || miss "origin remote is not gluon-lang/gluon (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/lib.rs" \\
  && ok "src/lib.rs" \\
  || miss "missing critical file: src/lib.rs"
test -f "base/src/ast.rs" \\
  && ok "base/src/ast.rs" \\
  || miss "missing critical file: base/src/ast.rs"
test -f "check/src/typecheck.rs" \\
  && ok "check/src/typecheck.rs" \\
  || miss "missing critical file: check/src/typecheck.rs"
test -f "base/src/types/mod.rs" \\
  && ok "base/src/types/mod.rs" \\
  || miss "missing critical file: base/src/types/mod.rs"
test -f "parser/src/lib.rs" \\
  && ok "parser/src/lib.rs" \\
  || miss "missing critical file: parser/src/lib.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 548 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~518d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/gluon-lang/gluon"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Gluon is a statically-typed, garbage-collected functional programming language written in Rust designed for embedding into Rust applications. It provides type inference, UTF-8 string support, separate heaps per thread for GC efficiency, and transparent marshalling between Rust and Gluon code—enabling developers to write safe scripting logic that runs alongside Rust without boilerplate FFI glue. Monorepo with workspace members: base/ (AST, types, symbols, error handling), check/ (type checker), parser/ (lexing/parsing), vm/ (bytecode VM), codegen/ (code generation), plus companion tools in repl/, completion/, format/, doc/. Core orchestration lives in src/lib.rs; language metadata and type flags in base/src/types/; runtime in vm/.

Rust application developers who need to embed a safe, typed scripting layer (game engines, configuration systems, plugin frameworks). Contributors are primarily language designers and compiler engineers interested in type systems, bytecode VMs, and functional language implementation.

Actively maintained at v0.18.2 with a monorepo structure, CI/CD via GitHub Actions (rust.yml, release.yml), comprehensive test suites in base/tests/, and a published book. The project is production-ready for embedded scripting but marked 'actively developed' rather than stable, as evidenced by the detailed CONTRIBUTING.md and ongoing feature work visible in the workspace structure.

Single primary author (Markus, marwes91@gmail.com) presents bus-factor risk. Dependency footprint is moderate but notable (salsa for incremental computation, codespan-reporting for diagnostics, tokio for async). The 'Parallel execution of gluon programs is a recent addition and may still have issues such as deadlocks' warning in README signals incomplete stability in concurrent scenarios.

Recent activity visible in CI workflows (rust.yml running on push/PR), semantic versioning maintained (0.18.2), and the changelog (CHANGELOG.md) discipline suggests active releases. The book/ directory indicates ongoing documentation effort for the embedding API.

git clone https://github.com/gluon-lang/gluon && cd gluon && cargo build && cargo test. The project uses Rust 2018 edition; ensure rustc is up to date. Run cargo run --example to explore examples/.

Daily commands: cargo build to compile all workspace crates; cargo run --bin gluon (if a binary exists) or cargo run --example <name> to run examples. For REPL: cargo build -p repl && ./target/debug/repl or similar path depending on platform.

• src/lib.rs — Main entry point for the gluon language library; all public APIs and primary module organization flow through here.
• base/src/ast.rs — AST definition is fundamental to parsing, type checking, and code generation; changes here ripple across the entire compiler pipeline.
• check/src/typecheck.rs — Core type inference and checking engine; this is where type safety is enforced before execution.
• base/src/types/mod.rs — Type system representation and operations; used by type checker, inference, and code generation.
• parser/src/lib.rs — Lexical analysis and parsing; the first stage of compilation that transforms source code into AST.
• Cargo.toml — Workspace configuration defining the multi-crate architecture and external dependencies for the entire project.

• Parser (parser/src/lib.rs) (LALRPOP, regex-based lexing) — Tokenizes source code and builds AST respecting Gluon's expression-oriented syntax
  • Failure mode: Syntax errors; reports location and expected tokens
• Type Checker (check/src/typecheck.rs) (Unification algorithm, substitution tables, recursive descent inference) — Infers types, unifies constraints, checks for type safety and kind correctness
  • Failure mode: Type mismatch, unresolved implicit, non-unifiable constraints; produces diagnostic with source location
• Code Generator (codegen/src/lib.rs) (Bytecode instruction set, static analysis for optimization) — Transforms typed AST into bytecode instructions for the VM
  • Failure mode: Internal compiler error (should not occur on valid input); stack overflow on deeply nested expressions
• Virtual Machine (vm/src/lib.rs) (Stack-based architecture, GC'd heap for values, native function pointers) — Executes bytecode with support for function calls, data structures, and Rust function invocation
  • Failure mode: Runtime error (divide by zero, type error in native function, stack overflow); panics or returns Err
• Type System (base/src/types/mod.rs) (Recursive algebraic data types, substitution maps) — Representation of types (function types, records, variants, forall, row polymorphism); unification operations
  • Failure mode: Unification failure; recursive type detected
• Embedding API (src/lib.rs) (Thread-local VM state, trait-based marshalling (Pushable, Getable)) — Public interface for loading, type-checking, and executing Gluon code from Rust; value marshalling
  • Failure mode: Compilation error, runtime error, or type mismatch during marshalling; all surfaced to caller

• User/Host Rust code → `` — undefined

Add a new built-in type

1. Define the Rust struct and implement Pushable/Getable traits for VM marshalling (codegen/src/lib.rs)
2. Register the type in the standard library module by adding it to the root environment (src/lib.rs)
3. Add type metadata and documentation comments so the type checker can reference it (base/src/metadata.rs)

Add a new syntax construct

1. Extend the AST with new expression or statement variants (base/src/ast.rs)
2. Add parsing rules in the parser to recognize the new syntax (parser/src/lib.rs)
3. Implement type checking logic for the new construct (check/src/typecheck.rs)
4. Add code generation for the new construct to produce bytecode (codegen/src/lib.rs)

Add a new standard library function

1. Implement the function as a Rust function exposing it via the embedding API (src/lib.rs)
2. Define its type signature and metadata for the type checker (base/src/metadata.rs)
3. Register it in the virtual machine's standard environment (vm/src/lib.rs)

Handle a new error case

1. Add a new error variant to the appropriate error enum (base/src/error.rs)
2. Implement error detection and reporting in the relevant phase (parser, type checker, etc.) (check/src/typecheck.rs)
3. Add tests verifying the error message and recovery behavior (check/tests/fail.rs)

• Rust — Memory safety without garbage collection, zero-cost abstractions for embedding, and strong type system mirror language design goals
• LALRPOP parser generator — Declarative grammar definition reduces parser bugs and makes syntax changes transparent and maintainable
• Multi-crate workspace (base, parser, check, codegen, vm, c-api) — Clear separation of concerns; allows independent compilation and testing; c-api crate enables FFI without exposing all internals
• Bytecode VM — Portable across platforms; interpreted execution allows tight integration with Rust host; simple to extend with new instructions

• Static typing with full type inference instead of dynamic typing

  • Why: Catches errors at compile time and enables better Rust↔Gluon marshalling with no boilerplate
  • Consequence: Type errors must be understood before execution; slightly longer feedback loop than dynamic languages

• Monomorphic bytecode VM over JIT compilation

  • Why: Simpler implementation, faster cold startup, more predictable performance, easier to embed and sandbox
  • Consequence: Cannot achieve peak performance of JIT-compiled code; better suited for application scripting than high-performance numerical computing

• Separate parsing, type checking, and code generation phases rather than single-pass

  • Why: Enables better error recovery and error messages; cleaner module boundaries; easier to add new features
  • Consequence: Slightly slower compilation; more memory overhead during compilation

• Eager type inference using unification rather than lazy or bidirectional checking

  • Why: Simpler to understand and implement; works well for straightforward functional code
  • Consequence: May require explicit type annotations in some complex polymorphic scenarios

• Not a systems programming language—no manual memory management or low-level hardware access
• Not designed for real-time or hard real-time use—garbage collection and lazy compilation not suitable
• Not a replacement for Rust—intended as a lightweight scripting layer, not standalone application development
• Not optimized for numerical/scientific computing—no SIMD support or specialized numeric libraries

1. Symbol resolution requires proper module import; unqualified names may fail to resolve if the prelude is not loaded. 2) Garbage collection is per-thread; sharing mutable state across gluon threads requires careful Arena pinning. 3) Type errors accumulate; the type checker may report cascading errors after the first mismatch—check the first error line carefully. 4) Async support (tokio features) is optional; enabling parallel execution requires careful deadlock avoidance as warned in README. 5) Cross.toml suggests cross-compilation; native dependencies (native-tls, hyper) may not compile on all targets without additional setup.

• Hindley-Milner Type Inference — Gluon's core feature; enables static typing without explicit type annotations, implemented in check/ crate—understanding this algorithm is essential to modifying the type checker
• Bytecode Virtual Machine — Gluon compiles to bytecode executed by vm/; understanding instruction sets, register allocation, and stack discipline is critical for codegen/ and vm/ changes
• Salsa Incremental Computation — Gluon uses salsa (gluon-salsa fork) for memoized, dependency-tracked compilation phases—changes to parser or checker must respect Salsa's query model for correctness
• Generational Garbage Collection (Per-Thread Heaps) — Each Gluon thread owns its own GC heap to reduce pause times and enable parallelism; this design choice impacts thread-safety guarantees and Arena pinning patterns in the embedding API
• Unification and Constraint Solving — Type inference relies on unifying type variables with concrete types and solving constraints; base/src/types/mod.rs implements this core algorithm
• Module System and Symbol Resolution — Gluon supports import statements and qualified names; base/src/symbol.rs manages scope and name resolution across module boundaries—essential for understanding how identifiers bind
• Marshalling / Serialization Bridges — Gluon's 'simple embedding' feature requires automatic marshalling between Rust types and Gluon values; serde integration and custom marshaller traits in src/ hide boilerplate

• rust-lang/rustlings — Interactive Rust learning; Gluon could serve as a companion scripting layer for a Rust application
• gluon-lang/gluon-lsp — LSP server for Gluon (if it exists as separate repo); completion/ crate suggests IDE tooling ecosystem
• luna-lang/luna — Another Rust-embedded functional language; direct design alternative solving similar embedding problem
• rune-rs/rune — Rust-based dynamic language with strong embeddability focus; immediate architectural competitor
• alacritty/alacritty — Rust GPU-accelerated terminal; demonstrates the ecosystem of high-performance Rust projects that might embed Gluon for config

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for the embedding API

The repo has book/src/embedding-api.md documentation but base/tests/ only contains compile-fail tests and type tests. There are no integration tests validating the embedding workflows described in the book (marshalling types, effects, modules). This would catch regressions in the C FFI layer and Rust embedding scenarios.

• [ ] Create base/tests/embedding_integration.rs with tests for marshalling basic types (integers, strings, functions)
• [ ] Add tests for embedding effects and async operations using the patterns shown in book/src/extending-the-guessing-game-with-effects.md
• [ ] Test module loading and namespace resolution as documented in book/src/modules.md
• [ ] Add tests validating the C API bindings in c-api/src/lib.rs work correctly with these scenarios

Add benchmark comparisons for type checking and code generation

The benches/ directory has check.rs, function_call.rs, and precompiled.rs, but there are no benchmarks comparing different optimization strategies or measuring the performance impact of the salsa incremental compilation (version 0.15.2 in Cargo.toml). Adding baseline benchmarks would help track performance regressions across the gluon_check and gluon_codegen crates.

• [ ] Create benches/typecheck_incremental.rs measuring salsa cache hit rates and incremental vs full type checking
• [ ] Create benches/codegen_performance.rs comparing code generation time for various program complexities
• [ ] Add a benchmark comparing parse + check + codegen pipeline with different optimization levels
• [ ] Document baseline numbers in the repository or CI

Add missing CI workflow for WASM and cross-platform builds

The repo has Cross.toml indicating cross-platform support intentions, but .github/workflows/ only contains release.yml and rust.yml (which likely test standard targets). There's no documented WASM target testing, despite gluon being embeddable. Adding WASM CI would validate the pin-project-lite optional dependency and catch platform-specific issues.

• [ ] Create .github/workflows/wasm.yml testing wasm32-unknown-unknown target using wasm-pack and wasm-bindgen
• [ ] Verify c-api builds without C dependencies for WASM target
• [ ] Add a workflow step testing the book examples compile on at least one additional platform (e.g., aarch64-unknown-linux-gnu via Cross.toml)
• [ ] Document supported platforms in README.md with CI badge

• Add serialize/deserialize derive tests in base/tests/types.rs for the new serde feature flags (serde, serde_state, serde_derive_state are present but test coverage unclear)
• Implement missing documentation examples for the completion/ crate (currently no book chapter and minimal inline docs for IDE integration)
• Add benchmarks in benches/ for the new parallel thread-local execution path mentioned in README to help validate thread-safety claims

The Gluon language codebase demonstrates generally good security practices as a programming language implementation. No critical vulnerabilities were identified. Main concerns are: (1) outdated dependencies like hyper 0.14.x instead of 1.x, (2) lack of visible TLS configuration documentation, (3) missing security policy documentation, and (4) limited visible context for input validation in regex and FFI operations. The codebase is well-structured with no obvious injection vectors, hardcoded secrets, or dangerous patterns in the visible file structure. Recommendations focus on dependency updates, security documentation, and ensuring proper validation in optional features like regex handling.

• Medium · Outdated hyper dependency — Cargo.toml - hyper dependency. The hyper dependency is pinned to version 0.14.27, which is in maintenance mode. Version 1.x is the actively maintained branch with security patches and improvements. Using an older major version may expose the application to known vulnerabilities. Fix: Upgrade hyper to the latest 1.x version and update code accordingly to use the new API.
• Medium · Native TLS dependency without verification — Cargo.toml - native-tls and tokio-native-tls dependencies. The native-tls crate (0.2.11) is included as an optional dependency. While the crate itself is reputable, TLS configuration is often mishandled. There's no evidence in the visible files of proper certificate validation or pinning configuration. Fix: Ensure TLS is configured with proper certificate verification enabled. Document TLS configuration requirements for users of this library. Consider using rustls as a pure-Rust alternative if appropriate.
• Low · Dependency on quick-error (deprecated) — Cargo.toml - quick-error dependency. The quick-error crate (2.0.1) is in maintenance mode and considered legacy. Modern Rust projects typically use thiserror or anyhow for error handling, which provide better ergonomics and more active maintenance. Fix: Consider migrating to thiserror for custom error types to benefit from active maintenance and modern error handling patterns.
• Low · Regex dependency without input validation context — Cargo.toml - regex dependency. The regex crate is included as an optional dependency but without visible context in the provided files about how user input is validated before regex processing. Improperly constructed regexes or unbounded regex operations could lead to ReDoS (Regular Expression Denial of Service). Fix: If regex is used with user-controlled patterns, implement strict limits on pattern complexity, size, and timeout mechanisms. Document regex security considerations.
• Low · No visible security audit trail — Repository root. No evidence of security audit documentation, SECURITY.md file, or vulnerability disclosure policy in the visible file structure. Fix: Create a SECURITY.md file documenting how security vulnerabilities should be reported. Consider establishing a vulnerability disclosure policy.
• Low · C API without visible safety documentation — c-api/src/lib.rs. A C API layer (c-api/) exists but there's no visible documentation about unsafe memory handling, bounds checking, or FFI safety considerations in the provided file structure. Fix: Document all unsafe code blocks with their safety invariants. Provide clear guidelines for C API users regarding memory safety, input validation, and error handling.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.