@grafema/core 0.1.0-alpha.4 → 0.1.1-alpha

package/src/diagnostics/DiagnosticWriter.ts

@@ -0,0 +1,50 @@
+/**
+ * DiagnosticWriter - Writes diagnostics to .grafema/diagnostics.log
+ *
+ * Writes diagnostics in JSON lines format (one JSON object per line).
+ * This format is:
+ * - Easy to parse line-by-line
+ * - Appendable without reading entire file
+ * - Compatible with streaming tools (grep, jq, etc.)
+ *
+ * Usage:
+ *   const writer = new DiagnosticWriter();
+ *   await writer.write(collector, '/project/.grafema');
+ */
+
+import { writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+
+import type { DiagnosticCollector } from './DiagnosticCollector.js';
+
+/**
+ * DiagnosticWriter - writes diagnostics.log file
+ */
+export class DiagnosticWriter {
+  /**
+   * Write all diagnostics to .grafema/diagnostics.log
+   *
+   * Creates the directory if it doesn't exist.
+   * Overwrites existing file.
+   */
+  async write(collector: DiagnosticCollector, grafemaDir: string): Promise<void> {
+    const logPath = this.getLogPath(grafemaDir);
+
+    // Create directory if it doesn't exist
+    const dir = dirname(logPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    // Write diagnostics as JSON lines
+    const content = collector.toDiagnosticsLog();
+    writeFileSync(logPath, content, 'utf-8');
+  }
+
+  /**
+   * Get the path to the diagnostics.log file
+   */
+  getLogPath(grafemaDir: string): string {
+    return join(grafemaDir, 'diagnostics.log');
+  }
+}

package/src/diagnostics/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Diagnostics - Error collection, reporting, and logging
+ *
+ * This module provides the diagnostics infrastructure for Grafema:
+ * - DiagnosticCollector: Collects errors from plugin execution
+ * - DiagnosticReporter: Formats diagnostics for output (text/json/csv)
+ * - DiagnosticWriter: Writes diagnostics.log file
+ */
+
+export { DiagnosticCollector } from './DiagnosticCollector.js';
+export type { Diagnostic, DiagnosticInput } from './DiagnosticCollector.js';
+
+export { DiagnosticReporter } from './DiagnosticReporter.js';
+export type { ReportOptions, SummaryStats } from './DiagnosticReporter.js';
+
+export { DiagnosticWriter } from './DiagnosticWriter.js';

package/src/errors/GrafemaError.ts

@@ -0,0 +1,174 @@
+/**
+ * GrafemaError - Error hierarchy for Grafema
+ *
+ * All errors extend the native JavaScript Error class for compatibility
+ * with PluginResult.errors[] (Error[]).
+ *
+ * Error types:
+ * - ConfigError: Configuration parsing/validation errors (fatal)
+ * - FileAccessError: File system access errors (error)
+ * - LanguageError: Unsupported language/parsing errors (warning)
+ * - DatabaseError: RFDB database errors (fatal)
+ * - PluginError: Plugin execution errors (error)
+ * - AnalysisError: Analysis/timeout errors (error)
+ */
+
+import type { PluginPhase } from '@grafema/types';
+
+/**
+ * Context for error reporting
+ */
+export interface ErrorContext {
+  filePath?: string;
+  lineNumber?: number;
+  phase?: PluginPhase;
+  plugin?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * JSON representation of GrafemaError
+ */
+export interface GrafemaErrorJSON {
+  code: string;
+  severity: 'fatal' | 'error' | 'warning';
+  message: string;
+  context: ErrorContext;
+  suggestion?: string;
+}
+
+/**
+ * Abstract base class for all Grafema errors.
+ *
+ * Extends native Error for compatibility with PluginResult.errors[].
+ */
+export abstract class GrafemaError extends Error {
+  abstract readonly code: string;
+  abstract readonly severity: 'fatal' | 'error' | 'warning';
+  readonly context: ErrorContext;
+  readonly suggestion?: string;
+
+  constructor(message: string, context: ErrorContext = {}, suggestion?: string) {
+    super(message);
+    this.name = this.constructor.name;
+    this.context = context;
+    this.suggestion = suggestion;
+
+    // Ensure proper prototype chain for instanceof checks
+    Object.setPrototypeOf(this, new.target.prototype);
+
+    // Capture stack trace (V8 specific)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  /**
+   * Serialize error to JSON for diagnostics.log
+   */
+  toJSON(): GrafemaErrorJSON {
+    return {
+      code: this.code,
+      severity: this.severity,
+      message: this.message,
+      context: this.context,
+      suggestion: this.suggestion,
+    };
+  }
+}
+
+/**
+ * Configuration error - config.json parsing, validation, missing required fields
+ *
+ * Severity: fatal (always)
+ * Codes: ERR_CONFIG_INVALID, ERR_CONFIG_MISSING_FIELD
+ */
+export class ConfigError extends GrafemaError {
+  readonly code: string;
+  readonly severity = 'fatal' as const;
+
+  constructor(message: string, code: string, context: ErrorContext = {}, suggestion?: string) {
+    super(message, context, suggestion);
+    this.code = code;
+  }
+}
+
+/**
+ * File access error - unreadable files, missing git, permissions
+ *
+ * Severity: error (default)
+ * Codes: ERR_FILE_UNREADABLE, ERR_GIT_NOT_FOUND, ERR_GIT_ACCESS_DENIED
+ */
+export class FileAccessError extends GrafemaError {
+  readonly code: string;
+  readonly severity = 'error' as const;
+
+  constructor(message: string, code: string, context: ErrorContext = {}, suggestion?: string) {
+    super(message, context, suggestion);
+    this.code = code;
+  }
+}
+
+/**
+ * Language error - unsupported file type, unparseable syntax
+ *
+ * Severity: warning (always)
+ * Codes: ERR_UNSUPPORTED_LANG, ERR_PARSE_FAILURE
+ */
+export class LanguageError extends GrafemaError {
+  readonly code: string;
+  readonly severity = 'warning' as const;
+
+  constructor(message: string, code: string, context: ErrorContext = {}, suggestion?: string) {
+    super(message, context, suggestion);
+    this.code = code;
+  }
+}
+
+/**
+ * Database error - RFDB connection, corruption, lock
+ *
+ * Severity: fatal (always)
+ * Codes: ERR_DATABASE_LOCKED, ERR_DATABASE_CORRUPTED
+ */
+export class DatabaseError extends GrafemaError {
+  readonly code: string;
+  readonly severity = 'fatal' as const;
+
+  constructor(message: string, code: string, context: ErrorContext = {}, suggestion?: string) {
+    super(message, context, suggestion);
+    this.code = code;
+  }
+}
+
+/**
+ * Plugin error - plugin execution failed, dependency missing
+ *
+ * Severity: error (default)
+ * Codes: ERR_PLUGIN_FAILED, ERR_PLUGIN_DEPENDENCY_MISSING
+ */
+export class PluginError extends GrafemaError {
+  readonly code: string;
+  readonly severity = 'error' as const;
+
+  constructor(message: string, code: string, context: ErrorContext = {}, suggestion?: string) {
+    super(message, context, suggestion);
+    this.code = code;
+  }
+}
+
+/**
+ * Analysis error - internal analyzer failure, timeout
+ *
+ * Severity: error (default)
+ * Codes: ERR_ANALYSIS_TIMEOUT, ERR_ANALYSIS_INTERNAL
+ */
+export class AnalysisError extends GrafemaError {
+  readonly code: string;
+  readonly severity = 'error' as const;
+
+  constructor(message: string, code: string, context: ErrorContext = {}, suggestion?: string) {
+    super(message, context, suggestion);
+    this.code = code;
+  }
+}

package/src/index.ts

@@ -2,6 +2,30 @@
  * @grafema/core - Core analysis engine for GraphDD
  */
 
+// Error types
+export {
+  GrafemaError,
+  ConfigError,
+  FileAccessError,
+  LanguageError,
+  DatabaseError,
+  PluginError,
+  AnalysisError,
+} from './errors/GrafemaError.js';
+export type { ErrorContext, GrafemaErrorJSON } from './errors/GrafemaError.js';
+
+// Logging
+export { Logger, ConsoleLogger, createLogger } from './logging/Logger.js';
+export type { LogLevel } from './logging/Logger.js';
+
+// Diagnostics
+export { DiagnosticCollector, DiagnosticReporter, DiagnosticWriter } from './diagnostics/index.js';
+export type { Diagnostic, DiagnosticInput, ReportOptions, SummaryStats } from './diagnostics/index.js';
+
+// Config
+export { loadConfig, DEFAULT_CONFIG } from './config/index.js';
+export type { GrafemaConfig } from './config/index.js';
+
 // Main orchestrator
 export { Orchestrator } from './Orchestrator.js';
 export type {
@@ -30,9 +54,50 @@ export { RFDBServerBackend } from './storage/backends/RFDBServerBackend.js';
 // Core utilities
 export { NodeFactory } from './core/NodeFactory.js';
 export { Profiler } from './core/Profiler.js';
+export {
+  computeSemanticId,
+  parseSemanticId,
+  computeDiscriminator
+} from './core/SemanticId.js';
+export type {
+  Location,
+  ScopeContext,
+  SemanticIdOptions,
+  ParsedSemanticId,
+  LocatedItem
+} from './core/SemanticId.js';
+export { ScopeTracker } from './core/ScopeTracker.js';
+export type { ScopeEntry, CountedScopeResult } from './core/ScopeTracker.js';
 export { AnalysisQueue } from './core/AnalysisQueue.js';
+export { ASTWorkerPool, type ModuleInfo as ASTModuleInfo, type ParseResult, type ASTWorkerPoolStats } from './core/ASTWorkerPool.js';
 export { GuaranteeManager } from './core/GuaranteeManager.js';
 export type { GuaranteeGraph } from './core/GuaranteeManager.js';
+export { clearFileNodesIfNeeded, clearServiceNodeIfExists } from './core/FileNodeManager.js';
+export { CoverageAnalyzer } from './core/CoverageAnalyzer.js';
+export type { CoverageResult } from './core/CoverageAnalyzer.js';
+
+// Hash utilities
+export { calculateFileHash, calculateFileHashAsync, calculateContentHash } from './core/HashUtils.js';
+
+// Type validation and path validation
+export {
+  levenshtein,
+  checkTypoAgainstKnownTypes,
+  resetKnownNodeTypes,
+  getKnownNodeTypes
+} from './storage/backends/typeValidation.js';
+export { PathValidator } from './validation/PathValidator.js';
+export type { PathValidationResult, EndpointDiff } from './validation/PathValidator.js';
+
+// Version management
+export { VersionManager, versionManager } from './core/VersionManager.js';
+export type { VersionedNode, VersionConstants, EnrichOptions, ModifiedNodeInfo, ChangesSummary, ClassifyChangesResult } from './core/VersionManager.js';
+
+// Freshness checking and incremental reanalysis
+export { GraphFreshnessChecker } from './core/GraphFreshnessChecker.js';
+export type { FreshnessGraph, FreshnessResult, StaleModule } from './core/GraphFreshnessChecker.js';
+export { IncrementalReanalyzer } from './core/IncrementalReanalyzer.js';
+export type { ReanalysisOptions, ReanalysisProgress, ReanalysisResult } from './core/IncrementalReanalyzer.js';
 
 // API
 export { GraphAPI } from './api/GraphAPI.js';
@@ -42,13 +107,64 @@ export type { GuaranteeGraphBackend } from './api/GuaranteeAPI.js';
 // Node kinds
 export { isGuaranteeType } from './core/nodes/NodeKind.js';
 
+// Issue nodes (detected problems)
+export { IssueNode, type IssueNodeRecord, type IssueSeverity, type IssueType } from './core/nodes/IssueNode.js';
+
+// Node contracts
+export { FunctionNode } from './core/nodes/FunctionNode.js';
+export { CallSiteNode } from './core/nodes/CallSiteNode.js';
+export { MethodCallNode } from './core/nodes/MethodCallNode.js';
+export { ScopeNode } from './core/nodes/ScopeNode.js';
+export { ClassNode } from './core/nodes/ClassNode.js';
+export { MethodNode } from './core/nodes/MethodNode.js';
+export { ExportNode } from './core/nodes/ExportNode.js';
+export { VariableDeclarationNode } from './core/nodes/VariableDeclarationNode.js';
+export { ExternalModuleNode } from './core/nodes/ExternalModuleNode.js';
+export { NetworkRequestNode } from './core/nodes/NetworkRequestNode.js';
+export { InterfaceNode, type InterfacePropertyRecord } from './core/nodes/InterfaceNode.js';
+export { TypeNode } from './core/nodes/TypeNode.js';
+export { EnumNode, type EnumMemberRecord } from './core/nodes/EnumNode.js';
+export { DecoratorNode, type DecoratorTargetType } from './core/nodes/DecoratorNode.js';
+export { ExpressionNode, type ExpressionNodeOptions } from './core/nodes/ExpressionNode.js';
+export { ArgumentExpressionNode, type ArgumentExpressionNodeRecord, type ArgumentExpressionNodeOptions } from './core/nodes/ArgumentExpressionNode.js';
+
+// AST Visitors (for advanced usage)
+export {
+  ASTVisitor,
+  ImportExportVisitor,
+  VariableVisitor,
+  FunctionVisitor,
+  ClassVisitor,
+  CallExpressionVisitor,
+  TypeScriptVisitor
+} from './plugins/analysis/ast/visitors/index.js';
+export type {
+  VisitorModule,
+  VisitorCollections,
+  VisitorHandlers,
+  VisitorHandler,
+  VariableInfo,
+  ExtractVariableNamesCallback,
+  TrackVariableAssignmentCallback,
+  AnalyzeFunctionBodyCallback
+} from './plugins/analysis/ast/visitors/index.js';
+
+// AST Location utilities (REG-122)
+export {
+  getNodeLocation,
+  getLine,
+  getColumn,
+  getEndLocation,
+  UNKNOWN_LOCATION
+} from './plugins/analysis/ast/utils/location.js';
+export type { NodeLocation } from './plugins/analysis/ast/utils/location.js';
+
 // === PLUGINS ===
 
 // Indexing plugins
 export { JSModuleIndexer } from './plugins/indexing/JSModuleIndexer.js';
 export { IncrementalModuleIndexer } from './plugins/indexing/IncrementalModuleIndexer.js';
 export { RustModuleIndexer } from './plugins/indexing/RustModuleIndexer.js';
-export { ServiceDetector } from './plugins/indexing/ServiceDetector.js';
 
 // Analysis plugins
 export { JSASTAnalyzer } from './plugins/analysis/JSASTAnalyzer.js';
@@ -83,11 +199,42 @@ export { ShadowingDetector } from './plugins/validation/ShadowingDetector.js';
 export { GraphConnectivityValidator } from './plugins/validation/GraphConnectivityValidator.js';
 export { DataFlowValidator } from './plugins/validation/DataFlowValidator.js';
 export { TypeScriptDeadCodeValidator } from './plugins/validation/TypeScriptDeadCodeValidator.js';
+export { NodeCreationValidator } from './plugins/validation/NodeCreationValidator.js';
 
 // Discovery plugins
 export { SimpleProjectDiscovery } from './plugins/discovery/SimpleProjectDiscovery.js';
 export { DiscoveryPlugin } from './plugins/discovery/DiscoveryPlugin.js';
 export { MonorepoServiceDiscovery } from './plugins/discovery/MonorepoServiceDiscovery.js';
+export { WorkspaceDiscovery } from './plugins/discovery/WorkspaceDiscovery.js';
+export { resolveSourceEntrypoint } from './plugins/discovery/resolveSourceEntrypoint.js';
+export type { PackageJsonForResolution } from './plugins/discovery/resolveSourceEntrypoint.js';
+
+// Workspace detection utilities
+export {
+  detectWorkspaceType,
+  parsePnpmWorkspace,
+  parseNpmWorkspace,
+  parseLernaConfig,
+  resolveWorkspacePackages
+} from './plugins/discovery/workspaces/index.js';
+export type {
+  WorkspaceType,
+  WorkspaceDetectionResult,
+  WorkspaceConfig,
+  WorkspacePackage
+} from './plugins/discovery/workspaces/index.js';
+
+// VCS plugins
+export { GitPlugin } from './plugins/vcs/GitPlugin.js';
+export { VCSPlugin, VCSPluginFactory, FileStatus } from './plugins/vcs/VCSPlugin.js';
+export type {
+  VCSConfig,
+  VCSPluginMetadata,
+  ChangedFile,
+  FileDiff,
+  DiffHunk,
+} from './plugins/vcs/VCSPlugin.js';
+export type { CommitInfo } from './plugins/vcs/GitPlugin.js';
 
 // Re-export types for convenience
 export type * from '@grafema/types';

package/src/logging/Logger.ts

@@ -0,0 +1,152 @@
+/**
+ * Logger - Lightweight logging for Grafema
+ *
+ * Features:
+ * - 5 log levels: silent, errors, warnings, info, debug
+ * - Context support for structured logging
+ * - No external dependencies
+ * - Safe handling of circular references
+ *
+ * Usage:
+ *   const logger = createLogger('info');
+ *   logger.info('Processing files', { count: 150 });
+ */
+
+/**
+ * Log level type
+ */
+export type LogLevel = 'silent' | 'errors' | 'warnings' | 'info' | 'debug';
+
+/**
+ * Logger interface
+ */
+export interface Logger {
+  error(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  info(message: string, context?: Record<string, unknown>): void;
+  debug(message: string, context?: Record<string, unknown>): void;
+  trace(message: string, context?: Record<string, unknown>): void;
+}
+
+/**
+ * Log level priorities (higher = more verbose)
+ */
+const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
+  silent: 0,
+  errors: 1,
+  warnings: 2,
+  info: 3,
+  debug: 4,
+};
+
+/**
+ * Minimum level required for each method
+ */
+const METHOD_LEVELS = {
+  error: LOG_LEVEL_PRIORITY.errors,
+  warn: LOG_LEVEL_PRIORITY.warnings,
+  info: LOG_LEVEL_PRIORITY.info,
+  debug: LOG_LEVEL_PRIORITY.debug,
+  trace: LOG_LEVEL_PRIORITY.debug,
+};
+
+/**
+ * Safe JSON stringify that handles circular references
+ */
+function safeStringify(obj: unknown): string {
+  const seen = new WeakSet();
+  return JSON.stringify(obj, (_key, value) => {
+    if (typeof value === 'object' && value !== null) {
+      if (seen.has(value)) {
+        return '[Circular]';
+      }
+      seen.add(value);
+    }
+    return value;
+  });
+}
+
+/**
+ * Format log message with optional context
+ */
+function formatMessage(message: string, context?: Record<string, unknown>): string {
+  if (!context || Object.keys(context).length === 0) {
+    return message;
+  }
+  try {
+    return `${message} ${safeStringify(context)}`;
+  } catch {
+    return `${message} [context serialization failed]`;
+  }
+}
+
+/**
+ * Console-based Logger implementation
+ *
+ * Respects log level threshold - methods below threshold are no-ops.
+ */
+export class ConsoleLogger implements Logger {
+  private readonly level: LogLevel;
+  private readonly priority: number;
+
+  constructor(logLevel: LogLevel = 'info') {
+    this.level = logLevel;
+    this.priority = LOG_LEVEL_PRIORITY[logLevel];
+  }
+
+  private shouldLog(methodLevel: number): boolean {
+    return this.priority >= methodLevel;
+  }
+
+  error(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.error)) return;
+    try {
+      console.error(formatMessage(`[ERROR] ${message}`, context));
+    } catch {
+      console.log(`[ERROR] ${message} [logging failed]`);
+    }
+  }
+
+  warn(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.warn)) return;
+    try {
+      console.warn(formatMessage(`[WARN] ${message}`, context));
+    } catch {
+      console.log(`[WARN] ${message} [logging failed]`);
+    }
+  }
+
+  info(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.info)) return;
+    try {
+      console.info(formatMessage(`[INFO] ${message}`, context));
+    } catch {
+      console.log(`[INFO] ${message} [logging failed]`);
+    }
+  }
+
+  debug(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.debug)) return;
+    try {
+      console.debug(formatMessage(`[DEBUG] ${message}`, context));
+    } catch {
+      console.log(`[DEBUG] ${message} [logging failed]`);
+    }
+  }
+
+  trace(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.trace)) return;
+    try {
+      console.debug(formatMessage(`[TRACE] ${message}`, context));
+    } catch {
+      console.log(`[TRACE] ${message} [logging failed]`);
+    }
+  }
+}
+
+/**
+ * Create a Logger instance with the specified log level
+ */
+export function createLogger(level: LogLevel): Logger {
+  return new ConsoleLogger(level);
+}

package/src/plugins/Plugin.ts

@@ -14,6 +14,7 @@ import type {
   PluginResult,
   IPlugin,
   NodeFilter,
+  Logger,
 } from '@grafema/types';
 import type { NodeRecord } from '@grafema/types';
 
@@ -71,4 +72,45 @@ export abstract class Plugin implements IPlugin {
     }
     return modules;
   }
+
+  /**
+   * Get a logger from context with console fallback for backward compatibility.
+   */
+  protected log(context: PluginContext): Logger {
+    if (context.logger) {
+      return context.logger;
+    }
+
+    // Fallback to console for backward compatibility
+    const safeStringify = (obj: Record<string, unknown>): string => {
+      try {
+        const seen = new WeakSet();
+        return JSON.stringify(obj, (_key, value) => {
+          if (typeof value === 'object' && value !== null) {
+            if (seen.has(value)) return '[Circular]';
+            seen.add(value);
+          }
+          return value;
+        });
+      } catch {
+        return '[serialization failed]';
+      }
+    };
+
+    const format = (msg: string, ctx?: Record<string, unknown>) =>
+      ctx ? `${msg} ${safeStringify(ctx)}` : msg;
+
+    return {
+      error: (msg: string, ctx?: Record<string, unknown>) =>
+        console.error(`[ERROR] ${format(msg, ctx)}`),
+      warn: (msg: string, ctx?: Record<string, unknown>) =>
+        console.warn(`[WARN] ${format(msg, ctx)}`),
+      info: (msg: string, ctx?: Record<string, unknown>) =>
+        console.log(`[INFO] ${format(msg, ctx)}`),
+      debug: (msg: string, ctx?: Record<string, unknown>) =>
+        console.debug(`[DEBUG] ${format(msg, ctx)}`),
+      trace: (msg: string, ctx?: Record<string, unknown>) =>
+        console.debug(`[TRACE] ${format(msg, ctx)}`),
+    };
+  }
 }