@grafema/core 0.1.0-alpha.5 → 0.2.0-beta

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, CategoryCount, CategorizedSummaryStats } from './DiagnosticReporter.js';
+
+export { DiagnosticWriter } from './DiagnosticWriter.js';

package/src/errors/GrafemaError.ts

@@ -0,0 +1,239 @@
+/**
+ * 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;
+  }
+}
+
+/**
+ * Validation error - issues found by validators during VALIDATION phase
+ *
+ * Unlike other error classes, ValidationError has CONFIGURABLE severity because
+ * validators report issues of varying importance:
+ * - warning: informational issues (unresolved calls, missing assignments)
+ * - error: problems that may indicate bugs (broken references)
+ * - fatal: critical issues that should fail the analysis
+ *
+ * Codes:
+ * - ERR_UNRESOLVED_CALL: function call doesn't resolve to definition
+ * - ERR_DISCONNECTED_NODES: graph nodes not connected to root
+ * - ERR_DISCONNECTED_NODE: individual disconnected node
+ * - ERR_MISSING_ASSIGNMENT: variable has no ASSIGNED_FROM edge
+ * - ERR_BROKEN_REFERENCE: reference to non-existent node
+ * - ERR_NO_LEAF_NODE: data flow doesn't reach leaf node
+ */
+export class ValidationError extends GrafemaError {
+  readonly code: string;
+  readonly severity: 'fatal' | 'error' | 'warning';
+
+  constructor(
+    message: string,
+    code: string,
+    context: ErrorContext = {},
+    suggestion?: string,
+    severity: 'fatal' | 'error' | 'warning' = 'warning'
+  ) {
+    super(message, context, suggestion);
+    this.code = code;
+    this.severity = severity;
+  }
+}
+
+/**
+ * Strict mode error - reported when strictMode=true and an enricher
+ * cannot resolve a reference.
+ *
+ * Unlike other errors, StrictModeError is used to collect issues that
+ * would normally be silently skipped. All collected StrictModeErrors
+ * cause analysis to fail after the ENRICHMENT phase completes.
+ *
+ * Severity: fatal (always)
+ * Codes:
+ * - STRICT_UNRESOLVED_METHOD: Method call cannot be resolved to definition
+ * - STRICT_UNRESOLVED_CALL: Function call cannot be resolved to definition
+ * - STRICT_UNRESOLVED_ARGUMENT: Argument cannot be linked to parameter
+ * - STRICT_ALIAS_DEPTH_EXCEEDED: Alias chain too deep (potential cycle)
+ * - STRICT_BROKEN_IMPORT: Import/re-export chain broken
+ */
+export class StrictModeError 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;
+  }
+}

package/src/index.ts

@@ -2,6 +2,32 @@
  * @grafema/core - Core analysis engine for GraphDD
  */
 
+// Error types
+export {
+  GrafemaError,
+  ConfigError,
+  FileAccessError,
+  LanguageError,
+  DatabaseError,
+  PluginError,
+  AnalysisError,
+  ValidationError,
+  StrictModeError,
+} 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 +56,52 @@ 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';
+export { FileExplainer } from './core/FileExplainer.js';
+export type { FileExplainResult, EnhancedNode } from './core/FileExplainer.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,17 +111,69 @@ 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';
 export { ExpressRouteAnalyzer } from './plugins/analysis/ExpressRouteAnalyzer.js';
+export { ExpressResponseAnalyzer } from './plugins/analysis/ExpressResponseAnalyzer.js';
 export { ExpressAnalyzer } from './plugins/analysis/ExpressAnalyzer.js';
 export { SocketIOAnalyzer } from './plugins/analysis/SocketIOAnalyzer.js';
 export { DatabaseAnalyzer } from './plugins/analysis/DatabaseAnalyzer.js';
@@ -66,6 +187,7 @@ export { IncrementalAnalysisPlugin } from './plugins/analysis/IncrementalAnalysi
 
 // Enrichment plugins
 export { MethodCallResolver } from './plugins/enrichment/MethodCallResolver.js';
+export { ArgumentParameterLinker } from './plugins/enrichment/ArgumentParameterLinker.js';
 export { AliasTracker } from './plugins/enrichment/AliasTracker.js';
 export { ValueDomainAnalyzer } from './plugins/enrichment/ValueDomainAnalyzer.js';
 export { MountPointResolver } from './plugins/enrichment/MountPointResolver.js';
@@ -73,7 +195,18 @@ export { PrefixEvaluator } from './plugins/enrichment/PrefixEvaluator.js';
 export { InstanceOfResolver } from './plugins/enrichment/InstanceOfResolver.js';
 export { HTTPConnectionEnricher } from './plugins/enrichment/HTTPConnectionEnricher.js';
 export { ImportExportLinker } from './plugins/enrichment/ImportExportLinker.js';
+export { FunctionCallResolver } from './plugins/enrichment/FunctionCallResolver.js';
 export { RustFFIEnricher } from './plugins/enrichment/RustFFIEnricher.js';
+export { NodejsBuiltinsResolver } from './plugins/enrichment/NodejsBuiltinsResolver.js';
+export { ExternalCallResolver } from './plugins/enrichment/ExternalCallResolver.js';
+export { ClosureCaptureEnricher } from './plugins/enrichment/ClosureCaptureEnricher.js';
+
+// Builtin registry
+export { BuiltinRegistry } from './data/builtins/index.js';
+export type { BuiltinFunctionDef, BuiltinModuleDef, SecurityCategory } from './data/builtins/index.js';
+
+// Globals registry
+export { GlobalsRegistry, ALL_GLOBALS } from './data/globals/index.js';
 
 // Validation plugins
 export { CallResolverValidator } from './plugins/validation/CallResolverValidator.js';
@@ -83,11 +216,70 @@ 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';
+export { BrokenImportValidator } from './plugins/validation/BrokenImportValidator.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';
+
+// Schema extraction
+export { InterfaceSchemaExtractor, GraphSchemaExtractor } from './schema/index.js';
+export type {
+  InterfaceSchema,
+  PropertySchema,
+  ExtractOptions,
+  GraphSchema,
+  NodeTypeSchema,
+  EdgeTypeSchema,
+  GraphExtractOptions,
+} from './schema/index.js';
+
+// Graph Query Utilities
+export { findCallsInFunction, findContainingFunction, traceValues, aggregateValues, NONDETERMINISTIC_PATTERNS, NONDETERMINISTIC_OBJECTS } from './queries/index.js';
+export type {
+  CallInfo,
+  CallerInfo,
+  FindCallsOptions,
+  TracedValue,
+  ValueSource,
+  UnknownReason,
+  TraceValuesOptions,
+  ValueSetResult,
+  TraceValuesGraphBackend,
+  NondeterministicPattern,
+} from './queries/index.js';
 
 // Re-export types for convenience
 export type * from '@grafema/types';