@grafema/core 0.1.0-alpha.1

package/dist/storage/backends/typeValidation.js

@@ -0,0 +1,137 @@
+/**
+ * Type Validation Utilities
+ *
+ * Levenshtein distance and typo detection for node/edge types.
+ * Extracted from ReginaFlowBackend for use in multiple contexts.
+ */
+// Known node types - source of truth for validation
+// Initial set of types, dynamically expanded as new valid types are encountered
+const KNOWN_NODE_TYPES = new Set([
+    // Base types
+    'FUNCTION', 'CLASS', 'METHOD', 'VARIABLE', 'PARAMETER', 'CONSTANT', 'LITERAL',
+    'MODULE', 'IMPORT', 'EXPORT', 'CALL', 'PROJECT', 'SERVICE', 'FILE', 'SCOPE',
+    'EXTERNAL', 'EXTERNAL_MODULE', 'SIDE_EFFECT',
+    // Namespaced types - HTTP/Express
+    'http:route', 'http:request',
+    'express:router', 'express:middleware', 'express:mount',
+    // Namespaced types - Socket.IO
+    'socketio:emit', 'socketio:on', 'socketio:namespace', 'socketio:room',
+    // Namespaced types - Database
+    'db:query', 'db:connection', 'db:table',
+    // Namespaced types - File System
+    'fs:read', 'fs:write', 'fs:operation',
+    // Namespaced types - Network/IO
+    'net:request', 'net:stdio',
+    // Namespaced types - Events
+    'event:listener', 'event:emit',
+    // Service layer types (legacy, to be refactored)
+    'SERVICE_CLASS', 'SERVICE_INSTANCE', 'SERVICE_REGISTRATION', 'SERVICE_USAGE',
+    // Guarantees/Invariants
+    'GUARANTEE',
+]);
+// Store initial types for reset
+const INITIAL_NODE_TYPES = [...KNOWN_NODE_TYPES];
+// Known edge types - source of truth for validation
+const KNOWN_EDGE_TYPES = new Set([
+    // Base edge types
+    'UNKNOWN', 'CONTAINS', 'DEPENDS_ON', 'CALLS', 'EXTENDS', 'IMPLEMENTS',
+    'USES', 'DEFINES', 'IMPORTS', 'EXPORTS', 'ROUTES_TO', 'HAS_SCOPE',
+    'CAPTURES', 'MODIFIES', 'DECLARES', 'WRITES_TO', 'INSTANCE_OF',
+    'HAS_CALLBACK', 'IMPORTS_FROM', 'HANDLED_BY', 'MAKES_REQUEST',
+    'PASSES_ARGUMENT', 'ASSIGNED_FROM', 'EXPORTS_TO', 'MOUNTS', 'EXPOSES',
+    'INTERACTS_WITH', 'CALLS_API', 'LISTENS_TO', 'JOINS_ROOM', 'EMITS_EVENT',
+    'RETURNS', 'RECEIVES_ARGUMENT', 'READS_FROM', 'THROWS', 'REGISTERS_VIEW',
+    'GOVERNS', 'VIOLATES', 'HAS_PARAMETER', 'DERIVES_FROM',
+]);
+// Store initial edge types for reset
+const INITIAL_EDGE_TYPES = [...KNOWN_EDGE_TYPES];
+/**
+ * Levenshtein distance for typo detection
+ */
+export function levenshtein(a, b) {
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const matrix = [];
+    for (let i = 0; i <= b.length; i++)
+        matrix[i] = [i];
+    for (let j = 0; j <= a.length; j++)
+        matrix[0][j] = j;
+    for (let i = 1; i <= b.length; i++) {
+        for (let j = 1; j <= a.length; j++) {
+            matrix[i][j] = b[i - 1] === a[j - 1]
+                ? matrix[i - 1][j - 1]
+                : Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
+        }
+    }
+    return matrix[b.length][a.length];
+}
+/**
+ * Check if a type is too similar to any existing known type (possible typo)
+ */
+export function checkTypoAgainstKnownTypes(newType) {
+    const newTypeLower = newType.toLowerCase();
+    for (const known of KNOWN_NODE_TYPES) {
+        const dist = levenshtein(newTypeLower, known.toLowerCase());
+        if (dist > 0 && dist <= 2) {
+            return { isTooSimilar: true, similarTo: known };
+        }
+    }
+    return { isTooSimilar: false, similarTo: null };
+}
+/**
+ * Reset KNOWN_NODE_TYPES to initial state (for testing)
+ */
+export function resetKnownNodeTypes() {
+    KNOWN_NODE_TYPES.clear();
+    for (const t of INITIAL_NODE_TYPES) {
+        KNOWN_NODE_TYPES.add(t);
+    }
+}
+/**
+ * Get current known node types (for testing/debugging)
+ */
+export function getKnownNodeTypes() {
+    return new Set(KNOWN_NODE_TYPES);
+}
+/**
+ * Check if an edge type is too similar to any existing known edge type (possible typo)
+ */
+export function checkTypoAgainstKnownEdgeTypes(newType) {
+    const newTypeLower = newType.toLowerCase();
+    for (const known of KNOWN_EDGE_TYPES) {
+        const dist = levenshtein(newTypeLower, known.toLowerCase());
+        if (dist > 0 && dist <= 2) {
+            return { isTooSimilar: true, similarTo: known };
+        }
+    }
+    return { isTooSimilar: false, similarTo: null };
+}
+/**
+ * Reset KNOWN_EDGE_TYPES to initial state (for testing)
+ */
+export function resetKnownEdgeTypes() {
+    KNOWN_EDGE_TYPES.clear();
+    for (const t of INITIAL_EDGE_TYPES) {
+        KNOWN_EDGE_TYPES.add(t);
+    }
+}
+/**
+ * Get current known edge types (for testing/debugging)
+ */
+export function getKnownEdgeTypes() {
+    return new Set(KNOWN_EDGE_TYPES);
+}
+/**
+ * Add a new node type to the known types set
+ */
+export function addKnownNodeType(nodeType) {
+    KNOWN_NODE_TYPES.add(nodeType);
+}
+/**
+ * Add a new edge type to the known types set
+ */
+export function addKnownEdgeType(edgeType) {
+    KNOWN_EDGE_TYPES.add(edgeType);
+}

package/dist/validation/PathValidator.d.ts

@@ -0,0 +1,81 @@
+/**
+ * PathValidator - проверяет безопасность рефакторинга через path equivalence
+ *
+ * КОНЦЕПЦИЯ:
+ * 1. Трассируем пути от main версии функции до endpoints (DATABASE, HTTP, EXTERNAL)
+ * 2. Трассируем пути от __local версии до тех же endpoints
+ * 3. Сравниваем: если все пути сохранились → safe, если нет → breaking change
+ *
+ * ENDPOINTS (критические точки):
+ * - DATABASE_QUERY: запросы к БД
+ * - HTTP_REQUEST: HTTP запросы
+ * - EXTERNAL: внешние сервисы
+ * - FILESYSTEM: операции с файлами
+ * - MODULE_BOUNDARY: exported functions
+ * - SIDE_EFFECTS: console.log, process.exit и т.д.
+ */
+import type { GraphBackend } from '@grafema/types';
+/**
+ * Validation result
+ */
+export interface PathValidationResult {
+    safe: boolean;
+    severity: 'info' | 'warning' | 'error';
+    message: string;
+    deleted?: boolean;
+    missing?: EndpointDiff[];
+    added?: EndpointDiff[];
+    endpointsChecked: number;
+}
+/**
+ * Endpoint diff info
+ */
+interface EndpointDiff {
+    type: string;
+    name: string;
+    reason: string;
+}
+export declare class PathValidator {
+    private backend;
+    constructor(backend: GraphBackend);
+    /**
+     * Проверить эквивалентность путей между main и __local версиями функции
+     *
+     * @param functionName - Имя функции
+     * @param file - Путь к файлу
+     * @returns Результат валидации
+     */
+    checkPathEquivalence(functionName: string, file: string): Promise<PathValidationResult>;
+    /**
+     * Получить все достижимые endpoints из данной ноды
+     *
+     * @param nodeId - ID начальной ноды
+     * @returns Массив endpoint нод
+     */
+    private _getReachableEndpoints;
+    /**
+     * Сравнить два набора endpoints
+     *
+     * @param mainEndpoints - Endpoints из main версии
+     * @param localEndpoints - Endpoints из __local версии
+     * @returns { missing: [], added: [] }
+     */
+    private _compareEndpoints;
+    /**
+     * Получить уникальный ключ для endpoint
+     *
+     * @param endpoint - Endpoint нода
+     * @returns Уникальный ключ
+     */
+    private _getEndpointKey;
+    /**
+     * Получить reason для missing endpoint
+     */
+    private _getMissingReason;
+    /**
+     * Получить reason для added endpoint
+     */
+    private _getAddedReason;
+}
+export {};
+//# sourceMappingURL=PathValidator.d.ts.map

package/dist/validation/PathValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PathValidator.d.ts","sourceRoot":"","sources":["../../src/validation/PathValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAmBnD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAWD,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAe;gBAElB,OAAO,EAAE,YAAY;IAIjC;;;;;;OAMG;IACG,oBAAoB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAsF7F;;;;;OAKG;YACW,sBAAsB;IAwDpC;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IA0CzB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAoBvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAgBzB;;OAEG;IACH,OAAO,CAAC,eAAe;CAexB"}

package/dist/validation/PathValidator.js

@@ -0,0 +1,251 @@
+/**
+ * PathValidator - проверяет безопасность рефакторинга через path equivalence
+ *
+ * КОНЦЕПЦИЯ:
+ * 1. Трассируем пути от main версии функции до endpoints (DATABASE, HTTP, EXTERNAL)
+ * 2. Трассируем пути от __local версии до тех же endpoints
+ * 3. Сравниваем: если все пути сохранились → safe, если нет → breaking change
+ *
+ * ENDPOINTS (критические точки):
+ * - DATABASE_QUERY: запросы к БД
+ * - HTTP_REQUEST: HTTP запросы
+ * - EXTERNAL: внешние сервисы
+ * - FILESYSTEM: операции с файлами
+ * - MODULE_BOUNDARY: exported functions
+ * - SIDE_EFFECTS: console.log, process.exit и т.д.
+ */
+export class PathValidator {
+    backend;
+    constructor(backend) {
+        this.backend = backend;
+    }
+    /**
+     * Проверить эквивалентность путей между main и __local версиями функции
+     *
+     * @param functionName - Имя функции
+     * @param file - Путь к файлу
+     * @returns Результат валидации
+     */
+    async checkPathEquivalence(functionName, file) {
+        // 1. Найти все версии функции (main и __local) по имени
+        const allVersions = [];
+        for await (const node of this.backend.queryNodes({ type: 'FUNCTION', name: functionName })) {
+            // Дополнительно фильтруем по file если он указан
+            if (node.file === file || node.file === undefined) {
+                allVersions.push(node);
+            }
+        }
+        const mainFunction = allVersions.find(n => n.version === 'main');
+        const localFunction = allVersions.find(n => n.version === '__local');
+        // 3. Обработать случаи: deleted, added, exists
+        if (!mainFunction && localFunction) {
+            // Новая функция
+            return {
+                safe: true,
+                severity: 'info',
+                message: `New function added: ${functionName}`,
+                endpointsChecked: 0
+            };
+        }
+        if (mainFunction && !localFunction) {
+            // Функция удалена
+            return {
+                safe: false,
+                severity: 'error',
+                deleted: true,
+                message: `Function deleted: ${functionName}`,
+                endpointsChecked: 0
+            };
+        }
+        if (!mainFunction && !localFunction) {
+            // Функция не найдена вообще
+            return {
+                safe: false,
+                severity: 'error',
+                message: `Function not found: ${functionName}`,
+                endpointsChecked: 0
+            };
+        }
+        // 4. Получить все endpoints для main версии
+        const mainEndpoints = await this._getReachableEndpoints(mainFunction.id);
+        // 5. Получить все endpoints для local версии
+        const localEndpoints = await this._getReachableEndpoints(localFunction.id);
+        // 6. Сравнить endpoints
+        const comparison = this._compareEndpoints(mainEndpoints, localEndpoints);
+        // 7. Определить результат
+        if (comparison.missing.length > 0) {
+            // Breaking change - критические endpoints удалены
+            return {
+                safe: false,
+                severity: 'error',
+                message: `Breaking change detected: ${comparison.missing.length} endpoint(s) no longer reachable`,
+                missing: comparison.missing,
+                endpointsChecked: mainEndpoints.length
+            };
+        }
+        if (comparison.added.length > 0) {
+            // Warning - новые endpoints добавлены
+            return {
+                safe: true,
+                severity: 'warning',
+                message: `New behavior added: ${comparison.added.length} new endpoint(s) reachable`,
+                added: comparison.added,
+                endpointsChecked: mainEndpoints.length
+            };
+        }
+        // Safe refactoring - все endpoints сохранены
+        return {
+            safe: true,
+            severity: 'info',
+            message: `Safe refactoring: all endpoints preserved`,
+            endpointsChecked: mainEndpoints.length
+        };
+    }
+    /**
+     * Получить все достижимые endpoints из данной ноды
+     *
+     * @param nodeId - ID начальной ноды
+     * @returns Массив endpoint нод
+     */
+    async _getReachableEndpoints(nodeId) {
+        // Трассируем пути через CALLS рёбра (BFS до глубины 10)
+        // Endpoints - это ноды типа: DATABASE_QUERY, HTTP_REQUEST, EXTERNAL, FILESYSTEM, SIDE_EFFECT
+        // Или exported FUNCTION (MODULE_BOUNDARY)
+        const CALLS_EDGE_TYPE = 'CALLS';
+        const MAX_DEPTH = 10;
+        // BFS для поиска всех достижимых нод
+        const visited = new Set();
+        const queue = [{ id: nodeId, depth: 0 }];
+        const endpoints = [];
+        while (queue.length > 0) {
+            const { id, depth } = queue.shift();
+            if (visited.has(id) || depth > MAX_DEPTH) {
+                continue;
+            }
+            visited.add(id);
+            // Получить ноду и проверить является ли она endpoint
+            const node = await this.backend.getNode(id);
+            if (node && id !== nodeId) {
+                // Check for endpoint types (new namespaced types + legacy names for backward compat)
+                const endpointTypes = [
+                    'db:query', 'DATABASE_QUERY',
+                    'http:request', 'HTTP_REQUEST',
+                    'EXTERNAL',
+                    'fs:operation', 'FILESYSTEM',
+                    'SIDE_EFFECT',
+                    'net:request', 'EXTERNAL_NETWORK',
+                    'net:stdio', 'EXTERNAL_STDIO'
+                ];
+                const isEndpoint = endpointTypes.includes(node.type) ||
+                    (node.type === 'FUNCTION' && node.exported === true);
+                if (isEndpoint) {
+                    endpoints.push(node);
+                }
+            }
+            // Получить исходящие CALLS рёбра
+            const outgoingEdges = await this.backend.getOutgoingEdges(id, [CALLS_EDGE_TYPE]);
+            for (const edge of outgoingEdges) {
+                const dstId = typeof edge.dst === 'string' ? edge.dst : String(edge.dst);
+                if (!visited.has(dstId)) {
+                    queue.push({ id: dstId, depth: depth + 1 });
+                }
+            }
+        }
+        return endpoints;
+    }
+    /**
+     * Сравнить два набора endpoints
+     *
+     * @param mainEndpoints - Endpoints из main версии
+     * @param localEndpoints - Endpoints из __local версии
+     * @returns { missing: [], added: [] }
+     */
+    _compareEndpoints(mainEndpoints, localEndpoints) {
+        const missing = [];
+        const added = [];
+        // Создаём Map для быстрого поиска
+        const localMap = new Map();
+        localEndpoints.forEach(ep => {
+            const key = this._getEndpointKey(ep);
+            localMap.set(key, ep);
+        });
+        const mainMap = new Map();
+        mainEndpoints.forEach(ep => {
+            const key = this._getEndpointKey(ep);
+            mainMap.set(key, ep);
+        });
+        // Находим missing endpoints (есть в main, но нет в local)
+        for (const [key, endpoint] of mainMap.entries()) {
+            if (!localMap.has(key)) {
+                missing.push({
+                    type: endpoint.type,
+                    name: endpoint.name || endpoint.query || 'unknown',
+                    reason: this._getMissingReason(endpoint)
+                });
+            }
+        }
+        // Находим added endpoints (есть в local, но нет в main)
+        for (const [key, endpoint] of localMap.entries()) {
+            if (!mainMap.has(key)) {
+                added.push({
+                    type: endpoint.type,
+                    name: endpoint.name || endpoint.query || 'unknown',
+                    reason: this._getAddedReason(endpoint)
+                });
+            }
+        }
+        return { missing, added };
+    }
+    /**
+     * Получить уникальный ключ для endpoint
+     *
+     * @param endpoint - Endpoint нода
+     * @returns Уникальный ключ
+     */
+    _getEndpointKey(endpoint) {
+        if (endpoint.type === 'DATABASE_QUERY' || endpoint.type === 'db:query') {
+            // Для DB query используем query text
+            return `db:query:${endpoint.query || endpoint.name}`;
+        }
+        if (endpoint.type === 'FUNCTION' && endpoint.exported) {
+            // Для exported functions используем stable ID
+            return `${endpoint.type}:${endpoint.name}:${endpoint.file}`;
+        }
+        if (endpoint.type === 'EXTERNAL') {
+            // Для external используем service + name
+            return `${endpoint.type}:${endpoint.service}:${endpoint.name}`;
+        }
+        // Для остальных используем type + name
+        return `${endpoint.type}:${endpoint.name}`;
+    }
+    /**
+     * Получить reason для missing endpoint
+     */
+    _getMissingReason(endpoint) {
+        if (endpoint.type === 'DATABASE_QUERY') {
+            return `Database query no longer executed: ${endpoint.query}`;
+        }
+        if (endpoint.type === 'FUNCTION' && endpoint.exported) {
+            return `Exported function no longer called: ${endpoint.name}`;
+        }
+        if (endpoint.type === 'EXTERNAL') {
+            return `External service no longer called: ${endpoint.service}/${endpoint.name}`;
+        }
+        return `Endpoint no longer reachable: ${endpoint.name}`;
+    }
+    /**
+     * Получить reason для added endpoint
+     */
+    _getAddedReason(endpoint) {
+        if (endpoint.type === 'DATABASE_QUERY') {
+            return `New database query added: ${endpoint.query}`;
+        }
+        if (endpoint.type === 'FUNCTION' && endpoint.exported) {
+            return `New call to exported function: ${endpoint.name}`;
+        }
+        if (endpoint.type === 'EXTERNAL') {
+            return `New external service call: ${endpoint.service}/${endpoint.name}`;
+        }
+        return `New endpoint reachable: ${endpoint.name}`;
+    }
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@grafema/core",
+  "version": "0.1.0-alpha.1",
+  "description": "Core analysis engine for Grafema code analysis toolkit",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "grafema",
+    "code-analysis",
+    "ast",
+    "static-analysis"
+  ],
+  "license": "Apache-2.0",
+  "author": "Vadim Reshetnikov",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Disentinel/grafema.git",
+    "directory": "packages/core"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.26.3",
+    "@babel/traverse": "^7.26.4",
+    "@babel/types": "^7.26.3",
+    "@grafema/rfdb-client": "workspace:*",
+    "@grafema/types": "workspace:*",
+    "ajv": "^8.17.1",
+    "chokidar": "^4.0.3",
+    "minimatch": "^10.1.1",
+    "node-source-walk": "^7.0.1",
+    "oxc-parser": "^0.96.0",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@types/babel__traverse": "^7.20.6",
+    "@types/node": "^25.0.8",
+    "typescript": "^5.9.3"
+  }
+}

package/src/.rfguard/current-session.txt

@@ -0,0 +1 @@
+118083cf-1249-4311-b452-79bb704fcf13