openplanter 0.1.0

package/dist/investigation-tools/insider-graph.js

@@ -0,0 +1,732 @@
+/**
+ * insider-graph.ts — Entity-event relationship graph builder for insider trading investigations.
+ *
+ * Builds directed graphs of people, companies, events, and tickers with weighted edges
+ * representing relationships (shareholdings, directorships, trades, announcements, etc.).
+ * Supports pathfinding (Dijkstra), neighbourhood queries, community detection, and
+ * suspicion-path analysis connecting trade events to information sources.
+ *
+ * Migrated from tools/insider_graph.py — all graph algorithms implemented from scratch
+ * with no external dependencies.
+ */
+// ── Constants ──────────────────────────────────────────────────
+export const VALID_NODE_TYPES = new Set(["person", "company", "event", "ticker"]);
+export const EDGE_TYPE_DEFAULTS = {
+    holds_shares: 1,
+    is_director: 1,
+    traded: 2,
+    announced: 1,
+    related_to: 3,
+    same_entity: 0,
+    lobbied_by: 2,
+    committee_member: 2,
+};
+/** Event sub-types treated as "information sources" for suspicion analysis. */
+export const INFO_SOURCE_EVENT_SUBTYPES = new Set([
+    "announcement",
+    "report",
+    "meeting",
+]);
+class MinHeap {
+    heap = [];
+    get size() {
+        return this.heap.length;
+    }
+    push(key, value) {
+        this.heap.push({ key, value });
+        this.bubbleUp(this.heap.length - 1);
+    }
+    pop() {
+        if (this.heap.length === 0)
+            return undefined;
+        const top = this.heap[0];
+        const last = this.heap.pop();
+        if (this.heap.length > 0) {
+            this.heap[0] = last;
+            this.sinkDown(0);
+        }
+        return top;
+    }
+    bubbleUp(idx) {
+        while (idx > 0) {
+            const parent = (idx - 1) >> 1;
+            if (this.heap[parent].key <= this.heap[idx].key)
+                break;
+            [this.heap[parent], this.heap[idx]] = [this.heap[idx], this.heap[parent]];
+            idx = parent;
+        }
+    }
+    sinkDown(idx) {
+        const len = this.heap.length;
+        for (;;) {
+            let smallest = idx;
+            const left = 2 * idx + 1;
+            const right = 2 * idx + 2;
+            if (left < len && this.heap[left].key < this.heap[smallest].key)
+                smallest = left;
+            if (right < len && this.heap[right].key < this.heap[smallest].key)
+                smallest = right;
+            if (smallest === idx)
+                break;
+            [this.heap[smallest], this.heap[idx]] = [this.heap[idx], this.heap[smallest]];
+            idx = smallest;
+        }
+    }
+}
+// ── Internal helpers ───────────────────────────────────────────
+function getEdgeWeight(edata) {
+    return typeof edata?.weight === "number" ? edata.weight : 1;
+}
+function undirectedEdgeData(G, u, v) {
+    return G.getEdgeData(u, v) ?? G.getEdgeData(v, u) ?? {};
+}
+function nodeStr(attrs, key, fallback) {
+    const v = attrs?.[key];
+    return typeof v === "string" ? v : fallback;
+}
+function nodeOptStr(attrs, key) {
+    const v = attrs?.[key];
+    return typeof v === "string" ? v : undefined;
+}
+// ── DiGraph class ──────────────────────────────────────────────
+/**
+ * Lightweight directed graph with adjacency-list storage.
+ *
+ * Stores node attributes and edge attributes. Supports both directed
+ * and undirected-view operations required for insider-graph analysis.
+ */
+export class DiGraph {
+    _nodes = new Map();
+    _adj = new Map();
+    _pred = new Map();
+    // ── Mutation ───────────────────────────────────────────────
+    /** Add a node (or update its attributes if it already exists). */
+    addNode(id, attrs = {}) {
+        const existing = this._nodes.get(id);
+        if (existing) {
+            Object.assign(existing, attrs);
+        }
+        else {
+            this._nodes.set(id, { ...attrs });
+            if (!this._adj.has(id))
+                this._adj.set(id, new Map());
+            if (!this._pred.has(id))
+                this._pred.set(id, new Set());
+        }
+    }
+    /** Add a directed edge (or update its attributes if it already exists). */
+    addEdge(source, target, attrs = {}) {
+        if (!this._nodes.has(source))
+            this.addNode(source);
+        if (!this._nodes.has(target))
+            this.addNode(target);
+        const fwd = this._adj.get(source);
+        const existing = fwd.get(target);
+        if (existing) {
+            Object.assign(existing, attrs);
+        }
+        else {
+            fwd.set(target, { ...attrs });
+        }
+        this._pred.get(target).add(source);
+    }
+    // ── Queries ────────────────────────────────────────────────
+    hasNode(id) {
+        return this._nodes.has(id);
+    }
+    getNodeData(id) {
+        return this._nodes.get(id);
+    }
+    getEdgeData(u, v) {
+        return this._adj.get(u)?.get(v);
+    }
+    numberOfNodes() {
+        return this._nodes.size;
+    }
+    numberOfEdges() {
+        let count = 0;
+        for (const targets of this._adj.values())
+            count += targets.size;
+        return count;
+    }
+    /** All node IDs. */
+    nodeIds() {
+        return [...this._nodes.keys()];
+    }
+    /** Iterate over nodes with their attribute dicts. */
+    nodesWithData() {
+        return [...this._nodes.entries()];
+    }
+    /** Iterate over edges as [source, target, attrs] triples. */
+    edgesWithData() {
+        const result = [];
+        for (const [src, targets] of this._adj) {
+            for (const [tgt, attrs] of targets) {
+                result.push([src, tgt, attrs]);
+            }
+        }
+        return result;
+    }
+    /** Outgoing neighbours (directed). */
+    successors(node) {
+        const adj = this._adj.get(node);
+        return adj ? [...adj.keys()] : [];
+    }
+    /** Incoming neighbours (directed). */
+    predecessors(node) {
+        const pred = this._pred.get(node);
+        return pred ? [...pred] : [];
+    }
+    /** All neighbours (undirected view — union of successors and predecessors). */
+    undirectedNeighbors(node) {
+        const nbrs = new Set();
+        const adj = this._adj.get(node);
+        if (adj)
+            for (const n of adj.keys())
+                nbrs.add(n);
+        const pred = this._pred.get(node);
+        if (pred)
+            for (const n of pred)
+                nbrs.add(n);
+        return [...nbrs];
+    }
+}
+// ── Graph algorithms (internal) ────────────────────────────────
+/**
+ * Dijkstra shortest path on the undirected view of G.
+ * Returns {path, length} or null if no path exists.
+ */
+function dijkstraPath(G, source, target) {
+    if (!G.hasNode(source) || !G.hasNode(target))
+        return null;
+    const dist = new Map();
+    const prev = new Map();
+    const visited = new Set();
+    const heap = new MinHeap();
+    dist.set(source, 0);
+    prev.set(source, null);
+    heap.push(0, source);
+    while (heap.size > 0) {
+        const { key: d, value: u } = heap.pop();
+        if (visited.has(u))
+            continue;
+        visited.add(u);
+        if (u === target) {
+            const path = [];
+            let cur = target;
+            while (cur != null) {
+                path.unshift(cur);
+                cur = prev.get(cur) ?? null;
+                if (cur === null)
+                    break; // reached source
+            }
+            return { path, length: d };
+        }
+        for (const nbr of G.undirectedNeighbors(u)) {
+            if (visited.has(nbr))
+                continue;
+            const edata = undirectedEdgeData(G, u, nbr);
+            const w = getEdgeWeight(edata);
+            const newDist = d + w;
+            const oldDist = dist.get(nbr);
+            if (oldDist === undefined || newDist < oldDist) {
+                dist.set(nbr, newDist);
+                prev.set(nbr, u);
+                heap.push(newDist, nbr);
+            }
+        }
+    }
+    return null;
+}
+/** Connected components on the undirected view (BFS). */
+function connectedComponents(G) {
+    const visited = new Set();
+    const components = [];
+    for (const node of G.nodeIds()) {
+        if (visited.has(node))
+            continue;
+        const component = [];
+        const queue = [node];
+        visited.add(node);
+        while (queue.length > 0) {
+            const cur = queue.shift();
+            component.push(cur);
+            for (const nbr of G.undirectedNeighbors(cur)) {
+                if (!visited.has(nbr)) {
+                    visited.add(nbr);
+                    queue.push(nbr);
+                }
+            }
+        }
+        components.push(component);
+    }
+    return components;
+}
+/**
+ * Betweenness centrality on the undirected view (Brandes' algorithm with weights).
+ * Returns a map of node ID → centrality score (normalised).
+ */
+function betweennessCentrality(G) {
+    const nodes = G.nodeIds();
+    const n = nodes.length;
+    const centrality = new Map();
+    for (const nd of nodes)
+        centrality.set(nd, 0);
+    for (const s of nodes) {
+        // Weighted single-source shortest-path (Dijkstra)
+        const stack = [];
+        const pred = new Map();
+        for (const nd of nodes)
+            pred.set(nd, []);
+        const sigma = new Map();
+        for (const nd of nodes)
+            sigma.set(nd, 0);
+        sigma.set(s, 1);
+        const dist = new Map();
+        for (const nd of nodes)
+            dist.set(nd, Infinity);
+        dist.set(s, 0);
+        const heap = new MinHeap();
+        heap.push(0, s);
+        while (heap.size > 0) {
+            const { key: d, value: v } = heap.pop();
+            if (d > dist.get(v))
+                continue;
+            stack.push(v);
+            for (const w of G.undirectedNeighbors(v)) {
+                const edata = undirectedEdgeData(G, v, w);
+                const ew = getEdgeWeight(edata);
+                const newDist = d + ew;
+                const wDist = dist.get(w);
+                if (newDist < wDist) {
+                    dist.set(w, newDist);
+                    sigma.set(w, 0);
+                    pred.set(w, [v]);
+                    sigma.set(w, sigma.get(v));
+                    heap.push(newDist, w);
+                }
+                else if (Math.abs(newDist - wDist) < 1e-10) {
+                    sigma.set(w, sigma.get(w) + sigma.get(v));
+                    pred.get(w).push(v);
+                }
+            }
+        }
+        // Accumulation
+        const delta = new Map();
+        for (const nd of nodes)
+            delta.set(nd, 0);
+        while (stack.length > 0) {
+            const w = stack.pop();
+            for (const v of pred.get(w)) {
+                const sigmaV = sigma.get(v);
+                const sigmaW = sigma.get(w);
+                if (sigmaW > 0) {
+                    delta.set(v, delta.get(v) + (sigmaV / sigmaW) * (1 + delta.get(w)));
+                }
+            }
+            if (w !== s) {
+                centrality.set(w, centrality.get(w) + delta.get(w));
+            }
+        }
+    }
+    // Normalise for undirected graph: multiply by 2 / ((n-1)(n-2))
+    if (n > 2) {
+        const norm = 2 / ((n - 1) * (n - 2));
+        for (const [nd, val] of centrality) {
+            centrality.set(nd, val * norm);
+        }
+    }
+    return centrality;
+}
+/** Diameter of the undirected view (max shortest-path hop-count). Unweighted BFS. */
+function computeDiameter(G) {
+    let maxDist = 0;
+    for (const s of G.nodeIds()) {
+        const dist = new Map();
+        dist.set(s, 0);
+        const queue = [s];
+        while (queue.length > 0) {
+            const u = queue.shift();
+            const uDist = dist.get(u);
+            for (const nbr of G.undirectedNeighbors(u)) {
+                if (!dist.has(nbr)) {
+                    const d = uDist + 1;
+                    dist.set(nbr, d);
+                    if (d > maxDist)
+                        maxDist = d;
+                    queue.push(nbr);
+                }
+            }
+        }
+    }
+    return maxDist;
+}
+// ── Graph construction ─────────────────────────────────────────
+/** Construct a DiGraph from the canonical input JSON schema. */
+export function buildGraph(data) {
+    const G = new DiGraph();
+    for (const node of data.nodes ?? []) {
+        const attrs = {};
+        attrs.type = node.type ?? "unknown";
+        attrs.label = node.label ?? node.id;
+        // Promote subtype from either top-level or properties.
+        const subtype = node.subtype ?? node.properties?.subtype;
+        if (subtype)
+            attrs.subtype = subtype;
+        // Merge remaining properties (skip keys already set).
+        if (node.properties) {
+            for (const [k, v] of Object.entries(node.properties)) {
+                if (!(k in attrs))
+                    attrs[k] = v;
+            }
+        }
+        G.addNode(node.id, attrs);
+    }
+    for (const edge of data.edges ?? []) {
+        const attrs = {};
+        attrs.type = edge.type ?? "unknown";
+        attrs.weight =
+            edge.weight ?? EDGE_TYPE_DEFAULTS[attrs.type] ?? 1;
+        if (edge.properties) {
+            for (const [k, v] of Object.entries(edge.properties)) {
+                if (!(k in attrs))
+                    attrs[k] = v;
+            }
+        }
+        G.addEdge(edge.source, edge.target, attrs);
+    }
+    return G;
+}
+// ── Query functions ────────────────────────────────────────────
+/** Dijkstra shortest path between source and target (undirected view). */
+export function findShortestPath(G, source, target) {
+    if (!G.hasNode(source)) {
+        return {
+            found: false,
+            source,
+            target,
+            error: `Node '${source}' not in graph`,
+            path: [],
+            length: null,
+        };
+    }
+    if (!G.hasNode(target)) {
+        return {
+            found: false,
+            source,
+            target,
+            error: `Node '${target}' not in graph`,
+            path: [],
+            length: null,
+        };
+    }
+    const result = dijkstraPath(G, source, target);
+    if (!result) {
+        return { found: false, source, target, path: [], length: null };
+    }
+    const edges = [];
+    for (let i = 0; i < result.path.length - 1; i++) {
+        const u = result.path[i];
+        const v = result.path[i + 1];
+        const edata = undirectedEdgeData(G, u, v);
+        edges.push({
+            from: u,
+            to: v,
+            type: nodeOptStr(edata, "type"),
+            weight: typeof edata.weight === "number" ? edata.weight : undefined,
+        });
+    }
+    return {
+        found: true,
+        source,
+        target,
+        path: result.path,
+        length: result.length,
+        edges,
+    };
+}
+/** All nodes reachable within `depth` hops (undirected neighbourhood, BFS). */
+export function findConnections(G, node, depth = 2) {
+    if (!G.hasNode(node)) {
+        return {
+            node,
+            error: `Node '${node}' not in graph`,
+            connections: [],
+        };
+    }
+    const visited = new Map();
+    let frontier = new Set([node]);
+    for (let d = 1; d <= depth; d++) {
+        const nextFrontier = new Set();
+        for (const n of frontier) {
+            for (const nbr of G.undirectedNeighbors(n)) {
+                if (!visited.has(nbr) && nbr !== node) {
+                    visited.set(nbr, d);
+                    nextFrontier.add(nbr);
+                }
+            }
+        }
+        frontier = nextFrontier;
+    }
+    const connections = [...visited.entries()]
+        .sort((a, b) => a[1] - b[1])
+        .map(([nid, dist]) => {
+        const ndata = G.getNodeData(nid);
+        return {
+            id: nid,
+            type: nodeOptStr(ndata, "type"),
+            label: nodeStr(ndata, "label", nid),
+            distance: dist,
+        };
+    });
+    return { node, depth, total: connections.length, connections };
+}
+/** Connected components (on the undirected projection) as clusters. */
+export function findClusters(G) {
+    const components = connectedComponents(G);
+    // Sort by size descending
+    components.sort((a, b) => b.length - a.length);
+    const clusters = components.map((comp, i) => {
+        const members = [...comp]
+            .sort()
+            .map((nid) => {
+            const ndata = G.getNodeData(nid);
+            return {
+                id: nid,
+                type: nodeOptStr(ndata, "type"),
+                label: nodeStr(ndata, "label", nid),
+            };
+        });
+        return { cluster_id: i, size: comp.length, members };
+    });
+    return { total_clusters: clusters.length, clusters };
+}
+/**
+ * Find paths connecting a trade event to any information-source event
+ * (announcement, report, meeting). Highlights how an insider may have
+ * received material non-public information before executing a trade.
+ */
+export function suspicionAnalysis(G, tradeEventId) {
+    if (!G.hasNode(tradeEventId)) {
+        return {
+            trade_event: tradeEventId,
+            error: `Node '${tradeEventId}' not in graph`,
+            paths: [],
+        };
+    }
+    // Identify information source nodes.
+    const infoSources = [];
+    for (const [nid, attrs] of G.nodesWithData()) {
+        if (attrs.type === "event" &&
+            typeof attrs.subtype === "string" &&
+            INFO_SOURCE_EVENT_SUBTYPES.has(attrs.subtype)) {
+            infoSources.push(nid);
+        }
+    }
+    const paths = [];
+    for (const srcId of infoSources) {
+        const result = dijkstraPath(G, tradeEventId, srcId);
+        if (!result)
+            continue;
+        const edges = [];
+        for (let i = 0; i < result.path.length - 1; i++) {
+            const u = result.path[i];
+            const v = result.path[i + 1];
+            const edata = undirectedEdgeData(G, u, v);
+            edges.push({
+                from: u,
+                to: v,
+                type: nodeOptStr(edata, "type"),
+                weight: typeof edata.weight === "number" ? edata.weight : undefined,
+            });
+        }
+        const srcData = G.getNodeData(srcId);
+        paths.push({
+            info_source: srcId,
+            info_source_label: nodeStr(srcData, "label", srcId),
+            path: result.path,
+            length: result.length,
+            edges,
+        });
+    }
+    // Sort by path length ascending.
+    paths.sort((a, b) => a.length - b.length);
+    return {
+        trade_event: tradeEventId,
+        total_paths: paths.length,
+        paths,
+    };
+}
+// ── Graph statistics ───────────────────────────────────────────
+/** Compute summary statistics for the graph. */
+export function graphStats(G) {
+    // Count node types.
+    const nodeTypes = {};
+    for (const [, attrs] of G.nodesWithData()) {
+        const t = typeof attrs.type === "string" ? attrs.type : "unknown";
+        nodeTypes[t] = (nodeTypes[t] ?? 0) + 1;
+    }
+    // Count edge types.
+    const edgeTypes = {};
+    for (const [, , attrs] of G.edgesWithData()) {
+        const t = typeof attrs.type === "string" ? attrs.type : "unknown";
+        edgeTypes[t] = (edgeTypes[t] ?? 0) + 1;
+    }
+    // Connected components.
+    const components = connectedComponents(G);
+    // Diameter — only meaningful for connected graphs (unweighted BFS).
+    let diameter = null;
+    if (components.length === 1 && G.numberOfNodes() > 1) {
+        try {
+            diameter = computeDiameter(G);
+        }
+        catch {
+            // leave null
+        }
+    }
+    // Betweenness centrality — top-5 nodes.
+    const centrality = betweennessCentrality(G);
+    const topCentral = [...centrality.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5);
+    const keyCentralNodes = topCentral
+        .filter(([, c]) => c > 0)
+        .map(([nid, c]) => {
+        const ndata = G.getNodeData(nid);
+        return {
+            id: nid,
+            label: nodeStr(ndata, "label", nid),
+            type: nodeOptStr(ndata, "type"),
+            centrality: Math.round(c * 10000) / 10000,
+        };
+    });
+    // Density for directed graph: m / (n * (n - 1))
+    const n = G.numberOfNodes();
+    const m = G.numberOfEdges();
+    const density = n > 1
+        ? Math.round((m / (n * (n - 1))) * 1000000) / 1000000
+        : 0;
+    return {
+        total_nodes: n,
+        total_edges: m,
+        node_types: nodeTypes,
+        edge_types: edgeTypes,
+        density,
+        connected_components: components.length,
+        diameter,
+        key_central_nodes: keyCentralNodes,
+    };
+}
+// ── Export functions ────────────────────────────────────────────
+/** Node-link JSON suitable for D3.js force-directed graphs. */
+export function exportJson(G) {
+    const data = {
+        directed: true,
+        multigraph: false,
+        graph: {},
+        nodes: G.nodesWithData().map(([id, attrs]) => ({ id, ...attrs })),
+        links: G.edgesWithData().map(([src, tgt, attrs]) => ({
+            source: src,
+            target: tgt,
+            ...attrs,
+        })),
+    };
+    return JSON.stringify(data, null, 2);
+}
+/** Escape special characters for XML content. */
+function escapeXml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+/** Infer a GraphML type string from a JS value. */
+function graphmlType(value) {
+    if (typeof value === "number") {
+        return Number.isInteger(value) ? "int" : "double";
+    }
+    if (typeof value === "boolean")
+        return "boolean";
+    return "string";
+}
+/** GraphML format for Gephi / yEd. */
+export function exportGraphml(G) {
+    // Collect all unique attribute keys and their types.
+    const nodeAttrKeys = new Map(); // name → graphml type
+    const edgeAttrKeys = new Map();
+    for (const [, attrs] of G.nodesWithData()) {
+        for (const [k, v] of Object.entries(attrs)) {
+            if (!nodeAttrKeys.has(k)) {
+                nodeAttrKeys.set(k, graphmlType(v));
+            }
+        }
+    }
+    for (const [, , attrs] of G.edgesWithData()) {
+        for (const [k, v] of Object.entries(attrs)) {
+            if (!edgeAttrKeys.has(k)) {
+                edgeAttrKeys.set(k, graphmlType(v));
+            }
+        }
+    }
+    // Assign key IDs.
+    const keyDefs = [];
+    const keyMap = new Map(); // "node:name" | "edge:name" → id
+    let keyIdx = 0;
+    for (const [name, type] of nodeAttrKeys) {
+        const id = `d${keyIdx++}`;
+        keyDefs.push({ id, for_: "node", name, type });
+        keyMap.set(`node:${name}`, id);
+    }
+    for (const [name, type] of edgeAttrKeys) {
+        const id = `d${keyIdx++}`;
+        keyDefs.push({ id, for_: "edge", name, type });
+        keyMap.set(`edge:${name}`, id);
+    }
+    // Build XML.
+    const lines = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<graphml xmlns="http://graphml.graphml.org/xmlns"',
+        '  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"',
+        '  xsi:schemaLocation="http://graphml.graphml.org/xmlns http://graphml.graphml.org/xmlns/1.0/graphml.xsd">',
+    ];
+    for (const kd of keyDefs) {
+        lines.push(`  <key id="${kd.id}" for="${kd.for_}" attr.name="${escapeXml(kd.name)}" attr.type="${kd.type}" />`);
+    }
+    lines.push('  <graph id="G" edgedefault="directed">');
+    // Nodes.
+    for (const [id, attrs] of G.nodesWithData()) {
+        lines.push(`    <node id="${escapeXml(id)}">`);
+        for (const [k, v] of Object.entries(attrs)) {
+            const kid = keyMap.get(`node:${k}`);
+            if (kid != null && v != null) {
+                const sv = typeof v === "object" ? JSON.stringify(v) : String(v);
+                lines.push(`      <data key="${kid}">${escapeXml(sv)}</data>`);
+            }
+        }
+        lines.push("    </node>");
+    }
+    // Edges.
+    let edgeIdx = 0;
+    for (const [src, tgt, attrs] of G.edgesWithData()) {
+        lines.push(`    <edge id="e${edgeIdx++}" source="${escapeXml(src)}" target="${escapeXml(tgt)}">`);
+        for (const [k, v] of Object.entries(attrs)) {
+            const kid = keyMap.get(`edge:${k}`);
+            if (kid != null && v != null) {
+                const sv = typeof v === "object" ? JSON.stringify(v) : String(v);
+                lines.push(`      <data key="${kid}">${escapeXml(sv)}</data>`);
+            }
+        }
+        lines.push("    </edge>");
+    }
+    lines.push("  </graph>");
+    lines.push("</graphml>");
+    return lines.join("\n");
+}
+/** Map of export format names to their exporter functions. */
+export const EXPORTERS = {
+    json: exportJson,
+    graphml: exportGraphml,
+};
+//# sourceMappingURL=insider-graph.js.map