[FEATURE] Add `stats` command to display AsyncAPI document metrics

[AviraL0013]

Why do we need this improvement?

Currently, there's no quick way to get an overview of what's inside an AsyncAPI document without manually opening and inspecting it.

Problems this solves:

1. Slower code reviews – Reviewers often need to open and scan large files to understand the scope of changes (e.g., how many channels or messages were added).

2. Limited quick discovery – New contributors must read significant parts of the document to understand the API surface and supported protocols.

3. Manual documentation metrics – Teams often want basic API statistics for READMEs or internal docs, but currently have to extract them manually.

4. Lack of simple complexity tracking – While diffs show what changed, there is no straightforward way to track how the API grows over time using consistent metrics.

5. CI/CD reporting limitations – Pipelines cannot easily extract structured, high-level metrics without custom scripts.

Example scenario:

# Current workflow (painful):
1. Open asyncapi.yaml in editor
2. Scroll through 500+ lines
3. Manually count channels, messages, schemas
4. Check server configurations
5. Look for version info

This becomes especially tedious when working with multiple AsyncAPI files or reviewing PRs.

How will this change help?

Adding a stats command will provide:

1. Instant Document Overview

Get a comprehensive summary in seconds instead of minutes of manual inspection.

2. Faster Code Reviews

Reviewers can quickly see:

• "This PR adds 5 new channels and 12 messages"
• "Schema count increased from 10 to 25"
• Changes in operations (send/receive ratio)

3. Better Documentation

Auto-generate API statistics for README files:

asyncapi stats ./asyncapi.yaml --format markdown >> README.md

4. Quality Insights

Identify issues like:

• Missing descriptions or examples
• Unused schemas
• Channels without servers
• Operations without documentation

5. CI/CD Integration

asyncapi stats ./asyncapi.yaml --format json > metrics.json
# Feed into monitoring dashboards, track API growth

6. Onboarding Experience

New developers get instant understanding:

• What protocols are used (Kafka, MQTT, AMQP)
• How many integration points exist
• Overall API complexity

Real-world impact: Similar to how git status gives quick repo overview, asyncapi stats gives quick API overview.

Screenshots

N/A - This is a CLI command. Will provide example output once implemented.

Expected output example:

 AsyncAPI Document Statistics

 Document Info
  Version: 3.0.0
  Title: Streetlight API
  API Version: 1.0.0

  Servers: 3
  ├─ production (mqtt)
  ├─ development (mqtt)
  └─ test (amqp)

 Channels: 5
 Messages: 12
 Operations: 8 (4 send, 4 receive)
 Schemas: 18
 Security Schemes: 2

 File Stats
  Size: 12.3 KB
  Lines: 450
  Format: YAML

  Quality Checks
  • 3 messages missing examples
  • 2 operations without descriptions

How could it be implemented/designed?

This is a rough implementation outline intended to show feasibility and alignment with the current CLI architecture, not a final design.

Implementation Approach

Tech Stack:

• TypeScript (what the CLI already uses)
• AsyncAPI Parser v3 (already there)
• oclif (CLI framework already in place)

Basic Structure:

src/commands/stats.ts      # The main command
src/core/analyzer.ts       # Extracts the metrics
src/core/formatter.ts      # Formats output

How it works:

async function analyzeDocument(filePath: string) {
  const { document } = await parse(filePath);
  
  const metrics = {
    channels: document.channels().all().length,
    messages: document.messages().all().length,
    operations: document.operations().all().length,
    schemas: document.components().schemas().all().length,
    servers: document.servers().all().length
  };
  
  return formatOutput(metrics, options);
}

No new dependencies needed - everything's already in the CLI.

🚧 Breaking changes

No

👀 Have you checked for similar open issues?

• I checked and didn't find a similar issue

🏢 Have you read the Contributing Guidelines?

• I have read the Contributing Guidelines

Are you willing to work on this issue?

Yes I am willing to submit a PR!

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[AviraL0013]

Hi @Souvikns @Amzani @Shurtu-gal @AayushSaini101 👋
I’ve opened this feature request to propose a small, complementary CLI addition (asyncapi stats) focused on quick discovery and reporting of AsyncAPI documents.

Would appreciate your thoughts on:

whether this fits the CLI’s direction, and

if the scope/approach makes sense from a maintainer perspective.

Happy to iterate based on feedback or adjust the proposal as needed. Thanks!

[AviraL0013]

@Shurtu-gal Hi,
Sorry to tag you again — it would be really helpful if you could review this whenever you get a moment.
Your feedback will help me move it forward.
Thanks a lot!

[Shurtu-gal]

Sorry but how would stats meaningfully boil down diff in asyncapi files?
Also how do we decide what needs to be put out in a markdown file?

[AviraL0013]

@Shurtu-gal Thankyou so much for the response
On diff vs stats:
stats isn’t trying to replace asyncapi diff. Diff already does the right thing at the line/spec level.
What stats adds is a high-level signal about how big or impactful a change is.

When reviewing a PR, I often want to answer things like:
--Did this add new channels?
--Did message count jump a lot?
--Are we introducing new protocols or servers?
--Is the overall surface area growing fast?

For example:

v1: 4 channels, 10 messages
v2: 9 channels, 25 messages

That immediately tells me: this is a much larger change than it looks from a quick skim.
stats just surfaces that structural delta — it doesn’t interpret the spec or judge correctness.

On Markdown output:
The rule I had in mind is simple: only include what you’d reasonably want in a PR description or release notes.
So Markdown stays intentionally small and stable:
--API title & version
--AsyncAPI spec version
--Counts: servers, channels, operations, messages, schemas

Example:

## AsyncAPI Summary

Title: Streetlight API  
Version: 1.0.0

- Servers: 3
- Channels: 5
- Operations: 8 (4 publish, 4 subscribe)
- Messages: 12
- Schemas: 18

Anything more detailed fits better in CLI output or JSON for CI.

[AviraL0013]

@Shurtu-gal Hi sir should I start to work on this?