Reference Doc Generator: Rich Content & Diagram Enhancements

[darko-mijic]

Summary

The reference doc generator (referenceDocConfigs) has a solid foundation with 4 content sources (conventions, diagrams, shapes, behaviors) but several gaps limit its usefulness for generating rich technical documentation. This issue tracks enhancements across three tiers of effort.

Context

The @libar-docs-arch-view annotation + DiagramScope filtering already enables scoped Mermaid diagrams. Shape extraction (@libar-docs-extract-shapes) pulls real TypeScript constructs from AST. Convention content pulls structured rules from Gherkin. But behavior rendering is shallow, diagram types are limited to flowcharts, and some extraction gaps exist.

Tier 1: Codec Enhancements (data exists in MasterDataset, rendering missing)

Deep behavior rendering

• Render full scenario steps, DataTables, and DocStrings from pattern.scenarios in reference docs
• Currently behaviorCategories only renders rule name + 120-char truncated description — essentially an index

Full rule descriptions in behavior content

• Remove 120-character truncation on rule descriptions
• Parse structured **Invariant:** / **Rationale:** content from behavior patterns (same as conventions do)

JSDoc prose alongside shapes

• Render directive.description markdown alongside extracted shapes in reference docs
• Currently shapes render source code but lose the narrative JSDoc context

archLayer filter in DiagramScope

• Add archLayer to DiagramScope interface and collectScopePatterns()
• Enable filtering diagrams by domain/application/infrastructure layer

New Mermaid diagram types

• Sequence diagrams (sequenceDiagram) — valuable for event flow documentation
• State machine diagrams (stateDiagram-v2) — FSM visualization
• C4 diagrams (C4Context, C4Container) — architecture overview
• Class diagrams (classDiagram) — could leverage shapeSources data
• Currently all diagrams are flowcharts (graph TD/TB/LR)
• Add diagramType field to DiagramScope

Edge labels on diagrams

• Show event/command names on relationship arrows
• Currently edges only distinguish type via arrow style

Custom node shapes/styles per archRole

• Different Mermaid node shapes for different archRole values (e.g., saga vs projection vs command)

Tier 2: Extraction Enhancements (pipeline changes)

@param/@returns/@throws extraction

• Currently dropped during JSDoc scanning in ast-parser.ts
• Function shapes lack parameter documentation
• Schema update needed: add params, returns, throws to ExtractedShape

Full property-level JSDoc

• Currently truncated to first line only (extractJsDocText())
• Multi-line property descriptions, markdown tables within property JSDoc discarded
• Remove first-line truncation, preserve full property docs

Auto-shape discovery mode

• Extract all exported types from a file without requiring explicit @libar-docs-extract-shapes tag
• Could be opt-in via @libar-docs-extract-shapes * or a new tag
• Reduces manual annotation burden

Convention content from TypeScript JSDoc

• Pull structured **Invariant:**/**Rationale:** content from TypeScript JSDoc blocks
• Currently convention extraction only works with Gherkin Rule: blocks
• Would enable TypeScript files to self-document business rules

Tier 3: Config-Only (zero code, available today)

These require no code changes — just annotation and config work:

• Add @libar-docs-arch-view to more source files for richer diagrams
• Add @libar-docs-extract-shapes to key infrastructure files
• Use diagramScopes (plural) for multiple views per reference doc
• Combine all 4 content sources in single reference doc configs

Priority Recommendation

1. Deep behavior rendering — highest ROI, unlocks full Gherkin content
2. JSDoc prose alongside shapes — makes shape docs self-documenting
3. @param/@returns extraction — completes function documentation story
4. New diagram types — sequence diagrams especially for event flows
5. Auto-shape discovery — removes manual annotation burden

Related

• Pattern Relationship Model spec (specs/pattern-relationship-model.feature)
• referenceDocConfigs in downstream delivery-process.config.js
• Reference codec: src/renderable/codecs/reference.ts
• Shape extractor: src/extractor/shape-extractor.ts
• Diagram utils: src/renderable/codecs/diagram-utils.ts

[darko-mijic]

Update: Cross-Reference with Ideation Deep Dive

The ideation docs (_ideation/01-ai-prompt-manager/) contain validated, code-grounded analysis that directly overlaps with several items in this issue. Key additions:

---

§1B — Function Signature Surfacing (upgrade existing item)

The ExportInfo.signature field already exists in the schema — it's just populated with the lossy '...' placeholder. The fix is ~15 lines:

• Thread sourceCode into extractFromDeclaration in ast-parser.ts:799
• Use sourceCode.slice(param.range[0], param.range[1]) for each parameter
• The shape-extractor's functionToSignature() already demonstrates the proven pattern
• No schema migration needed

Impact on reference docs: Function shapes would show full parameter types and return types without needing @libar-docs-extract-shapes. Makes shapeSources globs much more informative.

Effort: Small (~15 lines)

---

§2A — LSP-Lite / Auto-Shape Discovery (upgrade existing item)

The ideation exploration confirmed this is AST-only — no TypeScript type checker needed:

Capability	Current	Enhanced	Requires Type Checker?
Function param names/types	No	Yes	No — AST has node.params
Return types	No	Yes	No — AST has node.returnType
Interface members	Only @extract-shapes	Always for exports	No
Type parameters/generics	Only @extract-shapes	Always	No
Cross-file type resolution	No	No	Yes — needs compiler

This would eliminate the need for explicit @libar-docs-extract-shapes annotations in many cases. Any file matching a shapeSources glob would automatically contribute its exported types.

Effort: Medium (scanner changes + schema evolution)

---

NEW: §3B — Codec Composition

Currently each codec is a standalone MasterDataset → RenderableDocument transform. A CompositeCodec would enable building reference docs from multiple codec outputs:

const sessionBrief = composeCodecs([
  OverviewCodec,
  CurrentWorkCodec,
  RemainingWorkCodec
]);
const doc = sessionBrief.decode(dataset);

This would allow referenceDocConfigs to include content from any codec, not just the current 4 sources (conventions, diagrams, shapes, behaviors).

Effort: Small (RenderableDocument concatenation is trivial)

---

NEW: §3A — renderToClaudeContext Renderer

The _claude-md/ summary output currently uses the same markdown renderer. The Process API already has a custom === MARKERS === format optimized for AI consumption (in context-formatter.ts), but it bypasses the codec system.

A dedicated renderToClaudeContext renderer would:

• Make reference doc summaries more token-efficient for LLM context
• Unify the two formatting paths (codec-based markdown vs hand-written markers)
• Each renderer is ~200 lines (single switch statement over the 9 RenderableDocument block types)

Effort: Small per renderer

---

NEW: §2D — Data-Driven Gherkin Tag Extraction (enabler)

The Gherkin tag extractor has ~40 hardcoded if/else if branches. Refactoring to use the TagRegistry metadata-driven approach (like the TypeScript extractor already does) would make adding new tags zero-code-change. This is an enabler for:

• Adding diagramType to DiagramScope via a new tag
• Per-shape routing via new annotation tags
• Custom tags for external adopters

Effort: Medium (refactor, cuts maintenance burden roughly in half)

---

Updated Priority with Ideation Context

Phase 1 — Low-hanging fruit (validated, small effort)
  ├── §1B  Function signatures in ast-parser        (~15 lines)
  ├── Deep behavior rendering                        (codec change, data exists)
  ├── Full rule descriptions (remove 120-char truncation)
  └── archLayer filter in DiagramScope               (~10 lines)

Phase 2 — Medium effort, high payoff
  ├── §2A  LSP-Lite / auto-shape discovery           (scanner + schema)
  ├── §3B  Codec composition                         (small, unlocks flexible docs)
  ├── §3A  renderToClaudeContext renderer             (~200 lines)
  ├── New Mermaid diagram types                       (medium per type)
  └── Full property-level JSDoc                       (remove truncation)

Phase 3 — Enablers for future extensibility
  ├── §2D  Data-driven Gherkin tag extraction         (refactor)
  ├── Convention content from TypeScript JSDoc         (new extraction path)
  └── Per-shape annotation routing                    (scanner model change)

Reference

• Ideation deep dive: _ideation/01-ai-prompt-manager/02-ideation-deep-dive.md
• Adoption recommendations: _ideation/01-ai-prompt-manager/04-deep-dive-review.md
• Key files: ast-parser.ts:799, shape-extractor.ts, reference.ts, context-formatter.ts

[darko-mijic]

claude-new-convex-es-1a2e42f0 (1).md