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/amber-lang/amber 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
• 17 active contributors
• Distributed ownership (top contributor 23% of recent commits)
• LGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ LGPL-3.0 is copyleft — check downstream compatibility

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

What it runs against: a local clone of amber-lang/amber — 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 amber-lang/amber | Confirms the artifact applies here, not a fork | | 2 | License is still LGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch staging 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 amber-lang/amber. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/amber-lang/amber.git
#   cd amber
#
# 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 amber-lang/amber and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "src/compiler.rs" \\
  && ok "src/compiler.rs" \\
  || miss "missing critical file: src/compiler.rs"
test -f "src/modules/expression" \\
  && ok "src/modules/expression" \\
  || miss "missing critical file: src/modules/expression"
test -f "src/modules/builtin/mod.rs" \\
  && ok "src/modules/builtin/mod.rs" \\
  || miss "missing critical file: src/modules/builtin/mod.rs"
test -f "src/compiler/postprocessor.rs" \\
  && ok "src/compiler/postprocessor.rs" \\
  || miss "missing critical file: src/compiler/postprocessor.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/amber-lang/amber"
  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).

Amber is a compiled programming language that transpiles to Bash, allowing developers to write shell scripts in a high-level, type-safe syntax instead of raw Bash. It solves the problem of Bash's complexity and error-proneness by providing a modern language that outputs optimized, executable shell scripts—particularly suited for cloud services, DevOps automation, and infrastructure tooling. Workspace monorepo: main compiler (src/, Cargo.toml) written in Rust using heraclitus-compiler for parsing; meta/ subdirectory contains helper/dispatch utilities (meta/src/dispatch.rs, meta/src/manager.rs). Grammar defined in grammar.ebnf. Build tooling via build.rs. Debian/RPM packaging metadata indicates distribution-ready binaries. Scripts in scripts/ are written in Amber itself (e.g., scripts/docs.ab, scripts/keywords.ab)—eating its own dogfood.

DevOps engineers, infrastructure automation specialists, and shell script developers who want to write safer, more maintainable automation scripts without wrestling with Bash syntax, error handling, and portability issues. Contributors are primarily Rust developers interested in compiler design and language tooling.

Early-stage experimental project (v0.6.0-alpha) with active development visible in CI/CD pipelines (rust.yml, nix.yml, release.yml workflows), but explicitly marked as 'not ready for extended usage.' The codebase is well-structured with 687KB of Rust code and includes test infrastructure, but the alpha tag indicates breaking changes are expected.

Three main risks: (1) Alpha maturity with explicit warning against extended use suggests language syntax/semantics may change drastically, (2) dependency on heraclitus-compiler (a relatively specialized parsing library) and inventory framework for plugin registration creates architectural lock-in, (3) community appears small (Discord/Matrix/IRC channels only) with unclear maintainer count, so feature requests or critical bugs may stall. Rust 1.79 minimum version requirement is reasonable but should be monitored.

Active CI/CD testing on GitHub Actions (Rust tests, Nix builds, security scanning via zizmor.yml). Version 0.6.0-alpha in development. The codebase includes snapshot testing infrastructure (insta crate) and Docker-based test environments (TestEnvDockerfile). Debian/RPM packaging is integrated, suggesting focus on distribution and installation UX.

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

Or follow installation guide at https://docs.amber-lang.com/getting_started/installation. For Nix users, nix flake update && nix develop (flake.nix and .envrc present).

Daily commands:

cargo build --release
cargo test
./target/release/amber <script.ab>  # Compile Amber to Bash

For contributing: cargo build (dev), cargo test (run test suite), cargo fmt (format), cargo clippy (linting). Scripts in scripts/*.ab can be compiled to verify language features.

• src/main.rs — Entry point for the Amber compiler; processes command-line arguments and orchestrates the compilation pipeline.
• src/compiler.rs — Core compiler logic that coordinates lexing, parsing, and code generation for Amber→Bash transpilation.
• src/modules/expression — Expression evaluation and binary operator implementations; handles the semantic translation of Amber expressions to Bash equivalents.
• src/modules/builtin/mod.rs — Registry and dispatcher for all built-in functions (echo, cd, len, etc.) that Amber provides as language primitives.
• src/compiler/postprocessor.rs — Post-compilation optimization and shell code refinement; ensures generated Bash is efficient and correct.
• build.rs — Build-time script that prepares metadata and header files needed during compilation.
• Cargo.toml — Rust project manifest defining all dependencies, metadata, and package configuration for the Amber compiler.

• Compiler Core (src/compiler.rs) (Rust, AST processing) — Orchestrates the entire compilation pipeline: loads source, invokes parser, coordinates semantic analysis, delegates code generation.
  • Failure mode: Parse errors, semantic mismatches → compilation fails; invalid Amber syntax prevents script generation.
• Parser & AST (src/compiler.rs + modules) (Rust enums/pattern matching) — Tokenizes Amber source and builds abstract syntax tree; validates basic syntax structure.
  • Failure mode: Syntax errors detected; unclear error messages may frustrate users; malformed input causes panic or graceful error exit.
• Expression Evaluator (src/modules/expression — undefined

Add a new built-in function

1. Create a new module file in src/modules/builtin/ (e.g., src/modules/builtin/myfunction.rs) with a public function that returns Bash code as a String. (src/modules/builtin/myfunction.rs)
2. Add mod myfunction; to src/modules/builtin/mod.rs to register your module. (src/modules/builtin/mod.rs)
3. In src/modules/builtin/mod.rs, add a match arm in the function dispatcher that recognizes 'myfunction' and calls your implementation. (src/modules/builtin/mod.rs)
4. Write Bash shell code in your module's function that performs the operation and return it as a transpiled String. (src/modules/builtin/myfunction.rs)

Add a new binary operator

1. Create a new file in src/modules/expression/binop/ (e.g., src/modules/expression/binop/myop.rs) with evaluation logic. (src/modules/expression/binop/myop.rs)
2. Import and register your operator in src/modules/expression/binop/mod.rs by adding a match case for the operator symbol. (src/modules/expression/binop/mod.rs)
3. Implement the BinaryOp trait with an eval() method that generates equivalent Bash code for the left and right operands. (src/modules/expression/binop/myop.rs)

Add support for a new language statement

1. Create a new module in src/modules/ (e.g., src/modules/mystatement.rs) to handle parsing and code generation. (src/modules/mystatement.rs)
2. Register the module in src/modules/mod.rs and add it to the statement dispatcher. (src/modules/mod.rs)
3. Implement parsing logic to recognize your statement syntax in the compiler's tokenizer/AST builder. (src/compiler.rs)
4. Generate equivalent Bash code by implementing code generation in your statement module that returns a String. (src/modules/mystatement.rs)

Improve Bash output optimization

1. Review the postprocessor in src/compiler/postprocessor.rs to understand the current optimization passes. (src/compiler/postprocessor.rs)
2. Add a new transformation function in postprocessor.rs that identifies inefficient Bash patterns and rewrites them. (src/compiler/postprocessor.rs)
3. Call your optimization pass from the main postprocess() function in the correct order (before or after shell resolution). (src/compiler/postprocessor.rs)

• Rust — Provides memory safety, zero-cost abstractions, and excellent performance for a compiler; strong type system catches semantic errors at compile-time.
• Bash as compilation target — Makes Amber scripts portable across Unix-like systems; no runtime dependency required, scripts execute directly on any POSIX shell.
• Modular architecture (src/modules/) — Separates concerns: expressions, builtins, conditions, commands; allows independent extension of language features without coupling.

• Compile to Bash instead of bytecode/VM

  • Why: Maximizes portability and eliminates runtime dependencies for end users.
  • Consequence: Bash semantics and quirks must be carefully handled during code generation; performance optimizations are limited to Bash's capabilities.

• Single-pass compilation with postprocessing

  • Why: Simplifies compiler structure and speeds up compilation for simple scripts.
  • Consequence: Some advanced optimizations and cross-module analysis may be difficult; error recovery is limited.

• Language still marked alpha/unstable

  • Why: Allows rapid iteration and breaking changes without committed API stability.
  • Consequence: Not recommended for production use; frequent incompatibilities with previous versions expected.

• Real-time script execution or REPL-based evaluation
• Strict type safety enforced at compile time (Amber allows dynamic typing compatible with Bash)
• Cross-platform GUI application development
• Direct compilation to machine code (only Bash scripts)
• Package manager or ecosystem beyond setup scripts
• Windows native support (relies on Bash, inherently Unix-oriented)

Bash portability: Compiled scripts must work across Bash versions (likely 3.x+) due to shell script use-case—test on macOS /bin/bash (v3.x) and Linux bash (v4.x+). Nix builds: If using Nix tooling, .envrc and flake.nix must be trusted via direnv allow and synced with Cargo.lock. Snapshot tests (insta): Adding/modifying codegen requires reviewing and accepting insta snapshot diffs (cargo insta review); easy to miss in CI. Plugin system: inventory crate auto-registers modules at compile time—new codegen passes may need explicit inventory::submit! macro calls. Alpha instability: grammar.ebnf and codegen output may change between versions; pin Amber version in scripts or expect rewrites.

• Transpilation / Source-to-Source Compilation — Amber's core model: compile Amber → valid Bash; understanding AST transformation and code generation is fundamental to extending the language or debugging output.
• PEG (Parsing Expression Grammar) — heraclitus-compiler uses PEG-style parsing; grammar.ebnf is the language spec, and understanding ordered choice and memoization helps debug parser edge cases.
• Snapshot Testing / Golden Testing — Amber uses insta for snapshot tests; codegen changes are validated by comparing output Bash scripts against stored snapshots—critical for maintaining correct code generation without false negatives.
• Plugin Architecture via Inventory Registration — Amber uses inventory crate for compile-time registration of codegen passes and stdlib functions; new contributors adding language features must understand this zero-runtime-cost plugin system.
• Bash Portability & Shell Compatibility — Generated Bash scripts must work across POSIX sh, bash 3.x (macOS), and bash 4.x+ (Linux); understanding errexit, pipefail, and variable quoting edge cases is essential for safe codegen.
• Rayon Parallel Iterators — Amber uses rayon for parallelizing compilation of multiple files; understanding work-stealing and thread pool tuning helps with compiler performance optimization.
• Type Safety in Dynamic Context (Bash) — Amber provides type annotations and safety guarantees but outputs dynamically-typed Bash; understanding how type information is erased during codegen and what runtime checks remain is key to language design.

• bats-core/bats-core — Bash testing framework; essential for validating that Amber-compiled scripts run correctly across Bash versions and edge cases.
• koalaman/shellcheck — Shell script linter used in .github/workflows; Amber codegen should pass shellcheck cleanly to ensure quality output.
• nix-community/nixpkgs — Package manager integration point; Amber is distributed via Nix (flake.nix present), and many users will install via nixpkgs.
• rust-lang/rustc — Inspiration for compiler architecture (multi-stage compilation, error diagnostics); Amber uses similar patterns via heraclitus-compiler.
• ash-rs/ash — Alternative system language that compiles to C; shares similar problem domain (high-level syntax → lower-level output) and transpiler philosophy.

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 tests for src/compiler/shell_resolve.rs

The shell_resolve.rs module handles critical shell command resolution and compilation logic, but there are no dedicated test files visible in the repo structure. Given that this is a compiler that outputs Bash, robust testing of shell resolution is essential to prevent silent compilation bugs. New contributors can add unit tests covering edge cases like variable substitution, command piping, and shell builtins.

• [ ] Create tests/compiler_shell_resolve.rs with test cases for common shell patterns
• [ ] Test edge cases: nested variable expansion, command substitution in different contexts
• [ ] Test shell builtin resolution and conflict handling
• [ ] Integrate tests into the existing test suite (referenced in scripts/sh_tester.ab)
• [ ] Add documentation comments explaining what each test validates

Add linting workflow with Clippy and strict warnings for PRs

The repo has a .github/workflows/rust.yml but there's no explicit Clippy linting step visible. As a compiler written in Rust targeting alpha quality, enforcing Rust code quality through Clippy with deny-warnings would catch potential bugs early. This workflow should run on all PRs and fail if warnings are found.

• [ ] Examine existing .github/workflows/rust.yml to avoid duplication
• [ ] Add Clippy job to rust.yml with RUSTFLAGS='-D warnings'
• [ ] Configure allowed Clippy lints in src/lib.rs or via .clippy.toml
• [ ] Test locally with 'cargo clippy -- -D warnings' to identify existing violations
• [ ] Document the linting requirement in CONTRIBUTING.md or link from docs

Add integration tests for src/modules/builtin modules against Bash output

The src/modules/builtin directory contains compiled-to-Bash implementations of core language features, but there's no visible integration test suite that validates the generated Bash actually executes correctly. New contributors can create a test harness that compiles Amber code to Bash and executes it, verifying correctness. This would be particularly valuable given the complexity of Bash codegen.

• [ ] Create tests/integration/ directory for end-to-end tests
• [ ] Write test helper in tests/integration/bash_runner.rs that compiles Amber→Bash→executes
• [ ] Create test cases covering builtin modules: variable assignment, control flow, array operations
• [ ] Use TinyHttp (already in dev-dependencies) to test network-related builtins if present
• [ ] Add tests to CI pipeline in .github/workflows/rust.yml with bash version checking
• [ ] Document expected Bash version requirements based on features used

• Add comprehensive codegen tests for control flow (if/else/loops) by creating Amber test scripts in tests/ with corresponding snapshot files; currently unclear if all Bash edge cases (errexit, pipefail interaction) are covered.
• Document the heraclitus-compiler integration in a guide (e.g., under docs/ or README.md) explaining how the grammar.ebnf maps to parser stages and AST nodes; new contributors struggle to find where parsing errors occur.
• Create shell script linting CI checks beyond shellcheck: add ShellFormat or similar static analysis to catch common Bash anti-patterns in generated code (unquoted variables, missing set -e checks, etc.).

The Amber language compiler project has a moderate security posture. The primary risk stems from the nature of the project itself—compiling high-level code to Bash—which inherently involves shell injection risks if the compiler doesn't properly sanitize output. Key concerns include: (1) insufficient documentation on injection protection mechanisms in the compiler, (2) reliance on an external compiler library (heraclitus-compiler) without visible security audits, (3) potential unsafe patterns in generated Bash headers, and (4) limited security-focused CI/CD controls. The codebase appears well-maintained with modern Rust practices and pinned dependencies, but lacks explicit security testing, SBOM generation, and a security disclosure policy. Recommend implementing security-focused compiler validation tests, conducting dependency audits, and establishing clear security guidelines before production use.

• Medium · Potential Shell Injection in Bash Compilation — src/compiler/, src/modules/builtin/. The project compiles Amber code to Bash scripts. There is inherent risk of shell injection vulnerabilities if the compiler doesn't properly sanitize/escape user input or string interpolation. The codebase includes modules for shell operations (cd, rm, cp, mv) which are high-risk if improperly compiled. Fix: Implement strict input validation and output escaping in the compiler. Ensure all variable expansions in generated Bash code are properly quoted. Add security-focused tests for injection attack vectors. Consider using shellcheck integration (noted in .github/shellcheck-matcher.json) systematically.
• Medium · Dependency on Community Compiler Library — Cargo.toml (dependencies: heraclitus-compiler). The project depends on 'heraclitus-compiler' (v1.9.0) which is an external compiler library. While versions are pinned in Cargo.lock, there's no evidence of security audit or vendor verification of this critical dependency. Fix: Conduct security audit of heraclitus-compiler dependency. Enable cargo-audit in CI/CD to detect known vulnerabilities. Consider maintaining dependency update strategy with security testing.
• Medium · Unsafe Bash Script Header Inclusion — src/header.sh. The project includes a header.sh file (src/header.sh) that is embedded in generated Bash scripts. If this header contains unsafe patterns or is not properly validated, it could introduce vulnerabilities into all compiled scripts. Fix: Review src/header.sh for unsafe patterns. Ensure all shell variables are properly quoted. Use shellcheck on header.sh. Document security assumptions made by the header.
• Low · Build System Uses External Helper — Cargo.toml (build-dependencies). The build process uses 'build-helper' crate (v0.1.1) and 'built' crate with git2 features. These add complexity to the build process and potential supply chain risk. Fix: Verify build dependencies are from trusted sources. Consider if git2 feature in 'built' crate is necessary. Use cargo-tree to visualize transitive dependencies.
• Low · Development HTTP Server in Dependencies — Cargo.toml (dev-dependencies: tiny_http). The 'tiny_http' crate is included in dev-dependencies. If accidentally used in production code, it could expose unintended endpoints. Fix: Ensure tiny_http is only used in tests and examples. Add linting rules to prevent accidental inclusion in production code paths.
• Low · No SBOM or Lockfile Security Validation — .github/workflows/, Cargo.lock. While Cargo.lock exists, there's no evidence of automated SBOM generation or software composition analysis in the CI/CD pipeline. Fix: Add cargo-sbom or similar tools to generate SBOMs. Integrate cyclonedx-rust-cargo for supply chain security. Add dependency scanning in CI/CD.
• Low · Incomplete Security Policy — Repository root. No visible SECURITY.md or security policy file in the repository for responsible disclosure of vulnerabilities. Fix: Create SECURITY.md with vulnerability disclosure policy, supported versions, and contact information. Consider adding security.txt configuration.

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.