feat(logging)!: add includeDeprecatedElements to the operation logging plugin

[cuzzlor]

Note

Depends on MakerXStudio/graphql-core#146, now merged and published as @makerx/graphql-core@3.3.0. The lockfile here resolves it from the registry, so CI is green and this is ready to review.

This is the consumer half of porting an app-local deprecation-usage plugin into the shared libraries. graphql-core#146 adds the collector; this PR wires it into Apollo Server.

What it does

includeDeprecatedElements: true adds the @deprecated schema elements an operation used to its existing log entry:

{
  "type": "query",
  "operationName": "GetWidget",
  "oid": "...", "tid": "...", "requestId": "...",
  "deprecatedElements": [
    { "kind": "output-field", "name": "Widget.legacyName", "path": "widget.legacyName" },
    { "kind": "input-field", "name": "WidgetFilterInput.legacyId", "path": "$input.legacyId" }
  ]
}

Why an option here rather than a second plugin

The app version emitted one audit record per element. Folding into the operation entry instead means:

• One log write per request rather than N. The originating app's audit transport uploads one HTTPS request to Azure Monitor per record, so a request touching several deprecated elements multiplied round trips.
• Records inherit request and user metadata from the context logger, so the telemetry answers who is still using an element — the question you actually need answered before deleting a field. The app's module-scoped logger carried none of that.
• shouldIgnore, ignoreIntrospectionQueries, resolveLogger, logLevel and augmentLogEntry all apply for free, instead of being reimplemented or going without.
• No type key collision: type stays the OperationTypeNode and the element kind is kind, nested in the array.

Consumers wanting one record per element can still build that in ~10 lines on the public collector.

Apollo-side behaviour

• Skipped for subsequent payloads of an incremental (@defer/@stream) response — the elements belong to the operation, not each chunk.
• Guarded on ctx.document and ctx.operation, which are absent when a request fails to parse or validate.
• Uses the raw ctx.request.variables. graphql-js coerces into its own values and never writes back to the request object, so the collector's pre-coercion premise holds at willSendResponse.
• Collection failures are caught and reported via the context logger's warn; the operation is still logged, without the key. Telemetry must never turn a served request into a failed one.

Breaking changes (hence 3.0.0)

1. @makerx/graphql-core peer narrows >=1 → >=3.3.0. npm 7+ errors on unsatisfiable peers, so consumers currently resolving 1.x/2.x will fail to install — a breaking change to the install contract regardless of exported signatures. Shipping it as a minor with the peer left at >=1 was the alternative, and it resolves to TypeError: collectDeprecatedElementUsage is not a function at request time, inside the one code path whose whole design goal is never to fail a request.
2. Introspection is detected from ctx.source, not ctx.request.query. An automatic persisted query carries no query on the request once registered, so APQ introspection requests were being logged despite ignoreIntrospectionQueries: true. There is a test that replays a real APQ round trip; it fails against the old detection.

Testing

This repo's first tests — 16 of them — so --pass-with-no-tests is dropped from test:ci. They cover only what the collector's own suite in graphql-core cannot: hook wiring, the deprecatedElements shape, empty-key omission, truncation flagging (from the element cap and from a variable-walk limit), log level routing, resolveLogger precedence, shouldIgnore, introspection skipping (plain and APQ), failure containment, and that a malformed variable still fails on graphql's own coercion message and no other.

vitest.config.ts now inlines @apollo/server alongside graphql-core, so they and the test files share one graphql module instance — graphql-js rejects a GraphQLSchema built in another realm.

graphql-core and graphql are promoted to declared devDependencies; they were previously present only via npm's peer auto-install, so nothing pinned them and check-types relied on an implicit resolution.

Dependency and audit housekeeping

The lockfile now resolves @makerx/graphql-core@3.3.0 from the registry as a declared devDependency, rather than relying on npm's peer auto-install as before.

This also clears the 10 advisories npm run audit gates on, which could not be touched while ^3.3.0 was unresolvable — npm audit fix reconciles package.json against the registry, so it failed outright. Nine went within their existing ranges. The tenth was a low-severity esbuild dev-server file read on Windows, reachable only by bumping the two dev tools that pull esbuild in, so tsx goes to 4.23.12 (its esbuild range moves to ~0.28.0) and vitest to 4.1.10 with @vitest/coverage-v8 kept in lockstep. That leaves one deduped esbuild 0.28.2 and no .nsprc exception to justify later. All dev-only — this package ships rollup output with no runtime dependencies.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds optional deprecated GraphQL schema-element usage to operation logs.

Changes:

• Collects deprecated elements with configurable limits and failure containment.
• Fixes introspection detection for persisted queries.
• Adds tests, documentation, and dependency updates.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/plugins/graphql-operation-logging-plugin.ts	Implements collection and logging.
src/plugins/graphql-operation-logging-plugin.spec.ts	Adds plugin integration tests.
README.md	Documents options and output.
vitest.config.ts	Aligns GraphQL module instances in tests.
package.json	Updates version, dependencies, and test command.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.