mellos-mapping 0.18.0 → 0.20.0

package/lib/domain/types.js

@@ -0,0 +1,122 @@
+/**
+ * Layer 0 — domain model of a Mellos Map.
+ *
+ * A Mellos Map is a layered dependency map of a system under construction:
+ * horizontal layer bands ordered by rank (rank 0 = bottom = most primitive),
+ * nodes living inside exactly one band, and dependency edges that may only
+ * point STRICTLY DOWNWARD across bands.
+ *
+ * Structural invariants owned by this layer (and only these — the map is a
+ * ledger, not a judge; it records work honestly and never polices workflow):
+ *   I1. Layer ids are unique; layer ranks are unique (bands are totally ordered).
+ *   I2. Every node belongs to exactly one existing layer.
+ *   I3. Node ids are unique.
+ *   I4. An edge `from -> to` means "from USES to" and requires
+ *       rank(layer(from)) > rank(layer(to)).
+ *       Corollary: the graph is acyclic by construction — every edge strictly
+ *       decreases rank, so no cycle detection is ever needed.
+ *       Same-layer edges are rejected on purpose: if A needs a sibling B,
+ *       either B is really a lower-layer concept or A and B are one node.
+ *   I5. Node status is one of the closed vocabulary in NODE_STATUSES.
+ *   I6. Group ids are unique; every group lives in an existing layer.
+ *   I7. A node's group, when set, exists and lives in the node's own layer —
+ *       a group is band-local cohesion (a labeled subsystem the far zoom can
+ *       render); structure ACROSS bands is what layers and edges express.
+ *   I8. Lane ids are unique. A lane is a named vertical column CROSSING all
+ *       bands (a sequence participant, a swim lane); lane declaration order
+ *       is left-to-right render order.
+ *   I9. A node's lane, when set, exists.
+ *
+ * The map kind (dev | architecture | dataflow | behavior-tree | sequence) is
+ * presentation intent, not structure: every kind shares the same invariants,
+ * and the renderer alone decides what the kind changes (legend, neutral
+ * status skins, lane emphasis).
+ *
+ * Everything here is immutable data plus pure types. No I/O, no clock, no
+ * process state.
+ */
+export const ok = (value) => ({ ok: true, value });
+export const err = (error) => ({ ok: false, error });
+/** The shared slug grammar for every id in the system (nodes, layers, groups, lanes, kinds, store pages). */
+export const ID_RULE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+export const ID_RULE_TEXT = 'lowercase letters, digits and dashes, starting with a letter or digit, 1-64 chars';
+export function makeNodeId(raw) {
+    return ID_RULE.test(raw) ? ok(raw) : err({ kind: 'invalid-id', raw, rule: ID_RULE_TEXT });
+}
+export function makeLayerId(raw) {
+    return ID_RULE.test(raw) ? ok(raw) : err({ kind: 'invalid-id', raw, rule: ID_RULE_TEXT });
+}
+export function makeGroupId(raw) {
+    return ID_RULE.test(raw) ? ok(raw) : err({ kind: 'invalid-id', raw, rule: ID_RULE_TEXT });
+}
+export function makeLaneId(raw) {
+    return ID_RULE.test(raw) ? ok(raw) : err({ kind: 'invalid-id', raw, rule: ID_RULE_TEXT });
+}
+export function makeNodeKind(raw) {
+    return ID_RULE.test(raw) ? ok(raw) : err({ kind: 'invalid-id', raw, rule: ID_RULE_TEXT });
+}
+export function makeSubmapRef(raw) {
+    return ID_RULE.test(raw) ? ok(raw) : err({ kind: 'invalid-id', raw, rule: ID_RULE_TEXT });
+}
+/**
+ * Closed vocabulary of map kinds — the diagram's presentation intent.
+ * 'dev' (the default) is the progress ledger; the rest are documentation
+ * diagrams rendered with neutral skins. Structure is identical for all.
+ */
+export const MAP_KINDS = ['dev', 'architecture', 'dataflow', 'behavior-tree', 'sequence'];
+export function makeMapKind(raw) {
+    return MAP_KINDS.includes(raw) ? ok(raw) : err({ kind: 'invalid-map-kind', raw });
+}
+/** Closed status vocabulary. Transitions are NOT policed — see module header. */
+export const NODE_STATUSES = ['planned', 'in-progress', 'done', 'regressed'];
+export function makeNodeStatus(raw) {
+    return NODE_STATUSES.includes(raw)
+        ? ok(raw)
+        : err({ kind: 'invalid-status', raw });
+}
+export const EMPTY_MAP = { layers: [], groups: [], lanes: [], nodes: [], edges: [] };
+/** Human-readable rendering of a MapError, for tool results and logs. */
+export function describeMapError(e) {
+    switch (e.kind) {
+        case 'invalid-id':
+            return `invalid id "${e.raw}" (rule: ${e.rule})`;
+        case 'invalid-status':
+            return `invalid status "${e.raw}" (expected: ${NODE_STATUSES.join(' | ')})`;
+        case 'duplicate-layer':
+            return `layer "${e.id}" already exists`;
+        case 'duplicate-rank':
+            return `rank ${e.rank} is already taken by layer "${e.existing}"`;
+        case 'duplicate-node':
+            return `node "${e.id}" already exists`;
+        case 'unknown-layer':
+            return `layer "${e.id}" does not exist`;
+        case 'unknown-node':
+            return `node "${e.id}" does not exist`;
+        case 'duplicate-edge':
+            return `edge ${e.from} -> ${e.to} already exists`;
+        case 'unknown-edge':
+            return `edge ${e.from} -> ${e.to} does not exist`;
+        case 'self-edge':
+            return `node "${e.id}" cannot depend on itself`;
+        case 'duplicate-group':
+            return `group "${e.id}" already exists`;
+        case 'unknown-group':
+            return `group "${e.id}" does not exist`;
+        case 'invalid-map-kind':
+            return `invalid map kind "${e.raw}" (expected: ${MAP_KINDS.join(' | ')})`;
+        case 'duplicate-lane':
+            return `lane "${e.id}" already exists`;
+        case 'unknown-lane':
+            return `lane "${e.id}" does not exist`;
+        case 'group-layer-mismatch':
+            return (`node "${e.node}" (layer ${e.nodeLayer}) cannot join group "${e.group}" (layer ${e.groupLayer}); ` +
+                `groups cluster nodes within one band`);
+        case 'layer-not-empty':
+            return `layer "${e.id}" still holds node "${e.occupant}"; move or remove its nodes first`;
+        case 'layer-holds-group':
+            return `layer "${e.id}" still holds group "${e.occupant}"; remove its groups first`;
+        case 'edge-not-downward':
+            return (`edge ${e.from} (rank ${e.fromRank}) -> ${e.to} (rank ${e.toRank}) is not strictly downward; ` +
+                `dependencies may only point to a lower layer`);
+    }
+}

package/lib/render/render.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Layer 4 (presentation) — pure rendering of a MellosMap to terminal lines.
+ *
+ * Shared by the MCP `mmap_view` tool (monochrome) and the split-pane watcher
+ * (colored, animated). Pure function of (map, options): no I/O, no clock —
+ * animation is driven by the caller passing a spinner frame index.
+ *
+ * Visual language — a dark circuit board:
+ *   rank 0 renders at the BOTTOM of the picture ("primitives are the
+ *   ground"). Wiring and band bars are FAINT; the glowing things are the
+ *   nodes. Junctions where a wire enters a box inherit the box's color,
+ *   like lit pins. Dependency lines only ever travel downward.
+ *
+ *   planned      dashed dim rounded box, '·'  — a ghost: designed, not built
+ *   in-progress  amber rounded box, spinner   — where attention currently is
+ *   done         heavy green box, '■'         — built and verified
+ *   regressed    heavy red box, '✗'           — was done, foundation cracked
+ *
+ * Routing preference, in order:
+ *   1. STRAIGHT — an adjacent-band edge whose box borders share a free
+ *      column is one vertical line, no corners.
+ *   2. DOGLEG — descend, run horizontally on a track row in the gap above
+ *      the target band, descend. Tracks are PACKED: segments that do not
+ *      overlap share a row, keeping bands close together.
+ *   3. THREAD — a skip-level edge descends through the nearest column that
+ *      is free of boxes in every intermediate band (threading the needle
+ *      between boxes); only if no such column exists does it fall back to a
+ *      private column on the right margin.
+ * Crossings merge into proper junction characters via a direction-bitmask
+ * union instead of any routing cleverness.
+ *
+ * Zoom — terminals cannot scale glyphs, so zooming out first COMPRESSES the
+ * geometry (gaps, breathing rows, padding shrink; labels truncate toward a
+ * scale-proportional budget) while boxes stay boxes. Only when a further
+ * step would leave labels too short to mean anything does the picture switch
+ * mode — to a borderless glyph constellation whose band bars carry
+ * done/total counts. Zooming in past 100% unfolds evidence and design notes
+ * inside the boxes; a second step widens the boxes and unfolds the notes
+ * further. The ladder, one wheel tick per step:
+ *   +2   detail+       wider boxes, design notes unfold almost fully
+ *   +1   detail        evidence + design notes unfold inside boxes
+ *    0   100%          the standard working view (default, unchanged)
+ *   -1   85%           labels truncated to 85%, geometry still roomy
+ *   -2   70%           padding and breathing rows collapse
+ *   -3   55%           tightest meaningful boxes; band bars gain done/total
+ *   -4   overview      MODE SWITCH: borderless status glyphs, pure topology
+ * The same layout/routing machinery runs at every step; only the per-node
+ * box spec (size, border, content) and the whitespace geometry change.
+ */
+import type { MellosMap } from '../domain/types.js';
+import { type ZoomStep } from '../semantics/semantics.js';
+export { type ZoomStep, ZOOM_DEFAULT, ZOOM_MAX, ZOOM_MIN, clampZoom, isNeutralKind, zoomLabel } from '../semantics/semantics.js';
+export interface RenderOptions {
+    /** Emit ANSI color codes. */
+    readonly color: boolean;
+    /** Use box-drawing characters; false falls back to pure ASCII. */
+    readonly unicode: boolean;
+    /** Spinner frame index for in-progress nodes; caller advances it over time. */
+    readonly spinnerFrame: number;
+    /**
+     * Node id to spotlight: its box border and every wire touching it render
+     * bright instead of faint. Color mode only — monochrome output ignores it.
+     */
+    readonly focus?: string | undefined;
+    /** Position on the zoom ladder; omitted means ZOOM_DEFAULT (100%). */
+    readonly zoom?: ZoomStep | undefined;
+}
+/** A window over the rendered picture, in cell coordinates (0-based). */
+export interface Viewport {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** Terminal column width of a string (CJK chars occupy two columns). */
+export declare function displayWidth(text: string): number;
+/** Truncate to a display width, ANSI-free input, appending … when cut. */
+export declare function fitWidth(s: string, width: number): string;
+/** Hard word-wrap by display width (CJK-aware, splits anywhere). */
+export declare function wrapWidth(s: string, width: number): string[];
+/** Glyph for a node kind, or undefined for unknown kinds. Shared with the watcher's panel. */
+export declare function kindGlyph(kind: string, unicode: boolean): string | undefined;
+/** Render the whole map as terminal lines. */
+export declare function renderMap(map: MellosMap, opts: RenderOptions): string[];
+/** Where a node's box sits on the full (unwindowed) picture, for hit testing. */
+export interface BoxHit {
+    readonly id: string;
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+export interface WindowedRender {
+    readonly lines: string[];
+    /** Full extent of the picture, for viewport clamping. */
+    readonly contentWidth: number;
+    readonly contentHeight: number;
+    /** Node hit regions in full-picture coordinates, for mouse interaction. */
+    readonly hits: readonly BoxHit[];
+}
+/** Render only the given viewport of the map, plus the full content extent. */
+export declare function renderMapWindow(map: MellosMap, opts: RenderOptions, viewport: Viewport): WindowedRender;