pm-graph 2026.6.2 → 2026.6.7

package/dist/index.js

@@ -4,7 +4,7 @@ import { writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 const execFileAsync = promisify(execFile);
-const EXTENSION_VERSION = "0.1.4";
+const EXTENSION_VERSION = "0.2.0";
 // ---------------------------------------------------------------------------
 // Error contract
 // ---------------------------------------------------------------------------
@@ -412,6 +412,102 @@ function loadGraphFromPath(pmRoot) {
     const items = fetchItemsViaPath(pmRoot);
     return graphFromItems(items, workspaceFromPmRoot(pmRoot), new Map());
 }
+/**
+ * Build a Graph for a CommandContext via a single
+ * `pm list-all --json --include-body` call from the workspace cwd. The
+ * `--include-body` payload already carries dependencies/blocked_by/parent/tags,
+ * so no per-item `pm deps` round-trips are needed. Used by the offline
+ * analytics commands (analyze/cycles/path/critical-path).
+ */
+function loadGraphForContext(context) {
+    const workspace = getWorkspace(context);
+    const result = spawnSync("pm", ["list-all", "--json", "--include-body"], { cwd: workspace, encoding: "utf-8", maxBuffer: 20 * 1024 * 1024 });
+    if (result.error || result.status !== 0) {
+        throw new CommandError(`Failed to fetch pm items (exit ${result.status ?? "unknown"}): ${result.stderr?.trim() || result.error?.message || "no output"}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch (err) {
+        throw new CommandError(`Failed to parse pm list-all output as JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return graphFromItems(parsed.items ?? [], workspace, new Map());
+}
+/**
+ * Parse the shared analytics flags (--json, --include-closed, --root, --depth)
+ * and collect remaining positional arguments. Throws a USAGE CommandError on a
+ * malformed --depth or a value-less --root/--depth.
+ */
+function parseAnalyticsFlags(args) {
+    const flags = { json: false, includeClosed: false, positionals: [] };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json") {
+            flags.json = true;
+        }
+        else if (arg === "--include-closed") {
+            flags.includeClosed = true;
+        }
+        else if (arg === "--root") {
+            const value = args[++i];
+            if (value === undefined)
+                throw new CommandError("--root requires an item id.", EXIT_CODE.USAGE);
+            flags.root = value;
+        }
+        else if (arg.startsWith("--root=")) {
+            flags.root = arg.slice("--root=".length);
+        }
+        else if (arg === "--depth") {
+            const value = args[++i];
+            if (value === undefined)
+                throw new CommandError("--depth requires an integer.", EXIT_CODE.USAGE);
+            const parsed = parseInt(value, 10);
+            if (Number.isNaN(parsed) || parsed < 0) {
+                throw new CommandError(`Invalid --depth "${value}" (expected a non-negative integer).`, EXIT_CODE.USAGE);
+            }
+            flags.depth = parsed;
+        }
+        else if (arg.startsWith("--depth=")) {
+            const value = arg.slice("--depth=".length);
+            const parsed = parseInt(value, 10);
+            if (Number.isNaN(parsed) || parsed < 0) {
+                throw new CommandError(`Invalid --depth "${value}" (expected a non-negative integer).`, EXIT_CODE.USAGE);
+            }
+            flags.depth = parsed;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            // handled separately by hasHelpFlag
+        }
+        else if (arg.startsWith("--")) {
+            // ignore unknown flags rather than misparse them as positionals
+        }
+        else {
+            flags.positionals.push(arg);
+        }
+    }
+    return flags;
+}
+/**
+ * Load a graph for a context and apply the shared analytics shaping
+ * (structural edges only is enforced downstream; here we only honor
+ * --include-closed and an optional --root/--depth neighborhood). Throws
+ * NOT_FOUND when --root is absent from the workspace.
+ */
+function shapedAnalyticsGraph(context, flags) {
+    const full = loadGraphForContext(context);
+    if (flags.root && !full.nodes.some((n) => n.id === flags.root)) {
+        throw new CommandError(`--root node "${flags.root}" was not found in the workspace graph.`, EXIT_CODE.NOT_FOUND);
+    }
+    // Restrict to structural edges so neighborhood shaping follows dependencies,
+    // not facet/tag links. The analytics functions also re-filter defensively.
+    return shapeGraph(full, {
+        edges: "deps",
+        includeClosed: flags.includeClosed,
+        rootId: flags.root,
+        depth: flags.depth,
+    });
+}
 // ---------------------------------------------------------------------------
 // Cypher generation (for export)
 // ---------------------------------------------------------------------------
@@ -590,6 +686,85 @@ function renderJsonGraph(graph) {
     };
     return JSON.stringify(doc, null, 2);
 }
+/** Escape a string for XML text/attribute content. */
+function xmlEscape(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+/**
+ * Render a valid GraphML XML document (consumable by yEd / Gephi / NetworkX).
+ * Declares string keys for node title/type/status/labels and edge type, then
+ * emits one <node> per graph node and one <edge> per relationship.
+ */
+export function renderGraphml(graph) {
+    const lines = [];
+    lines.push('<?xml version="1.0" encoding="UTF-8"?>');
+    lines.push('<graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">');
+    lines.push('  <key id="title" for="node" attr.name="title" attr.type="string"/>');
+    lines.push('  <key id="type" for="node" attr.name="type" attr.type="string"/>');
+    lines.push('  <key id="status" for="node" attr.name="status" attr.type="string"/>');
+    lines.push('  <key id="labels" for="node" attr.name="labels" attr.type="string"/>');
+    lines.push('  <key id="reltype" for="edge" attr.name="reltype" attr.type="string"/>');
+    lines.push('  <graph id="pm-graph" edgedefault="directed">');
+    for (const node of graph.nodes) {
+        const title = typeof node.properties.title === "string" && node.properties.title
+            ? String(node.properties.title)
+            : node.id;
+        const type = typeof node.properties.type === "string" ? node.properties.type : "";
+        const status = typeof node.properties.status === "string" ? node.properties.status : "";
+        lines.push(`    <node id="${xmlEscape(node.id)}">`);
+        lines.push(`      <data key="title">${xmlEscape(title)}</data>`);
+        if (type)
+            lines.push(`      <data key="type">${xmlEscape(type)}</data>`);
+        if (status)
+            lines.push(`      <data key="status">${xmlEscape(status)}</data>`);
+        lines.push(`      <data key="labels">${xmlEscape(node.labels.join(" "))}</data>`);
+        lines.push("    </node>");
+    }
+    graph.relationships.forEach((rel, index) => {
+        lines.push(`    <edge id="e${index}" source="${xmlEscape(rel.from)}" target="${xmlEscape(rel.to)}">`);
+        lines.push(`      <data key="reltype">${xmlEscape(rel.type)}</data>`);
+        lines.push("    </edge>");
+    });
+    lines.push("  </graph>");
+    lines.push("</graphml>");
+    return lines.join("\n");
+}
+/** Sanitise an id for use as a PlantUML alias (alphanumeric/underscore). */
+function plantumlAlias(id) {
+    return "n_" + id.replace(/[^A-Za-z0-9_]/g, "_");
+}
+/** Escape a string for a PlantUML double-quoted label. */
+function plantumlLabel(s) {
+    return s.replace(/"/g, "'").replace(/\n/g, " ").trim();
+}
+/**
+ * Render a PlantUML object diagram (`@startuml`…`@enduml`) with one object per
+ * node and one arrow per relationship, the relationship type as the arrow
+ * label. Renders with PlantUML / Structurizr / many docs toolchains.
+ */
+export function renderPlantuml(graph) {
+    const lines = ["@startuml", "left to right direction"];
+    for (const node of graph.nodes) {
+        const title = typeof node.properties.title === "string" && node.properties.title
+            ? String(node.properties.title)
+            : node.id;
+        const status = typeof node.properties.status === "string" ? node.properties.status : "";
+        const label = status ? `${title} [${node.id}] (${status})` : `${title} [${node.id}]`;
+        lines.push(`object "${plantumlLabel(label)}" as ${plantumlAlias(node.id)}`);
+    }
+    if (graph.relationships.length > 0)
+        lines.push("");
+    for (const rel of graph.relationships) {
+        lines.push(`${plantumlAlias(rel.from)} --> ${plantumlAlias(rel.to)} : ${plantumlLabel(rel.type)}`);
+    }
+    lines.push("@enduml");
+    return lines.join("\n");
+}
 function renderExport(format, graph) {
     switch (format) {
         case "cypher":
@@ -602,6 +777,10 @@ function renderExport(format, graph) {
             return renderDot(graph);
         case "json":
             return renderJsonGraph(graph);
+        case "graphml":
+            return renderGraphml(graph);
+        case "plantuml":
+            return renderPlantuml(graph);
     }
 }
 function readExportOption(options, ...keys) {
@@ -612,6 +791,452 @@ function readExportOption(options, ...keys) {
     }
     return undefined;
 }
+// ---------------------------------------------------------------------------
+// Graph analytics (offline — operate on STRUCTURAL edges only)
+// ---------------------------------------------------------------------------
+// Analytics treat the workspace as a directed dependency graph. Only
+// *structural* edges (BLOCKED_BY + CHILD_OF + dependency edges such as BLOCKS /
+// RELATED) participate. Facet edges (HAS_TYPE/HAS_STATUS/ASSIGNED_TO/IN_SPRINT/
+// IN_RELEASE) and tag edges (TAGGED_WITH) are metadata, not dependencies — if
+// they were included, every item sharing a status or tag would appear linked,
+// producing meaningless cycles, components, and centrality. Filtering to
+// structural edges keeps cycle/path/critical-path results semantically honest.
+function isStructuralEdge(type) {
+    return type !== TAG_REL_TYPE && !FACET_REL_TYPES.has(type);
+}
+/** Item-only node ids (drop facet/tag/external nodes that are not PmItems). */
+function itemNodeIds(graph) {
+    const ids = new Set();
+    for (const node of graph.nodes) {
+        if (node.labels.includes("PmItem"))
+            ids.add(node.id);
+    }
+    return ids;
+}
+/** Extract the directed structural edges of a graph, between item nodes only. */
+function structuralEdges(graph) {
+    const items = itemNodeIds(graph);
+    const seen = new Set();
+    const edges = [];
+    for (const rel of graph.relationships) {
+        if (!isStructuralEdge(rel.type))
+            continue;
+        if (!items.has(rel.from) || !items.has(rel.to))
+            continue;
+        const key = `${rel.from}->${rel.to}:${rel.type}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        edges.push({ from: rel.from, to: rel.to, type: rel.type });
+    }
+    return edges;
+}
+/** Directed adjacency (from -> [to]) over a set of edges. */
+function buildAdjacency(edges) {
+    const adjacency = new Map();
+    for (const e of edges) {
+        const list = adjacency.get(e.from) ?? [];
+        if (!list.includes(e.to))
+            list.push(e.to);
+        adjacency.set(e.from, list);
+    }
+    return adjacency;
+}
+/**
+ * Detect all elementary directed cycles among structural edges using an
+ * iterative DFS with a recursion stack. Returns each cycle as an ordered id
+ * path whose first and last ids are equal (e.g. [E, F, E]). Cycles are
+ * de-duplicated by their canonical rotation so A->B->A and B->A->B collapse.
+ */
+export function findCycles(nodes, edges) {
+    const adjacency = buildAdjacency(edges);
+    const cycles = [];
+    const seenCanonical = new Set();
+    const canonical = (cycle) => {
+        // cycle excludes the repeated closing node; rotate to start at min id.
+        const core = cycle.slice(0, -1);
+        let minIdx = 0;
+        for (let i = 1; i < core.length; i++) {
+            if (core[i] < core[minIdx])
+                minIdx = i;
+        }
+        const rotated = [...core.slice(minIdx), ...core.slice(0, minIdx)];
+        return rotated.join("->");
+    };
+    for (const start of nodes) {
+        // Iterative DFS carrying the current path; detect back-edges to a node
+        // already on the path (a cycle), or revisits handled via path membership.
+        const stack = [
+            { node: start, path: [start], onPath: new Set([start]) },
+        ];
+        while (stack.length > 0) {
+            const { node, path: currentPath, onPath } = stack.pop();
+            for (const next of adjacency.get(node) ?? []) {
+                if (next === start && currentPath.length >= 1) {
+                    // Closed a cycle back to the start node.
+                    const cycle = [...currentPath, start];
+                    const key = canonical(cycle);
+                    if (!seenCanonical.has(key)) {
+                        seenCanonical.add(key);
+                        cycles.push(cycle);
+                    }
+                    continue;
+                }
+                // Only extend along nodes greater than start to avoid re-finding
+                // cycles rooted at smaller ids, and never revisit a node on this path.
+                if (next < start || onPath.has(next))
+                    continue;
+                const nextOnPath = new Set(onPath);
+                nextOnPath.add(next);
+                stack.push({ node: next, path: [...currentPath, next], onPath: nextOnPath });
+            }
+        }
+    }
+    return cycles;
+}
+/**
+ * Shortest directed path from `from` to `to` over structural edges (BFS).
+ * Returns the ordered id path (inclusive of both endpoints) or null if no path
+ * exists. Returns [from] when from === to.
+ */
+export function shortestPath(edges, from, to) {
+    if (from === to)
+        return [from];
+    const adjacency = buildAdjacency(edges);
+    const visited = new Set([from]);
+    const queue = [from];
+    const prev = new Map();
+    while (queue.length > 0) {
+        const node = queue.shift();
+        for (const next of adjacency.get(node) ?? []) {
+            if (visited.has(next))
+                continue;
+            visited.add(next);
+            prev.set(next, node);
+            if (next === to) {
+                const path = [to];
+                let cur = to;
+                while (prev.has(cur)) {
+                    cur = prev.get(cur);
+                    path.unshift(cur);
+                }
+                return path;
+            }
+            queue.push(next);
+        }
+    }
+    return null;
+}
+/**
+ * Longest dependency chain (critical path) over structural edges. Uses a
+ * memoised DFS that is safe on cyclic graphs (nodes on the active recursion
+ * stack are skipped, so a cycle cannot inflate the chain infinitely). Returns
+ * the ordered id list of the longest simple chain found.
+ */
+export function longestChain(nodes, edges) {
+    const adjacency = buildAdjacency(edges);
+    const memo = new Map();
+    const onStack = new Set();
+    const dfs = (node) => {
+        const cached = memo.get(node);
+        if (cached)
+            return cached;
+        onStack.add(node);
+        let best = [];
+        for (const next of adjacency.get(node) ?? []) {
+            if (onStack.has(next))
+                continue; // skip back-edges (cycle safety)
+            const candidate = dfs(next);
+            if (candidate.length > best.length)
+                best = candidate;
+        }
+        onStack.delete(node);
+        const result = [node, ...best];
+        memo.set(node, result);
+        return result;
+    };
+    let longest = [];
+    for (const node of nodes) {
+        const chain = dfs(node);
+        if (chain.length > longest.length)
+            longest = chain;
+    }
+    return longest;
+}
+/**
+ * Topological execution order over structural edges using Kahn's algorithm.
+ *
+ * Edges point from an item to its blocker/dependency (e.g. B --BLOCKED_BY--> A
+ * means "B is blocked by A", so A must be done before B). A valid execution
+ * order therefore lists a node only after every node it points to. We compute
+ * that order by treating out-edges as prerequisites: repeatedly emit nodes whose
+ * out-degree (unsatisfied prerequisites) has dropped to zero.
+ *
+ * Returns `{ order, cycleNodes }`. When the graph is acyclic, `order` contains
+ * every node and `cycleNodes` is empty. When a cycle exists, the nodes that
+ * could not be ordered are returned in `cycleNodes` (and `order` holds the
+ * resolvable prefix). Ties are broken by ascending id for deterministic output.
+ */
+export function topoSort(nodes, edges) {
+    // Prerequisites of a node = the distinct nodes it points to (its blockers).
+    const prereqs = new Map();
+    // Dependents: for each prerequisite, which nodes wait on it.
+    const dependents = new Map();
+    const nodeSet = new Set(nodes);
+    for (const id of nodes)
+        prereqs.set(id, new Set());
+    for (const e of edges) {
+        if (!nodeSet.has(e.from) || !nodeSet.has(e.to))
+            continue;
+        if (e.from === e.to)
+            continue; // self-loop is its own cycle, handled below
+        const set = prereqs.get(e.from);
+        if (!set.has(e.to)) {
+            set.add(e.to);
+            (dependents.get(e.to) ?? dependents.set(e.to, []).get(e.to)).push(e.from);
+        }
+    }
+    // Seed the ready queue with nodes that have no prerequisites.
+    const ready = nodes.filter((id) => prereqs.get(id).size === 0).sort();
+    const order = [];
+    const remaining = new Map();
+    for (const id of nodes)
+        remaining.set(id, prereqs.get(id).size);
+    while (ready.length > 0) {
+        const id = ready.shift();
+        order.push(id);
+        let inserted = false;
+        for (const dep of dependents.get(id) ?? []) {
+            const left = (remaining.get(dep) ?? 0) - 1;
+            remaining.set(dep, left);
+            if (left === 0) {
+                // Insert keeping the ready queue sorted for deterministic output.
+                const idx = ready.findIndex((x) => x > dep);
+                if (idx === -1)
+                    ready.push(dep);
+                else
+                    ready.splice(idx, 0, dep);
+                inserted = true;
+            }
+        }
+        void inserted;
+    }
+    // Any node never emitted is part of (or downstream of) a cycle.
+    const ordered = new Set(order);
+    const cycleNodes = nodes.filter((id) => !ordered.has(id)).sort();
+    return { order, cycleNodes };
+}
+/**
+ * Reverse-reachable set from `start` over structural edges: every node that can
+ * reach `start` by following edge direction (i.e. everything transitively
+ * blocked-by / downstream of `start`). With edges pointing item -> blocker, the
+ * dependents of X are the nodes with an edge INTO X, so we walk edges backwards
+ * via a reverse adjacency (BFS). Excludes `start` itself. Result is sorted.
+ */
+export function reverseReachable(edges, start) {
+    const reverse = new Map();
+    for (const e of edges) {
+        (reverse.get(e.to) ?? reverse.set(e.to, []).get(e.to)).push(e.from);
+    }
+    const seen = new Set();
+    const queue = [start];
+    while (queue.length > 0) {
+        const node = queue.shift();
+        for (const prev of reverse.get(node) ?? []) {
+            if (prev === start || seen.has(prev))
+                continue;
+            seen.add(prev);
+            queue.push(prev);
+        }
+    }
+    return [...seen].sort();
+}
+/**
+ * Longest-path depth per node: the number of edges on the longest directed
+ * structural path STARTING at the node (its distance to a leaf along blocker
+ * edges). A leaf (no outgoing edge) has depth 0. Cycle-safe: nodes on the active
+ * recursion stack are skipped so a cycle cannot inflate depth infinitely. This
+ * is the "longest path from any root" metric expressed per node, since the
+ * deepest node is exactly the far end of the critical path.
+ */
+export function dependencyDepths(nodes, edges) {
+    const adjacency = buildAdjacency(edges);
+    const memo = new Map();
+    const onStack = new Set();
+    const dfs = (node) => {
+        const cached = memo.get(node);
+        if (cached !== undefined)
+            return cached;
+        onStack.add(node);
+        let best = 0;
+        for (const next of adjacency.get(node) ?? []) {
+            if (onStack.has(next))
+                continue; // cycle safety
+            const candidate = 1 + dfs(next);
+            if (candidate > best)
+                best = candidate;
+        }
+        onStack.delete(node);
+        memo.set(node, best);
+        return best;
+    };
+    const depths = new Map();
+    for (const node of nodes)
+        depths.set(node, dfs(node));
+    return depths;
+}
+export function criticalConnectors(nodes, edges) {
+    const nodeSet = new Set(nodes);
+    const adjacency = new Map();
+    for (const id of nodes)
+        adjacency.set(id, new Set());
+    for (const edge of edges) {
+        if (!nodeSet.has(edge.from) || !nodeSet.has(edge.to) || edge.from === edge.to)
+            continue;
+        adjacency.get(edge.from)?.add(edge.to);
+        adjacency.get(edge.to)?.add(edge.from);
+    }
+    const disc = new Map();
+    const low = new Map();
+    const parent = new Map();
+    const articulation = new Set();
+    const bridges = [];
+    let time = 0;
+    const visit = (u) => {
+        disc.set(u, ++time);
+        low.set(u, disc.get(u));
+        let childCount = 0;
+        for (const v of [...(adjacency.get(u) ?? [])].sort()) {
+            if (!disc.has(v)) {
+                parent.set(v, u);
+                childCount++;
+                visit(v);
+                low.set(u, Math.min(low.get(u), low.get(v)));
+                const uParent = parent.get(u) ?? null;
+                if (uParent === null && childCount > 1)
+                    articulation.add(u);
+                if (uParent !== null && low.get(v) >= disc.get(u))
+                    articulation.add(u);
+                if (low.get(v) > disc.get(u)) {
+                    const [from, to] = [u, v].sort();
+                    bridges.push({ from, to });
+                }
+            }
+            else if (v !== parent.get(u)) {
+                low.set(u, Math.min(low.get(u), disc.get(v)));
+            }
+        }
+    };
+    for (const id of [...nodes].sort()) {
+        if (!disc.has(id)) {
+            parent.set(id, null);
+            visit(id);
+        }
+    }
+    bridges.sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to));
+    return {
+        articulationPoints: [...articulation].sort(),
+        bridges,
+    };
+}
+/**
+ * Compute a comprehensive offline graph-health report from a shaped graph.
+ * All analytics operate on structural edges between item nodes only.
+ */
+export function analyzeGraph(graph, topN = 10) {
+    const items = [...itemNodeIds(graph)].sort();
+    const edges = structuralEdges(graph);
+    const inDegree = new Map();
+    const outDegree = new Map();
+    for (const id of items) {
+        inDegree.set(id, 0);
+        outDegree.set(id, 0);
+    }
+    for (const e of edges) {
+        outDegree.set(e.from, (outDegree.get(e.from) ?? 0) + 1);
+        inDegree.set(e.to, (inDegree.get(e.to) ?? 0) + 1);
+    }
+    // Orphans: no structural edges at all (no in, no out).
+    const orphans = items.filter((id) => (inDegree.get(id) ?? 0) === 0 && (outDegree.get(id) ?? 0) === 0);
+    // Roots: have outgoing/incoming structure but no INCOMING dependency edge.
+    const roots = items.filter((id) => (inDegree.get(id) ?? 0) === 0 && (outDegree.get(id) ?? 0) > 0);
+    // Leaves: have incoming structure but no outgoing dependency edge.
+    const leaves = items.filter((id) => (outDegree.get(id) ?? 0) === 0 && (inDegree.get(id) ?? 0) > 0);
+    const cycles = findCycles(items, edges);
+    const longest = longestChain(items, edges);
+    // Connected components over the UNDIRECTED projection of structural edges.
+    const undirected = new Map();
+    for (const id of items)
+        undirected.set(id, new Set());
+    for (const e of edges) {
+        undirected.get(e.from)?.add(e.to);
+        undirected.get(e.to)?.add(e.from);
+    }
+    const visited = new Set();
+    let components = 0;
+    for (const id of items) {
+        if (visited.has(id))
+            continue;
+        components++;
+        const queue = [id];
+        visited.add(id);
+        while (queue.length > 0) {
+            const cur = queue.shift();
+            for (const next of undirected.get(cur) ?? []) {
+                if (!visited.has(next)) {
+                    visited.add(next);
+                    queue.push(next);
+                }
+            }
+        }
+    }
+    // Blocked items: any item carrying a BLOCKED_BY outgoing edge.
+    const blockedItems = items.filter((id) => edges.some((e) => e.from === id && e.type === "BLOCKED_BY"));
+    const topDegreeCentrality = items
+        .map((id) => ({
+        id,
+        degree: (inDegree.get(id) ?? 0) + (outDegree.get(id) ?? 0),
+        inDegree: inDegree.get(id) ?? 0,
+        outDegree: outDegree.get(id) ?? 0,
+    }))
+        .filter((d) => d.degree > 0)
+        .sort((a, b) => b.degree - a.degree || a.id.localeCompare(b.id))
+        .slice(0, topN);
+    // Dependency depth per item: longest directed structural path starting at the
+    // item (distance to a leaf). maxDepth is the depth of the critical path.
+    const depths = dependencyDepths(items, edges);
+    const depthByItem = items
+        .map((id) => ({ id, depth: depths.get(id) ?? 0 }))
+        .sort((a, b) => b.depth - a.depth || a.id.localeCompare(b.id));
+    const maxDepth = depthByItem.reduce((max, d) => (d.depth > max ? d.depth : max), 0);
+    const connectors = criticalConnectors(items, edges);
+    return {
+        workspace: graph.workspace,
+        projectKey: graph.projectKey,
+        itemCount: items.length,
+        structuralEdgeCount: edges.length,
+        cycleCount: cycles.length,
+        cycles,
+        orphanCount: orphans.length,
+        orphans,
+        rootCount: roots.length,
+        roots,
+        leafCount: leaves.length,
+        leaves,
+        longestChainLength: longest.length,
+        longestChain: longest,
+        connectedComponents: components,
+        blockedItemCount: blockedItems.length,
+        blockedItems,
+        topDegreeCentrality,
+        maxDepth,
+        depthByItem,
+        articulationPointCount: connectors.articulationPoints.length,
+        articulationPoints: connectors.articulationPoints,
+        bridgeEdgeCount: connectors.bridges.length,
+        bridgeEdges: connectors.bridges,
+    };
+}
 async function syncNeo4j(graph, options) {
     const driver = await createDriver();
     const session = driver.session({ database: process.env.NEO4J_DATABASE });
@@ -1026,17 +1651,241 @@ export function activate(api) {
             }
         },
     });
+    // --- pm-graph analyze ----------------------------------------------------
+    api.registerCommand({
+        name: "pm-graph analyze",
+        description: "Comprehensive offline graph-health report: cycles, orphans, roots, leaves, longest chain, bottleneck connectors, degree centrality, components, blocked items.",
+        run: async (context) => {
+            if (hasHelpFlag(context)) {
+                return {
+                    usage: "pm pm-graph analyze [--root <id>] [--depth <n>] [--include-closed] [--json]",
+                    description: "Build the workspace dependency graph offline (no Neo4j) and report its health: dependency cycle count, orphan/root/leaf items, longest dependency chain, top degree-centrality items, connected-component count, and blocked-item count. Operates on STRUCTURAL edges (BLOCKED_BY + CHILD_OF + dependency edges) only.",
+                    flags: {
+                        "--root <id>": "Restrict to the neighborhood of an item id",
+                        "--depth <n>": "Max hop distance from --root (non-negative integer)",
+                        "--include-closed": "Include closed/canceled items (excluded by default)",
+                        "--json": "Output as JSON",
+                    },
+                    output: {
+                        itemCount: "Number of item nodes analyzed",
+                        structuralEdgeCount: "Number of structural edges analyzed",
+                        cycleCount: "Number of distinct dependency cycles",
+                        orphans: "Item ids with no structural edges",
+                        roots: "Item ids with no incoming dependency edge",
+                        leaves: "Item ids with no outgoing dependency edge",
+                        longestChain: "Ordered ids of the longest dependency chain",
+                        connectedComponents: "Number of connected components (undirected projection)",
+                        blockedItems: "Item ids carrying a BLOCKED_BY edge",
+                        topDegreeCentrality: "Top-N items by total degree",
+                        maxDepth: "Longest dependency depth across all items (critical-path depth)",
+                        depthByItem: "Per-item dependency depth (longest path from the item to a leaf), sorted deepest-first",
+                        articulationPoints: "Items whose removal disconnects part of the structural graph",
+                        bridgeEdges: "Structural item-to-item links whose removal disconnects part of the structural graph",
+                    },
+                };
+            }
+            const flags = parseAnalyticsFlags(context.args ?? []);
+            const graph = shapedAnalyticsGraph(context, flags);
+            const report = analyzeGraph(graph);
+            return { ok: true, ...report };
+        },
+    });
+    // --- pm-graph cycles -----------------------------------------------------
+    api.registerCommand({
+        name: "pm-graph cycles",
+        description: "Detect and list dependency cycles among structural edges. Exits non-zero (1) when cycles exist — CI-usable.",
+        run: async (context) => {
+            if (hasHelpFlag(context)) {
+                return {
+                    usage: "pm pm-graph cycles [--root <id>] [--depth <n>] [--include-closed] [--json]",
+                    description: "Detect dependency cycles among STRUCTURAL edges (BLOCKED_BY + dependency edges, not facet/tag edges). Prints each cycle as an id path. Exits with code 1 when any cycle exists (so it can gate CI); exits 0 when there are none.",
+                    flags: {
+                        "--root <id>": "Restrict to the neighborhood of an item id",
+                        "--depth <n>": "Max hop distance from --root",
+                        "--include-closed": "Include closed/canceled items",
+                        "--json": "Output as JSON",
+                    },
+                    output: {
+                        cycleCount: "Number of distinct cycles",
+                        cycles: "Array of cycles, each an ordered id path (first === last)",
+                    },
+                };
+            }
+            const flags = parseAnalyticsFlags(context.args ?? []);
+            const graph = shapedAnalyticsGraph(context, flags);
+            const edges = structuralEdges(graph);
+            const items = [...itemNodeIds(graph)].sort();
+            const cycles = findCycles(items, edges);
+            if (cycles.length > 0) {
+                const detail = cycles.map((c) => c.join(" -> ")).join("; ");
+                throw new CommandError(`Found ${cycles.length} dependency cycle(s): ${detail}`, EXIT_CODE.GENERIC_FAILURE);
+            }
+            return { ok: true, cycleCount: 0, cycles: [] };
+        },
+    });
+    // --- pm-graph path -------------------------------------------------------
+    api.registerCommand({
+        name: "pm-graph path",
+        description: "Shortest directed dependency path between two item ids (BFS over structural edges).",
+        run: async (context) => {
+            if (hasHelpFlag(context)) {
+                return {
+                    usage: "pm pm-graph path <from> <to> [--include-closed] [--json]",
+                    description: "Compute the shortest directed dependency path from <from> to <to> via BFS over STRUCTURAL edges. Reports the ordered id path or that no path exists.",
+                    flags: {
+                        "--include-closed": "Include closed/canceled items",
+                        "--json": "Output as JSON",
+                    },
+                    example: "pm pm-graph path pm-ep18 pm-hd71 --json",
+                    output: {
+                        from: "Source item id",
+                        to: "Target item id",
+                        found: "Whether a directed path exists",
+                        path: "Ordered id path (inclusive) or null",
+                        length: "Number of edges on the path (path.length - 1) or null",
+                    },
+                };
+            }
+            const flags = parseAnalyticsFlags(context.args ?? []);
+            const [from, to] = flags.positionals;
+            if (!from || !to) {
+                throw new CommandError("Usage: pm pm-graph path <from> <to>\nExample: pm pm-graph path pm-ep18 pm-hd71", EXIT_CODE.USAGE);
+            }
+            const graph = shapedAnalyticsGraph(context, flags);
+            const items = itemNodeIds(graph);
+            if (!items.has(from)) {
+                throw new CommandError(`Item "${from}" was not found in the workspace graph.`, EXIT_CODE.NOT_FOUND);
+            }
+            if (!items.has(to)) {
+                throw new CommandError(`Item "${to}" was not found in the workspace graph.`, EXIT_CODE.NOT_FOUND);
+            }
+            const edges = structuralEdges(graph);
+            const path = shortestPath(edges, from, to);
+            return {
+                ok: true,
+                from,
+                to,
+                found: path !== null,
+                path,
+                length: path ? path.length - 1 : null,
+            };
+        },
+    });
+    // --- pm-graph critical-path ---------------------------------------------
+    api.registerCommand({
+        name: "pm-graph critical-path",
+        description: "The longest chain of blocking dependencies through the workspace (the critical path), as an ordered id list.",
+        run: async (context) => {
+            if (hasHelpFlag(context)) {
+                return {
+                    usage: "pm pm-graph critical-path [--root <id>] [--depth <n>] [--include-closed] [--json]",
+                    description: "Compute the longest chain of structural (blocking) dependencies through the workspace — the critical path. Reports the ordered id list and its length. Cycle-safe.",
+                    flags: {
+                        "--root <id>": "Restrict to the neighborhood of an item id",
+                        "--depth <n>": "Max hop distance from --root",
+                        "--include-closed": "Include closed/canceled items",
+                        "--json": "Output as JSON",
+                    },
+                    output: {
+                        length: "Number of items on the critical path",
+                        path: "Ordered id list of the critical path",
+                    },
+                };
+            }
+            const flags = parseAnalyticsFlags(context.args ?? []);
+            const graph = shapedAnalyticsGraph(context, flags);
+            const edges = structuralEdges(graph);
+            const items = [...itemNodeIds(graph)].sort();
+            const chain = longestChain(items, edges);
+            return { ok: true, length: chain.length, path: chain };
+        },
+    });
+    // --- pm-graph topo-sort --------------------------------------------------
+    api.registerCommand({
+        name: "pm-graph topo-sort",
+        description: "Topological execution order respecting dependency/blocked_by edges (Kahn's algorithm). Exits non-zero (1) on a cycle.",
+        run: async (context) => {
+            if (hasHelpFlag(context)) {
+                return {
+                    usage: "pm pm-graph topo-sort [--root <id>] [--depth <n>] [--include-closed] [--json]",
+                    description: "Emit a valid topological execution order of items over STRUCTURAL edges (BLOCKED_BY + dependency edges), so each item is listed only after the items it depends on. Uses Kahn's algorithm. Ties are broken by ascending id for deterministic output. Reports the resolvable prefix and the cycle members, and EXITS WITH CODE 1 when a dependency cycle prevents a complete ordering (CI-usable).",
+                    flags: {
+                        "--root <id>": "Restrict to the neighborhood of an item id",
+                        "--depth <n>": "Max hop distance from --root",
+                        "--include-closed": "Include closed/canceled items",
+                        "--json": "Output as JSON",
+                    },
+                    output: {
+                        order: "Ordered item ids (dependencies before dependents); complete when acyclic",
+                        count: "Number of items placed in the order",
+                        cyclic: "Whether a cycle prevented a complete ordering",
+                    },
+                };
+            }
+            const flags = parseAnalyticsFlags(context.args ?? []);
+            const graph = shapedAnalyticsGraph(context, flags);
+            const edges = structuralEdges(graph);
+            const items = [...itemNodeIds(graph)].sort();
+            const { order, cycleNodes } = topoSort(items, edges);
+            if (cycleNodes.length > 0) {
+                // Surface the actual cycle path(s) among the unresolved nodes for context.
+                const cycles = findCycles(cycleNodes, edges);
+                const detail = cycles.length > 0
+                    ? cycles.map((c) => c.join(" -> ")).join("; ")
+                    : cycleNodes.join(", ");
+                throw new CommandError(`Cannot produce a topological order: ${cycleNodes.length} item(s) are involved in a dependency cycle (${detail}). Resolved prefix: ${order.length} item(s).`, EXIT_CODE.GENERIC_FAILURE);
+            }
+            return { ok: true, count: order.length, cyclic: false, order };
+        },
+    });
+    // --- pm-graph impact -----------------------------------------------------
+    api.registerCommand({
+        name: "pm-graph impact",
+        description: "List all items transitively blocked-by / downstream of an item id (reverse-reachable set) with a count.",
+        run: async (context) => {
+            if (hasHelpFlag(context)) {
+                return {
+                    usage: "pm pm-graph impact <id> [--include-closed] [--json]",
+                    description: "Compute the impact set of an item: every item that transitively depends on it (is blocked-by / downstream of it) over STRUCTURAL edges. Equivalent to the reverse-reachable set following edge direction. Complements `path` and `neighbors`. Reports the affected item ids and their count.",
+                    flags: {
+                        "--include-closed": "Include closed/canceled items",
+                        "--json": "Output as JSON",
+                    },
+                    example: "pm pm-graph impact pm-ep18 --json",
+                    output: {
+                        id: "The item whose downstream impact was computed",
+                        count: "Number of items transitively affected",
+                        impacted: "Sorted ids of all items transitively blocked-by/downstream of <id>",
+                    },
+                };
+            }
+            const flags = parseAnalyticsFlags(context.args ?? []);
+            const [id] = flags.positionals;
+            if (!id) {
+                throw new CommandError("Usage: pm pm-graph impact <id>\nExample: pm pm-graph impact pm-ep18", EXIT_CODE.USAGE);
+            }
+            const graph = shapedAnalyticsGraph(context, flags);
+            const items = itemNodeIds(graph);
+            if (!items.has(id)) {
+                throw new CommandError(`Item "${id}" was not found in the workspace graph.`, EXIT_CODE.NOT_FOUND);
+            }
+            const edges = structuralEdges(graph);
+            const impacted = reverseReachable(edges, id);
+            return { ok: true, id, count: impacted.length, impacted };
+        },
+    });
     // --- pm graph export -----------------------------------------------------
     // registerExporter("graph") auto-creates the `pm graph export` command (the
     // `<name> export` form). It does NOT collide with the existing
     // `pm pm-graph cypher` command (different name). The export pipeline builds
     // the workspace graph from a single `pm list-all --json --include-body`
-    // call and renders it to one of four offline formats. No Neo4j required.
+    // call and renders it to one of six offline formats (cypher | mermaid | dot |
+    // json | graphml | plantuml). No Neo4j required.
     const exporter = (ctx) => {
         const options = ctx.options ?? {};
         const rawFormat = String(readExportOption(options, "format") ?? "json").toLowerCase();
-        if (!["cypher", "mermaid", "dot", "json"].includes(rawFormat)) {
-            throw new CommandError(`Unknown --format "${rawFormat}". Valid: cypher | mermaid | dot | json.`, EXIT_CODE.USAGE);
+        if (!["cypher", "mermaid", "dot", "json", "graphml", "plantuml"].includes(rawFormat)) {
+            throw new CommandError(`Unknown --format "${rawFormat}". Valid: cypher | mermaid | dot | json | graphml | plantuml.`, EXIT_CODE.USAGE);
         }
         const format = rawFormat;
         const rawEdges = String(readExportOption(options, "edges") ?? "all").toLowerCase();