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

package/dist/core/NodeFactory.js

@@ -10,22 +10,23 @@
  */
 import { createHash } from 'crypto';
 import { basename, relative } from 'path';
-import { ServiceNode, EntrypointNode, ModuleNode, FunctionNode, ScopeNode, CallSiteNode, MethodCallNode, VariableDeclarationNode, ConstantNode, LiteralNode, ExternalStdioNode, EventListenerNode, HttpRequestNode, DatabaseQueryNode, } from './nodes/index.js';
+import { ServiceNode, EntrypointNode, ModuleNode, FunctionNode, ScopeNode, BranchNode, CaseNode, CallSiteNode, MethodCallNode, ConstructorCallNode, VariableDeclarationNode, ConstantNode, LiteralNode, ObjectLiteralNode, ArrayLiteralNode, ExternalStdioNode, NetworkRequestNode, EventListenerNode, HttpRequestNode, DatabaseQueryNode, ImportNode, ClassNode, ExportNode, ExternalModuleNode, InterfaceNode, TypeNode, EnumNode, DecoratorNode, ExpressionNode, ArgumentExpressionNode, IssueNode, } from './nodes/index.js';
+import { brandNode } from '@grafema/types';
 export class NodeFactory {
     /**
      * Create SERVICE node
      */
     static createService(name, projectPath, options = {}) {
-        return ServiceNode.create(name, projectPath, options);
+        return brandNode(ServiceNode.create(name, projectPath, options));
     }
     /**
      * Create ENTRYPOINT node
      */
     static createEntrypoint(file, entrypointType, options = {}) {
-        return EntrypointNode.create(file, entrypointType, options);
+        return brandNode(EntrypointNode.create(file, entrypointType, options));
     }
     /**
-     * Create MODULE node
+     * Create MODULE node (LEGACY)
      */
     static createModule(filePath, projectPath, options = {}) {
         if (!filePath)
@@ -34,73 +35,288 @@ export class NodeFactory {
             throw new Error('NodeFactory.createModule: projectPath is required');
         const contentHash = options.contentHash || this._hashFile(filePath);
         const relativePath = relative(projectPath, filePath) || basename(filePath);
-        return ModuleNode.create(filePath, relativePath, contentHash, options);
+        return brandNode(ModuleNode.create(filePath, relativePath, contentHash, options));
+    }
+    /**
+     * Create MODULE node with semantic ID (NEW API)
+     *
+     * Uses ScopeContext for stable identifiers.
+     *
+     * @param context - Scope context with file path (relative to project root)
+     * @param options - Optional contentHash and isTest flag
+     * @returns ModuleNodeRecord with semantic ID
+     */
+    static createModuleWithContext(context, options = {}) {
+        return brandNode(ModuleNode.createWithContext(context, options));
     }
     /**
      * Create FUNCTION node
      */
     static createFunction(name, file, line, column, options = {}) {
-        return FunctionNode.create(name, file, line, column, options);
+        return brandNode(FunctionNode.create(name, file, line, column, options));
     }
     /**
      * Create SCOPE node
      */
     static createScope(scopeType, file, line, options = {}) {
-        return ScopeNode.create(scopeType, file, line, options);
+        return brandNode(ScopeNode.create(scopeType, file, line, options));
+    }
+    /**
+     * Create BRANCH node
+     */
+    static createBranch(branchType, file, line, column, options = {}) {
+        return brandNode(BranchNode.create(branchType, file, line, column, options));
+    }
+    /**
+     * Create CASE node
+     */
+    static createCase(value, isDefault, fallsThrough, isEmpty, file, line, column, options = {}) {
+        return brandNode(CaseNode.create(value, isDefault, fallsThrough, isEmpty, file, line, column, options));
     }
     /**
      * Create CALL_SITE node
      */
     static createCallSite(targetName, file, line, column, options = {}) {
-        return CallSiteNode.create(targetName, file, line, column, options);
+        return brandNode(CallSiteNode.create(targetName, file, line, column, options));
     }
     /**
      * Create METHOD_CALL node
      */
     static createMethodCall(objectName, methodName, file, line, column, options = {}) {
-        return MethodCallNode.create(objectName, methodName, file, line, column, options);
+        return brandNode(MethodCallNode.create(objectName, methodName, file, line, column, options));
+    }
+    /**
+     * Create CONSTRUCTOR_CALL node
+     *
+     * Represents a `new ClassName()` expression.
+     * Used for data flow: VARIABLE --ASSIGNED_FROM--> CONSTRUCTOR_CALL
+     *
+     * @param className - Name of the constructor (e.g., 'Date', 'MyClass')
+     * @param file - File path
+     * @param line - Line number
+     * @param column - Column position
+     * @param options - Optional counter for disambiguation
+     */
+    static createConstructorCall(className, file, line, column, options = {}) {
+        return brandNode(ConstructorCallNode.create(className, file, line, column, options));
+    }
+    /**
+     * Generate CONSTRUCTOR_CALL node ID without creating the full node
+     *
+     * Used by JSASTAnalyzer when creating assignment metadata.
+     * The full node is created later by GraphBuilder.
+     */
+    static generateConstructorCallId(className, file, line, column, options = {}) {
+        return ConstructorCallNode.generateId(className, file, line, column, options);
+    }
+    /**
+     * Check if a class name is a built-in JavaScript constructor
+     */
+    static isBuiltinConstructor(className) {
+        return ConstructorCallNode.isBuiltinConstructor(className);
     }
     /**
      * Create VARIABLE_DECLARATION node
      */
     static createVariableDeclaration(name, file, line, column, options = {}) {
-        return VariableDeclarationNode.create(name, file, line, column, options);
+        return brandNode(VariableDeclarationNode.create(name, file, line, column, options));
     }
     /**
      * Create CONSTANT node
      */
     static createConstant(name, file, line, column, options = {}) {
-        return ConstantNode.create(name, file, line, column, options);
+        return brandNode(ConstantNode.create(name, file, line, column, options));
     }
     /**
      * Create LITERAL node
      */
     static createLiteral(value, file, line, column, options = {}) {
-        return LiteralNode.create(value, file, line, column, options);
+        return brandNode(LiteralNode.create(value, file, line, column, options));
+    }
+    /**
+     * Create OBJECT_LITERAL node
+     */
+    static createObjectLiteral(file, line, column, options = {}) {
+        return brandNode(ObjectLiteralNode.create(file, line, column, options));
+    }
+    /**
+     * Create ARRAY_LITERAL node
+     */
+    static createArrayLiteral(file, line, column, options = {}) {
+        return brandNode(ArrayLiteralNode.create(file, line, column, options));
     }
     /**
      * Create EXTERNAL_STDIO node (singleton)
      */
     static createExternalStdio() {
-        return ExternalStdioNode.create();
+        return brandNode(ExternalStdioNode.create());
+    }
+    /**
+     * Create net:request singleton node
+     *
+     * This node represents the external network as a system resource.
+     * Should be created once per graph.
+     *
+     * All HTTP_REQUEST nodes connect to this singleton via CALLS edges.
+     *
+     * @returns NetworkRequestNodeRecord - singleton node
+     */
+    static createNetworkRequest() {
+        return brandNode(NetworkRequestNode.create());
     }
     /**
      * Create EVENT_LISTENER node
      */
-    static createEventListener(eventName, objectName, file, line, options = {}) {
-        return EventListenerNode.create(eventName, objectName, file, line, options);
+    static createEventListener(eventName, objectName, file, line, column, options = {}) {
+        return brandNode(EventListenerNode.create(eventName, objectName, file, line, column, options));
     }
     /**
      * Create HTTP_REQUEST node
      */
-    static createHttpRequest(url, method, file, line, options = {}) {
-        return HttpRequestNode.create(url, method, file, line, options);
+    static createHttpRequest(url, method, file, line, column, options = {}) {
+        return brandNode(HttpRequestNode.create(url, method, file, line, column, options));
     }
     /**
      * Create DATABASE_QUERY node
      */
-    static createDatabaseQuery(query, operation, file, line, options = {}) {
-        return DatabaseQueryNode.create(query, operation, file, line, options);
+    static createDatabaseQuery(query, operation, file, line, column, options = {}) {
+        return brandNode(DatabaseQueryNode.create(query, operation, file, line, column, options));
+    }
+    /**
+     * Create IMPORT node
+     *
+     * ImportNode automatically detects importType from imported field:
+     * - imported === 'default' → importType: 'default'
+     * - imported === '*' → importType: 'namespace'
+     * - anything else → importType: 'named'
+     *
+     * @param name - Local binding name (how it's used in this file)
+     * @param file - Absolute file path
+     * @param line - Line number (for debugging, not part of ID)
+     * @param column - Column position (0 if unavailable)
+     * @param source - Source module (e.g., 'react', './utils')
+     * @param options - Optional fields
+     * @returns ImportNodeRecord
+     */
+    static createImport(name, file, line, column, source, options = {}) {
+        return brandNode(ImportNode.create(name, file, line, column, source, options));
+    }
+    /**
+     * Create CLASS node
+     */
+    static createClass(name, file, line, column, options = {}) {
+        return brandNode(ClassNode.create(name, file, line, column, options));
+    }
+    /**
+     * Create EXPORT node
+     */
+    static createExport(name, file, line, column, options = {}) {
+        return brandNode(ExportNode.create(name, file, line, column, options));
+    }
+    /**
+     * Create EXTERNAL_MODULE node
+     *
+     * Represents external npm packages or Node.js built-in modules.
+     * Uses singleton pattern - same source always produces same ID.
+     *
+     * @param source - Module name (e.g., 'lodash', '@tanstack/react-query', 'node:fs')
+     */
+    static createExternalModule(source) {
+        return brandNode(ExternalModuleNode.create(source));
+    }
+    /**
+     * Create INTERFACE node
+     */
+    static createInterface(name, file, line, column, options = {}) {
+        return brandNode(InterfaceNode.create(name, file, line, column, options));
+    }
+    /**
+     * Create TYPE node
+     */
+    static createType(name, file, line, column, options = {}) {
+        return brandNode(TypeNode.create(name, file, line, column, options));
+    }
+    /**
+     * Create ENUM node
+     */
+    static createEnum(name, file, line, column, options = {}) {
+        return brandNode(EnumNode.create(name, file, line, column, options));
+    }
+    /**
+     * Create DECORATOR node
+     */
+    static createDecorator(name, file, line, column, targetId, targetType, options = {}) {
+        return brandNode(DecoratorNode.create(name, file, line, column, targetId, targetType, options));
+    }
+    /**
+     * Create EXPRESSION node
+     */
+    static createExpression(expressionType, file, line, column, options = {}) {
+        return brandNode(ExpressionNode.create(expressionType, file, line, column, options));
+    }
+    /**
+     * Generate EXPRESSION node ID without creating the full node
+     *
+     * Used by JSASTAnalyzer when creating assignment metadata.
+     * The full node is created later by GraphBuilder.
+     *
+     * @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 generateExpressionId(expressionType, file, line, column) {
+        return ExpressionNode.generateId(expressionType, file, 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
+     */
+    static createExpressionFromMetadata(expressionType, file, line, column, options) {
+        return brandNode(ExpressionNode.createFromMetadata(expressionType, file, line, column, options));
+    }
+    /**
+     * Create EXPRESSION node with argument context
+     *
+     * Used when EXPRESSION appears as a call argument and we need to track
+     * which call and argument position for data flow analysis.
+     *
+     * @param expressionType - Type of expression (BinaryExpression, LogicalExpression, etc.)
+     * @param file - File path
+     * @param line - Line number
+     * @param column - Column position
+     * @param options - Required: parentCallId, argIndex; Optional: expression properties, counter
+     * @returns ArgumentExpressionNodeRecord
+     */
+    static createArgumentExpression(expressionType, file, line, column, options) {
+        return brandNode(ArgumentExpressionNode.create(expressionType, file, line, column, options));
+    }
+    /**
+     * Create ISSUE node
+     *
+     * Issues represent detected problems in the codebase.
+     * Used by validation plugins to persist findings in the graph.
+     *
+     * @param category - Issue category (security, performance, style, smell)
+     * @param severity - error | warning | info
+     * @param message - Human-readable description
+     * @param plugin - Name of the plugin that detected this issue
+     * @param file - File path where issue was detected
+     * @param line - Line number
+     * @param column - Column number (optional)
+     * @param options - Optional context data
+     */
+    static createIssue(category, severity, message, plugin, file, line, column = 0, options = {}) {
+        return brandNode(IssueNode.create(category, severity, message, plugin, file, line, column, options));
     }
     /**
      * Validate node by its type
@@ -112,16 +328,35 @@ export class NodeFactory {
             'MODULE': ModuleNode,
             'FUNCTION': FunctionNode,
             'SCOPE': ScopeNode,
+            'BRANCH': BranchNode,
+            'CASE': CaseNode,
             'CALL_SITE': CallSiteNode,
             'METHOD_CALL': MethodCallNode,
+            'CONSTRUCTOR_CALL': ConstructorCallNode,
             'VARIABLE_DECLARATION': VariableDeclarationNode,
             'CONSTANT': ConstantNode,
             'LITERAL': LiteralNode,
-            'EXTERNAL_STDIO': ExternalStdioNode,
+            'OBJECT_LITERAL': ObjectLiteralNode,
+            'ARRAY_LITERAL': ArrayLiteralNode,
+            'net:stdio': ExternalStdioNode,
+            'net:request': NetworkRequestNode,
             'EVENT_LISTENER': EventListenerNode,
             'HTTP_REQUEST': HttpRequestNode,
-            'DATABASE_QUERY': DatabaseQueryNode
+            'DATABASE_QUERY': DatabaseQueryNode,
+            'IMPORT': ImportNode,
+            'CLASS': ClassNode,
+            'EXPORT': ExportNode,
+            'EXTERNAL_MODULE': ExternalModuleNode,
+            'INTERFACE': InterfaceNode,
+            'TYPE': TypeNode,
+            'ENUM': EnumNode,
+            'DECORATOR': DecoratorNode,
+            'EXPRESSION': ExpressionNode
         };
+        // Handle issue:* types dynamically
+        if (IssueNode.isIssueType(node.type)) {
+            return IssueNode.validate(node);
+        }
         const validator = validators[node.type];
         if (!validator) {
             return [`Unknown node type: ${node.type}`];

package/dist/core/ScopeTracker.d.ts

@@ -0,0 +1,84 @@
+/**
+ * ScopeTracker - Track scope hierarchy during AST traversal
+ *
+ * Maintains the current scope path and provides counters for:
+ * - Counted scopes (if#0, try#1, etc.)
+ * - Item counters (CALL, LITERAL, etc.)
+ * - Sibling tracking (anonymous[0], anonymous[1], etc.)
+ *
+ * Used with SemanticId to generate stable identifiers.
+ */
+import type { ScopeContext } from './SemanticId.js';
+/**
+ * Entry in the scope stack
+ */
+export interface ScopeEntry {
+    name: string;
+    type: string;
+    counter?: number;
+}
+/**
+ * Result of entering a counted scope
+ */
+export interface CountedScopeResult {
+    name: string;
+    discriminator: number;
+}
+/**
+ * ScopeTracker - Manages scope hierarchy and counters during AST traversal
+ */
+export declare class ScopeTracker {
+    /** Source file path */
+    readonly file: string;
+    /** Current scope stack */
+    private scopeStack;
+    /** Counters for various purposes (scoped by scope path) */
+    private counters;
+    constructor(file: string);
+    /**
+     * Enter a named scope (function, class, etc.)
+     */
+    enterScope(name: string, type: string): void;
+    /**
+     * Enter a counted scope (if, try, for, etc.)
+     * Automatically assigns a discriminator.
+     */
+    enterCountedScope(type: string): CountedScopeResult;
+    /**
+     * Exit the current scope
+     */
+    exitScope(): void;
+    /**
+     * Get current scope context for semantic ID generation
+     */
+    getContext(): ScopeContext;
+    /**
+     * Get scope path as string (for display/debugging)
+     */
+    getScopePath(): string;
+    /**
+     * Get the innermost enclosing scope of a specific type.
+     * Searches from innermost to outermost.
+     *
+     * @param scopeType - Type to search for ('CLASS', 'FUNCTION', etc.)
+     * @returns The scope entry name if found, undefined otherwise
+     */
+    getEnclosingScope(scopeType: string): string | undefined;
+    /**
+     * Get next counter for item type within current scope.
+     * Used for CALL, LITERAL, etc. that need #N discriminators.
+     */
+    getItemCounter(itemType: string): number;
+    /**
+     * Get current count without incrementing.
+     * Used to check for collisions.
+     */
+    peekItemCounter(itemType: string): number;
+    /**
+     * Track siblings by name within current scope.
+     * Used for anonymous functions: anonymous[0], anonymous[1]
+     */
+    getSiblingIndex(name: string): number;
+    private counterKey;
+}
+//# sourceMappingURL=ScopeTracker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ScopeTracker.d.ts","sourceRoot":"","sources":["../../src/core/ScopeTracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB,uBAAuB;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,0BAA0B;IAC1B,OAAO,CAAC,UAAU,CAAoB;IAEtC,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAkC;gBAEtC,IAAI,EAAE,MAAM;IAMxB;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAI5C;;;OAGG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB;IAUnD;;OAEG;IACH,SAAS,IAAI,IAAI;IAMjB;;OAEG;IACH,UAAU,IAAI,YAAY;IAO1B;;OAEG;IACH,YAAY,IAAI,MAAM;IAKtB;;;;;;OAMG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAYxD;;;OAGG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAOxC;;;OAGG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAMzC;;;OAGG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IASrC,OAAO,CAAC,UAAU;CAGnB"}

package/dist/core/ScopeTracker.js

@@ -0,0 +1,116 @@
+/**
+ * ScopeTracker - Track scope hierarchy during AST traversal
+ *
+ * Maintains the current scope path and provides counters for:
+ * - Counted scopes (if#0, try#1, etc.)
+ * - Item counters (CALL, LITERAL, etc.)
+ * - Sibling tracking (anonymous[0], anonymous[1], etc.)
+ *
+ * Used with SemanticId to generate stable identifiers.
+ */
+/**
+ * ScopeTracker - Manages scope hierarchy and counters during AST traversal
+ */
+export class ScopeTracker {
+    /** Source file path */
+    file;
+    /** Current scope stack */
+    scopeStack = [];
+    /** Counters for various purposes (scoped by scope path) */
+    counters = new Map();
+    constructor(file) {
+        this.file = file;
+    }
+    // === Scope Management ===
+    /**
+     * Enter a named scope (function, class, etc.)
+     */
+    enterScope(name, type) {
+        this.scopeStack.push({ name, type });
+    }
+    /**
+     * Enter a counted scope (if, try, for, etc.)
+     * Automatically assigns a discriminator.
+     */
+    enterCountedScope(type) {
+        const key = this.counterKey(type);
+        const n = this.counters.get(key) || 0;
+        this.counters.set(key, n + 1);
+        const name = `${type}#${n}`;
+        this.scopeStack.push({ name, type, counter: n });
+        return { name, discriminator: n };
+    }
+    /**
+     * Exit the current scope
+     */
+    exitScope() {
+        this.scopeStack.pop();
+    }
+    // === ID Generation ===
+    /**
+     * Get current scope context for semantic ID generation
+     */
+    getContext() {
+        return {
+            file: this.file,
+            scopePath: this.scopeStack.map(s => s.name)
+        };
+    }
+    /**
+     * Get scope path as string (for display/debugging)
+     */
+    getScopePath() {
+        if (this.scopeStack.length === 0)
+            return 'global';
+        return this.scopeStack.map(s => s.name).join('->');
+    }
+    /**
+     * Get the innermost enclosing scope of a specific type.
+     * Searches from innermost to outermost.
+     *
+     * @param scopeType - Type to search for ('CLASS', 'FUNCTION', etc.)
+     * @returns The scope entry name if found, undefined otherwise
+     */
+    getEnclosingScope(scopeType) {
+        // Search from end (innermost) to start (outermost)
+        for (let i = this.scopeStack.length - 1; i >= 0; i--) {
+            if (this.scopeStack[i].type === scopeType) {
+                return this.scopeStack[i].name;
+            }
+        }
+        return undefined;
+    }
+    // === Counter Management ===
+    /**
+     * Get next counter for item type within current scope.
+     * Used for CALL, LITERAL, etc. that need #N discriminators.
+     */
+    getItemCounter(itemType) {
+        const key = this.counterKey(itemType);
+        const n = this.counters.get(key) || 0;
+        this.counters.set(key, n + 1);
+        return n;
+    }
+    /**
+     * Get current count without incrementing.
+     * Used to check for collisions.
+     */
+    peekItemCounter(itemType) {
+        return this.counters.get(this.counterKey(itemType)) || 0;
+    }
+    // === Sibling Tracking ===
+    /**
+     * Track siblings by name within current scope.
+     * Used for anonymous functions: anonymous[0], anonymous[1]
+     */
+    getSiblingIndex(name) {
+        const key = `${this.getScopePath()}:sibling:${name}`;
+        const n = this.counters.get(key) || 0;
+        this.counters.set(key, n + 1);
+        return n;
+    }
+    // === Private ===
+    counterKey(itemType) {
+        return `${this.getScopePath()}:${itemType}`;
+    }
+}

package/dist/core/SemanticId.d.ts

@@ -0,0 +1,90 @@
+/**
+ * SemanticId - Stable identifiers for code elements
+ *
+ * Semantic IDs provide stable identifiers for code elements that don't change
+ * when unrelated code is added/removed (no line numbers in IDs).
+ *
+ * Format: {file}->{scope_path}->{type}->{name}[#discriminator]
+ *
+ * Examples:
+ *   src/app.js->global->FUNCTION->processData
+ *   src/app.js->UserService->METHOD->login
+ *   src/app.js->getUser->if#0->CALL->console.log#0
+ *
+ * Special formats:
+ *   Singletons: net:stdio->__stdio__
+ *   External modules: EXTERNAL_MODULE->lodash
+ */
+/**
+ * Location in source file
+ */
+export interface Location {
+    line: number;
+    column: number;
+    endLine?: number;
+    endColumn?: number;
+}
+/**
+ * Scope context for semantic ID generation
+ */
+export interface ScopeContext {
+    /** Source file path */
+    file: string;
+    /** Array of scope names, e.g. ['MyClass', 'myMethod', 'if#1'] */
+    scopePath: string[];
+}
+/**
+ * Options for semantic ID generation
+ */
+export interface SemanticIdOptions {
+    /** Counter for disambiguation (#N) */
+    discriminator?: number;
+    /** Context string for special cases ([context]) */
+    context?: string;
+}
+/**
+ * Parsed semantic ID components
+ */
+export interface ParsedSemanticId {
+    file: string;
+    scopePath: string[];
+    type: string;
+    name: string;
+    discriminator?: number;
+    context?: string;
+}
+/**
+ * Item with name and location for discriminator computation
+ */
+export interface LocatedItem {
+    name: string;
+    location: Location;
+}
+/**
+ * Compute semantic ID for any node type.
+ *
+ * @param type - Node type (FUNCTION, CALL, VARIABLE, etc.)
+ * @param name - Node name
+ * @param context - Scope context from ScopeTracker
+ * @param options - Optional discriminator or context
+ * @returns Semantic ID string
+ */
+export declare function computeSemanticId(type: string, name: string, context: ScopeContext, options?: SemanticIdOptions): string;
+/**
+ * Parse semantic ID back to components.
+ *
+ * @param id - Semantic ID to parse
+ * @returns Parsed components or null if invalid
+ */
+export declare function parseSemanticId(id: string): ParsedSemanticId | null;
+/**
+ * Compute discriminator for items with same name in same scope.
+ * Uses line/column for stable ordering.
+ *
+ * @param items - All items in scope
+ * @param targetName - Name to find discriminator for
+ * @param targetLocation - Location of target item
+ * @returns Discriminator (0-based index among same-named items)
+ */
+export declare function computeDiscriminator(items: LocatedItem[], targetName: string, targetLocation: Location): number;
+//# sourceMappingURL=SemanticId.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SemanticId.d.ts","sourceRoot":"","sources":["../../src/core/SemanticId.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,EACrB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,MAAM,CAaR;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAiDnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,WAAW,EAAE,EACpB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,QAAQ,GACvB,MAAM,CAwBR"}