docs(mermaid): give every subpackage an example for every symbol - #175
Conversation
📝 WalkthroughWalkthroughExpanded executable Mermaid examples across subpackages. The contract test now discovers all ChangesMermaid example coverage
Estimated code review effort: 4 (Complex) | ~45 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
nao1215
changed the title
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
er, radar, sankey, timeline and treemap each had one example, of a whole diagram, for between six and eleven exported symbols. pkg.go.dev puts an example under the symbol it is named for, so a reader looking at Leaf or Curve or Link saw nothing. Each symbol now has one, output verified, and each says something the signature does not: that a treemap section carries no value of its own, that a radar curve gives its values in the order the axes were declared, that a sankey node exists because a link names it. The examples every builder shares, Build and Error and LF and String and the options, are worded the same way across the five, because they do the same thing and a reader moving between packages should not have to work out whether a difference in wording means a difference in behavior. Every attribute in the er examples carries a comment. One without leaves a trailing space on its line, and a godoc Output block cannot hold trailing whitespace, so the alternative was an example that could not be verified. The audit added with the root examples now covers these five as well. Refs #131
mindmap, packet, piechart and userjourney join the five from the last commit. Each example says something the signature does not: that a mindmap Child descends and Sibling does not, that a packet Field takes a range inclusive at both ends while Next takes a width, that a pie chart label and value can be whole or fractional, that a user journey task needs a section and its actors are optional. The audit now covers nine of the twenty two subpackages. Refs #131
Twelve of the twenty two subpackages are covered now. The arch examples carry the warning the package documentation gives at more length: a title there takes only letters, digits, underscores and spaces, mermaid refuses the whole diagram when it finds anything else, and there is no escape to reach for. A reader copying an example is exactly the person who needs to know. Each of the others says something the signature does not: that an xy chart axis is either named points or a measured scale, that a chart may carry a line and bars at once, that a kanban board needs a column before any card, and that a ticket becomes a link only when the board has a base URL to prefix it with. Refs #131
Fourteen of the twenty two subpackages are covered now. The state examples take the composite state builder seriously, because it is the one construct in this library where the chain changes what it is building halfway through: CompositeState returns an inner diagram and End hands the outer one back. Each of its methods has an example of its own, and so does the builder type, since a reader who lands on it from pkg.go.dev has no other way to see where End goes. The gitgraph examples name every commit that a later call refers to. A cherry pick and a reset take an id, and an example that lets mermaid generate one would show a reader nothing they could copy. Refs #131
Fifteen of the twenty two subpackages are covered now. block has the widest surface of the ones done so far, most of it free functions rather than methods: a row is built from tokens, and Node, Space, Literal and the seven arrows are each one. Those are what a reader lands on from pkg.go.dev, and each now shows a row it belongs in rather than the token alone, because a token on its own is not a diagram. Refs #131
Sixteen of the twenty two subpackages are covered now. flowchart is fifteen node shapes and nine kinds of link, and the name of a method is not enough to picture what it draws: an asymmetric node is a flag, a rhombus is how a decision is usually drawn, a trapezoid comes two ways up. Each example says which, next to the mermaid it produces. The invisible link gets its own note, because a reader who finds it without one would reasonably wonder what a link nobody can see is for: it pushes a diagram into the layout its author wants without saying anything untrue about the flow. Refs #131
Seventeen of the twenty two subpackages are covered now. The boundary examples are the ones worth having here: a boundary is a pair of calls rather than a nested builder, and the pairing is invisible in the signature. Boundary, EnterpriseBoundary and SystemBoundary each show where BoundaryEnd goes, SystemBoundary shows two of them nested, and BoundaryEnd shows what falls outside one. Refs #131
Nineteen of the twenty two subpackages are covered now. gantt is the same task written sixteen ways, four states crossed with critical or not and with an identifier or not, and the difference between them is invisible in the names alone: an active task is drawn hatched, a done one filled in, a critical one red. Each example says which, and the WithID ones say what an identifier is for, which is that a later task can start when this one finishes. The option examples say what each one is actually for rather than restating its name: a date format is not an axis format, a today marker can be turned off outright, and excluded days change where a duration ends. Refs #131
…a mindmap one Twenty of the twenty two subpackages are covered now. The requirement examples were written twice. The first set called Requirement with an id alone, which the builder records as an error and writes nothing for, so every one of them printed an empty document and matched an empty Output block. They passed while documenting nothing. The audit is what found it, once this branch was rebased onto the commit that added it: an example whose output is empty does not count as documenting its symbol, because that is the rule godoc applies too. The mindmap LF example had the same fault from calling Root twice, and is fixed here as well. So the requirement examples now carry all four fields a requirement needs, which is the thing about this package a reader most needs to see: an id, the text, a risk and a verify method, or the block is not written at all. Refs #131
Every package in the module is covered now, and the audit lists them all rather than the handful it started with. Two faults turned up while finishing, both of the same kind: an example that builds nothing prints nothing, and an empty Output block matches that happily. The requirement examples called Requirement with an id alone, which the builder records as an error, and the mindmap LF example called Root twice. Both passed while documenting nothing. The audit is what found them, once this branch was rebased onto the commit that added it: an example whose output is empty does not count as documenting its symbol, which is the rule godoc applies too. So the requirement examples now carry all four fields a requirement needs, which is the thing about that package a reader most needs to see. 673 examples run across the module, none of them with an empty output. Closes #131
d0e8d33 to
4ec5f24
Compare
nao1215
changed the title
Code Metrics Report
Details | | main (9c02de6) | #175 (bef60b0) | +/- |
|---------------------|----------------|----------------|------|
| Coverage | 96.4% | 96.4% | 0.0% |
| Files | 79 | 79 | 0 |
| Lines | 3302 | 3302 | 0 |
| Covered | 3186 | 3186 | 0 |
- | Test Execution Time | 7s | 10s | +3s |Reported by octocov |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 11
🧹 Nitpick comments (5)
mermaid/requirement/examples_test.go (1)
60-77: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winRemove the duplicated
WithTextoption.Each of these examples passes
requirement.WithText("The system shall log a user in.")twice: once in the third position and again as the final option.WithTextassignsc.text, so the second call is a no-op and the output is unchanged. The duplication appears in godoc and shows readers a redundant call pattern.The same duplication appears in
ExampleDiagram_FunctionalRequirement,ExampleDiagram_InterfaceRequirement,ExampleDiagram_PerformanceRequirement,ExampleDiagram_PhysicalRequirement,ExampleDiagram_DesignConstraint,ExampleDiagram_Contains,ExampleDiagram_Copies,ExampleDiagram_Derives,ExampleDiagram_Satisfies,ExampleDiagram_Verifies,ExampleDiagram_Refines,ExampleDiagram_Traces, and all sevenExampleSourceRelationBuilder_*examples.♻️ Proposed fix for `ExampleDiagram_Requirement`
_ = requirement.NewDiagram(os.Stdout). Requirement("The system shall log in", requirement.WithID("1"), requirement.WithText("The system shall log a user in."), requirement.WithRisk(requirement.RiskMedium), - requirement.WithVerifyMethod(requirement.VerifyMethodTest), requirement.WithText("The system shall log a user in.")). + requirement.WithVerifyMethod(requirement.VerifyMethodTest)). Build()Apply the same removal in each listed example.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@mermaid/requirement/examples_test.go` around lines 60 - 77, Remove the duplicate final requirement.WithText option from ExampleDiagram_Requirement and every listed ExampleDiagram_* and ExampleSourceRelationBuilder_* example, retaining the first WithText call and preserving all other options and output.mermaid/class/examples_test.go (1)
643-671: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value
ExampleDiagram_ClassDefandExampleDiagram_CSSClassare identical.Both examples build the same chain and print the same output. Godoc requires one example per symbol, so both must exist. Make the
ClassDefexample apply the named style to two classes. The difference between defining a style and applying it then becomes visible.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@mermaid/class/examples_test.go` around lines 643 - 671, Update ExampleDiagram_ClassDef to define and apply the named style to two distinct classes, while keeping ExampleDiagram_CSSClass focused on applying the style to one class. Adjust the ClassDef example’s builder chain and expected output so both classes and their CSS class assignments are visible.mermaid/kanban/examples_test.go (1)
268-285: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value
ExampleWithTaskTicketandExampleWithTicketBaseURLare identical.Both examples build the same chain and print the same output. Only the doc comments differ. Change one so each shows what its own option controls. For example, drop
WithTicketBaseURLfromExampleWithTaskTicketto show the bare ticket attribute.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@mermaid/kanban/examples_test.go` around lines 268 - 285, Update ExampleWithTaskTicket so it demonstrates only WithTaskTicket by removing WithTicketBaseURL from its diagram-building chain and adjusting the expected output to omit the ticketBaseUrl configuration, while preserving the ticket attribute on the task. Keep ExampleWithTicketBaseURL focused on its own option.mermaid/block/examples_test.go (1)
541-554: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueShow every shape, or narrow the wording.
The comment states the example shows the shapes a block can be drawn as. The example shows
ShapeRound,ShapeStadiumandShapeRhombusonly.ShapeCylinderis used at line 34 and is not shown here. Add the remaining shapes, or change the wording to "some of the shapes".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@mermaid/block/examples_test.go` around lines 541 - 554, Update the ExampleShape comment to say it demonstrates some of the shapes a block can be drawn as, since it only includes ShapeRound, ShapeStadium, and ShapeRhombus.mermaid/gitgraph/examples_test.go (1)
393-414: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueOption-type examples pass empty slices. Both examples declare an empty option slice, so no option changes the rendered output and the example shows nothing about the type it documents.
mermaid/gitgraph/examples_test.go#L393-L414: putgitgraph.WithCherryPickParent(...)inoptionsand update the// Output:block to include theparent:attribute.mermaid/er/examples_test.go#L348-L362: populateoptionswith an exportederoption constructor if one exists; if the package exports none, say so in the comment.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@mermaid/gitgraph/examples_test.go` around lines 393 - 414, The option-type examples currently pass empty slices and do not demonstrate their documented options. In mermaid/gitgraph/examples_test.go lines 393-414, update ExampleCherryPickOption to include gitgraph.WithCherryPickParent(...) in options and revise the expected output with the resulting parent attribute; in mermaid/er/examples_test.go lines 348-362, populate the example’s options using an exported er option constructor if available, otherwise state in the comment that no exported option constructor exists.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@contract_test.go`:
- Around line 1627-1631: Update the package discovery logic in exportedSymbols
to use os.ReadDir("mermaid") instead of filepath.Glob("mermaid/*"), append only
entries whose IsDir() is true, and preserve the existing error handling and
inclusion of the current directory ".".
In `@mermaid/class/examples_test.go`:
- Around line 906-922: Update ExampleRelationship to use one reverse
relationship constant, preferably replacing one existing forward Relation call
with RelationshipInheritanceReverse, and adjust the expected // Output block to
match the resulting reversed arrow. Keep the example demonstrating the remaining
forward relationship types.
In `@mermaid/flowchart/examples_test.go`:
- Around line 370-379: Update the comment above ExampleWithOrientalTopDown to
state that WithOrientalTopDown selects Mermaid’s TD orientation and that the
package default is TB, rather than claiming TD is the default; leave the example
implementation and expected output unchanged.
In `@mermaid/gitgraph/examples_test.go`:
- Around line 95-104: The Error examples use invalid-looking inputs while
expecting nil errors, which is misleading. In mermaid/gitgraph/examples_test.go
lines 95-104, update ExampleDiagram_Error to use a valid checkout chain or
explicitly state that branch names are not validated; in
mermaid/state/examples_test.go lines 93-102, update the corresponding state
example to use a valid State input or explicitly state that state identifiers
are not validated.
In `@mermaid/kanban/examples_test.go`:
- Around line 220-239: Update ExampleDiagram_TaskIn to make TaskIn reuse the
previously declared “Todo” and “Done” columns instead of emitting duplicate
headers; ensure each column is listed once with its matching task beneath it,
preserving the declaration order.
In `@mermaid/quadrant/examples_test.go`:
- Around line 315-323: The examples must exercise rejected chart inputs instead
of valid chains that produce nil errors. In mermaid/quadrant/examples_test.go
lines 315-323, update ExampleChart_Error to use a Point input rejected by the
quadrant chart and change the expected output to its concrete error message; in
mermaid/radar/examples_test.go lines 94-103, update the corresponding Error
example to use an input rejected by the radar chart rather than Curve without
Axis, and update its output accordingly.
In `@mermaid/sequence/examples_test.go`:
- Around line 804-814: Update the rendering flow used by NewDiagram, String, and
Build so every configured sequence option, including WithMirrorActors, is
reflected in the generated Mermaid output rather than serializing only d.body.
Ensure ExampleWithMirrorActors verifies the resulting configuration-specific
output, or remove options and their examples if they cannot be rendered.
- Around line 244-286: Update AsyncRequestWithActivation,
AsyncRequestfWithActivation, AsyncResponseWithActivation, and
AsyncResponsefWithActivation to emit asynchronous arrow tokens ->)+ and --)-
instead of synchronous ->>+ and -->>-. Update the corresponding example expected
outputs in ExampleDiagram_AsyncRequestWithActivation,
ExampleDiagram_AsyncRequestfWithActivation,
ExampleDiagram_AsyncResponseWithActivation, and
ExampleDiagram_AsyncResponsefWithActivation, along with the golden output.
In `@mermaid/state/examples_test.go`:
- Around line 519-535: Update ExampleDiagram_Concurrent and the underlying
Concurrent/composite-state rendering flow so the concurrency separator is
emitted inside the Running composite state before CompositeStateBuilder.End
closes it. Use Mermaid’s required separator syntax `--` and update the example’s
expected output accordingly.
In `@mermaid/timeline/examples_test.go`:
- Around line 170-187: Update the documentation comment for
ExampleDiagram_Section to describe the actual behavior shown by the other
examples: periods may be added before any section and are rendered without an
error; sections group subsequent periods when present. Remove the claims that a
section is required first and that Build reports an error for unsectioned
periods.
In `@mermaid/userjourney/examples_test.go`:
- Around line 209-228: Remove the initial Section("Browse") and
Section("Checkout") calls from ExampleDiagram_TaskIn, leaving the chained TaskIn
calls to create each target section as needed. Update the example output to
match the resulting diagram without empty sections.
---
Nitpick comments:
In `@mermaid/block/examples_test.go`:
- Around line 541-554: Update the ExampleShape comment to say it demonstrates
some of the shapes a block can be drawn as, since it only includes ShapeRound,
ShapeStadium, and ShapeRhombus.
In `@mermaid/class/examples_test.go`:
- Around line 643-671: Update ExampleDiagram_ClassDef to define and apply the
named style to two distinct classes, while keeping ExampleDiagram_CSSClass
focused on applying the style to one class. Adjust the ClassDef example’s
builder chain and expected output so both classes and their CSS class
assignments are visible.
In `@mermaid/gitgraph/examples_test.go`:
- Around line 393-414: The option-type examples currently pass empty slices and
do not demonstrate their documented options. In
mermaid/gitgraph/examples_test.go lines 393-414, update ExampleCherryPickOption
to include gitgraph.WithCherryPickParent(...) in options and revise the expected
output with the resulting parent attribute; in mermaid/er/examples_test.go lines
348-362, populate the example’s options using an exported er option constructor
if available, otherwise state in the comment that no exported option constructor
exists.
In `@mermaid/kanban/examples_test.go`:
- Around line 268-285: Update ExampleWithTaskTicket so it demonstrates only
WithTaskTicket by removing WithTicketBaseURL from its diagram-building chain and
adjusting the expected output to omit the ticketBaseUrl configuration, while
preserving the ticket attribute on the task. Keep ExampleWithTicketBaseURL
focused on its own option.
In `@mermaid/requirement/examples_test.go`:
- Around line 60-77: Remove the duplicate final requirement.WithText option from
ExampleDiagram_Requirement and every listed ExampleDiagram_* and
ExampleSourceRelationBuilder_* example, retaining the first WithText call and
preserving all other options and output.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 059aaadb-58e3-4ebc-abe5-1888080cecb1
📒 Files selected for processing (23)
contract_test.gomermaid/arch/examples_test.gomermaid/block/examples_test.gomermaid/c4/examples_test.gomermaid/class/examples_test.gomermaid/er/examples_test.gomermaid/flowchart/examples_test.gomermaid/gantt/examples_test.gomermaid/gitgraph/examples_test.gomermaid/kanban/examples_test.gomermaid/mindmap/examples_test.gomermaid/packet/examples_test.gomermaid/piechart/examples_test.gomermaid/quadrant/examples_test.gomermaid/radar/examples_test.gomermaid/requirement/examples_test.gomermaid/sankey/examples_test.gomermaid/sequence/examples_test.gomermaid/state/examples_test.gomermaid/timeline/examples_test.gomermaid/treemap/examples_test.gomermaid/userjourney/examples_test.gomermaid/xychart/examples_test.go
| packages, err := filepath.Glob("mermaid/*") | ||
| if err != nil { | ||
| t.Fatalf("list the mermaid subpackages: %v", err) | ||
| } | ||
| packages = append(packages, ".") |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: List non-directory entries directly under mermaid/.
fd --max-depth 1 --type f . mermaidRepository: nao1215/markdown
Length of output: 154
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- target context ---'
sed -n '1590,1655p' contract_test.go
printf '%s\n' '--- mermaid entries ---'
find mermaid -maxdepth 2 -mindepth 1 -printf '%y %p\n' 2>/dev/null | sort
printf '%s\n' '--- exportedSymbols and ParseDir references ---'
rg -n -C 4 'exportedSymbols|ParseDir|filepath\.Glob\("mermaid/\*"\)' --glob '*.go' .Repository: nao1215/markdown
Length of output: 9565
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- helper implementation ---'
sed -n '1688,1735p' contract_test.go
printf '%s\n' '--- imports used by the proposed fix ---'
sed -n '1,90p' contract_test.go
printf '%s\n' '--- standalone glob and ParseDir behavior ---'
tmpdir=$(mktemp -d)
trap 'rm -rf "$tmpdir"' EXIT
mkdir -p "$tmpdir/mermaid/pkg"
: > "$tmpdir/mermaid/README.md"
cat > "$tmpdir/probe.go" <<'EOF'
package main
import (
"fmt"
"go/parser"
"go/token"
"os"
"path/filepath"
)
func main() {
root := os.Args[1]
matches, err := filepath.Glob(filepath.Join(root, "mermaid/*"))
if err != nil {
panic(err)
}
fmt.Printf("glob matches: %v\n", matches)
for _, path := range matches {
_, err := parser.ParseDir(token.NewFileSet(), path, nil, parser.ParseComments)
fmt.Printf("ParseDir(%s): %v\n", path, err)
}
}
EOF
if command -v go >/dev/null 2>&1; then
go run "$tmpdir/probe.go" "$tmpdir"
else
printf '%s\n' 'go is unavailable'
fiRepository: nao1215/markdown
Length of output: 5041
Filter filepath.Glob results to directories.
filepath.Glob("mermaid/*") also matches files. exportedSymbols passes each match to parser.ParseDir, which fails for a file path. Use os.ReadDir("mermaid") and append only entries where entry.IsDir() is true.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@contract_test.go` around lines 1627 - 1631, Update the package discovery
logic in exportedSymbols to use os.ReadDir("mermaid") instead of
filepath.Glob("mermaid/*"), append only entries whose IsDir() is true, and
preserve the existing error handling and inclusion of the current directory ".".
| // ExampleRelationship shows the lines two classes can be joined with. Each has | ||
| // a reverse, which points the same relationship the other way. | ||
| func ExampleRelationship() { | ||
| _ = class.NewDiagram(os.Stdout). | ||
| Relation("Order", class.RelationshipInheritance, "Document"). | ||
| Relation("Order", class.RelationshipComposition, "LineItem"). | ||
| Relation("Order", class.RelationshipAggregation, "Coupon"). | ||
| Relation("Order", class.RelationshipDependency, "Clock"). | ||
| Build() | ||
|
|
||
| // Output: | ||
| // classDiagram | ||
| // Order <|-- Document | ||
| // Order *-- LineItem | ||
| // Order o-- Coupon | ||
| // Order ..> Clock | ||
| } |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Show a reverse relationship, or drop the claim.
The comment states each relationship has a reverse. The example shows only forward constants. RelationshipInheritanceReverse exists in mermaid/class/relationship.go. Add one reverse constant so the output demonstrates the claim.
♻️ Proposed change
_ = class.NewDiagram(os.Stdout).
Relation("Order", class.RelationshipInheritance, "Document").
+ Relation("Order", class.RelationshipInheritanceReverse, "Receipt").
Relation("Order", class.RelationshipComposition, "LineItem").Update the // Output: block to match.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@mermaid/class/examples_test.go` around lines 906 - 922, Update
ExampleRelationship to use one reverse relationship constant, preferably
replacing one existing forward Relation call with
RelationshipInheritanceReverse, and adjust the expected // Output block to match
the resulting reversed arrow. Keep the example demonstrating the remaining
forward relationship types.
| // ExampleWithOrientalTopDown lays the flowchart out from the top downwards, which is the default. | ||
| func ExampleWithOrientalTopDown() { | ||
| _ = flowchart.NewFlowchart(os.Stdout, flowchart.WithOrientalTopDown()). | ||
| NodeWithText("A", "Start"). | ||
| Build() | ||
|
|
||
| // Output: | ||
| // flowchart TD | ||
| // A["Start"] | ||
| } |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Correct the default-orientation claim.
The comment states that top-down is the default. Examples in this file that pass no orientation option emit flowchart TB (see lines 64 and 437), not flowchart TD. WithOrientalTopDown emits TD. Mermaid treats TD and TB as the same layout, but the package default is TB.
📝 Proposed comment fix
-// ExampleWithOrientalTopDown lays the flowchart out from the top downwards, which is the default.
+// ExampleWithOrientalTopDown lays the flowchart out from the top downwards.
+// Mermaid treats TD and TB as the same layout. Without an orientation option
+// the package emits TB.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| // ExampleWithOrientalTopDown lays the flowchart out from the top downwards, which is the default. | |
| func ExampleWithOrientalTopDown() { | |
| _ = flowchart.NewFlowchart(os.Stdout, flowchart.WithOrientalTopDown()). | |
| NodeWithText("A", "Start"). | |
| Build() | |
| // Output: | |
| // flowchart TD | |
| // A["Start"] | |
| } | |
| // ExampleWithOrientalTopDown lays the flowchart out from the top downwards. | |
| // Mermaid treats TD and TB as the same layout. Without an orientation option | |
| // the package emits TB. | |
| func ExampleWithOrientalTopDown() { | |
| _ = flowchart.NewFlowchart(os.Stdout, flowchart.WithOrientalTopDown()). | |
| NodeWithText("A", "Start"). | |
| Build() | |
| // Output: | |
| // flowchart TD | |
| // A["Start"] | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@mermaid/flowchart/examples_test.go` around lines 370 - 379, Update the
comment above ExampleWithOrientalTopDown to state that WithOrientalTopDown
selects Mermaid’s TD orientation and that the package default is TB, rather than
claiming TD is the default; leave the example implementation and expected output
unchanged.
| // ExampleDiagram_Error reports the same error Build does, for code that wants | ||
| // to look before writing anything. | ||
| func ExampleDiagram_Error() { | ||
| d := gitgraph.NewDiagram(io.Discard). | ||
| Checkout("never-branched") | ||
| fmt.Println("error:", d.Error()) | ||
|
|
||
| // Output: | ||
| // error: <nil> | ||
| } |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Error examples pass invalid-looking input but print <nil>. Each example feeds input that reads as invalid, then prints error: <nil>. A reader can conclude the expected output is wrong rather than that the package performs no validation on that input.
mermaid/gitgraph/examples_test.go#L95-L104: replaceCheckout("never-branched")with a valid chain, or add a sentence stating that the package does not validate branch names.mermaid/state/examples_test.go#L93-L102: replaceState("", "")with a valid state, or add a sentence stating that the package does not validate state identifiers.
📍 Affects 2 files
mermaid/gitgraph/examples_test.go#L95-L104(this comment)mermaid/state/examples_test.go#L93-L102
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@mermaid/gitgraph/examples_test.go` around lines 95 - 104, The Error examples
use invalid-looking inputs while expecting nil errors, which is misleading. In
mermaid/gitgraph/examples_test.go lines 95-104, update ExampleDiagram_Error to
use a valid checkout chain or explicitly state that branch names are not
validated; in mermaid/state/examples_test.go lines 93-102, update the
corresponding state example to use a valid State input or explicitly state that
state identifiers are not validated.
| // ExampleDiagram_TaskIn adds a card to a column named outright, which saves | ||
| // switching back and forth when the cards of two columns are interleaved in the | ||
| // calling code. | ||
| func ExampleDiagram_TaskIn() { | ||
| _ = kanban.NewDiagram(os.Stdout). | ||
| Column("Todo"). | ||
| Column("Done"). | ||
| TaskIn("Todo", "Write the spec"). | ||
| TaskIn("Done", "Read the spec"). | ||
| Build() | ||
|
|
||
| // Output: | ||
| // kanban | ||
| // [Todo] | ||
| // [Done] | ||
| // [Todo] | ||
| // [Write the spec] | ||
| // [Done] | ||
| // [Read the spec] | ||
| } |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Inspect TaskIn rendering and any column tracking in the kanban package.
rg -nP --type=go -C6 'func \(d \*Diagram\) (TaskIn|Column|Task)\(' mermaid/kanbanRepository: nao1215/markdown
Length of output: 2252
🏁 Script executed:
#!/bin/bash
sed -n '120,330p' mermaid/kanban/kanban.go
printf '\n--- examples and related tests ---\n'
sed -n '180,260p' mermaid/kanban/examples_test.go
rg -n -C4 'TaskIn|currentColumn|columns' mermaid/kanban --type=goRepository: nao1215/markdown
Length of output: 12976
🏁 Script executed:
#!/bin/bash
printf '%s\n' '--- TaskIn test ---'
sed -n '145,185p' mermaid/kanban/kanban_test.go
printf '%s\n' '--- kanban documentation and examples ---'
rg -n -i -C3 'kanban|TaskIn|column' README.md mermaid docs 2>/dev/null | head -240
printf '%s\n' '--- source-level behavior probe ---'
python3 - <<'PY'
from pathlib import Path
p = Path("mermaid/kanban/kanban.go").read_text()
start = p.index("func (d *Diagram) TaskIn")
end = p.index("\n}\n", start) + 2
chunk = p[start:end]
print(chunk)
assert "if d.currentColumn != trimmedColumn" in chunk
assert "d.Column(trimmedColumn)" in chunk
assert "return d.Task(task, opts...)" in chunk
print("TaskIn emits Column when the target differs from currentColumn.")
PYRepository: nao1215/markdown
Length of output: 13228
🌐 Web query:
Mermaid Kanban syntax repeated column header same column or additional column
💡 Result:
In Mermaid Kanban syntax, each column must be defined with a unique identifier [1][2]. Attempting to reuse the same column identifier for multiple sections of a board is not supported and will likely result in rendering errors or unexpected behavior, as the diagram structure relies on tasks being uniquely nested under specific, distinct column identifiers [3]. To structure a Kanban board correctly: 1. Define each stage as a unique column using the format columnId[Column Title] [1][3]. 2. List tasks under their respective columns with proper indentation [3]. 3. Ensure every task also has a unique identifier taskId[Task Description] to avoid conflicts [1][2]. If you need to represent a workflow where tasks might appear in similar-sounding stages, you must assign each stage a distinct identifier even if they share similar titles [3]. For example: kanban col1[Todo] task1[Task A] col2[In Progress] task2[Task B] col3[Todo Again] task3[Task C] There is no native syntax in Mermaid Kanban to implicitly merge or repeat column headers; each column definition is treated as a discrete container within the diagram's layout [1][3].
Citations:
- 1: https://github.com/mermaid-js/mermaid/blob/f0ffb41c/docs/syntax/kanban.md
- 2: https://mermaid.ai/open-source/syntax/kanban.html
- 3: https://www.mintlify.com/mermaid-js/mermaid/diagrams/kanban
🏁 Script executed:
#!/bin/bash
python3 - <<'PY'
import urllib.request
url = "https://raw.githubusercontent.com/mermaid-js/mermaid/f0ffb41c/docs/syntax/kanban.md"
try:
text = urllib.request.urlopen(url, timeout=10).read().decode()
except Exception as e:
print(f"fetch failed: {e}")
else:
lines = text.splitlines()
for i, line in enumerate(lines, 1):
if "column" in line.lower() or "unique" in line.lower() or "kanban" in line.lower():
lo, hi = max(1, i - 2), min(len(lines), i + 3)
print(f"--- lines {lo}-{hi} ---")
for n in range(lo, hi + 1):
print(f"{n}: {lines[n-1]}")
PYRepository: nao1215/markdown
Length of output: 303
Make TaskIn reuse existing columns. Each repeated header creates a separate Mermaid column, so this output does not add tasks to the declared columns. Emit each column header once and place both tasks under their matching column.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@mermaid/kanban/examples_test.go` around lines 220 - 239, Update
ExampleDiagram_TaskIn to make TaskIn reuse the previously declared “Todo” and
“Done” columns instead of emitting duplicate headers; ensure each column is
listed once with its matching task beneath it, preserving the declaration order.
| // ExampleDiagram_AsyncRequestWithActivation draws an asynchronous call that turns the bar on. | ||
| func ExampleDiagram_AsyncRequestWithActivation() { | ||
| _ = sequence.NewDiagram(os.Stdout). | ||
| AsyncRequestWithActivation("Alice", "Bob", "Start the job"). | ||
| Build() | ||
|
|
||
| // Output: | ||
| // sequenceDiagram | ||
| // Alice->>+Bob: Start the job | ||
| } | ||
|
|
||
| // ExampleDiagram_AsyncRequestfWithActivation draws the same from a format string. | ||
| func ExampleDiagram_AsyncRequestfWithActivation() { | ||
| _ = sequence.NewDiagram(os.Stdout). | ||
| AsyncRequestfWithActivation("Alice", "Bob", "Start job %d", 7). | ||
| Build() | ||
|
|
||
| // Output: | ||
| // sequenceDiagram | ||
| // Alice->>+Bob: Start job 7 | ||
| } | ||
|
|
||
| // ExampleDiagram_AsyncResponseWithActivation draws an asynchronous reply that turns the bar off. | ||
| func ExampleDiagram_AsyncResponseWithActivation() { | ||
| _ = sequence.NewDiagram(os.Stdout). | ||
| AsyncResponseWithActivation("Bob", "Alice", "Job finished"). | ||
| Build() | ||
|
|
||
| // Output: | ||
| // sequenceDiagram | ||
| // Bob-->>-Alice: Job finished | ||
| } | ||
|
|
||
| // ExampleDiagram_AsyncResponsefWithActivation draws the same from a format string. | ||
| func ExampleDiagram_AsyncResponsefWithActivation() { | ||
| _ = sequence.NewDiagram(os.Stdout). | ||
| AsyncResponsefWithActivation("Bob", "Alice", "Job %d finished", 7). | ||
| Build() | ||
|
|
||
| // Output: | ||
| // sequenceDiagram | ||
| // Bob-->>-Alice: Job 7 finished | ||
| } |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Compare arrow tokens used by async and async-with-activation methods.
rg -nP --type=go -C4 'func \(d \*Diagram\) Async(Request|Response)f?(WithActivation)?\(' mermaid/sequenceRepository: nao1215/markdown
Length of output: 4089
🏁 Script executed:
#!/bin/bash
set -e
printf '%s\n' '--- activation methods ---'
sed -n '1,90p' mermaid/sequence/activation.go
printf '%s\n' '--- related examples ---'
sed -n '190,300p' mermaid/sequence/examples_test.go
printf '%s\n' '--- arrow syntax references ---'
rg -n --type=go --glob='*.md' --glob='*.go' -- '->\)|--\)|->>\+|-->>-|WithActivation' mermaid/sequence
printf '%s\n' '--- structural token comparison ---'
python3 - <<'PY'
from pathlib import Path
import re
files = [Path("mermaid/sequence/sequence.go"), Path("mermaid/sequence/activation.go")]
text = "\n".join(p.read_text() for p in files)
patterns = {
"AsyncRequest": r'func \(d \*Diagram\) AsyncRequest\(.*?\n\}',
"AsyncResponse": r'func \(d \*Diagram\) AsyncResponse\(.*?\n\}',
"AsyncRequestWithActivation": r'func \(d \*Diagram\) AsyncRequestWithActivation\(.*?\n\}',
"AsyncResponseWithActivation": r'func \(d \*Diagram\) AsyncResponseWithActivation\(.*?\n\}',
}
for name, pattern in patterns.items():
match = re.search(pattern, text, re.S)
if not match:
raise SystemExit(f"missing {name}")
body = match.group()
token = re.search(r'"(\s*%s?[^"]*)"' % "", body)
arrows = re.findall(r'->\)?\+?|-->\)?-?|\-\->\)?-?', body)
print(f"{name}: {arrows} | {body.splitlines()[1].strip()}")
PYRepository: nao1215/markdown
Length of output: 16798
🌐 Web query:
Mermaid sequence diagram asynchronous arrow activation syntax ->) + --) -
💡 Result:
In Mermaid sequence diagrams, asynchronous messages and activation markers are controlled by specific arrow syntax [1][2][3]. Asynchronous Message Syntax Asynchronous messages are represented using open-arrow heads [1][4][5]. - Solid asynchronous arrow: -) [1][4][6] - Dotted asynchronous arrow: --) [1][4][6] Activation/Deactivation Syntax You can manage lifeline activations concisely by appending + or - to your message arrows, which eliminates the need for separate activate and deactivate statements [2][3]. - Activate the target: Append + to the arrow (e.g., A->>+B) [2][7][3]. - Deactivate the source: Append - to the arrow (e.g., A->>-B) [7][3]. Combining Activation with Asynchronous Arrows You can combine these features by appending the + or - modifiers to the asynchronous arrow syntax [7][3]. - Example to activate target asynchronously: A-) + B: Message [7][3] - Example to deactivate source asynchronously: A-) - B: Message [7][3] Note: In standard Mermaid syntax, these modifiers are appended directly to the arrow [2][3]. For instance, A->>+B signifies a synchronous request that activates participant B [2][8]. Following this pattern, A-) + B is the standard way to denote an asynchronous message that simultaneously triggers an activation [7][3].
Citations:
- 1: https://mermaid.ai/open-source/syntax/sequenceDiagram.html
- 2: https://newdevsguide.com/2023/04/10/mermaid-sequence-diagrams/
- 3: https://showa-yojyo.github.io/notebook/javascript-mermaid/sequence-diagram.html
- 4: https://eric.run.place/MermZen/blog/en/sequence.html
- 5: https://hrgui.dev/posts/mermaid-tutorial/
- 6: Can you add hollow arrow in UML Sequence diagrams to represent the asynchronous message？ mermaid-js/mermaid#1528
- 7: Sequence Diagram shortcut for activation and deactivation mermaid-js/mermaid#3948
- 8: https://unmarkdown.com/blog/mermaid-diagrams-guide
🌐 Web query:
site:github.com/mermaid-js/mermaid "->)+" sequence diagram activation
💡 Result:
In sequence diagrams, particularly within tools like Mermaid, activation refers to the representation of an object or actor performing an action in response to a message [1]. This is visualized as an "activation bar" (or focus of control) on the participant's lifeline [1]. The + and - symbols are used as shorthand notation for activation and deactivation, respectively, when appended to the message arrow [2][3]. How the shortcut notation functions: 1. + (Activation): Appending + to the target end of a message arrow (e.g., Alice->>+John: message) activates the recipient (John) [2][4]. 2. - (Deactivation): Appending - to the target end of a message arrow (e.g., John-->>-Alice: reply) deactivates the sender (Alice) [4][5]. Key behavior details: - Activation changes the state of the recipient (the actor the arrow points to) [6]. - Deactivation changes the state of the sender (the actor the arrow originates from) [4][6]. - Activations can be stacked for the same actor, allowing for multiple nested or overlapping actions [2][3]. - These shortcuts are designed to simplify the syntax compared to using explicit activate and deactivate commands [2][3]. Example usage: sequenceDiagram Alice->>+John: Call John-->>-Alice: Reply In this example, Alice->>+John activates John upon receiving the message, and John-->>-Alice deactivates Alice when the reply is sent [2][3].
Citations:
- 1: activation boxes mermaid-js/mermaid#313
- 2: https://github.com/mermaid-js/mermaid/blob/9745f325/docs/syntax/sequenceDiagram.md
- 3: https://github.com/mermaid-js/mermaid/blob/9745f325/packages/mermaid/src/docs/syntax/sequenceDiagram.md
- 4: Different behavior of activation and its shortcut in sequence diagrams. mermaid-js/mermaid#5105
- 5: Sequence Diagram shortcut for activation and deactivation mermaid-js/mermaid#3948
- 6: Sequence diagram: Control multiple/overlapping activations mermaid-js/mermaid#1765
Preserve asynchronous arrow tokens in activation methods.
AsyncRequestWithActivation and AsyncResponseWithActivation emit synchronous tokens (->>+ and -->>-). Use ->)+ and --)- in all four activation methods, then update the examples and golden output.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@mermaid/sequence/examples_test.go` around lines 244 - 286, Update
AsyncRequestWithActivation, AsyncRequestfWithActivation,
AsyncResponseWithActivation, and AsyncResponsefWithActivation to emit
asynchronous arrow tokens ->)+ and --)- instead of synchronous ->>+ and -->>-.
Update the corresponding example expected outputs in
ExampleDiagram_AsyncRequestWithActivation,
ExampleDiagram_AsyncRequestfWithActivation,
ExampleDiagram_AsyncResponseWithActivation, and
ExampleDiagram_AsyncResponsefWithActivation, along with the golden output.
| // ExampleWithMirrorActors draws the actors along the bottom as well as the top, | ||
| // which a long diagram wants so a reader does not have to scroll back. | ||
| func ExampleWithMirrorActors() { | ||
| _ = sequence.NewDiagram(os.Stdout, sequence.WithMirrorActors(true)). | ||
| SyncRequest("Alice", "Bob", "How are you?"). | ||
| Build() | ||
|
|
||
| // Output: | ||
| // sequenceDiagram | ||
| // Alice->>Bob: How are you? | ||
| } |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Check whether sequence config values reach the rendered diagram.
rg -nP --type=go -C5 'mirrorActors|actorFontSize|bottomMarginAdj|func newConfig' mermaid/sequenceRepository: nao1215/markdown
Length of output: 5164
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '== sequence files =='
git ls-files 'mermaid/sequence'
printf '%s\n' '== config.go =='
cat -n mermaid/sequence/config.go
printf '%s\n' '== candidate declarations =='
ast-grep outline mermaid/sequence --lang go 2>/dev/null || true
printf '%s\n' '== Build and rendering references =='
rg -n -P --type=go -C8 'func \([^)]*\) Build|func Build|config\.|mirrorActors|bottomMariginAdjustment|actorFontSize|WithMirrorActors|WithActorFontSize|WithBottomMariginAdjustment' mermaid/sequenceRepository: nao1215/markdown
Length of output: 25144
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '== sequence.go =='
cat -n mermaid/sequence/sequence.go
printf '%s\n' '== option golden test =='
sed -n '510,575p' mermaid/sequence/sequence_test.go
printf '%s\n' '== option golden fixture =='
cat -n mermaid/sequence/testdata/golden/sequence_options.md
printf '%s\n' '== all configuration-field references outside config.go =='
rg -n -P --type=go 'mirrorActors|bottomMariginAdjustment|actorFontSize|actorFontFamily|actorFontWeight|noteFontSize|noteFontFamily|noteFontWeight|noteAlign|messageFontSize|messageFontFamily|messageFontWeight' mermaid --glob '!config.go'Repository: nao1215/markdown
Length of output: 8787
🏁 Script executed:
#!/bin/bash
set -eu
python3 - <<'PY'
from pathlib import Path
import re
root = Path("mermaid/sequence")
config = (root / "config.go").read_text()
fields = re.findall(r"^\s*([A-Za-z][A-Za-z0-9]*)\s+(?:bool|uint|string)\s*$", config, re.M)
production = {}
for path in root.glob("*.go"):
if path.name == "config.go" or path.name.endswith("_test.go"):
continue
text = path.read_text()
for field in fields:
hits = len(re.findall(rf"\b{re.escape(field)}\b", text))
if hits:
production.setdefault(field, []).append((path.name, hits))
print("configuration fields:", ", ".join(fields))
print("production references outside config.go:")
if production:
for field, refs in production.items():
print(f" {field}: {refs}")
else:
print(" none")
missing = [field for field in fields if field not in production]
print("unconsumed configuration fields:", ", ".join(missing))
assert len(missing) == len(fields)
PYRepository: nao1215/markdown
Length of output: 655
Render the sequence configuration options
NewDiagram stores the options, but String serializes only d.body; Build writes that unchanged text. Wire all configuration fields into the rendered Mermaid output, or remove the unused options and examples.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@mermaid/sequence/examples_test.go` around lines 804 - 814, Update the
rendering flow used by NewDiagram, String, and Build so every configured
sequence option, including WithMirrorActors, is reflected in the generated
Mermaid output rather than serializing only d.body. Ensure
ExampleWithMirrorActors verifies the resulting configuration-specific output, or
remove options and their examples if they cannot be rendered.
| // ExampleDiagram_Concurrent separates the regions of a state that run at the | ||
| // same time. | ||
| func ExampleDiagram_Concurrent() { | ||
| _ = state.NewDiagram(os.Stdout). | ||
| CompositeState("Running"). | ||
| State("Linting", "go vet"). | ||
| End(). | ||
| Concurrent(). | ||
| Build() | ||
|
|
||
| // Output: | ||
| // stateDiagram-v2 | ||
| // state Running { | ||
| // Linting : go vet | ||
| // } | ||
| // --- | ||
| } |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Inspect the Concurrent implementation and its separator.
rg -nP --type=go -C5 'func \(d \*Diagram\) Concurrent\(' mermaid/stateRepository: nao1215/markdown
Length of output: 693
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- state diagram implementation ---'
sed -n '1,340p' mermaid/state/state_diagram.go
printf '%s\n' '--- Concurrent call sites and examples ---'
rg -n -C4 --type=go 'Concurrent\(\)|ExampleDiagram_Concurrent|title|front.?matter|---|--' mermaid/stateRepository: nao1215/markdown
Length of output: 46094
🌐 Web query:
Mermaid state diagram syntax concurrent states separator -- composite state official documentation
💡 Result:
In Mermaid state diagrams, composite states are defined by using the state keyword followed by an identifier and a body enclosed in curly braces {}, which contains the internal state transitions [1][2][3]. To represent concurrent states within a composite state, the double-hyphen separator (--) is used to divide the nested state's internal workflow into parallel regions [4][5]. Each region separated by -- operates independently, allowing for the representation of concurrent behaviors within the parent composite state [4][6]. Example of concurrency syntax: stateDiagram-v2 state CompositeState { [] --> Region1_Start Region1_Start --> Region1_End -- [] --> Region2_Start Region2_Start --> Region2_End } [4][5]
Citations:
- 1: https://docs.min87.com/en/mermaid/syntax/stateDiagram.html
- 2: https://mermaid.ai/open-source/syntax/stateDiagram.html
- 3: https://www.vpascode.com/docs/vpascode-docs/mermaid-js-playbook/mermaid-js-state-diagram-syntax-guide/
- 4: https://github.com/mermaid-js/mermaid/blob/8b52e537/docs/syntax/stateDiagram.md
- 5: https://www.mintlify.com/mermaid-js/mermaid/diagrams/state-diagram
- 6: https://docs.mermaidviewer.com/diagrams/state
Emit the concurrency separator inside the composite state. Concurrent appends --- after CompositeStateBuilder.End closes Running. Mermaid requires --, not ---, inside the composite state.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@mermaid/state/examples_test.go` around lines 519 - 535, Update
ExampleDiagram_Concurrent and the underlying Concurrent/composite-state
rendering flow so the concurrency separator is emitted inside the Running
composite state before CompositeStateBuilder.End closes it. Use Mermaid’s
required separator syntax `--` and update the example’s expected output
accordingly.
| // ExampleDiagram_Section groups the periods that follow it. A timeline needs a | ||
| // section before anything else, and a period added without one is reported | ||
| // from Build rather than drawn in the wrong place. | ||
| func ExampleDiagram_Section() { | ||
| _ = timeline.NewDiagram(os.Stdout). | ||
| Section("2024"). | ||
| Period("Q1", "Kickoff"). | ||
| Section("2025"). | ||
| Period("Q1", "Launch"). | ||
| Build() | ||
|
|
||
| // Output: | ||
| // timeline | ||
| // section 2024 | ||
| // Q1 : Kickoff | ||
| // section 2025 | ||
| // Q1 : Launch | ||
| } |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
The Section doc contradicts two other examples in this file.
The comment states that a timeline needs a section before anything else and that a period added without one is reported from Build. Two examples in this file show otherwise:
- Line 23 calls
Period("2002", "LinkedIn")before anySection, and the output at line 40 renders2002 : LinkedInwith no error. ExampleDiagram_Errorat lines 94-101 adds a period with no section and printserror: <nil>.
Correct the comment so it matches the behavior.
📝 Proposed comment fix
-// ExampleDiagram_Section groups the periods that follow it. A timeline needs a
-// section before anything else, and a period added without one is reported
-// from Build rather than drawn in the wrong place.
+// ExampleDiagram_Section groups the periods that follow it. A section is
+// optional: a period added before any section is drawn at the top level.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| // ExampleDiagram_Section groups the periods that follow it. A timeline needs a | |
| // section before anything else, and a period added without one is reported | |
| // from Build rather than drawn in the wrong place. | |
| func ExampleDiagram_Section() { | |
| _ = timeline.NewDiagram(os.Stdout). | |
| Section("2024"). | |
| Period("Q1", "Kickoff"). | |
| Section("2025"). | |
| Period("Q1", "Launch"). | |
| Build() | |
| // Output: | |
| // timeline | |
| // section 2024 | |
| // Q1 : Kickoff | |
| // section 2025 | |
| // Q1 : Launch | |
| } | |
| // ExampleDiagram_Section groups the periods that follow it. A section is | |
| // optional: a period added before any section is drawn at the top level. | |
| func ExampleDiagram_Section() { | |
| _ = timeline.NewDiagram(os.Stdout). | |
| Section("2024"). | |
| Period("Q1", "Kickoff"). | |
| Section("2025"). | |
| Period("Q1", "Launch"). | |
| Build() | |
| // Output: | |
| // timeline | |
| // section 2024 | |
| // Q1 : Kickoff | |
| // section 2025 | |
| // Q1 : Launch | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@mermaid/timeline/examples_test.go` around lines 170 - 187, Update the
documentation comment for ExampleDiagram_Section to describe the actual behavior
shown by the other examples: periods may be added before any section and are
rendered without an error; sections group subsequent periods when present.
Remove the claims that a section is required first and that Build reports an
error for unsectioned periods.
| // ExampleDiagram_TaskIn adds a step to a section named outright, which saves | ||
| // switching back and forth when the steps of two sections are interleaved in | ||
| // the calling code. | ||
| func ExampleDiagram_TaskIn() { | ||
| _ = userjourney.NewDiagram(os.Stdout). | ||
| Section("Browse"). | ||
| Section("Checkout"). | ||
| TaskIn("Browse", "Search the catalog", userjourney.ScoreSatisfied, "Customer"). | ||
| TaskIn("Checkout", "Pay", userjourney.ScoreNeutral, "Customer"). | ||
| Build() | ||
|
|
||
| // Output: | ||
| // journey | ||
| // section Browse | ||
| // section Checkout | ||
| // section Browse | ||
| // Search the catalog: 4: Customer | ||
| // section Checkout | ||
| // Pay: 3: Customer | ||
| } |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Inspect the TaskIn implementation and its section handling.
ast-grep run --pattern 'func (d *Diagram) TaskIn($$$) $_ { $$$ }' --lang go mermaid/userjourney
rg -n -C5 'section' mermaid/userjourney --type=go -g '!*_test.go'Repository: nao1215/markdown
Length of output: 8542
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- Example and nearby tests ---'
sed -n '180,245p' mermaid/userjourney/examples_test.go
printf '%s\n' '--- TaskIn references and documentation ---'
rg -n -C4 'TaskIn|ExampleDiagram_TaskIn' mermaid/userjourney --type=go
printf '%s\n' '--- Build and output path ---'
sed -n '70,205p' mermaid/userjourney/user_journey.goRepository: nao1215/markdown
Length of output: 10841
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- TaskIn behavioral tests ---'
sed -n '84,112p' mermaid/userjourney/user_journey_test.go
sed -n '320,348p' mermaid/userjourney/user_journey_test.go
printf '%s\n' '--- Read-only sequence verifier ---'
python3 - <<'PY'
from pathlib import Path
import re
source = Path("mermaid/userjourney/user_journey.go").read_text()
example = Path("mermaid/userjourney/examples_test.go").read_text()
assert 'd.body = append(d.body, fmt.Sprintf(" section %s", escapeField(trimmed, sectionUnsafe)))' in source
assert 'if d.currentSection != trimmedSection {' in source
assert 'd.Section(trimmedSection)' in source
body = re.search(
r'func ExampleDiagram_TaskIn\(\) \{(.*?)\n\}',
example,
re.S,
).group(1)
calls = re.findall(r'\.(Section|TaskIn)\("([^"]+)"', body)
current = None
sections = []
for method, name in calls:
if method == "Section":
current = name
sections.append(name)
elif current != name:
current = name
sections.append(name)
print("effective section headers:", sections)
print("header counts:", {name: sections.count(name) for name in dict.fromkeys(sections)})
assert sections == ["Browse", "Checkout", "Browse", "Checkout"]
PYRepository: nao1215/markdown
Length of output: 2115
🏁 Script executed:
#!/bin/bash
set -eu
python3 - <<'PY'
from pathlib import Path
import re
source = Path("mermaid/userjourney/user_journey.go").read_text()
example = Path("mermaid/userjourney/examples_test.go").read_text()
assert 'd.body = append(d.body, fmt.Sprintf(" section %s", escapeField(trimmed, sectionUnsafe)))' in source
assert 'if d.currentSection != trimmedSection {' in source
assert 'd.Section(trimmedSection)' in source
body = re.search(
r'func ExampleDiagram_TaskIn\(\) \{(.*?)\n\}',
example,
re.S,
).group(1)
calls = re.findall(r'\.\s*(Section|TaskIn)\("([^"]+)"', body)
current = None
sections = []
for method, name in calls:
if method == "Section":
current = name
sections.append(name)
elif current != name:
current = name
sections.append(name)
print("calls:", calls)
print("effective section headers:", sections)
print("header counts:", {name: sections.count(name) for name in dict.fromkeys(sections)})
assert sections == ["Browse", "Checkout", "Browse", "Checkout"]
PYRepository: nao1215/markdown
Length of output: 372
Remove the redundant Section calls from ExampleDiagram_TaskIn.
TaskIn starts a section when its target differs from currentSection. The current chain emits Browse, Checkout, Browse, and Checkout, leaving the first two sections empty. Start the example with the two TaskIn calls instead.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@mermaid/userjourney/examples_test.go` around lines 209 - 228, Remove the
initial Section("Browse") and Section("Checkout") calls from
ExampleDiagram_TaskIn, leaving the chained TaskIn calls to create each target
section as needed. Update the example output to match the resulting diagram
without empty sections.
1 participant
Closes #131 (task 3, the mermaid half; the root package landed in #174).
What this covers
All twenty-two subpackages. Each had one example — of a whole diagram — for between six and sixty-six exported symbols. pkg.go.dev puts an example under the symbol it is named for, so a reader looking at
Leaf,Curve,Link,Sibling,Next,BoundaryEndorWithTaskPrioritysaw nothing at all.673 examples now run across the module, every one output-verified.
Not filler
Each example says something the signature does not:
Sectioncarries no value of its own — mermaid gives it the sum of what it holdsChilddescends a level andSiblingdoes notFieldtakes a range inclusive at both ends,Nexttakes a widthAsymmetricNodeis a flag and aRhombusNodeis how a decision is drawn — you cannot tell from the method nameInvisibleLinkpushes a diagram into the layout its author wants without saying anything untrue about the flowCompositeStatereturns an inner diagram andEndhands the outer one back — the one place in this library where the chain changes what it is building halfway througharchtitle takes only[A-Za-z0-9_ ], mermaid refuses the whole diagram otherwise, and there is no escape to reach forThe examples every builder shares —
Build,Error,LF,String,Option,WithTitle— are worded identically across all twenty-two. They do the same thing, and a reader moving between packages should not have to work out whether different wording means different behavior.Two bugs the audit caught, worth reporting
An example that builds nothing prints nothing, and an empty
// Output:block matches that happily — so it passes while documenting nothing.requirementexamples calledRequirementwith an id alone. That builder needs all four fields — id, text, risk, verify method — and records an error otherwise, writing no block at all. Twenty examples passed while producing empty documents.mindmapLFexample calledRoottwice, which records "root node is already defined".TestEveryExportedSymbolHasAnExamplefound both, because it requires a non-empty output before counting an example as documenting its symbol — the same rule godoc applies. Fixed, and the requirement examples now show the four-field requirement, which is the thing about that package a reader most needs to see.I also swept for empty output blocks across the module: none remain.
The audit now lists every package
It started at
["."]. It is nowmermaid/*plus the root, so a new subpackage or a new exported symbol arriving without an example fails the build.Verification
go test ./...passes; 673 examples, all with filled// Output:blocks captured from actual runs rather than written from memory.golangci-lint run ./...reports 0 issues.TestEveryExportedSymbolHasAnExamplereports nothing missing across all 23 packages.Summary by CodeRabbit
Documentation
Tests