agentic-mermaid 0.1.1 → 0.2.0

package/src/journey/types.ts

@@ -1,144 +0,0 @@
-// ============================================================================
-// Journey diagram types
-//
-// Models Mermaid user journey diagrams in parsed and positioned form.
-// Journey diagrams group scored tasks into optional sections with per-task actors.
-// ============================================================================
-
-import type { PositionedDiagram } from '../types.ts'
-
-/** Parsed journey diagram — logical structure from Mermaid text */
-export interface JourneyDiagram {
-  /** Optional diagram title */
-  title?: string
-  /** Optional accessibility title from Mermaid accTitle */
-  accessibilityTitle?: string
-  /** Optional accessibility description from Mermaid accDescr */
-  accessibilityDescription?: string
-  /** Ordered sections in input order */
-  sections: JourneySection[]
-}
-
-export interface JourneySection {
-  id: string
-  /** Optional section label. Undefined means an implicit / ungrouped section. */
-  label?: string
-  tasks: JourneyTask[]
-}
-
-export interface JourneyTask {
-  id: string
-  text: string
-  /** Satisfaction score on a 1..5 scale */
-  score: number
-  /** Optional actors attached to the task */
-  actors: string[]
-}
-
-// ============================================================================
-// Positioned journey diagram — ready for SVG rendering
-// ============================================================================
-
-export interface PositionedJourneyDiagram extends PositionedDiagram {
-  width: number
-  height: number
-  title?: PositionedJourneyTitle
-  accessibilityTitle?: string
-  accessibilityDescription?: string
-  actors: PositionedJourneyActor[]
-  scoreGuide: PositionedJourneyScoreGuide
-  sections: PositionedJourneySection[]
-}
-
-export interface PositionedJourneyTitle {
-  text: string
-  x: number
-  y: number
-}
-
-export interface PositionedJourneySection {
-  id: string
-  label?: string
-  x: number
-  y: number
-  width: number
-  height: number
-  labelX: number
-  labelY: number
-  /** Whether to render a section span for this section. */
-  framed: boolean
-  /** Height of the section span. 0 when there is no visible span. */
-  headerHeight: number
-  tasks: PositionedJourneyTask[]
-}
-
-export interface PositionedJourneyActor {
-  label: string
-  x: number
-  y: number
-  colorIndex: number
-}
-
-export interface PositionedJourneyScoreGuide {
-  x: number
-  y: number
-  width: number
-  height: number
-  ticks: PositionedJourneyScoreTick[]
-  baseline: PositionedJourneyBaseline
-}
-
-export interface PositionedJourneyScoreTick {
-  score: number
-  x1: number
-  x2: number
-  y: number
-  labelX: number
-  labelY: number
-}
-
-export interface PositionedJourneyBaseline {
-  x1: number
-  y1: number
-  x2: number
-  y2: number
-}
-
-export interface PositionedJourneyTask {
-  id: string
-  sectionId: string
-  text: string
-  score: number
-  actors: string[]
-  x: number
-  y: number
-  width: number
-  height: number
-  textX: number
-  textY: number
-  centerX: number
-  track: PositionedJourneyTrack
-  marker: PositionedJourneyScoreMarker
-  actorDots: PositionedJourneyActorDot[]
-}
-
-export interface PositionedJourneyTrack {
-  x: number
-  y1: number
-  y2: number
-}
-
-export interface PositionedJourneyScoreMarker {
-  cx: number
-  cy: number
-  r: number
-  score: number
-}
-
-export interface PositionedJourneyActorDot {
-  label: string
-  colorIndex: number
-  x: number
-  y: number
-  r: number
-}

package/src/layout/geometry.ts

@@ -1,182 +0,0 @@
-// Shared geometry kernel for the layout pipeline
-// (docs/design/system/layout-pass-pipeline.md §4 step 2 / OQ-D1).
-//
-// Leaf module: depends only on core types, so the relocated post-ELK passes in
-// ./passes/* can import these helpers WITHOUT importing layout-engine.ts — which
-// is what keeps the dependency one-directional (layout-engine -> passes -> geometry)
-// and free of import cycles.
-import type { Direction, MermaidSubgraph, Point, PositionedGroup, PositionedNode } from '../types.ts'
-
-export const DEFAULTS = {
-  font: 'Inter',
-  padding: 40,
-  nodeSpacing: 28,
-  layerSpacing: 48,
-  mergeEdges: true,
-  thoroughness: 3,
-} as const
-
-export function flattenGroupBounds(groups: PositionedGroup[]): Array<{ x: number; y: number; right: number; bottom: number }> {
-  const bounds: Array<{ x: number; y: number; right: number; bottom: number }> = []
-  for (const g of groups) {
-    bounds.push({ x: g.x, y: g.y, right: g.x + g.width, bottom: g.y + g.height })
-    bounds.push(...flattenGroupBounds(g.children))
-  }
-  return bounds
-}
-
-export function polylineLength(points: Point[]): number {
-  let totalLength = 0
-  for (let i = 1; i < points.length; i++) {
-    const dx = points[i]!.x - points[i - 1]!.x
-    const dy = points[i]!.y - points[i - 1]!.y
-    totalLength += Math.sqrt(dx * dx + dy * dy)
-  }
-  return totalLength
-}
-
-export function pointAtPathDistance(points: Point[], distance: number): { point: Point; segmentIndex: number; pathDistance: number } {
-  if (points.length === 0) return { point: { x: 0, y: 0 }, segmentIndex: 0, pathDistance: 0 }
-  if (points.length === 1) return { point: points[0]!, segmentIndex: 0, pathDistance: 0 }
-
-  const target = Math.max(0, Math.min(polylineLength(points), distance))
-  let remaining = target
-  let walked = 0
-  for (let i = 1; i < points.length; i++) {
-    const dx = points[i]!.x - points[i - 1]!.x
-    const dy = points[i]!.y - points[i - 1]!.y
-    const segLen = Math.sqrt(dx * dx + dy * dy)
-    if (segLen === 0) continue
-    if (remaining <= segLen) {
-      const t = remaining / segLen
-      return {
-        point: {
-          x: points[i - 1]!.x + t * dx,
-          y: points[i - 1]!.y + t * dy,
-        },
-        segmentIndex: i,
-        pathDistance: walked + remaining,
-      }
-    }
-    remaining -= segLen
-    walked += segLen
-  }
-
-  return { point: points[points.length - 1]!, segmentIndex: points.length - 1, pathDistance: walked }
-}
-
-/**
- * Calculate the midpoint along a polyline path.
- * Walks the path to find the point at half the total length.
- */
-export function calculatePathMidpoint(points: Point[]): Point {
-  return pointAtPathDistance(points, polylineLength(points) / 2).point
-}
-
-export function layoutFlow(direction: Direction): {
-  isHorizontal: boolean
-  main: 'x' | 'y'
-  cross: 'x' | 'y'
-  sign: 1 | -1
-  sourceSide: 'N' | 'E' | 'S' | 'W'
-  targetSide: 'N' | 'E' | 'S' | 'W'
-} {
-  if (direction === 'LR') return { isHorizontal: true, main: 'x', cross: 'y', sign: 1, sourceSide: 'E', targetSide: 'W' }
-  if (direction === 'RL') return { isHorizontal: true, main: 'x', cross: 'y', sign: -1, sourceSide: 'W', targetSide: 'E' }
-  if (direction === 'BT') return { isHorizontal: false, main: 'y', cross: 'x', sign: -1, sourceSide: 'N', targetSide: 'S' }
-  return { isHorizontal: false, main: 'y', cross: 'x', sign: 1, sourceSide: 'S', targetSide: 'N' }
-}
-
-export function positionedNodeCenter(node: PositionedNode): Point {
-  return { x: node.x + node.width / 2, y: node.y + node.height / 2 }
-}
-
-export function nodeMainStart(node: PositionedNode, direction: Direction): number {
-  const f = layoutFlow(direction)
-  return node[f.main]
-}
-
-export function nodeCrossStart(node: PositionedNode, direction: Direction): number {
-  const f = layoutFlow(direction)
-  return node[f.cross]
-}
-
-export function nodeCrossSize(node: PositionedNode, direction: Direction): number {
-  return layoutFlow(direction).isHorizontal ? node.height : node.width
-}
-
-export function nodeMainSize(node: PositionedNode, direction: Direction): number {
-  return layoutFlow(direction).isHorizontal ? node.width : node.height
-}
-
-export function nodeCrossCenter(node: PositionedNode, direction: Direction): number {
-  return nodeCrossStart(node, direction) + nodeCrossSize(node, direction) / 2
-}
-
-export function nodeMainCenter(node: PositionedNode, direction: Direction): number {
-  return nodeMainStart(node, direction) + nodeMainSize(node, direction) / 2
-}
-
-export function rectsOverlap(a: { x: number; y: number; width: number; height: number }, b: { x: number; y: number; width: number; height: number }, pad = 0): boolean {
-  return a.x < b.x + b.width + pad && a.x + a.width + pad > b.x && a.y < b.y + b.height + pad && a.y + a.height + pad > b.y
-}
-
-/** Margin routing info for cross-hierarchy edges */
-export interface MarginInfo {
-  leftX: number
-  rightX: number
-}
-
-/** Find a subgraph by ID in a nested structure */
-export function findSubgraph(subgraphs: MermaidSubgraph[], id: string): MermaidSubgraph | undefined {
-  for (const sg of subgraphs) {
-    if (sg.id === id) return sg
-    const found = findSubgraph(sg.children, id)
-    if (found) return found
-  }
-  return undefined
-}
-
-type LayoutDebugEnv = {
-  APL_DEBUG?: string
-  APL_NO_CENTER?: string
-  APL_NO_FACET?: string
-  APL_NO_SVERTEX?: string
-  // Disable the alignLabeledSourcePort pass (a labelled single-edge source is
-  // left exiting off its mid-port, as it was before that pass). For before/after
-  // evidence and bisecting, matching the other APL_NO_* pass switches.
-  APL_NO_LABELED_SOURCE_PORT?: string
-  // Label-decoupling (opt-in, validated): when set, edge labels are NOT handed
-  // to ELK, so a label cannot displace its target node off the edge's port lane
-  // (the sym A->B mid-port fix). Default is off — ELK still reserves a label
-  // cell — until the bent-duplicate-label route-contract regression is resolved.
-  // See the layout-engine label-injection sites and the decoupling write-up.
-  APL_DECOUPLE_LABELS?: string
-  // DISABLE co-ranking of a mixed-label fan-in (default ON). When a fan-in hub
-  // has sibling edges where some are labeled and some are not, the labeled edge
-  // reserves an extra label-dummy rank so its source lands one rank EARLIER
-  // than the unlabeled sibling's source — an asymmetric fan-in the centering
-  // can't square up. By default each unlabeled sibling edge gets a layout-only
-  // balancing label (a single space, sized to the widest labeled sibling) so
-  // ELK reserves the SAME dummy rank and every source co-ranks;
-  // centerPeerBarycenters then drops its labeled-edge exclusion for that
-  // now-co-ranked hub so it can center on the squared-up peers, and the spokes
-  // converge as symmetric doglegs (marked bundle-owned, so the bend is treated
-  // as justified — see route-contracts findRouteHitches and the layout-rubric
-  // justified-bend exemption). The balancing label is never rendered — readback
-  // keys off the Mermaid edge's own label, which stays undefined. Set this to
-  // restore the pre-co-rank base geometry (so before/after stays bisectable);
-  // matches the other APL_NO_* pass switches. See the layout-engine
-  // label-injection sites and centerPeerBarycenters.
-  APL_NO_CORANK_FANIN?: string
-}
-
-export function layoutEnvFlag(name: keyof LayoutDebugEnv): boolean {
-  const env = (globalThis as typeof globalThis & { process?: { env?: LayoutDebugEnv } }).process?.env
-  const value = env?.[name]
-  return value === '1' || value === 'true'
-}
-
-export function layoutDebug(...args: unknown[]): void {
-  if (layoutEnvFlag('APL_DEBUG')) console.error(...args)
-}

package/src/layout/pass.ts

@@ -1,142 +0,0 @@
-// The LayoutPass abstraction — see docs/design/system/layout-pass-pipeline.md.
-//
-// Generic over the concrete context so this module has NO dependency on the
-// layout engine (and therefore cannot create an import cycle). The concrete
-// `LayoutPassContext` and the `LAYOUT_PIPELINE` manifest live in
-// `src/layout-engine.ts`, where the per-pass functions are in scope.
-//
-// In production `runPipeline` is a thin dispatcher: each pass mutates the shared
-// context in place, byte-identical to the former hand-wired sequence. The
-// cross-pass invariants (§3) are enforced only when `checkInvariants` is set, so
-// they ride debug/CI and never the production render path.
-
-export type PassEffect = 'extract' | 'positions' | 'dimensions' | 'edges' | 'translate'
-export type Determinism = 'pure-order' | 'fixed-point' | 'in-place'
-export type RubricMetric = 'hard' | 'crossings' | 'bends' | 'straight' | 'portRate' | 'symErr'
-
-/** Per-metric direction/budget for the ratchet (§3.3, resolves OQ-B1). */
-export type MetricBudget = 'improve-only' | { worsenBy: number }
-
-/** The minimal shape `runPipeline` needs to enforce the freeze invariant (§3.2). */
-export interface PassContextBase {
-  frozen: boolean
-  nodes: ReadonlyArray<{ x: number; y: number; width: number; height: number }>
-  edges?: ReadonlyArray<{
-    points?: ReadonlyArray<{ x: number; y: number }>
-    routeCertificate?: unknown
-  }>
-}
-
-export interface LayoutPass<C extends PassContextBase> {
-  /** Stable id; the route-contracts §8 pipeline line is generated from `doc`. */
-  id: string
-  doc: string
-  /** Partial-order deps (ids that must run earlier). Checked in debug mode. */
-  after: string[]
-  /** Geometry channels this pass writes — drives the freeze invariant (§3.2). */
-  mutates: PassEffect[]
-  /** Per-metric direction/budget (the ratchet, §3.3); enforced only in debug/CI. */
-  mayChangeMetrics?: Partial<Record<RubricMetric, MetricBudget>>
-  determinism: Determinism
-  /** After this pass, node geometry is frozen (the route-contract pass). */
-  freezesNodes?: boolean
-  /** When present and false, the pass is skipped (e.g. bundling without mergeEdges). */
-  enabled?: (ctx: C) => boolean
-  run: (ctx: C) => void
-}
-
-export interface RunOptions<C extends PassContextBase> {
-  /** Debug/CI only: enforce ordering + freeze invariants (O(n) per mover). */
-  checkInvariants?: boolean
-  /** Debug/CI only: called after each pass that actually ran (e.g. to measure the ratchet). */
-  onAfterPass?: (pass: LayoutPass<C>, ctx: C) => void
-}
-
-/** Post-freeze a pass may only translate the whole graph or rewrite edges (§3.2). */
-const freezeSafe = (mutates: PassEffect[]): boolean =>
-  mutates.every(m => m === 'translate' || m === 'edges')
-
-const routeKey = (edge: { points?: ReadonlyArray<{ x: number; y: number }> }): string =>
-  edge.points?.map(p => `${p.x},${p.y}`).join('|') ?? ''
-
-/**
- * Run `passes` over `ctx` in array order. The array IS the execution path; with
- * `checkInvariants` the runner also enforces the §3 contract (ordering + freeze).
- */
-export function runPipeline<C extends PassContextBase>(
-  ctx: C,
-  passes: ReadonlyArray<LayoutPass<C>>,
-  opts: RunOptions<C> = {},
-): void {
-  const ran = new Set<string>()
-  for (const pass of passes) {
-    if (pass.enabled && !pass.enabled(ctx)) {
-      ran.add(pass.id)
-      continue
-    }
-
-    if (opts.checkInvariants) {
-      for (const dep of pass.after) {
-        if (!ran.has(dep)) {
-          throw new Error(`LayoutPass ordering: '${pass.id}' must run after '${dep}', which has not run`)
-        }
-      }
-    }
-
-    // Freeze invariant (§3.2): after the route-contract pass only a whole-graph
-    // translation (or an edge rewrite) may run; a positions/dimensions move is illegal.
-    const guardFreeze = opts.checkInvariants === true && ctx.frozen && !freezeSafe(pass.mutates)
-    const before = guardFreeze
-      ? ctx.nodes.map(n => ({ x: n.x, y: n.y, width: n.width, height: n.height }))
-      : undefined
-    const beforeEdges = opts.checkInvariants === true && ctx.frozen && pass.mutates.includes('edges') && ctx.edges
-      ? ctx.edges.map(routeKey)
-      : undefined
-
-    pass.run(ctx)
-
-    if (before) {
-      for (let i = 0; i < before.length; i++) {
-        const a = before[i]
-        const b = ctx.nodes[i]
-        if (!a || !b) continue
-        if (a.x !== b.x || a.y !== b.y || a.width !== b.width || a.height !== b.height) {
-          throw new Error(
-            `LayoutPass freeze: '${pass.id}' moved node geometry after the route-contract freeze ` +
-              `(only translate/edge passes are allowed; declare 'translate' in mutates if this is a uniform shift)`,
-          )
-        }
-      }
-    }
-
-    if (beforeEdges && ctx.edges) {
-      for (let i = 0; i < beforeEdges.length; i++) {
-        const edge = ctx.edges[i]
-        if (!edge) continue
-        if (beforeEdges[i] !== routeKey(edge) && edge.routeCertificate === undefined) {
-          throw new Error(
-            `LayoutPass certificate: '${pass.id}' rewrote edge geometry after the route-contract freeze ` +
-              'without re-issuing routeCertificate',
-          )
-        }
-      }
-    }
-
-    if (pass.freezesNodes) ctx.frozen = true
-    ran.add(pass.id)
-    opts.onAfterPass?.(pass, ctx)
-  }
-}
-
-/** A pipeline is well-formed iff its array order is a topological order of `after`. */
-export function assertTopologicalOrder<C extends PassContextBase>(passes: ReadonlyArray<LayoutPass<C>>): void {
-  const seen = new Set<string>()
-  for (const pass of passes) {
-    for (const dep of pass.after) {
-      if (!seen.has(dep)) {
-        throw new Error(`LayoutPass pipeline order: '${pass.id}' precedes its dependency '${dep}'`)
-      }
-    }
-    seen.add(pass.id)
-  }
-}