@miragon/team-topologies-schema-model 0.10.1 → 0.11.0

package/README.md

@@ -43,7 +43,7 @@ relate to (spatial overlap, the Team Topologies convention) — there is no sour
 ```jsonc
 {
   "version": 3,
-  "title": "Online shop — team topology",
+  "title": "Online shop team topology",
   "nodes": [
     {
       "id": "team_checkout",
@@ -146,24 +146,34 @@ console.log(SAMPLE_DOCUMENT.title);
 
 ### API surface
 
-| Export                                                                                                                      | Purpose                                                              |
-| --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `TtDocument`, `TeamNode`, `InteractionShape`, `FlowShape`, `TextAnnotation`, `Position`, `Size`                             | The document model types.                                            |
-| `TeamType`, `InteractionMode`, `TEAM_TYPES`, `INTERACTION_MODES`                                                            | The notation's discriminator unions + their value lists.             |
-| `TEAM_TYPE_SPECS`, `INTERACTION_MODE_SPECS`, `FLOW_SPEC`, `ANNOTATION_SPEC`, `dashArray()`                                  | The visual notation spec (shapes, colours, strokes) as data.         |
-| `documentSchema`, `teamNodeSchema`, `interactionSchema`, `flowSchema`, `annotationSchema`                                   | Zod schemas for each shape.                                          |
-| `parseDocument()`, `ParseResult`                                                                                            | Validate **and migrate** unknown input into a `TtDocument`.          |
-| `serializeDocument()`, `canonicalize()`                                                                                     | Deterministic JSON serialization (sorted, rounded, fixed key order). |
-| `emptyDocument()`, `createTeamNode()`, `createInteractionShape()`, `createFlowShape()`, `createTextAnnotation()`, `newId()` | Factories with notation defaults + id generation.                    |
-| `SAMPLE_DOCUMENT`                                                                                                           | A complete example topology.                                         |
-| `DOCUMENT_VERSION`                                                                                                          | The current document version (`3`).                                  |
+| Export                                                                                                                      | Purpose                                                                                               |
+| --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `TtDocument`, `TeamNode`, `InteractionShape`, `FlowShape`, `TextAnnotation`, `Position`, `Size`                             | The document model types.                                                                             |
+| `TeamType`, `InteractionMode`, `TEAM_TYPES`, `INTERACTION_MODES`                                                            | The notation's discriminator unions + their value lists.                                              |
+| `TEAM_TYPE_SPECS`, `INTERACTION_MODE_SPECS`, `FLOW_SPEC`, `ANNOTATION_SPEC`, `dashArray()`                                  | The visual notation spec (shapes, colours, strokes) as data.                                          |
+| `documentSchema`, `teamNodeSchema`, `interactionSchema`, `flowSchema`, `annotationSchema`                                   | Zod schemas for each shape.                                                                           |
+| `parseDocument()`, `ParseResult`, `DocumentIssue`                                                                           | Validate **and migrate** unknown input into a `TtDocument`; a failure lists each issue with its path. |
+| `serializeDocument()`, `canonicalize()`                                                                                     | Deterministic JSON serialization (sorted, rounded, fixed key order).                                  |
+| `foreignFields()`, `withForeignFields()`, `DOCUMENT_FIELDS`, `TEAM_NODE_FIELDS`, …                                          | The fields a document carries beyond the known ones.                                                  |
+| `documentIdProblems()`, `DIAGRAM_ROOT_ID`, `associationId()`                                                                | The id rules (unique, not reserved).                                                                  |
+| `emptyDocument()`, `createTeamNode()`, `createInteractionShape()`, `createFlowShape()`, `createTextAnnotation()`, `newId()` | Factories with notation defaults + id generation.                                                     |
+| `SAMPLE_DOCUMENT`                                                                                                           | A complete example topology.                                                                          |
+| `DOCUMENT_VERSION`                                                                                                          | The current document version (`3`).                                                                   |
 
 ## Determinism & migrations
 
 - **Determinism** — `serializeDocument()` runs `canonicalize()` first: arrays are sorted by `id`,
   coordinates are rounded to two decimals, optional fields with no value are dropped, and keys are
   written in a fixed order. The same logical diagram always produces byte-identical JSON, which is
-  what makes Git diffs small and share URLs stable.
+  what makes Git diffs small and share URLs stable. The pretty form (the default) is the file on
+  disk and ends with a line break; the compact form (`serializeDocument(doc, false)`) has none.
+- **Unknown fields** — fields a document carries that this package does not know (a vendor's
+  `"x-vendor"` on the root or on an element) pass `parseDocument()` untouched and are written after
+  the known fields, sorted by name (nested keys too), so another tool's data survives a save.
+- **Ids** — `parseDocument()` rejects a document whose ids would collide on the canvas: an id used
+  twice, the diagram's own id `tt-root` (`DIAGRAM_ROOT_ID`), ids starting with `__implicitroot`, and
+  `assoc_<annotation id>` (`associationId()`), the id of that annotation's connector.
+  `documentIdProblems()` lists them with their path.
 - **Migrations** — `parseDocument()` upgrades older documents before validating (keyed by `version`).
   The `1 → 2` step drops the legacy `showFlowOfChange` flag and the old edge-based interactions,
   keeping only interactions that carry geometry (the placed-shape model). The `2 → 3` step adds an

package/dist/index.cjs

@@ -140,6 +140,52 @@ function dashArray(style, strokeWidth = 2) {
 }
 var ALL_TEAM_SPECS = Object.values(TEAM_TYPE_SPECS);
 var ALL_INTERACTION_SPECS = Object.values(INTERACTION_MODE_SPECS);
+
+// src/ids.ts
+var DIAGRAM_ROOT_ID = "tt-root";
+var ENGINE_ROOT_ID_PREFIX = "__implicitroot";
+function associationId(annotationId) {
+  return `assoc_${annotationId}`;
+}
+var COLLECTIONS = ["nodes", "interactions", "flows", "annotations"];
+function documentIdProblems(doc) {
+  const problems = [];
+  const connectorIds = new Map(
+    doc.annotations.map((annotation) => [associationId(annotation.id), annotation.id])
+  );
+  const seen = /* @__PURE__ */ new Set();
+  for (const collection of COLLECTIONS) {
+    doc[collection].forEach((element, index) => {
+      const path = [collection, index, "id"];
+      const { id } = element;
+      if (seen.has(id)) {
+        problems.push({
+          path,
+          message: `duplicate id "${id}"; ids must be unique across nodes, interactions, flows and annotations`
+        });
+      }
+      seen.add(id);
+      if (id === DIAGRAM_ROOT_ID) {
+        problems.push({ path, message: `"${id}" is reserved for the diagram itself` });
+      } else if (id.startsWith(ENGINE_ROOT_ID_PREFIX)) {
+        problems.push({
+          path,
+          message: `ids starting with "${ENGINE_ROOT_ID_PREFIX}" are reserved`
+        });
+      }
+      const annotationId = connectorIds.get(id);
+      if (annotationId !== void 0) {
+        problems.push({
+          path,
+          message: `"${id}" is reserved for the connector of annotation "${annotationId}"`
+        });
+      }
+    });
+  }
+  return problems;
+}
+
+// src/schema.ts
 var teamTypeSchema = zod.z.enum(TEAM_TYPES);
 var interactionModeSchema = zod.z.enum(INTERACTION_MODES);
 var sizeSchema = zod.z.object({
@@ -151,7 +197,7 @@ var positionSchema = zod.z.object({
   y: zod.z.number().finite()
 });
 var hexColor = zod.z.string().regex(/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/, "expected a hex colour");
-var teamNodeSchema = zod.z.object({
+var teamNodeSchema = zod.z.looseObject({
   id: zod.z.string().min(1),
   type: teamTypeSchema,
   label: zod.z.string(),
@@ -161,7 +207,7 @@ var teamNodeSchema = zod.z.object({
   fill: hexColor.optional(),
   stroke: hexColor.optional()
 });
-var interactionSchema = zod.z.object({
+var interactionSchema = zod.z.looseObject({
   id: zod.z.string().min(1),
   mode: interactionModeSchema,
   label: zod.z.string().optional(),
@@ -170,34 +216,43 @@ var interactionSchema = zod.z.object({
   fill: hexColor.optional(),
   stroke: hexColor.optional()
 });
-var flowSchema = zod.z.object({
+var flowSchema = zod.z.looseObject({
   id: zod.z.string().min(1),
   label: zod.z.string().optional(),
   position: positionSchema,
   size: sizeSchema
 });
-var annotationSchema = zod.z.object({
+var annotationSchema = zod.z.looseObject({
   id: zod.z.string().min(1),
   text: zod.z.string(),
   position: positionSchema,
   size: sizeSchema,
   attachedTo: zod.z.string().min(1).optional()
 });
-var documentSchema = zod.z.object({
+var documentSchema = zod.z.looseObject({
   version: zod.z.literal(DOCUMENT_VERSION),
   title: zod.z.string(),
   nodes: zod.z.array(teamNodeSchema),
   interactions: zod.z.array(interactionSchema),
   flows: zod.z.array(flowSchema),
   annotations: zod.z.array(annotationSchema)
+}).superRefine((document, context) => {
+  for (const { path, message } of documentIdProblems(document)) {
+    context.addIssue({ code: "custom", path, message });
+  }
 });
 function parseDocument(input) {
   const migrated = migrate(input);
   const result = documentSchema.safeParse(migrated);
   if (!result.success) {
+    const issues = result.error.issues.map((issue) => ({
+      path: issue.path.filter((key) => typeof key !== "symbol"),
+      message: issue.message
+    }));
     return {
       ok: false,
-      error: result.error.issues.map((i2) => `${i2.path.join(".") || "(root)"}: ${i2.message}`).join("; ")
+      error: issues.map((i2) => `${i2.path.join(".") || "(root)"}: ${i2.message}`).join("; "),
+      issues
     };
   }
   return { ok: true, document: result.data };
@@ -218,6 +273,56 @@ function migrate(input) {
   return next;
 }
 
+// src/foreign.ts
+var DOCUMENT_FIELDS = [
+  "version",
+  "title",
+  "nodes",
+  "interactions",
+  "flows",
+  "annotations"
+];
+var TEAM_NODE_FIELDS = [
+  "id",
+  "type",
+  "label",
+  "description",
+  "position",
+  "size",
+  "fill",
+  "stroke"
+];
+var INTERACTION_FIELDS = [
+  "id",
+  "mode",
+  "label",
+  "position",
+  "size",
+  "fill",
+  "stroke"
+];
+var FLOW_FIELDS = ["id", "label", "position", "size"];
+var ANNOTATION_FIELDS = ["id", "text", "position", "size", "attachedTo"];
+function canonicalValue(value) {
+  if (Array.isArray(value)) return value.map(canonicalValue);
+  if (value === null || typeof value !== "object") return value;
+  const record = value;
+  return Object.fromEntries(
+    Object.keys(record).filter((key) => record[key] !== void 0).sort().map((key) => [key, canonicalValue(record[key])])
+  );
+}
+function foreignFields(value, knownFields) {
+  const record = value;
+  const names = Object.keys(record).filter((name) => !knownFields.includes(name) && record[name] !== void 0).sort();
+  if (names.length === 0) return void 0;
+  return Object.fromEntries(names.map((name) => [name, canonicalValue(record[name])]));
+}
+function withForeignFields(known, source, knownFields) {
+  const foreign = source ? foreignFields(source, knownFields) : void 0;
+  if (!foreign) return known;
+  return Object.fromEntries([...Object.entries(known), ...Object.entries(foreign)]);
+}
+
 // src/serialize.ts
 function round(n) {
   return Math.round(n * 100) / 100;
@@ -239,7 +344,7 @@ function normNode(n) {
   if (n.description) out.description = n.description;
   if (n.fill) out.fill = n.fill;
   if (n.stroke) out.stroke = n.stroke;
-  return out;
+  return withForeignFields(out, n, TEAM_NODE_FIELDS);
 }
 function normInteraction(e) {
   const out = {
@@ -251,7 +356,7 @@ function normInteraction(e) {
   if (e.label) out.label = e.label;
   if (e.fill) out.fill = e.fill;
   if (e.stroke) out.stroke = e.stroke;
-  return out;
+  return withForeignFields(out, e, INTERACTION_FIELDS);
 }
 function normFlow(f) {
   const out = {
@@ -260,7 +365,7 @@ function normFlow(f) {
     size: normSize(f.size)
   };
   if (f.label) out.label = f.label;
-  return out;
+  return withForeignFields(out, f, FLOW_FIELDS);
 }
 function normAnnotation(a) {
   const out = {
@@ -270,23 +375,28 @@ function normAnnotation(a) {
     size: normSize(a.size)
   };
   if (a.attachedTo) out.attachedTo = a.attachedTo;
-  return out;
+  return withForeignFields(out, a, ANNOTATION_FIELDS);
 }
 var byId = (a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
 function canonicalize(doc) {
-  return {
-    version: DOCUMENT_VERSION,
-    title: doc.title,
-    nodes: [...doc.nodes].map(normNode).sort(byId),
-    interactions: [...doc.interactions].map(normInteraction).sort(byId),
-    flows: [...doc.flows].map(normFlow).sort(byId),
-    annotations: [...doc.annotations].map(normAnnotation).sort(byId)
-  };
+  return withForeignFields(
+    {
+      version: DOCUMENT_VERSION,
+      title: doc.title,
+      nodes: [...doc.nodes].map(normNode).sort(byId),
+      interactions: [...doc.interactions].map(normInteraction).sort(byId),
+      flows: [...doc.flows].map(normFlow).sort(byId),
+      annotations: [...doc.annotations].map(normAnnotation).sort(byId)
+    },
+    doc,
+    DOCUMENT_FIELDS
+  );
 }
 function serializeDocument(doc, pretty = true) {
-  const { annotations, ...canonical } = canonicalize(doc);
-  const output = annotations.length > 0 ? { ...canonical, annotations } : canonical;
-  return JSON.stringify(output, null, pretty ? 2 : 0);
+  const canonical = canonicalize(doc);
+  const output = canonical.annotations.length > 0 ? canonical : Object.fromEntries(Object.entries(canonical).filter(([key]) => key !== "annotations"));
+  return pretty ? `${JSON.stringify(output, null, 2)}
+` : JSON.stringify(output);
 }
 function newId(prefix) {
   return `${prefix}_${nanoid.nanoid(8)}`;
@@ -347,40 +457,49 @@ function emptyDocument(title = "Untitled team topology") {
 // src/sample.ts
 var s = TEAM_TYPE_SPECS;
 var i = INTERACTION_MODE_SPECS;
+var LANE_WIDTH = 600;
 var SAMPLE_DOCUMENT = {
   version: DOCUMENT_VERSION,
-  title: "Online shop \u2014 team topology",
+  title: "Online shop team topology",
   nodes: [
     {
       id: "team_test_automation",
       type: "enabling",
       label: "Test Automation",
       description: "Coaches stream-aligned teams in test automation, then steps back.",
-      position: { x: 60, y: 150 },
-      size: { ...s.enabling.defaultSize }
+      position: { x: 40, y: 150 },
+      size: { width: s.enabling.defaultSize.width, height: 222 }
     },
     {
       id: "team_discovery",
       type: "stream-aligned",
       label: "Product Discovery",
       description: "Owns search, browsing and product pages end-to-end.",
-      position: { x: 240, y: 202 },
-      size: { ...s["stream-aligned"].defaultSize }
+      position: { x: 220, y: 150 },
+      size: { width: LANE_WIDTH, height: s["stream-aligned"].defaultSize.height }
     },
     {
       id: "team_checkout",
       type: "stream-aligned",
       label: "Checkout & Payments",
       description: "Owns the checkout and payment journey end-to-end.",
-      position: { x: 560, y: 202 },
-      size: { ...s["stream-aligned"].defaultSize }
+      position: { x: 220, y: 276 },
+      size: { width: LANE_WIDTH, height: s["stream-aligned"].defaultSize.height }
+    },
+    {
+      id: "team_fulfilment",
+      type: "stream-aligned",
+      label: "Order Fulfilment",
+      description: "Owns delivery, tracking and returns end-to-end.",
+      position: { x: 220, y: 402 },
+      size: { width: LANE_WIDTH, height: s["stream-aligned"].defaultSize.height }
     },
     {
       id: "team_fraud",
       type: "complicated-subsystem",
       label: "Fraud Detection",
       description: "Specialists for the real-time fraud scoring model.",
-      position: { x: 870, y: 175 },
+      position: { x: 880, y: 249 },
       size: { ...s["complicated-subsystem"].defaultSize }
     },
     {
@@ -388,34 +507,34 @@ var SAMPLE_DOCUMENT = {
       type: "platform",
       label: "Cloud Platform",
       description: "Self-service CI/CD, runtime and observability for all teams.",
-      position: { x: 240, y: 352 },
-      size: { width: 560, height: 110 }
+      position: { x: 220, y: 552 },
+      size: { width: LANE_WIDTH, height: 110 }
     }
   ],
   interactions: [
     {
       id: "int_testing_discovery",
       mode: "facilitating",
-      position: { x: 168, y: 208 },
+      position: { x: 148, y: 156 },
+      size: { ...i.facilitating.defaultSize }
+    },
+    {
+      id: "int_testing_checkout",
+      mode: "facilitating",
+      position: { x: 148, y: 282 },
       size: { ...i.facilitating.defaultSize }
     },
     {
       id: "int_checkout_fraud",
       mode: "collaboration",
       label: "fraud rules",
-      position: { x: 779, y: 214 },
+      position: { x: 794, y: 288 },
       size: { ...i.collaboration.defaultSize }
     },
     {
-      id: "int_platform_discovery",
-      mode: "x-as-a-service",
-      position: { x: 316, y: 286 },
-      size: { ...i["x-as-a-service"].defaultSize }
-    },
-    {
-      id: "int_platform_checkout",
+      id: "int_platform_fulfilment",
       mode: "x-as-a-service",
-      position: { x: 636, y: 286 },
+      position: { x: 476, y: 486 },
       size: { ...i["x-as-a-service"].defaultSize }
     }
   ],
@@ -423,15 +542,15 @@ var SAMPLE_DOCUMENT = {
     {
       id: "flow_main",
       label: "Flow of change",
-      position: { x: 60, y: 60 },
-      size: { width: 980, height: 56 }
+      position: { x: 40, y: 40 },
+      size: { width: 1010, height: 56 }
     }
   ],
   annotations: [
     {
       id: "ann_fraud_handover",
       text: "Collaboration until the fraud rules are stable (Q3), then X-as-a-Service",
-      position: { x: 830, y: 350 },
+      position: { x: 880, y: 423 },
       size: { ...ANNOTATION_SPEC.defaultSize },
       attachedTo: "int_checkout_fraud"
     }
@@ -440,29 +559,39 @@ var SAMPLE_DOCUMENT = {
 
 exports.ALL_INTERACTION_SPECS = ALL_INTERACTION_SPECS;
 exports.ALL_TEAM_SPECS = ALL_TEAM_SPECS;
+exports.ANNOTATION_FIELDS = ANNOTATION_FIELDS;
 exports.ANNOTATION_SPEC = ANNOTATION_SPEC;
+exports.DIAGRAM_ROOT_ID = DIAGRAM_ROOT_ID;
 exports.DND_MIME = DND_MIME;
+exports.DOCUMENT_FIELDS = DOCUMENT_FIELDS;
 exports.DOCUMENT_VERSION = DOCUMENT_VERSION;
+exports.FLOW_FIELDS = FLOW_FIELDS;
 exports.FLOW_SPEC = FLOW_SPEC;
+exports.INTERACTION_FIELDS = INTERACTION_FIELDS;
 exports.INTERACTION_MODES = INTERACTION_MODES;
 exports.INTERACTION_MODE_SPECS = INTERACTION_MODE_SPECS;
 exports.SAMPLE_DOCUMENT = SAMPLE_DOCUMENT;
+exports.TEAM_NODE_FIELDS = TEAM_NODE_FIELDS;
 exports.TEAM_TYPES = TEAM_TYPES;
 exports.TEAM_TYPE_SPECS = TEAM_TYPE_SPECS;
 exports.annotationSchema = annotationSchema;
+exports.associationId = associationId;
 exports.canonicalize = canonicalize;
 exports.createFlowShape = createFlowShape;
 exports.createInteractionShape = createInteractionShape;
 exports.createTeamNode = createTeamNode;
 exports.createTextAnnotation = createTextAnnotation;
 exports.dashArray = dashArray;
+exports.documentIdProblems = documentIdProblems;
 exports.documentSchema = documentSchema;
 exports.emptyDocument = emptyDocument;
 exports.flowSchema = flowSchema;
+exports.foreignFields = foreignFields;
 exports.interactionSchema = interactionSchema;
 exports.newId = newId;
 exports.parseDocument = parseDocument;
 exports.serializeDocument = serializeDocument;
 exports.teamNodeSchema = teamNodeSchema;
+exports.withForeignFields = withForeignFields;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map