@yalehwang/plantuml-js 0.2.0 → 0.3.0

package/dist/transform.js

@@ -9,6 +9,11 @@
  * input and produces the same output for the same input, so a transformed
  * render stays byte-for-byte reproducible.
  */
+import { relationSemantics } from './foundation/relation-semantics.js';
+/** Entity count above which inter-package edges aggregate into corridors by default. */
+export const INTER_PACKAGE_AGGREGATE_ENTITY_THRESHOLD = 150;
+/** Stub count above which a single-package view groups stubs by name prefix. */
+export const DEFAULT_STUB_GROUP_THRESHOLD = 8;
 const ROOT = '__root__';
 function cloneModel(model) {
     return {
@@ -24,23 +29,89 @@ function cloneModel(model) {
  * summarization, then cycle marking on the final edge set.
  */
 export function transformModel(model, options = {}) {
-    const { aggregate = true, transitiveReduction = false, hubThreshold, cycles = false } = options;
+    return transformModelDetailed(model, options).model;
+}
+/** [[transformModel]] plus the number of edges the transitive reduction hid. */
+export function transformModelDetailed(model, options = {}) {
+    const { aggregate = true, transitiveReduction = false, hubThreshold, cycles = false, interPackage = 'raw' } = options;
     let out = cloneModel(model);
+    out = summarizeExternals(out, EXTERNAL_SUMMARY_MIN_IN_EDGES);
     if (aggregate)
         out = aggregateRelations(out);
-    if (transitiveReduction)
+    let hiddenTransitive = 0;
+    if (transitiveReduction) {
+        const before = out.relations.length;
         out = transitiveReduce(out);
+        hiddenTransitive = before - out.relations.length;
+    }
     if (hubThreshold !== undefined)
         out = summarizeHubs(out, hubThreshold);
+    if (interPackage === 'aggregate')
+        out = aggregateInterPackage(out);
     if (cycles)
         out = markCycles(out);
-    return out;
+    return { model: groupExternals(out), hiddenTransitive };
+}
+/** Edge count ÷ node count above which `edgeReduction: 'auto'` reduces a pure dependency graph. */
+export const AUTO_REDUCTION_EDGE_NODE_RATIO = 3;
+/**
+ * Whether `edgeReduction: 'auto'` applies: every relation is bundlable
+ * (dependency/association) and there are more than
+ * [[AUTO_REDUCTION_EDGE_NODE_RATIO]] times as many edges as nodes.
+ */
+export function shouldAutoReduce(model) {
+    if (model.relations.length === 0)
+        return false;
+    if (!model.relations.every((r) => relationSemantics(r.type).isBundlable()))
+        return false;
+    const nodes = model.entities.length;
+    const distinct = new Set(model.relations.map((r) => `${r.source}\u0000${r.target}`)).size;
+    return distinct > AUTO_REDUCTION_EDGE_NODE_RATIO * nodes;
+}
+/** Incoming edges at which an external type's edges collapse into a count badge. */
+export const EXTERNAL_SUMMARY_MIN_IN_EDGES = 3;
+/** Id of the synthetic package that gathers implicit/external types. */
+export const EXTERNAL_PACKAGE_ID = '__external__';
+/**
+ * Implicit/external types (`Error`, `EventEmitter`, …) receive many parallel
+ * edges that would fly across the whole canvas. Once one has `minEdges` or more
+ * incoming relations they are dropped and replaced by a `usageCount` badge that
+ * carries the original incoming-edge count.
+ */
+export function summarizeExternals(model, minEdges) {
+    const incoming = new Map();
+    for (const r of model.relations) {
+        const e = model.entities.find((x) => x.id === r.target);
+        if (e?.external)
+            incoming.set(r.target, (incoming.get(r.target) ?? 0) + (r.weight ?? 1));
+    }
+    const summarized = new Set([...incoming].filter(([, n]) => n >= minEdges).map(([id]) => id));
+    if (summarized.size === 0)
+        return model;
+    return {
+        ...model,
+        entities: model.entities.map((e) => summarized.has(e.id) ? { ...e, usageCount: incoming.get(e.id) } : e),
+        relations: model.relations.filter((r) => !summarized.has(r.target)),
+    };
+}
+/** Gather top-level external entities into one synthetic External package. */
+export function groupExternals(model) {
+    const externals = model.entities.filter((e) => e.external && e.packageId === undefined);
+    if (externals.length < 2 || model.packages.some((p) => p.id === EXTERNAL_PACKAGE_ID)) {
+        return model;
+    }
+    const ids = new Set(externals.map((e) => e.id));
+    return {
+        ...model,
+        entities: model.entities.map((e) => (ids.has(e.id) ? { ...e, packageId: EXTERNAL_PACKAGE_ID } : e)),
+        packages: [...model.packages, { id: EXTERNAL_PACKAGE_ID, name: 'External' }],
+    };
 }
 /** Merge relations sharing (source, target) into one edge with `weight`. */
 export function aggregateRelations(model) {
     const byKey = new Map();
     for (const relation of model.relations) {
-        const key = `${relation.source}\u0000${relation.target}`;
+        const key = `${relation.source}\u0000${relation.target}\u0000${relation.sourcePackageId ?? ''}\u0000${relation.targetPackageId ?? ''}`;
         const existing = byKey.get(key);
         if (existing) {
             existing.weight = (existing.weight ?? 1) + 1;
@@ -51,6 +122,89 @@ export function aggregateRelations(model) {
     }
     return { ...model, relations: [...byKey.values()] };
 }
+/**
+ * Fold every relation between two different packages into one corridor edge
+ * per ordered package pair: `weight` = number of originals, `descriptions`
+ * keeps each original, and the endpoints are the entities carrying most of the
+ * traffic with `sourcePackageId`/`targetPackageId` set so the layout clips the
+ * edge to the frame boundaries. Intra-package edges and edges touching
+ * package-less entities, or between nested packages, are left as they are.
+ */
+export function aggregateInterPackage(model) {
+    const pkgOf = new Map(model.entities.map((e) => [e.id, e.packageId]));
+    const parent = new Map(model.packages.map((p) => [p.id, p.parentId]));
+    const nested = (a, b) => {
+        for (const [x, y] of [[a, b], [b, a]]) {
+            for (let p = parent.get(x); p !== undefined; p = parent.get(p))
+                if (p === y)
+                    return true;
+        }
+        return false;
+    };
+    const groups = new Map();
+    const relations = [];
+    for (const rel of model.relations) {
+        const a = pkgOf.get(rel.source);
+        const b = pkgOf.get(rel.target);
+        if (!a || !b || a === b || nested(a, b) || rel.sourcePackageId || rel.targetPackageId) {
+            relations.push(rel);
+            continue;
+        }
+        const key = `${a}\u0000${b}`;
+        let g = groups.get(key);
+        if (!g) {
+            g = { src: a, dst: b, items: [], srcCount: new Map(), dstCount: new Map(), at: relations.length };
+            groups.set(key, g);
+            relations.push(g);
+        }
+        g.items.push(rel);
+        g.srcCount.set(rel.source, (g.srcCount.get(rel.source) ?? 0) + 1);
+        g.dstCount.set(rel.target, (g.dstCount.get(rel.target) ?? 0) + 1);
+    }
+    const top = (m) => {
+        let best = '';
+        let n = -1;
+        for (const [k, v] of m)
+            if (v > n) {
+                best = k;
+                n = v;
+            }
+        return best;
+    };
+    const out = relations.map((r) => {
+        if (!('items' in r))
+            return r;
+        const types = new Set(r.items.map((i) => i.type));
+        const only = r.items.length === 1 ? r.items[0].type : [...types][0];
+        const type = types.size === 1 && relationSemantics(only).isBundlable() ? only : 'dependency';
+        return {
+            source: top(r.srcCount),
+            target: top(r.dstCount),
+            type,
+            weight: r.items.reduce((sum, i) => sum + (i.weight ?? 1), 0),
+            feedback: r.items.every((i) => i.feedback) || undefined,
+            sourcePackageId: r.src,
+            targetPackageId: r.dst,
+            descriptions: r.items.map((i) => `${i.source} ${ARROWS[i.type]} ${i.target}${i.label ? ` : ${i.label}` : ''}`),
+        };
+    });
+    return { ...model, relations: out.map(dropUndefined) };
+}
+const ARROWS = {
+    inheritance: '--|>',
+    implementation: '..|>',
+    dependency: '..>',
+    association: '-->',
+    aggregation: 'o--',
+    composition: '*--',
+};
+function dropUndefined(r) {
+    const copy = { ...r };
+    for (const k of Object.keys(copy))
+        if (copy[k] === undefined)
+            delete copy[k];
+    return copy;
+}
 /**
  * Remove a relation A→B when A still reaches B through another path (an edge
  * derivable by transitivity). Only the redundant direct edge is dropped; the
@@ -58,37 +212,52 @@ export function aggregateRelations(model) {
  */
 export function transitiveReduce(model) {
     const targets = new Map();
-    for (const relation of model.relations) {
-        const list = targets.get(relation.source);
-        if (list)
-            list.push(relation.target);
-        else
-            targets.set(relation.source, [relation.target]);
-    }
-    const reachable = (start, goal, skipTarget) => {
-        const seen = new Set();
-        const queue = [start];
-        while (queue.length > 0) {
-            const u = queue.shift();
-            for (const v of targets.get(u) ?? []) {
-                if (u === start && v === skipTarget)
-                    continue; // ignore the direct edge under test
+    const addEdge = (u, v) => {
+        const m = targets.get(u) ?? new Map();
+        m.set(v, (m.get(v) ?? 0) + 1);
+        targets.set(u, m);
+    };
+    for (const relation of model.relations)
+        addEdge(relation.source, relation.target);
+    const reachable = (start, goal) => {
+        const seen = new Set([start]);
+        const stack = [start];
+        while (stack.length > 0) {
+            const u = stack.pop();
+            for (const v of targets.get(u)?.keys() ?? []) {
                 if (v === goal)
                     return true;
                 if (!seen.has(v)) {
                     seen.add(v);
-                    queue.push(v);
+                    stack.push(v);
                 }
             }
         }
         return false;
     };
-    const relations = model.relations.filter((relation) => {
-        // A self-loop is its own shortest witness; keep it. A single-hop edge with
-        // no alternate path is necessary; keep it.
-        return !reachable(relation.source, relation.target, relation.target);
+    // Greedy in authored order: an edge is dropped when its end points stay
+    // connected through the edges still present, so reachability is preserved
+    // exactly (also inside cycles, where dropping every "redundant" edge at once
+    // would disconnect the cycle). A self-loop is its own witness and is kept.
+    const removed = new Set();
+    model.relations.forEach((relation, i) => {
+        if (relation.source === relation.target)
+            return;
+        const out = targets.get(relation.source);
+        const count = out.get(relation.target);
+        if (count > 1) {
+            // A parallel duplicate of the same pair is always redundant.
+            out.set(relation.target, count - 1);
+            removed.add(i);
+            return;
+        }
+        out.delete(relation.target);
+        if (reachable(relation.source, relation.target))
+            removed.add(i);
+        else
+            out.set(relation.target, 1);
     });
-    return { ...model, relations };
+    return { ...model, relations: model.relations.filter((_, i) => !removed.has(i)) };
 }
 /**
  * Nodes with an in-degree above `threshold` have their incoming edges dropped
@@ -170,7 +339,7 @@ export function applyView(model, view) {
             }
             return overviewView(model);
         case 'package':
-            return packageView(model, view.id);
+            return packageView(model, view.id, view.stubGroupThreshold ?? DEFAULT_STUB_GROUP_THRESHOLD);
         case 'neighborhood':
             return neighborhoodView(model, view.entity, view.hops);
     }
@@ -276,7 +445,7 @@ export function groupByPathPrefix(model, depth) {
  * merged by aggregation). Entities and relations entirely outside the package
  * are dropped.
  */
-function packageView(model, id) {
+function packageView(model, id, stubGroupThreshold) {
     const pkgById = new Map(model.packages.map((p) => [p.id, p]));
     const selected = pkgById.get(id);
     if (!selected) {
@@ -332,13 +501,92 @@ function packageView(model, id) {
         const stub = stubFor(externalKey);
         relations.push(sourceIn ? { ...relation, target: stub.id } : { ...relation, source: stub.id });
     }
+    const grouped = groupStubs({ entities, relations }, stubGroupThreshold);
     return {
         diagramType: 'class',
-        entities,
-        relations,
+        entities: grouped.entities,
+        relations: grouped.relations,
         packages: [{ ...selected, parentId: undefined }],
     };
 }
+/** Name with its last word dropped (`Src Cli Utils` → `Src Cli`); a one-word name stays as is. */
+function namePrefix(name) {
+    const words = name.trim().split(/\s+/);
+    return words.length > 1 ? words.slice(0, -1).join(' ') : name;
+}
+/**
+ * Past `threshold` stubs, merge stubs sharing a name prefix into one group stub
+ * (`Src Cli … (×6)`), dropping trailing words until the group count fits (or nothing shortens any
+ * more). The edges to the members of a group collapse onto
+ * the group stub per (entity, direction): `weight` counts the originals and
+ * `descriptions` keeps each one for the edge's `<title>`.
+ */
+export function groupStubs(model, threshold) {
+    const stubs = model.entities.filter((e) => e.stub);
+    if (stubs.length <= threshold)
+        return model;
+    let keyOf = new Map(stubs.map((e) => [e.id, e.name]));
+    for (;;) {
+        if (new Set(keyOf.values()).size <= threshold)
+            break;
+        const next = new Map([...keyOf].map(([id, k]) => [id, namePrefix(k)]));
+        if ([...next].every(([id, k]) => k === keyOf.get(id)))
+            break;
+        keyOf = next;
+    }
+    const members = new Map();
+    for (const stub of stubs) {
+        const key = keyOf.get(stub.id);
+        const list = members.get(key);
+        if (list)
+            list.push(stub);
+        else
+            members.set(key, [stub]);
+    }
+    const groupId = new Map();
+    const entities = [];
+    for (const e of model.entities) {
+        if (!e.stub) {
+            entities.push(e);
+            continue;
+        }
+        const key = keyOf.get(e.id);
+        const list = members.get(key);
+        if (list.length === 1) {
+            groupId.set(e.id, e.id);
+            entities.push(e);
+        }
+        else if (list[0] === e) {
+            const id = `stub::group::${key}`;
+            for (const m of list)
+                groupId.set(m.id, id);
+            entities.push({ ...e, id, name: `${list.length} other ${key} packages`, groupMembers: list.map((m) => m.name) });
+        }
+    }
+    const merged = new Map();
+    const out = [];
+    const label = (r) => `${r.source} ${r.type} ${r.target}`;
+    for (const r of model.relations) {
+        const source = groupId.get(r.source) ?? r.source;
+        const target = groupId.get(r.target) ?? r.target;
+        if (source === r.source && target === r.target) {
+            out.push(r);
+            continue;
+        }
+        const key = `${source}\u0000${target}`;
+        const existing = merged.get(key);
+        if (existing) {
+            existing.weight = (existing.weight ?? 1) + (r.weight ?? 1);
+            existing.descriptions.push(...(r.descriptions ?? [label(r)]));
+        }
+        else {
+            const rel = { ...r, source, target, weight: r.weight ?? 1, descriptions: [...(r.descriptions ?? [label(r)])] };
+            merged.set(key, rel);
+            out.push(rel);
+        }
+    }
+    return { entities, relations: out };
+}
 /**
  * Expand one entity plus every entity within `hops` undirected hops, together
  * with the package frames that contain the kept entities.

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@yalehwang/plantuml-js",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Pure-TypeScript PlantUML class diagram renderer (MIT)",
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yaleh/plantuml-js.git"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -30,11 +34,13 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.test.json",
     "test": "vitest run",
     "demo:build": "node scripts/build-demo.mjs",
-    "prepublishOnly": "npm run typecheck && npm run build"
+    "release": "node scripts/release.mjs",
+    "prepublishOnly": "npm run typecheck && npm run build && node scripts/check-dist-clean.mjs"
   },
   "dependencies": {
     "@viz-js/viz": "^3.31.0",

package/dist/layout-metrics.d.ts

@@ -1,42 +0,0 @@
-/**
- * Layout quality metrics. Pure functions from (model, layout) to numbers, so a
- * layout strategy change can be judged by a diff in figures rather than by eye.
- *
- * Edge polylines are taken at face value: for the viz engine they are bezier
- * control points, which is a coarse but consistent approximation. Every metric
- * is deterministic — the same (model, layout) always yields the same numbers —
- * so a run can be committed as `rendered/metrics.baseline.json` and diffed
- * against a later run to prove an improvement or a regression.
- */
-import { PlantUmlModel } from './model.js';
-import { LayoutResult } from './layout.js';
-export interface LayoutMetrics {
-    /** Proper crossings between segments of two different edges. */
-    edgeCrossings: number;
-    /** Edge segments passing through the interior of an unrelated node. */
-    edgeNodeIntersections: number;
-    /** Summed polyline length of every edge, in canvas pixels. */
-    totalEdgeLength: number;
-    /** Sum of node areas divided by canvas area (0..1). */
-    areaUtilization: number;
-    /** Canvas width / height. */
-    aspectRatio: number;
-    /** Entity text lines wider than the box they are drawn in. */
-    textOverflowCount: number;
-    /** Package label tabs that overlap content or are narrower than their text. */
-    labelOverlapCount: number;
-    /**
-     * Summed length of collinear, overlapping segments from *different* edges —
-     * the orthogonal router's "parallel-line wall" is invisible to
-     * [[edgeCrossings]] (segments that merely overlap never *cross*), so this
-     * counts that hidden overlap in canvas pixels.
-     */
-    overlappingEdgeLength: number;
-    /**
-     * Incoming arrowheads stacked beyond a threshold on the same side of the
-     * same node — the "everything points at this hub" pile-up that
-     * [[edgeCrossings]] cannot see either.
-     */
-    hubArrowStack: number;
-}
-export declare function computeLayoutMetrics(model: PlantUmlModel, layout: LayoutResult): LayoutMetrics;