@grafema/core 0.1.1-alpha → 0.2.0-beta

package/src/data/globals/index.ts

@@ -0,0 +1,66 @@
+/**
+ * Global Symbols Registry
+ *
+ * Provides lookup for JavaScript/TypeScript global symbols.
+ * Used by BrokenImportValidator to avoid false positives on globals.
+ */
+
+import { ALL_GLOBALS as DEFAULT_GLOBALS } from './definitions.js';
+
+export {
+  ECMASCRIPT_GLOBALS,
+  NODEJS_GLOBALS,
+  BROWSER_GLOBALS,
+  TEST_GLOBALS,
+  ALL_GLOBALS,
+} from './definitions.js';
+
+/**
+ * GlobalsRegistry class for extensible globals management.
+ *
+ * Usage:
+ *   const registry = new GlobalsRegistry();
+ *   if (registry.isGlobal('console')) { ... }
+ *   registry.addCustomGlobals(['myGlobal']);
+ */
+export class GlobalsRegistry {
+  private globals: Set<string>;
+
+  constructor(includeDefaults: boolean = true) {
+    this.globals = includeDefaults
+      ? new Set(DEFAULT_GLOBALS)
+      : new Set();
+  }
+
+  /**
+   * Check if a symbol name is a known global.
+   */
+  isGlobal(name: string): boolean {
+    return this.globals.has(name);
+  }
+
+  /**
+   * Add custom globals (e.g., from project config).
+   */
+  addCustomGlobals(names: string[]): void {
+    for (const name of names) {
+      this.globals.add(name);
+    }
+  }
+
+  /**
+   * Remove globals from the set (e.g., if project doesn't use browser env).
+   */
+  removeGlobals(names: string[]): void {
+    for (const name of names) {
+      this.globals.delete(name);
+    }
+  }
+
+  /**
+   * Get all registered globals.
+   */
+  getAllGlobals(): string[] {
+    return Array.from(this.globals);
+  }
+}

package/src/diagnostics/DiagnosticReporter.ts

@@ -14,6 +14,21 @@
 
 import type { Diagnostic, DiagnosticCollector } from './DiagnosticCollector.js';
 
+/**
+ * Mapping from diagnostic codes to category information
+ */
+const DIAGNOSTIC_CODE_CATEGORIES: Record<string, { name: string; checkCommand: string }> = {
+  'ERR_DISCONNECTED_NODES': { name: 'disconnected nodes', checkCommand: 'grafema check connectivity' },
+  'ERR_DISCONNECTED_NODE': { name: 'disconnected nodes', checkCommand: 'grafema check connectivity' },
+  'ERR_UNRESOLVED_CALL': { name: 'unresolved calls', checkCommand: 'grafema check calls' },
+  'ERR_MISSING_ASSIGNMENT': { name: 'missing assignments', checkCommand: 'grafema check dataflow' },
+  'ERR_BROKEN_REFERENCE': { name: 'broken references', checkCommand: 'grafema check dataflow' },
+  'ERR_NO_LEAF_NODE': { name: 'incomplete traces', checkCommand: 'grafema check dataflow' },
+  'DISCONNECTED_NODES': { name: 'disconnected nodes', checkCommand: 'grafema check connectivity' },
+  'UNRESOLVED_FUNCTION_CALL': { name: 'unresolved calls', checkCommand: 'grafema check calls' },
+  'MISSING_ASSIGNMENT': { name: 'missing assignments', checkCommand: 'grafema check dataflow' },
+};
+
 /**
  * Report output options
  */
@@ -34,6 +49,23 @@ export interface SummaryStats {
   info: number;
 }
 
+/**
+ * Category count with metadata
+ */
+export interface CategoryCount {
+  code: string;
+  count: number;
+  name: string;
+  checkCommand: string;
+}
+
+/**
+ * Summary statistics with category breakdown
+ */
+export interface CategorizedSummaryStats extends SummaryStats {
+  byCode: CategoryCount[];
+}
+
 /**
  * DiagnosticReporter - formats diagnostics for different output formats
  */
@@ -80,6 +112,51 @@ export class DiagnosticReporter {
     return parts.join(', ');
   }
 
+  /**
+   * Generate a categorized summary with actionable commands.
+   */
+  categorizedSummary(): string {
+    const stats = this.getCategorizedStats();
+
+    if (stats.total === 0) {
+      return 'No issues found.';
+    }
+
+    const lines: string[] = [];
+
+    // Severity totals (same format as summary())
+    const severityParts: string[] = [];
+    if (stats.fatal > 0) {
+      severityParts.push(`Fatal: ${stats.fatal}`);
+    }
+    if (stats.errors > 0) {
+      severityParts.push(`Errors: ${stats.errors}`);
+    }
+    if (stats.warnings > 0) {
+      severityParts.push(`Warnings: ${stats.warnings}`);
+    }
+    lines.push(severityParts.join(', '));
+
+    // Top 5 categories
+    const topCategories = stats.byCode.slice(0, 5);
+    for (const category of topCategories) {
+      lines.push(`  - ${category.count} ${category.name} (run \`${category.checkCommand}\`)`);
+    }
+
+    // "Other issues" if more than 5 categories
+    if (stats.byCode.length > 5) {
+      const remainingCount = stats.byCode.slice(5).reduce((sum, cat) => sum + cat.count, 0);
+      const issueWord = remainingCount === 1 ? 'other issue' : 'other issues';
+      lines.push(`  - ${remainingCount} ${issueWord}`);
+    }
+
+    // Footer
+    lines.push('');
+    lines.push('Run `grafema check --all` for full diagnostics.');
+
+    return lines.join('\n');
+  }
+
   /**
    * Get diagnostic statistics by severity.
    */
@@ -94,6 +171,49 @@ export class DiagnosticReporter {
     };
   }
 
+  /**
+   * Get diagnostic statistics grouped by category.
+   */
+  getCategorizedStats(): CategorizedSummaryStats {
+    const diagnostics = this.collector.getAll();
+
+    // Get severity stats
+    const severityStats: SummaryStats = {
+      total: diagnostics.length,
+      fatal: diagnostics.filter(d => d.severity === 'fatal').length,
+      errors: diagnostics.filter(d => d.severity === 'error').length,
+      warnings: diagnostics.filter(d => d.severity === 'warning').length,
+      info: diagnostics.filter(d => d.severity === 'info').length,
+    };
+
+    // Group by code
+    const codeMap = new Map<string, number>();
+    for (const diag of diagnostics) {
+      const count = codeMap.get(diag.code) || 0;
+      codeMap.set(diag.code, count + 1);
+    }
+
+    // Convert to CategoryCount array with metadata
+    const byCode: CategoryCount[] = [];
+    for (const [code, count] of codeMap.entries()) {
+      const category = DIAGNOSTIC_CODE_CATEGORIES[code];
+      byCode.push({
+        code,
+        count,
+        name: category?.name || code,
+        checkCommand: category?.checkCommand || 'grafema check --all',
+      });
+    }
+
+    // Sort by count descending
+    byCode.sort((a, b) => b.count - a.count);
+
+    return {
+      ...severityStats,
+      byCode,
+    };
+  }
+
   /**
    * Generate human-readable text report.
    */

package/src/diagnostics/index.ts

@@ -11,6 +11,6 @@ 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 type { ReportOptions, SummaryStats, CategoryCount, CategorizedSummaryStats } from './DiagnosticReporter.js';
 
 export { DiagnosticWriter } from './DiagnosticWriter.js';

package/src/errors/GrafemaError.ts

@@ -172,3 +172,68 @@ export class AnalysisError extends GrafemaError {
     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

@@ -11,6 +11,8 @@ export {
   DatabaseError,
   PluginError,
   AnalysisError,
+  ValidationError,
+  StrictModeError,
 } from './errors/GrafemaError.js';
 export type { ErrorContext, GrafemaErrorJSON } from './errors/GrafemaError.js';
 
@@ -75,6 +77,8 @@ 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';
@@ -169,6 +173,7 @@ export { RustModuleIndexer } from './plugins/indexing/RustModuleIndexer.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';
@@ -182,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';
@@ -189,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';
@@ -200,6 +217,7 @@ export { GraphConnectivityValidator } from './plugins/validation/GraphConnectivi
 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';
@@ -236,5 +254,32 @@ export type {
 } 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';

package/src/plugins/analysis/DatabaseAnalyzer.ts

@@ -11,7 +11,7 @@ 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 { getLine } from './ast/utils/location.js';
+import { getLine, getColumn } from './ast/utils/location.js';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const traverse = (traverseModule as any).default || traverseModule;
@@ -30,6 +30,7 @@ interface DatabaseQueryNode {
   method: string;
   file: string;
   line: number;
+  column: number;
 }
 
 /**
@@ -224,7 +225,8 @@ export class DatabaseAnalyzer extends Plugin {
                   object: objectName,
                   method: methodName,
                   file: module.file!,
-                  line: getLine(node)
+                  line: getLine(node),
+                  column: getColumn(node)
                 });
               }
             }

package/src/plugins/analysis/ExpressAnalyzer.ts

@@ -13,7 +13,7 @@ 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 } from './ast/utils/location.js';
+import { getLine, getColumn } from './ast/utils/location.js';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const traverse = (traverseModule as any).default || traverseModule;
@@ -29,6 +29,7 @@ interface EndpointNode {
   localPath: string;
   file: string;
   line: number;
+  column: number;
   mountedOn: string;
 }
 
@@ -43,6 +44,7 @@ interface MountPointNode {
   targetVariable: string | null;
   file: string;
   line: number;
+  column: number;
   mountedOn: string;
 }
 
@@ -210,6 +212,7 @@ export class ExpressAnalyzer extends Plugin {
                   localPath: routePath,
                   file: module.file!,
                   line: getLine(node),
+                  column: getColumn(node),
                   mountedOn: objectName
                 });
               }
@@ -287,6 +290,7 @@ export class ExpressAnalyzer extends Plugin {
                   targetVariable: targetVariable,
                   file: module.file!,
                   line: getLine(node),
+                  column: getColumn(node),
                   mountedOn: objectName
                 });
               }