spmallette commented on code in PR #3341: URL: https://github.com/apache/tinkerpop/pull/3341#discussion_r2987837194
########## gremlin-js/gremlin-javascript/AGENTS.md: ########## @@ -0,0 +1,138 @@ +### 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 Review Comment: just pushed a fix for that. -- 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]
