@grafema/core 0.1.0-alpha.1

package/dist/core/ManifestStore.js

@@ -0,0 +1,146 @@
+/**
+ * ManifestStore - simple persistent processing state storage
+ *
+ * Format: StableID|Phase|Status|Timestamp
+ * Operations: grep for search, sed for update
+ */
+import { existsSync, readFileSync, writeFileSync, appendFileSync } from 'fs';
+import { execSync } from 'child_process';
+export class ManifestStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+        // Create file if doesn't exist
+        if (!existsSync(filePath)) {
+            writeFileSync(filePath, '# StableID|Phase|Status|Timestamp\n', 'utf-8');
+        }
+    }
+    /**
+     * Check if file is processed in phase
+     * @param key - Full key like "PHASE|Plugin|Hash" or stableId
+     * @param phase - For backward compat, ignored if key contains |
+     */
+    isDone(key, phase) {
+        try {
+            // If key already contains pipe, use as-is, else build pattern
+            const searchKey = key.includes('|') ? key : `${key}|${phase}`;
+            const pattern = `^${searchKey}\\|done`;
+            execSync(`grep -q "${pattern}" "${this.filePath}"`, { encoding: 'utf-8' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Mark file as processed in phase
+     * @param key - Full key like "PHASE|Plugin|Hash" or stableId
+     * @param phase - For backward compat, ignored if key contains |
+     */
+    markDone(key, phase) {
+        const timestamp = Math.floor(Date.now() / 1000);
+        const fullKey = key.includes('|') ? key : `${key}|${phase}`;
+        const line = `${fullKey}|done|${timestamp}\n`;
+        // Atomic append
+        appendFileSync(this.filePath, line, 'utf-8');
+    }
+    /**
+     * Mark file as in progress
+     * @param key - Full key like "PHASE|Plugin|Hash" or stableId
+     * @param phase - For backward compat, ignored if key contains |
+     */
+    markInProgress(key, phase) {
+        const timestamp = Math.floor(Date.now() / 1000);
+        const fullKey = key.includes('|') ? key : `${key}|${phase}`;
+        const line = `${fullKey}|in_progress|${timestamp}\n`;
+        appendFileSync(this.filePath, line, 'utf-8');
+    }
+    /**
+     * Get status of file in phase
+     * @param key - Full key like "PHASE|Plugin|Hash" or stableId
+     * @param phase - For backward compat, ignored if key contains |
+     */
+    getStatus(key, phase) {
+        try {
+            const searchKey = key.includes('|') ? key : `${key}|${phase}`;
+            const pattern = `^${searchKey}\\|`;
+            const result = execSync(`grep "${pattern}" "${this.filePath}" | tail -1`, { encoding: 'utf-8' }).trim();
+            if (!result)
+                return 'pending';
+            const parts = result.split('|');
+            // Status is after the key parts
+            const statusIndex = key.includes('|') ? key.split('|').length : 2;
+            return parts[statusIndex];
+        }
+        catch {
+            return 'pending';
+        }
+    }
+    /**
+     * Get all files for phase with specific status
+     */
+    getByStatus(phase, status) {
+        try {
+            const pattern = `\\|${phase}\\|${status}\\|`;
+            const result = execSync(`grep "${pattern}" "${this.filePath}" | cut -d'|' -f1`, { encoding: 'utf-8' }).trim();
+            return result ? result.split('\n') : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Get statistics by phases
+     */
+    getStats() {
+        const content = readFileSync(this.filePath, 'utf-8');
+        const lines = content.split('\n').filter(l => l && !l.startsWith('#'));
+        const stats = {};
+        for (const line of lines) {
+            const parts = line.split('|');
+            const phase = parts[1];
+            const status = parts[2];
+            if (!phase || !status)
+                continue;
+            if (!stats[phase]) {
+                stats[phase] = { done: 0, in_progress: 0, pending: 0 };
+            }
+            if (status in stats[phase]) {
+                stats[phase][status]++;
+            }
+        }
+        return stats;
+    }
+    /**
+     * Clean up stale in_progress (crashed processes)
+     * @param olderThanSeconds - older than N seconds considered dead
+     */
+    cleanupStaleProgress(olderThanSeconds = 300) {
+        const now = Math.floor(Date.now() / 1000);
+        const content = readFileSync(this.filePath, 'utf-8');
+        const lines = content.split('\n');
+        const cleaned = lines.map(line => {
+            if (!line || line.startsWith('#'))
+                return line;
+            const parts = line.split('|');
+            const status = parts[2];
+            const timestamp = parts[3];
+            if (status === 'in_progress' && timestamp) {
+                const age = now - parseInt(timestamp);
+                if (age > olderThanSeconds) {
+                    // Mark as crashed (process died)
+                    parts[2] = 'crashed';
+                    return parts.join('|');
+                }
+            }
+            return line;
+        });
+        writeFileSync(this.filePath, cleaned.join('\n'), 'utf-8');
+    }
+    /**
+     * Clear entire manifest (for testing)
+     */
+    clear() {
+        writeFileSync(this.filePath, '# StableID|Phase|Status|Timestamp\n', 'utf-8');
+    }
+}

package/dist/core/NodeFactory.d.ts

@@ -0,0 +1,160 @@
+/**
+ * NodeFactory - centralized graph node creation
+ *
+ * Single point for creating all node types with:
+ * - Required field validation
+ * - Standard field set for each type
+ * - Automatic ID generation
+ *
+ * Delegates creation to node contracts from ./nodes/
+ */
+import { type EntrypointType, type EntrypointTrigger } from './nodes/index.js';
+import type { BaseNodeRecord } from '@grafema/types';
+interface ServiceOptions {
+    version?: string;
+    entrypoint?: string;
+    discoveryMethod?: string;
+    description?: string;
+    dependencies?: string[];
+    serviceType?: string;
+    testFiles?: string[];
+    metadata?: {
+        type?: string;
+        testFiles?: string[];
+    };
+}
+interface EntrypointOptions {
+    id?: string;
+    name?: string;
+    trigger?: EntrypointTrigger;
+    source?: string;
+    serviceId?: string;
+}
+interface ModuleOptions {
+    contentHash?: string;
+    isTest?: boolean;
+}
+interface FunctionOptions {
+    async?: boolean;
+    generator?: boolean;
+    exported?: boolean;
+    arrowFunction?: boolean;
+    parentScopeId?: string;
+    isClassMethod?: boolean;
+    className?: string;
+    params?: string[];
+    counter?: number;
+}
+interface ScopeOptions {
+    name?: string;
+    conditional?: boolean;
+    parentScopeId?: string;
+    parentFunctionId?: string;
+    capturesFrom?: string[];
+    counter?: number;
+}
+interface CallSiteOptions {
+    parentScopeId?: string;
+    counter?: number;
+}
+interface MethodCallOptions {
+    parentScopeId?: string;
+    args?: unknown[];
+    counter?: number;
+}
+interface VariableOptions {
+    parentScopeId?: string;
+    counter?: number;
+}
+interface ConstantOptions {
+    value?: unknown;
+    parentScopeId?: string;
+    counter?: number;
+}
+interface LiteralOptions {
+    parentCallId?: string;
+    argIndex?: number;
+    counter?: number;
+}
+interface EventListenerOptions {
+    column?: number;
+    parentScopeId?: string;
+    callbackArg?: string;
+    counter?: number;
+}
+interface HttpRequestOptions {
+    column?: number;
+    parentScopeId?: string;
+    counter?: number;
+}
+interface DatabaseQueryOptions {
+    parentScopeId?: string;
+}
+export declare class NodeFactory {
+    /**
+     * Create SERVICE node
+     */
+    static createService(name: string, projectPath: string, options?: ServiceOptions): import("./nodes/ServiceNode.js").ServiceNodeRecord;
+    /**
+     * Create ENTRYPOINT node
+     */
+    static createEntrypoint(file: string, entrypointType: EntrypointType, options?: EntrypointOptions): import("./nodes/EntrypointNode.js").EntrypointNodeRecord;
+    /**
+     * Create MODULE node
+     */
+    static createModule(filePath: string, projectPath: string, options?: ModuleOptions): import("./nodes/ModuleNode.js").ModuleNodeRecord;
+    /**
+     * Create FUNCTION node
+     */
+    static createFunction(name: string, file: string, line: number, column: number, options?: FunctionOptions): import("@grafema/types").FunctionNodeRecord;
+    /**
+     * Create SCOPE node
+     */
+    static createScope(scopeType: string, file: string, line: number, options?: ScopeOptions): import("./nodes/ScopeNode.js").ScopeNodeRecord;
+    /**
+     * Create CALL_SITE node
+     */
+    static createCallSite(targetName: string, file: string, line: number, column: number, options?: CallSiteOptions): import("./nodes/CallSiteNode.js").CallSiteNodeRecord;
+    /**
+     * Create METHOD_CALL node
+     */
+    static createMethodCall(objectName: string | undefined, methodName: string, file: string, line: number, column: number, options?: MethodCallOptions): import("./nodes/MethodCallNode.js").MethodCallNodeRecord;
+    /**
+     * Create VARIABLE_DECLARATION node
+     */
+    static createVariableDeclaration(name: string, file: string, line: number, column: number, options?: VariableOptions): import("./nodes/VariableDeclarationNode.js").VariableDeclarationNodeRecord;
+    /**
+     * Create CONSTANT node
+     */
+    static createConstant(name: string, file: string, line: number, column: number, options?: ConstantOptions): import("./nodes/ConstantNode.js").ConstantNodeRecord;
+    /**
+     * Create LITERAL node
+     */
+    static createLiteral(value: unknown, file: string, line: number, column: number, options?: LiteralOptions): import("./nodes/LiteralNode.js").LiteralNodeRecord;
+    /**
+     * Create EXTERNAL_STDIO node (singleton)
+     */
+    static createExternalStdio(): import("./nodes/ExternalStdioNode.js").ExternalStdioNodeRecord;
+    /**
+     * Create EVENT_LISTENER node
+     */
+    static createEventListener(eventName: string, objectName: string | undefined, file: string, line: number, options?: EventListenerOptions): import("./nodes/EventListenerNode.js").EventListenerNodeRecord;
+    /**
+     * Create HTTP_REQUEST node
+     */
+    static createHttpRequest(url: string | undefined, method: string | undefined, file: string, line: number, options?: HttpRequestOptions): import("./nodes/HttpRequestNode.js").HttpRequestNodeRecord;
+    /**
+     * Create DATABASE_QUERY node
+     */
+    static createDatabaseQuery(query: string | undefined, operation: string | undefined, file: string, line: number, options?: DatabaseQueryOptions): import("./nodes/DatabaseQueryNode.js").DatabaseQueryNodeRecord;
+    /**
+     * Validate node by its type
+     */
+    static validate(node: BaseNodeRecord): string[];
+    /**
+     * Helper: hash file path for stable ID
+     */
+    static _hashFile(filePath: string): string;
+}
+export {};
+//# sourceMappingURL=NodeFactory.d.ts.map

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

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

package/dist/core/NodeFactory.js

@@ -0,0 +1,137 @@
+/**
+ * NodeFactory - centralized graph node creation
+ *
+ * Single point for creating all node types with:
+ * - Required field validation
+ * - Standard field set for each type
+ * - Automatic ID generation
+ *
+ * Delegates creation to node contracts from ./nodes/
+ */
+import { createHash } from 'crypto';
+import { basename, relative } from 'path';
+import { ServiceNode, EntrypointNode, ModuleNode, FunctionNode, ScopeNode, CallSiteNode, MethodCallNode, VariableDeclarationNode, ConstantNode, LiteralNode, ExternalStdioNode, EventListenerNode, HttpRequestNode, DatabaseQueryNode, } from './nodes/index.js';
+export class NodeFactory {
+    /**
+     * Create SERVICE node
+     */
+    static createService(name, projectPath, options = {}) {
+        return ServiceNode.create(name, projectPath, options);
+    }
+    /**
+     * Create ENTRYPOINT node
+     */
+    static createEntrypoint(file, entrypointType, options = {}) {
+        return EntrypointNode.create(file, entrypointType, options);
+    }
+    /**
+     * Create MODULE node
+     */
+    static createModule(filePath, projectPath, options = {}) {
+        if (!filePath)
+            throw new Error('NodeFactory.createModule: filePath is required');
+        if (!projectPath)
+            throw new Error('NodeFactory.createModule: projectPath is required');
+        const contentHash = options.contentHash || this._hashFile(filePath);
+        const relativePath = relative(projectPath, filePath) || basename(filePath);
+        return ModuleNode.create(filePath, relativePath, contentHash, options);
+    }
+    /**
+     * Create FUNCTION node
+     */
+    static createFunction(name, file, line, column, options = {}) {
+        return FunctionNode.create(name, file, line, column, options);
+    }
+    /**
+     * Create SCOPE node
+     */
+    static createScope(scopeType, file, line, options = {}) {
+        return ScopeNode.create(scopeType, file, line, options);
+    }
+    /**
+     * Create CALL_SITE node
+     */
+    static createCallSite(targetName, file, line, column, options = {}) {
+        return CallSiteNode.create(targetName, file, line, column, options);
+    }
+    /**
+     * Create METHOD_CALL node
+     */
+    static createMethodCall(objectName, methodName, file, line, column, options = {}) {
+        return MethodCallNode.create(objectName, methodName, file, line, column, options);
+    }
+    /**
+     * Create VARIABLE_DECLARATION node
+     */
+    static createVariableDeclaration(name, file, line, column, options = {}) {
+        return VariableDeclarationNode.create(name, file, line, column, options);
+    }
+    /**
+     * Create CONSTANT node
+     */
+    static createConstant(name, file, line, column, options = {}) {
+        return ConstantNode.create(name, file, line, column, options);
+    }
+    /**
+     * Create LITERAL node
+     */
+    static createLiteral(value, file, line, column, options = {}) {
+        return LiteralNode.create(value, file, line, column, options);
+    }
+    /**
+     * Create EXTERNAL_STDIO node (singleton)
+     */
+    static createExternalStdio() {
+        return ExternalStdioNode.create();
+    }
+    /**
+     * Create EVENT_LISTENER node
+     */
+    static createEventListener(eventName, objectName, file, line, options = {}) {
+        return EventListenerNode.create(eventName, objectName, file, line, options);
+    }
+    /**
+     * Create HTTP_REQUEST node
+     */
+    static createHttpRequest(url, method, file, line, options = {}) {
+        return HttpRequestNode.create(url, method, file, line, options);
+    }
+    /**
+     * Create DATABASE_QUERY node
+     */
+    static createDatabaseQuery(query, operation, file, line, options = {}) {
+        return DatabaseQueryNode.create(query, operation, file, line, options);
+    }
+    /**
+     * Validate node by its type
+     */
+    static validate(node) {
+        const validators = {
+            'SERVICE': ServiceNode,
+            'ENTRYPOINT': EntrypointNode,
+            'MODULE': ModuleNode,
+            'FUNCTION': FunctionNode,
+            'SCOPE': ScopeNode,
+            'CALL_SITE': CallSiteNode,
+            'METHOD_CALL': MethodCallNode,
+            'VARIABLE_DECLARATION': VariableDeclarationNode,
+            'CONSTANT': ConstantNode,
+            'LITERAL': LiteralNode,
+            'EXTERNAL_STDIO': ExternalStdioNode,
+            'EVENT_LISTENER': EventListenerNode,
+            'HTTP_REQUEST': HttpRequestNode,
+            'DATABASE_QUERY': DatabaseQueryNode
+        };
+        const validator = validators[node.type];
+        if (!validator) {
+            return [`Unknown node type: ${node.type}`];
+        }
+        return validator.validate(node);
+    }
+    /**
+     * Helper: hash file path for stable ID
+     */
+    static _hashFile(filePath) {
+        return createHash('md5').update(filePath).digest('hex').substring(0, 12);
+    }
+}

package/dist/core/NodeId.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Deterministic Node ID generation scheme for the graph
+ *
+ * Format: TYPE|SCOPE|FILE|IDENTIFIER|LINE:COL
+ *
+ * Components:
+ * - TYPE: node type (MODULE, FUNCTION, CLASS, METHOD, VARIABLE, etc.)
+ * - SCOPE: context/scope (path to parent or project)
+ * - FILE: relative file path from project root
+ * - IDENTIFIER: entity name (for MODULE can be empty)
+ * - LINE:COL: position in file (for uniqueness of anonymous functions)
+ *
+ * Examples:
+ * MODULE|/project|src/index.js||0:0
+ * FUNCTION|/project|src/index.js|handleRequest|42:5
+ * CLASS|/project|src/User.js|User|10:0
+ * METHOD|User|src/User.js|login|25:2
+ * VARIABLE|handleRequest|src/index.js|userId|45:10
+ * EXTERNAL_MODULE|/project||express|0:0
+ */
+/**
+ * Parameters for computing Node ID
+ */
+export interface NodeIdParams {
+    type: string;
+    scope?: string;
+    file?: string;
+    identifier?: string;
+    line?: number;
+    column?: number;
+}
+/**
+ * Parsed Node ID components
+ */
+export interface ParsedNodeId {
+    type: string;
+    scope: string;
+    file: string;
+    identifier: string;
+    line: number;
+    column: number;
+}
+/**
+ * Compute deterministic Node ID
+ */
+export declare function computeNodeId({ type, scope, file, identifier, line, column }: NodeIdParams): string;
+/**
+ * Compute u128 numeric ID from string (for Rust backend)
+ * Uses SHA-256 hash and takes first 16 bytes
+ */
+export declare function computeNumericId(stringId: string): bigint;
+/**
+ * Parse Node ID back into components
+ */
+export declare function parseNodeId(nodeId: string): ParsedNodeId;
+/**
+ * Helper for creating MODULE ID
+ */
+export declare function createModuleId(filePath: string, projectPath?: string): string;
+/**
+ * Helper for creating FUNCTION ID
+ */
+export declare function createFunctionId(filePath: string, functionName: string, line: number, column: number, scope?: string): string;
+/**
+ * Helper for creating CLASS ID
+ */
+export declare function createClassId(filePath: string, className: string, line: number, column: number, scope?: string): string;
+/**
+ * Helper for creating METHOD ID
+ */
+export declare function createMethodId(filePath: string, className: string, methodName: string, line: number, column: number): string;
+/**
+ * Helper for creating VARIABLE ID
+ */
+export declare function createVariableId(filePath: string, varName: string, line: number, column: number, scope: string): string;
+/**
+ * Helper for creating EXTERNAL_MODULE ID
+ */
+export declare function createExternalModuleId(moduleName: string, projectPath?: string): string;
+/**
+ * Helper for creating IMPORT ID
+ */
+export declare function createImportId(filePath: string, source: string, localName: string, line: number, scope?: string): string;
+/**
+ * Helper for creating EXPORT ID
+ */
+export declare function createExportId(filePath: string, exportName: string, line: number, scope?: string): string;
+//# sourceMappingURL=NodeId.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NodeId.d.ts","sourceRoot":"","sources":["../../src/core/NodeId.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAC5B,IAAI,EACJ,KAAU,EACV,IAAS,EACT,UAAe,EACf,IAAQ,EACR,MAAU,EACX,EAAE,YAAY,GAAG,MAAM,CAWvB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUzD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAiBxD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,GAAE,MAAmB,GAAG,MAAM,CASzF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAmB,GACzB,MAAM,CASR;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAmB,GACzB,MAAM,CASR;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,MAAM,CASR;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,MAAM,CASR;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,WAAW,GAAE,MAAmB,GAC/B,MAAM,CASR;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,MAAmB,GACzB,MAAM,CASR;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,MAAmB,GACzB,MAAM,CASR"}