dsh-model-everything 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,152 @@
+/**
+ * The timing diagram module.
+ *
+ * A timing diagram is an interaction seen against a clock: which participants exist,
+ * what state each one is in over time, and what they send each other. It is not a
+ * machine and not a trace, so it has its own model — lifelines, the time points they
+ * change state at, the messages between them, and the duration constraints — its own
+ * renderer, and its own review.
+ *
+ * PlantUML is the only notation that draws one. Mermaid has no timing diagram, and the
+ * engine's capability table says so with a reason instead of drawing something else
+ * under the name.
+ *
+ * @module model-everything-uml-timing
+ */
+import { type UmlNotation, type UmlFamilyModule, type UmlFamilyParse, type UmlFamilyRender, type UmlFamilyFinding } from './uml-syntax.js';
+/**
+ * What this module carries out of the PlantUML timing syntax, and what it does not.
+ *
+ * Carried: the lifeline kinds with their `period`, state points and ranges, relative
+ * times, messages with their own time, and the `<->` duration constraints.
+ *
+ * Not carried, and reported as discarded constructs rather than dropped: participant
+ * blocks (`@WB` with per-lifeline times), anchor points (`@XX as :name`), states with
+ * comments or colours (`is Waiting : note`, `is Waiting #LightCyan`), `highlight`,
+ * `note top of`, scale and date axes, `mode compact`, and the `has` state-order
+ * declaration. Each is a real construct of the notation; none of them is a state or a
+ * message, and inventing a model for them would be the fabrication this plugin exists to
+ * refuse.
+ *
+ * The syntax reference is <https://plantuml.com/timing-diagram>.
+ */
+/**
+ * How PlantUML draws a lifeline. The kind is part of the model, not decoration: a
+ * `binary` lifeline can only be in two states, and a `clock` one carries a period.
+ */
+export type TimingLifelineKind = 'robust' | 'concise' | 'binary' | 'clock' | 'analog' | 'rectangle';
+export interface TimingLifeline {
+    id: string;
+    /** Human-readable name, when the diagram gave one that differs from the id. */
+    label?: string;
+    /** Drawing style. Absent means PlantUML's default. */
+    kind?: TimingLifelineKind;
+    /** `clock` only: the period PlantUML draws the clock with. */
+    period?: number;
+}
+/**
+ * One state a lifeline is monitored in, over a half-open time interval `[from, to)`.
+ *
+ * `to` is optional in the input and always written on parse: a state runs until the
+ * next one on the same lifeline begins. Carrying it makes "how long was it in this
+ * state" a property of the model instead of a question about its neighbours.
+ */
+export interface TimingLifelineState {
+    id: string;
+    /** What the state means to a reader, when it is more than the id. */
+    label?: string;
+}
+/**
+ * One stretch of time a lifeline spends in a state, starting at `from`.
+ *
+ * There is no `to`. The PlantUML syntax has no way to say "this state ends here": a
+ * lifeline is a list of changes, so the next change on the same lifeline *is* this
+ * one's end. Carrying an explicit end would be a field the diagram cannot express, and
+ * the round trip would drop it — which is exactly what it did before this field was
+ * removed.
+ */
+export interface TimingSegment {
+    /** The lifeline being monitored. */
+    lifeline: string;
+    /** The state it is in from `from` up to the next state change on the same lifeline. */
+    state: string;
+    from: number;
+    /** PlantUML's `at <time> is <state>`, which marks the left edge as well. */
+    atStart?: boolean;
+}
+export interface TimingMessage {
+    from: string;
+    to: string;
+    time: number;
+    label?: string;
+}
+/** `@a <-> @b : {duration}` between two moments of the timeline. */
+export interface TimingConstraint {
+    fromTime: number;
+    toTime: number;
+    /** The duration text as PlantUML draws it, braces included. */
+    label?: string;
+}
+/**
+ * A timing diagram as a model.
+ *
+ * Times are numbers on one axis for the whole diagram. Their unit is a property of the
+ * diagram (`unit`), not of a point: `{ms}` on one arrow and `{s}` on the next would be
+ * a diagram that cannot be read.
+ */
+export interface TimingModelV1 {
+    schemaVersion: 1;
+    /** The time unit the axis is drawn in, when the diagram declares one. */
+    unit?: string;
+    lifelines: TimingLifeline[];
+    states: TimingLifelineState[];
+    segments: TimingSegment[];
+    messages: TimingMessage[];
+    constraints: TimingConstraint[];
+    /**
+     * Ids a message or a segment named that no declaration introduced. PlantUML accepts
+     * them and draws a bare timeline, which is exactly how a typo stays invisible.
+     */
+    undeclared?: string[];
+    narrative?: {
+        lifelines?: Record<string, string>;
+        states?: Record<string, string>;
+        unit?: string;
+    };
+}
+/**
+ * Validate a candidate model and normalize it.
+ *
+ * The contract other families keep: an undeclared key or a wrong type is a refusal with
+ * `UML_INPUT`, never a silently dropped field. A model that renders into a diagram that
+ * is not the model is worse than no diagram.
+ */
+export declare function validateTimingModel(input: unknown): TimingModelV1;
+/**
+ * Render a timing model as PlantUML.
+ *
+ * @param input - candidate `TimingModelV1`.
+ * @param notation - only `plantuml` draws a timing diagram; another notation is refused
+ *   by the capability table before reaching here.
+ */
+export declare function renderTiming(input: unknown, notation: UmlNotation): UmlFamilyRender;
+/**
+ * Read PlantUML timing text back into a model.
+ *
+ * Two sources are read together, and the diagram wins where they disagree: the diagram
+ * is what a reader sees. The directives carry only what the syntax cannot spell — the
+ * exact state ids, the explicit end of a segment, the unit — so a hand-written diagram
+ * with no directives still parses into a complete model.
+ */
+export declare function parseTiming(text: string, notation: UmlNotation): UmlFamilyParse<TimingModelV1>;
+export type TimingFindingCode = 'UML042_TIMING_NO_LIFELINES' | 'UML043_TIMING_EMPTY_LIFELINE' | 'UML044_TIMING_TIME_ORDER' | 'UML045_TIMING_SIMULTANEOUS_STATES' | 'UML046_TIMING_UNDECLARED_REFERENCE' | 'UML047_TIMING_CONSTRAINT_RANGE' | 'UML048_TIMING_STATE_UNUSED' | 'UML049_TIMING_UNDOCUMENTED';
+export declare const TIMING_FINDING_CODES: readonly TimingFindingCode[];
+/**
+ * What a reader would get wrong about a timing diagram.
+ *
+ * The checks read the model alone: whether a duration is achievable is a question about
+ * the system, not about the diagram, and it is not answered here.
+ */
+export declare function reviewTimingModel(model: TimingModelV1, labels: Record<string, string>): UmlFamilyFinding[];
+/** The timing family, as the engine's registry expects it. */
+export declare const timingModule: UmlFamilyModule<TimingModelV1>;

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

@@ -0,0 +1,12 @@
+export declare const UML_RENDER_TOOL_NAME = "uml_render";
+export declare const UML_PARSE_TOOL_NAME = "uml_parse";
+export declare const UML_REVIEW_TOOL_NAME = "uml_review";
+export declare const UML_LABELS_TOOL_NAME = "uml_explain_labels";
+/** Draw a model as diagram source. */
+export declare const umlRenderTool: import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** Read diagram text into the model of the family it declares. */
+export declare const umlParseTool: import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** Audit the modelling: the diagram, the model, or the two against each other. */
+export declare const umlReviewTool: import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** Print the label and comment contract the parser accepts. */
+export declare const umlExplainLabelsTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

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

@@ -0,0 +1,58 @@
+/**
+ * The use case diagram module.
+ *
+ * A use case diagram is not a machine: it says who uses the system and which services
+ * the system offers, not in what order anything happens. So it has its own model
+ * (actors, use cases, a subject, and the relations between them), its own renderer,
+ * and its own review. Handing this text to the state parser was the bug this module
+ * exists to fix: `:User: --> (Login)` used to come back as a state machine with no
+ * finding at all.
+ *
+ * PlantUML is the only notation that draws one. Mermaid has no use case diagram, and
+ * the engine's capability table says so with a reason instead of rendering something
+ * else under the name.
+ *
+ * @module model-everything-uml-usecase
+ */
+import { type UmlNotation, type UmlFamilyModule, type UmlFamilyParse, type UmlFamilyRender, type UmlFamilyFinding } from './uml-syntax.js';
+export interface UseCaseElement {
+    id: string;
+    /** Human-readable name, when the diagram gave one that differs from the id. */
+    label?: string;
+}
+export type UseCaseRelationKind = 'association' | 'include' | 'extend' | 'generalization';
+export interface UseCaseRelation {
+    /** The element the relation starts at. For a generalization this is the more specific one. */
+    from: string;
+    to: string;
+    kind: UseCaseRelationKind;
+}
+/**
+ * A use case diagram as a model.
+ *
+ * The narrative is optional and holds the same information a reader needs: what each
+ * actor and each use case means in the words of the system being described.
+ */
+export interface UseCaseModelV1 {
+    schemaVersion: 1;
+    /** The system under discussion, when the diagram draws its boundary. */
+    subject?: string;
+    actors: UseCaseElement[];
+    useCases: UseCaseElement[];
+    relations: UseCaseRelation[];
+    /** Ids a relation named that no declaration introduced; the review reports them. */
+    undeclared?: string[];
+    narrative?: {
+        subject?: string;
+        actors?: Record<string, string>;
+        useCases?: Record<string, string>;
+    };
+}
+export declare function validateUseCaseModel(input: unknown): UseCaseModelV1;
+export declare function renderUseCase(input: unknown, notation: UmlNotation): UmlFamilyRender;
+export declare function parseUseCase(text: string, notation: UmlNotation): UmlFamilyParse<UseCaseModelV1>;
+export type UseCaseFindingCode = 'UML030_USE_CASE_NO_ACTORS' | 'UML031_USE_CASE_NO_USE_CASES' | 'UML032_ISOLATED_ACTOR' | 'UML033_USE_CASE_WITHOUT_ACTOR' | 'UML034_DANGLING_RELATION_ENDPOINT' | 'UML035_INCLUDE_EXTEND_CYCLE' | 'UML036_ACTOR_TO_ACTOR_ASSOCIATION' | 'UML037_ACTOR_INCLUDE_EXTEND' | 'UML038_SELF_RELATION' | 'UML039_USE_CASE_UNDOCUMENTED';
+export declare const USE_CASE_FINDING_CODES: readonly UseCaseFindingCode[];
+export declare function reviewUseCaseModel(model: UseCaseModelV1, labels: Record<string, string>): UmlFamilyFinding[];
+/** The use case family, as the engine's registry expects it. */
+export declare const useCaseModule: UmlFamilyModule<UseCaseModelV1>;

package/lib/types/uml.d.ts

@@ -0,0 +1,303 @@
+/**
+ * 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
+ * `dsh-model-everything:` 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 `model_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 model-everything-uml
+ */
+import { type HashSpec, type NarrativeCoverage, type ReportSchema, type Verdict } from './engine.js';
+import type { GuardNode, LogicModelV1, UpdateSpec } from './engine.js';
+import { type UmlNotation, type UmlFamilyId } from './uml-syntax.js';
+import { type UseCaseModelV1 } from './uml-usecase.js';
+import { type StructureModelV1 } from './uml-structure.js';
+import { type TimingModelV1 } from './uml-timing.js';
+import { type ProfileModelV1 } from './uml-profile.js';
+import { type CompositeModelV1 } from './uml-composite.js';
+import { type CommunicationModelV1 } from './uml-communication.js';
+import { type InteractionOverviewModelV1 } from './uml-interaction-overview.js';
+export { UmlError, UML_NOTATIONS } from './uml-syntax.js';
+export type { UmlNotation, UmlFamilyId } from './uml-syntax.js';
+export { validateTimingModel, reviewTimingModel, TIMING_FINDING_CODES, parseTiming, renderTiming } from './uml-timing.js';
+export type { TimingModelV1, TimingSegment, TimingLifeline, TimingFindingCode } from './uml-timing.js';
+export { validateProfileModel, reviewProfileModel, PROFILE_FINDING_CODES, renderProfile, profileModule } from './uml-profile.js';
+export type { ProfileModelV1, ProfileExtension, ProfileApplication, ProfileFindingCode } from './uml-profile.js';
+export { validateCompositeModel, reviewCompositeModel, COMPOSITE_FINDING_CODES, renderComposite, parseComposite, compositeModule } from './uml-composite.js';
+export type { CompositeModelV1, CompositePart, CompositePort, CompositeConnector, CompositeFindingCode } from './uml-composite.js';
+export { validateCommunicationModel, reviewCommunicationModel, COMMUNICATION_FINDING_CODES, renderCommunication, parseCommunication, communicationModule, communicationSequenceOrder } from './uml-communication.js';
+export type { CommunicationModelV1, CommunicationLifeline, CommunicationMessage, CommunicationFindingCode } from './uml-communication.js';
+export { validateInteractionOverviewModel, reviewInteractionOverviewModel, INTERACTION_OVERVIEW_FINDING_CODES, renderInteractionOverview, parseInteractionOverview, interactionOverviewModule } from './uml-interaction-overview.js';
+export type { InteractionOverviewModelV1, InteractionOverviewNode, InteractionOverviewEdge, InteractionOverviewFindingCode } from './uml-interaction-overview.js';
+/**
+ * The diagram families this front end knows, in the engine's order. The name is kept
+ * for callers that already use it: it is now the whole UML 2.5 family list rather
+ * than the three machine views.
+ */
+export type UmlDiagram = UmlFamilyId;
+export declare const UML_DIAGRAMS: readonly UmlDiagram[];
+/**
+ * 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 declare const UML_INTENTS: readonly UmlIntent[];
+/** The tool actions, for the entry check. `labels` is `action=explain-labels`. */
+export type UmlIntentAction = 'render' | 'parse' | 'review' | 'labels';
+export interface UmlRenderResult {
+    notation: UmlNotation;
+    diagram: UmlDiagram;
+    /** The diagram source; hand this to the user or a renderer as-is. */
+    primary: string;
+    warnings: string[];
+}
+/** What a family's parse produces: a LogicModelV1 for the machine families, the family model otherwise. */
+export type UmlFamilyModel = LogicModelV1 | UseCaseModelV1 | StructureModelV1 | TimingModelV1 | ProfileModelV1 | CompositeModelV1 | CommunicationModelV1 | InteractionOverviewModelV1;
+export interface UmlParseResult {
+    notation: UmlNotation;
+    diagram: UmlDiagram;
+    /** Which family model `model` holds. */
+    family: UmlFamilyId;
+    model: UmlFamilyModel;
+    /**
+     * 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>;
+    /**
+     * 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';
+    message: string;
+    states?: string[];
+    events?: string[];
+    transitions?: Array<{
+        from: string;
+        event: string;
+        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';
+    /** Which UML family this review covers. */
+    family?: UmlFamilyId;
+    /** Element counts for a family whose model is not a machine. */
+    familySummary?: {
+        actors?: number;
+        useCases?: number;
+        relations?: number;
+        nodes?: number;
+        edges?: number;
+    };
+    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 (a machine feeds `model_verify`). */
+    model?: UmlFamilyModel;
+    /** 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[];
+}
+/** 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;
+/**
+ * Refuse a view the requested notation cannot draw, before any work. The entry check
+ * every caller already used now asks the engine and the registry.
+ */
+export declare function assertUmlView(notation: UmlNotation, diagram: UmlDiagram): void;
+/**
+ * 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 declare function checkUmlIntent(intent: UmlIntent | undefined, action: UmlIntentAction, view?: {
+    notation: UmlNotation;
+    diagram: UmlDiagram;
+}): void;
+/**
+ * Render a LogicModelV1 as UML.
+ *
+ * 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 declare function renderUml(input: unknown, notation?: UmlNotation, diagram?: UmlDiagram, maxSteps?: number, intent?: UmlIntent): 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[];
+/**
+ * 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 `dsh-model-everything:` 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.
+ *
+ * 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;
+    /** What the review is for; a view that cannot serve it is refused before any work. */
+    intent?: UmlIntent;
+}
+export declare function reviewUml(options: UmlReviewOptions): UmlReviewReport;