@yalehwang/plantuml-js 0.2.2 → 0.3.0

package/dist/render/theme.js

@@ -0,0 +1,99 @@
+/**
+ * Theme — every visual decision of the SVG renderer as a token. `svg.ts` and
+ * `legend.ts` read only from a resolved Theme, so no colour, size or dash
+ * pattern lives as a literal in drawing code. Rationale and the font decision
+ * are recorded in docs/visual-design.md.
+ */
+export const defaultTheme = {
+    font: {
+        family: 'monospace',
+        size: { title: 13, member: 12, packageLabel: 12, edgeLabel: 11, badge: 11 },
+        weight: { title: 'bold', member: 'normal', packageLabel: 'bold' },
+    },
+    color: {
+        canvas: '#ffffff',
+        stroke: '#64748b',
+        strokeStub: '#7c8ba1',
+        nodeFill: '#ffffff',
+        stubFill: '#f1f5f9',
+        textTitle: '#1e293b',
+        textMember: '#475569',
+        textPackage: '#334155',
+        edge: '#5b6a80',
+        edgeWeak: '#566479',
+        labelHalo: '#ffffff',
+        warn: '#3b0a0a',
+        accent: '#475569',
+        accentText: '#ffffff',
+        packageFills: ['#f8fafc', '#f1f5f9', '#eef2f7', '#e8eef5'],
+        packageStroke: '#94a3b8',
+        legendStroke: '#94a3b8',
+    },
+    shape: { nodeRadius: 6, packageRadius: 8, edgeCornerRadius: 6 },
+    stroke: {
+        node: 1,
+        package: 1,
+        edge: 1,
+        arrow: 1,
+        weightStep: 0.5,
+        edgeWidthMax: 4,
+        feedback: 1.5,
+        heavyWeight: 3,
+        opacity: { light: 0.8, medium: 0.9, strong: 1, feedback: 0.95 },
+        edgeNonScaling: true,
+        labelHalo: 3,
+    },
+    dash: { weak: '6,3', stub: '5,3', feedback: '10,3,2,3' },
+    arrow: { triangle: 12, chevron: 10, diamond: 14 },
+    grid: 8,
+};
+/** Merge a partial theme over the defaults (arrays replace, objects merge). */
+export function resolveTheme(overrides) {
+    return mergeDeep(defaultTheme, overrides ?? {});
+}
+function mergeDeep(base, over) {
+    if (over === undefined)
+        return base;
+    if (typeof base === 'object' && base !== null && !Array.isArray(base) &&
+        typeof over === 'object' && over !== null && !Array.isArray(over)) {
+        const out = {};
+        const b = base;
+        const o = over;
+        for (const key of Object.keys(b))
+            out[key] = mergeDeep(b[key], o[key]);
+        return out;
+    }
+    return over;
+}
+/** Every colour value of a theme (for token-membership assertions). */
+export function themeColors(theme) {
+    const out = new Set();
+    for (const v of Object.values(theme.color)) {
+        if (Array.isArray(v))
+            v.forEach((c) => out.add(c));
+        else
+            out.add(v);
+    }
+    return out;
+}
+/** `fg` at `alpha` composited over `bg` (both `#rrggbb`), as a `#rrggbb` colour. */
+export function blendOver(fg, bg, alpha) {
+    const f = parseInt(fg.slice(1), 16);
+    const b = parseInt(bg.slice(1), 16);
+    const mix = (shift) => Math.round(alpha * ((f >> shift) & 255) + (1 - alpha) * ((b >> shift) & 255));
+    return `#${((mix(16) << 16) | (mix(8) << 8) | mix(0)).toString(16).padStart(6, '0')}`;
+}
+/** WCAG relative luminance contrast ratio between two `#rrggbb` colours. */
+export function contrastRatio(a, b) {
+    const la = luminance(a);
+    const lb = luminance(b);
+    return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+function luminance(hex) {
+    const n = parseInt(hex.slice(1), 16);
+    const ch = [(n >> 16) & 255, (n >> 8) & 255, n & 255].map((v) => {
+        const s = v / 255;
+        return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * ch[0] + 0.7152 * ch[1] + 0.0722 * ch[2];
+}

package/dist/serialize.d.ts

@@ -0,0 +1,32 @@
+/**
+ * PlantUmlModel → PlantUML class-diagram text.
+ *
+ * The inverse of [[parsePlantUml]]: `toPlantUml(renderDetailed(...).model)`
+ * reproduces the diagram that was actually drawn (after view/transform/detail)
+ * as source a user can copy and paste. Pure and synchronous — the model is the
+ * only input, so the caller composes the scope by picking the model
+ * (`toPlantUml(applyView(model, {kind: 'neighborhood', entity, hops}))`); this
+ * function never chooses a range on its own.
+ *
+ * Shapes that only exist after parsing (stub/external/usageCount, aggregated
+ * edge weights, cycle markers) are rendering semantics with no PlantUML
+ * spelling; they serialize as their plain-text equivalent (stub → class,
+ * weighted edge → one edge). The parts that do have a spelling — packages
+ * (nested), entity kind/generics/alias, member rows, relation arrow/label/
+ * cardinality — round-trip back through [[parsePlantUml]] unchanged.
+ *
+ * The displayed name is always emitted quoted (`class "<<function>> halt"
+ * as n0`), so names carrying a stereotype prefix or `/` path separators survive
+ * the round trip as authored.
+ */
+import type { PlantUmlModel } from './foundation/model.js';
+/**
+ * Serialize a model to `@startuml … @enduml` class-diagram source.
+ *
+ * Emitted layout: nested `package` blocks first (each holding the entities that
+ * carry its `packageId`), then package-less entities, then every relation.
+ * Entities always use the quoted form with an explicit alias, which is the only
+ * form that carries a display name containing whitespace, `/`, or a
+ * `<<stereotype>>` prefix.
+ */
+export declare function toPlantUml(model: PlantUmlModel): string;

package/dist/serialize.js

@@ -0,0 +1,218 @@
+/**
+ * PlantUmlModel → PlantUML class-diagram text.
+ *
+ * The inverse of [[parsePlantUml]]: `toPlantUml(renderDetailed(...).model)`
+ * reproduces the diagram that was actually drawn (after view/transform/detail)
+ * as source a user can copy and paste. Pure and synchronous — the model is the
+ * only input, so the caller composes the scope by picking the model
+ * (`toPlantUml(applyView(model, {kind: 'neighborhood', entity, hops}))`); this
+ * function never chooses a range on its own.
+ *
+ * Shapes that only exist after parsing (stub/external/usageCount, aggregated
+ * edge weights, cycle markers) are rendering semantics with no PlantUML
+ * spelling; they serialize as their plain-text equivalent (stub → class,
+ * weighted edge → one edge). The parts that do have a spelling — packages
+ * (nested), entity kind/generics/alias, member rows, relation arrow/label/
+ * cardinality — round-trip back through [[parsePlantUml]] unchanged.
+ *
+ * The displayed name is always emitted quoted (`class "<<function>> halt"
+ * as n0`), so names carrying a stereotype prefix or `/` path separators survive
+ * the round trip as authored.
+ */
+/** A bare PlantUML identifier (what `as <alias>` accepts). */
+const PLANTUML_ID = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const INDENT = '  ';
+const VISIBILITY_SYMBOL = {
+    public: '+',
+    private: '-',
+    protected: '#',
+    'package-private': '~',
+};
+/**
+ * One arrow per relation type, written in canonical source→target direction.
+ * The parser's own arrow table also accepts the swapped mirror forms
+ * (`<|--`, `--o`, …); emitting the canonical form is what makes the round trip
+ * stable.
+ */
+const RELATION_ARROW = {
+    inheritance: '--|>',
+    implementation: '..|>',
+    dependency: '..>',
+    association: '-->',
+    aggregation: 'o--',
+    composition: '*--',
+};
+/**
+ * Serialize a model to `@startuml … @enduml` class-diagram source.
+ *
+ * Emitted layout: nested `package` blocks first (each holding the entities that
+ * carry its `packageId`), then package-less entities, then every relation.
+ * Entities always use the quoted form with an explicit alias, which is the only
+ * form that carries a display name containing whitespace, `/`, or a
+ * `<<stereotype>>` prefix.
+ */
+export function toPlantUml(model) {
+    const entities = new AliasBook('entity');
+    const packages = new AliasBook('package');
+    const lines = ['@startuml'];
+    const nodes = packageNodes(model);
+    const emitted = new Set();
+    for (const node of nodes.roots)
+        emitPackage(node, 0, lines, entities, packages, emitted);
+    // Defensive: a parentId cycle leaves nodes unreachable from any root; emit
+    // each remaining package as a root rather than silently dropping it.
+    for (const node of nodes.all) {
+        if (!emitted.has(node.pkg.id))
+            emitPackage(node, 0, lines, entities, packages, emitted);
+    }
+    for (const entity of nodes.topLevel) {
+        lines.push(...entityLines(entity, 0, entities));
+    }
+    for (const relation of model.relations) {
+        lines.push(relationLine(relation, entities));
+    }
+    lines.push('@enduml');
+    return lines.join('\n');
+}
+/**
+ * Index packages into a tree, attaching each entity to the innermost package it
+ * names. An entity whose `packageId` names no declared package is emitted at
+ * the top level instead of being dropped.
+ */
+function packageNodes(model) {
+    const byId = new Map();
+    const all = [];
+    for (const pkg of model.packages) {
+        // A duplicated id keeps its first package; the parser never produces one.
+        if (byId.has(pkg.id))
+            continue;
+        const node = { pkg, children: [], entities: [] };
+        byId.set(pkg.id, node);
+        all.push(node);
+    }
+    const roots = [];
+    for (const node of all) {
+        const parentId = node.pkg.parentId;
+        const parent = parentId === undefined ? undefined : byId.get(parentId);
+        if (parent !== undefined && parent !== node)
+            parent.children.push(node);
+        else
+            roots.push(node);
+    }
+    const topLevel = [];
+    for (const entity of model.entities) {
+        const owner = entity.packageId === undefined ? undefined : byId.get(entity.packageId);
+        if (owner !== undefined)
+            owner.entities.push(entity);
+        else
+            topLevel.push(entity);
+    }
+    return { roots, all, topLevel };
+}
+function emitPackage(node, depth, lines, entities, packages, emitted) {
+    if (emitted.has(node.pkg.id))
+        return;
+    emitted.add(node.pkg.id);
+    const indent = INDENT.repeat(depth);
+    const alias = packages.alias(node.pkg.id, node.pkg.name);
+    lines.push(`${indent}package ${quoteName(node.pkg.name)} as ${alias} {`);
+    for (const entity of node.entities) {
+        lines.push(...entityLines(entity, depth + 1, entities));
+    }
+    for (const child of node.children) {
+        emitPackage(child, depth + 1, lines, entities, packages, emitted);
+    }
+    lines.push(`${indent}}`);
+}
+function entityKeyword(entity) {
+    return entity.kind === 'abstract' ? 'abstract class' : entity.kind;
+}
+function entityLines(entity, depth, aliases) {
+    const indent = INDENT.repeat(depth);
+    const alias = aliases.alias(entity.id, entity.name);
+    const head = `${entityKeyword(entity)} ${quoteName(entity.name)}${genericSuffix(entity)} as ${alias}`;
+    if (entity.members.length === 0)
+        return [`${indent}${head}`];
+    const lines = [`${indent}${head} {`];
+    for (const member of entity.members) {
+        lines.push(`${indent}${INDENT}${memberLine(member)}`);
+    }
+    lines.push(`${indent}}`);
+    return lines;
+}
+function genericSuffix(entity) {
+    const generics = entity.generics ?? [];
+    return generics.length === 0 ? '' : `~${generics.join(',')}~`;
+}
+/**
+ * One member row. The authored `raw` text is authoritative (it carries the
+ * visibility symbol and the exact signature), except for synthesized rows —
+ * the detail pipeline's `… +N more (M members)` truncation marker has no
+ * visibility symbol, so it gets one prefixed to stay parseable as a member
+ * row while keeping the marker text verbatim.
+ */
+function memberLine(member) {
+    const raw = (member.raw ?? '').trim();
+    const symbol = VISIBILITY_SYMBOL[member.visibility] ?? '+';
+    if (raw === '')
+        return symbol;
+    if (/^[+\-#~]/.test(raw))
+        return raw;
+    return `${symbol} ${raw}`;
+}
+function relationLine(relation, aliases) {
+    const source = aliases.alias(relation.source, relation.source);
+    const target = aliases.alias(relation.target, relation.target);
+    const parts = [source];
+    if (relation.sourceCardinality !== undefined)
+        parts.push(quoteName(relation.sourceCardinality));
+    parts.push(RELATION_ARROW[relation.type] ?? '-->');
+    if (relation.targetCardinality !== undefined)
+        parts.push(quoteName(relation.targetCardinality));
+    parts.push(target);
+    let line = parts.join(' ');
+    if (relation.label !== undefined && relation.label !== '') {
+        line += ` : ${relation.label.replace(/[\r\n]+/g, ' ')}`;
+    }
+    return line;
+}
+/** Quote a display name; a `"` inside a PlantUML name is written as `'`. */
+function quoteName(name) {
+    const safe = name.replace(/[\r\n\t]+/g, ' ').replace(/"/g, "'");
+    return `"${safe}"`;
+}
+/**
+ * Deterministic, collision-free alias assignment, in emission order. A
+ * plant-legal id is kept verbatim (so a parsed model round-trips its ids); an
+ * id PlantUML cannot spell (view-internal ids such as `ov::src`, `stub::x`)
+ * falls back to an identifier derived from the display name.
+ */
+class AliasBook {
+    used = new Set();
+    byId = new Map();
+    fallback;
+    constructor(fallback) {
+        this.fallback = fallback;
+    }
+    alias(id, name) {
+        const existing = this.byId.get(id);
+        if (existing !== undefined)
+            return existing;
+        const base = PLANTUML_ID.test(id) ? id : identifierFrom(name, this.fallback);
+        let alias = base;
+        let suffix = 2;
+        while (this.used.has(alias))
+            alias = `${base}_${suffix++}`;
+        this.used.add(alias);
+        this.byId.set(id, alias);
+        return alias;
+    }
+}
+/** Derive a bare identifier from a display name (`Src Layer` → `Src_Layer`). */
+function identifierFrom(name, fallback) {
+    const cleaned = name
+        .replace(/[^A-Za-z0-9_]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+    const base = cleaned === '' ? fallback : cleaned;
+    return /^[A-Za-z_]/.test(base) ? base : `_${base}`;
+}

package/dist/transform.d.ts

@@ -9,7 +9,7 @@
  * input and produces the same output for the same input, so a transformed
  * render stays byte-for-byte reproducible.
  */
-import { PlantUmlModel } from './model.js';
+import { PlantUmlModel } from './foundation/model.js';
 /** Options driving the model-transform pipeline. */
 export interface TransformOptions {
     /**
@@ -25,6 +25,12 @@ export interface TransformOptions {
      * hub summarization. Default undefined.
      */
     hubThreshold?: number;
+    /**
+     * `'aggregate'` folds all relations between two packages into one
+     * box-to-box weighted corridor edge; `'raw'` keeps every edge. Default:
+     * `'aggregate'` above [[INTER_PACKAGE_AGGREGATE_ENTITY_THRESHOLD]] entities.
+     */
+    interPackage?: 'aggregate' | 'raw';
     /** Detect cycles and mark one edge per cycle as a `feedback` arc. Default false. */
     cycles?: boolean;
 }
@@ -44,19 +50,59 @@ export type ViewSpec = {
 } | {
     kind: 'package';
     id: string;
+    stubGroupThreshold?: number;
 } | {
     kind: 'neighborhood';
     entity: string;
     hops: number;
 };
+/** Entity count above which inter-package edges aggregate into corridors by default. */
+export declare const INTER_PACKAGE_AGGREGATE_ENTITY_THRESHOLD = 150;
+/** Stub count above which a single-package view groups stubs by name prefix. */
+export declare const DEFAULT_STUB_GROUP_THRESHOLD = 8;
 /**
  * Run the transform pipeline over a model. Order matters: aggregation first
  * (so transitive reduction sees one edge per pair), then reduction, then hub
  * summarization, then cycle marking on the final edge set.
  */
 export declare function transformModel(model: PlantUmlModel, options?: TransformOptions): PlantUmlModel;
+/** [[transformModel]] plus the number of edges the transitive reduction hid. */
+export declare function transformModelDetailed(model: PlantUmlModel, options?: TransformOptions): {
+    model: PlantUmlModel;
+    hiddenTransitive: number;
+};
+/** Edge count ÷ node count above which `edgeReduction: 'auto'` reduces a pure dependency graph. */
+export declare 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 declare function shouldAutoReduce(model: PlantUmlModel): boolean;
+/** Incoming edges at which an external type's edges collapse into a count badge. */
+export declare const EXTERNAL_SUMMARY_MIN_IN_EDGES = 3;
+/** Id of the synthetic package that gathers implicit/external types. */
+export declare 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 declare function summarizeExternals(model: PlantUmlModel, minEdges: number): PlantUmlModel;
+/** Gather top-level external entities into one synthetic External package. */
+export declare function groupExternals(model: PlantUmlModel): PlantUmlModel;
 /** Merge relations sharing (source, target) into one edge with `weight`. */
 export declare function aggregateRelations(model: PlantUmlModel): PlantUmlModel;
+/**
+ * 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 declare function aggregateInterPackage(model: PlantUmlModel): PlantUmlModel;
 /**
  * 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
@@ -90,3 +136,11 @@ export declare function applyView(model: PlantUmlModel, view?: ViewSpec): PlantU
  * edges are dropped (they do not cross the collapsed boundary).
  */
 export declare function groupByPathPrefix(model: PlantUmlModel, depth: number): PlantUmlModel;
+/**
+ * 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 declare function groupStubs(model: Pick<PlantUmlModel, 'entities' | 'relations'>, threshold: number): Pick<PlantUmlModel, 'entities' | 'relations'>;