This is an automated email from the ASF dual-hosted git repository. spmallette pushed a commit to branch agent-skills in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit 7fe79e7aa820bba911fc02401b2e80cfa69ea058 Author: Stephen Mallette <[email protected]> AuthorDate: Tue Apr 7 13:58:08 2026 -0400 Added tinkerpop-dev skills based on Agent Skills standard Included a agent-setup.sh script that will help build shims as needed to common agents, for those that won't look in .skills by default. --- .gitignore | 5 + .skills/tinkerpop-dev/SKILL.md | 158 ++++++++++++++ .skills/tinkerpop-dev/references/build-dotnet.md | 97 +++++++++ .skills/tinkerpop-dev/references/build-go.md | 111 ++++++++++ .skills/tinkerpop-dev/references/build-java.md | 134 ++++++++++++ .../tinkerpop-dev/references/build-javascript.md | 171 +++++++++++++++ .skills/tinkerpop-dev/references/build-python.md | 127 +++++++++++ .../references/dev-environment-setup.md | 140 ++++++++++++ .skills/tinkerpop-dev/references/documentation.md | 129 ++++++++++++ .skills/tinkerpop-dev/references/gremlin-mcp.md | 159 ++++++++++++++ .skills/tinkerpop-dev/scripts/check-env.sh | 151 +++++++++++++ AGENTS.md | 234 +++------------------ bin/agent-setup.sh | 200 ++++++++++++++++++ .../dev/developer/development-environment.asciidoc | 59 +++--- gremlin-js/AGENTS.md | 103 --------- gremlin-js/gremlin-javascript/AGENTS.md | 138 ------------ gremlin-python/AGENTS.md | 107 ---------- pom.xml | 2 + 18 files changed, 1641 insertions(+), 584 deletions(-) diff --git a/.gitignore b/.gitignore index 822c58116f..143a92592b 100644 --- a/.gitignore +++ b/.gitignore @@ -48,6 +48,11 @@ coverage.out gremlinconsoletest.egg-info CLAUDE.md **/.claude/ +.kiro/ +.agents/ +.cursor/ +.codex/ +.github/skills/ .beads/ gremlin-python/src/main/python/build/ node_modules/ diff --git a/.skills/tinkerpop-dev/SKILL.md b/.skills/tinkerpop-dev/SKILL.md new file mode 100644 index 0000000000..ad2b40cf30 --- /dev/null +++ b/.skills/tinkerpop-dev/SKILL.md @@ -0,0 +1,158 @@ +--- +name: tinkerpop-dev +description: > + Development guidance for the Apache TinkerPop monorepo. Use when building, + testing, or contributing to TinkerPop's graph computing framework and its + multi-language Gremlin ecosystem (Java, Python, JavaScript, .NET, Go). + Covers coding conventions, build recipes, test evaluation, documentation, + development environment setup, and Gremlin MCP server usage. +license: Apache-2.0 +compatibility: Requires Java 11+, Maven 3.5.3+, Docker. Individual GLVs may need Python, Node.js, .NET SDK, or Go. +metadata: + version: 1.0.0 + project: Apache TinkerPop +--- + +# TinkerPop Development Skill + +## Project Overview + +Apache TinkerPop is a graph computing framework providing a standard API (the Gremlin graph +traversal language) for graph databases and processors. The repository is a Maven multi-module +monorepo that wraps JVM code, Python, JavaScript/TypeScript, .NET, and Go under a single build. + +Canonical project documentation (prefer local files over external URLs): + +- `README.md` and `CONTRIBUTING.md` at the repo root +- Reference docs: `docs/src/reference/` +- Developer docs: `docs/src/dev/developer/` +- Provider docs and Gremlin Semantics: `docs/src/dev/provider/` +- IO and Serialization: `docs/src/dev/io/` +- Recipes: `docs/src/recipes/` +- Upgrade docs: `docs/src/upgrade/` +- Future plans: `docs/src/dev/future/` + +## Repository Structure + +``` +tinkerpop/ +├── gremlin-core/ Core graph API and traversal engine (Java) +├── gremlin-server/ Gremlin Server (Java) +├── tinkergraph-gremlin/ In-memory reference graph (Java) +├── gremlin-python/ Python GLV +├── gremlin-js/ JavaScript/TypeScript workspace root +│ ├── gremlin-javascript/ JS driver (npm: "gremlin") +│ ├── gremlin-mcp/ Gremlin MCP server (npm: "gremlin-mcp") +│ └── gremlint/ Gremlin query formatter (npm: "gremlint") +├── gremlin-dotnet/ .NET GLV +├── gremlin-go/ Go GLV +├── gremlin-test/ Shared test resources and Gherkin features +├── gremlin-tools/ Benchmarks, coverage, socket server +├── docs/src/ AsciiDoc documentation +├── docker/ Docker build scripts and configs +├── bin/ Utility scripts +└── CHANGELOG.asciidoc Changelog +``` + +Maven is the build orchestration tool for all modules, including non-JVM ones. + +## Basic Build Commands + +Build everything: +```bash +mvn clean install +``` + +Build a specific module: +```bash +mvn clean install -pl <module-name> +``` + +For GLV-specific builds, test execution, and advanced workflows, see the appropriate +reference file under `references/`. + +## Coding Conventions + +- All files must include the Apache Software Foundation license header. Canonical text + is at `bin/asf-license-header.txt`. +- Do not use import wildcards (e.g., avoid `import org.apache.tinkerpop.gremlin.structure.*`). + Use explicit imports. +- Define variables as `final` whenever possible, except for loop variables. +- Respect existing naming patterns and package organization. +- Use `@/` path aliases for JavaScript/TypeScript imports where the project uses them. + +## Test Conventions + +- Prefer SLF4J `Logger` over `System.out.println` or `println` in tests. +- Use `TestHelper` utilities for temporary directories and file structures instead of + hard-coding paths. +- Always close `Graph` instances that are manually constructed in tests. +- Tests using a `GraphProvider` with `AbstractGremlinTest` should be suffixed `Check`, + not `Test`. +- Prefer Hamcrest matchers for boolean assertions (e.g., `assertThat(..., is(true))`) + instead of manually checking booleans. +- Gremlin language tests use Gherkin features under: + `gremlin-test/src/main/resources/org/apache/tinkerpop/gremlin/test/features/` + See `docs/src/dev/developer/for-committers.asciidoc` for details. + +## Documentation Conventions + +- TinkerPop documentation is AsciiDoc-based under `docs/src/`. Do not use Markdown in + the main docs tree. +- Place new content in the appropriate book (reference, dev, recipes, etc.). +- Update the relevant `index.asciidoc` so new content is included in the build. +- For detailed documentation generation instructions, see `references/documentation.md`. + +## Changelog, License, and Checks + +When changes affect behavior, APIs, or user-visible features: + +- Add or update entries in `CHANGELOG.asciidoc` in the correct version section. +- Do not invent new version numbers or release names; follow the existing pattern. +- Preserve and respect license headers and notices in all files. +- Avoid adding third-party code or dependencies with incompatible licenses. + +## Agent Guardrails + +### Do + +- Make small, focused changes that are easy to review. +- Run the relevant build and test commands before suggesting a change is complete. +- Update or add tests when behavior changes. +- Update documentation and/or changelog when changing public behavior or APIs. +- Follow existing patterns for code structure, documentation layout, and naming. +- Point maintainers to relevant documentation or issues when proposing non-trivial changes. + +### Don't + +- Don't perform large, sweeping refactors unless explicitly requested. +- Don't change public APIs, configuration formats, or network protocols without explicit + human approval and an associated design/issue. +- Don't switch documentation formats (e.g., AsciiDoc to Markdown) in the main docs tree. +- Don't introduce new external dependencies, modules, or build plugins without an + associated discussion and issue. +- Don't invent project policies, version numbers, or release names. +- Don't remove or weaken tests to "fix" failures; adjust the implementation or test + data instead. + +If uncertain about the impact of a change, prefer to make a minimal patch, add comments +for reviewers, and ask for clarification. + +## When In Doubt + +1. Check `CONTRIBUTING.md`, developer docs under `docs/src/dev/developer/`, and reference docs. +2. Prefer no change over an unsafe or speculative change. +3. Surface the question to human maintainers. + +## Reference Guides + +For deeper, task-specific guidance, see the reference files in this skill: + +- [Development Environment Setup](references/dev-environment-setup.md) — fresh clone to working environment +- [Java / Core Builds](references/build-java.md) — Java modules, gremlin-server, integration tests +- [Python GLV](references/build-python.md) — build, test, result evaluation +- [JavaScript GLV](references/build-javascript.md) — npm workspace, build, test, evaluation +- [.NET GLV](references/build-dotnet.md) — build, test, Docker setup +- [Go GLV](references/build-go.md) — build, test, Docker setup +- [Documentation](references/documentation.md) — AsciiDoc generation, website +- [Gremlin MCP Server](references/gremlin-mcp.md) — translation, formatting, querying via MCP diff --git a/.skills/tinkerpop-dev/references/build-dotnet.md b/.skills/tinkerpop-dev/references/build-dotnet.md new file mode 100644 index 0000000000..979a7eca6d --- /dev/null +++ b/.skills/tinkerpop-dev/references/build-dotnet.md @@ -0,0 +1,97 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# .NET GLV Build and Test + +## Requirements + +- **.NET SDK 8.0+** — optional; Docker handles test execution via Maven. +- **Docker and Docker Compose** — required for running tests through Maven. +- **Maven** — preferred build orchestration. +- **Mono** — only needed for packing the `Gremlin.Net.Template` project. + +## Module Structure + +``` +gremlin-dotnet/ +├── pom.xml Maven parent (packaging=pom) +├── Gremlin.Net.sln .NET solution file +├── src/ Source code (Gremlin.Net library + template) +│ ├── .glv Sentinel file to activate build +│ └── Gremlin.Net/ Main library +├── test/ Test projects +│ ├── .glv Sentinel file to activate tests +│ ├── Gremlin.Net.UnitTest/ +│ ├── Gremlin.Net.IntegrationTest/ +│ ├── Gremlin.Net.Benchmarks/ +│ └── Gremlin.Net.Template.IntegrationTest/ +├── Examples/ Example projects +└── docker-compose.yml Test infrastructure +``` + +## Activation + +Both `src` and `test` directories need `.glv` sentinel files: +```bash +touch gremlin-dotnet/src/.glv +touch gremlin-dotnet/test/.glv +``` + +Without these files, TinkerPop still builds with Maven but .NET projects are skipped. + +## Maven Build Commands + +Run from the repository root. + +Build and test (requires Docker): +```bash +mvn clean install -pl gremlin-dotnet,gremlin-dotnet-source,gremlin-dotnet-tests +``` + +The test execution uses Docker Compose to: +1. Start a Gremlin Server test container (`gremlin-server-test-dotnet`) +2. Run `dotnet test ./Gremlin.Net.sln -c Release` inside a .NET SDK 8.0 container +3. Run example projects to verify they work +4. Tear down containers + +## Docker Test Infrastructure + +The `docker-compose.yml` defines: +- `gremlin-server-test-dotnet` — Gremlin Server on ports 45940-45942 and 4588 +- `gremlin-dotnet-integration-tests` — .NET SDK 8.0 container that runs `dotnet test` + +The test container uses `dotnet-trx` for test result reporting. + +## Test Results + +Test results are written as `.trx` files inside the container. On failure, check the +Maven console output for the `dotnet test` exit code and error summary. + +## Template Packaging + +To pack the `Gremlin.Net.Template` NuGet package (requires Mono): +```bash +mvn clean install -Dnuget +``` + +## Evaluating Build Results + +Use the Maven exit code to determine pass/fail: +- Exit `0` — success +- Non-zero — failure; check the `dotnet test` output in the Maven console diff --git a/.skills/tinkerpop-dev/references/build-go.md b/.skills/tinkerpop-dev/references/build-go.md new file mode 100644 index 0000000000..354385622a --- /dev/null +++ b/.skills/tinkerpop-dev/references/build-go.md @@ -0,0 +1,111 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# Go GLV Build and Test + +## Requirements + +- **Go 1.22+** — optional for local development; Docker handles test execution via Maven. +- **Docker and Docker Compose** — required for running tests through Maven. +- **Maven** — preferred build orchestration. + +## Module Structure + +``` +gremlin-go/ +├── pom.xml Maven module (no Java source; Maven wraps Go) +├── go.mod Go module definition +├── go.sum Go dependency checksums +├── run.sh Convenience script for Docker-based testing +├── driver/ Go driver source and tests +│ ├── cucumber/ BDD feature test support +│ ├── resources/ Test resources +│ └── *.go / *_test.go Source and test files +├── examples/ Example programs +└── docker-compose.yml Test infrastructure +``` + +## Activation + +Create a `.glv` sentinel file to include Go in standard builds: +```bash +touch gremlin-go/.glv +``` + +Without this file, TinkerPop still builds with Maven but Go is skipped. + +## Maven Build Commands + +Run from the repository root. + +Build and test (requires Docker): +```bash +mvn clean install -Pglv-go -pl gremlin-go +``` + +The Maven build uses Docker Compose to: +1. Start a Gremlin Server test container +2. Run `go test -v -json ./... -race -covermode=atomic` inside a Go container +3. Run example programs +4. Tear down containers and prune dangling images + +## Convenience Script + +From `gremlin-go/`: +```bash +./run.sh # Uses current project version +./run.sh 4.0.0-SNAPSHOT # Specify server version +./run.sh 3.8.0 # Use a released version +``` + +The default requires a SNAPSHOT server image built with: +```bash +mvn clean install -pl :gremlin-server -DskipTests -DskipIntegrationTests=true -am +mvn install -Pdocker-images -pl :gremlin-server +``` + +## Docker Test Infrastructure + +The `docker-compose.yml` defines: +- `gremlin-server-test` — Gremlin Server on ports 45940-45942 and 4588 +- `gremlin-go-integration-tests` — Go 1.25 container that runs tests with race + detection, coverage, and `gotestfmt` for formatted output + +Environment variables in the test container: +- `CUCUMBER_FEATURE_FOLDER` — path to Gherkin feature files +- `GREMLIN_SERVER_URL` — server endpoint for integration tests +- `RUN_INTEGRATION_TESTS=true` +- `RUN_BASIC_AUTH_INTEGRATION_TESTS=true` + +## Local Development + +After installing Go locally: +```bash +cd gremlin-go +go build ./... +go test ./driver/ -run TestName +``` + +For integration tests, a running Gremlin Server is required. + +## Evaluating Build Results + +Use the Maven exit code to determine pass/fail: +- Exit `0` — success +- Non-zero — failure; check the `go test` output in the Maven console diff --git a/.skills/tinkerpop-dev/references/build-java.md b/.skills/tinkerpop-dev/references/build-java.md new file mode 100644 index 0000000000..0f06230503 --- /dev/null +++ b/.skills/tinkerpop-dev/references/build-java.md @@ -0,0 +1,134 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# Java / Core Module Builds + +## Building Specific Modules + +Build a single module: +```bash +mvn clean install -pl <module-name> +``` + +Examples: +```bash +mvn clean install -pl tinkergraph-gremlin +mvn clean install -pl gremlin-core +mvn clean install -pl gremlin-server +``` + +Build a module and its dependencies: +```bash +mvn clean install -pl gremlin-server -am +``` + +## Gremlin Server + +Build gremlin-server (commonly needed before GLV testing): +```bash +mvn clean install -pl :gremlin-server -am -DskipTests +``` + +Run gremlin-server integration tests: +```bash +mvn clean install -pl gremlin-server -DskipIntegrationTests=false +``` + +Start Gremlin Server with Docker using the standard test configuration: +```bash +docker/gremlin-server.sh +``` + +## Integration Tests + +Enable integration tests across the project: +```bash +mvn clean install -DskipIntegrationTests=false +``` + +Use the `-DuseEpoll` option to try Netty native transport (Linux only; falls back to +Java NIO on other OS). + +## Test Options + +Disable iterator leak assertions: +```bash +mvn clean install -DtestIteratorLeaks=false +``` + +Specify a test seed for reproducible `Random` behavior: +```bash +mvn clean install -DtestSeed +``` +When a test fails, the seed is printed in build output (look for "TestHelper" logger). +Re-run with the same seed to reproduce. + +Mute heavy logging in process tests: +```bash +mvn clean install -DargLine="-DmuteTestLogs=true" +``` + +Run specific tests in a TinkerPop Suite: +```bash +export GREMLIN_TESTS='org.apache.tinkerpop.gremlin.process.traversal.step.map.MatchTest$CountMatchTraversals' +mvn -Dmaven.javadoc.skip=true --projects tinkergraph-gremlin test +``` + +## Docker Images + +Build Docker images of Gremlin Server and Console: +```bash +mvn clean install -pl gremlin-server,gremlin-console -DdockerImages +``` + +Skip automatic Docker image build: +```bash +mvn clean install -DskipImageBuild +``` + +## Other Useful Commands + +Check license headers: +```bash +mvn apache-rat:check +``` + +Check for newer dependencies: +```bash +mvn versions:display-dependency-updates +mvn versions:display-plugin-updates +``` + +Test coverage report (must use `install`, not `test`): +```bash +mvn clean install -Dcoverage +``` +Reports go to `gremlin-tools/gremlin-coverage/target/site`. + +Benchmarks: +```bash +mvn verify -DskipBenchmarks=false +``` +Reports go to `gremlin-tools/gremlin-benchmark/target/reports/benchmark`. + +Regenerate toy graph data (only after IO class changes): +```bash +# From tinkergraph-gremlin directory +mvn clean install -Dio +``` diff --git a/.skills/tinkerpop-dev/references/build-javascript.md b/.skills/tinkerpop-dev/references/build-javascript.md new file mode 100644 index 0000000000..4dce0dd284 --- /dev/null +++ b/.skills/tinkerpop-dev/references/build-javascript.md @@ -0,0 +1,171 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# JavaScript / TypeScript GLV Build and Test + +## Architecture + +`gremlin-js/` serves two roles simultaneously: + +- **Maven parent module** (`packaging=pom`): declares `gremlin-javascript`, `gremlin-mcp`, + and `gremlint` as child modules; runs `npm ci` once at the workspace root. +- **npm workspace root**: `package.json` and `package-lock.json` live here; all three + packages share a single hoisted `node_modules/`. + +``` +gremlin-js/ +├── pom.xml Maven parent — runs npm ci +├── package.json npm workspace root +├── package-lock.json single lockfile for all packages +├── node_modules/ hoisted dependencies (gitignored) +├── node/ Node.js runtime from frontend-maven-plugin (gitignored) +├── gremlin-javascript/ JS driver (npm: "gremlin") +├── gremlin-mcp/ Gremlin MCP server (npm: "gremlin-mcp") +└── gremlint/ Gremlin query formatter (npm: "gremlint") +``` + +## Requirements + +- **Node.js 20+** / **npm 10+** — optional; Maven downloads a local copy. +- **Docker and Docker Compose** — required for integration and feature tests. +- **Maven** — preferred orchestration. + +## Maven Build Commands + +Run from the repository root. + +Build all JS packages (parent + children must be listed explicitly): +```bash +mvn clean install -pl :gremlin-js,:gremlin-javascript,:gremlint,:gremlin-mcp -DskipTests +mvn clean install -pl :gremlin-js,:gremlin-javascript,:gremlint,:gremlin-mcp # with tests +``` + +Build a single package: +```bash +mvn clean install -pl :gremlin-javascript -DskipTests +mvn clean install -pl :gremlin-mcp -DskipTests +mvn clean install -pl :gremlint -DskipTests +``` + +**`-DskipTests` behavior:** +- Skips Docker-based integration and feature tests for `gremlin-javascript` +- Skips `npm run validate` (which includes `npm test`) for `gremlin-mcp` +- Still runs `npm run build` and `npm run lint` for all modules + +Full build with tests (requires Docker): +```bash +mvn clean install -pl :gremlin-javascript +``` + +If building in isolation fails due to a missing parent: +```bash +mvn clean install -pl gremlin-js -DskipTests +``` + +## npm Commands + +Run from `gremlin-js/gremlin-javascript/` after `npm ci` has been run from `gremlin-js/`: + +| Command | Purpose | +|----------------------------|--------------------------------------------| +| `npm run unit-test` | Unit tests only — no server needed | +| `npm run integration-test` | Integration tests — requires Gremlin Server| +| `npm run features` | BDD feature tests — requires Gremlin Server| +| `npm run build` | Compile TypeScript to `build/` (ESM + CJS) | +| `npm run lint` | ESLint check | +| `npm run generate` | Regenerate grammar from `Gremlin.g4` | + +**Do not run `npm test` directly** — it chains unit and integration tests and will fail +without a server. Use `npm run unit-test` for fast local feedback. + +For `gremlin-mcp`: + +| Command | Purpose | +|----------------------|--------------------------------------------------| +| `npm test` | Run unit tests | +| `npm run test:it` | Integration tests (requires Gremlin Server) | +| `npm run lint` | ESLint check | +| `npm run build` | Compile TypeScript | +| `npm run validate` | All checks (format, lint, type-check, test) | + +## npm Workspace Rules + +All npm commands that affect dependencies must be run from `gremlin-js/`, not from +child package directories: + +```bash +cd gremlin-js/ +npm install +``` + +Scripts inside child packages must reference binaries by name (`mocha`, `tsc`, `eslint`) +rather than by relative path (`./node_modules/.bin/...`) because dependencies are hoisted. + +## What Not to Change Without Care + +- **`package-lock.json`** — regenerated by `npm install` from `gremlin-js/`. Do not edit + manually. After any `package.json` change in any child, run `npm install` from + `gremlin-js/` and commit the updated lockfile. +- **`gremlin-js/pom.xml`** — the `frontend-maven-plugin` block runs `npm ci` with + `<inherited>false</inherited>` so it executes only once at this level. Removing or + moving it will break partial `-pl` child builds. +- **Workspace member paths in `package.json`** — must match subdirectory names. Changing + them requires regenerating the lockfile and updating the pom `<modules>` list. + +## gremlin-javascript Directory Structure + +``` +gremlin-javascript/ +├── lib/ TypeScript source +│ └── language/ +│ ├── grammar/ Generated from Gremlin.g4 — do not edit; gitignored +│ └── translator/ Gremlin query translators (JS, Python, Go, .NET, Java, Groovy) +├── test/ +│ ├── unit/ Unit tests (mocha); no server needed +│ ├── integration/ Requires running Gremlin Server +│ └── cucumber/ BDD feature tests +├── scripts/ +│ ├── patch-antlr4ng.js postinstall — patches antlr4ng for CJS +│ └── groovy/ +│ └── generate.groovy Generates test/cucumber/gremlin.js from feature corpus +├── examples/ Standalone examples; excluded from ESLint +└── build/ Compiled output (ESM + CJS); gitignored +``` + +## Docker Permissions + +The integration test container runs as the host user (`HOST_UID`/`HOST_GID`, defaulting +to `1000:1000`). If you see `EACCES` errors: + +```bash +sudo chown -R $(whoami) /path/to/tinkerpop/gremlin-js/ +``` + +If your UID is not 1000: +```bash +mvn clean install -Dhost.uid=$(id -u) -Dhost.gid=$(id -g) -pl :gremlin-javascript +``` + +## Evaluating Build Results + +Do not use `grep` or `tail` on Maven output to judge pass/fail. Use the exit code: +- Exit `0` — success +- Non-zero — failure; inspect Docker container logs or Maven `[ERROR]` lines + +Test failures surface directly in the Maven console via npm's exit code. diff --git a/.skills/tinkerpop-dev/references/build-python.md b/.skills/tinkerpop-dev/references/build-python.md new file mode 100644 index 0000000000..469dacc50e --- /dev/null +++ b/.skills/tinkerpop-dev/references/build-python.md @@ -0,0 +1,127 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# Python GLV Build and Test + +## Requirements + +- **Python 3.9+** — optional for local development; Docker handles test execution via Maven. +- **Docker and Docker Compose** — required for running tests through Maven. +- **Maven** — preferred build orchestration. + +## Activation + +Create a `.glv` sentinel file to include Python in standard builds: +```bash +touch gremlin-python/.glv +``` + +Or use the Maven profile explicitly: +```bash +mvn clean install -Pglv-python -pl gremlin-python +``` + +## Maven Build Commands + +Run from the repository root. + +Run all tests: +```bash +mvn clean install -pl gremlin-python -Pglv-python +``` + +Run only unit tests: +```bash +mvn clean install -pl gremlin-python -Pglv-python -DpytestArgs="tests/unit" +``` + +Run only integration tests: +```bash +mvn clean install -pl gremlin-python -Pglv-python -DpytestArgs="tests/integration" +``` + +Run only feature tests: +```bash +mvn clean install -pl gremlin-python -Pglv-python -DradishArgs=" " +``` + +Run a specific test by name: +```bash +mvn clean install -pl gremlin-python -Pglv-python -DpytestArgs="-k test_name" +``` + +Run feature tests with specific tags: +```bash +mvn clean install -pl gremlin-python -Pglv-python -DradishArgs="-t @some_tag" +``` + +## Evaluating Build Results + +**Do not** use `grep`, `tail`, or similar text-search tools on Maven console output to +determine pass/fail. Maven output can be misleading because tests validate expected errors. + +Follow this hierarchy: + +1. **Check the exit code.** Exit `0` = success. Non-zero = failure. +2. **Inspect XML reports** on failure. Reports are in + `gremlin-python/target/python3/python-reports/`: + - `TEST-native-python.xml` — unit/integration tests + - `feature-graphbinary-result.xml` — GraphBinary feature tests + - `feature-graphbinary-params-result.xml` — GraphBinary parameterized + - `feature-graphbinary-bulked-result.xml` — GraphBinary bulked + - `feature-graphson-result.xml` — GraphSON feature tests + - `feature-graphson-params-result.xml` — GraphSON parameterized + +Feature test XML reports will not be present if unit/integration tests fail. + +**Do not** investigate a build failure beyond reporting what failed unless asked. + +## Manual Test Execution + +If you must run tests outside Maven, work from `gremlin-python/src/main/python/`: + +### Environment setup +```bash +python3 -m venv .venv +source .venv/bin/activate +pip install --upgrade pip +pip install .[test,kerberos] +``` + +### Gremlin Server management + +From `gremlin-python/`: +```bash +# Start/restart server +docker compose down gremlin-server-test-python +docker compose up -d gremlin-server-test-python + +# Check status (wait for healthy) +docker compose ps gremlin-server-test-python +``` + +### Running tests manually +- Unit tests: `pytest tests/unit/` +- Integration tests: `pytest tests/integration/` +- Feature tests: + ```bash + radish -f dots -e -t -b ./tests/radish \ + ../../../../gremlin-test/src/main/resources/org/apache/tinkerpop/gremlin/test/features \ + --user-data='serializer=application/vnd.gremlin-v3.0+json' + ``` diff --git a/.skills/tinkerpop-dev/references/dev-environment-setup.md b/.skills/tinkerpop-dev/references/dev-environment-setup.md new file mode 100644 index 0000000000..7e96b30867 --- /dev/null +++ b/.skills/tinkerpop-dev/references/dev-environment-setup.md @@ -0,0 +1,140 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# Development Environment Setup + +This guide walks through setting up a TinkerPop development environment from a fresh clone. +The canonical reference is `docs/src/dev/developer/development-environment.asciidoc`. + +## Prerequisites + +### Minimum (Java-only build) + +- **Java 11 or 17** — OpenJDK recommended. Use [SDKMAN!](https://sdkman.io/) to manage versions. + Note: some deep reflection requires `--add-opens` JVM options, which are already configured + in the pom files. +- **Maven 3.5.3+** — also manageable via SDKMAN. + +With just Java and Maven you can build JVM modules and get a clean `mvn clean install`, but +GLV builds and many integration tests will be skipped. + +### Full environment (all GLVs and integration tests) + +- **Docker and Docker Compose** — required for all GLV test execution. Docker Desktop includes + both. GLV tests run inside Docker containers, so local language runtimes are optional for + test execution via Maven. +- **Python 3.9+** — optional for local development; Docker handles test execution. +- **Node.js 20+ / npm 10+** — optional; Maven downloads a local copy via `frontend-maven-plugin`. + Consider [nvm](https://github.com/nvm-sh/nvm) for version management. +- **.NET SDK 8.0+** — optional; Docker handles test execution. +- **Go 1.22+** — optional; Docker handles test execution. + +## Environment Verification + +Run the included check script to verify your setup: + +```bash +bash .skills/tinkerpop-dev/scripts/check-env.sh +``` + +This checks for Java, Maven, Docker, and optionally Python, Node.js, .NET, and Go. + +## First Build + +After cloning, verify the basic build works: + +```bash +mvn clean install +``` + +This builds all JVM modules. GLV modules will be skipped unless activated (see below). + +## Activating GLV Builds + +Each Gremlin Language Variant uses a `.glv` sentinel file to signal Maven that the GLV +should be built as part of a standard `mvn clean install`. The file can be empty. + +### Python +```bash +touch gremlin-python/.glv +``` + +### JavaScript / TypeScript +No `.glv` file needed — JS modules build by default via the `frontend-maven-plugin`. +Tests require Docker and are skipped with `-DskipTests`. + +### .NET +Both `src` and `test` directories need the sentinel: +```bash +touch gremlin-dotnet/src/.glv +touch gremlin-dotnet/test/.glv +``` + +### Go +```bash +touch gremlin-go/.glv +``` + +Once `.glv` files are in place, a standard `mvn clean install` will include those GLVs. +The `.glv` files are gitignored. + +Alternatively, activate GLV builds explicitly with Maven profiles without `.glv` files: +- Python: `mvn clean install -Pglv-python -pl gremlin-python` +- .NET: `mvn clean install -pl gremlin-dotnet,gremlin-dotnet-source,gremlin-dotnet-tests` +- Go: `mvn clean install -Pglv-go -pl gremlin-go` + +## Groovy / Ivy Configuration + +The Gremlin Console is Groovy-based. For documentation generation or console testing with +SNAPSHOT dependencies, configure `~/.groovy/grapeConfig.xml`: + +```xml +<ivysettings> + <settings defaultResolver="downloadGrapes"/> + <resolvers> + <chain name="downloadGrapes"> + <ibiblio name="local" root="file:${user.home}/.m2/repository/" m2compatible="true"/> + <ibiblio name="central" root="https://repo1.maven.org/maven2/"; m2compatible="true"/> + </chain> + </resolvers> +</ivysettings> +``` + +## Docker Permissions (Linux) + +If you encounter "Permission denied" errors: + +```bash +sudo groupadd docker +sudo usermod -aG docker $USER +newgrp docker +sudo chmod 666 /var/run/docker.sock +``` + +## IDE Setup + +TinkerPop does not mandate a specific IDE. Import the root `pom.xml` as a Maven project. +For AI coding agent configuration, see the "Using AI Coding Agents" section in +`docs/src/dev/developer/development-environment.asciidoc`. + +## Next Steps + +- See `references/build-java.md` for Java module build details +- See the GLV-specific reference files for language-specific workflows +- See `references/documentation.md` for documentation generation diff --git a/.skills/tinkerpop-dev/references/documentation.md b/.skills/tinkerpop-dev/references/documentation.md new file mode 100644 index 0000000000..5e436cc8fa --- /dev/null +++ b/.skills/tinkerpop-dev/references/documentation.md @@ -0,0 +1,129 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# Documentation + +## Format and Location + +TinkerPop documentation is AsciiDoc-based and lives under `docs/src/`: + +``` +docs/src/ +├── reference/ Main reference documentation +├── dev/ +│ ├── developer/ Developer guides (environment, contributing, releases) +│ ├── provider/ Graph provider documentation, Gremlin semantics +│ ├── io/ IO and serialization formats +│ └── future/ Future plans +├── recipes/ Gremlin recipes and patterns +├── tutorials/ Getting started tutorials +└── upgrade/ Version upgrade guides +``` + +Do not use Markdown in the main docs tree. Use AsciiDoc. + +## Adding or Updating Documentation + +1. Place new content in the appropriate book (reference, dev, recipes, etc.). +2. Update the relevant `index.asciidoc` so the new content is included in the build. +3. Follow existing patterns for section structure and formatting. + +## Generating Documentation + +Documentation generation requires: +- Java 11 (specifically for doc generation) +- Hadoop 3.3.x in pseudo-distributed mode +- GNU versions of `grep`, `awk` (4.0.1+), `sed`, `findutils`, `diffutils` + (on macOS, install via Homebrew) +- `zip` utility + +Generate documentation: +```bash +bin/process-docs.sh +``` +Output goes to `target/docs/`. + +Dry run (don't evaluate code blocks): +```bash +bin/process-docs.sh --dryRun +``` + +Dry run for specific files: +```bash +bin/process-docs.sh --dryRun docs/src/reference/the-graph.asciidoc,docs/src/tutorial/getting-started,... +``` + +Full run for specific files only: +```bash +bin/process-docs.sh --fullRun docs/src/reference/the-graph.asciidoc,... +``` + +Process a single file: +```bash +docs/preprocessor/preprocess-file.sh \ + $(pwd)/gremlin-console/target/apache-tinkerpop-gremlin-console-*-standalone \ + "" "*" $(pwd)/docs/src/xyz.asciidoc +``` + +Documentation can also be generated with Docker: +```bash +docker/build.sh -d +``` + +## Website Generation + +Generate the website locally (no Hadoop or special infrastructure needed): +```bash +bin/generate-home.sh +``` +Output goes to `target/site/home`. + +The `docs/gremlint` web app requires Node.js and npm to be installed locally for +website generation and publishing. + +## JavaDoc / JSDoc + +Generate JavaDocs and JSDoc: +```bash +mvn process-resources -Djavadoc +``` +- JavaDoc output: `target/site/apidocs/` +- JSDoc output: `gremlin-js/gremlin-javascript/doc/` + +Use Java 11 for JavaDoc generation. + +## Publishing + +Deploy documentation: +```bash +bin/publish-docs.sh svn-username +``` + +Publish website: +```bash +bin/publish-home.sh <username> +``` + +## Common Issues + +- **"Error grabbing grapes"** during plugin installation: delete the problematic + dependency directories from both `~/.m2/` and `~/.groovy/grapes/`. +- **Unexpected OLAP failures**: usually a jar conflict from modified Hadoop/Spark + dependencies. Check `DependencyGrabber` class and plugin loading paths. +- **awk version**: version 4.0.1 is required. diff --git a/.skills/tinkerpop-dev/references/gremlin-mcp.md b/.skills/tinkerpop-dev/references/gremlin-mcp.md new file mode 100644 index 0000000000..680fc9bff5 --- /dev/null +++ b/.skills/tinkerpop-dev/references/gremlin-mcp.md @@ -0,0 +1,159 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# Gremlin MCP Server + +The Gremlin MCP server (`gremlin-mcp`) is an MCP (Model Context Protocol) server that +enables AI assistants to interact with Apache TinkerPop-compatible graph databases. It +lives at `gremlin-js/gremlin-mcp/` and is published as the `gremlin-mcp` npm package. + +## When to Use + +Use gremlin-mcp when you need to: +- **Translate Gremlin queries** between language variants (JavaScript, Python, Go, .NET, + Java, Groovy, canonical, anonymized) +- **Format Gremlin queries** using gremlint for consistent style +- **Query a graph database** through natural language via an AI assistant +- **Discover graph schema** including vertex/edge labels, properties, and enum values + +## Available Tools + +| Tool | Requires Server | Purpose | +|------------------------------|-----------------|--------------------------------------------| +| `translate_gremlin_query` | No | Translate Gremlin between language variants | +| `format_gremlin_query` | No | Format a Gremlin query with gremlint | +| `get_graph_status` | Yes | Check database connectivity | +| `get_graph_schema` | Yes | Get complete graph structure | +| `run_gremlin_query` | Yes | Execute a Gremlin traversal | +| `refresh_schema_cache` | Yes | Force refresh of cached schema | + +## Offline Mode + +When `GREMLIN_MCP_ENDPOINT` is not set, graph tools are not registered but +`translate_gremlin_query` and `format_gremlin_query` remain fully available. This is +useful for query translation and formatting without a running database. + +## Configuration + +### MCP Client Configuration (e.g., Claude Desktop, Cursor, Windsurf, Kiro) + +Using the published package: +```json +{ + "mcpServers": { + "gremlin": { + "command": "npx", + "args": ["gremlin-mcp"], + "env": { + "GREMLIN_MCP_ENDPOINT": "localhost:8182", + "GREMLIN_MCP_LOG_LEVEL": "info" + } + } + } +} +``` + +From source (after building): +```json +{ + "mcpServers": { + "gremlin": { + "command": "node", + "args": ["gremlin-js/gremlin-mcp/dist/server.js"], + "env": { + "GREMLIN_MCP_ENDPOINT": "localhost:8182", + "GREMLIN_MCP_LOG_LEVEL": "info" + } + } + } +} +``` + +For offline mode (translation and formatting only), omit `GREMLIN_MCP_ENDPOINT`. + +### With Authentication +```json +{ + "mcpServers": { + "gremlin": { + "command": "npx", + "args": ["gremlin-mcp"], + "env": { + "GREMLIN_MCP_ENDPOINT": "your-server.com:8182/g", + "GREMLIN_MCP_USERNAME": "your-username", + "GREMLIN_MCP_PASSWORD": "your-password", + "GREMLIN_MCP_USE_SSL": "true" + } + } + } +} +``` + +### Environment Variables + +| Variable | Required | Default | Purpose | +|---------------------------------------|----------|---------|----------------------------------| +| `GREMLIN_MCP_ENDPOINT` | No | — | Server endpoint (host:port[/g]) | +| `GREMLIN_MCP_USE_SSL` | No | false | Enable SSL/TLS | +| `GREMLIN_MCP_USERNAME` | No | — | Authentication username | +| `GREMLIN_MCP_PASSWORD` | No | — | Authentication password | +| `GREMLIN_MCP_IDLE_TIMEOUT` | No | 300 | Connection timeout (seconds) | +| `GREMLIN_MCP_LOG_LEVEL` | No | info | Logging: error, warn, info, debug| +| `GREMLIN_MCP_ENUM_DISCOVERY_ENABLED` | No | true | Smart enum detection | +| `GREMLIN_MCP_ENUM_CARDINALITY_THRESHOLD` | No | 10 | Max distinct values for enum | +| `GREMLIN_MCP_ENUM_PROPERTY_DENYLIST` | No | — | Properties to exclude from enums | + +## Translation + +The `translate_gremlin_query` tool supports these targets: +`canonical`, `javascript`, `python`, `go`, `dotnet`, `java`, `groovy`, `anonymized` + +The optional `source` parameter controls normalization: +- Omit or `auto` (default): mechanical normalization + LLM normalization via MCP sampling +- `canonical`: skip normalization (input must be canonical Gremlin ANTLR grammar) + +## Testing with MCP Inspector + +A fast way to test gremlin-mcp after building: +```bash +npx @modelcontextprotocol/inspector \ + node gremlin-js/gremlin-mcp/dist/server.js \ + -e GREMLIN_MCP_ENDPOINT=localhost:8182/g \ + -e GREMLIN_MCP_LOG_LEVEL=info +``` + +This starts the MCP server and opens a browser-based tool for interacting with it. + +## Building gremlin-mcp + +See `references/build-javascript.md` for full build instructions. Quick reference: + +```bash +# Build only +mvn clean install -pl :gremlin-mcp -DskipTests + +# Build and test +mvn clean install -pl :gremlin-mcp + +# npm commands (from gremlin-js/gremlin-mcp/) +npm test # Unit tests +npm run test:it # Integration tests (requires server) +npm run lint # Linting +npm run validate # All checks +``` diff --git a/.skills/tinkerpop-dev/scripts/check-env.sh b/.skills/tinkerpop-dev/scripts/check-env.sh new file mode 100755 index 0000000000..47c40e5259 --- /dev/null +++ b/.skills/tinkerpop-dev/scripts/check-env.sh @@ -0,0 +1,151 @@ +#!/usr/bin/env bash +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# + +# Verify TinkerPop development environment prerequisites. +# Usage: bash .skills/tinkerpop-dev/scripts/check-env.sh + +set -uo pipefail + +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[0;33m' +NC='\033[0m' + +pass=0 +warn=0 +fail=0 + +ok() { echo -e " ${GREEN}✓${NC} $1"; pass=$((pass + 1)); } +skip() { echo -e " ${YELLOW}○${NC} $1"; warn=$((warn + 1)); } +bad() { echo -e " ${RED}✗${NC} $1"; fail=$((fail + 1)); } + +echo "TinkerPop Development Environment Check" +echo "========================================" +echo "" + +# --- Java --- +echo "Core prerequisites:" +if command -v java &>/dev/null; then + java_version=$(java -version 2>&1 | head -1 | sed 's/.*"\(.*\)".*/\1/' | cut -d. -f1) + if [[ "$java_version" -ge 11 ]]; then + ok "Java $java_version (11+ required)" + else + bad "Java $java_version found — version 11 or 17 required" + fi +else + bad "Java not found — install Java 11 or 17 (try sdkman.io)" +fi + +# --- Maven --- +if command -v mvn &>/dev/null; then + mvn_version=$(mvn --version 2>/dev/null | head -1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1) + ok "Maven $mvn_version (3.5.3+ required)" +else + bad "Maven not found — install Maven 3.5.3+ (try sdkman.io)" +fi + +# --- Docker --- +if command -v docker &>/dev/null; then + if docker info &>/dev/null; then + ok "Docker installed and running" + else + bad "Docker installed but not running — start Docker Desktop or the daemon" + fi +else + bad "Docker not found — install Docker Desktop (includes Compose)" +fi + +# --- Docker Compose --- +if docker compose version &>/dev/null 2>&1; then + ok "Docker Compose available" +elif command -v docker-compose &>/dev/null; then + ok "Docker Compose (standalone) available" +else + skip "Docker Compose not found — needed for GLV tests" +fi + +echo "" +echo "Optional (GLV development):" + +# --- Python --- +if command -v python3 &>/dev/null; then + py_version=$(python3 --version 2>&1 | grep -oE '[0-9]+\.[0-9]+') + ok "Python $py_version (3.9+ recommended for gremlin-python local dev)" +else + skip "Python 3 not found — Docker handles test execution, but local dev needs it" +fi + +# --- Node.js --- +if command -v node &>/dev/null; then + node_version=$(node --version 2>/dev/null | sed 's/v//') + ok "Node.js $node_version (20+ recommended for gremlin-js local dev)" +else + skip "Node.js not found — Maven downloads a local copy automatically" +fi + +# --- .NET SDK --- +if command -v dotnet &>/dev/null; then + dotnet_version=$(dotnet --version 2>/dev/null) + ok ".NET SDK $dotnet_version (8.0+ recommended for gremlin-dotnet local dev)" +else + skip ".NET SDK not found — Docker handles test execution" +fi + +# --- Go --- +if command -v go &>/dev/null; then + go_version=$(go version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?') + ok "Go $go_version (1.22+ recommended for gremlin-go local dev)" +else + skip "Go not found — Docker handles test execution" +fi + +echo "" +echo "GLV activation status:" + +# --- .glv sentinel files --- +check_glv() { + local name="$1" + shift + local found=false + for f in "$@"; do + if [[ -f "$f" ]]; then + found=true + fi + done + if $found; then + ok "$name — activated (.glv present)" + else + skip "$name — not activated (create .glv to enable in standard builds)" + fi +} + +check_glv "gremlin-python" "gremlin-python/.glv" +check_glv "gremlin-dotnet" "gremlin-dotnet/src/.glv" "gremlin-dotnet/test/.glv" +check_glv "gremlin-go" "gremlin-go/.glv" + +echo "" +echo "----------------------------------------" +echo -e "Results: ${GREEN}$pass passed${NC}, ${YELLOW}$warn skipped${NC}, ${RED}$fail failed${NC}" + +if [[ $fail -gt 0 ]]; then + echo "" + echo "Fix the failed items above before building. See references/dev-environment-setup.md" + exit 1 +fi diff --git a/AGENTS.md b/AGENTS.md index aa8a2e13d3..d78729603c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,219 +1,49 @@ # AGENTS.md -You are a TinkerPop developer working across the entire monorepo—code, tests, docs, and website to implement, -maintain, and validate Apache TinkerPop’s graph computing framework and its multi-language Gremlin ecosystem. +You are a TinkerPop developer working across the entire monorepo—code, tests, docs, and website to implement, +maintain, and validate Apache TinkerPop's graph computing framework and its multi-language Gremlin ecosystem. -- `README.md` -- `CONTRIBUTING.md` -- Developer documentation at `docs/src/dev/**` - -This file must not contradict those documents. If it appears to, treat them as canonical and update this file -accordingly. - -*** - -## 1. Project overview - -Key project docs (prefer these local files over external URLs): - -- Reference docs: `docs/src/reference/**` -- Recipes: `docs/src/recipes/**` -- Upgrade docs: `docs/src/upgrade/**` -- IO and Serialization docs: `docs/src/dev/io/**` -- Provider docs and Gremlin Semantics: `docs/src/dev/provider/**` -- Developer docs: `docs/src/dev/developer/**` -- Future plans: `docs/src/dev/future/**` - -The project website mirrors these for released versions; use local files for branch‑accurate information. - -*** - -## 2. Repository structure (high level) - -Use these as anchors when exploring the repo: - -- Core code and modules: Maven multi‑module layout under the repo root, though modules may not contain JVM-relevant code - (i.e. Maven is simply the build orchestration tool wrapping other environments like Python or Go) -- Docs: `docs/src/**` (AsciiDoc “books”, reference, dev docs, recipes, etc.) -- Changelog: `CHANGELOG.asciidoc` -- Website: `docs/site/**` -- Scripts: - - Docker scripts: `docker/*.sh` - - Docs/site scripts: `bin/process-docs.sh`, `bin/generate-home.sh` - -When adding or modifying files, follow the existing structure and conventions in the surrounding directory. - -*** - -## 3. Nested AGENTS.md files - -This repository uses additional `AGENTS.md` files in certain subdirectories (for example, -`gremlin-python/AGENTS.md`, `gremlin-dotnet/AGENTS.md`, etc.) to provide stack‑specific guidance. - -Agents should: - -- Always read this root `AGENTS.md` for global rules. -- When working in a subdirectory, also look for the closest `AGENTS.md` in the current or parent -directories and apply its instructions for that area. -- Treat more specific `AGENTS.md` files (deeper in the tree) as overriding or refining the generic -guidance here when there is a conflict. - -## 4. Build and test recipes - -### 4.1 Basic build and test - -- Build everything: - - ```bash - mvn clean install - ``` - -- Build a specific module: - - ```bash - mvn clean install -pl <module-name> - ``` - - Example: - - ```bash - mvn clean install -pl tinkergraph-gremlin - ``` - -### 4.2 Integration and specialized builds - -- Enable integration tests: - - ```bash - mvn clean install -DskipIntegrationTests=false - ``` - -### 4.3 Gremlin Language Variant (GLV) builds - -Build Gremlin Server first: +## Primary Guidance: Agent Skills -```bash -mvn clean install -pl :gremlin-server -am -DskipTests -``` +This repository provides development guidance as an [Agent Skill](https://agentskills.io) named +`tinkerpop-dev`. If your tool supports Agent Skills, **activate that skill** for detailed, +task-specific instructions covering build recipes, test evaluation, coding conventions, and +reference material for each Gremlin Language Variant. -Each GLV has its own module structure: +If your tool does not discover the skill automatically, run `bin/agent-setup.sh --list` to +see how to configure it, or `bin/agent-setup.sh <agent>` to set up the integration. -- Python: +## Canonical Documentation - ```bash - mvn clean install -Pglv-python -pl gremlin-python - ``` +These local documents are authoritative. If this file appears to contradict them, treat them as canonical. -- .NET: - - ```bash - mvn clean install -pl gremlin-dotnet,gremlin-dotnet-source,gremlin-dotnet-tests - ``` - -- JavaScript: - - ```bash - mvn clean install -Pglv-js -pl gremlin-javascript - ``` - -- Go: - - ```bash - mvn clean install -Pglv-go -pl gremlin-go - ``` - -*** - -## 5. Documentation - -TinkerPop’s documentation is AsciiDoc‑based and lives under `docs/src/**`. - -When adding or updating docs: - -- Use AsciiDoc (not Markdown) in the main docs tree. -- Place new content in the appropriate book (reference, dev, recipes, etc.). -- Update the relevant `index.asciidoc` so the new content is included in the build. - -*** - -## 6. Coding and testing conventions - -Agents should follow these conventions when generating or editing code and tests. - -### 6.1 Code style - -- All files should include the Apache Software Foundation license header - canonical text for the header is at `bin/asf-license-header.txt`. -- Do **not** use import wildcards (for example, avoid `import org.apache.tinkerpop.gremlin.structure.*`); prefer explicit imports. -- Respect existing naming patterns and package organization. -- Define variables as `final` whenever possible, except for loop variables. - -### 6.2 Test guidelines - -- Prefer SLF4J `Logger` for output instead of `System.out.println` or `println` in tests. -- Use `TestHelper` utilities to create temporary directories and file structures for file‑based tests, instead of hard‑coding paths. -- Always close `Graph` instances that are manually constructed in tests. -- Tests using a `GraphProvider` implementation with `AbstractGremlinTest` should be suffixed with `Check` instead of `Test`. -- Prefer Hamcrest matchers for boolean‑style assertions (for example, `assertThat(..., is(true))`) instead of manually checking booleans. -- For Gremlin language tests, see the "Gremlin Language Test Cases" section of `docs/src/dev/developer/for-committers.asciidoc` -for more details and use Gherkin tests under: - - ```text - gremlin-tests/src/main/resources/org/apache/tinkerpop/gremlin/test/features - ``` - -*** - -## 7. Changelog, license, and checks - -When changes affect behavior, APIs, or user‑visible features: - -- Add or update entries in `CHANGELOG.asciidoc` in the correct version section. -- Do not invent new version numbers or release names; follow the existing pattern. -- Preserve and respect license headers and notices in all files. -- Avoid adding third‑party code or dependencies with incompatible licenses. - -*** +- `README.md` +- `CONTRIBUTING.md` +- Developer documentation at `docs/src/dev/**` -## 8. Do and don’t for agents +## Essential Rules These rules apply to any AI/IDE assistant operating on this repository. -### 8.1 Do - -- **Do** make small, focused changes that are easy to review. -- **Do** run the relevant build and test commands before suggesting that a change is complete. -- **Do** update or add tests when behavior changes. -- **Do** update documentation and/or changelog when you change public behavior or APIs. -- **Do** follow existing patterns for code structure, documentation layout, and naming. -- **Do** point maintainers to relevant documentation or issues when proposing non‑trivial changes. - -### 8.2 Don’t - -- **Don’t** perform large, sweeping refactors (across many modules or files) unless explicitly requested. -- **Don’t** change public APIs, configuration formats, or network protocols without explicit human approval and associated design/issue. -- **Don’t** switch documentation formats (e.g., AsciiDoc to Markdown) in the main docs tree. -- **Don’t** introduce new external dependencies, modules, or build plugins without an associated discussion and issue. -- **Don’t** invent project policies, version numbers, or release names. -- **Don’t** remove or weaken tests to “fix” failures; adjust the implementation or the test data instead. - -If you are uncertain about the impact of a change, prefer to: - -- Make a minimal patch. -- Add comments or notes for reviewers. -- Ask for clarification. +### Do -*** +- Make small, focused changes that are easy to review. +- Run the relevant build and test commands before suggesting that a change is complete. +- Update or add tests when behavior changes. +- Update documentation and/or changelog when you change public behavior or APIs. +- Follow existing patterns for code structure, documentation layout, and naming. -## 9. When in doubt +### Don't -If AGENTS.md does not clearly cover a situation: +- Don't perform large, sweeping refactors unless explicitly requested. +- Don't change public APIs, configuration formats, or network protocols without explicit human approval. +- Don't switch documentation formats (e.g., AsciiDoc to Markdown) in the main docs tree. +- Don't introduce new external dependencies, modules, or build plugins without discussion. +- Don't invent project policies, version numbers, or release names. +- Don't remove or weaken tests to "fix" failures; adjust the implementation or test data instead. -1. Look for relevant information in: - - `CONTRIBUTING.md` - - Developer docs under `docs/src/dev/developer/**` - - Reference docs and recipes -2. Prefer **no change** over an unsafe or speculative change. -3. Surface the question to human maintainers (for example, by leaving a comment, or drafting a minimal PR that asks for guidance). +### When In Doubt -This file is intended to help tools act like a careful, well‑informed contributor. When in doubt, defer to human -judgment and the canonical project documentation. \ No newline at end of file +1. Check `CONTRIBUTING.md` and developer docs under `docs/src/dev/developer/`. +2. Prefer no change over an unsafe or speculative change. +3. Ask for clarification. diff --git a/bin/agent-setup.sh b/bin/agent-setup.sh new file mode 100755 index 0000000000..23097448e5 --- /dev/null +++ b/bin/agent-setup.sh @@ -0,0 +1,200 @@ +#!/usr/bin/env bash +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# + +# Set up AI coding agent integration with TinkerPop's Agent Skills. +# +# TinkerPop maintains development guidance as an Agent Skill in .skills/tinkerpop-dev/. +# Different AI coding tools discover skills in different directories. This script +# creates the necessary symlinks or shims so your tool can find the skill. +# +# Usage: +# bin/agent-setup.sh <agent> +# bin/agent-setup.sh --list +# bin/agent-setup.sh --all +# +# Examples: +# bin/agent-setup.sh claude # Set up for Claude Code +# bin/agent-setup.sh kiro # Set up for Kiro +# bin/agent-setup.sh --all # Set up for all supported agents +# +# Supported agents: +# claude - Claude Code (.claude/skills/) +# copilot - GitHub Copilot (.github/skills/ and .agents/skills/) +# cursor - Cursor (.cursor/skills/) +# codex - OpenAI Codex (.codex/skills/) +# junie - JetBrains Junie (.junie/skills/) +# kiro - Kiro (.kiro/skills/) + +set -uo pipefail + +SKILL_DIR=".skills/tinkerpop-dev" +SKILL_NAME="tinkerpop-dev" + +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[0;33m' +NC='\033[0m' + +ok() { echo -e " ${GREEN}✓${NC} $1"; } +skip() { echo -e " ${YELLOW}○${NC} $1"; } +bad() { echo -e " ${RED}✗${NC} $1"; } + +usage() { + echo "Usage: bin/agent-setup.sh <agent|--list|--all>" + echo "" + echo "Agents: claude, copilot, cursor, codex, junie, kiro" + echo "" + echo "Options:" + echo " --list List supported agents and their skill discovery paths" + echo " --all Set up shims for all supported agents" + echo " --help Show this message" +} + +# Verify we're in the repo root +if [[ ! -d "$SKILL_DIR" ]]; then + bad "Cannot find $SKILL_DIR — run this script from the TinkerPop repository root." + exit 1 +fi + +# Create a symlink from a tool's skill directory to our canonical skill +setup_symlink() { + local tool_name="$1" + local target_dir="$2" + + mkdir -p "$target_dir" + local link_path="$target_dir/$SKILL_NAME" + + if [[ -L "$link_path" ]]; then + skip "$tool_name: symlink already exists at $link_path" + return 0 + fi + + if [[ -e "$link_path" ]]; then + bad "$tool_name: $link_path already exists and is not a symlink — skipping" + return 1 + fi + + # Compute relative path from target_dir to SKILL_DIR + local rel_path + rel_path=$(python3 -c "import os.path; print(os.path.relpath('$SKILL_DIR', '$target_dir'))" 2>/dev/null) + if [[ -z "$rel_path" ]]; then + # Fallback if python3 not available + rel_path=$(perl -e 'use File::Spec; print File::Spec->abs2rel("'"$SKILL_DIR"'", "'"$target_dir"'")' 2>/dev/null) + fi + if [[ -z "$rel_path" ]]; then + bad "$tool_name: could not compute relative path (need python3 or perl)" + return 1 + fi + + ln -s "$rel_path" "$link_path" + ok "$tool_name: created symlink $link_path -> $rel_path" +} + +# Kiro doesn't follow symlinks in .kiro/skills/, so we copy the skill directory +# instead. See: https://github.com/kirodotdev/Kiro/issues (symlink support). +setup_kiro() { + local target_dir=".kiro/skills/$SKILL_NAME" + + if [[ -d "$target_dir" ]]; then + rm -rf "$target_dir" + skip "kiro: removed existing copy at $target_dir" + fi + + mkdir -p ".kiro/skills" + cp -r "$SKILL_DIR" "$target_dir" + ok "kiro: copied skill to $target_dir" + echo "" + echo -e " ${YELLOW}NOTE:${NC} Kiro uses a copy, not a symlink. If you update the skill in" + echo -e " $SKILL_DIR, re-run this script to sync the changes." +} + +setup_agent() { + local agent="$1" + case "$agent" in + claude) + setup_symlink "claude" ".claude/skills" + ;; + copilot) + setup_symlink "copilot (.github)" ".github/skills" + setup_symlink "copilot (.agents)" ".agents/skills" + ;; + cursor) + setup_symlink "cursor" ".cursor/skills" + ;; + codex) + setup_symlink "codex" ".codex/skills" + ;; + junie) + setup_symlink "junie" ".junie/skills" + ;; + kiro) + setup_kiro + ;; + *) + bad "Unknown agent: $agent" + echo "" + usage + return 1 + ;; + esac +} + +list_agents() { + echo "Supported agents and their skill discovery paths:" + echo "" + echo " claude .claude/skills/$SKILL_NAME/ -> symlink to $SKILL_DIR" + echo " copilot .github/skills/$SKILL_NAME/ -> symlink to $SKILL_DIR" + echo " .agents/skills/$SKILL_NAME/ -> symlink to $SKILL_DIR" + echo " cursor .cursor/skills/$SKILL_NAME/ -> symlink to $SKILL_DIR" + echo " codex .codex/skills/$SKILL_NAME/ -> symlink to $SKILL_DIR" + echo " junie .junie/skills/$SKILL_NAME/ -> symlink to $SKILL_DIR" + echo " kiro .kiro/skills/$SKILL_NAME/ -> copy of $SKILL_DIR (re-run to sync)" +} + +# --- Main --- + +if [[ $# -eq 0 ]]; then + usage + exit 1 +fi + +case "$1" in + --help|-h) + usage + ;; + --list) + list_agents + ;; + --all) + echo "Setting up all agent integrations..." + echo "" + for agent in claude copilot cursor codex junie kiro; do + setup_agent "$agent" + done + echo "" + echo "Done. Symlinked directories and generated files are gitignored." + echo "Add them to .gitignore if they aren't already." + ;; + *) + echo "Setting up $1..." + echo "" + setup_agent "$1" + ;; +esac diff --git a/docs/src/dev/developer/development-environment.asciidoc b/docs/src/dev/developer/development-environment.asciidoc index b7b419d46c..a38842c2e1 100644 --- a/docs/src/dev/developer/development-environment.asciidoc +++ b/docs/src/dev/developer/development-environment.asciidoc @@ -448,48 +448,39 @@ be done automatically on `mvn deploy` or it can be triggered manually with `mvn == Using AI Coding Agents TinkerPop does not endorse or require any particular AI Coding Agents or tool. As a result, tool-specific project -guidelines are not included with the code base. TinkerPop does, however, provide for a generic, agent-agnostic `AGENTS.md` -file at the root of the project. Developers should make use of this file's instructions by pointing their specific -AI-based tool to it. While tools may vary in how they are set up, the approach is to treat tool-specific files, such as -`.junie/guidelines.md`, `.claude/CLAUDE.md` etc., as thin shims that just point to TinkerPop's `AGENTS.md` instead of -relying on individual rules. The content of those tool-specific files should: +guidelines are not included with the code base. In general, TinkerPop attempts to stay agnostic to coding agents +while also supporting -* Explain that AGENTS.md is the canonical source. -* Tell the assistant to read and follow it, and not to diverge from it. -* Optionally include one or two tool‑specific behaviors (like “prefer smaller edits”) if you want. +=== Agent Skills -The following is a basic example of such a setup: +TinkerPop provides development guidance as an link:https://agentskills.io[Agent Skill] in `.skills/tinkerpop-dev/`. +The skill follows the open Agent Skills standard and includes: -[source,text] ----- -# Apache TinkerPop – Guidelines - -This project uses `AGENTS.md` in the repository root as the canonical guide for AI/IDE assistants and automated tools. - -You should: - -1. Read and follow the instructions in `AGENTS.md` for: - - Repository structure - - Build and test commands - - Coding, testing, and deprecation conventions - - “Do” and “Don’t” rules for agents +* Project conventions, coding standards, and agent guardrails (in `SKILL.md`) +* Build and test recipes for each Gremlin Language Variant (in `references/`) +* Development environment setup instructions and a verification script (in `scripts/`) +* Gremlin MCP server usage guidance for query translation, formatting, and graph querying -2. Treat `AGENTS.md`, `CONTRIBUTING.*`, and the developer docs under `docs/src/dev/**` as higher priority than any generic or built‑in behavior. +Tools that support Agent Skills (Claude Code, GitHub Copilot, Cursor, OpenAI Codex, JetBrains Junie, Kiro, and others) +will discover and activate the skill automatically when it is placed in the tool's expected directory. A setup script +is provided to create the necessary symlinks or copies: -3. Prefer small, focused edits that: - - Match the existing code style and patterns in the files being changed - - Include or update tests when behavior changes - - Update documentation and `CHANGELOG.asciidoc` when public behavior or APIs change - -You must **not**: +[source,bash] +---- +# Set up for a specific tool +bin/agent-setup.sh claude +bin/agent-setup.sh kiro -- Introduce new dependencies, modules, or large refactors without an explicit human request -- Change public APIs, protocols, or configuration formats without a clearly documented issue and human approval -- Rewrite AsciiDoc documentation into other formats +# Set up for all supported tools +bin/agent-setup.sh --all -If you are uncertain how to proceed based on this file, `AGENTS.md`, or the local AsciiDoc documentation, you should stop and ask for clarification instead of guessing. +# List supported tools and their discovery paths +bin/agent-setup.sh --list ---- +The script supports: `claude`, `copilot`, `cursor`, `codex`, `junie`, and `kiro`. The generated symlinks and copies +are gitignored and local to each developer's environment. + [[building-testing]] == Building and Testing @@ -577,7 +568,7 @@ supported: A list of command line options is provided by `docker/build.sh --help`. The container will install, configure and start all required dependencies, such as Hadoop. -By default, this script will run every module in the project. However, if you are planning on working on just a +By default, this script will run every module in the project. However, if you are planning on working on just small set of the modules (e.g. the GLVs) then you can use the script options to reduce the modules included by specifically selecting which modules you want. This behavior is currently supported for the non-Java GLVs and gremlin-console. This option will include only the selected modules as well as gremlin-server, gremlin-test, diff --git a/gremlin-js/AGENTS.md b/gremlin-js/AGENTS.md deleted file mode 100644 index c7d6548572..0000000000 --- a/gremlin-js/AGENTS.md +++ /dev/null @@ -1,103 +0,0 @@ -### gremlin-js AGENTS.md - -This document provides guidance for developers and AI agents working anywhere inside the `gremlin-js/` -directory. It supplements the root `AGENTS.md` and is the parent context for the child module AGENTS.md -files in `gremlin-javascript/`, `gremlin-mcp/`, and `gremlint/`. - ---- - -### 1. What This Directory Is - -`gremlin-js/` is a Maven parent module (`packaging=pom`) that owns all JavaScript packages in the -TinkerPop monorepo. It serves two roles simultaneously: - -- **Maven parent**: declares `gremlin-javascript`, `gremlin-mcp`, and `gremlint` as child modules; - runs `npm ci` once at the workspace root before any child build executes -- **npm workspace root**: `package.json` and `package-lock.json` live here; all three packages are - workspace members and share a single hoisted `node_modules/` - -These two roles are coupled. When Maven builds any child module, it first installs Node/npm here and -runs `npm ci` here, populating `node_modules/` for all three packages at once. - ---- - -### 2. Directory Structure - -``` -gremlin-js/ -├── pom.xml Maven parent — runs npm ci; no jar produced, no artifact deployed -├── package.json npm workspace root -├── package-lock.json single lockfile for all three packages -├── node_modules/ hoisted dependencies for all workspace members (gitignored) -├── node/ Node.js runtime installed by frontend-maven-plugin (gitignored) -├── gremlin-javascript/ Gremlin JavaScript driver (npm package "gremlin") -├── gremlin-mcp/ Gremlin MCP server (npm package "gremlin-mcp") -└── gremlint/ Gremlin query formatter (npm package "gremlint") -``` - -Child module AGENTS.md files provide package-specific detail: -- `gremlin-javascript/AGENTS.md` - ---- - -### 3. Maven Build Commands - -Run from the **repository root**: - -**Build all JS packages together** (parent + all three children must be listed explicitly — -`-pl gremlin-js` alone only builds the parent pom, not its child modules): -```bash -mvn clean install -pl :gremlin-js,:gremlin-javascript,:gremlint,:gremlin-mcp -DskipTests -mvn clean install -pl :gremlin-js,:gremlin-javascript,:gremlint,:gremlin-mcp # includes tests (requires Docker) -``` - -**Build a single child module** (Maven resolves by artifactId): -```bash -mvn clean install -pl :gremlin-javascript -DskipTests -mvn clean install -pl :gremlin-mcp -DskipTests -mvn clean install -pl :gremlint -DskipTests -``` - -Each child module pom contains its own `npm ci` execution (workspace root) so partial `-pl` builds -are self-sufficient — they do not require the parent to have been built first. - -**`-DskipTests` behavior:** -- Skips Docker-based integration tests and feature tests for `gremlin-javascript` -- Skips `npm run validate` (which includes `npm test`) for `gremlin-mcp` -- Still runs `npm run build` and `npm run lint` for all modules - ---- - -### 4. npm Workspace Mechanics - -All npm commands that affect dependencies must be run from `gremlin-js/`, not from inside a child -package directory, to keep `package-lock.json` consistent. - -```bash -# Install / update dependencies -cd gremlin-js/ -npm install - -# Run scripts for a specific workspace member -npm run build -w gremlin-javascript -npm run test -w gremlin-mcp -``` - -Because packages are hoisted to `gremlin-js/node_modules/`, scripts inside child packages must -reference binaries by name (`mocha`, `tsc`, `eslint`) rather than by relative path -(`./node_modules/.bin/...`). Similarly, `postinstall` scripts that resolve packages must use -`createRequire` or `require.resolve` rather than hardcoded relative paths. - ---- - -### 5. What Not to Change Without Care - -- **`package-lock.json`** — regenerated by running `npm install` from this directory; do not edit - manually. After any `package.json` change in any child, run `npm install` here and commit the - updated lockfile. -- **`gremlin-js/pom.xml`** — the `frontend-maven-plugin` block here runs `npm ci` with - `<inherited>false</inherited>` so it executes only once at this level, not in every child. - Removing or moving it will break partial `-pl` child builds. -- **Workspace member paths in `package.json`** — must match the actual subdirectory names - (`gremlin-javascript`, `gremlin-mcp`, `gremlint`). Changing these requires regenerating the - lockfile and updating the pom `<modules>` list. diff --git a/gremlin-js/gremlin-javascript/AGENTS.md b/gremlin-js/gremlin-javascript/AGENTS.md deleted file mode 100644 index 64e6e6994e..0000000000 --- a/gremlin-js/gremlin-javascript/AGENTS.md +++ /dev/null @@ -1,138 +0,0 @@ -### gremlin-javascript AGENTS.md - -This document provides stack-specific guidance for developers and AI agents working on the `gremlin-javascript` -module. It supplements the root `AGENTS.md` file. - ---- - -### 1. Maven and npm Workspace Relationship - -`gremlin-javascript` is part of the `gremlin-js` Maven parent module. Understanding this relationship is -critical before making build or path changes. - -**Maven hierarchy:** -``` -tinkerpop/pom.xml -└── gremlin-js/pom.xml ← Maven parent; runs `npm ci` at workspace root - ├── gremlin-javascript/pom.xml ← this module - ├── gremlin-mcp/pom.xml - └── gremlint/pom.xml -``` - -**npm workspace hierarchy:** -``` -gremlin-js/package.json ← workspace root (node_modules/ lives here) -├── gremlin-javascript/ ← workspace member "gremlin" -├── gremlin-mcp/ ← workspace member "gremlin-mcp" -└── gremlint/ ← workspace member "gremlint" -``` - -Because npm workspaces hoist shared dependencies to `gremlin-js/node_modules/`, packages such as `mocha`, -`antlr4ng`, and `typescript` may **not** exist under `gremlin-javascript/node_modules/`. Scripts must -reference them by name (e.g. `mocha`) rather than by relative path (e.g. `./node_modules/mocha/bin/mocha.js`). -The `postinstall` script (`scripts/patch-antlr4ng.js`) uses `createRequire` to resolve packages through -the workspace rather than assuming a local `node_modules/`. - ---- - -### 2. Directory Structure - -``` -gremlin-javascript/ -├── lib/ TypeScript source (driver, process, structure, language) -│ └── language/ -│ ├── grammar/ Generated by antlr-ng from Gremlin.g4 — do not edit manually; gitignored -│ └── translator/ Gremlin query translators (JS, Python, Go, .NET, Java, Groovy) -├── test/ -│ ├── unit/ Unit tests (mocha); run without a server -│ └── integration/ Integration tests; require a running Gremlin Server -│ └── cucumber/ BDD feature tests driven by gremlin-test feature files -├── scripts/ -│ ├── patch-antlr4ng.js postinstall — patches antlr4ng for CJS TypeScript declarations -│ └── groovy/ -│ └── generate.groovy Maven/gmavenplus script that generates test/cucumber/gremlin.js -│ from the gremlin-test feature corpus; referenced in pom.xml -├── examples/ Standalone Node.js examples; excluded from ESLint and not part of the npm build -├── build/ Compiled output (ESM + CJS); gitignored; deleted and recreated by `npm run build` -├── gremlin-test/ Docker bind-mount target only — not tracked by git; created at runtime by -│ the integration test container to hold graphbinary test data and translator -│ resources mounted from the repo's gremlin-test/ module -├── gremlin-test-server/ Docker bind-mount target only — not tracked by git -└── gremlin-socket-server/ Docker bind-mount target only — not tracked by git -``` - ---- - -### 3. Build and Test Requirements - -- **Node.js** 20 or higher -- **npm** 10 or higher -- **Docker** and Docker Compose (for integration and feature tests) -- **Maven** (preferred orchestration for full test runs) - ---- - -### 4. Preferred Build Orchestration - -Run from the **repository root**. Maven handles Node installation, `npm ci`, grammar generation, linting, -and test execution. - -**Full build with tests (requires Docker):** -```bash -mvn clean install -pl :gremlin-javascript -``` - -**Skip tests (no Docker required):** -```bash -mvn clean install -pl :gremlin-javascript -DskipTests -``` - -The `gremlin-js` parent must be resolvable. If building in isolation fails due to a missing parent, build -the parent first: -```bash -mvn clean install -pl gremlin-js -DskipTests -``` - ---- - -### 5. Manual npm Commands - -Run from `gremlin-js/gremlin-javascript/` after `npm ci` has been run from `gremlin-js/`: - -| Command | Purpose | -|---|---| -| `npm run unit-test` | Unit tests only — no server needed | -| `npm run integration-test` | Integration tests — requires Gremlin Server | -| `npm run features` | BDD feature tests — requires Gremlin Server | -| `npm run build` | Compile TypeScript to `build/` (ESM + CJS) | -| `npm run lint` | ESLint check | -| `npm run generate` | Regenerate `lib/language/grammar/` from `Gremlin.g4` | - -**Do not run `npm test` directly** — it chains unit and integration tests and will fail without a server. -Use `npm run unit-test` for fast local feedback. - ---- - -### 6. Docker Permissions - -The integration test container mounts the repo under `/workspace` and runs as the host user -(`HOST_UID`/`HOST_GID`, defaulting to `1000:1000`). If you see `EACCES` errors from `npm ci` or -`mvn clean`, a previous Docker run likely wrote root-owned files into `gremlin-js/`. Fix with: - -```bash -sudo chown -R $(whoami) /path/to/tinkerpop/gremlin-js/ -``` - -If your UID is not 1000, pass `-Dhost.uid=$(id -u) -Dhost.gid=$(id -g)` to Maven. - ---- - -### 7. Evaluating Build Results - -Do **not** use `grep` or `tail` on Maven output to judge pass/fail. Use the exit code: - -- Exit `0` — success -- Non-zero — failure; inspect Docker container logs or the Maven `[ERROR]` lines for root cause - -Test output files are not written to `target/` in the JUnit XML sense for this module — failures surface -directly in the Maven console via npm's exit code. diff --git a/gremlin-python/AGENTS.md b/gremlin-python/AGENTS.md deleted file mode 100644 index c05d67aacd..0000000000 --- a/gremlin-python/AGENTS.md +++ /dev/null @@ -1,107 +0,0 @@ -### gremlin-python AGENTS.md - -This document provides stack-specific guidance for developers and AI agents working on the `gremlin-python` module. It -supplements the root `AGENTS.md` file. - ---- - -### 1. Build and Test Requirements - -To build and run tests for `gremlin-python`, ensure the following: - -* **Python Version**: Python 3.9 or higher must be installed. -* **Virtual Environment**: While a virtual environment is recommended for local development, the preferred way to - run tests is via Maven and Docker, which handles environment isolation automatically. -* **Docker**: Docker and Docker Compose must be installed and running. -* **Maven**: Maven must be installed. - -### 2. Preferred Build Orchestration - -The preferred way to run tests is via Maven from the repository root. This ensures an OS-agnostic execution environment -and handles all dependencies, including starting the Gremlin Server. - -* **Run all tests**: - ```bash - mvn clean install -pl gremlin-python -Pglv-python - ``` - -* **Run only Unit Tests**: - ```bash - mvn clean install -pl gremlin-python -Pglv-python -DpytestArgs="tests/unit" - ``` - -* **Run only Integration Tests**: - ```bash - mvn clean install -pl gremlin-python -Pglv-python -DpytestArgs="tests/integration" - ``` - -* **Run only Feature Tests**: - ```bash - mvn clean install -pl gremlin-python -Pglv-python -DradishArgs=" " - ``` - -### 3. Targeted Test Execution - -You can pass arguments to `pytest` or `radish` via Maven properties to run specific tests. - -* **Run a specific Unit/Integration test**: - ```bash - mvn clean install -pl gremlin-python -Pglv-python -DpytestArgs="-k test_name" - ``` - -* **Run Feature tests with specific tags**: - ```bash - mvn clean install -pl gremlin-python -Pglv-python -DradishArgs="-t @some_tag" - ``` - -### 4. Evaluating Build Results - -**DO NOT** use `grep`, `tail` or similar text-search tools on the Maven console output (or `.output.txt`) to determine -if the tests passed or failed. The Maven output can be misleading due to the tests validating expected errors. - -To accurately evaluate the results, follow this strict hierarchy: - -1. **Check the Command Exit Code**: A successful build **must** exit with code `0`. Any non-zero exit code is a failure. -2. **Verify via XML Reports**: If the build fails (non-zero exit) you **must** inspect the JUnit XML reports in `gremlin-python/target/python3/python-reports/`: - * `TEST-native-python.xml` (Unit/Integration tests) - * `feature-graphbinary-result.xml` (Feature tests - GraphBinary) - * `feature-graphbinary-params-result.xml` (Feature tests - GraphBinary parameterized) - * `feature-graphbinary-bulked-result.xml` (Feature tests - GraphBinary bulked) - * `feature-graphson-result.xml` (Feature tests - GraphSON) - * `feature-graphson-params-result.xml` (Feature tests - GraphSON parameterized) - -Feature test XML reports will not be present if the unit/integration tests fail. - -**DO NOT** attempt to investigate a build failure beyond reporting what failed unless asked. - -### 5. Manual Test Execution (Advanced) - -If you must run tests manually outside Maven, follow these steps from the `gremlin-python/src/main/python/` directory. - -#### 5.1 Environment Setup -```bash -python3 -m venv .venv -source .venv/bin/activate -pip install --upgrade pip -pip install .[test,kerberos] -``` - -#### 5.2 Gremlin Server Management - -Manual integration and feature tests require a running Gremlin Server. Run these from `gremlin-python/`: -```bash -# Start/Restart server -docker compose down gremlin-server-test-python -docker compose up -d gremlin-server-test-python - -# Check status (wait for healthy) -docker compose ps gremlin-server-test-python -``` - -#### 5.3 Running Tests Manually -* **Unit Tests**: `pytest tests/unit/` -* **Integration Tests**: `pytest tests/integration/` -* **Feature Tests**: - ```bash - radish -f dots -e -t -b ./tests/radish ../../../../gremlin-test/src/main/resources/org/apache/tinkerpop/gremlin/test/features --user-data='serializer=application/vnd.gremlin-v3.0+json' - ``` \ No newline at end of file diff --git a/pom.xml b/pom.xml index 414fc5efb1..3736a8e47a 100644 --- a/pom.xml +++ b/pom.xml @@ -563,6 +563,8 @@ limitations under the License. <exclude>**/go.sum</exclude> <exclude>**/coverage.out</exclude> <exclude>**/gremlinconsoletest.egg-info/**</exclude> + <!-- SKILL.md requires frontmatter at very start of file so that precludes use of the license header --> + <exclude>**/.skills/**/SKILL.md</exclude> </excludes> <licenses> <license implementation="org.apache.rat.analysis.license.ApacheSoftwareLicense20"/>
