dsh-logicprobe 0.7.1 → 0.8.0

package/lib/json-value.js

@@ -0,0 +1,18 @@
+/**
+ * Structural mirror of the JSON value union the dsh tool registry accepts.
+ *
+ * `@deepseek-ai/dsh-tools` exported this type through the 0.1.x line and stopped
+ * exporting it in 0.2.x, where the same type now lives in
+ * `@deepseek-ai/dsh-util-values`. This package declares peer support for both
+ * lines, so it cannot import the type from either one without breaking the other
+ * build. Declaring the one-line union here keeps `npm run typecheck` green against
+ * both, and it costs nothing at runtime: every use is a type-only cast on a value
+ * this package already produced.
+ *
+ * Keep it structurally identical to the official type. A cast through `unknown` to
+ * this alias is only a way to satisfy `defineTool`'s return-type constraint; if the
+ * official union ever widens, this alias must widen with it.
+ *
+ * @module logicprobe-json-value
+ */
+export {};

package/lib/types/json-value.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Structural mirror of the JSON value union the dsh tool registry accepts.
+ *
+ * `@deepseek-ai/dsh-tools` exported this type through the 0.1.x line and stopped
+ * exporting it in 0.2.x, where the same type now lives in
+ * `@deepseek-ai/dsh-util-values`. This package declares peer support for both
+ * lines, so it cannot import the type from either one without breaking the other
+ * build. Declaring the one-line union here keeps `npm run typecheck` green against
+ * both, and it costs nothing at runtime: every use is a type-only cast on a value
+ * this package already produced.
+ *
+ * Keep it structurally identical to the official type. A cast through `unknown` to
+ * this alias is only a way to satisfy `defineTool`'s return-type constraint; if the
+ * official union ever widens, this alias must widen with it.
+ *
+ * @module logicprobe-json-value
+ */
+/** JSON-serializable value: null, boolean, number, string, or an array/object of those. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};

package/lib/types/uml-tool.d.ts

@@ -0,0 +1,14 @@
+export declare const LOGICPROBE_UML_TOOL_NAME = "logicprobe_uml";
+/**
+ * DSH tool wrapping the UML front end: model a code flow as a UML diagram
+ * (`action: "render"`), read a UML diagram back into a LogicModelV1
+ * (`action: "parse"`), or review the modelling itself (`action: "review"`).
+ *
+ * review is the half that makes the feature a check rather than a drawing
+ * utility: it reports structural defects the diagram would present as valid
+ * flow (unreachable states, dead ends, ambiguous and non-exhaustive branches,
+ * self-loops with no exit), documentation gaps (a symbol no reader can map back
+ * to code), and — the fidelity check — whether the rendered diagram reads back
+ * as the model it was drawn from.
+ */
+export declare const logicProbeUmlTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/types/uml.d.ts

@@ -0,0 +1,167 @@
+/**
+ * UML front end for LogicModelV1 — model a code flow as a UML diagram, then
+ * review the modelling itself.
+ *
+ * Two halves, one data flow:
+ *
+ *   1. `renderUml` turns a validated LogicModelV1 into Mermaid or PlantUML text
+ *      (state machine, activity/flow, or sequence trace). The diagram is a
+ *      *view*: it never invents structure the model does not have, and anything
+ *      the notation cannot express is reported as a warning instead of being
+ *      dropped silently.
+ *   2. `parseUml` reads that text back into a LogicModelV1, and `reviewUml`
+ *      compares the two. That comparison is the point of the feature: a UML
+ *      diagram of a code flow is itself a model, and a model can be wrong —
+ *      ambiguous branches, dead ends, flows nobody can enter, symbols the
+ *      source never names. A diagram that does not round-trip to the model it
+ *      was drawn from is mis-modelled, and the review says so.
+ *
+ * Why the round trip is the fidelity check: rendering and parsing are inverse
+ * only if every construct survives the notation. The generated text carries
+ * `logicprobe:` directives (ignored by Mermaid/PlantUML renderers) that pin the
+ * initial state, the terminal states and any state id the notation cannot spell
+ * verbatim, so an exact comparison is possible rather than a fuzzy one.
+ *
+ * The review deliberately does NOT replace `logicprobe_verify`: it checks the
+ * modelling (structure the diagram claims, documentation coverage, notation
+ * fidelity), while S1-S8/A1-A14 check the machine's behaviour (guard
+ * exhaustiveness under real valuations, invariant paths, deadlock/liveness in
+ * the runtime state space). Findings name the engine check to run next.
+ *
+ * @module logicprobe-uml
+ */
+import type { GuardNode, LogicModelV1, UpdateSpec } from './engine.js';
+export type UmlNotation = 'mermaid' | 'plantuml';
+export type UmlDiagram = 'state' | 'activity' | 'sequence';
+export declare const UML_NOTATIONS: readonly UmlNotation[];
+export declare const UML_DIAGRAMS: readonly UmlDiagram[];
+export interface UmlRenderResult {
+    notation: UmlNotation;
+    diagram: UmlDiagram;
+    /** The diagram source; hand this to the user or a renderer as-is. */
+    primary: string;
+    warnings: string[];
+}
+export interface UmlParseResult {
+    notation: UmlNotation;
+    diagram: UmlDiagram;
+    model: LogicModelV1;
+    /**
+     * Display labels found in the diagram, keyed by state id. They are how a
+     * reader learns what a symbol means; a missing entry is an undocumented
+     * symbol, which the review reports.
+     */
+    labels: Record<string, string>;
+    warnings: string[];
+}
+export interface UmlFinding {
+    code: string;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    states?: string[];
+    events?: string[];
+    transitions?: Array<{
+        from: string;
+        event: string;
+        to: string;
+    }>;
+    detail?: string;
+}
+export interface UmlRoundTripReport {
+    notation: UmlNotation;
+    diagram: UmlDiagram;
+    ok: boolean;
+    modelHash: string;
+    parsedHash: string;
+    diffs: string[];
+    warnings: string[];
+}
+export interface UmlReviewReport {
+    ok: boolean;
+    source: 'model' | 'diagram' | 'model+diagram';
+    summary: {
+        errors: number;
+        warnings: number;
+        info: number;
+        states: number;
+        events: number;
+        transitions: number;
+        terminalStates: number;
+        reachableStates: number;
+        documentedStates: number;
+    };
+    findings: UmlFinding[];
+    roundTrip: UmlRoundTripReport | null;
+    /** Diagram display labels, when a diagram took part in the review. */
+    labels?: Record<string, string>;
+    /** Model parsed from the diagram, when a diagram was given (feed it to `logicprobe_verify`). */
+    model?: LogicModelV1;
+    /** Diagram rendered from the model, when only a model was given. */
+    primary?: string;
+    warnings: string[];
+    nextSteps: string[];
+}
+export declare class UmlError extends Error {
+}
+/** Canonical guard text. Rendering wraps every composite node in parentheses, and the parser flattens same-operator chains, so render∘parse is the identity. */
+export declare function guardText(node: GuardNode): string;
+/**
+ * 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.
+ *
+ * @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.
+ */
+export declare function renderUml(input: unknown, notation?: UmlNotation, diagram?: UmlDiagram, maxSteps?: number): UmlRenderResult;
+/** Parse a guard expression such as `(retry < 3 && armed == true)`. */
+export declare function parseGuardText(text: string): GuardNode;
+/** Parse a UML action clause such as `retry := retry + 1, armed := true`. */
+export declare function parseUpdatesText(text: string, warnings: string[]): UpdateSpec[];
+/**
+ * Parse a Mermaid or PlantUML diagram back into a LogicModelV1.
+ *
+ * State and activity diagrams carry the whole machine, so they parse into a
+ * complete model. Sequence diagrams do not: a trace shows the paths that were
+ * walked, not the branches that were not, so parsing one would silently prune
+ * the machine. That case is refused rather than approximated.
+ *
+ * @param text - diagram source.
+ * @param notation - `auto` (default) detects Mermaid vs PlantUML from the text.
+ */
+export declare function parseUml(text: string, notation?: UmlNotation | 'auto'): UmlParseResult;
+/** Compare two machines by structure — the fidelity measure behind the round-trip check. */
+export declare function diffModels(left: LogicModelV1, right: LogicModelV1): string[];
+export interface UmlReviewOptions {
+    /** LogicModelV1 to review. Provide it, `diagram`, or both. */
+    model?: unknown;
+    /** Diagram text: reviewed on its own, or compared against `model` when both are given. */
+    diagram?: string;
+    notation?: UmlNotation | 'auto';
+    diagramKind?: UmlDiagram;
+    /** Render-and-reparse fidelity check (default true; only meaningful with a model). */
+    roundTrip?: boolean;
+    /** Cap on the sequence trace used for the fidelity check. */
+    maxSteps?: number;
+}
+/**
+ * Review a UML model of a code flow.
+ *
+ * Three inputs are possible and each answers a different question:
+ *
+ * - `model` only — "is this machine well-modelled?" The review checks the
+ *   structure the diagram would draw, then renders and re-parses it to prove the
+ *   diagram carries the machine faithfully (round trip).
+ * - `diagram` only — "what does this diagram actually say?" The diagram is parsed
+ *   into a model, and that model is reviewed; nothing can be said about fidelity
+ *   to a machine the caller did not provide.
+ * - both — "does this diagram match this model?" Any structural difference is a
+ *   modelling defect and is reported both as round-trip diffs and as a finding.
+ */
+export declare function reviewUml(options: UmlReviewOptions): UmlReviewReport;

package/lib/uml-tool.js

@@ -0,0 +1,104 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { renderUml, parseUml, reviewUml, UmlError } from './uml.js';
+export const LOGICPROBE_UML_TOOL_NAME = 'logicprobe_uml';
+/**
+ * DSH tool wrapping the UML front end: model a code flow as a UML diagram
+ * (`action: "render"`), read a UML diagram back into a LogicModelV1
+ * (`action: "parse"`), or review the modelling itself (`action: "review"`).
+ *
+ * review is the half that makes the feature a check rather than a drawing
+ * utility: it reports structural defects the diagram would present as valid
+ * flow (unreachable states, dead ends, ambiguous and non-exhaustive branches,
+ * self-loops with no exit), documentation gaps (a symbol no reader can map back
+ * to code), and — the fidelity check — whether the rendered diagram reads back
+ * as the model it was drawn from.
+ */
+export const logicProbeUmlTool = defineTool({
+    name: LOGICPROBE_UML_TOOL_NAME,
+    description: 'Model a code flow as UML, and review the modelling. action="render" turns a LogicModelV1 (schemaVersion=1) into diagram source: notation mermaid (state | activity flowchart | sequence) or plantuml (state | sequence). action="parse" reads Mermaid/PlantUML state or activity text back into a LogicModelV1 (plus the display labels it found), so a hand-drawn diagram can be verified with logicprobe_verify; a sequence diagram is refused because a trace cannot reconstruct a machine. action="review" audits the modelling: structural defects (UML002 unreachable state, UML003 dead end, UML004 ambiguous branch, UML005 overlapping guard, UML006 inexhaustive branch, UML007 unused event, UML008 self-loop with no exit, UML009 duplicate transition), documentation gaps (UML010 unused variable, UML011 unbounded variable, UML012 no terminal, UML013 no narrative, UML014 undocumented state, UML015 label drift), and the fidelity check — the diagram is rendered and re-parsed and any structural difference is reported as UML017 round-trip mismatch. Give review a model (checks it, renders and re-parses it), a diagram (parses and reviews that), or both (checks the diagram against the model). Rendering never invents structure and never silently drops a construct the notation cannot express: those become warnings. Review does NOT replace logicprobe_verify — it covers the modelling, not behaviour; findings name the engine check to run next.',
+    parameters: {
+        action: {
+            type: 'string',
+            required: true,
+            enum: ['render', 'parse', 'review'],
+            description: 'render = model → UML source; parse = UML source → model; review = audit the modelling (and its fidelity to the model).',
+        },
+        model: {
+            type: 'json',
+            description: 'LogicModelV1 machine. Required for render; accepted by review (alone, or next to diagram to check the two against each other).',
+        },
+        diagram: {
+            type: 'string',
+            description: 'UML source text. Required for parse; accepted by review.',
+        },
+        notation: {
+            type: 'string',
+            enum: ['auto', 'mermaid', 'plantuml'],
+            description: 'Diagram language. Default auto: detected from the text for parse/review, mermaid for render.',
+        },
+        kind: {
+            type: 'string',
+            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.',
+        },
+        roundTrip: {
+            type: 'boolean',
+            description: 'review only: render and re-parse the model to prove the diagram carries it. Default true.',
+        },
+        maxSteps: {
+            type: 'integer',
+            description: 'Cap on the sequence trace length when rendering kind=sequence. Default 60.',
+        },
+    },
+    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;
+            // 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', text: record.diagram },
+                    { type: 'text', text: JSON.stringify(value, null, 2) },
+                ];
+            }
+            return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+        },
+    },
+    timeoutMs: 10_000,
+    isConcurrencySafe: () => true,
+    async execute(args) {
+        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), (args.kind ?? 'state'), args.maxSteps);
+                return { ok: true, action: 'render', notation: result.notation, kind: result.diagram, diagram: result.primary, warnings: result.warnings };
+            }
+            if (args.action === 'parse') {
+                if (args.diagram === undefined)
+                    return errorResult('action=parse needs `diagram` (Mermaid or PlantUML text)');
+                const result = parseUml(args.diagram, args.notation ?? 'auto');
+                return { ok: true, action: 'parse', notation: result.notation, kind: result.diagram, model: result.model, labels: result.labels, warnings: result.warnings };
+            }
+            const report = reviewUml({
+                model: args.model,
+                diagram: args.diagram,
+                notation: args.notation ?? 'auto',
+                diagramKind: (args.kind ?? 'state'),
+                roundTrip: args.roundTrip,
+                maxSteps: args.maxSteps,
+            });
+            return report;
+        }
+        catch (error) {
+            return errorResult(error instanceof Error ? error.message : String(error), error instanceof UmlError);
+        }
+    },
+});
+function errorResult(message, isUmlError = false) {
+    return { ok: false, ...(isUmlError ? { errorCode: 'UML_INPUT' } : {}), error: message };
+}