@grafema/core 0.1.0-alpha.4 → 0.1.1-alpha

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,6 +23,14 @@ 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"];
@@ -23,6 +39,20 @@ export declare class MethodCallNode {
      * 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,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;;;;;;;;;;;;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;IA4BvB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,EAAE;CAgBtD;AAED,YAAY,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/core/nodes/MethodCallNode.js

@@ -1,6 +1,14 @@
 /**
  * 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'];
@@ -31,6 +39,47 @@ export class MethodCallNode {
             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 (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 ?? 0,
+            parentScopeId: options.parentScopeId,
+            args: options.args || []
+        };
+    }
     static validate(node) {
         const errors = [];
         if (node.type !== this.TYPE) {

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 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,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;;;;;;;;;;;;;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;IAyBnB,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,6 +1,14 @@
 /**
  * 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'];
@@ -28,6 +36,46 @@ export class MethodNode {
             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');
+        // 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 ?? 0,
+            className,
+            async: options.async || false,
+            generator: options.generator || false,
+            static: options.static || false,
+            kind: options.kind || 'method'
+        };
+    }
     static validate(node) {
         const errors = [];
         if (node.type !== this.TYPE) {

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);
     }

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

@@ -0,0 +1,54 @@
+/**
+ * NetworkRequestNode - contract for net:request singleton node
+ *
+ * Represents the external network as a system resource.
+ * All HTTP_REQUEST nodes connect to this singleton via CALLS edges.
+ *
+ * This is NOT the same as HttpRequestNode (type: HTTP_REQUEST), which represents
+ * individual HTTP request call sites in source code.
+ *
+ * Architectural role:
+ * - net:request is a singleton representing external network (like net:stdio for console I/O)
+ * - HTTP_REQUEST nodes are call sites that connect to this singleton via CALLS edges
+ *
+ * Example graph structure:
+ * ```
+ * /app/api.ts:HTTP_REQUEST:GET:15:0 --CALLS--> net:request#__network__
+ * /app/service.ts:HTTP_REQUEST:POST:42:0 --CALLS--> net:request#__network__
+ * ```
+ */
+import type { BaseNodeRecord } from '@grafema/types';
+interface NetworkRequestNodeRecord extends BaseNodeRecord {
+    type: 'net:request';
+}
+export declare class NetworkRequestNode {
+    static readonly TYPE: "net:request";
+    static readonly SINGLETON_ID = "net:request#__network__";
+    static readonly REQUIRED: readonly ["name", "file"];
+    static readonly OPTIONAL: readonly [];
+    /**
+     * Create net:request singleton node
+     *
+     * This node represents the external network as a system resource.
+     * All HTTP_REQUEST nodes connect to this singleton via CALLS edges.
+     *
+     * Should be created once per graph. GraphBuilder and ExpressAnalyzer
+     * use singleton deduplication to ensure only one instance exists.
+     *
+     * @returns NetworkRequestNodeRecord - singleton node
+     */
+    static create(): NetworkRequestNodeRecord;
+    /**
+     * Validate net:request node structure
+     *
+     * Ensures:
+     * - type is net:request (NOT NET_REQUEST)
+     * - id matches SINGLETON_ID
+     *
+     * @param node - Node to validate
+     * @returns Array of error messages (empty if valid)
+     */
+    static validate(node: NetworkRequestNodeRecord): string[];
+}
+export type { NetworkRequestNodeRecord };
+//# sourceMappingURL=NetworkRequestNode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NetworkRequestNode.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/NetworkRequestNode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,UAAU,wBAAyB,SAAQ,cAAc;IACvD,IAAI,EAAE,aAAa,CAAC;CACrB;AAED,qBAAa,kBAAkB;IAC7B,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,aAAa,CAAU;IAC9C,MAAM,CAAC,QAAQ,CAAC,YAAY,6BAA6B;IAEzD,MAAM,CAAC,QAAQ,CAAC,QAAQ,4BAA6B;IACrD,MAAM,CAAC,QAAQ,CAAC,QAAQ,cAAe;IAEvC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,MAAM,IAAI,wBAAwB;IAUzC;;;;;;;;;OASG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,wBAAwB,GAAG,MAAM,EAAE;CAU1D;AAED,YAAY,EAAE,wBAAwB,EAAE,CAAC"}

package/dist/core/nodes/NetworkRequestNode.js

@@ -0,0 +1,65 @@
+/**
+ * NetworkRequestNode - contract for net:request singleton node
+ *
+ * Represents the external network as a system resource.
+ * All HTTP_REQUEST nodes connect to this singleton via CALLS edges.
+ *
+ * This is NOT the same as HttpRequestNode (type: HTTP_REQUEST), which represents
+ * individual HTTP request call sites in source code.
+ *
+ * Architectural role:
+ * - net:request is a singleton representing external network (like net:stdio for console I/O)
+ * - HTTP_REQUEST nodes are call sites that connect to this singleton via CALLS edges
+ *
+ * Example graph structure:
+ * ```
+ * /app/api.ts:HTTP_REQUEST:GET:15:0 --CALLS--> net:request#__network__
+ * /app/service.ts:HTTP_REQUEST:POST:42:0 --CALLS--> net:request#__network__
+ * ```
+ */
+export class NetworkRequestNode {
+    static TYPE = 'net:request';
+    static SINGLETON_ID = 'net:request#__network__';
+    static REQUIRED = ['name', 'file'];
+    static OPTIONAL = [];
+    /**
+     * Create net:request singleton node
+     *
+     * This node represents the external network as a system resource.
+     * All HTTP_REQUEST nodes connect to this singleton via CALLS edges.
+     *
+     * Should be created once per graph. GraphBuilder and ExpressAnalyzer
+     * use singleton deduplication to ensure only one instance exists.
+     *
+     * @returns NetworkRequestNodeRecord - singleton node
+     */
+    static create() {
+        return {
+            id: this.SINGLETON_ID,
+            type: this.TYPE,
+            name: '__network__',
+            file: '__builtin__',
+            line: 0
+        };
+    }
+    /**
+     * Validate net:request node structure
+     *
+     * Ensures:
+     * - type is net:request (NOT NET_REQUEST)
+     * - id matches SINGLETON_ID
+     *
+     * @param node - Node to validate
+     * @returns Array of error messages (empty if valid)
+     */
+    static validate(node) {
+        const errors = [];
+        if (node.type !== this.TYPE) {
+            errors.push(`Expected type ${this.TYPE}, got ${node.type}`);
+        }
+        if (node.id !== this.SINGLETON_ID) {
+            errors.push(`Invalid singleton ID: expected ${this.SINGLETON_ID}, got ${node.id}`);
+        }
+        return errors;
+    }
+}

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

@@ -0,0 +1,27 @@
+/**
+ * ObjectLiteralNode - contract for OBJECT_LITERAL node
+ *
+ * Represents an object literal expression: { key: value, ... }
+ * Used for tracking data flow through object construction.
+ */
+import type { BaseNodeRecord } from '@grafema/types';
+interface ObjectLiteralNodeRecord extends BaseNodeRecord {
+    type: 'OBJECT_LITERAL';
+    column: number;
+    parentCallId?: string;
+    argIndex?: number;
+}
+interface ObjectLiteralNodeOptions {
+    parentCallId?: string;
+    argIndex?: number;
+    counter?: number;
+}
+export declare class ObjectLiteralNode {
+    static readonly TYPE: "OBJECT_LITERAL";
+    static readonly REQUIRED: readonly ["file", "line", "column"];
+    static readonly OPTIONAL: readonly ["parentCallId", "argIndex"];
+    static create(file: string, line: number, column: number, options?: ObjectLiteralNodeOptions): ObjectLiteralNodeRecord;
+    static validate(node: ObjectLiteralNodeRecord): string[];
+}
+export type { ObjectLiteralNodeRecord, ObjectLiteralNodeOptions };
+//# sourceMappingURL=ObjectLiteralNode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ObjectLiteralNode.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/ObjectLiteralNode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,UAAU,uBAAwB,SAAQ,cAAc;IACtD,IAAI,EAAE,gBAAgB,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,wBAAwB;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,iBAAiB;IAC5B,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,gBAAgB,CAAU;IAEjD,MAAM,CAAC,QAAQ,CAAC,QAAQ,sCAAuC;IAC/D,MAAM,CAAC,QAAQ,CAAC,QAAQ,wCAAyC;IAEjE,MAAM,CAAC,MAAM,CACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,wBAA6B,GACrC,uBAAuB;IAoB1B,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,GAAG,MAAM,EAAE;CASzD;AAED,YAAY,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,CAAC"}

package/dist/core/nodes/ObjectLiteralNode.js

@@ -0,0 +1,41 @@
+/**
+ * ObjectLiteralNode - contract for OBJECT_LITERAL node
+ *
+ * Represents an object literal expression: { key: value, ... }
+ * Used for tracking data flow through object construction.
+ */
+export class ObjectLiteralNode {
+    static TYPE = 'OBJECT_LITERAL';
+    static REQUIRED = ['file', 'line', 'column'];
+    static OPTIONAL = ['parentCallId', 'argIndex'];
+    static create(file, line, column, options = {}) {
+        if (!file)
+            throw new Error('ObjectLiteralNode.create: file is required');
+        if (line === undefined)
+            throw new Error('ObjectLiteralNode.create: line is required');
+        const counter = options.counter !== undefined ? `:${options.counter}` : '';
+        const argSuffix = options.argIndex !== undefined ? `arg${options.argIndex}` : 'obj';
+        const id = `OBJECT_LITERAL#${argSuffix}#${file}#${line}:${column || 0}${counter}`;
+        return {
+            id,
+            type: this.TYPE,
+            name: `<object>`,
+            file,
+            line,
+            column: column || 0,
+            parentCallId: options.parentCallId,
+            argIndex: options.argIndex
+        };
+    }
+    static validate(node) {
+        const errors = [];
+        if (node.type !== this.TYPE)
+            errors.push(`Expected type ${this.TYPE}`);
+        const nodeRecord = node;
+        for (const field of this.REQUIRED) {
+            if (nodeRecord[field] === undefined)
+                errors.push(`Missing: ${field}`);
+        }
+        return errors;
+    }
+}

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

@@ -1,7 +1,15 @@
 /**
  * ScopeNode - contract for SCOPE 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}->SCOPE->{scopeType}#N
+ * Example: src/app.js->handler->SCOPE->if#0
  */
 import type { BaseNodeRecord } from '@grafema/types';
+import { type ScopeContext, type Location } from '../SemanticId.js';
 interface ScopeNodeRecord extends BaseNodeRecord {
     type: 'SCOPE';
     scopeType: string;
@@ -18,6 +26,16 @@ interface ScopeNodeOptions {
     capturesFrom?: string[];
     counter?: number;
 }
+/**
+ * Options for createWithContext
+ */
+interface ScopeContextOptions {
+    discriminator: number;
+    conditional?: boolean;
+    parentScopeId?: string;
+    parentFunctionId?: string;
+    capturesFrom?: string[];
+}
 export declare class ScopeNode {
     static readonly TYPE: "SCOPE";
     static readonly REQUIRED: readonly ["scopeType", "file", "line"];
@@ -26,6 +44,19 @@ export declare class ScopeNode {
      * Create SCOPE node
      */
     static create(scopeType: string, file: string, line: number, options?: ScopeNodeOptions): ScopeNodeRecord;
+    /**
+     * Create SCOPE node with semantic ID (NEW API)
+     *
+     * Uses ScopeContext from ScopeTracker for stable identifiers.
+     * Requires discriminator for multiple scopes of same type within parent scope.
+     *
+     * @param scopeType - Type of scope (if, else, try, catch, finally, for, while, switch)
+     * @param context - Scope context from ScopeTracker.getContext()
+     * @param location - Source location { line }
+     * @param options - Options including required discriminator
+     * @returns ScopeNodeRecord with semantic ID
+     */
+    static createWithContext(scopeType: string, context: ScopeContext, location: Partial<Location>, options: ScopeContextOptions): ScopeNodeRecord;
     static validate(node: ScopeNodeRecord): string[];
 }
 export type { ScopeNodeRecord };

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

@@ -1 +1 @@
-{"version":3,"file":"ScopeNode.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/ScopeNode.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,UAAU,eAAgB,SAAQ,cAAc;IAC9C,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,UAAU,gBAAgB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,SAAS;IACpB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAU;IAExC,MAAM,CAAC,QAAQ,CAAC,QAAQ,yCAA0C;IAClE,MAAM,CAAC,QAAQ,CAAC,QAAQ,wFAAyF;IAEjH;;OAEG;IACH,MAAM,CAAC,MAAM,CACX,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,gBAAqB,GAC7B,eAAe;IAuBlB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,EAAE;CAgBjD;AAED,YAAY,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"ScopeNode.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/ScopeNode.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,eAAgB,SAAQ,cAAc;IAC9C,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,UAAU,gBAAgB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,UAAU,mBAAmB;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,qBAAa,SAAS;IACpB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAU;IAExC,MAAM,CAAC,QAAQ,CAAC,QAAQ,yCAA0C;IAClE,MAAM,CAAC,QAAQ,CAAC,QAAQ,wFAAyF;IAEjH;;OAEG;IACH,MAAM,CAAC,MAAM,CACX,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,gBAAqB,GAC7B,eAAe;IAuBlB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,iBAAiB,CACtB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,EAC3B,OAAO,EAAE,mBAAmB,GAC3B,eAAe;IA6BlB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,EAAE;CAgBjD;AAED,YAAY,EAAE,eAAe,EAAE,CAAC"}