dsh-logicprobe 0.9.0 → 1.1.0

package/lib/types/granularity.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Multi-granularity structure review: one architecture, several levels of detail.
+ *
+ * A module diagram and the repository-wide diagram it belongs to are two views of one
+ * fact, and nothing keeps them in step — the child grows a dependency the parent never
+ * had, or the parent keeps an arrow the child quietly stopped drawing. This module
+ * checks that a child diagram is a **refinement** of its declared parent:
+ *
+ * - every dependency the child draws between two nodes the parent also has must exist in
+ *   the parent (nothing appears out of nowhere);
+ * - an edge the parent draws and the child does not must be *expanded* in the child, i.e.
+ *   a child path must connect the same two ends;
+ * - the declared parent relation must be a forest, not a cycle.
+ *
+ * Every per-diagram structural check still runs, and its findings are tagged with the
+ * diagram they came from (`file`), so one report can carry several diagrams without the
+ * findings becoming anonymous.
+ *
+ * @module logicprobe-granularity
+ */
+import { type Finding, type ReportSchema, type Verdict, type VerdictSummary } from './engine.js';
+import { type StructureNotation } from './structure.js';
+export interface GranularityDiagram {
+    /** Name of this level, e.g. `L2/motion` or `repo`. Referenced by a child's `parent`. */
+    name: string;
+    /** Diagram source text. */
+    diagram: string;
+    /** Name of the diagram this one refines; absent for a root. */
+    parent?: string;
+}
+export interface GranularityOptions {
+    diagrams: GranularityDiagram[];
+    notation?: 'auto' | StructureNotation;
+    /** Optional dependency matrix, applied to every diagram. */
+    matrix?: unknown;
+}
+export interface GranularityEdgeRef {
+    from: string;
+    to: string;
+    line?: number;
+}
+export interface GranularityPairSummary {
+    parent: string;
+    child: string;
+    parentNodes: number;
+    childNodes: number;
+    parentEdges: number;
+    childEdges: number;
+    /** Child edges whose endpoints both exist in the parent and which the parent also draws. */
+    inheritedEdges: number;
+    /** Child edges with at least one endpoint the parent does not have (the refinement's own detail). */
+    newEdges: number;
+    /** Parent edges with no direct child counterpart, but a child path connects the same ends. */
+    expandedEdges: GranularityEdgeRef[];
+    /** Parent edges with no direct counterpart and no connecting path — the refinement lost them. */
+    missingEdges: GranularityEdgeRef[];
+    /** Child edges between two parent nodes that the parent does not draw — invented dependencies. */
+    inventedEdges: GranularityEdgeRef[];
+}
+export interface GranularityDiagramSummary {
+    name: string;
+    parent?: string;
+    notation: StructureNotation;
+    nodes: number;
+    edges: number;
+    verdict: Verdict;
+    findings: number;
+}
+export interface GranularityReport {
+    ok: boolean;
+    ran: boolean;
+    verdict: Verdict;
+    verdictReason: string;
+    schema: ReportSchema;
+    diagrams: GranularityDiagramSummary[];
+    pairs: GranularityPairSummary[];
+    findings: Finding[];
+    summary: {
+        diagrams: number;
+        roots: number;
+        pairs: number;
+        nodes: number;
+        edges: number;
+        inventedEdges: number;
+        missingEdges: number;
+        expandedEdges: number;
+        errors: number;
+        warnings: number;
+    };
+    hashes: {
+        diagrams: Array<{
+            name: string;
+            hash: string;
+        }>;
+    };
+    warnings: string[];
+    nextSteps: string[];
+}
+/**
+ * Review a set of structure diagrams with declared parent relations. Per-diagram
+ * structural checks run first; the cross-diagram refinement checks follow.
+ */
+export declare function reviewGranularity(options: GranularityOptions): GranularityReport;
+/** Deterministic JSON of a granularity report's pair table, for a stable summary line. */
+export declare function granularityDigest(pairs: GranularityPairSummary[]): string;
+export type { VerdictSummary };

package/lib/types/index.d.ts

@@ -1,8 +1,9 @@
 /**
  * logicprobe — DeepSeek Harness native plugin for the Logic Probe toolbox.
- * Injects the session-start gate text (claim-verification doctrine, 1% Rule,
- * Red Flags, proactive suggestion) into the first model step of every agent
- * session, mirroring the SessionStart hook the Claude Code plugin installs.
+ * 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)
+ * 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
  * apply time into dsh's `ctx.skills` registry through the standard filesystem
  * provider, so it appears in every session catalog without a manual copy step.
@@ -16,11 +17,11 @@
  * reminders (skill catalog, AGENTS.md, gate plugins) simply defer this message
  * 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`: behavior rules
- * (1% Rule / Red Flags / proactive suggestion) stay in sync, while
- * presentation is adapted to dsh's native skill catalog — the trigger list
- * lives in the skill description, not duplicated in the gate. Deployments
- * override via Config.
+ * `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.
+ * They stay in sync. Method, doctrine and per-domain detail live in the skills
+ * and their references, not here. Deployments override via Config.
  *
  * @module logicprobe-dsh
  */

package/lib/types/report-diff-tool.d.ts

@@ -0,0 +1,8 @@
+export declare const LOGICPROBE_REPORT_DIFF_TOOL_NAME = "logicprobe_report_diff";
+/**
+ * Model-visible DSH tool that compares two reports of the same family — the accepted
+ * "violations must not increase" acceptance criterion, computed instead of eyeballed.
+ * A finding's identity is its check + code + machine-readable locator, so a reworded
+ * message reads as `changed`, and two runs over the same input add nothing.
+ */
+export declare const logicProbeReportDiffTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

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

@@ -0,0 +1,10 @@
+export declare const LOGICPROBE_STRUCTURE_TOOL_NAME = "logicprobe_structure_verify";
+/**
+ * Model-visible DSH tool that audits a *structure* diagram — components, packages,
+ * classes, deployment nodes and the dependency arrows between them — against an
+ * optional dependency matrix. A structure diagram is not a state machine: this tool
+ * reads the graph the diagram actually draws, instead of refusing it (which is what
+ * `logicprobe_uml action=parse` does) or pretending the arrows are state transitions
+ * (which is what a false `ok` used to hide).
+ */
+export declare const logicProbeStructureTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/types/structure.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Structure-diagram review: a dependency graph is not a state machine.
+ *
+ * The state-machine front end (`uml.ts`) reads a component, package, class or
+ * deployment diagram as a *by-product* and says so (`UML_NOT_A_STATE_DIAGRAM`).
+ * This module reads the same text as what it actually is — a directed graph of
+ * nodes and dependency edges — and audits it against a declared dependency matrix.
+ *
+ * The checks are the structural ones a reader performs by eye and gets wrong:
+ * an isolated node nobody notices, an arrow whose endpoint was never declared, a
+ * dependency cycle, an edge that violates the allowed-dependency matrix, a child
+ * depending on its parent, and an edge the matrix says must exist but the diagram
+ * does not draw. Every finding names the rule id it hit, so the diagram and the
+ * source-side checker can be reconciled rule by rule.
+ *
+ * @module logicprobe-structure
+ */
+import { type Finding, type ReportSchema, type Verdict, type VerdictSummary } from './engine.js';
+export type StructureNotation = 'plantuml' | 'mermaid';
+/** What a node declares itself to be. Containers hold other nodes; they are not dependencies. */
+export type StructureNodeKind = 'component' | 'class' | 'interface' | 'actor' | 'database' | 'node' | 'package' | 'rectangle' | 'cloud' | 'queue' | 'unknown';
+export interface StructureNode {
+    id: string;
+    /** Display label when the declaration carried one (`component "Order Service" as SVC`). */
+    label?: string;
+    kind: StructureNodeKind;
+    /** True when the node is a container (package/rectangle/frame): it owns members and carries no dependency of its own. */
+    container: boolean;
+    /** 1-based line of the declaration. Absent when the node was only ever named by an edge. */
+    line?: number;
+    declared: boolean;
+    /** Container id this node was declared inside, if any. */
+    parent?: string;
+}
+export interface StructureEdge {
+    from: string;
+    to: string;
+    /** Arrow label, e.g. `read` in `PAY --> DRV : read`. */
+    label?: string;
+    line: number;
+}
+export interface StructureGraph {
+    notation: StructureNotation;
+    nodes: StructureNode[];
+    edges: StructureEdge[];
+    warnings: string[];
+}
+/** One dependency rule from the matrix document. */
+export interface StructureRule {
+    id: string;
+    /** Node id or glob the rule applies to; absent = applies to every source. */
+    source?: string;
+    /** Permitted targets (glob or node id). Winning an allow match permits the edge. */
+    allow?: string[];
+    /** Forbidden targets. Deny always wins over allow. */
+    deny?: string[];
+    /** When true, at least one edge matching source→targets must exist (UML025). */
+    require?: boolean;
+}
+export interface StructureLayer {
+    name: string;
+    /** Node ids or globs that belong to this layer. */
+    members: string[];
+}
+/**
+ * The dependency matrix: the single source of truth a diagram is checked against.
+ * `default` decides the fate of an edge no rule mentions (`allow` = only explicit
+ * rules judge, `deny` = anything unlisted is a violation).
+ */
+export interface DependencyMatrix {
+    rules?: StructureRule[];
+    layers?: StructureLayer[];
+    default?: 'allow' | 'deny';
+}
+export interface StructureEdgeVerdict {
+    from: string;
+    to: string;
+    line: number;
+    /** Rule ids whose `source` matched this edge, whether they allowed or denied it. */
+    matchedRules: string[];
+    allowed: boolean;
+    /** `allow` (a rule permitted it), `default` (nothing judged it), `deny` (a rule forbade it), `unlisted` (default=deny and no rule matched). */
+    basis: 'allow' | 'default' | 'deny' | 'unlisted';
+}
+export interface StructureSummary {
+    nodes: number;
+    edges: number;
+    containers: number;
+    isolated: number;
+    dangling: number;
+    cycles: number;
+    disallowedEdges: number;
+    layerViolations: number;
+    missingExpectedEdges: number;
+    errors: number;
+    warnings: number;
+    rules: number;
+}
+export interface StructureReport {
+    /** The tool ran and produced this report; read `verdict` for the outcome. */
+    ok: boolean;
+    ran: boolean;
+    verdict: Verdict;
+    verdictReason: string;
+    /** The versioned report contract this result follows. */
+    schema: ReportSchema;
+    notation: StructureNotation;
+    graph: StructureGraph;
+    /** Per-edge matrix verdict, present only when a matrix was supplied. */
+    edgeVerdicts?: StructureEdgeVerdict[];
+    findings: Finding[];
+    summary: StructureSummary;
+    /** Hashes of the inputs this report is about: the diagram text, and the matrix when one was supplied. */
+    hashes: {
+        diagram: string;
+        matrix?: string;
+    };
+    warnings: string[];
+    nextSteps: string[];
+}
+/** A finding code in the structure family; the numbers continue the UML0xx series after UML019. */
+export type StructureFindingCode = 'UML020_ISOLATED_NODE' | 'UML021_DANGLING_REFERENCE' | 'UML022_CYCLE' | 'UML023_DISALLOWED_EDGE' | 'UML024_LAYER_VIOLATION' | 'UML025_MISSING_EXPECTED_EDGE' | 'UML026_NO_NODES';
+/**
+ * Parse a structure diagram (PlantUML component/package/class/deployment, Mermaid
+ * class diagram) into nodes and dependency edges.
+ *
+ * A structure diagram is *not* refused here: refusing is the state-machine front
+ * end's job (`parseUml`). This parser is the honest reading of the same text.
+ */
+export declare function parseStructure(text: string, notation?: 'auto' | StructureNotation): StructureGraph;
+/** `*` matches any run of characters, `?` exactly one. Ids keep their own punctuation. */
+export declare function globMatches(pattern: string, value: string): boolean;
+export declare function validateMatrix(input: unknown): {
+    ok: true;
+    matrix: DependencyMatrix;
+} | {
+    ok: false;
+    errors: string[];
+};
+/** Shortest directed cycle through the graph, as a node path with the start repeated. */
+export declare function shortestCycle(nodes: string[], edges: StructureEdge[]): string[] | undefined;
+export interface StructureReviewOptions {
+    /** Diagram text to review. */
+    diagram: string;
+    notation?: 'auto' | StructureNotation;
+    /** Dependency matrix: allowed/denied edges, layers, required edges. */
+    matrix?: unknown;
+}
+/**
+ * Audit a structure diagram. Every check is structural: it reads the drawn graph and
+ * the declared matrix, and never claims anything about the code behind them.
+ */
+export declare function reviewStructure(options: StructureReviewOptions): StructureReport;
+/** The finding codes this module can emit, for documentation and tests. */
+export declare const STRUCTURE_FINDING_CODES: readonly StructureFindingCode[];
+export type { VerdictSummary };

package/lib/types/tool.d.ts

@@ -5,7 +5,7 @@ export declare const LOGICPROBE_VERIFY_TOOL_NAME = "logicprobe_verify";
  * the 22-check report (S1-S8 structural, A1-A14), or a 26-check
  * report when beforeModel is supplied (D1 behavioral preservation, D2
  * invariant continuity, D3 regression delta, D4 deadlock/liveness regression).
- * This is the dsh-native replacement for hand-filling the Python template
- * shipped in the skill references.
+ * This is the dsh-native path: the model is built and run here, with no
+ * template to fill in by hand.
  */
 export declare const logicProbeVerifyTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

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.
  *