@optave/codegraph 3.1.3 → 3.1.4

package/src/embeddings/strategies/structured.js

@@ -0,0 +1,43 @@
+import { findCalleeNames, findCallerNames } from '../../db.js';
+import { extractLeadingComment, splitIdentifier } from './text-utils.js';
+
+/**
+ * Build graph-enriched text for a symbol using dependency context.
+ * Produces compact, semantic text (~100 tokens) instead of full source code.
+ */
+export function buildStructuredText(node, file, lines, db) {
+  const readable = splitIdentifier(node.name);
+  const parts = [`${node.kind} ${node.name} (${readable}) in ${file}`];
+  const startLine = Math.max(0, node.line - 1);
+
+  // Extract parameters from signature (best-effort, single-line)
+  const sigLine = lines[startLine] || '';
+  const paramMatch = sigLine.match(/\(([^)]*)\)/);
+  if (paramMatch?.[1]?.trim()) {
+    parts.push(`Parameters: ${paramMatch[1].trim()}`);
+  }
+
+  // Graph context: callees (capped at 10)
+  const callees = findCalleeNames(db, node.id);
+  if (callees.length > 0) {
+    parts.push(`Calls: ${callees.slice(0, 10).join(', ')}`);
+  }
+
+  // Graph context: callers (capped at 10)
+  const callers = findCallerNames(db, node.id);
+  if (callers.length > 0) {
+    parts.push(`Called by: ${callers.slice(0, 10).join(', ')}`);
+  }
+
+  // Leading comment (high semantic value) or first few lines of code
+  const comment = extractLeadingComment(lines, startLine);
+  if (comment) {
+    parts.push(comment);
+  } else {
+    const endLine = Math.min(lines.length, startLine + 4);
+    const snippet = lines.slice(startLine, endLine).join('\n').trim();
+    if (snippet) parts.push(snippet);
+  }
+
+  return parts.join('\n');
+}

package/src/embeddings/strategies/text-utils.js

@@ -0,0 +1,43 @@
+/**
+ * Split an identifier into readable words.
+ * camelCase/PascalCase -> "camel Case", snake_case -> "snake case", kebab-case -> "kebab case"
+ */
+export function splitIdentifier(name) {
+  return name
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ')
+    .trim();
+}
+
+/**
+ * Extract leading comment text (JSDoc, //, #, etc.) above a function line.
+ * Returns the cleaned comment text or null if none found.
+ */
+export function extractLeadingComment(lines, fnLineIndex) {
+  if (fnLineIndex > lines.length) return null;
+  const raw = [];
+  for (let i = fnLineIndex - 1; i >= Math.max(0, fnLineIndex - 15); i--) {
+    if (i >= lines.length) continue;
+    const trimmed = lines[i].trim();
+    if (/^(\/\/|\/\*|\*\/|\*|#|\/\/\/)/.test(trimmed)) {
+      raw.unshift(trimmed);
+    } else if (trimmed === '') {
+      if (raw.length > 0) break;
+    } else {
+      break;
+    }
+  }
+  if (raw.length === 0) return null;
+  return raw
+    .map((line) =>
+      line
+        .replace(/^\/\*\*?\s?|\*\/$/g, '') // opening /** or /* and closing */
+        .replace(/^\*\s?/, '') // middle * lines
+        .replace(/^\/\/\/?\s?/, '') // // or ///
+        .replace(/^#\s?/, '') // # (Python/Ruby)
+        .trim(),
+    )
+    .filter((l) => l.length > 0)
+    .join(' ');
+}

package/src/errors.js

@@ -0,0 +1,78 @@
+/**
+ * Domain error hierarchy for codegraph.
+ *
+ * Library code throws these instead of calling process.exit() or throwing
+ * bare Error instances. The CLI top-level catch formats them for humans;
+ * MCP returns structured { isError, code } responses.
+ */
+
+export class CodegraphError extends Error {
+  /** @type {string} */
+  code;
+
+  /** @type {string|undefined} */
+  file;
+
+  /**
+   * @param {string} message
+   * @param {object} [opts]
+   * @param {string} [opts.code]
+   * @param {string} [opts.file]  - Related file path, if applicable
+   * @param {Error}  [opts.cause] - Original error that triggered this one
+   */
+  constructor(message, { code = 'CODEGRAPH_ERROR', file, cause } = {}) {
+    super(message, { cause });
+    this.name = 'CodegraphError';
+    this.code = code;
+    this.file = file;
+  }
+}
+
+export class ParseError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'PARSE_FAILED', ...opts });
+    this.name = 'ParseError';
+  }
+}
+
+export class DbError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'DB_ERROR', ...opts });
+    this.name = 'DbError';
+  }
+}
+
+export class ConfigError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'CONFIG_INVALID', ...opts });
+    this.name = 'ConfigError';
+  }
+}
+
+export class ResolutionError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'RESOLUTION_FAILED', ...opts });
+    this.name = 'ResolutionError';
+  }
+}
+
+export class EngineError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'ENGINE_UNAVAILABLE', ...opts });
+    this.name = 'EngineError';
+  }
+}
+
+export class AnalysisError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'ANALYSIS_FAILED', ...opts });
+    this.name = 'AnalysisError';
+  }
+}
+
+export class BoundaryError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'BOUNDARY_VIOLATION', ...opts });
+    this.name = 'BoundaryError';
+  }
+}