Skip to content

armgit / cogit

Public Imported from GitHub
0

Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.

feat(shape): draw an ordered Flow as a sequence diagram

Eren1195cdc63cb1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 64714db..87b3157 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
+### Changed
+- An ordered **Flow** is drawn as a sequence diagram with the kind symbols.
+
+### Fixed
+- A wide diagram in **Open** keeps its size and scrolls sideways instead of shrinking its text until it cannot be read.
## [0.25.5] - 2026-10-31
### Fixed
diff --git a/docs/guide/map.md b/docs/guide/map.md
index b580210..4cdcd98 100644
--- a/docs/guide/map.md
+++ b/docs/guide/map.md
@@ -89,7 +89,8 @@ A message that landed commits has three layers, in that order:
- **Shape** — a small representation of what the change *does*, in up to three of these:
- a **Flow** of the path through the code: each box is one kind of thing (a function, a
store, a hook, an outside system) with its fixed symbol, and the arrows are the work
- handed between them;
+ handed between them. An ordered Flow — work handed between parts over time — is drawn
+ as a sequence diagram, numbered arrow by arrow;
- a **Before / After** table for a fix or any change you can see, and an **Interface**
table for a command, flag, exported function, config key or schema field that changed;
- an **Example**, one concrete run with real values (every new command gets one);
diff --git a/packages/cli/skills/record/SKILL.md b/packages/cli/skills/record/SKILL.md
index 1eccbcc..220d4af 100644
--- a/packages/cli/skills/record/SKILL.md
+++ b/packages/cli/skills/record/SKILL.md
@@ -92,8 +92,9 @@ Tools (at most three, the ones that say the most; never two that tell the same t
- `flow`: a path through code as JSON. Every node has a `kind` from the table below and a
`label` in the project's own words; at most 12 nodes and 16 edges; ids are short lowercase
- words (`a`, `hook`), unique, and every edge names two of them. Set `ordered: true` when the
- edges are steps over time and work is handed between parts (the map numbers them 1, 2, 3…).
+ words (`a`, `hook`), unique, and every edge names two of them. Set `ordered: true` when
+ work is handed between parts over time (a hook → a job → a store, a client → a server): the
+ map draws it as a sequence diagram, so keep the edges in time order.
```json
{"kind": "flow", "text": "{\"nodes\":[{\"id\":\"a\",\"kind\":\"event\",\"label\":\"after a commit\"}],\"edges\":[{\"from\":\"a\",\"to\":\"b\",\"label\":\"no\"}],\"ordered\":false}"}
diff --git a/packages/cli/src/shape.ts b/packages/cli/src/shape.ts
index 32d42f3..1d5652f 100644
--- a/packages/cli/src/shape.ts
+++ b/packages/cli/src/shape.ts
@@ -89,8 +89,9 @@ export const SHAPE_TOOLS: readonly ShapeToolSpec[] = [
"The change is a path through code across files: the functions, files, stores, hooks and " +
"outside calls it moves between. Every node gets a kind from the list below and a label " +
"in the project's own words; the map draws the symbol, never you. Set `ordered` true " +
- "when the edges are steps over time and work is handed between parts. Node ids are short " +
- `lowercase words; at most ${FLOW_MAX_NODES} nodes and ${FLOW_MAX_EDGES} edges.`,
+ "when work is handed between parts over time (a hook → a job → a store, a client → a " +
+ "server): the map draws it as a sequence diagram, so keep the edges in time order. " +
+ `Node ids are short lowercase words; at most ${FLOW_MAX_NODES} nodes and ${FLOW_MAX_EDGES} edges.`,
output:
'{"kind": "flow", "text": "{\\"nodes\\":[{\\"id\\":\\"a\\",\\"kind\\":\\"event\\",\\"label\\":\\"after a commit\\"}],\\"edges\\":[{\\"from\\":\\"a\\",\\"to\\":\\"b\\",\\"label\\":\\"no\\"}],\\"ordered\\":false}"}',
validate(text) {
@@ -351,7 +352,7 @@ export function shapePrompt(opts: {
"",
"Rules:",
"- Give at most three tools, the ones that say the most about this change; never two that tell the same thing.",
- "- A Flow for a change across two or more files: every node gets a kind from the list above and a label in the project's own words. Set `ordered` true when the edges are steps over time and work is handed between parts.",
+ "- A Flow for a change across two or more files: every node gets a kind from the list above and a label in the project's own words. Set `ordered` true when work is handed between parts over time (a hook → a job → a store, a client → a server): the map draws it as a sequence diagram, so keep the edges in time order and give every edge a label saying what is handed over or done.",
"- A Before / After table when behaviour someone can see changes (a fix, a new default, a rule).",
"- A change nobody would notice from outside (a refactor, a rename, moved code, a wording tweak in a prompt or comment) takes no tool at all: return none.",
"- An Interface table only for what is reached from outside the changed module: a CLI command or flag, an exported function or type other packages use, a config key, a stored schema field, an HTTP route. Never an internal helper, a component prop or a view-model field.",
diff --git a/packages/cli/src/view/shape.ts b/packages/cli/src/view/shape.ts
index dbbfad0..60f56d6 100644
--- a/packages/cli/src/view/shape.ts
+++ b/packages/cli/src/view/shape.ts
@@ -197,25 +197,47 @@ function flowLabel(text: string): string {
}
/**
- * The deterministic `flowchart TD` a Flow draws (Story 13.7): one node per box
- * with its kind's symbol and shape, one edge per arrow; `ordered` numbers the
- * edge labels 1, 2, 3… in the order given. Undefined for input the rules
- * refuse. The same input is always byte-identical.
+ * A sequence participant's name or a message's text: the flowchart label rules
+ * plus no newlines; a `:` inside a participant's name reads ` -` so it cannot
+ * break the `participant … as …` line.
+ */
+function sequenceText(text: string, actor: boolean): string {
+ const base = flowLabel(text).replace(/[\r\n]+/g, "");
+ return actor ? base.replace(/:/g, " -") : base;
+}
+
+/**
+ * The deterministic Mermaid a Flow draws (Story 13.7): an ordered Flow is a
+ * `sequenceDiagram` — one `participant` column per node and one numbered arrow
+ * per edge, top to bottom — and an unordered one is a `flowchart TD`, one box
+ * per node with its kind's symbol and shape, one edge per arrow. Undefined for
+ * input the rules refuse. The same input is always byte-identical.
*/
export function flowToMermaid(text: string): string | undefined {
const flow = parseFlow(text);
if (flow === undefined) return undefined;
const symbol = (kind: string) => UNIVERSAL_KINDS.find((entry) => entry.id === kind)?.symbol ?? "";
+ if (flow.ordered) {
+ const lines = ["sequenceDiagram"];
+ for (const node of flow.nodes)
+ lines.push(
+ ` participant ${node.id} as ${symbol(node.kind)} ${sequenceText(node.label, true)}`,
+ );
+ flow.edges.forEach((edge, index) => {
+ const label =
+ edge.label !== undefined && edge.label !== "" ? ` ${sequenceText(edge.label, false)}` : "";
+ lines.push(` ${edge.from}->>${edge.to}: ${index + 1}.${label}`);
+ });
+ return lines.join("\n");
+ }
const lines = ["flowchart TD"];
for (const node of flow.nodes) {
const [open, close] = FLOW_NODE_SHAPE[node.kind] ?? ["[", "]"];
lines.push(` ${node.id}${open}"${symbol(node.kind)} ${flowLabel(node.label)}"${close}`);
}
- flow.edges.forEach((edge, index) => {
- // Ordered edges keep their words after the step number: "2. puts it in the queue".
- const label = flow.ordered ? `${index + 1}. ${edge.label ?? ""}`.trim() : edge.label;
- if (label !== undefined && label !== "")
- lines.push(` ${edge.from} -->|"${flowLabel(label)}"| ${edge.to}`);
+ flow.edges.forEach((edge) => {
+ if (edge.label !== undefined && edge.label !== "")
+ lines.push(` ${edge.from} -->|"${flowLabel(edge.label)}"| ${edge.to}`);
else lines.push(` ${edge.from} --> ${edge.to}`);
});
return lines.join("\n");
diff --git a/packages/cli/test/shape.test.ts b/packages/cli/test/shape.test.ts
index 285fe13..da9d80a 100644
--- a/packages/cli/test/shape.test.ts
+++ b/packages/cli/test/shape.test.ts
@@ -163,6 +163,7 @@ describe("the Shape tool catalogue", () => {
expect(prompt).toContain("A Before / After table when behaviour someone can see changes");
expect(prompt).toContain("A new or changed command or flag always gets an example");
expect(prompt).toContain("Never an internal helper");
+ expect(prompt).toContain("give every edge a label");
expect(prompt).toContain("takes no tool at all");
expect(prompt).toContain("never an invented one");
expect(prompt).toContain("fn (ƒ Function): a function or method");
@@ -174,7 +175,7 @@ describe("the Shape tool catalogue", () => {
expect(prompt).toContain('"example" (Example)');
// The retired Mermaid tools are no longer offered to the writer.
expect(prompt).not.toContain("mermaid");
- expect(prompt).not.toContain("sequence");
+ expect(prompt).not.toContain('"sequence"');
});
it("names the offered tools and says when to use each", () => {
@@ -269,27 +270,27 @@ describe("the Flow tool", () => {
);
});
- it("numbers the edge labels when ordered, and refuses invalid input", () => {
+ it("draws an ordered Flow as a sequence diagram, and refuses invalid input", () => {
const ordered = JSON.stringify({
nodes: [
{ id: "a", kind: "event", label: "after a commit" },
{ id: "b", kind: "fn", label: "enqueue" },
- { id: "c", kind: "store", label: "queue" },
+ { id: "c", kind: "store", label: "queue: pending" },
],
edges: [
{ from: "a", to: "b" },
- { from: "b", to: "c", label: "puts it in" },
+ { from: "b", to: "c", label: "puts; it in: the queue" },
],
ordered: true,
});
expect(flowToMermaid(ordered)).toBe(
[
- "flowchart TD",
- ' a>"⚡ after a commit"]',
- ' b["ƒ enqueue"]',
- ' c[("▤ queue")]',
- ' a -->|"1."| b',
- ' b -->|"2. puts it in"| c',
+ "sequenceDiagram",
+ " participant a as ⚡ after a commit",
+ " participant b as ƒ enqueue",
+ " participant c as ▤ queue - pending",
+ " a->>b: 1.",
+ " b->>c: 2. puts it in: the queue",
].join("\n"),
);
expect(flowToMermaid("not json")).toBeUndefined();
diff --git a/packages/template/src/MermaidDiagram.tsx b/packages/template/src/MermaidDiagram.tsx
index ba92d85..83a9971 100644
--- a/packages/template/src/MermaidDiagram.tsx
+++ b/packages/template/src/MermaidDiagram.tsx
@@ -57,7 +57,27 @@ function loadMermaid(): Promise<Mermaid> {
let seq = 0;
-export function MermaidDiagram({ source, className }: { source: string; className?: string }) {
+/**
+ * Gives a drawn diagram its own width: Mermaid writes `width="100%"`, which
+ * shrinks a wide diagram's text to fit; the Open window scrolls it instead.
+ */
+export function naturalSize(svg: SVGSVGElement): void {
+ const width = svg.style.maxWidth;
+ if (width === "") return;
+ svg.style.width = width;
+ svg.style.maxWidth = "none";
+}
+
+export function MermaidDiagram({
+ source,
+ className,
+ fit = false,
+}: {
+ source: string;
+ className?: string;
+ /** Shrink to the box (the panel's preview) instead of keeping the drawn size. */
+ fit?: boolean;
+}) {
const host = useRef<HTMLDivElement>(null);
const available = mermaidAvailable();
const [failed, setFailed] = useState(false);
@@ -70,7 +90,10 @@ export function MermaidDiagram({ source, className }: { source: string; classNam
loadMermaid()
.then((mermaid) => mermaid.render(id, source))
.then(({ svg }) => {
- if (!cancelled && host.current !== null) host.current.innerHTML = svg;
+ if (cancelled || host.current === null) return;
+ host.current.innerHTML = svg;
+ const drawn = host.current.querySelector("svg");
+ if (!fit && drawn !== null) naturalSize(drawn);
})
.catch(() => {
if (!cancelled) setFailed(true);
@@ -78,7 +101,7 @@ export function MermaidDiagram({ source, className }: { source: string; classNam
return () => {
cancelled = true;
};
- }, [source, available]);
+ }, [source, available, fit]);
const extra = className ? ` ${className}` : "";
if (!available)
diff --git a/packages/template/src/ShapeModal.tsx b/packages/template/src/ShapeModal.tsx
index 68e99f8..4e896e7 100644
--- a/packages/template/src/ShapeModal.tsx
+++ b/packages/template/src/ShapeModal.tsx
@@ -2,6 +2,7 @@ import { type ReactNode, useEffect, useRef, useState } from "react";
import type { ViewNode } from "../../cli/src/view/model.js";
import {
flowToMermaid,
+ parseFlow,
SHAPE_READING,
shapeKindsUsed,
shapePreview,
@@ -124,17 +125,28 @@ const KINDS_CAPTIONS = new Set(["flow", "pseudo"]);
/**
* A tool's caption with a "?" that says how to read it; a Flow or Steps also
- * lists every kind, so the symbols name themselves.
+ * lists every kind, so the symbols name themselves. `reading` swaps in another
+ * tool's explanation (an ordered Flow reads like a Sequence).
*/
-function ToolCaption({ id, kind, label }: { id: string; kind: string; label: string }) {
- const reading = SHAPE_READING[kind];
+function ToolCaption({
+ id,
+ kind,
+ label,
+ reading = kind,
+}: {
+ id: string;
+ kind: string;
+ label: string;
+ reading?: string;
+}) {
+ const help = SHAPE_READING[reading];
const listsKinds = KINDS_CAPTIONS.has(kind);
return (
<figcaption className="shape-caption">
<span>{label}</span>
- {reading ? (
+ {help ? (
<HelpTip id={`shape-${id}`} label={`How to read the ${label}`}>
- <span className="shape-reading">{reading}</span>
+ <span className="shape-reading">{help}</span>
{listsKinds ? (
<span className="shape-kinds">
{UNIVERSAL_KINDS.map((kind) => (
@@ -235,11 +247,17 @@ function ShapeLayer({
{tools.map((tool, index) => {
const key = `${tool.kind}-${index}`;
const source = tool.kind === "flow" ? flowToMermaid(tool.text) : tool.text;
+ const orderedFlow = tool.kind === "flow" && parseFlow(tool.text)?.ordered === true;
if (DIAGRAM_KINDS.has(tool.kind) && tool.valid !== false && source !== undefined)
return (
<figure key={key} className="shape-figure">
{renderMermaid(source)}
- <ToolCaption id={key} kind={tool.kind} label={diagramLabel(tool.kind)} />
+ <ToolCaption
+ id={key}
+ kind={tool.kind}
+ label={orderedFlow ? "Sequence" : diagramLabel(tool.kind)}
+ reading={orderedFlow ? "sequence" : tool.kind}
+ />
</figure>
);
const columns = TABLE_COLUMNS[tool.kind];
@@ -431,7 +449,7 @@ export function ShapeSection({
preview ? (
<pre className="shape-preview">{preview}</pre>
) : diagramSource !== undefined ? (
- <MermaidDiagram source={diagramSource} className="shape-preview-diagram" />
+ <MermaidDiagram source={diagramSource} className="shape-preview-diagram" fit />
) : null
) : state === "off" ? (
<p className="muted">Shapes are off.</p>
diff --git a/packages/template/test/shape-modal.test.tsx b/packages/template/test/shape-modal.test.tsx
index 280e4ef..50d1a0a 100644
--- a/packages/template/test/shape-modal.test.tsx
+++ b/packages/template/test/shape-modal.test.tsx
@@ -113,6 +113,42 @@ describe("Intent, Shape and Code", () => {
expect(html).not.toContain("Function");
});
+ it("captions an ordered Flow as a Sequence and an unordered one as a Flow", () => {
+ const ordered = JSON.stringify({
+ nodes: [
+ { id: "a", kind: "event", label: "after a commit" },
+ { id: "b", kind: "store", label: "queue" },
+ ],
+ edges: [{ from: "a", to: "b", label: "enqueue" }],
+ ordered: true,
+ });
+ const sequence = render("shape", {
+ shape: {
+ tools: [{ kind: "flow", text: ordered, valid: true }],
+ commits: [],
+ },
+ });
+ expect(sequence).toContain("<span>Sequence</span>");
+ expect(sequence).toContain('aria-label="How to read the Sequence"');
+
+ const unordered = JSON.stringify({
+ nodes: [
+ { id: "a", kind: "event", label: "after a commit" },
+ { id: "b", kind: "store", label: "queue" },
+ ],
+ edges: [{ from: "a", to: "b", label: "enqueue" }],
+ ordered: false,
+ });
+ const flow = render("shape", {
+ shape: {
+ tools: [{ kind: "flow", text: unordered, valid: true }],
+ commits: [],
+ },
+ });
+ expect(flow).toContain("<span>Flow</span>");
+ expect(flow).toContain('aria-label="How to read the Flow"');
+ });
+
it("lays out a Before / After table and shows an unknown tool as text", () => {
const html = render("shape", {
shape: {