dsh-model-everything 0.0.0-stage → 0.2.0

package/src/uml-composite.ts

@@ -0,0 +1,520 @@
+/**
+ * The composite structure diagram module.
+ *
+ * A composite structure diagram is a structured classifier seen from the inside: the parts
+ * it is made of, the ports on its boundary, and the connectors between them. That reads
+ * back out of the text, which is what separates this family from the profile.
+ *
+ * PlantUML has no composite-structure page, so the view is an approximation built from the
+ * deployment diagram's vocabulary: a nested element for the classifier, the nestable
+ * elements for its parts, `port`/`portin`/`portout` for the boundary, and the arrows for
+ * connectors. Nesting is spelled, port direction is spelled, and both connector ends are
+ * spelled - so the model survives the round trip. What the notation cannot say (a part's
+ * type, a port's required interface, a connector's name) stays out of the model rather
+ * than being invented on the way back.
+ *
+ * @module model-everything-uml-composite
+ */
+
+import {
+  UmlError, UML_PLAIN_ID, directiveLine, type UmlNotation, type UmlFamilyModule,
+  type UmlFamilyParse, type UmlFamilyRender, type UmlFamilyFinding, type UmlFamilyRenderOptions,
+} from './uml-syntax.js'
+
+/** One end of a connector: the classifier itself, one of its ports, or one of its parts. */
+export type CompositeEndpoint = string
+
+/** The structured classifier being opened up. */
+export interface CompositeSpec {
+  id: string
+  label?: string
+  /** The keyword it is drawn with; `component` is the deployment diagram's default. */
+  kind: string
+}
+
+export interface CompositePart {
+  id: string
+  label?: string
+}
+
+export type CompositePortDirection = 'in' | 'out' | 'inout'
+
+export interface CompositePort {
+  id: string
+  /** `in` is `portin`, `out` is `portout`, `inout` is the bare `port`. */
+  direction: CompositePortDirection
+}
+
+export interface CompositeConnector {
+  from: CompositeEndpoint
+  to: CompositeEndpoint
+  label?: string
+}
+
+/**
+ * A composite structure diagram as a model.
+ *
+ * `self` is the classifier. Ports and parts belong to it, and a connector endpoint names
+ * one of the three - the classifier itself, a port, or a part. The model has no nesting:
+ * a part of a part is a second diagram, which is how a reader keeps each view readable.
+ */
+export interface CompositeModelV1 {
+  schemaVersion: 1
+  self: CompositeSpec
+  parts: CompositePart[]
+  ports: CompositePort[]
+  connectors: CompositeConnector[]
+  /** Ids a connector named that no declaration introduced; the review reports them. */
+  undeclared?: string[]
+  narrative?: { self?: string; parts?: Record<string, string>; ports?: Record<string, string> }
+}
+
+/** Elements PlantUML can nest; a part is declared with one of these. */
+const NESTABLE = [
+  'component', 'node', 'artifact', 'database', 'file', 'folder', 'frame', 'cloud',
+  'package', 'queue', 'rectangle', 'stack', 'storage', 'card', 'hexagon', 'action',
+  'process', 'collections',
+] as const
+
+const PORT_KEYWORDS: Record<string, CompositePortDirection> = { port: 'inout', portin: 'in', portout: 'out' }
+
+/** The port keyword a direction is drawn with. */
+function portKeyword(direction: CompositePortDirection): string {
+  if (direction === 'in') return 'portin'
+  if (direction === 'out') return 'portout'
+  return 'port'
+}
+
+function quote(text: string): string {
+  return '"' + text.replace(/"/g, "'") + '"'
+}
+
+function isPlainId(id: string): boolean {
+  return UML_PLAIN_ID.test(id) && !(NESTABLE as readonly string[]).includes(id.toLowerCase()) && id !== 'port' && id !== 'portin' && id !== 'portout'
+}
+
+/**
+ * Validate a candidate model and normalize it.
+ *
+ * A port id and a part id may not collide: a connector endpoint is a bare name, so two
+ * declarations sharing one would make the drawing say two things at once.
+ */
+export function validateCompositeModel(input: unknown): CompositeModelV1 {
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    throw new UmlError('a composite structure model must be an object with schemaVersion 1, a self, parts, ports and connectors', 'UML_INPUT')
+  }
+  const model = input as Partial<CompositeModelV1>
+  if (model.schemaVersion !== 1) throw new UmlError('a composite structure model must declare schemaVersion 1', 'UML_INPUT')
+  const self = model.self
+  if (self === null || typeof self !== 'object' || typeof self.id !== 'string' || self.id.trim() === '') {
+    throw new UmlError('a composite structure model needs a `self` with a non-empty id', 'UML_INPUT')
+  }
+  const kind = self.kind ?? 'component'
+  if (!(NESTABLE as readonly string[]).includes(kind)) {
+    throw new UmlError('self.kind must be one of ' + NESTABLE.join(' | ') + ', got ' + quote(String(kind)), 'UML_INPUT')
+  }
+  for (const [name, value] of Object.entries({ parts: model.parts ?? [], ports: model.ports ?? [], connectors: model.connectors ?? [] })) {
+    if (!Array.isArray(value)) throw new UmlError(name + ' must be an array', 'UML_INPUT')
+  }
+
+  const declared = new Set<string>([self.id])
+  const parts: CompositePart[] = []
+  for (const part of model.parts ?? []) {
+    if (part === null || typeof part !== 'object' || typeof part.id !== 'string' || part.id.trim() === '') {
+      throw new UmlError('every part needs a non-empty string id', 'UML_INPUT')
+    }
+    if (declared.has(part.id)) throw new UmlError(quote(part.id) + ' is declared more than once as a part or a port', 'UML_INPUT')
+    declared.add(part.id)
+    parts.push({ id: part.id, ...(part.label === undefined ? {} : { label: part.label }) })
+  }
+  const ports: CompositePort[] = []
+  for (const port of model.ports ?? []) {
+    if (port === null || typeof port !== 'object' || typeof port.id !== 'string' || port.id.trim() === '') {
+      throw new UmlError('every port needs a non-empty string id', 'UML_INPUT')
+    }
+    if (declared.has(port.id)) throw new UmlError(quote(port.id) + ' is declared more than once as a part or a port', 'UML_INPUT')
+    declared.add(port.id)
+    const direction = port.direction ?? 'inout'
+    if (direction !== 'in' && direction !== 'out' && direction !== 'inout') {
+      throw new UmlError('port direction must be in | out | inout, got ' + quote(String(direction)), 'UML_INPUT')
+    }
+    ports.push({ id: port.id, direction })
+  }
+
+  const undeclared = new Set<string>()
+  const connectors: CompositeConnector[] = []
+  for (const connector of model.connectors ?? []) {
+    if (connector === null || typeof connector !== 'object') throw new UmlError('every connector must be an object', 'UML_INPUT')
+    for (const side of ['from', 'to'] as const) {
+      const endpoint = connector[side]
+      if (typeof endpoint !== 'string' || endpoint.trim() === '') {
+        throw new UmlError('every connector needs a non-empty `' + side + '` end', 'UML_INPUT')
+      }
+      if (!declared.has(endpoint)) undeclared.add(endpoint)
+    }
+    if (connector.from === connector.to) {
+      throw new UmlError('a connector cannot join ' + quote(connector.from) + ' to itself', 'UML_INPUT')
+    }
+    connectors.push({
+      from: connector.from,
+      to: connector.to,
+      ...(connector.label === undefined ? {} : { label: connector.label }),
+    })
+  }
+
+  return {
+    schemaVersion: 1,
+    self: { id: self.id, kind, ...(self.label === undefined ? {} : { label: self.label }) },
+    parts,
+    ports,
+    connectors,
+    ...(undeclared.size === 0 ? {} : { undeclared: [...undeclared].sort() }),
+    ...(model.narrative === undefined ? {} : { narrative: model.narrative }),
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+
+/**
+ * Render a composite structure diagram as PlantUML.
+ *
+ * The classifier is drawn as a nested element, its parts inside it, its ports on its
+ * boundary, and the connectors after the block. The `self` directive carries the
+ * classifier's own id, because a nested element's closing brace is the only thing that
+ * says where its inside ends.
+ *
+ * @param input - candidate `CompositeModelV1`.
+ * @param notation - only `plantuml` draws this family; mermaid has no ports or connectors.
+ */
+export function renderComposite(input: unknown, notation: UmlNotation): UmlFamilyRender {
+  if (notation !== 'plantuml') {
+    throw new UmlError('a composite structure diagram can only be drawn in plantuml; mermaid has no port or connector element and no nested element to put parts in. Render it with notation "plantuml".', 'UML_VIEW_UNREPRESENTABLE')
+  }
+  const model = validateCompositeModel(input)
+  const warnings: string[] = [
+    'UML_RENDER_APPROXIMATE_VIEW: plantuml has no composite structure diagram; this is a deployment-diagram drawing of one. Nesting, part names, port direction and both connector ends are carried; a part\'s type, a port\'s interfaces and a connector\'s name are not expressible and are not drawn.',
+  ]
+  const lines: string[] = ['@startuml']
+  lines.push(directiveLine('plantuml', 'uml v1 notation=plantuml family=composite-structure'))
+  lines.push(directiveLine('plantuml', 'compositeSelf ' + model.self.kind + ' ' + model.self.id))
+  const label = model.self.label === undefined ? quote(model.self.id) : quote(model.self.label)
+  lines.push(model.self.kind + ' ' + label + ' as ' + model.self.id + ' {')
+  for (const port of model.ports) {
+    // A port declaration takes no alias, so its id is what the reader sees; a port whose
+    // id PlantUML cannot use is reported rather than silently renamed.
+    lines.push('  ' + portKeyword(port.direction) + ' ' + port.id)
+  }
+  for (const part of model.parts) {
+    if (part.label === undefined) lines.push('  component ' + part.id)
+    else lines.push('  component ' + quote(part.label) + ' as ' + part.id)
+  }
+  lines.push('}')
+  for (const connector of model.connectors) {
+    lines.push(connector.from + ' --> ' + connector.to + (connector.label === undefined ? '' : ' : ' + connector.label))
+  }
+  lines.push('@enduml')
+  return { primary: lines.join('\n') + '\n', warnings }
+}
+
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+
+interface CompositeLine {
+  line: number
+  text: string
+}
+
+const SELF_DIRECTIVE = /^compositeSelf\s+([A-Za-z_][A-Za-z0-9_]*)\s+(\S+)\s*$/
+const DECLARATION = new RegExp('^(' + NESTABLE.join('|') + ')\\s+(?:"([^"]*)"|(\\S+))(?:\\s+as\\s+(\\S+))?\\s*(\\{)?\\s*$', 'i')
+const PORT_DECLARATION = /^(port|portin|portout)\s+(\S+)\s*$/i
+const CONNECTOR = /^(\S+)\s+(-->|->|--|\.\.>|\.\.)\s+(\S+?)(?:\s*:\s*(.*))?$/
+
+/**
+ * Read a composite structure diagram back into a model.
+ *
+ * Faithful to this module's renderer and tolerant of hand-written text: the classifier is
+ * the outermost block (named by the `compositeSelf` directive when the renderer wrote it),
+ * `port`/`portin`/`portout` lines are its ports, nestable declarations inside the block are
+ * its parts, and every arrow between two names is a connector. A construct the notation
+ * carries but this model does not - a nested block inside a part, a stereotype, a note - is
+ * reported in `discardedConstructs`, never dropped in silence.
+ */
+export function parseComposite(text: string, notation: UmlNotation): UmlFamilyParse<CompositeModelV1> {
+  if (notation !== 'plantuml') {
+    throw new UmlError('a composite structure diagram can only be read from plantuml', 'UML_VIEW_UNREPRESENTABLE')
+  }
+  const all: CompositeLine[] = text.split(/\r?\n/).map((raw, index) => ({ line: index + 1, text: raw.trim() }))
+  const warnings: string[] = []
+  const discarded: Array<{ line: number; text: string; construct: string }> = []
+  const labels: Record<string, string> = {}
+
+  let self: CompositeSpec | undefined
+  let fromDirective: { kind: string; id: string } | undefined
+  const parts: CompositePart[] = []
+  const ports: CompositePort[] = []
+  const connectors: CompositeConnector[] = []
+  let depth = 0
+  let seenConnector = false
+
+  for (const entry of all) {
+    const line = entry.text
+    if (line === '' || line.startsWith('@') || line.startsWith("'")) {
+      // The renderer's own directives are read elsewhere; a comment is not a construct.
+      if (line.startsWith("'dsh-model-everything:")) {
+        const directive = line.slice("'dsh-model-everything:".length).trim()
+        const selfMatch = SELF_DIRECTIVE.exec(directive)
+        if (selfMatch !== null) fromDirective = { kind: selfMatch[1].toLowerCase(), id: selfMatch[2] }
+      }
+      continue
+    }
+    if (/^(left to right direction|top to bottom direction|skinparam|hide|show|title|scale|allowmixing|allow_mixing)\b/i.test(line)) {
+      discarded.push({ line: entry.line, text: line, construct: line.split(/\s+/)[0].toLowerCase() })
+      continue
+    }
+
+    const port = PORT_DECLARATION.exec(line)
+    if (port !== null) {
+      if (depth === 0) {
+        discarded.push({ line: entry.line, text: line, construct: 'port outside a classifier' })
+        continue
+      }
+      const id = port[2]
+      if (ports.some((entry) => entry.id === id) || parts.some((entry) => entry.id === id)) {
+        warnings.push('line ' + String(entry.line) + ': ' + id + ' is declared twice; the second declaration is ignored')
+        continue
+      }
+      ports.push({ id, direction: PORT_KEYWORDS[port[1].toLowerCase()] })
+      continue
+    }
+
+    const declaration = DECLARATION.exec(line)
+    if (declaration !== null) {
+      const kind = declaration[1].toLowerCase()
+      const quoted = declaration[2]
+      const bare = declaration[3]
+      const alias = declaration[4]
+      const opens = declaration[5] === '{'
+      const id = alias ?? bare ?? quoted ?? ''
+      // `component "App" as app` names the id in the alias and the label in the quotes.
+      // `component App as app` puts the label in the bare position instead, and that is a
+      // label rather than an id: the alias is what the rest of the diagram refers to.
+      const labelText = quoted ?? (alias === undefined ? undefined : bare)
+      if (labelText !== undefined) labels[id] = labelText
+      if (depth === 0) {
+        if (self !== undefined) {
+          discarded.push({ line: entry.line, text: line, construct: 'second top-level block' })
+        } else {
+          self = { id, kind, ...(labelText === undefined ? {} : { label: labelText }) }
+        }
+      } else if (depth === 1) {
+        if (opens) {
+          // A block inside the classifier would be a part with its own inside. The model
+          // has no nesting, so the part is kept and the block it opens is reported.
+          discarded.push({ line: entry.line, text: line, construct: 'nested block inside a part' })
+        }
+        if (!parts.some((entry) => entry.id === id) && !ports.some((entry) => entry.id === id)) {
+          parts.push({ id, ...(labelText === undefined ? {} : { label: labelText }) })
+        } else {
+          warnings.push('line ' + String(entry.line) + ': ' + id + ' is declared twice; the second declaration is ignored')
+        }
+      } else {
+        // Whatever is declared inside a part is that part's inside, and this model has no
+        // place for it. Reporting it is the only alternative to inventing a structure.
+        discarded.push({ line: entry.line, text: line, construct: 'declaration inside a part' })
+      }
+      if (opens) depth += 1
+      continue
+    }
+    if (line === '}') {
+      depth = Math.max(0, depth - 1)
+      seenConnector = false
+      continue
+    }
+
+    const connector = CONNECTOR.exec(line)
+    if (connector !== null) {
+      const [, from, , to, label] = connector
+      connectors.push({ from, to, ...(label === undefined || label === '' ? {} : { label }) })
+      seenConnector = true
+      continue
+    }
+    if (seenConnector || depth > 0) {
+      discarded.push({ line: entry.line, text: line, construct: 'line this model does not carry' })
+    } else {
+      discarded.push({ line: entry.line, text: line, construct: 'statement outside any classifier' })
+    }
+  }
+
+  if (self === undefined) {
+    if (fromDirective === undefined) {
+      throw new UmlError('no structured classifier found: a composite structure diagram needs one block that holds its parts, such as `component Order as order { ... }`', 'UML_INPUT')
+    }
+    self = { id: fromDirective.id, kind: fromDirective.kind }
+  } else if (fromDirective !== undefined) {
+    // The directive is the renderer's own record; it wins, because the block's alias can
+    // be a label PlantUML was given.
+    self = { ...self, id: fromDirective.id, kind: fromDirective.kind }
+  }
+
+  const declared = new Set<string>([self.id, ...parts.map((part) => part.id), ...ports.map((port) => port.id)])
+  const undeclared = [...new Set(connectors.flatMap((connector) => [connector.from, connector.to]))].filter((endpoint) => !declared.has(endpoint)).sort()
+  // No narrative is invented here. The labels a reader gave the drawing come back in
+  // `labels`, which is where a display name belongs; writing them into the model as well
+  // would add a field the model never carried, and the round trip would stop being exact.
+  const model: CompositeModelV1 = {
+    schemaVersion: 1,
+    self,
+    parts,
+    ports,
+    connectors,
+    ...(undeclared.length === 0 ? {} : { undeclared }),
+  }
+  return { model, labels, warnings, discardedConstructs: discarded, discardedEdges: 0 }
+}
+
+// ---------------------------------------------------------------------------
+// Review
+// ---------------------------------------------------------------------------
+
+export type CompositeFindingCode =
+  | 'UML057_COMPOSITE_NO_PARTS'
+  | 'UML058_COMPOSITE_PORT_UNCONNECTED'
+  | 'UML059_COMPOSITE_CONNECTOR_ENDPOINT_MISSING'
+  | 'UML060_COMPOSITE_DUPLICATE_PART'
+  | 'UML061_COMPOSITE_PORT_COLLISION'
+  | 'UML062_COMPOSITE_UNDOCUMENTED'
+
+export const COMPOSITE_FINDING_CODES: readonly CompositeFindingCode[] = [
+  'UML057_COMPOSITE_NO_PARTS',
+  'UML058_COMPOSITE_PORT_UNCONNECTED',
+  'UML059_COMPOSITE_CONNECTOR_ENDPOINT_MISSING',
+  'UML060_COMPOSITE_DUPLICATE_PART',
+  'UML061_COMPOSITE_PORT_COLLISION',
+  'UML062_COMPOSITE_UNDOCUMENTED',
+]
+
+/**
+ * What a reader would get wrong about a composite structure.
+ *
+ * The questions are the ones the diagram exists to answer: is anything inside, does every
+ * port lead somewhere, does every connector join two things that exist, and is each part
+ * and port named after something in the system rather than after its drawing position.
+ * Whether the decomposition is *right* is a question about the design, and this does not
+ * answer it.
+ */
+export function reviewCompositeModel(model: CompositeModelV1, labels: Record<string, string>): UmlFamilyFinding[] {
+  const findings: UmlFamilyFinding[] = []
+  const name = (id: string): string => labels[id] ?? id
+
+  if (model.parts.length === 0) {
+    findings.push({
+      code: 'UML057_COMPOSITE_NO_PARTS',
+      severity: 'error',
+      message: 'the classifier is drawn as a composite structure but holds no part: a structure diagram with an empty inside says nothing about how it is built.',
+      evidence: { parts: 0 },
+    })
+  }
+
+  const connected = new Set(model.connectors.flatMap((connector) => [connector.from, connector.to]))
+  for (const port of model.ports) {
+    if (connected.has(port.id)) continue
+    findings.push({
+      code: 'UML058_COMPOSITE_PORT_UNCONNECTED',
+      severity: 'warning',
+      message: 'port ' + name(port.id) + ' (' + port.direction + ') has no connector, so nothing reaches the classifier through it.',
+      evidence: { id: port.id, direction: port.direction },
+    })
+  }
+
+  const undeclared = model.undeclared ?? []
+  if (undeclared.length > 0) {
+    findings.push({
+      code: 'UML059_COMPOSITE_CONNECTOR_ENDPOINT_MISSING',
+      severity: 'error',
+      message: 'a connector ends at ' + String(undeclared.length) + ' name(s) the classifier never declares, so the line points at nothing a reader can look up.',
+      detail: undeclared.join(', '),
+      evidence: { ids: undeclared },
+    })
+  }
+
+  const seen = new Set<string>()
+  for (const part of model.parts) {
+    if (seen.has(part.id)) {
+      findings.push({
+        code: 'UML060_COMPOSITE_DUPLICATE_PART',
+        severity: 'error',
+        message: 'part ' + part.id + ' is declared more than once, so a connector that names it is ambiguous.',
+        evidence: { id: part.id },
+      })
+    }
+    seen.add(part.id)
+  }
+  if (seen.has(model.self.id)) {
+    findings.push({
+      code: 'UML061_COMPOSITE_PORT_COLLISION',
+      severity: 'error',
+      message: 'the classifier itself is also declared as a part (' + model.self.id + '): a nested element inside itself has no reading.',
+      evidence: { id: model.self.id },
+    })
+  }
+  for (const port of model.ports) {
+    if (seen.has(port.id)) {
+      findings.push({
+        code: 'UML061_COMPOSITE_PORT_COLLISION',
+        severity: 'error',
+        message: 'port ' + port.id + ' shares its name with a part: a connector that names it cannot be read.',
+        evidence: { id: port.id },
+      })
+    }
+  }
+
+  if (model.self.label === undefined && labels[model.self.id] === undefined) {
+    findings.push({
+      code: 'UML062_COMPOSITE_UNDOCUMENTED',
+      severity: 'info',
+      message: 'the classifier carries no name a reader can map back to the design: give it a display label or a narrative entry.',
+      evidence: { id: model.self.id },
+    })
+  }
+  for (const part of model.parts) {
+    if (part.label !== undefined || labels[part.id] !== undefined) continue
+    findings.push({
+      code: 'UML062_COMPOSITE_UNDOCUMENTED',
+      severity: 'info',
+      message: 'part ' + part.id + ' carries no name a reader can map back to the design: give it a display label or a narrative entry.',
+      evidence: { id: part.id },
+    })
+  }
+  return findings
+}
+
+/** The composite structure family, as the engine's registry expects it. */
+export const compositeModule: UmlFamilyModule<CompositeModelV1> = {
+  id: 'composite-structure',
+  render: (input: unknown, notation: UmlNotation, _options: UmlFamilyRenderOptions): UmlFamilyRender => renderComposite(input, notation),
+  parse: (text: string, notation: UmlNotation): UmlFamilyParse<CompositeModelV1> => parseComposite(text, notation),
+  // The self's `kind` is always drawn - the renderer writes it into the `compositeSelf` directive
+  // and into the declaration - so the parser always reads one back. A model that left it out is
+  // normalized to the same shape before the fidelity comparison, or the review reports its own
+  // default as drift: "self.kind invented by the diagram" on a diagram that says exactly what the
+  // model meant.
+  //
+  // `undeclared` is carried through deliberately. It is what `UML059` reads, and it is a fact about
+  // the supplied model rather than about the diagram, so normalizing it away would silence the one
+  // finding that says a connector ends at a name the classifier never declares - the silent pass
+  // this file's own comments promise not to produce.
+  normalize: (input: unknown): CompositeModelV1 | undefined => {
+    try {
+      const normalized = validateCompositeModel(input)
+      const undeclared = (input as { undeclared?: unknown }).undeclared
+      if (!Array.isArray(undeclared)) return normalized
+      return { ...normalized, undeclared: undeclared.filter((entry): entry is string => typeof entry === 'string') }
+    } catch {
+      return undefined
+    }
+  },
+  review: (model: CompositeModelV1, labels: Record<string, string>): UmlFamilyFinding[] => reviewCompositeModel(model, labels),
+}