pm-graph 2026.6.2 → 2026.6.4

package/CHANGELOG.md

@@ -1,6 +1,28 @@
 # Changelog
 
-## 2026.6.2 - 2026-06-02
+## 2026.6.4 - 2026-06-04
+
+### Added
+
+- Add topo-sort, impact, and dependency-depth analytics ([pm-graph-r5yz](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/features/pm-graph-r5yz.toon))
+
+## 2026.06.02-1 - 2026-06-02
+
+### Added
+
+- Deepen pm-graph with offline analytics + new export formats ([pm-graph-1dpk](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/features/pm-graph-1dpk.toon))
+- Unit tests for analytics + new renderers ([pm-graph-f9c3](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/tasks/pm-graph-f9c3.toon))
+- graph exporter: add graphml + plantuml formats ([pm-graph-79f2](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/tasks/pm-graph-79f2.toon))
+
+### Other
+
+- pm-graph critical-path: longest blocking chain ([pm-graph-f1k9](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/tasks/pm-graph-f1k9.toon))
+- pm-graph path: shortest dependency path \(BFS\) ([pm-graph-vtlu](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/tasks/pm-graph-vtlu.toon))
+- pm-graph cycles: detect dependency cycles, CI exit code ([pm-graph-h0xs](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/tasks/pm-graph-h0xs.toon))
+- pm-graph analyze: offline graph-health report ([pm-graph-d9tz](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/tasks/pm-graph-d9tz.toon))
+- Decision: analytics operate on STRUCTURAL edges only ([pm-graph-89nw](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/tasks/pm-graph-89nw.toon))
+
+## 2026.06.02 - 2026-06-02
 
 ### Added
 

package/README.md

@@ -4,7 +4,9 @@ Knowledge graph and dependency graph extension for [pm CLI](https://github.com/u
 
 The extension reads the current workspace through `pm list-all --json` and `pm deps <id> --json`, then turns items, parent links, `blocked_by` metadata, dependency metadata, tags, statuses, types, assignees, sprints, and releases into graph nodes and relationships.
 
-It can sync that graph into Neo4j, or export it offline to **Mermaid**, **Graphviz DOT**, **JSON Graph**, or **Cypher** via `pm graph export` — with neighborhood (`--root`/`--depth`) and edge-type (`--edges`) shaping.
+It can sync that graph into Neo4j, or export it offline to **Mermaid**, **Graphviz DOT**, **JSON Graph**, **Cypher**, **GraphML**, or **PlantUML** via `pm graph export` — with neighborhood (`--root`/`--depth`) and edge-type (`--edges`) shaping.
+
+It also ships **offline graph analytics** (no Neo4j required): `pm pm-graph analyze`, `cycles`, `path`, `critical-path`, `topo-sort`, and `impact` run dependency-cycle detection, shortest-path, longest-chain, topological ordering, downstream-impact, orphan/root/leaf and centrality analysis directly against your workspace.
 
 ## Quick Start
 
@@ -54,7 +56,7 @@ pm install github.com/unbraind/pm-graph --force
 | `NEO4J_DATABASE` | No | Target database (defaults to server default) |
 | `PM_GRAPH_PROJECT_KEY` | No | Override the project key (defaults to workspace directory name) |
 
-The commands `export` and `cypher` do not require Neo4j at all.
+The commands `export`, `cypher`, `analyze`, `cycles`, `path`, `critical-path`, `topo-sort`, and `impact`, plus the `pm graph export` exporter, do not require Neo4j at all.
 
 ## Commands
 
@@ -73,7 +75,7 @@ Example output:
   "ok": true,
   "source": "pm-graph",
   "neo4jConfigured": true,
-  "version": "0.1.4"
+  "version": "0.2.0"
 }
 ```
 
@@ -136,6 +138,8 @@ pm graph export --format mermaid                       # Mermaid graph TD to std
 pm graph export --format dot --output graph.dot        # Graphviz DOT to a file
 pm graph export --format json --output graph.json      # JSON Graph (nodes/edges)
 pm graph export --format cypher                         # parameterized Cypher (commented params)
+pm graph export --format graphml --output graph.graphml # GraphML XML for yEd / Gephi / NetworkX
+pm graph export --format plantuml --output graph.puml   # PlantUML object diagram
 ```
 
 Shape the exported graph:
@@ -156,7 +160,7 @@ pm graph export --format json --include-closed
 
 | Flag | Values | Default | Description |
 |---|---|---|---|
-| `--format` | `cypher` \| `mermaid` \| `dot` \| `json` | `json` | Output format. `mermaid` emits a `graph TD` flowchart; `dot` emits Graphviz `digraph`; `json` emits a JSON Graph (`nodes`/`edges`) document; `cypher` reuses the parameterized Neo4j import statements. |
+| `--format` | `cypher` \| `mermaid` \| `dot` \| `json` \| `graphml` \| `plantuml` | `json` | Output format. `mermaid` emits a `graph TD` flowchart; `dot` emits Graphviz `digraph`; `json` emits a JSON Graph (`nodes`/`edges`) document; `cypher` reuses the parameterized Neo4j import statements; `graphml` emits a valid GraphML XML document for yEd / Gephi / NetworkX; `plantuml` emits a `@startuml`…`@enduml` object diagram. |
 | `--output <file>` | path | — | Write to this file instead of stdout. |
 | `--root <id>` | item id | — | Restrict the graph to the neighborhood around this node. |
 | `--depth <n>` | non-negative integer | unlimited | Max hops from `--root` (undirected). Only meaningful with `--root`. |
@@ -221,8 +225,8 @@ Example output (Neo4j connected):
   "nodeCount": 18,
   "relationshipCount": 11,
   "lastSyncedAt": "2026-05-14T10:00:00.000Z",
-  "syncVersion": "0.1.4",
-  "version": "0.1.4"
+  "syncVersion": "0.2.0",
+  "version": "0.2.0"
 }
 ```
 
@@ -236,7 +240,7 @@ Example output (Neo4j not configured):
   "projectKey": "my-project",
   "workspace": "/path/to/workspace",
   "localItemCount": 15,
-  "version": "0.1.4"
+  "version": "0.2.0"
 }
 ```
 
@@ -284,6 +288,113 @@ Example output:
 }
 ```
 
+## Offline Analytics
+
+These commands analyze the workspace dependency graph **entirely offline** — no Neo4j required. They operate on **structural edges only** (`BLOCKED_BY`, `CHILD_OF`, and dependency edges such as `BLOCKS`/`RELATED`) between real items; facet edges (type/status/assignee/sprint/release) and tag edges are deliberately excluded so cycle, path, and centrality results stay meaningful.
+
+Closed/canceled items are excluded by default; pass `--include-closed` to keep them. `analyze`, `cycles`, `critical-path`, and `topo-sort` also accept `--root <id>` / `--depth <n>` to scope the analysis to a neighborhood.
+
+### `pm pm-graph analyze`
+
+Comprehensive graph-health report: dependency-cycle count, orphan items (no edges), root items (no incoming dependency), leaf items (no outgoing dependency), longest dependency chain, top-N degree-centrality items, connected-component count, and blocked-item count.
+
+```bash
+pm pm-graph analyze --json
+pm pm-graph analyze --root pm-ep18 --depth 2 --json
+pm pm-graph analyze --include-closed --json
+```
+
+Example output (abbreviated):
+
+```json
+{
+  "ok": true,
+  "itemCount": 7,
+  "structuralEdgeCount": 6,
+  "cycleCount": 1,
+  "cycles": [["pm-oj3m", "pm-zc3a", "pm-oj3m"]],
+  "orphans": ["pm-op0k"],
+  "roots": ["pm-ep18"],
+  "leaves": ["pm-hd71"],
+  "longestChainLength": 4,
+  "longestChain": ["pm-ep18", "pm-k849", "pm-p2q3", "pm-hd71"],
+  "connectedComponents": 3,
+  "blockedItemCount": 5,
+  "topDegreeCentrality": [{ "id": "pm-ep18", "degree": 2, "inDegree": 0, "outDegree": 2 }],
+  "maxDepth": 3,
+  "depthByItem": [{ "id": "pm-hd71", "depth": 3 }, { "id": "pm-p2q3", "depth": 2 }]
+}
+```
+
+The `maxDepth` and `depthByItem` fields report the **dependency depth** of each item — the number of edges on the longest directed structural path starting at the item (its distance to a leaf along blocker edges). A leaf has depth `0`; `maxDepth` equals the critical-path depth. `depthByItem` is sorted deepest-first. These fields are additive; all previously emitted fields are unchanged.
+
+### `pm pm-graph cycles`
+
+Detect and list dependency cycles. Each cycle is printed as an ordered id path (first id equals last). **Exits with code 1 when any cycle exists** (so it can gate CI) and exits 0 when there are none.
+
+```bash
+pm pm-graph cycles            # human-readable; exit 1 if cycles found
+pm pm-graph cycles --json     # machine-readable
+```
+
+```jsonc
+// no cycles -> exit 0
+{ "ok": true, "cycleCount": 0, "cycles": [] }
+```
+
+### `pm pm-graph path`
+
+Shortest **directed** dependency path between two item ids via BFS over structural edges. Missing arguments yield a usage error (exit 2); an unknown id yields a not-found error (exit 3).
+
+```bash
+pm pm-graph path pm-ep18 pm-hd71 --json
+```
+
+```json
+{ "ok": true, "from": "pm-ep18", "to": "pm-hd71", "found": true, "path": ["pm-ep18", "pm-hd71"], "length": 1 }
+```
+
+### `pm pm-graph critical-path`
+
+The longest chain of blocking dependencies through the workspace — the critical path — as an ordered id list with its length. Cycle-safe.
+
+```bash
+pm pm-graph critical-path --json
+```
+
+```json
+{ "ok": true, "length": 4, "path": ["pm-ep18", "pm-k849", "pm-p2q3", "pm-hd71"] }
+```
+
+### `pm pm-graph topo-sort`
+
+Emit a valid **topological execution order** of items over structural edges (Kahn's algorithm), so each item is listed only after the items it depends on. Ties are broken by ascending id for deterministic output. **Exits with code 1 when a dependency cycle prevents a complete ordering** (CI-usable), reporting the cycle members and the resolvable prefix. Accepts `--root`/`--depth`/`--include-closed`.
+
+```bash
+pm pm-graph topo-sort --json
+```
+
+```json
+{
+  "ok": true,
+  "count": 6,
+  "cyclic": false,
+  "order": ["pm-p030", "pm-ijd7", "pm-vc4q", "pm-yol1", "pm-0wtl", "pm-8k1m"]
+}
+```
+
+### `pm pm-graph impact`
+
+List every item **transitively blocked-by / downstream** of a given item id — the reverse-reachable set following edge direction. Complements `path` and `neighbors`. A missing id yields a not-found error (exit 3); no id yields a usage error (exit 2).
+
+```bash
+pm pm-graph impact pm-vc4q --json
+```
+
+```json
+{ "ok": true, "id": "pm-vc4q", "count": 3, "impacted": ["pm-0wtl", "pm-8k1m", "pm-yol1"] }
+```
+
 ## Graph Model
 
 - **`PmItem`** nodes for real pm items, labelled with item type (e.g. `task`, `bug`).

package/dist/index.d.ts

@@ -14,8 +14,133 @@ type ExtensionApi = {
     registerCommand(command: RegisterCommand): void;
     registerExporter(name: string, exporter: Exporter): void;
 };
-export type ExportFormat = "cypher" | "mermaid" | "dot" | "json";
+type GraphNode = {
+    id: string;
+    labels: string[];
+    properties: Record<string, unknown>;
+};
+type GraphRelationship = {
+    from: string;
+    to: string;
+    type: string;
+    properties: Record<string, unknown>;
+};
+type Graph = {
+    generatedAt: string;
+    workspace: string;
+    projectKey: string;
+    nodes: GraphNode[];
+    relationships: GraphRelationship[];
+};
+export type ExportFormat = "cypher" | "mermaid" | "dot" | "json" | "graphml" | "plantuml";
 export type EdgeFilter = "deps" | "tags" | "all";
+/**
+ * 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 declare function renderGraphml(graph: Graph): string;
+/**
+ * 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 declare function renderPlantuml(graph: Graph): string;
+type StructuralEdge = {
+    from: string;
+    to: string;
+    type: string;
+};
+/**
+ * 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 declare function findCycles(nodes: string[], edges: StructuralEdge[]): string[][];
+/**
+ * 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 declare function shortestPath(edges: StructuralEdge[], from: string, to: string): string[] | 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 declare function longestChain(nodes: string[], edges: StructuralEdge[]): string[];
+/**
+ * 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 declare function topoSort(nodes: string[], edges: StructuralEdge[]): {
+    order: string[];
+    cycleNodes: string[];
+};
+/**
+ * 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 declare function reverseReachable(edges: StructuralEdge[], start: string): string[];
+/**
+ * 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 declare function dependencyDepths(nodes: string[], edges: StructuralEdge[]): Map<string, number>;
+type AnalyzeReport = {
+    workspace: string;
+    projectKey: string;
+    itemCount: number;
+    structuralEdgeCount: number;
+    cycleCount: number;
+    cycles: string[][];
+    orphanCount: number;
+    orphans: string[];
+    rootCount: number;
+    roots: string[];
+    leafCount: number;
+    leaves: string[];
+    longestChainLength: number;
+    longestChain: string[];
+    connectedComponents: number;
+    blockedItemCount: number;
+    blockedItems: string[];
+    topDegreeCentrality: Array<{
+        id: string;
+        degree: number;
+        inDegree: number;
+        outDegree: number;
+    }>;
+    maxDepth: number;
+    depthByItem: Array<{
+        id: string;
+        depth: number;
+    }>;
+};
+/**
+ * Compute a comprehensive offline graph-health report from a shaped graph.
+ * All analytics operate on structural edges between item nodes only.
+ */
+export declare function analyzeGraph(graph: Graph, topN?: number): AnalyzeReport;
 export declare function activate(api: ExtensionApi): void;
 declare const _default: {
     activate: typeof activate;