dsh-model-everything 0.0.0-stage → 0.1.0

package/src/report-view.ts

@@ -0,0 +1,451 @@
+/**
+ * The report body: the text a model reads for a this plugin result.
+ *
+ * Why this is not `JSON.stringify(value, null, 2)` any more: the structured report is a
+ * contract (schema, verdict, hashes, check ids, finding codes, evidence — a finding's
+ * identity is `check|code|<evidence + path>`, so `report_diff` and the test
+ * suite read the object, never this text). The object is unchanged and still reaches the
+ * client and the file path; this module only decides what the *model* pays for.
+ *
+ * Measured on a real 37,167-character report: 33.1% indentation, 21.7% repeated key names,
+ * 12.7% punctuation; 105 findings carried 47 distinct facts. So the work this module does —
+ * silencing passing checks, grouping repeated (state, event) facts, collapsing identical
+ * lines, dropping warning evidence — is work the model would otherwise have to redo by
+ * reading every finding. Everything a consumer does not need to act on is handled here.
+ *
+ * Determinism: the same report always renders to the same text (first-seen order, stable
+ * check order, no clock, no randomness), so two runs over the same input stay comparable.
+ *
+ * @module model-everything/report-view
+ */
+import type { JsonValue } from './json-value.js'
+
+/** Rendering limits. Defaults are the shipped behaviour; tests pin them. */
+export interface ReportViewOptions {
+  /** Maximum finding lines per check. Error findings are never dropped, only warnings are capped. */
+  maxFindingsPerCheck?: number
+  /** Evidence is inlined for `error` findings only, truncated to this many characters. */
+  maxEvidenceChars?: number
+  /** Include passing checks' bodies (default false: a passing check carries no actionable finding). */
+  includePassing?: boolean
+  /**
+   * Print the whole structured report instead of the body. This is the escape hatch for a
+   * caller that must hand the report to another tool verbatim — `report_diff`
+   * matches on check + code + evidence, so a body cannot stand in for the object.
+   */
+  full?: boolean
+}
+
+const DEFAULTS = { maxFindingsPerCheck: 24, maxEvidenceChars: 160, includePassing: false, full: false } as const
+
+type Record_ = Record<string, unknown>
+
+const record = (value: unknown): Record_ | undefined =>
+  typeof value === 'object' && value !== null && !Array.isArray(value) ? (value as Record_) : undefined
+const array = (value: unknown): unknown[] => (Array.isArray(value) ? value : [])
+const text = (value: unknown): string | undefined => (typeof value === 'string' ? value : undefined)
+const count = (value: unknown): number | undefined => (typeof value === 'number' && Number.isFinite(value) ? value : undefined)
+
+/** One normalized finding. `evidence` is kept because a finding's identity depends on it. */
+export interface ViewFinding {
+  code: string
+  severity: string
+  message: string
+  evidence?: Record_
+  file?: string
+  line?: number
+  check?: string
+}
+
+/** Normalize one raw finding. Unknown fields are ignored; a missing message renders as the code. */
+export function toViewFinding(value: unknown, check?: string): ViewFinding {
+  const raw = record(value) ?? {}
+  const code = text(raw.code) ?? 'FINDING'
+  const file = text(raw.file)
+  const line = count(raw.line)
+  return {
+    code,
+    severity: text(raw.severity) ?? 'warning',
+    message: text(raw.message) ?? code,
+    ...(record(raw.evidence) === undefined ? {} : { evidence: record(raw.evidence) as Record_ }),
+    ...(file === undefined ? {} : { file }),
+    ...(line === undefined ? {} : { line }),
+    ...(check === undefined ? {} : { check }),
+  }
+}
+
+/**
+ * The fact a finding states, as a comparable key. The verify/datamodel families report the
+ * same (state, event) fact from more than one check, so the key ignores which check said it;
+ * anything else falls back to code + message.
+ */
+export function factKey(finding: ViewFinding): string {
+  const stateEvent = /^(\S+) silently ignores event (\S+)/.exec(finding.message)
+  if (stateEvent !== null) return `event-in-state|${stateEvent[1] ?? ''}|${stateEvent[2] ?? ''}`
+  const eventState = /^Event (\S+) in state (\S+) /.exec(finding.message)
+  if (eventState !== null) return `event-in-state|${eventState[2] ?? ''}|${eventState[1] ?? ''}`
+  return `message|${finding.code}|${finding.message}`
+}
+
+/** `[severity/CODE] message` plus, for errors, a compact evidence tail. */
+function findingLine(finding: ViewFinding, options: Required<ReportViewOptions>): string {
+  const where = finding.file === undefined ? '' : ` (${finding.file}${finding.line === undefined ? '' : ':' + String(finding.line)})`
+  const evidence =
+    finding.evidence === undefined || finding.severity !== 'error'
+      ? ''
+      : ' evidence=' + truncate(JSON.stringify(finding.evidence), options.maxEvidenceChars)
+  return `  [${finding.severity}/${finding.code}] ${finding.message}${where}${evidence}`
+}
+
+function truncate(value: string, limit: number): string {
+  return value.length <= limit ? value : value.slice(0, limit - 1) + '…'
+}
+
+/** Collapse identical lines into `line (xN)`, keeping first-seen order. */
+function collapse(lines: string[]): string[] {
+  const order: string[] = []
+  const seen = new Map<string, number>()
+  for (const line of lines) {
+    if (!seen.has(line)) order.push(line)
+    seen.set(line, (seen.get(line) ?? 0) + 1)
+  }
+  return order.map((line) => (seen.get(line) === 1 ? line : `${line} (x${String(seen.get(line))})`))
+}
+
+/**
+ * Body lines for one group of findings. Findings that restate a fact an earlier check already
+ * reported are dropped (only their count survives), because re-reading them is pure cost;
+ * `error` findings are never dropped.
+ */
+function findingLines(findings: ViewFinding[], options: Required<ReportViewOptions>, seenFacts: Set<string>): string[] {
+  const lines: string[] = []
+  let repeats = 0
+  const fresh: ViewFinding[] = []
+  const addedHere = new Set<string>()
+  for (const finding of findings) {
+    const key = factKey(finding)
+    // A fact another check already reported is dropped here (only its count survives), but a
+    // fact repeated inside this same group is not a cross-check repeat: it collapses below
+    // into one line with a multiplier, which keeps the count visible where it belongs.
+    if (finding.severity !== 'error' && seenFacts.has(key) && !addedHere.has(key)) {
+      repeats += 1
+      continue
+    }
+    addedHere.add(key)
+    seenFacts.add(key)
+    fresh.push(finding)
+  }
+  const stateGroups = new Map<string, { severity: string; code: string; events: string[] }>()
+  const singles: ViewFinding[] = []
+  for (const finding of fresh) {
+    const match = /^(\S+) silently ignores event (\S+)/.exec(finding.message) ?? /^Event (\S+) in state (\S+) /.exec(finding.message)
+    if (match === null) {
+      singles.push(finding)
+      continue
+    }
+    // `event in state` puts the state second; `state ignores event` puts it first.
+    const state = / silently ignores event /.test(finding.message) ? match[1] ?? '' : match[2] ?? ''
+    const event = / silently ignores event /.test(finding.message) ? match[2] ?? '' : match[1] ?? ''
+    const group = stateGroups.get(state) ?? { severity: finding.severity, code: finding.code, events: [] }
+    group.events.push(event)
+    stateGroups.set(state, group)
+  }
+  for (const [state, group] of stateGroups) {
+    lines.push(`  ${state} (${String(group.events.length)}) [${group.severity}/${group.code}]: ${group.events.join(', ')}`)
+  }
+  const rendered = collapse(singles.map((finding) => findingLine(finding, options)))
+  const budget = options.maxFindingsPerCheck
+  const kept: string[] = []
+  let dropped = 0
+  for (const line of [...lines, ...rendered]) {
+    if (kept.length < budget || line.includes('/error]')) kept.push(line)
+    else dropped += 1
+  }
+  if (dropped > 0) kept.push(`  +${String(dropped)} more warning line(s) — ask for this check by id to see them all`)
+  if (repeats > 0) kept.push(`  (${String(repeats)} finding(s) here repeat facts already reported above)`)
+  return kept
+}
+
+/** `ok`/`verdict` header fields, shared by every report family. */
+function headerLines(report: Record_, options: Required<ReportViewOptions>): string[] {
+  const schema = text(report.schema) ?? 'model-everything/report'
+  const verdict = text(report.verdict)
+  const ok = report.ok
+  const summary = record(report.summary) ?? {}
+  const lines: string[] = []
+  const bits = [
+    `${schema}`,
+    verdict === undefined ? `ok=${String(ok)}` : `verdict=${verdict}`,
+    text(report.verdictReason) ?? '',
+    ok === undefined || verdict === undefined ? '' : `ok=${String(ok)}`,
+  ].filter((bit) => bit !== '')
+  lines.push(bits.join('  '))
+  // A refusal carries no model to hash, and the field is an empty string rather than absent, so it rendered
+  // as `modelHash=…` - which reads as a truncated hash rather than as nothing to hash. An empty value means
+  // the same thing as a missing one here.
+  const hashText = text(report.modelHash) ?? text(record(report.hashes)?.modelHash)
+  const hash = hashText === '' ? undefined : hashText
+  // The scheme belongs beside the digest: a hex string with no spec cannot be reproduced, and two hashes cannot
+  // be compared across report versions without it.
+  const hashSpec = text(report.hashSpec) ?? text(record(report.hashes)?.hashSpec)
+  const hashBits = hash === undefined ? [] : [`modelHash=${hash.slice(0, 12)}…`, ...(hashSpec === undefined ? [] : [`hashSpec=${hashSpec}`])]
+  const counts = ['states', 'transitions', 'errors', 'warnings', 'checksRun']
+    .map((key) => (count(summary[key]) === undefined ? '' : `${key}=${String(count(summary[key]))}`))
+    .filter((bit) => bit !== '')
+  if (counts.length > 0 || hashBits.length > 0) lines[0] += '  ' + [...hashBits, ...counts].join(' ')
+  if (report.ran === false) lines.push('note: the tool did not run (the engine refused the input) — the fields below describe the refusal.')
+  // `truncated` is the flag that says a search stopped at its budget. It reached the object and never the body, so
+  // the one reader who sees only the body - the model - read an unfinished search as a complete one. It belongs
+  // at the top, before the inventory: a reader who stops after the first line still learns the report is partial.
+  if (summary.truncated === true) {
+    lines.push('LIMIT  the searches stopped at their budget, so part of this report is undecided rather than clean — the *_UNDECIDED findings name what.')
+  }
+  // A replaced or clamped bound is the reason the header's numbers are not the ones the caller asked for.
+  for (const note of array(summary.boundNotes).map(String).filter((note) => note !== '')) lines.push(`BOUND  ${note}`)
+  // Coverage arrives as "described/total" strings, so reading only numbers dropped every value the engine sends
+  // and the line never appeared. Take both shapes.
+  const coverage = record(report.narrativeCoverage)
+  if (coverage !== undefined) {
+    const parts = Object.entries(coverage)
+      .map(([key, value]) => {
+        const shown = count(value) ?? text(value)
+        return shown === undefined ? undefined : `${key} ${String(shown)}`
+      })
+      .filter((part): part is string => part !== undefined)
+    if (parts.length > 0) lines.push(`NARRATIVE  ${parts.join(' / ')} documented`)
+  }
+  // The schema ignores `_`-prefixed keys as annotation metadata and the report echoes their paths. Naming them
+  // here makes the ignoring auditable; dropping them made "the schema ignored your field" invisible.
+  const metadata = array(report.metadataKeys).map(String).filter((key) => key !== '')
+  if (metadata.length > 0) lines.push(`METADATA  _-prefixed keys the schema ignored: ${metadata.join(', ')}`)
+  void options
+  return lines
+}
+
+/** Trailing lines: notes about what was not checked, then the next steps. */
+function footerLines(report: Record_): string[] {
+  const lines: string[] = []
+  const notes = array(report.coverageNotes).map(String).filter((note) => note !== '')
+  if (notes.length > 0) lines.push(`COVERAGE  ${notes.join(' ')}`)
+  const steps = array(report.nextSteps).map(String).filter((step) => step !== '')
+  for (const step of steps) lines.push(`NEXT  ${step}`)
+  const comparison = record(report.comparison)
+  if (comparison !== undefined) {
+    const parts = Object.entries(comparison)
+      .filter(([, value]) => count(value) !== undefined || typeof value === 'string')
+      .map(([key, value]) => `${key}=${String(value)}`)
+    if (parts.length > 0) lines.push(`COMPARISON  ${parts.join(' ')}`)
+  }
+  return lines
+}
+
+/** A `checks[]` report (verify, compose, datamodel): silence pass, expand the rest. */
+function renderChecksReport(report: Record_, options: Required<ReportViewOptions>): string[] {
+  const checks = array(report.checks).map((value) => record(value) ?? {})
+  const byStatus = (status: string): string[] =>
+    checks.filter((check) => text(check.status) === status).map((check) => text(check.id) ?? '?')
+  /**
+   * Whether a failing check carries an error or only warnings.
+   *
+   * `status` is `fail` for any check with a finding, which is the right field for a machine and a
+   * misleading word for a reader: a report can say `verdict=pass_with_findings ... no error findings` on
+   * one line and `fail S5 A1 A3` on the next, where all three hold warnings only. The word `fail` beside a
+   * verdict that says nothing failed is the misreading the reading skill warns about, so the inventory
+   * distinguishes them and leaves the status field alone.
+   */
+  const failingKind = (check: Record_): 'error' | 'warn' => {
+    const findings = array(check.findings).map((value) => record(value) ?? {})
+    return findings.some((finding) => text(finding.severity) === 'error') ? 'error' : 'warn'
+  }
+  const failing = checks.filter((check) => text(check.status) === 'fail')
+  const inventory = [
+    ['pass', byStatus('pass')],
+    ['fail', failing.filter((check) => failingKind(check) === 'error').map((check) => text(check.id) ?? '?')],
+    ['warn', failing.filter((check) => failingKind(check) === 'warn').map((check) => text(check.id) ?? '?')],
+    ['skip', byStatus('skip')],
+  ]
+    .filter(([, ids]) => (ids as string[]).length > 0)
+    .map(([status, ids]) => `${String(status)} ${(ids as string[]).join(' ')}`)
+    .join(' | ')
+  const lines = [...headerLines(report, options), `CHECKS  ${inventory}`]
+  const seenFacts = new Set<string>()
+  for (const check of checks) {
+    const status = text(check.status) ?? 'skip'
+    const findings = array(check.findings).map((finding) => toViewFinding(finding, text(check.id)))
+    if (status === 'pass' && !options.includePassing) continue
+    const body = findingLines(findings, options, seenFacts)
+    if (status !== 'fail' && body.length === 0) continue
+    lines.push('')
+    // The section header says what the inventory said: `fail` for a check carrying an error, `warn` for one
+    // carrying warnings only. Printing FAIL here while the CHECKS line grouped the same check under `warn`
+    // put the misreading one line below where it had just been removed.
+    const label = status === 'fail' ? (failingKind(check) === 'error' ? 'FAIL' : 'WARN') : status.toUpperCase()
+    lines.push(
+      `${label} ${text(check.id) ?? '?'} ${text(check.name) ?? ''} — ${text(check.detail) ?? ''} (${String(findings.length)} finding(s))`.replace(/ +— +$/, ''),
+    )
+    lines.push(...body)
+  }
+  return [...lines, ...wrapFooter(report)]
+}
+
+/** A flat `findings[]` report (uml review, structure, granularity, concurrency). */
+function renderFindingsReport(report: Record_, options: Required<ReportViewOptions>): string[] {
+  const findings = array(report.findings).map((finding) => toViewFinding(finding))
+  const errors = findings.filter((finding) => finding.severity === 'error').length
+  const warnings = findings.length - errors
+  const byCode = new Map<string, number>()
+  for (const finding of findings) byCode.set(finding.code, (byCode.get(finding.code) ?? 0) + 1)
+  // A report can carry notes beside its findings: `uml_parse` puts what the parser could not read in `warnings`, and
+  // the verdict counts them. The body printed neither, so a report with one parser note said "1 warning finding(s)"
+  // above "FINDINGS none — nothing was reported". They are printed now, and the empty-roster sentence stops claiming
+  // nothing was reported when something was.
+  const notes = array(report.warnings).map(String).filter((note) => note !== '')
+  const lines = [
+    ...headerLines(report, options),
+    ...parseBodyLines(report),
+    // An empty roster says so in one word. `0 total (0 error, 0 warning):` with a dangling colon read like a
+    // line that had lost its content.
+    findings.length === 0
+      ? (notes.length === 0
+        ? 'FINDINGS  none — nothing was reported'
+        : `FINDINGS  none — ${String(notes.length)} note(s) under WARNING say what could not be carried`)
+      : `FINDINGS  ${String(findings.length)} total (${String(errors)} error, ${String(warnings)} warning): ${[...byCode].map(([code, n]) => `${code} x${String(n)}`).join(' | ')}`,
+  ]
+  const body = findingLines(findings, options, new Set<string>())
+  if (body.length > 0) lines.push('', ...body)
+  if (notes.length > 0) {
+    lines.push('')
+    for (const note of notes) lines.push(`WARNING  ${truncate(note, options.maxEvidenceChars * 2)}`)
+  }
+  return [...lines, ...wrapFooter(report)]
+}
+
+/**
+ * A report that carries a model rather than findings about one (`uml_parse`).
+ *
+ * The reader asked to read the diagram into a model, and the body printed neither the model nor how the text was
+ * read, so the one reader who only has the body got `FINDINGS none` as the entire answer. The model is printed as
+ * compact JSON on one line: it is data the caller feeds to `model_verify`, not prose.
+ */
+function parseBodyLines(report: Record_): string[] {
+  // Only a parse report: a review report carries a model too, but the caller already has it and the review is about
+  // what the diagram says. Printing it there would be the same body for two different questions.
+  if (text(report.action) !== 'parse') return []
+  const model = record(report.model)
+  if (model === undefined) return []
+  const where = ['notation', 'kind', 'family']
+    .map((key) => (text(report[key]) === undefined ? undefined : `${key}=${String(text(report[key]))}`))
+    .filter((part): part is string => part !== undefined)
+  return [...(where.length === 0 ? [] : [`PARSE  ${where.join('  ')}`]), `MODEL  ${JSON.stringify(model)}`]
+}
+
+/** A baseline diff report: what a change added, removed or changed. */
+function renderDeltaReport(report: Record_, options: Required<ReportViewOptions>): string[] {
+  const lines = headerLines(report, options)
+  const delta = record(report.delta) ?? report
+  const section = (key: string): ViewFinding[] => array(delta[key]).map((finding) => toViewFinding(finding))
+  for (const key of ['added', 'removed']) {
+    const findings = section(key)
+    if (findings.length === 0) continue
+    lines.push('', `${key.toUpperCase()} (${String(findings.length)})`)
+    lines.push(...findingLines(findings, options, new Set<string>()))
+  }
+  // `changed` items are not findings: each carries the two sides of a finding that kept its identity and moved.
+  // Reading them with `toViewFinding` invented `severity: warning` for an item that has no severity, and dropped
+  // both messages - so a warning that escalated to an error rendered as `[warning/CODE] CODE`, which says the
+  // opposite of what happened.
+  const changes = array(delta.changed)
+  if (changes.length > 0) {
+    lines.push('', `CHANGED (${String(changes.length)})`)
+    for (const raw of changes) {
+      const change = record(raw) ?? {}
+      const before = record(change.before) ?? {}
+      const after = record(change.after) ?? {}
+      const beforeSeverity = text(before.severity)
+      const afterSeverity = text(after.severity)
+      const beforeMessage = text(before.message)
+      const afterMessage = text(after.message)
+      const parts: string[] = []
+      if (beforeSeverity !== afterSeverity) parts.push(`severity ${String(beforeSeverity)} → ${String(afterSeverity)}`)
+      if (beforeMessage !== afterMessage) {
+        parts.push(`message "${truncate(String(beforeMessage), options.maxEvidenceChars)}" → "${truncate(String(afterMessage), options.maxEvidenceChars)}"`)
+      }
+      lines.push(`  ${text(change.code) ?? '?'}  ${parts.length === 0 ? 'reported differently' : parts.join('; ')}`)
+    }
+  }
+  const current = text(report.currentVerdict) ?? text(record(report.current)?.verdict)
+  if (current !== undefined) lines.push(`CURRENT  verdict=${current}`)
+  return [...lines, ...wrapFooter(report)]
+}
+
+/** A payload result (a rendered diagram, an exported file): print the payload, not JSON of it. */
+function renderPayloadReport(report: Record_, options: Required<ReportViewOptions>): string[] {
+  const lines = headerLines(report, options)
+  const primary = text(report.diagram) ?? text(report.primary)
+  if (primary !== undefined) lines.push('', primary.trimEnd())
+  const extras = record(report.extras)
+  for (const [name, content] of Object.entries(extras ?? {})) {
+    const body = text(content)
+    if (body !== undefined) lines.push('', `--- ${name} ---`, body.trimEnd())
+  }
+  const warnings = array(report.warnings).map(String).filter((warning) => warning !== '')
+  for (const warning of warnings) lines.push(`WARNING  ${warning}`)
+  return [...lines, ...wrapFooter(report)]
+}
+
+function wrapFooter(report: Record_): string[] {
+  const footer = footerLines(report)
+  return footer.length === 0 ? [] : ['', ...footer]
+}
+
+/**
+ * A refusal, or a shape this module does not recognize: state the reason first, then the
+ * remaining fields compactly so nothing is lost, without paying for indentation.
+ */
+function renderFallbackReport(report: Record_, options: Required<ReportViewOptions>): string[] {
+  const lines = headerLines(report, options)
+  const message = text(report.error)
+  if (message !== undefined) {
+    const code = text(report.errorCode)
+    lines.push(`ERROR  ${message}${code === undefined ? '' : ` [${code}]`}`)
+  }
+  const rest: Record_ = { ...report }
+  delete rest.error
+  delete rest.errorCode
+  lines.push('', JSON.stringify(rest))
+  return [...lines, ...wrapFooter(report)]
+}
+
+/**
+ * Render any this plugin result as the text a model reads.
+ *
+ * Order of recognition: a `checks[]` report, a flat `findings[]` report, a baseline delta,
+ * a payload result (`diagram`/`primary`), and finally compact JSON so an unrecognized shape
+ * is still readable rather than silently empty.
+ */
+export function renderReportText(value: unknown, options: ReportViewOptions = {}): string {
+  const resolved: Required<ReportViewOptions> = { ...DEFAULTS, ...options }
+  if (resolved.full) return JSON.stringify(value as JsonValue, null, 2)
+  const report = record(value)
+  if (report === undefined) return JSON.stringify(value as JsonValue) ?? String(value)
+  const hasChecks = array(report.checks).some((check) => record(check) !== undefined)
+  // A report that CARRIES a findings list is a findings report even when the list is empty. Routing on
+  // length sent a clean report to the unknown-shape fallback, which printed the whole JSON - so the default
+  // view cost more than the `full` escape hatch it exists to be cheaper than.
+  const hasFindings = Array.isArray(report.findings)
+  // A delta is recognised by its shape, not by whether anything moved: a clean comparison is the case a baseline
+  // is used for most often, and requiring a non-empty list sent exactly that case to the unknown-shape fallback,
+  // which printed the whole object as JSON.
+  const isDelta = Array.isArray(report.added) || Array.isArray(report.removed) || Array.isArray(report.changed) || typeof report.currentVerdict === 'string'
+  const isPayload = typeof report.diagram === 'string' || typeof report.primary === 'string'
+  const lines = hasChecks
+    ? renderChecksReport(report, resolved)
+    : isDelta
+      ? renderDeltaReport(report, resolved)
+      : hasFindings
+        ? renderFindingsReport(report, resolved)
+        : isPayload
+          ? renderPayloadReport(report, resolved)
+          : renderFallbackReport(report, resolved)
+  return lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd()
+}

package/src/structure-tool.ts

@@ -0,0 +1,93 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from './json-value.js'
+import { REPORT_SCHEMAS } from './engine.js'
+import { reviewStructure } from './structure.js'
+import { reviewGranularity, type GranularityDiagram } from './granularity.js'
+import { OptionShapeError, optionRefusal, requireArrayOption } from './option-shape.js'
+import { renderReportText } from './report-view.js'
+
+export const STRUCTURE_TOOL_NAME = 'uml_structure_verify'
+
+/**
+ * Model-visible DSH tool that audits a *structure* diagram — components, packages,
+ * classes, deployment nodes and the dependency arrows between them — against an
+ * optional dependency matrix. A structure diagram is not a state machine: this tool
+ * reads the graph the diagram actually draws, instead of refusing it (which is what
+ * `uml action=parse` does) or pretending the arrows are state transitions
+ * (which is what a false `ok` used to hide).
+ */
+export const umlStructureTool = defineTool({
+  name: STRUCTURE_TOOL_NAME,
+  description:
+    'Audit a structure diagram as a dependency graph. Takes PlantUML component, package, class or deployment text, or a Mermaid class diagram. Reports UML020 isolated node, UML021 dangling reference, UML022 cycle (shortest path), UML023 disallowed edge and UML024 layer violation against a matrix, UML025 missing required edge, and UML026 when no node is declared. The matrix is {rules: [{id, source, allow?, deny?, require?}], layers: [{name, members}], default: "allow"|"deny"}. Ids and members accept globs (`*`, `?`). Deny beats allow, and layers run top-first, so downward edges pass and upward ones are UML024. With a matrix, every edge appears in `edgeVerdicts` with the rules it matched. Pass `diagrams` instead of `diagram` to check several levels at once: each child must refine its parent. This audits the diagram, not the code: reconcile it with a source-side scan. Read `verdict`, not `ok`. For state or activity diagrams use `uml` and `model_verify`.',
+  parameters: {
+    diagram: {
+      type: 'string',
+      description: 'Structure-diagram source text: PlantUML component/package/class/deployment, or a Mermaid class diagram. Omit when `diagrams` is given.',
+    },
+    diagrams: {
+      type: 'json',
+      description: 'Multi-granularity mode: an array of {name, diagram, parent?} levels. Each diagram is checked on its own AND against its declared parent (UML028 unknown parent, UML029 refinement violation, UML030 parent cycle), with per-pair node/edge counts.',
+    },
+    notation: {
+      type: 'string',
+      enum: ['auto', 'plantuml', 'mermaid'],
+      description: 'Diagram language. Default auto (detected from the text).',
+    },
+    matrix: {
+      type: 'json',
+      description: 'Optional dependency matrix: {rules: [{id, source, allow?, deny?, require?}], layers: [{name, members}], default: "allow"|"deny"}. Every edge is judged against it and the matched rule ids are reported.',
+    },
+    reportView: {
+      type: 'string',
+      enum: ['digest', 'full'],
+      description: 'digest (default) prints the readable body; full prints the structured report, which report_diff needs.',
+    },
+  },
+  output: {
+    schema: {
+      type: 'json',
+      description: 'Structure review report: graph (nodes/edges), the findings with their codes, per-edge matrix verdicts, summary and next steps.',
+    },
+    render(args, value) {
+      return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
+    },
+  },
+  timeoutMs: 10_000,
+  isConcurrencySafe: () => true,
+  async execute(args) {
+    if (args.diagrams !== undefined) {
+      try {
+        // `diagrams` was read with `.map` behind no guard, and a level's `diagram` with `.split`, so a string
+        // or a nameless level escaped as a raw TypeError. The level is the unit a caller writes by hand, so a
+        // missing field has to be named with its position.
+        requireArrayOption(args.diagrams, 'diagrams', 'STRUCTURE_OPTION_INVALID')
+        for (const [index, level] of (args.diagrams as unknown[]).entries()) {
+          if (level === null || typeof level !== 'object' || Array.isArray(level)) continue
+          const entry = level as Record<string, unknown>
+          if (typeof entry.diagram !== 'string') {
+            throw new OptionShapeError('STRUCTURE_OPTION_INVALID', 'diagrams[' + String(index) + '].diagram is ' + (entry.diagram === undefined ? 'missing' : typeof entry.diagram) + ', not a string. Every level needs the diagram text it audits.')
+          }
+          if (typeof entry.name !== 'string' || entry.name === '') {
+            throw new OptionShapeError('STRUCTURE_OPTION_INVALID', 'diagrams[' + String(index) + '].name is ' + (entry.name === undefined ? 'missing' : 'not a non-empty string') + '. The name is how a refinement violation says which level it means.')
+          }
+        }
+        return reviewGranularity({
+          diagrams: args.diagrams as unknown as GranularityDiagram[],
+          notation: (args.notation ?? 'auto') as 'auto' | 'plantuml' | 'mermaid',
+          ...(args.matrix === undefined ? {} : { matrix: args.matrix }),
+        }) as unknown as JsonValue
+      } catch (error) {
+        return optionRefusal(error, 'STRUCTURE_OPTION_INVALID') as unknown as JsonValue
+      }
+    }
+    if (args.diagram === undefined) {
+      return { ok: false, ran: false, verdict: 'fail', verdictReason: 'the tool did not run: pass `diagram` (one structure diagram) or `diagrams` (several levels with parents)', schema: REPORT_SCHEMAS.structure, errorCode: 'UML_INPUT', error: 'structure review needs `diagram` or `diagrams`' } as unknown as JsonValue
+    }
+    return reviewStructure({
+      diagram: args.diagram,
+      notation: (args.notation ?? 'auto') as 'auto' | 'plantuml' | 'mermaid',
+      ...(args.matrix === undefined ? {} : { matrix: args.matrix }),
+    }) as unknown as JsonValue
+  },
+})