kingmadoc 0.3.0.dev7__tar.gz → 0.3.0.dev8__tar.gz

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev8}/CHANGELOG.md

@@ -9,6 +9,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Tidier diagrams: `kingmadoc render` lays figures out with ELK (straight,
+  right-angled arrows with fewer crossings; a diagram that sets its own
+  `layout-engine` keeps it) and warns about more than 12 arrows or two arrows between
+  the same shapes. `explaining-code` 5.7: one flow direction, one arrow per pair, at
+  most 12 arrows, labels of at most six words; C4 boundary labels sit top-left in a
+  small font so arrows do not cross them. At hand-over the agent asks whether VS Code
+  should open explainers as a preview (the pictures only show there) and sets it up on
+  yes.
 - Beta channel: every commit on `main` that passes CI is published to PyPI as a
   development version (`0.3.0.devN`); follow it with
   `pipx install --pip-args=--pre kingmadoc` and `pipx upgrade kingmadoc`.

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: kingmadoc
-Version: 0.3.0.dev7
+Version: 0.3.0.dev8
 Summary: Feature docs for AI coding agents: a plan with C4 diagrams before the code, a verification doc after.
 Project-URL: Homepage, https://github.com/ATkingma/KingmaDoc
 Project-URL: Issues, https://github.com/ATkingma/KingmaDoc/issues

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev8}/skill/explaining-code/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: explaining-code
 description: "Explains existing code with rendered diagrams (C4 in Simon Brown's notation; UML sequence, state, class, activity, use case; ER; data flow) and short tables, as an arc42 or compact C4 document, one file or split into functional and technical. Fixes code blindness, e.g. after an agent wrote the code. Scope: a feature, a branch or PR, a whole project, or a folder, service or module. Use when the user asks to explain, describe, document, map, diagram, draw, visualise or give an overview of existing code or architecture; asks how something works, what it does, how the parts fit together, where something happens, or what a branch, PR, commit or task changed; wants onboarding, a walkthrough, a codebase tour, an architecture or design document, arc42, C4, UML, sequence, ER or deployment diagrams of existing code; or no longer understands the code. The request may be in any language. Not for features that are not built yet."
-version: 5.6.0
+version: 5.7.0
 allowed-tools: [Read, Write, Glob, Grep, Bash]
 ---
 
@@ -163,6 +163,12 @@ Write every diagram in **D2** (Step 5 turns them into images).
    Never set a `font-color` without a fill (titles, labels: the theme picks the colour),
    and never fill white: boundaries and nodes are `fill: transparent`. Put
    `shape: sequence_diagram` at the top level, or give its container the label `""`.
+5. **Tidy arrows:** set `direction: down` (people on top, data stores at the bottom;
+   `right` only for timelines and swimlanes), draw one arrow per pair of shapes with a
+   combined label, keep at most 12 arrows per figure (split it otherwise, e.g. one
+   figure per container), label each arrow in at most six words plus `[protocol]`, and
+   point arrows at the shapes inside a boundary, not at the boundary. `kingmadoc render`
+   lays figures out with straight, right-angled arrows (ELK) and warns about crowded ones.
 
 For a **branch**, mark changes by border, so the C4 colours stay meaningful, and add
 both to the legend:
@@ -174,6 +180,7 @@ classes: {
   changed: {style: {stroke: "#ef6c00"; stroke-width: 4}}
 }
 title: "[Container] Webshop - branch feature/invoices" {shape: text; near: top-center; style: {font-size: 24; bold: true}}
+direction: down
 vars: {
   d2-legend: {
     n: New in this branch {class: [container; new]}
@@ -236,6 +243,10 @@ Go through the checklist of each figure's model (end of
 and fix what fails; check that the document embeds every image. Then hand over in at most five lines:
 the path, one or two sentences on what the system is, the number of figures, and the
 "Couldn't work out" questions (at most three), which you then answer into the explainer.
-Do not paste the explainer or its figures into the chat. If VS Code opens it as text,
-say once that Ctrl+Shift+V shows the pictures, or `kingmadoc skills install --vscode`
-always does; never run that without the user's consent.
+Do not paste the explainer or its figures into the chat.
+
+VS Code shows the pictures only in its Markdown preview. If `.vscode/settings.json` does
+not yet open `docs/explain/` as a preview, Ask once: "Should VS Code open explainers
+directly as a preview, with the pictures?" and, on yes, run
+`kingmadoc skills install --vscode` (it adds one setting). Never run it without that yes;
+without it, mention that Ctrl+Shift+V shows the pictures.

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev8}/skill/explaining-code/reference/arc42.md

@@ -63,7 +63,7 @@ Text in `<angle brackets>` is filled in; leave out subsections marked optional.
 | **Scope**        | <feature / branch `<branch>` vs `<base>` / project / part `<path>`>                 |
 | **Stack**        | <languages, frameworks, data stores>                                                |
 | **Entry points** | <`path`, …>                                                                         |
-| **Based on**     | <commit hash (branch)> · <ISO date> · KingmaDoc skill explaining-code 5.6.0 (arc42) |
+| **Based on**     | <commit hash (branch)> · <ISO date> · KingmaDoc skill explaining-code 5.7.0 (arc42) |
 
 ## What changed (branch only)
 

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev8}/skill/explaining-code/reference/c4-model.md

@@ -106,10 +106,11 @@ classes: {
   container: {shape: rectangle; style: {fill: "#438dd5"; stroke: "#3c7fc0"; font-color: "#ffffff"}}
   database: {shape: cylinder; style: {fill: "#438dd5"; stroke: "#3c7fc0"; font-color: "#ffffff"}}
   component: {shape: rectangle; style: {fill: "#85bbf0"; stroke: "#5d82a8"; font-color: "#000000"}}
-  boundary: {style: {fill: transparent; stroke: "#888888"; stroke-dash: 4}}
-  node: {style: {fill: transparent; stroke: "#888888"}}
+  boundary: {label.near: top-left; style: {fill: transparent; stroke: "#888888"; stroke-dash: 4; font-size: 15}}
+  node: {label.near: top-left; style: {fill: transparent; stroke: "#888888"; font-size: 15}}
 }
 title: "[System Context] Webshop" {
+direction: down
   shape: text
   near: top-center
   style: {font-size: 24; bold: true}
@@ -155,9 +156,10 @@ classes: {
   external: {shape: rectangle; style: {fill: "#999999"; stroke: "#6b6b6b"; font-color: "#ffffff"}}
   container: {shape: rectangle; style: {fill: "#438dd5"; stroke: "#3c7fc0"; font-color: "#ffffff"}}
   database: {shape: cylinder; style: {fill: "#438dd5"; stroke: "#3c7fc0"; font-color: "#ffffff"}}
-  boundary: {style: {fill: transparent; stroke: "#888888"; stroke-dash: 4}}
+  boundary: {label.near: top-left; style: {fill: transparent; stroke: "#888888"; stroke-dash: 4; font-size: 15}}
 }
 title: "[Container] Webshop" {shape: text; near: top-center; style: {font-size: 24; bold: true}}
+direction: down
 vars: {
   d2-legend: {
     p: Person {class: person}
@@ -213,9 +215,10 @@ classes: {
   container: {shape: rectangle; style: {fill: "#438dd5"; stroke: "#3c7fc0"; font-color: "#ffffff"}}
   database: {shape: cylinder; style: {fill: "#438dd5"; stroke: "#3c7fc0"; font-color: "#ffffff"}}
   component: {shape: rectangle; style: {fill: "#85bbf0"; stroke: "#5d82a8"; font-color: "#000000"}}
-  boundary: {style: {fill: transparent; stroke: "#888888"; stroke-dash: 4}}
+  boundary: {label.near: top-left; style: {fill: transparent; stroke: "#888888"; stroke-dash: 4; font-size: 15}}
 }
 title: "[Component] Webshop - API" {shape: text; near: top-center; style: {font-size: 24; bold: true}}
+direction: down
 vars: {
   d2-legend: {
     c: Container {class: container}
@@ -262,9 +265,10 @@ instances they run; infrastructure (proxy, DNS) only when the code configures it
 classes: {
   container: {shape: rectangle; style: {fill: "#438dd5"; stroke: "#3c7fc0"; font-color: "#ffffff"}}
   database: {shape: cylinder; style: {fill: "#438dd5"; stroke: "#3c7fc0"; font-color: "#ffffff"}}
-  node: {style: {fill: transparent; stroke: "#888888"}}
+  node: {label.near: top-left; style: {fill: transparent; stroke: "#888888"; font-size: 15}}
 }
 title: "[Deployment] Webshop - production" {shape: text; near: top-center; style: {font-size: 24; bold: true}}
+direction: down
 vars: {
   d2-legend: {
     n: Deployment node {class: node}
@@ -298,6 +302,7 @@ classes: {
   database: {shape: cylinder; style: {fill: "#438dd5"; stroke: "#3c7fc0"; font-color: "#ffffff"}}
 }
 title: "[Dynamic] Webshop - placing an order" {shape: text; near: top-center; style: {font-size: 24; bold: true}}
+direction: down
 vars: {
   d2-legend: {
     p: Person {class: person}

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev8}/skill/explaining-code/reference/c4.md

@@ -22,7 +22,7 @@ Text in `<angle brackets>` is filled in.
 | **Scope**        | <feature / branch `<branch>` vs `<base>` / project / part `<path>`>         |
 | **Stack**        | <languages, frameworks, data stores>                                        |
 | **Entry points** | <`path`, …>                                                                 |
-| **Based on**     | <commit hash (branch)> · <ISO date> · KingmaDoc skill explaining-code 5.6.0 |
+| **Based on**     | <commit hash (branch)> · <ISO date> · KingmaDoc skill explaining-code 5.7.0 |
 
 ## In short
 

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev8}/skill/explaining-code/reference/models.md

@@ -140,6 +140,7 @@ no methods, no types, multiplicities kept.
 
 ```d2
 title: "[Class] Diagram backends" {shape: text; near: top-center; style: {font-size: 24; bold: true}}
+direction: down
 backend: "«interface» DiagramBackend" {
   shape: class
   "+render_context(diagram)": str
@@ -171,6 +172,7 @@ inside it.
 
 ```d2
 title: "[Package] kingmadoc" {shape: text; near: top-center; style: {font-size: 24; bold: true}}
+direction: down
 cli: cli {shape: package}
 plan: plan {shape: package}
 diagrams: diagrams {shape: package}

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev8}/skill/explaining-code/reference/split.md

@@ -43,7 +43,7 @@ in its first line. `kingmadoc render` takes all three files at once.
 | **Scope**        | <feature / branch `<branch>` vs `<base>` / project / part `<path>`>                 |
 | **Stack**        | <languages, frameworks, data stores>                                                |
 | **Entry points** | <`path`, …>                                                                         |
-| **Based on**     | <commit hash (branch)> · <ISO date> · KingmaDoc skill explaining-code 5.6.0 (split) |
+| **Based on**     | <commit hash (branch)> · <ISO date> · KingmaDoc skill explaining-code 5.7.0 (split) |
 
 <at most three plain sentences: what it is, for whom, what it does>
 

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev8}/src/kingmadoc/cli.py

@@ -49,7 +49,7 @@ from kingmadoc.plan.generator import (
     render_plan,
 )
 from kingmadoc.plandoc import check_plan, generated_at, parse_plan, set_status
-from kingmadoc.render import dark_mode_warnings, render_file
+from kingmadoc.render import diagram_warnings, render_file
 from kingmadoc.skills import AGENT_DIRS, install_skills
 from kingmadoc.verify.changes import detect_changes
 from kingmadoc.verify.commands import MARKER_FILES, detect_commands, run_check
@@ -474,10 +474,11 @@ def render_command(documents: tuple[Path, ...], light: bool, verbose: bool) -> N
                 noun = "image" if len(images) == 1 else "images"
                 click.echo(f"{document}: {len(images)} {noun} ({span})")
             for image in images:
-                if not light:
-                    source = image.with_suffix(".d2")
-                    for warning in dark_mode_warnings(source.read_text(encoding="utf-8")):
-                        click.echo(f"{source}: {warning} (dark mode)", err=True)
+                source = image.with_suffix(".d2")
+                for warning in diagram_warnings(source.read_text(encoding="utf-8")):
+                    if light and warning.endswith("(dark mode)"):
+                        continue
+                    click.echo(f"{source}: {warning}", err=True)
     except KingmaDocError as exc:
         raise click.ClickException(str(exc)) from exc
 

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev8}/src/kingmadoc/render.py

@@ -35,6 +35,12 @@ D2_PAD = 20
 IMAGE_MODE = 0o644
 # D2's own dark theme; the SVG switches to it when the viewer uses dark mode.
 D2_DARK_THEME = 200
+# Straight, right-angled arrows (see _layout_args); bundled with D2 like dagre.
+LAYOUT_ENGINE = "elk"
+# Above this many arrows a figure gets hard to follow (render warns).
+MAX_ARROWS = 12
+_ARROW = re.compile(r"^\s*([\w.]+)\s*(<->|->|<-|--)\s*([\w.]+)", re.M)
+_LEGEND = re.compile(r"vars:\s*\{\s*d2-legend:\s*\{.*?^\s*\}\s*^\}", re.S | re.M)
 
 # A diagram is either a fenced d2 block, or a reference written by an earlier render.
 # References may only point into img/ next to the document (no other paths).
@@ -82,7 +88,7 @@ def render_file(path: Path, d2: Sequence[str], dark: bool = True) -> list[Path]:
     # across filesystems (EXDEV when /tmp is another disk).
     with tempfile.TemporaryDirectory(dir=path.parent, prefix=".kingmadoc-render-") as tmp:
         rendered = [
-            _render(source, Path(tmp), n, path, [*d2, *_theme_args(dark)])
+            _render(source, Path(tmp), n, path, [*d2, *_theme_args(dark), *_layout_args(source)])
             for n, source in enumerate(sources, start=1)
         ]
         image_dir.mkdir(parents=True, exist_ok=True)
@@ -101,6 +107,49 @@ def render_file(path: Path, d2: Sequence[str], dark: bool = True) -> list[Path]:
     return [image_dir / f"{name}.svg" for name in names]
 
 
+def diagram_warnings(source: str) -> list[str]:
+    """Everything worth fixing in a D2 diagram: dark-mode styles and crowded arrows.
+
+    Args:
+        source: The D2 source.
+
+    Returns:
+        One message per problem (empty when there is none).
+    """
+    return dark_mode_warnings(source) + crowding_warnings(source)
+
+
+def crowding_warnings(source: str) -> list[str]:
+    """Warn about figures whose arrows get hard to follow.
+
+    More than :data:`MAX_ARROWS` arrows, or two arrows between the same two shapes (one
+    arrow with a combined label reads better).
+
+    Args:
+        source: The D2 source.
+
+    Returns:
+        One message per problem.
+    """
+    body = _LEGEND.sub("", source)
+    if "sequence_diagram" in body:
+        return []  # a sequence diagram's arrows are its messages, in order
+    pairs = [(a, b) for a, _, b in _ARROW.findall(body)]
+    warnings = []
+    if len(pairs) > MAX_ARROWS:
+        warnings.append(f"{len(pairs)} arrows (more than {MAX_ARROWS}) are hard to follow; "
+                        "split the figure or combine arrows")
+    seen: dict[frozenset[str], int] = {}
+    for a, b in pairs:
+        seen[frozenset((a, b))] = seen.get(frozenset((a, b)), 0) + 1
+    for pair, count in seen.items():
+        if count > 1 and len(pair) == 2:
+            a, b = sorted(pair)
+            warnings.append(f"{count} arrows between `{a}` and `{b}`; draw one with a "
+                            "combined label")
+    return warnings
+
+
 def dark_mode_warnings(source: str) -> list[str]:
     """Find styles in a D2 diagram that break when the image shows in dark mode.
 
@@ -121,10 +170,10 @@ def dark_mode_warnings(source: str) -> list[str]:
         fill = re.search(r"\bfill: *\"?([^;}\n\"]+)", block)
         if not fill or fill.group(1).strip() == "transparent":
             warnings.append(f"{_key(source, match.start())}: font-color without a fill stays "
-                            "dark on the dark background; remove the font-color")
+                            "dark on the dark background; remove the font-color (dark mode)")
     for match in re.finditer(r"\bfill: *\"?(?:#fff\b|#ffffff|white)\"?", source, re.I):
         warnings.append(f"{_key(source, match.start())}: a white fill stays white while the "
-                        "text on it turns light; use fill: transparent")
+                        "text on it turns light; use fill: transparent (dark mode)")
     for match in re.finditer(r"^( +)shape: *sequence_diagram", source, re.M):
         opening = source[: match.start()].rstrip().rsplit("\n", 1)[-1]
         if not re.search(r':\s*""\s*\{$', opening):
@@ -202,6 +251,15 @@ def _render(source: str, tmp: Path, n: int, doc: Path, d2: Sequence[str]) -> Pat
     return out
 
 
+def _layout_args(source: str) -> list[str]:
+    """ELK unless the diagram picks its own engine (``vars: {d2-config: {layout-engine}}``).
+
+    ELK routes arrows orthogonally, with fewer crossings than D2's default (dagre, curved
+    splines that run over each other in bigger diagrams).
+    """
+    return [] if "layout-engine" in source else ["--layout", LAYOUT_ENGINE]
+
+
 def _theme_args(dark: bool) -> list[str]:
     return ["--dark-theme", str(D2_DARK_THEME)] if dark else []
 

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev8}/tests/test_render.py

@@ -426,3 +426,46 @@ def test_images_are_readable_by_everyone(tmp_path: Path, d2: list[str]) -> None:
     images = render_file(_doc(tmp_path), d2)
 
     assert all(p.stat().st_mode & 0o777 == 0o644 for p in images)
+
+
+def test_images_use_the_elk_layout(
+    tmp_path: Path, d2: list[str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """ELK routes arrows straight and at right angles (dagre curves them over each other)."""
+    commands = _commands(tmp_path, d2, monkeypatch)
+
+    assert commands and all(c[c.index("--layout") + 1] == "elk" for c in commands)
+
+
+def test_a_diagram_that_picks_its_layout_keeps_it(
+    tmp_path: Path, d2: list[str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """vars.d2-config.layout-engine in the source wins over the default."""
+    import subprocess
+
+    from kingmadoc import render
+
+    seen: list[list[str]] = []
+    real_run = subprocess.run
+
+    def run(command: list[str], **kwargs: object):  # type: ignore[no-untyped-def]
+        seen.append(command)
+        return real_run(command, **kwargs)  # type: ignore[call-overload]
+
+    monkeypatch.setattr(render.subprocess, "run", run)
+    source = "vars: {d2-config: {layout-engine: dagre}}\na -> b\n"
+    render_file(_doc(tmp_path, f"# T\n\n```d2\n{source}```\n"), d2)
+
+    assert seen and "--layout" not in seen[0]
+
+
+def test_crowded_diagrams_are_reported() -> None:
+    """More than 12 arrows, or two arrows between the same pair, make a figure hard to read."""
+    from kingmadoc.render import diagram_warnings
+
+    crowded = "\n".join(f"a{i} -> b{i}: x" for i in range(13))
+    twice = "api -> db: reads\ndb -> api: rows\nweb -> api: calls\n"
+
+    assert any("13 arrows" in w for w in diagram_warnings(crowded))
+    assert any("`api` and `db`" in w for w in diagram_warnings(twice))
+    assert diagram_warnings("a -> b: x\nb -> c: y\n") == []

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev8}/tests/test_skill_explaining_code.py

@@ -211,8 +211,12 @@ def test_d2_examples_compile(tmp_path: Path, index: int) -> None:
     source = re.sub(r"<([A-Za-z][^<>\n]*)>", r"\1", examples[index])
     (tmp_path / "x.d2").write_text(source, encoding="utf-8")
 
+    # The same options as `kingmadoc render`: the ELK layout and the dark theme.
+    from kingmadoc.render import D2_DARK_THEME, _layout_args
+
     result = subprocess.run(
-        [D2 or "d2", str(tmp_path / "x.d2"), str(tmp_path / "x.svg")],
+        [D2 or "d2", *_layout_args(source), "--dark-theme", str(D2_DARK_THEME),
+         str(tmp_path / "x.d2"), str(tmp_path / "x.svg")],
         capture_output=True, text=True, timeout=60, check=False,
     )
 
@@ -262,3 +266,19 @@ def test_long_references_start_with_their_contents() -> None:
         assert "Contents:" in head, path.name
         for section in re.findall(r"^## (.+)$", _read(path).split("````", 1)[0], re.M):
             assert section.split(".")[0] in head or section in head, f"{path.name}: {section}"
+
+
+def test_arrows_stay_tidy() -> None:
+    """One flow direction, one arrow per pair, at most 12 arrows, short labels."""
+    step = re.sub(r"\s+", " ", _read(SKILL).split("## Step 3.", 1)[1].split("## Step 4.", 1)[0])
+
+    assert "direction: down" in step and "one arrow per pair" in step
+    assert "at most 12 arrows" in step and "six words" in step
+
+
+def test_hand_over_offers_the_vs_code_preview() -> None:
+    """The pictures only show in a preview: ask once, then set it up on yes."""
+    hand_over = re.sub(r"\s+", " ", _read(SKILL).split("## Step 6.", 1)[1])
+
+    assert "kingmadoc skills install --vscode" in hand_over
+    assert "Ask" in hand_over and "on yes" in hand_over

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev8}/tests/test_skill_models.py

@@ -331,3 +331,20 @@ def test_algorithm_model_explains_with_formula_trace_and_complexity() -> None:
     assert "```text" in body and "Invariant" in body
     assert re.search(r"\bO\(.+\) time", body)
     assert re.search(r"^\| Step \|", body, re.M), "a trace table, one row per step"
+
+
+def test_c4_boundaries_keep_their_label_out_of_the_arrows() -> None:
+    """Boundary and node labels sit top-left in a small font, so arrows do not cross them."""
+    for line in re.findall(r"^\s*(?:boundary|node): \{.*$", _read(C4_MODEL), re.M):
+        assert "label.near: top-left" in line and "font-size: 15" in line, line
+
+
+@pytest.mark.parametrize("path", ALL_FILES, ids=lambda p: p.name)
+def test_diagrams_flow_down(path: Path) -> None:
+    """Every example with arrows (except sequence diagrams) sets one flow direction:
+    down, or right for timelines and swimlanes."""
+    for source in _examples(_read(path)):
+        if _edges(source) and "sequence_diagram" not in source and "grid-" not in source:
+            assert re.search(r"^direction: (down|right)$", source, re.M), (
+                f"{path.name}:\n{source[:120]}"
+            )