Cole-Greer commented on code in PR #3380: URL: https://github.com/apache/tinkerpop/pull/3380#discussion_r3054553608
########## .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 Review Comment: ```suggestion mvn clean install -pl :tinkergraph-gremlin mvn clean install -pl :gremlin-core mvn clean install -pl :gremlin-server ``` ########## .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 Review Comment: ```suggestion mvn clean install -pl :gremlin-server -am ``` ########## .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 Review Comment: ```suggestion mvn clean install -pl :gremlin-server -DskipIntegrationTests=false ``` ########## .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 Review Comment: ```suggestion mvn clean install -Pglv-go -pl :gremlin-go ``` ########## .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. Review Comment: ```suggestion - **Go 1.25+** — optional for local development; Docker handles test execution via Maven. ``` ########## .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. Review Comment: ```suggestion - **Node.js 22+** / **npm 10+** — optional; Maven downloads a local copy. ``` ########## .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` Review Comment: ```suggestion - Skips Docker-based integration, unit, and feature tests for `gremlin-javascript` ``` ########## .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 Review Comment: ```suggestion mvn clean install -DtestSeed=<seed-value> ``` ########## .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 Review Comment: ```suggestion mvn clean install -pl :gremlin-dotnet,:gremlin-dotnet-source,:gremlin-dotnet-tests ``` ########## .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 Review Comment: ```suggestion mvn clean install -pl :gremlin-server,:gremlin-console -DdockerImages ``` ########## .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 Review Comment: ```suggestion mvn clean install -pl :gremlin-js -DskipTests ``` ########## 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)" Review Comment: Should we go ahead and proactively exclude these paths from the source-release? ########## .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 Review Comment: This should probably be hadoop 3.4.x, although there are currently additional dependency conflicts with spark and hadoop as I understand it in master, so this will likely need further refinement soon. ########## .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` Review Comment: ```suggestion - Python: `mvn clean install -Pglv-python -pl :gremlin-python` - .NET: `mvn clean install -Pgremlin-dotnet -pl :gremlin-dotnet,:gremlin-dotnet-source,:gremlin-dotnet-tests` - Go: `mvn clean install -Pglv-go -pl :gremlin-go` ``` ########## .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. Review Comment: We may want to be careful instructing agents to commit changes. ########## docs/src/dev/developer/development-environment.asciidoc: ########## @@ -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 Review Comment: ```suggestion By default, this script will run every module in the project. However, if you are planning on working on just a ``` ########## .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 Review Comment: I'm not sure it's advisable to instruct agents how to publish the docs and site. I think this at least warrants additional warnings instructing never to publish unless specifically requested. Also, these publishing scripts likely won't work with agents regardless in their current form as they require the user to enter a password. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
