arcadedb: Instructions file for Claude Code

CLAUDE.md

Response Formatting

• Never use the em dash character (—) in responses. Use a normal dash (-), a comma, or rephrase instead.

Project Instructions

Before writing any code:

• State how you will verify this change works (e.g., unit tests, integration tests, manual testing)
• Write the tests first (TDD approach) whenever possible
• Ensure code adheres to existing coding standards and styles
• Then implement the code
• Run verification and iterate until it passes
• Run all the connected tests could be affected by the change to ensure nothing is broken (no need to run the whole suite, it would take too long)

General design principles:

• reuse existing components whenever is possible
• don't use fully qualified names if possible, always import the class and just use the name
• don't include a new dependency unless is strictly necessary, and they MUST be Apache 2.0 compatible:
  • ✅ ALLOWED: Apache 2.0, MIT, BSD (2/3-Clause), ISC, EPL 1.0/2.0, UPL 1.0, EDL 1.0, LGPL 2.1+ (for libraries only), MPL-2.0 (for libraries only, unmodified), CDDL 1.0/1.1 (for libraries only, unmodified), GPL-2.0 WITH the Classpath Exception specifically (never a bare GPL), CC0/Public Domain, Zlib, BlueOak-1.0.0, OFL-1.1 (fonts only, unmodified), CC-BY-4.0 (icons and other non-code assets only, unmodified, with the attribution it requires in ATTRIBUTIONS.md)
  • ❌ FORBIDDEN: GPL, AGPL, proprietary licenses without explicit permission, SSPL, Commons Clause, BUSL-1.1, Elastic-2.0
  • This is an allow-list: a license in neither row above is not permitted by default. Get explicit maintainer sign-off and add it to the ALLOWED row before depending on it. "For libraries only" / "unmodified" means: depending on the unmodified jar as-is is fine, but do not vendor or patch its source under this project without revisiting the license implications. CI enforces this allow-list on the Maven graph (.github/scripts/check-license-allowlist.py, run from license-compliance.yml) and on the npm packages Studio ships (studio/test/dependency-licenses.test.js, run by npm test in the Maven build and by studio-security-audit.yml). Zlib, BlueOak-1.0.0, OFL-1.1 and CC-BY-4.0 are so far only in the npm check: the Maven script matches exact clause spellings and fails closed, so the first Maven dependency under one of them adds its spelling to ALLOWED_CLAUSES
  • When adding a dependency, you MUST update ATTRIBUTIONS.md and, if Apache-licensed with a NOTICE file, incorporate required notices into the main NOTICE file
• for Studio (webapp), limit to jquery and bootstrap 5. If necessary use 3rd party libs, but they must be Apache 2.0 compatible (see allowed licenses above)
• always bear in mind PERFORMANCE. It must be always your mantra: performance and lightweight on garbage collector. If you can, prefer using arrays of primitives to List of Objects
• if you need to use JSON, use the class com.arcadedb.serializer.json.JSONObject. Leverage the getter methods that accept the default value as 2nd argument, so you don't need to check if they present or not null = less boilerplate code
• same thing for JSON arrays: use com.arcadedb.serializer.json.JSONArray class
• code styles:
• adhere to the existing code
• if statements with only one child sub-statement don't require a curly brace open/close, keep it simple
• use the final keyword when possible on variables and parameters
• all new server-side code must be tested with a test case. Check existing test case to see the framework and style to use
• write a regression test
• after every change in the backend (Java), compile the project and fix all the issues until the compilation passes
• test all the new and old components you've modified before considering the job finished. Please do not provide something untested
• always keep in mind speed and security with ArcadeDB, do not introduce security hazard or code that could slow down other parts unless requested/approved
• do not commit on git, I will do it after a review
• remove any System.out you used for debug when you have finished
• For test cases, prefer this syntax: assertThat(property.isMandatory()).isTrue();
• Annotate performance/benchmark tests so they're skipped from regular CI builds:
  • Use @Tag("benchmark") for pure microbenchmarks (e.g., JMH-style or comparison runs)
  • Use @Tag("slow") for functional regression tests that take noticeably long (large batches, multi-second elapsed time, big payloads)
  • Use @Tag("vector") for an LSM vector-index test that spends most of its time waiting on a background rebuild. LSMVectorIndex.REBUILD_SEMAPHORE holds one permit for the whole JVM, so these tests convoy against each other and the waits have to be sized for the worst case; the tag routes the class to the vector-unit-tests lane where the convoy costs nobody else anything
  • Apply at the class level when every method in the class is slow; at the method level when only some methods are slow
  • The tags are a partition, not a set of overlapping labels: CI selects each lane with -Dgroups/-DexcludedGroups such that every test runs in exactly one lane. Tagging a class vector and one of its methods slow is fine, but do not expect that method in the slow lane
  • Required imports: import org.junit.jupiter.api.Tag;
  • A JUnit tag on a Cucumber @Suite does not work: Surefire's groups/excludedGroups reach the scenarios inside the suite rather than the suite class. Route a suite to a lane with -Dsurefire.includes instead, as .github/workflows/mvn-test.yml does for the openCypher TCK
• Never assert on raw wall-clock elapsed time. A full-suite run shares one JVM, and a stop-the-world pause of tens of seconds late in a 12,000-test run turns any bound with less headroom than that into a coin flip on the JVM's mood (#6260). Measure with com.arcadedb.utility.StallAwareStopwatch (engine test-jar) instead: it discounts the JVM-wide stall observed inside the measured window, so the bound can stay tight AND stop flaking. Pick the assertion that says what the number is for, because the message is what stops the next person from "fixing" a red run by loosening it:
  • assertGaveUpWithin(bound, whatItSeparates) when the bound is a tripwire between a bounded operation and an unbounded one. Generous is free here: a wider bound cannot turn a passing run red
  • assertStayedUnder(bound, claim) when the bound IS the assertion - a complexity claim with no other practical expression (a regex that must not backtrack exponentially, one deadline shared across rows rather than charged per row). Loosening it deletes the test
  • a short wait expected to TIME OUT needs neither, and neither does a lower bound (isGreaterThan): a stall only makes those more true
  • @Timeout is plain wall clock and cannot be discounted, so size it as a hang detector, not as a latency bound
• don't add Claude as author of any source code
• Test server ports - never address or bind a hand-picked port in a test. Parallel builds (other worktrees, other agents, an IDE's server) share the machine, and a collision reads as 403 / "Too many failed authentication attempts" or "Address already in use" in some other test, never as a port conflict:
  • start servers through a fixture base (BaseGraphServerTest, StaticBaseServerTest, BaseRaftHATest) rather than a bare new ArcadeDBServer(...), and leave SERVER_HTTP_INCOMING_PORT on its default range
  • derive every URL from the port the server actually bound: getServerHttpUrl(serverIndex, path) / getServerHttpPort(serverIndex), or getServerHttpPort(server) for a server you started yourself. Never "http://127.0.0.1:248" + serverIndex or localhost:2480: one stranger on 2480 shifts every server up by one, so each index talks to its neighbour
  • a listener with no range to fall back on (Raft, gRPC, Bolt, a standalone Ratis cluster, a second HTTPS port) takes its port from StaticBaseServerTest.allocateFreePorts(n), or allocateFixturePorts(n) inside a BaseRaftHATest so it cannot coincide with the cluster's Raft ports. Never a BASE_PORT + i constant, and never new ServerSocket(0) (the ephemeral range, where any outgoing connection can take it first)
  • the only legitimate 2480 + i is a getServerAddresses() override: it runs before any server exists and the base class patches it with the bound ports afterwards
  • HardcodedTestServerPortsTest (server module) scans every module's test sources for these shapes; do not allow-list a new offender, fix it