sad-mcp 2.2.7 → 2.2.8

package/package.json

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

package/skills/uml-class-diagram/SKILL.md

@@ -14,7 +14,8 @@ description: >
 
 > **Canonical authority:** The notation rules in `NOTATION.md` (sibling file) are the ground truth. If any rule below conflicts with `NOTATION.md`, `NOTATION.md` wins.
 
-Produce a single self-contained interactive HTML file with an embedded SVG class diagram.
+Produce a single self-contained interactive HTML file. The SVG is **built at runtime by inline JavaScript**: Claude generates `CLASSES` and `RELS` data arrays; a `render()` engine (§9d) builds the SVG from them. This is essential — SVG cannot measure text at generation time, so box heights must be computed in JS from data, not hardcoded by Claude.
+
 The shared files prepended to this prompt define the layout recipes, model shape, and export button you must use.
 
 ---
@@ -44,6 +45,20 @@ Before drawing, extract:
 - Visibility: `+` public, `-` private, `#` protected
 - Stereotype: when present, render above the class name in the header at 9px; increase header height to ≥38px so both lines are readable
 
+### What NOT to model as a class
+
+Before adding any class, verify: **"Does the system store and manage records of this entity?"**
+- **Yes** → model as a class.
+- **No** → do not add it.
+
+Two common false positives:
+
+**1. Computed outputs** — reports, invoices-as-output, receipts, confirmation emails, search results. These are system behavior (use cases), not persistent entities. Do not add them as classes.
+
+**2. Real-world participants the system never tracks** — if an entity is mentioned only as a real-world actor ("the customer calls", "the supplier sends goods") but the system never stores their record, do not model them as a class.
+
+**UC diagram cross-check:** if a candidate class has no associations to any use case in the UC diagram, it almost certainly does not belong in the domain model. Verify before adding it.
+
 ### Enumerations
 - Stereotype header: `«enumeration»`
 - Styling: gray dashed border (`#94a3b8`, dasharray 5 3), gray header (`#475569`), `#f8fafc` fill
@@ -63,12 +78,17 @@ Before drawing, extract:
 
 | Relationship | Line | Arrowhead | When to use |
 |---|---|---|---|
-| Association | Solid | None | Default: two classes know of each other |
-| Directed association | Solid | Open arrow | When navigation is one-way only |
+| Association | Solid | **None** | Default for all class-to-class relationships in a domain/analysis diagram — plain lines only |
+| Directed association | Solid | Open arrow | **NEVER in domain/analysis diagrams.** Only in design-level diagrams when documenting one-way navigation in code |
 | Aggregation | Solid | Hollow diamond at whole | "has-a", part can exist independently |
 | Composition | Solid | Filled diamond at whole | Part cannot exist without whole |
 | Generalization | Solid | Hollow triangle at parent | True is-a; subtypes have different attributes/ops |
-| Dependency | Dashed | Open arrow | One class uses another transiently |
+| Dependency | Dashed | Open arrow | **ONLY** when a class references an enumeration type as an attribute type. Never between two regular classes — use plain association instead |
+
+> **CRITICAL — domain diagram association rules:**
+> - Plain association (──): the default for every class-to-class relationship. No arrowheads.
+> - Dependency (---→): only for enumeration usage. Never on class-to-class relationships.
+> - Directed association (──→): never in a domain or analysis diagram.
 
 **Multiplicity at both ends of every association**: `1`, `0..1`, `1..*`, `0..*`. Never leave one end unlabeled.
 
@@ -76,18 +96,25 @@ Before drawing, extract:
 
 **Constraint notation**: if a business rule constrains an attribute or association, add `{constraint text}` near the relevant end.
 
-### Mediating class (מחלקה מתווכת)
-When a many-to-many relationship needs to store data (e.g., enrollment has a grade), convert it to a mediating class:
-- Draw a regular class with a meaningful name
-- Connect it with two associations (each 1..* or 1 depending on the domain)
-- Add the data attributes to this class
-- This is different from an association class — a mediating class is a full entity in the model
+### Mediating class vs Association class — never confuse these two
+
+| | Mediating class (מחלקה מתווכת) | Association class (מחלקת קשר) |
+|---|---|---|
+| **When** | Intermediate entity has independent identity and lifecycle | Relationship itself has attributes; no independent lifecycle |
+| **Drawing** | Regular class box with two **separate** associations replacing the many-to-many | Regular class box connected to the **midpoint** of an existing association line via a **dashed perpendicular line** |
+| **The original association** | Is **removed** — the mediating class replaces it | **Remains** — the association class is attached to it |
+| **Example** | `OrderLine` between `Order` and `Product` | `Enrollment` (grade) between `Student` and `Course` |
 
-### Association class (מחלקת קשר)
-When a relationship itself has attributes but no independent identity:
-- Draw a regular class box with `«association class»` stereotype
-- Connect it to the **midpoint** of the association line with a **dashed line**, perpendicular where possible
-- Never connect it as a plain class with a dependency arrow — that is wrong UML
+**Mediating class (מחלקה מתווכת):**
+- Replaces a many-to-many association entirely
+- Drawn as a normal class with two separate associations pointing to each side
+- Has its own primary key, independent existence
+
+**Association class (מחלקת קשר):**
+- Does NOT replace the association — the association line stays
+- Connected to the **midpoint** of that line with a dashed perpendicular line
+- Stereotype: `«association class»`
+- Never connect it with a dependency arrow — that is wrong UML
 
 ### Generalization (inheritance)
 Use only when subtypes have genuinely different attributes or operations:
@@ -114,6 +141,8 @@ MARGIN_LEFT = 60, MARGIN_TOP = 80
 ```
 Enumerations share the grid with the classes that reference them (not in a separate zone).
 
+The resulting `x, y` values for each class go directly into the `CLASSES` data array (§9b). Use `boxW ≈ max(120, longestString * 6.5 + 16)` to estimate widths for routing; the runtime recomputes actual widths from text content.
+
 ### Step 3 — Post-placement safety pass with `collision-nudge`
 Run `collision-nudge` after step 2. After nudging, recompute all relationship endpoints using `rect-boundary-intersect`.
 
@@ -167,6 +196,12 @@ Hollow diamond:   fill white, stroke #334155
 Font:             'IBM Plex Mono', monospace (Google Fonts import)
 ```
 
+### SVG rendering rules (enforced by §9d engine)
+
+- `<html>` must **not** have `dir="rtl"` — SVG coordinates are always LTR.
+- Class name: `text-anchor="middle"`. Attribute and operation rows: `text-anchor="start"` at `x = box.x + 6`. Never use `text-anchor="middle"` for attribute/op rows.
+- Box heights are computed by `boxH()` in the §9d engine — never hardcode them.
+
 ---
 
 ## 7. Legend Bar
@@ -187,45 +222,232 @@ Define this JavaScript variable in every generated HTML `<script>` block, follow
 
 ## 9. HTML File Structure
 
+The file uses **JS-driven rendering**: Claude fills in `CLASSES` + `RELS` data; the engine builds the SVG at page load. Do not write raw SVG with class boxes — use the pattern below.
+
+### 9a. Page skeleton
+
 ```html
 <!DOCTYPE html>
-<html lang="he" dir="rtl">
+<html lang="he">
 <head>
   <meta charset="UTF-8">
   <title>[Diagram title]</title>
   <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;700&display=swap" rel="stylesheet">
-  <style>/* tabs, layout, export button, dot-grid */</style>
+  <style>
+    body { margin: 0; background: #f1f5f9; font-family: 'IBM Plex Mono', monospace; }
+    .tab-bar { display: flex; gap: 4px; padding: 8px; background: #e2e8f0; }
+    .tab-btn { padding: 4px 12px; border: 1px solid #cbd5e1; background: white; cursor: pointer; border-radius: 4px; }
+    .tab-btn.active { background: #1e40af; color: white; }
+    .split-rationale { font-size: 11px; color: #64748b; padding: 4px 8px; }
+    svg { display: block; }
+    /* VP export button styles from export-buttons.md */
+  </style>
 </head>
 <body>
-  <!-- Tab bar (only when split) -->
-  <div class="tab-bar">...</div>
-
-  <!-- One SVG per part, shown/hidden by tab selection -->
-  <div class="diagram-part" id="part-1">
-    <div class="split-rationale">Split by package: ...</div>
-    <svg>
-      <!-- dot-grid background, classes, enumerations, edges, legend -->
-    </svg>
-  </div>
-
-  <!-- Visual Paradigm export button (from export-buttons.md) -->
+  <!-- Tab bar — include only when split (§5) -->
+  <div class="tab-bar" id="tab-bar"></div>
+
+  <!-- SVG target; JS populates it -->
+  <svg id="diagram-svg" xmlns="http://www.w3.org/2000/svg"></svg>
+
+  <!-- VP export button (from export-buttons.md) -->
   <button class="vp-export-btn" onclick="exportXMI()">Download .xmi (Visual Paradigm)</button>
 
   <script>
-    const diagramModel = { ... };   // model-shape.md for kind:'class'
-    function xmiBody(elements, rels) { ... }  // from export-buttons.md
-    function exportXMI() { ... }              // from export-buttons.md
-    // xmlEscape, downloadFile helpers        // from export-buttons.md
-    // Tab switching
-    function showPart(id) {
-      document.querySelectorAll('.diagram-part').forEach(p => p.hidden = true);
-      document.getElementById(id).hidden = false;
-    }
+    /* 1. DATA — Claude fills in CLASSES and RELS (§9b, §9c) */
+    /* 2. ENGINE — copy §9d verbatim                         */
+    /* 3. VP EXPORT — from export-buttons.md                 */
+    /* 4. diagramModel — from model-shape.md for kind:'class'*/
+    document.addEventListener('DOMContentLoaded', render);
   </script>
 </body>
 </html>
 ```
 
+### 9b. CLASSES data (Claude generates this)
+
+```javascript
+const CLASSES = [
+  {
+    id: 'Order',           // unique key — referenced by RELS
+    name: 'Order',         // display name
+    stereotype: null,      // null | '«enumeration»' | '«abstract»' | custom string
+    isEnum: false,         // true → enum styling (gray dashed border + header)
+    isAbstract: false,     // true → name in italic
+    attrs: [               // attribute strings, as they appear in the box
+      '+ orderId : String',
+      '+ date : Date',
+      '+ status : OrderStatus'
+    ],
+    ops: [                 // operation strings — rendered italic
+      '+ calculateTotal() : Money'
+    ],
+    x: 60,                 // top-left x from layout algorithm (§4)
+    y: 80                  // top-left y from layout algorithm (§4)
+  }
+  // ... more entries
+];
+```
+
+### 9c. RELS data (Claude generates this)
+
+```javascript
+const RELS = [
+  {
+    type: 'assoc',         // 'assoc' | 'agg' | 'comp' | 'gen' | 'dep'
+    from: 'Order',         // class id
+    to: 'Customer',
+    fromMult: '0..*',      // null for generalization
+    toMult: '1',
+    fromRole: null,        // null or role name string
+    toRole: null,
+    label: null,           // optional mid-line label
+    points: [              // orthogonal polyline — Claude computes from layout positions
+      [200, 130], [200, 200], [340, 200]
+    ]
+  }
+];
+```
+
+**Computing `points`:** estimate `boxW ≈ max(120, longestString * 6.5 + 16)` for routing. All consecutive pairs must share x or y (orthogonal). Start/end at the nearest box edge.
+
+### 9d. Rendering engine (copy verbatim into `<script>`)
+
+```javascript
+// ── Constants ─────────────────────────────────────────────────────────────
+const HDR_H = 28, PAD = 6, LINE_H = 14, DIV_H = 1;
+const FM = 'font-family="IBM Plex Mono, monospace"';
+
+function escXml(s) {
+  return String(s)
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+function boxH(cls) {
+  const hdrH = cls.stereotype ? 38 : HDR_H;
+  return hdrH + PAD + cls.attrs.length * LINE_H +
+    (cls.ops.length > 0 ? DIV_H + cls.ops.length * LINE_H : 0) + PAD;
+}
+
+function boxW(cls) {
+  const longest = [...cls.attrs, ...cls.ops, cls.name]
+    .reduce((m, s) => Math.max(m, s.length), 0);
+  return Math.max(120, Math.ceil(longest * 6.5) + 16);
+}
+
+function svgBox(cls) {
+  const w = boxW(cls), h = boxH(cls), { x, y } = cls;
+  const hdrH = cls.stereotype ? 38 : HDR_H;
+  const border   = cls.isEnum ? '#94a3b8' : '#3b82f6';
+  const hdrFill  = cls.isEnum ? '#475569' : '#1e40af';
+  const bodyFill = cls.isEnum ? '#f8fafc' : 'white';
+  const dash     = cls.isEnum ? 'stroke-dasharray="5 3"' : '';
+
+  let s = `<rect x="${x}" y="${y}" width="${w}" height="${h}" fill="${bodyFill}" stroke="${border}" stroke-width="2" ${dash} rx="2"/>`;
+  s += `<rect x="${x}" y="${y}" width="${w}" height="${hdrH}" fill="${hdrFill}" rx="2"/>`;
+
+  if (cls.stereotype) {
+    s += `<text x="${x + w/2}" y="${y + 13}" text-anchor="middle" fill="white" font-size="9" ${FM}>${escXml(cls.stereotype)}</text>`;
+  }
+  const nameStyle = cls.isAbstract ? 'font-style:italic' : '';
+  const nameY = cls.stereotype ? y + hdrH - 8 : y + hdrH / 2 + 4;
+  s += `<text x="${x + w/2}" y="${nameY}" text-anchor="middle" fill="white" font-size="11" font-weight="700" ${FM} style="${nameStyle}">${escXml(cls.name)}</text>`;
+
+  const divY = y + hdrH;
+  s += `<line x1="${x}" y1="${divY}" x2="${x + w}" y2="${divY}" stroke="${border}" stroke-width="1"/>`;
+
+  let curY = divY + PAD + 10;
+  for (const a of cls.attrs) {
+    s += `<text x="${x + 6}" y="${curY}" text-anchor="start" fill="#1e293b" font-size="10.5" ${FM}>${escXml(a)}</text>`;
+    curY += LINE_H;
+  }
+  if (cls.ops.length > 0) {
+    const opDivY = divY + PAD + cls.attrs.length * LINE_H;
+    s += `<line x1="${x}" y1="${opDivY}" x2="${x + w}" y2="${opDivY}" stroke="${border}" stroke-width="1"/>`;
+    curY = opDivY + PAD + 10;
+    for (const o of cls.ops) {
+      s += `<text x="${x + 6}" y="${curY}" text-anchor="start" fill="#2563eb" font-size="10.5" font-style="italic" ${FM}>${escXml(o)}</text>`;
+      curY += LINE_H;
+    }
+  }
+  return s;
+}
+
+function svgRel(rel) {
+  const pts = rel.points.map(([px, py]) => `${px},${py}`).join(' ');
+  let mS = '', mE = '', dash = '';
+  if (rel.type === 'comp') mS = 'marker-start="url(#compFill)"';
+  if (rel.type === 'agg')  mS = 'marker-start="url(#aggHollow)"';
+  if (rel.type === 'gen')  mE = 'marker-end="url(#genHollow)"';
+  if (rel.type === 'dep')  { mE = 'marker-end="url(#arrOpen)"'; dash = 'stroke-dasharray="6 3"'; }
+  // 'assoc': no markers — plain line
+
+  let s = `<polyline points="${pts}" fill="none" stroke="#334155" stroke-width="1.8" ${dash} ${mS} ${mE}/>`;
+  if (rel.fromMult) {
+    const [fx, fy] = rel.points[0];
+    s += `<text x="${fx + 4}" y="${fy - 4}" fill="#64748b" font-size="9.5" ${FM}>${escXml(rel.fromMult)}</text>`;
+  }
+  if (rel.toMult) {
+    const [tx, ty] = rel.points[rel.points.length - 1];
+    s += `<text x="${tx + 4}" y="${ty - 4}" fill="#64748b" font-size="9.5" ${FM}>${escXml(rel.toMult)}</text>`;
+  }
+  if (rel.label) {
+    const mid = rel.points[Math.floor(rel.points.length / 2)];
+    s += `<text x="${mid[0]}" y="${mid[1] - 6}" text-anchor="middle" fill="#64748b" font-size="9.5" ${FM}>${escXml(rel.label)}</text>`;
+  }
+  return s;
+}
+
+function render() {
+  let maxX = 600, maxY = 400;
+  for (const cls of CLASSES) {
+    maxX = Math.max(maxX, cls.x + boxW(cls) + 60);
+    maxY = Math.max(maxY, cls.y + boxH(cls) + 80);
+  }
+
+  const defs = `<defs>
+    <pattern id="dotgrid" width="24" height="24" patternUnits="userSpaceOnUse">
+      <circle cx="12" cy="12" r="0.8" fill="#cbd5e1"/>
+    </pattern>
+    <marker id="genHollow" markerWidth="12" markerHeight="10" refX="10" refY="5" orient="auto">
+      <polygon points="0,0 10,5 0,10" fill="white" stroke="#334155" stroke-width="1.5"/>
+    </marker>
+    <marker id="arrOpen" markerWidth="10" markerHeight="8" refX="9" refY="4" orient="auto">
+      <polyline points="0,0 9,4 0,8" fill="none" stroke="#334155" stroke-width="1.5"/>
+    </marker>
+    <marker id="compFill" markerWidth="14" markerHeight="10" refX="1" refY="5" orient="auto">
+      <polygon points="0,5 7,0 14,5 7,10" fill="#1e40af" stroke="#1e40af"/>
+    </marker>
+    <marker id="aggHollow" markerWidth="14" markerHeight="10" refX="1" refY="5" orient="auto">
+      <polygon points="0,5 7,0 14,5 7,10" fill="white" stroke="#334155"/>
+    </marker>
+  </defs>`;
+
+  // totalWidth / totalHeight include margins and space for the legend.
+  // RIGHT_MARGIN ≥ 40px, BOTTOM_MARGIN ≥ 70px (legend needs ~50px).
+  // These are already baked into maxX / maxY from the loop above (60px / 80px).
+  const totalWidth  = maxX;
+  const totalHeight = maxY;   // legend drawn at totalHeight - 60, inside this height
+
+  const bg    = `<rect width="${totalWidth}" height="${totalHeight}" fill="url(#dotgrid)"/>`;
+  const rels  = RELS.map(svgRel).join('');
+  const boxes = CLASSES.map(svgBox).join('');
+  // Legend is placed at totalHeight - 60 so it always lands inside the viewBox.
+  const legend = `<text x="16" y="${totalHeight - 60}" fill="#64748b" font-size="9" ${FM}>── Association  ◇── Aggregation  ◆── Composition  ──▷ Generalization  --→ Dependency (enum only)</text>`;
+
+  const svg = document.getElementById('diagram-svg');
+  svg.setAttribute('width',   totalWidth);
+  svg.setAttribute('height',  totalHeight);
+  svg.setAttribute('viewBox', `0 0 ${totalWidth} ${totalHeight}`);
+  svg.innerHTML = defs + bg + rels + boxes + legend;
+}
+```
+
+### 9e. Multi-part (tabbed) diagrams
+
+When splitting (§5), generate one `<svg id="svg-part-N">` per part. Split `CLASSES` and `RELS` into per-part arrays. Call `render()` variants that target each SVG element. Tab buttons toggle `hidden` and call the matching render function.
+
 ---
 
 ## 10. Output
@@ -248,14 +470,21 @@ When in doubt, use the male form.
 
 ## 12. Common Mistakes — Check Before Delivering
 
+- [ ] Every class passes the persistence test: "Does the system store and manage records of this entity?" — computed outputs (reports, receipts) and real-world participants the system never tracks are not domain entities
 - [ ] Every association has multiplicity at **both** ends
 - [ ] All lines are orthogonal — run the x1===x2 || y1===y2 check on every polyline
 - [ ] No line segment passes through any class bounding box — use `rect-boundary-intersect` for all endpoints
-- [ ] Association class connected to midpoint of association via dashed line (not as a standalone class)
-- [ ] Many-to-many with data → mediating class (not association class)
+- [ ] Association class (מחלקת קשר): connected to the **midpoint** of the original association line via a dashed perpendicular line; the original association remains
+- [ ] Mediating class (מחלקה מתווכת): **replaces** the many-to-many with two separate associations; drawn as a plain class, NOT connected to a line midpoint
 - [ ] Enumerations placed near using class (not in a fixed zone)
 - [ ] diagramModel defined in `<script>` and matches model-shape.md
 - [ ] VP export button present and wired to `exportXMI()`
 - [ ] If split: each part has a visible split-rationale line
 - [ ] Operations text is italic
 - [ ] Hebrew names use male form
+- [ ] **No raw SVG class boxes** — class boxes are rendered by `svgBox()` from `CLASSES` data, not hand-written SVG
+- [ ] **No arrowheads on plain associations** — `type: 'assoc'` in RELS produces no marker; directed association never appears in domain/analysis diagrams
+- [ ] **Dependency (---→) only for enum usage** — `type: 'dep'` only when a class references an enum type; never between two regular classes
+- [ ] **`<html>` has no `dir="rtl"`** — SVG coordinates are LTR; page language does not affect SVG rendering
+- [ ] **`boxH()` / `boxW()` from §9d engine used** — never hardcode box dimensions in data or SVG
+- [ ] **Attribute/operation rows: `text-anchor="start"` at `x = box.x + 6`** — enforced by engine; do not override