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/borgo-lang/borgo 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.

AVOID — Stale and unlicensed — last commit 2y ago

• 2 active contributors
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 99% of recent commits
• ⚠ No license — legally unclear to depend on

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

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

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

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

# 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 "compiler/src/main.rs" \\
  && ok "compiler/src/main.rs" \\
  || miss "missing critical file: compiler/src/main.rs"
test -f "compiler/src/parser.rs" \\
  && ok "compiler/src/parser.rs" \\
  || miss "missing critical file: compiler/src/parser.rs"
test -f "compiler/src/infer.rs" \\
  && ok "compiler/src/infer.rs" \\
  || miss "missing critical file: compiler/src/infer.rs"
test -f "compiler/src/codegen.rs" \\
  && ok "compiler/src/codegen.rs" \\
  || miss "missing critical file: compiler/src/codegen.rs"
test -f "compiler/src/ast.rs" \\
  && ok "compiler/src/ast.rs" \\
  || miss "missing critical file: compiler/src/ast.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 588 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~558d)"
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/borgo-lang/borgo"
  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).

Borgo is a statically-typed programming language that transpiles to Go, offering Rust-like syntax and type safety (algebraic data types, pattern matching, Result<T,E>, Option<T>) while maintaining full compatibility with existing Go packages. It solves the gap between Go's simplicity and Rust's expressiveness by providing a higher-level language that compiles to idiomatic Go code. Monorepo structure: compiler/ (Rust) contains the core transpiler split into lexer.rs → parser.rs → infer.rs (type inference) → codegen.rs (Go emission). Separate wasm/ member for browser playground. Tests live in compiler/test/ as markdown files (codegen-emit.md, infer-expr.md) with snapshot comparisons in compiler/test/snapshot/codegen-emit/. Prelude types defined in compiler/test/prelude.brg.

Go developers who want stronger type safety and more expressive pattern matching without learning Rust; backend engineers building applications where Go's lack of enums and sum types feels limiting; developers who value interoperability with Go ecosystem (stdlib, third-party packages) but prefer a safer language.

Experimental/Early-stage. The project has a working compiler (365KB Rust codebase), comprehensive test suite via snapshot testing (compiler/test/snapshot/codegen-emit with 50+ .exp files), and CI/CD setup (.github/workflows/ci.yml), but is too new and small for production use. The large Rust component and sparse Go output (18KB) suggest an actively developed transpiler, not yet battle-tested.

Single-maintainer risk is high (no visible team in description). The transpiler is young—breaking changes to Borgo syntax are likely as the design stabilizes. Dependency on Rust toolchain for compilation adds friction. No visible release process or versioning strategy. Go compatibility layer not yet proven at scale.

Active development on type inference (infer.rs) and code generation (codegen.rs). The test snapshot directory shows recent work on enums, pattern matching, concurrency primitives, and error handling. The online playground (referenced in README) suggests ongoing user-facing polish. No visible recent commits or PR data provided, but test coverage indicates regular iteration.

git clone https://github.com/borgo-lang/borgo.git
cd borgo
cargo build --release
./target/release/borgo --help

Or try the online playground at https://borgo-lang.github.io/ without local installation.

Daily commands: Build the compiler: cargo build --release. Run tests: cargo test (Rust unit tests) or npm test (TypeScript snapshot tests in compiler/test/). The Justfile likely contains convenience recipes—check just --list. No dev server; this is a batch compiler.

• compiler/src/main.rs — Entry point for the Borgo compiler; orchestrates lexing, parsing, type inference, and code generation pipeline.
• compiler/src/parser.rs — Parses Borgo source code into an AST; foundational for all downstream compilation stages.
• compiler/src/infer.rs — Implements type inference and checking; ensures type safety before Go code generation.
• compiler/src/codegen.rs — Transforms typed AST into Go source code; the final critical stage that produces executable output.
• compiler/src/ast.rs — Defines the abstract syntax tree structure used throughout parsing, inference, and code generation.
• compiler/src/type_.rs — Core type system implementation including unification, substitution, and type representation.
• compiler/Cargo.toml — Rust project manifest; defines dependencies and build configuration for the compiler.

• Lexer (lexer.rs) (Rust pattern matching, Unicode support) — Tokenizes Borgo source; handles strings, numbers, operators, keywords, and whitespace
  • Failure mode: Invalid tokens → early parse error; unclosed strings or invalid escape sequences
• Parser (parser.rs) (Recursive descent, operator precedence, error recovery) — Recursive descent parser; builds AST respecting Borgo's expression-oriented syntax
  • Failure mode: Syntax error with location; mismatched braces, unexpected tokens
• Type Inferencer (infer.rs + type_.rs) (Constraint generation, unification, substitution, pattern matching) — Hindley-Milner style inference; solves type constraints and checks exhaustiveness
  • Failure mode: Type mismatch, undeclared variables, non-exhaustive patterns → compile error with context
• Code Generator (codegen.rs) (String building, Go AST (internal representation)) — Emits Go source from typed AST; handles struct layouts, method dispatch, and FFI to Go packages
  • Failure mode: Invalid Go code generated → compile fails at go build stage (should not happen with correct inference)
• Prelude (prelude.rs) (Type definition, standard library bindings) — Defines built-in types (Result, Option, List, etc.) and their Go equivalents
  • Failure mode: Missing or incorrect prelude definition → inference failures

• Borgo source file → Lexer — Raw text → token stream

Add a new language feature (e.g., new expression type)

1. Define new AST node variant in the Expression or Statement enum (compiler/src/ast.rs)
2. Add parser rule to handle the new syntax (compiler/src/parser.rs)
3. Implement type inference rule for the new node in infer_expr or infer_stmt (compiler/src/infer.rs)
4. Add code generation logic to emit Go code (compiler/src/codegen.rs)
5. Add snapshot test cases to verify parsing, inference, and codegen (compiler/test/codegen-emit.md)

Add a new built-in type or standard library binding

1. Define the type structure in the prelude module (compiler/src/prelude.rs)
2. Add inference rules for constructors or methods in infer.rs if needed (compiler/src/infer.rs)
3. Map the type to its Go equivalent in code generation (compiler/src/codegen.rs)
4. Add test cases validating instantiation and usage (compiler/test/infer-expr.md)

Fix or enhance type inference behavior

1. Identify the inference function handling the construct (infer_expr, infer_stmt, infer_call, etc.) (compiler/src/infer.rs)
2. Modify the constraint generation or unification logic (compiler/src/infer.rs)
3. Update type substitution if new type variables are involved (compiler/src/substitute.rs)
4. Add or update snapshot test to validate the new behavior (compiler/test/infer-expr.md)

Add a new compiler error or improve error reporting

1. Define new error variant in the CompileError or TypeError enum (compiler/src/error.rs)
2. Emit the error from the appropriate checker (parser, inference, codegen) (compiler/src/infer.rs)
3. Add a test case that triggers the error condition (compiler/test/infer-expr.md)

• Rust — Compiler written in Rust for memory safety and performance; no runtime overhead during type checking
• Go (target) — Borgo transpiles to Go, leveraging its simplicity, concurrency primitives, and rich standard library
• Hindley-Milner type inference — Enables expressive type safety with minimal annotations, bridging Rust-like correctness and Go-like readability
• Snapshot testing (Markdown + TypeScript) — Embedded test files verify parser, inference, and codegen output; easy to inspect and maintain golden files

• Transpilation to Go vs. self-hosted runtime

  • Why: Leverages existing Go ecosystem and tooling; eliminates need to implement a new runtime
  • Consequence: Borgo is tightly coupled to Go semantics; harder to add non-Go-like features (e.g., full pattern matching on mutable state)

• Single-pass inference with bidirectional flow vs. multi-pass

  • Why: Faster compilation and simpler implementation
  • Consequence: Some inference scenarios require explicit type annotations; less inference power than two-way constraint solving

• Monolithic compiler (lexer → parser → infer → codegen in sequence)

  • Why: Straightforward pipeline; easy to debug and test each stage
  • Consequence: Harder to implement incremental compilation or parallel type checking across modules

• Does not aim to be a systems language; performance optimization and low-level control are secondary
• Not attempting runtime polymorphism or dynamic dispatch beyond Go interfaces
• Does not provide its own package manager; relies on Go modules
• Not a Go replacement; Borgo is for new code that needs stronger types, not for rewriting existing Go

1. Snapshot test format: Tests in .md files use code blocks followed by expected output in comments; the test runner (runner.ts) parses and compares them, not standard cargo test. Easy to break if you don't know the format. 2) Go code emission: codegen.rs produces Go that must be valid—type mismatches between Borgo and Go types can silently compile to broken Go. 3) Prelude coupling: The prelude.brg and prelude.rs must stay in sync; Option/Result definitions must match Go semantics. 4) No version constraints visible: No Cargo.lock hints on Rust MSRV or Go version target—unclear if this compiles on older toolchains. 5) Test discovery: Tests live in markdown files, not standard Rust test modules; contributors might miss them.

• Algebraic Data Types (ADTs) and Sum Types — Borgo's enums are sum types (NetworkState.Loading | Failed(int) | Success(string)); understanding ADTs is critical to using pattern matching safely and modeling domain logic.
• Pattern Matching and Exhaustiveness Checking — Borgo guarantees all enum variants are handled via exhaustive.rs; this is a core safety feature missing in Go. Understanding how the compiler verifies coverage prevents silent bugs.
• Hindley-Milner Type Inference — infer.rs implements constraint-based type inference similar to Haskell/ML; contributors must understand unification and type variable substitution to extend the type system.
• Transpilation vs. Compilation — Borgo is a transpiler (source→source, not source→machine code). This means debugging must account for the generated Go; understanding Go output is critical to troubleshooting Borgo code.
• Option and Result Monads — Borgo uses Option<T> and Result<T,E> instead of nil and error returns; understanding monadic composition and the ? operator (syntactic sugar for Result unwrapping) is essential.
• Go Interoperability and FFI — Borgo code calls Go stdlib packages directly (fmt, os, net.http). The interop layer in prelude.rs bridges Borgo's type system to Go's; understanding this boundary is critical for real-world code.
• Snapshot Testing — Borgo's test suite uses markdown snapshot files (compiler/test/codegen-emit.md) instead of traditional unit tests. Understanding this format is required to write or debug tests.

• golang/go — The target runtime; understanding Go's type system and code patterns is essential since Borgo emits Go code.
• rust-lang/rust — Inspiration for Borgo's syntax (pattern matching, Result/Option), error handling, and ownership model (adapted for GC).
• CUE-lang/cue — Alternative transpiled-to-Go language with similar goals (Go compatibility + stronger typing); studying its approach informs Borgo design.
• elm-lang/compiler — Reference implementation for pattern match exhaustiveness checking and functional-style error handling that Borgo emulates.
• borgo-lang/borgo-lang.github.io — Official website and online playground source; needed to understand the web frontend and deployment model.

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 snapshot tests for parser edge cases (parse-expr.md)

The repo has codegen-emit snapshot tests with ~40+ .exp files covering various language features, but parse-expr.md test file exists with no corresponding snapshot directory visible. Parser is critical infrastructure (compiler/src/parser.rs) that should have comprehensive snapshot coverage for edge cases like operator precedence, destructuring patterns, and error recovery. This ensures parser stability as the language evolves.

• [ ] Review compiler/test/parse-expr.md to identify test cases that lack corresponding .exp snapshot files
• [ ] Create compiler/test/snapshot/parse-expr/ directory if missing
• [ ] Add .exp snapshot files for complex parser scenarios: nested destructuring, operator precedence chains, generic type syntax, malformed input recovery
• [ ] Update compiler/test/runner.ts to ensure parse-expr tests are executed in CI

Add type inference snapshot tests for advanced patterns (infer-expr.md and infer-file.md)

Type inference (compiler/src/infer.rs) is a complex subsystem with two test markdown files but no visible snapshot directory in compiler/test/snapshot/. Given that the codebase has infer.rs, substitute.rs, and type_.rs files, snapshot tests for type unification, generic resolution, and error cases would catch regressions early. This is especially critical since type safety is Borgo's key differentiator from Go.

• [ ] Create compiler/test/snapshot/infer-expr/ and compiler/test/snapshot/infer-file/ directories
• [ ] Add snapshots for: generic type instantiation, constraint solving, polymorphic function inference, type mismatch error messages
• [ ] Document expected type inference behavior in snapshot files matching codegen-emit test format
• [ ] Integrate into test runner to execute alongside existing tests in CI

Add Go interop validation tests (compiler/test/snapshot/codegen-emit/)

The README emphasizes 'fully compatible with existing Go packages' and there are two net-http.exp and native-call-to-result.exp tests, but no comprehensive suite for Go FFI. The Go compatibility story is a core selling point. Missing are snapshot tests for: calling Go functions with various signatures, handling error returns, using Go structs in Borgo, generics interop limitations, and unsafe pointers. These would document and enforce the FFI contract.

• [ ] Create additional .exp snapshot files in compiler/test/snapshot/codegen-emit/: go-string-interop, go-error-handling, go-interface-implementation, go-reflection-usage, go-goroutine-calls
• [ ] Document expected generated Go code for each interop pattern
• [ ] Add tests that call stdlib packages (strings, fmt, json) to verify real-world compatibility
• [ ] Update README with Go interop examples referencing these snapshot tests

• Add missing snapshot tests for Option<T> and Result<T,E> error paths in compiler/test/snapshot/codegen-emit/. Many happy-path examples exist, but edge cases like nested Result chains and nested Options are absent—write Borgo code and compare Go output.
• Expand compiler/src/error.rs with concrete error messages. Currently error reporting likely prints generic messages; add source location tracking and context-aware hints (e.g., 'type mismatch: expected Option<int>, got int; did you forget to unwrap?') similar to Rust's rustc.
• Document the type inference algorithm in compiler/src/infer.rs with inline comments. The constraint-based inference is non-obvious; a junior can add comments explaining unification, constraint generation, and substitution without changing logic, making code more maintainable.

The Borgo compiler codebase appears reasonably secure from a code structure perspective. It's a compiler written in Rust (memory-safe), with no apparent hardcoded secrets, SQL injection risks, or exposed credentials visible in the provided file structure. The main security concerns are operational: lack of a defined security reporting policy, missing dependency vulnerability scanning in the CI/CD pipeline (no evidence in provided workflows), and the need for robust input validation testing given that the compiler processes untrusted user input. The codebase would benefit from fuzz testing of the parser/lexer and integration of security scanning tools into the CI/CD workflow.

• Low · Workspace resolver version not explicitly pinned — Cargo.toml. The Cargo.toml uses resolver = '2' which is a relative version specification. While this is generally safe for workspace configurations, it could potentially allow unexpected behavior across different Rust/Cargo versions. Fix: Consider documenting the minimum required Rust version in rust-toolchain.toml or MSRV specification for reproducible builds.
• Low · No security policy defined — .github/. The repository does not appear to have a SECURITY.md file visible in the provided structure. This makes it unclear how security vulnerabilities should be reported privately. Fix: Create a SECURITY.md file outlining responsible disclosure procedures and contact information for reporting security issues.
• Low · Limited visibility into dependency vulnerabilities — Cargo.lock. The Cargo.lock file exists but its content was not provided for analysis. Without examining pinned dependency versions, transitive dependency vulnerabilities cannot be fully assessed. Fix: Regularly run 'cargo audit' in CI/CD pipeline to detect known vulnerabilities in dependencies. Integrate dependency scanning tools like dependabot or cargo-deny.
• Low · No apparent input validation framework visible — compiler/src/lexer.rs, compiler/src/parser.rs. As a compiler codebase, the lexer and parser components handle untrusted input (user code). While the structure suggests these are present, there's no visible evidence of comprehensive input sanitization or fuzz testing configuration. Fix: Implement fuzzing tests (cargo-fuzz) for parser and lexer components. Add comprehensive error handling for malformed input to prevent DoS attacks from pathological inputs.

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.