WAIT — Mixed signals — read the receipts

• Last commit 5d ago
• 17 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 69% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ Scorecard: default branch unprotected (0/10)

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against OpenSSF Scorecard}

Javassist is a Java bytecode engineering library that enables runtime class definition and modification without requiring deep bytecode knowledge. It provides two API levels: source-level (write Java code that gets compiled to bytecode on-the-fly) and bytecode-level (direct bytecode manipulation). Core capability: modify or generate Java classes at runtime, either when the JVM loads them or dynamically via ClassPool and CtClass APIs. Classic flat-structure project: src/main contains core library source code, examples/sample/ holds runnable demonstrations (hotswap, evolve, reflect, rmi, vector examples showing different Javassist use cases), build via Maven (pom.xml at root) and legacy Ant (build.xml). No monorepo structure—single cohesive jar artifact.

Framework developers and middleware engineers building Java systems that need runtime instrumentation, class generation, or hot-swapping (e.g., ORM frameworks like Hibernate, proxy generators, APM tools, dependency injection containers). Users avoid hand-writing raw bytecode by expressing changes in Java source syntax.

Highly mature production-ready library: 25+ year heritage (since 1999), currently at version 3.32.0-GA, active Maven CI/CD pipeline (see .github/workflows/maven.yml), regular releases tracked in Changes.md. Actively maintained by JBoss/Red Hat with continuing updates.

Low risk for a foundational library: no external Maven dependencies listed in pom.xml snippet (bundle packaging suggests self-contained), clear triple-license strategy (MPL 1.1 / LGPL 2.1 / Apache 2.0) reduces adoption friction. Risks: single original author (Shigeru Chiba) though now JBoss-backed; bytecode APIs are inherently brittle across Java versions—changes to bytecode format can require updates.

Active maintenance: Maven CI pipeline running on commits, versioning at 3.32.0-GA, Changes.md maintained with release notes. Examples directory suggests ongoing developer education focus (hotswap and evolve samples demonstrate advanced features like class reloading). Last visible commit activity reflected in Maven workflow configuration.

git clone https://github.com/jboss-javassist/javassist.git && cd javassist && mvn clean install. To verify: java -jar javassist.jar (prints version). To explore: mvn compile and examine examples/ directory, or run sample programs in examples/sample/.

Daily commands: This is a library, not an executable project. Build: mvn clean install. Run examples: cd examples/sample/hotswap && javac *.java && java Test (see Examples.md for per-example instructions). Create new Javassist programs: add javassist-3.32.0-GA.jar to classpath and invoke ClassPool.getDefault() to start.

• src/main/javassist/ClassPool.java — Central registry for CtClass objects; all bytecode manipulation flows through ClassPool's methods for class loading and caching.
• src/main/javassist/CtClass.java — Abstract representation of a class; primary API surface for reading/modifying class structure, fields, methods, and constructors.
• src/main/javassist/CtBehavior.java — Base class for CtMethod and CtConstructor; handles bytecode insertion and method body transformation.
• src/main/javassist/CodeConverter.java — Bytecode-level transformation engine that rewrites bytecode instructions for field/method redirection and constant replacement.
• src/main/javassist/CtClassType.java — Concrete implementation of CtClass that manages actual class data, field/method lists, and bytecode generation.
• src/main/javassist/ClassPath.java — Abstract interface for class resource discovery; implementations (ByteArrayClassPath, ClassClassPath) resolve class bytecode from various sources.
• pom.xml — Maven build configuration defining project metadata, version 3.32.0-GA, MPL 1.1 license, and OSGi bundle packaging.

• ClassPool (HashMap caching, ClassPath SPI) — Manages CtClass cache, delegates class loading to ClassPath stack, and provides factory methods.
  • Failure mode: ClassNotFoundException if no ClassPath finds requested class; stale cache if concurrent modifications.
• CtClass / CtClassType (ClassFile format parsing, Java bytecode instruction set) — Represents a single class; stores metadata (name, superclass, fields, methods) and generates bytecode on-demand.
  • Failure mode: CannotCompileException if inserted source fails to compile; corrupted bytecode if internal state inconsistent.
• CtBehavior / CtMethod / CtConstructor (Javassist compiler, MethodInfo bytecode analysis) — Represents method/constructor; handles source insertion, bytecode patching, and signature modification.
  • Failure mode: Compilation error if source syntax invalid; VerifyError if inserted bytecode violates stack/type constraints.
• CodeConverter (Javassist bytecode instructions, MethodInfo patching) — Applies bytecode instruction transformations (field/method redirection, constant replacement) to compiled methods.
  • Failure mode: Silent bytecode corruption if transformation logic incorrectly rewritten opcodes.
• ClassPath Stack (I/O abstraction, URLClassLoader delegation) — Discovers and opens bytecode streams from multiple sources (JVM system classes, files, memory, network).
  • Failure mode: IOException if bytecode source unavailable; malformed bytecode if source corrupted.

• Application Code → ClassPool — Request CtClass for target classname via get().
• ClassPool → ClassPath Stack — Query registered ClassPath implementations to locate and open bytecode InputStream.
• ClassPath Stack → CtClassType Parser — Bytecode stream parsed into internal field/method/attribute data structures.
• CtBehavior / CtField → Bytecode Generator — User mutations (insertBefore, insertAfter, addField) accumulated and applied to regenerate class bytes.
• CodeConverter → CtClassType — Bytecode instruction patches (field/method redirection) applied to compiled method bytecode.
• CtClassType → Application Code — Modified class bytes returned via toBytecode() for writing to disk or loading into JVM.

Add a New Source-Level API Method to Transform Classes

1. Add public method to CtClass.java (e.g., void addAnnotation(...)) that modifies class metadata without bytecode knowledge. (src/main/javassist/CtClass.java)
2. Implement internal logic in CtClassType.java to apply the transformation to the underlying classfile structure. (src/main/javassist/CtClassType.java)
3. Write example demonstrating the new API in examples/sample/ (e.g., examples/sample/Test.java). (examples/sample/Test.java)

Add a Custom ClassPath Source

1. Create new class extending ClassPath interface in src/main/javassist/ (e.g., DatabaseClassPath.java). (src/main/javassist/ClassPath.java)
2. Implement find(String classname) and openClassfile(String classname) to load bytecode from custom source. (src/main/javassist/ClassPath.java)
3. Register the ClassPath via ClassPool.insertClassPath() or appendClassPath() in application bootstrap code. (src/main/javassist/ClassPool.java)

Add a Bytecode Instruction Transformation Rule

1. Create transformation method in CodeConverter.java (e.g., replaceFieldAccess(...)) that identifies and rewrites specific bytecode patterns. (src/main/javassist/CodeConverter.java)
2. Use CtBehavior.instrument() or MethodInfo utilities to apply the bytecode patch to target methods. (src/main/javassist/CtBehavior.java)
3. Test transformation in examples/sample/ with before/after bytecode verification. (examples/sample/Test.java)

• Maven + OSGi Bundle — Enables dependency management and modular packaging for enterprise deployment and framework integration.
• Dual API (Source & Bytecode levels) — Source-level API abstracts complexity for common use cases; bytecode-level API allows power users to optimize or implement advanced patterns.
• ClassPath abstraction — Decouples bytecode source resolution, enabling runtime class loading from JVM, filesystem, network, or memory without recompilation.
• CtClass caching in ClassPool — Avoids redundant bytecode parsing and enables consistent mutations across a single compilation session.

• Source-level API compiles insertions on-the-fly

  • Why: Improves developer experience by accepting Java source text for injected code.
  • Consequence: Adds compilation overhead at runtime; slower than pre-compiled bytecode patches.

• Bytecode-level API requires deep JVM specification knowledge

  • Why: Provides maximum flexibility and performance for advanced users.
  • Consequence: Steep learning curve and error-prone for typical use cases; mistakes can corrupt class files.

• Single ClassPool per thread recommended (not fully thread-safe)

  • Why: Simplifies caching and reduces synchronization overhead.
  • Consequence: Concurrent modifications to same CtClass require external synchronization.

• Does not provide runtime JVM bytecode patching (HotSwap) without agent support.
• Does not automatically validate generated bytecode against JVM specifications; responsibility on user.
• Not a class file decompiler; only reads and writes bytecode, does not reverse-engineer source.
• Does not handle native method code or JNI bindings.

• Avg cyclomatic complexity: ~7 — Bytecode manipulation requires deep JVM specification knowledge; class file format parsing and instruction-level transformations are inherently complex. CtClass and CodeConverter are particularly intricate.
• Largest file: src/main/javassist/CtClassType.java (2,800 lines)
• Estimated quality issues: ~4 — Thread-safety violations in cached CtClass access; lack of bytecode validation before class loading; no streaming/incremental bytecode output; compiler overhead not cached.

• Manual ClassPath chaining without fail-fast (Medium) — src/main/javassist/ClassPool.java (insertClassPath/appendClassPath): Multiple ClassPath implementations queried sequentially; failure to find class in first N sources causes silent fallthrough, delaying error detection.
• Mutable CtClass shared without synchronization (High) — src/main/javassist/ClassPool.java (caching) + CtClassType.java: Cached CtClass instances returned directly; concurrent modifications by multiple threads can corrupt bytecode without explicit locking.
• Source-level insertion compiles on every invocation (Medium) — src/main/javassist/CtBehavior.java (insertBefore/insertAfter): Each call to insertBefore() retriggers Javassist's internal compiler; no compilation caching or batching.
• No validation of bytecode before class loading (High) — src/main/javassist/CtClassType.java (toBytecode): Generated bytecode is not verified against JVM specifications; VerifyError may occur only at runtime during class loading.

• src/main/javassist/CtBehavior.java insertBefore/insertAfter (Compilation overhead) — Source text compiled to bytecode on every call; compilation is CPU-bound and occurs serially.
• src/main/javassist/ClassPool.java get() (I/O latency) — Linear scan of ClassPath stack on cache miss; multiple file I/O calls may block if ClassPath sources are I/O-bound.
• src/main/javassist/CtClassType.java toBytecode() (Memory & CPU (large classes)) — Full bytecode regeneration required even if only one method modified; no incremental bytecode patching.

Java version compatibility: bytecode format varies across Java versions (e.g., lambda instructions in Java 8+, records in Java 16+)—Javassist must be kept in sync. ClassPool is global/singleton by default—multiple threads modifying the same class can cause race conditions; use ClassClassPath carefully. Generated bytecode can fail if CtClass modifications violate JVM verification rules (e.g., incorrect stack depth); errors only surface at class load time, not edit time. build.xml (legacy Ant) and pom.xml (Maven) coexist; use Maven. No test directory visible in file listing—testing appears minimal or in separate module.

• Bytecode Instrumentation / AST Manipulation — Javassist's core strength is editing Abstract Syntax Trees (Java source) and bytecode at runtime; understanding how classes are represented in memory as mutable objects (CtClass, CtMethod) is essential
• Java Class File Format & Constant Pool — Javassist's bytecode-level API directly manipulates the JVM Class File Format spec (JVMS); understanding constant pool entries, method descriptors, and instruction opcodes is required for low-level edits
• Hot Swapping / Dynamic Class Reloading — Javassist enables modifying classes after JVM startup via custom ClassLoaders; examples/sample/hotswap/ demonstrates this; critical for frameworks needing runtime class evolution without restart
• Visitor Pattern (Bytecode Visitors) — Javassist's compiler and bytecode traversal use visitor pattern to walk instruction sequences and apply transformations; understanding this pattern is key to writing transformers
• ClassLoader Hierarchies & Custom ClassLoaders — Javassist works through custom ClassLoaders (ClassClassPath, URLClassPath) to intercept class loading; misconfiguring loader hierarchy is a common trap
• Java Instrumentation API (java.lang.instrument) — Javassist integrates with JVM Instrumentation for agent-based class transformation at load time; understanding agents and MANIFEST.MF premain/agentmain is required for advanced use cases
• Type Erasure & Generic Signature Attributes — Java generics are erased at bytecode level but stored in Signature attributes; Javassist must preserve these during editing to maintain type safety contracts

• bytebuddy/byte-buddy — Direct competitor: modern bytecode manipulation library with fluent API and Instrumentation agent support; same problem domain but different design philosophy
• cglib/cglib — Complementary library: uses Javassist or ASM for dynamic proxy and CGLIB class generation; often sits atop Javassist in frameworks
• spring-projects/spring-framework — Major consumer: Spring uses Javassist (and ByteBuddy) for aspect proxies, component scanning bytecode generation, and runtime class modification
• hibernate/hibernate-orm — Key user: Hibernate leverages Javassist for lazy-loading proxy generation, bytecode enhancement, and entity instrumentation
• jboss-javassist/javassist-maven-plugin — Official companion: Maven plugin that applies Javassist transformations during build phase

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 unit tests for javassist.tools.reflect package

The examples/src/main/javassist/tools/reflect/ directory contains reflection utilities (ClassMetaobject.java, Loader.java, Metalevel.java, etc.) but there are no corresponding unit tests visible in the repo structure. This is a critical API for bytecode manipulation and deserves dedicated test coverage to prevent regressions.

• [ ] Create src/test/java/javassist/tools/reflect/ directory structure
• [ ] Write unit tests for ClassMetaobject.java covering metadata creation and manipulation
• [ ] Write unit tests for Loader.java covering custom class loading behavior
• [ ] Write integration tests for Reflection.java end-to-end reflection scenarios
• [ ] Ensure tests cover edge cases like circular dependencies and class reloading
• [ ] Add tests to maven.yml CI workflow to run on every push

Add integration tests for examples in CI/CD pipeline

The examples/ directory contains 7+ sample applications (duplicate, evolve, hotswap, preproc, reflect, rmi, vector) but none appear to be automatically tested in .github/workflows/maven.yml. These examples serve as regression tests and documentation—they should compile and ideally run as part of CI.

• [ ] Update .github/workflows/maven.yml to add a 'Test Examples' step
• [ ] Configure Maven to compile all examples in examples/src/main/javassist/tools/
• [ ] Add a verification step that runs sample tests like examples/sample/reflect/Main.java
• [ ] Document in Examples.md which examples can be run in headless CI (exclude GUI examples like rmi/webdemo.html)
• [ ] Ensure failures in example compilation block PR merges

Create platform-specific CI workflow for Java version matrix testing

The current maven.yml workflow is minimal and doesn't test against multiple Java versions (8, 11, 17, 21+). Javassist is a bytecode toolkit used across Java ecosystems with varying compatibility requirements—the repo should validate it works across supported JDK versions to catch compatibility regressions early.

• [ ] Extend .github/workflows/maven.yml to include matrix testing with java-version: ['8', '11', '17', '21']
• [ ] Add separate job for testing with different Maven versions if needed
• [ ] Document in README.md the officially supported Java versions
• [ ] Add a compatibility matrix to Changes.md for release notes
• [ ] Test that bytecode generation works correctly across Java version targets (javac -target flag)

• Add comprehensive unit tests for src/main/javassist/bytecode/Instruction.java covering all bytecode instruction types and opcodes—currently no test files visible in repo structure
• Document the source-level compiler API (javassist.compiler package) with a tutorial example showing how Java expressions are parsed and compiled to bytecode, similar to existing examples/sample/ demos
• Create a new example in examples/sample/ demonstrating Java 16+ Records and Java 17+ sealed classes bytecode manipulation, as current examples focus on older Java features

Javassist demonstrates a reasonable security posture for an established bytecode manipulation library. The primary concerns are around dependency management practices and CI/CD security hardening rather than code-level vulnerabilities. The project uses Maven and has GitHub Actions configured, but lacks explicit security scanning integration. There are no obvious hardcoded credentials or critical misconfigurations in the visible configuration files. Recommendations focus on enhancing the build pipeline with automated security testing, improving dependency version management, and establishing clear security policies for vulnerability reporting.

• Medium · Outdated Maven Dependencies — pom.xml. The pom.xml file does not specify explicit versions for most dependencies, relying on transitive dependency resolution. This can lead to inconsistent builds and potential inclusion of vulnerable transitive dependencies. The project should use dependency management sections to lock versions. Fix: Add explicit version pinning for all direct dependencies and use <dependencyManagement> sections to control transitive dependencies. Run regular dependency scans with tools like OWASP DependencyCheck or Snyk.
• Medium · Missing Security Configuration in Build Pipeline — .github/workflows/maven.yml. The Maven CI workflow (.github/workflows/maven.yml) file is referenced but not fully provided. There is no evidence of security scanning (SAST, dependency checks, or code quality gates) in the build process. Fix: Implement automated security scanning in CI/CD pipeline including: SAST tools (SpotBugs, FindSecBugs), dependency vulnerability scanning (DependencyCheck, Snyk), and code coverage analysis. Add branch protection rules requiring passing security checks.
• Low · Multiple License Definitions — pom.xml - licenses section. The pom.xml defines three different licenses (MPL 1.1, LGPL 2.1, and Apache 2.0) which could create ambiguity about the actual licensing terms and potential compliance issues for downstream users. Fix: Clarify the primary license and document the conditions under which each alternative license applies. Update LICENSE.html file to reflect this clearly. Consider using a SPDX expression for clarity.
• Low · No Security Policy Documented — Repository root. The repository does not appear to have a SECURITY.md or security policy file visible in the provided structure, making it unclear how security issues should be reported. Fix: Create a SECURITY.md file documenting: how to responsibly disclose security vulnerabilities, expected response times, and which versions are currently supported. Consider using GitHub's security advisory feature.
• Low · Incomplete POM Configuration — pom.xml - end of file. The pom.xml file provided appears to be truncated (ends mid-developer section), which may indicate incomplete or missing configuration details. Fix: Ensure the complete pom.xml is valid and properly formatted. Validate the entire file structure.

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

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

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/jboss-javassist/javassist 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.

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

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

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

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

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

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

# 4. Critical files exist
test -f "src/main/javassist/ClassPool.java" \\
  && ok "src/main/javassist/ClassPool.java" \\
  || miss "missing critical file: src/main/javassist/ClassPool.java"
test -f "src/main/javassist/CtClass.java" \\
  && ok "src/main/javassist/CtClass.java" \\
  || miss "missing critical file: src/main/javassist/CtClass.java"
test -f "src/main/javassist/CtBehavior.java" \\
  && ok "src/main/javassist/CtBehavior.java" \\
  || miss "missing critical file: src/main/javassist/CtBehavior.java"
test -f "src/main/javassist/CodeConverter.java" \\
  && ok "src/main/javassist/CodeConverter.java" \\
  || miss "missing critical file: src/main/javassist/CodeConverter.java"
test -f "src/main/javassist/CtClassType.java" \\
  && ok "src/main/javassist/CtClassType.java" \\
  || miss "missing critical file: src/main/javassist/CtClassType.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 35 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~5d)"
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/jboss-javassist/javassist"
  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).

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