@grafema/util 0.3.0-beta

package/dist/core/GraphBackend.d.ts

@@ -0,0 +1,158 @@
+/**
+ * GraphBackend - abstract base class for graph storage implementations
+ *
+ * This defines the full contract for graph storage backends.
+ * All operations are async for compatibility with disk-based storage.
+ *
+ * Implementations:
+ * - RFDBServerBackend (Rust-based, production)
+ * - TestBackend (wrapper over RFDBServerBackend for tests)
+ */
+import type { NodeRecord } from '@grafema/types';
+import type { EdgeRecord, EdgeType } from '@grafema/types';
+export type { NodeRecord as Node } from '@grafema/types';
+export type { EdgeRecord as Edge, EdgeType } from '@grafema/types';
+/**
+ * Query filter for finding nodes by attributes
+ */
+export interface AttrQuery {
+    kind?: number;
+    version?: string;
+    file_id?: string;
+    file?: string;
+    exported?: boolean;
+    type?: string;
+    name?: string;
+    /** When true, name and file filters use substring (contains) matching instead of exact match */
+    substringMatch?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Graph statistics
+ */
+export interface GraphStats {
+    nodeCount: number;
+    edgeCount: number;
+}
+/**
+ * Exported graph data
+ */
+export interface GraphExport {
+    nodes: NodeRecord[];
+    edges: EdgeRecord[];
+}
+/**
+ * Abstract GraphBackend class - base for all graph storage implementations
+ */
+export declare abstract class GraphBackend {
+    /**
+     * Initialize backend
+     */
+    abstract initialize(): Promise<void>;
+    /**
+     * Connect to storage (alias for initialize)
+     */
+    connect(): Promise<void>;
+    /**
+     * Close connection and flush data to disk
+     */
+    abstract close(): Promise<void>;
+    /**
+     * Clear all data
+     */
+    abstract clear(): Promise<void>;
+    /**
+     * Add a single node
+     */
+    abstract addNode(node: NodeRecord): Promise<void>;
+    /**
+     * Add multiple nodes (batch operation)
+     */
+    abstract addNodes(nodes: NodeRecord[]): Promise<void>;
+    /**
+     * Get node by ID
+     */
+    abstract getNode(id: string): Promise<NodeRecord | null>;
+    /**
+     * Check if node exists
+     */
+    abstract nodeExists(id: string): Promise<boolean>;
+    /**
+     * Delete a node
+     */
+    abstract deleteNode(id: string): Promise<void>;
+    /**
+     * Find nodes by attributes
+     * @returns Array of node IDs
+     */
+    abstract findByAttr(query: AttrQuery): Promise<string[]>;
+    /**
+     * Add a single edge
+     */
+    abstract addEdge(edge: EdgeRecord): Promise<void>;
+    /**
+     * Add multiple edges (batch operation)
+     */
+    abstract addEdges(edges: EdgeRecord[]): Promise<void>;
+    /**
+     * Delete an edge
+     */
+    abstract deleteEdge(src: string, dst: string, type: string): Promise<void>;
+    /**
+     * Get outgoing edges from a node
+     * @param nodeId - Node ID
+     * @param edgeTypes - Filter by edge types (optional)
+     */
+    abstract getOutgoingEdges(nodeId: string, edgeTypes?: EdgeType[] | null): Promise<EdgeRecord[]>;
+    /**
+     * Get incoming edges to a node
+     * @param nodeId - Node ID
+     * @param edgeTypes - Filter by edge types (optional)
+     */
+    abstract getIncomingEdges(nodeId: string, edgeTypes?: EdgeType[] | null): Promise<EdgeRecord[]>;
+    /**
+     * BFS traversal from start nodes
+     * @param startIds - Starting nodes
+     * @param maxDepth - Maximum depth
+     * @param edgeTypes - Edge types to traverse (as numbers)
+     * @returns Array of reachable node IDs
+     */
+    abstract bfs(startIds: string[], maxDepth: number, edgeTypes: number[]): Promise<string[]>;
+    /**
+     * Flush data to disk
+     */
+    abstract flush(): Promise<void>;
+    /**
+     * Get graph statistics
+     */
+    abstract getStats(): Promise<GraphStats>;
+    /**
+     * Export entire graph to memory (only for tests!)
+     * WARNING: Do not use on large graphs
+     */
+    abstract export(): Promise<GraphExport>;
+    /**
+     * Find nodes by predicate (for demo-gui compatibility)
+     * WARNING: May be slow on large graphs
+     */
+    abstract findNodes(predicate: (node: NodeRecord) => boolean): Promise<NodeRecord[]>;
+    /**
+     * Get all nodes (for GUI - only for first level visualization)
+     * WARNING: Do not use on large graphs
+     */
+    abstract getAllNodes(): Promise<NodeRecord[]>;
+    /**
+     * Get all edges (for GUI)
+     * WARNING: Do not use on large graphs
+     */
+    abstract getAllEdges(): Promise<EdgeRecord[]>;
+}
+/**
+ * Convert node type to numeric kind
+ */
+export declare function typeToKind(type: string): number;
+/**
+ * Convert edge type to number
+ */
+export declare function edgeTypeToNumber(type: string): number;
+//# sourceMappingURL=GraphBackend.d.ts.map

package/dist/core/GraphBackend.d.ts.map

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

package/dist/core/GraphBackend.js

@@ -0,0 +1,85 @@
+/**
+ * GraphBackend - abstract base class for graph storage implementations
+ *
+ * This defines the full contract for graph storage backends.
+ * All operations are async for compatibility with disk-based storage.
+ *
+ * Implementations:
+ * - RFDBServerBackend (Rust-based, production)
+ * - TestBackend (wrapper over RFDBServerBackend for tests)
+ */
+/**
+ * Abstract GraphBackend class - base for all graph storage implementations
+ */
+export class GraphBackend {
+    /**
+     * Connect to storage (alias for initialize)
+     */
+    async connect() {
+        return this.initialize();
+    }
+}
+/**
+ * Node type to numeric kind mapping
+ */
+const NODE_TYPE_TO_KIND = {
+    'PROJECT': 1,
+    'SERVICE': 2,
+    'FUNCTION': 3,
+    'CLASS': 4,
+    'METHOD': 5,
+    'VARIABLE': 6,
+    'PARAMETER': 7,
+    'MODULE': 8,
+    'ROUTE': 9,
+    'ENDPOINT': 10,
+    'FILE': 11,
+    'EXTERNAL_MODULE': 12,
+    'IMPORT': 13,
+    'EXPORT': 14,
+    'CALL_SITE': 15,
+    'METHOD_CALL': 16,
+    'SCOPE': 17,
+    'VARIABLE_DECLARATION': 18,
+    'CONSTANT': 19,
+    'EVENT_LISTENER': 20,
+    'HTTP_REQUEST': 21,
+};
+/**
+ * Convert node type to numeric kind
+ */
+export function typeToKind(type) {
+    return NODE_TYPE_TO_KIND[type] || 0;
+}
+/**
+ * Edge type to numeric mapping
+ */
+const EDGE_TYPE_TO_NUMBER = {
+    'CONTAINS': 1,
+    'DEPENDS_ON': 2,
+    'CALLS': 3,
+    'EXTENDS': 4,
+    'IMPLEMENTS': 5,
+    'USES': 6,
+    'DEFINES': 7,
+    'IMPORTS': 8,
+    'EXPORTS': 9,
+    'ROUTES_TO': 10,
+    'DECLARES': 11,
+    'HAS_SCOPE': 12,
+    'CAPTURES': 13,
+    'MODIFIES': 14,
+    'WRITES_TO': 15,
+    'INSTANCE_OF': 16,
+    'HANDLED_BY': 17,
+    'HAS_CALLBACK': 18,
+    'MAKES_REQUEST': 19,
+    'IMPORTS_FROM': 20,
+};
+/**
+ * Convert edge type to number
+ */
+export function edgeTypeToNumber(type) {
+    return EDGE_TYPE_TO_NUMBER[type] || 0;
+}
+//# sourceMappingURL=GraphBackend.js.map

package/dist/core/GraphBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphBackend.js","sourceRoot":"","sources":["../../src/core/GraphBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAyCH;;GAEG;AACH,MAAM,OAAgB,YAAY;IAMhC;;OAEG;IACH,KAAK,CAAC,OAAO;QACX,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC;IAC3B,CAAC;CAsIF;AAED;;GAEG;AACH,MAAM,iBAAiB,GAA2B;IAChD,SAAS,EAAE,CAAC;IACZ,SAAS,EAAE,CAAC;IACZ,UAAU,EAAE,CAAC;IACb,OAAO,EAAE,CAAC;IACV,QAAQ,EAAE,CAAC;IACX,UAAU,EAAE,CAAC;IACb,WAAW,EAAE,CAAC;IACd,QAAQ,EAAE,CAAC;IACX,OAAO,EAAE,CAAC;IACV,UAAU,EAAE,EAAE;IACd,MAAM,EAAE,EAAE;IACV,iBAAiB,EAAE,EAAE;IACrB,QAAQ,EAAE,EAAE;IACZ,QAAQ,EAAE,EAAE;IACZ,WAAW,EAAE,EAAE;IACf,aAAa,EAAE,EAAE;IACjB,OAAO,EAAE,EAAE;IACX,sBAAsB,EAAE,EAAE;IAC1B,UAAU,EAAE,EAAE;IACd,gBAAgB,EAAE,EAAE;IACpB,cAAc,EAAE,EAAE;CACnB,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,mBAAmB,GAA2B;IAClD,UAAU,EAAE,CAAC;IACb,YAAY,EAAE,CAAC;IACf,OAAO,EAAE,CAAC;IACV,SAAS,EAAE,CAAC;IACZ,YAAY,EAAE,CAAC;IACf,MAAM,EAAE,CAAC;IACT,SAAS,EAAE,CAAC;IACZ,SAAS,EAAE,CAAC;IACZ,SAAS,EAAE,CAAC;IACZ,WAAW,EAAE,EAAE;IACf,UAAU,EAAE,EAAE;IACd,WAAW,EAAE,EAAE;IACf,UAAU,EAAE,EAAE;IACd,UAAU,EAAE,EAAE;IACd,WAAW,EAAE,EAAE;IACf,aAAa,EAAE,EAAE;IACjB,YAAY,EAAE,EAAE;IAChB,cAAc,EAAE,EAAE;IAClB,eAAe,EAAE,EAAE;IACnB,cAAc,EAAE,EAAE;CACnB,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC"}

package/dist/core/GraphFreshnessChecker.d.ts

@@ -0,0 +1,33 @@
+/**
+ * GraphFreshnessChecker - checks if graph data matches current files
+ *
+ * Compares contentHash stored in MODULE nodes against current file hashes.
+ * Used by `grafema check` to detect when files have changed since analysis.
+ */
+import type { NodeRecord } from '@grafema/types';
+export interface StaleModule {
+    id: string;
+    file: string;
+    storedHash: string;
+    currentHash: string | null;
+    reason: 'changed' | 'deleted' | 'unreadable';
+}
+export interface FreshnessResult {
+    isFresh: boolean;
+    staleModules: StaleModule[];
+    freshCount: number;
+    staleCount: number;
+    deletedCount: number;
+    checkDurationMs: number;
+}
+export interface FreshnessGraph {
+    queryNodes(query: {
+        type: string;
+    }): AsyncGenerator<NodeRecord, void, unknown>;
+}
+export declare class GraphFreshnessChecker {
+    checkFreshness(graph: FreshnessGraph, projectPath?: string): Promise<FreshnessResult>;
+    private _checkModuleFreshness;
+    private _fileExists;
+}
+//# sourceMappingURL=GraphFreshnessChecker.d.ts.map

package/dist/core/GraphFreshnessChecker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphFreshnessChecker.d.ts","sourceRoot":"","sources":["../../src/core/GraphFreshnessChecker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,YAAY,CAAC;CAC9C;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,cAAc,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;CAChF;AAUD,qBAAa,qBAAqB;IAC1B,cAAc,CAAC,KAAK,EAAE,cAAc,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;YAyD7E,qBAAqB;YAqCrB,WAAW;CAQ1B"}

package/dist/core/GraphFreshnessChecker.js

@@ -0,0 +1,104 @@
+/**
+ * GraphFreshnessChecker - checks if graph data matches current files
+ *
+ * Compares contentHash stored in MODULE nodes against current file hashes.
+ * Used by `grafema check` to detect when files have changed since analysis.
+ */
+import { access, constants } from 'fs/promises';
+import { calculateFileHashAsync } from './HashUtils.js';
+import { resolveNodeFile } from '../utils/resolveNodeFile.js';
+const BATCH_SIZE = 50;
+export class GraphFreshnessChecker {
+    async checkFreshness(graph, projectPath) {
+        const startTime = Date.now();
+        const modules = [];
+        for await (const node of graph.queryNodes({ type: 'MODULE' })) {
+            if (node.file && typeof node.contentHash === 'string') {
+                modules.push({
+                    id: node.id,
+                    file: node.file,
+                    contentHash: node.contentHash
+                });
+            }
+        }
+        if (modules.length === 0) {
+            return {
+                isFresh: true,
+                staleModules: [],
+                freshCount: 0,
+                staleCount: 0,
+                deletedCount: 0,
+                checkDurationMs: Date.now() - startTime
+            };
+        }
+        const staleModules = [];
+        let freshCount = 0;
+        let deletedCount = 0;
+        for (let i = 0; i < modules.length; i += BATCH_SIZE) {
+            const batch = modules.slice(i, i + BATCH_SIZE);
+            const results = await Promise.all(batch.map(module => this._checkModuleFreshness(module, projectPath)));
+            for (const result of results) {
+                if (result === null) {
+                    freshCount++;
+                }
+                else {
+                    staleModules.push(result);
+                    if (result.reason === 'deleted') {
+                        deletedCount++;
+                    }
+                }
+            }
+        }
+        return {
+            isFresh: staleModules.length === 0,
+            staleModules,
+            freshCount,
+            staleCount: staleModules.length,
+            deletedCount,
+            checkDurationMs: Date.now() - startTime
+        };
+    }
+    async _checkModuleFreshness(module, projectPath) {
+        const absoluteFile = projectPath ? resolveNodeFile(module.file, projectPath) : module.file;
+        const exists = await this._fileExists(absoluteFile);
+        if (!exists) {
+            return {
+                id: module.id,
+                file: module.file,
+                storedHash: module.contentHash,
+                currentHash: null,
+                reason: 'deleted'
+            };
+        }
+        const currentHash = await calculateFileHashAsync(absoluteFile);
+        if (currentHash === null) {
+            return {
+                id: module.id,
+                file: module.file,
+                storedHash: module.contentHash,
+                currentHash: null,
+                reason: 'unreadable'
+            };
+        }
+        if (currentHash !== module.contentHash) {
+            return {
+                id: module.id,
+                file: module.file,
+                storedHash: module.contentHash,
+                currentHash,
+                reason: 'changed'
+            };
+        }
+        return null;
+    }
+    async _fileExists(filePath) {
+        try {
+            await access(filePath, constants.R_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=GraphFreshnessChecker.js.map

package/dist/core/GraphFreshnessChecker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphFreshnessChecker.js","sourceRoot":"","sources":["../../src/core/GraphFreshnessChecker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AA8B9D,MAAM,UAAU,GAAG,EAAE,CAAC;AAEtB,MAAM,OAAO,qBAAqB;IAChC,KAAK,CAAC,cAAc,CAAC,KAAqB,EAAE,WAAoB;QAC9D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,MAAM,OAAO,GAAiB,EAAE,CAAC;QACjC,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,KAAK,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;YAC9D,IAAI,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ,EAAE,CAAC;gBACtD,OAAO,CAAC,IAAI,CAAC;oBACX,EAAE,EAAE,IAAI,CAAC,EAAE;oBACX,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,WAAW,EAAE,IAAI,CAAC,WAAW;iBAC9B,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,YAAY,EAAE,EAAE;gBAChB,UAAU,EAAE,CAAC;gBACb,UAAU,EAAE,CAAC;gBACb,YAAY,EAAE,CAAC;gBACf,eAAe,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;aACxC,CAAC;QACJ,CAAC;QAED,MAAM,YAAY,GAAkB,EAAE,CAAC;QACvC,IAAI,UAAU,GAAG,CAAC,CAAC;QACnB,IAAI,YAAY,GAAG,CAAC,CAAC;QAErB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,UAAU,EAAE,CAAC;YACpD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC;YAC/C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,qBAAqB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CACrE,CAAC;YAEF,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;oBACpB,UAAU,EAAE,CAAC;gBACf,CAAC;qBAAM,CAAC;oBACN,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;oBAC1B,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;wBAChC,YAAY,EAAE,CAAC;oBACjB,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO;YACL,OAAO,EAAE,YAAY,CAAC,MAAM,KAAK,CAAC;YAClC,YAAY;YACZ,UAAU;YACV,UAAU,EAAE,YAAY,CAAC,MAAM;YAC/B,YAAY;YACZ,eAAe,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;SACxC,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,qBAAqB,CAAC,MAAkB,EAAE,WAAoB;QAC1E,MAAM,YAAY,GAAG,WAAW,CAAC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;QAC3F,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;QACpD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO;gBACL,EAAE,EAAE,MAAM,CAAC,EAAE;gBACb,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,UAAU,EAAE,MAAM,CAAC,WAAW;gBAC9B,WAAW,EAAE,IAAI;gBACjB,MAAM,EAAE,SAAS;aAClB,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAG,MAAM,sBAAsB,CAAC,YAAY,CAAC,CAAC;QAC/D,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YACzB,OAAO;gBACL,EAAE,EAAE,MAAM,CAAC,EAAE;gBACb,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,UAAU,EAAE,MAAM,CAAC,WAAW;gBAC9B,WAAW,EAAE,IAAI;gBACjB,MAAM,EAAE,YAAY;aACrB,CAAC;QACJ,CAAC;QAED,IAAI,WAAW,KAAK,MAAM,CAAC,WAAW,EAAE,CAAC;YACvC,OAAO;gBACL,EAAE,EAAE,MAAM,CAAC,EAAE;gBACb,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,UAAU,EAAE,MAAM,CAAC,WAAW;gBAC9B,WAAW;gBACX,MAAM,EAAE,SAAS;aAClB,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,QAAgB;QACxC,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;YACvC,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}

package/dist/core/GuaranteeManager.d.ts

@@ -0,0 +1,254 @@
+/**
+ * GuaranteeManager - управление гарантиями/инвариантами кода
+ *
+ * GUARANTEE ноды хранят Datalog правила, которые код должен соблюдать.
+ * GOVERNS edges связывают гарантии с модулями, к которым они применяются.
+ *
+ * Workflow:
+ * 1. Создать гарантию (create) → GUARANTEE нода + GOVERNS edges
+ * 2. Проверить (check) → выполнить Datalog rule, найти нарушения
+ * 3. Экспортировать (export) → сохранить в YAML для version control
+ * 4. Импортировать (import) → загрузить из YAML в граф
+ * 5. Drift detection → сравнить граф с файлом
+ */
+/**
+ * Severity level for guarantees
+ */
+export type GuaranteeSeverity = 'error' | 'warning' | 'info';
+/**
+ * Guarantee definition
+ */
+export interface GuaranteeDefinition {
+    id: string;
+    name?: string;
+    rule: string;
+    severity?: GuaranteeSeverity;
+    governs?: string[];
+}
+/**
+ * Guarantee node structure
+ */
+export interface GuaranteeNode {
+    id: string;
+    type: 'GUARANTEE';
+    name: string;
+    rule: string;
+    severity: GuaranteeSeverity;
+    governs: string[];
+    version: 'meta';
+    createdAt: number;
+    governedModules?: string[];
+}
+/**
+ * Edge structure
+ */
+export interface GraphEdge {
+    type: string;
+    src: string;
+    dst: string;
+}
+/**
+ * Module node
+ */
+export interface ModuleNode {
+    id: string;
+    type: string;
+    file?: string;
+}
+/**
+ * Violation binding
+ */
+export interface ViolationBinding {
+    name: string;
+    value: string;
+}
+/**
+ * Violation result from Datalog
+ */
+export interface ViolationResult {
+    bindings?: ViolationBinding[];
+}
+/**
+ * Enriched violation info
+ */
+export interface EnrichedViolation {
+    nodeId: string;
+    type: string;
+    name?: string;
+    file?: string;
+    line?: number;
+}
+/**
+ * Check result for a single guarantee
+ */
+export interface GuaranteeCheckResult {
+    guaranteeId: string;
+    name: string;
+    severity: GuaranteeSeverity;
+    passed: boolean;
+    violationCount: number;
+    violations: EnrichedViolation[];
+    error: string | null;
+    checkDurationMs: number;
+}
+/**
+ * Check all result
+ */
+export interface CheckAllResult {
+    total: number;
+    passed: number;
+    failed: number;
+    errors: number;
+    results: GuaranteeCheckResult[];
+}
+/**
+ * Import options
+ */
+export interface ImportOptions {
+    clearExisting?: boolean;
+}
+/**
+ * Import result
+ */
+export interface ImportResult {
+    imported: number;
+    skipped: number;
+    importedIds: string[];
+    skippedIds: string[];
+}
+/**
+ * Modified guarantee in drift
+ */
+export interface ModifiedGuarantee {
+    id: string;
+    changes: string[];
+}
+/**
+ * Drift summary
+ */
+export interface DriftSummary {
+    onlyInGraph: number;
+    onlyInFile: number;
+    modified: number;
+    unchanged: number;
+}
+/**
+ * Drift result
+ */
+export interface DriftResult {
+    hasDrift: boolean;
+    summary: DriftSummary;
+    onlyInGraph: string[];
+    onlyInFile: string[];
+    modified: ModifiedGuarantee[];
+    unchanged: string[];
+}
+/**
+ * Export data format
+ */
+export interface ExportData {
+    version: number;
+    exportedAt: string;
+    guarantees: Array<{
+        id: string;
+        name: string;
+        rule: string;
+        severity: GuaranteeSeverity;
+        governs: string[];
+    }>;
+}
+/**
+ * Graph interface for GuaranteeManager
+ */
+export interface GuaranteeGraph {
+    addNode(node: GuaranteeNode): Promise<void>;
+    getNode(id: string): Promise<GuaranteeNode | ModuleNode | null>;
+    deleteNode(id: string): Promise<void>;
+    queryNodes(filter: {
+        type: string;
+    }): AsyncIterable<GuaranteeNode | ModuleNode>;
+    addEdge(edge: GraphEdge): Promise<void>;
+    deleteEdge(src: string, dst: string, type: string): Promise<void>;
+    getOutgoingEdges(nodeId: string, types: string[]): Promise<GraphEdge[]>;
+    getIncomingEdges(nodeId: string, types: string[]): Promise<GraphEdge[]>;
+    checkGuarantee(rule: string): Promise<ViolationResult[]>;
+}
+export declare class GuaranteeManager {
+    private graph;
+    private projectPath;
+    private guaranteesFile;
+    constructor(graph: GuaranteeGraph, projectPath: string);
+    /**
+     * Создать новую гарантию
+     */
+    create(guarantee: GuaranteeDefinition): Promise<GuaranteeNode>;
+    /**
+     * Получить все гарантии из графа
+     */
+    list(): Promise<GuaranteeNode[]>;
+    /**
+     * Проверить гарантию
+     */
+    check(guaranteeId: string): Promise<GuaranteeCheckResult>;
+    /**
+     * Проверить все гарантии
+     */
+    checkAll(): Promise<CheckAllResult>;
+    /**
+     * Extract type references from a Datalog rule.
+     * Matches node(X, "TYPE") and edge(X, Y, "TYPE") patterns.
+     * Returns unique types array. If nothing parseable, returns empty array.
+     */
+    extractRelevantTypes(rule: string): string[];
+    /**
+     * Selectively check guarantees whose relevant types overlap with changedTypes.
+     * Guarantees with no parseable types are always checked (conservative).
+     * Returns CheckAllResult with total = all guarantees count,
+     * but results only for the checked subset.
+     */
+    checkSelective(changedTypes: Set<string>): Promise<CheckAllResult>;
+    /**
+     * Load guarantees from the project's YAML file (.grafema/guarantees.yaml).
+     *
+     * Reads the YAML file, skips non-datalog guarantees (e.g., integration-test),
+     * and creates GUARANTEE nodes in the graph for each datalog guarantee.
+     * Idempotent: skips guarantees that already exist in the graph.
+     * Gracefully handles missing file (no error, just returns).
+     *
+     * @returns ImportResult with counts of imported and skipped guarantees
+     */
+    loadFromYaml(): Promise<ImportResult>;
+    /**
+     * Удалить гарантию
+     */
+    delete(guaranteeId: string): Promise<void>;
+    /**
+     * Экспортировать гарантии в YAML файл
+     */
+    export(filePath?: string): Promise<string>;
+    /**
+     * Импортировать гарантии из YAML файла
+     */
+    import(filePath?: string, options?: ImportOptions): Promise<ImportResult>;
+    /**
+     * Показать drift между графом и файлом
+     */
+    drift(filePath?: string): Promise<DriftResult>;
+    /**
+     * Найти гарантии затронутые изменением ноды
+     */
+    findAffectedGuarantees(nodeId: string): Promise<string[]>;
+    /**
+     * Создать GOVERNS edges к модулям по glob patterns
+     */
+    private _createGovernsEdges;
+    /**
+     * Проверить есть ли изменения между версиями гарантии
+     */
+    private _hasChanges;
+    /**
+     * Описать изменения между версиями
+     */
+    private _describeChanges;
+}
+//# sourceMappingURL=GuaranteeManager.d.ts.map

package/dist/core/GuaranteeManager.d.ts.map

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