@grafema/util 0.3.0-beta

package/dist/core/nodes/IssueNode.d.ts

@@ -0,0 +1,73 @@
+/**
+ * IssueNode - contract for issue:* nodes
+ *
+ * Types: issue:security, issue:performance, issue:style, issue:smell
+ * ID format: issue:<category>#<hash>
+ *
+ * Issues represent detected problems in the codebase.
+ * They connect to affected code via AFFECTS edges.
+ */
+import type { BaseNodeRecord } from '@grafema/types';
+export type IssueSeverity = 'error' | 'warning' | 'info';
+export type IssueType = `issue:${string}`;
+export interface IssueNodeRecord extends BaseNodeRecord {
+    type: IssueType;
+    severity: IssueSeverity;
+    category: string;
+    message: string;
+    plugin: string;
+    targetNodeId?: string;
+    createdAt: number;
+    context?: Record<string, unknown>;
+}
+export interface IssueNodeOptions {
+    context?: Record<string, unknown>;
+}
+export declare class IssueNode {
+    static readonly REQUIRED: readonly ["category", "severity", "message", "plugin", "file"];
+    static readonly OPTIONAL: readonly ["targetNodeId", "context"];
+    /**
+     * Generate deterministic issue ID
+     * Format: issue:<category>#<hash12>
+     *
+     * Hash is based on plugin + file + line + column + message
+     * This ensures same issue = same ID across analysis runs
+     */
+    static generateId(category: string, plugin: string, file: string, line: number, column: number, message: string): string;
+    /**
+     * Create issue node
+     *
+     * @param category - Issue category (security, performance, style, smell, or custom)
+     * @param severity - error | warning | info
+     * @param message - Human-readable description
+     * @param plugin - Plugin name that detected this issue
+     * @param file - File where issue was detected
+     * @param line - Line number
+     * @param column - Column number (optional, defaults to 0)
+     * @param options - Optional fields (context)
+     */
+    static create(category: string, severity: IssueSeverity, message: string, plugin: string, file: string, line: number, column?: number, options?: IssueNodeOptions): IssueNodeRecord;
+    /**
+     * Validate issue node
+     * @returns array of error messages, empty if valid
+     */
+    static validate(node: IssueNodeRecord): string[];
+    /**
+     * Parse issue ID into components
+     * @param id - full ID (e.g., 'issue:security#a3f2b1c4d5e6')
+     * @returns { category, hash } or null if invalid
+     */
+    static parseId(id: string): {
+        category: string;
+        hash: string;
+    } | null;
+    /**
+     * Check if type is an issue type
+     */
+    static isIssueType(type: string): boolean;
+    /**
+     * Get all known issue categories
+     */
+    static getCategories(): string[];
+}
+//# sourceMappingURL=IssueNode.d.ts.map

package/dist/core/nodes/IssueNode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IssueNode.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/IssueNode.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAIrD,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAGzD,MAAM,MAAM,SAAS,GAAG,SAAS,MAAM,EAAE,CAAC;AAE1C,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAKD,qBAAa,SAAS;IACpB,MAAM,CAAC,QAAQ,CAAC,QAAQ,iEAAkE;IAC1F,MAAM,CAAC,QAAQ,CAAC,QAAQ,uCAAwC;IAEhE;;;;;;OAMG;IACH,MAAM,CAAC,UAAU,CACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,MAAM;IAMT;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,MAAM,CACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,aAAa,EACvB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,MAAU,EAClB,OAAO,GAAE,gBAAqB,GAC7B,eAAe;IA8BlB;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,EAAE;IA4BhD;;;;OAIG;IACH,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAYrE;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAKzC;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,MAAM,EAAE;CAGjC"}

package/dist/core/nodes/IssueNode.js

@@ -0,0 +1,130 @@
+/**
+ * IssueNode - contract for issue:* nodes
+ *
+ * Types: issue:security, issue:performance, issue:style, issue:smell
+ * ID format: issue:<category>#<hash>
+ *
+ * Issues represent detected problems in the codebase.
+ * They connect to affected code via AFFECTS edges.
+ */
+import { createHash } from 'crypto';
+import { getNamespace } from './NodeKind.js';
+// Valid severity levels
+const VALID_SEVERITIES = ['error', 'warning', 'info'];
+export class IssueNode {
+    static REQUIRED = ['category', 'severity', 'message', 'plugin', 'file'];
+    static OPTIONAL = ['targetNodeId', 'context'];
+    /**
+     * Generate deterministic issue ID
+     * Format: issue:<category>#<hash12>
+     *
+     * Hash is based on plugin + file + line + column + message
+     * This ensures same issue = same ID across analysis runs
+     */
+    static generateId(category, plugin, file, line, column, message) {
+        const hashInput = `${plugin}|${file}|${line}|${column}|${message}`;
+        const hash = createHash('sha256').update(hashInput).digest('hex').substring(0, 12);
+        return `issue:${category}#${hash}`;
+    }
+    /**
+     * Create issue node
+     *
+     * @param category - Issue category (security, performance, style, smell, or custom)
+     * @param severity - error | warning | info
+     * @param message - Human-readable description
+     * @param plugin - Plugin name that detected this issue
+     * @param file - File where issue was detected
+     * @param line - Line number
+     * @param column - Column number (optional, defaults to 0)
+     * @param options - Optional fields (context)
+     */
+    static create(category, severity, message, plugin, file, line, column = 0, options = {}) {
+        if (!category)
+            throw new Error('IssueNode.create: category is required');
+        if (!severity)
+            throw new Error('IssueNode.create: severity is required');
+        if (!VALID_SEVERITIES.includes(severity)) {
+            throw new Error(`IssueNode.create: invalid severity "${severity}". Valid: ${VALID_SEVERITIES.join(', ')}`);
+        }
+        if (!message)
+            throw new Error('IssueNode.create: message is required');
+        if (!plugin)
+            throw new Error('IssueNode.create: plugin is required');
+        if (!file)
+            throw new Error('IssueNode.create: file is required');
+        const type = `issue:${category}`;
+        const id = this.generateId(category, plugin, file, line, column, message);
+        const now = Date.now();
+        return {
+            id,
+            type,
+            name: message.substring(0, 100), // Truncate for display
+            file,
+            line,
+            column,
+            severity,
+            category,
+            message,
+            plugin,
+            createdAt: now,
+            context: options.context,
+        };
+    }
+    /**
+     * Validate issue node
+     * @returns array of error messages, empty if valid
+     */
+    static validate(node) {
+        const errors = [];
+        if (!IssueNode.isIssueType(node.type)) {
+            errors.push(`Expected issue:* type, got ${node.type}`);
+        }
+        if (!node.category) {
+            errors.push('Missing required field: category');
+        }
+        if (!node.severity) {
+            errors.push('Missing required field: severity');
+        }
+        else if (!VALID_SEVERITIES.includes(node.severity)) {
+            errors.push(`Invalid severity: ${node.severity}. Valid: ${VALID_SEVERITIES.join(', ')}`);
+        }
+        if (!node.message) {
+            errors.push('Missing required field: message');
+        }
+        if (!node.plugin) {
+            errors.push('Missing required field: plugin');
+        }
+        return errors;
+    }
+    /**
+     * Parse issue ID into components
+     * @param id - full ID (e.g., 'issue:security#a3f2b1c4d5e6')
+     * @returns { category, hash } or null if invalid
+     */
+    static parseId(id) {
+        if (!id)
+            return null;
+        const match = id.match(/^issue:([^#]+)#(.+)$/);
+        if (!match)
+            return null;
+        return {
+            category: match[1],
+            hash: match[2],
+        };
+    }
+    /**
+     * Check if type is an issue type
+     */
+    static isIssueType(type) {
+        if (!type)
+            return false;
+        return getNamespace(type) === 'issue';
+    }
+    /**
+     * Get all known issue categories
+     */
+    static getCategories() {
+        return ['security', 'performance', 'style', 'smell'];
+    }
+}
+//# sourceMappingURL=IssueNode.js.map

package/dist/core/nodes/IssueNode.js.map

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

package/dist/core/nodes/NodeKind.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Node Types - string type system for nodes
+ *
+ * Base types: FUNCTION, CLASS, METHOD, etc.
+ * Namespaced types: http:route, socketio:emit, express:router, etc.
+ *
+ * Namespace convention:
+ * - http:* - HTTP endpoints and requests
+ * - express:* - Express.js specifics
+ * - socketio:* - Socket.IO
+ * - db:* - Database queries
+ * - fs:* - Filesystem operations
+ */
+export declare const NODE_TYPE: {
+    readonly FUNCTION: "FUNCTION";
+    readonly CLASS: "CLASS";
+    readonly METHOD: "METHOD";
+    readonly VARIABLE: "VARIABLE";
+    readonly PARAMETER: "PARAMETER";
+    readonly CONSTANT: "CONSTANT";
+    readonly LITERAL: "LITERAL";
+    readonly EXPRESSION: "EXPRESSION";
+    readonly TYPE_PARAMETER: "TYPE_PARAMETER";
+    readonly MODULE: "MODULE";
+    readonly IMPORT: "IMPORT";
+    readonly EXPORT: "EXPORT";
+    readonly CALL: "CALL";
+    readonly PROJECT: "PROJECT";
+    readonly SERVICE: "SERVICE";
+    readonly FILE: "FILE";
+    readonly SCOPE: "SCOPE";
+    readonly EXTERNAL: "EXTERNAL";
+    readonly EXTERNAL_MODULE: "EXTERNAL_MODULE";
+    readonly SIDE_EFFECT: "SIDE_EFFECT";
+};
+export type BaseNodeType = typeof NODE_TYPE[keyof typeof NODE_TYPE];
+export declare const NAMESPACED_TYPE: {
+    readonly HTTP_ROUTE: "http:route";
+    readonly HTTP_REQUEST: "http:request";
+    readonly EXPRESS_ROUTER: "express:router";
+    readonly EXPRESS_MIDDLEWARE: "express:middleware";
+    readonly EXPRESS_MOUNT: "express:mount";
+    readonly SOCKETIO_EMIT: "socketio:emit";
+    readonly SOCKETIO_ON: "socketio:on";
+    readonly SOCKETIO_NAMESPACE: "socketio:namespace";
+    readonly DB_QUERY: "db:query";
+    readonly DB_CONNECTION: "db:connection";
+    readonly REDIS_READ: "redis:read";
+    readonly REDIS_WRITE: "redis:write";
+    readonly REDIS_DELETE: "redis:delete";
+    readonly REDIS_PUBLISH: "redis:publish";
+    readonly REDIS_SUBSCRIBE: "redis:subscribe";
+    readonly REDIS_TRANSACTION: "redis:transaction";
+    readonly REDIS_CONNECTION: "redis:connection";
+    readonly FS_READ: "fs:read";
+    readonly FS_WRITE: "fs:write";
+    readonly FS_OPERATION: "fs:operation";
+    readonly NET_REQUEST: "net:request";
+    readonly NET_STDIO: "net:stdio";
+    readonly EVENT_LISTENER: "event:listener";
+    readonly EVENT_EMIT: "event:emit";
+    readonly GUARANTEE_QUEUE: "guarantee:queue";
+    readonly GUARANTEE_API: "guarantee:api";
+    readonly GUARANTEE_PERMISSION: "guarantee:permission";
+    readonly GRAFEMA_PLUGIN: "grafema:plugin";
+};
+export type NamespacedNodeType = typeof NAMESPACED_TYPE[keyof typeof NAMESPACED_TYPE];
+export type NodeType = BaseNodeType | NamespacedNodeType | string;
+/**
+ * Check if type is namespaced (contains :)
+ */
+export declare function isNamespacedType(nodeType: string): boolean;
+/**
+ * Get namespace from type
+ * @returns namespace or null for base types
+ */
+export declare function getNamespace(nodeType: string): string | null;
+/**
+ * Get base name from namespaced type
+ */
+export declare function getBaseName(nodeType: string): string;
+/**
+ * Check if type is an endpoint (HTTP route, WebSocket handler, etc.)
+ */
+export declare function isEndpointType(nodeType: string): boolean;
+/**
+ * Check if type is a side effect (DB, FS, Network)
+ */
+export declare function isSideEffectType(nodeType: string): boolean;
+/**
+ * Check if type matches a pattern with wildcard
+ * @param nodeType - node type
+ * @param pattern - pattern (e.g., "http:*", "FUNCTION")
+ */
+export declare function matchesTypePattern(nodeType: string, pattern: string): boolean;
+/**
+ * Check if type is a guarantee type (guarantee:queue, guarantee:api, etc.)
+ */
+export declare function isGuaranteeType(nodeType: string): boolean;
+/**
+ * Check if type is a grafema internal type (grafema:plugin, etc.)
+ */
+export declare function isGrafemaType(nodeType: string): boolean;
+//# sourceMappingURL=NodeKind.d.ts.map

package/dist/core/nodes/NodeKind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeKind.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/NodeKind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;CAgCZ,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,OAAO,SAAS,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAKpE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDlB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,OAAO,eAAe,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAGtF,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,kBAAkB,GAAG,MAAM,CAAC;AAIlE;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG5D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIpD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAIxD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAK1D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAa7E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGvD"}

package/dist/core/nodes/NodeKind.js

@@ -0,0 +1,166 @@
+/**
+ * Node Types - string type system for nodes
+ *
+ * Base types: FUNCTION, CLASS, METHOD, etc.
+ * Namespaced types: http:route, socketio:emit, express:router, etc.
+ *
+ * Namespace convention:
+ * - http:* - HTTP endpoints and requests
+ * - express:* - Express.js specifics
+ * - socketio:* - Socket.IO
+ * - db:* - Database queries
+ * - fs:* - Filesystem operations
+ */
+// === BASE TYPES ===
+// Abstract types, not tied to language or framework
+export const NODE_TYPE = {
+    // Core code entities
+    FUNCTION: 'FUNCTION',
+    CLASS: 'CLASS',
+    METHOD: 'METHOD',
+    VARIABLE: 'VARIABLE',
+    PARAMETER: 'PARAMETER',
+    CONSTANT: 'CONSTANT',
+    LITERAL: 'LITERAL',
+    EXPRESSION: 'EXPRESSION', // Generic expression node for data flow tracking
+    TYPE_PARAMETER: 'TYPE_PARAMETER',
+    // Module system
+    MODULE: 'MODULE',
+    IMPORT: 'IMPORT',
+    EXPORT: 'EXPORT',
+    // Call graph
+    CALL: 'CALL', // unified METHOD_CALL + CALL_SITE
+    // Project structure
+    PROJECT: 'PROJECT',
+    SERVICE: 'SERVICE',
+    FILE: 'FILE',
+    SCOPE: 'SCOPE',
+    // External dependencies
+    EXTERNAL: 'EXTERNAL',
+    EXTERNAL_MODULE: 'EXTERNAL_MODULE',
+    // Generic side effects
+    SIDE_EFFECT: 'SIDE_EFFECT',
+};
+// === NAMESPACED TYPES ===
+// Types specific to frameworks and libraries
+export const NAMESPACED_TYPE = {
+    // HTTP (generic)
+    HTTP_ROUTE: 'http:route',
+    HTTP_REQUEST: 'http:request',
+    // Express.js
+    EXPRESS_ROUTER: 'express:router',
+    EXPRESS_MIDDLEWARE: 'express:middleware',
+    EXPRESS_MOUNT: 'express:mount',
+    // Socket.IO
+    SOCKETIO_EMIT: 'socketio:emit',
+    SOCKETIO_ON: 'socketio:on',
+    SOCKETIO_NAMESPACE: 'socketio:namespace',
+    // Database
+    DB_QUERY: 'db:query',
+    DB_CONNECTION: 'db:connection',
+    // Redis
+    REDIS_READ: 'redis:read',
+    REDIS_WRITE: 'redis:write',
+    REDIS_DELETE: 'redis:delete',
+    REDIS_PUBLISH: 'redis:publish',
+    REDIS_SUBSCRIBE: 'redis:subscribe',
+    REDIS_TRANSACTION: 'redis:transaction',
+    REDIS_CONNECTION: 'redis:connection',
+    // Filesystem
+    FS_READ: 'fs:read',
+    FS_WRITE: 'fs:write',
+    FS_OPERATION: 'fs:operation',
+    // Network
+    NET_REQUEST: 'net:request',
+    NET_STDIO: 'net:stdio',
+    // Events
+    EVENT_LISTENER: 'event:listener',
+    EVENT_EMIT: 'event:emit',
+    // Guarantees (contract-based)
+    GUARANTEE_QUEUE: 'guarantee:queue',
+    GUARANTEE_API: 'guarantee:api',
+    GUARANTEE_PERMISSION: 'guarantee:permission',
+    // Grafema internal (self-describing pipeline)
+    GRAFEMA_PLUGIN: 'grafema:plugin',
+};
+// === HELPERS ===
+/**
+ * Check if type is namespaced (contains :)
+ */
+export function isNamespacedType(nodeType) {
+    return nodeType !== undefined && nodeType !== null && nodeType.includes(':');
+}
+/**
+ * Get namespace from type
+ * @returns namespace or null for base types
+ */
+export function getNamespace(nodeType) {
+    if (!nodeType || !nodeType.includes(':'))
+        return null;
+    return nodeType.split(':')[0];
+}
+/**
+ * Get base name from namespaced type
+ */
+export function getBaseName(nodeType) {
+    if (!nodeType)
+        return '';
+    if (!nodeType.includes(':'))
+        return nodeType;
+    return nodeType.split(':').slice(1).join(':');
+}
+/**
+ * Check if type is an endpoint (HTTP route, WebSocket handler, etc.)
+ */
+export function isEndpointType(nodeType) {
+    if (!nodeType)
+        return false;
+    const ns = getNamespace(nodeType);
+    return ns === 'http' || ns === 'express' || ns === 'socketio';
+}
+/**
+ * Check if type is a side effect (DB, FS, Network)
+ */
+export function isSideEffectType(nodeType) {
+    if (!nodeType)
+        return false;
+    if (nodeType === NODE_TYPE.SIDE_EFFECT)
+        return true;
+    const ns = getNamespace(nodeType);
+    return ns === 'db' || ns === 'fs' || ns === 'net' || ns === 'redis';
+}
+/**
+ * Check if type matches a pattern with wildcard
+ * @param nodeType - node type
+ * @param pattern - pattern (e.g., "http:*", "FUNCTION")
+ */
+export function matchesTypePattern(nodeType, pattern) {
+    if (!nodeType || !pattern)
+        return false;
+    // Exact match
+    if (nodeType === pattern)
+        return true;
+    // Wildcard match (e.g., "http:*" matches "http:route")
+    if (pattern.endsWith(':*')) {
+        const patternNs = pattern.slice(0, -2);
+        return getNamespace(nodeType) === patternNs;
+    }
+    return false;
+}
+/**
+ * Check if type is a guarantee type (guarantee:queue, guarantee:api, etc.)
+ */
+export function isGuaranteeType(nodeType) {
+    if (!nodeType)
+        return false;
+    return getNamespace(nodeType) === 'guarantee';
+}
+/**
+ * Check if type is a grafema internal type (grafema:plugin, etc.)
+ */
+export function isGrafemaType(nodeType) {
+    if (!nodeType)
+        return false;
+    return getNamespace(nodeType) === 'grafema';
+}
+//# sourceMappingURL=NodeKind.js.map

package/dist/core/nodes/NodeKind.js.map

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

package/dist/diagnostics/DiagnosticCollector.d.ts

@@ -0,0 +1,103 @@
+/**
+ * DiagnosticCollector - Collects and filters diagnostics from plugin execution
+ *
+ * The DiagnosticCollector aggregates errors from PluginResult.errors[],
+ * converting both GrafemaError instances (with rich info) and plain Error
+ * instances (treated as generic errors) into unified Diagnostic entries.
+ *
+ * Usage:
+ *   const collector = new DiagnosticCollector();
+ *   collector.addFromPluginResult('INDEXING', 'JSModuleIndexer', result);
+ *
+ *   if (collector.hasFatal()) {
+ *     throw new Error('Fatal error detected');
+ *   }
+ *
+ *   console.log(collector.toDiagnosticsLog());
+ */
+import type { PluginPhase, PluginResult } from '@grafema/types';
+import { type ResolutionStep, type ResolutionFailureReason } from '../errors/GrafemaError.js';
+/**
+ * Diagnostic entry - unified format for all errors/warnings
+ */
+export interface Diagnostic {
+    code: string;
+    severity: 'fatal' | 'error' | 'warning' | 'info';
+    message: string;
+    file?: string;
+    line?: number;
+    phase: PluginPhase;
+    plugin: string;
+    timestamp: number;
+    suggestion?: string;
+    /** Resolution chain for context (REG-332) */
+    resolutionChain?: ResolutionStep[];
+    /** Failure reason for context-aware suggestions (REG-332) */
+    failureReason?: ResolutionFailureReason;
+}
+/**
+ * Diagnostic input (without timestamp, which is auto-generated)
+ */
+export type DiagnosticInput = Omit<Diagnostic, 'timestamp'>;
+/**
+ * DiagnosticCollector - collects, filters, and formats diagnostics
+ */
+export declare class DiagnosticCollector {
+    private diagnostics;
+    /**
+     * Extract errors from PluginResult and add as diagnostics.
+     *
+     * GrafemaError instances provide rich info (code, severity, context, suggestion).
+     * Plain Error instances are treated as generic errors with code 'ERR_UNKNOWN'.
+     */
+    addFromPluginResult(phase: PluginPhase, plugin: string, result: PluginResult): void;
+    /**
+     * Add a diagnostic directly.
+     * Timestamp is set automatically.
+     */
+    add(diagnostic: DiagnosticInput): void;
+    /**
+     * Get all diagnostics.
+     * Returns a copy to prevent external modification.
+     */
+    getAll(): Diagnostic[];
+    /**
+     * Get diagnostics filtered by phase.
+     */
+    getByPhase(phase: PluginPhase): Diagnostic[];
+    /**
+     * Get diagnostics filtered by plugin name (case-sensitive).
+     */
+    getByPlugin(plugin: string): Diagnostic[];
+    /**
+     * Get diagnostics filtered by error code.
+     */
+    getByCode(code: string): Diagnostic[];
+    /**
+     * Check if any fatal diagnostic exists.
+     * Fatal errors require immediate stop of analysis.
+     */
+    hasFatal(): boolean;
+    /**
+     * Check if any error (including fatal) exists.
+     */
+    hasErrors(): boolean;
+    /**
+     * Check if any warning exists.
+     */
+    hasWarnings(): boolean;
+    /**
+     * Get total count of diagnostics.
+     */
+    count(): number;
+    /**
+     * Format diagnostics as JSON lines (one JSON object per line).
+     * Suitable for .grafema/diagnostics.log file.
+     */
+    toDiagnosticsLog(): string;
+    /**
+     * Clear all diagnostics.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=DiagnosticCollector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DiagnosticCollector.d.ts","sourceRoot":"","sources":["../../src/diagnostics/DiagnosticCollector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAgB,KAAK,cAAc,EAAE,KAAK,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAE5G;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,WAAW,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IACnC,6DAA6D;IAC7D,aAAa,CAAC,EAAE,uBAAuB,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;AAE5D;;GAEG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,WAAW,CAAoB;IAEvC;;;;;OAKG;IACH,mBAAmB,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI;IA6BnF;;;OAGG;IACH,GAAG,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI;IAOtC;;;OAGG;IACH,MAAM,IAAI,UAAU,EAAE;IAItB;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,UAAU,EAAE;IAI5C;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE;IAIzC;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE;IAIrC;;;OAGG;IACH,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,KAAK,IAAI,MAAM;IAIf;;;OAGG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}