Generate a Class Diagram from Code

Draft a PlantUML or Mermaid class diagram from a slice of the codebase, returning source text to review and then save with diagrams_create.

This is the generative flip side of diagrams_check_consistency: the same code-reading machinery that detects drift can seed the diagram in the first place. It reads class/interface/enum/type/function declarations under the requested scope and emits one box per declared name, plus extends/implements edges when the TypeScript AST can evidence them. It never writes: nothing lands in the diagrams directory without an explicit diagrams_create call.

It is a heuristic (name extraction, not full type modeling) and says so in every result: member lists, generics, package nesting, and cross-file inheritance through re-exports are out of scope, and a scope without TypeScript-family files yields entities with no relations.

Args:

• scope (string, default "."): Relative path under the project root pointing at a file or a directory. Absolute paths and anything resolving outside the project root are refused

• format ('puml' | 'mermaid', default 'puml'): Output dialect

• max_entities (integer 1-60, default 30): Hard cap on emitted declarations

• include_relations (boolean, default true): Emit extends/implements edges when evidence is available

Returns: JSON with schema: { "scope": string, // POSIX path as resolved, "." for the project root "format": "puml" | "mermaid", "source": string, // the generated diagram; identical to the text block "entities": string[], // declared names in emission order, capped "entities_included": number, // length of "entities" "entities_available": number, // distinct names found, may exceed the cap "entities_capped": boolean, // true when names were dropped by the cap "entity_limit": number, // the applied cap (max_entities, at most 60) "relations": [ // evidenced edges only; empty when evidence is unavailable { "from": string, "to": string, "kind": "extends" | "implements" } ], "relations_included": number, "relations_available": number, "relations_capped": boolean, // true when edges were dropped by the cap or by an entity the cap removed "relation_limit": number, // 60 "files_scanned": number, "truncated": boolean, // true when the 5,000-file scan cap was reached "scan_limit": number, // 5,000 "scan_warning": string | null, // human-readable warning when truncated, otherwise null "dialect_note": string | null, // non-null when relations are unavailable or the scope has no code files "confidence": "heuristic", "heuristic_warning": string, // what name extraction can and cannot tell you "written": false // always false; save with diagrams_create }

Every cap reports itself in-band, so a truncated or capped result is never silent.

Examples:

• Use when: "Draft a class diagram for the services layer" -> scope="src/services"

• Use when: "Give me a Mermaid starter for this module" -> scope="src/models", format="mermaid"

• Don't use when: You want a hand-written skeleton instead of one read from code (write the source directly, or use diagrams_create)

• Don't use when: You expect semantic accuracy (member types, generics, or resolved cross-file inheritance); this is a heuristic draft

Error Handling:

• Returns "Error: Refused to resolve scope outside the project root: ''" when scope is absolute or resolves outside the project root; no file is read

• A scope with no code files is not an error: entities is empty with a dialect_note explaining why

• Emitted source always passes the same syntax gate diagrams_create enforces; an emission that cannot is reported as an unexpected internal error

• Unexpected internal failures return a generic "Error: Unexpected internal error ..." with isError:true and are logged to stderr without source, paths, or secrets