@grafema/util 0.3.0-beta

package/src/core/FileOverview.ts

@@ -0,0 +1,397 @@
+/**
+ * FileOverview - Get a structured overview of all entities in a file.
+ *
+ * Purpose: Show what a file contains and how its parts relate to each other.
+ * Unlike FileExplainer (which lists ALL nodes flat), FileOverview shows only
+ * meaningful entities (functions, classes, variables) with their key relationships
+ * (calls, extends, assigned-from).
+ *
+ * Unlike the context command (which shows ONE node's full neighborhood),
+ * FileOverview shows ALL entities at file level with curated edges.
+ *
+ * Use this when:
+ * - AI agent needs to understand a file before diving deeper
+ * - User wants a table-of-contents of a file with relationships
+ * - Quick orientation before using get_context on specific nodes
+ *
+ * @example
+ * ```typescript
+ * const overview = new FileOverview(backend);
+ * const result = await overview.getOverview('/abs/path/to/file.js');
+ * // result.functions[0].calls -> ["express", "Router"]
+ * ```
+ *
+ * @see REG-412
+ */
+
+import type { GraphBackend, BaseNodeRecord, NodeFilter } from '@grafema/types';
+import type { CallInfo } from '../queries/types.js';
+import { findCallsInFunction } from '../queries/findCallsInFunction.js';
+
+// === Result Types ===
+
+export interface ImportInfo {
+  id: string;
+  source: string;
+  specifiers: string[];
+}
+
+export interface ExportInfo {
+  id: string;
+  name: string;
+  isDefault: boolean;
+}
+
+export interface FunctionOverview {
+  id: string;
+  name: string;
+  line?: number;
+  async: boolean;
+  params?: string[];
+  calls: string[];
+  returnType?: string;
+  signature?: string;
+}
+
+export interface ClassOverview {
+  id: string;
+  name: string;
+  line?: number;
+  extends?: string;
+  exported: boolean;
+  methods: FunctionOverview[];
+}
+
+export interface VariableOverview {
+  id: string;
+  name: string;
+  line?: number;
+  kind: string;
+  assignedFrom?: string;
+}
+
+export interface FileOverviewResult {
+  file: string;
+  status: 'ANALYZED' | 'NOT_ANALYZED';
+  imports: ImportInfo[];
+  exports: ExportInfo[];
+  classes: ClassOverview[];
+  functions: FunctionOverview[];
+  variables: VariableOverview[];
+}
+
+/** Node types we display in the file overview */
+const OVERVIEW_NODE_TYPES = new Set([
+  'FUNCTION',
+  'CLASS',
+  'METHOD',
+  'VARIABLE',
+  'CONSTANT',
+  'IMPORT',
+  'EXPORT',
+]);
+
+export class FileOverview {
+  constructor(private graph: GraphBackend) {}
+
+  /**
+   * Get structured overview of a file's entities and relationships.
+   *
+   * @param filePath - Absolute file path (after realpath resolution)
+   * @param options - Optional: { includeEdges: boolean }
+   * @returns FileOverviewResult
+   */
+  async getOverview(
+    filePath: string,
+    options: { includeEdges?: boolean } = {}
+  ): Promise<FileOverviewResult> {
+    const { includeEdges = true } = options;
+
+    const moduleNode = await this.findModuleNode(filePath);
+    if (!moduleNode) {
+      return {
+        file: filePath,
+        status: 'NOT_ANALYZED',
+        imports: [],
+        exports: [],
+        classes: [],
+        functions: [],
+        variables: [],
+      };
+    }
+
+    const children = await this.getTopLevelEntities(moduleNode.id);
+
+    const imports: ImportInfo[] = [];
+    const exports: ExportInfo[] = [];
+    const classes: ClassOverview[] = [];
+    const functions: FunctionOverview[] = [];
+    const variables: VariableOverview[] = [];
+
+    for (const child of children) {
+      switch (child.type) {
+        case 'IMPORT':
+          imports.push(this.buildImportInfo(child));
+          break;
+        case 'EXPORT':
+          exports.push(this.buildExportInfo(child));
+          break;
+        case 'CLASS':
+          classes.push(await this.buildClassOverview(child, includeEdges));
+          break;
+        case 'FUNCTION':
+        case 'METHOD':
+          functions.push(await this.buildFunctionOverview(child, includeEdges));
+          break;
+        case 'VARIABLE':
+        case 'CONSTANT':
+          variables.push(await this.buildVariableOverview(child, includeEdges));
+          break;
+      }
+    }
+
+    const byLine = (a: { line?: number }, b: { line?: number }) =>
+      (a.line ?? 0) - (b.line ?? 0);
+
+    classes.sort(byLine);
+    functions.sort(byLine);
+    variables.sort(byLine);
+
+    return {
+      file: filePath,
+      status: 'ANALYZED',
+      imports,
+      exports,
+      classes,
+      functions,
+      variables,
+    };
+  }
+
+  /**
+   * Find the MODULE node for the given file path.
+   * Complexity: O(1) - server-side filtered query
+   */
+  private async findModuleNode(
+    filePath: string
+  ): Promise<BaseNodeRecord | null> {
+    const filter: NodeFilter = { file: filePath, type: 'MODULE' };
+    for await (const node of this.graph.queryNodes(filter)) {
+      if (node.file === filePath && node.type === 'MODULE') {
+        return node;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Get direct children of MODULE node that are "interesting" types.
+   * Complexity: O(C) where C = total CONTAINS edges from MODULE
+   */
+  private async getTopLevelEntities(
+    moduleId: string
+  ): Promise<BaseNodeRecord[]> {
+    const containsEdges = await this.graph.getOutgoingEdges(
+      moduleId,
+      ['CONTAINS']
+    );
+
+    const entities: BaseNodeRecord[] = [];
+    for (const edge of containsEdges) {
+      const child = await this.graph.getNode(edge.dst);
+      if (child && OVERVIEW_NODE_TYPES.has(child.type)) {
+        entities.push(child);
+      }
+    }
+    return entities;
+  }
+
+  /**
+   * Build ImportInfo from an IMPORT node.
+   * Data read directly from node record fields.
+   * Complexity: O(1)
+   */
+  private buildImportInfo(node: BaseNodeRecord): ImportInfo {
+    const source = (node.source as string) ?? (node.name || '');
+    const rawSpecifiers = node.specifiers;
+    let specifierNames: string[] = [];
+
+    if (Array.isArray(rawSpecifiers)) {
+      specifierNames = rawSpecifiers.map(
+        (s: { local?: string; imported?: string; type?: string }) =>
+          s.local || s.imported || 'unknown'
+      );
+    }
+
+    return {
+      id: node.id,
+      source,
+      specifiers: specifierNames,
+    };
+  }
+
+  /**
+   * Build ExportInfo from an EXPORT node.
+   * Data read directly from node record fields.
+   * Complexity: O(1)
+   */
+  private buildExportInfo(node: BaseNodeRecord): ExportInfo {
+    return {
+      id: node.id,
+      name: (node.exportedName as string) ?? node.name ?? '<anonymous>',
+      isDefault: (node.isDefault as boolean) ?? false,
+    };
+  }
+
+  /**
+   * Build FunctionOverview from a FUNCTION node.
+   * When includeEdges=true, resolves calls via findCallsInFunction.
+   * Complexity: Without edges O(1), with edges O(S + C)
+   */
+  private async buildFunctionOverview(
+    node: BaseNodeRecord,
+    includeEdges: boolean
+  ): Promise<FunctionOverview> {
+    const overview: FunctionOverview = {
+      id: node.id,
+      name: node.name ?? '<anonymous>',
+      line: node.line as number | undefined,
+      async: (node.async as boolean) ?? false,
+      params: node.params as string[] | undefined,
+      calls: [],
+      returnType: node.returnType as string | undefined,
+      signature: node.signature as string | undefined,
+    };
+
+    if (includeEdges) {
+      const callInfos: CallInfo[] = await findCallsInFunction(
+        this.graph,
+        node.id,
+        { transitive: false }
+      );
+
+      const callNames = new Set<string>();
+      for (const call of callInfos) {
+        if (call.resolved && call.target) {
+          callNames.add(call.target.name);
+        } else {
+          callNames.add(call.name);
+        }
+      }
+
+      // Fallback: when HAS_SCOPE edges are missing (orchestrator doesn't create
+      // FUNCTION → HAS_SCOPE), find CALL nodes by file + line range.
+      if (callNames.size === 0 && node.file && node.line != null) {
+        const endLine = (node.endLine as number | undefined) ?? (node.line as number) + 100000;
+        const nodeLine = node.line as number;
+        const filter: NodeFilter = { file: node.file, type: 'CALL' };
+        for await (const callNode of this.graph.queryNodes(filter)) {
+          const callLine = callNode.line as number | undefined;
+          if (callLine != null && callLine >= nodeLine && callLine <= endLine) {
+            const callsEdges = await this.graph.getOutgoingEdges(callNode.id, ['CALLS']);
+            if (callsEdges.length > 0) {
+              const target = await this.graph.getNode(callsEdges[0].dst);
+              if (target) {
+                callNames.add(target.name ?? callNode.name ?? '<unknown>');
+              }
+            } else {
+              callNames.add(callNode.name ?? '<unknown>');
+            }
+          }
+        }
+      }
+
+      overview.calls = Array.from(callNames);
+    }
+
+    return overview;
+  }
+
+  /**
+   * Build ClassOverview from a CLASS node.
+   * Fetches EXTENDS edge and methods via CONTAINS.
+   * Complexity: Without edges O(M), with edges O(M * (S + C))
+   */
+  private async buildClassOverview(
+    node: BaseNodeRecord,
+    includeEdges: boolean
+  ): Promise<ClassOverview> {
+    const overview: ClassOverview = {
+      id: node.id,
+      name: node.name ?? '<anonymous>',
+      line: node.line as number | undefined,
+      exported: (node.exported as boolean) ?? false,
+      methods: [],
+    };
+
+    // Get superclass
+    if (includeEdges) {
+      const extendsEdges = await this.graph.getOutgoingEdges(
+        node.id,
+        ['EXTENDS']
+      );
+      if (extendsEdges.length > 0) {
+        const superNode = await this.graph.getNode(extendsEdges[0].dst);
+        overview.extends = superNode?.name ?? (node.superClass as string);
+      } else if (node.superClass) {
+        overview.extends = node.superClass as string;
+      }
+    } else if (node.superClass) {
+      overview.extends = node.superClass as string;
+    }
+
+    // Get methods via CONTAINS or HAS_METHOD edges
+    const containsEdges = await this.graph.getOutgoingEdges(
+      node.id,
+      ['CONTAINS', 'HAS_METHOD']
+    );
+
+    for (const edge of containsEdges) {
+      const child = await this.graph.getNode(edge.dst);
+      if (!child) continue;
+
+      if (child.type === 'FUNCTION' || child.type === 'METHOD') {
+        const methodOverview = await this.buildFunctionOverview(
+          child,
+          includeEdges
+        );
+        overview.methods.push(methodOverview);
+      }
+    }
+
+    overview.methods.sort((a, b) => (a.line ?? 0) - (b.line ?? 0));
+
+    return overview;
+  }
+
+  /**
+   * Build VariableOverview from a VARIABLE or CONSTANT node.
+   * Complexity: Without edges O(1), with edges O(1)
+   */
+  private async buildVariableOverview(
+    node: BaseNodeRecord,
+    includeEdges: boolean
+  ): Promise<VariableOverview> {
+    const overview: VariableOverview = {
+      id: node.id,
+      name: node.name ?? '<anonymous>',
+      line: node.line as number | undefined,
+      kind: (node.kind as string) ?? 'const',
+    };
+
+    if (includeEdges) {
+      const assignedEdges = await this.graph.getOutgoingEdges(
+        node.id,
+        ['ASSIGNED_FROM']
+      );
+      if (assignedEdges.length > 0) {
+        const sourceNode = await this.graph.getNode(assignedEdges[0].dst);
+        if (sourceNode) {
+          overview.assignedFrom = sourceNode.name ?? sourceNode.type;
+        }
+      }
+    }
+
+    return overview;
+  }
+}

package/src/core/GrafemaUri.ts

@@ -0,0 +1,216 @@
+/**
+ * GrafemaUri -- conversion between compact semantic IDs and grafema:// URIs.
+ *
+ * URI format: grafema://{authority}/{file}#{encoded_fragment}
+ * Virtual nodes: grafema://{authority}/_/{encoded_full_id}
+ * Module nodes: grafema://{authority}/{file}#MODULE
+ *
+ * Fragment encoding: only > [ ] # need percent-encoding.
+ */
+
+const GRAFEMA_SCHEME = 'grafema://';
+
+/**
+ * Check if a string is a grafema:// URI.
+ */
+export function isGrafemaUri(str: string): boolean {
+  return str.startsWith(GRAFEMA_SCHEME);
+}
+
+/**
+ * Encode a fragment string for grafema:// URIs.
+ * Only 4 chars need percent-encoding: > [ ] #
+ */
+export function encodeFragment(raw: string): string {
+  let out = '';
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i];
+    switch (ch) {
+      case '>': out += '%3E'; break;
+      case '[': out += '%5B'; break;
+      case ']': out += '%5D'; break;
+      case '#': out += '%23'; break;
+      default: out += ch;
+    }
+  }
+  return out;
+}
+
+/**
+ * Decode a percent-encoded fragment back to raw string.
+ */
+export function decodeFragment(encoded: string): string {
+  return encoded
+    .replaceAll('%3E', '>')
+    .replaceAll('%3e', '>')
+    .replaceAll('%5B', '[')
+    .replaceAll('%5b', '[')
+    .replaceAll('%5D', ']')
+    .replaceAll('%5d', ']')
+    .replaceAll('%23', '#');
+}
+
+/**
+ * Convert a compact semantic ID to a grafema:// URI.
+ *
+ * @param compactId - Compact format: "file->TYPE->name[in:p,h:x]#N", "MODULE#file", "EXTERNAL_MODULE->x"
+ * @param authority - URI authority: "github.com/owner/repo" or "localhost/project"
+ * @returns grafema:// URI string
+ */
+export function toGrafemaUri(compactId: string, authority: string): string {
+  // Case 1: MODULE#file
+  if (compactId.startsWith('MODULE#')) {
+    const file = compactId.slice(7); // len("MODULE#") = 7
+    return `${GRAFEMA_SCHEME}${authority}/${file}#MODULE`;
+  }
+
+  // Case 2 & 3: Check for file->REST pattern
+  const firstArrow = compactId.indexOf('->');
+  if (firstArrow !== -1) {
+    const beforeArrow = compactId.slice(0, firstArrow);
+
+    // Heuristic: file paths contain '/' or '.'
+    const isFilePath = beforeArrow.includes('/') || beforeArrow.includes('.');
+
+    if (isFilePath) {
+      // Standard node: file->REST
+      const file = beforeArrow;
+      const rest = compactId.slice(firstArrow + 2);
+      return `${GRAFEMA_SCHEME}${authority}/${file}#${encodeFragment(rest)}`;
+    } else {
+      // Virtual node: encode the whole ID
+      return `${GRAFEMA_SCHEME}${authority}/_/${encodeFragment(compactId)}`;
+    }
+  }
+
+  // No arrow -- virtual node
+  return `${GRAFEMA_SCHEME}${authority}/_/${encodeFragment(compactId)}`;
+}
+
+/**
+ * Parsed grafema:// URI components.
+ */
+export interface ParsedGrafemaUri {
+  /** URI authority, e.g. "github.com/owner/repo" */
+  authority: string;
+  /** File path within the project, or empty for virtual nodes */
+  filePath: string;
+  /** Decoded symbol part (the fragment, decoded) */
+  symbolPart: string;
+  /** Reconstructed compact semantic ID */
+  semanticId: string;
+  /** Whether this is a virtual node (uses _/ path) */
+  isVirtual: boolean;
+}
+
+/**
+ * Parse a grafema:// URI into components.
+ *
+ * @returns Parsed components or null if not a valid grafema:// URI
+ */
+export function parseGrafemaUri(uri: string): ParsedGrafemaUri | null {
+  if (!uri.startsWith(GRAFEMA_SCHEME)) return null;
+
+  const rest = uri.slice(GRAFEMA_SCHEME.length); // "authority/file#fragment"
+
+  // Find the authority: everything up to the first '/' after the host
+  // Authority format: "host/project" (e.g., "github.com/owner/repo" or "localhost/project")
+  // We need to find where authority ends and file path begins.
+  // Convention: authority is "host/path" where host has no '/', so we split on first '/' after host.
+  // Actually, authority can be multi-segment (github.com/owner/repo = 3 segments).
+  // Strategy: find '#' first (fragment delimiter), then split the path part.
+
+  const hashPos = rest.indexOf('#');
+  const slashUnderscoreSlash = rest.indexOf('/_/');
+
+  if (slashUnderscoreSlash !== -1 && (hashPos === -1 || slashUnderscoreSlash < hashPos)) {
+    // Virtual node: authority/_/encoded_id
+    const authority = rest.slice(0, slashUnderscoreSlash);
+    const encodedId = rest.slice(slashUnderscoreSlash + 3); // after "/_/"
+    const decodedId = decodeFragment(encodedId);
+
+    // Reconstruct compact ID -- it's just the decoded full ID
+    return {
+      authority,
+      filePath: '',
+      symbolPart: decodedId,
+      semanticId: decodedId,
+      isVirtual: true,
+    };
+  }
+
+  if (hashPos === -1) return null; // No fragment = invalid
+
+  const pathPart = rest.slice(0, hashPos); // "authority/file/path"
+  const fragment = rest.slice(hashPos + 1); // "TYPE-%3Ename..."
+  const decodedFragment = decodeFragment(fragment);
+
+  // Split pathPart into authority and filePath.
+  // The authority is the first N segments that represent the host+project.
+  // Problem: we don't know where authority ends and file begins.
+  // Convention from the plan: authority = "host/project" (e.g., "localhost/grafema")
+  //   or "github.com/owner/repo" (3 segments).
+  // The file path typically starts with src/, lib/, etc.
+  //
+  // Better approach: find the file path by working backward from the fragment.
+  // The fragment's decoded form tells us the type. The module_id for MODULE# format
+  // means filePath = pathPart minus authority.
+  //
+  // Simplest reliable approach: the authority is stored separately or we use a heuristic.
+  // For now: authority = first 2 segments for "host/project" format,
+  // first 3 segments for known hosts (github.com, gitlab.com, bitbucket.org).
+
+  const segments = pathPart.split('/');
+  let authoritySegments: number;
+
+  const host = segments[0];
+  if (host === 'github.com' || host === 'gitlab.com' || host === 'bitbucket.org') {
+    authoritySegments = 3; // host/owner/repo
+  } else {
+    authoritySegments = 2; // host/project (localhost/grafema)
+  }
+
+  if (segments.length < authoritySegments) return null;
+
+  const authority = segments.slice(0, authoritySegments).join('/');
+  const filePath = segments.slice(authoritySegments).join('/');
+
+  // Reconstruct compact semantic ID
+  let semanticId: string;
+  if (decodedFragment === 'MODULE') {
+    semanticId = `MODULE#${filePath}`;
+  } else {
+    semanticId = `${filePath}->${decodedFragment}`;
+  }
+
+  return {
+    authority,
+    filePath,
+    symbolPart: decodedFragment,
+    semanticId,
+    isVirtual: false,
+  };
+}
+
+/**
+ * Convert a grafema:// URI to compact semantic ID format.
+ * Convenience wrapper around parseGrafemaUri.
+ *
+ * @returns Compact semantic ID or the input unchanged if not a grafema:// URI
+ */
+export function toCompactSemanticId(uri: string): string {
+  if (!isGrafemaUri(uri)) return uri;
+  const parsed = parseGrafemaUri(uri);
+  if (!parsed) return uri;
+  return parsed.semanticId;
+}
+
+/**
+ * Normalize a semantic ID input -- accepts either URI or compact format.
+ * If it's a URI, converts to compact. If already compact, returns as-is.
+ *
+ * Useful in MCP handlers that need to accept both formats.
+ */
+export function normalizeSemanticId(input: string): string {
+  return toCompactSemanticId(input);
+}