feat: add AsyncAPI support in the stats command by tibisabau · Pull Request #2553 · Redocly/redocly-cli

tibisabau · 2026-02-10T15:38:34Z

What/Why/How?

Added AsyncAPI 2.x and 3.x support to the stats command to provide statistics for AsyncAPI documents, similar to existing OpenAPI support. The stats command now counts channels, operations, schemas, references, tags, parameters, and external docs for AsyncAPI specifications.

Why: Since AsyncAPI support was added for lint and bundle commands, the stats command should support it as well for consistency and completeness.

How: Extended the Stats visitor in packages/core/src/rules/other/stats.ts to handle AsyncAPI-specific node types (ChannelMap, NamedChannels, NamedOperations) and map them to appropriate metrics (channels → pathItems, operations → operations).

Reference

Closes #2353.

Testing

Added 3 new E2E test cases covering AsyncAPI 2.x and 3.x stats in stylish and JSON formats
All tests pass successfully with generated snapshots
Verified stats output for both AsyncAPI versions:
- AsyncAPI 2.x: 4 channels, 4 operations, 18 references, 17 schemas, 12 external docs, 11 tags
- AsyncAPI 3.x: 1 channel, 1 operation, 2 references

Screenshots (optional)

N/A

Check yourself

Code changed? - Tested with Redoc/Realm/Reunite (internal)
All new/updated code is covered by tests
New package installed? - Tested in different environments (browser/node)
Documentation update considered

Security

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

changeset-bot · 2026-02-10T15:38:40Z

🦋 Changeset detected

Latest commit: de85bd9

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

This PR includes changesets to release 3 packages

Name	Type
@redocly/openapi-core	Major
@redocly/cli	Major
@redocly/respect-core	Major

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

.changeset/modern-coats-sink.md

DmitryAnansky · 2026-02-13T11:00:54Z

tests/e2e/build-docs/simple-build-docs/pets.yaml

@@ -1 +1 @@
-../../../../resources/pets.yaml
+../../../../resources/pets.yaml


Looks like nothing changed here.

Could you revert this change? It seems it was accidental.

packages/core/src/rules/other/stats.ts

tests/e2e/stats/stats-async3-stylish/snapshot.txt

packages/core/src/rules/other/stats.ts

tests/e2e/stats/stats-async2-json/snapshot.txt

tatomyr · 2026-02-23T13:15:31Z

packages/cli/src/commands/stats.ts


-function printStatsStylish(statsAccumulator: StatsAccumulator) {
+// Determine which stats are relevant for a given spec version
+function isStatRelevant(stat: StatsName, specVersion: SpecVersion): boolean {


The walker should handle this by itself. To get different output for different specs, please use different statsAccumulator presets. (If I get your intention correctly.)

tatomyr · 2026-02-23T14:13:45Z

packages/core/src/rules/other/stats.ts

+  },
+});
+
+export const Stats = (statsAccumulator: StatsAccumulator, specVersion?: SpecVersion) => {


I suggest creating different Stats rules for different specifications/version: SpecOAS, SpecAsync2, SpecAsync3 (for now). This will help to avoid collisions and later on will ease our way when migrating to a more robust solution (ultimately, the stats should use the same approach as lint and bundle, but it requires a bit of a preparation on our side, so I'd go with this PR first, and then we'll implement what's needed on our side).

Chances are, we'll need separate statsAccumulators too to be able to scope the stats we're showing to the spec.

tatomyr · 2026-02-23T14:19:43Z

packages/core/src/rules/other/stats.ts

-        statsAccumulator.externalDocs.total++;
-      },
+// Common visitor for all specs (refs, tags, externalDocs, links)
+const getCommonVisitor = (statsAccumulator: StatsAccumulator) => ({


Please do not use common visitors, just duplicate what's needed. It's better for understanding the actual structure of the data we're trying to get.

tatomyr · 2026-02-23T14:31:54Z

packages/core/src/rules/other/stats.ts

+        // Handle refs in messages array (AsyncAPI 3 specific)
+        // Note: The ref visitor may not catch refs in arrays due to walker limitations,


What is the limitation? If there's any that doesn't allow us to walk here, it should be fixed.

tatomyr

Already much better, thank you! One more push needed though--left a couple of comments.

tatomyr · 2026-02-24T10:09:58Z

packages/cli/src/commands/stats.ts

  parameters: { metric: '👉 Parameters', total: 0, color: 'yellow', items: new Set() },
  links: { metric: '🔗 Links', total: 0, color: 'cyan', items: new Set() },
  pathItems: { metric: '🔀 Path Items', total: 0, color: 'green' },
+  channels: { metric: '📡 Channels', total: 0, color: 'green' },


This is actually the point of the split for the accumulators: let's declare only the specific fields there.

Suggested change

channels: { metric: '📡 Channels', total: 0, color: 'green' },

tatomyr · 2026-02-24T10:10:39Z

packages/cli/src/commands/stats.ts

+  links: { metric: '🔗 Links', total: 0, color: 'cyan', items: new Set() },
+  pathItems: { metric: '🔀 Path Items', total: 0, color: 'green' },


There's no links and pathItems in AsyncAPI (and probably other fields too).

tatomyr · 2026-02-24T10:12:05Z

packages/cli/src/commands/stats.ts

+});
+
+// Stats to show for OpenAPI
+const oasStatsToShow: Set<StatsName> = new Set([


Just put only those things into accumulator objects (and then check if they are defined why formatting the output). This will simplify the code as you won't have to pass statsToShow down to the printStats... functions.

tatomyr · 2026-02-24T10:22:05Z

packages/cli/src/commands/stats.ts

+  const isAsyncAPI = specVersion === 'async2' || specVersion === 'async3';
+  const statsAccumulator = isAsyncAPI
+    ? createAsyncAPIStatsAccumulator()
+    : createOASStatsAccumulator();
+  const statsToShow = isAsyncAPI ? asyncStatsToShow : oasStatsToShow;
+
+  const statsVisitorFn =
+    specVersion === 'async2' ? StatsAsync2 : specVersion === 'async3' ? StatsAsync3 : StatsOAS;


Could this be simplified like so?

Suggested change

const isAsyncAPI = specVersion === 'async2' || specVersion === 'async3';

const statsAccumulator = isAsyncAPI

? createAsyncAPIStatsAccumulator()

: createOASStatsAccumulator();

const statsToShow = isAsyncAPI ? asyncStatsToShow : oasStatsToShow;

const statsVisitorFn =

specVersion === 'async2' ? StatsAsync2 : specVersion === 'async3' ? StatsAsync3 : StatsOAS;

const statsVisitor =

specVersion === 'async2' ? StatsAsync2(statsAccumulatorAsync2) : specVersion === 'async3' ? StatsAsync3(statsAccumulatorAsync3) : StatsOAS(statsAccumulatorOAS);

tatomyr · 2026-02-24T10:23:34Z

packages/core/src/typings/common.ts

  | 'tags'
  | 'externalDocs'
  | 'pathItems'
+  | 'channels'


Can we have separate types for different specs?

tatomyr · 2026-02-24T10:26:30Z

And please rebase your branch against main--there were some changes that might conflict with yours.

Co-authored-by: Dmytro Anansky <dmytro@redocly.com>

…specs

tatomyr · 2026-02-24T13:40:58Z

packages/core/src/rules/other/stats.ts

    ref: {
      enter(ref: OasRef) {
-        statsAccumulator.refs.items!.add(ref['$ref']);
+        statsAccumulator.refs?.items!.add(ref['$ref']);


Why do you need the optional chaining here? There are always items in the refs field unless I'm missing something. Just use the appropriate type. You can even infer the keys from the accumulator objects if needed.

Same for if (statsAccumulator.parameters) { and other precautions.

tatomyr · 2026-02-24T13:42:28Z

packages/core/src/rules/other/stats.ts

-        statsAccumulator.links.items!.add(link.operationId);
-      },
-    },
-    Root: {


Is changing the order really necessary? If not, please revert that so it's easier to read the diffs.

tatomyr · 2026-02-24T14:01:06Z

tests/e2e/build-docs/simple-build-docs/pets.yaml

@@ -1 +1 @@
-../../../../resources/pets.yaml
+../../../../resources/pets.yaml


Could you revert this change? It seems it was accidental.

tatomyr · 2026-02-24T14:07:38Z

tests/e2e/stats/stats-async2-stylish/async.yaml

@@ -0,0 +1,606 @@
+asyncapi: '2.6.0'


Could you clean up test examples (preferably leaving a minimalistic sample) so it's easier to track the actual statistics?

tatomyr · 2026-02-24T14:12:19Z

packages/cli/src/commands/stats.ts

  const json: any = {};
  for (const key of Object.keys(statsAccumulator)) {
+    const stat = statsAccumulator[key as keyof StatsAccumulator];
+    if (!stat) continue;


What could be the case when there's no stat?

packages/cli/src/commands/stats.ts

packages/core/src/rules/other/stats.ts

tatomyr · 2026-02-25T07:41:06Z

The coverage threshold still fails. Please relax it a bit in the config.
Overall looks good to me. Let's wait for the tech writer's approval.

.changeset/modern-coats-sink.md

packages/cli/src/commands/stats.ts

DmitryAnansky

Left a small note regarding the comments in another file.

DmitryAnansky · 2026-02-26T10:03:23Z

@tibisabau
Thank you for your contribution!
The changes will be included in the next release.

tibisabau requested review from a team as code owners February 10, 2026 15:38

DmitryAnansky reviewed Feb 13, 2026

View reviewed changes

.changeset/modern-coats-sink.md Outdated Show resolved Hide resolved

DmitryAnansky reviewed Feb 13, 2026

View reviewed changes

packages/core/src/rules/other/stats.ts Outdated Show resolved Hide resolved

DmitryAnansky reviewed Feb 13, 2026

View reviewed changes

tests/e2e/stats/stats-async3-stylish/snapshot.txt Outdated Show resolved Hide resolved

DmitryAnansky reviewed Feb 13, 2026

View reviewed changes

packages/core/src/rules/other/stats.ts Outdated Show resolved Hide resolved

DmitryAnansky requested changes Feb 13, 2026

View reviewed changes

tibisabau requested a review from DmitryAnansky February 14, 2026 21:28

DmitryAnansky reviewed Feb 16, 2026

View reviewed changes

tests/e2e/stats/stats-async2-json/snapshot.txt Show resolved Hide resolved

tibisabau requested a review from DmitryAnansky February 17, 2026 19:25

tatomyr reviewed Feb 23, 2026

View reviewed changes

tibisabau requested a review from tatomyr February 24, 2026 10:05

tatomyr reviewed Feb 24, 2026

View reviewed changes

tibisabau and others added 6 commits February 24, 2026 13:46

Add AsyncAPI support in the stats command

55f7b01

Update .changeset/modern-coats-sink.md

b82fbfd

Co-authored-by: Dmytro Anansky <dmytro@redocly.com>

Add channels and detectspecs

5c65114

fix: add condition to control whether channels are shown

f089ec3

fix: separate stats per specification

f94cbec

fix: add spec-specific accumulators and separate types for different …

4d9b3f6

…specs

tibisabau force-pushed the feat/add-asyncapi-support-stats branch from c5fcbbf to 4d9b3f6 Compare February 24, 2026 12:54

tibisabau requested a review from tatomyr February 24, 2026 12:55

tatomyr reviewed Feb 24, 2026

View reviewed changes

DmitryAnansky reviewed Feb 24, 2026

View reviewed changes

packages/cli/src/commands/stats.ts Outdated Show resolved Hide resolved

DmitryAnansky reviewed Feb 24, 2026

View reviewed changes

packages/core/src/rules/other/stats.ts Outdated Show resolved Hide resolved

tibisabau changed the title ~~feat: Add AsyncAPI support in the stats command~~ feat: add AsyncAPI support in the stats command Feb 24, 2026

fix: remove unnecessary checks and comments + simplify tests

6127d70

tibisabau requested a review from DmitryAnansky February 24, 2026 19:42

tibisabau requested a review from tatomyr February 24, 2026 19:42

JLekawa reviewed Feb 25, 2026

View reviewed changes

.changeset/modern-coats-sink.md Outdated Show resolved Hide resolved

Apply suggestion from @JLekawa

c31a14c

JLekawa approved these changes Feb 25, 2026

View reviewed changes

DmitryAnansky reviewed Feb 25, 2026

View reviewed changes

packages/cli/src/commands/stats.ts Outdated Show resolved Hide resolved

DmitryAnansky approved these changes Feb 25, 2026

View reviewed changes

tibisabau and others added 2 commits February 25, 2026 17:46

fix: relax coverage metrics and remove unnecessary comments

b000d15

Merge branch 'main' into feat/add-asyncapi-support-stats

de85bd9

DmitryAnansky merged commit 5ab3de9 into Redocly:main Feb 26, 2026
36 checks passed

		@@ -1 +1 @@
		../../../../resources/pets.yaml No newline at end of file
		../../../../resources/pets.yaml

		// Handle refs in messages array (AsyncAPI 3 specific)
		// Note: The ref visitor may not catch refs in arrays due to walker limitations,

		links: { metric: '🔗 Links', total: 0, color: 'cyan', items: new Set() },
		pathItems: { metric: '🔀 Path Items', total: 0, color: 'green' },

Conversation

tibisabau commented Feb 10, 2026

What/Why/How?

Reference

Testing

Screenshots (optional)

Check yourself

Security

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

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!

Uh oh!

tatomyr Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

tatomyr left a comment

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!

tatomyr commented Feb 24, 2026

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!

Uh oh!

tatomyr commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DmitryAnansky left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

DmitryAnansky commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

changeset-bot bot commented Feb 10, 2026 •

edited

Loading

tatomyr Feb 23, 2026 •

edited

Loading

tatomyr commented Feb 25, 2026 •

edited

Loading

DmitryAnansky commented Feb 26, 2026 •

edited

Loading