micro-contracts 0.18.10 → 0.18.12

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 (202) hide show
  1. package/README.md +7 -14
  2. package/cli-contract.yaml +15 -27
  3. package/dist/agents/context-builder.d.ts +5 -0
  4. package/dist/agents/context-builder.d.ts.map +1 -0
  5. package/dist/agents/context-builder.js +239 -0
  6. package/dist/agents/context-builder.js.map +1 -0
  7. package/dist/agents/formatter.d.ts +9 -0
  8. package/dist/agents/formatter.d.ts.map +1 -0
  9. package/dist/agents/formatter.js +124 -0
  10. package/dist/agents/formatter.js.map +1 -0
  11. package/dist/agents/index.d.ts +6 -0
  12. package/dist/agents/index.d.ts.map +1 -0
  13. package/dist/agents/index.js +4 -0
  14. package/dist/agents/index.js.map +1 -0
  15. package/dist/agents/orchestrator.d.ts +5 -0
  16. package/dist/agents/orchestrator.d.ts.map +1 -0
  17. package/dist/agents/orchestrator.js +46 -0
  18. package/dist/agents/orchestrator.js.map +1 -0
  19. package/dist/agents/types.d.ts +29 -0
  20. package/dist/agents/types.d.ts.map +1 -0
  21. package/dist/agents/types.js +7 -0
  22. package/dist/agents/types.js.map +1 -0
  23. package/dist/cli/templates.d.ts +15 -0
  24. package/dist/cli/templates.d.ts.map +1 -0
  25. package/dist/cli/templates.js +445 -0
  26. package/dist/cli/templates.js.map +1 -0
  27. package/dist/cli.d.ts +3 -0
  28. package/dist/cli.d.ts.map +1 -0
  29. package/dist/cli.js +1201 -0
  30. package/dist/cli.js.map +1 -0
  31. package/dist/commands/audit-guardrails.d.ts +15 -0
  32. package/dist/commands/audit-guardrails.d.ts.map +1 -0
  33. package/dist/commands/audit-guardrails.js +33 -0
  34. package/dist/commands/audit-guardrails.js.map +1 -0
  35. package/dist/commands/audit-openapi.d.ts +15 -0
  36. package/dist/commands/audit-openapi.d.ts.map +1 -0
  37. package/dist/commands/audit-openapi.js +33 -0
  38. package/dist/commands/audit-openapi.js.map +1 -0
  39. package/dist/commands/insights.d.ts +8 -0
  40. package/dist/commands/insights.d.ts.map +1 -0
  41. package/dist/commands/insights.js +13 -0
  42. package/dist/commands/insights.js.map +1 -0
  43. package/dist/commands/propose-overlays.d.ts +15 -0
  44. package/dist/commands/propose-overlays.d.ts.map +1 -0
  45. package/dist/commands/propose-overlays.js +33 -0
  46. package/dist/commands/propose-overlays.js.map +1 -0
  47. package/dist/commands/review-published.d.ts +15 -0
  48. package/dist/commands/review-published.d.ts.map +1 -0
  49. package/dist/commands/review-published.js +33 -0
  50. package/dist/commands/review-published.js.map +1 -0
  51. package/dist/external/insight-provider.d.ts.map +1 -0
  52. package/dist/external/insight-provider.js.map +1 -0
  53. package/dist/generated/commands.d.ts +2 -0
  54. package/dist/generated/commands.d.ts.map +1 -0
  55. package/dist/generated/commands.js +2 -0
  56. package/dist/generated/commands.js.map +1 -0
  57. package/dist/generated/contract.d.ts +3 -0
  58. package/dist/generated/contract.d.ts.map +1 -0
  59. package/dist/generated/contract.js +5 -0
  60. package/dist/generated/contract.js.map +1 -0
  61. package/dist/generated/dsl/agents.d.ts +34 -0
  62. package/dist/generated/dsl/agents.d.ts.map +1 -0
  63. package/dist/generated/dsl/agents.js +98 -0
  64. package/dist/generated/dsl/agents.js.map +1 -0
  65. package/dist/generated/dsl/dsl-data.d.ts +7 -0
  66. package/dist/generated/dsl/dsl-data.d.ts.map +1 -0
  67. package/dist/generated/dsl/dsl-data.js +1041 -0
  68. package/dist/generated/dsl/dsl-data.js.map +1 -0
  69. package/dist/generated/dsl/handoffs.d.ts +457 -0
  70. package/dist/generated/dsl/handoffs.d.ts.map +1 -0
  71. package/dist/generated/dsl/handoffs.js +205 -0
  72. package/dist/generated/dsl/handoffs.js.map +1 -0
  73. package/dist/generated/dsl/index.d.ts +14 -0
  74. package/dist/generated/dsl/index.d.ts.map +1 -0
  75. package/dist/generated/dsl/index.js +11 -0
  76. package/dist/generated/dsl/index.js.map +1 -0
  77. package/dist/generated/dsl/tasks.d.ts +28 -0
  78. package/dist/generated/dsl/tasks.d.ts.map +1 -0
  79. package/dist/generated/dsl/tasks.js +137 -0
  80. package/dist/generated/dsl/tasks.js.map +1 -0
  81. package/dist/generated/dsl/workflows.d.ts +34 -0
  82. package/dist/generated/dsl/workflows.d.ts.map +1 -0
  83. package/dist/generated/dsl/workflows.js +84 -0
  84. package/dist/generated/dsl/workflows.js.map +1 -0
  85. package/dist/generated/index.d.ts +8 -0
  86. package/dist/generated/index.d.ts.map +1 -0
  87. package/dist/generated/index.js +8 -0
  88. package/dist/generated/index.js.map +1 -0
  89. package/dist/generated/policy-runtime.d.ts +114 -0
  90. package/dist/generated/policy-runtime.d.ts.map +1 -0
  91. package/dist/generated/policy-runtime.js +195 -0
  92. package/dist/generated/policy-runtime.js.map +1 -0
  93. package/dist/generated/policy.d.ts +658 -0
  94. package/dist/generated/policy.d.ts.map +1 -0
  95. package/dist/generated/policy.js +844 -0
  96. package/dist/generated/policy.js.map +1 -0
  97. package/dist/generated/program.d.ts +120 -0
  98. package/dist/generated/program.d.ts.map +1 -0
  99. package/dist/generated/program.js +370 -0
  100. package/dist/generated/program.js.map +1 -0
  101. package/dist/generated/schemas.d.ts +779 -0
  102. package/dist/generated/schemas.d.ts.map +1 -0
  103. package/dist/generated/schemas.js +1006 -0
  104. package/dist/generated/schemas.js.map +1 -0
  105. package/dist/generated/types.d.ts +786 -0
  106. package/dist/generated/types.d.ts.map +1 -0
  107. package/dist/generated/types.js +3 -0
  108. package/dist/generated/types.js.map +1 -0
  109. package/dist/generator/dependencyGenerator.d.ts +16 -0
  110. package/dist/generator/dependencyGenerator.d.ts.map +1 -0
  111. package/dist/generator/dependencyGenerator.js +25 -0
  112. package/dist/generator/dependencyGenerator.js.map +1 -0
  113. package/dist/generator/index.d.ts +47 -0
  114. package/dist/generator/index.d.ts.map +1 -0
  115. package/dist/generator/index.js +707 -0
  116. package/dist/generator/index.js.map +1 -0
  117. package/dist/generator/inputHash.d.ts +23 -0
  118. package/dist/generator/inputHash.d.ts.map +1 -0
  119. package/dist/generator/inputHash.js +138 -0
  120. package/dist/generator/inputHash.js.map +1 -0
  121. package/dist/generator/linter.d.ts +26 -0
  122. package/dist/generator/linter.d.ts.map +1 -0
  123. package/dist/generator/linter.js +441 -0
  124. package/dist/generator/linter.js.map +1 -0
  125. package/dist/generator/overlayProcessor.d.ts +71 -0
  126. package/dist/generator/overlayProcessor.d.ts.map +1 -0
  127. package/dist/generator/overlayProcessor.js +500 -0
  128. package/dist/generator/overlayProcessor.js.map +1 -0
  129. package/dist/generator/schemaGenerator.d.ts +10 -0
  130. package/dist/generator/schemaGenerator.d.ts.map +1 -0
  131. package/dist/generator/schemaGenerator.js +296 -0
  132. package/dist/generator/schemaGenerator.js.map +1 -0
  133. package/dist/generator/serviceGenerator.d.ts +20 -0
  134. package/dist/generator/serviceGenerator.d.ts.map +1 -0
  135. package/dist/generator/serviceGenerator.js +293 -0
  136. package/dist/generator/serviceGenerator.js.map +1 -0
  137. package/dist/generator/templateProcessor.d.ts +208 -0
  138. package/dist/generator/templateProcessor.d.ts.map +1 -0
  139. package/dist/generator/templateProcessor.js +604 -0
  140. package/dist/generator/templateProcessor.js.map +1 -0
  141. package/dist/generator/typeGenerator.d.ts +22 -0
  142. package/dist/generator/typeGenerator.d.ts.map +1 -0
  143. package/dist/generator/typeGenerator.js +439 -0
  144. package/dist/generator/typeGenerator.js.map +1 -0
  145. package/dist/generator/typeGenerator.test.d.ts +2 -0
  146. package/dist/generator/typeGenerator.test.d.ts.map +1 -0
  147. package/dist/generator/typeGenerator.test.js +155 -0
  148. package/dist/generator/typeGenerator.test.js.map +1 -0
  149. package/dist/glob.d.ts +22 -0
  150. package/dist/glob.d.ts.map +1 -0
  151. package/dist/glob.js +103 -0
  152. package/dist/glob.js.map +1 -0
  153. package/dist/guardrails/allowlist.d.ts +30 -0
  154. package/dist/guardrails/allowlist.d.ts.map +1 -0
  155. package/dist/guardrails/allowlist.js +174 -0
  156. package/dist/guardrails/allowlist.js.map +1 -0
  157. package/dist/guardrails/config.d.ts +40 -0
  158. package/dist/guardrails/config.d.ts.map +1 -0
  159. package/dist/guardrails/config.js +177 -0
  160. package/dist/guardrails/config.js.map +1 -0
  161. package/dist/guardrails/drift.d.ts +19 -0
  162. package/dist/guardrails/drift.d.ts.map +1 -0
  163. package/dist/guardrails/drift.js +115 -0
  164. package/dist/guardrails/drift.js.map +1 -0
  165. package/dist/guardrails/index.d.ts +18 -0
  166. package/dist/guardrails/index.d.ts.map +1 -0
  167. package/dist/guardrails/index.js +21 -0
  168. package/dist/guardrails/index.js.map +1 -0
  169. package/dist/guardrails/lint.d.ts +16 -0
  170. package/dist/guardrails/lint.d.ts.map +1 -0
  171. package/dist/guardrails/lint.js +172 -0
  172. package/dist/guardrails/lint.js.map +1 -0
  173. package/dist/guardrails/manifest.d.ts +63 -0
  174. package/dist/guardrails/manifest.d.ts.map +1 -0
  175. package/dist/guardrails/manifest.js +310 -0
  176. package/dist/guardrails/manifest.js.map +1 -0
  177. package/dist/guardrails/runner.d.ts +53 -0
  178. package/dist/guardrails/runner.d.ts.map +1 -0
  179. package/dist/guardrails/runner.js +387 -0
  180. package/dist/guardrails/runner.js.map +1 -0
  181. package/dist/guardrails/types.d.ts +196 -0
  182. package/dist/guardrails/types.d.ts.map +1 -0
  183. package/dist/guardrails/types.js +8 -0
  184. package/dist/guardrails/types.js.map +1 -0
  185. package/dist/index.d.ts +21 -4
  186. package/dist/index.d.ts.map +1 -0
  187. package/dist/index.js +21 -4
  188. package/dist/index.js.map +1 -0
  189. package/dist/micro-contracts.bundle.mjs +349 -374
  190. package/dist/micro-contracts.bundle.mjs.map +3 -3
  191. package/dist/types.d.ts +502 -0
  192. package/dist/types.d.ts.map +1 -0
  193. package/dist/types.js +409 -0
  194. package/dist/types.js.map +1 -0
  195. package/dist/version.d.ts +10 -0
  196. package/dist/version.d.ts.map +1 -0
  197. package/dist/version.js +31 -0
  198. package/dist/version.js.map +1 -0
  199. package/docs/cli-reference.md +13 -15
  200. package/docs/development-guardrails.md +3 -3
  201. package/docs/screen-spec.md +3 -3
  202. package/package.json +13 -12
@@ -0,0 +1,441 @@
1
+ /**
2
+ * OpenAPI specification linter
3
+ *
4
+ * Validates x-public/x-private constraints
5
+ */
6
+ import { isReference, getRefName, hasPrivateProperties, collectReferencedSchemas, collectReachableComponents, isTsIdentifier } from '../types.js';
7
+ /**
8
+ * Lint OpenAPI specification for x-public/x-private violations
9
+ */
10
+ export function lintSpec(spec, options = {}) {
11
+ const errors = [];
12
+ const warnings = [];
13
+ const eventDefs = spec.components?.['x-event-defs'] ?? {};
14
+ // Check each operation
15
+ for (const [path, pathItem] of Object.entries(spec.paths)) {
16
+ for (const method of ['get', 'post', 'put', 'patch', 'delete']) {
17
+ const operation = pathItem[method];
18
+ if (!operation)
19
+ continue;
20
+ const location = `${method.toUpperCase()} ${path}`;
21
+ // Routes, service interfaces and template contexts are all keyed by these
22
+ // extensions: an operation without them is dropped from every artifact.
23
+ // In screen mode operations are consumed via ScreenContext instead.
24
+ if (!options.screen) {
25
+ const service = operation['x-micro-contracts-service'];
26
+ const serviceMethod = operation['x-micro-contracts-method'];
27
+ if (!service) {
28
+ errors.push({
29
+ type: 'error',
30
+ code: 'MISSING_X_SERVICE',
31
+ message: `Missing x-micro-contracts-service extension (operation would be dropped from routes and services)`,
32
+ path,
33
+ location,
34
+ });
35
+ }
36
+ else if (!isTsIdentifier(service)) {
37
+ errors.push({
38
+ type: 'error',
39
+ code: 'INVALID_X_SERVICE',
40
+ message: `x-micro-contracts-service '${service}' is not a valid TypeScript identifier (used verbatim in generated type and interface names)`,
41
+ path,
42
+ location,
43
+ });
44
+ }
45
+ if (!serviceMethod) {
46
+ errors.push({
47
+ type: 'error',
48
+ code: 'MISSING_X_METHOD',
49
+ message: `Missing x-micro-contracts-method extension (operation would be dropped from routes and services)`,
50
+ path,
51
+ location,
52
+ });
53
+ }
54
+ else if (!isTsIdentifier(serviceMethod)) {
55
+ errors.push({
56
+ type: 'error',
57
+ code: 'INVALID_X_METHOD',
58
+ message: `x-micro-contracts-method '${serviceMethod}' is not a valid TypeScript identifier (used verbatim in generated method and type names)`,
59
+ path,
60
+ location,
61
+ });
62
+ }
63
+ }
64
+ // Screen spec consistency: if x-screen-id is present, require x-screen-const and x-screen-name
65
+ if (operation['x-screen-id']) {
66
+ if (!operation['x-screen-const']) {
67
+ errors.push({
68
+ type: 'error',
69
+ code: 'SCREEN_MISSING_CONST',
70
+ message: `Operation has x-screen-id but missing x-screen-const`,
71
+ path,
72
+ location,
73
+ });
74
+ }
75
+ if (!operation['x-screen-name']) {
76
+ errors.push({
77
+ type: 'error',
78
+ code: 'SCREEN_MISSING_NAME',
79
+ message: `Operation has x-screen-id but missing x-screen-name`,
80
+ path,
81
+ location,
82
+ });
83
+ }
84
+ if (!operation.operationId) {
85
+ errors.push({
86
+ type: 'error',
87
+ code: 'SCREEN_MISSING_OPERATION_ID',
88
+ message: `Screen operation requires operationId`,
89
+ path,
90
+ location,
91
+ });
92
+ }
93
+ }
94
+ // Deprecated x-events validation (warn + still validate structure)
95
+ if (operation['x-events']) {
96
+ warnings.push({
97
+ type: 'warning',
98
+ code: 'SCREEN_DEPRECATED_X_EVENTS',
99
+ message: 'x-events (flat list) is deprecated. Use inline x-event instead.',
100
+ path,
101
+ location,
102
+ });
103
+ const events = operation['x-events'];
104
+ if (!Array.isArray(events)) {
105
+ errors.push({
106
+ type: 'error',
107
+ code: 'SCREEN_INVALID_EVENTS',
108
+ message: `x-events must be an array`,
109
+ path,
110
+ location,
111
+ });
112
+ }
113
+ else {
114
+ for (let i = 0; i < events.length; i++) {
115
+ const event = events[i];
116
+ if (!event.name || !event.type) {
117
+ errors.push({
118
+ type: 'error',
119
+ code: 'SCREEN_INVALID_EVENT',
120
+ message: `x-events[${i}] must have name and type`,
121
+ path,
122
+ location,
123
+ });
124
+ }
125
+ }
126
+ }
127
+ }
128
+ // Conflicting x-events + x-event on same operation
129
+ if (operation['x-events'] && operation['x-event'] != null) {
130
+ errors.push({
131
+ type: 'error',
132
+ code: 'SCREEN_CONFLICTING_EVENT_DEFS',
133
+ message: 'x-events and x-event cannot coexist on the same operation',
134
+ path,
135
+ location,
136
+ });
137
+ }
138
+ // Validate inline x-event on this operation (any method)
139
+ if (operation['x-event'] != null) {
140
+ validateInlineEvent(operation['x-event'], path, location, errors, eventDefs);
141
+ }
142
+ // Validate x-event on links (200 response only, GET operations)
143
+ if (method === 'get') {
144
+ const resp200 = operation.responses?.['200'];
145
+ if (resp200 && !isReference(resp200)) {
146
+ const responseLinks = resp200.links;
147
+ if (responseLinks) {
148
+ for (const [linkName, linkObj] of Object.entries(responseLinks)) {
149
+ if (linkObj['x-event'] != null) {
150
+ validateInlineEvent(linkObj['x-event'], `${path}.responses.200.links.${linkName}`, location, errors, eventDefs);
151
+ }
152
+ }
153
+ }
154
+ }
155
+ // Validate x-interactions
156
+ if (operation['x-interactions']) {
157
+ const interactions = operation['x-interactions'];
158
+ if (!Array.isArray(interactions)) {
159
+ errors.push({
160
+ type: 'error',
161
+ code: 'SCREEN_INVALID_INTERACTIONS',
162
+ message: 'x-interactions must be an array',
163
+ path,
164
+ location,
165
+ });
166
+ }
167
+ else {
168
+ for (let i = 0; i < interactions.length; i++) {
169
+ if (!interactions[i].name) {
170
+ errors.push({
171
+ type: 'error',
172
+ code: 'SCREEN_INVALID_INTERACTION',
173
+ message: `x-interactions[${i}] must have a name`,
174
+ path,
175
+ location,
176
+ });
177
+ }
178
+ if (interactions[i]['x-event'] != null) {
179
+ validateInlineEvent(interactions[i]['x-event'], `${path}.x-interactions[${i}]`, location, errors, eventDefs);
180
+ }
181
+ }
182
+ }
183
+ }
184
+ }
185
+ // Check public endpoints for private schema references
186
+ if (operation['x-micro-contracts-published'] === true) {
187
+ const privateErrors = checkPublicEndpointForPrivate(path, method, operation, spec);
188
+ errors.push(...privateErrors);
189
+ // Check for allOf/oneOf/anyOf in public endpoint schemas
190
+ const compositionWarnings = checkPublicEndpointComposition(path, method, operation, spec);
191
+ warnings.push(...compositionWarnings);
192
+ }
193
+ }
194
+ }
195
+ // Check schemas for x-private in required (warning - may indicate design issue)
196
+ if (spec.components?.schemas) {
197
+ for (const [schemaName, schema] of Object.entries(spec.components.schemas)) {
198
+ if (isReference(schema))
199
+ continue;
200
+ const privateInRequired = checkPrivateInRequired(schemaName, schema);
201
+ warnings.push(...privateInRequired);
202
+ }
203
+ }
204
+ const valid = errors.length === 0 && (!options.strict || warnings.length === 0);
205
+ return { errors, warnings, valid };
206
+ }
207
+ /**
208
+ * Check if a public endpoint references schemas with x-private properties
209
+ */
210
+ function checkPublicEndpointForPrivate(path, method, operation, spec) {
211
+ const errors = [];
212
+ const location = `${method.toUpperCase()} ${path}`;
213
+ // Every part of the operation that reaches a schema is checked, through
214
+ // $ref into any component section, and for every status code: whatever the
215
+ // published contract pulls in must be visible here.
216
+ const sections = [
217
+ { code: 'PUBLIC_ENDPOINT_PRIVATE_REQUEST', label: 'request', root: operation.requestBody },
218
+ { code: 'PUBLIC_ENDPOINT_PRIVATE_RESPONSE', label: 'response', root: operation.responses },
219
+ { code: 'PUBLIC_ENDPOINT_PRIVATE_PARAMETER', label: 'parameter', root: operation.parameters },
220
+ ];
221
+ // An operation cannot be both published and non-exportable.
222
+ if (operation['x-micro-contracts-non-exportable']) {
223
+ errors.push({
224
+ type: 'error',
225
+ code: 'PUBLIC_ENDPOINT_NON_EXPORTABLE',
226
+ message: 'Operation is x-micro-contracts-published and x-micro-contracts-non-exportable',
227
+ path,
228
+ location,
229
+ });
230
+ }
231
+ for (const section of sections) {
232
+ if (!section.root)
233
+ continue;
234
+ for (const schemaRef of findReachableSchemas(section.root, spec, s => hasPrivateProperties(s, spec))) {
235
+ errors.push({
236
+ type: 'error',
237
+ code: section.code,
238
+ message: `Public endpoint references ${section.label} schema "${schemaRef}" with x-private properties`,
239
+ path,
240
+ location,
241
+ });
242
+ }
243
+ for (const schemaRef of findReachableSchemas(section.root, spec, s => s['x-micro-contracts-non-exportable'] === true)) {
244
+ errors.push({
245
+ type: 'error',
246
+ code: 'PUBLIC_ENDPOINT_NON_EXPORTABLE',
247
+ message: `Public endpoint references ${section.label} schema "${schemaRef}" marked x-micro-contracts-non-exportable`,
248
+ path,
249
+ location,
250
+ });
251
+ }
252
+ }
253
+ return errors;
254
+ }
255
+ /**
256
+ * Names of schemas reachable from `root` (part of an operation) that `matches`
257
+ * accepts. Every rule about "what the public surface pulls in" asks this same
258
+ * question, over the same reachability, so no rule can see a narrower graph.
259
+ *
260
+ * Inline schemas are reported as "inline schema"; named ones by component name.
261
+ */
262
+ function findReachableSchemas(root, spec, matches) {
263
+ const found = [];
264
+ // Named components reachable from here, including across responses,
265
+ // requestBodies and parameters.
266
+ for (const pointer of collectReachableComponents(root, spec)) {
267
+ const [section, name] = [pointer.slice(0, pointer.indexOf('/')), pointer.slice(pointer.indexOf('/') + 1)];
268
+ if (section !== 'schemas')
269
+ continue;
270
+ const schema = spec.components?.schemas?.[name];
271
+ if (schema && matches(schema)) {
272
+ found.push(name);
273
+ }
274
+ }
275
+ // Inline schemas: reachable but unnamed, so they carry no component pointer.
276
+ for (const schema of collectInlineSchemas(root)) {
277
+ if (matches(schema)) {
278
+ found.push('inline schema');
279
+ }
280
+ }
281
+ return [...new Set(found)];
282
+ }
283
+ /** Inline (non-$ref) values of `schema` keys anywhere under `root`. */
284
+ function collectInlineSchemas(root) {
285
+ const schemas = [];
286
+ const pending = [root];
287
+ while (pending.length > 0) {
288
+ const node = pending.pop();
289
+ if (!node || typeof node !== 'object')
290
+ continue;
291
+ if (Array.isArray(node)) {
292
+ pending.push(...node);
293
+ continue;
294
+ }
295
+ const record = node;
296
+ const schema = record.schema;
297
+ if (schema && typeof schema === 'object' && !isReference(schema)) {
298
+ schemas.push(schema);
299
+ }
300
+ pending.push(...Object.values(record));
301
+ }
302
+ return schemas;
303
+ }
304
+ /**
305
+ * Check for allOf/oneOf/anyOf in public endpoint schemas (warning)
306
+ */
307
+ function checkPublicEndpointComposition(path, method, operation, spec) {
308
+ const warnings = [];
309
+ const location = `${method.toUpperCase()} ${path}`;
310
+ // Collect all referenced schemas
311
+ const referencedSchemas = new Set();
312
+ if (operation.requestBody && !isReference(operation.requestBody)) {
313
+ const content = operation.requestBody.content?.['application/json'];
314
+ if (content?.schema) {
315
+ collectReferencedSchemas(content.schema, spec, referencedSchemas);
316
+ }
317
+ }
318
+ for (const response of Object.values(operation.responses)) {
319
+ const resp = isReference(response)
320
+ ? spec.components?.responses?.[getRefName(response.$ref)]
321
+ : response;
322
+ if (resp?.content?.['application/json']?.schema) {
323
+ collectReferencedSchemas(resp.content['application/json'].schema, spec, referencedSchemas);
324
+ }
325
+ }
326
+ // Check each referenced schema for composition
327
+ for (const schemaName of referencedSchemas) {
328
+ const schema = spec.components?.schemas?.[schemaName];
329
+ if (!schema || isReference(schema))
330
+ continue;
331
+ if (schema.allOf || schema.oneOf || schema.anyOf) {
332
+ warnings.push({
333
+ type: 'warning',
334
+ code: 'PUBLIC_ENDPOINT_COMPOSITION',
335
+ message: `Public endpoint uses schema "${schemaName}" with allOf/oneOf/anyOf (may complicate compatibility)`,
336
+ path,
337
+ location,
338
+ });
339
+ }
340
+ }
341
+ return warnings;
342
+ }
343
+ /**
344
+ * Check if x-private properties are in required array
345
+ * This is a warning because it may indicate a design issue
346
+ * (the schema cannot be promoted to public use without removing the property)
347
+ */
348
+ function checkPrivateInRequired(schemaName, schema) {
349
+ const warnings = [];
350
+ if (!schema.properties || !schema.required)
351
+ return warnings;
352
+ for (const propName of schema.required) {
353
+ const prop = schema.properties[propName];
354
+ if (prop && !isReference(prop) && prop['x-private']) {
355
+ warnings.push({
356
+ type: 'warning',
357
+ code: 'PRIVATE_IN_REQUIRED',
358
+ message: `Schema "${schemaName}" has x-private property "${propName}" in required array (cannot be used in public endpoints)`,
359
+ location: `components/schemas/${schemaName}`,
360
+ });
361
+ }
362
+ }
363
+ return warnings;
364
+ }
365
+ /**
366
+ * Validate an inline x-event value (string, {name}, or {$ref}).
367
+ */
368
+ function validateInlineEvent(raw, path, location, errors, eventDefs = {}) {
369
+ if (typeof raw === 'string')
370
+ return; // valid string form
371
+ if (typeof raw !== 'object' || raw === null) {
372
+ errors.push({
373
+ type: 'error',
374
+ code: 'SCREEN_INVALID_X_EVENT',
375
+ message: 'x-event must be a string, object with {name}, or {$ref}',
376
+ path,
377
+ location,
378
+ });
379
+ return;
380
+ }
381
+ const obj = raw;
382
+ if (!obj.$ref && !obj.name) {
383
+ errors.push({
384
+ type: 'error',
385
+ code: 'SCREEN_INVALID_X_EVENT',
386
+ message: 'x-event object must have either $ref or name',
387
+ path,
388
+ location,
389
+ });
390
+ return;
391
+ }
392
+ if (typeof obj.$ref === 'string' && obj.$ref.startsWith('#/components/x-event-defs/')) {
393
+ const defName = obj.$ref.split('/').pop();
394
+ if (!(defName in eventDefs)) {
395
+ errors.push({
396
+ type: 'error',
397
+ code: 'SCREEN_UNKNOWN_EVENT_REF',
398
+ message: `x-event references '${obj.$ref}' but components.x-event-defs has no '${defName}' ` +
399
+ `(defined: ${Object.keys(eventDefs).join(', ') || 'none'})`,
400
+ path,
401
+ location,
402
+ });
403
+ }
404
+ }
405
+ }
406
+ /**
407
+ * Format lint results for console output
408
+ */
409
+ export function formatLintResults(result) {
410
+ const lines = [];
411
+ if (result.errors.length > 0) {
412
+ lines.push('Errors:');
413
+ for (const error of result.errors) {
414
+ lines.push(` ❌ [${error.code}] ${error.message}`);
415
+ if (error.location)
416
+ lines.push(` at ${error.location}`);
417
+ }
418
+ lines.push('');
419
+ }
420
+ if (result.warnings.length > 0) {
421
+ lines.push('Warnings:');
422
+ for (const warning of result.warnings) {
423
+ lines.push(` ⚠️ [${warning.code}] ${warning.message}`);
424
+ if (warning.location)
425
+ lines.push(` at ${warning.location}`);
426
+ }
427
+ lines.push('');
428
+ }
429
+ if (result.valid) {
430
+ lines.push('✅ Lint passed');
431
+ }
432
+ else if (result.errors.length === 0) {
433
+ // Only reachable under --strict, where warnings decide the outcome.
434
+ lines.push(`❌ Lint failed with ${result.warnings.length} warning(s) (strict)`);
435
+ }
436
+ else {
437
+ lines.push(`❌ Lint failed with ${result.errors.length} error(s)`);
438
+ }
439
+ return lines.join('\n');
440
+ }
441
+ //# sourceMappingURL=linter.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"linter.js","sourceRoot":"","sources":["../../src/generator/linter.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,71 @@
1
+ /**
2
+ * OpenAPI Overlay Processor
3
+ *
4
+ * Implements OpenAPI Overlay Specification for cross-cutting concerns.
5
+ * Parses overlays and applies transformations to OpenAPI specs.
6
+ */
7
+ import type { OpenAPISpec, ParameterObject, ResponseObject } from '../types.js';
8
+ export interface ExtensionInfo {
9
+ /** Extension name (e.g., 'requireAuth', 'tenantIsolation') */
10
+ name: string;
11
+ /** Extension marker (e.g., 'x-middleware') */
12
+ marker: string;
13
+ /** Parameters injected by this extension */
14
+ injectedParameters: ParameterObject[];
15
+ /** Responses injected by this extension */
16
+ injectedResponses: Record<string, ResponseObject>;
17
+ }
18
+ export interface OverlayResult {
19
+ /** Transformed OpenAPI spec */
20
+ spec: OpenAPISpec;
21
+ /** Extension information extracted from overlays */
22
+ extensionInfo: Map<string, ExtensionInfo>;
23
+ /** List of applied overlays */
24
+ appliedOverlays: string[];
25
+ /** Application log */
26
+ log: OverlayApplicationLog[];
27
+ }
28
+ interface OverlayApplicationLog {
29
+ overlay: string;
30
+ target: string;
31
+ path: string;
32
+ method: string;
33
+ changes: string[];
34
+ }
35
+ export interface OverlayConfig {
36
+ /** Collision policy: error | warn | last-wins */
37
+ collision?: 'error' | 'warn' | 'last-wins';
38
+ /** Overlay files to apply in order */
39
+ files: string[];
40
+ }
41
+ /**
42
+ * Process overlays and apply to OpenAPI spec
43
+ *
44
+ * @param spec - Source OpenAPI spec
45
+ * @param overlayConfig - Overlay configuration
46
+ * @param basePath - Base path for resolving overlay file paths
47
+ * @param specPath - Path to the source spec file (for $ref rebasing)
48
+ */
49
+ export declare function processOverlays(spec: OpenAPISpec, overlayConfig: OverlayConfig, basePath?: string, specPath?: string): OverlayResult;
50
+ /**
51
+ * Rebase $ref paths in an object from source directory to target directory
52
+ *
53
+ * @param obj - Object that may contain $ref properties
54
+ * @param sourceDir - Directory where the source file is located (e.g., overlay or OpenAPI source)
55
+ * @param targetDir - Directory where the output file will be written
56
+ * @returns Object with rebased $ref paths
57
+ */
58
+ export declare function rebaseRefs<T>(obj: T, sourceDir?: string, targetDir?: string): T;
59
+ /**
60
+ * Generate TypeScript interfaces for overlays
61
+ *
62
+ * These interfaces are HTTP-agnostic. The HTTP layer (routes template)
63
+ * extracts parameters from the request and passes them to overlay handlers.
64
+ */
65
+ export declare function generateExtensionInterfaces(extensionInfo: Map<string, ExtensionInfo>): string;
66
+ /**
67
+ * Format overlay application log for console output
68
+ */
69
+ export declare function formatOverlayLog(result: OverlayResult): string;
70
+ export {};
71
+ //# sourceMappingURL=overlayProcessor.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"overlayProcessor.d.ts","sourceRoot":"","sources":["../../src/generator/overlayProcessor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAmB,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAwBjG,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,kBAAkB,EAAE,eAAe,EAAE,CAAC;IACtC,2CAA2C;IAC3C,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,aAAa;IAC5B,+BAA+B;IAC/B,IAAI,EAAE,WAAW,CAAC;IAClB,oDAAoD;IACpD,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC1C,+BAA+B;IAC/B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,sBAAsB;IACtB,GAAG,EAAE,qBAAqB,EAAE,CAAC;CAC9B;AAED,UAAU,qBAAqB;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC;IAC3C,sCAAsC;IACtC,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAMD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,WAAW,EACjB,aAAa,EAAE,aAAa,EAC5B,QAAQ,GAAE,MAAsB,EAChC,QAAQ,CAAC,EAAE,MAAM,GAChB,aAAa,CA4Cf;AA2LD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAO/E;AAoJD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GACxC,MAAM,CAqJR;AA2CD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAa9D"}