@miragon/design-iq-validator 5.5.0 → 5.7.0

package/README.md

@@ -3,13 +3,50 @@
 Deterministic validator for designIQ content repositories: `designiq.yml` discovery, BPMN
 structural checks (flow soundness, complete BPMNDI coverage), DMN structure and DMNDI coverage,
 the generic cross-model reference rule (every required reference — `callActivity` calls,
-`businessRuleTask` decides — must resolve in the repo), and a per-mediaKind parse baseline for
-every other registered notation (a broken `.tt`/`.vc.json` is an ERROR; DSL notations are
-lenient by design; a `mermaid` fence in a Markdown document that does not start with a diagram
-type such as `flowchart` or `sequenceDiagram` is a WARN, `mermaid/diagram-type`, naming the
-document's line). Every finding carries a stable `ruleId` (e.g. `bpmn/flow`, `dmn/di`,
-`refs/dangling`). It treats the target repo as pure data — it never executes content-repo code.
-Exit code 0 = no errors (warnings allowed), 1 = errors.
+`businessRuleTask` decides — must resolve in the repo), the schema check of the Miragon JSON
+notations, and a per-mediaKind parse baseline for every other registered notation (a file that
+is no JSON or XML is an ERROR; DSL notations are lenient by design; a `mermaid` fence in a
+Markdown document that does not start with a diagram type such as `flowchart` or
+`sequenceDiagram` is a WARN, `mermaid/diagram-type`, naming the document's line). Every finding
+carries a stable `ruleId` (e.g. `bpmn/flow`, `dmn/di`, `refs/dangling`). It treats the target
+repo as pure data — it never executes content-repo code. Exit code 0 = no errors (warnings
+allowed), 1 = errors.
+
+## Team Topologies, Context Maps and Value Chains
+
+A `.tt`/`.ttm.json`, `.cm.json` or `.vc.json` file is parsed with the schema model its canvas
+opens it with (`@miragon/team-topologies-schema-model`, `@miragon/context-maps-schema-model`,
+`@miragon/value-chain-schema-model`). Whatever the schema model refuses, the canvas cannot open,
+so each refusal is an ERROR (`team-topology/schema`, `context-map/schema`,
+`value-chain/schema`) that names the offending value by its JSON path, e.g.
+`nodes.1.id: duplicate id "a"`. Refused among others:
+
+- a duplicate id, and the ids the diagram keeps for itself: `tt-root`, `cm-root`, `vc-root`,
+  every id starting with `__implicitroot`, and `assoc_<annotation id>` in a Team Topology;
+- in all three notations, an id that names a built-in JavaScript object property such as
+  `constructor`, `toString` or `__proto__`: the canvas keeps its elements in a plain object and
+  cannot import it;
+- in a Team Topology whose `version` is not 1, a file without `version` included: an interaction
+  without `position` or `size`, at the missing field (`interactions.0.size`). Opened anyway, it
+  would drop out of the file with the next save. A version 1 file still loses its edge
+  interactions, which have no geometry;
+- in a Context Map: a JSON list instead of an object, a `version` newer than 1, coordinates or
+  sizes beyond 1,000,000, and a repeated id at the path of the repeat, e.g.
+  `contexts.2.id: duplicate id "a"; ids must be unique across contexts and relationships`;
+- in a Value Chain: keys other than `x`, `y`, `width`, `height` in `bounds` and other than `x`,
+  `y` in a waypoint, coordinates beyond ±1e9, a `__proto__` key anywhere, and nesting deeper than
+  100 levels;
+- in a Team Topology and a Context Map: a document nested too deep for the schema model's
+  serializer, which every canvas save runs, as `(root): could not be checked: …`.
+
+A Context Map's strategic-DDD rules (`validateDocument`, e.g. `protect-or-conform`,
+`endpoints-on-map`) are WARNs, `context-map/semantics`, with the rule named at the end of the
+message: the canvas opens such a map and marks the finding.
+
+Paths count in the file, a Team Topology's interactions included. Some rules only run once the
+document's shape is valid: the id rules of a Team Topology and a Value Chain, and a Context Map's
+strategic-DDD rules. Fixing the reported errors can therefore bring up further ones, so check
+again until the file is clean.
 
 ## Usage
 

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as runCli } from "./validate-DjtZJTGk.js";
+import { o as runCli } from "./validate-CUTctX4d.js";
 //#region src/cli.ts
 /**
 * CLI entry for the platform validator. A dedicated entry file (instead of an

package/dist/{content-wjC_epKd.js → content-B0u0kwZN.js}

@@ -1 +1 @@
-export { t as CONTENT_CONFIG_FILE, i as contentConfigConflict, a as discoverModels, o as legacyContentConfigFile, s as loadContentConfig } from "./content-Bsv9ZLFd.js";
+export { t as CONTENT_CONFIG_FILE, i as contentConfigConflict, a as discoverModels, o as legacyContentConfigFile, s as loadContentConfig } from "./content-DfRb_tAL.js";

package/dist/{content-Bsv9ZLFd.js → content-DfRb_tAL.js}

@@ -535,22 +535,27 @@ function extractWardley(raw) {
 		edges
 	};
 }
+const TT_EDGE_INTERACTIONS_VERSION = 1;
 function extractTeamTopology(raw) {
 	const data = JSON.parse(raw);
+	const list = (v) => Array.isArray(v) ? v : [];
+	const teams = list(data.nodes).map((n) => ({
+		id: n.id,
+		type: n.type ?? "team",
+		name: n.label ?? n.name,
+		extra: n.description ? { description: n.description } : void 0
+	}));
+	const placed = (i) => "position" in i && "size" in i;
+	const interactions = list(data.interactions).filter((i) => i !== null && typeof i === "object").filter((i) => data.version !== TT_EDGE_INTERACTIONS_VERSION || placed(i)).map((i) => ({
+		id: i.id,
+		type: "interaction",
+		name: i.label,
+		extra: { mode: i.mode }
+	}));
 	return {
 		notation: "team-topology",
-		nodes: (data.nodes ?? []).map((n) => ({
-			id: n.id,
-			type: n.type ?? "team",
-			name: n.label ?? n.name,
-			extra: n.description ? { description: n.description } : void 0
-		})),
-		edges: (data.edges ?? []).map((e, i) => ({
-			id: e.id ?? `edge-${i}`,
-			from: e.source ?? e.from,
-			to: e.target ?? e.to,
-			kind: e.interaction ?? e.type ?? "interaction"
-		}))
+		nodes: [...teams, ...interactions],
+		edges: []
 	};
 }
 const STORM_ID_PREFIX = {
@@ -801,7 +806,7 @@ function extractValueChain(raw) {
 		nodes: (data.elements ?? []).map((el) => ({
 			id: el.id,
 			type: el.elementType ?? "element",
-			name: el.label ?? el.name
+			name: el.name
 		})),
 		edges: (data.connections ?? []).map((c, i) => ({
 			id: c.id ?? `conn-${i}`,

package/dist/{validate-DjtZJTGk.js → validate-CUTctX4d.js}

@@ -1,6 +1,9 @@
-import { _ as byId, c as resolveContentConfigFile, d as extractModelGraph, f as parseXml, g as byExtension, h as kindOf, l as XMLValidator, m as requirementHref, p as readBpmn, r as CONTENT_CONFIG_NAMES, u as asArray } from "./content-Bsv9ZLFd.js";
+import { _ as byId, c as resolveContentConfigFile, d as extractModelGraph, f as parseXml, g as byExtension, h as kindOf, l as XMLValidator, m as requirementHref, p as readBpmn, r as CONTENT_CONFIG_NAMES, u as asArray } from "./content-DfRb_tAL.js";
 import { readFileSync } from "node:fs";
 import { relative, resolve } from "node:path";
+import { parseDocumentText, serializeDocumentText, validateDocument } from "@miragon/context-maps-schema-model";
+import { parseDocument, serializeDocument } from "@miragon/team-topologies-schema-model";
+import { documentIssues } from "@miragon/value-chain-schema-model";
 //#region ../notations/refs.ts
 const REF_EMITTERS = { bpmn: (graph) => {
 	const refs = [];
@@ -476,11 +479,23 @@ const MERMAID_DIAGRAM_TYPES = [
 	"railroad-beta",
 	"railroad-ebnf-beta",
 	"railroad-abnf-beta",
-	"railroad-peg-beta"
+	"railroad-peg-beta",
+	"usecase-beta",
+	"agentflow-beta"
 ];
 const FRONT_MATTER = /^([^\S\n\r]*)-{3}\s*[\n\r](.*?)[\n\r]\1-{3}\s*[\n\r]+/s;
 const DIRECTIVE = /%{2}{\s*(?:(\w+)\s*:|(\w+))\s*(?:(\w+)|((?:(?!}%{2}).|\r?\n)*))?\s*(?:}%{2})?/gi;
 const COMMENT_LINE = /^\s*%%(?!{)[^\n]+\n?/gm;
+/**
+* The diagram types whose parser reads the comment lines too: their db sets
+* preserveCommentsWhenParsing (src/Diagram.ts), so their errors count those
+* lines. mermaid's detectors for them (src/diagrams/eventmodeling/detector.ts,
+* src/diagrams/agentflow/afDetector.ts), against the header line.
+*/
+const KEEPS_COMMENTS = /^(?:eventmodeling|agentflow-beta\b)/;
+/** mermaid's default maxTextSize, which apps/web keeps (a secure key): past
+*  it, mermaid parses even those types without their comment lines */
+const MAX_TEXT_SIZE = 5e4;
 /** a header keyword, followed by the end of the line, a space, ":" or ";" */
 const HEADER = new RegExp(`^(?:${MERMAID_DIAGRAM_TYPES.map((t) => t.replace(/[.*+?^${}()|[\]\\-]/g, "\\$&")).join("|")})(?=$|[\\s:;])`);
 /** mermaid's cleanupText: line breaks to \n, tag attributes single-quoted;
@@ -488,11 +503,34 @@ const HEADER = new RegExp(`^(?:${MERMAID_DIAGRAM_TYPES.map((t) => t.replace(/[.*
 function cleanup(source) {
 	return source.replace(/\r\n?/g, "\n").replace(/<(\w+)([^>]*)>/g, (_tag, name, attrs) => `<${name}${attrs.replace(/="([^"]*)"/g, "='$1'")}>`);
 }
+/** the first line that is neither blank nor a bare `%%` comment (mermaid's
+*  type detection skips those too), -1 when there is none */
+function headerIndex(lines) {
+	return lines.findIndex((l) => l.trim() !== "" && !l.trim().startsWith("%%"));
+}
+/** mermaid's preprocess (src/preprocess.ts), step by step */
+function preprocess(source) {
+	const text = cleanup(source);
+	const frontMatter = FRONT_MATTER.exec(text)?.[0] ?? "";
+	const body = text.slice(frontMatter.length);
+	const withComments = body.replace(DIRECTIVE, "");
+	const cleaned = withComments.replace(COMMENT_LINE, "").trimStart();
+	const cleanedLines = cleaned.split("\n");
+	const header = cleanedLines[headerIndex(cleanedLines)]?.trim() ?? "";
+	const keepsComments = KEEPS_COMMENTS.test(header) && withComments.length <= MAX_TEXT_SIZE;
+	return {
+		text,
+		frontMatterLines: frontMatter.split("\n").length - 1,
+		body,
+		keepsComments,
+		code: keepsComments ? withComments : cleaned
+	};
+}
 /** The text mermaid's diagram parser reads: the source after mermaid's
-*  preprocess (front matter, directives and comment lines removed, leading
-*  whitespace trimmed). */
+*  preprocess, its front matter and directives removed and, for all but the
+*  KEEPS_COMMENTS types, its comment lines and leading whitespace too. */
 function mermaidCode(source) {
-	return cleanup(source).replace(FRONT_MATTER, "").replace(DIRECTIVE, "").replace(COMMENT_LINE, "").trimStart();
+	return preprocess(source).code;
 }
 /**
 * The 1-based source line of the 1-based line `codeLine` of mermaidCode(source).
@@ -500,18 +538,32 @@ function mermaidCode(source) {
 * that spans lines), so the code is the source's lines in order: each code
 * line is matched to the next source line with the same text. A line the
 * preprocess rewrote matches nothing and takes the next line; a line past the
-* end clamps to the last one.
+* end clamps to the last one. Code that kept its comment lines lost no line
+* but the front matter's and a directive's inner line breaks, so its lines
+* are counted instead: matching by text would take a line a directive
+* emptied for a later blank line.
 */
 function mermaidSourceLine(source, codeLine) {
-	const cleaned = cleanup(source);
-	const sourceLines = cleaned.split("\n").map((l) => l.trim());
-	const codeLines = mermaidCode(source).split("\n");
-	let next = (cleaned.match(FRONT_MATTER)?.[0] ?? "").split("\n").length - 1;
+	const { text, frontMatterLines, body, keepsComments, code } = preprocess(source);
+	const sourceLines = text.split("\n").map((l) => l.trim());
+	if (keepsComments) {
+		const joined = /* @__PURE__ */ new Set();
+		for (const directive of body.matchAll(DIRECTIVE)) for (let i = directive.index; i < directive.index + directive[0].length; i++) if (body[i] === "\n") joined.add(i);
+		let line = frontMatterLines;
+		for (let i = 0, breaks = 0; i < body.length && breaks < codeLine - 1; i++) {
+			if (body[i] !== "\n") continue;
+			line++;
+			if (!joined.has(i)) breaks++;
+		}
+		return Math.min(line, sourceLines.length - 1) + 1;
+	}
+	const codeLines = code.split("\n");
+	let next = frontMatterLines;
 	let at = next;
 	for (let i = 0; i < Math.min(codeLine, codeLines.length); i++) {
-		const text = codeLines[i].trim();
+		const lineText = codeLines[i].trim();
 		let k = next;
-		while (k < sourceLines.length && sourceLines[k] !== text) k++;
+		while (k < sourceLines.length && sourceLines[k] !== lineText) k++;
 		at = k < sourceLines.length ? k : next;
 		next = at + 1;
 	}
@@ -525,7 +577,7 @@ function mermaidSourceLine(source, codeLine) {
 */
 function mermaidHeader(source) {
 	const lines = mermaidCode(source).split("\n");
-	const index = lines.findIndex((l) => l.trim() !== "" && !l.trim().startsWith("%%"));
+	const index = headerIndex(lines);
 	if (index < 0) return void 0;
 	const text = lines[index].trim();
 	return {
@@ -718,7 +770,7 @@ function checkBpmnXml(raw, opts = {}) {
 *
 * Deliberately NOT here: FEEL semantics, hit-policy reachability, dead wiring.
 * Those need the FEEL engine and live in @designiq/decisions (`analyze_decision`),
-* which would drag a browser-side dependency into this zero-dep CLI.
+* which would drag a browser-side dependency into this CLI.
 */
 function checkDmnXml(raw, opts = {}) {
 	const file = opts.file ?? "<dmn>";
@@ -809,8 +861,8 @@ function mermaidFenceProblem(content, line) {
 * notation that is not .bpmn/.dmn): a discovered model must at minimum parse
 * per its notation's mediaKind — a broken .tt/.vc.json used to pass
 * validation untouched. Pure: no filesystem, no process.exit. Deliberately
-* mechanical: notation-specific structure checks arrive with the per-notation
-* checkers (epic #118, step 3).
+* mechanical: notation-specific structure checks are the per-notation
+* checkers' (epic #118, step 3; checkSchemaModel runs this gate first).
 */
 function checkModelBaseline(raw, opts) {
 	const file = opts.file ?? `<${opts.notation}>`;
@@ -856,18 +908,103 @@ function checkModelBaseline(raw, opts) {
 	}
 	return findings;
 }
+/** a schema model's issue location as the canvases print it ("nodes.1.id"),
+*  "(root)" for the document itself */
+const issuePath = (path) => path.join(".") || "(root)";
+const schemaError = (ruleId, file) => (issue) => ({
+	severity: "ERROR",
+	ruleId,
+	file,
+	message: `${issuePath(issue.path)}: ${issue.message}`
+});
+function checkTeamTopology(raw, file) {
+	const parsed = parseDocument(JSON.parse(raw));
+	if (!parsed.ok) return parsed.issues.map(schemaError("team-topology/schema", file));
+	serializeDocument(parsed.document);
+	return [];
+}
+/**
+* The schema model refuses what the canvas cannot draw (a repeated or
+* reserved id among them), the rest of its strategic-DDD rules are
+* advisory: the canvas opens the map and marks the finding, so a save must
+* not refuse it either.
+*/
+function checkContextMap(raw, file) {
+	const parsed = parseDocumentText(raw);
+	if (!parsed.ok) return (parsed.issues ?? [{
+		path: [],
+		message: parsed.error
+	}]).map(schemaError("context-map/schema", file));
+	serializeDocumentText(parsed.document);
+	const { errors, warnings } = validateDocument(parsed.document);
+	return [...errors, ...warnings].map((finding) => ({
+		severity: "WARN",
+		ruleId: "context-map/semantics",
+		file,
+		message: `${finding.relationshipId === void 0 ? "" : `relationship "${finding.relationshipId}": `}${finding.message} (${finding.rule})`
+	}));
+}
+function checkValueChain(raw, file) {
+	return documentIssues(JSON.parse(raw)).map(schemaError("value-chain/schema", file));
+}
+/** each JSON notation's schema model, read the way its canvas reads the file
+*  (a Map, not an object: the notation id may be a caller's free text such
+*  as "constructor") */
+const SCHEMA_CHECKS = /* @__PURE__ */ new Map([
+	["team-topology", {
+		ruleId: "team-topology/schema",
+		check: checkTeamTopology
+	}],
+	["context-map", {
+		ruleId: "context-map/schema",
+		check: checkContextMap
+	}],
+	["value-chain", {
+		ruleId: "value-chain/schema",
+		check: checkValueChain
+	}]
+]);
+/**
+* The schema check of a Miragon JSON notation (Team Topology, Context Map,
+* Value Chain): the file is parsed with the notation's schema model, the
+* same parse its canvas opens it with, so everything the model refuses (a
+* duplicate or reserved id, a coordinate out of range, a newer version) is
+* an ERROR — a save would otherwise land a file the canvas cannot open.
+* Text that is no JSON keeps the baseline's finding, and a notation without
+* a schema model gets the baseline alone. Pure: no filesystem, no
+* process.exit.
+*/
+function checkSchemaModel(raw, opts) {
+	const baseline = checkModelBaseline(raw, opts);
+	const schema = SCHEMA_CHECKS.get(opts.notation);
+	if (!schema || baseline.length > 0 || byId(opts.notation)?.docShape === "structured") return baseline;
+	const file = opts.file ?? `<${opts.notation}>`;
+	try {
+		return schema.check(raw, file);
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		return [{
+			severity: "ERROR",
+			ruleId: schema.ruleId,
+			file,
+			message: `(root): could not be checked: ${reason}`
+		}];
+	}
+}
 /**
 * THE one check dispatch: the platform check for whatever notation `ctx.path`
-* is — full checkers for BPMN/DMN, the mediaKind baseline for everything
-* else, plus the generic dangling-reference rule for ANY notation with a
-* refs emitter; `undefined` when the path matches no registered notation
-* (the file is not a model; nothing to check). Consumed by the CLI (runCli)
-* AND the Live Host's save gate (application/content.ts) so both always agree.
+* is — full checkers for BPMN/DMN, the schema model for the Miragon JSON
+* notations, the mediaKind baseline for everything else, plus the generic
+* dangling-reference rule for ANY notation with a refs emitter; `undefined`
+* when the path matches no registered notation (the file is not a model;
+* nothing to check) or `ctx.notation` names none (a mistyped id must not
+* pass a file unchecked). Consumed by the CLI (runCli) AND the Live Host's
+* save gate (application/content.ts) so both always agree.
 */
 function checkModel(raw, ctx) {
 	const notation = ctx.notation ?? byExtension(ctx.path)?.id;
-	if (!notation) return void 0;
-	return [...notation === "bpmn" ? checkBpmnXml(raw, { file: ctx.path }).findings : notation === "dmn" ? checkDmnXml(raw, { file: ctx.path }).findings : checkModelBaseline(raw, {
+	if (!notation || !byId(notation)) return void 0;
+	return [...notation === "bpmn" ? checkBpmnXml(raw, { file: ctx.path }).findings : notation === "dmn" ? checkDmnXml(raw, { file: ctx.path }).findings : checkSchemaModel(raw, {
 		file: ctx.path,
 		notation
 	}), ...checkRefs(notation, raw, ctx)];
@@ -916,7 +1053,7 @@ async function runCli() {
 	/** optional single-model filter (a model file stem) */
 	const only = argv[0];
 	const rel = (p) => p.startsWith("/") ? relative(ROOT, p) : p;
-	const { CONTENT_CONFIG_FILE, contentConfigConflict, discoverModels, legacyContentConfigFile, loadContentConfig } = await import("./content-wjC_epKd.js");
+	const { CONTENT_CONFIG_FILE, contentConfigConflict, discoverModels, legacyContentConfigFile, loadContentConfig } = await import("./content-B0u0kwZN.js");
 	const cfg = loadContentConfig(ROOT);
 	if (!cfg) {
 		console.error(notContentRepoError(ROOT));
@@ -979,4 +1116,4 @@ async function runCli() {
 	process.exit(errorCount === 0 ? 0 : 1);
 }
 //#endregion
-export { runCli as a, checkModelBaseline as i, checkDmnXml as n, checkModel as r, checkBpmnXml as t };
+export { checkSchemaModel as a, checkModelBaseline as i, checkDmnXml as n, runCli as o, checkModel as r, checkBpmnXml as t };

package/dist/validate.js

@@ -1 +1 @@
-export { t as checkBpmnXml, n as checkDmnXml, r as checkModel, i as checkModelBaseline, a as runCli } from "./validate-DjtZJTGk.js";
+export { t as checkBpmnXml, n as checkDmnXml, r as checkModel, i as checkModelBaseline, a as checkSchemaModel, o as runCli } from "./validate-CUTctX4d.js";

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@miragon/design-iq-validator",
-  "version": "5.5.0",
+  "version": "5.7.0",
   "type": "module",
-  "description": "Platform-owned validator for designIQ content repos — designiq.yml discovery, BPMN/DMN structure and diagram coverage, cross-model references, and a parse check for every other notation. Runs against any checkout via --root; never executes content-repo code.",
+  "description": "Platform-owned validator for designIQ content repos — designiq.yml discovery, BPMN/DMN structure and diagram coverage, cross-model references, the schema check of Team Topologies, Context Maps and Value Chains, and a parse check for every other notation. Runs against any checkout via --root; never executes content-repo code.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -32,10 +32,14 @@
   "publishConfig": {
     "access": "public"
   },
-  "//": "fast-xml-parser stays a RUNTIME dependency although src/ no longer imports it directly: tsdown inlines @designiq/notations (whose extract.ts imports it) but keeps npm deps external, so the published dist/ resolves it from here. Removing it breaks the npm artifact at import time while the workspace keeps working.",
+  "//": "fast-xml-parser stays a RUNTIME dependency although src/ no longer imports it directly: tsdown inlines @designiq/notations (whose extract.ts imports it) but keeps npm deps external, so the published dist/ resolves it from here. Removing it breaks the npm artifact at import time while the workspace keeps working. zod is a RUNTIME dependency for the same reason: src/ never imports it, but the team-topologies, context-maps and value-chain schema models take it as a peer, and the published package is what provides it.",
   "dependencies": {
+    "@miragon/context-maps-schema-model": "0.4.0",
+    "@miragon/team-topologies-schema-model": "0.12.0",
+    "@miragon/value-chain-schema-model": "0.6.0",
     "fast-xml-parser": "5.11.2",
-    "yaml": "2.9.1"
+    "yaml": "2.9.1",
+    "zod": "4.6.7"
   },
   "devDependencies": {
     "tsdown": "0.23.1",