feat(nx-graph-to-mermaid): extract // comments from project.json and render as a target description table

[datalackey]

Summary

project.json files use "//" keys (NX's JSON-comment convention) as an
array of strings to document what each target does. Currently
nx-graph-to-mermaid ignores this metadata entirely. This issue tracks
adding a companion Markdown table that surfaces those descriptions alongside
the generated Mermaid diagram.

Background / motivation

The idea is directly analogous to how update-markdown-uml uses
_COMPONENT_INFO.md sidecar files to annotate component diagrams with a
human-readable description table. The pattern is already proven in this
repo:

• Diagram → shows structure (arrows, nodes, dependency flow)
• Table → shows intent (// descriptions, one row per target)

Injecting descriptions directly into Mermaid node labels was considered and
rejected: even a single short sentence bloats node boxes and breaks the
visual flow of the graph. A separate table is the right vehicle.

Proposed behaviour

Two independent, opt-in marker pairs in the target Markdown file:

<!-- NX_GRAPH:START -->
(existing mermaid diagram — unchanged)
<!-- NX_GRAPH:END -->

<!-- NX_GRAPH_TABLE:START -->
| Target | Description |
|--------|-------------|
| check-all | Run locally before pushing — equivalent to what CI runs |
| check-docs | Verifies all auto-generated documentation is up to date |
| update-all | Run locally before committing |
<!-- NX_GRAPH_TABLE:END -->

The table is only injected/checked when NX_GRAPH_TABLE markers are
present in the file — same opt-in contract as the existing graph markers.
The graph section is unaffected.

Design decisions (recommended defaults)

#	Question	Recommendation	Rationale
1	Which element of the // array to use?	First element only (//[0])	Subsequent elements are typically caveats/footnotes, not summaries. Mirrors the UML plugin's first-sentence rule.
2	Targets without a // key?	Omit from the table	An empty or TBD row adds noise without value; the graph already shows the target exists.
3	Table placement	Separate NX_GRAPH_TABLE markers, independently placeable	Gives authors full control over document layout; decouples table from diagram.
4	Opt-in vs always-on	Opt-in (markers must be present)	Consistent with how NX_GRAPH markers work today; no surprise output in existing docs.

Implementation sketch

The change is self-contained to nx-graph-to-mermaid:

1. New function buildMermaidTable(project: NxProjectJson): string (new
   file src/core/buildMermaidTable.ts) — walks targets, extracts
   target["//"][0] where present, emits the Markdown table.
2. normalizeOptions.ts — add NX_GRAPH_TABLE_START / NX_GRAPH_TABLE_END
   constants; extend NormalizedOptions with tableMarkdownPath? if a
   separate path is ever needed (likely not — same file as the graph).
3. executor.ts — in update and check modes, detect whether
   NX_GRAPH_TABLE markers exist in the target file; if so,
   inject/diff the table using the existing injectBetweenMarkers helper.
4. buildMermaid.ts / NxTarget interface — no change needed; the
   // key is extracted at the table-build layer only.

No new runtime dependencies required.

Out of scope

• Rendering descriptions as node labels inside the Mermaid graph (rejected above).
• Linking target names to in-document anchors (no per-target heading exists
  to link to).
• A generate-mode output for the table (the update/check modes cover
  all current use cases).