@grafema/core 0.1.0-alpha.5 → 0.2.0-beta

package/dist/core/nodes/DecoratorNode.js

@@ -0,0 +1,64 @@
+/**
+ * DecoratorNode - contract for DECORATOR node
+ *
+ * Represents TypeScript/JavaScript decorators applied to
+ * classes, methods, properties, or parameters.
+ *
+ * ID format: {file}:DECORATOR:{name}:{line}:{column}
+ * Example: /src/services/UserService.ts:DECORATOR:Injectable:5:0
+ */
+export class DecoratorNode {
+    static TYPE = 'DECORATOR';
+    static REQUIRED = ['name', 'file', 'line', 'column', 'targetId', 'targetType'];
+    static OPTIONAL = ['arguments'];
+    /**
+     * Create DECORATOR node
+     *
+     * @param name - Decorator name
+     * @param file - File path
+     * @param line - Line number
+     * @param column - Column position
+     * @param targetId - ID of decorated element
+     * @param targetType - Type of decorated element
+     * @param options - Optional decorator properties
+     * @returns DecoratorNodeRecord
+     */
+    static create(name, file, line, column, targetId, targetType, options = {}) {
+        if (!name)
+            throw new Error('DecoratorNode.create: name is required');
+        if (!file)
+            throw new Error('DecoratorNode.create: file is required');
+        if (!line)
+            throw new Error('DecoratorNode.create: line is required');
+        if (column === undefined)
+            throw new Error('DecoratorNode.create: column is required');
+        if (!targetId)
+            throw new Error('DecoratorNode.create: targetId is required');
+        if (!targetType)
+            throw new Error('DecoratorNode.create: targetType is required');
+        return {
+            id: `${file}:DECORATOR:${name}:${line}:${column}`,
+            type: this.TYPE,
+            name,
+            file,
+            line,
+            column,
+            arguments: options.arguments || [],
+            targetId,
+            targetType
+        };
+    }
+    static validate(node) {
+        const errors = [];
+        if (node.type !== this.TYPE) {
+            errors.push(`Expected type ${this.TYPE}, got ${node.type}`);
+        }
+        const nodeRecord = node;
+        for (const field of this.REQUIRED) {
+            if (!nodeRecord[field]) {
+                errors.push(`Missing required field: ${field}`);
+            }
+        }
+        return errors;
+    }
+}

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

@@ -0,0 +1,42 @@
+/**
+ * EnumNode - contract for ENUM node
+ *
+ * Represents TypeScript enum declarations.
+ *
+ * ID format: {file}:ENUM:{name}:{line}
+ * Example: /src/types.ts:ENUM:Status:20
+ */
+import type { BaseNodeRecord } from '@grafema/types';
+interface EnumMemberRecord {
+    name: string;
+    value?: string | number;
+}
+interface EnumNodeRecord extends BaseNodeRecord {
+    type: 'ENUM';
+    column: number;
+    isConst: boolean;
+    members: EnumMemberRecord[];
+}
+interface EnumNodeOptions {
+    isConst?: boolean;
+    members?: EnumMemberRecord[];
+}
+export declare class EnumNode {
+    static readonly TYPE: "ENUM";
+    static readonly REQUIRED: readonly ["name", "file", "line", "column"];
+    static readonly OPTIONAL: readonly ["isConst", "members"];
+    /**
+     * Create ENUM node
+     *
+     * @param name - Enum name
+     * @param file - File path
+     * @param line - Line number
+     * @param column - Column position
+     * @param options - Optional enum properties
+     * @returns EnumNodeRecord
+     */
+    static create(name: string, file: string, line: number, column: number, options?: EnumNodeOptions): EnumNodeRecord;
+    static validate(node: EnumNodeRecord): string[];
+}
+export type { EnumNodeRecord, EnumMemberRecord };
+//# sourceMappingURL=EnumNode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EnumNode.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/EnumNode.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED,UAAU,cAAe,SAAQ,cAAc;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED,UAAU,eAAe;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAED,qBAAa,QAAQ;IACnB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;IAEvC,MAAM,CAAC,QAAQ,CAAC,QAAQ,8CAA+C;IACvE,MAAM,CAAC,QAAQ,CAAC,QAAQ,kCAAmC;IAE3D;;;;;;;;;OASG;IACH,MAAM,CAAC,MAAM,CACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,eAAoB,GAC5B,cAAc;IAkBjB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,EAAE;CAgBhD;AAED,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/core/nodes/EnumNode.js

@@ -0,0 +1,56 @@
+/**
+ * EnumNode - contract for ENUM node
+ *
+ * Represents TypeScript enum declarations.
+ *
+ * ID format: {file}:ENUM:{name}:{line}
+ * Example: /src/types.ts:ENUM:Status:20
+ */
+export class EnumNode {
+    static TYPE = 'ENUM';
+    static REQUIRED = ['name', 'file', 'line', 'column'];
+    static OPTIONAL = ['isConst', 'members'];
+    /**
+     * Create ENUM node
+     *
+     * @param name - Enum name
+     * @param file - File path
+     * @param line - Line number
+     * @param column - Column position
+     * @param options - Optional enum properties
+     * @returns EnumNodeRecord
+     */
+    static create(name, file, line, column, options = {}) {
+        if (!name)
+            throw new Error('EnumNode.create: name is required');
+        if (!file)
+            throw new Error('EnumNode.create: file is required');
+        if (!line)
+            throw new Error('EnumNode.create: line is required');
+        if (column === undefined)
+            throw new Error('EnumNode.create: column is required');
+        return {
+            id: `${file}:ENUM:${name}:${line}`,
+            type: this.TYPE,
+            name,
+            file,
+            line,
+            column,
+            isConst: options.isConst || false,
+            members: options.members || []
+        };
+    }
+    static validate(node) {
+        const errors = [];
+        if (node.type !== this.TYPE) {
+            errors.push(`Expected type ${this.TYPE}, got ${node.type}`);
+        }
+        const nodeRecord = node;
+        for (const field of this.REQUIRED) {
+            if (!nodeRecord[field]) {
+                errors.push(`Missing required field: ${field}`);
+            }
+        }
+        return errors;
+    }
+}

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

@@ -4,21 +4,21 @@
 import type { BaseNodeRecord } from '@grafema/types';
 interface EventListenerNodeRecord extends BaseNodeRecord {
     type: 'EVENT_LISTENER';
+    column: number;
     object?: string;
     parentScopeId?: string;
     callbackArg?: string;
 }
 interface EventListenerNodeOptions {
-    column?: number;
     parentScopeId?: string;
     callbackArg?: string;
     counter?: number;
 }
 export declare class EventListenerNode {
     static readonly TYPE: "EVENT_LISTENER";
-    static readonly REQUIRED: readonly ["name", "file", "line"];
-    static readonly OPTIONAL: readonly ["object", "column", "parentScopeId", "callbackArg"];
-    static create(eventName: string, objectName: string | undefined, file: string, line: number, options?: EventListenerNodeOptions): EventListenerNodeRecord;
+    static readonly REQUIRED: readonly ["name", "file", "line", "column"];
+    static readonly OPTIONAL: readonly ["object", "parentScopeId", "callbackArg"];
+    static create(eventName: string, objectName: string | undefined, file: string, line: number, column: number, options?: EventListenerNodeOptions): EventListenerNodeRecord;
     static validate(node: EventListenerNodeRecord): string[];
 }
 export type { EventListenerNodeRecord };

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

@@ -1 +1 @@
-{"version":3,"file":"EventListenerNode.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/EventListenerNode.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,UAAU,uBAAwB,SAAQ,cAAc;IACtD,IAAI,EAAE,gBAAgB,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,wBAAwB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,iBAAiB;IAC5B,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,gBAAgB,CAAU;IAEjD,MAAM,CAAC,QAAQ,CAAC,QAAQ,oCAAqC;IAC7D,MAAM,CAAC,QAAQ,CAAC,QAAQ,gEAAiE;IAEzF,MAAM,CAAC,MAAM,CACX,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,wBAA6B,GACrC,uBAAuB;IAoB1B,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,GAAG,MAAM,EAAE;CASzD;AAED,YAAY,EAAE,uBAAuB,EAAE,CAAC"}
+{"version":3,"file":"EventListenerNode.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/EventListenerNode.ts"],"names":[],"mappings":"AAAA;;GAEG;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,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,wBAAwB;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,iBAAiB;IAC5B,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,gBAAgB,CAAU;IAEjD,MAAM,CAAC,QAAQ,CAAC,QAAQ,8CAA+C;IACvE,MAAM,CAAC,QAAQ,CAAC,QAAQ,sDAAuD;IAE/E,MAAM,CAAC,MAAM,CACX,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,wBAA6B,GACrC,uBAAuB;IAsB1B,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,GAAG,MAAM,EAAE;CASzD;AAED,YAAY,EAAE,uBAAuB,EAAE,CAAC"}

package/dist/core/nodes/EventListenerNode.js

@@ -3,17 +3,19 @@
  */
 export class EventListenerNode {
     static TYPE = 'EVENT_LISTENER';
-    static REQUIRED = ['name', 'file', 'line'];
-    static OPTIONAL = ['object', 'column', 'parentScopeId', 'callbackArg'];
-    static create(eventName, objectName, file, line, options = {}) {
+    static REQUIRED = ['name', 'file', 'line', 'column'];
+    static OPTIONAL = ['object', 'parentScopeId', 'callbackArg'];
+    static create(eventName, objectName, file, line, column, options = {}) {
         if (!eventName)
             throw new Error('EventListenerNode.create: eventName is required');
         if (!file)
             throw new Error('EventListenerNode.create: file is required');
         if (line === undefined)
             throw new Error('EventListenerNode.create: line is required');
+        if (column === undefined)
+            throw new Error('EventListenerNode.create: column is required');
         const counter = options.counter !== undefined ? `:${options.counter}` : '';
-        const id = `${file}:EVENT_LISTENER:${eventName}:${line}:${options.column || 0}${counter}`;
+        const id = `${file}:EVENT_LISTENER:${eventName}:${line}:${column}${counter}`;
         return {
             id,
             type: this.TYPE,
@@ -21,6 +23,7 @@ export class EventListenerNode {
             object: objectName,
             file,
             line,
+            column,
             parentScopeId: options.parentScopeId,
             callbackArg: options.callbackArg
         };

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

@@ -1,25 +1,61 @@
 /**
  * ExportNode - contract for EXPORT 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}->global->EXPORT->{exportedName}
+ * Example: src/utils.js->global->EXPORT->formatDate
  */
 import type { BaseNodeRecord } from '@grafema/types';
+import { type ScopeContext, type Location } from '../SemanticId.js';
 type ExportKind = 'value' | 'type';
+type ExportType = 'default' | 'named' | 'all';
 interface ExportNodeRecord extends BaseNodeRecord {
     type: 'EXPORT';
     column: number;
     exportKind: ExportKind;
     local: string;
     default: boolean;
+    source?: string;
+    exportType?: ExportType;
 }
 interface ExportNodeOptions {
     exportKind?: ExportKind;
     local?: string;
     default?: boolean;
+    source?: string;
+    exportType?: ExportType;
+}
+/**
+ * Options for createWithContext
+ */
+interface ExportContextOptions {
+    exportKind?: ExportKind;
+    local?: string;
+    default?: boolean;
+    source?: string;
+    exportType?: ExportType;
 }
 export declare class ExportNode {
     static readonly TYPE: "EXPORT";
-    static readonly REQUIRED: readonly ["name", "file", "line"];
-    static readonly OPTIONAL: readonly ["column", "exportKind", "local", "default"];
+    static readonly REQUIRED: readonly ["name", "file", "line", "column"];
+    static readonly OPTIONAL: readonly ["exportKind", "local", "default", "source", "exportType"];
     static create(name: string, file: string, line: number, column: number, options?: ExportNodeOptions): ExportNodeRecord;
+    /**
+     * Create EXPORT node with semantic ID (NEW API)
+     *
+     * Uses ScopeContext from ScopeTracker for stable identifiers.
+     * Export names are unique within module, so no discriminator needed.
+     *
+     * @param name - Exported name (as visible to importers)
+     * @param context - Scope context from ScopeTracker.getContext()
+     * @param location - Source location { line, column }
+     * @param options - Optional export properties
+     * @returns ExportNodeRecord with semantic ID
+     */
+    static createWithContext(name: string, context: ScopeContext, location: Partial<Location>, options?: ExportContextOptions): ExportNodeRecord;
     static validate(node: ExportNodeRecord): string[];
 }
 export type { ExportNodeRecord, ExportKind };

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

@@ -1 +1 @@
-{"version":3,"file":"ExportNode.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/ExportNode.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,KAAK,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;AAEnC,UAAU,gBAAiB,SAAQ,cAAc;IAC/C,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,UAAU,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,UAAU,iBAAiB;IACzB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,UAAU;IACrB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;IAEzC,MAAM,CAAC,QAAQ,CAAC,QAAQ,oCAAqC;IAC7D,MAAM,CAAC,QAAQ,CAAC,QAAQ,wDAAyD;IAEjF,MAAM,CAAC,MAAM,CACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB;IAkBnB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,EAAE;CAgBlD;AAED,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAC"}
+{"version":3,"file":"ExportNode.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/ExportNode.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,OAAO,GAAG,MAAM,CAAC;AAEnC,KAAK,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,CAAC;AAE9C,UAAU,gBAAiB,SAAQ,cAAc;IAC/C,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,UAAU,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,UAAU,iBAAiB;IACzB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;GAEG;AACH,UAAU,oBAAoB;IAC5B,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,qBAAa,UAAU;IACrB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;IAEzC,MAAM,CAAC,QAAQ,CAAC,QAAQ,8CAA+C;IACvE,MAAM,CAAC,QAAQ,CAAC,QAAQ,sEAAuE;IAE/F,MAAM,CAAC,MAAM,CACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB;IAqBnB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,iBAAiB,CACtB,IAAI,EAAE,MAAM,EACZ,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/ExportNode.js

@@ -1,10 +1,18 @@
 /**
  * ExportNode - contract for EXPORT 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}->global->EXPORT->{exportedName}
+ * Example: src/utils.js->global->EXPORT->formatDate
  */
+import { computeSemanticId } from '../SemanticId.js';
 export class ExportNode {
     static TYPE = 'EXPORT';
-    static REQUIRED = ['name', 'file', 'line'];
-    static OPTIONAL = ['column', 'exportKind', 'local', 'default'];
+    static REQUIRED = ['name', 'file', 'line', 'column'];
+    static OPTIONAL = ['exportKind', 'local', 'default', 'source', 'exportType'];
     static create(name, file, line, column, options = {}) {
         if (!name)
             throw new Error('ExportNode.create: name is required');
@@ -12,16 +20,58 @@ export class ExportNode {
             throw new Error('ExportNode.create: file is required');
         if (!line)
             throw new Error('ExportNode.create: line is required');
+        if (column === undefined)
+            throw new Error('ExportNode.create: column is required');
         return {
             id: `${file}:EXPORT:${name}:${line}`,
             type: this.TYPE,
             name,
             file,
             line,
-            column: column || 0,
+            column,
             exportKind: options.exportKind || 'value',
             local: options.local || name,
-            default: options.default || false
+            default: options.default || false,
+            ...(options.source !== undefined && { source: options.source }),
+            ...(options.exportType !== undefined && { exportType: options.exportType })
+        };
+    }
+    /**
+     * Create EXPORT node with semantic ID (NEW API)
+     *
+     * Uses ScopeContext from ScopeTracker for stable identifiers.
+     * Export names are unique within module, so no discriminator needed.
+     *
+     * @param name - Exported name (as visible to importers)
+     * @param context - Scope context from ScopeTracker.getContext()
+     * @param location - Source location { line, column }
+     * @param options - Optional export properties
+     * @returns ExportNodeRecord with semantic ID
+     */
+    static createWithContext(name, context, location, options = {}) {
+        // Validate required fields
+        if (!name)
+            throw new Error('ExportNode.createWithContext: name is required');
+        if (!context.file)
+            throw new Error('ExportNode.createWithContext: file is required');
+        if (location.line === undefined)
+            throw new Error('ExportNode.createWithContext: line is required');
+        if (location.column === undefined)
+            throw new Error('ExportNode.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,
+            exportKind: options.exportKind || 'value',
+            local: options.local || name,
+            default: options.default || false,
+            ...(options.source !== undefined && { source: options.source }),
+            ...(options.exportType !== undefined && { exportType: options.exportType })
         };
     }
     static validate(node) {

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

@@ -0,0 +1,97 @@
+/**
+ * ExpressionNode - contract for EXPRESSION node
+ *
+ * Represents complex expressions for data flow tracking
+ * (MemberExpression, BinaryExpression, LogicalExpression, etc.)
+ *
+ * ID format: {file}:EXPRESSION:{expressionType}:{line}:{column}
+ * Example: /src/app.ts:EXPRESSION:MemberExpression:25:10
+ */
+import type { BaseNodeRecord } from '@grafema/types';
+interface ExpressionNodeRecord extends BaseNodeRecord {
+    type: 'EXPRESSION';
+    column: number;
+    expressionType: string;
+    object?: string;
+    property?: string;
+    computed?: boolean;
+    computedPropertyVar?: string;
+    operator?: string;
+    path?: string;
+    baseName?: string;
+    propertyPath?: string[];
+    arrayIndex?: number;
+}
+interface ExpressionNodeOptions {
+    object?: string;
+    property?: string;
+    computed?: boolean;
+    computedPropertyVar?: string;
+    operator?: string;
+    path?: string;
+    baseName?: string;
+    propertyPath?: string[];
+    arrayIndex?: number;
+}
+export declare class ExpressionNode {
+    static readonly TYPE: "EXPRESSION";
+    static readonly REQUIRED: readonly ["expressionType", "file", "line", "column"];
+    static readonly OPTIONAL: readonly ["object", "property", "computed", "computedPropertyVar", "operator", "path", "baseName", "propertyPath", "arrayIndex"];
+    /**
+     * Create EXPRESSION node
+     *
+     * @param expressionType - Type of expression (MemberExpression, BinaryExpression, etc.)
+     * @param file - File path
+     * @param line - Line number
+     * @param column - Column position
+     * @param options - Optional expression properties
+     * @returns ExpressionNodeRecord
+     */
+    static create(expressionType: string, file: string, line: number, column: number, options?: ExpressionNodeOptions): ExpressionNodeRecord;
+    /**
+     * Compute name from expression properties
+     *
+     * Naming conventions:
+     * - MemberExpression: "object.property"
+     * - BinaryExpression: "<BinaryExpression>"
+     * - LogicalExpression: "<LogicalExpression>"
+     * - ConditionalExpression: "<ternary>"
+     * - TemplateLiteral: "<template>"
+     * - Other: expressionType
+     */
+    private static _computeName;
+    /**
+     * Generate EXPRESSION node ID without creating the full node
+     *
+     * Used by JSASTAnalyzer when creating assignment metadata.
+     * The full node is created later by GraphBuilder.
+     *
+     * ID format: {file}:EXPRESSION:{expressionType}:{line}:{column}
+     *
+     * @param expressionType - Type of expression (MemberExpression, BinaryExpression, etc.)
+     * @param file - File path
+     * @param line - Line number
+     * @param column - Column position
+     * @returns Generated ID string in colon format
+     */
+    static generateId(expressionType: string, file: string, line: number, column: number): string;
+    /**
+     * Create EXPRESSION node from assignment metadata
+     *
+     * Used by GraphBuilder when processing variableAssignments.
+     * The ID is provided from upstream (generated by JSASTAnalyzer).
+     *
+     * @param expressionType - Type of expression
+     * @param file - File path
+     * @param line - Line number
+     * @param column - Column position
+     * @param options - Must include id; optional: expression properties
+     * @returns ExpressionNodeRecord
+     */
+    static createFromMetadata(expressionType: string, file: string, line: number, column: number, options: ExpressionNodeOptions & {
+        id: string;
+    }): ExpressionNodeRecord;
+    static validate(node: ExpressionNodeRecord): string[];
+}
+export type { ExpressionNodeRecord, ExpressionNodeOptions };
+//# sourceMappingURL=ExpressionNode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ExpressionNode.d.ts","sourceRoot":"","sources":["../../../src/core/nodes/ExpressionNode.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,UAAU,oBAAqB,SAAQ,cAAc;IACnD,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IAEvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,qBAAqB;IAE7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,cAAc;IACzB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAU;IAE7C,MAAM,CAAC,QAAQ,CAAC,QAAQ,wDAAyD;IACjF,MAAM,CAAC,QAAQ,CAAC,QAAQ,mIAGb;IAEX;;;;;;;;;OASG;IACH,MAAM,CAAC,MAAM,CACX,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,qBAA0B,GAClC,oBAAoB;IA8BvB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAqB3B;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,UAAU,CACf,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,MAAM;IAIT;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,kBAAkB,CACvB,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,qBAAqB,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAC9C,oBAAoB;IAsCvB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,EAAE;CAiBtD;AAED,YAAY,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/core/nodes/ExpressionNode.js

@@ -0,0 +1,180 @@
+/**
+ * ExpressionNode - contract for EXPRESSION node
+ *
+ * Represents complex expressions for data flow tracking
+ * (MemberExpression, BinaryExpression, LogicalExpression, etc.)
+ *
+ * ID format: {file}:EXPRESSION:{expressionType}:{line}:{column}
+ * Example: /src/app.ts:EXPRESSION:MemberExpression:25:10
+ */
+export class ExpressionNode {
+    static TYPE = 'EXPRESSION';
+    static REQUIRED = ['expressionType', 'file', 'line', 'column'];
+    static OPTIONAL = [
+        'object', 'property', 'computed', 'computedPropertyVar',
+        'operator', 'path', 'baseName', 'propertyPath', 'arrayIndex'
+    ];
+    /**
+     * Create EXPRESSION node
+     *
+     * @param expressionType - Type of expression (MemberExpression, BinaryExpression, etc.)
+     * @param file - File path
+     * @param line - Line number
+     * @param column - Column position
+     * @param options - Optional expression properties
+     * @returns ExpressionNodeRecord
+     */
+    static create(expressionType, file, line, column, options = {}) {
+        if (!expressionType)
+            throw new Error('ExpressionNode.create: expressionType is required');
+        if (!file)
+            throw new Error('ExpressionNode.create: file is required');
+        if (!line)
+            throw new Error('ExpressionNode.create: line is required');
+        if (column === undefined)
+            throw new Error('ExpressionNode.create: column is required');
+        const node = {
+            id: `${file}:EXPRESSION:${expressionType}:${line}:${column}`,
+            type: this.TYPE,
+            name: this._computeName(expressionType, options),
+            file,
+            line,
+            column,
+            expressionType
+        };
+        // Add optional fields if present
+        if (options.object !== undefined)
+            node.object = options.object;
+        if (options.property !== undefined)
+            node.property = options.property;
+        if (options.computed !== undefined)
+            node.computed = options.computed;
+        if (options.computedPropertyVar !== undefined)
+            node.computedPropertyVar = options.computedPropertyVar;
+        if (options.operator !== undefined)
+            node.operator = options.operator;
+        if (options.path !== undefined)
+            node.path = options.path;
+        if (options.baseName !== undefined)
+            node.baseName = options.baseName;
+        if (options.propertyPath !== undefined)
+            node.propertyPath = options.propertyPath;
+        if (options.arrayIndex !== undefined)
+            node.arrayIndex = options.arrayIndex;
+        return node;
+    }
+    /**
+     * Compute name from expression properties
+     *
+     * Naming conventions:
+     * - MemberExpression: "object.property"
+     * - BinaryExpression: "<BinaryExpression>"
+     * - LogicalExpression: "<LogicalExpression>"
+     * - ConditionalExpression: "<ternary>"
+     * - TemplateLiteral: "<template>"
+     * - Other: expressionType
+     */
+    static _computeName(expressionType, options) {
+        if (options.path) {
+            return options.path;
+        }
+        if (options.object && options.property) {
+            return `${options.object}.${options.property}`;
+        }
+        // Special naming for non-MemberExpression types
+        switch (expressionType) {
+            case 'BinaryExpression':
+            case 'LogicalExpression':
+                return `<${expressionType}>`;
+            case 'ConditionalExpression':
+                return '<ternary>';
+            case 'TemplateLiteral':
+                return '<template>';
+            default:
+                return expressionType;
+        }
+    }
+    /**
+     * Generate EXPRESSION node ID without creating the full node
+     *
+     * Used by JSASTAnalyzer when creating assignment metadata.
+     * The full node is created later by GraphBuilder.
+     *
+     * ID format: {file}:EXPRESSION:{expressionType}:{line}:{column}
+     *
+     * @param expressionType - Type of expression (MemberExpression, BinaryExpression, etc.)
+     * @param file - File path
+     * @param line - Line number
+     * @param column - Column position
+     * @returns Generated ID string in colon format
+     */
+    static generateId(expressionType, file, line, column) {
+        return `${file}:EXPRESSION:${expressionType}:${line}:${column}`;
+    }
+    /**
+     * Create EXPRESSION node from assignment metadata
+     *
+     * Used by GraphBuilder when processing variableAssignments.
+     * The ID is provided from upstream (generated by JSASTAnalyzer).
+     *
+     * @param expressionType - Type of expression
+     * @param file - File path
+     * @param line - Line number
+     * @param column - Column position
+     * @param options - Must include id; optional: expression properties
+     * @returns ExpressionNodeRecord
+     */
+    static createFromMetadata(expressionType, file, line, column, options) {
+        if (!options.id) {
+            throw new Error('ExpressionNode.createFromMetadata: id is required');
+        }
+        // Validate ID format - must use colon format
+        if (!options.id.includes(':EXPRESSION:')) {
+            throw new Error(`ExpressionNode.createFromMetadata: Invalid ID format "${options.id}". ` +
+                `Expected format: {file}:EXPRESSION:{type}:{line}:{column}`);
+        }
+        // Create base node structure
+        const node = {
+            id: options.id, // Use provided ID (from upstream)
+            type: this.TYPE,
+            name: this._computeName(expressionType, options),
+            file,
+            line,
+            column,
+            expressionType
+        };
+        // Add optional fields if present (same logic as create())
+        if (options.object !== undefined)
+            node.object = options.object;
+        if (options.property !== undefined)
+            node.property = options.property;
+        if (options.computed !== undefined)
+            node.computed = options.computed;
+        if (options.computedPropertyVar !== undefined)
+            node.computedPropertyVar = options.computedPropertyVar;
+        if (options.operator !== undefined)
+            node.operator = options.operator;
+        if (options.path !== undefined)
+            node.path = options.path;
+        if (options.baseName !== undefined)
+            node.baseName = options.baseName;
+        if (options.propertyPath !== undefined)
+            node.propertyPath = options.propertyPath;
+        if (options.arrayIndex !== undefined)
+            node.arrayIndex = options.arrayIndex;
+        return node;
+    }
+    static validate(node) {
+        const errors = [];
+        if (node.type !== this.TYPE) {
+            errors.push(`Expected type ${this.TYPE}, got ${node.type}`);
+        }
+        if (!node.expressionType) {
+            errors.push('Missing required field: expressionType');
+        }
+        if (!node.file) {
+            errors.push('Missing required field: file');
+        }
+        return errors;
+    }
+}