feat: add vendor extensions metric with per-extension counts by n0rahh · Pull Request #3021 · Redocly/redocly-cli

n0rahh · 2026-08-05T12:38:25Z

What/Why/How?

Adds a Vendor Extensions metric to the stats command. It reports how many distinct x- extensions a document uses and how many times each one occurs, shown in the stylish, json, and markdown output. Works across OpenAPI and AsyncAPI.

The stats visitors collect extensions through a single SpecExtension entrypoint. Two walker fixes make that possible:

SpecExtension nodes now dedupe by location, so every occurrence is visited — previously occurrences with equal scalar values (e.g. x-internal: true on many operations) were visited only once. This also means visitors and configurable rules targeting SpecExtension now fire per occurrence.
Fixed a pre-existing bug where x- properties with a declared type (e.g. x-codeSamples) were walked twice, which inflated other metrics.

For the stats walk only, ensureSpecExtensionDispatch adjusts the command's normalized types so every x- key dispatches as SpecExtension — including natively-typed extensions and AsyncAPI types that don't declare extensionsPrefix. The structural extensions x-webhooks and x-query keep their declared types so the webhooks/operations/tags metrics still traverse their subtrees; the visitors count those two explicitly. Lint and bundle behavior is unchanged.

The collector also gathers per-extension prop names and value samples for the portal's stats collector (telemetry) via the accumulator — the CLI prints only totals and counts. Samples are bounded (20 props / 20 values per extension), long strings become a <string:N> marker, and credential-like keys and values are masked.

Fixed the stats command always reporting Parameters: 0 for AsyncAPI 2.x and 3.x descriptions. Channel parameters are keyed by name rather than carrying a name property, so none of them were counted.

Reference

Testing

Covered with unit and e2e tests.
Published snapshot and tested cli commands in terminal.

Screenshots (optional)

Check yourself

This PR follows the contributing guide
All new/updated code is covered by tests
Core code changed? - Tested with other Redocly products (internal contributions only)
New package installed? - Tested in different environments (browser/node)
Documentation update has been considered

Security

The security impact of the change has been considered
Code follows company security practices and guidelines

Note

Medium Risk
Walker and resolve dispatch changes affect all lint/stats walks and SpecExtension rule behavior (more visits, fewer duplicates); scope is large but covered by new unit and e2e tests.

Overview
Adds a Vendor Extensions (xExtensions) metric to redocly stats: total distinct x- names plus per-extension occurrence counts, surfaced in stylish, JSON, and Markdown output (including optional counts on each metric row in JSON).

The stats visitors count extensions via SpecExtension enter hooks; AsyncAPI parameter totals now use the channel parameter map key instead of parameter.name, fixing Parameters: 0 on AsyncAPI 2.x/3.x.

Core walker/resolver changes route x- properties to SpecExtension (including when additionalProperties would otherwise match), attach SpecExtension visitors for declared extensions while keeping typed walks where defined, dedupe seen nodes by location for scalars so repeated identical extension values are counted separately, and avoid double-visiting declared extensions like x-codeSamples. AsyncAPI/OAS type trees gain broader extensionsPrefix: 'x-' coverage; Swagger 2 scopes use a dedicated Scopes map so x- keys inside scopes dispatch correctly.

^{Reviewed by Cursor Bugbot for commit 33e26b1. Bugbot is set up for automated code reviews on this repo. Configure here.}

changeset-bot · 2026-08-05T12:38:29Z

🦋 Changeset detected

Latest commit: 33e26b1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@redocly/openapi-core	Minor
@redocly/cli	Minor
@redocly/client-generator	Patch
@redocly/respect-core	Minor

Not sure what this means? Click here to learn what changesets are.

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

github-actions · 2026-08-05T12:41:12Z

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	77.31% (🎯 77%)	11680 / 15107
🔵	Statements	77.4% (🎯 77%)	12502 / 16152
🔵	Functions	81.2% (🎯 81%)	2355 / 2900
🔵	Branches	71% (🎯 71%)	8607 / 12121

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/cli/src/commands/stats/visitor-and-accumulator-resolver.ts	0%	0%	0%	0%	13-57
packages/cli/src/commands/stats/print-stats/json.ts	0%	100%	0%	0%	8-15
packages/cli/src/commands/stats/print-stats/markdown.ts	0%	0%	0%	0%	10-24
packages/cli/src/commands/stats/print-stats/stylish.ts	0%	0%	0%	0%	11-15
packages/core/src/resolve.ts	97.17%	96.5%	100%	97.1%	96, 143, 301, 492-493
packages/core/src/walk.ts	98.3%	96.64%	85%	98.8%	222, 237, 484
packages/core/src/rules/other/stats.ts	5.08%	0%	0%	5.17%	19-34, 38-107, 114-166, 173-227
packages/core/src/types/asyncapi-bindings.ts	95.37%	0%	0%	95.37%	245-246, 257, 268, 283
packages/core/src/types/asyncapi2.ts	85.71%	57.14%	100%	85.71%	580-582, 588, 596-598, 604
packages/core/src/types/asyncapi3.ts	57.14%	15%	25%	57.14%	188-194, 262-270, 500-528
packages/core/src/types/index.ts	97.29%	88.46%	100%	97.29%	140
packages/core/src/types/json-schema-draft7.shared.ts	71.42%	50%	71.42%	71.42%	68, 91-94
packages/core/src/types/oas2.ts	52.23%	21.95%	33.33%	52.23%	173, 176, 179, 209-212, 266-269, 320-332, 390-428
packages/core/src/types/oas3.ts	75.36%	37.5%	66.66%	75.36%	618, 625, 760-763, 823-847
packages/core/src/types/oas3_2.ts	62.5%	14.28%	50%	62.5%	68-155

Generated in workflow #11305 for commit 33e26b1 by the Vitest Coverage Report Action

github-actions · 2026-08-05T12:41:30Z

Performance Benchmark (Lower is Faster)

CLI Version	Bundle	Lint	Check Config
cli-latest	▓ 1.00x (Fastest)	▓ 1.00x (Fastest)	▓ 1.00x ± 0.01
cli-next	▓ 1.01x ± 0.01	▓ 1.00x ± 0.01	▓ 1.00x (Fastest)

github-actions · 2026-08-05T12:54:44Z

📦 A new experimental 🧪 version v0.0.0-snapshot.1785934483 of Redocly CLI has been published for testing.

Install with NPM:

npm install @redocly/cli@0.0.0-snapshot.1785934483

⚠️ Note: This is a development build and may contain unstable features.

… to $ref and ignore map keys starting with x-

…sions

github-actions · 2026-08-07T10:49:46Z

📦 A new experimental 🧪 version v0.0.0-snapshot.1786099785 of Redocly CLI has been published for testing.

Install with NPM:

npm install @redocly/cli@0.0.0-snapshot.1786099785

⚠️ Note: This is a development build and may contain unstable features.

adamaltman · 2026-08-08T21:04:37Z

I found things I didn't know existed in there. Thank you.

Document: ./website/api-definitions/openapi/openapi.yaml stats:

🚗 References: 972
📦 External Documents: 0
📈 Schemas: 838
👉 Parameters: 61
🔗 Links: 0
🔀 Path Items: 382
🎣 Webhooks: 148
👷 Operations: 613
🔖 Tags: 88
🧩 Vendor Extensions: 16
  - x-badges: 151
  - x-basic: 92
  - x-codeSamples: 261
  - x-currency-field: 16
  - x-enumDescriptions: 79
  - x-is-free-form: 1
  - x-label: 26
  - x-logo: 1
  - x-multiline: 31
  - x-products: 761
  - x-sdk-operation-name: 613
  - x-sdk-resource: 43
  - x-sdk-skip: 5
  - x-sortable: 155
  - x-tagGroups: 1
  - x-type: 138

./website/api-definitions/openapi/openapi.yaml: stats processed in 143ms

…2.x and 3.x

tatomyr · 2026-08-11T08:01:23Z


      currentLocation = resolvedLocation;
-      const isNodeSeen = seenNodesPerType[type.name]?.has?.(resolvedNode);
+      const seenKey = type === SpecExtension ? location.absolutePointer : resolvedNode;


What is this change for?

SpecExtension nodes are often equal scalars (true, "internal"), and deduping them by node value made the walker visit only the first occurrence document-wide — deduping by location visits every occurrence exactly once (while a $ref-shared extension still counts once), which the stats need to count extensions correctly.

There are plenty of other scalar nodes. It looks like you've found a but that has to be fixed instead of masking.

tatomyr · 2026-08-11T09:21:19Z

+export function ensureSpecExtensionDispatch(types: Record<string, NormalizedNodeType>) {
+  for (const type of Object.values(types)) {
+    if (type === SpecExtension) continue;
+    type.extensionsPrefix ??= EXTENSION_PREFIX;


Not sure this is still needed after using the SpecExtension visitor.

It is needed: the walker only dispatches an x- key to SpecExtension when the type declares extensionsPrefix, and most AsyncAPI types (everything except SecurityScheme) plus Paths in OAS never declare it. Removing this line drops the AsyncAPI fixture's extension count — only the additionalProperties: {} path survives.

Adding extensionsPrefix to the AsyncAPI type definitions themselves would make extension values walked (and their $refs bundled/linted) for every consumer, which is a behavior change beyond stats — could be a follow-up if we want it.

So we can modify types to declare the extensions where needed. The purpose of having right visitors tree is exactly to avoid manipulations like this.

tatomyr · 2026-08-11T09:34:16Z

+    }
+  }
+  const extensionNames = Object.keys(extensions).sort();
+  statsAccumulator.xExtensions.total = extensionNames.length;


Why not use the same approach with Set like in other rows?

Moreover, maybe we can simply calculate the items' size in place instead of assigning the total?

On Set question already answered above.

Four consumers (three printers and the portal collector) read .total uniformly for every row, so deriving the size at read time would push an items ? items.size : total check into each of them. This one-time assignment at Root.leave also predates the PR — the loop just replaces the four per-row copies that main already had.

tatomyr · 2026-08-11T09:51:33Z

+    const entryType = type.additionalProperties;
+    // An untyped catch-all (`additionalProperties: {}`) swallows x- keys before the extensions fallback.
+    if (isPlainObject(entryType) && !isNamedType(entryType) && entryType.type === undefined) {
+      type.additionalProperties = (_value, key: string) =>


I don't think it's a good idea to modify types. What are you're trying to achieve?

This modifies only the stats command's own copy of the types — lint keeps the original ones where the declarations matter for validation. Without it, typed extensions (x-codeSamples, x-logo) and most AsyncAPI nodes never reach the SpecExtension visitor, since the walker dispatches them to their declared types instead. The only alternative is going back to key-scanning in the any hook — the approach you wanted to replace with SpecExtension

Then we have wrong types or wrong walker logic. Making different types for different commands makes no sense to me.

Agree, most of this can be fixed at the source instead of remapping types per command

Declare extensionsPrefix: 'x-' in the type definitions where the specs allow extensions

In the walker, check extensionsPrefix before falling back to additionalProperties

@tatomyr wdyt?

Agree. I believe it makes sense to do that in this PR as it directly touches the spec extensions functionality and it'd be easier to spot uncovered places.

vadyvas · 2026-08-11T12:33:40Z


      currentLocation = resolvedLocation;
-      const isNodeSeen = seenNodesPerType[type.name]?.has?.(resolvedNode);
+      const seenKey = type === SpecExtension ? location.absolutePointer : resolvedNode;


@n0rahh
why scope the fix to SpecExtension only? can other primitive nodes hit the same problem?
If they can, using resolvedLocation.absolutePointer as a key instead of checking type === SpecExtension would cover them all in one place

Only SpecExtension holds arbitrary user data, so equal scalar values like true are its normal case — other node types hold objects, which never collide as keys. Using the location as the key for all types isn't safe either: a YAML anchor puts the same object in many places, and every rule would then visit and report it once per place instead of once

…ions and updating counts

vadyvas · 2026-08-13T07:02:58Z

+  }
+}
+
+export function collectSpecExtension(


Nothing in this repo reads props, the printers only use count, and CLI telemetry never sends it

So could the sampling (props, describe, these regexes) move to the portal collector instead?

…tion

cursor

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 33e26b1. Configure here.}

github-actions · 2026-08-13T13:00:05Z

📦 A new experimental 🧪 version v0.0.0-snapshot.1786626004 of Redocly CLI has been published for testing.

Install with NPM:

npm install @redocly/cli@0.0.0-snapshot.1786626004

⚠️ Note: This is a development build and may contain unstable features.

n0rahh added 7 commits August 5, 2026 13:25

feat: add support for vendor extensions in stats reporting

974233d

chore: update stats documentation to include Vendor Extensions metrics

9a79e40

chore: update snapshots

b957cfe

tests: add e2e tests

304374f

tests: add unit tests

5af764e

chore: update snapshot to include Vendor Extensions in stats

d8f062b

feat: add Vendor Extensions metric to stats command

3f2b9f8

n0rahh added the snapshot Create experimental release PR label Aug 5, 2026

n0rahh marked this pull request as ready for review August 5, 2026 13:45

n0rahh requested review from a team as code owners August 5, 2026 13:45

cursor Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread packages/core/src/rules/other/spec-extensions.ts Outdated

Comment thread packages/core/src/rules/other/spec-extensions.ts Outdated

feat: enhance StatsSpecExtensions to correctly handle extensions next…

2efddb1

… to $ref and ignore map keys starting with x-

cursor Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread packages/core/src/rules/other/spec-extensions.ts Outdated

JLekawa reviewed Aug 5, 2026

View reviewed changes

Comment thread .changeset/seven-waves-create.md Outdated

Update .changeset/seven-waves-create.md

c2439e9

JLekawa approved these changes Aug 5, 2026

View reviewed changes

n0rahh added 2 commits August 5, 2026 16:32

feat: add support for counting map-typed extensions in StatsSpecExten…

05fbcdf

…sions

feat: add masking for sensitive values in StatsSpecExtensions

15e669c

cursor Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread packages/core/src/rules/other/spec-extensions.ts Outdated

feat: add authorization key to be masked in StatsSpecExtensions tests

c99afa0

DmitryAnansky reviewed Aug 6, 2026

View reviewed changes

Comment thread packages/core/src/rules/other/spec-extensions.ts Outdated

n0rahh and others added 2 commits August 6, 2026 12:01

chore: refactor after cr

3bb9922

Merge branch 'main' into feat/stats-for-vendor-extensions

d327074

n0rahh added snapshot Create experimental release PR and removed snapshot Create experimental release PR labels Aug 6, 2026

n0rahh added snapshot Create experimental release PR and removed snapshot Create experimental release PR labels Aug 7, 2026

n0rahh requested a review from tatomyr August 7, 2026 10:49

RomanHotsiy reviewed Aug 10, 2026

View reviewed changes

Comment thread docs/@v2/commands/stats.md Outdated

feat: standardize indentation for vendor extensions in stats output

280804f

n0rahh requested a review from RomanHotsiy August 10, 2026 07:17

feat: fix stats command to accurately report parameters for AsyncAPI …

ef28db3

…2.x and 3.x

tatomyr reviewed Aug 11, 2026

View reviewed changes

vadyvas reviewed Aug 11, 2026

View reviewed changes

n0rahh added 2 commits August 11, 2026 14:46

feat: enhance stats output for vendor extensions by adding new extens…

bbedead

…ions and updating counts

chore: update changeset

66b983c

n0rahh requested review from tatomyr and vadyvas August 11, 2026 13:21

n0rahh and others added 2 commits August 12, 2026 14:44

Merge branch 'main' into feat/stats-for-vendor-extensions

9ef37bd

feat: add tests for ensureSpecExtensionDispatch functionality

141c77c

vadyvas reviewed Aug 13, 2026

View reviewed changes

n0rahh marked this pull request as draft August 13, 2026 08:05

chore: enhance vendor extension handling and statistics collection

c97e6fb

cursor Bot reviewed Aug 13, 2026

View reviewed changes

Comment thread packages/core/src/walk.ts

Comment thread packages/core/src/walk.ts

feat: enhance spec extension handling in walkDocument function

34f0c03

cursor Bot reviewed Aug 13, 2026

View reviewed changes

Comment thread packages/core/src/walk.ts

feat: enhance SpecExtension lifecycle handling in tests and walk func…

33e26b1

…tion

cursor Bot reviewed Aug 13, 2026

View reviewed changes

n0rahh added snapshot Create experimental release PR and removed snapshot Create experimental release PR labels Aug 13, 2026

n0rahh requested a review from vadyvas August 13, 2026 12:59

n0rahh marked this pull request as ready for review August 13, 2026 12:59

Uh oh!

Conversation

n0rahh commented Aug 5, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What/Why/How?

Reference

Testing

Screenshots (optional)

Check yourself

Security

Uh oh!

changeset-bot Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report

Uh oh!

github-actions Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Performance Benchmark (Lower is Faster)

Uh oh!

github-actions Bot commented Aug 5, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Aug 7, 2026

Uh oh!

adamaltman commented Aug 8, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

n0rahh commented Aug 5, 2026 •

edited by cursor Bot

Loading

changeset-bot Bot commented Aug 5, 2026 •

edited

Loading

github-actions Bot commented Aug 5, 2026 •

edited

Loading

github-actions Bot commented Aug 5, 2026 •

edited

Loading