md-semantic-search 0.3.0 → 0.4.0

package/src/serve.mjs

@@ -0,0 +1,387 @@
+// @ts-check
+/**
+ * Long-running daemon mode (issue #12): keeps the parsed index AND the
+ * embedding extractor in memory across queries, so repeated searches skip
+ * the ~280 MB model load and the full vectors.json parse on every call.
+ *
+ *   mdss serve --db ./docs [--port 8747] [--host 127.0.0.1] [--watch]
+ *
+ * HTTP API (no auth — binds to loopback 127.0.0.1 by default; use --host to
+ * opt into LAN exposure, issue #16):
+ *   POST /search  {"query": "...", "k": 6, "semanticOnly": false} → {results: [...]}
+ *   GET  /health  → {ok, chunks, model, dim, built, watching}
+ *   GET  /        → endpoint list
+ *
+ * --watch polls the markdown base for mtime changes (no new deps) and runs the
+ * incremental re-index (chunk-level cache) when something changed.
+ */
+import http from 'node:http';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildIndex } from './indexer.mjs';
+import { loadIndex, searchIndex } from './search.mjs';
+import { walkMarkdown } from './core.mjs';
+
+const DEFAULT_PORT = 8747;
+const DEFAULT_HOST = '127.0.0.1';     // loopback by default — LAN exposure is opt-in via --host
+const WATCH_INTERVAL_MS = 3000;
+const WATCH_DELAY_MS = 1000;          // quiet-period debounce before a change fires a re-index (issue #42)
+const MAX_BODY_BYTES = 64 * 1024;     // POST /search body cap (DoS guard, issue #16)
+
+/**
+ * @typedef {Object} ServeState
+ * @property {ReturnType<typeof loadIndex>} loaded - parsed index + resolved model
+ * @property {string} indexDir
+ * @property {string} cacheDir
+ * @property {boolean} offline
+ * @property {Function} embedFn
+ * @property {Function} [rerankFn] - rerank override (tests)
+ * @property {boolean} watching
+ * @property {number} [reindexCount] - watch loop: how many re-indexes fired (tests)
+ */
+
+/**
+ * Create the HTTP server (not yet listening). The index is built if missing,
+ * then loaded once into memory; every /search reuses it (issue #2).
+ * @param {object} opts
+ * @param {string} opts.indexDir
+ * @param {string} opts.cacheDir
+ * @param {string} [opts.db] - markdown base; required for --watch / auto-build
+ * @param {string} [opts.modelName='e5-base']
+ * @param {string[]} [opts.ignore=[]]
+ * @param {boolean} [opts.offline=false]
+ * @param {boolean} [opts.watch=false]
+ * @param {number} [opts.watchInterval=WATCH_INTERVAL_MS]
+ * @param {number} [opts.watchDelay=WATCH_DELAY_MS] - quiet-period debounce (issue #42)
+ * @param {Function} [opts.embedFn] - embed override (tests)
+ * @param {Function} [opts.rerankFn] - rerank override (tests)
+ * @param {(msg:string)=>void} [opts.log]
+ * @returns {Promise<{server: import('node:http').Server, state: ServeState, close: ()=>Promise<void>}>}
+ */
+export async function createServe(opts) {
+  const {
+    indexDir, cacheDir, db, modelName = 'e5-base', ignore = [],
+    offline = false, watch = false, watchInterval = WATCH_INTERVAL_MS,
+    watchDelay = WATCH_DELAY_MS,
+    embedFn, rerankFn, log = () => {},
+  } = opts;
+
+  fs.mkdirSync(indexDir, { recursive: true });
+  if (!fs.existsSync(path.join(indexDir, 'vectors.json'))) {
+    if (!db) throw new Error('serve: no index found and no --db given to build one');
+    log(`No index at ${indexDir} — building it from ${db}…`);
+    await buildIndex({ db, indexDir, cacheDir, modelName, ignore, offline, log, embedFn });
+  }
+
+  /** @type {ServeState} */
+  const state = {
+    loaded: loadIndex(indexDir),
+    indexDir, cacheDir, offline, embedFn, rerankFn, watching: watch,
+  };
+
+  const server = http.createServer((req, res) => {
+    handleRequest(req, res, state).catch(e => {
+      json(res, 500, { error: e.message });
+    });
+  });
+
+  let stopped = false;
+  let timer = null;
+
+  const reload = async () => {
+    if (!db) return;
+    log('Change detected — re-indexing…');
+    // buildIndex acquires the index lock itself (issue #37). When a manual
+    // `mdss index` (or another mdss process) holds it, we get a "locked by PID…"
+    // error — that's NOT a failure: we just yield this cycle and let the next
+    // watch poll pick the change up once the other writer is done.
+    try {
+      await buildIndex({ db, indexDir, cacheDir, modelName, ignore, offline, log, embedFn });
+    } catch (e) {
+      if (/(being written by pid|being written|lock)/i.test(String(e?.message || ''))) {
+        log(`re-index deferred: ${e.message}`);
+        return false;                       // politely yield — next poll retries
+      }
+      throw e;                              // real error → caller's .catch logs it
+    }
+    state.loaded = loadIndex(indexDir);
+    state.reindexCount = (state.reindexCount ?? 0) + 1;
+    log(`Re-indexed; ${state.loaded.index.chunks.length} chunks in memory.`);
+    return true;
+  };
+
+  // --- watch scanning (issue #42) ---
+  // Detection is anchored to the CONTENT the indexer last wrote, never to the
+  // poll-to-poll mtime delta. The authoritative per-file md5 lives in
+  // `.hashes.json` (keys are POSIX-relative paths, values are md5 of the file
+  // bytes as read by buildIndex). We compare the live tree against THAT
+  // baseline, so three subclasses are handled uniformly:
+  //   (a) no-op writes (touch/chmod, an editor rewriting identical bytes) —
+  //       mtime moved but md5 still equals the indexed hash → filtered out;
+  //   (b) coarse-mtime filesystems (FAT, older SMB) where two real edits share
+  //       one mtime window — mtime is a *hint to skip hashing*, never proof of
+  //       "unchanged"; the md5 compare still catches the edit;
+  //   (c) new / deleted files — a rel path absent from / present-only-in the
+  //       indexed set.
+  // A settle debounce (`watchDelay`, default 1s) then collapses a burst of
+  // successive saves (editor save → linter → save) into ONE re-index: we only
+  // reload once the tree's fingerprint has been stable for the quiet period.
+  const fileMd5 = (f) => crypto.createHash('md5').update(fs.readFileSync(f)).digest('hex');
+  const relOf = (f) => path.relative(db, f).split(path.sep).join('/');
+
+  /**
+   * Content fingerprint of the live tree: sorted `rel:md5` pairs. Two polls that
+   * see the same tree content produce the same fingerprint — this is the settle
+   * signal. Each file resolves through `hashAt`, so an unchanged (path, mtime)
+   * is served from the cache and only a file whose mtime moved pays a re-hash.
+   */
+  const treeContentFingerprint = (tree) => {
+    const parts = [];
+    for (const [f, { m, rel }] of tree) {
+      let md5;
+      try { md5 = hashAt(f, m); } catch { md5 = 'unreadable'; }
+      parts.push(`${rel}:${md5}`);
+    }
+    return parts.sort().join('|');
+  };
+
+  /** rel path → md5 of the content the indexer last persisted ({} when unreadable). */
+  const readIndexedHashes = () => {
+    try { return JSON.parse(fs.readFileSync(path.join(indexDir, '.hashes.json'), 'utf8')); }
+    catch { return {}; }
+  };
+
+  /** Live tree snapshot: abs path → { m, rel }. Files that vanish mid-scan are skipped. */
+  const scanTree = () => {
+    const tree = new Map();
+    if (!db) return tree;
+    for (const f of walkMarkdown(db, ignore)) {
+      try { tree.set(f, { m: fs.statSync(f).mtimeMs, rel: relOf(f) }); }
+      catch { /* file vanished mid-scan */ }
+    }
+    return tree;
+  };
+
+  // md5s are cached per (path, mtime) so steady-state polls stay cheap; the
+  // cache is only a memo of "hash of the content at that mtime" and is never
+  // trusted across an mtime bump.
+  const md5Cache = new Map();   // abs path → { mtime, md5 }
+  const hashAt = (f, m) => {
+    const hit = md5Cache.get(f);
+    if (hit && hit.mtime === m) return hit.md5;
+    const md5 = fileMd5(f);
+    md5Cache.set(f, { mtime: m, md5 });
+    return md5;
+  };
+
+  /**
+   * rel paths whose CONTENT differs from the INDEXED baseline. mtime is only a
+   * pre-filter to skip hashing a file that is unchanged AND already confirmed:
+   * the hash cache tells us "content at this mtime", the index tells us "content
+   * that is indexed". A file is reported changed iff its *current* content hash
+   * differs from the hash the indexer last persisted.
+   */
+  const contentChangedPaths = (tree, indexedHashes) => {
+    const out = [];
+    const liveRels = new Set();
+    for (const [f, { m, rel }] of tree) {
+      liveRels.add(rel);
+      if (!(rel in indexedHashes)) { out.push(rel); continue; }       // new file
+      const cached = md5Cache.get(f);
+      // Fast path: we have already hashed THIS (path, mtime) and it matches the index.
+      if (cached && cached.mtime === m && cached.md5 === indexedHashes[rel]) continue;
+      let fresh;
+      try { fresh = hashAt(f, m); } catch { continue; }               // unreadable mid-write → next poll
+      if (fresh !== indexedHashes[rel]) out.push(rel);                // real content change
+      // no-op write (mtime moved, content identical to the index): fall through,
+      // the cache now confirms content-at-this-mtime matches the baseline, so the
+      // NEXT poll with the same mtime takes the fast path and stays quiet.
+    }
+    for (const rel of Object.keys(indexedHashes)) {
+      if (!liveRels.has(rel)) out.push(rel);                          // deleted file
+    }
+    return out;
+  };
+
+  const watchLoop = async () => {
+    // The baseline is what the INDEX contains, not what the last poll saw.
+    let indexedHashes = readIndexedHashes();
+    // NOTE: NO cache pre-seeding. The md5 cache is a memo of «content at this
+    // (path, mtime)», and seeding it from the INDEXED hashes would stamp a file
+    // we never read with the indexed value under a CURRENT mtime — the same
+    // false-clean that masks a deferred edit (the source of the watch-loop bug
+    // this fixed, issue #37). Unseeded first polls hash everything ONCE, then
+    // steady-state polls hit the cache on unchanged (path, mtime).
+
+    let lastFingerprint = treeContentFingerprint(scanTree()); // content baseline
+    let lastChangeAt = 0;   // timestamp of the most recent content movement
+    let pending = false;    // tree differs from the index AND has stopped moving
+    while (!stopped) {
+      await new Promise(r => { timer = setTimeout(r, watchInterval); });
+      if (stopped) return;
+      const tree = scanTree();
+      const fingerprint = treeContentFingerprint(tree);
+      const changed = contentChangedPaths(tree, indexedHashes);
+      if (fingerprint !== lastFingerprint) {
+        // Content moved since the last poll: a save (or several) is in flight.
+        // (Re)start the quiet window; do NOT reload yet — the burst may not be
+        // done (editor save → linter → save). A no-op touch does NOT move the
+        // fingerprint, so it can't even enter here.
+        if (!pending) log(`watch: change in ${changed.length} file(s) — waiting ${watchDelay} ms for the tree to settle…`);
+        pending = true;
+        lastFingerprint = fingerprint;
+        lastChangeAt = Date.now();
+      } else if (pending && changed.length > 0 && Date.now() - lastChangeAt >= watchDelay) {
+        // Tree content stable for the whole quiet window AND still differs from
+        // the index → the burst settled on real new content. Re-index ONCE.
+        pending = false;
+        await reload().catch(e => log(`re-index failed: ${e.message}`));
+        // Whether or not the build ran (it may have been DEFERRED on another
+        // writer's lock, issue #37): re-read the baseline. When deferred the
+        // baseline is unchanged, so the tree STILL differs from it — and the
+        // no-motion re-check below re-opens the window next poll.
+        indexedHashes = readIndexedHashes();
+        // Re-seed ONLY files we have never hashed — never overwrite a fresh
+        // hash under an unchanged mtime with the STALE indexed value (it would
+        // mask the deferred edit, and the very defer we just made needs that
+        // fresh hash to survive into the next poll).
+        for (const [f, { m, rel }] of scanTree()) {
+          if (!md5Cache.has(f) && rel in indexedHashes) {
+            md5Cache.set(f, { mtime: m, md5: indexedHashes[rel] });
+          }
+        }
+        lastFingerprint = treeContentFingerprint(scanTree());
+      } else if (!pending && changed.length > 0 && fingerprint === lastFingerprint) {
+        // No motion this poll, yet the tree still differs from the index —
+        // the fingerprint/advanced-lock cycle closed (release after a defer,
+        // issue #37) or a coarse-mtime edit landed without moving the hash
+        // baseline. Open the quiet window so the deferred edit lands.
+        pending = true;
+        lastChangeAt = Date.now();
+        log(`watch: tree differs from index (no motion) — settling then re-index…`);
+      } else if (pending && changed.length === 0 && Date.now() - lastChangeAt < watchDelay) {
+        // Fingerprint stable AND content already equals the index — happens when
+        // a no-op write raced us into pending. Nothing to do; drop the pend.
+        pending = false;
+      }
+    }
+  };
+
+  if (watch) {
+    if (!db) throw new Error('serve --watch requires --db');
+    watchLoop();
+  }
+
+  const close = async () => {
+    stopped = true;
+    if (timer) clearTimeout(timer);
+    await /** @type {Promise<void>} */ (new Promise((resolve, reject) =>
+      server.close(err => err ? reject(err) : resolve())));
+  };
+
+  return { server, state, close };
+}
+
+/**
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {ServeState} state
+ */
+async function handleRequest(req, res, state) {
+  const url = new URL(req.url || '/', 'http://localhost');
+
+  if (req.method === 'POST' && url.pathname === '/search') {
+    // DoS guard (issue #16): honor a declared Content-Length, cap the streamed
+    // body at MAX_BODY_BYTES with 413, and never buffer unbounded input.
+    const declared = req.headers['content-length'];
+    if (declared !== undefined) {
+      const n = Number(declared);
+      if (!Number.isInteger(n) || n < 0 || n > MAX_BODY_BYTES) {
+        json(res, 413, { error: `payload too large (limit ${MAX_BODY_BYTES} bytes)` });
+        return;
+      }
+    }
+    let body = '';
+    let tooLarge = false;
+    for await (const chunk of req) {
+      body += chunk;
+      if (body.length > MAX_BODY_BYTES) { tooLarge = true; break; }
+    }
+    if (tooLarge) {
+      json(res, 413, { error: `payload too large (limit ${MAX_BODY_BYTES} bytes)` });
+      req.resume(); // drain the rest so the connection is not left half-open
+      return;
+    }
+    /** @type {Record<string, any>} */
+    let payload = {};
+    try { payload = body ? JSON.parse(body) : {}; }
+    catch (e) {
+      json(res, 400, { error: `invalid JSON body: ${e.message}` });
+      return;
+    }
+    const query = typeof payload.query === 'string' ? payload.query.trim() : '';
+    if (!query) { json(res, 400, { error: 'missing "query" string in JSON body' }); return; }
+    const k = Number.isInteger(payload.k) && payload.k > 0 ? payload.k : 6;
+
+    try {
+      const results = await searchIndex({
+        loaded: state.loaded,
+        cacheDir: state.cacheDir,
+        query,
+        k,
+        semanticOnly: !!payload.semanticOnly,
+        rerank: !!payload.rerank,
+        offline: state.offline,
+        embedFn: state.embedFn,
+        rerankFn: state.rerankFn,
+        tag: payload.tag,
+        project: payload.project,
+        type: payload.type,
+        status: payload.status,
+        canonicalOnly: payload.canonicalOnly,
+        custom: payload.custom,
+        explain: !!payload.explain,
+        maxPerFile: payload.maxPerFile || payload.maxPerDoc,
+      });
+      json(res, 200, { query, k, count: results.length, results });
+    } catch (e) {
+      json(res, 500, { error: e.message });
+    }
+    return;
+  }
+
+  if (req.method === 'GET' && url.pathname === '/health') {
+    json(res, 200, {
+      ok: true,
+      chunks: state.loaded.index.chunks.length,
+      model: state.loaded.model.id,
+      dim: state.loaded.index.dim || state.loaded.model.dim || 0,
+      built: state.loaded.index.built || null,
+      watching: state.watching,
+      indexDir: state.indexDir,
+    });
+    return;
+  }
+
+  if (req.method === 'GET' && (url.pathname === '/' || url.pathname === '/help')) {
+    json(res, 200, {
+      name: 'mdss serve',
+      endpoints: [
+        { method: 'POST', path: '/search', body: '{ "query": "...", "k": 6, "semanticOnly": false, "rerank": false }' },
+        { method: 'GET', path: '/health' },
+      ],
+    });
+    return;
+  }
+
+  json(res, 404, { error: `not found: ${req.method} ${url.pathname}` });
+}
+
+/** @param {import('node:http').ServerResponse} res @param {number} status @param {object} data */
+function json(res, status, data) {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+  res.end(JSON.stringify(data));
+}
+
+export { DEFAULT_PORT, DEFAULT_HOST, MAX_BODY_BYTES, WATCH_INTERVAL_MS };

package/src/wikilinks.mjs

@@ -0,0 +1,241 @@
+// @ts-check
+/**
+ * Wikilink and backlink relationship extraction and resolution (issue #61).
+ * Supports Obsidian wikilinks [[note]], [[note#heading|alias]], and relative Markdown links.
+ */
+
+/**
+ * @typedef {Object} RawLink
+ * @property {'wikilink'|'markdown'} type
+ * @property {string} target
+ * @property {string} [anchor]
+ * @property {string} [label]
+ * @property {string} raw
+ * @property {number} line
+ */
+
+/**
+ * @typedef {Object} ResolvedLink
+ * @property {string} raw
+ * @property {string} target
+ * @property {string} [resolvedFile]
+ * @property {'resolved'|'broken'|'ambiguous'} status
+ * @property {number} line
+ */
+
+/**
+ * Extract wikilinks and relative Markdown links from Markdown content.
+ * @param {string} text
+ * @returns {RawLink[]}
+ */
+export function extractLinks(text) {
+  if (!text) return [];
+  const lines = text.split(/\r?\n/);
+  const links = [];
+
+  // Match [[target#anchor|label]] or [[target|label]] or [[target]]
+  const wikiRegex = /\[\[([^\]\|#]+)(?:#([^\]\|]+))?(?:\|([^\]]+))?\]\]/g;
+  // Match relative Markdown links [label](./path/to/file.md) or [label](../path.md)
+  const mdLinkRegex = /\[([^\]]+)\]\(([^)]+\.md)(?:#([^)]+))?\)/g;
+
+  for (let i = 0; i < lines.length; i++) {
+    const lineNum = i + 1;
+    const line = lines[i];
+
+    let match;
+    wikiRegex.lastIndex = 0;
+    while ((match = wikiRegex.exec(line)) !== null) {
+      links.push({
+        type: 'wikilink',
+        target: match[1].trim(),
+        anchor: match[2]?.trim(),
+        label: match[3]?.trim(),
+        raw: match[0],
+        line: lineNum,
+      });
+    }
+
+    mdLinkRegex.lastIndex = 0;
+    while ((match = mdLinkRegex.exec(line)) !== null) {
+      const rawTarget = match[2].trim();
+      if (!rawTarget.startsWith('http://') && !rawTarget.startsWith('https://')) {
+        links.push({
+          type: 'markdown',
+          target: rawTarget,
+          anchor: match[3]?.trim(),
+          label: match[1]?.trim(),
+          raw: match[0],
+          line: lineNum,
+        });
+      }
+    }
+  }
+
+  return links;
+}
+
+/**
+ * Resolve extracted links against a map of documents (keyed by relative path/file).
+ * @param {RawLink[]} rawLinks
+ * @param {string} currentFile
+ * @param {Array<{file:string, title?:string, meta?:import('./frontmatter.mjs').DocumentMetadata}>} docs
+ * @returns {ResolvedLink[]}
+ */
+export function resolveLinks(rawLinks, currentFile, docs) {
+  if (!rawLinks || rawLinks.length === 0) return [];
+
+  // Build lookups: titleMap, aliasMap, pathMap
+  const pathMap = new Map();
+  const titleMap = new Map();
+  const aliasMap = new Map();
+
+  for (const doc of docs) {
+    const relFile = doc.file;
+    pathMap.set(relFile.toLowerCase(), relFile);
+    const basename = relFile.replace(/\.md$/i, '').split('/').pop()?.toLowerCase();
+    if (basename && !pathMap.has(basename)) {
+      pathMap.set(basename, relFile);
+    }
+
+    if (doc.title) {
+      const titleKey = doc.title.toLowerCase();
+      const existing = titleMap.get(titleKey) || [];
+      existing.push(relFile);
+      titleMap.set(titleKey, existing);
+    }
+
+    if (doc.meta?.aliases) {
+      for (const alias of doc.meta.aliases) {
+        const aliasKey = alias.toLowerCase();
+        const existing = aliasMap.get(aliasKey) || [];
+        existing.push(relFile);
+        aliasMap.set(aliasKey, existing);
+      }
+    }
+  }
+
+  return rawLinks.map(link => {
+    const targetKey = link.target.toLowerCase().replace(/\.md$/i, '');
+    let matches = [];
+
+    if (pathMap.has(targetKey)) {
+      matches.push(pathMap.get(targetKey));
+    } else if (titleMap.has(targetKey)) {
+      matches = titleMap.get(targetKey);
+    } else if (aliasMap.has(targetKey)) {
+      matches = aliasMap.get(targetKey);
+    }
+
+    matches = [...new Set(matches)];
+
+    if (matches.length === 1) {
+      return {
+        raw: link.raw,
+        target: link.target,
+        resolvedFile: matches[0],
+        status: 'resolved',
+        line: link.line,
+      };
+    } else if (matches.length > 1) {
+      return {
+        raw: link.raw,
+        target: link.target,
+        status: 'ambiguous',
+        line: link.line,
+      };
+    } else {
+      return {
+        raw: link.raw,
+        target: link.target,
+        status: 'broken',
+        line: link.line,
+      };
+    }
+  });
+}
+
+/**
+ * Build graph of outgoing links and backlinks across documents.
+ * @param {Array<{file:string, title?:string, text:string, meta?:import('./frontmatter.mjs').DocumentMetadata}>} docs
+ */
+export function buildRelationshipGraph(docs) {
+  const outgoing = new Map();
+  const backlinks = new Map();
+
+  for (const doc of docs) {
+    if (!outgoing.has(doc.file)) outgoing.set(doc.file, []);
+    if (!backlinks.has(doc.file)) backlinks.set(doc.file, []);
+  }
+
+  for (const doc of docs) {
+    const rawLinks = extractLinks(doc.text);
+    const resolved = resolveLinks(rawLinks, doc.file, docs);
+
+    const docOutgoing = outgoing.get(doc.file) || [];
+    for (const r of resolved) {
+      if (r.status === 'resolved' && r.resolvedFile && r.resolvedFile !== doc.file) {
+        docOutgoing.push({ file: r.resolvedFile, raw: r.raw, line: r.line });
+        const targetBacklinks = backlinks.get(r.resolvedFile) || [];
+        targetBacklinks.push({ file: doc.file, raw: r.raw, line: r.line });
+        backlinks.set(r.resolvedFile, targetBacklinks);
+      }
+    }
+    outgoing.set(doc.file, docOutgoing);
+  }
+
+  return { outgoing, backlinks };
+}
+
+/**
+ * Traverse graph to find related notes.
+ * @param {{outgoing: Map<string, Array<{file:string}>>, backlinks: Map<string, Array<{file:string}>>}} graph
+ * @param {string} targetFile
+ * @param {object} [opts]
+ * @param {'both'|'outgoing'|'backlinks'} [opts.direction='both']
+ * @param {number} [opts.depth=1]
+ * @returns {Array<{file:string, distance:number, direction:string}>}
+ */
+export function getRelatedNotes(graph, targetFile, opts = {}) {
+  const direction = opts.direction || 'both';
+  const maxDepth = opts.depth || 1;
+
+  const visited = new Set([targetFile]);
+  const results = [];
+
+  const queue = [{ file: targetFile, depth: 0 }];
+
+  while (queue.length > 0) {
+    const curr = queue.shift();
+    if (!curr) continue;
+
+    if (curr.depth >= maxDepth) continue;
+
+    const nextNodes = [];
+
+    if (direction === 'both' || direction === 'outgoing') {
+      const outList = graph.outgoing.get(curr.file) || [];
+      for (const item of outList) {
+        if (!visited.has(item.file)) {
+          visited.add(item.file);
+          results.push({ file: item.file, distance: curr.depth + 1, direction: 'outgoing' });
+          nextNodes.push({ file: item.file, depth: curr.depth + 1 });
+        }
+      }
+    }
+
+    if (direction === 'both' || direction === 'backlinks') {
+      const backList = graph.backlinks.get(curr.file) || [];
+      for (const item of backList) {
+        if (!visited.has(item.file)) {
+          visited.add(item.file);
+          results.push({ file: item.file, distance: curr.depth + 1, direction: 'backlink' });
+          nextNodes.push({ file: item.file, depth: curr.depth + 1 });
+        }
+      }
+    }
+
+    queue.push(...nextNodes);
+  }
+
+  return results;
+}