dsh-model-everything 0.4.0 → 0.5.0

package/src/diagram-diff-tool.ts

@@ -0,0 +1,94 @@
+/**
+ * The structural diff tool: two drawings, compared by containment.
+ *
+ * One job per file: this module declares the tool and nothing else, so the documentation generator that walks
+ * `*-tool` modules finds it, and so a change to the drawing never touches the reviewing.
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { render, type Notation } from './render/index.js'
+import { diffStructure } from './render/diff.js'
+
+export const DIAGRAM_DIFF_TOOL_NAME = 'diagram_diff'
+
+/** Parse one side of a comparison, reporting which side failed to produce a drawing. */
+function sideOf(source: string, notation: Notation | 'auto', which: 'before' | 'after'): { diagram?: ReturnType<typeof render>['diagram']; refused: string[]; problem?: string } {
+  if (source.trim() === '') return { refused: [], problem: which + ' is empty: pass the diagram text for that side' }
+  const rendered = render({ source, notation })
+  if (rendered.diagram.nodes.length === 0) {
+    return { refused: rendered.refused, problem: which + ' produced no nodes (' + String(rendered.refused.length) + ' line(s) refused)' }
+  }
+  return { diagram: rendered.diagram, refused: rendered.refused }
+}
+
+export const diagramDiffTool = defineTool({
+  name: DIAGRAM_DIFF_TOOL_NAME,
+  description:
+    'Compare the containment structure of two diagrams: which boundaries are new or gone, which were renamed, which moved inside another, and which nodes changed owner. Accepts the same Mermaid and PlantUML subset as diagram_render. This decides what moved, never whether the move is better - read `verdict`, never `ok`. It does not diff report files (report_diff does) and it does not draw (diagram_render does).',
+  parameters: {
+    before: {
+      type: 'string',
+      description: 'The earlier diagram source.',
+    },
+    after: {
+      type: 'string',
+      description: 'The later diagram source.',
+    },
+    notation: {
+      type: 'string',
+      enum: ['auto', 'mermaid', 'plantuml'],
+      description: 'Which notation both sides are written in. Default auto: decided per side from its first meaningful line.',
+    },
+  },
+  output: {
+    schema: { type: 'json', description: 'Structural diff: the verdict, every change with the id it is about, and the sizes of both sides.' },
+    render(_args, value) {
+      const report = value as Record<string, unknown>
+      const changes = Array.isArray(report.changes) ? (report.changes as Array<Record<string, unknown>>) : []
+      const measured = (report.measured ?? {}) as Record<string, Record<string, number>>
+      const lines: string[] = []
+      lines.push('dsh-diagram/diff/v1  verdict=' + String(report.verdict) + '  ' + String(changes.length) + ' change(s)')
+      lines.push(
+        'MEASURED  before=' + String(measured.before?.nodes) + ' node(s)/' + String(measured.before?.groups) + ' group(s)' +
+          '  after=' + String(measured.after?.nodes) + ' node(s)/' + String(measured.after?.groups) + ' group(s)',
+      )
+      for (const change of changes) lines.push('  [' + String(change.severity) + '/' + String(change.code) + '] ' + String(change.message))
+      if (changes.length === 0) lines.push('NEXT  The structure is unchanged. That is all this compares: node text, edges and guards are not part of it.')
+      else lines.push('NEXT  Read each change against the design intent: a move is a decision, and this tool only reports that it happened.')
+      return [{ type: 'text' as const, text: lines.join('\n') }]
+    },
+  },
+  timeoutMs: 10_000,
+  isConcurrencySafe: () => true,
+  async execute(args: { before?: unknown; after?: unknown; notation?: unknown }) {
+    const notation = args.notation === 'mermaid' || args.notation === 'plantuml' ? (args.notation as Notation) : 'auto'
+    const before = sideOf(typeof args.before === 'string' ? args.before : '', notation, 'before')
+    const after = sideOf(typeof args.after === 'string' ? args.after : '', notation, 'after')
+    const problems = [before.problem, after.problem].filter((problem): problem is string => problem !== undefined)
+    if (before.diagram === undefined || after.diagram === undefined) {
+      return {
+        ok: false,
+        verdict: 'fail' as const,
+        changes: problems.map((problem) => ({ code: 'D1_SIDE_UNREADABLE', severity: 'error', kind: 'removed', subject: '-', message: problem })),
+        measured: {
+          before: { nodes: before.diagram?.nodes.length ?? 0, groups: before.diagram?.groups?.length ?? 0 },
+          after: { nodes: after.diagram?.nodes.length ?? 0, groups: after.diagram?.groups?.length ?? 0 },
+        },
+      }
+    }
+    const report = diffStructure(before.diagram, after.diagram)
+    return {
+      ok: report.verdict !== 'fail',
+      verdict: report.verdict,
+      changes: report.changes.map((change) => ({
+        code: change.code,
+        severity: change.severity,
+        kind: change.kind,
+        subject: change.subject,
+        message: change.message,
+      })),
+      measured: report.measured,
+    }
+  },
+})
+

package/src/diagram-render-tool.ts

@@ -0,0 +1,108 @@
+/**
+ * The drawing tool: source text in, SVG out.
+ *
+ * One job per file: this module declares the tool and nothing else, so the documentation generator that walks
+ * `*-tool` modules finds it, and so a change to the drawing never touches the reviewing.
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { render, type Notation } from './render/index.js'
+import { schemeNames, type PaletteScheme } from './render/palette.js'
+import { writeSvg } from './render/write.js'
+
+export const DIAGRAM_TOOL_NAME = 'diagram_render'
+
+export const diagramRenderTool = defineTool({
+  name: DIAGRAM_TOOL_NAME,
+  description:
+    'Draw a diagram from its source text and get back SVG. Accepts Mermaid (flowchart, stateDiagram) and PlantUML (component, package, state) for the subset this renderer draws, lays out boxes and arrows itself, and reports every line it refused with its line number instead of drawing half a diagram. Pass `out` to write the SVG next to a document. This tool draws; it does not parse a diagram back into a model, and it does not review one - uml_parse and uml_review do that.',
+  parameters: {
+    source: {
+      type: 'string',
+      description: 'The diagram source text, in Mermaid or PlantUML syntax.',
+    },
+    notation: {
+      type: 'string',
+      enum: ['auto', 'mermaid', 'plantuml'],
+      description: 'Which notation `source` is written in. Default auto: read from the first meaningful line.',
+    },
+    title: {
+      type: 'string',
+      description: 'The heading drawn above the diagram. Defaults to the component configuration.',
+    },
+    scheme: {
+      type: 'string',
+      enum: schemeNames(),
+      description: 'Colour scheme. Default: the standard light palette. print is greyscale, for a drawing that will be printed or embedded in a plain document.',
+    },
+    out: {
+      type: 'string',
+      description: 'Write the SVG here and report the path. Relative paths resolve against the session workspace.',
+    },
+  },
+  output: {
+    schema: { type: 'json', description: 'Drawing result: the notation used, the counts, every refused line, and the SVG markup.' },
+    render(_args, value) {
+      const result = value as Record<string, unknown>
+      const lines: string[] = []
+      const refused = Array.isArray(result.refused) ? (result.refused as string[]) : []
+      lines.push(
+        'dsh-diagram/v1  notation=' + String(result.notation) + '  nodes=' + String(result.nodes) + '  edges=' + String(result.edges) +
+          (Number(result.groups) > 0 ? '  groups=' + String(result.groups) : '') +
+          (result.path === undefined ? '' : '  written=' + String(result.path)),
+      )
+      lines.push('CAPTION  ' + String(result.caption))
+      if (refused.length > 0) {
+        lines.push('')
+        lines.push('REFUSED  ' + String(refused.length) + ' line(s) - the drawing covers the rest')
+        for (const line of refused) lines.push('  ' + line)
+        lines.push('NEXT  Fix or delete the refused lines, or render them in a tool that supports them. The drawing you got does not show them.')
+      } else {
+        lines.push('NEXT  Every line was drawn. Paste the SVG where the diagram belongs, or pass `out` to write it next to the document.')
+      }
+      return [{ type: 'text' as const, text: lines.join('\n') }]
+    },
+  },
+  timeoutMs: 10_000,
+  isConcurrencySafe: () => true,
+  async execute(args: { source?: unknown; notation?: unknown; title?: unknown; out?: unknown; scheme?: unknown }) {
+    const source = typeof args.source === 'string' ? args.source : ''
+    if (source.trim() === '') {
+      // One shape for every answer, so the output contract has nothing to special-case.
+      return {
+        ok: false,
+        notation: 'mermaid',
+        nodes: 0,
+        edges: 0,
+        groups: 0,
+        caption: 'no source',
+        refused: ['source is empty: pass the diagram text to draw'],
+        dropped: 0,
+        svg: '',
+      }
+    }
+    const notation = args.notation === 'mermaid' || args.notation === 'plantuml' ? (args.notation as Notation) : 'auto'
+    const title = typeof args.title === 'string' && args.title.trim() !== '' ? args.title.trim() : undefined
+    // The argument validator has already held this to the shipped schemes; an unknown value falls back rather
+    // than throwing, because a stale deployment may still send one.
+    const scheme = schemeNames().includes(args.scheme as PaletteScheme) ? (args.scheme as PaletteScheme) : 'default'
+    const rendered = render({ source, notation, ...(title === undefined ? {} : { title }) }, {}, { scheme })
+    const written =
+      typeof args.out === 'string' && args.out.trim() !== ''
+        ? writeSvg({ source, notation, ...(title === undefined ? {} : { title }) }, args.out.trim(), {}, { scheme })
+        : undefined
+
+    return {
+      ok: rendered.refused.length === 0,
+      notation: rendered.notation,
+      nodes: rendered.diagram.nodes.length,
+      edges: rendered.diagram.edges.length,
+      groups: rendered.diagram.groups?.length ?? 0,
+      caption: rendered.diagram.caption,
+      refused: rendered.refused,
+      dropped: rendered.dropped,
+      ...(written === undefined ? {} : { path: written.path, bytes: written.bytes }),
+      svg: rendered.markup,
+    }
+  },
+})

package/src/diagram-review-tool.ts

@@ -0,0 +1,109 @@
+/**
+ * The structural review tool: budgets against one drawing.
+ *
+ * One job per file: this module declares the tool and nothing else, so the documentation generator that walks
+ * `*-tool` modules finds it, and so a change to the drawing never touches the reviewing.
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { render, type Notation } from './render/index.js'
+import { checkBudget, DEFAULT_LIMITS, type BudgetLimits } from './render/budget.js'
+
+export const DIAGRAM_REVIEW_TOOL_NAME = 'diagram_review'
+
+/** Read the three caps a caller may override, ignoring anything that is not a positive number. */
+function limitsOf(args: { maxMembers?: unknown; maxDepth?: unknown; maxNodes?: unknown }): BudgetLimits {
+  const pick = (value: unknown, fallback: number): number =>
+    typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback
+  return {
+    maxMembers: pick(args.maxMembers, DEFAULT_LIMITS.maxMembers),
+    maxDepth: pick(args.maxDepth, DEFAULT_LIMITS.maxDepth),
+    maxNodes: pick(args.maxNodes, DEFAULT_LIMITS.maxNodes),
+  }
+}
+
+export const diagramReviewTool = defineTool({
+  name: DIAGRAM_REVIEW_TOOL_NAME,
+  description:
+    'Review the structure of a diagram from its source text: how wide each boundary is, how deep they nest, and how many nodes the drawing holds, against budgets you can set. Accepts the same Mermaid and PlantUML subset as diagram_render and reports what it measured, so an empty report cannot be mistaken for a clean one. Read `verdict`, never `ok`. This reviews structure; it does not draw (diagram_render does) and it does not check behaviour (model_verify does).',
+  parameters: {
+    source: {
+      type: 'string',
+      description: 'The diagram source text, in Mermaid or PlantUML syntax.',
+    },
+    notation: {
+      type: 'string',
+      enum: ['auto', 'mermaid', 'plantuml'],
+      description: 'Which notation `source` is written in. Default auto: read from the first meaningful line.',
+    },
+    maxMembers: {
+      type: 'integer',
+      description: 'How many direct children a boundary may hold. Default 7: more than a handful of boxes stops reading as a package.',
+    },
+    maxDepth: {
+      type: 'integer',
+      description: 'How deep boundaries may nest. Default 3.',
+    },
+    maxNodes: {
+      type: 'integer',
+      description: 'How many nodes the whole drawing may hold. Default 40.',
+    },
+  },
+  output: {
+    schema: { type: 'json', description: 'Structural review: the verdict, one finding per breached budget, and what was measured.' },
+    render(_args, value) {
+      const report = value as Record<string, unknown>
+      const findings = Array.isArray(report.findings) ? (report.findings as Array<Record<string, unknown>>) : []
+      const measured = (report.measured ?? {}) as Record<string, unknown>
+      const lines: string[] = []
+      lines.push(
+        'dsh-diagram/review/v1  verdict=' + String(report.verdict) + '  ' + String(findings.length) + ' finding(s)',
+      )
+      lines.push(
+        'MEASURED  nodes=' + String(measured.nodes) + '  groups=' + String(measured.groups) + '  deepest=' + String(measured.deepest) +
+          (measured.widest === null || measured.widest === undefined ? '' : '  widest=' + JSON.stringify(measured.widest)),
+      )
+      for (const finding of findings) {
+        lines.push('  [' + String(finding.severity) + '/' + String(finding.code) + '] ' + String(finding.message))
+      }
+      for (const line of Array.isArray(report.refused) ? (report.refused as string[]) : []) {
+        lines.push('  refused ' + line)
+      }
+      if (findings.length === 0) lines.push('NEXT  The drawing is inside every budget. That says nothing about whether the system it describes is right.')
+      else lines.push('NEXT  Split or fold the groups named above, or raise the budget if the medium is larger than a conversation pane.')
+      return [{ type: 'text' as const, text: lines.join('\n') }]
+    },
+  },
+  timeoutMs: 10_000,
+  isConcurrencySafe: () => true,
+  async execute(args: { source?: unknown; notation?: unknown; maxMembers?: unknown; maxDepth?: unknown; maxNodes?: unknown }) {
+    const source = typeof args.source === 'string' ? args.source : ''
+    const notation = args.notation === 'mermaid' || args.notation === 'plantuml' ? (args.notation as Notation) : 'auto'
+    if (source.trim() === '') {
+      return {
+        ok: false,
+        verdict: 'fail' as const,
+        findings: [{ code: 'D0_NO_SOURCE', severity: 'error', message: 'source is empty: pass the diagram text to review' }],
+        measured: { nodes: 0, groups: 0, deepest: 0, widest: null },
+        refused: [],
+      }
+    }
+    const rendered = render({ source, notation })
+    const report = checkBudget(rendered.diagram, limitsOf(args))
+    return {
+      ok: report.verdict !== 'fail',
+      verdict: report.verdict,
+      // Plain JSON fields: a finding whose `group` is absent must not carry an undefined key.
+      findings: report.findings.map((finding) => ({
+        code: finding.code,
+        severity: finding.severity,
+        message: finding.message,
+        ...(finding.group === undefined ? {} : { group: finding.group }),
+      })),
+      measured: report.measured,
+      refused: rendered.refused,
+    }
+  },
+})
+
+

package/src/diagram.ts

@@ -0,0 +1,61 @@
+/**
+ * The diagram component: one row, one switch, three tools.
+ *
+ * A separate component rather than a feature of the tools above it, because drawing has nothing to do with
+ * verifying. It can be on while the tools are off, off while they are on, and it carries no engine: a
+ * deployment that only wants pictures of its Mermaid diagrams installs the same package and leaves the rest of
+ * it alone.
+ *
+ * The switch is `config.enabled`, live, exactly like the routing gate: a deployment can turn the drawing off at
+ * boot, from the Plugins page, or by disabling this row, and none of those touches the tools or the skills.
+ */
+
+import z from '@deepseek-ai/schemastery'
+import { diagramDiffTool } from './diagram-diff-tool.js'
+import { diagramRenderTool } from './diagram-render-tool.js'
+import { diagramReviewTool } from './diagram-review-tool.js'
+
+/** The default a deployment inherits: on, because a component nobody knows about is a component nobody uses. */
+const DEFAULT_ENABLED = true
+
+/**
+ * A live boolean, or a plain one on a host that predates the live wrapper.
+ *
+ * `live` is what makes the Plugins page switch take effect without a restart; the value it returns is read
+ * through {@link enabledOf} rather than compared, because both shapes have been seen in the wild.
+ */
+const liveBoolean = (z as unknown as { live?: (schema: unknown) => unknown }).live
+
+export interface Config {
+  /** Whether the diagram tools are registered. Read through {@link enabledOf}. */
+  enabled: unknown
+  /** The title a drawing carries when the caller did not name one. */
+  defaultTitle: string
+}
+
+export const Config = z.object({
+  enabled:
+    liveBoolean === undefined
+      ? z.boolean().default(DEFAULT_ENABLED)
+      : (liveBoolean(z.boolean().default(DEFAULT_ENABLED)) as never),
+  defaultTitle: z.string().default('diagram'),
+})
+
+/** Read the switch as a boolean, whichever shape this host produced. */
+export function enabledOf(config: Config): boolean {
+  const value = config.enabled as boolean | { get: () => boolean }
+  return typeof value === 'boolean' ? value : value.get()
+}
+
+export interface ComponentContext {
+  tools: { register(definition: unknown): () => void }
+}
+
+export function apply(ctx: ComponentContext, config: Config): void {
+  if (!enabledOf(config)) return
+  ctx.tools.register(diagramRenderTool)
+  ctx.tools.register(diagramReviewTool)
+  ctx.tools.register(diagramDiffTool)
+}
+
+export const inject = ['tools']

package/src/gate.ts

@@ -68,6 +68,7 @@ const SKILL_ROWS: Record<string, string> = {
   'model-everything-design': 'layering, responsibilities, substitutability, interface width',
   'model-everything-datamodel': 'a schema, a migration, a data guarantee',
   'model-everything-interleaving': 'thread-safe, lock-free, ISR, async interleaving; a shared location is decided, the rest is routed',
+  'model-everything-diagram': 'drawing, sizing or diffing a diagram from its source text',
   'model-everything-report-reading': 'reading a report this plugin returned',
 }
 
@@ -108,11 +109,11 @@ export function renderGateText(skills: string[] = shippedSkills(), extraGuidance
   const rows = skills.map((skill) => '| ' + (SKILL_ROWS[skill] ?? 'see its catalog line') + ' | `' + skill + '` |')
   const extra = extraGuidance.trim()
   return `<EXTREMELY_IMPORTANT>
-Before answering anything about code, a design or a diagram: load the skill whose row matches, and let its tool decide. Do not answer from memory first.
+Before answering anything about code, a design or a diagram: load the skill whose row matches and let its tool decide. Do not answer from memory.
 
-Plugin dsh-model-everything is active. It checks claims about designs and code: facts against the source, behaviour as an executable model, structure as a graph.
+dsh-model-everything is active: it checks claims about designs and code - facts against the source, behaviour as a model, structure as a graph.
 
-**Unsure which row applies?** Load \`model-everything\` first: it owns the doctrine, the model schema and the routing to its siblings.
+**Unsure which row applies?** Load \`model-everything\` first: it owns the doctrine, the schema and the routing to its siblings.
 
 | The request | The skill |
 | --- | --- |
@@ -120,22 +121,23 @@ ${rows.join('\n')}
 
 **Tools** (dsh):
 
-- \`model_verify\` — one state machine: structural checks, adversarial probes, budgets, deadlines, before/after regression.
+- \`model_verify\` — one state machine: structural checks, adversarial probes, budgets, deadlines, regression.
 - \`model_compose_verify\` — two or more machines: deadlock, a rendezvous that never fires, and - with \`shared\` + \`accesses\` - an unordered write (C4) or a non-atomic update (C5).
-- \`model_datamodel_verify\` — a data model and its migration: keys, domains, migration coverage, copy consistency, rollback symmetry.
-- \`model_design_review\` — a design against its own declarations: layering, boundaries, substitutability, interface width. The graph's shape is reported, not judged.
-- \`model_interleaving_scan\` — finds claims about threads, synchronization, async and interrupts, names the family, and routes each to the tool that decides it. It proves nothing about any of them.
-- \`model_export\` — UPPAAL, TLA+, PRISM or SPIN input from a verified model. It exports; it does not check the target tool.
-- \`uml_render\`, \`uml_parse\`, \`uml_review\` — draw a model, read a diagram into one, audit one. Round-trip fidelity is measured, never assumed.
+- \`model_datamodel_verify\` — a data model and its migration: keys, domains, coverage, copy consistency, rollback symmetry.
+- \`model_design_review\` — a design against its own declarations: layering, boundaries, substitutability, interface width. Graph shape is reported, not judged.
+- \`model_interleaving_scan\` — finds claims about threads, async and interrupts, names the family and routes each to what decides it. It proves nothing itself.
+- \`model_export\` — UPPAAL, TLA+, PRISM or SPIN input from a model. It exports; it does not check the target.
+- \`uml_render\`, \`uml_parse\`, \`uml_review\` — draw a model, read a diagram into one, audit one. Round-trip fidelity is measured.
 - \`uml_explain_labels\` — the accepted label and comment forms for one notation.
 - \`uml_structure_verify\` — dependency review of a structure drawing, one level or several. It audits the drawing, not the code.
+- \`diagram_render\`, \`diagram_review\`, \`diagram_diff\` — draw, size and compare a Mermaid or PlantUML source. Undrawable lines are refused by number.
 - \`report_diff\` — baseline against current: what a change added, removed or changed.
 
-**Read a report**: gate on \`verdict\` (\`pass\`, \`pass_with_findings\`, \`fail\`), never on \`ok\`. \`verdictReason\` says why and \`nextSteps\` says what to do. \`ran\` says whether it executed, \`checksRun\` how much it examined: a \`skip\` is not a \`pass\`, and a code ending \`_UNDECIDED\` means the search hit its limit and decided nothing. Keys starting with \`_\` are notes: ignored, and left out of the model hash.
+**Read a report**: gate on \`verdict\`, never on \`ok\`. \`verdictReason\` says why and \`nextSteps\` says what to do. \`ran\` says whether it executed, \`checksRun\` how much it examined: a \`skip\` is not a \`pass\`, and a code ending \`_UNDECIDED\` means the search hit its limit and decided nothing. Keys starting with \`_\` are notes: ignored, and left out of the model hash.
 
-**When a tool refuses, or is not there.** Read its \`errorCode\` and fix the input before retrying; if the tool is not registered in this deployment, say so and use the general method. A check that nothing ran is not a passing check.${extra === '' ? '' : '\n\n' + extra}
+**When a tool refuses or is absent.** Read its \`errorCode\` and fix the input; if it is not registered here, say so and use the general method. A check that nothing ran is not a passing check.${extra === '' ? '' : '\n\n' + extra}
 
-The rule again, because it is the one that gets skipped: before answering anything about code, a design or a diagram, load the skill whose routing applies and let its tool decide - a claim you can check is not a claim you may answer from memory.
+The rule again, because it is the one that gets skipped: load the skill whose routing applies and let its tool decide - a claim you can check is not one you may answer from memory.
 </EXTREMELY_IMPORTANT>`
 }
 

package/src/presentation.ts

@@ -53,6 +53,8 @@ export interface ReportCard {
   graph?: { nodes: number; edges: number; cycles: number; isolated: number; dangling: number }
   /** `model_design_review`: three levels, because a signal is not a violation and a fact is neither. */
   levels?: { violations: number; signals: number; facts: number; skipped: number }
+  /** `uml_structure_verify` with `repoPath`: what the scan itself resolved, and what it could not. */
+  scan?: { files: number; unresolved: number; packages: number; dynamic: number }
   /** `model_interleaving_scan`: how many claims were found, and in which families. */
   claims?: { absolute: number; keywords: number; families: Array<{ family: string; count: number }> }
 }
@@ -109,6 +111,7 @@ export function reportCard(value: unknown, family: string): ReportCard {
   const errors = findings.filter((entry) => severity(entry) === 'error')
   const warnings = findings.filter((entry) => severity(entry) === 'warning')
   const summary = record(report.summary)
+  const scan = record(report.scan)
   const summaryErrors = typeof summary?.errors === 'number' ? summary.errors : undefined
   const summaryWarnings = typeof summary?.warnings === 'number' ? summary.warnings : undefined
   const checksRun = typeof summary?.checksRun === 'number'
@@ -156,6 +159,9 @@ export function reportCard(value: unknown, family: string): ReportCard {
     ...(violations.length === 0 && signals.length === 0 && facts.length === 0
       ? {}
       : { levels: { violations: violations.length, signals: signals.length, facts: facts.length, skipped: array(report.checksSkipped).length } }),
+    ...(typeof scan?.files === 'number'
+      ? { scan: { files: scan.files, unresolved: Number(scan.unresolved ?? 0), packages: Number(scan.packages ?? 0), dynamic: Number(scan.dynamic ?? 0) } }
+      : {}),
     ...(typeof summary?.absoluteClaims === 'number'
       ? { claims: { absolute: summary.absoluteClaims, keywords: Number(summary.keywords ?? 0), families: claimFamilies(findings) } }
       : {}),
@@ -309,6 +315,12 @@ export function structureCardBlocks(card: ReportCard): ContentBlock[] {
   if (card.graph !== undefined) {
     lines.push('graph: ' + String(card.graph.nodes) + ' nodes · ' + String(card.graph.edges) + ' edges · ' + String(card.graph.cycles) + ' cycle(s) · ' + String(card.graph.isolated) + ' isolated')
   }
+  if (card.scan !== undefined) {
+    // A scan that resolved half its imports reads the same as one that resolved all of them unless the
+    // counts are on the card.
+    const dynamic = card.scan.dynamic > 0 ? ' · ' + String(card.scan.dynamic) + ' computed' : ''
+    lines.push('scan: ' + String(card.scan.files) + ' file(s) · ' + String(card.scan.unresolved) + ' unresolved · ' + String(card.scan.packages) + ' package(s)' + dynamic)
+  }
   if (card.first != null) lines.push((card.first.severity === 'error' ? '✗ ' : '⚠ ') + card.first.code + ': ' + card.first.message)
   if (card.next != null) lines.push('next: ' + card.next)
   return [{ type: 'text', text: lines.join(String.fromCharCode(10)) }]

package/src/render/budget.ts

@@ -0,0 +1,135 @@
+/**
+ * Structural budgets for a diagram: the checks a drawing can fail without being wrong.
+ *
+ * A diagram is not verified the way a state machine is - there is no deadlock to find - but an architecture
+ * picture has properties a reader relies on, and they are checkable: a package that holds twenty things is not
+ * communicating anything, a boundary around one box is a layer the source did not mean, a group nothing points
+ * into and nothing leaves is a group that belongs on another page.
+ *
+ * Pure: a diagram and a set of limits in, findings out. The limits are arguments, not constants, because what
+ * counts as too wide depends on the medium - a slide holds less than a scrollable tab.
+ */
+
+import type { Diagram, DiagramGroup } from './model.js'
+
+export type Severity = 'error' | 'warning'
+
+export interface BudgetFinding {
+  code: string
+  severity: Severity
+  message: string
+  /** The group the finding is about, when it is about one. */
+  group?: string
+}
+
+export interface BudgetLimits {
+  /** How many direct children a boundary may hold: its own nodes plus the groups directly inside it. */
+  maxMembers: number
+  /** How deep boundaries may nest. */
+  maxDepth: number
+  /** How many nodes the whole drawing may hold. */
+  maxNodes: number
+}
+
+/**
+ * Defaults, chosen for a drawing read in a conversation pane: a package with more than a handful of boxes stops
+ * being a package and becomes a diagram of its own, and three levels is what fits on one screen before a reader
+ * needs the source.
+ */
+export const DEFAULT_LIMITS: BudgetLimits = { maxMembers: 7, maxDepth: 3, maxNodes: 40 }
+
+export interface BudgetReport {
+  verdict: 'pass' | 'pass_with_findings' | 'fail'
+  findings: BudgetFinding[]
+  /** What was measured, so a reader can tell "nothing to check" from "checked and clean". */
+  measured: { nodes: number; groups: number; deepest: number; widest: { group: string; size: number } | null }
+}
+
+/** The direct children of a boundary: its own nodes plus the groups that name it as parent. */
+function childrenOf(groups: DiagramGroup[], group: DiagramGroup): number {
+  const nested = groups.filter((entry) => entry.parent === group.id).length
+  return group.members.length + nested
+}
+
+/** How deep the nesting goes, guarding against a parent cycle in the data. */
+function depthOf(groups: DiagramGroup[], groupId: string): number {
+  const byId = new Map(groups.map((group) => [group.id, group] as const))
+  let depth = 1
+  let cursor = byId.get(groupId)?.parent
+  const seen = new Set<string>([groupId])
+  while (cursor !== undefined && !seen.has(cursor)) {
+    seen.add(cursor)
+    depth += 1
+    cursor = byId.get(cursor)?.parent
+  }
+  return depth
+}
+
+/**
+ * Measure a drawing against its limits.
+ *
+ * Every finding names the group it is about, because a budget report that says "a group is too wide" without
+ * saying which one is a report nobody can act on.
+ */
+export function checkBudget(diagram: Diagram, limits: Partial<BudgetLimits> = {}): BudgetReport {
+  const caps: BudgetLimits = { ...DEFAULT_LIMITS, ...limits }
+  const groups = diagram.groups ?? []
+  const findings: BudgetFinding[] = []
+
+  const nodeIds = new Set(diagram.nodes.map((node) => node.id))
+  for (const group of groups) {
+    const size = childrenOf(groups, group)
+    const depth = depthOf(groups, group.id)
+    if (size > caps.maxMembers) {
+      findings.push({
+        code: 'B1_GROUP_TOO_WIDE',
+        severity: 'error',
+        group: group.id,
+        message: 'group "' + group.label + '" holds ' + String(size) + ' direct children; the budget is ' + String(caps.maxMembers),
+      })
+    }
+    if (depth > caps.maxDepth) {
+      findings.push({
+        code: 'B2_TOO_DEEP',
+        severity: 'error',
+        group: group.id,
+        message: 'group "' + group.label + '" nests ' + String(depth) + ' levels deep; the budget is ' + String(caps.maxDepth),
+      })
+    }
+    const realMembers = group.members.filter((member) => nodeIds.has(member))
+    if (realMembers.length === 0 && groups.every((entry) => entry.parent !== group.id)) {
+      findings.push({
+        code: 'B3_EMPTY_GROUP',
+        severity: 'error',
+        group: group.id,
+        message: 'group "' + group.label + '" holds nothing that is drawn, so the boundary claims a containment the drawing does not show',
+      })
+    }
+    if (size === 1) {
+      findings.push({
+        code: 'B4_SINGLE_MEMBER',
+        severity: 'warning',
+        group: group.id,
+        message: 'group "' + group.label + '" holds one child; a boundary around one thing usually means a layer that was never split',
+      })
+    }
+  }
+
+  if (diagram.nodes.length > caps.maxNodes) {
+    findings.push({
+      code: 'B5_TOO_MANY_NODES',
+      severity: 'error',
+      message: 'the drawing holds ' + String(diagram.nodes.length) + ' nodes; the budget is ' + String(caps.maxNodes),
+    })
+  }
+
+  const deepest = groups.reduce((max, group) => Math.max(max, depthOf(groups, group.id)), 0)
+  const widest = groups.reduce<{ group: string; size: number } | null>((best, group) => {
+    const size = childrenOf(groups, group)
+    return best === null || size > best.size ? { group: group.label, size } : best
+  }, null)
+
+  const errors = findings.filter((finding) => finding.severity === 'error').length
+  const verdict: BudgetReport['verdict'] = errors > 0 ? 'fail' : findings.length > 0 ? 'pass_with_findings' : 'pass'
+  return { verdict, findings, measured: { nodes: diagram.nodes.length, groups: groups.length, deepest, widest } }
+}