Generate a Sequence Diagram from Code

Draft a PlantUML or Mermaid sequence diagram from the message-call patterns in a slice of the codebase, returning source text to review and then save with diagrams_create.

Static call-site order is not runtime order. This tool reads call sites in the order a reader meets them and says so in every result: a call inside a callback, promise, or listener is counted in deferred_count and excluded from the messages, because its real position in the conversation is unknowable from source.

It is the generative flip side of the consistency checker's ordered call graph: the same caller-to-callee evidence, turned into a starter diagram instead of a verdict. It never writes: nothing lands in the diagrams directory without an explicit diagrams_create call.

Each sender is the file containing the call site even when another file declares the same caller name. Callee mapping uses case-insensitive declared-identifier equality and the first declaring participant in file order. A callee that no file in the scope declares is reported in unresolved_callees, never attached to an invented participant. Which class owns a method is a type question, and out of scope.

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_participants (integer 1-20, default 8): Hard cap on declared participants

• max_messages (integer 1-50, default 20): Hard cap on emitted messages

• include_call_parentheses (boolean, default false): When true, emitted message labels append '()' in both dialects; structured messages.message values stay bare

Returns: JSON with schema: { "scope": string, // POSIX path as resolved, "." for the project root "format": "puml" | "mermaid", "source": string, // the generated sequence; identical to the text block (message labels carry '()' when include_call_parentheses is true) "participants": string[], // participant names as emitted, in first-conversation order, capped "participants_included": number, // length of "participants" "participants_available": number,// distinct participants in candidate messages, may exceed the cap "participants_capped": boolean, // true when participants were dropped by the cap "participant_limit": number, // the applied cap (max_participants, at most 20) "messages": [ // ordered call sites, one per sequenced call (message stays bare when include_call_parentheses is true) { "from": string, "to": string, "message": string, "line": number, "via_callback": false } ], "messages_included": number, "messages_available": number, // candidate messages, may exceed the cap "messages_capped": boolean, // true when messages were dropped by either cap "message_limit": number, // the applied cap (max_messages, at most 50) "deferred_count": number, // call sites inside callbacks/promises: counted, never sequenced "unresolved_callees": string[], // callees no participant in the scope declares "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 "confidence": "heuristic", "heuristic_warning": string, // what static call order 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: "Show the call flow between the checkout and payment modules" -> scope="src/checkout"

• Use when: "Draft a Mermaid sequence for this service layer" -> scope="src/services", format="mermaid"

• Don't use when: You need runtime ordering, async semantics, or which class a method belongs to (out of scope; deferred and unresolved calls are reported instead)

• Don't use when: You want a class diagram (use diagrams_generate) or a hand-written skeleton (write the source directly)

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: participants and messages are empty, and the emitted source is a valid empty diagram

• 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