dsh-logicprobe 1.1.0 → 1.3.0

package/src/uml-tool.ts

@@ -2,7 +2,8 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import { createHash } from 'node:crypto'
 import type { JsonValue } from './json-value.js'
 import { REPORT_SCHEMAS, DEFAULT_HASH_SPEC, modelHash, refusalVerdict, verdictOf, verdictOfFindings, type VerdictSummary } from './engine.js'
-import { renderUml, parseUml, parseFindings, reviewUml, explainLabels, UmlError, type UmlDiagram, type UmlFinding, type UmlNotation, type UmlParseResult } from './uml.js'
+import { renderUml, parseUml, parseFindings, reviewUml, explainLabels, checkUmlIntent, UmlError, type UmlDiagram, type UmlFinding, type UmlIntent, type UmlNotation, type UmlParseResult } from './uml.js'
+import { renderReportText } from './report-view.js'
 
 export const LOGICPROBE_UML_TOOL_NAME = 'logicprobe_uml'
 
@@ -21,7 +22,7 @@ export const LOGICPROBE_UML_TOOL_NAME = 'logicprobe_uml'
 export const logicProbeUmlTool = defineTool({
   name: LOGICPROBE_UML_TOOL_NAME,
   description:
-    'Model a code flow as UML, and audit the modelling. action="render" turns a LogicModelV1 into diagram source: mermaid (state, activity, sequence) or plantuml (state, sequence). action="parse" reads Mermaid or PlantUML state or activity text back into a LogicModelV1, so a hand-drawn diagram can be verified. A sequence diagram is refused: a trace cannot reconstruct a machine. So is any other diagram family (class, ER, gantt, mindmap). That refusal carries errorCode "UML_NOT_A_STATE_DIAGRAM". A PlantUML component, package or deployment diagram declares no kind, so the parser detects those constructs itself. It returns a by-product model and reports the error UML_NOT_A_STATE_DIAGRAM, with `discardedConstructs` and `discardedEdges`. Never treat that model as a model of the file. action="review" audits the modelling: structural defects (UML002-UML009), documentation gaps (UML010-UML015), and a fidelity check that re-parses the rendered diagram (UML017). Give it a model, a diagram, or both. action="explain-labels" prints the label and comment conventions the parser accepts, without needing a diagram. Rendering never invents structure. A construct the notation cannot express becomes a warning. For dependency questions on a component or class diagram, use `logicprobe_structure_verify` instead. Read `verdict`, not `ok`: error findings mean a failed review.',
+    'Model a code flow as UML, and audit the modelling. action="render" turns a LogicModelV1 into diagram source: mermaid (state, activity, sequence) or plantuml (state, sequence). action="parse" reads Mermaid or PlantUML state or activity text back into a LogicModelV1, so a hand-drawn diagram can be verified. A sequence diagram is refused: a trace cannot reconstruct a machine. So is any other diagram family (class, ER, gantt, mindmap). That refusal carries errorCode "UML_NOT_A_STATE_DIAGRAM". A PlantUML component, package or deployment diagram declares no kind, so the parser detects those constructs itself. It returns a by-product model and reports the error UML_NOT_A_STATE_DIAGRAM, with `discardedConstructs` and `discardedEdges`. Never treat that model as a model of the file. action="review" audits the modelling: structural defects (UML002-UML009), documentation gaps (UML010-UML015), and a fidelity check that re-parses the rendered diagram (UML017). Give it a model, a diagram, or both. action="explain-labels" prints the label and comment conventions the parser accepts, without needing a diagram. Rendering never invents structure. A construct the notation cannot express becomes a warning. For dependency questions on a component or class diagram, use `logicprobe_structure_verify` instead. Declare `intent` (present, verify, fidelity) to say what the artifact is for: a view that cannot serve it is refused before any work, with errorCode UML_INTENT_UNSERVABLE, UML_VIEW_UNREPRESENTABLE or UML_INTENT_MISMATCH. Omit it and nothing changes. Read `verdict`, not `ok`: error findings mean a failed review.',
   parameters: {
     action: {
       type: 'string',
@@ -47,6 +48,11 @@ export const logicProbeUmlTool = defineTool({
       enum: ['state', 'activity', 'sequence'],
       description: 'Diagram kind to render. Default state. sequence is one BFS trace, not the whole machine. PlantUML activity is refused (its structured-flowchart syntax cannot faithfully carry a graph with merges or cycles) — use mermaid for that view.',
     },
+    intent: {
+      type: 'string',
+      enum: ['present', 'verify', 'fidelity'],
+      description: 'What the artifact is for, declared up front: present = a human will read the diagram (any view), verify = it must be parseable into a LogicModelV1 for the engine (state or activity), fidelity = the point is the render-and-reparse proof (review only, state or activity). A view that cannot serve the intent is refused before any work, with errorCode UML_INTENT_UNSERVABLE, UML_VIEW_UNREPRESENTABLE or UML_INTENT_MISMATCH. Omit it and nothing changes: a sequence view is still rendered, and review still reports UML019.',
+    },
     roundTrip: {
       type: 'boolean',
       description: 'review only: render and re-parse the model to prove the diagram carries it. Default true.',
@@ -55,23 +61,21 @@ export const logicProbeUmlTool = defineTool({
       type: 'integer',
       description: 'Cap on the sequence trace length when rendering kind=sequence. Default 60.',
     },
+    reportView: {
+      type: 'string',
+      enum: ['digest', 'full'],
+      description: 'digest (default) prints the diagram or report body; full prints the structured result as JSON.',
+    },
   },
   output: {
     schema: {
       type: 'json',
       description: 'Render result (diagram source), parse result (LogicModelV1 + labels), or the modelling review report with findings, round-trip diff and next steps.',
     },
-    render(_args, value) {
-      const record = value as unknown as Record<string, unknown>
-      // A rendered diagram is source text: print it verbatim so it can be copied
-      // into a file, then the structured result (warnings, notation, kind).
-      if (typeof record.diagram === 'string') {
-        return [
-          { type: 'text' as const, text: record.diagram },
-          { type: 'text' as const, text: JSON.stringify(value, null, 2) },
-        ]
-      }
-      return [{ type: 'text' as const, text: JSON.stringify(value, null, 2) }]
+    render(args, value) {
+      // A rendered diagram is source text: the report body prints it verbatim, once.
+      // Echoing the whole result as JSON printed the same diagram a second time, escaped.
+      return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
     },
   },
   timeoutMs: 10_000,
@@ -80,11 +84,12 @@ export const logicProbeUmlTool = defineTool({
     try {
       if (args.action === 'render') {
         if (args.model === undefined) return errorResult('action=render needs `model` (a LogicModelV1 object)')
-        const result = renderUml(args.model, (args.notation === undefined || args.notation === 'auto' ? 'mermaid' : args.notation) as UmlNotation, (args.kind ?? 'state') as UmlDiagram, args.maxSteps)
+        const result = renderUml(args.model, (args.notation === undefined || args.notation === 'auto' ? 'mermaid' : args.notation) as UmlNotation, (args.kind ?? 'state') as UmlDiagram, args.maxSteps, args.intent as UmlIntent | undefined)
         return { ok: true, ran: true, ...verdictOf(0, result.warnings.length), schema: REPORT_SCHEMAS.umlRender, action: 'render', notation: result.notation, kind: result.diagram, diagram: result.primary, hashes: { diagram: createHash('sha256').update(result.primary).digest('hex') }, warnings: result.warnings } as unknown as JsonValue
       }
       if (args.action === 'parse') {
         if (args.diagram === undefined) return errorResult('action=parse needs `diagram` (Mermaid or PlantUML text)')
+        checkUmlIntent(args.intent as UmlIntent | undefined, 'parse')
         const result = parseUml(args.diagram, args.notation ?? 'auto')
         // A diagram from another family still parses into *something*. `parseFindings`
         // says so, and the verdict is what stops that something from being trusted:
@@ -110,6 +115,7 @@ export const logicProbeUmlTool = defineTool({
       // R9: the label contract was documented in the library and in `explainLabels()`, but no
       // tool exposed it, so it was reachable only by reading the source or the docs.
       if (args.action === 'explain-labels') {
+        checkUmlIntent(args.intent as UmlIntent | undefined, 'labels')
         const notation = (args.notation === undefined || args.notation === 'auto' ? 'mermaid' : args.notation) as UmlNotation
         return {
           ok: true,
@@ -127,6 +133,7 @@ export const logicProbeUmlTool = defineTool({
         diagramKind: (args.kind ?? 'state') as UmlDiagram,
         roundTrip: args.roundTrip,
         maxSteps: args.maxSteps,
+        intent: args.intent as UmlIntent | undefined,
       })
       return report as unknown as JsonValue
     } catch (error) {

package/src/uml.ts

@@ -42,6 +42,20 @@ export const UML_NOTATIONS: readonly UmlNotation[] = ['mermaid', 'plantuml']
 
 export const UML_DIAGRAMS: readonly UmlDiagram[] = ['state', 'activity', 'sequence']
 
+/**
+ * What the caller is going to do with the artifact, declared up front.
+ *
+ * The view follows the question, not the machine, so the tool cannot pick it. What it
+ * can do is refuse a pairing that cannot serve the question — before the work, not as
+ * a finding after it.
+ */
+export type UmlIntent = 'present' | 'verify' | 'fidelity'
+
+export const UML_INTENTS: readonly UmlIntent[] = ['present', 'verify', 'fidelity']
+
+/** The tool actions, for the entry check. `labels` is `action=explain-labels`. */
+export type UmlIntentAction = 'render' | 'parse' | 'review' | 'labels'
+
 /** Marker every generated diagram carries; renderers ignore it, the parser uses it. */
 const DIRECTIVE_NAMESPACE = 'logicprobe:'
 
@@ -401,26 +415,92 @@ function renderSequence(context: RenderContext, notation: UmlNotation, maxSteps:
   return { text: lines.join('\n') + '\n', truncated }
 }
 
+/** What each action hands back, so a declared intent can be matched against it. */
+const ACTION_PRODUCES: Record<UmlIntentAction, string> = {
+  render: 'a diagram',
+  parse: 'a LogicModelV1 read out of a diagram',
+  review: 'an audit of the modelling',
+  labels: 'the label and comment conventions the parser accepts',
+}
+
+/**
+ * The intents each action can serve.
+ *
+ * `fidelity` is a review job: render produces a diagram, and a diagram nothing has
+ * compared back to its model proves nothing about it.
+ */
+const ACTION_INTENTS: Record<UmlIntentAction, readonly UmlIntent[]> = {
+  render: ['present', 'verify'],
+  parse: ['verify'],
+  review: ['present', 'verify', 'fidelity'],
+  labels: [],
+}
+
+/**
+ * The `(notation, view)` cells this module can draw.
+ *
+ * PlantUML activity is the cell that does not exist: its activity syntax is a
+ * structured flowchart language, so a graph with merges or cycles needs a while/if
+ * reconstruction this module does not perform. Refusing is the honest outcome —
+ * quietly emitting a state diagram under an "activity" request would mislabel the
+ * model.
+ */
+export function assertUmlView(notation: UmlNotation, diagram: UmlDiagram): void {
+  if (!UML_NOTATIONS.includes(notation)) throw new UmlError('unknown notation "' + String(notation) + '"; expected ' + UML_NOTATIONS.join(' | '))
+  if (!UML_DIAGRAMS.includes(diagram)) throw new UmlError('unknown diagram "' + String(diagram) + '"; expected ' + UML_DIAGRAMS.join(' | '))
+  if (notation === 'plantuml' && diagram === 'activity') {
+    throw new UmlError('plantuml has no faithful activity view here (its activity syntax is a structured flowchart language; a graph with merges or cycles needs a while/if reconstruction logicprobe does not perform) — use notation "mermaid" for the activity view, or diagram "state"', 'UML_VIEW_UNREPRESENTABLE')
+  }
+}
+
+/**
+ * Refuse, before any work, a request whose declared purpose the view cannot serve.
+ *
+ * Without an intent this changes nothing: the review still reports `UML019` when the
+ * fidelity check does not apply to the view it was given. With one, an impossible
+ * pairing is an error carrying a code, instead of a report about the wrong artifact —
+ * which is the failure this check exists to prevent.
+ *
+ * @param intent - the declared purpose, or `undefined` to leave the behaviour unchanged.
+ * @param action - which action is about to run.
+ * @param view - the requested `(notation, diagram)`, for the actions that have one.
+ */
+export function checkUmlIntent(intent: UmlIntent | undefined, action: UmlIntentAction, view?: { notation: UmlNotation; diagram: UmlDiagram }): void {
+  if (intent === undefined) return
+  if (!UML_INTENTS.includes(intent)) throw new UmlError('unknown intent "' + String(intent) + '"; expected ' + UML_INTENTS.join(' | '))
+  const served = ACTION_INTENTS[action]
+  if (!served.includes(intent)) {
+    throw new UmlError(
+      'intent "' + intent + '" cannot be served by action=' + action + ', which returns ' + ACTION_PRODUCES[action] + '; it serves ' +
+      (served.length === 0 ? 'no intent — leave `intent` off' : served.join(' | ')),
+      'UML_INTENT_MISMATCH')
+  }
+  if (view === undefined) return
+  assertUmlView(view.notation, view.diagram)
+  if (intent === 'present' || view.diagram !== 'sequence') return
+  throw new UmlError(
+    'intent "' + intent + '" needs a machine, and a sequence view is one BFS trace: ' +
+    (intent === 'fidelity'
+      ? 'the render/parse fidelity check does not apply to a trace, so nothing would be proven. Review kind "state" or "activity" to have the diagram checked against the model, and render the trace separately with intent "present".'
+      : '`parse` refuses a trace because it cannot reconstruct a machine, so the diagram cannot feed verification. Model the machine as a state or activity diagram, and render the trace separately with intent "present".'),
+    'UML_INTENT_UNSERVABLE')
+}
+
 /**
  * Render a LogicModelV1 as UML.
  *
- * PlantUML has no faithful activity view here: its activity syntax is a
- * structured flowchart language, so a graph with merges or cycles needs a
- * while/if reconstruction this module does not perform. Refusing is the honest
- * outcome — quietly emitting a state diagram under an "activity" request would
- * mislabel the model. Mermaid covers all three views.
+ * Mermaid covers all three views; PlantUML covers state and sequence (see
+ * `assertUmlView` for why activity is refused).
  *
  * @param input - candidate LogicModelV1.
  * @param notation - `mermaid` (default) or `plantuml`.
  * @param diagram - `state` (default), `activity`, or `sequence`.
  * @param maxSteps - cap on the sequence trace length.
+ * @param intent - what the diagram is for; a view that cannot serve it is refused first.
  */
-export function renderUml(input: unknown, notation: UmlNotation = 'mermaid', diagram: UmlDiagram = 'state', maxSteps = 60): UmlRenderResult {
-  if (!UML_NOTATIONS.includes(notation)) throw new UmlError('unknown notation "' + String(notation) + '"; expected ' + UML_NOTATIONS.join(' | '))
-  if (!UML_DIAGRAMS.includes(diagram)) throw new UmlError('unknown diagram "' + String(diagram) + '"; expected ' + UML_DIAGRAMS.join(' | '))
-  if (notation === 'plantuml' && diagram === 'activity') {
-    throw new UmlError('plantuml has no faithful activity view here (its activity syntax is a structured flowchart language; a graph with merges or cycles needs a while/if reconstruction logicprobe does not perform) — use notation "mermaid" for the activity view, or diagram "state"')
-  }
+export function renderUml(input: unknown, notation: UmlNotation = 'mermaid', diagram: UmlDiagram = 'state', maxSteps = 60, intent?: UmlIntent): UmlRenderResult {
+  assertUmlView(notation, diagram)
+  checkUmlIntent(intent, 'render', { notation, diagram })
   const context = prepareRender(input)
   const warnings = [...context.warnings]
   let primary: string
@@ -1524,6 +1604,8 @@ export interface UmlReviewOptions {
   roundTrip?: boolean
   /** Cap on the sequence trace used for the fidelity check. */
   maxSteps?: number
+  /** What the review is for; a view that cannot serve it is refused before any work. */
+  intent?: UmlIntent
 }
 
 /**
@@ -1549,6 +1631,7 @@ export function reviewUml(options: UmlReviewOptions): UmlReviewReport {
 
   let notation: UmlNotation = options.notation === undefined || options.notation === 'auto' ? 'mermaid' : options.notation
   const kind: UmlDiagram = options.diagramKind ?? 'state'
+  checkUmlIntent(options.intent, 'review', { notation, diagram: kind })
   let model: LogicModelV1 | undefined
   let labels: Record<string, string> | undefined
   let parsed: UmlParseResult | undefined