@living-architecture/riviere-builder 0.2.1

package/dist/builder.js

@@ -0,0 +1,749 @@
+import { promises as fs } from 'node:fs';
+import { dirname } from 'node:path';
+import { RiviereQuery } from '@living-architecture/riviere-query';
+import { calculateStats, findOrphans, findWarnings, toRiviereGraph, validateGraph } from './inspection';
+import { assertCustomTypeExists, assertDomainExists, assertRequiredPropertiesProvided } from './builder-assertions';
+import { ComponentId } from '@living-architecture/riviere-schema';
+import { createSourceNotFoundError, findNearMatches } from './component-suggestion';
+import { DuplicateComponentError, DuplicateDomainError, InvalidEnrichmentTargetError } from './errors';
+/**
+ * Programmatically construct Rivière architecture graphs.
+ *
+ * RiviereBuilder provides a fluent API for creating graphs, adding components,
+ * linking them together, and exporting valid JSON conforming to the Rivière schema.
+ *
+ * @example
+ * ```typescript
+ * import { RiviereBuilder } from '@living-architecture/riviere-builder'
+ *
+ * const builder = RiviereBuilder.new({
+ *   sources: [{ type: 'git', url: 'https://github.com/org/repo' }],
+ *   domains: { orders: { description: 'Order management' } }
+ * })
+ *
+ * const api = builder.addApi({
+ *   name: 'Create Order',
+ *   domain: 'orders',
+ *   module: 'checkout',
+ *   apiType: 'REST',
+ *   sourceLocation: { file: 'src/api/orders.ts', line: 10 }
+ * })
+ *
+ * const graph = builder.build()
+ * ```
+ */
+export class RiviereBuilder {
+    graph;
+    constructor(graph) {
+        this.graph = graph;
+    }
+    /**
+     * Restores a builder from a previously serialized graph.
+     *
+     * Use this to continue building a graph that was saved mid-construction,
+     * or to modify an existing graph.
+     *
+     * @param graph - A valid RiviereGraph object to resume from
+     * @returns A new RiviereBuilder instance with the graph state restored
+     * @throws If the graph is missing required sources
+     *
+     * @example
+     * ```typescript
+     * const json = await fs.readFile('draft.json', 'utf-8')
+     * const graph = JSON.parse(json)
+     * const builder = RiviereBuilder.resume(graph)
+     * builder.addApi({ ... })
+     * ```
+     */
+    static resume(graph) {
+        if (!graph.metadata.sources || graph.metadata.sources.length === 0) {
+            throw new Error('Invalid graph: missing sources');
+        }
+        const builderGraph = {
+            version: graph.version,
+            metadata: {
+                ...graph.metadata,
+                sources: graph.metadata.sources,
+                customTypes: graph.metadata.customTypes ?? {},
+            },
+            components: graph.components,
+            links: graph.links,
+            externalLinks: graph.externalLinks ?? [],
+        };
+        return new RiviereBuilder(builderGraph);
+    }
+    /**
+     * Creates a new builder with initial configuration.
+     *
+     * @param options - Configuration including sources and domains
+     * @returns A new RiviereBuilder instance
+     * @throws If sources array is empty
+     * @throws If domains object is empty
+     *
+     * @example
+     * ```typescript
+     * const builder = RiviereBuilder.new({
+     *   name: 'My System',
+     *   sources: [{ type: 'git', url: 'https://github.com/org/repo' }],
+     *   domains: {
+     *     orders: { description: 'Order management' },
+     *     users: { description: 'User accounts' }
+     *   }
+     * })
+     * ```
+     */
+    static new(options) {
+        if (options.sources.length === 0) {
+            throw new Error('At least one source required');
+        }
+        if (Object.keys(options.domains).length === 0) {
+            throw new Error('At least one domain required');
+        }
+        const graph = {
+            version: '1.0',
+            metadata: {
+                ...(options.name !== undefined && { name: options.name }),
+                ...(options.description !== undefined && { description: options.description }),
+                sources: options.sources,
+                domains: options.domains,
+                customTypes: {},
+            },
+            components: [],
+            links: [],
+            externalLinks: [],
+        };
+        return new RiviereBuilder(graph);
+    }
+    /**
+     * Adds an additional source repository to the graph.
+     *
+     * @param source - Source repository information
+     *
+     * @example
+     * ```typescript
+     * builder.addSource({
+     *   type: 'git',
+     *   url: 'https://github.com/org/another-repo'
+     * })
+     * ```
+     */
+    addSource(source) {
+        this.graph.metadata.sources.push(source);
+    }
+    /**
+     * Adds a new domain to the graph.
+     *
+     * @param input - Domain name and description
+     * @throws If domain with same name already exists
+     *
+     * @example
+     * ```typescript
+     * builder.addDomain({
+     *   name: 'payments',
+     *   description: 'Payment processing'
+     * })
+     * ```
+     */
+    addDomain(input) {
+        if (this.graph.metadata.domains[input.name]) {
+            throw new DuplicateDomainError(input.name);
+        }
+        this.graph.metadata.domains[input.name] = {
+            description: input.description,
+            systemType: input.systemType,
+        };
+    }
+    /**
+     * Adds a UI component to the graph.
+     *
+     * @param input - UI component properties including route and source location
+     * @returns The created UI component with generated ID
+     * @throws If the specified domain does not exist
+     *
+     * @example
+     * ```typescript
+     * const ui = builder.addUI({
+     *   name: 'Order List',
+     *   domain: 'orders',
+     *   module: 'dashboard',
+     *   route: '/orders',
+     *   sourceLocation: { file: 'src/pages/OrderList.tsx', line: 15 }
+     * })
+     * ```
+     */
+    addUI(input) {
+        this.validateDomainExists(input.domain);
+        const id = this.generateComponentId(input.domain, input.module, 'ui', input.name);
+        const component = {
+            id,
+            type: 'UI',
+            name: input.name,
+            domain: input.domain,
+            module: input.module,
+            route: input.route,
+            sourceLocation: input.sourceLocation,
+            ...(input.description !== undefined && { description: input.description }),
+            ...(input.metadata !== undefined && { metadata: input.metadata }),
+        };
+        return this.registerComponent(component);
+    }
+    /**
+     * Adds an API component to the graph.
+     *
+     * @param input - API component properties including type, method, and path
+     * @returns The created API component with generated ID
+     * @throws If the specified domain does not exist
+     *
+     * @example
+     * ```typescript
+     * const api = builder.addApi({
+     *   name: 'Create Order',
+     *   domain: 'orders',
+     *   module: 'checkout',
+     *   apiType: 'REST',
+     *   httpMethod: 'POST',
+     *   path: '/api/orders',
+     *   sourceLocation: { file: 'src/api/orders.ts', line: 25 }
+     * })
+     * ```
+     */
+    addApi(input) {
+        this.validateDomainExists(input.domain);
+        const id = this.generateComponentId(input.domain, input.module, 'api', input.name);
+        const component = {
+            id,
+            type: 'API',
+            name: input.name,
+            domain: input.domain,
+            module: input.module,
+            apiType: input.apiType,
+            sourceLocation: input.sourceLocation,
+            ...(input.httpMethod !== undefined && { httpMethod: input.httpMethod }),
+            ...(input.path !== undefined && { path: input.path }),
+            ...(input.operationName !== undefined && { operationName: input.operationName }),
+            ...(input.description !== undefined && { description: input.description }),
+            ...(input.metadata !== undefined && { metadata: input.metadata }),
+        };
+        return this.registerComponent(component);
+    }
+    /**
+     * Adds a UseCase component to the graph.
+     *
+     * @param input - UseCase component properties
+     * @returns The created UseCase component with generated ID
+     * @throws If the specified domain does not exist
+     *
+     * @example
+     * ```typescript
+     * const useCase = builder.addUseCase({
+     *   name: 'Place Order',
+     *   domain: 'orders',
+     *   module: 'checkout',
+     *   sourceLocation: { file: 'src/usecases/PlaceOrder.ts', line: 10 }
+     * })
+     * ```
+     */
+    addUseCase(input) {
+        this.validateDomainExists(input.domain);
+        const id = this.generateComponentId(input.domain, input.module, 'usecase', input.name);
+        const component = {
+            id,
+            type: 'UseCase',
+            name: input.name,
+            domain: input.domain,
+            module: input.module,
+            sourceLocation: input.sourceLocation,
+            ...(input.description !== undefined && { description: input.description }),
+            ...(input.metadata !== undefined && { metadata: input.metadata }),
+        };
+        return this.registerComponent(component);
+    }
+    /**
+     * Adds a DomainOp component to the graph.
+     *
+     * DomainOp represents domain operations that change entity state.
+     * Can be enriched later with state changes and business rules.
+     *
+     * @param input - DomainOp component properties including operation name
+     * @returns The created DomainOp component with generated ID
+     * @throws If the specified domain does not exist
+     *
+     * @example
+     * ```typescript
+     * const domainOp = builder.addDomainOp({
+     *   name: 'Confirm Order',
+     *   domain: 'orders',
+     *   module: 'fulfillment',
+     *   operationName: 'confirmOrder',
+     *   entity: 'Order',
+     *   sourceLocation: { file: 'src/domain/Order.ts', line: 45 }
+     * })
+     * ```
+     */
+    addDomainOp(input) {
+        this.validateDomainExists(input.domain);
+        const id = this.generateComponentId(input.domain, input.module, 'domainop', input.name);
+        const component = {
+            id,
+            type: 'DomainOp',
+            name: input.name,
+            domain: input.domain,
+            module: input.module,
+            operationName: input.operationName,
+            sourceLocation: input.sourceLocation,
+            ...(input.entity !== undefined && { entity: input.entity }),
+            ...(input.signature !== undefined && { signature: input.signature }),
+            ...(input.behavior !== undefined && { behavior: input.behavior }),
+            ...(input.stateChanges !== undefined && { stateChanges: input.stateChanges }),
+            ...(input.businessRules !== undefined && { businessRules: input.businessRules }),
+            ...(input.description !== undefined && { description: input.description }),
+            ...(input.metadata !== undefined && { metadata: input.metadata }),
+        };
+        return this.registerComponent(component);
+    }
+    /**
+     * Adds an Event component to the graph.
+     *
+     * @param input - Event component properties including event name
+     * @returns The created Event component with generated ID
+     * @throws If the specified domain does not exist
+     *
+     * @example
+     * ```typescript
+     * const event = builder.addEvent({
+     *   name: 'Order Placed',
+     *   domain: 'orders',
+     *   module: 'checkout',
+     *   eventName: 'OrderPlaced',
+     *   sourceLocation: { file: 'src/events/OrderPlaced.ts', line: 5 }
+     * })
+     * ```
+     */
+    addEvent(input) {
+        this.validateDomainExists(input.domain);
+        const id = this.generateComponentId(input.domain, input.module, 'event', input.name);
+        const component = {
+            id,
+            type: 'Event',
+            name: input.name,
+            domain: input.domain,
+            module: input.module,
+            eventName: input.eventName,
+            sourceLocation: input.sourceLocation,
+            ...(input.eventSchema !== undefined && { eventSchema: input.eventSchema }),
+            ...(input.description !== undefined && { description: input.description }),
+            ...(input.metadata !== undefined && { metadata: input.metadata }),
+        };
+        return this.registerComponent(component);
+    }
+    /**
+     * Adds an EventHandler component to the graph.
+     *
+     * @param input - EventHandler component properties including subscribed events
+     * @returns The created EventHandler component with generated ID
+     * @throws If the specified domain does not exist
+     *
+     * @example
+     * ```typescript
+     * const handler = builder.addEventHandler({
+     *   name: 'Send Confirmation Email',
+     *   domain: 'notifications',
+     *   module: 'email',
+     *   subscribedEvents: ['OrderPlaced'],
+     *   sourceLocation: { file: 'src/handlers/OrderConfirmation.ts', line: 10 }
+     * })
+     * ```
+     */
+    addEventHandler(input) {
+        this.validateDomainExists(input.domain);
+        const id = this.generateComponentId(input.domain, input.module, 'eventhandler', input.name);
+        const component = {
+            id,
+            type: 'EventHandler',
+            name: input.name,
+            domain: input.domain,
+            module: input.module,
+            subscribedEvents: input.subscribedEvents,
+            sourceLocation: input.sourceLocation,
+            ...(input.description !== undefined && { description: input.description }),
+            ...(input.metadata !== undefined && { metadata: input.metadata }),
+        };
+        return this.registerComponent(component);
+    }
+    /**
+     * Defines a custom component type for the graph.
+     *
+     * Custom types allow extending the schema with domain-specific component kinds.
+     * Must be defined before adding custom components of that type.
+     *
+     * @param input - Custom type definition with required and optional properties
+     * @throws If a custom type with the same name already exists
+     *
+     * @example
+     * ```typescript
+     * builder.defineCustomType({
+     *   name: 'MessageQueue',
+     *   description: 'Async message queue',
+     *   requiredProperties: {
+     *     queueName: { type: 'string', description: 'Queue identifier' }
+     *   }
+     * })
+     * ```
+     */
+    defineCustomType(input) {
+        const customTypes = this.graph.metadata.customTypes;
+        if (customTypes[input.name]) {
+            throw new Error(`Custom type '${input.name}' already defined`);
+        }
+        customTypes[input.name] = {
+            ...(input.requiredProperties !== undefined && { requiredProperties: input.requiredProperties }),
+            ...(input.optionalProperties !== undefined && { optionalProperties: input.optionalProperties }),
+            ...(input.description !== undefined && { description: input.description }),
+        };
+    }
+    /**
+     * Adds a Custom component to the graph.
+     *
+     * Custom components use types defined via defineCustomType().
+     * Validates that the custom type exists and required properties are provided.
+     *
+     * @param input - Custom component properties including type name and metadata
+     * @returns The created Custom component with generated ID
+     * @throws If the specified domain does not exist
+     * @throws If the custom type has not been defined
+     * @throws If required properties for the custom type are missing
+     *
+     * @example
+     * ```typescript
+     * const queue = builder.addCustom({
+     *   customTypeName: 'MessageQueue',
+     *   name: 'Order Events Queue',
+     *   domain: 'orders',
+     *   module: 'messaging',
+     *   sourceLocation: { file: 'src/queues/orders.ts', line: 5 },
+     *   metadata: { queueName: 'order-events' }
+     * })
+     * ```
+     */
+    addCustom(input) {
+        this.validateDomainExists(input.domain);
+        this.validateCustomType(input.customTypeName);
+        this.validateRequiredProperties(input.customTypeName, input.metadata);
+        const id = this.generateComponentId(input.domain, input.module, 'custom', input.name);
+        const component = {
+            id,
+            type: 'Custom',
+            customTypeName: input.customTypeName,
+            name: input.name,
+            domain: input.domain,
+            module: input.module,
+            sourceLocation: input.sourceLocation,
+            ...(input.description !== undefined && { description: input.description }),
+            ...(input.metadata !== undefined && { metadata: input.metadata }),
+        };
+        return this.registerComponent(component);
+    }
+    /**
+     * Enriches a DomainOp component with additional domain details.
+     *
+     * Adds state changes and business rules to an existing DomainOp.
+     * Multiple enrichments accumulate rather than replace.
+     *
+     * @param id - The component ID to enrich
+     * @param enrichment - State changes and business rules to add
+     * @throws If the component does not exist
+     * @throws If the component is not a DomainOp type
+     *
+     * @example
+     * ```typescript
+     * builder.enrichComponent('orders:fulfillment:domainop:confirm-order', {
+     *   entity: 'Order',
+     *   stateChanges: [{ entity: 'Order', from: 'pending', to: 'confirmed' }],
+     *   businessRules: ['Order must have valid payment']
+     * })
+     * ```
+     */
+    enrichComponent(id, enrichment) {
+        const component = this.graph.components.find((c) => c.id === id);
+        if (!component) {
+            throw this.componentNotFoundError(id);
+        }
+        if (component.type !== 'DomainOp') {
+            throw new InvalidEnrichmentTargetError(id, component.type);
+        }
+        if (enrichment.entity !== undefined) {
+            component.entity = enrichment.entity;
+        }
+        if (enrichment.stateChanges !== undefined) {
+            component.stateChanges = [...(component.stateChanges ?? []), ...enrichment.stateChanges];
+        }
+        if (enrichment.businessRules !== undefined) {
+            component.businessRules = [...(component.businessRules ?? []), ...enrichment.businessRules];
+        }
+    }
+    componentNotFoundError(id) {
+        return createSourceNotFoundError(this.graph.components, ComponentId.parse(id));
+    }
+    validateDomainExists(domain) {
+        assertDomainExists(this.graph.metadata.domains, domain);
+    }
+    validateCustomType(customTypeName) {
+        assertCustomTypeExists(this.graph.metadata.customTypes, customTypeName);
+    }
+    validateRequiredProperties(customTypeName, metadata) {
+        assertRequiredPropertiesProvided(this.graph.metadata.customTypes, customTypeName, metadata);
+    }
+    generateComponentId(domain, module, type, name) {
+        const nameSegment = name.toLowerCase().replace(/\s+/g, '-');
+        return `${domain}:${module}:${type}:${nameSegment}`;
+    }
+    registerComponent(component) {
+        if (this.graph.components.some((c) => c.id === component.id)) {
+            throw new DuplicateComponentError(component.id);
+        }
+        this.graph.components.push(component);
+        return component;
+    }
+    /**
+     * Finds components similar to a query for error recovery.
+     *
+     * Returns fuzzy matches when an exact component lookup fails,
+     * enabling actionable error messages with "Did you mean...?" suggestions.
+     *
+     * @param query - Search criteria including partial ID, name, type, or domain
+     * @param options - Optional matching thresholds and limits
+     * @returns Array of similar components with similarity scores
+     *
+     * @example
+     * ```typescript
+     * const matches = builder.nearMatches({ name: 'Place Ordr' })
+     * // [{ component: {...}, score: 0.9, mismatches: [...] }]
+     * ```
+     */
+    nearMatches(query, options) {
+        return findNearMatches(this.graph.components, query, options);
+    }
+    /**
+     * Creates a link between two components in the graph.
+     *
+     * Source component must exist; target validation is deferred to build().
+     * Use linkExternal() for connections to external systems.
+     *
+     * @param input - Link properties including source, target, and type
+     * @returns The created link
+     * @throws If the source component does not exist
+     *
+     * @example
+     * ```typescript
+     * const link = builder.link({
+     *   from: 'orders:checkout:api:create-order',
+     *   to: 'orders:checkout:usecase:place-order',
+     *   type: 'sync'
+     * })
+     * ```
+     */
+    link(input) {
+        const sourceExists = this.graph.components.some((c) => c.id === input.from);
+        if (!sourceExists) {
+            throw this.sourceNotFoundError(input.from);
+        }
+        const link = {
+            source: input.from,
+            target: input.to,
+            ...(input.type !== undefined && { type: input.type }),
+        };
+        this.graph.links.push(link);
+        return link;
+    }
+    /**
+     * Creates a link from a component to an external system.
+     *
+     * Use this for connections to systems outside the graph,
+     * such as third-party APIs or external databases.
+     *
+     * @param input - External link properties including target system info
+     * @returns The created external link
+     * @throws If the source component does not exist
+     *
+     * @example
+     * ```typescript
+     * const link = builder.linkExternal({
+     *   from: 'orders:payments:usecase:process-payment',
+     *   target: { name: 'Stripe API', domain: 'payments' },
+     *   type: 'sync'
+     * })
+     * ```
+     */
+    linkExternal(input) {
+        const sourceExists = this.graph.components.some((c) => c.id === input.from);
+        if (!sourceExists) {
+            throw this.sourceNotFoundError(input.from);
+        }
+        const externalLink = {
+            source: input.from,
+            target: input.target,
+            ...(input.type !== undefined && { type: input.type }),
+            ...(input.description !== undefined && { description: input.description }),
+            ...(input.sourceLocation !== undefined && { sourceLocation: input.sourceLocation }),
+            ...(input.metadata !== undefined && { metadata: input.metadata }),
+        };
+        this.graph.externalLinks.push(externalLink);
+        return externalLink;
+    }
+    /**
+     * Returns non-fatal issues found in the graph.
+     *
+     * Warnings indicate potential problems that don't prevent building,
+     * such as orphaned components or unused domains.
+     *
+     * @returns Array of warning objects with type and message
+     *
+     * @example
+     * ```typescript
+     * const warnings = builder.warnings()
+     * for (const w of warnings) {
+     *   console.log(`${w.type}: ${w.message}`)
+     * }
+     * ```
+     */
+    warnings() {
+        return findWarnings(this.graph);
+    }
+    /**
+     * Returns statistics about the current graph state.
+     *
+     * @returns Counts of components by type, domains, and links
+     *
+     * @example
+     * ```typescript
+     * const stats = builder.stats()
+     * console.log(`Components: ${stats.componentCount}`)
+     * console.log(`Links: ${stats.linkCount}`)
+     * ```
+     */
+    stats() {
+        return calculateStats(this.graph);
+    }
+    /**
+     * Runs full validation on the graph.
+     *
+     * Checks for dangling references, orphans, and schema compliance.
+     * Called automatically by build().
+     *
+     * @returns Validation result with valid flag and error details
+     *
+     * @example
+     * ```typescript
+     * const result = builder.validate()
+     * if (!result.valid) {
+     *   for (const error of result.errors) {
+     *     console.error(error.message)
+     *   }
+     * }
+     * ```
+     */
+    validate() {
+        return validateGraph(this.graph);
+    }
+    /**
+     * Returns IDs of components with no incoming or outgoing links.
+     *
+     * @returns Array of orphaned component IDs
+     *
+     * @example
+     * ```typescript
+     * const orphans = builder.orphans()
+     * if (orphans.length > 0) {
+     *   console.warn('Orphaned components:', orphans)
+     * }
+     * ```
+     */
+    orphans() {
+        return findOrphans(this.graph);
+    }
+    /**
+     * Returns a RiviereQuery instance for the current graph state.
+     *
+     * Enables querying mid-construction without affecting builder state.
+     *
+     * @returns RiviereQuery instance for the current graph
+     *
+     * @example
+     * ```typescript
+     * const query = builder.query()
+     * const apis = query.componentsByType('API')
+     * ```
+     */
+    query() {
+        return new RiviereQuery(toRiviereGraph(this.graph));
+    }
+    /**
+     * Serializes the current graph state as a JSON string.
+     *
+     * Does not validate. Use for saving drafts mid-construction
+     * that can be resumed later with RiviereBuilder.resume().
+     *
+     * @returns JSON string representation of the graph
+     *
+     * @example
+     * ```typescript
+     * const json = builder.serialize()
+     * await fs.writeFile('draft.json', json)
+     * ```
+     */
+    serialize() {
+        return JSON.stringify(this.graph, null, 2);
+    }
+    /**
+     * Validates and returns the completed graph.
+     *
+     * @returns Valid RiviereGraph object
+     * @throws If validation fails with error details
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const graph = builder.build()
+     *   console.log('Graph built successfully')
+     * } catch (error) {
+     *   console.error('Build failed:', error.message)
+     * }
+     * ```
+     */
+    build() {
+        const result = this.validate();
+        if (!result.valid) {
+            const messages = result.errors.map((e) => e.message).join('; ');
+            throw new Error(`Validation failed: ${messages}`);
+        }
+        return toRiviereGraph(this.graph);
+    }
+    /**
+     * Validates the graph and writes it to a file.
+     *
+     * @param path - Absolute or relative file path to write
+     * @throws If validation fails
+     * @throws If the directory does not exist
+     * @throws If write fails
+     *
+     * @example
+     * ```typescript
+     * await builder.save('./output/architecture.json')
+     * ```
+     */
+    async save(path) {
+        const graph = this.build();
+        const dir = dirname(path);
+        try {
+            await fs.access(dir);
+        }
+        catch {
+            throw new Error(`Directory does not exist: ${dir}`);
+        }
+        const json = JSON.stringify(graph, null, 2);
+        await fs.writeFile(path, json, 'utf-8');
+    }
+    sourceNotFoundError(id) {
+        return createSourceNotFoundError(this.graph.components, ComponentId.parse(id));
+    }
+}