@grafema/util 0.3.0-beta

package/dist/knowledge/KnowledgeBase.js

@@ -0,0 +1,420 @@
+/**
+ * KnowledgeBase — in-memory index over git-tracked knowledge files.
+ *
+ * Scans knowledge/ directory, parses markdown files with YAML frontmatter,
+ * builds an in-memory index for fast lookups. All mutations also write to disk.
+ */
+import { join } from 'path';
+import { readdirSync, statSync, readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { parseFrontmatter, parseKBNode, serializeKBNode, parseEdgesFile, appendEdge as appendEdgeToFile, parseYamlArrayFile } from './parser.js';
+import { SemanticAddressResolver } from './SemanticAddressResolver.js';
+/** Pluralized directory names for each node type */
+const TYPE_DIR = {
+    DECISION: 'decisions',
+    FACT: 'facts',
+    SESSION: 'sessions',
+    COMMIT: 'commits',
+    FILE_CHANGE: 'file-changes',
+    AUTHOR: 'authors',
+    TICKET: 'tickets',
+    INCIDENT: 'incidents',
+};
+export class KnowledgeBase {
+    knowledgeDir;
+    nodes = new Map();
+    edges = [];
+    loaded = false;
+    resolver = null;
+    constructor(knowledgeDir) {
+        this.knowledgeDir = knowledgeDir;
+    }
+    /**
+     * Wire up a code graph backend for resolving semantic addresses.
+     * Creates a SemanticAddressResolver that lazily resolves `relates_to`
+     * and `applies_to` addresses to current code node IDs.
+     */
+    setBackend(backend) {
+        this.resolver = new SemanticAddressResolver(backend);
+    }
+    /**
+     * Bump the resolver's generation counter, marking all cached resolutions stale.
+     * Call after re-analysis so next resolve() re-queries the code graph.
+     */
+    invalidateResolutionCache() {
+        this.resolver?.bumpGeneration();
+    }
+    /**
+     * Resolve all code addresses in a node's relates_to (and applies_to for decisions).
+     * KB-internal addresses (kb:...) pass through without backend query.
+     * Returns empty array if no resolver is set.
+     */
+    async resolveReferences(node) {
+        if (!this.resolver)
+            return [];
+        const addresses = [];
+        if (node.relates_to)
+            addresses.push(...node.relates_to);
+        if (node.type === 'DECISION') {
+            const d = node;
+            if (d.applies_to)
+                addresses.push(...d.applies_to);
+        }
+        // Filter to code addresses only (not kb: internal refs)
+        const codeAddresses = addresses.filter(a => !a.startsWith('kb:'));
+        if (codeAddresses.length === 0)
+            return [];
+        return this.resolver.resolveAll(codeAddresses);
+    }
+    /**
+     * Find all KB nodes with code addresses that don't resolve to graph nodes.
+     * Returns pairs of (KB node ID, dangling address).
+     */
+    async getDanglingCodeRefs() {
+        if (!this.resolver)
+            return [];
+        const results = [];
+        for (const node of this.nodes.values()) {
+            const resolved = await this.resolveReferences(node);
+            for (const r of resolved) {
+                if (r.status === 'dangling') {
+                    results.push({ nodeId: node.id, address: r.address });
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * Scan knowledge directory recursively, parse all .md files, build index.
+     * Malformed files are skipped with console.warn, don't crash.
+     * Missing directory succeeds with empty index.
+     */
+    async load() {
+        this.nodes.clear();
+        this.edges = [];
+        if (!existsSync(this.knowledgeDir)) {
+            this.loaded = true;
+            return;
+        }
+        // Scan for .md files recursively
+        const mdFiles = this.scanFiles(this.knowledgeDir, '.md');
+        for (const filePath of mdFiles) {
+            try {
+                const content = readFileSync(filePath, 'utf-8');
+                const { frontmatter, body } = parseFrontmatter(content);
+                const node = parseKBNode(frontmatter, body, filePath);
+                if (this.nodes.has(node.id)) {
+                    const existing = this.nodes.get(node.id);
+                    throw new Error(`ID collision: "${node.id}" exists in both ${existing.filePath} and ${filePath}`);
+                }
+                this.nodes.set(node.id, node);
+            }
+            catch (error) {
+                // ID collisions should propagate — they're data integrity errors
+                if (error instanceof Error && error.message.startsWith('ID collision:')) {
+                    throw error;
+                }
+                console.warn(`[KnowledgeBase] Skipping malformed file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        // Scan for .yaml array files (derived data like commits, authors)
+        const yamlFiles = this.scanFiles(this.knowledgeDir, '.yaml');
+        for (const filePath of yamlFiles) {
+            // Skip edges.yaml and meta.yaml — they have special formats
+            const fileName = filePath.split('/').pop() || '';
+            if (fileName === 'edges.yaml' || fileName === 'meta.yaml')
+                continue;
+            try {
+                const nodes = parseYamlArrayFile(filePath);
+                for (const node of nodes) {
+                    if (this.nodes.has(node.id)) {
+                        // For derived data, silently skip duplicates (can happen with incremental ingest)
+                        continue;
+                    }
+                    this.nodes.set(node.id, node);
+                }
+            }
+            catch (error) {
+                console.warn(`[KnowledgeBase] Skipping malformed YAML file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        // Load edges
+        const edgesPath = join(this.knowledgeDir, 'edges.yaml');
+        try {
+            this.edges = parseEdgesFile(edgesPath);
+        }
+        catch (error) {
+            console.warn(`[KnowledgeBase] Failed to parse edges.yaml: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        this.loaded = true;
+    }
+    /**
+     * Get a node by its semantic ID.
+     */
+    getNode(id) {
+        return this.nodes.get(id);
+    }
+    /**
+     * Query nodes with filters. All filters are AND-combined.
+     * When include_dangling_only is true, only returns nodes with dangling code refs.
+     * Note: include_dangling_only requires a resolver backend; without one it returns empty.
+     */
+    async queryNodes(filter) {
+        let results = Array.from(this.nodes.values());
+        if (filter.type) {
+            results = results.filter(n => n.type === filter.type);
+        }
+        if (filter.projection) {
+            results = results.filter(n => n.projections.includes(filter.projection));
+        }
+        if (filter.text) {
+            const lower = filter.text.toLowerCase();
+            results = results.filter(n => n.content.toLowerCase().includes(lower));
+        }
+        if (filter.status) {
+            results = results.filter(n => {
+                if (n.type === 'DECISION')
+                    return n.status === filter.status;
+                return false;
+            });
+        }
+        if (filter.relates_to) {
+            results = results.filter(n => n.relates_to?.includes(filter.relates_to));
+        }
+        if (filter.include_dangling_only) {
+            if (!this.resolver)
+                return [];
+            const danglingNodeIds = new Set();
+            for (const node of results) {
+                const resolved = await this.resolveReferences(node);
+                if (resolved.some(r => r.status === 'dangling')) {
+                    danglingNodeIds.add(node.id);
+                }
+            }
+            results = results.filter(n => danglingNodeIds.has(n.id));
+        }
+        return results;
+    }
+    /**
+     * Find active decisions that apply to a given module/semantic address.
+     * Uses string includes matching on applies_to entries.
+     */
+    async activeDecisionsFor(module) {
+        const decisions = await this.queryNodes({ type: 'DECISION', status: 'active' });
+        return decisions.filter(d => d.applies_to?.some(addr => addr.includes(module) || module.includes(addr)));
+    }
+    /**
+     * Add a new node to the knowledge base.
+     * Creates the .md file on disk and updates the in-memory index.
+     *
+     * @param params - Node properties. `id` and `filePath` are auto-generated.
+     * @returns The created node.
+     */
+    async addNode(params) {
+        const slug = params.slug || this.generateSlug(params.content);
+        const typeLower = params.type.toLowerCase();
+        const id = `kb:${typeLower}:${slug}`;
+        // Collision check
+        if (this.nodes.has(id)) {
+            throw new Error(`Slug collision: "${id}" already exists. Did you mean to supersede? Use supersedeFact() for facts.`);
+        }
+        const typeDir = TYPE_DIR[params.type] || typeLower + 's';
+        const dir = join(this.knowledgeDir, 'declared', typeDir);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        const fileName = `${slug}.md`;
+        const filePath = join(dir, fileName);
+        // Secondary collision guard — file on disk
+        if (existsSync(filePath)) {
+            throw new Error(`File already exists: ${filePath}`);
+        }
+        const created = new Date().toISOString().split('T')[0];
+        // Build frontmatter
+        const frontmatter = {
+            id,
+            type: params.type,
+            created,
+        };
+        if (params.subtype)
+            frontmatter.subtype = params.subtype;
+        if (params.scope)
+            frontmatter.scope = params.scope;
+        if (params.projections?.length)
+            frontmatter.projections = params.projections;
+        if (params.source)
+            frontmatter.source = params.source;
+        if (params.relates_to?.length)
+            frontmatter.relates_to = params.relates_to;
+        // Decision fields
+        if (params.type === 'DECISION') {
+            frontmatter.status = params.status || 'proposed';
+            if (params.applies_to?.length)
+                frontmatter.applies_to = params.applies_to;
+            if (params.effective_from)
+                frontmatter.effective_from = params.effective_from;
+        }
+        // Fact fields
+        if (params.type === 'FACT') {
+            if (params.confidence)
+                frontmatter.confidence = params.confidence;
+        }
+        // Session fields
+        if (params.type === 'SESSION') {
+            if (params.task_id)
+                frontmatter.task_id = params.task_id;
+            if (params.session_path)
+                frontmatter.session_path = params.session_path;
+            if (params.produced?.length)
+                frontmatter.produced = params.produced;
+        }
+        // Parse to get a proper node, then serialize
+        const node = parseKBNode(frontmatter, params.content, filePath);
+        const markdown = serializeKBNode(node);
+        writeFileSync(filePath, markdown, 'utf-8');
+        // Update index
+        this.nodes.set(id, node);
+        // Create edges for relates_to
+        if (params.relates_to?.length) {
+            const edgesPath = join(this.knowledgeDir, 'edges.yaml');
+            for (const target of params.relates_to) {
+                const edge = { type: 'RELATES_TO', from: id, to: target };
+                appendEdgeToFile(edgesPath, edge);
+                this.edges.push(edge);
+            }
+        }
+        return node;
+    }
+    /**
+     * Supersede an existing fact with a new version.
+     * Creates new fact, updates old fact with superseded_by.
+     */
+    async supersedeFact(oldId, newContent, newSlug) {
+        const oldNode = this.nodes.get(oldId);
+        if (!oldNode) {
+            throw new Error(`Fact not found: ${oldId}`);
+        }
+        if (oldNode.type !== 'FACT') {
+            throw new Error(`Node "${oldId}" is type ${oldNode.type}, not FACT. Only facts can be superseded.`);
+        }
+        const oldFact = oldNode;
+        const slug = newSlug || this.generateSlug(newContent);
+        const newId = `kb:fact:${slug}`;
+        // Create new fact
+        const newFact = await this.addNode({
+            type: 'FACT',
+            content: newContent,
+            slug,
+            projections: oldFact.projections,
+            source: oldFact.source,
+            confidence: oldFact.confidence,
+        });
+        // Update old fact: set superseded_by and rewrite file
+        oldFact.superseded_by = newId;
+        const markdown = serializeKBNode(oldFact);
+        writeFileSync(oldFact.filePath, markdown, 'utf-8');
+        // Add supersedes edge
+        const edgesPath = join(this.knowledgeDir, 'edges.yaml');
+        const edge = { type: 'SUPERSEDES', from: newId, to: oldId };
+        appendEdgeToFile(edgesPath, edge);
+        this.edges.push(edge);
+        return { old: oldFact, new: newFact };
+    }
+    /**
+     * Add an edge to the knowledge graph.
+     */
+    addEdge(edge) {
+        const edgesPath = join(this.knowledgeDir, 'edges.yaml');
+        appendEdgeToFile(edgesPath, edge);
+        this.edges.push(edge);
+    }
+    /**
+     * Get edges, optionally filtered by node ID (from or to).
+     */
+    getEdges(nodeId) {
+        if (!nodeId)
+            return [...this.edges];
+        return this.edges.filter(e => e.from === nodeId || e.to === nodeId);
+    }
+    /**
+     * Get statistics about the knowledge base.
+     * Includes dangling code references if a resolver backend is available.
+     */
+    async getStats() {
+        const byType = {};
+        const byLifecycle = {};
+        for (const node of this.nodes.values()) {
+            byType[node.type] = (byType[node.type] || 0) + 1;
+            byLifecycle[node.lifecycle] = (byLifecycle[node.lifecycle] || 0) + 1;
+        }
+        const edgesByType = {};
+        for (const edge of this.edges) {
+            edgesByType[edge.type] = (edgesByType[edge.type] || 0) + 1;
+        }
+        // Find dangling KB-internal refs
+        const nodeIds = new Set(this.nodes.keys());
+        const danglingRefs = [];
+        for (const edge of this.edges) {
+            if (!nodeIds.has(edge.from) && !danglingRefs.includes(edge.from)) {
+                danglingRefs.push(edge.from);
+            }
+            if (!nodeIds.has(edge.to) && !danglingRefs.includes(edge.to)) {
+                danglingRefs.push(edge.to);
+            }
+        }
+        // Find dangling code references
+        const danglingCodeRefs = await this.getDanglingCodeRefs();
+        return {
+            totalNodes: this.nodes.size,
+            byType,
+            byLifecycle,
+            totalEdges: this.edges.length,
+            edgesByType,
+            danglingRefs,
+            danglingCodeRefs,
+        };
+    }
+    // --- Private helpers ---
+    /**
+     * Recursively scan directory for files with given extension.
+     */
+    scanFiles(dir, ext) {
+        const results = [];
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return results;
+        }
+        for (const entry of entries) {
+            const fullPath = join(dir, entry);
+            try {
+                const stat = statSync(fullPath);
+                if (stat.isDirectory()) {
+                    results.push(...this.scanFiles(fullPath, ext));
+                }
+                else if (entry.endsWith(ext)) {
+                    results.push(fullPath);
+                }
+            }
+            catch {
+                // Skip unreadable entries
+            }
+        }
+        return results;
+    }
+    /**
+     * Generate a slug from content (first line, simplified).
+     */
+    generateSlug(content) {
+        const firstLine = content.split('\n')[0].trim();
+        return firstLine
+            .toLowerCase()
+            .replace(/[^a-z0-9\s-]/g, '')
+            .replace(/\s+/g, '-')
+            .replace(/-+/g, '-')
+            .replace(/^-|-$/g, '')
+            .slice(0, 60) || 'untitled';
+    }
+}
+//# sourceMappingURL=KnowledgeBase.js.map

package/dist/knowledge/KnowledgeBase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KnowledgeBase.js","sourceRoot":"","sources":["../../src/knowledge/KnowledgeBase.ts"],"names":[],"mappings":"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"}

package/dist/knowledge/SemanticAddressResolver.d.ts

@@ -0,0 +1,59 @@
+/**
+ * SemanticAddressResolver — lazy resolver from semantic addresses to code graph node IDs.
+ *
+ * Semantic addresses (e.g., "src/auth.js:hashPassword:FUNCTION") are human-readable
+ * references to code. After re-analysis, node IDs may change.
+ * This resolver bridges KB references to current graph state at query time.
+ */
+import type { ParsedSemanticAddress, ResolvedAddress } from './types.js';
+/** Minimal backend interface for resolving semantic addresses */
+export interface ResolverBackend {
+    getAllNodes(filter?: Record<string, unknown>): Promise<Array<Record<string, unknown> & {
+        id: string;
+    }>>;
+}
+/**
+ * Parse a semantic address string into its components.
+ *
+ * Format: `file:name:TYPE` or `file:scope1:...:scopeN:name:TYPE`
+ * - Last segment = node type (FUNCTION, CLASS, VARIABLE, etc.)
+ * - First segment = file path (contains `/` or `.`)
+ * - Middle segments = scope path; last middle segment is the name
+ *
+ * @returns parsed address or null if invalid
+ */
+export declare function parseSemanticAddress(address: string): ParsedSemanticAddress | null;
+export declare class SemanticAddressResolver {
+    private backend;
+    private cache;
+    private generation;
+    constructor(backend: ResolverBackend);
+    /**
+     * Increment the generation counter, marking all cached entries stale.
+     * Call this after re-analysis to force re-resolution on next access.
+     */
+    bumpGeneration(): void;
+    /** Current generation number */
+    getGeneration(): number;
+    /**
+     * Resolve a semantic address to a code graph node ID.
+     *
+     * - `kb:` addresses pass through without backend query (KB-internal refs).
+     * - Results are cached; stale entries (resolvedAt < generation) are re-resolved.
+     */
+    resolve(address: string): Promise<ResolvedAddress>;
+    /**
+     * Resolve multiple addresses in bulk.
+     */
+    resolveAll(addresses: string[]): Promise<ResolvedAddress[]>;
+    /**
+     * Get all addresses that resolved as dangling at the current generation.
+     */
+    getDanglingAddresses(): ResolvedAddress[];
+    /**
+     * Disambiguate multiple matching nodes using the scope path from the address.
+     * Matches the node whose scopePath best matches the address's scope segments.
+     */
+    private disambiguateByScope;
+}
+//# sourceMappingURL=SemanticAddressResolver.d.ts.map

package/dist/knowledge/SemanticAddressResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SemanticAddressResolver.d.ts","sourceRoot":"","sources":["../../src/knowledge/SemanticAddressResolver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEzE,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;CACzG;AAOD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CAwBlF;AAED,qBAAa,uBAAuB;IAClC,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,UAAU,CAAK;gBAEX,OAAO,EAAE,eAAe;IAIpC;;;OAGG;IACH,cAAc,IAAI,IAAI;IAItB,gCAAgC;IAChC,aAAa,IAAI,MAAM;IAIvB;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAiDxD;;OAEG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAIjE;;OAEG;IACH,oBAAoB,IAAI,eAAe,EAAE;IAUzC;;;OAGG;IACH,OAAO,CAAC,mBAAmB;CAiC5B"}

package/dist/knowledge/SemanticAddressResolver.js

@@ -0,0 +1,160 @@
+/**
+ * SemanticAddressResolver — lazy resolver from semantic addresses to code graph node IDs.
+ *
+ * Semantic addresses (e.g., "src/auth.js:hashPassword:FUNCTION") are human-readable
+ * references to code. After re-analysis, node IDs may change.
+ * This resolver bridges KB references to current graph state at query time.
+ */
+/**
+ * Parse a semantic address string into its components.
+ *
+ * Format: `file:name:TYPE` or `file:scope1:...:scopeN:name:TYPE`
+ * - Last segment = node type (FUNCTION, CLASS, VARIABLE, etc.)
+ * - First segment = file path (contains `/` or `.`)
+ * - Middle segments = scope path; last middle segment is the name
+ *
+ * @returns parsed address or null if invalid
+ */
+export function parseSemanticAddress(address) {
+    if (!address || typeof address !== 'string')
+        return null;
+    const parts = address.split(':');
+    // Minimum: file:name:TYPE = 3 parts
+    if (parts.length < 3)
+        return null;
+    const type = parts[parts.length - 1];
+    const file = parts[0];
+    // File must contain / or . to be valid
+    if (!file.includes('/') && !file.includes('.'))
+        return null;
+    // Type must be uppercase
+    if (type !== type.toUpperCase() || !/^[A-Z_]+$/.test(type))
+        return null;
+    // Middle segments: everything between file and type
+    const middle = parts.slice(1, -1);
+    if (middle.length === 0)
+        return null;
+    const name = middle[middle.length - 1];
+    const scopePath = middle.slice(0, -1);
+    return { file, name, type, scopePath };
+}
+export class SemanticAddressResolver {
+    backend;
+    cache = new Map();
+    generation = 0;
+    constructor(backend) {
+        this.backend = backend;
+    }
+    /**
+     * Increment the generation counter, marking all cached entries stale.
+     * Call this after re-analysis to force re-resolution on next access.
+     */
+    bumpGeneration() {
+        this.generation++;
+    }
+    /** Current generation number */
+    getGeneration() {
+        return this.generation;
+    }
+    /**
+     * Resolve a semantic address to a code graph node ID.
+     *
+     * - `kb:` addresses pass through without backend query (KB-internal refs).
+     * - Results are cached; stale entries (resolvedAt < generation) are re-resolved.
+     */
+    async resolve(address) {
+        // KB-internal addresses pass through
+        if (address.startsWith('kb:')) {
+            return { address, codeNodeId: null, status: 'resolved' };
+        }
+        // Check cache
+        const cached = this.cache.get(address);
+        if (cached && cached.resolvedAt >= this.generation) {
+            return cached.result;
+        }
+        const parsed = parseSemanticAddress(address);
+        if (!parsed) {
+            const result = { address, codeNodeId: null, status: 'dangling' };
+            this.cache.set(address, { result, resolvedAt: this.generation });
+            return result;
+        }
+        // Query backend for matching nodes
+        const filter = {
+            file: parsed.file,
+            name: parsed.name,
+            nodeType: parsed.type,
+        };
+        const nodes = await this.backend.getAllNodes(filter);
+        let result;
+        if (nodes.length === 1) {
+            result = { address, codeNodeId: nodes[0].id, status: 'resolved' };
+        }
+        else if (nodes.length === 0) {
+            result = { address, codeNodeId: null, status: 'dangling' };
+        }
+        else {
+            // Multiple matches — disambiguate by scope path
+            const match = this.disambiguateByScope(nodes, parsed.scopePath);
+            if (match) {
+                result = { address, codeNodeId: match.id, status: 'resolved' };
+            }
+            else {
+                // Take first match as best-effort
+                result = { address, codeNodeId: nodes[0].id, status: 'resolved' };
+            }
+        }
+        this.cache.set(address, { result, resolvedAt: this.generation });
+        return result;
+    }
+    /**
+     * Resolve multiple addresses in bulk.
+     */
+    async resolveAll(addresses) {
+        return Promise.all(addresses.map(addr => this.resolve(addr)));
+    }
+    /**
+     * Get all addresses that resolved as dangling at the current generation.
+     */
+    getDanglingAddresses() {
+        const results = [];
+        for (const entry of this.cache.values()) {
+            if (entry.resolvedAt >= this.generation && entry.result.status === 'dangling') {
+                results.push(entry.result);
+            }
+        }
+        return results;
+    }
+    /**
+     * Disambiguate multiple matching nodes using the scope path from the address.
+     * Matches the node whose scopePath best matches the address's scope segments.
+     */
+    disambiguateByScope(nodes, addressScopePath) {
+        if (addressScopePath.length === 0)
+            return null;
+        let bestMatch = null;
+        let bestScore = -1;
+        for (const node of nodes) {
+            const nodeScopePath = node['scopePath'];
+            if (!Array.isArray(nodeScopePath))
+                continue;
+            // Score: count matching scope segments from the end
+            let score = 0;
+            const aLen = addressScopePath.length;
+            const nLen = nodeScopePath.length;
+            for (let i = 1; i <= Math.min(aLen, nLen); i++) {
+                if (addressScopePath[aLen - i] === nodeScopePath[nLen - i]) {
+                    score++;
+                }
+                else {
+                    break;
+                }
+            }
+            if (score > bestScore) {
+                bestScore = score;
+                bestMatch = node;
+            }
+        }
+        return bestScore > 0 ? bestMatch : null;
+    }
+}
+//# sourceMappingURL=SemanticAddressResolver.js.map

package/dist/knowledge/SemanticAddressResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SemanticAddressResolver.js","sourceRoot":"","sources":["../../src/knowledge/SemanticAddressResolver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAcH;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEzD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,oCAAoC;IACpC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAElC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAEtB,uCAAuC;IACvC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAE5D,yBAAyB;IACzB,IAAI,IAAI,KAAK,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAExE,oDAAoD;IACpD,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAClC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAErC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACvC,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAEtC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AACzC,CAAC;AAED,MAAM,OAAO,uBAAuB;IAC1B,OAAO,CAAkB;IACzB,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IACtC,UAAU,GAAG,CAAC,CAAC;IAEvB,YAAY,OAAwB;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED;;;OAGG;IACH,cAAc;QACZ,IAAI,CAAC,UAAU,EAAE,CAAC;IACpB,CAAC;IAED,gCAAgC;IAChC,aAAa;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAO,CAAC,OAAe;QAC3B,qCAAqC;QACrC,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;QAC3D,CAAC;QAED,cAAc;QACd,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,MAAM,IAAI,MAAM,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACnD,OAAO,MAAM,CAAC,MAAM,CAAC;QACvB,CAAC;QAED,MAAM,MAAM,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,MAAM,GAAoB,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;YAClF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;YACjE,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,mCAAmC;QACnC,MAAM,MAAM,GAA4B;YACtC,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,QAAQ,EAAE,MAAM,CAAC,IAAI;SACtB,CAAC;QAEF,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAErD,IAAI,MAAuB,CAAC;QAE5B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;QACpE,CAAC;aAAM,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9B,MAAM,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;QAC7D,CAAC;aAAM,CAAC;YACN,gDAAgD;YAChD,MAAM,KAAK,GAAG,IAAI,CAAC,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;YAChE,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;YACjE,CAAC;iBAAM,CAAC;gBACN,kCAAkC;gBAClC,MAAM,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;YACpE,CAAC;QACH,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QACjE,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU,CAAC,SAAmB;QAClC,OAAO,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAChE,CAAC;IAED;;OAEG;IACH,oBAAoB;QAClB,MAAM,OAAO,GAAsB,EAAE,CAAC;QACtC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YACxC,IAAI,KAAK,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;gBAC9E,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;OAGG;IACK,mBAAmB,CACzB,KAAsD,EACtD,gBAA0B;QAE1B,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAE/C,IAAI,SAAS,GAA0B,IAAI,CAAC;QAC5C,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC;QAEnB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;YACxC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC;gBAAE,SAAS;YAE5C,oDAAoD;YACpD,IAAI,KAAK,GAAG,CAAC,CAAC;YACd,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,CAAC;YACrC,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC;YAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC/C,IAAI,gBAAgB,CAAC,IAAI,GAAG,CAAC,CAAC,KAAK,aAAa,CAAC,IAAI,GAAG,CAAC,CAAC,EAAE,CAAC;oBAC3D,KAAK,EAAE,CAAC;gBACV,CAAC;qBAAM,CAAC;oBACN,MAAM;gBACR,CAAC;YACH,CAAC;YAED,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;gBACtB,SAAS,GAAG,KAAK,CAAC;gBAClB,SAAS,GAAG,IAAI,CAAC;YACnB,CAAC;QACH,CAAC;QAED,OAAO,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1C,CAAC;CACF"}