@grafema/core 0.2.3-beta → 0.2.5-beta

package/src/instructions/onboarding.md

@@ -0,0 +1,121 @@
+# Grafema Project Onboarding
+
+## Goal
+Study the target project and create a `.grafema/config.yaml` that correctly
+describes its services, entry points, and analysis configuration.
+
+## Prerequisites
+- The project directory exists and contains source code
+- `.grafema/` directory exists (run `grafema init` if not)
+
+## Step 1: Initial Reconnaissance
+
+Use `read_project_structure` to get the directory tree.
+
+Look for:
+- `package.json` in root and subdirectories (indicates JS/TS packages)
+- `pnpm-workspace.yaml`, `lerna.json`, root `package.json` with `workspaces`
+  field (workspace/monorepo indicators)
+- `tsconfig.json` files (TypeScript project)
+- `Dockerfile`, `docker-compose.yml`, `k8s/`, `apps.json` (deployment configs
+  that may reveal service boundaries)
+- Directories named `apps/`, `packages/`, `services/`, `pkg/`, `modules/`
+  (common monorepo structures)
+
+## Step 2: Identify Services
+
+A "service" in Grafema is an independently analyzable unit of code with its
+own entry point. Typically:
+- A standalone application (API server, web app, CLI tool)
+- A package in a monorepo that other packages depend on
+- A microservice in a deployment configuration
+
+For each potential service, determine:
+1. **Name** — human-readable identifier (e.g., "backend", "dashboard")
+2. **Path** — directory path relative to project root
+3. **Entry point** — the main source file (prefer TypeScript source over
+   compiled output)
+
+### How to find entry points
+Check in order:
+1. `package.json` "source" field (TypeScript source entry)
+2. `package.json` "main" field, but look for `.ts` equivalent in `src/`
+3. Common patterns: `src/index.ts`, `src/main.ts`, `src/app.ts`,
+   `src/server.ts`, `index.ts`
+4. For React apps: `src/App.tsx`, `src/index.tsx`
+5. Check `bin` field in package.json for CLI tools
+
+### When to ask the user
+- "I found [X] that looks like [description]. Should I include it as a
+  service?"
+- "This directory has multiple potential entry points: [list].
+  Which should I use?"
+- "I found deployment configuration mentioning services not visible in
+  the code structure. Should I investigate?"
+
+## Step 3: Run Auto-Discovery (Optional)
+
+Use `discover_services` to see what Grafema's built-in detection finds.
+Compare with your own findings from Steps 1-2. Note discrepancies —
+auto-discovery may miss services or misidentify entry points.
+
+## Step 4: Configure Plugins
+
+Default plugins work for most JS/TS projects. Adjust if:
+- Project uses specific frameworks (Express, React, Socket.IO) — ensure
+  corresponding analyzers are enabled
+- Project has Rust components — add `RustModuleIndexer` and `RustAnalyzer`
+- Project has unusual file patterns — configure `include`/`exclude`
+
+Default plugin list (reference only — omit from config to use defaults):
+  indexing: [JSModuleIndexer]
+  analysis: [JSASTAnalyzer, ExpressRouteAnalyzer, ExpressResponseAnalyzer,
+    SocketIOAnalyzer, DatabaseAnalyzer, FetchAnalyzer, ServiceLayerAnalyzer]
+  enrichment: [MethodCallResolver, ArgumentParameterLinker, AliasTracker,
+    ClosureCaptureEnricher, RejectionPropagationEnricher, ValueDomainAnalyzer,
+    MountPointResolver, ExpressHandlerLinker, PrefixEvaluator,
+    ImportExportLinker, HTTPConnectionEnricher]
+  validation: [GraphConnectivityValidator, DataFlowValidator, EvalBanValidator,
+    CallResolverValidator, SQLInjectionValidator, ShadowingDetector,
+    TypeScriptDeadCodeValidator, BrokenImportValidator]
+
+## Step 5: Write Configuration
+
+Use `write_config` to save the discovered configuration.
+
+The config should include:
+- `services` array with all confirmed services (name, path, optional entryPoint)
+- `plugins` section (only if overriding defaults)
+- `include`/`exclude` patterns (only if needed)
+- `workspace.roots` (for multi-root workspaces only)
+
+## Step 6: Verify
+
+Run `analyze_project` to build the graph. Then check:
+- `get_stats` — are node/edge counts reasonable for the project size?
+- `get_coverage` — are the expected files analyzed?
+
+If coverage is low or results are unexpected, iterate:
+revisit services, entry points, or include/exclude patterns.
+
+## Common Patterns
+
+### Monorepo with workspaces
+Look for `pnpm-workspace.yaml` or `workspaces` in root `package.json`.
+Each workspace package is typically a service. Use `read_project_structure`
+with depth=2 to see the package layout.
+
+### Legacy project with multiple entry points
+Look for `scripts` in `package.json`, `bin` field, or multiple files
+in `src/` that look like entry points (contain `app.listen()`,
+`createServer()`, `express()`).
+
+### Microservices with shared deployment
+Look for `docker-compose.yml`, Kubernetes configs, or similar
+deployment manifests that list services. Cross-reference with
+code directories.
+
+### Single-package project
+If there is only one `package.json` at the root and no monorepo
+structure, the project is likely a single service. The service path
+is `.` (root), and the entry point is determined from `package.json`.

package/src/logging/Logger.ts

@@ -4,14 +4,20 @@
  * Features:
  * - 5 log levels: silent, errors, warnings, info, debug
  * - Context support for structured logging
- * - No external dependencies
+ * - Console and file output (or both via MultiLogger)
  * - Safe handling of circular references
  *
  * Usage:
  *   const logger = createLogger('info');
  *   logger.info('Processing files', { count: 150 });
+ *
+ *   // Write logs to file (REG-199):
+ *   const logger = createLogger('info', { logFile: '.grafema/analysis.log' });
  */
 
+import { createWriteStream, writeFileSync, mkdirSync, accessSync, statSync, constants, type WriteStream } from 'fs';
+import { dirname, resolve } from 'path';
+
 /**
  * Log level type
  */
@@ -145,8 +151,153 @@ export class ConsoleLogger implements Logger {
 }
 
 /**
- * Create a Logger instance with the specified log level
+ * File-based Logger implementation (REG-199)
+ *
+ * Writes log messages to a file with ISO timestamps using a write stream
+ * (non-blocking I/O). File is truncated on construction (overwritten each run).
+ * Parent directories are created automatically.
+ *
+ * Validates path on construction — throws if the directory is not writable
+ * or the path points to a directory.
+ */
+export class FileLogger implements Logger {
+  private readonly priority: number;
+  private readonly stream: WriteStream;
+
+  constructor(logLevel: LogLevel, filePath: string) {
+    this.priority = LOG_LEVEL_PRIORITY[logLevel];
+    const resolvedPath = resolve(filePath);
+
+    // Create parent directories
+    const dir = dirname(resolvedPath);
+    mkdirSync(dir, { recursive: true });
+
+    // Validate: parent directory must be writable
+    try {
+      accessSync(dir, constants.W_OK);
+    } catch {
+      throw new Error(`Cannot write log file: directory '${dir}' is not writable`);
+    }
+
+    // Validate: path must not point to an existing directory
+    try {
+      if (statSync(resolvedPath).isDirectory()) {
+        throw new Error(`Cannot write log file: '${resolvedPath}' is a directory`);
+      }
+    } catch (e) {
+      // If stat throws, file doesn't exist yet — that's fine
+      if (e instanceof Error && e.message.includes('is a directory')) throw e;
+    }
+
+    // Truncate/create file synchronously (validates writeability),
+    // then open stream in append mode for non-blocking writes
+    writeFileSync(resolvedPath, '');
+    this.stream = createWriteStream(resolvedPath, { flags: 'a' });
+    this.stream.on('error', () => {
+      // Silently ignore stream errors — don't crash analysis for logging failures
+    });
+  }
+
+  private shouldLog(methodLevel: number): boolean {
+    return this.priority >= methodLevel;
+  }
+
+  private writeLine(level: string, message: string, context?: Record<string, unknown>): void {
+    const timestamp = new Date().toISOString();
+    const formatted = formatMessage(`${timestamp} [${level}] ${message}`, context);
+    this.stream.write(formatted + '\n');
+  }
+
+  error(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.error)) return;
+    this.writeLine('ERROR', message, context);
+  }
+
+  warn(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.warn)) return;
+    this.writeLine('WARN', message, context);
+  }
+
+  info(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.info)) return;
+    this.writeLine('INFO', message, context);
+  }
+
+  debug(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.debug)) return;
+    this.writeLine('DEBUG', message, context);
+  }
+
+  trace(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.trace)) return;
+    this.writeLine('TRACE', message, context);
+  }
+
+  /** Flush and close the write stream. Returns when all data is written. */
+  close(): Promise<void> {
+    return new Promise((resolve) => {
+      this.stream.end(resolve);
+    });
+  }
+}
+
+/**
+ * Multi-output Logger that delegates to multiple Logger instances.
+ *
+ * Each inner logger applies its own level filtering independently.
+ * Used to write to both console and file simultaneously.
+ */
+export class MultiLogger implements Logger {
+  private readonly loggers: Logger[];
+
+  constructor(loggers: Logger[]) {
+    this.loggers = loggers;
+  }
+
+  error(message: string, context?: Record<string, unknown>): void {
+    for (const logger of this.loggers) logger.error(message, context);
+  }
+
+  warn(message: string, context?: Record<string, unknown>): void {
+    for (const logger of this.loggers) logger.warn(message, context);
+  }
+
+  info(message: string, context?: Record<string, unknown>): void {
+    for (const logger of this.loggers) logger.info(message, context);
+  }
+
+  debug(message: string, context?: Record<string, unknown>): void {
+    for (const logger of this.loggers) logger.debug(message, context);
+  }
+
+  trace(message: string, context?: Record<string, unknown>): void {
+    for (const logger of this.loggers) logger.trace(message, context);
+  }
+
+  /** Close all inner loggers that have a close() method (e.g., FileLogger). */
+  async close(): Promise<void> {
+    for (const logger of this.loggers) {
+      if (logger instanceof FileLogger) {
+        await logger.close();
+      }
+    }
+  }
+}
+
+/**
+ * Create a Logger instance with the specified log level.
+ *
+ * When logFile is specified, returns a MultiLogger that writes to both
+ * console and file. The file logger always captures at 'debug' level
+ * for complete post-mortem debugging, regardless of the console level.
  */
-export function createLogger(level: LogLevel): Logger {
-  return new ConsoleLogger(level);
+export function createLogger(level: LogLevel, options?: { logFile?: string }): Logger {
+  const consoleLogger = new ConsoleLogger(level);
+
+  if (options?.logFile) {
+    const fileLogger = new FileLogger('debug', options.logFile);
+    return new MultiLogger([consoleLogger, fileLogger]);
+  }
+
+  return consoleLogger;
 }

package/src/plugins/analysis/DatabaseAnalyzer.ts

@@ -4,7 +4,8 @@
  */
 
 import { readFileSync } from 'fs';
-import { parse, ParserPlugin } from '@babel/parser';
+import type { ParserPlugin } from '@babel/parser';
+import { parse } from '@babel/parser';
 import traverseModule from '@babel/traverse';
 import type { CallExpression, Identifier } from '@babel/types';
 import type { NodePath } from '@babel/traverse';
@@ -12,9 +13,9 @@ import { Plugin, createSuccessResult, createErrorResult } from '../Plugin.js';
 import type { PluginContext, PluginResult, PluginMetadata } from '../Plugin.js';
 import type { NodeRecord } from '@grafema/types';
 import { getLine, getColumn } from './ast/utils/location.js';
+import { getTraverseFunction } from './ast/utils/babelTraverse.js';
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const traverse = (traverseModule as any).default || traverseModule;
+const traverse = getTraverseFunction(traverseModule);
 
 /**
  * Database query node
@@ -47,7 +48,6 @@ export class DatabaseAnalyzer extends Plugin {
     return {
       name: 'DatabaseAnalyzer',
       phase: 'ANALYSIS',
-      priority: 75, // После JSASTAnalyzer (80)
       creates: {
         nodes: ['db:query', 'db:table', 'db:connection'],
         edges: ['MAKES_QUERY', 'TARGETS', 'READS_FROM', 'WRITES_TO']
@@ -109,7 +109,8 @@ export class DatabaseAnalyzer extends Plugin {
       );
     } catch (error) {
       logger.error('Analysis failed', { error });
-      return createErrorResult(error as Error);
+      const err = error instanceof Error ? error : new Error(String(error));
+      return createErrorResult(err);
     }
   }
 
@@ -234,30 +235,32 @@ export class DatabaseAnalyzer extends Plugin {
         }
       });
 
-      // Создаём EXTERNAL_DATABASE ноду если есть хотя бы один query
+      // Collect all nodes and edges for batch operations
       if (databaseQueries.length > 0) {
         const databaseId = 'EXTERNAL_DATABASE:__database__';
+        const nodes: NodeRecord[] = [];
+        const edges: Array<{ type: string; src: string; dst: string }> = [];
 
         const existingDb = await graph.getNode(databaseId);
         if (!existingDb) {
-          await graph.addNode({
+          nodes.push({
             id: databaseId,
             type: 'db:connection',
             name: '__database__'
           } as NodeRecord);
         }
 
-        // Создаём DATABASE_QUERY ноды
+        // Prepare DATABASE_QUERY and TABLE nodes
         for (const query of databaseQueries) {
-          await graph.addNode(query as unknown as NodeRecord);
+          nodes.push(query as unknown as NodeRecord);
           queriesCreated++;
 
-          // Создаём TABLE ноду если есть tableName
+          // Prepare TABLE node if has tableName
           if (query.tableName) {
             const tableId = `TABLE:${query.tableName}`;
 
             if (!createdTables.has(tableId)) {
-              await graph.addNode({
+              nodes.push({
                 id: tableId,
                 type: 'db:table',
                 name: query.tableName
@@ -267,7 +270,7 @@ export class DatabaseAnalyzer extends Plugin {
             }
 
             // DATABASE_QUERY -> TARGETS -> TABLE
-            await graph.addEdge({
+            edges.push({
               type: 'TARGETS',
               src: query.id,
               dst: tableId
@@ -279,7 +282,7 @@ export class DatabaseAnalyzer extends Plugin {
           const isReadOperation = query.operation === 'SELECT';
           const edgeType = isReadOperation ? 'READS_FROM' : 'WRITES_TO';
 
-          await graph.addEdge({
+          edges.push({
             type: edgeType,
             src: query.id,
             dst: databaseId
@@ -290,7 +293,7 @@ export class DatabaseAnalyzer extends Plugin {
           const parentFunction = this.findParentFunction(query, functions);
 
           if (parentFunction) {
-            await graph.addEdge({
+            edges.push({
               type: 'MAKES_QUERY',
               src: parentFunction.id,
               dst: query.id
@@ -298,8 +301,12 @@ export class DatabaseAnalyzer extends Plugin {
             edgesCreated++;
           }
         }
+
+        // Flush all nodes and edges
+        await graph.addNodes(nodes);
+        await graph.addEdges(edges);
       }
-    } catch (error) {
+    } catch {
       // Silent - per-module errors shouldn't spam logs
     }
 

package/src/plugins/analysis/ExpressAnalyzer.ts

@@ -4,19 +4,20 @@
  */
 
 import { readFileSync } from 'fs';
-import { parse, ParserPlugin } from '@babel/parser';
+import type { ParserPlugin } from '@babel/parser';
+import { parse } from '@babel/parser';
 import traverseModule from '@babel/traverse';
 import { dirname, resolve, relative } from 'path';
-import type { CallExpression, ImportDeclaration, StringLiteral, TemplateLiteral, Identifier, MemberExpression } from '@babel/types';
+import type { CallExpression, ImportDeclaration, Identifier, MemberExpression } from '@babel/types';
 import type { NodePath } from '@babel/traverse';
 import { Plugin, createSuccessResult, createErrorResult } from '../Plugin.js';
 import type { PluginContext, PluginResult, PluginMetadata } from '../Plugin.js';
 import type { NodeRecord } from '@grafema/types';
 import { NetworkRequestNode } from '../../core/nodes/NetworkRequestNode.js';
 import { getLine, getColumn } from './ast/utils/location.js';
+import { getTraverseFunction } from './ast/utils/babelTraverse.js';
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const traverse = (traverseModule as any).default || traverseModule;
+const traverse = getTraverseFunction(traverseModule);
 
 /**
  * Endpoint node
@@ -71,7 +72,6 @@ export class ExpressAnalyzer extends Plugin {
     return {
       name: 'ExpressAnalyzer',
       phase: 'ANALYSIS',
-      priority: 75, // После JSASTAnalyzer (80)
       creates: {
         nodes: ['http:route', 'express:mount'],
         edges: ['EXPOSES', 'MOUNTS', 'DEFINES']
@@ -86,9 +86,13 @@ export class ExpressAnalyzer extends Plugin {
     try {
       const { graph } = context;
 
+      // Batch arrays
+      const nodes: NodeRecord[] = [];
+      const edges: Array<{type: string; src: string; dst: string; [key: string]: unknown}> = [];
+
       // Create net:request singleton (GraphBackend handles deduplication)
       const networkNode = NetworkRequestNode.create();
-      await graph.addNode(networkNode);
+      nodes.push(networkNode as unknown as NodeRecord);
 
       // Получаем все MODULE ноды
       const modules = await this.getModules(graph);
@@ -99,12 +103,16 @@ export class ExpressAnalyzer extends Plugin {
 
       // Анализируем каждый модуль
       for (const module of modules) {
-        const result = await this.analyzeModule(module, graph, networkNode.id);
+        const result = await this.analyzeModule(module, graph, networkNode.id, nodes, edges);
         endpointsCreated += result.endpoints;
         mountPointsCreated += result.mountPoints;
         edgesCreated += result.edges;
       }
 
+      // Add all nodes and edges in batch
+      await graph.addNodes(nodes);
+      await graph.addEdges(edges);
+
       logger.info('Analysis complete', { endpointsCreated, mountPointsCreated });
 
       return createSuccessResult(
@@ -119,7 +127,8 @@ export class ExpressAnalyzer extends Plugin {
       );
     } catch (error) {
       logger.error('Analysis failed', { error });
-      return createErrorResult(error as Error);
+      const err = error instanceof Error ? error : new Error(String(error));
+      return createErrorResult(err);
     }
   }
 
@@ -129,7 +138,9 @@ export class ExpressAnalyzer extends Plugin {
   private async analyzeModule(
     module: NodeRecord,
     graph: PluginContext['graph'],
-    networkId: string
+    networkId: string,
+    nodes: NodeRecord[],
+    edges: Array<{type: string; src: string; dst: string; [key: string]: unknown}>
   ): Promise<AnalysisResult> {
     let endpointsCreated = 0;
     let mountPointsCreated = 0;
@@ -301,11 +312,11 @@ export class ExpressAnalyzer extends Plugin {
 
       // Создаём ENDPOINT ноды
       for (const endpoint of endpoints) {
-        await graph.addNode(endpoint as unknown as NodeRecord);
+        nodes.push(endpoint as unknown as NodeRecord);
         endpointsCreated++;
 
         // MODULE --EXPOSES--> ENDPOINT
-        await graph.addEdge({
+        edges.push({
           type: 'EXPOSES',
           src: module.id,
           dst: endpoint.id
@@ -313,7 +324,7 @@ export class ExpressAnalyzer extends Plugin {
         edgesCreated++;
 
         // ENDPOINT --INTERACTS_WITH--> EXTERNAL_NETWORK
-        await graph.addEdge({
+        edges.push({
           type: 'INTERACTS_WITH',
           src: endpoint.id,
           dst: networkId
@@ -323,11 +334,11 @@ export class ExpressAnalyzer extends Plugin {
 
       // Создаём MOUNT_POINT ноды
       for (const mountPoint of mountPoints) {
-        await graph.addNode(mountPoint as unknown as NodeRecord);
+        nodes.push(mountPoint as unknown as NodeRecord);
         mountPointsCreated++;
 
         // MODULE --DEFINES--> MOUNT_POINT
-        await graph.addEdge({
+        edges.push({
           type: 'DEFINES',
           src: module.id,
           dst: mountPoint.id
@@ -335,10 +346,10 @@ export class ExpressAnalyzer extends Plugin {
         edgesCreated++;
 
         // Создаём MOUNTS рёбра
-        const mountEdges = await this.createMountEdges(mountPoint, module, imports, graph);
+        const mountEdges = await this.createMountEdges(mountPoint, module, imports, graph, edges);
         edgesCreated += mountEdges;
       }
-    } catch (error) {
+    } catch {
       // Silent - per-module errors shouldn't spam logs
     }
 
@@ -356,7 +367,8 @@ export class ExpressAnalyzer extends Plugin {
     mountPoint: MountPointNode,
     module: NodeRecord,
     imports: ImportInfo[],
-    graph: PluginContext['graph']
+    graph: PluginContext['graph'],
+    edges: Array<{type: string; src: string; dst: string; [key: string]: unknown}>
   ): Promise<number> {
     let edgesCreated = 0;
 
@@ -401,7 +413,7 @@ export class ExpressAnalyzer extends Plugin {
       // Проверяем что модуль существует в графе
       const targetModule = await graph.getNode(targetModuleId);
       if (targetModule) {
-        await graph.addEdge({
+        edges.push({
           type: 'MOUNTS',
           src: mountPoint.id,
           dst: targetModuleId