sendproof-core 0.1.0.alpha.1

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.
Files changed (229) hide show
  1. checksums.yaml +7 -0
  2. data/LICENSE +21 -0
  3. data/README.md +55 -0
  4. data/lib/sendproof/assets.rb +70 -0
  5. data/lib/sendproof/attribution.rb +98 -0
  6. data/lib/sendproof/capture.rb +66 -0
  7. data/lib/sendproof/clock.rb +54 -0
  8. data/lib/sendproof/configuration.rb +241 -0
  9. data/lib/sendproof/data_store.rb +34 -0
  10. data/lib/sendproof/dynamodb/store.rb +183 -0
  11. data/lib/sendproof/dynamodb.rb +17 -0
  12. data/lib/sendproof/elasticsearch/store.rb +24 -0
  13. data/lib/sendproof/elasticsearch.rb +17 -0
  14. data/lib/sendproof/firestore/interceptor.rb +38 -0
  15. data/lib/sendproof/firestore/store.rb +150 -0
  16. data/lib/sendproof/firestore.rb +99 -0
  17. data/lib/sendproof/handler.rb +23 -0
  18. data/lib/sendproof/identity.rb +37 -0
  19. data/lib/sendproof/limits.rb +113 -0
  20. data/lib/sendproof/middleware.rb +68 -0
  21. data/lib/sendproof/mongo/engine.rb +692 -0
  22. data/lib/sendproof/mongo/guarded.rb +100 -0
  23. data/lib/sendproof/mongo/plain.rb +45 -0
  24. data/lib/sendproof/mongo/store.rb +54 -0
  25. data/lib/sendproof/mongo/subscriber.rb +21 -0
  26. data/lib/sendproof/mongo.rb +41 -0
  27. data/lib/sendproof/mongoid/store.rb +58 -0
  28. data/lib/sendproof/mongoid.rb +65 -0
  29. data/lib/sendproof/observed_request.rb +108 -0
  30. data/lib/sendproof/opensearch/store.rb +21 -0
  31. data/lib/sendproof/opensearch.rb +17 -0
  32. data/lib/sendproof/operation_matcher.rb +28 -0
  33. data/lib/sendproof/pool_hooks.rb +80 -0
  34. data/lib/sendproof/preview_request.rb +44 -0
  35. data/lib/sendproof/preview_transport.rb +331 -0
  36. data/lib/sendproof/protocol.rb +81 -0
  37. data/lib/sendproof/provider.rb +83 -0
  38. data/lib/sendproof/recorder.rb +298 -0
  39. data/lib/sendproof/redaction.rb +98 -0
  40. data/lib/sendproof/redis/commands.rb +76 -0
  41. data/lib/sendproof/redis/store.rb +205 -0
  42. data/lib/sendproof/redis.rb +18 -0
  43. data/lib/sendproof/search/middleware.rb +39 -0
  44. data/lib/sendproof/search/store.rb +213 -0
  45. data/lib/sendproof/search.rb +82 -0
  46. data/lib/sendproof/stores/classify.rb +346 -0
  47. data/lib/sendproof/stores/guard.rb +127 -0
  48. data/lib/sendproof/stores/tables.rb +1328 -0
  49. data/lib/sendproof/stores.rb +12 -0
  50. data/lib/sendproof/trace_store.rb +110 -0
  51. data/lib/sendproof/transaction_control.rb +187 -0
  52. data/lib/sendproof/ui/action-bar.js +91 -0
  53. data/lib/sendproof/ui/api.js +239 -0
  54. data/lib/sendproof/ui/app.css +848 -0
  55. data/lib/sendproof/ui/app.js +742 -0
  56. data/lib/sendproof/ui/autofill.js +137 -0
  57. data/lib/sendproof/ui/code-copy.js +71 -0
  58. data/lib/sendproof/ui/code-picker.js +149 -0
  59. data/lib/sendproof/ui/commands.js +197 -0
  60. data/lib/sendproof/ui/components.js +77 -0
  61. data/lib/sendproof/ui/context-bar.js +82 -0
  62. data/lib/sendproof/ui/copy.js +92 -0
  63. data/lib/sendproof/ui/coverage-popover.js +35 -0
  64. data/lib/sendproof/ui/crumb-fit.js +80 -0
  65. data/lib/sendproof/ui/deprecation.js +164 -0
  66. data/lib/sendproof/ui/display-settings.js +175 -0
  67. data/lib/sendproof/ui/doc-diff.js +209 -0
  68. data/lib/sendproof/ui/docs-view.js +347 -0
  69. data/lib/sendproof/ui/favicon.png +0 -0
  70. data/lib/sendproof/ui/favicon.svg +1 -0
  71. data/lib/sendproof/ui/field-help.js +52 -0
  72. data/lib/sendproof/ui/field-modules.js +23 -0
  73. data/lib/sendproof/ui/fields/controls.js +179 -0
  74. data/lib/sendproof/ui/fields/dom.js +36 -0
  75. data/lib/sendproof/ui/fields/infer.js +71 -0
  76. data/lib/sendproof/ui/fields/lookup-source.js +63 -0
  77. data/lib/sendproof/ui/fields/lookup.js +285 -0
  78. data/lib/sendproof/ui/fields/render.js +496 -0
  79. data/lib/sendproof/ui/fields/select.js +175 -0
  80. data/lib/sendproof/ui/fields/validate.js +363 -0
  81. data/lib/sendproof/ui/fields/validation-formats.js +164 -0
  82. data/lib/sendproof/ui/fields/validation-references.js +68 -0
  83. data/lib/sendproof/ui/fields/validation-values.js +137 -0
  84. data/lib/sendproof/ui/generate-menu.js +44 -0
  85. data/lib/sendproof/ui/generate.js +184 -0
  86. data/lib/sendproof/ui/header-editor.js +777 -0
  87. data/lib/sendproof/ui/headers.js +188 -0
  88. data/lib/sendproof/ui/highlight.js +257 -0
  89. data/lib/sendproof/ui/history-popover.js +24 -0
  90. data/lib/sendproof/ui/i18n.js +253 -0
  91. data/lib/sendproof/ui/icons.js +87 -0
  92. data/lib/sendproof/ui/index.html +70 -0
  93. data/lib/sendproof/ui/issues.js +187 -0
  94. data/lib/sendproof/ui/json-view.js +166 -0
  95. data/lib/sendproof/ui/lang-icons.js +62 -0
  96. data/lib/sendproof/ui/layout.js +262 -0
  97. data/lib/sendproof/ui/listbox.js +334 -0
  98. data/lib/sendproof/ui/locales/ar-capture.js +366 -0
  99. data/lib/sendproof/ui/locales/ar-stores.js +116 -0
  100. data/lib/sendproof/ui/locales/ar.js +561 -0
  101. data/lib/sendproof/ui/locales/cs-capture.js +442 -0
  102. data/lib/sendproof/ui/locales/cs-stores.js +116 -0
  103. data/lib/sendproof/ui/locales/cs.js +689 -0
  104. data/lib/sendproof/ui/locales/da-capture.js +347 -0
  105. data/lib/sendproof/ui/locales/da-stores.js +116 -0
  106. data/lib/sendproof/ui/locales/da.js +522 -0
  107. data/lib/sendproof/ui/locales/de-capture.js +347 -0
  108. data/lib/sendproof/ui/locales/de-stores.js +116 -0
  109. data/lib/sendproof/ui/locales/de.js +519 -0
  110. data/lib/sendproof/ui/locales/el-capture.js +347 -0
  111. data/lib/sendproof/ui/locales/el-stores.js +116 -0
  112. data/lib/sendproof/ui/locales/el.js +520 -0
  113. data/lib/sendproof/ui/locales/en-capture.js +349 -0
  114. data/lib/sendproof/ui/locales/en-stores.js +95 -0
  115. data/lib/sendproof/ui/locales/en.js +522 -0
  116. data/lib/sendproof/ui/locales/es-capture.js +353 -0
  117. data/lib/sendproof/ui/locales/es-stores.js +116 -0
  118. data/lib/sendproof/ui/locales/es.js +525 -0
  119. data/lib/sendproof/ui/locales/fa-capture.js +348 -0
  120. data/lib/sendproof/ui/locales/fa-stores.js +116 -0
  121. data/lib/sendproof/ui/locales/fa.js +521 -0
  122. data/lib/sendproof/ui/locales/fi-capture.js +347 -0
  123. data/lib/sendproof/ui/locales/fi-stores.js +116 -0
  124. data/lib/sendproof/ui/locales/fi.js +523 -0
  125. data/lib/sendproof/ui/locales/fr-capture.js +353 -0
  126. data/lib/sendproof/ui/locales/fr-stores.js +116 -0
  127. data/lib/sendproof/ui/locales/fr.js +525 -0
  128. data/lib/sendproof/ui/locales/he-capture.js +358 -0
  129. data/lib/sendproof/ui/locales/he-stores.js +116 -0
  130. data/lib/sendproof/ui/locales/he.js +529 -0
  131. data/lib/sendproof/ui/locales/hi-capture.js +348 -0
  132. data/lib/sendproof/ui/locales/hi-stores.js +116 -0
  133. data/lib/sendproof/ui/locales/hi.js +523 -0
  134. data/lib/sendproof/ui/locales/id-capture.js +347 -0
  135. data/lib/sendproof/ui/locales/id-stores.js +116 -0
  136. data/lib/sendproof/ui/locales/id.js +521 -0
  137. data/lib/sendproof/ui/locales/it-capture.js +361 -0
  138. data/lib/sendproof/ui/locales/it-stores.js +116 -0
  139. data/lib/sendproof/ui/locales/it.js +523 -0
  140. data/lib/sendproof/ui/locales/ja-capture.js +346 -0
  141. data/lib/sendproof/ui/locales/ja-stores.js +116 -0
  142. data/lib/sendproof/ui/locales/ja.js +521 -0
  143. data/lib/sendproof/ui/locales/ko-capture.js +346 -0
  144. data/lib/sendproof/ui/locales/ko-stores.js +116 -0
  145. data/lib/sendproof/ui/locales/ko.js +522 -0
  146. data/lib/sendproof/ui/locales/nb-capture.js +349 -0
  147. data/lib/sendproof/ui/locales/nb-stores.js +116 -0
  148. data/lib/sendproof/ui/locales/nb.js +521 -0
  149. data/lib/sendproof/ui/locales/nl-capture.js +355 -0
  150. data/lib/sendproof/ui/locales/nl-stores.js +116 -0
  151. data/lib/sendproof/ui/locales/nl.js +520 -0
  152. data/lib/sendproof/ui/locales/pl-capture.js +432 -0
  153. data/lib/sendproof/ui/locales/pl-stores.js +116 -0
  154. data/lib/sendproof/ui/locales/pl.js +528 -0
  155. data/lib/sendproof/ui/locales/pt-BR-capture.js +350 -0
  156. data/lib/sendproof/ui/locales/pt-BR-stores.js +116 -0
  157. data/lib/sendproof/ui/locales/pt-BR.js +523 -0
  158. data/lib/sendproof/ui/locales/pt-PT-capture.js +350 -0
  159. data/lib/sendproof/ui/locales/pt-PT-stores.js +116 -0
  160. data/lib/sendproof/ui/locales/pt-PT.js +523 -0
  161. data/lib/sendproof/ui/locales/ru-capture.js +437 -0
  162. data/lib/sendproof/ui/locales/ru-stores.js +116 -0
  163. data/lib/sendproof/ui/locales/ru.js +624 -0
  164. data/lib/sendproof/ui/locales/sv-capture.js +349 -0
  165. data/lib/sendproof/ui/locales/sv-stores.js +116 -0
  166. data/lib/sendproof/ui/locales/sv.js +518 -0
  167. data/lib/sendproof/ui/locales/th-capture.js +347 -0
  168. data/lib/sendproof/ui/locales/th-stores.js +116 -0
  169. data/lib/sendproof/ui/locales/th.js +521 -0
  170. data/lib/sendproof/ui/locales/tr-capture.js +348 -0
  171. data/lib/sendproof/ui/locales/tr-stores.js +116 -0
  172. data/lib/sendproof/ui/locales/tr.js +521 -0
  173. data/lib/sendproof/ui/locales/uk-capture.js +442 -0
  174. data/lib/sendproof/ui/locales/uk-stores.js +116 -0
  175. data/lib/sendproof/ui/locales/uk.js +630 -0
  176. data/lib/sendproof/ui/locales/vi-capture.js +346 -0
  177. data/lib/sendproof/ui/locales/vi-stores.js +116 -0
  178. data/lib/sendproof/ui/locales/vi.js +523 -0
  179. data/lib/sendproof/ui/locales/zh-Hans-capture.js +347 -0
  180. data/lib/sendproof/ui/locales/zh-Hans-stores.js +116 -0
  181. data/lib/sendproof/ui/locales/zh-Hans.js +523 -0
  182. data/lib/sendproof/ui/locales/zh-Hant-capture.js +346 -0
  183. data/lib/sendproof/ui/locales/zh-Hant-stores.js +116 -0
  184. data/lib/sendproof/ui/locales/zh-Hant.js +522 -0
  185. data/lib/sendproof/ui/manifest.json +866 -0
  186. data/lib/sendproof/ui/markdown.js +39 -0
  187. data/lib/sendproof/ui/model-view.js +182 -0
  188. data/lib/sendproof/ui/navigation.js +233 -0
  189. data/lib/sendproof/ui/operation-header.js +76 -0
  190. data/lib/sendproof/ui/operations.js +7 -0
  191. data/lib/sendproof/ui/overview-view.js +63 -0
  192. data/lib/sendproof/ui/personas.js +59 -0
  193. data/lib/sendproof/ui/popover.js +71 -0
  194. data/lib/sendproof/ui/preview-false.js +108 -0
  195. data/lib/sendproof/ui/request-editor.js +496 -0
  196. data/lib/sendproof/ui/response-metadata.js +354 -0
  197. data/lib/sendproof/ui/response-viewer.js +618 -0
  198. data/lib/sendproof/ui/result-blocked.js +155 -0
  199. data/lib/sendproof/ui/result-capture.js +25 -0
  200. data/lib/sendproof/ui/result-database.js +185 -0
  201. data/lib/sendproof/ui/result-effects.js +176 -0
  202. data/lib/sendproof/ui/result-headers.js +106 -0
  203. data/lib/sendproof/ui/result-logs.js +408 -0
  204. data/lib/sendproof/ui/result-states.js +213 -0
  205. data/lib/sendproof/ui/results.js +371 -0
  206. data/lib/sendproof/ui/router.js +118 -0
  207. data/lib/sendproof/ui/schema-model.js +336 -0
  208. data/lib/sendproof/ui/schema-tree.js +344 -0
  209. data/lib/sendproof/ui/schema.js +397 -0
  210. data/lib/sendproof/ui/security.js +31 -0
  211. data/lib/sendproof/ui/seeded-menu.js +69 -0
  212. data/lib/sendproof/ui/settings.js +93 -0
  213. data/lib/sendproof/ui/shortcuts-sheet.js +73 -0
  214. data/lib/sendproof/ui/shortcuts.js +190 -0
  215. data/lib/sendproof/ui/sidebar.js +289 -0
  216. data/lib/sendproof/ui/signin.js +259 -0
  217. data/lib/sendproof/ui/snippets.js +530 -0
  218. data/lib/sendproof/ui/store-marks.js +47 -0
  219. data/lib/sendproof/ui/stores.js +131 -0
  220. data/lib/sendproof/ui/styles.css +971 -0
  221. data/lib/sendproof/ui/toggletip.js +53 -0
  222. data/lib/sendproof/ui/uuid.js +10 -0
  223. data/lib/sendproof/ui/view.js +122 -0
  224. data/lib/sendproof/ui/views.css +653 -0
  225. data/lib/sendproof/version.rb +9 -0
  226. data/lib/sendproof/workbench.rb +102 -0
  227. data/lib/sendproof-core.rb +3 -0
  228. data/lib/sendproof.rb +121 -0
  229. metadata +292 -0
@@ -0,0 +1,118 @@
1
+ // Hash routes and history for the workbench. Every page has an address, every navigation pushes
2
+ // a history entry, and Back/Forward restore the page and its scroll position.
3
+ //
4
+ // #overview
5
+ // #op/<operationId> Try it
6
+ // #docs/<operationId> the Docs view of an operation
7
+ // #model/<Name> a model picked in the Models tab
8
+ // #model/<Name>?from=docs/<operationId>&via=<Model>,<Model>
9
+ // a model opened from an operation (`from` is docs/… or
10
+ // op/…) or from a $ref followed through other models (`via`)
11
+ //
12
+ // Expanding a schema inline is not navigation and never changes the address.
13
+
14
+ /**
15
+ * @typedef {object} Route
16
+ * @property {'overview'|'op'|'docs'|'model'} kind
17
+ * @property {string} [id] operation id (or "METHOD /path") for op and docs
18
+ * @property {string} [name] model name for model
19
+ * @property {{kind: 'op'|'docs', id: string}} [from] the operation a model was opened from
20
+ * @property {string[]} [via] models followed on the way, nearest to the operation first
21
+ */
22
+
23
+ const OVERVIEW = Object.freeze({ kind: 'overview' });
24
+
25
+ /** Parses a location hash ("#model/Payment?from=docs/Op") into a route. Unknown hashes mean the overview. */
26
+ export function parseRoute(hash) {
27
+ const text = String(hash ?? '').replace(/^#/, '');
28
+ const split = text.indexOf('?');
29
+ const path = split < 0 ? text : text.slice(0, split);
30
+ const query = new URLSearchParams(split < 0 ? '' : text.slice(split + 1));
31
+ const slash = path.indexOf('/');
32
+ const kind = slash < 0 ? path : path.slice(0, slash);
33
+ let key = '';
34
+ try { key = decodeURIComponent(slash < 0 ? '' : path.slice(slash + 1)); } catch { return OVERVIEW; }
35
+ if ((kind === 'op' || kind === 'docs') && key) return { kind, id: key };
36
+ if (kind === 'model' && key) {
37
+ const route = { kind, name: key };
38
+ const from = /^(op|docs)\/(.+)$/.exec(query.get('from') ?? '');
39
+ if (from) route.from = { kind: from[1], id: from[2] };
40
+ const via = (query.get('via') ?? '').split(',').filter(Boolean);
41
+ if (via.length) route.via = via;
42
+ return route;
43
+ }
44
+ return OVERVIEW;
45
+ }
46
+
47
+ /** The hash for a route, the inverse of {@link parseRoute}. */
48
+ export function formatRoute(route) {
49
+ const encode = encodeURIComponent;
50
+ if (route.kind === 'op' || route.kind === 'docs') return `#${route.kind}/${encode(route.id)}`;
51
+ if (route.kind !== 'model') return '#overview';
52
+ const query = [];
53
+ if (route.from) query.push(`from=${route.from.kind}/${encode(route.from.id)}`);
54
+ if (route.via?.length) query.push(`via=${route.via.map(encode).join(',')}`);
55
+ return `#model/${encode(route.name)}${query.length ? '?' + query.join('&') : ''}`;
56
+ }
57
+
58
+ /** Whether two routes are the same page. */
59
+ export const sameRoute = (a, b) => formatRoute(a) === formatRoute(b);
60
+
61
+ /**
62
+ * Where Back goes from a model page: the last model followed, else the operation it was opened
63
+ * from (in the view it came from). Models opened from the Models tab have nowhere to go back to.
64
+ * @returns {{route: Route, label: {kind: 'model'|'op', name?: string, id?: string}} | null}
65
+ */
66
+ export function backTarget(route) {
67
+ if (route.kind !== 'model' || !route.from) return null;
68
+ const via = route.via ?? [];
69
+ if (via.length) {
70
+ const name = via.at(-1);
71
+ const rest = via.slice(0, -1);
72
+ return { route: { kind: 'model', name, from: route.from, ...(rest.length ? { via: rest } : {}) }, label: { kind: 'model', name } };
73
+ }
74
+ return { route: { kind: route.from.kind, id: route.from.id }, label: { kind: 'op', id: route.from.id } };
75
+ }
76
+
77
+ /** The route of a model followed from the current page, one step deeper than `route`. */
78
+ export function followModel(route, name) {
79
+ if (route.kind === 'model') {
80
+ const via = route.from ? [...(route.via ?? []), route.name] : [];
81
+ return { kind: 'model', name, ...(route.from ? { from: route.from, via } : {}) };
82
+ }
83
+ if (route.kind === 'op' || route.kind === 'docs') return { kind: 'model', name, from: { kind: route.kind, id: route.id } };
84
+ return { kind: 'model', name };
85
+ }
86
+
87
+ /**
88
+ * Keeps history entries in step with navigation. Each entry's state is `{ idx, prev, scroll }`:
89
+ * its position in this session, the address of the page before it, and the scroll offsets saved
90
+ * when the user left it. `idx` and `prev` let Back know whether the browser's previous entry is
91
+ * really the parent page, which a deep link or a reload may break.
92
+ *
93
+ * @param {{ history?: History, location?: Location }} [env] replaceable in tests
94
+ */
95
+ export function createHistory({ history: h = globalThis.history, location: where = globalThis.location } = {}) {
96
+ const url = () => where.hash || '#overview';
97
+ const read = () => (h.state && typeof h.state === 'object' ? h.state : {});
98
+ if (!Number.isInteger(read().idx)) h.replaceState({ ...read(), idx: 0 }, '', url());
99
+ return {
100
+ /** The current entry's saved state. */
101
+ get state() { return read(); },
102
+ /** The address of the page now shown. */
103
+ get url() { return url(); },
104
+ /** Saves scroll offsets on the entry being left. */
105
+ saveScroll(scroll) { h.replaceState({ ...read(), scroll }, '', url()); },
106
+ /** Pushes (or replaces) an entry for `route`; returns false when it is already the current page. */
107
+ go(route, { replace = false } = {}) {
108
+ const hash = formatRoute(route);
109
+ if (hash === url()) return false;
110
+ if (replace) h.replaceState({ ...read(), scroll: undefined }, '', hash);
111
+ else h.pushState({ idx: (read().idx ?? 0) + 1, prev: url() }, '', hash);
112
+ return true;
113
+ },
114
+ /** True when the browser's previous entry is `hash`, so `history.back()` lands on it. */
115
+ previousIs(hash) { return (read().idx ?? 0) > 0 && read().prev === hash; },
116
+ back: () => h.back(),
117
+ };
118
+ }
@@ -0,0 +1,336 @@
1
+ // Reading components.schemas for people: what kind each schema is, how big, which operations
2
+ // use it, how its properties merge, and a representative example. Pure data, no markup: the
3
+ // property tree (schema-tree.js) and the model page build on it. Port of mocks/schema.js.
4
+ import { dereference } from './api.js';
5
+ import { formatNumber, t } from './i18n.js';
6
+
7
+ const PREFIX = '#/components/schemas/';
8
+
9
+ /** The model name of a `$ref` into components.schemas, or '' for anything else. */
10
+ export const refName = raw => raw?.$ref?.startsWith(PREFIX) ? decodeURIComponent(raw.$ref.slice(PREFIX.length)) : '';
11
+
12
+ /** Follows `$ref` chains to the target schema (cycle-safe). */
13
+ export function resolve(raw, document) {
14
+ let current = raw;
15
+ const seen = new Set();
16
+ while (current?.$ref && !seen.has(current.$ref)) {
17
+ seen.add(current.$ref);
18
+ current = dereference(current, document);
19
+ }
20
+ return current ?? {};
21
+ }
22
+
23
+ const typesOf = schema => Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : [];
24
+ const isNull = schema => schema && (schema.type === 'null' || (Array.isArray(schema.type) && schema.type.length === 1 && schema.type[0] === 'null'));
25
+ const omit = (object, keys) => Object.fromEntries(Object.entries(object).filter(([key]) => !keys.includes(key)));
26
+
27
+ /** Splits "string | null" style schemas into the real schema and a nullable flag. */
28
+ export function unwrapNull(raw) {
29
+ if (!raw) return { schema: {}, nullable: false };
30
+ for (const key of ['oneOf', 'anyOf']) {
31
+ if (Array.isArray(raw[key]) && raw[key].some(isNull)) {
32
+ const rest = raw[key].filter(option => !isNull(option));
33
+ if (rest.length === 1) return { schema: { ...rest[0], ...omit(raw, [key]) }, nullable: true };
34
+ return { schema: { ...raw, [key]: rest }, nullable: true };
35
+ }
36
+ }
37
+ if (Array.isArray(raw.type) && raw.type.includes('null')) {
38
+ const types = raw.type.filter(type => type !== 'null');
39
+ return { schema: { ...raw, type: types.length === 1 ? types[0] : types }, nullable: true };
40
+ }
41
+ return { schema: raw, nullable: raw.nullable === true };
42
+ }
43
+
44
+ /**
45
+ * An enum's values and what each means: x-enum-descriptions ({ value: text }), or a oneOf of
46
+ * `const` schemas with descriptions. `values` is undefined when the schema isn't an enum.
47
+ * Arrays of enums report their items' values.
48
+ */
49
+ export function enumOf(raw, document) {
50
+ const { schema } = unwrapNull(raw || {});
51
+ const resolved = resolve(schema, document);
52
+ const items = resolved.items ? resolve(resolved.items, document) : undefined;
53
+ const own = resolved.enum ? resolved : items?.enum ? items : undefined;
54
+ const consts = (resolved.oneOf || resolved.anyOf || []).map(option => resolve(option, document));
55
+ if (!own && !(consts.length && consts.every(option => option && Object.hasOwn(option, 'const')))) return undefined;
56
+ const values = own ? own.enum.filter(value => value !== null) : consts.map(option => option.const);
57
+ const desc = own ? (own['x-enum-descriptions'] || own['x-enumDescriptions'] || schema['x-enum-descriptions'] || {})
58
+ : Object.fromEntries(consts.filter(option => option.description).map(option => [String(option.const), option.description]));
59
+ return { values, desc, described: values.some(value => desc[String(value)]) };
60
+ }
61
+
62
+ /** oneOf, anyOf, allOf, or the JSON type of a schema ('any' when nothing says). */
63
+ export function typeOf(raw, document) {
64
+ const schema = resolve(raw, document);
65
+ if (schema.oneOf) return 'oneOf';
66
+ if (schema.anyOf) return 'anyOf';
67
+ if (schema.allOf && !schema.properties) return 'allOf';
68
+ const types = typesOf(schema).filter(type => type !== 'null');
69
+ return types[0] || (schema.properties ? 'object' : schema.items ? 'array' : schema.enum ? 'string' : 'any');
70
+ }
71
+
72
+ /** Properties of an object with allOf parts merged: `{ props, required, sources }`. */
73
+ export function propertiesOf(raw, document, seen = new Set()) {
74
+ const schema = resolve(typeof raw === 'string' ? { $ref: PREFIX + encodeURIComponent(raw) } : raw, document);
75
+ let props = { ...(schema.properties || {}) };
76
+ const required = new Set(schema.required || []);
77
+ const sources = [];
78
+ for (const part of schema.allOf || []) {
79
+ if (part.$ref && seen.has(part.$ref)) continue;
80
+ const merged = propertiesOf(part, document, new Set([...seen, part.$ref]));
81
+ if (refName(part)) sources.push(refName(part));
82
+ props = { ...merged.props, ...props };
83
+ merged.required.forEach(name => required.add(name));
84
+ }
85
+ return { props, required, sources };
86
+ }
87
+
88
+ /** The non-null options of a oneOf or anyOf. */
89
+ export const variantsOf = (raw, document) => {
90
+ const schema = resolve(raw, document);
91
+ return (schema.oneOf || schema.anyOf || []).filter(option => !isNull(option));
92
+ };
93
+
94
+ /** The discriminator of a union: `{ prop, map: [[value, modelName], …] }`, or undefined. */
95
+ export function discriminatorOf(raw, document) {
96
+ const schema = resolve(raw, document);
97
+ if (!schema.discriminator) return undefined;
98
+ const map = Object.entries(schema.discriminator.mapping || {}).map(([value, ref]) => [value, decodeURIComponent(String(ref).split('/').at(-1))]);
99
+ if (!map.length) for (const option of variantsOf(schema, document)) if (refName(option)) map.push([refName(option), refName(option)]);
100
+ return { prop: schema.discriminator.propertyName, map };
101
+ }
102
+
103
+ /** The schema's kind for lists and chips: enum, oneOf, anyOf, allOf, array, object or scalar. */
104
+ export function modelKind(raw, document) {
105
+ const schema = resolve(raw, document);
106
+ if (schema.enum) return { id: 'enum', glyph: 'enum' };
107
+ if (schema.oneOf) return { id: 'oneOf', glyph: '1 of' };
108
+ if (schema.anyOf) return { id: 'anyOf', glyph: 'any' };
109
+ if (schema.allOf && !schema.properties) return { id: 'allOf', glyph: 'all' };
110
+ if (typesOf(schema).includes('array')) return { id: 'array', glyph: '[ ]' };
111
+ if (schema.properties || schema.allOf || typesOf(schema).includes('object')) return { id: 'object', glyph: '{ }' };
112
+ return { id: 'scalar', glyph: typesOf(schema)[0] || 'any' };
113
+ }
114
+
115
+ /** Properties for objects, members for enums, variants for compositions. */
116
+ export function modelSize(raw, document) {
117
+ const schema = resolve(raw, document);
118
+ if (schema.enum) return schema.enum.length;
119
+ const variants = variantsOf(schema, document);
120
+ if (variants.length) return variants.length;
121
+ return Object.keys(propertiesOf(schema, document).props).length;
122
+ }
123
+
124
+ /**
125
+ * Models grouped by what they are, so a long list stays scannable: resources, request bodies,
126
+ * list pages, enums and errors. Empty groups are left out. Each group is `[key, names]`.
127
+ */
128
+ export function modelGroups(document) {
129
+ const schemas = document?.components?.schemas || {};
130
+ const names = Object.keys(schemas).sort((a, b) => a.localeCompare(b));
131
+ const bucket = name => modelKind(schemas[name], document).id === 'enum' ? 'enums'
132
+ : /^PagedListOf/.test(name) ? 'lists'
133
+ : /Problem|Error/.test(name) ? 'errors'
134
+ : /(Request|Input|Command)$/.test(name) ? 'requests' : 'resources';
135
+ return ['resources', 'requests', 'lists', 'enums', 'errors'].map(key => [key, names.filter(name => bucket(name) === key)]).filter(([, list]) => list.length);
136
+ }
137
+
138
+ /** The group key of a model (see {@link modelGroups}). */
139
+ export const modelGroupOf = (name, document) => modelGroups(document).find(([, names]) => names.includes(name))?.[0] ?? 'resources';
140
+
141
+ /** Whether a schema has something to show underneath its row: properties, items or variants. */
142
+ export function isExpandable(raw, document) {
143
+ const { schema } = unwrapNull(raw);
144
+ const type = typeOf(schema, document);
145
+ if (type === 'object') return Object.keys(propertiesOf(schema, document).props).length > 0;
146
+ if (type === 'array') return isExpandable(resolve(schema, document).items || {}, document);
147
+ return ['oneOf', 'anyOf', 'allOf'].includes(type);
148
+ }
149
+
150
+ /** The schema whose properties are a tree's top-level rows: an array's items, else the schema itself. */
151
+ export function rowSchema(raw, document) {
152
+ const schema = resolve(raw, document);
153
+ return typeOf(schema, document) === 'array' && schema.items ? schema.items : raw;
154
+ }
155
+
156
+ /** The label after a property name: `{ text, ref? }` where ref is the model a link should open. */
157
+ export function typeLabel(raw, document) {
158
+ const { schema } = unwrapNull(raw);
159
+ const name = refName(schema);
160
+ if (name) return { text: name, ref: name };
161
+ const resolved = resolve(schema, document);
162
+ if (resolved.oneOf || resolved.anyOf) return { text: t('schema.oneOf', { n: variantsOf(resolved, document).length }) };
163
+ if (resolved.allOf && !resolved.properties) {
164
+ const base = resolved.allOf.map(refName).find(Boolean);
165
+ return base ? { text: base, ref: base } : { text: 'object' };
166
+ }
167
+ const type = typeOf(resolved, document);
168
+ if (type === 'array') {
169
+ const inner = typeLabel(resolved.items || {}, document);
170
+ return { text: inner.text + '[]', ref: inner.ref, array: true };
171
+ }
172
+ return { text: type === 'number' && resolved.format === 'decimal' ? 'decimal' : type };
173
+ }
174
+
175
+ /** The referenced model name of a schema, or "Name[]" for arrays of a model. */
176
+ export function schemaName(raw, document) {
177
+ const name = refName(raw);
178
+ if (name) return name;
179
+ const item = refName(resolve(raw, document).items);
180
+ return item ? `${item}[]` : '';
181
+ }
182
+
183
+ /** Model names referenced anywhere under a schema node (it does not look inside the models). */
184
+ function refsIn(node, out = new Set(), depth = 0) {
185
+ if (!node || typeof node !== 'object' || depth > 8) return out;
186
+ if (node.$ref) { if (refName(node)) out.add(refName(node)); return out; }
187
+ for (const value of Object.values(node)) if (value && typeof value === 'object') refsIn(value, out, depth + 1);
188
+ return out;
189
+ }
190
+
191
+ /** Schemas this one references directly, for the References card. */
192
+ export const references = (raw, document) => [...refsIn(resolve(raw, document))];
193
+
194
+ const bodySchema = (operation, document) => Object.values(resolve(operation.requestBody, document).content || {}).map(media => media.schema).filter(Boolean);
195
+ const responseSchemas = (operation, document) => Object.entries(operation.responses || {}).map(([code, raw]) => [code, Object.values(resolve(raw, document).content || {})[0]?.schema]).filter(([, schema]) => schema);
196
+
197
+ /**
198
+ * Where operations use a model. `operations` are the direct users, each with the places it
199
+ * appears: `{ op, request, codes }`. When nothing uses the model directly, `via` lists the
200
+ * operations of the models that contain it (`{ op, request, codes, model }`, the model being the
201
+ * one the operation uses), so the page still answers "where does this appear?". `models` are the
202
+ * schemas that reference it ("Referenced by").
203
+ */
204
+ export function usedBy(name, ops, document) {
205
+ const schemas = document?.components?.schemas || {};
206
+ const direct = target => {
207
+ const rows = [];
208
+ for (const op of ops) {
209
+ const request = bodySchema(op.operation, document).some(schema => refsIn(schema).has(target));
210
+ const codes = responseSchemas(op.operation, document).filter(([, schema]) => refsIn(schema).has(target)).map(([code]) => code);
211
+ if (request || codes.length) rows.push({ op, request, codes });
212
+ }
213
+ return rows;
214
+ };
215
+ const containers = target => Object.keys(schemas).filter(other => other !== target && refsIn(schemas[other]).has(target));
216
+ const operations = direct(name);
217
+ const models = containers(name);
218
+ const via = [];
219
+ if (!operations.length) {
220
+ // Breadth first through the models that contain this one, so the nearest container wins.
221
+ const seen = new Set([name]);
222
+ let level = models;
223
+ for (let depth = 0; depth < 4 && level.length; depth++) {
224
+ const next = [];
225
+ for (const model of level) {
226
+ if (seen.has(model)) continue;
227
+ seen.add(model);
228
+ for (const row of direct(model)) if (!via.some(item => item.op === row.op)) via.push({ ...row, model });
229
+ next.push(...containers(model));
230
+ }
231
+ level = next;
232
+ }
233
+ }
234
+ return { operations, via, models };
235
+ }
236
+
237
+ const hintCache = new WeakMap();
238
+ /**
239
+ * Property values from every example in the document, by property name. A generated example
240
+ * reuses them, so a Payment example shows the amount and IDs the API author already wrote.
241
+ */
242
+ function exampleHints(document) {
243
+ if (!document || typeof document !== 'object') return new Map();
244
+ if (hintCache.has(document)) return hintCache.get(document);
245
+ const hints = new Map();
246
+ const collect = value => {
247
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return;
248
+ for (const [key, item] of Object.entries(value)) if (!hints.has(key) && item !== null) hints.set(key, item);
249
+ };
250
+ for (const schema of Object.values(document.components?.schemas || {})) {
251
+ collect(schema?.example);
252
+ (Array.isArray(schema?.examples) ? schema.examples : []).forEach(collect);
253
+ }
254
+ hintCache.set(document, hints);
255
+ return hints;
256
+ }
257
+
258
+ /** A representative example: the schema's own example, else one generated from its shape. */
259
+ export function exampleFor(raw, document, depth = 0, seen = new Set(), name) {
260
+ const schema = resolve(unwrapNull(raw).schema, document);
261
+ const hint = name !== undefined ? exampleHints(document).get(name) : undefined;
262
+ if (hint !== undefined && schema.example === undefined && !schema.properties) return hint;
263
+ if (schema.example !== undefined) return schema.example;
264
+ if (Array.isArray(schema.examples) && schema.examples.length) return schema.examples[0];
265
+ if ((raw?.$ref && seen.has(raw.$ref)) || depth > 5) return {};
266
+ const nextSeen = raw?.$ref ? new Set([...seen, raw.$ref]) : seen;
267
+ if (schema.default !== undefined) return schema.default;
268
+ if (schema.enum) return schema.enum[0];
269
+ if (schema.const !== undefined) return schema.const;
270
+ const variants = variantsOf(schema, document);
271
+ if (variants.length) return exampleFor(variants[0], document, depth + 1, nextSeen);
272
+ const types = typesOf(schema).filter(type => type !== 'null');
273
+ if (schema.properties || schema.allOf || types.includes('object')) {
274
+ const { props } = propertiesOf(schema, document);
275
+ return Object.fromEntries(Object.entries(props).filter(([, child]) => !resolve(child, document).writeOnly)
276
+ .map(([key, child]) => [key, exampleFor(child, document, depth + 1, nextSeen, key)]));
277
+ }
278
+ if (types.includes('array')) return [exampleFor(schema.items, document, depth + 1, nextSeen)];
279
+ if (schema.format === 'date-time') return new Date().toISOString().replace(/\.\d+Z$/, 'Z');
280
+ if (types.includes('integer') || types.includes('number')) return schema.minimum ?? 0;
281
+ if (types.includes('boolean')) return true;
282
+ return { uuid: '00000000-0000-4000-8000-000000000000', date: '2026-01-01', 'date-time': '2026-01-01T00:00:00Z', email: 'name@example.test', uri: 'https://example.test' }[schema.format] ?? 'string';
283
+ }
284
+
285
+ /**
286
+ * A real captured value that fits a schema: the first object, anywhere in `samples`, that has
287
+ * every required property (or any property when none is required) and nothing the schema
288
+ * doesn't declare. Returns undefined when nothing fits, so callers fall back to the
289
+ * schema's example or a generated one.
290
+ */
291
+ export function findSample(raw, document, samples) {
292
+ const keys = Object.keys(propertiesOf(raw, document).props);
293
+ if (!keys.length) return undefined;
294
+ const queue = [...(samples || [])];
295
+ for (let seen = 0; queue.length && seen < 2000; seen++) {
296
+ const value = queue.shift();
297
+ if (fitsSchema(value, raw, document)) return value;
298
+ if (value && typeof value === 'object') queue.push(...Object.values(value));
299
+ }
300
+ return undefined;
301
+ }
302
+
303
+ /**
304
+ * Whether a captured value has the shape of an object schema: its required keys, no keys the
305
+ * schema doesn't declare, and (one level down) the first item of each array of objects fits the
306
+ * item schema too, so a page of payments never passes for a page of accounts.
307
+ */
308
+ function fitsSchema(value, raw, document, depth = 0) {
309
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
310
+ const { props, required } = propertiesOf(raw, document);
311
+ const keys = Object.keys(props);
312
+ if (!keys.length) return true;
313
+ const need = required.size ? [...required] : keys;
314
+ if (!need.every(key => key in value) || !Object.keys(value).every(key => keys.includes(key))) return false;
315
+ if (depth > 1) return true;
316
+ return Object.entries(props).every(([key, child]) => {
317
+ const schema = resolve(unwrapNull(child).schema, document);
318
+ if (typeOf(schema, document) !== 'array' || !Array.isArray(value[key]) || !value[key].length) return true;
319
+ const item = resolve(schema.items || {}, document);
320
+ return typeOf(item, document) !== 'object' || !Object.keys(propertiesOf(schema.items, document).props).length || fitsSchema(value[key][0], schema.items, document, depth + 1);
321
+ });
322
+ }
323
+
324
+ export function modelExample(name, document, samples = []) {
325
+ const raw = { $ref: PREFIX + encodeURIComponent(name) };
326
+ const schema = resolve(raw, document);
327
+ const kind = modelKind(schema, document).id;
328
+ if (kind === 'enum') return { value: schema.enum?.[0], source: schema.example !== undefined ? 'spec' : 'generated' };
329
+ const real = kind === 'object' ? findSample(raw, document, samples) : undefined;
330
+ if (real) return { value: real, source: 'real' };
331
+ const own = schema.example ?? (Array.isArray(schema.examples) ? schema.examples[0] : undefined);
332
+ if (own !== undefined) return { value: own, source: 'spec' };
333
+ return { value: exampleFor(raw, document), source: 'generated' };
334
+ }
335
+
336
+ export const countLabel = (n, key) => t(key, { n: formatNumber(n) });