@unrdf/kgc-probe 26.4.2

package/src/utils/errors.mjs

@@ -0,0 +1,397 @@
+/**
+ * @fileoverview KGC Probe - Custom Error Classes
+ *
+ * Provides structured error types with:
+ * - Error codes for programmatic handling
+ * - Context information for debugging
+ * - Recovery suggestions for users
+ *
+ * @module @unrdf/kgc-probe/utils/errors
+ */
+
+/**
+ * Base error for KGC Probe operations
+ *
+ * @class ProbeError
+ * @extends Error
+ * @example
+ * throw new ProbeError('Operation failed', 'OP_FAILED', { operation: 'scan' });
+ */
+export class ProbeError extends Error {
+  /**
+   * @param {string} message - Error message
+   * @param {string} [code='PROBE_ERROR'] - Error code
+   * @param {Object} [context] - Additional context
+   * @param {string} [recovery] - Recovery suggestion
+   */
+  constructor(message, code = 'PROBE_ERROR', context = {}, recovery = undefined) {
+    super(message);
+    this.name = 'ProbeError';
+
+    /** @type {string} */
+    this.code = code;
+
+    /** @type {Object} */
+    this.context = context;
+
+    /** @type {string | undefined} */
+    this.recovery = recovery;
+
+    /** @type {string} */
+    this.timestamp = new Date().toISOString();
+
+    // Capture stack trace
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  /**
+   * Convert to JSON for logging
+   * @returns {Object}
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      context: this.context,
+      recovery: this.recovery,
+      timestamp: this.timestamp,
+      stack: this.stack
+    };
+  }
+
+  /**
+   * Create from unknown error
+   * @param {unknown} error - Unknown error
+   * @param {string} [code] - Override code
+   * @returns {ProbeError}
+   */
+  static from(error, code) {
+    if (error instanceof ProbeError) {
+      return error;
+    }
+
+    if (error instanceof Error) {
+      return new ProbeError(error.message, code || 'UNKNOWN_ERROR', {
+        originalName: error.name,
+        originalStack: error.stack
+      });
+    }
+
+    return new ProbeError(String(error), code || 'UNKNOWN_ERROR');
+  }
+}
+
+/**
+ * Error thrown when a guard blocks an operation
+ *
+ * @class GuardViolationError
+ * @extends ProbeError
+ * @example
+ * throw new GuardViolationError(
+ *   'Access to AWS credentials forbidden',
+ *   'G-H1-ENV-TOKEN',
+ *   { variable: 'AWS_SECRET_KEY', pattern: 'AWS_*' },
+ *   'receipt-123'
+ * );
+ */
+export class GuardViolationError extends ProbeError {
+  /**
+   * @param {string} message - Error message
+   * @param {string} guardId - Guard that blocked the operation
+   * @param {Object} [context] - Additional context
+   * @param {string} [receiptId] - Denial receipt ID
+   */
+  constructor(message, guardId, context = {}, receiptId = undefined) {
+    super(message, 'GUARD_VIOLATION', {
+      ...context,
+      guardId,
+      receiptId
+    }, 'Check guard policy configuration or request access exemption');
+
+    this.name = 'GuardViolationError';
+
+    /** @type {string} */
+    this.guardId = guardId;
+
+    /** @type {string | undefined} */
+    this.receiptId = receiptId;
+  }
+}
+
+/**
+ * Error thrown when input validation fails
+ *
+ * @class ValidationError
+ * @extends ProbeError
+ * @example
+ * throw new ValidationError('Invalid universe ID', { field: 'universe_id', value: null });
+ */
+export class ValidationError extends ProbeError {
+  /**
+   * @param {string} message - Error message
+   * @param {Object} [context] - Validation context
+   * @param {string} [field] - Field that failed validation
+   */
+  constructor(message, context = {}, field = undefined) {
+    super(message, 'VALIDATION_ERROR', {
+      ...context,
+      field
+    }, 'Check input format and required fields');
+
+    this.name = 'ValidationError';
+
+    /** @type {string | undefined} */
+    this.field = field;
+
+    /** @type {any} */
+    this.issues = context.issues || [];
+  }
+
+  /**
+   * Create from Zod error
+   * @param {import('zod').ZodError} zodError - Zod validation error
+   * @returns {ValidationError}
+   */
+  static fromZod(zodError) {
+    const issues = zodError.issues.map(i => ({
+      path: i.path.join('.'),
+      message: i.message,
+      code: i.code
+    }));
+
+    const firstIssue = issues[0];
+    return new ValidationError(
+      `Validation failed: ${firstIssue?.message || 'Invalid input'}`,
+      { issues },
+      firstIssue?.path
+    );
+  }
+}
+
+/**
+ * Error thrown when shard merge conflicts occur
+ *
+ * @class MergeConflictError
+ * @extends ProbeError
+ * @example
+ * throw new MergeConflictError('Conflicting claims detected', [
+ *   { claimId: 'cap-1', agents: ['agent-1', 'agent-2'] }
+ * ]);
+ */
+export class MergeConflictError extends ProbeError {
+  /**
+   * @param {string} message - Error message
+   * @param {Array<{claimId: string, agents: string[]}>} conflicts - Conflict details
+   */
+  constructor(message, conflicts = []) {
+    super(message, 'MERGE_CONFLICT', {
+      conflicts,
+      conflictCount: conflicts.length
+    }, 'Use --on-conflict=list to review conflicts or --on-conflict=merge to auto-resolve');
+
+    this.name = 'MergeConflictError';
+
+    /** @type {Array<{claimId: string, agents: string[]}>} */
+    this.conflicts = conflicts;
+  }
+}
+
+/**
+ * Error thrown when receipt verification fails
+ *
+ * @class ReceiptError
+ * @extends ProbeError
+ * @example
+ * throw new ReceiptError('Hash chain verification failed', {
+ *   expectedHash: '0xabc...',
+ *   actualHash: '0xdef...'
+ * });
+ */
+export class ReceiptError extends ProbeError {
+  /**
+   * @param {string} message - Error message
+   * @param {Object} [context] - Receipt context
+   * @param {string} [verificationStep] - Which verification step failed
+   */
+  constructor(message, context = {}, verificationStep = undefined) {
+    super(message, 'RECEIPT_ERROR', {
+      ...context,
+      verificationStep
+    }, 'Regenerate receipts or check artifact integrity');
+
+    this.name = 'ReceiptError';
+
+    /** @type {string | undefined} */
+    this.verificationStep = verificationStep;
+  }
+}
+
+/**
+ * Error thrown when artifact is not found
+ *
+ * @class ArtifactNotFoundError
+ * @extends ProbeError
+ * @example
+ * throw new ArtifactNotFoundError('run-123');
+ */
+export class ArtifactNotFoundError extends ProbeError {
+  /**
+   * @param {string} artifactId - Missing artifact ID
+   * @param {string} [path] - Path searched
+   */
+  constructor(artifactId, path = undefined) {
+    super(`Artifact not found: ${artifactId}`, 'ARTIFACT_NOT_FOUND', {
+      artifactId,
+      path
+    }, 'Run a probe scan first or check the artifact path');
+
+    this.name = 'ArtifactNotFoundError';
+
+    /** @type {string} */
+    this.artifactId = artifactId;
+  }
+}
+
+/**
+ * Error thrown when command execution times out
+ *
+ * @class TimeoutError
+ * @extends ProbeError
+ * @example
+ * throw new TimeoutError('Scan timed out', 30000);
+ */
+export class TimeoutError extends ProbeError {
+  /**
+   * @param {string} message - Error message
+   * @param {number} timeoutMs - Timeout in milliseconds
+   * @param {string} [operation] - Operation that timed out
+   */
+  constructor(message, timeoutMs, operation = undefined) {
+    super(message, 'TIMEOUT', {
+      timeoutMs,
+      operation
+    }, 'Increase --timeout value or check for performance issues');
+
+    this.name = 'TimeoutError';
+
+    /** @type {number} */
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+/**
+ * Error thrown when agent execution fails
+ *
+ * @class AgentError
+ * @extends ProbeError
+ * @example
+ * throw new AgentError('Agent failed', 'completeness-agent', new Error('Query failed'));
+ */
+export class AgentError extends ProbeError {
+  /**
+   * @param {string} message - Error message
+   * @param {string} agentId - Agent that failed
+   * @param {Error} [cause] - Underlying error
+   */
+  constructor(message, agentId, cause = undefined) {
+    super(message, 'AGENT_ERROR', {
+      agentId,
+      cause: cause?.message
+    }, 'Check agent configuration and dependencies');
+
+    this.name = 'AgentError';
+
+    /** @type {string} */
+    this.agentId = agentId;
+
+    /** @type {Error | undefined} */
+    this.cause = cause;
+  }
+}
+
+/**
+ * Error thrown when storage operation fails
+ *
+ * @class StorageError
+ * @extends ProbeError
+ * @example
+ * throw new StorageError('Failed to write artifact', 'write', { path: '/tmp/artifact.json' });
+ */
+export class StorageError extends ProbeError {
+  /**
+   * @param {string} message - Error message
+   * @param {string} operation - Storage operation (read|write|delete)
+   * @param {Object} [context] - Additional context
+   */
+  constructor(message, operation, context = {}) {
+    super(message, 'STORAGE_ERROR', {
+      ...context,
+      operation
+    }, 'Check storage permissions and disk space');
+
+    this.name = 'StorageError';
+
+    /** @type {string} */
+    this.operation = operation;
+  }
+}
+
+/**
+ * Error thrown when configuration is invalid
+ *
+ * @class ConfigurationError
+ * @extends ProbeError
+ * @example
+ * throw new ConfigurationError('Invalid config file', { path: '.kgc-probe.json' });
+ */
+export class ConfigurationError extends ProbeError {
+  /**
+   * @param {string} message - Error message
+   * @param {Object} [context] - Configuration context
+   */
+  constructor(message, context = {}) {
+    super(message, 'CONFIG_ERROR', context, 'Check configuration file format and required fields');
+
+    this.name = 'ConfigurationError';
+  }
+}
+
+/**
+ * Error code constants
+ * @type {Object<string, string>}
+ */
+export const ErrorCodes = {
+  PROBE_ERROR: 'PROBE_ERROR',
+  GUARD_VIOLATION: 'GUARD_VIOLATION',
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  MERGE_CONFLICT: 'MERGE_CONFLICT',
+  RECEIPT_ERROR: 'RECEIPT_ERROR',
+  ARTIFACT_NOT_FOUND: 'ARTIFACT_NOT_FOUND',
+  TIMEOUT: 'TIMEOUT',
+  AGENT_ERROR: 'AGENT_ERROR',
+  STORAGE_ERROR: 'STORAGE_ERROR',
+  CONFIG_ERROR: 'CONFIG_ERROR',
+  UNKNOWN_ERROR: 'UNKNOWN_ERROR'
+};
+
+/**
+ * Check if error is a ProbeError
+ * @param {unknown} error - Error to check
+ * @returns {boolean}
+ */
+export function isProbeError(error) {
+  return error instanceof ProbeError;
+}
+
+/**
+ * Wrap error in ProbeError if not already
+ * @param {unknown} error - Error to wrap
+ * @param {string} [code] - Error code
+ * @returns {ProbeError}
+ */
+export function wrapError(error, code) {
+  return ProbeError.from(error, code);
+}

package/src/utils/index.mjs

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview KGC Probe - Utilities Index
+ *
+ * Re-exports all utility modules for convenience.
+ *
+ * @module @unrdf/kgc-probe/utils
+ */
+
+// Logger
+export {
+  Logger,
+  createLogger,
+  defaultLogger,
+  LOG_LEVELS
+} from './logger.mjs';
+
+// Error classes
+export {
+  ProbeError,
+  GuardViolationError,
+  ValidationError,
+  MergeConflictError,
+  ReceiptError,
+  ArtifactNotFoundError,
+  TimeoutError,
+  AgentError,
+  StorageError,
+  ConfigurationError,
+  ErrorCodes,
+  isProbeError,
+  wrapError
+} from './errors.mjs';

package/src/utils/logger.mjs

@@ -0,0 +1,236 @@
+/**
+ * @fileoverview KGC Probe - Structured Logger
+ *
+ * Simple, structured logging utility for observability.
+ * No external dependencies - outputs JSON for log aggregation.
+ *
+ * @module @unrdf/kgc-probe/utils/logger
+ */
+
+/**
+ * Log levels in order of severity
+ * @type {Object<string, number>}
+ */
+const LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  silent: 4
+};
+
+/**
+ * Logger configuration
+ * @typedef {Object} LoggerConfig
+ * @property {string} [level='info'] - Minimum log level
+ * @property {boolean} [json=true] - Output JSON format
+ * @property {string} [prefix=''] - Log prefix
+ * @property {boolean} [timestamps=true] - Include timestamps
+ * @property {Function} [output] - Custom output function
+ */
+
+/**
+ * Structured log entry
+ * @typedef {Object} LogEntry
+ * @property {string} level - Log level
+ * @property {string} message - Log message
+ * @property {string} [timestamp] - ISO timestamp
+ * @property {Object} [context] - Additional context
+ */
+
+/**
+ * Logger - Structured logging with JSON output
+ *
+ * @class Logger
+ * @example
+ * const logger = createLogger({ prefix: 'kgc-probe' });
+ * logger.info('Scan started', { universe: 'my-universe' });
+ * logger.error('Scan failed', { error: err.message });
+ */
+export class Logger {
+  /**
+   * Create logger instance
+   * @param {LoggerConfig} [config] - Logger configuration
+   */
+  constructor(config = {}) {
+    /** @type {string} */
+    this.level = config.level || 'info';
+
+    /** @type {boolean} */
+    this.json = config.json !== false;
+
+    /** @type {string} */
+    this.prefix = config.prefix || '';
+
+    /** @type {boolean} */
+    this.timestamps = config.timestamps !== false;
+
+    /** @type {Function} */
+    this.output = config.output || console.log;
+
+    /** @type {Function} */
+    this.errorOutput = config.errorOutput || console.error;
+  }
+
+  /**
+   * Check if level should be logged
+   * @private
+   * @param {string} level - Level to check
+   * @returns {boolean}
+   */
+  shouldLog(level) {
+    return LOG_LEVELS[level] >= LOG_LEVELS[this.level];
+  }
+
+  /**
+   * Format log entry
+   * @private
+   * @param {string} level - Log level
+   * @param {string} message - Log message
+   * @param {Object} [context] - Additional context
+   * @returns {string}
+   */
+  format(level, message, context) {
+    /** @type {LogEntry} */
+    const entry = {
+      level,
+      message: this.prefix ? `[${this.prefix}] ${message}` : message
+    };
+
+    if (this.timestamps) {
+      entry.timestamp = new Date().toISOString();
+    }
+
+    if (context && Object.keys(context).length > 0) {
+      entry.context = context;
+    }
+
+    if (this.json) {
+      return JSON.stringify(entry);
+    }
+
+    // Human-readable format
+    const ts = this.timestamps ? `[${entry.timestamp}] ` : '';
+    const ctx = context ? ` ${JSON.stringify(context)}` : '';
+    return `${ts}${level.toUpperCase()}: ${entry.message}${ctx}`;
+  }
+
+  /**
+   * Log debug message
+   * @param {string} message - Log message
+   * @param {Object} [context] - Additional context
+   */
+  debug(message, context) {
+    if (this.shouldLog('debug')) {
+      this.output(this.format('debug', message, context));
+    }
+  }
+
+  /**
+   * Log info message
+   * @param {string} message - Log message
+   * @param {Object} [context] - Additional context
+   */
+  info(message, context) {
+    if (this.shouldLog('info')) {
+      this.output(this.format('info', message, context));
+    }
+  }
+
+  /**
+   * Log warning message
+   * @param {string} message - Log message
+   * @param {Object} [context] - Additional context
+   */
+  warn(message, context) {
+    if (this.shouldLog('warn')) {
+      this.errorOutput(this.format('warn', message, context));
+    }
+  }
+
+  /**
+   * Log error message
+   * @param {string} message - Log message
+   * @param {Object} [context] - Additional context
+   */
+  error(message, context) {
+    if (this.shouldLog('error')) {
+      this.errorOutput(this.format('error', message, context));
+    }
+  }
+
+  /**
+   * Create child logger with additional prefix
+   * @param {string} childPrefix - Child prefix
+   * @returns {Logger}
+   */
+  child(childPrefix) {
+    const newPrefix = this.prefix
+      ? `${this.prefix}:${childPrefix}`
+      : childPrefix;
+
+    return new Logger({
+      level: this.level,
+      json: this.json,
+      prefix: newPrefix,
+      timestamps: this.timestamps,
+      output: this.output,
+      errorOutput: this.errorOutput
+    });
+  }
+
+  /**
+   * Set log level
+   * @param {string} level - New log level
+   */
+  setLevel(level) {
+    if (LOG_LEVELS[level] === undefined) {
+      throw new Error(`Invalid log level: ${level}`);
+    }
+    this.level = level;
+  }
+
+  /**
+   * Log with timing
+   * @param {string} message - Log message
+   * @param {Function} fn - Function to time
+   * @returns {Promise<any>} Function result
+   */
+  async timed(message, fn) {
+    const start = Date.now();
+    try {
+      const result = await fn();
+      const duration = Date.now() - start;
+      this.info(message, { duration_ms: duration, status: 'success' });
+      return result;
+    } catch (err) {
+      const duration = Date.now() - start;
+      this.error(message, { duration_ms: duration, status: 'error', error: err.message });
+      throw err;
+    }
+  }
+}
+
+/**
+ * Create logger instance
+ * @param {LoggerConfig} [config] - Logger configuration
+ * @returns {Logger}
+ * @example
+ * const logger = createLogger({ prefix: 'my-module', level: 'debug' });
+ * logger.info('Hello', { key: 'value' });
+ */
+export function createLogger(config) {
+  return new Logger(config);
+}
+
+/**
+ * Default logger instance
+ * @type {Logger}
+ */
+export const defaultLogger = createLogger({ prefix: 'kgc-probe' });
+
+/**
+ * Log levels constant
+ * @type {Object<string, number>}
+ */
+export { LOG_LEVELS };