pm-graph 2026.5.30 → 2026.6.2-1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 2026.6.2-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
+
+- Add multi-format graph exporter \(pm graph export\): cypher, mermaid, dot, json-graph ([pm-graph-xii9](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/features/pm-graph-xii9.toon))
+
 ## 2026.05.28 - 2026-05-28
 
 ### Added

package/README.md

@@ -4,6 +4,10 @@ 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**, **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`, and `critical-path` run dependency-cycle detection, shortest-path, longest-chain, orphan/root/leaf and centrality analysis directly against your workspace.
+
 ## Quick Start
 
 **Step 1 — Install the extension:**
@@ -52,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`, and `critical-path`, plus the `pm graph export` exporter, do not require Neo4j at all.
 
 ## Commands
 
@@ -71,7 +75,7 @@ Example output:
   "ok": true,
   "source": "pm-graph",
   "neo4jConfigured": true,
-  "version": "0.1.4"
+  "version": "0.2.0"
 }
 ```
 
@@ -125,6 +129,55 @@ Example output (abbreviated):
 }
 ```
 
+### `pm graph export`
+
+Export the current workspace graph to a portable file format for diagramming or import into other graph tooling. Builds the graph from a single `pm list-all --json --include-body` call. **Does not require Neo4j.**
+
+```bash
+pm graph export --format mermaid                       # Mermaid graph TD to stdout
+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:
+
+```bash
+# Dependency edges only (drop facet + tag edges)
+pm graph export --format mermaid --edges deps
+
+# Only tag relationships
+pm graph export --format mermaid --edges tags
+
+# 2-hop neighborhood around one item (undirected reachability)
+pm graph export --format dot --root TASK-42 --depth 2
+
+# Include closed/canceled items (excluded by default)
+pm graph export --format json --include-closed
+```
+
+| Flag | Values | Default | Description |
+|---|---|---|---|
+| `--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`. |
+| `--include-closed` | flag | off | Include `closed`/`canceled` items (excluded by default). |
+| `--edges <deps\|tags\|all>` | `deps` \| `tags` \| `all` | `all` | `deps` keeps dependency/structural edges (`BLOCKED_BY`, `CHILD_OF`, dependency kinds); `tags` keeps only `TAGGED_WITH`; `all` keeps everything including facet edges. |
+
+Example output (`--format mermaid --edges deps`):
+
+```mermaid
+graph TD
+  n_TASK_2["Build API [TASK-2] (in_progress)"]
+  n_TASK_1["Design schema [TASK-1] (closed)"]
+  n_TASK_2 -->|BLOCKED_BY| n_TASK_1
+```
+
+`pm graph export` is provided through pm's exporter pipeline, so it is invoked as `pm graph export` (the `<name> export` form). It is fully offline and never touches Neo4j.
+
 ### `pm pm-graph sync`
 
 Sync the current workspace graph into Neo4j using the `NEO4J_*` environment variables.
@@ -172,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"
 }
 ```
 
@@ -187,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"
 }
 ```
 
@@ -235,6 +288,80 @@ 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`, and `critical-path` 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 }]
+}
+```
+
+### `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"] }
+```
+
 ## Graph Model
 
 - **`PmItem`** nodes for real pm items, labelled with item type (e.g. `task`, `bug`).

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import type { Exporter } from "@unbrained/pm-cli/sdk";
 type CommandContext = {
     command?: string;
     args?: string[];
@@ -11,7 +12,95 @@ type RegisterCommand = {
 };
 type ExtensionApi = {
     registerCommand(command: RegisterCommand): void;
+    registerExporter(name: string, exporter: Exporter): void;
 };
+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[];
+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;
+    }>;
+};
+/**
+ * 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;