@grafema/core 0.2.5-beta → 0.2.7

package/src/config/ConfigLoader.ts

@@ -1,7 +1,8 @@
 import { readFileSync, existsSync, statSync } from 'fs';
 import { join, basename } from 'path';
 import { parse as parseYAML } from 'yaml';
-import type { ServiceDefinition } from '@grafema/types';
+import type { ServiceDefinition, RoutingRule } from '@grafema/types';
+import { GRAFEMA_VERSION, getSchemaVersion } from '../version.js';
 
 /**
  * Grafema configuration schema.
@@ -36,6 +37,15 @@ import type { ServiceDefinition } from '@grafema/types';
  * If 'services' is specified and non-empty, auto-discovery plugins are skipped entirely.
  */
 export interface GrafemaConfig {
+  /**
+   * Config schema version (major.minor.patch, no pre-release tag).
+   * Must be compatible with the running Grafema version.
+   * If omitted, no version check is performed (backward compatibility).
+   *
+   * @example "0.2.5"
+   */
+  version?: string;
+
   plugins: {
     discovery?: string[];
     indexing: string[];
@@ -61,6 +71,23 @@ export interface GrafemaConfig {
    */
   exclude?: string[];
 
+  /**
+   * Routing rules for cross-service URL mapping (REG-256).
+   * Describes how infrastructure (nginx, gateway) transforms URLs between services.
+   *
+   * @example
+   * ```yaml
+   * routing:
+   *   - from: frontend
+   *     to: backend
+   *     stripPrefix: /api
+   *   - from: frontend
+   *     to: auth-service
+   *     stripPrefix: /auth
+   * ```
+   */
+  routing?: RoutingRule[];
+
   /**
    * Enable strict mode for fail-fast debugging.
    * When true, analysis fails if enrichers cannot resolve references.
@@ -106,6 +133,7 @@ export interface WorkspaceConfig {
  * Matches current DEFAULT_PLUGINS in analyze.ts and config.ts (MCP).
  */
 export const DEFAULT_CONFIG: GrafemaConfig = {
+  version: getSchemaVersion(GRAFEMA_VERSION),
   plugins: {
     discovery: [],
     indexing: ['JSModuleIndexer'],
@@ -113,6 +141,7 @@ export const DEFAULT_CONFIG: GrafemaConfig = {
       'JSASTAnalyzer',
       'ExpressRouteAnalyzer',
       'ExpressResponseAnalyzer',
+      'NestJSRouteAnalyzer',
       'SocketIOAnalyzer',
       'DatabaseAnalyzer',
       'FetchAnalyzer',
@@ -129,7 +158,9 @@ export const DEFAULT_CONFIG: GrafemaConfig = {
       'ExpressHandlerLinker',
       'PrefixEvaluator',
       'ImportExportLinker',
-      'HTTPConnectionEnricher',
+      'ConfigRoutingMapBuilder',
+      'ServiceConnectionEnricher',
+      'CallbackCallResolver',
     ],
     validation: [
       'GraphConnectivityValidator',
@@ -137,9 +168,12 @@ export const DEFAULT_CONFIG: GrafemaConfig = {
       'EvalBanValidator',
       'CallResolverValidator',
       'SQLInjectionValidator',
+      'AwaitInLoopValidator',
       'ShadowingDetector',
       'TypeScriptDeadCodeValidator',
       'BrokenImportValidator',
+      'UnconnectedRouteValidator',
+      'PackageCoverageValidator',
     ],
   },
   services: [], // Empty by default (uses auto-discovery)
@@ -194,6 +228,9 @@ export function loadConfig(
       return DEFAULT_CONFIG;
     }
 
+    // Validate version compatibility (THROWS on error) - REG-403
+    validateVersion(parsed.version);
+
     // Validate services array if present (THROWS on error per Linus review)
     // This is OUTSIDE try-catch - config errors MUST throw
     validateServices(parsed.services, projectPath);
@@ -204,6 +241,9 @@ export function loadConfig(
     // Validate workspace.roots if present (THROWS on error) - REG-76
     validateWorkspace(parsed.workspace, projectPath);
 
+    // Validate routing rules if present (THROWS on error) - REG-256
+    validateRouting(parsed.routing, (parsed.services || []) as ServiceDefinition[]);
+
     // Merge with defaults (user config may be partial)
     return mergeConfig(DEFAULT_CONFIG, parsed);
   }
@@ -224,6 +264,9 @@ export function loadConfig(
       return DEFAULT_CONFIG;
     }
 
+    // Validate version compatibility (THROWS on error) - REG-403
+    validateVersion(parsed.version);
+
     // Validate services array if present (THROWS on error)
     // This is OUTSIDE try-catch - config errors MUST throw
     validateServices(parsed.services, projectPath);
@@ -234,6 +277,9 @@ export function loadConfig(
     // Validate workspace.roots if present (THROWS on error) - REG-76
     validateWorkspace(parsed.workspace, projectPath);
 
+    // Validate routing rules if present (THROWS on error) - REG-256
+    validateRouting(parsed.routing, (parsed.services || []) as ServiceDefinition[]);
+
     return mergeConfig(DEFAULT_CONFIG, parsed);
   }
 
@@ -241,6 +287,46 @@ export function loadConfig(
   return DEFAULT_CONFIG;
 }
 
+/**
+ * Validate config version compatibility with running Grafema version.
+ * THROWS on error (fail loudly per project convention).
+ *
+ * Compares major.minor.patch (pre-release tags are stripped).
+ * If config has no version field, validation passes silently (backward compat).
+ *
+ * @param configVersion - Version string from config file (may be undefined)
+ * @param currentVersion - Override for testing (defaults to GRAFEMA_VERSION)
+ */
+export function validateVersion(
+  configVersion: unknown,
+  currentVersion?: string
+): void {
+  // No version field = backward compat, accept silently
+  if (configVersion === undefined || configVersion === null) {
+    return;
+  }
+
+  if (typeof configVersion !== 'string') {
+    throw new Error(`Config error: version must be a string, got ${typeof configVersion}`);
+  }
+
+  if (!configVersion.trim()) {
+    throw new Error('Config error: version cannot be empty');
+  }
+
+  const current = currentVersion ?? GRAFEMA_VERSION;
+  const configSchema = getSchemaVersion(configVersion);
+  const currentSchema = getSchemaVersion(current);
+
+  if (configSchema !== currentSchema) {
+    throw new Error(
+      `Config error: config version "${configVersion}" is not compatible with ` +
+      `Grafema ${current}. Expected "${currentSchema}".\n` +
+      `  Run: grafema init --force  (to regenerate config for current version)`
+    );
+  }
+}
+
 /**
  * Validate services array structure.
  * THROWS on error (fail loudly per Linus review).
@@ -309,6 +395,13 @@ export function validateServices(services: unknown, projectPath: string): void {
         throw new Error(`Config error: services[${i}].entryPoint cannot be empty or whitespace-only`);
       }
     }
+
+    // customerFacing validation (optional field) - must be boolean if provided (REG-256)
+    if (svc.customerFacing !== undefined) {
+      if (typeof svc.customerFacing !== 'boolean') {
+        throw new Error(`Config error: services[${i}].customerFacing must be a boolean, got ${typeof svc.customerFacing}`);
+      }
+    }
   }
 }
 
@@ -390,6 +483,84 @@ export function validateWorkspace(workspace: unknown, projectPath: string): void
   }
 }
 
+/**
+ * Validate routing rules structure (REG-256).
+ * THROWS on error (fail loudly per project convention).
+ *
+ * Validation rules:
+ * 1. Must be an array if provided
+ * 2. Each rule must have 'from' and 'to' as non-empty strings
+ * 3. 'stripPrefix' must start with '/' if provided
+ * 4. 'addPrefix' must start with '/' if provided
+ * 5. 'from' and 'to' must reference services defined in the services array
+ *
+ * @param routing - Parsed routing rules (may be undefined)
+ * @param services - Parsed services array (for cross-validation)
+ */
+export function validateRouting(routing: unknown, services: ServiceDefinition[]): void {
+  if (routing === undefined || routing === null) return;
+
+  if (!Array.isArray(routing)) {
+    throw new Error(`Config error: routing must be an array, got ${typeof routing}`);
+  }
+
+  const serviceNames = new Set(services.map(s => s.name));
+
+  for (let i = 0; i < routing.length; i++) {
+    const rule = routing[i];
+
+    if (typeof rule !== 'object' || rule === null) {
+      throw new Error(`Config error: routing[${i}] must be an object`);
+    }
+
+    // from — required
+    if (typeof rule.from !== 'string' || !rule.from.trim()) {
+      throw new Error(`Config error: routing[${i}].from must be a non-empty string`);
+    }
+
+    // to — required
+    if (typeof rule.to !== 'string' || !rule.to.trim()) {
+      throw new Error(`Config error: routing[${i}].to must be a non-empty string`);
+    }
+
+    // Cross-validate against services (only if services are defined)
+    if (serviceNames.size > 0) {
+      if (!serviceNames.has(rule.from)) {
+        throw new Error(
+          `Config error: routing[${i}].from "${rule.from}" does not match any service name. ` +
+          `Available: ${[...serviceNames].join(', ')}`
+        );
+      }
+      if (!serviceNames.has(rule.to)) {
+        throw new Error(
+          `Config error: routing[${i}].to "${rule.to}" does not match any service name. ` +
+          `Available: ${[...serviceNames].join(', ')}`
+        );
+      }
+    }
+
+    // stripPrefix — optional, must start with /
+    if (rule.stripPrefix !== undefined) {
+      if (typeof rule.stripPrefix !== 'string') {
+        throw new Error(`Config error: routing[${i}].stripPrefix must be a string`);
+      }
+      if (!rule.stripPrefix.startsWith('/')) {
+        throw new Error(`Config error: routing[${i}].stripPrefix must start with '/'`);
+      }
+    }
+
+    // addPrefix — optional, must start with /
+    if (rule.addPrefix !== undefined) {
+      if (typeof rule.addPrefix !== 'string') {
+        throw new Error(`Config error: routing[${i}].addPrefix must be a string`);
+      }
+      if (!rule.addPrefix.startsWith('/')) {
+        throw new Error(`Config error: routing[${i}].addPrefix must start with '/'`);
+      }
+    }
+  }
+}
+
 /**
  * Validate include/exclude patterns.
  * THROWS on error (fail loudly per project convention).
@@ -452,6 +623,7 @@ function mergeConfig(
   user: Partial<GrafemaConfig>
 ): GrafemaConfig {
   return {
+    version: user.version ?? defaults.version,
     plugins: {
       discovery: user.plugins?.discovery ?? defaults.plugins.discovery,
       indexing: user.plugins?.indexing ?? defaults.plugins.indexing,
@@ -466,6 +638,8 @@ function mergeConfig(
     include: user.include ?? undefined,
     exclude: user.exclude ?? undefined,
     strict: user.strict ?? defaults.strict,
+    // Routing rules: pass through if specified (REG-256)
+    routing: user.routing ?? undefined,
     // Workspace config: pass through if specified (REG-76)
     workspace: user.workspace ?? undefined,
   };

package/src/config/index.ts

@@ -4,8 +4,10 @@
 export {
   loadConfig,
   DEFAULT_CONFIG,
+  validateVersion,
   validateServices,
   validatePatterns,
   validateWorkspace,
+  validateRouting,
 } from './ConfigLoader.js';
 export type { GrafemaConfig } from './ConfigLoader.js';

package/src/core/ASTWorker.ts

@@ -125,6 +125,8 @@ interface CallSiteNode {
   targetFunctionName?: string;
   object?: string;
   method?: string;
+  /** REG-297: true if wrapped in await expression */
+  isAwaited?: boolean;
 }
 
 /**
@@ -486,6 +488,9 @@ function parseModule(filePath: string, moduleId: string, moduleName: string): AS
       const node = path.node;
       const nodeKey = `${node.start}:${node.end}`;
 
+      // REG-297: Detect isAwaited for module-level calls
+      const isAwaited = path.parentPath?.isAwaitExpression() ?? false;
+
       if (node.callee.type === 'Identifier') {
         if (processed.callSites.has(nodeKey)) return;
         processed.callSites.add(nodeKey);
@@ -502,7 +507,8 @@ function parseModule(filePath: string, moduleId: string, moduleName: string): AS
           file: filePath,
           line: getLine(node),
           parentScopeId: moduleId,
-          targetFunctionName: calleeName
+          targetFunctionName: calleeName,
+          isAwaited: isAwaited || undefined
         });
       } else if (node.callee.type === 'MemberExpression') {
         const obj = node.callee.object;
@@ -528,7 +534,8 @@ function parseModule(filePath: string, moduleId: string, moduleName: string): AS
             method: methodName,
             file: filePath,
             line: getLine(node),
-            parentScopeId: moduleId
+            parentScopeId: moduleId,
+            isAwaited: isAwaited || undefined
           });
         }
       }

package/src/core/FileOverview.ts

@@ -0,0 +1,374 @@
+/**
+ * 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);
+        }
+      }
+      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 edges
+    const containsEdges = await this.graph.getOutgoingEdges(
+      node.id,
+      ['CONTAINS']
+    );
+
+    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;
+  }
+}