agentic-mermaid 0.1.1 → 0.1.2

package/docs/layout-characterization/README.md

@@ -1,245 +0,0 @@
-# Characterising the layout system
-
-This folder bootstraps a **characterisation-test** suite for the layout
-algorithm, in the sense of
-[adewale/testing-best-practices](https://github.com/adewale/testing-best-practices):
-pin what the code does today, with worked examples + property-based tests, so
-the algorithm can be refactored safely and improved deliberately.
-
-It contains three layers — a **deep** characterisation of the flowchart/state
-grid engine, a **breadth** layer spanning every renderer, and a **visual-quality**
-approval layer for reviewable layout drift:
-
-| File | What it is |
-|------|------------|
-| [`contact-sheet.md`](./contact-sheet.md) | **Depth** — the minimum set of worked examples that exercise every load-bearing decision in the grid engine. One phenomenon per example. (Generated by `scripts/characterization/contact-sheet.ts`.) |
-| [`properties.md`](./properties.md) | **Depth** — the smallest load-bearing set of properties for the grid engine, with a minimality (mutation-kill) argument and academic grounding. |
-| [`../../src/__tests__/characterization-layout.test.ts`](../../src/__tests__/characterization-layout.test.ts) | **Depth** — those properties as executable `fast-check` tests (13 tests). |
-| [`contact-sheet-families.md`](./contact-sheet-families.md) | **Breadth** — one canonical example per renderer (all 12 families) + the universal-invariant coverage matrix. (Generated by `scripts/characterization/contact-sheet-families.ts`.) |
-| [`../../src/__tests__/characterization-families.test.ts`](../../src/__tests__/characterization-families.test.ts) | **Breadth** — the universal invariants extended across every family and public output surface, asserting only what holds per family (17 tests). |
-| [`visual-quality.md`](./visual-quality.md) | **Visual approval** — SVG snapshots, SVG/PNG fingerprints, and advisory graph-drawing metrics for all 12 families. (Generated by `scripts/characterization/visual-quality.ts`.) |
-| [`../../src/__tests__/characterization-generated-artifacts.test.ts`](../../src/__tests__/characterization-generated-artifacts.test.ts) | **Drift check** — fails when generated contact sheets, visual report, or SVG snapshots are stale. |
-
-No implementation code was changed to produce any of this.
-
-## Visual testing rule
-
-Snapshots and contact sheets are approval evidence, not the whole oracle. When a
-bug report says something **looks** wrong, add at least one executable visual
-contract that would fail before updating any golden file. Pick the cheapest
-contract that observes the thing users actually see:
-
-| Visual risk | Preferred contract | Examples |
-|-------------|--------------------|----------|
-| Route geometry, ports, label lanes, overlaps | Geometry/rubric invariant over positioned layout | `route-contracts*.test.ts`, `layout-rubric.test.ts`, `contact-sheet.test.ts` hard metrics |
-| Effective color, stroke thickness, blank/collapsed render, visible endpoint glyphs | Raster invariant with `@resvg/resvg-js` pixels | `visual-rendering-contracts.test.ts`, `helpers/raster.ts` |
-| ASCII/Unicode line style or marker placement | Row/region assertion on the rendered character grid | `ascii-edge-styles.test.ts` connector-row contracts |
-| Broad family drift that needs human judgement | Golden/snapshot/contact sheet after an invariant already guards the principle | `visual-quality.md`, `visual-snapshots/*.svg`, PR screenshots |
-| Parser, escaping, config, IDs, public API shape | Structural/string assertion | Parser/security/integration tests |
-
-The red-green loop for visual work is:
-
-1. Reproduce the bad rendering with the smallest diagram that shows the fault.
-2. Encode the visual principle as geometry, raster, or row-level evidence.
-3. Prove the test is sensitive: where practical, simulate the old behaviour or
-   run a temporary source-level sabotage before trusting the green run.
-4. Fix the implementation.
-5. Regenerate approval artifacts only after the invariant test passes and the
-   visual diff has been reviewed.
-
-## Relationship to PR 30
-
-PR 30 changed the right baseline for layout characterisation. It introduced the
-route-contract layer (`src/route-contracts.ts`), the deterministic graph-drawing
-rubric (`src/layout-rubric.ts`), route/contact-sheet gates
-(`src/__tests__/contact-sheet.test.ts`, `src/__tests__/layout-rubric.test.ts`),
-and the heuristic tracker (`eval/heuristic-tracker/`). Those tests now own the
-question "is this flowchart/state/architecture route geometrically valid and
-free of hitches, stale certificates, off-outline endpoints, and label-route
-ambiguity?"
-
-This directory owns a different question: "what observable layout behaviour did
-we approve, and did it drift deliberately?" After rebasing this PR over PR 30,
-`bun run characterization:check` reported only the visual-quality report plus
-the flowchart/state SVG snapshots as stale. That is the intended signal:
-flowchart/state are exactly the families PR 30's route-contract work should
-move, while the other renderer-family snapshots stayed unchanged. The correct
-course is therefore to approve the new flowchart/state baselines after the PR 30
-route gates pass, rather than add duplicate route-contract assertions here.
-
-For future layout changes:
-
-| If this changes | Use this gate | Review action |
-|-----------------|---------------|---------------|
-| Flowchart/state/architecture routing geometry | `bun test src/__tests__/contact-sheet.test.ts src/__tests__/layout-rubric.test.ts` and `bun run track` | Hard rubric violations must stay zero; baseline deltas must be explained as improvement or intended drift. |
-| Generated characterisation artifacts | `bun run characterization:check` | Regenerate the contact sheets / visual snapshots only after reviewing the visual diff. |
-| ASCII grid mechanics | `bun test src/__tests__/characterization-layout.test.ts` plus `bun run mutation-test:characterization` | Update P-properties only when the algorithm deliberately changes. |
-| Renderer-family dispatch/output surfaces | `bun test src/__tests__/characterization-families.test.ts` | Drift outside the PR's claimed layout surface is suspicious and needs a separate explanation. |
-
-## Coverage across renderers
-
-The **depth** layer targets the flowchart + `stateDiagram-v2` family (the
-hand-written grid + A\* engine — see next section for why). The **breadth** layer
-extends the universal invariants to every diagram family and public output
-surface: text (`renderMermaidASCII`), SVG (`renderMermaidSVG`), and PNG
-(`renderMermaidPNG`, which rasterizes the SVG path). It asserts only what is
-empirically true for each:
-
-| Invariant | Holds for |
-|-----------|-----------|
-| Dispatch totality (non-empty text/SVG and valid PNG signature) | **every** family and public output surface |
-| Sentinel label conservation | **every** family on text/SVG surfaces |
-| Determinism (byte-identical) | **every** family on text/SVG/PNG matrix cases (also pinned corpus-wide for ASCII by `ascii-determinism.test.ts`) |
-| Output hygiene (no `NaN` / `Infinity` / `undefined`, no ANSI when color is disabled) | **every** family on text/SVG surfaces |
-| No diagonals | **every** family on text output (xychart plots with block glyphs, not `/\`) |
-| Rectangular canvas (all rows one width) | box/graph families only: flowchart, state, sequence, class, er |
-| Layered placement, non-overlap, round-trip (P5–P10) | flowchart/state grid engine only |
-
-The chart, list, schedule, and architecture families (timeline, journey, xychart,
-pie, quadrant, gantt, architecture) emit ragged rows by design, so rectangularity is **not**
-asserted there — and that boundary is pinned as a known limit. The deep
-structural and layering properties are specific to the grid engine and do not
-generalise; each non-grid family has its own layout strategy (documented in
-`contact-sheet-families.md`) whose deep per-family invariants are the natural
-next increment.
-
-The visual-quality layer deliberately sits beside, not inside, the minimal
-property kernel. It records SVG snapshots, PNG hashes, crossings, bends, route
-length, area fill, label fit, and edge-label overlap risk for one canonical case
-per family. Those values are approval signals: a diff should be inspected and
-approved, not automatically interpreted as a semantic bug. PR 30's rubric is the
-hard correctness oracle for route-contract families; these snapshots are the
-cross-family drift ledger.
-
----
-
-## What "the layout algorithm" means here
-
-This project has **two** distinct layout engines:
-
-1. **ELK-based engine** (`src/layout-engine.ts`) — wraps Eclipse Layout Kernel's
-   *layered* (Sugiyama) algorithm to produce pixel coordinates for **SVG/PNG**.
-   The placement is a configured third-party black box; the bespoke part is the
-   post-processing (layer snapping, edge bundling, margin routing, shape
-   clipping).
-2. **ASCII grid engine** (`src/ascii/grid.ts` + `pathfinder.ts` +
-   `edge-routing.ts` + `edge-bundling.ts`) — a **hand-written** grid layout with
-   **A\* orthogonal edge routing** that renders flowcharts and state diagrams as
-   character art. It is a TypeScript port and extension of
-   [`AlexanderGrooff/mermaid-ascii`](https://github.com/AlexanderGrooff/mermaid-ascii).
-
-**This characterisation targets the ASCII grid engine.** It is the genuinely
-"ours" algorithm (the ELK one delegates placement), it is pure / synchronous /
-deterministic / dependency-free, and it is the surface the project already
-mutation-tests (`stryker.ascii.config.json`). It is therefore the ideal
-characterisation subject. The flowchart and `stateDiagram-v2` families share
-this exact pipeline (`src/ascii/index.ts`); the other families (sequence, class,
-ER, pie, quadrant, xychart, timeline, journey, architecture) have their own
-renderers and are out of scope here.
-
-### The pipeline in one line
-
-```
-parseMermaid → convertToAsciiGraph → createMapping (grid + A*) → drawGraph → canvasToString
-```
-
-`createMapping` (`grid.ts`) is the heart: it places each node as a **3×3 grid
-block**, assigns layers along the flow axis with a **stride of 4**, routes every
-edge with a **bounded, deterministic A\***, and bundles fan-in/fan-out edges onto
-shared trunks.
-
----
-
-## How the layout works (the load-bearing mechanics)
-
-- **Grid model.** Every node owns a 3×3 block of an integer grid; `gridCoord` is
-  its top-left cell, and the eight surrounding cells are edge attachment points.
-  Blocks are placed 4 grid units apart (3 cells + a 1-cell routing gutter).
-- **Layer assignment.** Roots (nodes with no incoming edge) go at level 0;
-  each child is placed one level (stride 4) along the **flow axis** (y for
-  TD/BT, x for LR/RL). TD and LR are the same code with x/y transposed; **BT =
-  TD then vertical flip**; **RL is currently treated as LR**.
-- **A\* routing.** Edges are routed cell-by-cell with A\* over the same grid that
-  tracks node occupancy. Moves are 4-directional only (⇒ **orthogonal**, no
-  diagonals); the heuristic is Manhattan distance + a corner penalty (prefers
-  straight runs); ties break FIFO (⇒ **deterministic**); the search is bounded
-  (⇒ **terminates**, returns `null` + a straight fallback if walled off).
-- **Edge bundling.** Sibling fan-out / fan-in edges of the same style merge onto
-  a single shared trunk that splits at one junction; labelled siblings (which
-  can't bundle) share a trunk prefix instead.
-- **Best-effort, not a solver.** For cyclic / dense graphs the multi-pass
-  placement can drop or overlap nodes. That limitation is real, current, and
-  pinned by property **P10** rather than hidden.
-
-A fuller mechanical anatomy (with `file:line` citations for all 30+ invariants)
-informed `properties.md`; the citations are inlined there.
-
----
-
-## How this connects to the testing literature
-
-- **Characterisation tests** (Feathers, *WELC* ch. 13): tests that document the
-  system's *actual* behaviour, not its intended behaviour — the safety net for
-  refactoring. The contact sheet is the worked-example form; the property suite
-  is the generalised form.
-- **Approval / golden tests** (Falco): the contact sheet is generated and
-  reviewed as a diff — a surprising change is a regression, an expected change
-  is the new approved baseline. The repo's `src/__tests__/testdata/` corpus is
-  the byte-level golden layer beneath it.
-- **Property-based testing** (fast-check): the kernel asserts **invariants** and
-  **metamorphic relations** rather than exact outputs, so it generalises across
-  thousands of generated graphs instead of a handful of fixtures.
-- **Mutation testing** (Stryker, already configured): the oracle for *which*
-  properties are load-bearing — a property is kept only if it kills a mutant no
-  other test kills. See the minimality argument in `properties.md`.
-- **Visual approval / metric drift:** `visual-quality.md` keeps the literature's
-  aesthetic objectives visible (crossings, bends, area, label overlap) without
-  turning them into brittle universal laws.
-
-Together: **goldens characterise, properties generalise, mutation proves which
-assertions do work, visual snapshots make quality drift reviewable.**
-
----
-
-## Reproduce
-
-```bash
-bun install
-
-# Executable characterisation kernels
-bun test src/__tests__/characterization-layout.test.ts     # grid engine (depth)
-bun test src/__tests__/characterization-families.test.ts   # all families (breadth)
-bun test src/__tests__/characterization-generated-artifacts.test.ts
-
-# Regenerate the contact sheets / visual report, then review the diff and commit
-bun run scripts/characterization/contact-sheet.ts
-bun run scripts/characterization/contact-sheet-families.ts
-bun run scripts/characterization/visual-quality.ts
-git diff docs/layout-characterization/
-
-# CI-friendly generated-artifact drift check
-bun run characterization:check
-
-# Route-contract correctness gates introduced by PR 30
-bun test src/__tests__/contact-sheet.test.ts src/__tests__/layout-rubric.test.ts
-bun run track
-
-# (optional) quick mutation evidence for the load-bearing ranges
-bun run mutation-test:characterization
-
-# exhaustive but slow: mutates the whole ASCII layout core
-bun run mutation-test:ascii
-```
-
-## Sources
-
-Layered graph drawing: Sugiyama–Tagawa–Toda (1981); Gansner–Koutsofios–North–Vo
-(1993, the `dot` algorithm, <https://www.graphviz.org/documentation/TSE93.pdf>);
-Brandes–Köpf (2002). A\*: Hart–Nilsson–Raphael (1968). Orthogonal routing:
-Tamassia (1987); Wybrow–Marriott–Stuckey (2009),
-<https://users.monash.edu/~mwybrow/papers/wybrow-gd-2009.pdf>. ELK:
-<https://eclipse.dev/elk/>. ASCII prior art: mermaid-ascii
-(<https://github.com/AlexanderGrooff/mermaid-ascii>), Graph::Easy. Testing:
-Feathers, *Working Effectively with Legacy Code* (2004); Falco, ApprovalTests
-(<https://approvaltests.com/>); Bartocci et al., property-based mutation testing
-(2023, <https://arxiv.org/pdf/2301.13615>).