compasso 0.1.0 → 0.3.0

package/README.md

@@ -1,11 +1,14 @@
 # compasso
 
-Standards-faithful relational diagrams as **pure SVG strings**. Deterministic, zero
+Standards-faithful technical diagrams as **pure SVG strings**. Deterministic, zero
 runtime dependencies, server-safe (no DOM, no canvas, no clock, no randomness).
 
-**v0.1 ships two clinical diagrams:** the **genogram** (McGoldrick family-systems
-notation) and the **ecomap** (radial person↔environment ties). The architecture is
-built for more — see the roadmap.
+**Six diagrams shipped:** the **genogram** (McGoldrick family-systems notation), the
+**ecomap** (radial person↔environment ties), the **fault tree** (NUREG-0492 / IEC 61025
+distinctive-shape notation), the **fishbone** (Ishikawa cause-and-effect), the
+**pedigree** (Bennett 2008 standardized clinical-genetics nomenclature) and the
+**phylogenetic tree** (cladogram + phylogram). The architecture is built for more —
+see the roadmap.
 
 ## Principles
 
@@ -85,6 +88,114 @@ Arrowheads appear **only** for a declared `direction` (`"in"` toward the center,
 `"out"` toward the system, `"both"`); `null` draws no arrow — never a default. Large
 sets split onto two alternating rings; node spacing is overlap-proof by construction.
 
+## Fault tree
+
+```ts
+import { faultTreeSvg } from "compasso/fault-tree";
+
+const { svg, layout } = faultTreeSvg({
+  topId: 1,
+  events: [
+    { id: 1, kind: "intermediate", label: "Pump system fails", code: "TOP" },
+    { id: 2, kind: "basic", label: "Motor winding failure", code: "B1" },
+    { id: 3, kind: "undeveloped", label: "Control logic fault", code: "U1" },
+  ],
+  gates: [{ id: 1, type: "or", eventId: 1, inputIds: [2, 3] }],
+});
+```
+
+NUREG-0492 distinctive shapes: rectangles (intermediate events), circles (basic),
+diamonds (undeveloped), house (expected external events), oval (conditioning events
+attached to INHIBIT gates), transfer triangles. Gates: `and | or | xor | inhibit |
+vote` (k-of-n, drawn with its threshold). The layout is deterministic, orthogonal and
+overlap-proof (proven by its own test harness).
+
+A fault tree is a **logic artifact**, so structurally invalid input is **refused**, not
+repaired: `faultTreeSvg` throws `FaultTreeValidationError` listing **every** issue with
+a stable machine-readable `code` (`event-without-gate`, `cycle`, `unknown-input`, …).
+Honest incompleteness has standard notation instead — that's what `undeveloped` and
+`transfer` are for.
+
+## Fishbone
+
+```ts
+import { fishboneSvg } from "compasso/fishbone";
+
+const svg = fishboneSvg({
+  effectLabel: "Late deliveries",
+  categories: [
+    {
+      id: 1,
+      label: "People",
+      causes: [
+        { id: 1, label: "Driver shortage", subCauses: [{ id: 1, label: "High turnover" }] },
+      ],
+    },
+  ],
+});
+```
+
+Classic Ishikawa: spine into the effect head, category bones alternating above/below,
+horizontal cause twigs, one level of sub-causes, arrowheads converging toward the
+effect at every level (suppressible via `arrowheads: false`). **Declared order is
+honored** — significance-near-the-head is the analyst's call, never re-sorted. Label
+spacing is driven by measured text widths, so labels never collide.
+
+## Pedigree
+
+```ts
+import { pedigreeSvg } from "compasso/pedigree";
+
+const { svg } = pedigreeSvg({
+  conditions: [{ id: 1, label: "Cystic fibrosis" }],
+  individuals: [
+    { id: 1, label: "I-1", sex: "male", generation: 1, deceased: true, carrier: true, role: null, lifeStatus: "alive", affectedBy: [] },
+    { id: 2, label: "I-2", sex: "female", generation: 1, deceased: false, carrier: true, role: null, lifeStatus: "alive", affectedBy: [] },
+    { id: 3, label: "II-1", sex: "female", generation: 2, deceased: false, carrier: false, role: "proband", lifeStatus: "alive", affectedBy: [1] },
+  ],
+  matings: [{ id: 1, partnerAId: 1, partnerBId: 2, consanguineous: false }],
+  sibships: [{ id: 1, matingId: 1, childIds: [3], twinGroups: [] }],
+});
+```
+
+Standardized clinical-genetics notation (Bennett et al. 2008): square/circle/diamond by
+sex, **filled glyph = affected** (multiple conditions shown as up to four vertical
+partitions), carrier center dot, deceased slash, **proband filled arrow / consultand
+open arrow**, **consanguineous matings as a double line**, MZ/DZ/unknown-zygosity twins,
+Roman-numeral generations with within-generation "II-3" addresses. A pedigree is a
+clinical record, so structurally invalid input is **refused with coded issues**
+(`PedigreeValidationError`), never silently repaired. The layout is deterministic and
+overlap-proof — including remarriages and multi-spouse hubs.
+
+## Phylogenetic tree
+
+```ts
+import { phyloSvg } from "compasso/phylo";
+
+const { svg } = phyloSvg({
+  rootId: 1,
+  nodes: [
+    { id: 1, label: "root" },
+    { id: 2, label: "Clade A", support: 98 },
+    { id: 3, label: "Homo sapiens" },
+    { id: 4, label: "Pan troglodytes" },
+  ],
+  edges: [
+    { id: 1, parentId: 1, childId: 2, length: 0.4 },
+    { id: 2, parentId: 2, childId: 3, length: 0.6 },
+    { id: 3, parentId: 2, childId: 4, length: 0.55 },
+  ],
+}, { mode: "phylogram", showSupport: true });
+```
+
+Rectangular cladogram or phylogram. In `phylogram` mode each node's x is its cumulative
+branch length from the root (fit to width); in `cladogram` mode tips right-align with
+optional dotted extensions. Optional bootstrap/posterior `support` values at clades and a
+distance scale bar (phylogram only). The flat `{rootId, nodes, edges}` AST is
+Newick-importable. Branch lengths are never lost — a `null`/zero length is valid (the
+node sits at its parent's depth), and the verbatim length always rides the branch
+`<title>`.
+
 ## Localization
 
 ```ts
@@ -110,10 +221,17 @@ with a negation list. PRs for new locales are welcome.
 ## Roadmap
 
 The goal is a family of standards-faithful technical diagrams sharing this core
-(text metrics, stroke vocabulary, escaping, legend machinery): tree-based diagrams
-(fault tree, phylogenetic, fishbone), flow/layered diagrams (PRISMA, UML), and
-symbol-library diagrams (P&ID, single-line, ladder logic) — each built from its public
-standard. AST-first; text DSLs may come later.
+(text metrics, stroke vocabulary, escaping, legend machinery). Shipped: genogram,
+ecomap, fault tree, fishbone, pedigree, phylogenetic tree. Next: org charts, flow/
+layered diagrams (PRISMA, UML), and symbol-library diagrams (P&ID, single-line, ladder
+logic) — each built from its public standard. AST-first; text DSLs may come later.
+
+## Contributing
+
+`AGENTS.md` is the contract for changing compasso (the house conventions: pure
+input→SVG, determinism, the honesty rule, the overlap harness, validation doctrine,
+module anatomy). `docs/architecture.md` covers the internal structure and `docs/design/`
+the per-module design rationale.
 
 ## Provenance & license