dsh-logicprobe 1.1.0 → 1.2.0

package/lib/types/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * logicprobe — DeepSeek Harness native plugin for the Logic Probe toolbox.
- * Injects the session-start gate text (what this plugin checks, the 1% Rule,
- * the Red Flags, the routing to the skills, the tool list, how to read a report)
+ * Injects the session-start gate text (what this plugin checks, the routing to
+ * the skills, the tool list, how to read a report)
  * into the first model step of every agent session, mirroring the SessionStart
  * hook the Claude Code plugin installs.
  * The skill ships in this package's `skills/` directory and is registered at
@@ -18,8 +18,9 @@
  * to the first step after their promotion, and the history guard re-injects it
  * there. The default gate text is the dsh-native adaptation of
  * `hooks/session-start-content.md`. Both are a guide to calling the tools: what
- * this plugin checks, the 1% Rule and the Red Flags that raise the chance of a
- * call, the routing to the five skills, the tool list, and how to read a report.
+ * this plugin checks, the routing to the sibling skills, the tool list, and how to
+ * read a report. The Red Flags table is enforcement scaffolding and lives in the
+ * skill body instead, where a session that needs it can load it.
  * They stay in sync. Method, doctrine and per-domain detail live in the skills
  * and their references, not here. Deployments override via Config.
  *

package/lib/types/report-view.d.ts

@@ -0,0 +1,43 @@
+/** Rendering limits. Defaults are the shipped behaviour; tests pin them. */
+export interface ReportViewOptions {
+    /** Maximum finding lines per check. Error findings are never dropped, only warnings are capped. */
+    maxFindingsPerCheck?: number;
+    /** Evidence is inlined for `error` findings only, truncated to this many characters. */
+    maxEvidenceChars?: number;
+    /** Include passing checks' bodies (default false: a passing check carries no actionable finding). */
+    includePassing?: boolean;
+    /**
+     * Print the whole structured report instead of the body. This is the escape hatch for a
+     * caller that must hand the report to another tool verbatim — `logicprobe_report_diff`
+     * matches on check + code + evidence, so a body cannot stand in for the object.
+     */
+    full?: boolean;
+}
+type Record_ = Record<string, unknown>;
+/** One normalized finding. `evidence` is kept because a finding's identity depends on it. */
+export interface ViewFinding {
+    code: string;
+    severity: string;
+    message: string;
+    evidence?: Record_;
+    file?: string;
+    line?: number;
+    check?: string;
+}
+/** Normalize one raw finding. Unknown fields are ignored; a missing message renders as the code. */
+export declare function toViewFinding(value: unknown, check?: string): ViewFinding;
+/**
+ * The fact a finding states, as a comparable key. The verify/datamodel families report the
+ * same (state, event) fact from more than one check, so the key ignores which check said it;
+ * anything else falls back to code + message.
+ */
+export declare function factKey(finding: ViewFinding): string;
+/**
+ * Render any logicprobe result as the text a model reads.
+ *
+ * Order of recognition: a `checks[]` report, a flat `findings[]` report, a baseline delta,
+ * a payload result (`diagram`/`primary`), and finally compact JSON so an unrecognized shape
+ * is still readable rather than silently empty.
+ */
+export declare function renderReportText(value: unknown, options?: ReportViewOptions): string;
+export {};

package/lib/uml-tool.js

@@ -1,146 +1,145 @@
-import { defineTool } from '@deepseek-ai/dsh-tools';
-import { createHash } from 'node:crypto';
-import { REPORT_SCHEMAS, DEFAULT_HASH_SPEC, modelHash, refusalVerdict, verdictOf, verdictOfFindings } from './engine.js';
-import { renderUml, parseUml, parseFindings, reviewUml, explainLabels, 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 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.',
-    parameters: {
-        action: {
-            type: 'string',
-            required: true,
-            enum: ['render', 'parse', 'review', 'explain-labels'],
-            description: 'render = model → UML source; parse = UML source → model; review = audit the modelling (and its fidelity to the model); explain-labels = print the label and comment conventions this parser accepts.',
-        },
-        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, 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');
-                // 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,
-                };
-            }
-            // 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') {
-                const notation = (args.notation === undefined || args.notation === 'auto' ? 'mermaid' : args.notation);
-                return {
-                    ok: true,
-                    ran: true,
-                    ...verdictOf(0, 0),
-                    schema: REPORT_SCHEMAS.umlExplainLabels,
-                    action: 'explain-labels',
-                    ...explainLabels(notation),
-                };
-            }
-            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) {
-            const message = error instanceof Error ? error.message : String(error);
-            return errorResult(message, error instanceof UmlError ? error.code : undefined);
-        }
-    },
-});
-/** 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 };
-}
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { createHash } from 'node:crypto';
+import { REPORT_SCHEMAS, DEFAULT_HASH_SPEC, modelHash, refusalVerdict, verdictOf, verdictOfFindings } from './engine.js';
+import { renderUml, parseUml, parseFindings, reviewUml, explainLabels, UmlError } from './uml.js';
+import { renderReportText } from './report-view.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 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.',
+    parameters: {
+        action: {
+            type: 'string',
+            required: true,
+            enum: ['render', 'parse', 'review', 'explain-labels'],
+            description: 'render = model → UML source; parse = UML source → model; review = audit the modelling (and its fidelity to the model); explain-labels = print the label and comment conventions this parser accepts.',
+        },
+        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.',
+        },
+        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) {
+            // 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', text: renderReportText(value, { full: args.reportView === 'full' }) }];
+        },
+    },
+    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, 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');
+                // 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,
+                };
+            }
+            // 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') {
+                const notation = (args.notation === undefined || args.notation === 'auto' ? 'mermaid' : args.notation);
+                return {
+                    ok: true,
+                    ran: true,
+                    ...verdictOf(0, 0),
+                    schema: REPORT_SCHEMAS.umlExplainLabels,
+                    action: 'explain-labels',
+                    ...explainLabels(notation),
+                };
+            }
+            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) {
+            const message = error instanceof Error ? error.message : String(error);
+            return errorResult(message, error instanceof UmlError ? error.code : undefined);
+        }
+    },
+});
+/** 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 };
+}