@zvk/graphs 0.1.1 → 0.1.3

package/dist/algorithms.js

@@ -38,6 +38,180 @@ export function getGraphDegrees(graph) {
     }
     return degrees;
 }
+function graphModelFields(options) {
+    return {
+        ...(options.id !== undefined ? { id: options.id } : {}),
+        title: options.title,
+        ...(options.description !== undefined ? { description: options.description } : {}),
+        ...(options.direction !== undefined ? { direction: options.direction } : {}),
+        ...(options.groups !== undefined ? { groups: options.groups } : {})
+    };
+}
+function addGraphInteropNode(nodes, nodeIds, nodeId, getNodeLabel) {
+    if (nodeIds.has(nodeId)) {
+        return;
+    }
+    const index = nodes.length;
+    nodeIds.add(nodeId);
+    nodes.push({
+        id: nodeId,
+        label: getNodeLabel?.(nodeId, { nodeId, index }) ?? nodeId
+    });
+}
+function uniqueGeneratedEdgeId(baseId, edgeIds) {
+    if (!edgeIds.has(baseId)) {
+        edgeIds.add(baseId);
+        return baseId;
+    }
+    let nextIndex = 2;
+    let nextId = `${baseId}-${nextIndex}`;
+    while (edgeIds.has(nextId)) {
+        nextIndex += 1;
+        nextId = `${baseId}-${nextIndex}`;
+    }
+    edgeIds.add(nextId);
+    return nextId;
+}
+export function graphFromEdgeList(edgeList, options) {
+    const nodes = [];
+    const nodeIds = new Set();
+    const edgeIds = new Set();
+    for (const node of options.nodes ?? []) {
+        if (!nodeIds.has(node.id)) {
+            nodeIds.add(node.id);
+            nodes.push(node);
+        }
+    }
+    for (const entry of edgeList) {
+        addGraphInteropNode(nodes, nodeIds, entry.source, options.getNodeLabel);
+        addGraphInteropNode(nodes, nodeIds, entry.target, options.getNodeLabel);
+    }
+    const edges = edgeList.map((entry, index) => {
+        const { id: explicitId, ...edge } = entry;
+        const proposedId = explicitId ?? `${entry.source}-${entry.target}`;
+        const customId = explicitId ?? options.getEdgeId?.(entry, { entry, index, proposedId });
+        const id = customId ?? uniqueGeneratedEdgeId(proposedId, edgeIds);
+        if (customId !== undefined) {
+            edgeIds.add(customId);
+        }
+        return { id, ...edge };
+    });
+    return {
+        ...graphModelFields(options),
+        nodes,
+        edges
+    };
+}
+export function graphToEdgeList(graph) {
+    return graph.edges.map((edge) => ({ ...edge }));
+}
+export function graphToAdjacencyList(graph) {
+    const targetsBySource = new Map();
+    for (const node of graph.nodes) {
+        targetsBySource.set(node.id, []);
+    }
+    for (const edge of graph.edges) {
+        targetsBySource.set(edge.source, [...(targetsBySource.get(edge.source) ?? []), edge.target]);
+    }
+    return [...targetsBySource.entries()].map(([source, targets]) => ({ source, targets }));
+}
+export function graphFromAdjacencyList(adjacencyList, options) {
+    const nodes = [];
+    const nodeIds = new Set();
+    const edgeIds = new Set();
+    const edges = [];
+    for (const node of options.nodes ?? []) {
+        if (!nodeIds.has(node.id)) {
+            nodeIds.add(node.id);
+            nodes.push(node);
+        }
+    }
+    for (const { source, targets } of adjacencyList) {
+        addGraphInteropNode(nodes, nodeIds, source, options.getNodeLabel);
+        for (const target of targets) {
+            addGraphInteropNode(nodes, nodeIds, target, options.getNodeLabel);
+            edges.push({
+                id: uniqueGeneratedEdgeId(`${source}-${target}`, edgeIds),
+                source,
+                target
+            });
+        }
+    }
+    return {
+        ...graphModelFields(options),
+        nodes,
+        edges
+    };
+}
+export function pickGraphSubgraph(graph, options) {
+    const selectedNodeIds = new Set(options.nodeIds);
+    const includeConnectedEdges = options.includeConnectedEdges ?? true;
+    const includeDanglingEdges = options.includeDanglingEdges ?? false;
+    const nodes = graph.nodes.filter((node) => selectedNodeIds.has(node.id));
+    const edges = graph.edges.filter((edge) => {
+        const hasSource = selectedNodeIds.has(edge.source);
+        const hasTarget = selectedNodeIds.has(edge.target);
+        if (includeDanglingEdges) {
+            return hasSource || hasTarget;
+        }
+        if (!includeConnectedEdges) {
+            return false;
+        }
+        return hasSource && hasTarget;
+    });
+    return { ...graph, nodes, edges };
+}
+function adjacentNodeId(edge, nodeId, direction) {
+    if (direction === "incoming") {
+        return edge.source;
+    }
+    if (direction === "outgoing") {
+        return edge.target;
+    }
+    return edge.source === nodeId ? edge.target : edge.source;
+}
+export function getGraphNeighborhood(graph, options) {
+    const index = createGraphIndex(graph);
+    const maxDepth = Math.max(0, Math.floor(options.maxDepth));
+    const direction = options.direction ?? "outgoing";
+    if (!index.nodeById.has(options.rootId)) {
+        return { ...graph, nodes: [], edges: [] };
+    }
+    const selectedNodeIds = new Set([options.rootId]);
+    const queue = [{ nodeId: options.rootId, depth: 0 }];
+    for (let cursor = 0; cursor < queue.length; cursor += 1) {
+        const item = queue[cursor];
+        if (!item || item.depth >= maxDepth) {
+            continue;
+        }
+        const edges = direction === "both"
+            ? [...(index.outgoingByNodeId.get(item.nodeId) ?? []), ...(index.incomingByNodeId.get(item.nodeId) ?? [])]
+            : direction === "incoming"
+                ? (index.incomingByNodeId.get(item.nodeId) ?? [])
+                : (index.outgoingByNodeId.get(item.nodeId) ?? []);
+        for (const edge of edges) {
+            const nextNodeId = adjacentNodeId(edge, item.nodeId, direction);
+            if (selectedNodeIds.has(nextNodeId) || !index.nodeById.has(nextNodeId)) {
+                continue;
+            }
+            selectedNodeIds.add(nextNodeId);
+            queue.push({ nodeId: nextNodeId, depth: item.depth + 1 });
+        }
+    }
+    return pickGraphSubgraph(graph, { nodeIds: [...selectedNodeIds] });
+}
+export function mapGraphNodes(graph, mapper) {
+    return {
+        ...graph,
+        nodes: graph.nodes.map((node, index) => mapper(node, { graph, index }))
+    };
+}
+export function mapGraphEdges(graph, mapper) {
+    return {
+        ...graph,
+        edges: graph.edges.map((edge, index) => mapper(edge, { graph, index }))
+    };
+}
 export function detectGraphCycle(graph) {
     const index = createGraphIndex(graph);
     const visiting = new Set();
@@ -142,6 +316,119 @@ export function getReachableNodeIds(graph, startId) {
     }
     return reachable;
 }
+function reachableSet(graph, startId, omittedEdgeId) {
+    const index = createGraphIndex(graph);
+    const visited = new Set();
+    const queue = [];
+    if (!index.nodeById.has(startId)) {
+        return visited;
+    }
+    visited.add(startId);
+    queue.push(startId);
+    for (let cursor = 0; cursor < queue.length; cursor += 1) {
+        const nodeId = queue[cursor];
+        if (!nodeId) {
+            continue;
+        }
+        for (const edge of index.outgoingByNodeId.get(nodeId) ?? []) {
+            if (edge.id === omittedEdgeId || visited.has(edge.target) || !index.nodeById.has(edge.target)) {
+                continue;
+            }
+            visited.add(edge.target);
+            queue.push(edge.target);
+        }
+    }
+    return visited;
+}
+export function getUnreachableNodeIds(graph, startId) {
+    const reachable = reachableSet(graph, startId);
+    return graph.nodes.filter((node) => node.id !== startId && !reachable.has(node.id)).map((node) => node.id);
+}
+export function getIsolatedNodeIds(graph) {
+    const degrees = getGraphDegrees(graph);
+    return graph.nodes.filter((node) => degrees[node.id]?.total === 0).map((node) => node.id);
+}
+export function getShortestPath(graph, sourceId, targetId) {
+    const index = createGraphIndex(graph);
+    if (!index.nodeById.has(sourceId) || !index.nodeById.has(targetId)) {
+        return null;
+    }
+    if (sourceId === targetId) {
+        return [sourceId];
+    }
+    const visited = new Set([sourceId]);
+    const queue = [[sourceId]];
+    for (let cursor = 0; cursor < queue.length; cursor += 1) {
+        const path = queue[cursor];
+        const nodeId = path?.at(-1);
+        if (!path || !nodeId) {
+            continue;
+        }
+        for (const edge of index.outgoingByNodeId.get(nodeId) ?? []) {
+            if (visited.has(edge.target) || !index.nodeById.has(edge.target)) {
+                continue;
+            }
+            const nextPath = [...path, edge.target];
+            if (edge.target === targetId) {
+                return nextPath;
+            }
+            visited.add(edge.target);
+            queue.push(nextPath);
+        }
+    }
+    return null;
+}
+export function getStronglyConnectedComponents(graph) {
+    const assigned = new Set();
+    const reachableByNode = new Map();
+    const components = [];
+    for (const node of graph.nodes) {
+        reachableByNode.set(node.id, reachableSet(graph, node.id));
+    }
+    for (const node of graph.nodes) {
+        if (assigned.has(node.id)) {
+            continue;
+        }
+        const nodeReachable = reachableByNode.get(node.id) ?? new Set();
+        const component = graph.nodes
+            .filter((candidate) => {
+            if (assigned.has(candidate.id)) {
+                return false;
+            }
+            const candidateReachable = reachableByNode.get(candidate.id) ?? new Set();
+            return nodeReachable.has(candidate.id) && candidateReachable.has(node.id);
+        })
+            .map((candidate) => candidate.id);
+        for (const componentNodeId of component) {
+            assigned.add(componentNodeId);
+        }
+        components.push(component);
+    }
+    return components;
+}
+export function getTransitiveReductionEdges(graph) {
+    const cycle = detectGraphCycle(graph);
+    if (cycle) {
+        return {
+            edges: [],
+            diagnostics: [
+                {
+                    code: "cycle-detected",
+                    severity: "error",
+                    message: `Transitive reduction requires an acyclic graph; found ${cycle.join(" -> ")}.`
+                }
+            ]
+        };
+    }
+    const index = createGraphIndex(graph);
+    const edges = graph.edges.filter((edge) => {
+        if (!index.nodeById.has(edge.source) || !index.nodeById.has(edge.target)) {
+            return true;
+        }
+        return !reachableSet(graph, edge.source, edge.id).has(edge.target);
+    });
+    return { edges, diagnostics: [] };
+}
 export function getWeaklyConnectedComponents(graph) {
     const index = createGraphIndex(graph);
     const visited = new Set();

package/dist/diagnostics.d.ts

@@ -1,19 +1,91 @@
 import type { GraphEdge, GraphId, GraphModel, GraphNode } from "./model.js";
-export type GraphDiagnosticCode = "missing-graph-title" | "duplicate-node-id" | "duplicate-edge-id" | "dangling-edge-source" | "dangling-edge-target" | "self-loop" | "cycle-detected" | "missing-node-label" | "missing-edge-label" | "missing-node-position" | "tree-multiple-roots" | "tree-multiple-parents" | "tree-disconnected";
-export type GraphDiagnosticSeverity = "error" | "warning";
+export type GraphDiagnosticCode = "missing-graph-title" | "duplicate-node-id" | "duplicate-edge-id" | "duplicate-group-id" | "dangling-edge-source" | "dangling-edge-target" | "unknown-node-group" | "self-loop" | "cycle-detected" | "missing-group-label" | "missing-node-label" | "missing-edge-label" | "missing-node-description" | "missing-edge-description" | "missing-graph-description" | "duplicate-node-label" | "duplicate-edge-label" | "fallback-disabled" | "missing-node-position" | "missing-node-size" | "duplicate-node-position" | "large-graph" | "dense-graph" | "large-fallback-content" | "large-visible-label-count" | "high-route-complexity" | "large-metadata-summary" | "parallel-edge" | "edge-label-overlap-risk" | "empty-group" | "tree-multiple-roots" | "tree-multiple-parents" | "tree-disconnected";
+export type GraphDiagnosticSeverity = "error" | "warning" | "info";
+export type GraphDiagnosticCategory = "accessibility" | "structure" | "layout" | "performance" | "fallback" | "tree";
+export type GraphDiagnosticDetails = Readonly<Record<string, string | number | boolean | null>>;
+export interface GraphDiagnosticFix {
+    readonly title: string;
+    readonly description?: string;
+    readonly target?: "graph" | "group" | "node" | "edge" | "layout";
+}
 export interface GraphDiagnostic {
     readonly code: GraphDiagnosticCode;
     readonly severity: GraphDiagnosticSeverity;
     readonly message: string;
     readonly nodeId?: GraphId;
     readonly edgeId?: GraphId;
+    readonly category?: GraphDiagnosticCategory;
+    readonly details?: GraphDiagnosticDetails;
+    readonly fix?: GraphDiagnosticFix;
 }
 export interface ValidateGraphOptions {
     readonly allowSelfLoops?: boolean;
     readonly requireEdgeLabels?: boolean;
+    readonly requireGraphDescription?: boolean;
+    readonly auditAccessibility?: boolean;
+    readonly warnDuplicateLabels?: boolean;
+    readonly fallbackMode?: "list" | "tree" | "none";
 }
 export declare function validateGraph(graph: GraphModel, options?: ValidateGraphOptions): GraphDiagnostic[];
 export declare function hasGraphErrors(diagnostics: readonly GraphDiagnostic[]): boolean;
+export type GraphDiagnosticGroupBy = "severity" | "code" | "category";
+export interface GraphDiagnosticFilter {
+    readonly severity?: GraphDiagnosticSeverity;
+    readonly code?: GraphDiagnosticCode;
+    readonly category?: GraphDiagnosticCategory;
+    readonly nodeId?: GraphId;
+    readonly edgeId?: GraphId;
+}
+export declare function countGraphDiagnostics(diagnostics: readonly GraphDiagnostic[], groupBy: GraphDiagnosticGroupBy): Record<string, number>;
+export declare function groupGraphDiagnostics(diagnostics: readonly GraphDiagnostic[], groupBy: GraphDiagnosticGroupBy): Record<string, readonly GraphDiagnostic[]>;
+export declare function filterGraphDiagnostics(diagnostics: readonly GraphDiagnostic[], filter: GraphDiagnosticFilter): readonly GraphDiagnostic[];
+export declare function getGraphDiagnosticFixes(diagnostics: readonly GraphDiagnostic[]): readonly GraphDiagnosticFix[];
 export declare function formatGraphDiagnostic(diagnosticEntry: GraphDiagnostic): string;
 export declare function getNodeLabel(node: GraphNode): string;
 export declare function getEdgeAccessibleLabel(edge: GraphEdge, graph: GraphModel): string;
+export interface ValidateGraphLayoutOptions {
+    readonly warnFallbackRowsAt?: number;
+    readonly warnLargeGraphAt?: number;
+    readonly warnDenseGraphAt?: number;
+    readonly warnMetadataSummariesAt?: number;
+    readonly warnMissingSizes?: boolean;
+    readonly warnDuplicatePositions?: boolean;
+    readonly warnEdgeLabelOverlaps?: boolean;
+    readonly warnParallelEdges?: boolean;
+    readonly warnRoutePointsAt?: number;
+    readonly warnSelfLoops?: boolean;
+    readonly warnVisibleLabelsAt?: number;
+}
+export interface GraphRenderCostThresholdOptions {
+    readonly warnFallbackRowsAt?: number;
+    readonly warnMetadataSummariesAt?: number;
+    readonly warnRoutePointsAt?: number;
+    readonly warnVisibleLabelsAt?: number;
+}
+export interface GraphRenderCostEstimate {
+    readonly complexRouteCount: number;
+    readonly edgeCount: number;
+    readonly fallbackRowCount: number;
+    readonly groupCount: number;
+    readonly metadataSummaryCount: number;
+    readonly nodeCount: number;
+    readonly roughSvgElementCount: number;
+    readonly routedEdgeCount: number;
+    readonly routePointCount: number;
+    readonly visibleLabelCount: number;
+}
+export interface GraphHealthReportOptions extends ValidateGraphOptions, ValidateGraphLayoutOptions {
+}
+export interface GraphHealthReport {
+    readonly diagnostics: readonly GraphDiagnostic[];
+    readonly errors: readonly GraphDiagnostic[];
+    readonly warnings: readonly GraphDiagnostic[];
+    readonly info: readonly GraphDiagnostic[];
+    readonly countsByCode: Readonly<Record<string, number>>;
+    readonly countsByCategory: Readonly<Record<string, number>>;
+    readonly canRenderStaticSvg: boolean;
+    readonly shouldRenderFallback: boolean;
+}
+export declare function estimateGraphRenderCost(graph: GraphModel): GraphRenderCostEstimate;
+export declare function validateGraphLayout(graph: GraphModel, options?: ValidateGraphLayoutOptions): GraphDiagnostic[];
+export declare function createGraphHealthReport(graph: GraphModel, options?: GraphHealthReportOptions): GraphHealthReport;