feat(deprecation): collect deprecated schema element usage

[cuzzlor]

Note

Consumer: MakerXStudio/graphql-apollo-server#157 (draft) wires this collector into Apollo Server via a new includeDeprecatedElements option on graphqlOperationLoggingPlugin.
That PR is blocked on this one: it imports collectDeprecatedElementUsage, so its CI stays red until this merges and publishes 3.3.0. Reviewing the two together shows the full intent — this PR is the mechanism, that one is the usage.

Adds collectDeprecatedElementUsage — a pure, server-agnostic collector that reports every @deprecated schema element an operation uses, so we can tell whether a deprecated element is actually safe to remove.

This is the first half of porting an app-local Apollo plugin into the shared libraries; see the linked consumer PR above for the second half.

Why here rather than in graphql-apollo-server

The collector is pure — (schema, document, operation, variables) -> DeprecatedElementUsage[], no logger, server, or clock — and graphql is already a required peer, so this adds no dependency, peer, or subpath export. Putting it here also means the subscription path gets covered: onOperation already receives everything the collector needs, and subscriptions are invisible to this telemetry otherwise.

What consumers get

• deprecatedElements on the operation log entry, omitted when empty.
• includeDeprecatedElements on useSubscriptionsServer — collected once when the subscription is established, not per emitted payload, since the usage is a property of the operation rather than of each event.

Fixes made during the port

The behaviour is not a straight lift-and-shift. Each of these is pinned by a test that fails against the old behaviour:

• Operation scoping. The AST pass walked the whole document, so a multi-operation request reported elements from operations that never ran — including fragments only those operations could reach. Now scoped with separateOperations. The old code was scrupulous about this for variables and then did the opposite for literals.
• Directive arguments. TypeInfo resolves an argument against the enclosing directive when there is one, so a deprecated directive argument was reported as Query.field(arg) — a field argument that doesn't exist. Now reported as directive-argument / @directive(arg). This also explains the old <unknown> fallbacks, which were papering over the unhandled case.
• Uniform dedupe. Only input fields and enum values deduped, so an aliased document could emit one record per occurrence. All kinds now dedupe on kind + name, and results are sorted for stable, diffable records.
• Bounded work. The walk was depth-capped but unbounded in breadth and result size — a large flat array of input objects is shallow but arbitrarily wide. Adds maxVariableNodes (10,000) and maxElements (50) alongside maxVariableDepth (25).
• path demoted to best-effort. It's fragment-relative for elements inside a fragment definition, which is the common case for clients using generated fragments. Documented as a debugging aid; aggregate on name.
• Deep graphql/utilities and graphql/language/ast imports flattened to the package root, which the dual ESM/CJS build and attw check require.

Testing

148 tests pass. Roughly 400 lines of the original 512-line suite port across as pure-function tests — no Apollo Server boot, no logger spy — using buildSchema + parse, so no @graphql-tools/schema dependency. The fixture-integrity guard comes across too: it stops the suite going vacuous if a fixture loses its @deprecated directive, and confirms buildSchema preserves @deprecated on argument and input-field definitions.

Full npm run build is green, including attw on all four entry points, and I verified collectDeprecatedElementUsage resolves from both the CJS and ESM builds.

Limitations, documented in the README

• Request-side only. It observes values a caller sends, never values the server returns — a deprecated enum value appearing solely in responses reads as unused.
• path is not an aggregation key, per above.

Second commit: audit fixes

CI gates on npm run audit, which had started failing on seven advisories published since main last ran — unrelated to this change. This package declares no runtime dependencies, so every affected path is a devDependency or peer and none reach consumers (fast-uri arrives via better-npm-audit's own tree). npm audit fix cleared all seven within the existing semver ranges, so only the lockfile changes.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a reusable deprecated GraphQL schema element collector for operation telemetry and the linked Apollo Server integration.

Changes:

• Collects and deduplicates deprecated fields, arguments, input fields, and enum values.
• Integrates collection into subscription operation logging.
• Adds tests, documentation, release metadata, and audit dependency updates.

Reviewed changes

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

Show a summary per file

File	Description
src/deprecation.ts	Implements the collector and traversal limits.
src/deprecation.spec.ts	Tests collection, scoping, resilience, and limits.
src/logging.ts	Adds deprecated elements to operation logs.
src/logging.spec.ts	Tests log entry inclusion and omission.
src/subscriptions/server.ts	Exposes subscription collection option.
src/index.ts	Exports the collector API.
README.md	Documents usage and limitations.
package.json	Bumps the package to 3.3.0.
package-lock.json	Updates version and audited dependencies.

---

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

[mderriey]

Wow, great work!