chore: benchmark the downgraders with CodSpeed

.github/workflows/codspeed.yaml

@@ -0,0 +1,29 @@
+name: CodSpeed
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  # `workflow_dispatch` allows CodSpeed to trigger backtest
+  # performance analysis in order to generate initial data.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  benchmarks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: pnpm/action-setup@v6
+
+      - run: pnpm i
+
+      - uses: CodSpeedHQ/action@v4
+        with:
+          mode: simulation
+          run: pnpm run bench

README.md

@@ -7,6 +7,9 @@
   <a href="https://www.npmjs.com/package/@openapi-spec/types">
     <img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40openapi-spec%2Ftypes?logo=npm" />
   </a>
+  <a href="https://app.codspeed.io/middleapi/openapi-spec?utm_source=badge">
+    <img src="https://img.shields.io/endpoint?url=https://codspeed.io/badge.json" alt="CodSpeed" />
+  </a>
   <a href="https://github.com/middleapi/openapi-spec/blob/main/LICENSE">
     <img alt="MIT License" src="https://img.shields.io/github/license/middleapi/openapi-spec?logo=open-source-initiative" />
   </a>
@@ -32,6 +35,7 @@ pnpm install
 pnpm test
 pnpm lint
 pnpm type:check
+pnpm bench
 ```
 
 ## Sponsors

package.json

@@ -8,13 +8,15 @@
     "type:check": "pnpm run -r type:check && tsc",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "bench": "vitest bench --run",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
     "repo:fix": "sherif --fix",
     "sync:sponsors": "node scripts/sync-sponsors.ts && eslint --fix '**/README.md'"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^9.5.1",
+    "@codspeed/vitest-plugin": "^5.7.1",
     "@seriousme/openapi-schema-validator": "^2.9.1",
     "@types/node": "^26.4.0",
     "@vitest/coverage-v8": "^4.1.11",

packages/downgrader/README.md

@@ -7,6 +7,9 @@
   <a href="https://www.npmjs.com/package/@openapi-spec/downgrader">
     <img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40openapi-spec%2Fdowngrader?logo=npm" />
   </a>
+  <a href="https://app.codspeed.io/middleapi/openapi-spec?utm_source=badge">
+    <img src="https://img.shields.io/endpoint?url=https://codspeed.io/badge.json" alt="CodSpeed" />
+  </a>
   <a href="https://github.com/middleapi/openapi-spec/blob/main/LICENSE">
     <img alt="MIT License" src="https://img.shields.io/github/license/middleapi/openapi-spec?logo=open-source-initiative" />
   </a>
@@ -247,6 +250,12 @@ A schema is _loosened_ when the conversion removes a restriction from it or a su
 - A schema without `type` that has `contentEncoding: base64`, or `contentMediaType` without `contentEncoding`, gains `type: string`, so non-string values the original accepts are rejected.
 - Non-standard keywords are kept, although the official 3.0 schema forbids them.
 
+## Performance
+
+An object reached through many `$ref`s or shared references is converted once and reused, so the work grows with the size of the document, not with the number of paths through its references, even where they form cycles.
+
+[Benchmarks](https://github.com/middleapi/openapi-spec/tree/main/packages/downgrader/benches) cover each converter on the official example documents, generated APIs, and worst-case reference graphs. [CodSpeed](https://app.codspeed.io/middleapi/openapi-spec) runs them on every pull request to catch regressions.
+
 ## Sponsors
 
 Like what we build over at [middleapi](https://github.com/middleapi)? You can help keep it going through [GitHub Sponsors](https://github.com/sponsors/dinwwwh) or [Open Collective](https://opencollective.com/middleapi). Every bit helps! 🚀