@grafema/core 0.1.0-alpha.5 → 0.2.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,129 @@
+/**
+ * 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'];
+    }
+}

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

@@ -17,8 +17,8 @@ interface LiteralNodeOptions {
 }
 export declare class LiteralNode {
     static readonly TYPE: "LITERAL";
-    static readonly REQUIRED: readonly ["file", "line"];
-    static readonly OPTIONAL: readonly ["value", "valueType", "column", "parentCallId", "argIndex"];
+    static readonly REQUIRED: readonly ["file", "line", "column"];
+    static readonly OPTIONAL: readonly ["value", "valueType", "parentCallId", "argIndex"];
     static create(value: unknown, file: string, line: number, column: number, options?: LiteralNodeOptions): LiteralNodeRecord;
     static validate(node: LiteralNodeRecord): string[];
 }

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

@@ -1 +1 @@
-{"version":3,"file":"LiteralNode.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/LiteralNode.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,UAAU,iBAAkB,SAAQ,cAAc;IAChD,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,kBAAkB;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,WAAW;IACtB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,SAAS,CAAU;IAE1C,MAAM,CAAC,QAAQ,CAAC,QAAQ,4BAA6B;IACrD,MAAM,CAAC,QAAQ,CAAC,QAAQ,wEAAyE;IAEjG,MAAM,CAAC,MAAM,CACX,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB;IAsBpB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,EAAE;CASnD;AAED,YAAY,EAAE,iBAAiB,EAAE,CAAC"}
+{"version":3,"file":"LiteralNode.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/LiteralNode.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,UAAU,iBAAkB,SAAQ,cAAc;IAChD,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,kBAAkB;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,WAAW;IACtB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,SAAS,CAAU;IAE1C,MAAM,CAAC,QAAQ,CAAC,QAAQ,sCAAuC;IAC/D,MAAM,CAAC,QAAQ,CAAC,QAAQ,8DAA+D;IAEvF,MAAM,CAAC,MAAM,CACX,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB;IAuBpB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,EAAE;CASnD;AAED,YAAY,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/core/nodes/LiteralNode.js

@@ -3,16 +3,18 @@
  */
 export class LiteralNode {
     static TYPE = 'LITERAL';
-    static REQUIRED = ['file', 'line'];
-    static OPTIONAL = ['value', 'valueType', 'column', 'parentCallId', 'argIndex'];
+    static REQUIRED = ['file', 'line', 'column'];
+    static OPTIONAL = ['value', 'valueType', 'parentCallId', 'argIndex'];
     static create(value, file, line, column, options = {}) {
         if (!file)
             throw new Error('LiteralNode.create: file is required');
         if (line === undefined)
             throw new Error('LiteralNode.create: line is required');
+        if (column === undefined)
+            throw new Error('LiteralNode.create: column is required');
         const counter = options.counter !== undefined ? `:${options.counter}` : '';
         const argIndex = options.argIndex !== undefined ? `arg${options.argIndex}` : 'value';
-        const id = `${file}:LITERAL:${argIndex}:${line}:${column || 0}${counter}`;
+        const id = `${file}:LITERAL:${argIndex}:${line}:${column}${counter}`;
         return {
             id,
             type: this.TYPE,
@@ -21,7 +23,7 @@ export class LiteralNode {
             valueType: typeof value,
             file,
             line,
-            column: column || 0,
+            column,
             parentCallId: options.parentCallId,
             argIndex: options.argIndex
         };

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

@@ -1,7 +1,15 @@
 /**
  * MethodCallNode - contract for METHOD_CALL node
+ *
+ * Supports two creation modes:
+ * 1. createWithContext() - NEW: Uses ScopeContext + Location for semantic IDs
+ * 2. create() - LEGACY: Uses line-based IDs for backward compatibility
+ *
+ * Semantic ID format: {file}->{scope_path}->CALL->{object.method}#N
+ * Example: src/app.js->handler->CALL->db.query#0
  */
 import type { BaseNodeRecord } from '@grafema/types';
+import { type ScopeContext, type Location } from '../SemanticId.js';
 interface MethodCallNodeRecord extends BaseNodeRecord {
     type: 'METHOD_CALL';
     object?: string;
@@ -15,14 +23,36 @@ interface MethodCallNodeOptions {
     args?: unknown[];
     counter?: number;
 }
+/**
+ * Options for createWithContext
+ */
+interface MethodCallContextOptions {
+    discriminator: number;
+    parentScopeId?: string;
+    args?: unknown[];
+}
 export declare class MethodCallNode {
     static readonly TYPE: "METHOD_CALL";
-    static readonly REQUIRED: readonly ["name", "file", "line", "args"];
-    static readonly OPTIONAL: readonly ["object", "method", "column", "parentScopeId"];
+    static readonly REQUIRED: readonly ["name", "file", "line", "column", "args"];
+    static readonly OPTIONAL: readonly ["object", "method", "parentScopeId"];
     /**
      * Create METHOD_CALL node
      */
     static create(objectName: string | undefined, methodName: string, file: string, line: number, column: number, options?: MethodCallNodeOptions): MethodCallNodeRecord;
+    /**
+     * Create METHOD_CALL node with semantic ID (NEW API)
+     *
+     * Uses ScopeContext from ScopeTracker for stable identifiers.
+     * Requires discriminator for multiple calls to same method within scope.
+     *
+     * @param objectName - Object name (can be undefined for bare function calls)
+     * @param methodName - Method name
+     * @param context - Scope context from ScopeTracker.getContext()
+     * @param location - Source location { line, column }
+     * @param options - Options including required discriminator
+     * @returns MethodCallNodeRecord with semantic ID
+     */
+    static createWithContext(objectName: string | undefined, methodName: string, context: ScopeContext, location: Partial<Location>, options: MethodCallContextOptions): MethodCallNodeRecord;
     static validate(node: MethodCallNodeRecord): string[];
 }
 export type { MethodCallNodeRecord };

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

@@ -1 +1 @@
-{"version":3,"file":"MethodCallNode.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/MethodCallNode.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,UAAU,oBAAqB,SAAQ,cAAc;IACnD,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,OAAO,EAAE,CAAC;CACjB;AAED,UAAU,qBAAqB;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,cAAc;IACzB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,aAAa,CAAU;IAE9C,MAAM,CAAC,QAAQ,CAAC,QAAQ,4CAA6C;IACrE,MAAM,CAAC,QAAQ,CAAC,QAAQ,2DAA4D;IAEpF;;OAEG;IACH,MAAM,CAAC,MAAM,CACX,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,qBAA0B,GAClC,oBAAoB;IAuBvB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,EAAE;CAgBtD;AAED,YAAY,EAAE,oBAAoB,EAAE,CAAC"}
+{"version":3,"file":"MethodCallNode.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/MethodCallNode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAqB,KAAK,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEvF,UAAU,oBAAqB,SAAQ,cAAc;IACnD,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,OAAO,EAAE,CAAC;CACjB;AAED,UAAU,qBAAqB;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,UAAU,wBAAwB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;CAClB;AAED,qBAAa,cAAc;IACzB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,aAAa,CAAU;IAE9C,MAAM,CAAC,QAAQ,CAAC,QAAQ,sDAAuD;IAC/E,MAAM,CAAC,QAAQ,CAAC,QAAQ,iDAAkD;IAE1E;;OAEG;IACH,MAAM,CAAC,MAAM,CACX,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,qBAA0B,GAClC,oBAAoB;IAwBvB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,iBAAiB,CACtB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,EAC3B,OAAO,EAAE,wBAAwB,GAChC,oBAAoB;IA6BvB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,EAAE;CAgBtD;AAED,YAAY,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/core/nodes/MethodCallNode.js

@@ -1,10 +1,18 @@
 /**
  * MethodCallNode - contract for METHOD_CALL node
+ *
+ * Supports two creation modes:
+ * 1. createWithContext() - NEW: Uses ScopeContext + Location for semantic IDs
+ * 2. create() - LEGACY: Uses line-based IDs for backward compatibility
+ *
+ * Semantic ID format: {file}->{scope_path}->CALL->{object.method}#N
+ * Example: src/app.js->handler->CALL->db.query#0
  */
+import { computeSemanticId } from '../SemanticId.js';
 export class MethodCallNode {
     static TYPE = 'METHOD_CALL';
-    static REQUIRED = ['name', 'file', 'line', 'args'];
-    static OPTIONAL = ['object', 'method', 'column', 'parentScopeId'];
+    static REQUIRED = ['name', 'file', 'line', 'column', 'args'];
+    static OPTIONAL = ['object', 'method', 'parentScopeId'];
     /**
      * Create METHOD_CALL node
      */
@@ -15,9 +23,11 @@ export class MethodCallNode {
             throw new Error('MethodCallNode.create: file is required');
         if (line === undefined)
             throw new Error('MethodCallNode.create: line is required');
+        if (column === undefined)
+            throw new Error('MethodCallNode.create: column is required');
         const fullName = objectName ? `${objectName}.${methodName}` : methodName;
         const counter = options.counter !== undefined ? `:${options.counter}` : '';
-        const id = `${file}:METHOD_CALL:${fullName}:${line}:${column || 0}${counter}`;
+        const id = `${file}:METHOD_CALL:${fullName}:${line}:${column}${counter}`;
         return {
             id,
             type: this.TYPE,
@@ -26,7 +36,50 @@ export class MethodCallNode {
             method: methodName,
             file,
             line,
-            column: column || 0,
+            column,
+            parentScopeId: options.parentScopeId,
+            args: options.args || []
+        };
+    }
+    /**
+     * Create METHOD_CALL node with semantic ID (NEW API)
+     *
+     * Uses ScopeContext from ScopeTracker for stable identifiers.
+     * Requires discriminator for multiple calls to same method within scope.
+     *
+     * @param objectName - Object name (can be undefined for bare function calls)
+     * @param methodName - Method name
+     * @param context - Scope context from ScopeTracker.getContext()
+     * @param location - Source location { line, column }
+     * @param options - Options including required discriminator
+     * @returns MethodCallNodeRecord with semantic ID
+     */
+    static createWithContext(objectName, methodName, context, location, options) {
+        // Validate required fields
+        if (!methodName)
+            throw new Error('MethodCallNode.createWithContext: methodName is required');
+        if (!context.file)
+            throw new Error('MethodCallNode.createWithContext: file is required');
+        if (location.line === undefined)
+            throw new Error('MethodCallNode.createWithContext: line is required');
+        if (location.column === undefined)
+            throw new Error('MethodCallNode.createWithContext: column is required');
+        if (options.discriminator === undefined)
+            throw new Error('MethodCallNode.createWithContext: discriminator is required');
+        const fullName = objectName ? `${objectName}.${methodName}` : methodName;
+        // Compute semantic ID with discriminator
+        const id = computeSemanticId('CALL', fullName, context, {
+            discriminator: options.discriminator
+        });
+        return {
+            id,
+            type: this.TYPE,
+            name: fullName,
+            object: objectName,
+            method: methodName,
+            file: context.file,
+            line: location.line,
+            column: location.column,
             parentScopeId: options.parentScopeId,
             args: options.args || []
         };

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

@@ -1,7 +1,15 @@
 /**
  * MethodNode - contract for METHOD node (class method)
+ *
+ * Supports two creation modes:
+ * 1. createWithContext() - NEW: Uses ScopeContext + Location for semantic IDs
+ * 2. create() - LEGACY: Uses line-based IDs for backward compatibility
+ *
+ * Semantic ID format: {file}->{className}->METHOD->{name}
+ * Example: src/services/UserService.js->UserService->METHOD->login
  */
 import type { BaseNodeRecord } from '@grafema/types';
+import { type ScopeContext, type Location } from '../SemanticId.js';
 type MethodKind = 'method' | 'get' | 'set' | 'constructor';
 interface MethodNodeRecord extends BaseNodeRecord {
     type: 'METHOD';
@@ -18,11 +26,35 @@ interface MethodNodeOptions {
     static?: boolean;
     kind?: MethodKind;
 }
+/**
+ * Options for createWithContext
+ */
+interface MethodContextOptions {
+    async?: boolean;
+    generator?: boolean;
+    static?: boolean;
+    kind?: MethodKind;
+}
 export declare class MethodNode {
     static readonly TYPE: "METHOD";
-    static readonly REQUIRED: readonly ["name", "file", "line", "className"];
-    static readonly OPTIONAL: readonly ["column", "async", "generator", "static", "kind"];
+    static readonly REQUIRED: readonly ["name", "file", "line", "column", "className"];
+    static readonly OPTIONAL: readonly ["async", "generator", "static", "kind"];
     static create(name: string, file: string, line: number, column: number, className: string, options?: MethodNodeOptions): MethodNodeRecord;
+    /**
+     * Create METHOD node with semantic ID (NEW API)
+     *
+     * Uses ScopeContext from ScopeTracker for stable identifiers.
+     * Method names are unique within class, so no discriminator needed.
+     * Context should include the class in scopePath.
+     *
+     * @param name - Method name
+     * @param className - Name of the class containing this method
+     * @param context - Scope context from ScopeTracker.getContext() (should be inside class)
+     * @param location - Source location { line, column }
+     * @param options - Optional method properties
+     * @returns MethodNodeRecord with semantic ID
+     */
+    static createWithContext(name: string, className: string, context: ScopeContext, location: Partial<Location>, options?: MethodContextOptions): MethodNodeRecord;
     static validate(node: MethodNodeRecord): string[];
 }
 export type { MethodNodeRecord, MethodKind };

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

@@ -1 +1 @@
-{"version":3,"file":"MethodNode.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/MethodNode.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,KAAK,UAAU,GAAG,QAAQ,GAAG,KAAK,GAAG,KAAK,GAAG,aAAa,CAAC;AAE3D,UAAU,gBAAiB,SAAQ,cAAc;IAC/C,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,UAAU,iBAAiB;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAED,qBAAa,UAAU;IACrB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;IAEzC,MAAM,CAAC,QAAQ,CAAC,QAAQ,iDAAkD;IAC1E,MAAM,CAAC,QAAQ,CAAC,QAAQ,8DAA+D;IAEvF,MAAM,CAAC,MAAM,CACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB;IAqBnB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,EAAE;CAgBlD;AAED,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAC"}
+{"version":3,"file":"MethodNode.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/MethodNode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAqB,KAAK,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEvF,KAAK,UAAU,GAAG,QAAQ,GAAG,KAAK,GAAG,KAAK,GAAG,aAAa,CAAC;AAE3D,UAAU,gBAAiB,SAAQ,cAAc;IAC/C,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,UAAU,iBAAiB;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAED;;GAEG;AACH,UAAU,oBAAoB;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAED,qBAAa,UAAU;IACrB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;IAEzC,MAAM,CAAC,QAAQ,CAAC,QAAQ,2DAA4D;IACpF,MAAM,CAAC,QAAQ,CAAC,QAAQ,oDAAqD;IAE7E,MAAM,CAAC,MAAM,CACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB;IAsBnB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,iBAAiB,CACtB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,EAC3B,OAAO,GAAE,oBAAyB,GACjC,gBAAgB;IA0BnB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,EAAE;CAgBlD;AAED,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAC"}

package/dist/core/nodes/MethodNode.js

@@ -1,10 +1,18 @@
 /**
  * MethodNode - contract for METHOD node (class method)
+ *
+ * Supports two creation modes:
+ * 1. createWithContext() - NEW: Uses ScopeContext + Location for semantic IDs
+ * 2. create() - LEGACY: Uses line-based IDs for backward compatibility
+ *
+ * Semantic ID format: {file}->{className}->METHOD->{name}
+ * Example: src/services/UserService.js->UserService->METHOD->login
  */
+import { computeSemanticId } from '../SemanticId.js';
 export class MethodNode {
     static TYPE = 'METHOD';
-    static REQUIRED = ['name', 'file', 'line', 'className'];
-    static OPTIONAL = ['column', 'async', 'generator', 'static', 'kind'];
+    static REQUIRED = ['name', 'file', 'line', 'column', 'className'];
+    static OPTIONAL = ['async', 'generator', 'static', 'kind'];
     static create(name, file, line, column, className, options = {}) {
         if (!name)
             throw new Error('MethodNode.create: name is required');
@@ -12,6 +20,8 @@ export class MethodNode {
             throw new Error('MethodNode.create: file is required');
         if (!line)
             throw new Error('MethodNode.create: line is required');
+        if (column === undefined)
+            throw new Error('MethodNode.create: column is required');
         if (!className)
             throw new Error('MethodNode.create: className is required');
         return {
@@ -20,7 +30,49 @@ export class MethodNode {
             name,
             file,
             line,
-            column: column || 0,
+            column,
+            className,
+            async: options.async || false,
+            generator: options.generator || false,
+            static: options.static || false,
+            kind: options.kind || 'method'
+        };
+    }
+    /**
+     * Create METHOD node with semantic ID (NEW API)
+     *
+     * Uses ScopeContext from ScopeTracker for stable identifiers.
+     * Method names are unique within class, so no discriminator needed.
+     * Context should include the class in scopePath.
+     *
+     * @param name - Method name
+     * @param className - Name of the class containing this method
+     * @param context - Scope context from ScopeTracker.getContext() (should be inside class)
+     * @param location - Source location { line, column }
+     * @param options - Optional method properties
+     * @returns MethodNodeRecord with semantic ID
+     */
+    static createWithContext(name, className, context, location, options = {}) {
+        // Validate required fields
+        if (!name)
+            throw new Error('MethodNode.createWithContext: name is required');
+        if (!className)
+            throw new Error('MethodNode.createWithContext: className is required');
+        if (!context.file)
+            throw new Error('MethodNode.createWithContext: file is required');
+        if (location.line === undefined)
+            throw new Error('MethodNode.createWithContext: line is required');
+        if (location.column === undefined)
+            throw new Error('MethodNode.createWithContext: column is required');
+        // Compute semantic ID
+        const id = computeSemanticId(this.TYPE, name, context);
+        return {
+            id,
+            type: this.TYPE,
+            name,
+            file: context.file,
+            line: location.line,
+            column: location.column,
             className,
             async: options.async || false,
             generator: options.generator || false,

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

@@ -1,7 +1,17 @@
 /**
  * ModuleNode - contract for MODULE node
+ *
+ * Supports two creation modes:
+ * 1. createWithContext() - NEW: Uses ScopeContext for semantic IDs
+ * 2. create() - LEGACY: Uses hash-based IDs for backward compatibility
+ *
+ * Semantic ID format: {file}->global->MODULE->module
+ * Example: src/index.js->global->MODULE->module
+ *
+ * Each file has exactly one MODULE node. The name in the ID is always "module".
  */
 import type { BaseNodeRecord } from '@grafema/types';
+import { type ScopeContext } from '../SemanticId.js';
 interface ModuleNodeRecord extends BaseNodeRecord {
     type: 'MODULE';
     contentHash: string;
@@ -10,6 +20,13 @@ interface ModuleNodeRecord extends BaseNodeRecord {
 interface ModuleNodeOptions {
     isTest?: boolean;
 }
+/**
+ * Options for createWithContext
+ */
+interface ModuleContextOptions {
+    contentHash?: string;
+    isTest?: boolean;
+}
 export declare class ModuleNode {
     static readonly TYPE: "MODULE";
     static readonly REQUIRED: readonly ["name", "file", "contentHash"];
@@ -22,6 +39,20 @@ export declare class ModuleNode {
      * @param options - Additional options (isTest, etc.)
      */
     static create(filePath: string, relativePath: string, contentHash: string, options?: ModuleNodeOptions): ModuleNodeRecord;
+    /**
+     * Create MODULE node with semantic ID (NEW API)
+     *
+     * Uses ScopeContext for stable identifiers that don't change
+     * when file content changes (unlike hash-based IDs).
+     *
+     * Each file has exactly one MODULE node.
+     * The name in the semantic ID is always "module".
+     *
+     * @param context - Scope context with file path (relative to project root)
+     * @param options - Optional contentHash and isTest flag
+     * @returns ModuleNodeRecord with semantic ID
+     */
+    static createWithContext(context: ScopeContext, options?: ModuleContextOptions): ModuleNodeRecord;
     static _hashPath(path: string): string;
     static validate(node: ModuleNodeRecord): string[];
 }

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

@@ -1 +1 @@
-{"version":3,"file":"ModuleNode.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/ModuleNode.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,UAAU,gBAAiB,SAAQ,cAAc;IAC/C,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,UAAU,iBAAiB;IACzB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,UAAU;IACrB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;IAEzC,MAAM,CAAC,QAAQ,CAAC,QAAQ,2CAA4C;IACpE,MAAM,CAAC,QAAQ,CAAC,QAAQ,sBAAuB;IAE/C;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CACX,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB;IAgBnB,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAItC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,EAAE;CAgBlD;AAED,YAAY,EAAE,gBAAgB,EAAE,CAAC"}
+{"version":3,"file":"ModuleNode.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/ModuleNode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAExE,UAAU,gBAAiB,SAAQ,cAAc;IAC/C,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,UAAU,iBAAiB;IACzB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,UAAU,oBAAoB;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,UAAU;IACrB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;IAEzC,MAAM,CAAC,QAAQ,CAAC,QAAQ,2CAA4C;IACpE,MAAM,CAAC,QAAQ,CAAC,QAAQ,sBAAuB;IAE/C;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CACX,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB;IAgBnB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,iBAAiB,CACtB,OAAO,EAAE,YAAY,EACrB,OAAO,GAAE,oBAAyB,GACjC,gBAAgB;IAgBnB,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAItC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,EAAE;CAgBlD;AAED,YAAY,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/core/nodes/ModuleNode.js

@@ -1,7 +1,17 @@
 /**
  * ModuleNode - contract for MODULE node
+ *
+ * Supports two creation modes:
+ * 1. createWithContext() - NEW: Uses ScopeContext for semantic IDs
+ * 2. create() - LEGACY: Uses hash-based IDs for backward compatibility
+ *
+ * Semantic ID format: {file}->global->MODULE->module
+ * Example: src/index.js->global->MODULE->module
+ *
+ * Each file has exactly one MODULE node. The name in the ID is always "module".
  */
 import { createHash } from 'crypto';
+import { computeSemanticId } from '../SemanticId.js';
 export class ModuleNode {
     static TYPE = 'MODULE';
     static REQUIRED = ['name', 'file', 'contentHash'];
@@ -30,6 +40,33 @@ export class ModuleNode {
             isTest: options.isTest || false
         };
     }
+    /**
+     * Create MODULE node with semantic ID (NEW API)
+     *
+     * Uses ScopeContext for stable identifiers that don't change
+     * when file content changes (unlike hash-based IDs).
+     *
+     * Each file has exactly one MODULE node.
+     * The name in the semantic ID is always "module".
+     *
+     * @param context - Scope context with file path (relative to project root)
+     * @param options - Optional contentHash and isTest flag
+     * @returns ModuleNodeRecord with semantic ID
+     */
+    static createWithContext(context, options = {}) {
+        if (!context.file)
+            throw new Error('ModuleNode.createWithContext: file is required in context');
+        const id = computeSemanticId(this.TYPE, 'module', context);
+        return {
+            id,
+            type: this.TYPE,
+            name: context.file,
+            file: context.file,
+            line: 0,
+            contentHash: options.contentHash || '',
+            isTest: options.isTest || false
+        };
+    }
     static _hashPath(path) {
         return createHash('md5').update(path).digest('hex').substring(0, 12);
     }