dsh-model-everything 0.2.0 → 0.4.0

package/src/report-view.ts

@@ -199,6 +199,29 @@ function headerLines(report: Record_, options: Required<ReportViewOptions>): str
     ok === undefined || verdict === undefined ? '' : `ok=${String(ok)}`,
   ].filter((bit) => bit !== '')
   lines.push(bits.join('  '))
+  // A graph report answers "which module is the hub" in one line: counting incoming edges off the graph by
+  // hand is where a correct graph still produced a wrong answer, in both conditions of the round that asked.
+  const degreeSummary = record(report.summary)
+  const hubs = array(degreeSummary?.hubs).map((entry) => record(entry)).filter((entry) => entry !== undefined)
+  if (hubs.length > 0) {
+    const counts = degreeSummary?.nodes !== undefined && degreeSummary?.edges !== undefined ? `  ${String(degreeSummary.nodes)} modules, ${String(degreeSummary.edges)} edges` : ''
+    lines.push(`GRAPH${counts}`)
+    lines.push('  ' + hubs.map((entry) => `${String(entry.id)} (${String(entry.dependents)} dependents)`).join(', '))
+    const leaves = array(degreeSummary?.leaves).map((leaf) => String(leaf))
+    if (leaves.length > 0) lines.push('  imports nothing: ' + leaves.join(', '))
+  }
+  // A scan has to say what it covered, or a model that cannot see the boundary recounts the tree by hand
+  // and spends more than the tool saved. The numbers are the boundary: files read, references resolved.
+  const scan = record(report.scan)
+  if (scan !== undefined) {
+    const files = String(scan.files ?? '?')
+    const unresolved = Number(scan.unresolved ?? 0)
+    const languages = array(scan.languages).map((entry) => String(entry))
+    lines.push(`SCAN  ${files} files read, ${String(unresolved)} unresolved${languages.length === 0 ? '' : ', ' + languages.join(', ')}`)
+    lines.push(unresolved === 0
+      ? '  this is the whole tree: every relative reference resolved, so a recount by hand cannot find more'
+      : '  the unresolved lines above are outside this tree; count nothing twice')
+  }
   // 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.
@@ -259,6 +282,29 @@ function footerLines(report: Record_): string[] {
 }
 
 /** A `checks[]` report (verify, compose, datamodel): silence pass, expand the rest. */
+/**
+ * An edit result: what changed in the model, then what changed in the findings.
+ *
+ * The two belong together because the second is the reason the first happened. The delta is
+ * rendered by the delta renderer rather than restated here, so an edit and a `report_diff` of the
+ * same two reports cannot drift apart.
+ */
+function renderEditReport(report: Record_, options: Required<ReportViewOptions>): string[] {
+  const lines = headerLines(report, options)
+  const changes = array(report.changes).map((value) => record(value) ?? {})
+  const added = changes.filter((change) => text(change.kind) === 'added').length
+  const removed = changes.filter((change) => text(change.kind) === 'removed').length
+  const updated = changes.filter((change) => text(change.kind) === 'updated').length
+  lines.push(`CHANGES  ${String(added)} added, ${String(removed)} removed, ${String(updated)} updated`)
+  for (const change of changes) {
+    const detail = text(change.detail)
+    lines.push(`  ${text(change.kind) ?? '?'} ${text(change.what) ?? '?'}${detail === undefined || detail === '' ? '' : ` — ${detail}`}`)
+  }
+  const delta = record(report.reportDelta)
+  if (delta !== undefined) lines.push('', ...renderDeltaReport(delta, options))
+  return [...lines, ...wrapFooter(report)]
+}
+
 function renderChecksReport(report: Record_, options: Required<ReportViewOptions>): string[] {
   const checks = array(report.checks).map((value) => record(value) ?? {})
   const byStatus = (status: string): string[] =>
@@ -286,7 +332,8 @@ function renderChecksReport(report: Record_, options: Required<ReportViewOptions
     .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 lines = [...headerLines(report, options)]
+  lines.push(`CHECKS  ${inventory}`)
   const requested = options.check
   const ids = checks.map((check) => text(check.id)).filter((id): id is string => id !== undefined)
   const selected = requested === undefined ? checks : checks.filter((check) => text(check.id) === requested)
@@ -470,7 +517,11 @@ export function renderReportText(value: unknown, options: ReportViewOptions = {}
   // 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
+  // An edit result names its changes; the findings it brings along are a delta, which already has a renderer.
+  const isEdit = Array.isArray(report.changes)
+  const lines = isEdit
+    ? renderEditReport(report, resolved)
+    : hasChecks
     ? renderChecksReport(report, resolved)
     : isDelta
       ? renderDeltaReport(report, resolved)

package/src/routing.ts

@@ -0,0 +1,96 @@
+/**
+ * Which tool owns which question, in one table.
+ *
+ * Two consumers read this, and they used to read two different things: the result a model gets
+ * (`nextSteps` naming a sibling) and the toolset map a human reads (hand-written prose). That is how the
+ * map came to say "about ten thousand characters" while the descriptions measured twenty-nine: a fact
+ * stated twice drifts, and nothing fails when it does.
+ *
+ * So the table states the routing once. `routeFor` hands it to the card a UI draws; the toolset map
+ * generator reads the same table and refuses to write a map for a tool that is missing from it.
+ *
+ * What it is not: a decision. The tool a request should use is chosen by the model from the descriptions.
+ * This table says what each tool owns and which neighbour takes the case just outside that line, so a
+ * report can redirect without a reader having to remember the roster.
+ */
+
+export interface Route {
+  /** What this tool decides, in the words its report already uses. */
+  owns: string
+  /** The case just outside the line, and the tool that owns it. */
+  notFor: { when: string; tool: string }
+}
+
+export const ROUTES: Record<string, Route> = {
+  model_verify: {
+    owns: 'one machine: reachable states, invariants, deadlock, and a before/after regression',
+    notFor: { when: 'two or more machines must handshake or share a location', tool: 'model_compose_verify' },
+  },
+  model_compose_verify: {
+    owns: 'several machines run together: rendezvous, shared locations, lost updates',
+    notFor: { when: 'the question is about one machine on its own', tool: 'model_verify' },
+  },
+  model_automaton_verify: {
+    owns: 'a finite-word language, and its relation to another automaton',
+    notFor: { when: 'the question is reachability or deadlock inside one state machine', tool: 'model_verify' },
+  },
+  model_edit: {
+    owns: 'one editing round on a model file, answered with the structural diff and the change in findings',
+    notFor: { when: 'the edit is done and the model has to be decided again', tool: 'model_verify' },
+  },
+  model_datamodel_verify: {
+    owns: 'entities, keys, migrations, and whether the data survived them',
+    notFor: { when: 'the question is about behaviour over time rather than stored state', tool: 'model_verify' },
+  },
+  model_design_review: {
+    owns: "a design's own declarations: layering, responsibility, substitutability, interface width",
+    notFor: { when: 'the question is a fact about the graph - does this edge exist', tool: 'uml_structure_verify' },
+  },
+  model_interleaving_scan: {
+    owns: 'mining a document or plan for concurrency claims, and routing each to the analysis that decides it',
+    notFor: { when: 'the protocol itself has to be decided', tool: 'model_compose_verify' },
+  },
+  model_export: {
+    owns: 'a model translated into UPPAAL, TLA+, PRISM or SPIN for a property this plugin does not decide',
+    notFor: { when: 'the property can be decided here', tool: 'model_verify' },
+  },
+  report_diff: {
+    owns: 'what changed between two reports of the same family',
+    notFor: { when: 'the current report does not exist yet', tool: 'model_verify' },
+  },
+  uml_render: {
+    owns: 'drawing a model in the notation that can carry its family',
+    notFor: { when: 'the question is whether the modelling is sound', tool: 'uml_review' },
+  },
+  uml_parse: {
+    owns: 'reading a diagram back into the model its family declares',
+    notFor: { when: 'the question is whether the diagram says something sound', tool: 'uml_review' },
+  },
+  uml_review: {
+    owns: 'auditing the modelling: reachability, ambiguity, round-trip fidelity, family-specific defects',
+    notFor: { when: 'the claim is about behaviour rather than the drawing', tool: 'model_verify' },
+  },
+  uml_explain_labels: {
+    owns: 'the label spellings a notation accepts and the directives that pin the rest',
+    notFor: { when: 'a diagram has to be read rather than explained', tool: 'uml_parse' },
+  },
+  uml_structure_verify: {
+    owns: 'a dependency graph as a graph - cycles, layers, dangling edges - from a drawing or a source tree',
+    notFor: { when: 'the question is a rule the design declared for itself, not an edge that exists', tool: 'model_design_review' },
+  },
+}
+
+/** The route for a tool, or undefined when the tool has none. */
+export function routeFor(tool: string): Route | undefined {
+  return ROUTES[tool]
+}
+
+/** Every tool a route names, for a caller that has to check the table against the registry. */
+export function routedTools(): string[] {
+  return Object.keys(ROUTES)
+}
+
+/** The tools named as the owner of an adjacent case. */
+export function siblingTools(): string[] {
+  return [...new Set(Object.values(ROUTES).map((route) => route.notFor.tool))].sort()
+}