@grafema/util 0.3.0-beta

package/dist/diagnostics/categories.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Diagnostic Categories - Single source of truth for category/code mappings
+ *
+ * This module defines diagnostic categories once and derives both mapping
+ * directions:
+ * - DIAGNOSTIC_CATEGORIES: category → codes (used by CLI check command)
+ * - CODE_TO_CATEGORY: code → category metadata (used by DiagnosticReporter)
+ *
+ * Adding a new diagnostic code requires updating only this file.
+ */
+/**
+ * Category definition with human-readable metadata and associated codes
+ */
+export interface DiagnosticCategory {
+    /** Human-readable name for display */
+    readonly name: string;
+    /** Description of what this category checks */
+    readonly description: string;
+    /** Diagnostic codes that belong to this category */
+    readonly codes: readonly string[];
+}
+/**
+ * Valid category keys
+ */
+export type DiagnosticCategoryKey = 'connectivity' | 'calls' | 'dataflow' | 'imports';
+/**
+ * Canonical definition of all diagnostic categories
+ *
+ * This is the SINGLE SOURCE OF TRUTH for category mappings.
+ * Both CLI and DiagnosticReporter derive their mappings from this.
+ */
+export declare const DIAGNOSTIC_CATEGORIES: Record<DiagnosticCategoryKey, DiagnosticCategory>;
+/**
+ * Metadata for code-to-category lookup (used by DiagnosticReporter)
+ */
+export interface CodeCategoryInfo {
+    /** Human-readable name for the issue type */
+    name: string;
+    /** CLI command to check this category */
+    checkCommand: string;
+}
+/**
+ * Derived mapping: code → category metadata
+ *
+ * Auto-generated from DIAGNOSTIC_CATEGORIES.
+ * Used by DiagnosticReporter to show actionable commands.
+ */
+export declare const CODE_TO_CATEGORY: Record<string, CodeCategoryInfo>;
+/**
+ * Get category for a diagnostic code
+ */
+export declare function getCategoryForCode(code: string): CodeCategoryInfo | undefined;
+/**
+ * Get all codes for a category
+ */
+export declare function getCodesForCategory(category: DiagnosticCategoryKey): readonly string[];
+//# sourceMappingURL=categories.d.ts.map

package/dist/diagnostics/categories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"categories.d.ts","sourceRoot":"","sources":["../../src/diagnostics/categories.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,cAAc,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;AAEtF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,qBAAqB,EAAE,kBAAkB,CAqBnF,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAgB1D,CAAC;AAEL;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAE7E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,SAAS,MAAM,EAAE,CAEtF"}

package/dist/diagnostics/categories.js

@@ -0,0 +1,71 @@
+/**
+ * Diagnostic Categories - Single source of truth for category/code mappings
+ *
+ * This module defines diagnostic categories once and derives both mapping
+ * directions:
+ * - DIAGNOSTIC_CATEGORIES: category → codes (used by CLI check command)
+ * - CODE_TO_CATEGORY: code → category metadata (used by DiagnosticReporter)
+ *
+ * Adding a new diagnostic code requires updating only this file.
+ */
+/**
+ * Canonical definition of all diagnostic categories
+ *
+ * This is the SINGLE SOURCE OF TRUTH for category mappings.
+ * Both CLI and DiagnosticReporter derive their mappings from this.
+ */
+export const DIAGNOSTIC_CATEGORIES = {
+    connectivity: {
+        name: 'Graph Connectivity',
+        description: 'Check for disconnected nodes in the graph',
+        codes: ['ERR_DISCONNECTED_NODES', 'ERR_DISCONNECTED_NODE'],
+    },
+    calls: {
+        name: 'Call Resolution',
+        description: 'Check for unresolved function calls',
+        codes: ['ERR_UNRESOLVED_CALL'],
+    },
+    dataflow: {
+        name: 'Data Flow',
+        description: 'Check for missing assignments and broken references',
+        codes: ['ERR_MISSING_ASSIGNMENT', 'ERR_BROKEN_REFERENCE', 'ERR_NO_LEAF_NODE'],
+    },
+    imports: {
+        name: 'Import Validation',
+        description: 'Check for broken imports and undefined symbols',
+        codes: ['ERR_BROKEN_IMPORT', 'ERR_UNDEFINED_SYMBOL'],
+    },
+};
+/**
+ * Derived mapping: code → category metadata
+ *
+ * Auto-generated from DIAGNOSTIC_CATEGORIES.
+ * Used by DiagnosticReporter to show actionable commands.
+ */
+export const CODE_TO_CATEGORY = (() => {
+    const result = {};
+    for (const [categoryKey, category] of Object.entries(DIAGNOSTIC_CATEGORIES)) {
+        // Generate human-readable name from category name (lowercase, plural)
+        const issueName = category.name.toLowerCase().replace('graph ', '');
+        for (const code of category.codes) {
+            result[code] = {
+                name: issueName,
+                checkCommand: `grafema check ${categoryKey}`,
+            };
+        }
+    }
+    return result;
+})();
+/**
+ * Get category for a diagnostic code
+ */
+export function getCategoryForCode(code) {
+    return CODE_TO_CATEGORY[code];
+}
+/**
+ * Get all codes for a category
+ */
+export function getCodesForCategory(category) {
+    return DIAGNOSTIC_CATEGORIES[category].codes;
+}
+//# sourceMappingURL=categories.js.map

package/dist/diagnostics/categories.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"categories.js","sourceRoot":"","sources":["../../src/diagnostics/categories.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAmBH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAsD;IACtF,YAAY,EAAE;QACZ,IAAI,EAAE,oBAAoB;QAC1B,WAAW,EAAE,2CAA2C;QACxD,KAAK,EAAE,CAAC,wBAAwB,EAAE,uBAAuB,CAAC;KAC3D;IACD,KAAK,EAAE;QACL,IAAI,EAAE,iBAAiB;QACvB,WAAW,EAAE,qCAAqC;QAClD,KAAK,EAAE,CAAC,qBAAqB,CAAC;KAC/B;IACD,QAAQ,EAAE;QACR,IAAI,EAAE,WAAW;QACjB,WAAW,EAAE,qDAAqD;QAClE,KAAK,EAAE,CAAC,wBAAwB,EAAE,sBAAsB,EAAE,kBAAkB,CAAC;KAC9E;IACD,OAAO,EAAE;QACP,IAAI,EAAE,mBAAmB;QACzB,WAAW,EAAE,gDAAgD;QAC7D,KAAK,EAAE,CAAC,mBAAmB,EAAE,sBAAsB,CAAC;KACrD;CACF,CAAC;AAYF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAqC,CAAC,GAAG,EAAE;IACtE,MAAM,MAAM,GAAqC,EAAE,CAAC;IAEpD,KAAK,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,qBAAqB,CAAC,EAAE,CAAC;QAC5E,sEAAsE;QACtE,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAEpE,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YAClC,MAAM,CAAC,IAAI,CAAC,GAAG;gBACb,IAAI,EAAE,SAAS;gBACf,YAAY,EAAE,iBAAiB,WAAW,EAAE;aAC7C,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC,EAAE,CAAC;AAEL;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAA+B;IACjE,OAAO,qBAAqB,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC;AAC/C,CAAC"}

package/dist/diagnostics/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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
+ * - categories: Single source of truth for diagnostic category mappings
+ */
+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';
+export { DIAGNOSTIC_CATEGORIES, CODE_TO_CATEGORY, getCategoryForCode, getCodesForCategory, } from './categories.js';
+export type { DiagnosticCategory, DiagnosticCategoryKey, CodeCategoryInfo, } from './categories.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/diagnostics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/diagnostics/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAE5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEnH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGzD,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC"}

package/dist/diagnostics/index.js

@@ -0,0 +1,15 @@
+/**
+ * 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
+ * - categories: Single source of truth for diagnostic category mappings
+ */
+export { DiagnosticCollector } from './DiagnosticCollector.js';
+export { DiagnosticReporter } from './DiagnosticReporter.js';
+export { DiagnosticWriter } from './DiagnosticWriter.js';
+// Category mappings (single source of truth)
+export { DIAGNOSTIC_CATEGORIES, CODE_TO_CATEGORY, getCategoryForCode, getCodesForCategory, } from './categories.js';
+//# sourceMappingURL=index.js.map

package/dist/diagnostics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/diagnostics/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAG/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAG7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,6CAA6C;AAC7C,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC"}

package/dist/errors/GrafemaError.d.ts

@@ -0,0 +1,200 @@
+/**
+ * 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 declare 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);
+    /**
+     * Serialize error to JSON for diagnostics.log
+     */
+    toJSON(): GrafemaErrorJSON;
+}
+/**
+ * Configuration error - config.json parsing, validation, missing required fields
+ *
+ * Severity: fatal (always)
+ * Codes: ERR_CONFIG_INVALID, ERR_CONFIG_MISSING_FIELD
+ */
+export declare class ConfigError extends GrafemaError {
+    readonly code: string;
+    readonly severity: "fatal";
+    constructor(message: string, code: string, context?: ErrorContext, suggestion?: string);
+}
+/**
+ * File access error - unreadable files, missing git, permissions
+ *
+ * Severity: error (default)
+ * Codes: ERR_FILE_UNREADABLE, ERR_GIT_NOT_FOUND, ERR_GIT_ACCESS_DENIED
+ */
+export declare class FileAccessError extends GrafemaError {
+    readonly code: string;
+    readonly severity: "error";
+    constructor(message: string, code: string, context?: ErrorContext, suggestion?: string);
+}
+/**
+ * Language error - unsupported file type, unparseable syntax
+ *
+ * Severity: warning (always)
+ * Codes: ERR_UNSUPPORTED_LANG, ERR_PARSE_FAILURE
+ */
+export declare class LanguageError extends GrafemaError {
+    readonly code: string;
+    readonly severity: "warning";
+    constructor(message: string, code: string, context?: ErrorContext, suggestion?: string);
+}
+/**
+ * Database error - RFDB connection, corruption, lock
+ *
+ * Severity: fatal (always)
+ * Codes: ERR_DATABASE_LOCKED, ERR_DATABASE_CORRUPTED
+ */
+export declare class DatabaseError extends GrafemaError {
+    readonly code: string;
+    readonly severity: "fatal";
+    constructor(message: string, code: string, context?: ErrorContext, suggestion?: string);
+}
+/**
+ * Plugin error - plugin execution failed, dependency missing
+ *
+ * Severity: error (default)
+ * Codes: ERR_PLUGIN_FAILED, ERR_PLUGIN_DEPENDENCY_MISSING
+ */
+export declare class PluginError extends GrafemaError {
+    readonly code: string;
+    readonly severity: "error";
+    constructor(message: string, code: string, context?: ErrorContext, suggestion?: string);
+}
+/**
+ * Analysis error - internal analyzer failure, timeout
+ *
+ * Severity: error (default)
+ * Codes: ERR_ANALYSIS_TIMEOUT, ERR_ANALYSIS_INTERNAL
+ */
+export declare class AnalysisError extends GrafemaError {
+    readonly code: string;
+    readonly severity: "error";
+    constructor(message: string, code: string, context?: ErrorContext, suggestion?: string);
+}
+/**
+ * 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 declare 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');
+}
+/**
+ * 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 declare class StrictModeError extends GrafemaError {
+    readonly code: string;
+    readonly severity: "fatal";
+    constructor(message: string, code: string, context?: ErrorContext, suggestion?: string);
+}
+/**
+ * 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' | 'class_not_imported' | 'method_not_found' | 'external_dependency' | 'circular_reference' | 'builtin_method' | 'unknown';
+/**
+ * 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 declare 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);
+}
+//# sourceMappingURL=GrafemaError.d.ts.map

package/dist/errors/GrafemaError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GrafemaError.d.ts","sourceRoot":"","sources":["../../src/errors/GrafemaError.ts"],"names":[],"mappings":"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"}

package/dist/errors/GrafemaError.js

@@ -0,0 +1,209 @@
+/**
+ * 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)
+ */
+/**
+ * Abstract base class for all Grafema errors.
+ *
+ * Extends native Error for compatibility with PluginResult.errors[].
+ */
+export class GrafemaError extends Error {
+    context;
+    suggestion;
+    constructor(message, context = {}, suggestion) {
+        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() {
+        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 {
+    code;
+    severity = 'fatal';
+    constructor(message, code, context = {}, suggestion) {
+        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 {
+    code;
+    severity = 'error';
+    constructor(message, code, context = {}, suggestion) {
+        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 {
+    code;
+    severity = 'warning';
+    constructor(message, code, context = {}, suggestion) {
+        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 {
+    code;
+    severity = 'fatal';
+    constructor(message, code, context = {}, suggestion) {
+        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 {
+    code;
+    severity = 'error';
+    constructor(message, code, context = {}, suggestion) {
+        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 {
+    code;
+    severity = 'error';
+    constructor(message, code, context = {}, suggestion) {
+        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 {
+    code;
+    severity;
+    constructor(message, code, context = {}, suggestion, severity = '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 {
+    code;
+    severity = 'fatal';
+    constructor(message, code, context = {}, suggestion) {
+        super(message, context, suggestion);
+        this.code = code;
+    }
+}
+/**
+ * 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 */
+    diagnostics;
+    /** Error count for summary */
+    count;
+    /** REG-332: Number of errors suppressed by grafema-ignore comments */
+    suppressedCount;
+    constructor(diagnostics, suppressedCount = 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);
+    }
+}
+//# sourceMappingURL=GrafemaError.js.map

package/dist/errors/GrafemaError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GrafemaError.js","sourceRoot":"","sources":["../../src/errors/GrafemaError.ts"],"names":[],"mappings":"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"}