@grafema/util 0.3.0-beta

package/src/notation/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Notation — Grafema DSL rendering engine
+ *
+ * Transforms graph data into compact visual notation.
+ * Output-only — Datalog remains the query language.
+ *
+ * @module notation
+ */
+
+export type {
+  Archetype,
+  EdgeMapping,
+  DescribeOptions,
+  SubgraphData,
+  NotationBlock,
+  NotationLine,
+  FoldMeta,
+} from './types.js';
+
+export { EDGE_ARCHETYPE_MAP, lookupEdge, generateLegend } from './archetypes.js';
+export { PERSPECTIVES } from './perspectives.js';
+export { renderNotation } from './renderer.js';
+export { extractSubgraph } from './lodExtractor.js';
+export { shortenName } from './nameShortener.js';
+export { foldBlocks } from './fold.js';
+export { renderTraceNarrative } from './traceRenderer.js';
+export type { TraceDetail, TraceNarrativeOptions } from './traceRenderer.js';

package/src/notation/lodExtractor.ts

@@ -0,0 +1,177 @@
+/**
+ * LOD (Level of Detail) Subgraph Extractor
+ *
+ * Extracts a SubgraphData from the graph backend using BFS from a root node.
+ * Different depth levels control how much of the graph neighborhood is fetched.
+ *
+ * - LOD 0: Root + direct containment children (names only in renderer)
+ * - LOD 1: Same + outgoing non-containment edges for each child, resolved targets
+ * - LOD 2: Same + expand children that have their own CONTAINS children
+ *
+ * @module notation/lodExtractor
+ */
+
+import type { BaseNodeRecord, EdgeRecord } from '@grafema/types';
+import type { SubgraphData } from './types.js';
+import { lookupEdge } from './archetypes.js';
+
+/**
+ * Minimal backend interface — matches the project pattern of loose coupling.
+ */
+interface GraphBackend {
+  getNode(id: string): Promise<BaseNodeRecord | null>;
+  getOutgoingEdges(nodeId: string, edgeTypes?: string[] | null): Promise<EdgeRecord[]>;
+  getIncomingEdges(nodeId: string, edgeTypes?: string[] | null): Promise<EdgeRecord[]>;
+}
+
+/**
+ * Containment edge types that define the nesting tree.
+ */
+const CONTAINMENT_TYPES = [
+  'CONTAINS', 'HAS_SCOPE', 'HAS_MEMBER', 'HAS_BODY',
+  'HAS_PROPERTY', 'HAS_ELEMENT', 'HAS_INIT', 'HAS_UPDATE',
+  'HAS_CALLBACK', 'HAS_CATCH', 'HAS_FINALLY',
+  'DECLARES', 'DEFINES', 'MOUNTS', 'PROPERTY_KEY', 'PROPERTY_VALUE',
+];
+
+/**
+ * Extract a subgraph from the backend, rooted at the given node.
+ *
+ * @param backend  Graph backend
+ * @param rootNodeId  Semantic ID of the root node
+ * @param depth  LOD level (0, 1, or 2)
+ */
+export async function extractSubgraph(
+  backend: GraphBackend,
+  rootNodeId: string,
+  depth: number = 1,
+): Promise<SubgraphData> {
+  const nodeMap = new Map<string, BaseNodeRecord>();
+  const allEdges: EdgeRecord[] = [];
+
+  const root = await backend.getNode(rootNodeId);
+  if (!root) {
+    return { rootNodes: [], edges: [], nodeMap };
+  }
+
+  nodeMap.set(root.id, root);
+
+  // Step 1: Get direct containment children
+  const containmentEdges = await backend.getOutgoingEdges(rootNodeId, CONTAINMENT_TYPES);
+  const childIds: string[] = [];
+
+  for (const edge of containmentEdges) {
+    allEdges.push(edge);
+    childIds.push(edge.dst);
+    if (!nodeMap.has(edge.dst)) {
+      const child = await backend.getNode(edge.dst);
+      if (child) nodeMap.set(child.id, child);
+    }
+  }
+
+  // LOD 0: stop here (renderer shows names only)
+  if (depth <= 0) {
+    return { rootNodes: [root], edges: allEdges, nodeMap };
+  }
+
+  // Step 2: For each child (and root), get outgoing non-containment edges
+  const nodesToExpand = [rootNodeId, ...childIds];
+  for (const nodeId of nodesToExpand) {
+    const outgoing = await backend.getOutgoingEdges(nodeId);
+    for (const edge of outgoing) {
+      const mapping = lookupEdge(edge.type);
+      if (mapping.archetype === 'contains') continue; // already handled
+
+      allEdges.push(edge);
+      // Resolve target nodes
+      if (!nodeMap.has(edge.dst)) {
+        const target = await backend.getNode(edge.dst);
+        if (target) nodeMap.set(target.id, target);
+      }
+    }
+  }
+
+  // LOD 1: stop here
+  if (depth <= 1) {
+    return { rootNodes: [root], edges: allEdges, nodeMap };
+  }
+
+  // Step 3 (LOD 2): Expand children that have their own containment children
+  for (const childId of childIds) {
+    const childContainment = await backend.getOutgoingEdges(childId, CONTAINMENT_TYPES);
+    for (const edge of childContainment) {
+      allEdges.push(edge);
+      if (!nodeMap.has(edge.dst)) {
+        const grandchild = await backend.getNode(edge.dst);
+        if (grandchild) nodeMap.set(grandchild.id, grandchild);
+      }
+    }
+
+    // Also get operator edges for grandchildren
+    const grandchildIds = childContainment.map(e => e.dst);
+    for (const gcId of grandchildIds) {
+      const gcOutgoing = await backend.getOutgoingEdges(gcId);
+      for (const edge of gcOutgoing) {
+        const mapping = lookupEdge(edge.type);
+        if (mapping.archetype === 'contains') continue;
+        allEdges.push(edge);
+        if (!nodeMap.has(edge.dst)) {
+          const target = await backend.getNode(edge.dst);
+          if (target) nodeMap.set(target.id, target);
+        }
+      }
+    }
+  }
+
+  // Step 4: Fetch incoming PASSES_ARGUMENT edges for anonymous functions
+  // so the renderer can resolve λ names via callback context.
+  // CALL nodes are often not in the containment tree, so their outgoing
+  // PASSES_ARGUMENT edges don't get picked up by the BFS above.
+  await fetchCallbackContext(backend, allEdges, nodeMap);
+
+  return { rootNodes: [root], edges: allEdges, nodeMap };
+}
+
+/**
+ * For each anonymous arrow/expression in nodeMap, fetch incoming
+ * PASSES_ARGUMENT edges and resolve the CALL source node + sibling args.
+ */
+async function fetchCallbackContext(
+  backend: GraphBackend,
+  allEdges: EdgeRecord[],
+  nodeMap: Map<string, BaseNodeRecord>,
+): Promise<void> {
+  const edgeSet = new Set(allEdges.map(e => `${e.src}|${e.dst}|${e.type}`));
+
+  for (const node of nodeMap.values()) {
+    if (node.name !== '<arrow>' && node.name !== '<expression>') continue;
+
+    const incoming = await backend.getIncomingEdges(node.id, ['PASSES_ARGUMENT']);
+    for (const edge of incoming) {
+      const key = `${edge.src}|${edge.dst}|${edge.type}`;
+      if (edgeSet.has(key)) continue;
+      edgeSet.add(key);
+      allEdges.push(edge);
+
+      // Resolve the CALL node (edge source)
+      if (!nodeMap.has(edge.src)) {
+        const callNode = await backend.getNode(edge.src);
+        if (callNode) nodeMap.set(callNode.id, callNode);
+      }
+
+      // Fetch all PASSES_ARGUMENT from same CALL to find sibling args
+      const callOutgoing = await backend.getOutgoingEdges(edge.src, ['PASSES_ARGUMENT']);
+      for (const sibEdge of callOutgoing) {
+        const sibKey = `${sibEdge.src}|${sibEdge.dst}|${sibEdge.type}`;
+        if (edgeSet.has(sibKey)) continue;
+        edgeSet.add(sibKey);
+        allEdges.push(sibEdge);
+
+        if (!nodeMap.has(sibEdge.dst)) {
+          const sibNode = await backend.getNode(sibEdge.dst);
+          if (sibNode) nodeMap.set(sibNode.id, sibNode);
+        }
+      }
+    }
+  }
+}

package/src/notation/nameShortener.ts

@@ -0,0 +1,24 @@
+/**
+ * Name Shortener — shortest-unambiguous-name within scope
+ *
+ * Given a set of display names in a subgraph, shorten them to the
+ * minimum unique suffix. For example:
+ *
+ *   auth/login.ts -> UserDB.findByEmail  →  UserDB.findByEmail
+ *   auth/login.ts -> createToken         →  createToken
+ *   auth/utils.ts -> createToken         →  utils:createToken
+ *
+ * Phase 4 feature — placeholder for future implementation.
+ *
+ * @module notation/nameShortener
+ */
+
+/**
+ * Shorten a display name to its shortest unambiguous form
+ * within the given set of all names.
+ *
+ * Current implementation: return name as-is (no shortening).
+ */
+export function shortenName(name: string, _allNames: string[]): string {
+  return name;
+}

package/src/notation/perspectives.ts

@@ -0,0 +1,18 @@
+/**
+ * Perspective Presets — archetype filters for describe tool
+ *
+ * Shared between MCP and CLI to keep perspectives in sync.
+ *
+ * @module notation/perspectives
+ */
+
+import type { Archetype } from './types.js';
+
+/** Perspective presets map to archetype filters */
+export const PERSPECTIVES: Record<string, Archetype[]> = {
+  security: ['write', 'exception'],
+  data: ['flow_out', 'flow_in', 'write'],
+  errors: ['exception'],
+  api: ['flow_out', 'publishes', 'depends'],
+  events: ['publishes'],
+};

package/src/notation/renderer.ts

@@ -0,0 +1,394 @@
+/**
+ * Notation Renderer — pure function: SubgraphData → DSL string
+ *
+ * Pipeline:
+ * 1. Classify edges via EDGE_ARCHETYPE_MAP
+ * 2. Separate containment from operator edges
+ * 3. Group operator edges by source node
+ * 4. Sort lines by sortOrder
+ * 5. Merge same-operator same-verb targets
+ * 6. Serialize to indented DSL text
+ *
+ * @module notation/renderer
+ */
+
+import type { EdgeRecord, BaseNodeRecord } from '@grafema/types';
+import type { DescribeOptions, NotationBlock, NotationLine, SubgraphData } from './types.js';
+import { lookupEdge } from './archetypes.js';
+import { getNodeDisplayName } from '../queries/NodeContext.js';
+import { foldBlocks } from './fold.js';
+
+/**
+ * Render a subgraph as compact DSL notation.
+ *
+ * Example output:
+ * ```
+ * login {
+ *   o- imports bcrypt
+ *   > calls UserDB.findByEmail, createToken
+ *   < reads config.auth
+ *   => writes session
+ *   >x throws AuthError
+ *   ~>> emits 'auth:login'
+ * }
+ * ```
+ */
+export function renderNotation(
+  input: SubgraphData,
+  options: DescribeOptions = {},
+): string {
+  const { depth = 1, archetypeFilter, budget = 7, includeLocations = false } = options;
+
+  const blocks = buildBlocks(input, depth, archetypeFilter, budget, includeLocations);
+  const finalBlocks = depth === 2 ? foldBlocks(blocks) : blocks;
+  return serializeBlocks(finalBlocks, 0);
+}
+
+// ---------------------------------------------------------------------------
+// Block building
+// ---------------------------------------------------------------------------
+
+function buildBlocks(
+  input: SubgraphData,
+  depth: number,
+  archetypeFilter: DescribeOptions['archetypeFilter'],
+  budget: number,
+  includeLocations: boolean,
+): NotationBlock[] {
+  const { rootNodes, edges, nodeMap } = input;
+
+  // Index: src → edges, containment edges (src → child node IDs)
+  const outgoingBySource = new Map<string, EdgeRecord[]>();
+  const childrenOf = new Map<string, string[]>();
+
+  for (const edge of edges) {
+    const mapping = lookupEdge(edge.type);
+
+    if (mapping.archetype === 'contains') {
+      // Containment defines tree structure
+      if (!childrenOf.has(edge.src)) childrenOf.set(edge.src, []);
+      childrenOf.get(edge.src)!.push(edge.dst);
+    } else {
+      if (!outgoingBySource.has(edge.src)) outgoingBySource.set(edge.src, []);
+      outgoingBySource.get(edge.src)!.push(edge);
+    }
+  }
+
+  // Build set of node IDs that are descendants of LOOP nodes in containment tree
+  const insideLoopNodes = buildLoopDescendants(childrenOf, nodeMap);
+
+  const resolvedNames = resolveAnonymousNames(edges, nodeMap);
+
+  return rootNodes.map(node =>
+    buildBlock(node, outgoingBySource, childrenOf, nodeMap, depth, archetypeFilter, budget, includeLocations, insideLoopNodes, resolvedNames),
+  );
+}
+
+/**
+ * Collect all node IDs that are descendants of LOOP-type nodes in the containment tree.
+ * Uses BFS from each LOOP node, traversing containment children recursively.
+ */
+function buildLoopDescendants(
+  childrenOf: Map<string, string[]>,
+  nodeMap: Map<string, BaseNodeRecord>,
+): Set<string> {
+  const result = new Set<string>();
+
+  // Find all LOOP nodes and collect their descendants
+  for (const [parentId, children] of childrenOf) {
+    const parentNode = nodeMap.get(parentId);
+    if (parentNode?.type === 'LOOP') {
+      // BFS to collect all descendants of this LOOP node
+      const queue = [...children];
+      while (queue.length > 0) {
+        const id = queue.shift()!;
+        if (result.has(id)) continue;
+        result.add(id);
+        const grandchildren = childrenOf.get(id);
+        if (grandchildren) {
+          queue.push(...grandchildren);
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Resolve meaningful names for anonymous arrow functions and expressions.
+ *
+ * Priority:
+ * 1. Assignment: `const handler = () => {}` → "handler"
+ * 2. Callback: `setRequestHandler(Schema, λ)` → "λ → setRequestHandler(Schema)"
+ * 3. Fallback: "λ"
+ */
+function resolveAnonymousNames(
+  edges: EdgeRecord[],
+  nodeMap: Map<string, BaseNodeRecord>,
+): Map<string, string> {
+  const resolved = new Map<string, string>();
+
+  // Reverse index: dstId → edges (for ASSIGNED_FROM and PASSES_ARGUMENT)
+  const incomingByDst = new Map<string, EdgeRecord[]>();
+  // Forward index: srcId → PASSES_ARGUMENT edges (for finding siblings)
+  const passArgBySrc = new Map<string, EdgeRecord[]>();
+
+  for (const edge of edges) {
+    if (edge.type === 'ASSIGNED_FROM' || edge.type === 'PASSES_ARGUMENT') {
+      if (!incomingByDst.has(edge.dst)) incomingByDst.set(edge.dst, []);
+      incomingByDst.get(edge.dst)!.push(edge);
+    }
+    if (edge.type === 'PASSES_ARGUMENT') {
+      if (!passArgBySrc.has(edge.src)) passArgBySrc.set(edge.src, []);
+      passArgBySrc.get(edge.src)!.push(edge);
+    }
+  }
+
+  for (const [nodeId, node] of nodeMap) {
+    if (node.name !== '<arrow>' && node.name !== '<expression>') continue;
+
+    const incoming = incomingByDst.get(nodeId) ?? [];
+
+    // Priority 1: Assignment — const handler = () => {}
+    const assignEdge = incoming.find(e => e.type === 'ASSIGNED_FROM');
+    if (assignEdge) {
+      const srcNode = nodeMap.get(assignEdge.src);
+      if (srcNode?.name && srcNode.name !== '<arrow>' && srcNode.name !== '<expression>') {
+        resolved.set(nodeId, srcNode.name);
+        continue;
+      }
+    }
+
+    // Priority 2: Callback — setRequestHandler(Schema, λ)
+    const passEdge = incoming.find(e => e.type === 'PASSES_ARGUMENT');
+    if (passEdge) {
+      const callNode = nodeMap.get(passEdge.src);
+      const callName = callNode ? getNodeDisplayName(callNode) : null;
+      if (callName && callName !== '<arrow>' && callName !== '<expression>' && callName !== 'λ') {
+        // Named sibling args (skip other anonymous ones)
+        const allSiblings = passArgBySrc.get(passEdge.src) ?? [];
+        const namedSiblings = allSiblings
+          .filter(e => e.dst !== nodeId)
+          .map(e => {
+            const argNode = nodeMap.get(e.dst);
+            if (!argNode?.name) return null;
+            if (argNode.name === '<arrow>' || argNode.name === '<expression>') return null;
+            return argNode.name;
+          })
+          .filter((n): n is string => n !== null);
+
+        // Multiple lambdas in same call → add index to distinguish
+        const lambdaCount = allSiblings.filter(e => {
+          const n = nodeMap.get(e.dst);
+          return n && (n.name === '<arrow>' || n.name === '<expression>');
+        }).length;
+        const indexSuffix = lambdaCount > 1
+          ? String(passEdge.metadata?.index ?? passEdge.metadata?.argIndex ?? '')
+          : '';
+
+        const argStr = namedSiblings.length > 0 ? `(${namedSiblings.join(', ')})` : '';
+        resolved.set(nodeId, `λ${indexSuffix} → ${callName}${argStr}`);
+        continue;
+      }
+    }
+
+    // Priority 3: Fallback
+    resolved.set(nodeId, 'λ');
+  }
+
+  return resolved;
+}
+
+function buildBlock(
+  node: BaseNodeRecord,
+  outgoingBySource: Map<string, EdgeRecord[]>,
+  childrenOf: Map<string, string[]>,
+  nodeMap: Map<string, BaseNodeRecord>,
+  depth: number,
+  archetypeFilter: DescribeOptions['archetypeFilter'],
+  budget: number,
+  includeLocations: boolean,
+  insideLoopNodes: Set<string>,
+  resolvedNames: Map<string, string>,
+): NotationBlock {
+  const displayName = resolvedNames.get(node.id) ?? getNodeDisplayName(node);
+  const location = includeLocations && node.file
+    ? `${node.file}${node.line ? ':' + node.line : ''}`
+    : undefined;
+
+  // LOD 0: names only — no edges, no children
+  if (depth <= 0) {
+    return { nodeId: node.id, displayName, nodeType: node.type, lines: [], children: [], location };
+  }
+
+  // LOD 1+: build edge lines
+  const nodeEdges = outgoingBySource.get(node.id) ?? [];
+  const lines = buildLines(nodeEdges, nodeMap, archetypeFilter, budget, resolvedNames);
+
+  // Apply [] loop modifier if this node is inside a LOOP
+  // Combines with existing modifiers: [] ?? > calls foo
+  if (insideLoopNodes.has(node.id)) {
+    for (const line of lines) {
+      line.modifier = line.modifier ? `[] ${line.modifier}` : '[]';
+    }
+  }
+
+  // LOD 2+: recurse into contained children
+  let children: NotationBlock[] = [];
+  if (depth >= 2) {
+    const childIds = childrenOf.get(node.id) ?? [];
+    children = childIds
+      .map(id => nodeMap.get(id))
+      .filter((n): n is BaseNodeRecord => n != null)
+      .map(child =>
+        buildBlock(child, outgoingBySource, childrenOf, nodeMap, depth - 1, archetypeFilter, budget, includeLocations, insideLoopNodes, resolvedNames),
+      );
+  }
+
+  return { nodeId: node.id, displayName, nodeType: node.type, lines, children, location };
+}
+
+// ---------------------------------------------------------------------------
+// Line building — group, sort, merge
+// ---------------------------------------------------------------------------
+
+function buildLines(
+  edges: EdgeRecord[],
+  nodeMap: Map<string, BaseNodeRecord>,
+  archetypeFilter: DescribeOptions['archetypeFilter'],
+  budget: number,
+  resolvedNames: Map<string, string>,
+): NotationLine[] {
+  // Group by modifier+operator+verb key (modifier separates certain from uncertain)
+  const groups = new Map<string, { operator: string; verb: string; targets: string[]; sortOrder: number; modifier?: string }>();
+
+  for (const edge of edges) {
+    const mapping = lookupEdge(edge.type);
+
+    // Apply archetype filter
+    if (archetypeFilter && !archetypeFilter.includes(mapping.archetype)) continue;
+
+    const targetNode = nodeMap.get(edge.dst);
+    const targetName = resolvedNames.get(edge.dst) ?? (targetNode ? getNodeDisplayName(targetNode) : edge.dst);
+
+    // Detect dynamic/uncertain edges
+    const modifier = isDynamicEdge(edge) ? '??' : undefined;
+
+    const key = `${modifier ?? ''}|${mapping.operator}|${mapping.verb}`;
+    if (!groups.has(key)) {
+      groups.set(key, {
+        operator: mapping.operator,
+        verb: mapping.verb,
+        targets: [],
+        sortOrder: mapping.sortOrder,
+        modifier,
+      });
+    }
+    groups.get(key)!.targets.push(targetName);
+  }
+
+  // Sort by sortOrder
+  const sorted = Array.from(groups.values()).sort((a, b) => a.sortOrder - b.sortOrder);
+
+  // Apply budget: show top-N, summarize rest
+  if (sorted.length > budget) {
+    const shown = sorted.slice(0, budget);
+    const hidden = sorted.slice(budget);
+    const hiddenCount = hidden.reduce((sum, g) => sum + g.targets.length, 0);
+    shown.push({
+      operator: '',
+      verb: `...+${hiddenCount} more`,
+      targets: [],
+      sortOrder: 999,
+    });
+    return shown.map(g => ({
+      operator: g.operator,
+      verb: g.verb,
+      targets: g.targets,
+      sortOrder: g.sortOrder,
+      modifier: g.modifier,
+    }));
+  }
+
+  return sorted.map(g => ({
+    operator: g.operator,
+    verb: g.verb,
+    targets: g.targets,
+    sortOrder: g.sortOrder,
+    modifier: g.modifier,
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Edge metadata helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if an edge is dynamic/uncertain based on its metadata.
+ *
+ * An edge is dynamic/uncertain if any of these hold:
+ * - metadata.resolved === false (unresolved reference)
+ * - metadata.confidence exists and is < 1.0 (low-confidence inference)
+ * - metadata.dynamic === true (dynamic dispatch)
+ */
+function isDynamicEdge(edge: EdgeRecord): boolean {
+  const meta = edge.metadata;
+  if (!meta) return false;
+
+  if (meta.resolved === false) return true;
+  if (typeof meta.confidence === 'number' && meta.confidence < 1.0) return true;
+  if (meta.dynamic === true) return true;
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Serialization
+// ---------------------------------------------------------------------------
+
+function serializeBlocks(blocks: NotationBlock[], indentLevel: number): string {
+  return blocks.map(block => serializeBlock(block, indentLevel)).join('\n');
+}
+
+function serializeBlock(block: NotationBlock, indentLevel: number): string {
+  const indent = '  '.repeat(indentLevel);
+  const hasContent = block.lines.length > 0 || block.children.length > 0;
+
+  // Header
+  const loc = block.location ? `  (${block.location})` : '';
+  let result: string;
+
+  if (!hasContent) {
+    // Leaf node — just name
+    result = `${indent}${block.displayName}${loc}`;
+  } else {
+    result = `${indent}${block.displayName}${loc} {\n`;
+
+    // Lines
+    for (const line of block.lines) {
+      result += serializeLine(line, indentLevel + 1);
+    }
+
+    // Children
+    if (block.children.length > 0) {
+      result += serializeBlocks(block.children, indentLevel + 1) + '\n';
+    }
+
+    result += `${indent}}`;
+  }
+
+  return result;
+}
+
+function serializeLine(line: NotationLine, indentLevel: number): string {
+  const indent = '  '.repeat(indentLevel);
+  const mod = line.modifier ? `${line.modifier} ` : '';
+  const prefix = line.operator ? `${line.operator} ` : '';
+
+  if (line.targets.length === 0) {
+    return `${indent}${mod}${prefix}${line.verb}\n`;
+  }
+
+  return `${indent}${mod}${prefix}${line.verb} ${line.targets.join(', ')}\n`;
+}