@mgamil/mapx 0.2.4

package/dist/core/context-builder.js

@@ -0,0 +1,252 @@
+const STOP_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "and",
+  "for",
+  "this",
+  "that",
+  "with",
+  "from",
+  "test",
+  "task",
+  "implement",
+  "add",
+  "fix",
+  "bug",
+  "issue",
+  "update",
+  "delete",
+  "remove",
+  "create",
+  "make",
+  "get",
+  "set",
+  "run",
+  "code",
+  "file",
+  "project",
+  "class",
+  "function",
+  "method",
+  "interface",
+  "type",
+  "import",
+  "export",
+  "require",
+  "include",
+  "exclude"
+]);
+const SUFFIXES = /* @__PURE__ */ new Set(["controller", "service", "repository", "manager", "handler", "helper", "provider", "model"]);
+class ContextBuilder {
+  store;
+  graph;
+  constructor(store, graph) {
+    this.store = store;
+    this.graph = graph;
+  }
+  static extractKeywords(text) {
+    const withSpaces = text.replace(/([a-z])([A-Z])/g, "$1 $2");
+    const words = withSpaces.toLowerCase().split(/[^a-z0-9]+/);
+    const keywords = [];
+    for (const word of words) {
+      if (word.length >= 3 && !STOP_WORDS.has(word)) {
+        keywords.push(word);
+        for (const suffix of SUFFIXES) {
+          if (word.endsWith(suffix) && word.length > suffix.length) {
+            keywords.push(word.slice(0, -suffix.length));
+          }
+        }
+      }
+    }
+    return Array.from(new Set(keywords));
+  }
+  async buildContext(options) {
+    const budget = options.tokens ?? 8192;
+    const maxDepth = options.depth ?? 2;
+    const repo = options.repo;
+    const matchedSymbols = [];
+    const seedFiles = /* @__PURE__ */ new Set();
+    if (options.seeds) {
+      for (const seed of options.seeds) {
+        if (seed.includes(".") || seed.includes("/")) {
+          if (this.store.getFile(seed)) {
+            seedFiles.add(seed);
+          }
+        } else {
+          const sym = this.store.getSymbolByName(seed, repo);
+          if (sym) {
+            seedFiles.add(sym.file_path);
+            matchedSymbols.push({
+              name: sym.name,
+              kind: sym.kind,
+              filePath: sym.file_path
+            });
+          }
+        }
+      }
+    }
+    const keywords = ContextBuilder.extractKeywords(options.task);
+    for (const kw of keywords) {
+      const syms = this.store.searchSymbolsFiltered({ term: kw, repo, limit: 10 });
+      for (const sym of syms) {
+        seedFiles.add(sym.file_path);
+        if (!matchedSymbols.some((s) => s.name === sym.name && s.filePath === sym.file_path)) {
+          matchedSymbols.push({
+            name: sym.name,
+            kind: sym.kind,
+            filePath: sym.file_path
+          });
+        }
+      }
+    }
+    const allFiles = this.store.getAllFiles(repo);
+    for (const kw of keywords) {
+      const kwLower = kw.toLowerCase();
+      for (const f of allFiles) {
+        if (f.path.toLowerCase().includes(kwLower)) {
+          seedFiles.add(f.path);
+        }
+      }
+    }
+    if (seedFiles.size === 0) {
+      const topFiles = this.graph.getRankedFiles().slice(0, 5);
+      for (const tf of topFiles) {
+        seedFiles.add(tf.path);
+      }
+    }
+    const distances = /* @__PURE__ */ new Map();
+    for (const sf of seedFiles) {
+      distances.set(sf, 0);
+    }
+    const queue = Array.from(seedFiles);
+    let head = 0;
+    while (head < queue.length) {
+      const file = queue[head++];
+      const currentDepth = distances.get(file);
+      if (currentDepth >= maxDepth) continue;
+      const neighbors = [
+        ...this.graph.getDependencies(file).map((d) => d.target),
+        ...this.graph.getReverseDependencies(file).map((r) => r.source)
+      ];
+      for (const neighbor of neighbors) {
+        if (!distances.has(neighbor)) {
+          distances.set(neighbor, currentDepth + 1);
+          queue.push(neighbor);
+        }
+      }
+    }
+    const rankedAll = this.graph.getRankedFiles();
+    const rankedMap = /* @__PURE__ */ new Map();
+    for (const f of rankedAll) {
+      rankedMap.set(f.path, f.pagerank);
+    }
+    const candidates = Array.from(distances.keys());
+    const candidateScores = candidates.map((path) => {
+      const depth = distances.get(path);
+      const dbFile = this.store.getFile(path);
+      const language = dbFile ? dbFile.language : "unknown";
+      let score = 0;
+      if (depth === 0) {
+        score += 1e3;
+      } else if (depth === 1) {
+        score += 100;
+      } else if (depth === 2) {
+        score += 10;
+      } else {
+        score += 1;
+      }
+      const pathLower = path.toLowerCase();
+      let keywordPathMatches = 0;
+      for (const kw of keywords) {
+        if (pathLower.includes(kw.toLowerCase())) {
+          keywordPathMatches++;
+        }
+      }
+      score += keywordPathMatches * 200;
+      const fileSyms = this.store.getSymbolsForFile(path);
+      let keywordSymbolMatches = 0;
+      for (const sym of fileSyms) {
+        const symNameLower = sym.name.toLowerCase();
+        for (const kw of keywords) {
+          if (symNameLower.includes(kw.toLowerCase())) {
+            keywordSymbolMatches++;
+          }
+        }
+      }
+      score += keywordSymbolMatches * 50;
+      const pr = rankedMap.get(path) || 0;
+      score += pr * 20;
+      return {
+        path,
+        language,
+        score,
+        depth
+      };
+    });
+    candidateScores.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+    const includedFiles = [];
+    const excludedFiles = [];
+    let currentTokens = 0;
+    for (const cand of candidateScores) {
+      const dbFile = this.store.getFile(cand.path);
+      if (!dbFile) continue;
+      const syms = this.store.getSymbolsForFile(cand.path);
+      const symbolCount = syms.length;
+      let fileTokens = 150;
+      if (symbolCount > 3) {
+        fileTokens += (symbolCount - 3) * 20;
+      }
+      if (currentTokens + fileTokens <= budget) {
+        includedFiles.push({
+          path: cand.path,
+          language: cand.language,
+          lineCount: dbFile.lines || 0,
+          sizeBytes: dbFile.size_bytes || 0,
+          symbols: syms.map((s) => ({
+            name: s.name,
+            kind: s.kind,
+            scope: s.scope,
+            startLine: s.start_line,
+            endLine: s.end_line
+          }))
+        });
+        currentTokens += fileTokens;
+      } else {
+        excludedFiles.push(cand.path);
+      }
+    }
+    const includedPaths = new Set(includedFiles.map((f) => f.path));
+    const edges = [];
+    for (const path of includedPaths) {
+      const fileEdges = this.store.getEdgesForFile(path);
+      for (const edge of fileEdges) {
+        if (includedPaths.has(edge.target_file)) {
+          edges.push({
+            sourceFile: edge.source_file,
+            targetFile: edge.target_file,
+            sourceSymbol: edge.source_symbol,
+            targetSymbol: edge.target_symbol,
+            edgeType: edge.edge_type
+          });
+        }
+      }
+    }
+    const simpleFiles = includedFiles.map((f) => ({
+      path: f.path,
+      language: f.language,
+      lineCount: f.lineCount,
+      sizeBytes: f.sizeBytes
+    }));
+    return {
+      includedFiles,
+      excludedFiles,
+      edges,
+      estimatedTokens: currentTokens,
+      matchedSymbols,
+      files: simpleFiles,
+      symbols: matchedSymbols
+    };
+  }
+}
+export {
+  ContextBuilder
+};

package/dist/core/flow-tracer.d.ts

@@ -0,0 +1,63 @@
+import { Store } from './store.js';
+import { ReferenceType } from '../types.js';
+import './store-interface.js';
+import './graph.js';
+
+type TraceDirection = 'down' | 'up' | 'both';
+interface TraceOptions {
+    startSymbol?: string;
+    startFile?: string;
+    direction: TraceDirection;
+    maxDepth: number;
+    edgeTypes?: ReferenceType[];
+    includeStructural: boolean;
+    repo?: string;
+}
+interface TraceNode {
+    file: string;
+    symbol: string | null;
+    depth: number;
+    incomingEdgeType: ReferenceType | 'start';
+}
+interface TracePath {
+    nodes: TraceNode[];
+    cycles: CyclicEdge[];
+}
+interface CyclicEdge {
+    fromFile: string;
+    fromSymbol: string | null;
+    toFile: string;
+    toSymbol: string | null;
+    edgeType: ReferenceType;
+    cycleLength: number;
+}
+interface TraceResult {
+    start: {
+        file: string;
+        symbol: string | null;
+    };
+    direction: TraceDirection;
+    paths: TracePath[];
+    sources: TraceNode[];
+    sinks: TraceNode[];
+    cycles: CyclicEdge[];
+    nodeCount: number;
+    edgeCount: number;
+    maxDepthReached: boolean;
+}
+declare class FlowTracer {
+    private store;
+    constructor(store: Store);
+    trace(options: TraceOptions): TraceResult;
+    resolveStart(input: string, repo?: string): {
+        file: string;
+        symbol: string | null;
+    } | null;
+    findSources(repo?: string): TraceNode[];
+    findSinks(repo?: string): TraceNode[];
+    findCriticalPath(from: string, to: string, repo?: string): TracePath | null;
+    private getEdgesForNode;
+    private getScopedSymbolName;
+}
+
+export { type CyclicEdge, FlowTracer, type TraceDirection, type TraceNode, type TraceOptions, type TracePath, type TraceResult };

package/dist/core/flow-tracer.js

@@ -0,0 +1,366 @@
+const DATA_BEARING_EDGES = [
+  "call",
+  "instantiation",
+  "param_type",
+  "return_type",
+  "relation",
+  "dispatch",
+  "notify",
+  "route"
+];
+const STRUCTURAL_EDGES = [
+  "import",
+  "require",
+  "extends",
+  "implements",
+  "binding",
+  "middleware"
+];
+function matchesSymbol(nodeSymbol, edgeSymbol) {
+  if (!nodeSymbol) return true;
+  if (!edgeSymbol) return true;
+  if (nodeSymbol === edgeSymbol) return true;
+  if (nodeSymbol.includes("::")) {
+    const [, name] = nodeSymbol.split("::");
+    if (edgeSymbol === name) return true;
+  }
+  return false;
+}
+class FlowTracer {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  trace(options) {
+    const repo = options.repo;
+    const direction = options.direction;
+    const maxDepth = options.maxDepth ?? 3;
+    let startFile = options.startFile;
+    let startSymbol = options.startSymbol;
+    if (!startFile && startSymbol) {
+      const resolved = this.resolveStart(startSymbol, repo);
+      if (resolved) {
+        startFile = resolved.file;
+        startSymbol = resolved.symbol ?? void 0;
+      }
+    } else if (startFile && !startSymbol) {
+      const resolved = this.resolveStart(startFile, repo);
+      if (resolved) {
+        startFile = resolved.file;
+        startSymbol = resolved.symbol ?? void 0;
+      }
+    }
+    if (!startFile) {
+      throw new Error(`Could not resolve starting file or symbol: ${options.startFile || options.startSymbol}`);
+    }
+    const startNode = {
+      file: startFile,
+      symbol: startSymbol || null,
+      depth: 0,
+      incomingEdgeType: "start"
+    };
+    if (direction === "both") {
+      const downRes = this.trace({ ...options, direction: "down", startFile, startSymbol });
+      const upRes = this.trace({ ...options, direction: "up", startFile, startSymbol });
+      const uniqueNodesMap = /* @__PURE__ */ new Map();
+      const addNode = (n) => {
+        const key = `${n.file}::${n.symbol || ""}`;
+        if (!uniqueNodesMap.has(key) || uniqueNodesMap.get(key).depth > n.depth) {
+          uniqueNodesMap.set(key, n);
+        }
+      };
+      for (const p of [...downRes.paths, ...upRes.paths]) {
+        for (const n of p.nodes) addNode(n);
+      }
+      const mergedCycles = [...downRes.cycles, ...upRes.cycles];
+      const mergedSources = [...downRes.sources, ...upRes.sources];
+      const mergedSinks = [...downRes.sinks, ...upRes.sinks];
+      return {
+        start: { file: startFile, symbol: startSymbol || null },
+        direction: "both",
+        paths: [...downRes.paths, ...upRes.paths],
+        sources: Array.from(new Map(mergedSources.map((n) => [`${n.file}::${n.symbol || ""}`, n])).values()),
+        sinks: Array.from(new Map(mergedSinks.map((n) => [`${n.file}::${n.symbol || ""}`, n])).values()),
+        cycles: Array.from(new Map(mergedCycles.map((c) => [`${c.fromFile}->${c.toFile}`, c])).values()),
+        nodeCount: uniqueNodesMap.size,
+        edgeCount: downRes.edgeCount + upRes.edgeCount,
+        maxDepthReached: downRes.maxDepthReached || upRes.maxDepthReached
+      };
+    }
+    const allPaths = [];
+    const detectedCycles = [];
+    const stack = [startNode];
+    const stackKeys = /* @__PURE__ */ new Set([`${startFile}::${startSymbol || ""}`]);
+    const uniqueVisited = /* @__PURE__ */ new Set([`${startFile}::${startSymbol || ""}`]);
+    let maxDepthReached = false;
+    const getPathKey = (file, symbol) => `${file}::${symbol || ""}`;
+    const dfs = (current) => {
+      const edges = this.getEdgesForNode(current, direction, options.includeStructural, repo);
+      let hasValidSteps = false;
+      const validNextEdges = [];
+      for (const edge of edges) {
+        const nextFile = direction === "up" ? edge.source_file : edge.target_file;
+        const nextSymbolName = direction === "up" ? edge.source_symbol : edge.target_symbol;
+        const nextSymbol = this.getScopedSymbolName(nextFile, nextSymbolName, repo);
+        const nextKey = getPathKey(nextFile, nextSymbol);
+        if (stackKeys.has(nextKey)) {
+          const ancestorIndex = stack.findIndex((n) => getPathKey(n.file, n.symbol) === nextKey);
+          const cycleLength = stack.length - ancestorIndex;
+          detectedCycles.push({
+            fromFile: current.file,
+            fromSymbol: current.symbol,
+            toFile: nextFile,
+            toSymbol: nextSymbol,
+            edgeType: edge.edge_type,
+            cycleLength
+          });
+        } else {
+          hasValidSteps = true;
+          validNextEdges.push({ edge, nextFile, nextSymbol, nextKey });
+        }
+      }
+      if (!hasValidSteps || current.depth >= maxDepth) {
+        allPaths.push({
+          nodes: [...stack],
+          cycles: []
+        });
+        if (current.depth >= maxDepth && hasValidSteps) {
+          maxDepthReached = true;
+        }
+        return;
+      }
+      for (const next of validNextEdges) {
+        if (uniqueVisited.has(next.nextKey)) {
+          continue;
+        }
+        const nextNode = {
+          file: next.nextFile,
+          symbol: next.nextSymbol,
+          depth: current.depth + 1,
+          incomingEdgeType: next.edge.edge_type
+        };
+        stack.push(nextNode);
+        stackKeys.add(next.nextKey);
+        uniqueVisited.add(next.nextKey);
+        dfs(nextNode);
+        stack.pop();
+        stackKeys.delete(next.nextKey);
+      }
+    };
+    dfs(startNode);
+    const uniqueNodes = /* @__PURE__ */ new Set();
+    const traceEdges = /* @__PURE__ */ new Set();
+    for (const p of allPaths) {
+      for (let i = 0; i < p.nodes.length; i++) {
+        uniqueNodes.add(`${p.nodes[i].file}::${p.nodes[i].symbol || ""}`);
+        if (i > 0) {
+          const from = direction === "up" ? p.nodes[i].file : p.nodes[i - 1].file;
+          const to = direction === "up" ? p.nodes[i - 1].file : p.nodes[i].file;
+          traceEdges.add(`${from}->${to}`);
+        }
+      }
+    }
+    const traceSources = [];
+    const traceSinks = [];
+    for (const key of uniqueNodes) {
+      const [file, symbol] = key.split("::");
+      const nodeSym = symbol || null;
+      const node = { file, symbol: nodeSym, depth: 0, incomingEdgeType: "start" };
+      const outEdges = this.getEdgesForNode(node, "down", options.includeStructural, repo);
+      const inEdges = this.getEdgesForNode(node, "up", options.includeStructural, repo);
+      if (inEdges.length === 0) {
+        traceSources.push(node);
+      }
+      if (outEdges.length === 0) {
+        traceSinks.push(node);
+      }
+    }
+    return {
+      start: { file: startFile, symbol: startSymbol || null },
+      direction,
+      paths: allPaths,
+      sources: traceSources,
+      sinks: traceSinks,
+      cycles: detectedCycles,
+      nodeCount: uniqueNodes.size,
+      edgeCount: traceEdges.size,
+      maxDepthReached
+    };
+  }
+  resolveStart(input, repo) {
+    const allFiles = this.store.getAllFiles(repo);
+    const matchedFile = allFiles.find((f) => f.path === input || f.path.endsWith(input));
+    if (matchedFile) {
+      return { file: matchedFile.path, symbol: null };
+    }
+    let scope = null;
+    let name = input;
+    if (input.includes("::")) {
+      const parts = input.split("::");
+      scope = parts[0];
+      name = parts[1];
+    }
+    const allSymbols = this.store.getAllSymbols(repo);
+    let matchedSymbol = null;
+    if (scope) {
+      matchedSymbol = allSymbols.find((s) => s.name === name && s.scope === scope);
+    } else {
+      matchedSymbol = allSymbols.find((s) => s.name === name || s.scope === name);
+    }
+    if (matchedSymbol) {
+      return {
+        file: matchedSymbol.file_path,
+        symbol: matchedSymbol.scope ? `${matchedSymbol.scope}::${matchedSymbol.name}` : matchedSymbol.name
+      };
+    }
+    return null;
+  }
+  findSources(repo) {
+    const files = this.store.getAllFiles(repo);
+    const edges = this.store.getAllEdges(repo);
+    const filePaths = new Set(files.map((f) => f.path));
+    for (const e of edges) {
+      filePaths.add(e.source_file);
+      filePaths.add(e.target_file);
+    }
+    const dataEdges = edges.filter((e) => DATA_BEARING_EDGES.includes(e.edge_type));
+    const incomingCount = /* @__PURE__ */ new Map();
+    const outgoingCount = /* @__PURE__ */ new Map();
+    for (const p of filePaths) {
+      incomingCount.set(p, 0);
+      outgoingCount.set(p, 0);
+    }
+    for (const e of dataEdges) {
+      const src = e.source_file;
+      const tgt = e.target_file;
+      outgoingCount.set(src, (outgoingCount.get(src) || 0) + 1);
+      incomingCount.set(tgt, (incomingCount.get(tgt) || 0) + 1);
+    }
+    const sources = [];
+    for (const p of filePaths) {
+      const inc = incomingCount.get(p) || 0;
+      const out = outgoingCount.get(p) || 0;
+      if (inc === 0 && out > 0) {
+        sources.push({
+          file: p,
+          symbol: null,
+          depth: 0,
+          incomingEdgeType: "start"
+        });
+      }
+    }
+    return sources;
+  }
+  findSinks(repo) {
+    const files = this.store.getAllFiles(repo);
+    const edges = this.store.getAllEdges(repo);
+    const filePaths = new Set(files.map((f) => f.path));
+    for (const e of edges) {
+      filePaths.add(e.source_file);
+      filePaths.add(e.target_file);
+    }
+    const dataEdges = edges.filter((e) => DATA_BEARING_EDGES.includes(e.edge_type));
+    const incomingCount = /* @__PURE__ */ new Map();
+    const outgoingCount = /* @__PURE__ */ new Map();
+    for (const p of filePaths) {
+      incomingCount.set(p, 0);
+      outgoingCount.set(p, 0);
+    }
+    for (const e of dataEdges) {
+      const src = e.source_file;
+      const tgt = e.target_file;
+      outgoingCount.set(src, (outgoingCount.get(src) || 0) + 1);
+      incomingCount.set(tgt, (incomingCount.get(tgt) || 0) + 1);
+    }
+    const sinks = [];
+    for (const p of filePaths) {
+      const inc = incomingCount.get(p) || 0;
+      const out = outgoingCount.get(p) || 0;
+      if (out === 0 && inc > 0) {
+        sinks.push({
+          file: p,
+          symbol: null,
+          depth: 0,
+          incomingEdgeType: "start"
+        });
+      }
+    }
+    return sinks;
+  }
+  findCriticalPath(from, to, repo) {
+    const startNode = this.resolveStart(from, repo);
+    if (!startNode) return null;
+    const targetNode = this.resolveStart(to, repo);
+    if (!targetNode) return null;
+    const getPathKey = (file, symbol) => `${file}::${symbol || ""}`;
+    const targetKey = getPathKey(targetNode.file, targetNode.symbol);
+    const queue = [
+      { node: { file: startNode.file, symbol: startNode.symbol, depth: 0, incomingEdgeType: "start" }, path: [{ file: startNode.file, symbol: startNode.symbol, depth: 0, incomingEdgeType: "start" }] }
+    ];
+    const visited = /* @__PURE__ */ new Set([getPathKey(startNode.file, startNode.symbol)]);
+    while (queue.length > 0) {
+      const { node, path } = queue.shift();
+      const currentKey = getPathKey(node.file, node.symbol);
+      if (currentKey === targetKey) {
+        return {
+          nodes: path,
+          cycles: []
+        };
+      }
+      const edges = this.getEdgesForNode(node, "down", false, repo);
+      for (const edge of edges) {
+        const nextFile = edge.target_file;
+        const nextSymbolName = edge.target_symbol;
+        const nextSymbol = this.getScopedSymbolName(nextFile, nextSymbolName, repo);
+        const nextKey = getPathKey(nextFile, nextSymbol);
+        if (!visited.has(nextKey)) {
+          visited.add(nextKey);
+          const nextNode = {
+            file: nextFile,
+            symbol: nextSymbol,
+            depth: node.depth + 1,
+            incomingEdgeType: edge.edge_type
+          };
+          queue.push({
+            node: nextNode,
+            path: [...path, nextNode]
+          });
+        }
+      }
+    }
+    return null;
+  }
+  getEdgesForNode(node, direction, includeStructural, repo) {
+    const edges = direction === "up" ? this.store.getReverseEdges(node.file) : this.store.getEdgesForFile(node.file);
+    let filtered = edges;
+    if (repo) {
+      filtered = filtered.filter((e) => e.repo === repo);
+    }
+    const isDataBearing = (type) => DATA_BEARING_EDGES.includes(type);
+    const isStructural = (type) => STRUCTURAL_EDGES.includes(type);
+    filtered = filtered.filter((e) => {
+      const type = e.edge_type;
+      if (includeStructural) {
+        return isDataBearing(type) || isStructural(type);
+      }
+      return isDataBearing(type);
+    });
+    filtered = filtered.filter((e) => {
+      const edgeSym = direction === "up" ? e.target_symbol : e.source_symbol;
+      return matchesSymbol(node.symbol, edgeSym);
+    });
+    return filtered;
+  }
+  getScopedSymbolName(file, name, repo) {
+    if (!name) return null;
+    const symbols = this.store.getSymbolsForFile(file);
+    const found = symbols.find((s) => s.name === name);
+    if (found && found.scope) {
+      return `${found.scope}::${name}`;
+    }
+    return name;
+  }
+}
+export {
+  FlowTracer
+};

package/dist/core/git-tracker.d.ts

@@ -0,0 +1,20 @@
+import { SubmoduleInfo } from '../types.js';
+
+interface GitFileStatus {
+    path: string;
+    status: 'added' | 'modified' | 'removed' | 'renamed' | 'unchanged';
+}
+interface GitBlobHash {
+    path: string;
+    hash: string;
+}
+declare function getGitBlobHashes(repoRoot: string): Map<string, string>;
+declare function getChangedFiles(repoRoot: string, since?: string): GitFileStatus[];
+declare function getCurrentCommitSha(repoRoot: string): string | null;
+declare function getPreviousCommitSha(repoRoot: string): string | null;
+declare function isGitRepo(dir: string): boolean;
+declare function getRepoName(repoRoot: string): string;
+
+declare function discoverSubmodules(repoRoot: string): SubmoduleInfo[];
+
+export { type GitBlobHash, type GitFileStatus, discoverSubmodules, getChangedFiles, getCurrentCommitSha, getGitBlobHashes, getPreviousCommitSha, getRepoName, isGitRepo };