@grafema/util 0.3.0-beta

package/src/errors/GrafemaError.ts

@@ -0,0 +1,297 @@
+/**
+ * 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';
+import type { Diagnostic } from '../diagnostics/DiagnosticCollector.js';
+
+/**
+ * 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;
+  }
+}
+
+/**
+ * A step in the resolution chain showing what was resolved before failure.
+ * Used by StrictModeError to provide context-aware error messages (REG-332).
+ */
+export interface ResolutionStep {
+  /** Description of what was resolved, e.g., "getUser() return" */
+  step: string;
+  /** Result of resolution, e.g., "unknown" or "User class" */
+  result: string;
+  /** File where this step occurred */
+  file?: string;
+  /** Line number */
+  line?: number;
+}
+
+/**
+ * Reasons why resolution can fail.
+ * Used by StrictModeError for context-aware suggestions (REG-332).
+ */
+export type ResolutionFailureReason =
+  | 'unknown_object_type'      // getUser() return unknown
+  | 'class_not_imported'       // User class not in scope
+  | 'method_not_found'         // Class exists but no such method
+  | 'external_dependency'      // From node_modules
+  | 'circular_reference'       // Alias chain too deep
+  | 'builtin_method'           // Built-in prototype method (not an error)
+  | 'unknown';                 // Catch-all
+
+/**
+ * StrictModeFailure - thrown when strict mode stops analysis due to fatal errors.
+ *
+ * Unlike other errors, this carries a reference to the fatal diagnostic(s)
+ * rather than duplicating the message. The CLI formats output from
+ * the diagnostic, not from error.message.
+ *
+ * This prevents the duplication issue where both error.message and
+ * DiagnosticReporter show the same error (REG-332).
+ */
+export class StrictModeFailure extends Error {
+  /** The fatal diagnostics that caused the failure */
+  readonly diagnostics: Diagnostic[];
+  /** Error count for summary */
+  readonly count: number;
+  /** REG-332: Number of errors suppressed by grafema-ignore comments */
+  readonly suppressedCount: number;
+
+  constructor(diagnostics: Diagnostic[], suppressedCount: number = 0) {
+    // Keep message minimal - CLI will format from diagnostics
+    super(`Strict mode: ${diagnostics.length} unresolved reference(s) found`);
+    this.name = 'StrictModeFailure';
+    this.diagnostics = diagnostics;
+    this.count = diagnostics.length;
+    this.suppressedCount = suppressedCount;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/src/index.ts

@@ -0,0 +1,261 @@
+/**
+ * @grafema/util - Query, config, and guarantee utilities for Grafema
+ *
+ * This package contains the live query layer, configuration, diagnostics,
+ * and guarantee management. Analysis is handled by grafema-orchestrator (Rust).
+ */
+
+// Error types
+export {
+  GrafemaError,
+  ConfigError,
+  FileAccessError,
+  LanguageError,
+  DatabaseError,
+  PluginError,
+  AnalysisError,
+  ValidationError,
+  StrictModeError,
+  StrictModeFailure,
+} from './errors/GrafemaError.js';
+export type {
+  ErrorContext,
+  GrafemaErrorJSON,
+  ResolutionStep,
+  ResolutionFailureReason,
+} from './errors/GrafemaError.js';
+
+// Logging
+export { ConsoleLogger, FileLogger, MultiLogger, createLogger } from './logging/Logger.js';
+export type { Logger, LogLevel } from './logging/Logger.js';
+
+// Diagnostics
+export { DiagnosticCollector, DiagnosticReporter, DiagnosticWriter } from './diagnostics/index.js';
+export type { Diagnostic, DiagnosticInput, ReportOptions, SummaryStats } from './diagnostics/index.js';
+export { DIAGNOSTIC_CATEGORIES, CODE_TO_CATEGORY, getCategoryForCode, getCodesForCategory } from './diagnostics/index.js';
+export type { DiagnosticCategory, DiagnosticCategoryKey, CodeCategoryInfo } from './diagnostics/index.js';
+
+// Config
+export {
+  loadConfig,
+  DEFAULT_CONFIG,
+  validateVersion,
+  validateServices,
+  validatePatterns,
+  validateWorkspace,
+  validateRouting,
+} from './config/index.js';
+export type { GrafemaConfig } from './config/index.js';
+
+// Version
+export { GRAFEMA_VERSION, getSchemaVersion } from './version.js';
+
+// Instructions (for AI agents)
+export { getOnboardingInstruction } from './instructions/index.js';
+
+// Graph backend
+export { GraphBackend, typeToKind, edgeTypeToNumber } from './core/GraphBackend.js';
+export type { Node, Edge, EdgeType, AttrQuery, GraphStats, GraphExport } from './core/GraphBackend.js';
+
+// RFDB
+export { RFDBClient } from '@grafema/rfdb-client';
+export { RFDBServerBackend } from './storage/backends/RFDBServerBackend.js';
+
+// Core utilities
+export {
+  computeSemanticId,
+  parseSemanticId,
+  computeDiscriminator,
+  computeSemanticIdV2,
+  parseSemanticIdV2,
+  computeContentHash
+} from './core/SemanticId.js';
+export type {
+  Location,
+  ScopeContext,
+  SemanticIdOptions,
+  ParsedSemanticId,
+  LocatedItem,
+  ParsedSemanticIdV2,
+  ContentHashHints
+} from './core/SemanticId.js';
+
+// URI format
+export {
+  isGrafemaUri,
+  encodeFragment,
+  decodeFragment,
+  toGrafemaUri,
+  parseGrafemaUri,
+  toCompactSemanticId,
+  normalizeSemanticId
+} from './core/GrafemaUri.js';
+export type { ParsedGrafemaUri } from './core/GrafemaUri.js';
+
+export { GuaranteeManager } from './core/GuaranteeManager.js';
+export type { GuaranteeGraph } from './core/GuaranteeManager.js';
+
+// Hash utilities
+export { calculateFileHash, calculateFileHashAsync, calculateContentHash } from './core/HashUtils.js';
+
+// Binary finder utilities
+export { findBinary, findAnalyzerBinary, findRfdbBinary, findOrchestratorBinary, getBinaryNotFoundMessage, getPlatformDir, getPlatformPackageName } from './utils/findRfdbBinary.js';
+export type { FindBinaryOptions, BinaryName } from './utils/findRfdbBinary.js';
+
+// Lazy download
+export { ensureBinary, downloadBinary, isDownloadable, findInGrafemaBin, getGrafemaBinDir } from './utils/lazyDownload.js';
+
+// RFDB server lifecycle
+export { startRfdbServer, checkExistingServer } from './utils/startRfdbServer.js';
+export type { StartRfdbServerOptions } from './utils/startRfdbServer.js';
+
+// Module resolution utilities
+export {
+  resolveModulePath,
+  isRelativeImport,
+  resolveRelativeSpecifier,
+  DEFAULT_EXTENSIONS,
+  DEFAULT_INDEX_FILES
+} from './utils/moduleResolution.js';
+export type { ModuleResolutionOptions } from './utils/moduleResolution.js';
+
+// Node file path resolution
+export { resolveNodeFile } from './utils/resolveNodeFile.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';
+
+// Coverage
+export { CoverageAnalyzer } from './core/CoverageAnalyzer.js';
+export type { CoverageResult } from './core/CoverageAnalyzer.js';
+
+// File analysis utilities
+export { FileExplainer } from './core/FileExplainer.js';
+export type { FileExplainResult, EnhancedNode } from './core/FileExplainer.js';
+export { FileOverview } from './core/FileOverview.js';
+export type {
+  FileOverviewResult,
+  ImportInfo,
+  ExportInfo,
+  FunctionOverview,
+  ClassOverview,
+  VariableOverview,
+} from './core/FileOverview.js';
+
+// Resource system
+export { ResourceRegistryImpl } from './core/ResourceRegistry.js';
+
+// API
+export { GraphAPI } from './api/GraphAPI.js';
+export { GuaranteeAPI } from './api/GuaranteeAPI.js';
+export type { GuaranteeGraphBackend } from './api/GuaranteeAPI.js';
+
+// Node kinds
+export { isGuaranteeType, isGrafemaType } from './core/nodes/NodeKind.js';
+
+// Issue nodes (detected problems)
+export { IssueNode, type IssueNodeRecord, type IssueSeverity, type IssueType } from './core/nodes/IssueNode.js';
+
+// Guarantee nodes (contract-based)
+export { GuaranteeNode } from './core/nodes/GuaranteeNode.js';
+export type {
+  GuaranteeNodeRecord,
+  GuaranteeNodeOptions,
+  GuaranteePriority,
+  GuaranteeStatus,
+  GuaranteeType,
+} from './core/nodes/GuaranteeNode.js';
+
+// Schema extraction
+export { InterfaceSchemaExtractor, GraphSchemaExtractor } from './schema/index.js';
+export type {
+  InterfaceSchema,
+  PropertySchema,
+  ExtractOptions,
+  GraphSchema,
+  NodeTypeSchema,
+  EdgeTypeSchema,
+  GraphExtractOptions,
+} from './schema/index.js';
+
+// Knowledge Base
+export { KnowledgeBase, SemanticAddressResolver, parseSemanticAddress, parseFrontmatter, parseKBNode, serializeKBNode, parseEdgesFile, appendEdge, parseYamlArrayFile, GitIngest, parseGitLog, normalizeAuthors, getChurn, getCoChanges, getOwnership, getArchaeology } from './knowledge/index.js';
+export type { ResolverBackend } from './knowledge/index.js';
+export type {
+  KBNodeType,
+  KBLifecycle,
+  KBScope,
+  KBNodeBase,
+  KBDecision,
+  KBFact,
+  KBSession,
+  KBNode,
+  KBEdge,
+  KBStats,
+  KBQueryFilter,
+  ParsedSemanticAddress,
+  ResolvedAddress,
+  DanglingCodeRef,
+} from './knowledge/index.js';
+export type { RawCommit, FileChange, AuthorEntry, CommitEntry, IngestResult, Meta } from './knowledge/index.js';
+export type { ChurnEntry, CoChangeEntry, OwnershipEntry, ArchaeologyEntry } from './knowledge/index.js';
+
+// Graph Query Utilities
+export { findCallsInFunction, findContainingFunction, traceValues, aggregateValues, NONDETERMINISTIC_PATTERNS, NONDETERMINISTIC_OBJECTS } from './queries/index.js';
+export { traceDataflow, traceForwardBFS, traceBackwardBFS } from './queries/index.js';
+export { buildNodeContext, getNodeDisplayName, formatEdgeMetadata, STRUCTURAL_EDGE_TYPES } from './queries/index.js';
+export type {
+  CallInfo,
+  CallerInfo,
+  FindCallsOptions,
+  TracedValue,
+  ValueSource,
+  UnknownReason,
+  TraceValuesOptions,
+  ValueSetResult,
+  TraceValuesGraphBackend,
+  NondeterministicPattern,
+  EdgeWithNode,
+  EdgeGroup,
+  SourcePreview,
+  NodeContext,
+  BuildNodeContextOptions,
+  DataflowNode,
+  DataflowEdge,
+  DataflowBackend,
+  TraceDataflowOptions,
+  TraceDataflowResult,
+} from './queries/index.js';
+
+// Notation — DSL rendering engine
+export { EDGE_ARCHETYPE_MAP, lookupEdge, generateLegend, PERSPECTIVES, renderNotation, extractSubgraph, shortenName, renderTraceNarrative } from './notation/index.js';
+export type {
+  Archetype,
+  EdgeMapping,
+  DescribeOptions,
+  SubgraphData,
+  NotationBlock,
+  NotationLine,
+  TraceDetail,
+  TraceNarrativeOptions,
+} from './notation/index.js';
+
+// Re-export types for convenience
+export type * from '@grafema/types';

package/src/instructions/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Grafema instruction documents for AI agents.
+ *
+ * Instructions are markdown documents that guide agent behavior.
+ * They are read at runtime from the installed package.
+ */
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Get the onboarding instruction document.
+ *
+ * Returns the full markdown text of the onboarding procedure
+ * that guides an AI agent through project study and configuration.
+ */
+export function getOnboardingInstruction(): string {
+  return readFileSync(join(__dirname, 'onboarding.md'), 'utf-8');
+}