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/gleam-lang/gleam 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 the board

• Last commit today
• 12 active contributors
• Distributed ownership (top contributor 44% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{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 gleam-lang/gleam repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/gleam-lang/gleam.

What it runs against: a local clone of gleam-lang/gleam — 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 gleam-lang/gleam | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of gleam-lang/gleam. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/gleam-lang/gleam.git
#   cd gleam
#
# 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 gleam-lang/gleam and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "compiler-cli/src/lib.rs" \\
  && ok "compiler-cli/src/lib.rs" \\
  || miss "missing critical file: compiler-cli/src/lib.rs"
test -f "compiler-cli/src/cli.rs" \\
  && ok "compiler-cli/src/cli.rs" \\
  || miss "missing critical file: compiler-cli/src/cli.rs"
test -f "compiler-cli/src/build.rs" \\
  && ok "compiler-cli/src/build.rs" \\
  || miss "missing critical file: compiler-cli/src/build.rs"
test -f "compiler-cli/src/dependencies.rs" \\
  && ok "compiler-cli/src/dependencies.rs" \\
  || miss "missing critical file: compiler-cli/src/dependencies.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 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
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/gleam-lang/gleam"
  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).

Gleam is a statically-typed, functional programming language that compiles to both Erlang and JavaScript, designed to make building type-safe, scalable systems fast and pleasant. It runs on the BEAM VM (via Erlang) for backend systems and can compile to JavaScript for the browser, eliminating entire classes of runtime errors through exhaustive type checking and immutable-by-default semantics. Rust monorepo structured as Cargo workspace with 11 member crates: compiler-core (the type checker and code generator), compiler-cli (gleam command-line tool), compiler-wasm (browser-based compiler), language-server (LSP implementation for IDE support), and compiler variants for different targets. JavaScript runtime and Erlang prelude are committed alongside compiler code. Build artifacts flow: Rust compiler → gleam-bin binary → target language (Erlang/JS) → runtime execution.

Backend engineers and full-stack developers building distributed, fault-tolerant systems who want strong compile-time guarantees without verbose type annotations; teams migrating from Erlang/Elixir who want a more modern syntax; and JavaScript developers seeking type safety without TypeScript's complexity.

Actively developed with strong momentum: the repo shows Gleam v1.14+ in changelog, CI/CD is comprehensive (ci.yaml, release workflows, CodeQL scanning), and the language is used in production by early adopters. However, the ecosystem is still growing compared to Rust or Go—community packages exist but are smaller than mainstream languages. Production-ready for new projects with adoption risk being community library maturity, not language stability.

Standard open source risks apply.

Version 1.14+ actively maintained with recent changelog entries across v1.10–v1.16. CI workflows show continuous testing across release builds, nightly builds, and container deployments. Language-server and wasm compiler are priority features suggesting IDE/web tooling investment. Dependabot configuration indicates active dependency management. Benchmark suite (benchmark/list/) suggests performance work is ongoing.

Clone: git clone https://github.com/gleam-lang/gleam.git && cd gleam. Install Rust (required): curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh. Build: cargo build --release (Cargo.toml at root). Install binary: cargo install --path compiler-cli. Verify: gleam --version.

Daily commands: Development: cargo build generates gleam binary in target/debug/. CLI tool: cargo run -p compiler-cli -- --help to test commands (uses compiler-core). Language server: cargo build -p language-server starts LSP server on stdio (connect via editor config). Full test suite: cargo test --workspace runs all unit/integration tests across 11 crates. Makefile has convenience targets: make build, make test.

• Cargo.toml — Workspace configuration defining all member crates (compiler-cli, compiler-core, language-server, etc.) and shared dependencies—essential for understanding the project structure and build system.
• compiler-cli/src/lib.rs — Primary entry point for the CLI tool that orchestrates compilation, formatting, LSP, and package management—all main user interactions flow through here.
• compiler-cli/src/cli.rs — CLI argument parsing and command routing using clap—defines the public API of the Gleam compiler tool and how users invoke functionality.
• compiler-cli/src/build.rs — Core build orchestration logic that compiles Gleam projects—handles dependency resolution, incremental compilation, and target-specific code generation.
• compiler-cli/src/dependencies.rs — Dependency resolution and package management—interfaces with Hex, manages manifests, and handles semantic versioning constraints.
• compiler-cli/src/lsp.rs — Language Server Protocol implementation—enables IDE integration and real-time compiler feedback for developers.
• README.md — High-level project overview, vision statement, and link to sponsorship—every contributor should understand Gleam's design philosophy and funding model.

Add a new CLI command

1. Define the command struct and clap derive attributes in compiler-cli/src/cli.rs (compiler-cli/src/cli.rs)
2. Add a new match arm in the CLI handler to route to a new module (e.g., src/my_command.rs) (compiler-cli/src/lib.rs)
3. Implement the command logic module with appropriate error handling and file I/O (compiler-cli/src/my_command.rs)
4. Add integration tests in compiler-cli/test directories or use snapshot testing patterns from existing commands (compiler-cli/src/my_command.rs)

Add support for a new compilation target

1. Extend gleam.toml schema in compiler-cli/src/config.rs to accept the new target (compiler-cli/src/config.rs)
2. Create a new backend module (e.g., src/javascript_compiler.rs) following the pattern of compiler-cli/src/beam_compiler.rs (compiler-cli/src/javascript_compiler.rs)
3. Update compiler-cli/src/build.rs to select the appropriate backend based on gleam.toml target configuration (compiler-cli/src/build.rs)
4. Add target-specific code generation and linker logic in the new backend module (compiler-cli/src/javascript_compiler.rs)

Add a new dependency resolution strategy or constraint handler

1. Examine the current semver parsing and constraint logic in compiler-cli/src/dependencies/dependency_manager.rs (compiler-cli/src/dependencies/dependency_manager.rs)
2. Extend the resolution algorithm or add new constraint types to handle edge cases (compiler-cli/src/dependencies/dependency_manager.rs)
3. Add snapshot tests in compiler-cli/src/dependencies/tests.rs with expected behavior outputs (compiler-cli/src/dependencies/tests.rs)
4. Update manifest validation in compiler-cli/src/build_lock.rs if the lock file format changes (compiler-cli/src/build_lock.rs)

• Rust (Cargo) — Provides memory safety, zero-cost abstractions, and fast native compilation—critical for a compiler toolchain that must run reliably on developer machines and CI pipelines.
• BEAM (Erlang Virtual Machine) — Gleam compiles to Erlang/BEAM code, leveraging battle-tested distributed systems and hot-code-reload capabilities for production workloads.
• LSP (Language Server Protocol) — Enables editor-agnostic IDE integration (VS Code, Vim, Emacs, etc.) with real-time type checking and diagnostics without modifying individual editor plugins.
• Hex Package Manager — Standardized package distribution and dependency resolution—reuses Erlang ecosystem infrastructure while allowing Gleam to have its own package namespace.
• Clap (CLI framework) — Declarative command-line argument parsing with automatic help generation and validation—reduces boilerplate for managing the compiler's command surface.

• Monorepo with multiple Cargo members (compiler-cli, compiler-core, language-server, etc.) vs. single crate

  • Why: Allows separation of concerns: CLI is separate from core compiler logic, LSP is modular, WASM builds don't pull in CLI dependencies.
  • Consequence: Increased coordination overhead during refactors; some duplicated test infrastructure; requires discipline to maintain clear boundaries between members.

• Compile to BEAM/Erlang rather than directly to native code

  • Why: Leverages 40+ years of Erlang runtime maturity for fault tolerance, distribution, and OTP frameworks; shorter compilation times than full AOT.
  • Consequence: Performance ceiling set by BEAM VM; less suitable for compute-heavy or latency-critical workloads where native compilation would excel; adds Erlang as a runtime dependency.

• Build a custom dependency resolver instead of reusing cargo/npm resolvers

  • Why: Gleam-specific constraints (e.g., target-specific dependencies) and tight Hex integration require custom logic; avoids pulling in large external resolver frameworks.
  • Consequence: Maintenance burden for semver resolution and conflict handling; potential for subtle bugs in complex dependency scenarios; limited ecosystem of third-party resolver tools.

• Ship compiler as statically-linked binaries (Cross.toml) across multiple platforms

  • Why: Ensures consistent compiler behavior regardless of system Erlang/BEAM installation; reduces onboarding friction for new users.
  • Consequence: Larger binary size (~50–100 MB); must maintain separate release pipelines for Linux, macOS, Windows; requires tooling (Cross) for cross-compilation.

• Does not manage system-level Erlang/OTP installation—assumes or provides pre-built BEAM runtime; Gleam compiler itself is not a runtime.
• Does not provide a runtime-integrated package manager like npm's node_modules lock-in—delegates to Hex and manifests; package isolation is implicit.
• Does not compile directly to native machine code—transpiles to Erlang/BEAM; not suitable for bare-metal or kernel-level programming.
• Does not include a debugger, profiler, or performance analysis tools in core—assumes downstream tools in the BEAM ecosystem.
• Does not handle platform-specific system APIs directly—relies on Erlang OTP and external Gleam libraries for file I/O, networking, etc.

Workspace interdependencies: Changes to compiler-core require rebuilding compiler-cli, language-server, and compiler-wasm—cargo build --workspace is mandatory, not just individual crates. Snapshot tests: cargo test will fail diffs; use cargo insta review to accept/reject changes (non-obvious if you've never used insta). Erlang output targets: The compiler generates Erlang code that must compile with erlc; have Erlang OTP installed locally if testing Erlang backend (apt-get install erlang on Linux). WASM build: compiler-wasm requires wasm32-unknown-unknown target: rustup target add wasm32-unknown-unknown. Locking versions: lsp-types pinned to exact v0.95.1 in workspace.dependencies (not a range)—don't casually upgrade without checking LSP protocol compatibility. Cross-compilation: Cross.toml present suggests toolchain config needed for non-native targets (ARM, aarch64 binaries)—relevant for release builds, not typical dev work.

• BEAM VM (Bogdan/Ryszard Efficient Abstract Machine) — Gleam targets BEAM as its primary runtime for backend systems; understanding actor model, hot code reloading, and fault-tolerance primitives is essential for writing correct Gleam code
• Hindley-Milner Type Inference — Gleam's type checker uses HM-style inference to eliminate most type annotations while maintaining strong static guarantees; knowing how type variables unify explains compilation behavior
• Algebraic Data Types (ADTs) and Pattern Matching — Core to Gleam's expressiveness; exhaustive pattern matching on sum types prevents null/undefined errors and is enforced by the compiler in compiler-core/src/type_/
• PubGrub Dependency Resolution — Gleam's package manager uses pubgrub (v0.3 in workspace.dependencies) for conflict resolution; understanding version constraint solving prevents package lock issues
• LSP (Language Server Protocol) — Gleam implements LSP in language-server crate to power IDE features (autocomplete, diagnostics); required knowledge for IDE tooling contributions
• Immutable Data Structures (im v15 crate) — Compiler uses persistent/immutable collections for AST and type state to enable fearless concurrent passes; understanding COW semantics prevents performance surprises
• Snapshot Testing (insta framework) — Test suite uses insta snapshots for compiler output regression testing; misunderstanding snapshot mechanics leads to failed CI even when code is correct

• elixir-lang/elixir — Sibling language on BEAM VM with similar fault-tolerance goals but dynamic typing; Gleam users often come from or compare with Elixir
• erlang/otp — The BEAM VM and Erlang runtime that Gleam compiles to on the backend; essential dependency for understanding execution model
• gleam-lang/packages — Central package registry and package documentation hub for Gleam ecosystem; where third-party libraries are published and discovered
• microsoft/language-server-protocol — Specification and reference implementations for LSP that Gleam's language-server crate implements; required reading for IDE integration work
• ocaml/ocaml — Inspiration for Gleam's type system design (algebraic data types, pattern matching, type inference); architectural cousin in functional language space

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 snapshot tests for dependency resolution edge cases in compiler-cli

The compiler-cli/src/dependencies/ directory exists but the snapshots folder suggests incomplete test coverage. Given that pubgrub (0.3) is used for dependency resolution, adding snapshot tests for edge cases (circular dependencies, version conflicts, constraint violations) would improve robustness. This is high-value because dependency resolution is critical infrastructure that affects all users.

• [ ] Review existing tests in compiler-cli/src/dependencies/snapshots/
• [ ] Identify untested edge cases in compiler-cli/src/dependencies/dependency_manager.rs
• [ ] Add insta snapshot tests for: circular dependency chains, conflicting version constraints, optional dependency resolution
• [ ] Add integration tests in compiler-cli/tests/ that exercise pubgrub through the full dependency pipeline
• [ ] Document test cases in inline comments explaining what each snapshot validates

Add CodeQL security analysis workflow for Rust code analysis

The repo has .github/workflows/codeql.yml and .github/zizmor.yml (likely Zizmor/Clippy linting), but codeql.yml likely focuses on non-Rust languages. The workspace contains multiple Rust crates (compiler-cli, compiler-core, compiler-wasm, language-server) that should have dedicated security scanning. Adding Rust-specific CodeQL analysis would catch security issues in compiler and language-server code before they reach users.

• [ ] Examine current .github/workflows/codeql.yml to determine language coverage
• [ ] Create or enhance CodeQL configuration to include Rust analysis (uses: github/codeql-action/init with language: rust)
• [ ] Add rust-clippy linting as part of CI pipeline in .github/workflows/ci.yaml if not present
• [ ] Configure SARIF upload for results visualization
• [ ] Document any new security-related configuration in CONTRIBUTING.md

Add integration tests for WASM compiler output in compiler-wasm

The workspace includes compiler-wasm crate but there are no references to wasm-specific tests in the file structure. Given that Gleam targets multiple backends (Erlang/BEAM via compiler-cli, JavaScript, and WASM), adding tests that validate WASM compilation correctness, output size, and runtime behavior is critical. This ensures the wasm32-unknown-unknown target (with getrandom support already configured) works reliably.

• [ ] Create compiler-wasm/tests/ directory if it doesn't exist
• [ ] Add integration tests that compile sample Gleam code to WASM and validate output
• [ ] Add wasm-bindgen tests to verify JavaScript interop works correctly
• [ ] Include tests for: basic functions, pattern matching, list/dict operations, type safety
• [ ] Add benchmark tests in benchmark/ directory comparing WASM output size across versions
• [ ] Update CONTRIBUTING.md with instructions for testing WASM locally (using wasm-pack or similar)

• Add snapshot tests for compiler-core/src/codegen/erlang.rs output: currently the Erlang backend generates code but has minimal regression tests comparing generated Erlang AST to expected output. Create test cases covering pattern matching, list comprehensions, and module imports by examining existing JavaScript backend tests in tests/ and mirroring the structure.
• Expand language-server diagnostics for common type errors: LSP currently returns diagnostics but missing specific recovery suggestions for unification failures (e.g., 'Expected Int, got String'). Add helper text to language-server/src/diagnostics.rs that suggests type conversions or type annotation fixes, borrowing patterns from rustc or TypeScript error messages.
• Document missing Erlang standard library bindings in src/: Examine compiler-core/src/codegen/erlang.rs to find Erlang functions wrapped in Gleam (lists:reverse, dicts:, etc.), then add docstring comments and examples to src/.rs files showing why bindings matter. Low-risk, high-value for new users encountering 'function not found' errors.

The Gleam compiler codebase demonstrates a generally secure foundation with a well-structured Rust project using modern security-conscious dependencies. The main security concerns are: (1) one pinned dependency version preventing patch updates, (2) overly permissive version constraints on several core dependencies that could introduce unexpected changes, and (3) missing visibility into CI/CD security practices and formal vulnerability disclosure policies. The project uses well-maintained, reputable dependencies with no evidence of hardcoded secrets or common injection vulnerabilities. Recommendations focus on tightening dependency management, establishing clear security communication channels, and reviewing CI/CD pipeline security.

• Medium · Pinned LSP Types Version — Cargo.toml - workspace.dependencies. The lsp-types dependency is pinned to an exact version (0.95.1) using '=' instead of allowing compatible updates. This can prevent receiving critical security patches for LSP protocol implementations. The exact pinning notation '=0.95.1' prevents automatic patch updates. Fix: Change 'lsp-types = "=0.95.1"' to 'lsp-types = "0.95"' or 'lsp-types = "0.95.1"' to allow patch version updates while maintaining stability. Alternatively, establish a regular dependency update schedule to receive security patches.
• Low · Overly Permissive Dependency Version Constraints — Cargo.toml - workspace.dependencies. Several dependencies use '0' or '0.x' version constraints which allow major version changes. Examples include 'strum = "0"', 'tar = "0"', 'itertools = "0"', 'base16 = "0"', 'lsp-server = "0"', 'opener = "0"', and 'pubgrub = "0.3"'. While this facilitates receiving updates including security patches, it also increases the risk of unexpected breaking changes or introduced vulnerabilities in major versions. Fix: Review and incrementally tighten version constraints to specific minor versions (e.g., 'strum = "0.25"') after thorough testing. Implement automated dependency scanning and update review processes. Use Cargo's cargo audit regularly to identify known vulnerabilities.
• Low · Missing Security Configuration Review — .github/workflows/. The .github/workflows configuration files exist but were not provided for analysis. CI/CD pipelines are critical security components that require review for proper secret handling, artifact signing, and supply chain security. Fix: Review all workflow files for: (1) Proper secret management (no secrets in logs), (2) Dependency pinning in CI steps, (3) Artifact signing, (4) OIDC token usage instead of personal access tokens, (5) Branch protection rules configuration.
• Low · Unclear Security Update Process — Repository root. No SECURITY.md or security policy file is evident in the provided file structure. This makes it unclear how security vulnerabilities should be reported privately. Fix: Create a SECURITY.md file at the repository root following the GitHub security advisory format. Include: (1) How to report vulnerabilities responsibly, (2) Expected response timeframes, (3) Security contact information, (4) Commitment to address reported issues.

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.