sad-mcp 2.2.0 → 2.2.1

package/dist/usecase/index (DESKTOP-GQHOSST's conflicted copy 2026-04-19).d.ts

@@ -0,0 +1,15 @@
+export interface ValidationIssue {
+    path: string;
+    code: string;
+    message: string;
+}
+export type ValidateResult = {
+    ok: true;
+    warnings: ValidationIssue[];
+} | {
+    ok: false;
+    issues: ValidationIssue[];
+    warnings: ValidationIssue[];
+};
+export declare function formatIssues(issues: ValidationIssue[]): string;
+export declare function parseAndValidate(jsonText: string): ValidateResult;

package/dist/usecase/index (DESKTOP-GQHOSST's conflicted copy 2026-04-19).js

@@ -0,0 +1,218 @@
+// Validator for use-case diagramModel JSON (kind: 'use-case').
+// Called by uml_usecase_validate_model MCP tool in tools.ts.
+// Returns all errors and warnings at once so an LLM can self-correct in one pass.
+export function formatIssues(issues) {
+    if (issues.length === 0)
+        return "(none)";
+    return issues.map(i => `- [${i.code}] ${i.path}: ${i.message}`).join("\n");
+}
+// ── Helpers ───────────────────────────────────────────────────────────────
+function hasHebrew(s) {
+    return /[\u0590-\u05FF\uFB1D-\uFB4F]/.test(s);
+}
+const SEND_ONLY_PREFIXES = [
+    /^שליחת /i, /^הודעה ל/i, /^הודעת /i, /^משלוח /i,
+    /^Send /i, /^Print /i, /^Notify /i,
+];
+const PHYSICAL_VERB_PREFIXES = [
+    /^ביצוע /i, /^הכנת /i, /^ספירת /i, /^מסירת /i,
+    /^תשלום ב/i, /^Perform /i, /^Execute /i,
+];
+const UNSAFE_WF = [
+    /<script\b/i, /\son\w+\s*=/i, /<iframe\b/i,
+    /src\s*=\s*["']https?:/i, /href\s*=\s*["']https?:/i,
+    /@import\b/i, /<style\b/i,
+];
+function wireframeSafe(html) {
+    return !UNSAFE_WF.some(rx => rx.test(html));
+}
+// ── Main validator ────────────────────────────────────────────────────────
+export function parseAndValidate(jsonText) {
+    let raw;
+    try {
+        raw = JSON.parse(jsonText);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, warnings: [], issues: [{ path: "(root)", code: "invalid-json", message: `JSON parse failed: ${msg}` }] };
+    }
+    const errors = [];
+    const warnings = [];
+    const err = (path, code, message) => errors.push({ path, code, message });
+    const warn = (path, code, message) => warnings.push({ path, code, message });
+    const m = raw;
+    if (!m || typeof m !== "object") {
+        err("(root)", "not-object", "model must be an object");
+        return { ok: false, issues: errors, warnings };
+    }
+    if (m["kind"] !== "use-case")
+        err("kind", "wrong-kind", `expected "use-case", got "${m["kind"]}"`);
+    const parts = Array.isArray(m["parts"]) ? m["parts"] : [];
+    if (!Array.isArray(m["parts"]) || parts.length === 0)
+        err("parts", "missing-parts", "parts array is required and must be non-empty");
+    // Narrative field checks at model level
+    for (const [key, val] of [["assumptions", m["assumptions"]], ["openQuestions", m["openQuestions"]]]) {
+        if (Array.isArray(val)) {
+            val.forEach((item, i) => {
+                if (typeof item === "string" && item.length > 0 && !hasHebrew(item)) {
+                    err(`${key}[${i}]`, "narrative-non-hebrew", `${key}[${i}] contains no Hebrew characters`);
+                }
+            });
+        }
+    }
+    for (const [pi, part] of parts.entries()) {
+        const pp = `parts[${pi}]`;
+        const elements = Array.isArray(part["elements"]) ? part["elements"] : [];
+        const relationships = Array.isArray(part["relationships"]) ? part["relationships"] : [];
+        const actorIds = new Set();
+        const ucIds = new Set();
+        // Index actors and UCs
+        for (const el of elements) {
+            if (el["kind"] === "actor" && typeof el["id"] === "string")
+                actorIds.add(el["id"]);
+            if (el["kind"] === "useCase" && typeof el["id"] === "string")
+                ucIds.add(el["id"]);
+        }
+        // Build relationship indexes
+        const includesByTarget = new Map(); // targetUcId → [baseUcId...]
+        const assocsByUc = new Map(); // ucId → [actorId...]
+        const includeSet = new Set(); // "from:to"
+        let totalIncludeExtend = 0;
+        for (const rel of relationships) {
+            if (rel["kind"] === "include") {
+                const from = String(rel["from"] ?? ""), to = String(rel["to"] ?? "");
+                const list = includesByTarget.get(to) ?? [];
+                list.push(from);
+                includesByTarget.set(to, list);
+                includeSet.add(`${from}:${to}`);
+                totalIncludeExtend++;
+            }
+            if (rel["kind"] === "extend")
+                totalIncludeExtend++;
+            if (rel["kind"] === "actorAssoc") {
+                const ucId = String(rel["ucId"] ?? ""), actorId = String(rel["actorId"] ?? "");
+                const list = assocsByUc.get(ucId) ?? [];
+                list.push(actorId);
+                assocsByUc.set(ucId, list);
+            }
+        }
+        if (totalIncludeExtend > 2)
+            warn(`${pp}.relationships`, "too-many-include-extend", `${totalIncludeExtend} include+extend relationships found — more than 2 is almost always wrong`);
+        // Check «include» targets
+        for (const [targetId, bases] of includesByTarget) {
+            if (bases.length < 2) {
+                err(`${pp}.relationships[include→${targetId}]`, "single-incoming-include", `UC "${targetId}" has exactly one incoming «include» (from "${bases[0]}") — fold it into the parent instead`);
+            }
+            if (assocsByUc.has(targetId)) {
+                err(`${pp}.relationships[include→${targetId}]`, "include-target-has-assoc", `UC "${targetId}" is an «include» target but also has direct actor associations — it cannot be both`);
+            }
+        }
+        // Check UC elements
+        for (const el of elements) {
+            if (el["kind"] !== "useCase")
+                continue;
+            const id = String(el["id"] ?? "");
+            const name = String(el["name"] ?? "");
+            const ePath = `${pp}.elements[id=${id}]`;
+            // Send-only check
+            if (SEND_ONLY_PREFIXES.some(rx => rx.test(name))) {
+                err(ePath, "send-only-uc", `UC "${id}" name "${name}" appears to be send-only — fold the send step into the UC that decided to send`);
+            }
+            // Physical verb check
+            if (PHYSICAL_VERB_PREFIXES.some(rx => rx.test(name))) {
+                warn(ePath, "physical-verb", `UC "${id}" name "${name}" uses a physical verb — wrap with a system verb (רישום, הזנה, עדכון, סימון…)`);
+            }
+            // Primary actor
+            const primaryActor = el["primaryActor"];
+            if (!primaryActor) {
+                err(ePath, "missing-primary-actor", `UC "${id}" has no primaryActor`);
+            }
+            else {
+                if (!actorIds.has(primaryActor)) {
+                    err(ePath, "unknown-primary-actor", `UC "${id}" primaryActor "${primaryActor}" is not in actors list`);
+                }
+                // Check that an actorAssoc with role=initiator exists for this actor↔UC pair
+                const initiatorAssoc = relationships.find(r => r["kind"] === "actorAssoc" && r["ucId"] === id && r["actorId"] === primaryActor && r["role"] === "initiator");
+                if (!initiatorAssoc) {
+                    err(ePath, "primary-not-initiator", `UC "${id}" primaryActor "${primaryActor}" has no actorAssoc with role="initiator"`);
+                }
+            }
+            // Narrative fields — must contain Hebrew
+            for (const [key, val] of [["description", el["description"]]]) {
+                if (typeof val === "string" && val.length > 0 && !hasHebrew(val)) {
+                    err(`${ePath}.${key}`, "narrative-non-hebrew", `${key} contains no Hebrew characters`);
+                }
+            }
+            for (const [key, arr] of [["preconditions", el["preconditions"]], ["postconditions", el["postconditions"]]]) {
+                if (!Array.isArray(arr) || arr.length === 0) {
+                    warn(`${ePath}.${key}`, `missing-${key}`, `UC "${id}" has no ${key}`);
+                }
+                else {
+                    arr.forEach((item, i) => {
+                        if (typeof item === "string" && item.length > 0 && !hasHebrew(item)) {
+                            err(`${ePath}.${key}[${i}]`, "narrative-non-hebrew", `${key}[${i}] contains no Hebrew characters`);
+                        }
+                    });
+                }
+            }
+            // User stories
+            const userStories = Array.isArray(el["userStories"]) ? el["userStories"] : [];
+            if (userStories.length < 2) {
+                warn(`${ePath}.userStories`, "few-user-stories", `UC "${id}" has ${userStories.length} user stor${userStories.length === 1 ? "y" : "ies"} — cover every distinct stakeholder goal`);
+            }
+            // Scenarios / flow steps
+            const scenarios = Array.isArray(el["scenarios"]) ? el["scenarios"] : [];
+            if (scenarios.length === 0) {
+                err(`${ePath}.scenarios`, "missing-scenarios", `UC "${id}" has no scenarios`);
+            }
+            for (const [si, sce] of scenarios.entries()) {
+                const sPath = `${ePath}.scenarios[${si}]`;
+                const flow = Array.isArray(sce["flow"]) ? sce["flow"] : [];
+                if (flow.length === 0) {
+                    err(`${sPath}.flow`, "empty-flow", `scenario "${sce["id"]}" in UC "${id}" has no flow steps`);
+                }
+                const flowLen = flow.length;
+                for (const [fi, step] of flow.entries()) {
+                    const stepPath = `${sPath}.flow[${fi}]`;
+                    if (step["kind"] === "actor" && typeof step["actor"] === "string" && !actorIds.has(step["actor"])) {
+                        err(stepPath, "unknown-actor-ref", `flow step references unknown actor id "${step["actor"]}"`);
+                    }
+                    if (step["kind"] === "include") {
+                        const targetUc = String(step["uc"] ?? "");
+                        if (!ucIds.has(targetUc)) {
+                            err(stepPath, "unknown-uc-ref", `«include» step references unknown UC id "${targetUc}"`);
+                        }
+                        else if (!includeSet.has(`${id}:${targetUc}`)) {
+                            err(stepPath, "include-step-no-relationship", `«include» step references "${targetUc}" but no include relationship exists from "${id}" to "${targetUc}"`);
+                        }
+                    }
+                    if (typeof step["text"] === "string" && step["text"].length > 0 && !hasHebrew(step["text"])) {
+                        err(stepPath, "narrative-non-hebrew", "flow step text contains no Hebrew characters");
+                    }
+                }
+                const extensions = Array.isArray(sce["extensions"]) ? sce["extensions"] : [];
+                for (const [ei, ext] of extensions.entries()) {
+                    const extPath = `${sPath}.extensions[${ei}]`;
+                    if (typeof ext["at"] === "number" && (ext["at"] < 1 || ext["at"] > flowLen)) {
+                        err(extPath, "invalid-extension-at", `extension "at" value ${ext["at"]} is out of range (flow has ${flowLen} steps)`);
+                    }
+                    if (typeof ext["text"] === "string" && ext["text"].length > 0 && !hasHebrew(ext["text"])) {
+                        err(extPath, "narrative-non-hebrew", "extension text contains no Hebrew characters");
+                    }
+                }
+            }
+            // Wireframe safety (only when present and non-empty)
+            if (typeof el["wireframe"] === "string" && el["wireframe"].length > 0) {
+                if (!wireframeSafe(el["wireframe"])) {
+                    err(`${ePath}.wireframe`, "unsafe-wireframe", `wireframe for UC "${id}" contains forbidden patterns (script/on*/iframe/external URL/@import/style)`);
+                }
+                if (!hasHebrew(el["wireframe"])) {
+                    err(`${ePath}.wireframe`, "wireframe-non-hebrew", `wireframe for UC "${id}" contains no Hebrew characters`);
+                }
+            }
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, issues: errors, warnings };
+    return { ok: true, warnings };
+}

package/dist/usecase/index.d (DESKTOP-GQHOSST's conflicted copy 2026-04-19).ts

@@ -0,0 +1,15 @@
+export interface ValidationIssue {
+    path: string;
+    code: string;
+    message: string;
+}
+export type ValidateResult = {
+    ok: true;
+    warnings: ValidationIssue[];
+} | {
+    ok: false;
+    issues: ValidationIssue[];
+    warnings: ValidationIssue[];
+};
+export declare function formatIssues(issues: ValidationIssue[]): string;
+export declare function parseAndValidate(jsonText: string): ValidateResult;

package/dist/usecase/index.d.ts

@@ -1,15 +1,2 @@
-export interface ValidationIssue {
-    path: string;
-    code: string;
-    message: string;
-}
-export type ValidateResult = {
-    ok: true;
-    warnings: ValidationIssue[];
-} | {
-    ok: false;
-    issues: ValidationIssue[];
-    warnings: ValidationIssue[];
-};
-export declare function formatIssues(issues: ValidationIssue[]): string;
-export declare function parseAndValidate(jsonText: string): ValidateResult;
+export { validateModel, parseAndValidate, formatIssues } from "./validate.js";
+export type { ValidateResult, ValidationIssue } from "./validate.js";

package/dist/usecase/index.js

@@ -1,218 +1 @@
-// Validator for use-case diagramModel JSON (kind: 'use-case').
-// Called by uml_usecase_validate_model MCP tool in tools.ts.
-// Returns all errors and warnings at once so an LLM can self-correct in one pass.
-export function formatIssues(issues) {
-    if (issues.length === 0)
-        return "(none)";
-    return issues.map(i => `- [${i.code}] ${i.path}: ${i.message}`).join("\n");
-}
-// ── Helpers ───────────────────────────────────────────────────────────────
-function hasHebrew(s) {
-    return /[\u0590-\u05FF\uFB1D-\uFB4F]/.test(s);
-}
-const SEND_ONLY_PREFIXES = [
-    /^שליחת /i, /^הודעה ל/i, /^הודעת /i, /^משלוח /i,
-    /^Send /i, /^Print /i, /^Notify /i,
-];
-const PHYSICAL_VERB_PREFIXES = [
-    /^ביצוע /i, /^הכנת /i, /^ספירת /i, /^מסירת /i,
-    /^תשלום ב/i, /^Perform /i, /^Execute /i,
-];
-const UNSAFE_WF = [
-    /<script\b/i, /\son\w+\s*=/i, /<iframe\b/i,
-    /src\s*=\s*["']https?:/i, /href\s*=\s*["']https?:/i,
-    /@import\b/i, /<style\b/i,
-];
-function wireframeSafe(html) {
-    return !UNSAFE_WF.some(rx => rx.test(html));
-}
-// ── Main validator ────────────────────────────────────────────────────────
-export function parseAndValidate(jsonText) {
-    let raw;
-    try {
-        raw = JSON.parse(jsonText);
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return { ok: false, warnings: [], issues: [{ path: "(root)", code: "invalid-json", message: `JSON parse failed: ${msg}` }] };
-    }
-    const errors = [];
-    const warnings = [];
-    const err = (path, code, message) => errors.push({ path, code, message });
-    const warn = (path, code, message) => warnings.push({ path, code, message });
-    const m = raw;
-    if (!m || typeof m !== "object") {
-        err("(root)", "not-object", "model must be an object");
-        return { ok: false, issues: errors, warnings };
-    }
-    if (m["kind"] !== "use-case")
-        err("kind", "wrong-kind", `expected "use-case", got "${m["kind"]}"`);
-    const parts = Array.isArray(m["parts"]) ? m["parts"] : [];
-    if (!Array.isArray(m["parts"]) || parts.length === 0)
-        err("parts", "missing-parts", "parts array is required and must be non-empty");
-    // Narrative field checks at model level
-    for (const [key, val] of [["assumptions", m["assumptions"]], ["openQuestions", m["openQuestions"]]]) {
-        if (Array.isArray(val)) {
-            val.forEach((item, i) => {
-                if (typeof item === "string" && item.length > 0 && !hasHebrew(item)) {
-                    err(`${key}[${i}]`, "narrative-non-hebrew", `${key}[${i}] contains no Hebrew characters`);
-                }
-            });
-        }
-    }
-    for (const [pi, part] of parts.entries()) {
-        const pp = `parts[${pi}]`;
-        const elements = Array.isArray(part["elements"]) ? part["elements"] : [];
-        const relationships = Array.isArray(part["relationships"]) ? part["relationships"] : [];
-        const actorIds = new Set();
-        const ucIds = new Set();
-        // Index actors and UCs
-        for (const el of elements) {
-            if (el["kind"] === "actor" && typeof el["id"] === "string")
-                actorIds.add(el["id"]);
-            if (el["kind"] === "useCase" && typeof el["id"] === "string")
-                ucIds.add(el["id"]);
-        }
-        // Build relationship indexes
-        const includesByTarget = new Map(); // targetUcId → [baseUcId...]
-        const assocsByUc = new Map(); // ucId → [actorId...]
-        const includeSet = new Set(); // "from:to"
-        let totalIncludeExtend = 0;
-        for (const rel of relationships) {
-            if (rel["kind"] === "include") {
-                const from = String(rel["from"] ?? ""), to = String(rel["to"] ?? "");
-                const list = includesByTarget.get(to) ?? [];
-                list.push(from);
-                includesByTarget.set(to, list);
-                includeSet.add(`${from}:${to}`);
-                totalIncludeExtend++;
-            }
-            if (rel["kind"] === "extend")
-                totalIncludeExtend++;
-            if (rel["kind"] === "actorAssoc") {
-                const ucId = String(rel["ucId"] ?? ""), actorId = String(rel["actorId"] ?? "");
-                const list = assocsByUc.get(ucId) ?? [];
-                list.push(actorId);
-                assocsByUc.set(ucId, list);
-            }
-        }
-        if (totalIncludeExtend > 2)
-            warn(`${pp}.relationships`, "too-many-include-extend", `${totalIncludeExtend} include+extend relationships found — more than 2 is almost always wrong`);
-        // Check «include» targets
-        for (const [targetId, bases] of includesByTarget) {
-            if (bases.length < 2) {
-                err(`${pp}.relationships[include→${targetId}]`, "single-incoming-include", `UC "${targetId}" has exactly one incoming «include» (from "${bases[0]}") — fold it into the parent instead`);
-            }
-            if (assocsByUc.has(targetId)) {
-                err(`${pp}.relationships[include→${targetId}]`, "include-target-has-assoc", `UC "${targetId}" is an «include» target but also has direct actor associations — it cannot be both`);
-            }
-        }
-        // Check UC elements
-        for (const el of elements) {
-            if (el["kind"] !== "useCase")
-                continue;
-            const id = String(el["id"] ?? "");
-            const name = String(el["name"] ?? "");
-            const ePath = `${pp}.elements[id=${id}]`;
-            // Send-only check
-            if (SEND_ONLY_PREFIXES.some(rx => rx.test(name))) {
-                err(ePath, "send-only-uc", `UC "${id}" name "${name}" appears to be send-only — fold the send step into the UC that decided to send`);
-            }
-            // Physical verb check
-            if (PHYSICAL_VERB_PREFIXES.some(rx => rx.test(name))) {
-                warn(ePath, "physical-verb", `UC "${id}" name "${name}" uses a physical verb — wrap with a system verb (רישום, הזנה, עדכון, סימון…)`);
-            }
-            // Primary actor
-            const primaryActor = el["primaryActor"];
-            if (!primaryActor) {
-                err(ePath, "missing-primary-actor", `UC "${id}" has no primaryActor`);
-            }
-            else {
-                if (!actorIds.has(primaryActor)) {
-                    err(ePath, "unknown-primary-actor", `UC "${id}" primaryActor "${primaryActor}" is not in actors list`);
-                }
-                // Check that an actorAssoc with role=initiator exists for this actor↔UC pair
-                const initiatorAssoc = relationships.find(r => r["kind"] === "actorAssoc" && r["ucId"] === id && r["actorId"] === primaryActor && r["role"] === "initiator");
-                if (!initiatorAssoc) {
-                    err(ePath, "primary-not-initiator", `UC "${id}" primaryActor "${primaryActor}" has no actorAssoc with role="initiator"`);
-                }
-            }
-            // Narrative fields — must contain Hebrew
-            for (const [key, val] of [["description", el["description"]]]) {
-                if (typeof val === "string" && val.length > 0 && !hasHebrew(val)) {
-                    err(`${ePath}.${key}`, "narrative-non-hebrew", `${key} contains no Hebrew characters`);
-                }
-            }
-            for (const [key, arr] of [["preconditions", el["preconditions"]], ["postconditions", el["postconditions"]]]) {
-                if (!Array.isArray(arr) || arr.length === 0) {
-                    warn(`${ePath}.${key}`, `missing-${key}`, `UC "${id}" has no ${key}`);
-                }
-                else {
-                    arr.forEach((item, i) => {
-                        if (typeof item === "string" && item.length > 0 && !hasHebrew(item)) {
-                            err(`${ePath}.${key}[${i}]`, "narrative-non-hebrew", `${key}[${i}] contains no Hebrew characters`);
-                        }
-                    });
-                }
-            }
-            // User stories
-            const userStories = Array.isArray(el["userStories"]) ? el["userStories"] : [];
-            if (userStories.length < 2) {
-                warn(`${ePath}.userStories`, "few-user-stories", `UC "${id}" has ${userStories.length} user stor${userStories.length === 1 ? "y" : "ies"} — cover every distinct stakeholder goal`);
-            }
-            // Scenarios / flow steps
-            const scenarios = Array.isArray(el["scenarios"]) ? el["scenarios"] : [];
-            if (scenarios.length === 0) {
-                err(`${ePath}.scenarios`, "missing-scenarios", `UC "${id}" has no scenarios`);
-            }
-            for (const [si, sce] of scenarios.entries()) {
-                const sPath = `${ePath}.scenarios[${si}]`;
-                const flow = Array.isArray(sce["flow"]) ? sce["flow"] : [];
-                if (flow.length === 0) {
-                    err(`${sPath}.flow`, "empty-flow", `scenario "${sce["id"]}" in UC "${id}" has no flow steps`);
-                }
-                const flowLen = flow.length;
-                for (const [fi, step] of flow.entries()) {
-                    const stepPath = `${sPath}.flow[${fi}]`;
-                    if (step["kind"] === "actor" && typeof step["actor"] === "string" && !actorIds.has(step["actor"])) {
-                        err(stepPath, "unknown-actor-ref", `flow step references unknown actor id "${step["actor"]}"`);
-                    }
-                    if (step["kind"] === "include") {
-                        const targetUc = String(step["uc"] ?? "");
-                        if (!ucIds.has(targetUc)) {
-                            err(stepPath, "unknown-uc-ref", `«include» step references unknown UC id "${targetUc}"`);
-                        }
-                        else if (!includeSet.has(`${id}:${targetUc}`)) {
-                            err(stepPath, "include-step-no-relationship", `«include» step references "${targetUc}" but no include relationship exists from "${id}" to "${targetUc}"`);
-                        }
-                    }
-                    if (typeof step["text"] === "string" && step["text"].length > 0 && !hasHebrew(step["text"])) {
-                        err(stepPath, "narrative-non-hebrew", "flow step text contains no Hebrew characters");
-                    }
-                }
-                const extensions = Array.isArray(sce["extensions"]) ? sce["extensions"] : [];
-                for (const [ei, ext] of extensions.entries()) {
-                    const extPath = `${sPath}.extensions[${ei}]`;
-                    if (typeof ext["at"] === "number" && (ext["at"] < 1 || ext["at"] > flowLen)) {
-                        err(extPath, "invalid-extension-at", `extension "at" value ${ext["at"]} is out of range (flow has ${flowLen} steps)`);
-                    }
-                    if (typeof ext["text"] === "string" && ext["text"].length > 0 && !hasHebrew(ext["text"])) {
-                        err(extPath, "narrative-non-hebrew", "extension text contains no Hebrew characters");
-                    }
-                }
-            }
-            // Wireframe safety (only when present and non-empty)
-            if (typeof el["wireframe"] === "string" && el["wireframe"].length > 0) {
-                if (!wireframeSafe(el["wireframe"])) {
-                    err(`${ePath}.wireframe`, "unsafe-wireframe", `wireframe for UC "${id}" contains forbidden patterns (script/on*/iframe/external URL/@import/style)`);
-                }
-                if (!hasHebrew(el["wireframe"])) {
-                    err(`${ePath}.wireframe`, "wireframe-non-hebrew", `wireframe for UC "${id}" contains no Hebrew characters`);
-                }
-            }
-        }
-    }
-    if (errors.length > 0)
-        return { ok: false, issues: errors, warnings };
-    return { ok: true, warnings };
-}
+export { validateModel, parseAndValidate, formatIssues } from "./validate.js";

package/dist/usecase/validate.d.ts

@@ -0,0 +1,17 @@
+export interface ValidationIssue {
+    severity: "error" | "warning";
+    code: string;
+    path: string;
+    message: string;
+}
+export type ValidateResult = {
+    ok: true;
+    warnings: ValidationIssue[];
+} | {
+    ok: false;
+    issues: ValidationIssue[];
+    warnings: ValidationIssue[];
+};
+export declare function validateModel(model: unknown): ValidateResult;
+export declare function parseAndValidate(jsonText: string): ValidateResult;
+export declare function formatIssues(issues: ValidationIssue[]): string;

package/dist/usecase/validate.js

@@ -0,0 +1,393 @@
+// Structural validator for UML use-case diagramModel JSON.
+//
+// Purpose: catch the business-rule violations the SKILL prompts for but cannot
+// enforce on its own — overeager «include», send-only UCs, physical-verb
+// labels, missing primary actor, broken references in scenario flows, etc.
+//
+// Returns ALL issues at once so the calling LLM can self-correct in a single
+// pass rather than iterating error-by-error.
+// ── Name heuristics (CR #8 and CR #10) ──────────────────────────────────
+// Send-only / output-only verbs that on their own do not constitute a UC.
+// Pattern allows "Record sending" etc. — only bare send-verbs flag.
+const SEND_ONLY_PATTERNS = [
+    /^(send|notify|email|sms|alert|push|broadcast)\b/i,
+    /^(print)\s+\w+\s+(label|receipt|ticket|slip)\b/i,
+    /^שליחת\s/,
+    /^הודעה\s/,
+    /^התראה\s/,
+    /^הפצת\s/,
+];
+// Physical verbs that describe actions outside the IS. Allowed only when
+// wrapped by a system verb (רישום / הזנה / עדכון / סימון / Record / Enter / ...).
+const PHYSICAL_VERBS = [
+    /^(perform|do|execute|conduct)\b/i,
+    /^(pick|pack|ship|deliver|receive|count|pay|collect)\b/i,
+    /^(ביצוע|הכנת|קבלת|מסירת|ספירת|תשלום|איסוף)\s/,
+];
+const SYSTEM_VERB_WRAPPERS = [
+    /^(record|register|enter|log|capture|mark|update|create|save)\b/i,
+    /^(רישום|הזנת|עדכון|סימון|יצירת|שמירת|קליטת|תיעוד)\s/,
+];
+function looksSendOnly(name) {
+    return SEND_ONLY_PATTERNS.some((rx) => rx.test(name.trim()));
+}
+function looksPhysical(name) {
+    const n = name.trim();
+    if (SYSTEM_VERB_WRAPPERS.some((rx) => rx.test(n)))
+        return false;
+    return PHYSICAL_VERBS.some((rx) => rx.test(n));
+}
+// CR #11 — narrative UC docs must be in Hebrew. We accept "contains at least
+// one Hebrew character" as a cheap heuristic; trivial strings (empty, whitespace,
+// pure punctuation) are treated as missing-content rather than English.
+const HEBREW_RANGE = /[\u0590-\u05FF]/;
+function hasHebrew(text) {
+    return typeof text === "string" && HEBREW_RANGE.test(text);
+}
+function isMeaningful(text) {
+    return typeof text === "string" && text.trim().length >= 2;
+}
+function asArray(v) {
+    return Array.isArray(v) ? v : [];
+}
+function getParts(model) {
+    if (!model || typeof model !== "object")
+        return [];
+    const parts = asArray(model.parts);
+    return parts.map((p) => {
+        const obj = (p && typeof p === "object") ? p : {};
+        return {
+            elements: asArray(obj.elements),
+            relationships: asArray(obj.relationships),
+        };
+    });
+}
+// ── Main validator ──────────────────────────────────────────────────────
+export function validateModel(model) {
+    const errors = [];
+    const warnings = [];
+    const err = (code, path, message) => {
+        errors.push({ severity: "error", code, path, message });
+    };
+    const warn = (code, path, message) => {
+        warnings.push({ severity: "warning", code, path, message });
+    };
+    // --- Root shape ---
+    if (!model || typeof model !== "object") {
+        err("not-object", "(root)", "diagramModel must be a JSON object.");
+        return { ok: false, issues: errors, warnings };
+    }
+    const root = model;
+    if (root.kind !== "use-case") {
+        err("wrong-kind", "kind", `Expected kind: "use-case", got ${JSON.stringify(root.kind)}.`);
+    }
+    const parts = getParts(root);
+    if (parts.length === 0) {
+        err("no-parts", "parts", "parts[] is empty — at least one part (tab) is required.");
+        return { ok: false, issues: errors, warnings };
+    }
+    // Collect everything across all parts for cross-part id lookup.
+    const allElements = [];
+    const allRelationships = [];
+    parts.forEach((p, i) => {
+        p.elements.forEach((el) => allElements.push({ part: i, el }));
+        p.relationships.forEach((rel) => allRelationships.push({ part: i, rel }));
+    });
+    const ucs = allElements.filter((x) => x.el.kind === "useCase").map((x) => x.el);
+    const actors = allElements.filter((x) => x.el.kind === "actor").map((x) => x.el);
+    const ucIds = new Set(ucs.map((u) => String(u.id)));
+    const actorIds = new Set(actors.map((a) => String(a.id)));
+    // --- Element shape checks ---
+    ucs.forEach((uc) => {
+        const id = String(uc.id ?? "");
+        const path = `useCase[${id || "?"}]`;
+        if (!id)
+            err("uc-missing-id", path, "useCase is missing an id.");
+        if (!uc.name)
+            err("uc-missing-name", path, "useCase is missing a name.");
+        if (uc.name && typeof uc.name === "string") {
+            if (looksSendOnly(uc.name)) {
+                err("send-only-uc", `${path}.name`, `UC name "${uc.name}" looks send-only (CR #10). Fold into the UC that decided to send.`);
+            }
+            if (looksPhysical(uc.name)) {
+                warn("physical-verb", `${path}.name`, `UC name "${uc.name}" starts with a physical verb (CR #8). Prefer "Record X" / "Enter X" / "Register X" to describe the IS action.`);
+            }
+        }
+    });
+    actors.forEach((a) => {
+        const id = String(a.id ?? "");
+        const path = `actor[${id || "?"}]`;
+        if (!id)
+            err("actor-missing-id", path, "actor is missing an id.");
+        if (!a.name)
+            err("actor-missing-name", path, "actor is missing a name.");
+    });
+    // --- Relationship cross-references + CR #4 + single-include + orphaned UC ---
+    const actorAssocsByUc = new Map();
+    const includeIntoByUc = new Map();
+    const initiatorByUc = new Map();
+    allRelationships.forEach(({ rel }, i) => {
+        const path = `relationships[${i}]`;
+        const kind = rel.kind;
+        if (kind === "actorAssoc") {
+            const actorId = String(rel.actorId ?? "");
+            const ucId = String(rel.ucId ?? "");
+            if (!actorIds.has(actorId))
+                err("unknown-actor", path, `actorAssoc.actorId "${actorId}" does not exist in actors[].`);
+            if (!ucIds.has(ucId))
+                err("unknown-uc", path, `actorAssoc.ucId "${ucId}" does not exist in use cases.`);
+            if (actorIds.has(actorId) && ucIds.has(ucId)) {
+                if (!actorAssocsByUc.has(ucId))
+                    actorAssocsByUc.set(ucId, []);
+                actorAssocsByUc.get(ucId).push(rel);
+                if (rel.role === "initiator") {
+                    if (!initiatorByUc.has(ucId))
+                        initiatorByUc.set(ucId, new Set());
+                    initiatorByUc.get(ucId).add(actorId);
+                }
+            }
+        }
+        else if (kind === "include") {
+            const from = String(rel.from ?? "");
+            const to = String(rel.to ?? "");
+            if (!ucIds.has(from))
+                err("unknown-uc", path, `include.from "${from}" does not exist.`);
+            if (!ucIds.has(to))
+                err("unknown-uc", path, `include.to "${to}" does not exist.`);
+            if (ucIds.has(to)) {
+                if (!includeIntoByUc.has(to))
+                    includeIntoByUc.set(to, []);
+                includeIntoByUc.get(to).push(rel);
+            }
+        }
+        else if (kind === "extend") {
+            const from = String(rel.from ?? "");
+            const to = String(rel.to ?? "");
+            if (!ucIds.has(from))
+                err("unknown-uc", path, `extend.from "${from}" does not exist.`);
+            if (!ucIds.has(to))
+                err("unknown-uc", path, `extend.to "${to}" does not exist.`);
+        }
+        else if (kind === "generalization") {
+            const from = String(rel.from ?? "");
+            const to = String(rel.to ?? "");
+            if (!ucIds.has(from) && !actorIds.has(from))
+                err("unknown-endpoint", path, `generalization.from "${from}" is neither a UC nor an actor.`);
+            if (!ucIds.has(to) && !actorIds.has(to))
+                err("unknown-endpoint", path, `generalization.to "${to}" is neither a UC nor an actor.`);
+        }
+    });
+    // CR #4 — include target checks
+    for (const [ucId, includes] of includeIntoByUc) {
+        const path = `useCase[${ucId}]`;
+        if (includes.length < 2) {
+            err("include-single-base", path, `UC "${ucId}" is the target of only ${includes.length} «include» arrow — an include target requires ≥2 bases (CR #4). Fold into the parent UC.`);
+        }
+        if ((actorAssocsByUc.get(ucId) || []).length > 0) {
+            err("include-target-has-actor", path, `UC "${ucId}" is an «include» target AND has a direct actor association — forbidden (CR #4). An include target must have ZERO actor associations.`);
+        }
+    }
+    // §4.1 — every UC must have ≥1 initiator (unless it's purely an include target)
+    ucs.forEach((uc) => {
+        const id = String(uc.id ?? "");
+        if (!id)
+            return;
+        const path = `useCase[${id}]`;
+        const isIncludeTarget = (includeIntoByUc.get(id) || []).length >= 2;
+        const hasInitiator = (initiatorByUc.get(id)?.size ?? 0) > 0;
+        const hasAnyActor = (actorAssocsByUc.get(id) || []).length > 0;
+        if (!isIncludeTarget && !hasAnyActor) {
+            err("uc-no-actor", path, `UC "${id}" has no actor association and is not an include target. Either connect an actor or remove the UC.`);
+        }
+        if (!isIncludeTarget && hasAnyActor && !hasInitiator) {
+            err("uc-no-initiator", path, `UC "${id}" has actor associations but none with role: "initiator" (§4.1). Every UC needs at least one initiator.`);
+        }
+    });
+    // §4.4 — per-UC documentation checks (only for non-include-target UCs; include
+    // targets are sub-behaviors and can use lighter docs in practice, but we still
+    // require description + at least one scenario if any doc is present).
+    ucs.forEach((uc) => {
+        const id = String(uc.id ?? "");
+        if (!id)
+            return;
+        const path = `useCase[${id}]`;
+        const isIncludeTarget = (includeIntoByUc.get(id) || []).length >= 2;
+        const primaryActor = uc.primaryActor;
+        if (!isIncludeTarget) {
+            if (!primaryActor) {
+                err("uc-missing-primary-actor", path, `UC "${id}" is missing primaryActor (§4.4).`);
+            }
+            else if (!actorIds.has(primaryActor)) {
+                err("uc-primary-actor-unknown", path, `UC "${id}" primaryActor "${primaryActor}" is not an actor.`);
+            }
+            else if (!(initiatorByUc.get(id)?.has(primaryActor))) {
+                err("uc-primary-actor-not-initiator", path, `UC "${id}" primaryActor "${primaryActor}" is not connected with role: "initiator". The primary actor must be an initiator.`);
+            }
+        }
+        const scenarios = asArray(uc.scenarios);
+        if (!isIncludeTarget && scenarios.length === 0) {
+            err("uc-no-scenarios", path, `UC "${id}" has no scenarios. At least one scenario with a flow is required (§4.4).`);
+        }
+        scenarios.forEach((sc, si) => {
+            const sco = (sc && typeof sc === "object") ? sc : {};
+            const scPath = `${path}.scenarios[${si}]`;
+            const flow = asArray(sco.flow);
+            if (flow.length === 0) {
+                err("scenario-no-flow", scPath, `Scenario has no flow steps. At least one step is required.`);
+            }
+            flow.forEach((step, stepIdx) => {
+                const s = (step && typeof step === "object") ? step : {};
+                const sPath = `${scPath}.flow[${stepIdx}]`;
+                const k = s.kind;
+                if (k === "actor") {
+                    const aId = String(s.actor ?? "");
+                    if (!actorIds.has(aId))
+                        err("flow-unknown-actor", sPath, `Flow step references unknown actor id "${aId}".`);
+                }
+                else if (k === "include") {
+                    const uId = String(s.uc ?? "");
+                    if (!ucIds.has(uId))
+                        err("flow-unknown-uc", sPath, `Flow step «include» references unknown UC id "${uId}".`);
+                    // Also require a matching include relationship to exist.
+                    const targets = includeIntoByUc.get(uId) || [];
+                    const hasMatching = targets.some((rel) => String(rel.from) === id);
+                    if (ucIds.has(uId) && !hasMatching) {
+                        err("flow-include-mismatch", sPath, `Flow step «include» ${uId} from UC "${id}" does not have a matching include relationship in relationships[]. Add { kind: "include", from: "${id}", to: "${uId}" } or remove this step.`);
+                    }
+                }
+                else if (k === "system" || k === "extension") {
+                    // no refs to check
+                }
+                else if (k) {
+                    err("flow-unknown-kind", sPath, `Flow step kind "${String(k)}" is not one of: actor, system, include, extension.`);
+                }
+            });
+            const extensions = asArray(sco.extensions);
+            extensions.forEach((ext, ei) => {
+                const e = (ext && typeof ext === "object") ? ext : {};
+                const at = Number(e.at);
+                if (!Number.isFinite(at) || at < 1 || at > flow.length) {
+                    err("extension-bad-at", `${scPath}.extensions[${ei}]`, `Extension.at=${String(e.at)} does not reference a valid flow step (1..${flow.length}).`);
+                }
+            });
+        });
+        if (!isIncludeTarget) {
+            const pre = asArray(uc.preconditions);
+            const post = asArray(uc.postconditions);
+            const stories = asArray(uc.userStories);
+            if (pre.length === 0)
+                warn("uc-no-preconditions", path, `UC "${id}" has no preconditions — recommended.`);
+            if (post.length === 0)
+                warn("uc-no-postconditions", path, `UC "${id}" has no postconditions — recommended.`);
+            if (stories.length === 0)
+                err("uc-no-user-stories", path, `UC "${id}" has no userStories (§4.4). Add as many as the UC warrants — one per distinct user goal.`);
+            else if (stories.length === 1)
+                warn("uc-single-user-story", path, `UC "${id}" has only 1 user story. Add one per distinct stakeholder goal behind the UC; a single token story is usually incomplete.`);
+            // CR #11 — narrative content must be in Hebrew.
+            if (isMeaningful(uc.description) && !hasHebrew(uc.description)) {
+                err("non-hebrew-text", `${path}.description`, `UC description must be written in Hebrew (CR #11).`);
+            }
+            pre.forEach((p, i) => {
+                if (isMeaningful(p) && !hasHebrew(p))
+                    err("non-hebrew-text", `${path}.preconditions[${i}]`, `Precondition must be written in Hebrew (CR #11).`);
+            });
+            post.forEach((p, i) => {
+                if (isMeaningful(p) && !hasHebrew(p))
+                    err("non-hebrew-text", `${path}.postconditions[${i}]`, `Postcondition must be written in Hebrew (CR #11).`);
+            });
+            stories.forEach((s, i) => {
+                const obj = (s && typeof s === "object") ? s : {};
+                const combined = `${obj.role ?? ""} ${obj.want ?? ""} ${obj.so ?? ""}`;
+                if (isMeaningful(combined) && !hasHebrew(combined))
+                    err("non-hebrew-text", `${path}.userStories[${i}]`, `User story must be written in Hebrew (role/want/so — CR #11).`);
+            });
+            scenarios.forEach((sc, si) => {
+                const sco = (sc && typeof sc === "object") ? sc : {};
+                const scPath = `${path}.scenarios[${si}]`;
+                asArray(sco.flow).forEach((step, stepIdx) => {
+                    const s = (step && typeof step === "object") ? step : {};
+                    if (isMeaningful(s.text) && !hasHebrew(s.text))
+                        err("non-hebrew-text", `${scPath}.flow[${stepIdx}].text`, `Flow step text must be written in Hebrew (CR #11).`);
+                });
+                asArray(sco.extensions).forEach((ext, ei) => {
+                    const e = (ext && typeof ext === "object") ? ext : {};
+                    if (isMeaningful(e.text) && !hasHebrew(e.text))
+                        err("non-hebrew-text", `${scPath}.extensions[${ei}].text`, `Extension text must be written in Hebrew (CR #11).`);
+                });
+            });
+            // Wireframe safety pre-check (regex-only; defense in depth — the HTML runtime
+            // also re-checks via wireframeSafe()).
+            const wf = uc.wireframe;
+            // §WF — a UC initiated by a human actor must have a wireframe.
+            if (primaryActor && actorIds.has(primaryActor)) {
+                const pa = actors.find((a) => String(a.id) === primaryActor);
+                const isHuman = !pa || pa.actorType !== "system";
+                const wfMissing = typeof wf !== "string" || wf.trim() === "";
+                if (isHuman && wfMissing) {
+                    err("wireframe-missing", `${path}.wireframe`, `UC "${id}" has a human primary actor ("${primaryActor}") but no wireframe. Every human-initiated UC requires a wireframe per §WF. Add one, or explicitly use a placeholder describing what info is missing.`);
+                }
+            }
+            if (typeof wf === "string" && wf.length > 0) {
+                const forbidden = [
+                    /<script\b/i,
+                    /\son\w+\s*=/i,
+                    /<iframe\b/i,
+                    /src\s*=\s*["']https?:/i,
+                    /href\s*=\s*["']https?:/i,
+                    /@import\b/i,
+                    /<style\b/i,
+                ];
+                const hit = forbidden.find((rx) => rx.test(wf));
+                if (hit) {
+                    err("wireframe-unsafe", `${path}.wireframe`, `Wireframe HTML contains a forbidden pattern (${hit}). Remove scripts / on*= / iframe / external URLs / @import / <style>.`);
+                }
+                // CR #11 — the visible text inside the wireframe (labels, buttons, headings)
+                // must be in Hebrew since the product is Hebrew. A wireframe with zero
+                // Hebrew characters is an English UI mock.
+                if (!hasHebrew(wf)) {
+                    err("wireframe-non-hebrew", `${path}.wireframe`, `Wireframe contains no Hebrew characters. Visible labels, headings, and buttons inside the wireframe must be in Hebrew (CR #11). Identifier/class names (wf-*) stay ASCII.`);
+                }
+            }
+        }
+    });
+    // CR #11 — assumptions / openQuestions must be Hebrew (they live at the model root).
+    asArray(root.assumptions).forEach((s, i) => {
+        if (isMeaningful(s) && !hasHebrew(s))
+            err("non-hebrew-text", `assumptions[${i}]`, `Assumption must be written in Hebrew (CR #11).`);
+    });
+    asArray(root.openQuestions).forEach((s, i) => {
+        if (isMeaningful(s) && !hasHebrew(s))
+            err("non-hebrew-text", `openQuestions[${i}]`, `Open question must be written in Hebrew (CR #11).`);
+    });
+    // --- Warn on too many includes (diagrams with 3+ usually have a design smell) ---
+    const totalIncludes = allRelationships.filter((r) => r.rel.kind === "include").length;
+    const totalExtends = allRelationships.filter((r) => r.rel.kind === "extend").length;
+    if (totalIncludes + totalExtends > 2) {
+        warn("many-include-extend", "relationships", `Diagram has ${totalIncludes} «include» and ${totalExtends} «extend» relationships. Most UC diagrams need ≤2 combined — review each against the §4 gate.`);
+    }
+    if (errors.length > 0)
+        return { ok: false, issues: errors, warnings };
+    return { ok: true, warnings };
+}
+export function parseAndValidate(jsonText) {
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonText);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            issues: [{ severity: "error", code: "invalid-json", path: "(root)", message: `JSON parse failed: ${msg}` }],
+            warnings: [],
+        };
+    }
+    return validateModel(parsed);
+}
+export function formatIssues(issues) {
+    if (issues.length === 0)
+        return "(no issues)";
+    return issues
+        .map((i) => `- [${i.severity === "error" ? "ERROR" : "warn"}] [${i.code}] ${i.path}: ${i.message}`)
+        .join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sad-mcp",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "MCP server for Software Analysis and Design course materials at BGU",
   "type": "module",
   "bin": {

package/skills/uml-use-case-diagram/SKILL.md

@@ -788,20 +788,25 @@ Available wireframe classes (for §WF): `wf-screen`, `wf-heading`, `wf-row`, `wf
   <!-- VP export button -->
   <button class="vp-export-btn" onclick="exportXMI()">Download .xmi (Visual Paradigm)</button>
 
-  <!-- DIAGRAM DATA ONLY — all functions are in uc-diagram-common.js -->
+  <!-- DIAGRAM DATA ONLY — all functions are in uc-diagram-common.js.
+       Use var (NOT const/let) so these become window properties accessible from the external script.
+       Do NOT add activeTab, currentLayout, showDiagram, exportXMI, xmlEscape, downloadFile,
+       or any DOMContentLoaded handler here — they all live in uc-diagram-common.js.
+       Adding let/const variables with the same names as any variable in the external script
+       causes a SyntaxError that silently kills the entire external script. -->
   <script>
-    const diagramLayouts      = [ /* one layout object per tab, per §6 */ ];
-    const actorDescriptions   = { /* §8b — one entry per actor */ };
-    const assocDescriptions   = { /* §8b — one entry per association line */ };
-    const useCaseDocs         = { /* §8a — full per-UC documentation */ };
-    const diagramModel        = { /* model-shape.md, kind: 'use-case' */ };
+    var diagramLayouts      = [ /* one layout object per tab, per §6 */ ];
+    var actorDescriptions   = { /* §8b — one entry per actor */ };
+    var assocDescriptions   = { /* §8b — one entry per association line */ };
+    var useCaseDocs         = { /* §8a — full per-UC documentation */ };
+    var diagramModel        = { /* model-shape.md, kind: 'use-case' */ };
   </script>
   <script src="https://themathbible.com/sad-mcp/uc-diagram-common.js"></script>
 </body>
 </html>
 ```
 
-**Single-tab diagrams still define the full script.** Always emit `diagramLayouts` (one-element array), `activeTab`, `currentLayout()`, **and `showDiagram(index)`**. Only the HTML-level tab bar and the second `.diagram-part` are conditional on splitting. Omitting `showDiagram` is a silent bug: a future edit that adds tabs will have dead onclick handlers with no console error pointing at the cause.
+**Single-tab diagrams still define the full script.** Always emit all five `var` data globals; the tab bar HTML and second `.diagram-part` are the only things conditional on splitting. `showDiagram`, `currentLayout`, `activeTab`, `fixLayout`, `exportXMI` and all other functions live exclusively in `uc-diagram-common.js` — never re-declare them inline.
 
 ---