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/killme2008/aviatorscript 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.

WAIT — Missing license — unclear to depend on

• Last commit 2mo ago
• 8 active contributors
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 90% 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 killme2008/aviatorscript repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/killme2008/aviatorscript.

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

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

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

# 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/main/java/com/googlecode/aviator/AviatorEvaluator.java" \\
  && ok "src/main/java/com/googlecode/aviator/AviatorEvaluator.java" \\
  || miss "missing critical file: src/main/java/com/googlecode/aviator/AviatorEvaluator.java"
test -f "src/main/java/com/googlecode/aviator/Expression.java" \\
  && ok "src/main/java/com/googlecode/aviator/Expression.java" \\
  || miss "missing critical file: src/main/java/com/googlecode/aviator/Expression.java"
test -f "src/main/java/com/googlecode/aviator/BaseExpression.java" \\
  && ok "src/main/java/com/googlecode/aviator/BaseExpression.java" \\
  || miss "missing critical file: src/main/java/com/googlecode/aviator/BaseExpression.java"
test -f "src/main/java/com/googlecode/aviator/EvalMode.java" \\
  && ok "src/main/java/com/googlecode/aviator/EvalMode.java" \\
  || miss "missing critical file: src/main/java/com/googlecode/aviator/EvalMode.java"
test -f "src/main/java/com/googlecode/aviator/InterpretExpression.java" \\
  && ok "src/main/java/com/googlecode/aviator/InterpretExpression.java" \\
  || miss "missing critical file: src/main/java/com/googlecode/aviator/InterpretExpression.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 95 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~65d)"
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/killme2008/aviatorscript"
  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).

AviatorScript is a high-performance JVM-hosted scripting language (v5.4.4-SNAPSHOT) that compiles scripts directly to Java bytecode via ASM or runs in interpreter mode for Android compatibility. It provides first-class functions, closures, operator overloading for BigDecimal/BigInt types, and a Sequence abstraction for functional collection processing—enabling dynamic script execution without external dependencies. Monolithic Java project: core compiler and interpreter in src/main/java (likely com.googlecode.aviator package), extensive example scripts in examples/ (35+ .av files demonstrating syntax/features), test suite in src/test, and shell wrapper at bin/aviator for CLI execution. Pre-built JARs versioned in downloads/ for quick local testing.

Java backend engineers and rule-engine developers who need to evaluate dynamic expressions, formulas, and conditional logic at runtime (e.g., risk assessment rules, pricing calculations, ETL data transformations) without spinning up a full scripting runtime like Groovy or Nashorn.

Production-ready and actively maintained. The project has stable releases (5.4.3 released, 5.4.4-SNAPSHOT in progress), comprehensive test coverage (evident from /src/test directory), CI/CD via GitHub Actions (.github/workflows/maven.yml), and Maven Central distribution. Single primary maintainer (dennis zhuang) with steady commits and documentation in Yuque (Chinese docs linked in README).

Moderate risk: single active maintainer (killme2008) with no visible co-maintainers increases bus factor. Dependencies are minimal (JUnit, Mockito, optional Spring for tests) reducing supply-chain risk. No recent breaking changes visible in 5.4.x releases, but adoption is primarily in Asia/China ecosystem (Chinese docs dominate) limiting English-speaking community support.

v5.4.3 added one-command sandbox enablement and bug fixes. v5.4.2 introduced getFunctionNames method and evaluation timeout settings. v5.4.1 fixed recursive function and serialization bugs. Active bug-fixing and feature-request triage with focus on sandbox safety and timeout control for untrusted script execution.

git clone https://github.com/killme2008/aviatorscript.git
cd aviatorscript
mvn clean install
mvn exec:java -Dexec.mainClass="com.googlecode.aviator.Main" -Dexec.args="examples/hello.av"

Or download pre-built JAR from downloads/aviator-5.4.3.jar and: java -cp aviator-5.4.3.jar com.googlecode.aviator.Main examples/hello.av

Daily commands:

mvn clean package
./bin/aviator examples/hello.av

Or embed in Java:

Aviator aviator = Aviator.getInstance();
Object result = aviator.execute("1 + 1");

• src/main/java/com/googlecode/aviator/AviatorEvaluator.java — Main public API entry point for script evaluation; every integration with Aviator starts here.
• src/main/java/com/googlecode/aviator/Expression.java — Core abstraction for compiled/interpreted expressions; all execution flows converge on this interface.
• src/main/java/com/googlecode/aviator/BaseExpression.java — Base class implementing expression lifecycle and evaluation logic shared across all expression types.
• src/main/java/com/googlecode/aviator/EvalMode.java — Enum defining compilation vs interpretation strategies; fundamental to understanding execution paths.
• src/main/java/com/googlecode/aviator/InterpretExpression.java — Interpreter implementation for dynamic evaluation; critical for understanding runtime behavior without bytecode generation.
• pom.xml — Maven build configuration; controls all dependencies, version, and artifact distribution.

Add a custom built-in function

1. Implement a class extending AviatorFunction in the appropriate package under src/main/java/com/googlecode/aviator/runtime/function/ (src/main/java/com/googlecode/aviator/FunctionLoader.java)
2. Register the function by updating ClassPathConfigFunctionLoader or implementing a custom FunctionLoader (src/main/java/com/googlecode/aviator/ClassPathConfigFunctionLoader.java)
3. Add test cases in src/test/java demonstrating the new function behavior (examples/function.av)

Enable or disable a language feature

1. Review Feature enum to see available feature flags (src/main/java/com/googlecode/aviator/Feature.java)
2. Call AviatorEvaluatorInstance.setFeature(feature, enabled) before compilation (src/main/java/com/googlecode/aviator/AviatorEvaluatorInstance.java)
3. Verify feature gating in parser/compiler is enforced during script parsing (src/main/java/com/googlecode/aviator/BaseExpression.java)

Switch between compilation and interpretation modes

1. Set eval mode via AviatorEvaluatorInstance.setMode(EvalMode.INTERPRETER or COMPILE) (src/main/java/com/googlecode/aviator/EvalMode.java)
2. Compilation mode generates bytecode; interpretation mode uses InterpretExpression for AST traversal (src/main/java/com/googlecode/aviator/InterpretExpression.java)
3. No code changes needed; mode is respected at compile() time in AviatorEvaluator (src/main/java/com/googlecode/aviator/AviatorEvaluator.java)

Implement custom expression handling for operator overloading

1. Define operator overload behavior in Feature flags and enable via setFeature() (src/main/java/com/googlecode/aviator/Feature.java)
2. Create custom Expression subclass extending BaseExpression to handle custom operator logic (src/main/java/com/googlecode/aviator/BaseExpression.java)
3. Register operator handlers via AviatorEvaluatorInstance for bigint/decimal type support (src/main/java/com/googlecode/aviator/AviatorEvaluatorInstance.java)

• Java/JVM — Host platform ensures portability across OS, integrates seamlessly with existing Java ecosystems, and Android support via DEX compilation.
• Maven — Standard build and dependency management for JVM projects; enables reproducible builds and artifact distribution to Maven Central.
• Dual compilation/interpretation modes — Compilation mode (bytecode generation) trades startup time for execution speed; interpretation mode trades speed for rapid iteration and debugging.
• AST-based interpretation — Allows dynamic code execution without JIT/bytecode generation, critical for REPL-like usage and embedded scripting scenarios.

• Bytecode compilation vs AST interpretation modes

  • Why: Different use cases require different tradeoffs: compiled scripts are fast but have startup overhead; interpreted scripts are slow but interactive.
  • Consequence: Users must choose mode upfront; switching modes requires recompilation. Hybrid approaches (JIT on hot paths) not implemented.

• Feature flags for language capabilities

  • Why: Allows stricter security/sandboxing by disabling features (e.g., reflection, dynamic calls) in untrusted environments.
  • Consequence: Scripts compiled with different feature sets may have different behavior; no runtime feature negotiation mechanism.

• Single-threaded expression evaluation

  • Why: Simplifies implementation and avoids synchronization overhead; expressions are immutable after compilation.
  • Consequence: Multi-threaded environments must manage thread-safety at the caller level; no built-in concurrent execution guarantees.

• Pluggable function loaders

  • Why: Decouples built-in functions from core engine; allows third-party libraries to register custom functions.
  • Consequence: Function namespace is global per evaluator instance; name conflicts require manual resolution by user application.

• Real-time/low-latency execution (startup overhead and GC pauses inherent to JVM)
• Strict memory sandboxing (Java heap is shared; no per-script memory limits)
• Full Java interoperability without reflection (security implications; reflection is feature-gated)
• JavaScript/Python compatibility (independent language with own syntax and semantics)
• Ahead-of-time compilation to native binaries (always JVM-hosted)

Bytecode vs. Interpreter mode: ASM mode (default) compiles to bytecode for speed but requires Java compiler access; interpreter mode is slower but works on Android—controlled via setCompileMode(). Operator precedence: Follows Java rules exactly but BigDecimal/BigInt overload resolution can surprise users unfamiliar with coercion rules. Closure variable capture: Captured variables are closed over at definition time (lexical scoping); reassignment in parent scope won't affect closures. Script serialization: Compiled scripts can be serialized for caching, but custom Java function references may fail deserialization if JAR versions differ. No type declarations: All variables are dynamic; performance relies on JIT optimization, not static types.

• Recursive descent parser — AviatorScript's parser (src/main/java/com/googlecode/aviator/parser/) uses recursive descent to parse Aviator syntax into AST; understanding this is key to extending language syntax.
• Abstract Syntax Tree (AST) and visitor pattern — Aviator transforms parsed scripts into AST nodes then traverses them via visitors for both interpretation and bytecode generation; modifying evaluation logic requires AST visitor knowledge.
• Java bytecode generation via ASM library — AviatorScript's performance comes from compiling AST directly to JVM bytecode using ASM; understanding bytecode generation is critical for optimizing codegen or adding new instructions.
• Lexical scoping and closure variable capture — Aviator supports first-class functions and closures with lexical scoping; variables are captured at definition time, not call time—this closure semantics differs from dynamic scoping and affects variable lookup during execution.
• Operator overloading — AviatorScript's BigDecimal and BigInt types overload arithmetic operators (+, -, *, /) to work transparently without explicit method calls; this requires compile-time resolution of operator method dispatch.
• Sequence abstraction and lazy evaluation — Aviator's Sequence API enables functional collection processing (map, filter, fold) with lazy evaluation; understanding this is key for efficient data transformation scripts avoiding intermediate collections.
• Sandbox / capability-based security — AviatorScript supports configurable execution sandboxes (v5.4.3 added one-command enablement) to restrict script access to Java methods, fields, and classes—critical for untrusted script execution in multi-tenant systems.

• groovy/groovy-core — Full-featured JVM scripting language alternative; Groovy has larger ecosystem but heavier footprint than AviatorScript's lightweight ASM compilation.
• jashkenas/coffeescript — Not JVM-hosted but pioneered functional closures + operator overloading syntax patterns that influenced AviatorScript's design philosophy.
• oracle/nashorn — Legacy JVM JavaScript engine (deprecated in Java 11+); similar use case (dynamic expressions on JVM) but AviatorScript is lighter and Java-native syntax-wise.
• alibaba/drools — Rule engine also used for formula/conditional evaluation in enterprise Java; AviatorScript is simpler, DSL-agnostic alternative for expression-only evaluation.
• spring-projects/spring-expression — SpEL is lightweight expression language for Spring apps; AviatorScript differs by supporting full scripting (functions, loops) vs. SpEL's expression-only scope.

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 examples/ scripts

The repo contains 40+ example scripts (examples/*.av) demonstrating language features, but there's no test suite validating that these examples execute correctly. This prevents regressions when the language evolves and helps new contributors understand expected behavior. A test harness would automatically run each example and verify output.

• [ ] Create src/test/java/com/googlecode/aviator/ExamplesIntegrationTest.java
• [ ] Implement test method that discovers all .av files in examples/ directory
• [ ] For each example, execute it via AviatorScript engine and verify it runs without exceptions
• [ ] Add expected output files (examples/*.expected) for examples with deterministic output (e.g., arithmetic.av, hello.av)
• [ ] Assert actual output matches expected output for validation
• [ ] Run as part of Maven test phase

Add GitHub Actions workflow for JDK matrix testing

Current .github/workflows/maven.yml likely tests against a single JDK version. AviatorScript targets JVM (including Android), so testing against multiple JDK versions (11, 17, 21, etc.) would catch compatibility issues early. The existing maven.yml provides a foundation to expand.

• [ ] Update .github/workflows/maven.yml to include matrix strategy with java-version: [11, 17, 21]
• [ ] Verify pom.xml target/source compiler versions are compatible with test matrix
• [ ] Test that mvn clean test passes on all JDK versions
• [ ] Add badges to README.md showing build status per JDK version if desired

Create unit tests for operator precedence and expression parsing edge cases

The README mentions 'complete support for all Java operators and precedence', but there's no dedicated test class validating complex expression parsing. This is critical for a scripting language to ensure correctness. Examples like '2 + 3 * 4 == 14' or '1 << 2 | 3' need explicit test coverage.

• [ ] Create src/test/java/com/googlecode/aviator/OperatorPrecedenceTest.java
• [ ] Add test cases for arithmetic precedence: multiplication/division before addition/subtraction
• [ ] Add test cases for bitwise operators: shifts, AND, OR, XOR with mixed operations
• [ ] Add test cases for comparison chaining and logical operators (&&, ||, !)
• [ ] Add test cases for ternary operator with nested expressions
• [ ] Add test cases for assignment operators and compound assignments (+=, -=, etc.)
• [ ] Verify results match expected Java behavior for equivalent expressions

• Add integration test for timeout enforcement (TimeoutExample.java exists but no regression tests in suite verify timeout actually interrupts long-running loops)—add test cases in src/test/java/com/googlecode/aviator/ exercising timeout with infinite loops.
• Document AST node types and visitor pattern in javadoc (parser generates AST but src/main/java/com/googlecode/aviator/ast/ classes lack description of visitor contract)—add comprehensive class-level docs explaining node hierarchy.
• Add example script demonstrating Spring integration (README mentions Spring support in provided scope, but examples/ lacks Spring bean access demo)—create examples/spring_bean_access.av showing how to call Spring-managed beans from scripts.

The AviatorScript project has several security concerns, primarily related to outdated and unmaintained dependencies. The most critical issue is the use of mockito-all 1.10.19, which is severely outdated and contains known vulnerabilities. The project also lacks comprehensive English-language security documentation for users of this scripting language, which could lead to unsafe script execution patterns. Dependencies should be updated immediately, and security guidelines should be clearly documented in English to ensure users understand the sandbox limitations and safe usage patterns of the scripting engine. The codebase appears to follow good practices otherwise, with no obvious hardcoded secrets or misconfigurations visible in the provided file structure.

• High · Outdated Mockito Dependency with Known Vulnerabilities — pom.xml - mockito-all dependency. The project uses mockito-all version 1.10.19, which is severely outdated (released in 2015). This version contains multiple known security vulnerabilities including deserialization issues and has been deprecated for years. The mockito-all artifact itself is no longer maintained. Fix: Upgrade to the latest stable version of mockito-core (currently 5.x). Replace 'mockito-all' with 'mockito-core' and use separate 'mockito-junit-jupiter' for test support. Consider running 'mvn dependency:tree' to identify any transitive vulnerable dependencies.
• Medium · Outdated JUnit Dependency — pom.xml - junit dependency. The project uses JUnit 4.13.1, released in 2020. While not critically vulnerable, this version is outdated. JUnit 5 (Jupiter) is the current standard and receives regular security updates. Fix: Upgrade to JUnit 5.x for better security, performance, and feature support. Update test code to use Jupiter annotations if needed.
• Medium · Incomplete Maven Configuration Visible in POM — pom.xml - jmh-core dependency section. The pom.xml file appears truncated in the provided content (jmh-core dependency section is incomplete). This could indicate incomplete dependency declaration or build configuration issues. Fix: Complete and review the full pom.xml file. Ensure all dependencies are fully declared with explicit versions and verify no malformed XML.
• Medium · Script Injection Risks in Scripting Language — Core scripting engine - entire codebase. As a JVM scripting language, AviatorScript executes user-provided scripts. Without proper sandboxing, this could allow arbitrary code execution if untrusted scripts are executed. The SECURITY.md references a Chinese documentation page but doesn't clearly document sandbox limitations in English. Fix: Ensure comprehensive English security documentation is provided. Implement and document script execution restrictions, disable dangerous functions by default, and validate all input scripts. Provide clear guidelines on safe script execution contexts.
• Low · Security Documentation in Non-English Language Only — SECURITY.md and referenced Yuque documentation. The SECURITY.md file references detailed security guidelines that are only available in Chinese, creating a documentation barrier for non-Chinese speakers who may miss critical security considerations. Fix: Provide comprehensive security documentation in English directly in the repository. Cover sandboxing capabilities, dangerous operations, input validation requirements, and safe usage patterns.
• Low · Missing SBOM and Dependency Tracking — Repository root. No Software Bill of Materials (SBOM) or comprehensive dependency documentation is visible, making it difficult to track all transitive dependencies and their security status. Fix: Generate and maintain an SBOM using tools like cyclonedx-maven-plugin or syft. Regularly scan dependencies using OWASP Dependency-Check or similar tools in CI/CD pipeline.

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.