@aabadin/project-memory-context 0.1.0

package/src/providers/cloud-api-provider.mjs

@@ -0,0 +1,88 @@
+import { classifyEnrichmentError } from '../enrichment-errors.mjs';
+
+function getCloudApiConfig(context) {
+  return context?.config?.cloudApi ?? {};
+}
+
+function trimTrailingSlash(value) {
+  return value.replace(/\/+$/, '');
+}
+
+function buildSignal(request) {
+  return request?.timeoutMs ? AbortSignal.timeout(request.timeoutMs) : undefined;
+}
+
+export function createCloudApiProvider({ fetchImpl = fetch } = {}) {
+  return {
+    kind: 'cloud-api',
+    isConfigured(context) {
+      const { provider = 'openai-compatible', baseUrl, model, apiKeyEnv } = getCloudApiConfig(context);
+      const apiKey = context?.env?.[apiKeyEnv];
+
+      if (!baseUrl || !model || !apiKeyEnv) {
+        return { ok: false, reason: 'cloud-api requires baseUrl, model, and apiKeyEnv' };
+      }
+
+      if (!apiKey) {
+        return { ok: false, reason: `cloud-api requires api key in ${apiKeyEnv}` };
+      }
+
+      return { ok: true, provider };
+    },
+    async isAvailable(context) {
+      const configured = this.isConfigured(context);
+      if (!configured.ok) {
+        return configured;
+      }
+
+      const { provider = 'openai-compatible', baseUrl, apiKeyEnv } = getCloudApiConfig(context);
+      const apiKey = context?.env?.[apiKeyEnv];
+
+      try {
+        const response = await fetchImpl(`${trimTrailingSlash(baseUrl)}/models`, {
+          method: 'GET',
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+          },
+          signal: buildSignal(context?.request),
+        });
+        if (!response.ok) {
+          const message = `${provider} ${response.status}: ${typeof response.text === 'function' ? await response.text() : 'provider unavailable'}`;
+          const classified = classifyEnrichmentError(new Error(message));
+          return { ok: false, reason: classified.message, errorType: classified.type };
+        }
+        return { ok: true };
+      } catch (error) {
+        const classified = classifyEnrichmentError(error);
+        return { ok: false, reason: classified.message, errorType: classified.type };
+      }
+    },
+    async enrich(request, context) {
+      const { provider = 'openai-compatible', baseUrl, model, apiKeyEnv } = getCloudApiConfig(context);
+      const apiKey = context?.env?.[apiKeyEnv];
+      const response = await fetchImpl(`${trimTrailingSlash(baseUrl)}/chat/completions`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${apiKey}`,
+        },
+        signal: buildSignal(request),
+        body: JSON.stringify({
+          model,
+          messages: [{ role: 'user', content: request.prompt }],
+        }),
+      });
+
+      if (!response.ok) {
+        throw new Error(`${provider} ${response.status}: ${await response.text()}`);
+      }
+
+      const data = await response.json();
+      return {
+        content: data.choices?.[0]?.message?.content ?? '',
+        provider,
+        model,
+      };
+    },
+  };
+}

package/src/providers/local-model-provider.mjs

@@ -0,0 +1,67 @@
+import { classifyEnrichmentError } from '../enrichment-errors.mjs';
+
+function getLocalModelConfig(context) {
+  return context?.config?.localModel ?? {};
+}
+
+function buildSignal(request) {
+  return request?.timeoutMs ? AbortSignal.timeout(request.timeoutMs) : undefined;
+}
+
+export function createLocalModelProvider({ fetchImpl = fetch } = {}) {
+  return {
+    kind: 'local-model',
+    isConfigured(context) {
+      const { baseUrl, model } = getLocalModelConfig(context);
+      if (!baseUrl || !model) {
+        return { ok: false, reason: 'local-model requires baseUrl and model' };
+      }
+
+      return { ok: true };
+    },
+    async isAvailable(context) {
+      const configured = this.isConfigured(context);
+      if (!configured.ok) {
+        return configured;
+      }
+
+      const { baseUrl } = getLocalModelConfig(context);
+
+      try {
+        const response = await fetchImpl(`${baseUrl}/api/tags`, {
+          signal: buildSignal(context?.request),
+        });
+        if (!response.ok) {
+          const message = `ollama ${response.status}: ${typeof response.text === 'function' ? await response.text() : 'provider unavailable'}`;
+          const classified = classifyEnrichmentError(new Error(message));
+          return { ok: false, reason: classified.message, errorType: classified.type };
+        }
+        return { ok: true };
+      } catch (error) {
+        const classified = classifyEnrichmentError(error);
+        return { ok: false, reason: classified.message, errorType: classified.type };
+      }
+    },
+    async enrich(request, context) {
+      const { provider = 'ollama', baseUrl, model } = getLocalModelConfig(context);
+      const response = await fetchImpl(`${baseUrl}/api/generate`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        signal: buildSignal(request),
+        body: JSON.stringify({
+          model,
+          prompt: request.prompt,
+          stream: false,
+          options: { temperature: 0.1, num_predict: 512 },
+        }),
+      });
+
+      if (!response.ok) {
+        throw new Error(`Ollama ${response.status}: ${await response.text()}`);
+      }
+
+      const data = await response.json();
+      return { content: data.response, provider, model };
+    },
+  };
+}

package/src/refresh-state.mjs

@@ -0,0 +1,21 @@
+export function createEmptyRefreshState() {
+  return {
+    trackedFiles: {},
+    memoryHashes: {},
+    updatedAt: null,
+  };
+}
+
+export function updateRefreshStateEntry(state, filePath, hash) {
+  return {
+    ...state,
+    trackedFiles: {
+      ...state.trackedFiles,
+      [filePath]: hash,
+    },
+  };
+}
+
+export function shouldRefreshProjectContext(state, filePath, nextHash) {
+  return state.trackedFiles[filePath] !== nextHash;
+}

package/src/result-input.mjs

@@ -0,0 +1,9 @@
+import { readFile } from 'node:fs/promises';
+
+export async function loadResultInput(rawInput) {
+  const input = String(rawInput ?? '').trim();
+  const jsonText = input.startsWith('@')
+    ? await readFile(input.slice(1), 'utf8')
+    : input;
+  return JSON.parse(jsonText);
+}

package/src/retrieval/context-renderer.mjs

@@ -0,0 +1,97 @@
+import { createDepthConfig } from './query-engine.mjs';
+
+export function renderContext({ target, neighbors, edges, depth, depthReached, projectBase, memoryContents, sourceCode }) {
+  const config = createDepthConfig(depth);
+  const maxChars = config.maxTokens * 4;
+
+  const sections = [];
+
+  if (projectBase) {
+    sections.push(`## Project Base\nStack: ${projectBase.stack} | Architecture: ${projectBase.architecture}`);
+  }
+
+  const enrichment = target.memoryId ? (memoryContents.get(target.memoryId) ?? '') : '';
+  const rangeStr = target.range ? ` (L${target.range.startLine}-${target.range.endLine})` : '';
+  let targetSection = `### Target: ${target.name} (${target.kind})\nFile: ${target.filePath}${rangeStr}`;
+  if (enrichment) {
+    targetSection += `\n${enrichment}`;
+  }
+  sections.push(targetSection);
+
+  if (neighbors.length > 0 && depth !== 'compact' || neighbors.length > 0 && depth === 'compact') {
+    const edgeMap = new Map();
+    for (const edge of edges) {
+      if (!edgeMap.has(edge.target)) edgeMap.set(edge.target, []);
+      edgeMap.get(edge.target).push(edge);
+      if (!edgeMap.has(edge.source)) edgeMap.set(edge.source, []);
+      edgeMap.get(edge.source).push(edge);
+    }
+
+    const lines = [];
+    for (const nb of neighbors) {
+      const nbEnrichment = nb.memoryId ? (memoryContents.get(nb.memoryId) ?? '') : '';
+      const firstLine = nbEnrichment ? nbEnrichment.split('\n')[0] : '';
+
+      const relEdge = edges.find(e => e.source === nb.graphNodeId || e.target === nb.graphNodeId);
+      const relation = relEdge ? relEdge.relation : '';
+      const dir = relEdge ? (relEdge.source === target.graphNodeId ? '→' : '←') : '';
+
+      let bullet = `- **${nb.name}** (${nb.kind}) ${dir} ${relation}`;
+      if (nb.filePath && nb.filePath !== target.filePath) {
+        bullet += ` — ${nb.filePath}`;
+      }
+      if (firstLine) {
+        bullet += `\n  ${firstLine}`;
+      }
+      lines.push(bullet);
+    }
+
+    if (lines.length > 0) {
+      sections.push(`### Structural Neighbors\n${lines.join('\n')}`);
+    }
+  }
+
+  if (depth === 'extended' || depth === 'deep' || depth === 'disk') {
+    const communities = new Map();
+    for (const nb of neighbors) {
+      const comm = nb.community ?? 'default';
+      if (!communities.has(comm)) communities.set(comm, []);
+      communities.get(comm).push(nb);
+    }
+    if (communities.size > 0 && !(communities.size === 1 && communities.has('default'))) {
+      const commLines = [];
+      for (const [comm, members] of communities) {
+        if (comm === 'default') continue;
+        commLines.push(`- **${comm}**: ${members.map(m => m.name).join(', ')}`);
+      }
+      if (commLines.length > 0) {
+        sections.push(`### Module Communities\n${commLines.join('\n')}`);
+      }
+    }
+  }
+
+  if (depth === 'deep' || depth === 'disk') {
+    const inbound = edges.filter(e => e.target === target.graphNodeId);
+    if (inbound.length > 0) {
+      const impactLines = inbound.map(e => {
+        const srcNode = neighbors.find(n => n.graphNodeId === e.source);
+        const srcName = srcNode ? srcNode.name : e.source;
+        return `- ${srcName} — ${e.relation}`;
+      });
+      sections.push(`### Impact Scope\n${impactLines.join('\n')}`);
+    }
+  }
+
+  if (depth === 'disk' && sourceCode) {
+    sections.push(`### Source Code\n\`\`\`\n${sourceCode}\n\`\`\``);
+  }
+
+  const header = `## Context: ${target.name}`;
+  let result = header + '\n\n' + sections.join('\n\n');
+
+  if (result.length > maxChars) {
+    result = result.slice(0, maxChars);
+  }
+
+  return result;
+}

package/src/retrieval/query-engine.mjs

@@ -0,0 +1,230 @@
+const DEPTH_PRESETS = {
+  compact: { maxHops: 1, includeCommunity: false, maxTokens: 2000, readSourceFiles: false },
+  extended: { maxHops: 2, includeCommunity: true, maxTokens: 5000, readSourceFiles: false },
+  deep: { maxHops: 3, includeCommunity: true, maxTokens: 10000, readSourceFiles: false },
+  disk: { maxHops: 3, includeCommunity: true, maxTokens: 15000, readSourceFiles: true },
+};
+
+export function createDepthConfig(depth) {
+  const preset = DEPTH_PRESETS[depth] ?? DEPTH_PRESETS.compact;
+  return { ...preset };
+}
+
+function parseSymbolKeyParts(key) {
+  return key.split('|');
+}
+
+function extractName(parts) {
+  return parts.length >= 5 ? parts[parts.length - 2] : null;
+}
+
+function extractFilePath(parts) {
+  return parts.length >= 2 ? parts[1] : null;
+}
+
+function normalizePath(filePath) {
+  return String(filePath ?? '').replace(/\\/g, '/');
+}
+
+export function focusToEdgeTypes(focus) {
+  const map = {
+    dependencies: ['imports', 'imports_from'],
+    callers: ['calls'],
+    containment: ['contains', 'method'],
+  };
+  return map[focus] ?? ['calls', 'imports', 'imports_from', 'contains', 'method'];
+}
+
+export function createQueryEngine({ graph, symbolIndex, worklist, enrichmentDir, projectSlug }) {
+  const nodeMap = new Map();
+  for (const node of graph.nodes ?? []) {
+    nodeMap.set(node.id, node);
+  }
+
+  const graphNodeIdToSymbolKeyMap = new Map();
+  const nameToSymbolKeys = new Map();
+  const filePathToSymbolKeys = new Map();
+
+  for (const key of Object.keys(symbolIndex)) {
+    const entry = symbolIndex[key];
+    if (entry.graphNodeId) {
+      graphNodeIdToSymbolKeyMap.set(entry.graphNodeId, key);
+    }
+
+    const parts = parseSymbolKeyParts(key);
+    const name = extractName(parts);
+    if (name) {
+      const arr = nameToSymbolKeys.get(name);
+      if (arr) {
+        arr.push(key);
+      } else {
+        nameToSymbolKeys.set(name, [key]);
+      }
+    }
+
+    const fp = extractFilePath(parts);
+    if (fp) {
+      const normalized = normalizePath(fp);
+      const arr = filePathToSymbolKeys.get(normalized);
+      if (arr) {
+        arr.push(key);
+      } else {
+        filePathToSymbolKeys.set(normalized, [key]);
+      }
+    }
+  }
+
+  const links = graph.links ?? [];
+
+  function traverseGraph({ nodeIds, maxHops, edgeTypes, direction }) {
+    const types = edgeTypes ?? ['calls', 'imports', 'imports_from', 'contains', 'method'];
+    const dir = direction ?? 'outbound';
+
+    const visited = new Set();
+    const resultNodes = [];
+    const resultEdges = [];
+    let frontier = [];
+
+    for (const id of nodeIds) {
+      const node = nodeMap.get(id);
+      if (!node) continue;
+      visited.add(id);
+      resultNodes.push(node);
+      frontier.push(id);
+    }
+
+    let depthReached = 0;
+
+    for (let hop = 0; hop < maxHops; hop++) {
+      const nextFrontier = [];
+      for (const nodeId of frontier) {
+        for (const link of links) {
+          if (!types.includes(link.relation)) continue;
+          let neighbor = null;
+          if (dir === 'outbound' && link.source === nodeId) {
+            neighbor = link.target;
+          } else if (dir === 'inbound' && link.target === nodeId) {
+            neighbor = link.source;
+          }
+          if (neighbor != null && !visited.has(neighbor)) {
+            visited.add(neighbor);
+            const neighborNode = nodeMap.get(neighbor);
+            if (neighborNode) {
+              resultNodes.push(neighborNode);
+              resultEdges.push(link);
+              nextFrontier.push(neighbor);
+            }
+          }
+        }
+      }
+      if (nextFrontier.length === 0) break;
+      frontier = nextFrontier;
+      depthReached = hop + 1;
+    }
+
+    return { nodes: resultNodes, edges: resultEdges, depth_reached: depthReached };
+  }
+
+  function resolveWorklistEntry(symbolKey) {
+    return (worklist ?? []).find((e) => e.symbolKey === symbolKey) ?? null;
+  }
+
+  function buildSymbolInfo(symbolKey) {
+    const entry = symbolIndex[symbolKey];
+    const wl = resolveWorklistEntry(symbolKey);
+    const parts = parseSymbolKeyParts(symbolKey);
+    return {
+      symbolKey,
+      name: wl?.name ?? extractName(parts),
+      filePath: wl?.filePath ?? extractFilePath(parts),
+      kind: wl?.kind ?? null,
+      range: wl?.range ?? null,
+      graphNodeId: entry?.graphNodeId ?? null,
+      memoryId: entry?.memoryId ?? null,
+      status: entry?.status ?? null,
+    };
+  }
+
+  function querySymbolContext({ symbolKey, depth }) {
+    const config = createDepthConfig(depth);
+    const target = buildSymbolInfo(symbolKey);
+    if (!target.graphNodeId) {
+      return { target, neighbors: [], edges: [], depth_reached: 0 };
+    }
+    const traversal = traverseGraph({ nodeIds: [target.graphNodeId], maxHops: config.maxHops });
+    const neighbors = traversal.nodes
+      .filter((n) => n.id !== target.graphNodeId)
+      .map((n) => {
+        const sk = graphNodeIdToSymbolKeyMap.get(n.id);
+        if (sk) return buildSymbolInfo(sk);
+        return { graphNodeId: n.id, label: n.label, sourceFile: n.source_file ?? null, symbolKey: null };
+      });
+    return { target, neighbors, edges: traversal.edges, depth_reached: traversal.depth_reached };
+  }
+
+  function queryFileContext({ filePath, depth }) {
+    const config = createDepthConfig(depth);
+    const normalized = normalizePath(filePath);
+    const symbolKeys = filePathToSymbolKeys.get(normalized) ?? [];
+    const symbols = symbolKeys.map(buildSymbolInfo);
+    const fileNodeIds = (graph.nodes ?? [])
+      .filter((n) => normalizePath(n.source_file ?? '') === normalized)
+      .map((n) => n.id);
+    const outTraversal = traverseGraph({ nodeIds: fileNodeIds, maxHops: config.maxHops });
+    const inTraversal = traverseGraph({ nodeIds: fileNodeIds, maxHops: config.maxHops, direction: 'inbound' });
+    const fileNodeIdSet = new Set(fileNodeIds);
+    const seen = new Set();
+    const neighbors = [];
+    const edges = [];
+    for (const n of [...outTraversal.nodes, ...inTraversal.nodes]) {
+      if (fileNodeIdSet.has(n.id) || seen.has(n.id)) continue;
+      seen.add(n.id);
+      const sk = graphNodeIdToSymbolKeyMap.get(n.id);
+      neighbors.push(sk ? buildSymbolInfo(sk) : { graphNodeId: n.id, label: n.label, sourceFile: n.source_file ?? null, symbolKey: null });
+    }
+    const edgeSet = new Set();
+    for (const e of [...outTraversal.edges, ...inTraversal.edges]) {
+      const key = `${e.source}->${e.target}`;
+      if (!edgeSet.has(key)) { edgeSet.add(key); edges.push(e); }
+    }
+    const depth_reached = Math.max(outTraversal.depth_reached, inTraversal.depth_reached);
+    return { symbols, neighbors, edges, depth_reached };
+  }
+
+  function queryImpactScope({ symbolKeys, depth }) {
+    const config = createDepthConfig(depth);
+    const targets = symbolKeys.map(buildSymbolInfo);
+    const nodeIds = targets.map((t) => t.graphNodeId).filter(Boolean);
+    const traversal = traverseGraph({ nodeIds, maxHops: config.maxHops, direction: 'inbound' });
+    const targetIdSet = new Set(nodeIds);
+    const dependents = traversal.nodes
+      .filter((n) => !targetIdSet.has(n.id))
+      .map((n) => {
+        const sk = graphNodeIdToSymbolKeyMap.get(n.id);
+        if (sk) return buildSymbolInfo(sk);
+        return { graphNodeId: n.id, label: n.label, sourceFile: n.source_file ?? null, symbolKey: null };
+      });
+    return {
+      target: targets.length === 1 ? targets[0] : targets,
+      dependents,
+      edges: traversal.edges,
+      depth_reached: traversal.depth_reached,
+    };
+  }
+
+  return {
+    graphNodeIdToSymbolKey(graphNodeId) {
+      return graphNodeIdToSymbolKeyMap.get(graphNodeId) ?? null;
+    },
+    findSymbolKeyByName(name) {
+      return nameToSymbolKeys.get(name) ?? [];
+    },
+    findSymbolKeysByFilePath(filePath) {
+      return filePathToSymbolKeys.get(normalizePath(filePath)) ?? [];
+    },
+    traverseGraph,
+    querySymbolContext,
+    queryFileContext,
+    queryImpactScope,
+  };
+}

package/src/semantic-report.mjs

@@ -0,0 +1,26 @@
+function parseList(value) {
+  return String(value ?? '')
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+export function normalizeSemanticReport(report) {
+  const fields = new Map();
+
+  for (const finding of report.findings ?? []) {
+    const [rawKey, ...rest] = String(finding).split(':');
+    if (!rawKey || rest.length === 0) continue;
+    fields.set(rawKey.trim().toLowerCase(), rest.join(':').trim());
+  }
+
+  const summary = String(report.summary ?? '').trim();
+  return {
+    responsibility: fields.get('responsibility') || summary,
+    inputs: parseList(fields.get('inputs')),
+    output: fields.get('output') || 'Not specified.',
+    dependencies: parseList(fields.get('dependencies')),
+    role: fields.get('role') || 'Not specified.',
+    summary,
+  };
+}

package/src/semantic-unit.mjs

@@ -0,0 +1,74 @@
+function sliceLines(content, startLine, endLine) {
+  return content.split('\n').slice(startLine - 1, endLine).join('\n');
+}
+
+function collectTypeScriptContext(lines, symbolStartLine) {
+  const context = [];
+  for (let index = 0; index < symbolStartLine - 1; index += 1) {
+    const line = lines[index];
+    if (/^\s*import\b/.test(line)) {
+      context.push(line);
+    }
+  }
+  return context;
+}
+
+function collectCSharpContext(lines, symbolStartLine) {
+  const context = [];
+  for (let index = 0; index < symbolStartLine - 1; index += 1) {
+    const line = lines[index];
+    if (/^\s*using\s+/.test(line) || /^\s*namespace\s+/.test(line)) {
+      context.push(line);
+    }
+  }
+  return context;
+}
+
+export function buildSemanticPrompt(unit) {
+  return [
+    `Symbol Key: ${unit.symbolKey}`,
+    `Language: ${unit.language}`,
+    `Kind: ${unit.kind}`,
+    `Name: ${unit.name}`,
+    `Location: ${unit.filePath}:${unit.range.startLine}-${unit.range.endLine}`,
+    '',
+    'Context:',
+    unit.context || 'None',
+    '',
+    'Code:',
+    unit.code,
+    '',
+    'Return a compact structured explanation with:',
+    '- responsibility',
+    '- primary inputs',
+    '- output',
+    '- immediate dependencies',
+    '- role in module',
+  ].join('\n');
+}
+
+export function buildSemanticUnit({ symbol, content }) {
+  const lines = content.split('\n');
+  const { startLine, endLine } = symbol.range;
+  const contextLines = symbol.language === 'csharp'
+    ? collectCSharpContext(lines, startLine)
+    : collectTypeScriptContext(lines, startLine);
+
+  const unit = {
+    symbolKey: symbol.symbolKey,
+    graphNodeId: symbol.graphNodeId ?? null,
+    language: symbol.language,
+    filePath: symbol.filePath,
+    kind: symbol.kind,
+    name: symbol.name,
+    range: symbol.range,
+    codeHash: symbol.codeHash,
+    context: contextLines.join('\n').trim(),
+    code: sliceLines(content, startLine, endLine),
+  };
+
+  return {
+    ...unit,
+    prompt: buildSemanticPrompt(unit),
+  };
+}