@living-architecture/riviere-builder 0.2.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.
- package/README.md +11 -0
- package/dist/builder-assertions.d.ts +5 -0
- package/dist/builder-assertions.d.ts.map +1 -0
- package/dist/builder-assertions.js +24 -0
- package/dist/builder-test-fixtures.d.ts +7 -0
- package/dist/builder-test-fixtures.d.ts.map +1 -0
- package/dist/builder-test-fixtures.js +12 -0
- package/dist/builder.d.ts +485 -0
- package/dist/builder.d.ts.map +1 -0
- package/dist/builder.js +749 -0
- package/dist/component-suggestion.d.ts +35 -0
- package/dist/component-suggestion.d.ts.map +1 -0
- package/dist/component-suggestion.js +66 -0
- package/dist/errors.d.ts +28 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +59 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +4 -0
- package/dist/inspection.d.ts +90 -0
- package/dist/inspection.d.ts.map +1 -0
- package/dist/inspection.js +137 -0
- package/dist/string-similarity.d.ts +32 -0
- package/dist/string-similarity.d.ts.map +1 -0
- package/dist/string-similarity.js +61 -0
- package/dist/types.d.ts +149 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +1 -0
- package/package.json +29 -0
package/README.md
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import type { CustomTypeDefinition, DomainMetadata } from '@living-architecture/riviere-schema';
|
|
2
|
+
export declare function assertDomainExists(domains: Record<string, DomainMetadata>, domain: string): void;
|
|
3
|
+
export declare function assertCustomTypeExists(customTypes: Record<string, CustomTypeDefinition>, customTypeName: string): void;
|
|
4
|
+
export declare function assertRequiredPropertiesProvided(customTypes: Record<string, CustomTypeDefinition>, customTypeName: string, metadata: Record<string, unknown> | undefined): void;
|
|
5
|
+
//# sourceMappingURL=builder-assertions.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"builder-assertions.d.ts","sourceRoot":"","sources":["../src/builder-assertions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAA;AAG/F,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAIhG;AAED,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,EACjD,cAAc,EAAE,MAAM,GACrB,IAAI,CAKN;AAED,wBAAgB,gCAAgC,CAC9C,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,EACjD,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC5C,IAAI,CAaN"}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { CustomTypeNotFoundError, DomainNotFoundError } from './errors';
|
|
2
|
+
export function assertDomainExists(domains, domain) {
|
|
3
|
+
if (!domains[domain]) {
|
|
4
|
+
throw new DomainNotFoundError(domain);
|
|
5
|
+
}
|
|
6
|
+
}
|
|
7
|
+
export function assertCustomTypeExists(customTypes, customTypeName) {
|
|
8
|
+
if (!customTypes[customTypeName]) {
|
|
9
|
+
const definedTypes = Object.keys(customTypes);
|
|
10
|
+
throw new CustomTypeNotFoundError(customTypeName, definedTypes);
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
export function assertRequiredPropertiesProvided(customTypes, customTypeName, metadata) {
|
|
14
|
+
const typeDefinition = customTypes[customTypeName];
|
|
15
|
+
if (!typeDefinition?.requiredProperties) {
|
|
16
|
+
return;
|
|
17
|
+
}
|
|
18
|
+
const requiredKeys = Object.keys(typeDefinition.requiredProperties);
|
|
19
|
+
const providedKeys = metadata ? Object.keys(metadata) : [];
|
|
20
|
+
const missingKeys = requiredKeys.filter((key) => !providedKeys.includes(key));
|
|
21
|
+
if (missingKeys.length > 0) {
|
|
22
|
+
throw new Error(`Missing required properties for '${customTypeName}': ${missingKeys.join(', ')}`);
|
|
23
|
+
}
|
|
24
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"builder-test-fixtures.d.ts","sourceRoot":"","sources":["../src/builder-test-fixtures.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAE/C,wBAAgB,kBAAkB,IAAI,cAAc,CAQnD;AAED,wBAAgB,oBAAoB;;;EAEnC"}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
export function createValidOptions() {
|
|
2
|
+
return {
|
|
3
|
+
sources: [{ repository: 'test/repo', commit: 'abc123' }],
|
|
4
|
+
domains: {
|
|
5
|
+
orders: { description: 'Order domain', systemType: 'domain' },
|
|
6
|
+
shipping: { description: 'Shipping domain', systemType: 'domain' },
|
|
7
|
+
},
|
|
8
|
+
};
|
|
9
|
+
}
|
|
10
|
+
export function createSourceLocation() {
|
|
11
|
+
return { repository: 'test/repo', filePath: 'src/test.ts' };
|
|
12
|
+
}
|
|
@@ -0,0 +1,485 @@
|
|
|
1
|
+
import type { APIComponent, CustomComponent, CustomTypeDefinition, DomainOpComponent, EventComponent, EventHandlerComponent, ExternalLink, GraphMetadata, Link, RiviereGraph, SourceInfo, UIComponent, UseCaseComponent } from '@living-architecture/riviere-schema';
|
|
2
|
+
import { RiviereQuery, type ValidationResult } from '@living-architecture/riviere-query';
|
|
3
|
+
import type { APIInput, BuilderOptions, BuilderStats, BuilderWarning, CustomInput, CustomTypeInput, DomainInput, DomainOpInput, EnrichmentInput, EventHandlerInput, EventInput, ExternalLinkInput, LinkInput, NearMatchMismatch, NearMatchOptions, NearMatchQuery, NearMatchResult, UIInput, UseCaseInput } from './types';
|
|
4
|
+
export type { APIInput, BuilderOptions, BuilderStats, BuilderWarning, CustomInput, CustomTypeInput, DomainInput, DomainOpInput, EnrichmentInput, EventHandlerInput, EventInput, ExternalLinkInput, LinkInput, NearMatchMismatch, NearMatchOptions, NearMatchQuery, NearMatchResult, UIInput, UseCaseInput, };
|
|
5
|
+
interface BuilderMetadata extends Omit<GraphMetadata, 'sources' | 'customTypes'> {
|
|
6
|
+
sources: SourceInfo[];
|
|
7
|
+
customTypes: Record<string, CustomTypeDefinition>;
|
|
8
|
+
}
|
|
9
|
+
interface BuilderGraph extends Omit<RiviereGraph, 'metadata' | 'externalLinks'> {
|
|
10
|
+
metadata: BuilderMetadata;
|
|
11
|
+
externalLinks: ExternalLink[];
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Programmatically construct Rivière architecture graphs.
|
|
15
|
+
*
|
|
16
|
+
* RiviereBuilder provides a fluent API for creating graphs, adding components,
|
|
17
|
+
* linking them together, and exporting valid JSON conforming to the Rivière schema.
|
|
18
|
+
*
|
|
19
|
+
* @example
|
|
20
|
+
* ```typescript
|
|
21
|
+
* import { RiviereBuilder } from '@living-architecture/riviere-builder'
|
|
22
|
+
*
|
|
23
|
+
* const builder = RiviereBuilder.new({
|
|
24
|
+
* sources: [{ type: 'git', url: 'https://github.com/org/repo' }],
|
|
25
|
+
* domains: { orders: { description: 'Order management' } }
|
|
26
|
+
* })
|
|
27
|
+
*
|
|
28
|
+
* const api = builder.addApi({
|
|
29
|
+
* name: 'Create Order',
|
|
30
|
+
* domain: 'orders',
|
|
31
|
+
* module: 'checkout',
|
|
32
|
+
* apiType: 'REST',
|
|
33
|
+
* sourceLocation: { file: 'src/api/orders.ts', line: 10 }
|
|
34
|
+
* })
|
|
35
|
+
*
|
|
36
|
+
* const graph = builder.build()
|
|
37
|
+
* ```
|
|
38
|
+
*/
|
|
39
|
+
export declare class RiviereBuilder {
|
|
40
|
+
graph: BuilderGraph;
|
|
41
|
+
private constructor();
|
|
42
|
+
/**
|
|
43
|
+
* Restores a builder from a previously serialized graph.
|
|
44
|
+
*
|
|
45
|
+
* Use this to continue building a graph that was saved mid-construction,
|
|
46
|
+
* or to modify an existing graph.
|
|
47
|
+
*
|
|
48
|
+
* @param graph - A valid RiviereGraph object to resume from
|
|
49
|
+
* @returns A new RiviereBuilder instance with the graph state restored
|
|
50
|
+
* @throws If the graph is missing required sources
|
|
51
|
+
*
|
|
52
|
+
* @example
|
|
53
|
+
* ```typescript
|
|
54
|
+
* const json = await fs.readFile('draft.json', 'utf-8')
|
|
55
|
+
* const graph = JSON.parse(json)
|
|
56
|
+
* const builder = RiviereBuilder.resume(graph)
|
|
57
|
+
* builder.addApi({ ... })
|
|
58
|
+
* ```
|
|
59
|
+
*/
|
|
60
|
+
static resume(graph: RiviereGraph): RiviereBuilder;
|
|
61
|
+
/**
|
|
62
|
+
* Creates a new builder with initial configuration.
|
|
63
|
+
*
|
|
64
|
+
* @param options - Configuration including sources and domains
|
|
65
|
+
* @returns A new RiviereBuilder instance
|
|
66
|
+
* @throws If sources array is empty
|
|
67
|
+
* @throws If domains object is empty
|
|
68
|
+
*
|
|
69
|
+
* @example
|
|
70
|
+
* ```typescript
|
|
71
|
+
* const builder = RiviereBuilder.new({
|
|
72
|
+
* name: 'My System',
|
|
73
|
+
* sources: [{ type: 'git', url: 'https://github.com/org/repo' }],
|
|
74
|
+
* domains: {
|
|
75
|
+
* orders: { description: 'Order management' },
|
|
76
|
+
* users: { description: 'User accounts' }
|
|
77
|
+
* }
|
|
78
|
+
* })
|
|
79
|
+
* ```
|
|
80
|
+
*/
|
|
81
|
+
static new(options: BuilderOptions): RiviereBuilder;
|
|
82
|
+
/**
|
|
83
|
+
* Adds an additional source repository to the graph.
|
|
84
|
+
*
|
|
85
|
+
* @param source - Source repository information
|
|
86
|
+
*
|
|
87
|
+
* @example
|
|
88
|
+
* ```typescript
|
|
89
|
+
* builder.addSource({
|
|
90
|
+
* type: 'git',
|
|
91
|
+
* url: 'https://github.com/org/another-repo'
|
|
92
|
+
* })
|
|
93
|
+
* ```
|
|
94
|
+
*/
|
|
95
|
+
addSource(source: SourceInfo): void;
|
|
96
|
+
/**
|
|
97
|
+
* Adds a new domain to the graph.
|
|
98
|
+
*
|
|
99
|
+
* @param input - Domain name and description
|
|
100
|
+
* @throws If domain with same name already exists
|
|
101
|
+
*
|
|
102
|
+
* @example
|
|
103
|
+
* ```typescript
|
|
104
|
+
* builder.addDomain({
|
|
105
|
+
* name: 'payments',
|
|
106
|
+
* description: 'Payment processing'
|
|
107
|
+
* })
|
|
108
|
+
* ```
|
|
109
|
+
*/
|
|
110
|
+
addDomain(input: DomainInput): void;
|
|
111
|
+
/**
|
|
112
|
+
* Adds a UI component to the graph.
|
|
113
|
+
*
|
|
114
|
+
* @param input - UI component properties including route and source location
|
|
115
|
+
* @returns The created UI component with generated ID
|
|
116
|
+
* @throws If the specified domain does not exist
|
|
117
|
+
*
|
|
118
|
+
* @example
|
|
119
|
+
* ```typescript
|
|
120
|
+
* const ui = builder.addUI({
|
|
121
|
+
* name: 'Order List',
|
|
122
|
+
* domain: 'orders',
|
|
123
|
+
* module: 'dashboard',
|
|
124
|
+
* route: '/orders',
|
|
125
|
+
* sourceLocation: { file: 'src/pages/OrderList.tsx', line: 15 }
|
|
126
|
+
* })
|
|
127
|
+
* ```
|
|
128
|
+
*/
|
|
129
|
+
addUI(input: UIInput): UIComponent;
|
|
130
|
+
/**
|
|
131
|
+
* Adds an API component to the graph.
|
|
132
|
+
*
|
|
133
|
+
* @param input - API component properties including type, method, and path
|
|
134
|
+
* @returns The created API component with generated ID
|
|
135
|
+
* @throws If the specified domain does not exist
|
|
136
|
+
*
|
|
137
|
+
* @example
|
|
138
|
+
* ```typescript
|
|
139
|
+
* const api = builder.addApi({
|
|
140
|
+
* name: 'Create Order',
|
|
141
|
+
* domain: 'orders',
|
|
142
|
+
* module: 'checkout',
|
|
143
|
+
* apiType: 'REST',
|
|
144
|
+
* httpMethod: 'POST',
|
|
145
|
+
* path: '/api/orders',
|
|
146
|
+
* sourceLocation: { file: 'src/api/orders.ts', line: 25 }
|
|
147
|
+
* })
|
|
148
|
+
* ```
|
|
149
|
+
*/
|
|
150
|
+
addApi(input: APIInput): APIComponent;
|
|
151
|
+
/**
|
|
152
|
+
* Adds a UseCase component to the graph.
|
|
153
|
+
*
|
|
154
|
+
* @param input - UseCase component properties
|
|
155
|
+
* @returns The created UseCase component with generated ID
|
|
156
|
+
* @throws If the specified domain does not exist
|
|
157
|
+
*
|
|
158
|
+
* @example
|
|
159
|
+
* ```typescript
|
|
160
|
+
* const useCase = builder.addUseCase({
|
|
161
|
+
* name: 'Place Order',
|
|
162
|
+
* domain: 'orders',
|
|
163
|
+
* module: 'checkout',
|
|
164
|
+
* sourceLocation: { file: 'src/usecases/PlaceOrder.ts', line: 10 }
|
|
165
|
+
* })
|
|
166
|
+
* ```
|
|
167
|
+
*/
|
|
168
|
+
addUseCase(input: UseCaseInput): UseCaseComponent;
|
|
169
|
+
/**
|
|
170
|
+
* Adds a DomainOp component to the graph.
|
|
171
|
+
*
|
|
172
|
+
* DomainOp represents domain operations that change entity state.
|
|
173
|
+
* Can be enriched later with state changes and business rules.
|
|
174
|
+
*
|
|
175
|
+
* @param input - DomainOp component properties including operation name
|
|
176
|
+
* @returns The created DomainOp component with generated ID
|
|
177
|
+
* @throws If the specified domain does not exist
|
|
178
|
+
*
|
|
179
|
+
* @example
|
|
180
|
+
* ```typescript
|
|
181
|
+
* const domainOp = builder.addDomainOp({
|
|
182
|
+
* name: 'Confirm Order',
|
|
183
|
+
* domain: 'orders',
|
|
184
|
+
* module: 'fulfillment',
|
|
185
|
+
* operationName: 'confirmOrder',
|
|
186
|
+
* entity: 'Order',
|
|
187
|
+
* sourceLocation: { file: 'src/domain/Order.ts', line: 45 }
|
|
188
|
+
* })
|
|
189
|
+
* ```
|
|
190
|
+
*/
|
|
191
|
+
addDomainOp(input: DomainOpInput): DomainOpComponent;
|
|
192
|
+
/**
|
|
193
|
+
* Adds an Event component to the graph.
|
|
194
|
+
*
|
|
195
|
+
* @param input - Event component properties including event name
|
|
196
|
+
* @returns The created Event component with generated ID
|
|
197
|
+
* @throws If the specified domain does not exist
|
|
198
|
+
*
|
|
199
|
+
* @example
|
|
200
|
+
* ```typescript
|
|
201
|
+
* const event = builder.addEvent({
|
|
202
|
+
* name: 'Order Placed',
|
|
203
|
+
* domain: 'orders',
|
|
204
|
+
* module: 'checkout',
|
|
205
|
+
* eventName: 'OrderPlaced',
|
|
206
|
+
* sourceLocation: { file: 'src/events/OrderPlaced.ts', line: 5 }
|
|
207
|
+
* })
|
|
208
|
+
* ```
|
|
209
|
+
*/
|
|
210
|
+
addEvent(input: EventInput): EventComponent;
|
|
211
|
+
/**
|
|
212
|
+
* Adds an EventHandler component to the graph.
|
|
213
|
+
*
|
|
214
|
+
* @param input - EventHandler component properties including subscribed events
|
|
215
|
+
* @returns The created EventHandler component with generated ID
|
|
216
|
+
* @throws If the specified domain does not exist
|
|
217
|
+
*
|
|
218
|
+
* @example
|
|
219
|
+
* ```typescript
|
|
220
|
+
* const handler = builder.addEventHandler({
|
|
221
|
+
* name: 'Send Confirmation Email',
|
|
222
|
+
* domain: 'notifications',
|
|
223
|
+
* module: 'email',
|
|
224
|
+
* subscribedEvents: ['OrderPlaced'],
|
|
225
|
+
* sourceLocation: { file: 'src/handlers/OrderConfirmation.ts', line: 10 }
|
|
226
|
+
* })
|
|
227
|
+
* ```
|
|
228
|
+
*/
|
|
229
|
+
addEventHandler(input: EventHandlerInput): EventHandlerComponent;
|
|
230
|
+
/**
|
|
231
|
+
* Defines a custom component type for the graph.
|
|
232
|
+
*
|
|
233
|
+
* Custom types allow extending the schema with domain-specific component kinds.
|
|
234
|
+
* Must be defined before adding custom components of that type.
|
|
235
|
+
*
|
|
236
|
+
* @param input - Custom type definition with required and optional properties
|
|
237
|
+
* @throws If a custom type with the same name already exists
|
|
238
|
+
*
|
|
239
|
+
* @example
|
|
240
|
+
* ```typescript
|
|
241
|
+
* builder.defineCustomType({
|
|
242
|
+
* name: 'MessageQueue',
|
|
243
|
+
* description: 'Async message queue',
|
|
244
|
+
* requiredProperties: {
|
|
245
|
+
* queueName: { type: 'string', description: 'Queue identifier' }
|
|
246
|
+
* }
|
|
247
|
+
* })
|
|
248
|
+
* ```
|
|
249
|
+
*/
|
|
250
|
+
defineCustomType(input: CustomTypeInput): void;
|
|
251
|
+
/**
|
|
252
|
+
* Adds a Custom component to the graph.
|
|
253
|
+
*
|
|
254
|
+
* Custom components use types defined via defineCustomType().
|
|
255
|
+
* Validates that the custom type exists and required properties are provided.
|
|
256
|
+
*
|
|
257
|
+
* @param input - Custom component properties including type name and metadata
|
|
258
|
+
* @returns The created Custom component with generated ID
|
|
259
|
+
* @throws If the specified domain does not exist
|
|
260
|
+
* @throws If the custom type has not been defined
|
|
261
|
+
* @throws If required properties for the custom type are missing
|
|
262
|
+
*
|
|
263
|
+
* @example
|
|
264
|
+
* ```typescript
|
|
265
|
+
* const queue = builder.addCustom({
|
|
266
|
+
* customTypeName: 'MessageQueue',
|
|
267
|
+
* name: 'Order Events Queue',
|
|
268
|
+
* domain: 'orders',
|
|
269
|
+
* module: 'messaging',
|
|
270
|
+
* sourceLocation: { file: 'src/queues/orders.ts', line: 5 },
|
|
271
|
+
* metadata: { queueName: 'order-events' }
|
|
272
|
+
* })
|
|
273
|
+
* ```
|
|
274
|
+
*/
|
|
275
|
+
addCustom(input: CustomInput): CustomComponent;
|
|
276
|
+
/**
|
|
277
|
+
* Enriches a DomainOp component with additional domain details.
|
|
278
|
+
*
|
|
279
|
+
* Adds state changes and business rules to an existing DomainOp.
|
|
280
|
+
* Multiple enrichments accumulate rather than replace.
|
|
281
|
+
*
|
|
282
|
+
* @param id - The component ID to enrich
|
|
283
|
+
* @param enrichment - State changes and business rules to add
|
|
284
|
+
* @throws If the component does not exist
|
|
285
|
+
* @throws If the component is not a DomainOp type
|
|
286
|
+
*
|
|
287
|
+
* @example
|
|
288
|
+
* ```typescript
|
|
289
|
+
* builder.enrichComponent('orders:fulfillment:domainop:confirm-order', {
|
|
290
|
+
* entity: 'Order',
|
|
291
|
+
* stateChanges: [{ entity: 'Order', from: 'pending', to: 'confirmed' }],
|
|
292
|
+
* businessRules: ['Order must have valid payment']
|
|
293
|
+
* })
|
|
294
|
+
* ```
|
|
295
|
+
*/
|
|
296
|
+
enrichComponent(id: string, enrichment: EnrichmentInput): void;
|
|
297
|
+
private componentNotFoundError;
|
|
298
|
+
private validateDomainExists;
|
|
299
|
+
private validateCustomType;
|
|
300
|
+
private validateRequiredProperties;
|
|
301
|
+
private generateComponentId;
|
|
302
|
+
private registerComponent;
|
|
303
|
+
/**
|
|
304
|
+
* Finds components similar to a query for error recovery.
|
|
305
|
+
*
|
|
306
|
+
* Returns fuzzy matches when an exact component lookup fails,
|
|
307
|
+
* enabling actionable error messages with "Did you mean...?" suggestions.
|
|
308
|
+
*
|
|
309
|
+
* @param query - Search criteria including partial ID, name, type, or domain
|
|
310
|
+
* @param options - Optional matching thresholds and limits
|
|
311
|
+
* @returns Array of similar components with similarity scores
|
|
312
|
+
*
|
|
313
|
+
* @example
|
|
314
|
+
* ```typescript
|
|
315
|
+
* const matches = builder.nearMatches({ name: 'Place Ordr' })
|
|
316
|
+
* // [{ component: {...}, score: 0.9, mismatches: [...] }]
|
|
317
|
+
* ```
|
|
318
|
+
*/
|
|
319
|
+
nearMatches(query: NearMatchQuery, options?: NearMatchOptions): NearMatchResult[];
|
|
320
|
+
/**
|
|
321
|
+
* Creates a link between two components in the graph.
|
|
322
|
+
*
|
|
323
|
+
* Source component must exist; target validation is deferred to build().
|
|
324
|
+
* Use linkExternal() for connections to external systems.
|
|
325
|
+
*
|
|
326
|
+
* @param input - Link properties including source, target, and type
|
|
327
|
+
* @returns The created link
|
|
328
|
+
* @throws If the source component does not exist
|
|
329
|
+
*
|
|
330
|
+
* @example
|
|
331
|
+
* ```typescript
|
|
332
|
+
* const link = builder.link({
|
|
333
|
+
* from: 'orders:checkout:api:create-order',
|
|
334
|
+
* to: 'orders:checkout:usecase:place-order',
|
|
335
|
+
* type: 'sync'
|
|
336
|
+
* })
|
|
337
|
+
* ```
|
|
338
|
+
*/
|
|
339
|
+
link(input: LinkInput): Link;
|
|
340
|
+
/**
|
|
341
|
+
* Creates a link from a component to an external system.
|
|
342
|
+
*
|
|
343
|
+
* Use this for connections to systems outside the graph,
|
|
344
|
+
* such as third-party APIs or external databases.
|
|
345
|
+
*
|
|
346
|
+
* @param input - External link properties including target system info
|
|
347
|
+
* @returns The created external link
|
|
348
|
+
* @throws If the source component does not exist
|
|
349
|
+
*
|
|
350
|
+
* @example
|
|
351
|
+
* ```typescript
|
|
352
|
+
* const link = builder.linkExternal({
|
|
353
|
+
* from: 'orders:payments:usecase:process-payment',
|
|
354
|
+
* target: { name: 'Stripe API', domain: 'payments' },
|
|
355
|
+
* type: 'sync'
|
|
356
|
+
* })
|
|
357
|
+
* ```
|
|
358
|
+
*/
|
|
359
|
+
linkExternal(input: ExternalLinkInput): ExternalLink;
|
|
360
|
+
/**
|
|
361
|
+
* Returns non-fatal issues found in the graph.
|
|
362
|
+
*
|
|
363
|
+
* Warnings indicate potential problems that don't prevent building,
|
|
364
|
+
* such as orphaned components or unused domains.
|
|
365
|
+
*
|
|
366
|
+
* @returns Array of warning objects with type and message
|
|
367
|
+
*
|
|
368
|
+
* @example
|
|
369
|
+
* ```typescript
|
|
370
|
+
* const warnings = builder.warnings()
|
|
371
|
+
* for (const w of warnings) {
|
|
372
|
+
* console.log(`${w.type}: ${w.message}`)
|
|
373
|
+
* }
|
|
374
|
+
* ```
|
|
375
|
+
*/
|
|
376
|
+
warnings(): BuilderWarning[];
|
|
377
|
+
/**
|
|
378
|
+
* Returns statistics about the current graph state.
|
|
379
|
+
*
|
|
380
|
+
* @returns Counts of components by type, domains, and links
|
|
381
|
+
*
|
|
382
|
+
* @example
|
|
383
|
+
* ```typescript
|
|
384
|
+
* const stats = builder.stats()
|
|
385
|
+
* console.log(`Components: ${stats.componentCount}`)
|
|
386
|
+
* console.log(`Links: ${stats.linkCount}`)
|
|
387
|
+
* ```
|
|
388
|
+
*/
|
|
389
|
+
stats(): BuilderStats;
|
|
390
|
+
/**
|
|
391
|
+
* Runs full validation on the graph.
|
|
392
|
+
*
|
|
393
|
+
* Checks for dangling references, orphans, and schema compliance.
|
|
394
|
+
* Called automatically by build().
|
|
395
|
+
*
|
|
396
|
+
* @returns Validation result with valid flag and error details
|
|
397
|
+
*
|
|
398
|
+
* @example
|
|
399
|
+
* ```typescript
|
|
400
|
+
* const result = builder.validate()
|
|
401
|
+
* if (!result.valid) {
|
|
402
|
+
* for (const error of result.errors) {
|
|
403
|
+
* console.error(error.message)
|
|
404
|
+
* }
|
|
405
|
+
* }
|
|
406
|
+
* ```
|
|
407
|
+
*/
|
|
408
|
+
validate(): ValidationResult;
|
|
409
|
+
/**
|
|
410
|
+
* Returns IDs of components with no incoming or outgoing links.
|
|
411
|
+
*
|
|
412
|
+
* @returns Array of orphaned component IDs
|
|
413
|
+
*
|
|
414
|
+
* @example
|
|
415
|
+
* ```typescript
|
|
416
|
+
* const orphans = builder.orphans()
|
|
417
|
+
* if (orphans.length > 0) {
|
|
418
|
+
* console.warn('Orphaned components:', orphans)
|
|
419
|
+
* }
|
|
420
|
+
* ```
|
|
421
|
+
*/
|
|
422
|
+
orphans(): string[];
|
|
423
|
+
/**
|
|
424
|
+
* Returns a RiviereQuery instance for the current graph state.
|
|
425
|
+
*
|
|
426
|
+
* Enables querying mid-construction without affecting builder state.
|
|
427
|
+
*
|
|
428
|
+
* @returns RiviereQuery instance for the current graph
|
|
429
|
+
*
|
|
430
|
+
* @example
|
|
431
|
+
* ```typescript
|
|
432
|
+
* const query = builder.query()
|
|
433
|
+
* const apis = query.componentsByType('API')
|
|
434
|
+
* ```
|
|
435
|
+
*/
|
|
436
|
+
query(): RiviereQuery;
|
|
437
|
+
/**
|
|
438
|
+
* Serializes the current graph state as a JSON string.
|
|
439
|
+
*
|
|
440
|
+
* Does not validate. Use for saving drafts mid-construction
|
|
441
|
+
* that can be resumed later with RiviereBuilder.resume().
|
|
442
|
+
*
|
|
443
|
+
* @returns JSON string representation of the graph
|
|
444
|
+
*
|
|
445
|
+
* @example
|
|
446
|
+
* ```typescript
|
|
447
|
+
* const json = builder.serialize()
|
|
448
|
+
* await fs.writeFile('draft.json', json)
|
|
449
|
+
* ```
|
|
450
|
+
*/
|
|
451
|
+
serialize(): string;
|
|
452
|
+
/**
|
|
453
|
+
* Validates and returns the completed graph.
|
|
454
|
+
*
|
|
455
|
+
* @returns Valid RiviereGraph object
|
|
456
|
+
* @throws If validation fails with error details
|
|
457
|
+
*
|
|
458
|
+
* @example
|
|
459
|
+
* ```typescript
|
|
460
|
+
* try {
|
|
461
|
+
* const graph = builder.build()
|
|
462
|
+
* console.log('Graph built successfully')
|
|
463
|
+
* } catch (error) {
|
|
464
|
+
* console.error('Build failed:', error.message)
|
|
465
|
+
* }
|
|
466
|
+
* ```
|
|
467
|
+
*/
|
|
468
|
+
build(): RiviereGraph;
|
|
469
|
+
/**
|
|
470
|
+
* Validates the graph and writes it to a file.
|
|
471
|
+
*
|
|
472
|
+
* @param path - Absolute or relative file path to write
|
|
473
|
+
* @throws If validation fails
|
|
474
|
+
* @throws If the directory does not exist
|
|
475
|
+
* @throws If write fails
|
|
476
|
+
*
|
|
477
|
+
* @example
|
|
478
|
+
* ```typescript
|
|
479
|
+
* await builder.save('./output/architecture.json')
|
|
480
|
+
* ```
|
|
481
|
+
*/
|
|
482
|
+
save(path: string): Promise<void>;
|
|
483
|
+
private sourceNotFoundError;
|
|
484
|
+
}
|
|
485
|
+
//# sourceMappingURL=builder.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"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"}
|