@domainlang/language 0.1.81

package/out/sdk/query.js

@@ -0,0 +1,679 @@
+/**
+ * Query and QueryBuilder implementation for the Model Query SDK.
+ * Provides fluent, lazy evaluation of model queries.
+ */
+import { AstUtils } from 'langium';
+import { isBoundedContext, isClassification, isContextMap, isDomain, isDomainMap, isModel, isNamespaceDeclaration, isTeam, isThisRef, } from '../generated/ast.js';
+import { QualifiedNameProvider } from '../lsp/domain-lang-naming.js';
+import { buildIndexes } from './indexes.js';
+import { metadataAsMap, effectiveClassification, effectiveTeam, } from './resolution.js';
+import { isDownstreamPattern, isUpstreamPattern, matchesPattern } from './patterns.js';
+/**
+ * Tracks which models have been augmented to avoid redundant augmentation.
+ * Uses WeakSet to allow garbage collection of unused models.
+ */
+const augmentedModels = new WeakSet();
+/**
+ * Ensures a model is augmented with SDK properties.
+ * Idempotent - safe to call multiple times.
+ *
+ * @param model - Model to ensure is augmented
+ */
+function ensureAugmented(model) {
+    if (!augmentedModels.has(model)) {
+        augmentModelInternal(model);
+        augmentedModels.add(model);
+    }
+}
+/**
+ * Creates a Query instance from a Model node.
+ * Zero-copy operation for already-linked AST (used in LSP/validation).
+ *
+ * Automatically augments the AST with resolved properties on first access.
+ *
+ * @param model - Root Model node
+ * @returns Query interface for model traversal
+ */
+export function fromModel(model) {
+    ensureAugmented(model);
+    return new QueryImpl(model);
+}
+/**
+ * Creates a Query instance from a LangiumDocument.
+ * Zero-copy operation for already-linked AST (used in LSP providers).
+ *
+ * Automatically augments the AST with resolved properties on first access.
+ *
+ * @param document - LangiumDocument containing a Model
+ * @returns Query interface for model traversal
+ */
+export function fromDocument(document) {
+    const model = document.parseResult.value;
+    ensureAugmented(model);
+    return new QueryImpl(model);
+}
+/**
+ * Creates a Query instance from DomainLangServices and document URI.
+ * Zero-copy operation for already-linked AST (used when only services available).
+ *
+ * Automatically augments the AST with resolved properties on first access.
+ *
+ * @param services - DomainLangServices instance
+ * @param documentUri - URI of the document to query
+ * @returns Query interface for model traversal
+ * @throws Error if document not found or not a Model
+ */
+export function fromServices(services, documentUri) {
+    const document = services.shared.workspace.LangiumDocuments.getDocument(documentUri);
+    if (!document) {
+        throw new Error(`Document not found: ${documentUri.toString()}`);
+    }
+    const model = document.parseResult.value;
+    if (!isModel(model)) {
+        throw new Error(`Document root is not a Model: ${documentUri.toString()}`);
+    }
+    ensureAugmented(model);
+    return new QueryImpl(model);
+}
+/**
+ * Implementation of Query interface.
+ * Lazily builds indexes on first access.
+ */
+class QueryImpl {
+    constructor(model) {
+        this.model = model;
+        this.fqnProvider = new QualifiedNameProvider();
+    }
+    /**
+     * Lazily builds and caches indexes on first access.
+     */
+    getIndexes() {
+        if (!this.indexes) {
+            this.indexes = buildIndexes(this.model);
+        }
+        return this.indexes;
+    }
+    domains() {
+        // Use generator for lazy iteration per PRS requirement
+        const model = this.model;
+        function* domainIterator() {
+            for (const node of AstUtils.streamAllContents(model)) {
+                if (isDomain(node)) {
+                    yield node;
+                }
+            }
+        }
+        return new QueryBuilderImpl(domainIterator(), this.fqnProvider);
+    }
+    boundedContexts() {
+        // Use generator for lazy iteration per PRS requirement
+        const model = this.model;
+        function* bcIterator() {
+            for (const node of AstUtils.streamAllContents(model)) {
+                if (isBoundedContext(node)) {
+                    yield node;
+                }
+            }
+        }
+        return new BcQueryBuilderImpl(bcIterator(), this.fqnProvider, this.getIndexes());
+    }
+    teams() {
+        // Use generator for lazy iteration
+        const model = this.model;
+        function* teamIterator() {
+            for (const node of AstUtils.streamAllContents(model)) {
+                if (isTeam(node)) {
+                    yield node;
+                }
+            }
+        }
+        return new QueryBuilderImpl(teamIterator(), this.fqnProvider);
+    }
+    classifications() {
+        // Use generator for lazy iteration
+        const model = this.model;
+        function* classIterator() {
+            for (const node of AstUtils.streamAllContents(model)) {
+                if (isClassification(node)) {
+                    yield node;
+                }
+            }
+        }
+        return new QueryBuilderImpl(classIterator(), this.fqnProvider);
+    }
+    relationships() {
+        // Use generator for lazy iteration - combines BC and ContextMap relationships
+        return new QueryBuilderImpl(this.iterateRelationships(), this.fqnProvider);
+    }
+    /** @internal Generator for relationship iteration */
+    *iterateRelationships() {
+        // Collect relationships defined on bounded contexts
+        for (const node of AstUtils.streamAllContents(this.model)) {
+            if (isBoundedContext(node)) {
+                for (const rel of node.relationships) {
+                    const view = this.createRelationshipView(rel, node, 'BoundedContext');
+                    if (view) {
+                        yield view;
+                    }
+                }
+            }
+        }
+        // Collect from ContextMap.relationships
+        for (const node of AstUtils.streamAllContents(this.model)) {
+            if (isContextMap(node)) {
+                for (const rel of node.relationships) {
+                    const view = this.createRelationshipView(rel, undefined, 'ContextMap');
+                    if (view) {
+                        yield view;
+                    }
+                }
+            }
+        }
+    }
+    contextMaps() {
+        const model = this.model;
+        function* cmapIterator() {
+            for (const node of AstUtils.streamAllContents(model)) {
+                if (isContextMap(node)) {
+                    yield node;
+                }
+            }
+        }
+        return new QueryBuilderImpl(cmapIterator(), this.fqnProvider);
+    }
+    domainMaps() {
+        const model = this.model;
+        function* dmapIterator() {
+            for (const node of AstUtils.streamAllContents(model)) {
+                if (isDomainMap(node)) {
+                    yield node;
+                }
+            }
+        }
+        return new QueryBuilderImpl(dmapIterator(), this.fqnProvider);
+    }
+    namespaces() {
+        const model = this.model;
+        function* nsIterator() {
+            for (const node of AstUtils.streamAllContents(model)) {
+                if (isNamespaceDeclaration(node)) {
+                    yield node;
+                }
+            }
+        }
+        return new QueryBuilderImpl(nsIterator(), this.fqnProvider);
+    }
+    byFqn(fqn) {
+        return this.getIndexes().byFqn.get(fqn);
+    }
+    domain(name) {
+        // Try FQN lookup first
+        const byFqn = this.byFqn(name);
+        if (byFqn) {
+            return byFqn;
+        }
+        // Fallback to simple name lookup
+        const nodes = this.getIndexes().byName.get(name) ?? [];
+        return nodes.find(isDomain);
+    }
+    boundedContext(name) {
+        // Try FQN lookup first
+        const byFqn = this.byFqn(name);
+        if (byFqn) {
+            return byFqn;
+        }
+        // Fallback to simple name lookup
+        const nodes = this.getIndexes().byName.get(name) ?? [];
+        return nodes.find(isBoundedContext);
+    }
+    bc(name) {
+        return this.boundedContext(name);
+    }
+    team(name) {
+        const nodes = this.getIndexes().byName.get(name) ?? [];
+        return nodes.find(isTeam);
+    }
+    fqn(node) {
+        if ('name' in node && typeof node.name === 'string' && node.$container) {
+            const container = node.$container;
+            if (isModel(container) || isNamespaceDeclaration(container)) {
+                return this.fqnProvider.getQualifiedName(container, node.name);
+            }
+        }
+        return '';
+    }
+    /**
+     * Creates a RelationshipView from a Relationship AST node.
+     * Resolves 'this' references to the containing BoundedContext.
+     */
+    createRelationshipView(rel, containingBc, source) {
+        const left = this.resolveContextRef(rel.left, containingBc);
+        const right = this.resolveContextRef(rel.right, containingBc);
+        if (!left || !right) {
+            return undefined;
+        }
+        return {
+            left,
+            right,
+            arrow: rel.arrow,
+            leftPatterns: rel.leftPatterns,
+            rightPatterns: rel.rightPatterns,
+            type: rel.type,
+            inferredType: this.inferRelationshipType(rel),
+            source,
+            astNode: rel,
+        };
+    }
+    /**
+     * Resolves a BoundedContextRef to a BoundedContext.
+     * Handles 'this' references by using the containing BoundedContext.
+     */
+    resolveContextRef(ref, containingBc) {
+        if (isThisRef(ref)) {
+            return containingBc;
+        }
+        return ref.link?.ref;
+    }
+    /**
+     * Infers relationship type from integration patterns.
+     * Simple heuristic based on common DDD pattern combinations.
+     */
+    inferRelationshipType(rel) {
+        const leftPatterns = rel.leftPatterns;
+        const rightPatterns = rel.rightPatterns;
+        // Partnership: Bidirectional with P or SK
+        if (rel.arrow === '<->' && (leftPatterns.includes('P') || leftPatterns.includes('SK'))) {
+            return 'Partnership';
+        }
+        // Shared Kernel: SK pattern
+        if (leftPatterns.includes('SK') || rightPatterns.includes('SK')) {
+            return 'SharedKernel';
+        }
+        // Customer-Supplier: OHS + CF
+        if (leftPatterns.includes('OHS') && rightPatterns.includes('CF')) {
+            return 'CustomerSupplier';
+        }
+        // Upstream-Downstream: directional arrow
+        if (rel.arrow === '->') {
+            return 'UpstreamDownstream';
+        }
+        // Separate Ways
+        if (rel.arrow === '><') {
+            return 'SeparateWays';
+        }
+        return undefined;
+    }
+}
+/**
+ * Base implementation of QueryBuilder with lazy iteration.
+ * Predicates are chained and only evaluated during iteration.
+ */
+class QueryBuilderImpl {
+    constructor(items, fqnProvider, predicates = []) {
+        this.fqnProvider = fqnProvider;
+        this.sourceItems = items;
+        this.predicateList = predicates;
+    }
+    where(predicate) {
+        return new QueryBuilderImpl(this.sourceItems, this.fqnProvider, [...this.predicateList, predicate]);
+    }
+    withName(pattern) {
+        const regex = typeof pattern === 'string' ? new RegExp(`^${escapeRegex(pattern)}$`) : pattern;
+        return this.where((item) => {
+            const node = item;
+            if ('name' in node && typeof node.name === 'string') {
+                return regex.test(node.name);
+            }
+            return false;
+        });
+    }
+    withFqn(pattern) {
+        const regex = typeof pattern === 'string' ? new RegExp(`^${escapeRegex(pattern)}$`) : pattern;
+        return this.where((item) => {
+            const node = item;
+            if ('name' in node && typeof node.name === 'string' && node.$container) {
+                const container = node.$container;
+                if (isModel(container) || isNamespaceDeclaration(container)) {
+                    const fqn = this.fqnProvider.getQualifiedName(container, node.name);
+                    return regex.test(fqn);
+                }
+            }
+            return false;
+        });
+    }
+    first() {
+        for (const item of this) {
+            return item;
+        }
+        return undefined;
+    }
+    toArray() {
+        return Array.from(this);
+    }
+    count() {
+        let count = 0;
+        for (const _ of this) {
+            count++;
+        }
+        return count;
+    }
+    *[Symbol.iterator]() {
+        for (const item of this.sourceItems) {
+            if (this.predicateList.every(p => p(item))) {
+                yield item;
+            }
+        }
+    }
+}
+/**
+ * BoundedContext-specific QueryBuilder with domain filters.
+ * Supports indexed lookups for performance when filters allow.
+ */
+class BcQueryBuilderImpl extends QueryBuilderImpl {
+    constructor(items, fqnProvider, indexes, predicates = []) {
+        super(items, fqnProvider, predicates);
+        this.indexes = indexes;
+    }
+    where(predicate) {
+        return new BcQueryBuilderImpl(this.sourceItems, this.fqnProvider, this.indexes, [...this.predicateList, predicate]);
+    }
+    withName(pattern) {
+        return super.withName(pattern);
+    }
+    withFqn(pattern) {
+        return super.withFqn(pattern);
+    }
+    inDomain(domain) {
+        const domainName = typeof domain === 'string' ? domain : domain.name;
+        return this.where(bc => bc.domain?.ref?.name === domainName);
+    }
+    withTeam(team) {
+        const teamName = typeof team === 'string' ? team : team.name;
+        // Use index for initial filtering if no predicates yet
+        if (this.predicateList.length === 0) {
+            const indexed = this.indexes.byTeam.get(teamName) ?? [];
+            return new BcQueryBuilderImpl(indexed, this.fqnProvider, this.indexes);
+        }
+        // Add predicate to existing chain
+        return this.where(bc => effectiveTeam(bc)?.name === teamName);
+    }
+    withClassification(classification) {
+        const classificationName = typeof classification === 'string' ? classification : classification.name;
+        // Use index for initial filtering if no predicates yet
+        if (this.predicateList.length === 0) {
+            const indexed = this.indexes.byClassification.get(classificationName) ?? [];
+            return new BcQueryBuilderImpl(indexed, this.fqnProvider, this.indexes);
+        }
+        // Add predicate to existing chain
+        return this.where(bc => effectiveClassification(bc)?.name === classificationName);
+    }
+    withMetadata(key, value) {
+        // Use index for initial filtering if no predicates yet and no value specified
+        if (this.predicateList.length === 0 && value === undefined) {
+            const indexed = this.indexes.byMetadataKey.get(key) ?? [];
+            return new BcQueryBuilderImpl(indexed, this.fqnProvider, this.indexes);
+        }
+        // Add predicate to existing chain
+        return this.where(bc => {
+            const metadata = metadataAsMap(bc);
+            const metaValue = metadata.get(key);
+            if (metaValue === undefined) {
+                return false;
+            }
+            return value === undefined || metaValue === value;
+        });
+    }
+}
+/**
+ * Escapes special regex characters in a string.
+ */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Augments BoundedContext instances with SDK-resolved properties.
+ * Called during model loading to enrich the AST.
+ *
+ * Properties use natural names (not sdk* prefix) per PRS:
+ * "Properties are discoverable in IDE autocomplete. The SDK enriches the AST
+ * during load, so `bc.classification` just works—no imports needed."
+ *
+ * Note: We use getters to avoid computing values until accessed.
+ * Note: We use Object.defineProperty to avoid modifying the original interface.
+ *
+ * @param bc - BoundedContext to augment
+ */
+export function augmentBoundedContext(bc) {
+    const fqnProvider = new QualifiedNameProvider();
+    // Define computed properties with getters for lazy evaluation
+    // Only include properties that add value beyond direct AST access:
+    // - effectiveClassification/effectiveTeam: array precedence resolution
+    // - metadataMap: array to Map conversion
+    // - fqn: computed qualified name
+    // - helper methods: hasClassification, hasTeam, hasMetadata
+    Object.defineProperties(bc, {
+        effectiveClassification: {
+            get: () => effectiveClassification(bc),
+            enumerable: true,
+            configurable: true,
+        },
+        effectiveTeam: {
+            get: () => effectiveTeam(bc),
+            enumerable: true,
+            configurable: true,
+        },
+        metadataMap: {
+            get: () => metadataAsMap(bc),
+            enumerable: true,
+            configurable: true,
+        },
+        fqn: {
+            get: () => {
+                if (bc.$container && (isModel(bc.$container) || isNamespaceDeclaration(bc.$container))) {
+                    return fqnProvider.getQualifiedName(bc.$container, bc.name);
+                }
+                return bc.name;
+            },
+            enumerable: true,
+            configurable: true,
+        },
+        // Helper methods
+        hasClassification: {
+            value: (name) => {
+                const classification = effectiveClassification(bc);
+                if (!classification)
+                    return false;
+                const targetName = typeof name === 'string' ? name : name?.name;
+                if (!targetName)
+                    return false;
+                return classification.name === targetName;
+            },
+            enumerable: false,
+            configurable: true,
+        },
+        hasTeam: {
+            value: (name) => {
+                const team = effectiveTeam(bc);
+                if (!team)
+                    return false;
+                const targetName = typeof name === 'string' ? name : name?.name;
+                if (!targetName)
+                    return false;
+                return team.name === targetName;
+            },
+            enumerable: false,
+            configurable: true,
+        },
+        hasMetadata: {
+            value: (key, value) => {
+                const metadata = metadataAsMap(bc);
+                const metaValue = metadata.get(key);
+                if (metaValue === undefined)
+                    return false;
+                return value === undefined || metaValue === value;
+            },
+            enumerable: false,
+            configurable: true,
+        },
+    });
+}
+/**
+ * Augments Domain instances with SDK-resolved properties.
+ * Called during model loading to enrich the AST.
+ *
+ * Only includes properties that add value beyond direct AST access:
+ * - fqn: computed qualified name
+ * - hasType: helper method
+ *
+ * Direct access (no augmentation needed):
+ * - domain.description
+ * - domain.vision
+ * - domain.type?.ref
+ *
+ * @param domain - Domain to augment
+ */
+export function augmentDomain(domain) {
+    const fqnProvider = new QualifiedNameProvider();
+    Object.defineProperties(domain, {
+        fqn: {
+            get: () => {
+                if (domain.$container && (isModel(domain.$container) || isNamespaceDeclaration(domain.$container))) {
+                    return fqnProvider.getQualifiedName(domain.$container, domain.name);
+                }
+                return domain.name;
+            },
+            enumerable: true,
+            configurable: true,
+        },
+        // Helper methods
+        hasType: {
+            value: (name) => {
+                const type = domain.type?.ref;
+                if (!type)
+                    return false;
+                const targetName = typeof name === 'string' ? name : name?.name;
+                if (!targetName)
+                    return false;
+                return type.name === targetName;
+            },
+            enumerable: false,
+            configurable: true,
+        },
+    });
+}
+/**
+ * Augments Relationship instances with SDK helper methods.
+ * Called during model loading to enrich the AST.
+ *
+ * @param rel - Relationship to augment
+ * @param containingBc - BoundedContext containing this relationship (for 'this' resolution)
+ */
+export function augmentRelationship(rel, containingBc) {
+    Object.defineProperties(rel, {
+        leftContextName: {
+            get: () => {
+                if (isThisRef(rel.left)) {
+                    return containingBc?.name ?? 'this';
+                }
+                return rel.left.link?.ref?.name ?? '';
+            },
+            enumerable: true,
+            configurable: true,
+        },
+        rightContextName: {
+            get: () => {
+                if (isThisRef(rel.right)) {
+                    return containingBc?.name ?? 'this';
+                }
+                return rel.right.link?.ref?.name ?? '';
+            },
+            enumerable: true,
+            configurable: true,
+        },
+        isBidirectional: {
+            get: () => rel.arrow === '<->',
+            enumerable: true,
+            configurable: true,
+        },
+        // Helper methods for pattern matching (type-safe, no magic strings)
+        hasPattern: {
+            value: (pattern) => {
+                return rel.leftPatterns.some(p => matchesPattern(p, pattern)) ||
+                    rel.rightPatterns.some(p => matchesPattern(p, pattern));
+            },
+            enumerable: false,
+            configurable: true,
+        },
+        hasLeftPattern: {
+            value: (pattern) => {
+                return rel.leftPatterns.some(p => matchesPattern(p, pattern));
+            },
+            enumerable: false,
+            configurable: true,
+        },
+        hasRightPattern: {
+            value: (pattern) => {
+                return rel.rightPatterns.some(p => matchesPattern(p, pattern));
+            },
+            enumerable: false,
+            configurable: true,
+        },
+        isUpstream: {
+            value: (side) => {
+                const patterns = side === 'left' ? rel.leftPatterns : rel.rightPatterns;
+                return patterns.some(p => isUpstreamPattern(p));
+            },
+            enumerable: false,
+            configurable: true,
+        },
+        isDownstream: {
+            value: (side) => {
+                const patterns = side === 'left' ? rel.leftPatterns : rel.rightPatterns;
+                return patterns.some(p => isDownstreamPattern(p));
+            },
+            enumerable: false,
+            configurable: true,
+        },
+    });
+}
+/**
+ * Internal implementation of model augmentation.
+ * Called by ensureAugmented() which tracks augmentation state.
+ *
+ * @param model - Root Model node to augment
+ */
+function augmentModelInternal(model) {
+    for (const node of AstUtils.streamAllContents(model)) {
+        if (isBoundedContext(node)) {
+            augmentBoundedContext(node);
+            // Augment relationships inside this bounded context
+            for (const rel of node.relationships) {
+                augmentRelationship(rel, node);
+            }
+        }
+        else if (isDomain(node)) {
+            augmentDomain(node);
+        }
+        else if (isContextMap(node)) {
+            // Augment relationships in context maps (no containing BC)
+            for (const rel of node.relationships) {
+                augmentRelationship(rel, undefined);
+            }
+        }
+    }
+}
+/**
+ * Augments all AST nodes in a model with SDK-resolved properties.
+ *
+ * This function walks the entire AST and adds lazy getters for resolved
+ * properties like `effectiveClassification`, `effectiveTeam`, etc.
+ *
+ * Idempotent - safe to call multiple times on the same model.
+ * Automatically called by `fromModel()`, `fromDocument()`, and `fromServices()`.
+ *
+ * @param model - Root Model node to augment
+ */
+export function augmentModel(model) {
+    ensureAugmented(model);
+}
+//# sourceMappingURL=query.js.map