Fix "Reference not found" error when filtering by tags with path-level parameters

[Copilot]

When using parser.filters.tags with orphans: false, operations on paths that define parameters at the path-item level (rather than on individual operations) would crash with Error: Reference not found: #/components/parameters/<name>.

Root cause

Two bugs in the filtering pipeline:

1. buildResourceMetadata only collected transitive dependencies from an operation's own subtree. Path-item–level parameters are siblings of operations in the spec tree, so they were invisible to the orphan analysis and subsequently removed from components.parameters.

2. filterSpec removed a path item only when it was completely empty (!Object.keys(pathItem).length). A path item with all HTTP-method operations filtered out but a parameters key remaining was kept in spec.paths, referencing now-deleted component parameters.

Changes

• packages/shared/src/openApi/shared/graph/meta.ts — when building an operation's dependency set, also traverse #/paths/<path>/parameters (the sibling parameters array) so path-item–level $ref parameters are counted as operation dependencies and survive orphan pruning.

• packages/shared/src/openApi/{2.0.x,3.0.x,3.1.x}/parser/filter.ts — replace the path-item removal guard:

  - if (!Object.keys(pathItem).length) {
  + if (!httpMethods.some((method) => method in pathItem)) {
      delete spec.paths[path];
    }

  This removes path items whenever no HTTP-method operations remain, regardless of other keys (e.g. parameters, summary).

• specs/3.0.x/filter-path-parameters.yaml + test case in 3.0.x.test.ts — reproduces the reported scenario: two tagged resource groups (pets, owners), each with path-item–level $ref parameters, filtered to a single tag with orphans: false.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• fonts.googleapis.com
  • Triggering command: /opt/hostedtoolcache/node/24.14.0/x64/bin/node /opt/hostedtoolcache/node/24.14.0/x64/bin/node /home/REDACTED/work/openapi-ts/openapi-ts/node_modules/.pnpm/next@15.2.4_react-dom@19.0.0_react@19.0.0__react@19.0.0_sass@1.97.1/node_modules/next/dist/compiled/jest-worker/processChild.js clients/@hey-api--noEmit clients/@hey-api/client-nuxt/base-url-string/client/index.ts ode_modules/.bin/../vite/bin/vite.js clients/@hey-api/client-nuxt/base-url-string/client/client.gen.ts clients/@hey-api/client-nuxt/base-url-string/client/types.gen.ts napi-ts/packages/json-schema-ref-parser/node_modules/.bin/node clients/@hey-apinode clients/@hey-api/home/REDACTED/work/openapi-ts/openapi-ts/examples/openapi-ts-next/nod�� clients/@hey-apibuild clients/@hey-api/client-nuxt/clenode16 de/n�� clients/@hey-api/client-nuxt/cle. clients/@hey-api/client-nuxt/clean-false/core/pathSerializer.gen.ts ules/.bin/sh clients/@hey-apigetconf clients/@hey-apiGNU_LIBC_VERSION (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hey-api-docs	Ready	Preview, Comment	Apr 2, 2026 8:42pm

[changeset-bot]

⚠️ No Changeset found

Latest commit: a049e2c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR