@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/artifacts/graph-query.js

@@ -0,0 +1,247 @@
+/**
+ * Cross-Graph Set Queries
+ *
+ * Provides neighbor lookup and set operations (intersection, union, difference)
+ * across dependency graphs. Supports typed edge filtering and cross-graph joins.
+ *
+ * @implements #725
+ * @source @src/artifacts/types.ts
+ * @tests @test/unit/artifacts/graph-query.test.ts
+ */
+import { normalizeEdges } from './types.js';
+import { loadGraphIndexFile } from './index-reader.js';
+import { buildFortemiCoreDependencyGraph } from './fortemi-core-query-adapter.js';
+/**
+ * Get neighbors of a node in a dependency graph.
+ *
+ * @param graph - Loaded dependency graph
+ * @param node - Node path to look up
+ * @param direction - "in" (upstream), "out" (downstream), or "both"
+ * @param edgeType - Optional filter by edge type
+ * @returns Array of neighbor paths
+ */
+export function getNeighbors(graph, node, direction = 'both', edgeType) {
+    const entry = graph[node];
+    if (!entry)
+        return [];
+    const results = new Set();
+    if (direction === 'in' || direction === 'both') {
+        const edges = normalizeEdges(entry.upstream);
+        for (const edge of edges) {
+            if (!edgeType || edge.type === edgeType) {
+                results.add(edge.path);
+            }
+        }
+    }
+    if (direction === 'out' || direction === 'both') {
+        const edges = normalizeEdges(entry.downstream);
+        for (const edge of edges) {
+            if (!edgeType || edge.type === edgeType) {
+                results.add(edge.path);
+            }
+        }
+    }
+    return [...results];
+}
+/**
+ * Resolve a node identifier to a graph key.
+ *
+ * Supports:
+ * - Exact path match ("documentation/citations/REF-008-citations.md")
+ * - REF-XXX shorthand — finds the first key containing the REF identifier
+ * - Partial path match — finds the first key ending with the given string
+ */
+export function resolveNode(graph, node) {
+    // Exact match
+    if (graph[node])
+        return node;
+    // REF-XXX shorthand
+    if (/^REF-\d+$/.test(node)) {
+        const key = Object.keys(graph).find(k => k.includes(node));
+        return key ?? null;
+    }
+    // Partial path match
+    const key = Object.keys(graph).find(k => k.endsWith(node));
+    return key ?? null;
+}
+/**
+ * Set intersection of two arrays
+ */
+export function setIntersection(a, b) {
+    const setB = new Set(b);
+    return a.filter(x => setB.has(x));
+}
+/**
+ * Set union of two arrays
+ */
+export function setUnion(a, b) {
+    return [...new Set([...a, ...b])];
+}
+/**
+ * Set difference: elements in a but not in b
+ */
+export function setDifference(a, b) {
+    const setB = new Set(b);
+    return a.filter(x => !setB.has(x));
+}
+/**
+ * Load a dependency graph for a given graph type
+ */
+function loadGraph(cwd, graphType) {
+    return loadGraphIndexFile(cwd, 'dependencies.json', graphType);
+}
+/**
+ * Execute the `neighbors` subcommand
+ */
+export async function showNeighbors(cwd, options) {
+    const { graph: graphType, node, direction = 'both', edgeType, json = false, backend = 'fortemi-core' } = options;
+    let graph = null;
+    if (backend === 'fortemi-core') {
+        const loaded = buildFortemiCoreDependencyGraph(cwd, graphType);
+        if (!loaded.graph) {
+            if (json) {
+                console.log(JSON.stringify({ error: 'fortemi-core-index-unavailable', hint: loaded.reason }, null, 2));
+            }
+            else {
+                console.error('Error: Fortemi Core static index is unavailable.');
+                console.log(loaded.reason ??
+                    "Run 'aiwg index sync' first, or pass '--backend local' to use the legacy local index.");
+            }
+            process.exit(1);
+        }
+        graph = loaded.graph;
+    }
+    else {
+        graph = loadGraph(cwd, graphType);
+    }
+    if (!graph) {
+        console.error(`Error: No index found for graph '${graphType}'.`);
+        console.log("Run 'aiwg index build --graph " + graphType + "' first.");
+        process.exit(1);
+    }
+    const resolved = resolveNode(graph, node);
+    if (!resolved) {
+        console.error(`Error: Node '${node}' not found in graph '${graphType}'.`);
+        const keys = Object.keys(graph);
+        // Suggest similar nodes
+        const similar = keys.filter(k => k.toLowerCase().includes(node.toLowerCase())).slice(0, 5);
+        if (similar.length > 0) {
+            console.log('Similar nodes:');
+            for (const s of similar)
+                console.log(`  ${s}`);
+        }
+        process.exit(1);
+    }
+    const neighbors = getNeighbors(graph, resolved, direction, edgeType);
+    if (json) {
+        console.log(JSON.stringify({
+            graph: graphType,
+            backend,
+            node: resolved,
+            direction,
+            edgeType: edgeType ?? null,
+            neighbors,
+            count: neighbors.length,
+        }, null, 2));
+    }
+    else {
+        const dirLabel = direction === 'in' ? 'IN' : direction === 'out' ? 'OUT' : 'ALL';
+        const typeLabel = edgeType ? ` [${edgeType}]` : '';
+        console.log(`Neighbors of ${resolved} (${dirLabel}${typeLabel}):`);
+        if (neighbors.length === 0) {
+            console.log('  (none)');
+        }
+        else {
+            for (const n of neighbors) {
+                console.log(`  ${n}`);
+            }
+        }
+        console.log(`\nTotal: ${neighbors.length}`);
+    }
+}
+/**
+ * Execute a set query (intersection, union, difference) on neighbor sets
+ */
+export async function executeSetQuery(cwd, options) {
+    const { graph: graphType, op, nodeA, nodeB, direction = 'in', edgeType, json = false, backend = 'fortemi-core' } = options;
+    let graph = null;
+    if (backend === 'fortemi-core') {
+        const loaded = buildFortemiCoreDependencyGraph(cwd, graphType);
+        if (!loaded.graph) {
+            if (json) {
+                console.log(JSON.stringify({ error: 'fortemi-core-index-unavailable', hint: loaded.reason }, null, 2));
+            }
+            else {
+                console.error('Error: Fortemi Core static index is unavailable.');
+                console.log(loaded.reason ??
+                    "Run 'aiwg index sync' first, or pass '--backend local' to use the legacy local index.");
+            }
+            process.exit(1);
+        }
+        graph = loaded.graph;
+    }
+    else {
+        graph = loadGraph(cwd, graphType);
+    }
+    if (!graph) {
+        console.error(`Error: No index found for graph '${graphType}'.`);
+        process.exit(1);
+    }
+    const resolvedA = resolveNode(graph, nodeA);
+    const resolvedB = resolveNode(graph, nodeB);
+    if (!resolvedA) {
+        console.error(`Error: Node '${nodeA}' not found in graph '${graphType}'.`);
+        process.exit(1);
+    }
+    if (!resolvedB) {
+        console.error(`Error: Node '${nodeB}' not found in graph '${graphType}'.`);
+        process.exit(1);
+    }
+    const neighborsA = getNeighbors(graph, resolvedA, direction, edgeType);
+    const neighborsB = getNeighbors(graph, resolvedB, direction, edgeType);
+    let result;
+    switch (op) {
+        case 'intersection':
+            result = setIntersection(neighborsA, neighborsB);
+            break;
+        case 'union':
+            result = setUnion(neighborsA, neighborsB);
+            break;
+        case 'difference':
+            result = setDifference(neighborsA, neighborsB);
+            break;
+    }
+    if (json) {
+        console.log(JSON.stringify({
+            graph: graphType,
+            backend,
+            op,
+            nodeA: resolvedA,
+            nodeB: resolvedB,
+            direction,
+            edgeType: edgeType ?? null,
+            result,
+            count: result.length,
+            setA_count: neighborsA.length,
+            setB_count: neighborsB.length,
+        }, null, 2));
+    }
+    else {
+        const dirLabel = direction === 'in' ? 'IN' : 'OUT';
+        const typeLabel = edgeType ? ` [${edgeType}]` : '';
+        console.log(`${op.toUpperCase()}(${dirLabel}${typeLabel}):`);
+        console.log(`  A: ${resolvedA} (${neighborsA.length} neighbors)`);
+        console.log(`  B: ${resolvedB} (${neighborsB.length} neighbors)`);
+        console.log('');
+        if (result.length === 0) {
+            console.log('  (empty set)');
+        }
+        else {
+            for (const r of result) {
+                console.log(`  ${r}`);
+            }
+        }
+        console.log(`\nResult: ${result.length} nodes`);
+    }
+}
+//# sourceMappingURL=graph-query.js.map

package/dist/src/artifacts/hybrid-query.js

@@ -0,0 +1,225 @@
+/**
+ * Hybrid Query Engine — combine location, semantic, and tag queries
+ *
+ * Provides artifact search combining file paths (glob), keyword matching,
+ * tag filtering, and dependency traversal. In-memory index for <100ms queries.
+ *
+ * @module artifacts/hybrid-query
+ * @issue #187
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import { resolveProjectAiwgDir } from '../config/project-artifacts.js';
+// ============================================================================
+// ArtifactIndex
+// ============================================================================
+export class ArtifactIndex {
+    artifacts;
+    projectPath;
+    constructor(projectPath) {
+        this.projectPath = projectPath;
+        this.artifacts = [];
+    }
+    /**
+     * Build index by scanning .aiwg/ directory.
+     */
+    async build() {
+        this.artifacts = [];
+        const aiwgDir = resolveProjectAiwgDir(this.projectPath);
+        try {
+            await this.scanDirectory(aiwgDir, '');
+        }
+        catch {
+            // .aiwg doesn't exist
+        }
+        return this.artifacts.length;
+    }
+    /**
+     * Execute a hybrid query against the index.
+     */
+    query(q) {
+        const limit = q.limit ?? 20;
+        let results = [];
+        for (const artifact of this.artifacts) {
+            let score = 0;
+            const reasons = [];
+            // Path match (glob-like)
+            if (q.path) {
+                if (matchesGlob(artifact.relativePath, q.path)) {
+                    score += 0.5;
+                    reasons.push(`path: ${q.path}`);
+                }
+                else {
+                    continue; // Path is a hard filter when specified
+                }
+            }
+            // Semantic query (keyword match)
+            if (q.semanticQuery) {
+                const kwScore = keywordScore(artifact, q.semanticQuery);
+                if (kwScore > 0) {
+                    score += kwScore * 0.3;
+                    reasons.push(`keyword: "${q.semanticQuery}" (${(kwScore * 100).toFixed(0)}%)`);
+                }
+                else if (!q.path && !q.tags && !q.phase) {
+                    continue; // Pure semantic query must match
+                }
+            }
+            // Tag filter
+            if (q.tags && q.tags.length > 0) {
+                const matched = q.tags.filter((t) => artifact.tags.includes(t.toLowerCase()));
+                if (matched.length > 0) {
+                    score += (matched.length / q.tags.length) * 0.2;
+                    reasons.push(`tags: ${matched.join(', ')}`);
+                }
+                else {
+                    continue; // Tags are a hard filter
+                }
+            }
+            // Phase filter
+            if (q.phase) {
+                if (artifact.phase === q.phase) {
+                    score += 0.1;
+                    reasons.push(`phase: ${q.phase}`);
+                }
+                else {
+                    continue;
+                }
+            }
+            // Type filter
+            if (q.type && artifact.type !== q.type) {
+                continue;
+            }
+            // Date filter
+            if (q.updatedAfter) {
+                const since = new Date(q.updatedAfter);
+                if (artifact.modifiedAt < since) {
+                    continue;
+                }
+            }
+            if (score > 0) {
+                results.push({ artifact, score, matchReasons: reasons });
+            }
+        }
+        return results
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+    }
+    /**
+     * Find artifacts that reference a given path.
+     */
+    findDependents(artifactPath) {
+        const normalized = artifactPath.replace(/^\.aiwg\//, '');
+        return this.artifacts.filter((a) => a.references.some((ref) => ref.includes(normalized)));
+    }
+    /**
+     * Find artifacts referenced by a given artifact.
+     */
+    findDependencies(artifactPath) {
+        const artifact = this.artifacts.find((a) => a.relativePath === artifactPath || a.path === artifactPath);
+        if (!artifact)
+            return [];
+        return artifact.references
+            .map((ref) => this.artifacts.find((a) => a.relativePath.includes(ref)))
+            .filter(Boolean);
+    }
+    getAll() {
+        return [...this.artifacts];
+    }
+    // ============================================================================
+    // Private
+    // ============================================================================
+    async scanDirectory(dirPath, relativeBase) {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dirPath, entry.name);
+            const relativePath = relativeBase ? `${relativeBase}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                // Skip working and internal dirs
+                if (['working', 'ralph', 'ralph-external', 'node_modules', 'index'].includes(entry.name))
+                    continue;
+                await this.scanDirectory(fullPath, relativePath);
+            }
+            else if (entry.name.endsWith('.md') || entry.name.endsWith('.yaml') || entry.name.endsWith('.json')) {
+                try {
+                    const stat = await fs.stat(fullPath);
+                    const content = await fs.readFile(fullPath, 'utf-8');
+                    const info = parseArtifactContent(fullPath, relativePath, content, stat.mtime, stat.size);
+                    this.artifacts.push(info);
+                }
+                catch {
+                    // Skip unreadable files
+                }
+            }
+        }
+    }
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function parseArtifactContent(fullPath, relativePath, content, mtime, size) {
+    // Extract phase from path
+    const pathParts = relativePath.split('/');
+    const phase = pathParts[0] || 'unknown';
+    // Extract tags from YAML frontmatter
+    const tags = [];
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (fmMatch) {
+        const tagMatch = fmMatch[1].match(/tags:\s*\[([^\]]+)\]/);
+        if (tagMatch) {
+            tags.push(...tagMatch[1].split(',').map((t) => t.trim().toLowerCase()));
+        }
+    }
+    // Extract title from first heading
+    const titleMatch = content.match(/^#\s+(.+)$/m);
+    const title = titleMatch ? titleMatch[1].trim() : path.basename(relativePath, path.extname(relativePath));
+    // Extract @-mention references
+    const references = [];
+    const refMatches = content.matchAll(/@([\w./-]+\.(?:md|yaml|json|ts|mjs))/g);
+    for (const match of refMatches) {
+        references.push(match[1]);
+    }
+    // Infer type from filename/path
+    const type = inferArtifactType(relativePath);
+    return { path: fullPath, relativePath, phase, type, tags, title, references, modifiedAt: mtime, sizeBytes: size };
+}
+function inferArtifactType(relativePath) {
+    if (relativePath.includes('requirements') || relativePath.match(/UC-\d+/))
+        return 'use-case';
+    if (relativePath.includes('architecture') || relativePath.includes('adr'))
+        return 'architecture';
+    if (relativePath.includes('testing') || relativePath.includes('test-plan'))
+        return 'testing';
+    if (relativePath.includes('planning'))
+        return 'planning';
+    if (relativePath.includes('risks'))
+        return 'risk';
+    if (relativePath.includes('security'))
+        return 'security';
+    if (relativePath.includes('deployment'))
+        return 'deployment';
+    if (relativePath.includes('reports'))
+        return 'report';
+    return 'document';
+}
+function matchesGlob(filePath, pattern) {
+    // Simple glob: * matches any segment, ** matches multiple segments
+    const regex = pattern
+        .replace(/\*\*/g, '___DOUBLE___')
+        .replace(/\*/g, '[^/]*')
+        .replace(/___DOUBLE___/g, '.*')
+        .replace(/\?/g, '.');
+    return new RegExp(`^${regex}$`).test(filePath) || filePath.startsWith(pattern.replace(/\*.*$/, ''));
+}
+function keywordScore(artifact, query) {
+    const terms = query.toLowerCase().split(/\s+/).filter((t) => t.length > 2);
+    if (terms.length === 0)
+        return 0;
+    const searchable = [artifact.title, artifact.relativePath, ...artifact.tags].join(' ').toLowerCase();
+    let matches = 0;
+    for (const term of terms) {
+        if (searchable.includes(term))
+            matches++;
+    }
+    return matches / terms.length;
+}
+//# sourceMappingURL=hybrid-query.js.map