feat: add vendor extensions metric with per-extension counts

.changeset/seven-waves-create.md

@@ -0,0 +1,6 @@
+---
+'@redocly/openapi-core': minor
+'@redocly/cli': minor
+---
+
+Added a Vendor Extensions metric to the `stats` command that reports how many distinct `x-` extensions a description file uses and how often each one occurs.

docs/@v2/commands/stats.md

@@ -21,6 +21,7 @@ The metrics reported depend on the type of API description:
 - Webhooks
 - Operations
 - Tags
+- Vendor Extensions
 
 **AsyncAPI 2.x and AsyncAPI 3.x**
 
@@ -31,6 +32,9 @@ The metrics reported depend on the type of API description:
 - Channels
 - Operations
 - Tags
+- Vendor Extensions
+
+For **Vendor Extensions**, the count is the number of distinct `x-` extensions used, and each extension is listed with how many times it occurs.
 
 If you're interested in the technical details, the statistics are calculated using the counting logic from the `StatsVisitor` module.
 
@@ -123,6 +127,11 @@ Document: museum.yaml stats:
 🎣 Webhooks: 0
 👷 Operations: 8
 🔖 Tags: 3
+🧩 Vendor Extensions: 4
+  - x-badges: 1
+  - x-codeSamples: 2
+  - x-internal: 2
+  - x-metadata: 1
 
 museum.yaml: stats processed in 4ms
 </pre>
@@ -139,6 +148,9 @@ Document: asyncapi.yaml stats:
 📡 Channels: 1
 👷 Operations: 1
 🔖 Tags: 2
+🧩 Vendor Extensions: 2
+  - x-internal: 1
+  - x-metadata: 1
 
 asyncapi.yaml: stats processed in 4ms
 </pre>
@@ -187,6 +199,16 @@ The following is an example JSON output for an OpenAPI description:
   "tags": {
     "metric": "🔖 Tags",
     "total": 3
+  },
+  "xExtensions": {
+    "metric": "🧩 Vendor Extensions",
+    "total": 4,
+    "counts": {
+      "x-badges": 1,
+      "x-codeSamples": 2,
+      "x-internal": 2,
+      "x-metadata": 1
+    }
   }
 }
 </pre>
@@ -214,6 +236,15 @@ The following is an example source output for an OpenAPI description:
 | 🎣 Webhooks | 0 |
 | 👷 Operations | 8 |
 | 🔖 Tags | 3 |
+| 🧩 Vendor Extensions | 4 |
+
+#### 🧩 Vendor Extensions
+| Extension | Count |
+| --- | --- |
+| x-badges | 1 |
+| x-codeSamples | 2 |
+| x-internal | 2 |
+| x-metadata | 1 |
 
 </pre>
 
@@ -230,6 +261,16 @@ Here's the rendered example source output:
 | 🎣 Webhooks           | 0     |
 | 👷 Operations         | 8     |
 | 🔖 Tags               | 3     |
+| 🧩 Vendor Extensions  | 4     |
+
+**🧩 Vendor Extensions**
+
+| Extension     | Count |
+| ------------- | ----- |
+| x-badges      | 1     |
+| x-codeSamples | 2     |
+| x-internal    | 2     |
+| x-metadata    | 1     |
 
 For AsyncAPI descriptions, the table includes a `📡 Channels` row instead of the `🔗 Links`, `🔀 Path Items`, and `🎣 Webhooks` rows.
 

packages/cli/src/commands/stats/index.ts

@@ -7,6 +7,7 @@ import {
   normalizeVisitors,
   walkDocument,
   bundle,
+  ensureSpecExtensionDispatch,
   type WalkContext,
   type OutputFormat,
 } from '@redocly/openapi-core';
@@ -30,6 +31,7 @@ export async function handleStats({ argv, config, collectSpecData }: CommandArgs
   collectSpecData?.(document);
   const specVersion = detectSpec(document.parsed);
   const types = normalizeTypes(config.extendTypes(getTypes(specVersion), specVersion), config);
+  ensureSpecExtensionDispatch(types);
 
   const { statsVisitor, statsAccumulator } = resolveStatsVisitorAndAccumulator(specVersion);
 

packages/cli/src/commands/stats/print-stats/json.ts

@@ -7,11 +7,13 @@ import {
 export function printStatsJson(statsAccumulator: OASStatsAccumulator | AsyncAPIStatsAccumulator) {
   const json: any = {};
   for (const key of Object.keys(statsAccumulator)) {
-    const stat = statsAccumulator[key as keyof typeof statsAccumulator];
-    json[key] = {
-      metric: stat.metric,
-      total: stat.total,
-    };
+    const { metric, total, details } = statsAccumulator[key as keyof typeof statsAccumulator];
+    json[key] = { metric, total };
+    if (details) {
+      json[key].counts = Object.fromEntries(
+        Object.entries(details).map(([name, { count }]) => [name, count])
+      );
+    }
   }
 
   logger.output(JSON.stringify(json, null, 2));

packages/cli/src/commands/stats/print-stats/markdown.ts

@@ -8,10 +8,19 @@ export function printStatsMarkdown(
   statsAccumulator: OASStatsAccumulator | AsyncAPIStatsAccumulator
 ) {
   let output = '| Feature  | Count  |\n| --- | --- |\n';
+  const breakdowns: string[] = [];
   for (const key of Object.keys(statsAccumulator)) {
     const stat = statsAccumulator[key as keyof typeof statsAccumulator];
     output += '| ' + stat.metric + ' | ' + stat.total + ' |\n';
+    const details = Object.entries(stat.details || {});
+    if (details.length) {
+      breakdowns.push(
+        `\n#### ${stat.metric}\n| Extension | Count |\n| --- | --- |\n` +
+          details.map(([name, { count }]) => `| ${name} | ${count} |`).join('\n') +
+          '\n'
+      );
+    }
   }
 
-  logger.output(output);
+  logger.output(output + breakdowns.join(''));
 }

packages/cli/src/commands/stats/print-stats/stylish.ts

@@ -10,8 +10,11 @@ export function printStatsStylish(
 ) {
   for (const node in statsAccumulator) {
     const stat = statsAccumulator[node as keyof typeof statsAccumulator];
-    const { metric, total, color } = stat;
+    const { metric, total, color, details } = stat;
     const colorFn = colors[color as keyof typeof colors] as (text: string) => string;
     logger.output(colorFn(`${metric}: ${total} \n`));
+    for (const [name, { count }] of Object.entries(details || {})) {
+      logger.output(colorFn(`  - ${name}: ${count} \n`));
+    }
   }
 }

packages/cli/src/commands/stats/visitor-and-accumulator-resolver.ts

@@ -20,6 +20,7 @@ export function resolveStatsVisitorAndAccumulator(specVersion: SpecVersion) {
     webhooks: { metric: '🎣 Webhooks', total: 0, color: 'green' },
     operations: { metric: '👷 Operations', total: 0, color: 'yellow' },
     tags: { metric: '🔖 Tags', total: 0, color: 'white', items: new Set() },
+    xExtensions: { metric: '🧩 Vendor Extensions', total: 0, color: 'cyan' },
   };
   const statsAccumulatorAsync: AsyncAPIStatsAccumulator = {
     refs: { metric: '🚗 References', total: 0, color: 'red', items: new Set() },
@@ -29,6 +30,7 @@ export function resolveStatsVisitorAndAccumulator(specVersion: SpecVersion) {
     channels: { metric: '📡 Channels', total: 0, color: 'green' },
     operations: { metric: '👷 Operations', total: 0, color: 'yellow' },
     tags: { metric: '🔖 Tags', total: 0, color: 'white', items: new Set() },
+    xExtensions: { metric: '🧩 Vendor Extensions', total: 0, color: 'cyan' },
   };
 
   let statsVisitor, statsAccumulator;

packages/core/src/index.ts

@@ -26,6 +26,7 @@ export { ConfigTypes, createConfigTypes } from './types/redocly-yaml.js';
 export { createEntityTypes } from './types/entity.js';
 export { normalizeTypes, type NormalizedNodeType, type NodeType } from './types/index.js';
 export { StatsOAS, StatsAsync2, StatsAsync3 } from './rules/other/stats.js';
+export { ensureSpecExtensionDispatch } from './utils/spec-extensions.js';
 export {
   loadConfig,
   loadIgnoreConfig,
@@ -142,4 +143,5 @@ export type {
   OASStatsAccumulator,
   AsyncAPIStatsAccumulator,
   StatsName,
+  SpecVendorExtensionsAccumulator,
 } from './typings/common.js';

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

@@ -1,4 +1,9 @@
-import type { OASStatsAccumulator, AsyncAPIStatsAccumulator } from '../../typings/common.js';
+import type {
+  OASStatsAccumulator,
+  AsyncAPIStatsAccumulator,
+  SpecVendorExtensionsAccumulator,
+  StatsAccumulator,
+} from '../../typings/common.js';
 import type {
   Oas3Link,
   Oas3Operation,
@@ -8,9 +13,34 @@ import type {
   OasRef,
 } from '../../typings/openapi.js';
 import type { Oas2Parameter } from '../../typings/swagger.js';
+import { collectSpecExtension } from '../../utils/spec-extensions.js';
+import type { UserContext } from '../../walk.js';
+
+function finalizeStats(
+  statsAccumulator: StatsAccumulator,
+  extensions: SpecVendorExtensionsAccumulator
+) {
+  for (const row of Object.values(statsAccumulator)) {
+    if (row.items) {
+      row.total = row.items.size;
+    }
+  }
+  const extensionNames = Object.keys(extensions).sort();
+  statsAccumulator.xExtensions.total = extensionNames.length;
+  statsAccumulator.xExtensions.details = Object.fromEntries(
+    extensionNames.map((name) => [name, extensions[name]])
+  );
+}
 
 export const StatsOAS = (statsAccumulator: OASStatsAccumulator) => {
+  const extensions: SpecVendorExtensionsAccumulator = {};
+
   return {
+    SpecExtension: {
+      enter(node: unknown, ctx: UserContext) {
+        collectSpecExtension(extensions, ctx.key.toString(), node);
+      },
+    },
     ExternalDocs: {
       leave() {
         statsAccumulator.externalDocs.total++;
@@ -32,6 +62,11 @@ export const StatsOAS = (statsAccumulator: OASStatsAccumulator) => {
       },
     },
     WebhooksMap: {
+      enter(node: unknown, ctx: UserContext) {
+        if (ctx.key === 'x-webhooks') {
+          collectSpecExtension(extensions, 'x-webhooks', node);
+        }
+      },
       Operation: {
         leave(operation: Oas3Operation) {
           statsAccumulator.webhooks.total++;
@@ -43,6 +78,13 @@ export const StatsOAS = (statsAccumulator: OASStatsAccumulator) => {
         },
       },
     },
+    Operation: {
+      enter(operation: Oas3Operation, ctx: UserContext) {
+        if (ctx.key === 'x-query') {
+          collectSpecExtension(extensions, 'x-query', operation);
+        }
+      },
+    },
     Paths: {
       PathItem: {
         leave() {
@@ -74,17 +116,21 @@ export const StatsOAS = (statsAccumulator: OASStatsAccumulator) => {
     },
     Root: {
       leave() {
-        statsAccumulator.parameters.total = statsAccumulator.parameters.items!.size;
-        statsAccumulator.refs.total = statsAccumulator.refs.items!.size;
-        statsAccumulator.links.total = statsAccumulator.links.items!.size;
-        statsAccumulator.tags.total = statsAccumulator.tags.items!.size;
+        finalizeStats(statsAccumulator, extensions);
       },
     },
   };
 };
 
 export const StatsAsync2 = (statsAccumulator: AsyncAPIStatsAccumulator) => {
+  const extensions: SpecVendorExtensionsAccumulator = {};
+
   return {
+    SpecExtension: {
+      enter(node: unknown, ctx: UserContext) {
+        collectSpecExtension(extensions, ctx.key.toString(), node);
+      },
+    },
     ExternalDocs: {
       leave() {
         statsAccumulator.externalDocs.total++;
@@ -133,16 +179,21 @@ export const StatsAsync2 = (statsAccumulator: AsyncAPIStatsAccumulator) => {
     },
     Root: {
       leave() {
-        statsAccumulator.parameters.total = statsAccumulator.parameters.items!.size;
-        statsAccumulator.refs.total = statsAccumulator.refs.items!.size;
-        statsAccumulator.tags.total = statsAccumulator.tags.items!.size;
+        finalizeStats(statsAccumulator, extensions);
       },
     },
   };
 };
 
 export const StatsAsync3 = (statsAccumulator: AsyncAPIStatsAccumulator) => {
+  const extensions: SpecVendorExtensionsAccumulator = {};
+
   return {
+    SpecExtension: {
+      enter(node: unknown, ctx: UserContext) {
+        collectSpecExtension(extensions, ctx.key.toString(), node);
+      },
+    },
     ExternalDocs: {
       leave() {
         statsAccumulator.externalDocs.total++;
@@ -193,9 +244,7 @@ export const StatsAsync3 = (statsAccumulator: AsyncAPIStatsAccumulator) => {
     },
     Root: {
       leave() {
-        statsAccumulator.parameters.total = statsAccumulator.parameters.items!.size;
-        statsAccumulator.refs.total = statsAccumulator.refs.items!.size;
-        statsAccumulator.tags.total = statsAccumulator.tags.items!.size;
+        finalizeStats(statsAccumulator, extensions);
       },
     },
   };

packages/core/src/typings/common.ts

@@ -3,6 +3,7 @@ export interface StatsRow {
   total: number;
   color: 'red' | 'yellow' | 'green' | 'white' | 'magenta' | 'cyan';
   items?: Set<string>;
+  details?: SpecVendorExtensionsAccumulator;
 }
 
 export type OASStatsName =
@@ -14,7 +15,8 @@ export type OASStatsName =
   | 'links'
   | 'schemas'
   | 'webhooks'
-  | 'parameters';
+  | 'parameters'
+  | 'xExtensions';
 
 export type AsyncAPIStatsName =
   | 'operations'
@@ -23,9 +25,14 @@ export type AsyncAPIStatsName =
   | 'externalDocs'
   | 'channels'
   | 'schemas'
-  | 'parameters';
+  | 'parameters'
+  | 'xExtensions';
 
 export type StatsName = OASStatsName | AsyncAPIStatsName;
 export type OASStatsAccumulator = Record<OASStatsName, StatsRow>;
 export type AsyncAPIStatsAccumulator = Record<AsyncAPIStatsName, StatsRow>;
 export type StatsAccumulator = OASStatsAccumulator | AsyncAPIStatsAccumulator;
+
+// Per `x-` extension: usage count, and a bounded sample of property names → property values.
+export type VendorExtension = { count: number; props: Record<string, Set<string>> };
+export type SpecVendorExtensionsAccumulator = Record<string, VendorExtension>;