@grafema/core 0.2.5-beta → 0.2.7

package/src/core/ResourceRegistry.ts

@@ -0,0 +1,39 @@
+import type { Resource, ResourceId, ResourceRegistry as IResourceRegistry } from '@grafema/types';
+
+/**
+ * In-memory Resource registry for a single pipeline run.
+ * Created by Orchestrator at run start, cleared at run end.
+ *
+ * Thread safety: Not needed — Grafema runs plugins sequentially within
+ * each phase. Plugins are toposorted and run one at a time.
+ */
+export class ResourceRegistryImpl implements IResourceRegistry {
+  private resources = new Map<ResourceId, Resource>();
+
+  getOrCreate<T extends Resource>(id: ResourceId, factory: () => T): T {
+    let resource = this.resources.get(id);
+    if (!resource) {
+      resource = factory();
+      if (resource.id !== id) {
+        throw new Error(
+          `Resource factory returned resource with id "${resource.id}" but expected "${id}"`
+        );
+      }
+      this.resources.set(id, resource);
+    }
+    return resource as T;
+  }
+
+  get<T extends Resource>(id: ResourceId): T | undefined {
+    return this.resources.get(id) as T | undefined;
+  }
+
+  has(id: ResourceId): boolean {
+    return this.resources.has(id);
+  }
+
+  /** Clear all Resources. Called by Orchestrator at the end of a run. */
+  clear(): void {
+    this.resources.clear();
+  }
+}

package/src/core/ScopeTracker.ts

@@ -95,6 +95,29 @@ export class ScopeTracker {
     return this.scopeStack.map(s => s.name).join('->');
   }
 
+  /**
+   * Get the nearest named ancestor scope.
+   *
+   * Walks the scope stack from innermost to outermost, skipping
+   * counted scopes (if#0, try#1, for#0, etc.) and returns the
+   * first named scope.
+   *
+   * Returns undefined when at top-level (global scope).
+   *
+   * Used by v2 semantic ID generation to determine the namedParent.
+   */
+  getNamedParent(): string | undefined {
+    for (let i = this.scopeStack.length - 1; i >= 0; i--) {
+      const entry = this.scopeStack[i];
+      // Skip counted scopes (if#0, try#1, for#0, etc.)
+      if (entry.name.includes('#')) continue;
+      // Skip anonymous functions (anonymous, anonymous[0], anonymous[1], etc.)
+      if (entry.name === 'anonymous' || entry.name.startsWith('anonymous[')) continue;
+      return entry.name;
+    }
+    return undefined;
+  }
+
   /**
    * Get the innermost enclosing scope of a specific type.
    * Searches from innermost to outermost.

package/src/core/SemanticId.ts

@@ -66,6 +66,46 @@ export interface LocatedItem {
   location: Location;
 }
 
+// =============================================================================
+// Semantic ID v2
+// =============================================================================
+
+/**
+ * Parsed v2 semantic ID components.
+ *
+ * v2 format: file->TYPE->name[in:namedParent,h:xxxx]#N
+ *
+ * Key difference from v1: no scope path in ID. Only nearest named ancestor
+ * (namedParent) is encoded. Anonymous scopes (if, for, try) are invisible.
+ */
+export interface ParsedSemanticIdV2 {
+  file: string;
+  type: string;
+  name: string;
+  namedParent?: string;
+  contentHash?: string;
+  counter?: number;
+}
+
+/**
+ * Content hint data for computing content hash.
+ * Each node type supplies different hints for disambiguation.
+ */
+export interface ContentHashHints {
+  /** Number of arguments (CALL) or parameters (FUNCTION) */
+  arity?: number;
+  /** First literal argument value (CALL) */
+  firstLiteralArg?: string;
+  /** First parameter name (FUNCTION) */
+  firstParamName?: string;
+  /** RHS expression type (VARIABLE/CONSTANT) */
+  rhsType?: string;
+  /** First significant token of RHS (VARIABLE/CONSTANT) */
+  rhsToken?: string;
+  /** Object expression chain (PROPERTY_ACCESS) */
+  objectChain?: string;
+}
+
 /**
  * Compute semantic ID for any node type.
  *
@@ -190,3 +230,146 @@ export function computeDiscriminator(
 
   return index >= 0 ? index : 0;
 }
+
+// =============================================================================
+// Semantic ID v2 Functions
+// =============================================================================
+
+/**
+ * Compute v2 semantic ID.
+ *
+ * Format: file->TYPE->name                           (top-level, no collision)
+ * Format: file->TYPE->name[in:parent]                (nested, no collision)
+ * Format: file->TYPE->name[in:parent,h:xxxx]         (collision, hash disambiguates)
+ * Format: file->TYPE->name[in:parent,h:xxxx]#N       (hash collision, counter)
+ *
+ * @param type - Node type (FUNCTION, CALL, VARIABLE, etc.)
+ * @param name - Node name
+ * @param file - Source file path
+ * @param namedParent - Nearest named ancestor (undefined for top-level)
+ * @param contentHash - 4-hex content hash (set by CollisionResolver)
+ * @param counter - Counter for hash collisions (set by CollisionResolver)
+ */
+export function computeSemanticIdV2(
+  type: string,
+  name: string,
+  file: string,
+  namedParent?: string,
+  contentHash?: string,
+  counter?: number
+): string {
+  const brackets: string[] = [];
+  if (namedParent) brackets.push(`in:${namedParent}`);
+  if (contentHash) brackets.push(`h:${contentHash}`);
+
+  let id = `${file}->${type}->${name}`;
+  if (brackets.length > 0) {
+    id += `[${brackets.join(',')}]`;
+  }
+  if (counter !== undefined && counter > 0) {
+    id += `#${counter}`;
+  }
+  return id;
+}
+
+/**
+ * Parse v2 semantic ID back to components.
+ *
+ * Handles v2 format: file->TYPE->name[in:parent,h:xxxx]#N
+ * and special formats: net:stdio->__stdio__, EXTERNAL_MODULE->lodash
+ *
+ * @returns Parsed components or null if not a valid v2 ID
+ */
+export function parseSemanticIdV2(id: string): ParsedSemanticIdV2 | null {
+  // Handle singletons
+  if (id.startsWith('net:stdio') || id.startsWith('net:request')) {
+    const arrowIdx = id.indexOf('->');
+    if (arrowIdx === -1) return null;
+    return { file: '', type: 'SINGLETON', name: id.slice(arrowIdx + 2) };
+  }
+
+  if (id.startsWith('EXTERNAL_MODULE')) {
+    const arrowIdx = id.indexOf('->');
+    if (arrowIdx === -1) return null;
+    return { file: '', type: 'EXTERNAL_MODULE', name: id.slice(arrowIdx + 2) };
+  }
+
+  // v2 format: file->TYPE->name[in:parent,h:xxxx]#N
+  // Exactly two '->' delimiters: file->TYPE->rest
+  const firstArrow = id.indexOf('->');
+  if (firstArrow === -1) return null;
+
+  const secondArrow = id.indexOf('->', firstArrow + 2);
+  if (secondArrow === -1) return null;
+
+  const file = id.slice(0, firstArrow);
+  const type = id.slice(firstArrow + 2, secondArrow);
+  let rest = id.slice(secondArrow + 2);
+
+  // Check this isn't a v1 ID (v1 has 4+ parts, meaning rest contains '->')
+  // v2 names don't contain '->' in practice
+  if (rest.includes('->')) return null;
+
+  // Parse counter suffix: #N (only at the very end, after brackets)
+  let counter: number | undefined;
+  const counterMatch = rest.match(/#(\d+)$/);
+  if (counterMatch) {
+    counter = parseInt(counterMatch[1], 10);
+    rest = rest.slice(0, -counterMatch[0].length);
+  }
+
+  // Parse bracket content: [in:parent,h:xxxx]
+  let namedParent: string | undefined;
+  let contentHash: string | undefined;
+  let name = rest;
+
+  const bracketStart = rest.indexOf('[');
+  const bracketEnd = rest.lastIndexOf(']');
+  if (bracketStart !== -1 && bracketEnd === rest.length - 1) {
+    name = rest.slice(0, bracketStart);
+    const bracketContent = rest.slice(bracketStart + 1, bracketEnd);
+
+    for (const part of bracketContent.split(',')) {
+      const colonIdx = part.indexOf(':');
+      if (colonIdx === -1) continue;
+      const key = part.slice(0, colonIdx);
+      const value = part.slice(colonIdx + 1);
+      if (key === 'in') namedParent = value;
+      else if (key === 'h') contentHash = value;
+    }
+  }
+
+  return { file, type, name, namedParent, contentHash, counter };
+}
+
+/**
+ * FNV-1a hash function, returns 4-hex-char string.
+ *
+ * FNV-1a is simple, fast, and has good distribution for short strings.
+ * 4 hex chars = 16 bits = 65536 buckets.
+ *
+ * @param hints - Content data to hash
+ * @returns 4-char hex string (e.g., "a1b2")
+ */
+export function computeContentHash(hints: ContentHashHints): string {
+  const parts: string[] = [];
+  if (hints.arity !== undefined) parts.push(`a:${hints.arity}`);
+  if (hints.firstLiteralArg !== undefined) parts.push(`l:${hints.firstLiteralArg}`);
+  if (hints.firstParamName !== undefined) parts.push(`p:${hints.firstParamName}`);
+  if (hints.rhsType !== undefined) parts.push(`r:${hints.rhsType}`);
+  if (hints.rhsToken !== undefined) parts.push(`t:${hints.rhsToken}`);
+  if (hints.objectChain !== undefined) parts.push(`o:${hints.objectChain}`);
+
+  const input = parts.join('|');
+
+  // FNV-1a 32-bit
+  let hash = 0x811c9dc5; // FNV offset basis
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193); // FNV prime
+  }
+
+  // Truncate to 16 bits, format as 4-hex
+  const truncated = (hash >>> 0) & 0xffff;
+  return truncated.toString(16).padStart(4, '0');
+}

package/src/core/brandNodeInternal.ts

@@ -0,0 +1,16 @@
+/**
+ * Internal branding helper for legitimate uses outside NodeFactory.
+ * DO NOT import this in analyzers or plugins - use NodeFactory instead.
+ *
+ * Legitimate uses:
+ * - NodeFactory (centralized node creation)
+ * - GraphBuilder._flushNodes() - batches validated nodes from builders
+ * - RFDBServerBackend._parseNode() - re-brands nodes from database
+ *
+ * @internal
+ */
+import type { BaseNodeRecord, BrandedNode } from '@grafema/types';
+
+export function brandNodeInternal<T extends BaseNodeRecord>(node: T): BrandedNode<T> {
+  return node as BrandedNode<T>;
+}

package/src/core/buildDependencyGraph.ts

@@ -0,0 +1,98 @@
+/**
+ * Build dependency graph from plugin consumes/produces declarations (RFD-2).
+ *
+ * Two-layer dependency resolution:
+ *
+ * Layer 1 (automatic): If plugin A produces edge type E,
+ *   and plugin B consumes edge type E, then B depends on A.
+ *   Self-references (same plugin consumes what it produces) excluded.
+ *
+ * Layer 2 (explicit): metadata.dependencies merged in.
+ *   Handles cross-phase deps and plugins without consumes/produces.
+ *
+ * Self-reference handling: When a plugin both consumes and produces the same
+ * edge type (e.g., InstanceOfResolver rewires INSTANCE_OF edges), it does NOT
+ * create a self-dependency. This is intentional — enrichers extend the graph.
+ *
+ * Opportunistic reading: If a plugin reads an edge type only for filtering
+ * (e.g., "skip if CALLS edge exists"), it should NOT declare that in consumes.
+ * Use explicit dependencies for the actual ordering constraint instead.
+ *
+ * Complexity: O(E + P) where E = plugins, P = total produces entries.
+ */
+
+import type { IPlugin, EdgeType } from '@grafema/types';
+import type { ToposortItem } from './toposort.js';
+
+/**
+ * Result of building the enricher dependency graph.
+ * Contains both the toposort items and a consumer index
+ * for downstream propagation (RFD-17).
+ */
+export interface EnricherDependencyInfo {
+  items: ToposortItem[];
+  /** Maps edgeType → set of enricher names that consume that type */
+  consumerIndex: Map<string, Set<string>>;
+}
+
+export function buildDependencyGraph(plugins: IPlugin[]): EnricherDependencyInfo {
+  // Step 1: Build producer index — Map<EdgeType, pluginNames[]>
+  const producers = new Map<EdgeType, string[]>();
+
+  for (const plugin of plugins) {
+    const meta = plugin.metadata;
+    if (!meta.produces) continue;
+    for (const edgeType of meta.produces) {
+      let list = producers.get(edgeType);
+      if (!list) {
+        list = [];
+        producers.set(edgeType, list);
+      }
+      list.push(meta.name);
+    }
+  }
+
+  // Step 2: For each plugin, compute deps from consumes + explicit
+  // Also build consumer index for downstream propagation (RFD-17)
+  const consumerIndex = new Map<string, Set<string>>();
+
+  const items = plugins.map(plugin => {
+    const meta = plugin.metadata;
+    const deps = new Set<string>();
+
+    // Layer 1: Automatic inference from consumes/produces
+    if (meta.consumes) {
+      for (const edgeType of meta.consumes) {
+        // Register in consumer index (RFD-17)
+        let consumers = consumerIndex.get(edgeType);
+        if (!consumers) {
+          consumers = new Set();
+          consumerIndex.set(edgeType, consumers);
+        }
+        consumers.add(meta.name);
+
+        const edgeProducers = producers.get(edgeType);
+        if (!edgeProducers) continue;
+        for (const producerName of edgeProducers) {
+          if (producerName !== meta.name) {
+            deps.add(producerName);
+          }
+        }
+      }
+    }
+
+    // Layer 2: Merge explicit dependencies
+    if (meta.dependencies) {
+      for (const dep of meta.dependencies) {
+        deps.add(dep);
+      }
+    }
+
+    return {
+      id: meta.name,
+      dependencies: [...deps],
+    };
+  });
+
+  return { items, consumerIndex };
+}