dsh-logicprobe 0.8.1 → 1.0.0

package/lib/types/uml.d.ts

@@ -30,6 +30,7 @@
  *
  * @module logicprobe-uml
  */
+import { type HashSpec, type NarrativeCoverage, type ReportSchema, type Verdict } from './engine.js';
 import type { GuardNode, LogicModelV1, UpdateSpec } from './engine.js';
 export type UmlNotation = 'mermaid' | 'plantuml';
 export type UmlDiagram = 'state' | 'activity' | 'sequence';
@@ -52,8 +53,29 @@ export interface UmlParseResult {
      * symbol, which the review reports.
      */
     labels: Record<string, string>;
+    /**
+     * Declarations found in the text that LogicModelV1 cannot represent. A non-empty
+     * list means the parsed model is NOT this diagram: the text belongs to another
+     * diagram family (component, package, class, deployment, …), so whatever came
+     * out is a by-product of reading keywords the parser does not own.
+     */
+    discardedConstructs: DiscardedConstruct[];
+    /**
+     * Arrows whose endpoints were declared by a discarded construct. They survive
+     * parsing as state transitions, which is exactly why they are counted out loud.
+     */
+    discardedEdges: number;
     warnings: string[];
 }
+/** One declaration the parser could not represent, with the source line that carried it. */
+export interface DiscardedConstruct {
+    /** The construct keyword, lower-cased (`component`, `package`, `classDiagram`). */
+    construct: string;
+    /** 1-based line number in the diagram source. */
+    line: number;
+    /** The source line, trimmed. */
+    text: string;
+}
 export interface UmlFinding {
     code: string;
     severity: 'error' | 'warning' | 'info';
@@ -66,18 +88,28 @@ export interface UmlFinding {
         to: string;
     }>;
     detail?: string;
+    /** Machine-readable context for the finding (ids, coverage, rule matches), same shape as the engine's findings. */
+    evidence?: Record<string, unknown>;
 }
 export interface UmlRoundTripReport {
     notation: UmlNotation;
     diagram: UmlDiagram;
     ok: boolean;
+    /** Which published hash specification the two hashes follow (see references/hash-spec.md). */
+    hashSpec: HashSpec;
     modelHash: string;
     parsedHash: string;
     diffs: string[];
     warnings: string[];
 }
 export interface UmlReviewReport {
+    /** The review ran and produced this report. It does NOT mean the modelling passed — read `verdict`. */
     ok: boolean;
+    ran: boolean;
+    verdict: Verdict;
+    verdictReason: string;
+    /** The versioned report contract this result follows. */
+    schema: ReportSchema;
     source: 'model' | 'diagram' | 'model+diagram';
     summary: {
         errors: number;
@@ -98,10 +130,30 @@ export interface UmlReviewReport {
     model?: LogicModelV1;
     /** Diagram rendered from the model, when only a model was given. */
     primary?: string;
+    /** Paths of the `_`-prefixed metadata keys found in the supplied model, when it carried any. */
+    metadataKeys?: string[];
+    /** How much of the model the narrative documents; absent when there is no narrative. */
+    narrativeCoverage?: NarrativeCoverage;
+    /** Hashes of what was reviewed, in one place. */
+    hashes: {
+        hashSpec: HashSpec;
+        modelHash?: string;
+        parsedHash?: string;
+    };
+    /** Declarations the parser could not represent; a non-empty list fails the review. */
+    discardedConstructs?: DiscardedConstruct[];
+    /** Arrows whose endpoints came from a discarded construct. */
+    discardedEdges?: number;
     warnings: string[];
     nextSteps: string[];
 }
+/**
+ * A UML front-end refusal. `code` lets the tool report *why* it refused instead of
+ * collapsing every refusal into a generic input error.
+ */
 export declare class UmlError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
 }
 /** 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;
@@ -124,6 +176,43 @@ export declare function renderUml(input: unknown, notation?: UmlNotation, diagra
 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[];
+/**
+ * Findings a parse result carries on its own. A diagram from another family parses
+ * into something; without this finding that something is presented as a model of the
+ * file, which is a false guarantee of exactly the kind this plugin exists to prevent.
+ */
+export declare function parseFindings(parsed: UmlParseResult): UmlFinding[];
+/** One accepted way of writing a state's meaning into a diagram label. */
+export interface LabelForm {
+    form: string;
+    example: string;
+    note: string;
+}
+export interface LabelExplanation {
+    notation: UmlNotation;
+    /** The comment prefix a `logicprobe:` directive uses in this notation. */
+    directivePrefix: string;
+    directiveLines: Array<{
+        example: string;
+        meaning: string;
+    }>;
+    /** Accepted label spellings, in the order `documentedMeaning` accepts them. */
+    acceptedLabelForms: LabelForm[];
+    /** What the renderer itself writes, so a hand-edited diagram can match it. */
+    renderedForm: string;
+    ignoredLines: Array<{
+        pattern: string;
+        behaviour: string;
+    }>;
+    rules: string[];
+}
+/**
+ * What the front end expects of labels and comments, so "why does my hand-drawn diagram
+ * report label drift or ignored lines?" has a printed answer instead of a guess.
+ * `tests/uml/run.mjs` feeds every claim here back through the parser, so this text cannot
+ * drift away from the behaviour it describes.
+ */
+export declare function explainLabels(notation?: UmlNotation): LabelExplanation;
 /**
  * Parse a Mermaid or PlantUML diagram back into a LogicModelV1.
  *

package/lib/uml-tool.js

@@ -1,5 +1,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { renderUml, parseUml, reviewUml, UmlError } from './uml.js';
+import { createHash } from 'node:crypto';
+import { REPORT_SCHEMAS, DEFAULT_HASH_SPEC, modelHash, refusalVerdict, verdictOf, verdictOfFindings } from './engine.js';
+import { renderUml, parseUml, parseFindings, 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
@@ -15,7 +17,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 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.',
+    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. 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.',
     parameters: {
         action: {
             type: 'string',
@@ -76,13 +78,32 @@ export const logicProbeUmlTool = defineTool({
                 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 };
+                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 };
             }
             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 };
+                // A diagram from another family still parses into *something*. `parseFindings`
+                // says so, and the verdict is what stops that something from being trusted:
+                // `ok: true` only means the parser ran.
+                const findings = parseFindings(result);
+                return {
+                    ok: true,
+                    ran: true,
+                    ...parseVerdict(result, findings),
+                    schema: REPORT_SCHEMAS.umlParse,
+                    action: 'parse',
+                    notation: result.notation,
+                    kind: result.diagram,
+                    model: result.model,
+                    labels: result.labels,
+                    findings,
+                    discardedConstructs: result.discardedConstructs,
+                    discardedEdges: result.discardedEdges,
+                    hashes: { hashSpec: DEFAULT_HASH_SPEC, modelHash: modelHash(result.model), diagram: createHash('sha256').update(args.diagram).digest('hex') },
+                    warnings: result.warnings,
+                };
             }
             const report = reviewUml({
                 model: args.model,
@@ -95,10 +116,18 @@ export const logicProbeUmlTool = defineTool({
             return report;
         }
         catch (error) {
-            return errorResult(error instanceof Error ? error.message : String(error), error instanceof UmlError);
+            const message = error instanceof Error ? error.message : String(error);
+            return errorResult(message, error instanceof UmlError ? error.code : undefined);
         }
     },
 });
-function errorResult(message, isUmlError = false) {
-    return { ok: false, ...(isUmlError ? { errorCode: 'UML_INPUT' } : {}), error: message };
+/** The parse verdict counts parser notes as findings: an ignored line is information the model does not carry. */
+function parseVerdict(result, findings) {
+    const errors = findings.filter((finding) => finding.severity === 'error').length;
+    const warnings = findings.filter((finding) => finding.severity === 'warning').length + result.warnings.length;
+    const firstCode = findings.find((finding) => finding.severity === 'error')?.code ?? findings.find((finding) => finding.severity === 'warning')?.code;
+    return verdictOf(errors, warnings, firstCode);
+}
+function errorResult(message, errorCode = 'UML_INPUT') {
+    return { ok: false, ran: false, ...refusalVerdict(message), errorCode, error: message };
 }