dsh-model-everything 0.4.0 → 0.5.0

package/README.en-US.md

@@ -1,4 +1,4 @@
-# Modeling / Automated Review for Designs and Code (dsh-model-everything)
+# Modeling, Architecture Visualisation and Automated Review (dsh-model-everything)
 
 <p align="center"><strong>English</strong> · <a href="README.md">中文</a></p>
 
@@ -11,38 +11,39 @@
 
 Abstract what a design or a piece of code claims into a model and let an engine run it: findings carry citations and hashes, so they can be recomputed and compared. The conclusion comes from a run rather than from reasoning it out: thinking it through becomes running it.
 
+The same models can be **drawn**: an architecture source renders directly, parent and child boundaries fold, the structure is measured against budgets, and two designs are compared by containment.
+
 A native DeepSeek Harness plugin. It turns the assertions a design makes **about behaviour** into models that can be run, reviewed and exported:
 
 - **Check a claim**: against the source, cited to `file:line`.
 - **Run a model**: state machines, protocols, composed machines and data models become executable, and an engine runs them.
 - **Review a diagram**: read as a model, reviewed as a model, reconciled with it.
+- **Draw the architecture**: a Mermaid or PlantUML source becomes a drawing - nested boundaries, folding, light and dark - while `diagram_review` measures the structure and `diagram_diff` compares two versions.
 - **Compare a refactor**: a model before and after, with the two reports side by side.
 - **Leave a record**: conclusions fixed into a report with hashes, recomputable and comparable and exportable.
 
-## It costs more; what it returns is a verdict
+## Specialised in modelling review for medium-to-large, medium-to-high-complexity projects
 
-This is a capability tool, not a token-saving one.
+This tool does one thing: it turns what a project claims about behaviour, structure and data into a model,
+runs it, and returns a conclusion that can be recomputed - not a paragraph that reads like one.
 
-**How much it costs depends on the size of the task, and the direction is the opposite of intuition.** On a
-fixture of a few hundred lines it costs several times the baseline, because the fixed cost - skill body,
-tool definitions - has nothing to amortise against. On an object of tens of thousands of lines across
-hundreds of files the ratio falls back toward parity: we measured 0.93x to 1.11x. **The larger the task,
-the better the trade**: one decision replaces dozens of `read` calls rather than a few lines of code.
+**The scale it specialises in is the medium-to-large, medium-to-high-complexity project**: tens of
+thousands of lines, hundreds of files, protocols and state machines that cross modules. At that scale one
+decision replaces dozens of reads, and the fixed cost of the skill body and the tool definitions is
+amortised; the ratio we measured falls to 0.93x-1.11x there.
 
-What the extra buys:
+It hands back three things:
 
-- a conclusion that can be **recomputed**: hashes, `verdict`, citations, not a paragraph that reads like one;
+- a conclusion that can be **recomputed**: hashes, `verdict`, citations;
 - a **counterexample path**: the steps or the event sequence that breaks the claim;
-- a **portable model**: the same conclusion can be handed to UPPAAL, TLA+, PRISM or SPIN for a second opinion.
-
-When it is not worth it: when one reading of the code settles the claim, or three lines of script count
-it out. **It does not buy speed over reading.** It buys the claims that reading cannot decide.
+- a **portable model**: the same conclusion can be handed to UPPAAL, TLA+, PRISM or SPIN for a second
+  opinion.
 
-**It decides small models, not programs.** The engine enumerates states, so a model that explodes is
-reported `truncated` with the undecided check named. That is not a bug to retry with a larger `maxStates`:
-reduce the model first, and if it still explodes the property needs a tool that does not enumerate - SPIN
-for partial-order reduction, NuSMV for symbolic search, CBMC for bounded SAT. This plugin builds no
-abstraction and reads no program source.
+**What it specialises in deciding is the small model a person has already abstracted**: state machines,
+finite-word automata, data models and migrations, design declarations, dependency graphs. When a model is
+too large to enumerate, it reports `truncated` and names the undecided check; reducing the model (dropping
+variables the property does not read, collapsing symmetric states), or handing that model to SPIN for
+partial-order reduction, NuSMV for symbolic search, CBMC for bounded SAT, carries the question further.
 
 ## Report cards
 
@@ -71,6 +72,36 @@ A card **saves no tokens**: the model still gets the full text.
 | Concurrency / synchrony / async | Mines claims about how work is executed (thread-safe, locks, interrupts, async/await, the event loop) and routes each to a tool that can decide it. It proves nothing itself |
 | Export | Exports a verified model as input for UPPAAL, TLA+, PRISM or SPIN |
 | Reports | Report body rendering, baseline comparison (`report_diff`), hash specification. Every report also carries a summary for a UI - verdict, the first finding, the next step - while the model still gets the full text |
+| Architecture visualisation | Draws a source directly (the drawable Mermaid / PlantUML subset), measures its structure against budgets, and compares two designs by containment. Parent/child grouping is first-class: nested boundaries, folding, light and dark palettes, and a sidebar whiteboard |
+
+## Architecture visualisation
+
+Drawing is not decoration here; it is how a design gets read. Three questions, kept apart because they are
+different questions:
+
+| You want | Tool | It answers | It does not answer |
+|---|---|---|---|
+| The source drawn | `diagram_render` | What the drawing looks like | Whether the system it draws is right |
+| Whether the drawing is too dense | `diagram_review` | How wide each boundary is, how deep they nest, how many nodes | Whether those boundaries should exist |
+| What changed between two designs | `diagram_diff` | Which boundary appeared, vanished, was renamed or re-parented, and which component changed owner | Whether the change is an improvement |
+
+**Parent/child grouping is first-class.** Mermaid `subgraph` and PlantUML `package` both read as boundaries,
+boundaries nest, and the layout stacks a group's members inside it and wraps a parent around its children -
+because a layered diagram whose members float outside their package is not showing containment at all. Clicking a
+boundary folds it into one box and clicking again unfolds it; folding is a transform on the model, not a mode of
+the painter, so the edges re-aim at the box.
+
+**A line it cannot draw is refused with its line number.** Sequence diagrams, class diagrams, Gantt charts, the
+`click`/`classDef` directives and PlantUML's `actor`/`note` are all refused by line. A sequence diagram that
+quietly lost its lifelines looks complete, and that is worse than no drawing.
+
+**Light and dark follow the page.** The rendered background decides which palette is used, and four schemes are
+available (`default`, `github`, `high-contrast`, `print`); the surface is painted inside the SVG, so a re-skinned
+container cannot change a picture's contrast. The right sidebar carries a whiteboard tab as well: paste a source,
+get the drawing, with no tool result involved.
+
+It **does not prove the design is right**: a tidy drawing is a readable model, and the judgement stays with
+`model_verify` and `uml_structure_verify`.
 
 ## Typical uses
 
@@ -170,6 +201,9 @@ What is kept is the **source file**; a rendered image is a by-product.
 | `model_automaton_verify` | Finite-word automata: empty language, trap states, reachability, and the equivalence or inclusion relation against another automaton, with the **shortest witness word** when it fails |
 | `model_edit` | Changes a model file by naming one change (add/remove a state, add/remove/update a transition, pointer set/remove): returns the structural diff and the difference in findings, so edit-verify-compare takes one call |
 | `report_diff` | Compares two reports: what a change added, removed or changed |
+| `diagram_render` | Source text to SVG: the drawable subset of Mermaid (flowchart, stateDiagram) and PlantUML (component, package, state). Layout, paint and output are all computed here; optionally writes a file and takes a colour scheme. A line it cannot draw is **refused with its line number**, never half-drawn |
+| `diagram_review` | Structural budgets: how wide each boundary is, how deep they nest, how many nodes the drawing holds. Every finding names its group, and the report also prints **what it measured**, so "nothing to check" cannot read as "checked and clean" |
+| `diagram_diff` | Structural difference between two drawings: boundaries added, removed, renamed or re-parented, and nodes that changed owner. It says what moved, never whether the move is better |
 
 `model_verify`, `model_datamodel_verify` and `model_design_review` also take `modelPath`: a JSON file in the workspace, in any formatting (indentation, a BOM and a trailing newline all parse). It is the alternative to an inline `model`; passing both is refused.
 
@@ -251,6 +285,16 @@ It registers its skills through the standard DSH filesystem skill provider and i
 |---|---|---|---|
 | `dsh-model-everything` | `dsh-model-everything` | every tool and skill | on |
 | Injected routing prompt | `dsh-model-everything-gate` | one routing message in the first model step of a session | on |
+| Drawing | `dsh-model-everything-diagram` | the three drawing tools, and the diagram whiteboard in the right sidebar | on |
+
+**Drawing** is the third component, kept apart on purpose: it carries no engine, so the two rows above can be
+off and it still draws. A deployment that only wants its Mermaid sources drawn installs the same package and
+enables this row alone.
+
+The whiteboard is a tab in the right sidebar: paste a source, get a drawing. It scales, switches colour scheme
+(`default`, `github`, `high-contrast`, `print`), follows the page's light or dark surface, and folds a group into
+one box when you click it. It reads no tool result at all, which is why a change on the tool side cannot break
+it.
 
 **Injected routing prompt** is the second component, switched on its own. It covers what text routing cannot: the catalog line is cut at 500 characters, and more to the point, a session that never decides to load a skill is never routed by anything.