camunda-schema-bundler 2.4.6 → 2.4.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -109,6 +109,7 @@ camunda-schema-bundler --version
109
109
  | `--deref-path-local` | Inline remaining path-local `$ref`s (needed for Microsoft.OpenApi) |
110
110
  | `--allow-like-refs` | Don't fail on surviving path-local `$like` refs |
111
111
  | `--allow-param-refs` | Don't fail on surviving path-local `$ref`s inside `parameters` arrays |
112
+ | `--allow-response-refs` | Don't fail on surviving path-local `$ref`s used as `responses` map values |
112
113
  | `--allow-interior-refs` | Don't fail on `$ref`s that point inside a component schema (e.g. `#/components/schemas/Foo/allOf/0`) and cannot be retargeted to a named component |
113
114
  | **General** | |
114
115
  | `--help`, `-h` | Show help |
@@ -195,6 +196,8 @@ import {
195
196
  findPathLocalLikeRefs, // Find surviving path-local $like refs in a spec
196
197
  findPathLocalParameterRefs, // Find surviving path-local $refs in parameters arrays
197
198
  forEachParameterArray, // Visit every path-item / operation `parameters` array
199
+ findPathLocalResponseRefs, // Find surviving path-local $refs in responses maps
200
+ forEachResponsesMap, // Visit every operation `responses` map
198
201
  } from 'camunda-schema-bundler';
199
202
  ```
200
203
 
@@ -214,9 +217,10 @@ import {
214
217
  7. **Retarget interior refs** — Rewrite `$ref`s that point inside a component schema (e.g. `#/components/schemas/AuthenticatedCamundaUserResult/allOf/0`) to the named component they resolve to. `SwaggerParser.bundle()` emits these when a schema is first met nested inside another component; once fresh dedup turns the nested copy into a component ref, they are refs to refs that generators cannot follow. Fail-fast if any cannot be retargeted (configurable with `--allow-interior-refs`)
215
218
  8. **Rewrite** — Decode URI-encoded internal refs (`%24like` → `$like`)
216
219
  9. **Inline parameter refs** — Always inline path-local `$ref`s that survive inside `parameters` arrays. `SwaggerParser.bundle()` drops `components.parameters` entirely and dedupes the resulting identical parameter objects into `#/paths/...` refs, which step 4 cannot rewrite because there is no surviving component to point at. Generators cannot resolve them (openapi-generator aborts with "There are duplicate parameter values"), and parameters are never emitted as named types, so inlining is lossless. Fail-fast if any survive (configurable with `--allow-param-refs`)
217
- 10. **Validate** — Fail-fast if any path-local `$like` refs survive (configurable with `--allow-like-refs`)
218
- 11. **Dereference** (optional, `--deref-path-local`) — Inline remaining path-local `$ref`s for strict generators
219
- 12. **Extract metadata** — Build the intermediate representation (semantic keys, unions, operations, etc.)
220
+ 10. **Inline response refs** — Same for path-local `$ref`s used as `responses` map values: `components.responses` does not survive bundling either, so every reuse of a shared response (e.g. `401`/`500` error responses) becomes a `#/paths/.../responses/<status>` ref. Consumers that only resolve `#/components/...` pointers drop these. Response Objects are never emitted as named types (the schemas inside them keep their component refs), so inlining is lossless. Only targets that are Response Objects are inlined; fail-fast if any survive (configurable with `--allow-response-refs`)
221
+ 11. **Validate** — Fail-fast if any path-local `$like` refs survive (configurable with `--allow-like-refs`)
222
+ 12. **Dereference** (optional, `--deref-path-local`) — Inline remaining path-local `$ref`s for strict generators
223
+ 13. **Extract metadata** — Build the intermediate representation (semantic keys, unions, operations, etc.)
220
224
 
221
225
  ## Metadata IR
222
226
 
package/dist/bundle.d.ts CHANGED
@@ -1,4 +1,15 @@
1
1
  import type { BundleOptions, BundleResult } from './types.js';
2
+ /**
3
+ * Collapse `$ref`s that point into a component subtree (see Step 4d).
4
+ * Rewrites in place and returns the number of collapsed refs plus the refs
5
+ * that survive: subtree refs that do not resolve, through bare `$ref` hops,
6
+ * to an existing named top-level component. The caller decides whether
7
+ * survivors are fatal (see `allowComponentInteriorRefs`).
8
+ */
9
+ export declare function collapseComponentSubtreeRefs(doc: Record<string, unknown>): {
10
+ collapsed: number;
11
+ survivors: string[];
12
+ };
2
13
  /**
3
14
  * Bundle the multi-file OpenAPI spec into a single normalized JSON document.
4
15
  */
@@ -1 +1 @@
1
- {"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAe,MAAM,YAAY,CAAC;AA2qB3E;;GAEG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAinB1E"}
1
+ {"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAe,MAAM,YAAY,CAAC;AA2qB3E;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB,CAsIA;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA41B1E"}
package/dist/bundle.js CHANGED
@@ -8,7 +8,7 @@ import fs from 'node:fs';
8
8
  import path from 'node:path';
9
9
  import SwaggerParser from '@apidevtools/swagger-parser';
10
10
  import { parse as parseYaml } from 'yaml';
11
- import { listFilesRecursive, hashDirectoryTree, normalizeInternalRef, rewriteInternalRefs, rewriteExternalRefsToLocal, resolveInternalRef, canonicalStringify, structuralStringify, findPathLocalLikeRefs, forEachParameterArray, findPathLocalParameterRefs, sortRequiredArrays, collapseComponentInteriorRefs, } from './helpers.js';
11
+ import { listFilesRecursive, hashDirectoryTree, normalizeInternalRef, rewriteInternalRefs, rewriteExternalRefsToLocal, resolveInternalRef, resolveTerminalRef, canonicalStringify, structuralStringify, findPathLocalLikeRefs, forEachParameterArray, findPathLocalParameterRefs, forEachResponsesMap, findPathLocalResponseRefs, sortRequiredArrays, collapseComponentInteriorRefs, } from './helpers.js';
12
12
  import { extractMetadata } from './metadata.js';
13
13
  /**
14
14
  * Promote inline schemas inside component-level `oneOf`/`anyOf` compositions
@@ -572,6 +572,138 @@ function isMonolithicEntryFile(entryPath) {
572
572
  return false;
573
573
  }
574
574
  }
575
+ /**
576
+ * Collapse `$ref`s that point into a component subtree (see Step 4d).
577
+ * Rewrites in place and returns the number of collapsed refs plus the refs
578
+ * that survive: subtree refs that do not resolve, through bare `$ref` hops,
579
+ * to an existing named top-level component. The caller decides whether
580
+ * survivors are fatal (see `allowComponentInteriorRefs`).
581
+ */
582
+ export function collapseComponentSubtreeRefs(doc) {
583
+ let collapsed = 0;
584
+ const isComponentSubtreeRef = (ref) => /^#\/components\/[^/]+\/[^/]+\/./.test(ref);
585
+ const bareRefTarget = (ref) => {
586
+ const target = resolveInternalRef(doc, ref);
587
+ if (!target || typeof target !== 'object' || Array.isArray(target))
588
+ return undefined;
589
+ const keys = Object.keys(target);
590
+ const next = target['$ref'];
591
+ return keys.length === 1 && typeof next === 'string' ? next : undefined;
592
+ };
593
+ // Keys whose values are literal payloads (data, not OpenAPI/schema
594
+ // positions): a `$ref` property inside them is data and must not be touched.
595
+ const LITERAL_KEYS = new Set(['example', 'default', 'enum', 'const']);
596
+ const isLiteralKey = (k) => LITERAL_KEYS.has(k) || k.startsWith('x-');
597
+ const survivors = [];
598
+ const seen = new Set();
599
+ // Keys (in `node` context) whose value is a map of user-chosen names.
600
+ const NAME_MAP_KEYS = new Set([
601
+ 'properties',
602
+ 'patternProperties',
603
+ '$defs',
604
+ 'definitions',
605
+ 'dependentSchemas',
606
+ 'content',
607
+ 'headers',
608
+ 'encoding',
609
+ ]);
610
+ // Keys whose value is a name map that also admits `x-*` extensions.
611
+ const NAME_MAP_EXT_KEYS = new Set(['responses', 'paths', 'webhooks', 'callbacks']);
612
+ const childCtx = (k, v) => {
613
+ if (k === 'examples')
614
+ return Array.isArray(v) ? undefined : 'exampleMap';
615
+ if (k === 'links')
616
+ return 'linkMap';
617
+ if (NAME_MAP_KEYS.has(k))
618
+ return 'nameMap';
619
+ if (NAME_MAP_EXT_KEYS.has(k))
620
+ return 'nameMapExt';
621
+ return 'node';
622
+ };
623
+ const stack = [
624
+ { node: doc, ctx: 'node' },
625
+ ];
626
+ while (stack.length) {
627
+ const { node, ctx } = stack.pop();
628
+ if (!node || typeof node !== 'object' || seen.has(node))
629
+ continue;
630
+ seen.add(node);
631
+ if (Array.isArray(node)) {
632
+ for (const v of node)
633
+ stack.push({ node: v, ctx: 'node' });
634
+ continue;
635
+ }
636
+ const obj = node;
637
+ if (ctx === 'nameMap' || ctx === 'nameMapExt' || ctx === 'exampleMap' || ctx === 'linkMap') {
638
+ const entryCtx = ctx === 'exampleMap' ? 'exampleObject' : ctx === 'linkMap' ? 'linkObject' : 'node';
639
+ for (const [k, v] of Object.entries(obj)) {
640
+ if (ctx === 'nameMapExt' && k.startsWith('x-'))
641
+ continue;
642
+ stack.push({ node: v, ctx: entryCtx });
643
+ }
644
+ continue;
645
+ }
646
+ const ref = obj['$ref'];
647
+ if (typeof ref === 'string' && isComponentSubtreeRef(ref)) {
648
+ let resolved = ref;
649
+ const chain = new Set();
650
+ // Follow bare internal refs (including path-local intermediaries such
651
+ // as `#/paths/...`) until a named top-level component is reached, or
652
+ // the chain hits a non-bare/missing target or a cycle.
653
+ const isNamedComponentRef = (r) => /^#\/components\/[^/]+\/[^/]+$/.test(r);
654
+ while (resolved.startsWith('#/') && !isNamedComponentRef(resolved)) {
655
+ if (chain.has(resolved))
656
+ break;
657
+ chain.add(resolved);
658
+ const next = bareRefTarget(resolved);
659
+ if (next === undefined)
660
+ break;
661
+ resolved = next;
662
+ }
663
+ // Accept only a ref to an existing, named top-level component.
664
+ // Leaving the subtree pattern is not enough: the chain could end
665
+ // at e.g. an unnamed `#/paths/...` schema.
666
+ const named = /^#\/components\/([^/]+)\/([^/]+)$/.exec(resolved);
667
+ const components = doc.components;
668
+ const namedTargetExists = named !== null &&
669
+ components?.[named[1]] !== undefined &&
670
+ Object.prototype.hasOwnProperty.call(components[named[1]], named[2].replace(/~1/g, '/').replace(/~0/g, '~'));
671
+ if (!namedTargetExists) {
672
+ survivors.push(ref);
673
+ }
674
+ else {
675
+ obj['$ref'] = resolved;
676
+ collapsed++;
677
+ }
678
+ }
679
+ for (const [k, v] of Object.entries(obj)) {
680
+ if (k === '$ref' || isLiteralKey(k))
681
+ continue;
682
+ if (ctx === 'exampleObject' && k === 'value')
683
+ continue;
684
+ if (ctx === 'linkObject' && (k === 'requestBody' || k === 'parameters'))
685
+ continue;
686
+ if (obj === doc && k === 'components' && v && typeof v === 'object') {
687
+ // Each component type map holds user-named components (any name,
688
+ // including `default` / `x-data`); `x-*` on `components` itself is data.
689
+ for (const [type, map] of Object.entries(v)) {
690
+ if (type.startsWith('x-'))
691
+ continue;
692
+ const mapCtx = type === 'examples' ? 'exampleMap' : type === 'links' ? 'linkMap' : 'nameMap';
693
+ stack.push({ node: map, ctx: mapCtx });
694
+ }
695
+ continue;
696
+ }
697
+ const c = childCtx(k, v);
698
+ if (c !== undefined)
699
+ stack.push({ node: v, ctx: c });
700
+ }
701
+ }
702
+ if (survivors.length > 0) {
703
+ return { collapsed, survivors: [...new Set(survivors)].sort() };
704
+ }
705
+ return { collapsed, survivors: [] };
706
+ }
575
707
  /**
576
708
  * Bundle the multi-file OpenAPI spec into a single normalized JSON document.
577
709
  */
@@ -594,7 +726,9 @@ export async function bundle(options) {
594
726
  ambiguousInlineCount: 0,
595
727
  dereferencedPathLocalRefCount: 0,
596
728
  pathLocalLikeRefCount: 0,
729
+ componentSubtreeRefsCollapsed: 0,
597
730
  inlinedPathLocalParameterCount: 0,
731
+ inlinedPathLocalResponseCount: 0,
598
732
  collapsedComponentInteriorRefCount: 0,
599
733
  componentInteriorRefCount: 0,
600
734
  };
@@ -874,6 +1008,17 @@ export async function bundle(options) {
874
1008
  const p = node;
875
1009
  return typeof p['name'] === 'string' && typeof p['in'] === 'string';
876
1010
  };
1011
+ // A parameter target must live in a `parameters` position
1012
+ // (`#/paths/<path>/<method>/parameters/<i>`, Path-Item-level
1013
+ // `#/paths/<path>/parameters/<i>`, or `#/components/parameters/<name>`).
1014
+ // `<path>` must be an API path (a `/`-prefixed key, JSON-pointer-encoded
1015
+ // as `~1`); any other key under `paths` is an `x-*` extension. This is
1016
+ // the same context distinction Step 3e applies to responses. The method segment must be a real HTTP method:
1017
+ // `x-*` extensions are arbitrary data, and a pointer that merely ENDS in
1018
+ // `/parameters/<i>` (e.g. into an example payload) is not a parameters
1019
+ // position either.
1020
+ const PARAMETER_TARGET_REF = /^#\/(?:components\/parameters\/[^/]+|paths\/~1[^/]*(?:\/(?:get|put|post|delete|options|head|patch|trace))?\/parameters\/\d+)$/;
1021
+ const isParameterTargetRef = (ref) => PARAMETER_TARGET_REF.test(ref);
877
1022
  for (let pass = 1; pass <= 20; pass++) {
878
1023
  let inlined = 0;
879
1024
  forEachParameterArray(bundled, (params) => {
@@ -884,15 +1029,37 @@ export async function bundle(options) {
884
1029
  const ref = param['$ref'];
885
1030
  // Prefer the post-normalization source (normalized $like refs,
886
1031
  // promoted schemas); fall back to pre-normalization if the path was
887
- // removed during normalization.
888
- const resolved = resolveInternalRef(postNormSnapshot, ref) ??
889
- resolveInternalRef(preNormSnapshot, ref);
1032
+ // removed during normalization. Follow terminal hops: the snapshots
1033
+ // predate inlining, so an acyclic chain's target is still the
1034
+ // intermediate reference. Cycle-safe: a cycle resolves to undefined.
1035
+ // The walk only starts from — and only continues through — pointers
1036
+ // that are themselves parameters positions: a chain may otherwise
1037
+ // lead into an `x-*` extension or transit a non-parameter position
1038
+ // to launder a non-parameter target.
1039
+ const hopWalk = isParameterTargetRef(ref)
1040
+ ? resolveTerminalRef(postNormSnapshot, preNormSnapshot, resolveInternalRef(postNormSnapshot, ref) ??
1041
+ resolveInternalRef(preNormSnapshot, ref), isParameterTargetRef)
1042
+ : { node: undefined };
1043
+ const resolved = hopWalk.node;
1044
+ const intermediateDescription = hopWalk.description;
890
1045
  // Only substitute something that is actually a parameter. Anything
891
- // else — a primitive, a response object, or another path-local ref
892
- // (a cycle, which could never make progress anyway) — leaves the
893
- // $ref in place so the Step 5 guard reports it, uncounted.
1046
+ // else — a primitive, a response object, or a reference cycle —
1047
+ // leaves the $ref in place so the Step 5 guard reports it,
1048
+ // uncounted.
894
1049
  if (isParameterObject(resolved)) {
895
- params[i] = JSON.parse(JSON.stringify(resolved));
1050
+ const copy = JSON.parse(JSON.stringify(resolved));
1051
+ // A Reference Object may carry a `description` sibling overriding
1052
+ // the target's (OpenAPI 3.1; 3.0.x processors apply the same
1053
+ // rule). Inlining must not discard that override: the use-site
1054
+ // reference's own sibling wins, then the nearest intermediate
1055
+ // reference's, then the terminal parameter's. `summary` is NOT
1056
+ // copied — a Parameter Object has no such field, so emitting it
1057
+ // would turn a valid reference into invalid output.
1058
+ const override = param['description'] ??
1059
+ intermediateDescription;
1060
+ if (typeof override === 'string')
1061
+ copy['description'] = override;
1062
+ params[i] = copy;
896
1063
  inlined++;
897
1064
  }
898
1065
  }
@@ -904,8 +1071,167 @@ export async function bundle(options) {
904
1071
  break;
905
1072
  }
906
1073
  }
1074
+ // ── Step 3e: Always inline path-local $refs used as `responses` values ────
1075
+ //
1076
+ // Same mechanism as Step 3d, for `components.responses`: the section does
1077
+ // not survive bundling, so every reuse of a shared response becomes a
1078
+ // path-local $ref to whichever operation SwaggerParser emitted first:
1079
+ //
1080
+ // GET /agent-definitions/{agentDefinitionKey}:
1081
+ // responses:
1082
+ // '401': { $ref: '#/paths/~1clock/get/responses/401' }
1083
+ //
1084
+ // The real Camunda spec carries hundreds of these. Consumers that only
1085
+ // resolve `#/components/...` pointers (e.g. api-test-generator) silently drop
1086
+ // the response.
1087
+ //
1088
+ // Response Objects are never emitted as named types by any generator — the
1089
+ // schemas inside them are, and those keep their `#/components/schemas/*`
1090
+ // refs through the deep copy — so inlining is lossless and done
1091
+ // unconditionally, for the same reason as Step 3d.
1092
+ {
1093
+ const isPathLocalRef = (node) => {
1094
+ if (!node || typeof node !== 'object' || Array.isArray(node))
1095
+ return false;
1096
+ const ref = node['$ref'];
1097
+ return typeof ref === 'string' && ref.startsWith('#/paths/');
1098
+ };
1099
+ // A Response Object requires `description` and allows only these fields
1100
+ // (plus `x-` extensions). Checking the full key set, not just
1101
+ // `description`, is what rejects a Parameter or Schema Object a bad
1102
+ // pointer may land on — both of which may also carry a `description`.
1103
+ const RESPONSE_KEYS = new Set(['description', 'headers', 'content', 'links']);
1104
+ const isResponseObject = (node) => {
1105
+ if (!node || typeof node !== 'object' || Array.isArray(node))
1106
+ return false;
1107
+ const r = node;
1108
+ return (typeof r['description'] === 'string' &&
1109
+ Object.keys(r).every((k) => RESPONSE_KEYS.has(k) || k.startsWith('x-')));
1110
+ };
1111
+ // Shape alone cannot distinguish a Response Object from an
1112
+ // annotation-only Schema Object (`{ description: '…' }` is valid as
1113
+ // both). The target's OpenAPI context can: a response target must live
1114
+ // under a `responses` map (`#/paths/<path>/<method>/responses/<status>`
1115
+ // or `#/components/responses/<name>`). The method segment must be a real
1116
+ // HTTP method and the key a real status code — `x-*` extensions are
1117
+ // arbitrary data — and a pointer that merely ENDS in
1118
+ // `/responses/<status>` (e.g. a nested schema position) is not a
1119
+ // response position.
1120
+ const RESPONSE_TARGET_REF = /^#\/(?:components\/responses\/[^/]+|paths\/~1[^/]*\/(?:get|put|post|delete|options|head|patch|trace)\/responses\/(?!x-)[^/]+)$/;
1121
+ const isResponseTargetRef = (ref) => RESPONSE_TARGET_REF.test(ref);
1122
+ for (let pass = 1; pass <= 20; pass++) {
1123
+ let inlined = 0;
1124
+ forEachResponsesMap(bundled, (responses) => {
1125
+ for (const [status, response] of Object.entries(responses)) {
1126
+ if (status.startsWith('x-'))
1127
+ continue; // extension, not a response
1128
+ if (!isPathLocalRef(response))
1129
+ continue;
1130
+ const ref = response['$ref'];
1131
+ // Follow terminal hops: the snapshots predate inlining, so the
1132
+ // target of an acyclic chain (`/c` → `/b` → `/a`) is still `/b`'s
1133
+ // reference. Cycle-safe: a cycle resolves to undefined and is left
1134
+ // for the survivor guard. The walk only starts from — and only
1135
+ // continues through — pointers that are themselves response
1136
+ // positions: a chain may otherwise lead into an `x-*` extension or
1137
+ // transit a schema position to launder a non-response target.
1138
+ const hopWalk = isResponseTargetRef(ref)
1139
+ ? resolveTerminalRef(postNormSnapshot, preNormSnapshot, resolveInternalRef(postNormSnapshot, ref) ??
1140
+ resolveInternalRef(preNormSnapshot, ref), isResponseTargetRef)
1141
+ : { node: undefined };
1142
+ const resolved = hopWalk.node;
1143
+ const intermediateDescription = hopWalk.description;
1144
+ // Anything that is not a Response Object — a primitive, another
1145
+ // object type, a missing target, or a reference cycle — leaves the
1146
+ // $ref in place, uncounted, so the Step 5 guard reports it. The
1147
+ // context check rejects a structurally identical Schema Object.
1148
+ if (isResponseObject(resolved)) {
1149
+ const copy = JSON.parse(JSON.stringify(resolved));
1150
+ // A Reference Object may carry a `description` sibling overriding
1151
+ // the target's (OpenAPI 3.1; 3.0.x processors apply the same
1152
+ // rule). Inlining must not discard that override: the use-site
1153
+ // reference's own sibling wins, then the nearest intermediate
1154
+ // reference's, then the terminal response's. `summary` is NOT
1155
+ // copied — a Response Object has no such field, so emitting it
1156
+ // would turn a valid reference into invalid output.
1157
+ const override = response['description'] ??
1158
+ intermediateDescription;
1159
+ if (typeof override === 'string')
1160
+ copy['description'] = override;
1161
+ responses[status] = copy;
1162
+ inlined++;
1163
+ }
1164
+ }
1165
+ });
1166
+ stats.inlinedPathLocalResponseCount += inlined;
1167
+ if (inlined === 0)
1168
+ break;
1169
+ }
1170
+ }
1171
+ // These guards run BEFORE Step 4: dereferencing would otherwise replace
1172
+ // the rejected refs with their (invalid) targets and hide them.
1173
+ //
1174
+ // Step 3d should have inlined all of these. A survivor means the pointer
1175
+ // could not be resolved, so the bundle is one no generator can consume —
1176
+ // fail loudly rather than emit it.
1177
+ const survivingParameterRefs = findPathLocalParameterRefs(bundled);
1178
+ if (survivingParameterRefs.length > 0 &&
1179
+ !options.allowPathLocalParameterRefs) {
1180
+ throw new Error(`${survivingParameterRefs.length} path-local $ref(s) survived inside parameters arrays:\n` +
1181
+ survivingParameterRefs.map((r) => ` ${r}`).join('\n') +
1182
+ `\n\nThese cannot be resolved by openapi-generator or Microsoft.OpenApi and cause ` +
1183
+ `"duplicate parameter values" failures. Set allowPathLocalParameterRefs ` +
1184
+ `(CLI: --allow-param-refs) to bypass.`);
1185
+ }
1186
+ // Step 3e should have inlined all of these. A survivor points at something
1187
+ // that is not a Response Object, so fail loudly rather than emit it.
1188
+ const survivingResponseRefs = findPathLocalResponseRefs(bundled);
1189
+ if (survivingResponseRefs.length > 0 &&
1190
+ !options.allowPathLocalResponseRefs) {
1191
+ throw new Error(`${survivingResponseRefs.length} path-local $ref(s) survived in responses maps ` +
1192
+ `and could not be inlined (target is missing, cyclic, or not a Response Object):\n` +
1193
+ survivingResponseRefs.map((r) => ` ${r}`).join('\n') +
1194
+ `\n\nConsumers that only resolve #/components/... pointers drop these responses. ` +
1195
+ `Set allowPathLocalResponseRefs (CLI: --allow-response-refs) to bypass.`);
1196
+ }
907
1197
  // ── Step 4: Optionally dereference remaining path-local $refs ─────────────
908
1198
  if (options.dereferencePathLocalRefs) {
1199
+ // A Reference Object may carry `summary`/`description` siblings
1200
+ // overriding the target's (OpenAPI 3.1; 3.0.x processors apply the same
1201
+ // rule). Expanding the ref must not discard those overrides — the
1202
+ // snapshots predate the inlining passes, so an aliased Path Item still
1203
+ // contains the reference with its siblings, and a naive expansion would
1204
+ // lose them.
1205
+ //
1206
+ // `summary` is only copied when the resolved target supports the field
1207
+ // (a Path Item or Operation Object does; a Response or Parameter Object
1208
+ // does not — copying it there would emit invalid output, the same rule
1209
+ // Steps 3d/3e apply). `description` is supported by every object this
1210
+ // expander can land on.
1211
+ // Path Item (`#/paths/<path>`) or Operation
1212
+ // (`#/paths/<path>/<method>`) positions — the only targets supporting
1213
+ // `summary`.
1214
+ const SUMMARY_TARGET_REF = /^#\/paths\/~1[^/]*(?:\/(?:get|put|post|delete|options|head|patch|trace))?$/;
1215
+ const expand = (refNode) => {
1216
+ const ref = refNode['$ref'];
1217
+ const resolved = resolveInternalRef(postNormSnapshot, ref) ??
1218
+ resolveInternalRef(preNormSnapshot, ref);
1219
+ if (!resolved || typeof resolved !== 'object' || Array.isArray(resolved))
1220
+ return undefined;
1221
+ const copy = JSON.parse(JSON.stringify(resolved));
1222
+ // Decided by the pointer's position, not the target's shape: a Path
1223
+ // Item with only method children carries none of the shape markers.
1224
+ const targetSupportsSummary = SUMMARY_TARGET_REF.test(ref);
1225
+ const siblings = targetSupportsSummary
1226
+ ? ['summary', 'description']
1227
+ : ['description'];
1228
+ for (const sibling of siblings) {
1229
+ const override = refNode[sibling];
1230
+ if (typeof override === 'string')
1231
+ copy[sibling] = override;
1232
+ }
1233
+ return copy;
1234
+ };
909
1235
  for (let pass = 1; pass <= 20; pass++) {
910
1236
  let dereferenced = 0;
911
1237
  const seen = new Set();
@@ -924,10 +1250,9 @@ export async function bundle(options) {
924
1250
  item['$ref'].startsWith('#/paths/')) {
925
1251
  // Prefer post-normalization source (normalized $like, promoted schemas);
926
1252
  // fall back to pre-normalization if the path was removed during normalization
927
- const resolved = resolveInternalRef(postNormSnapshot, item['$ref']) ??
928
- resolveInternalRef(preNormSnapshot, item['$ref']);
929
- if (resolved) {
930
- node[i] = JSON.parse(JSON.stringify(resolved));
1253
+ const expanded = expand(item);
1254
+ if (expanded) {
1255
+ node[i] = expanded;
931
1256
  dereferenced++;
932
1257
  }
933
1258
  }
@@ -942,10 +1267,9 @@ export async function bundle(options) {
942
1267
  const valObj = val;
943
1268
  if (typeof valObj['$ref'] === 'string' &&
944
1269
  valObj['$ref'].startsWith('#/paths/')) {
945
- const resolved = resolveInternalRef(postNormSnapshot, valObj['$ref']) ??
946
- resolveInternalRef(preNormSnapshot, valObj['$ref']);
947
- if (resolved) {
948
- obj[key] = JSON.parse(JSON.stringify(resolved));
1270
+ const expanded = expand(valObj);
1271
+ if (expanded) {
1272
+ obj[key] = expanded;
949
1273
  dereferenced++;
950
1274
  }
951
1275
  }
@@ -991,6 +1315,39 @@ export async function bundle(options) {
991
1315
  const interior = collapseComponentInteriorRefs(bundled);
992
1316
  stats.collapsedComponentInteriorRefCount = interior.collapsed;
993
1317
  stats.componentInteriorRefCount = interior.unresolved.length;
1318
+ // ── Step 4d: Collapse $refs that point into a component subtree ──────────
1319
+ //
1320
+ // When a named schema is first reached through another component's
1321
+ // composition, `SwaggerParser.bundle()` emits every other use of it as a
1322
+ // pointer into that component instead of a ref to the schema itself:
1323
+ //
1324
+ // GET /authentication/me -> 200:
1325
+ // $ref: '#/components/schemas/AuthenticatedCamundaUserResult/allOf/0'
1326
+ //
1327
+ // where `allOf/0` is just `{ $ref: '#/components/schemas/CamundaUserResult' }`
1328
+ // (camunda/camunda 1df63b8507). The pointer resolves, but generators name
1329
+ // the target after the pointer: openapi-generator (PHP) emitted a
1330
+ // non-existent `Model0` class. When the pointer lands on a bare `$ref`,
1331
+ // the two are the same schema, so rewrite to the final target. This runs
1332
+ // unconditionally: `--deref-path-local` only handles `#/paths/` refs.
1333
+ // It runs after Step 4/4b because dereferencing copies subtrees from
1334
+ // snapshots taken before this pass, which can reintroduce subtree refs.
1335
+ //
1336
+ // Step 4c already retargets `#/components/schemas/<name>/...` refs and
1337
+ // reports the ones it cannot resolve; a survivor here is one of those
1338
+ // (reported again, with the same wording) or a ref into a non-schema
1339
+ // component subtree, which 4c does not see. Both fail the same way
1340
+ // downstream, so they share the `allowComponentInteriorRefs` bypass.
1341
+ const subtree = collapseComponentSubtreeRefs(bundled);
1342
+ stats.componentSubtreeRefsCollapsed += subtree.collapsed;
1343
+ if (subtree.survivors.length > 0 && !options.allowComponentInteriorRefs) {
1344
+ throw new Error(`${subtree.survivors.length} $ref(s) point inside a component schema and do not resolve ` +
1345
+ `to a named schema:\n` +
1346
+ subtree.survivors.map((r) => ` ${r}`).join('\n') +
1347
+ `\n\nGenerators would name the target after the JSON pointer (e.g. \`Model0\`). ` +
1348
+ `Fix: register the referenced schema as a named component upstream. ` +
1349
+ `Set allowComponentInteriorRefs (CLI: --allow-interior-refs) to bypass.`);
1350
+ }
994
1351
  // ── Step 5: Validate ──────────────────────────────────────────────────────
995
1352
  // Fail if any inline schemas remain that match multiple component schemas
996
1353
  // but could not be disambiguated. These will cause generator failures
@@ -1011,18 +1368,6 @@ export async function bundle(options) {
1011
1368
  throw new Error(`${stats.pathLocalLikeRefCount} path-local $like ref(s) survived normalization. ` +
1012
1369
  `This will cause generator failures. Set allowPathLocalLikeRefs to bypass.`);
1013
1370
  }
1014
- // Step 3d should have inlined all of these. A survivor means the pointer
1015
- // could not be resolved, so the bundle is one no generator can consume —
1016
- // fail loudly rather than emit it.
1017
- const survivingParameterRefs = findPathLocalParameterRefs(bundled);
1018
- if (survivingParameterRefs.length > 0 &&
1019
- !options.allowPathLocalParameterRefs) {
1020
- throw new Error(`${survivingParameterRefs.length} path-local $ref(s) survived inside parameters arrays:\n` +
1021
- survivingParameterRefs.map((r) => ` ${r}`).join('\n') +
1022
- `\n\nThese cannot be resolved by openapi-generator or Microsoft.OpenApi and cause ` +
1023
- `"duplicate parameter values" failures. Set allowPathLocalParameterRefs ` +
1024
- `(CLI: --allow-param-refs) to bypass.`);
1025
- }
1026
1371
  // Step 4c could not retarget these: the interior location is not, and does
1027
1372
  // not resolve to, a named component, so there is no type to point at.
1028
1373
  if (interior.unresolved.length > 0 && !options.allowComponentInteriorRefs) {