@bleedingdev/modern-js-ultramodern-create 3.9.0-ultramodern.2 → 3.9.0-ultramodern.3

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 (65) hide show
  1. package/dist/cjs/ultramodern-tooling/commands/migrate-strict-effect/generated-artifacts-typescript.cjs +1 -0
  2. package/dist/cjs/ultramodern-tooling/commands/migrate-strict-effect/package-cohort.cjs +2 -0
  3. package/dist/cjs/ultramodern-tooling/commands/migrate-strict-effect/shared-api-infrastructure.cjs +99 -0
  4. package/dist/cjs/ultramodern-tooling/commands/migrate-strict-effect/toolchain-pins.cjs +1 -0
  5. package/dist/cjs/ultramodern-tooling/commands/migrate-strict-effect.cjs +2 -0
  6. package/dist/cjs/ultramodern-workspace/api/client.cjs +2 -2
  7. package/dist/cjs/ultramodern-workspace/api/service.cjs +45 -16
  8. package/dist/cjs/ultramodern-workspace/api/shared.cjs +26 -16
  9. package/dist/cjs/ultramodern-workspace/mf-validation/inspect.cjs +6 -2
  10. package/dist/cjs/ultramodern-workspace/module-federation/reexport-module.cjs +0 -5
  11. package/dist/cjs/ultramodern-workspace/package-json.cjs +12 -1
  12. package/dist/cjs/ultramodern-workspace/policy.cjs +1 -0
  13. package/dist/cjs/ultramodern-workspace/tsconfigs.cjs +3 -0
  14. package/dist/cjs/ultramodern-workspace/workspace-script-plan.cjs +1 -1
  15. package/dist/cjs/ultramodern-workspace/workspace-scripts.cjs +5 -0
  16. package/dist/cjs/ultramodern-workspace/write-app.cjs +9 -3
  17. package/dist/cjs/ultramodern-workspace/write-workspace.cjs +5 -3
  18. package/dist/esm/ultramodern-tooling/commands/migrate-strict-effect/generated-artifacts-typescript.js +1 -0
  19. package/dist/esm/ultramodern-tooling/commands/migrate-strict-effect/package-cohort.js +2 -0
  20. package/dist/esm/ultramodern-tooling/commands/migrate-strict-effect/shared-api-infrastructure.js +50 -0
  21. package/dist/esm/ultramodern-tooling/commands/migrate-strict-effect/toolchain-pins.js +1 -0
  22. package/dist/esm/ultramodern-tooling/commands/migrate-strict-effect.js +2 -0
  23. package/dist/esm/ultramodern-workspace/api/client.js +2 -2
  24. package/dist/esm/ultramodern-workspace/api/service.js +45 -16
  25. package/dist/esm/ultramodern-workspace/api/shared.js +27 -17
  26. package/dist/esm/ultramodern-workspace/mf-validation/inspect.js +6 -2
  27. package/dist/esm/ultramodern-workspace/module-federation/reexport-module.js +0 -5
  28. package/dist/esm/ultramodern-workspace/package-json.js +12 -1
  29. package/dist/esm/ultramodern-workspace/policy.js +1 -0
  30. package/dist/esm/ultramodern-workspace/tsconfigs.js +3 -0
  31. package/dist/esm/ultramodern-workspace/workspace-script-plan.js +1 -1
  32. package/dist/esm/ultramodern-workspace/workspace-scripts.js +5 -0
  33. package/dist/esm/ultramodern-workspace/write-app.js +9 -3
  34. package/dist/esm/ultramodern-workspace/write-workspace.js +6 -4
  35. package/dist/esm-node/ultramodern-tooling/commands/migrate-strict-effect/generated-artifacts-typescript.js +1 -0
  36. package/dist/esm-node/ultramodern-tooling/commands/migrate-strict-effect/package-cohort.js +2 -0
  37. package/dist/esm-node/ultramodern-tooling/commands/migrate-strict-effect/shared-api-infrastructure.js +51 -0
  38. package/dist/esm-node/ultramodern-tooling/commands/migrate-strict-effect/toolchain-pins.js +1 -0
  39. package/dist/esm-node/ultramodern-tooling/commands/migrate-strict-effect.js +2 -0
  40. package/dist/esm-node/ultramodern-workspace/api/client.js +2 -2
  41. package/dist/esm-node/ultramodern-workspace/api/service.js +45 -16
  42. package/dist/esm-node/ultramodern-workspace/api/shared.js +27 -17
  43. package/dist/esm-node/ultramodern-workspace/mf-validation/inspect.js +6 -2
  44. package/dist/esm-node/ultramodern-workspace/module-federation/reexport-module.js +0 -5
  45. package/dist/esm-node/ultramodern-workspace/package-json.js +12 -1
  46. package/dist/esm-node/ultramodern-workspace/policy.js +1 -0
  47. package/dist/esm-node/ultramodern-workspace/tsconfigs.js +3 -0
  48. package/dist/esm-node/ultramodern-workspace/workspace-script-plan.js +1 -1
  49. package/dist/esm-node/ultramodern-workspace/workspace-scripts.js +5 -0
  50. package/dist/esm-node/ultramodern-workspace/write-app.js +9 -3
  51. package/dist/esm-node/ultramodern-workspace/write-workspace.js +6 -4
  52. package/dist/types/ultramodern-tooling/commands/migrate-strict-effect/shared-api-infrastructure.d.ts +4 -0
  53. package/dist/types/ultramodern-workspace/api/client.d.ts +3 -1
  54. package/dist/types/ultramodern-workspace/api/service.d.ts +3 -1
  55. package/dist/types/ultramodern-workspace/api/shared.d.ts +2 -0
  56. package/dist/types/ultramodern-workspace/package-json.d.ts +1 -1
  57. package/dist/types/ultramodern-workspace/policy.d.ts +2 -0
  58. package/package.json +4 -4
  59. package/template-workspace/.modernjs/release-cohort.json +40 -40
  60. package/templates/packages/effect-bff-runtime.ts +50 -0
  61. package/templates/packages/microvertical-api-baseline.ts +102 -0
  62. package/templates/workspace-scripts/check-ultramodern-api-boundaries.mts +49 -28
  63. package/templates/workspace-scripts/microvertical-api-baseline-boundary.mts +944 -0
  64. package/templates/workspace-scripts/ultramodern-cloudflare-proof.mjs +25 -7
  65. package/templates/workspace-scripts/validate-ultramodern-workspace.mjs.handlebars +1 -1
@@ -0,0 +1,944 @@
1
+ import fs from 'node:fs';
2
+ import { createRequire } from 'node:module';
3
+ import path from 'node:path';
4
+ import {
5
+ isAsExpression,
6
+ isCallExpression,
7
+ isExportDeclaration,
8
+ isIdentifier,
9
+ isImportDeclaration,
10
+ isNamedExports,
11
+ isNamedImports,
12
+ isNumericLiteral,
13
+ isObjectLiteralExpression,
14
+ isParenthesizedExpression,
15
+ isPropertyAccessExpression,
16
+ isPropertyAssignment,
17
+ isSatisfiesExpression,
18
+ isSpreadAssignment,
19
+ isStringLiteralLikeNode,
20
+ isVariableStatement,
21
+ NodeFlags,
22
+ SyntaxKind,
23
+ } from '@typescript/native/unstable/ast';
24
+ import type {
25
+ CallExpression,
26
+ Expression,
27
+ Node,
28
+ ObjectLiteralElementLike,
29
+ ObjectLiteralExpression,
30
+ PropertyAssignment,
31
+ SourceFile,
32
+ VariableDeclaration,
33
+ } from '@typescript/native/unstable/ast';
34
+ import { API as TypeScriptApi } from '@typescript/native/unstable/sync';
35
+
36
+ const camelCaseStem = (stem: string): string =>
37
+ stem.replaceAll(/-(?<letter>[a-z0-9])/gu, (_match, letter: string) =>
38
+ letter.toUpperCase(),
39
+ );
40
+
41
+ const pascalCaseStem = (stem: string): string => {
42
+ const camelStem = camelCaseStem(stem);
43
+ return `${camelStem.slice(0, 1).toUpperCase()}${camelStem.slice(1)}`;
44
+ };
45
+
46
+ const identifierName = (node: Node | undefined): string | undefined =>
47
+ node !== undefined && isIdentifier(node) ? node.text : undefined;
48
+
49
+ const propertyName = (node: Node | undefined): string | undefined => {
50
+ if (
51
+ node !== undefined &&
52
+ (isIdentifier(node) ||
53
+ isStringLiteralLikeNode(node) ||
54
+ isNumericLiteral(node))
55
+ ) {
56
+ return node.text;
57
+ }
58
+ return undefined;
59
+ };
60
+
61
+ const accessPath = (node: Expression): readonly string[] | undefined => {
62
+ if (isIdentifier(node)) {
63
+ return [node.text];
64
+ }
65
+ if (isPropertyAccessExpression(node)) {
66
+ const parent = accessPath(node.expression);
67
+ return parent === undefined ? undefined : [...parent, node.name.text];
68
+ }
69
+ return undefined;
70
+ };
71
+
72
+ const isAccessPath = (
73
+ node: Expression,
74
+ expected: readonly string[],
75
+ ): boolean => accessPath(node)?.join('.') === expected.join('.');
76
+
77
+ const unwrapExpression = (expression: Expression): Expression => {
78
+ let current = expression;
79
+ while (
80
+ isAsExpression(current) ||
81
+ isParenthesizedExpression(current) ||
82
+ isSatisfiesExpression(current)
83
+ ) {
84
+ current = current.expression;
85
+ }
86
+ return current;
87
+ };
88
+
89
+ const stringLiteral = (
90
+ expression: Expression | undefined,
91
+ ): string | undefined => {
92
+ if (expression === undefined) {
93
+ return undefined;
94
+ }
95
+ const unwrapped = unwrapExpression(expression);
96
+ return isStringLiteralLikeNode(unwrapped) ? unwrapped.text : undefined;
97
+ };
98
+
99
+ const numericLiteral = (
100
+ expression: Expression | undefined,
101
+ ): number | undefined => {
102
+ if (expression === undefined) {
103
+ return undefined;
104
+ }
105
+ const unwrapped = unwrapExpression(expression);
106
+ return isNumericLiteral(unwrapped) ? Number(unwrapped.text) : undefined;
107
+ };
108
+
109
+ const callExpression = (
110
+ expression: Expression | undefined,
111
+ callee: readonly string[],
112
+ ): CallExpression | undefined => {
113
+ if (expression === undefined) {
114
+ return undefined;
115
+ }
116
+ const unwrapped = unwrapExpression(expression);
117
+ return isCallExpression(unwrapped) &&
118
+ isAccessPath(unwrapped.expression, callee)
119
+ ? unwrapped
120
+ : undefined;
121
+ };
122
+
123
+ const exportedConst = (
124
+ sourceFile: SourceFile,
125
+ name: string,
126
+ ): VariableDeclaration | undefined => {
127
+ for (const statement of sourceFile.statements) {
128
+ if (
129
+ !isVariableStatement(statement) ||
130
+ !(
131
+ statement.modifiers?.some(
132
+ modifier => modifier.kind === SyntaxKind.ExportKeyword,
133
+ ) ?? false
134
+ ) ||
135
+ statement.declarationList.flags !== NodeFlags.Const
136
+ ) {
137
+ continue;
138
+ }
139
+ const declarations = statement.declarationList.declarations.filter(
140
+ declaration => identifierName(declaration.name) === name,
141
+ );
142
+ if (declarations.length === 1) {
143
+ return declarations[0];
144
+ }
145
+ }
146
+ return undefined;
147
+ };
148
+
149
+ const localConst = (
150
+ sourceFile: SourceFile,
151
+ name: string,
152
+ ): VariableDeclaration | undefined => {
153
+ for (const statement of sourceFile.statements) {
154
+ if (
155
+ !isVariableStatement(statement) ||
156
+ statement.declarationList.flags !== NodeFlags.Const
157
+ ) {
158
+ continue;
159
+ }
160
+ const declarations = statement.declarationList.declarations.filter(
161
+ declaration => identifierName(declaration.name) === name,
162
+ );
163
+ if (declarations.length === 1) {
164
+ return declarations[0];
165
+ }
166
+ }
167
+ return undefined;
168
+ };
169
+
170
+ const objectLiteral = (
171
+ expression: Expression | undefined,
172
+ ): ObjectLiteralExpression | undefined => {
173
+ if (expression === undefined) {
174
+ return undefined;
175
+ }
176
+ const unwrapped = unwrapExpression(expression);
177
+ return isObjectLiteralExpression(unwrapped) ? unwrapped : undefined;
178
+ };
179
+
180
+ const propertyAssignments = (
181
+ properties: readonly ObjectLiteralElementLike[],
182
+ ): ReadonlyMap<string, PropertyAssignment> | undefined => {
183
+ const assignments = new Map<string, PropertyAssignment>();
184
+ for (const property of properties) {
185
+ if (!isPropertyAssignment(property)) {
186
+ return undefined;
187
+ }
188
+ const name = propertyName(property.name);
189
+ if (name === undefined || assignments.has(name)) {
190
+ return undefined;
191
+ }
192
+ assignments.set(name, property);
193
+ }
194
+ return assignments;
195
+ };
196
+
197
+ const exactCall = (
198
+ expression: Expression | undefined,
199
+ callee: readonly string[],
200
+ argumentCount: number,
201
+ ): CallExpression | undefined => {
202
+ const call = callExpression(expression, callee);
203
+ return call?.arguments.length === argumentCount ? call : undefined;
204
+ };
205
+
206
+ interface SharedSchemaObject {
207
+ readonly assignments: ReadonlyMap<string, PropertyAssignment>;
208
+ readonly identity: boolean;
209
+ }
210
+
211
+ const sharedSchemaObject = (
212
+ declaration: VariableDeclaration | undefined,
213
+ sharedSchemaName: string,
214
+ protectedFields: readonly string[],
215
+ ): SharedSchemaObject | undefined => {
216
+ if (declaration?.initializer === undefined) {
217
+ return undefined;
218
+ }
219
+ const initializer = unwrapExpression(declaration.initializer);
220
+ if (isIdentifier(initializer) && initializer.text === sharedSchemaName) {
221
+ return { assignments: new Map(), identity: true };
222
+ }
223
+ const struct = exactCall(initializer, ['Schema', 'Struct'], 1);
224
+ const schemaObject = objectLiteral(struct?.arguments[0]);
225
+ if (schemaObject === undefined) {
226
+ return undefined;
227
+ }
228
+ const spreads = schemaObject.properties.filter(isSpreadAssignment);
229
+ const assignments = propertyAssignments(
230
+ schemaObject.properties.filter(property => !isSpreadAssignment(property)),
231
+ );
232
+ if (
233
+ spreads.length !== 1 ||
234
+ !spreads.every(spread =>
235
+ isAccessPath(spread.expression, [sharedSchemaName, 'fields']),
236
+ ) ||
237
+ assignments === undefined ||
238
+ protectedFields.some(field => assignments.has(field))
239
+ ) {
240
+ return undefined;
241
+ }
242
+ return { assignments, identity: false };
243
+ };
244
+
245
+ interface DirectCallChain {
246
+ readonly base: CallExpression;
247
+ readonly methods: readonly {
248
+ readonly arguments: readonly Expression[];
249
+ readonly name: string;
250
+ }[];
251
+ }
252
+
253
+ const directCallChain = (
254
+ expression: Expression | undefined,
255
+ ): DirectCallChain | undefined => {
256
+ if (expression === undefined) {
257
+ return undefined;
258
+ }
259
+ let current = unwrapExpression(expression);
260
+ const methods: {
261
+ readonly arguments: readonly Expression[];
262
+ readonly name: string;
263
+ }[] = [];
264
+ while (
265
+ isCallExpression(current) &&
266
+ isPropertyAccessExpression(current.expression) &&
267
+ !isIdentifier(current.expression.expression)
268
+ ) {
269
+ methods.unshift({
270
+ arguments: current.arguments,
271
+ name: current.expression.name.text,
272
+ });
273
+ current = unwrapExpression(current.expression.expression);
274
+ }
275
+ if (!isCallExpression(current)) {
276
+ return undefined;
277
+ }
278
+ return { base: current, methods };
279
+ };
280
+
281
+ const brandedStringSchemaIsExact = (
282
+ declaration: VariableDeclaration | undefined,
283
+ brand: string,
284
+ ): boolean => {
285
+ const initializer = declaration?.initializer;
286
+ if (initializer === undefined) {
287
+ return false;
288
+ }
289
+ const pipeCall = unwrapExpression(initializer);
290
+ if (
291
+ !isCallExpression(pipeCall) ||
292
+ !isPropertyAccessExpression(pipeCall.expression) ||
293
+ pipeCall.expression.name.text !== 'pipe' ||
294
+ !isAccessPath(pipeCall.expression.expression, ['Schema', 'String']) ||
295
+ pipeCall.arguments.length !== 1
296
+ ) {
297
+ return false;
298
+ }
299
+ const brandCall = exactCall(pipeCall.arguments[0], ['Schema', 'brand'], 1);
300
+ return stringLiteral(brandCall?.arguments[0]) === brand;
301
+ };
302
+
303
+ const importedRuntimeNames = (
304
+ statement: Node,
305
+ expectedPackage: string,
306
+ ): readonly string[] => {
307
+ if (
308
+ !isImportDeclaration(statement) ||
309
+ stringLiteral(statement.moduleSpecifier) !== expectedPackage
310
+ ) {
311
+ return [];
312
+ }
313
+ const clause = statement.importClause;
314
+ const bindings = clause?.namedBindings;
315
+ if (
316
+ clause?.phaseModifier === SyntaxKind.TypeKeyword ||
317
+ bindings === undefined ||
318
+ !isNamedImports(bindings)
319
+ ) {
320
+ return [];
321
+ }
322
+ return bindings.elements
323
+ .filter(
324
+ element => !element.isTypeOnly && element.propertyName === undefined,
325
+ )
326
+ .map(element => element.name.text);
327
+ };
328
+
329
+ const importsExactBindings = (
330
+ sourceFile: SourceFile,
331
+ expectedPackage: string,
332
+ expectedBindings: readonly string[],
333
+ ): boolean => {
334
+ const names = new Set(
335
+ sourceFile.statements.flatMap(statement =>
336
+ importedRuntimeNames(statement, expectedPackage),
337
+ ),
338
+ );
339
+ return expectedBindings.every(name => names.has(name));
340
+ };
341
+
342
+ const baselineBindings = [
343
+ 'MicroVerticalBuildMarkerSchema',
344
+ 'MicroVerticalReadinessSchema',
345
+ 'createMicroVerticalOperationContext',
346
+ ] as const;
347
+
348
+ const importsSharedBaselinePrimitives = (
349
+ sourceFile: SourceFile,
350
+ expectedPackage: string,
351
+ ): boolean =>
352
+ [expectedPackage, `${expectedPackage}/microvertical-api-baseline`].some(
353
+ specifier => importsExactBindings(sourceFile, specifier, baselineBindings),
354
+ );
355
+
356
+ /** Resolve only the owner's two public baseline surfaces, never arbitrary subpaths. */
357
+ const baselinePublicIdentityIsExact = (
358
+ sourceFile: SourceFile,
359
+ expectation: MicroVerticalApiBaselineExpectation,
360
+ parse: (filePath: string) => SourceFile | undefined,
361
+ ): boolean => {
362
+ try {
363
+ const owner = fs.realpathSync(expectation.sharedContractsDirectory);
364
+ const manifest = JSON.parse(
365
+ fs.readFileSync(path.join(owner, 'package.json'), 'utf8'),
366
+ );
367
+ if (manifest.name !== expectation.sharedContractsPackage) return false;
368
+ const exports =
369
+ typeof manifest.exports === 'string'
370
+ ? { '.': manifest.exports }
371
+ : manifest.exports;
372
+ const specifier = [
373
+ expectation.sharedContractsPackage,
374
+ `${expectation.sharedContractsPackage}/microvertical-api-baseline`,
375
+ ].find(candidate =>
376
+ importsExactBindings(sourceFile, candidate, baselineBindings),
377
+ );
378
+ if (specifier === undefined) return false;
379
+ const subpath =
380
+ specifier === expectation.sharedContractsPackage
381
+ ? '.'
382
+ : './microvertical-api-baseline';
383
+ const target =
384
+ subpath === '.'
385
+ ? './src/index.ts'
386
+ : './src/microvertical-api-baseline.ts';
387
+ if (
388
+ exports?.[subpath] !== target ||
389
+ fs.realpathSync(createRequire(sourceFile.fileName).resolve(specifier)) !==
390
+ path.join(owner, target)
391
+ )
392
+ return false;
393
+ const rootPath = path.join(owner, 'src/index.ts');
394
+ const baselinePath = path.join(owner, 'src/microvertical-api-baseline.ts');
395
+ const publicFile = parse(path.join(owner, target));
396
+ if (publicFile === undefined) return false;
397
+ const exportedOwner = (
398
+ file: SourceFile,
399
+ name: string,
400
+ ): SourceFile | undefined => {
401
+ const filePath = path.resolve(file.fileName);
402
+ if (
403
+ ![rootPath, baselinePath].includes(filePath) ||
404
+ fs.realpathSync(filePath) !== filePath
405
+ )
406
+ return undefined;
407
+ if (exportedConst(file, name) !== undefined) return file;
408
+ // The legacy root may re-export the dedicated owner file. No foreign or
409
+ // multi-hop barrels, renamed exports, type-only exports, or decoys qualify.
410
+ if (filePath !== rootPath) return undefined;
411
+ const exports = file.statements
412
+ .filter(isExportDeclaration)
413
+ .filter(statement => !statement.isTypeOnly);
414
+ const explicit = exports.filter(statement =>
415
+ statement.exportClause !== undefined &&
416
+ isNamedExports(statement.exportClause) &&
417
+ statement.exportClause.elements.some(
418
+ element => !element.isTypeOnly && element.name.text === name,
419
+ ),
420
+ );
421
+ const candidates = explicit.length > 0
422
+ ? explicit
423
+ : exports.filter(statement => statement.exportClause === undefined);
424
+ // Explicit exports override stars; multiple unrelated stars can be ambiguous.
425
+ if (candidates.some(statement =>
426
+ stringLiteral(statement.moduleSpecifier) !== './microvertical-api-baseline.ts',
427
+ )) return undefined;
428
+ for (const statement of candidates) {
429
+ if (
430
+ statement.exportClause !== undefined &&
431
+ (!isNamedExports(statement.exportClause) ||
432
+ !statement.exportClause.elements.some(
433
+ element =>
434
+ !element.isTypeOnly &&
435
+ element.propertyName === undefined &&
436
+ element.name.text === name,
437
+ ))
438
+ )
439
+ continue;
440
+ const baseline = parse(baselinePath);
441
+ if (
442
+ baseline !== undefined &&
443
+ exportedConst(baseline, name) !== undefined &&
444
+ fs.realpathSync(baselinePath) === baselinePath
445
+ )
446
+ return baseline;
447
+ }
448
+ return undefined;
449
+ };
450
+ const owners = baselineBindings.map(name =>
451
+ exportedOwner(publicFile, name),
452
+ );
453
+ const baseline = owners[0];
454
+ return (
455
+ baseline !== undefined &&
456
+ owners.every(file => file?.fileName === baseline.fileName) &&
457
+ ['effect', expectation.effectClientPackage].some(specifier =>
458
+ importsExactBindings(baseline, specifier, ['Schema']),
459
+ ) &&
460
+ baselineBindings
461
+ .slice(0, 2)
462
+ .every(
463
+ name =>
464
+ exactCall(
465
+ exportedConst(baseline, name)?.initializer,
466
+ ['Schema', 'Struct'],
467
+ 1,
468
+ ) !== undefined,
469
+ )
470
+ );
471
+ } catch {
472
+ return false;
473
+ }
474
+ };
475
+
476
+ const singleAddedArgument = (
477
+ expression: Expression | undefined,
478
+ factory: readonly string[],
479
+ names: readonly string[],
480
+ ): Expression | undefined => {
481
+ const chain = directCallChain(expression);
482
+ if (chain === undefined || !isAccessPath(chain.base.expression, factory)) {
483
+ return undefined;
484
+ }
485
+ const [method] = chain.methods;
486
+ if (
487
+ chain.base.arguments.length !== 1 ||
488
+ !names.includes(stringLiteral(chain.base.arguments[0]) ?? '') ||
489
+ chain.methods.length !== 1 ||
490
+ method?.name !== 'add' ||
491
+ method.arguments.length !== 1
492
+ ) {
493
+ return undefined;
494
+ }
495
+ return method.arguments[0];
496
+ };
497
+
498
+ const foundationIsExact = (
499
+ declaration: VariableDeclaration | undefined,
500
+ stem: string,
501
+ readinessSchemaName: string,
502
+ ): boolean => {
503
+ const group = singleAddedArgument(
504
+ declaration?.initializer,
505
+ ['HttpApi', 'make'],
506
+ [
507
+ `${pascalCaseStem(stem)}FoundationApi`,
508
+ `${pascalCaseStem(stem)}ApiFoundation`,
509
+ ],
510
+ );
511
+ const endpointExpression = singleAddedArgument(
512
+ group,
513
+ ['HttpApiGroup', 'make'],
514
+ ['foundation'],
515
+ );
516
+ const endpoint = exactCall(
517
+ endpointExpression,
518
+ ['HttpApiEndpoint', 'get'],
519
+ 3,
520
+ );
521
+ const endpointOptions = objectLiteral(endpoint?.arguments[2]);
522
+ const endpointProperties =
523
+ endpointOptions === undefined
524
+ ? undefined
525
+ : propertyAssignments(endpointOptions.properties);
526
+ return (
527
+ endpoint !== undefined &&
528
+ stringLiteral(endpoint.arguments[0]) === 'readiness' &&
529
+ stringLiteral(endpoint.arguments[1]) === `/${stem}/readiness` &&
530
+ endpointProperties?.size === 1 &&
531
+ identifierName(endpointProperties.get('success')?.initializer) ===
532
+ readinessSchemaName
533
+ );
534
+ };
535
+
536
+ const rootComposesFoundation = (
537
+ sourceFile: SourceFile,
538
+ declaration: VariableDeclaration | undefined,
539
+ stem: string,
540
+ foundationName: string,
541
+ ): boolean => {
542
+ const chain = directCallChain(declaration?.initializer);
543
+ const first = chain?.methods[0];
544
+ return (
545
+ chain !== undefined &&
546
+ isAccessPath(chain.base.expression, ['HttpApi', 'make']) &&
547
+ chain.base.arguments.length === 1 &&
548
+ stringLiteral(chain.base.arguments[0]) === `${pascalCaseStem(stem)}Api` &&
549
+ chain.methods.length > 0 &&
550
+ chain.methods.every(
551
+ (method, index) =>
552
+ method.arguments.length === 1 &&
553
+ (method.name === 'add' ||
554
+ method.name === 'addHttpApi' ||
555
+ (index === chain.methods.length - 1 &&
556
+ method.name === 'pipe' &&
557
+ identifierName(method.arguments[0]) === 'identity' &&
558
+ importsExactBindings(sourceFile, 'effect', ['identity']))),
559
+ ) &&
560
+ first?.name === 'addHttpApi' &&
561
+ identifierName(first.arguments[0]) === foundationName
562
+ );
563
+ };
564
+
565
+ const operationContextFields = (property: PropertyAssignment) => {
566
+ const constructorCall = exactCall(
567
+ property.initializer,
568
+ ['createMicroVerticalOperationContext'],
569
+ 1,
570
+ );
571
+ const input = objectLiteral(constructorCall?.arguments[0]);
572
+ return input === undefined
573
+ ? undefined
574
+ : propertyAssignments(input.properties);
575
+ };
576
+
577
+ const operationContextIdentity = (
578
+ property: PropertyAssignment,
579
+ ):
580
+ | {
581
+ readonly method: string;
582
+ readonly operationId: string;
583
+ readonly routePath: string;
584
+ }
585
+ | undefined => {
586
+ const fields = operationContextFields(property);
587
+ const method = stringLiteral(fields?.get('method')?.initializer);
588
+ const operationId = stringLiteral(fields?.get('operationId')?.initializer);
589
+ const routePath = stringLiteral(fields?.get('routePath')?.initializer);
590
+ if (
591
+ fields?.size !== 3 ||
592
+ method === undefined ||
593
+ operationId === undefined ||
594
+ routePath === undefined
595
+ ) {
596
+ return undefined;
597
+ }
598
+ return { method, operationId, routePath };
599
+ };
600
+
601
+ const operationContextIsConstructed = (
602
+ property: PropertyAssignment,
603
+ stem: string,
604
+ propertyKey: string,
605
+ ): boolean => {
606
+ const identity = operationContextIdentity(property);
607
+ if (identity === undefined) {
608
+ return false;
609
+ }
610
+ const { method, operationId, routePath } = identity;
611
+ if (
612
+ !/^[A-Z]+$/u.test(method) ||
613
+ !/^\/(?!.*(?:^|\/)\.\.?\/)[^\s?#]*$/u.test(routePath)
614
+ ) {
615
+ return false;
616
+ }
617
+ const apiName = `${pascalCaseStem(stem)}Api`;
618
+ const generatedOperation = new Map([
619
+ ['addCartItem', ['POST', `/${stem}/cart/items`]],
620
+ ['clearCart', ['POST', `/${stem}/cart/clear`]],
621
+ ['create', ['POST', `/${stem}`]],
622
+ ['get', ['GET', `/${stem}/:id`]],
623
+ ['getCart', ['GET', `/${stem}/cart`]],
624
+ ['list', ['GET', `/${stem}`]],
625
+ ['readiness', ['GET', `/${stem}/readiness`]],
626
+ ['removeCartItem', ['POST', `/${stem}/cart/remove`]],
627
+ ]).get(propertyKey);
628
+ const requestedOperation = [method, routePath];
629
+ const matchesGenerated =
630
+ generatedOperation?.every(
631
+ (value, index) => value === requestedOperation[index],
632
+ ) === true;
633
+ if (propertyKey === 'readiness' && !matchesGenerated) {
634
+ return false;
635
+ }
636
+ return (
637
+ operationId === `${apiName}:${routePath}` ||
638
+ (operationId === `${apiName}:${camelCaseStem(stem)}:${propertyKey}` &&
639
+ matchesGenerated)
640
+ );
641
+ };
642
+
643
+ const operationMapIsConnected = (
644
+ declaration: VariableDeclaration | undefined,
645
+ stem: string,
646
+ ): boolean => {
647
+ const map = objectLiteral(declaration?.initializer);
648
+ const properties =
649
+ map === undefined ? undefined : propertyAssignments(map.properties);
650
+ return (
651
+ properties !== undefined &&
652
+ properties.has('readiness') &&
653
+ [...properties].every(([key, property]) =>
654
+ operationContextIsConstructed(property, stem, key),
655
+ )
656
+ );
657
+ };
658
+
659
+ const constAssertionObject = (
660
+ declaration: VariableDeclaration | undefined,
661
+ ): ObjectLiteralExpression | undefined => {
662
+ const initializer = declaration?.initializer;
663
+ if (
664
+ initializer === undefined ||
665
+ !isAsExpression(initializer) ||
666
+ initializer.type.getText() !== 'const'
667
+ ) {
668
+ return undefined;
669
+ }
670
+ return objectLiteral(initializer.expression);
671
+ };
672
+
673
+ const metadataIsExact = (
674
+ declaration: VariableDeclaration | undefined,
675
+ expectation: MicroVerticalApiBaselineExpectation,
676
+ ): boolean => {
677
+ const object = constAssertionObject(declaration);
678
+ const fields =
679
+ object === undefined ? undefined : propertyAssignments(object.properties);
680
+ const expectedFields = [
681
+ ['apiPrefix', expectation.apiPrefix],
682
+ ['basePath', expectation.basePath],
683
+ ['ownerId', expectation.ownerId],
684
+ ['readinessPath', expectation.readinessPath],
685
+ // Business endpoints may replace the scaffold's sample operations.
686
+ // Validate their metadata when exposed; the shared baseline requires only
687
+ // the owner, API prefix, base path, and readiness path.
688
+ ...Object.entries(expectation.additionalPaths).filter(([field]) =>
689
+ fields?.has(field)
690
+ ),
691
+ ] as const;
692
+ return (
693
+ fields !== undefined &&
694
+ fields.size === new Map(expectedFields).size &&
695
+ [...expectedFields].every(
696
+ ([field, value]) =>
697
+ stringLiteral(fields.get(field)?.initializer) === value,
698
+ )
699
+ );
700
+ };
701
+
702
+ const markerSchemaIsShared = (
703
+ sourceFile: SourceFile,
704
+ declaration: VariableDeclaration | undefined,
705
+ ): boolean => {
706
+ const schema = sharedSchemaObject(
707
+ declaration,
708
+ 'MicroVerticalBuildMarkerSchema',
709
+ [
710
+ 'build',
711
+ 'buildMarker',
712
+ 'deployProfile',
713
+ 'packageName',
714
+ 'sourceRevision',
715
+ 'surface',
716
+ 'version',
717
+ ],
718
+ );
719
+ if (schema === undefined || schema.identity) {
720
+ return schema?.identity === true;
721
+ }
722
+ const brandedField = (
723
+ property: PropertyAssignment,
724
+ brand: string,
725
+ ): boolean =>
726
+ identifierName(property.initializer) === `${brand}Schema` &&
727
+ brandedStringSchemaIsExact(
728
+ localConst(sourceFile, `${brand}Schema`),
729
+ brand,
730
+ );
731
+ const validators = new Map<
732
+ string,
733
+ (property: PropertyAssignment) => boolean
734
+ >([
735
+ ['appId', property => brandedField(property, 'AppId')],
736
+ ['unitId', property => brandedField(property, 'UnitId')],
737
+ [
738
+ 'kind',
739
+ property =>
740
+ stringLiteral(
741
+ exactCall(property.initializer, ['Schema', 'Literal'], 1)
742
+ ?.arguments[0],
743
+ ) === 'microvertical-delivery-unit',
744
+ ],
745
+ [
746
+ 'schemaVersion',
747
+ property =>
748
+ numericLiteral(
749
+ exactCall(property.initializer, ['Schema', 'Literal'], 1)
750
+ ?.arguments[0],
751
+ ) === 1,
752
+ ],
753
+ ]);
754
+ return [...schema.assignments].every(
755
+ ([field, property]) => validators.get(field)?.(property) === true,
756
+ );
757
+ };
758
+
759
+ const readinessSchemaIsShared = (
760
+ declaration: VariableDeclaration | undefined,
761
+ markerSchemaName: string,
762
+ ownerMarkerIsIdentity: boolean,
763
+ ): boolean => {
764
+ const schema = sharedSchemaObject(
765
+ declaration,
766
+ 'MicroVerticalReadinessSchema',
767
+ ['checks', 'status', 'versionSkew'],
768
+ );
769
+ return (
770
+ schema !== undefined &&
771
+ ((schema.identity && ownerMarkerIsIdentity) ||
772
+ (schema.assignments.size === 1 &&
773
+ identifierName(schema.assignments.get('marker')?.initializer) ===
774
+ markerSchemaName))
775
+ );
776
+ };
777
+
778
+ const declarationIsIdentifier = (
779
+ declaration: VariableDeclaration | undefined,
780
+ identifier: string,
781
+ ): boolean =>
782
+ declaration?.initializer !== undefined &&
783
+ identifierName(unwrapExpression(declaration.initializer)) === identifier;
784
+
785
+ const validateParsedContract = (
786
+ sourceFile: SourceFile,
787
+ stem: string,
788
+ expectation: MicroVerticalApiBaselineExpectation,
789
+ ): string | undefined => {
790
+ const exportStem = camelCaseStem(stem);
791
+ const foundationName = `${exportStem}FoundationApi`;
792
+ const markerSchemaName = `${exportStem}MarkerSchema`;
793
+ const readinessSchemaName = `${exportStem}ReadinessSchema`;
794
+ const markerDeclaration = exportedConst(sourceFile, markerSchemaName);
795
+ if (
796
+ !importsExactBindings(sourceFile, expectation.effectClientPackage, [
797
+ 'HttpApi',
798
+ 'HttpApiEndpoint',
799
+ 'HttpApiGroup',
800
+ 'Schema',
801
+ ])
802
+ ) {
803
+ return 'MicroVertical root contract must import exact Effect API primitives from the framework client package';
804
+ }
805
+ if (
806
+ !importsSharedBaselinePrimitives(
807
+ sourceFile,
808
+ expectation.sharedContractsPackage,
809
+ )
810
+ ) {
811
+ return 'MicroVertical root contract must import exact baseline primitives from the shared contracts package';
812
+ }
813
+ if (!markerSchemaIsShared(sourceFile, markerDeclaration)) {
814
+ return 'MicroVertical root contract must consume the shared build marker schema without overriding shared fields';
815
+ }
816
+ if (
817
+ !readinessSchemaIsShared(
818
+ exportedConst(sourceFile, readinessSchemaName),
819
+ markerSchemaName,
820
+ declarationIsIdentifier(
821
+ markerDeclaration,
822
+ 'MicroVerticalBuildMarkerSchema',
823
+ ),
824
+ )
825
+ ) {
826
+ return 'MicroVertical readiness schema must consume the shared readiness schema without overriding shared fields';
827
+ }
828
+ if (
829
+ !foundationIsExact(
830
+ exportedConst(sourceFile, foundationName),
831
+ stem,
832
+ readinessSchemaName,
833
+ )
834
+ ) {
835
+ return 'MicroVertical readiness foundation API must directly compose its exact readiness endpoint and foundation identity';
836
+ }
837
+ if (
838
+ !rootComposesFoundation(
839
+ sourceFile,
840
+ exportedConst(sourceFile, `${exportStem}Api`),
841
+ stem,
842
+ foundationName,
843
+ )
844
+ ) {
845
+ return 'MicroVertical root API must explicitly compose its readiness foundation API';
846
+ }
847
+ if (
848
+ !operationMapIsConnected(
849
+ exportedConst(sourceFile, `${exportStem}OperationContexts`),
850
+ stem,
851
+ )
852
+ ) {
853
+ return 'MicroVertical operation map must construct every operation with the shared context constructor';
854
+ }
855
+ if (
856
+ !metadataIsExact(
857
+ exportedConst(sourceFile, `${exportStem}ApiContract`),
858
+ expectation,
859
+ )
860
+ ) {
861
+ return 'MicroVertical root contract must keep exact owner and API path metadata without forbidden fields';
862
+ }
863
+ return undefined;
864
+ };
865
+
866
+ const parseAndValidate = (
867
+ stem: string,
868
+ filePath: string,
869
+ expectation: MicroVerticalApiBaselineExpectation,
870
+ ): string | undefined => {
871
+ const compiler = new TypeScriptApi();
872
+ try {
873
+ const ownerFiles = ['index.ts', 'microvertical-api-baseline.ts']
874
+ .map(name =>
875
+ path.resolve(expectation.sharedContractsDirectory, 'src', name),
876
+ )
877
+ .filter(file => fs.existsSync(file));
878
+ const snapshot = compiler.updateSnapshot({
879
+ openFiles: [filePath, ...ownerFiles],
880
+ });
881
+ const project = snapshot.getDefaultProjectForFile(filePath);
882
+ const sourceFile = project?.program.getSourceFile(filePath);
883
+ if (
884
+ sourceFile === undefined ||
885
+ (project?.program.getSyntacticDiagnostics(filePath).length ?? 1) > 0 ||
886
+ (project?.program.getBindDiagnostics(filePath).length ?? 1) > 0
887
+ ) {
888
+ return 'MicroVertical root contract must be valid TypeScript syntax';
889
+ }
890
+ if (
891
+ !baselinePublicIdentityIsExact(sourceFile, expectation, ownerFile => {
892
+ const ownerProject = snapshot.getDefaultProjectForFile(ownerFile);
893
+ if (
894
+ !ownerProject ||
895
+ ownerProject.program.getSyntacticDiagnostics(ownerFile).length > 0 ||
896
+ ownerProject.program.getBindDiagnostics(ownerFile).length > 0
897
+ )
898
+ return undefined;
899
+ return ownerProject.program.getSourceFile(ownerFile);
900
+ })
901
+ ) {
902
+ return 'MicroVertical baseline imports must resolve the exact shared owner public export and schema identity';
903
+ }
904
+ return validateParsedContract(sourceFile, stem, expectation);
905
+ } finally {
906
+ compiler.close();
907
+ }
908
+ };
909
+
910
+ export interface MicroVerticalApiBaselineExpectation {
911
+ readonly additionalPaths: Readonly<Record<string, string>>;
912
+ readonly apiPrefix: string;
913
+ readonly basePath: string;
914
+ readonly effectClientPackage: string;
915
+ readonly ownerId: string;
916
+ readonly readinessPath: string;
917
+ readonly sharedContractsPackage: string;
918
+ readonly sharedContractsDirectory: string;
919
+ }
920
+
921
+ export interface MicroVerticalTopologyEntry {
922
+ readonly api?: { readonly readiness?: { readonly endpoint?: string } };
923
+ readonly id: string;
924
+ readonly path?: string;
925
+ }
926
+
927
+ export const configuredMicroVerticalApiStem = (
928
+ verticalPath: string,
929
+ verticals: readonly MicroVerticalTopologyEntry[],
930
+ ): string | undefined => {
931
+ const topologyVertical = verticals.find(
932
+ vertical =>
933
+ (vertical.path ?? `verticals/${vertical.id}`) === verticalPath,
934
+ );
935
+ const endpoint = topologyVertical?.api?.readiness?.endpoint;
936
+ return endpoint?.match(/^\/(?<stem>[a-z0-9]+(?:-[a-z0-9]+)*)\/readiness$/u)
937
+ ?.groups?.stem;
938
+ };
939
+
940
+ export const microVerticalApiBaselineViolation = (
941
+ stem: string,
942
+ filePath: string,
943
+ expectation: MicroVerticalApiBaselineExpectation,
944
+ ): string | undefined => parseAndValidate(stem, filePath, expectation);