dsh-model-everything 0.0.0-stage → 0.2.0

package/lib/types/uml-interaction-overview.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The interaction overview diagram module.
+ *
+ * An interaction overview is a control-flow graph whose nodes are interactions: a start, a
+ * decision, one or more references to interactions, and a stop. PlantUML has no page for it
+ * and no dedicated type, but the drawing is expressible with the activity diagram's
+ * vocabulary plus a reference node - `start`, `:ref Login sequence;`, `if (ok?) then (yes)`
+ * - which is what the notation research in this repository recorded as the manual form.
+ *
+ * So this family is drawn approximately, like the composite structure and the
+ * communication diagram, and for the same reason the family table used to refuse it on
+ * grounds that were simply wrong ("neither notation spells the inline interaction
+ * references": it does).
+ *
+ * Reading it back is partial, and the parser refuses the part it cannot do. A sequence and
+ * an `if`/`else` are spelled clearly enough to reconstruct. A `fork` is not: the notation
+ * opens a `fork` block, lists the flows, and closes it with `end fork`, and the closing
+ * marker carries no label tying it to the opening one, so nested or adjacent forks cannot
+ * be told apart. Rather than guess, a diagram containing one is refused with that reason.
+ *
+ * @module model-everything-uml-interaction-overview
+ */
+import { type UmlNotation, type UmlFamilyModule, type UmlFamilyParse, type UmlFamilyRender, type UmlFamilyFinding } from './uml-syntax.js';
+/** What a node of the overview is. */
+export type InteractionOverviewNodeKind = 'initial' | 'final' | 'decision' | 'merge' | 'interaction' | 'reference';
+export interface InteractionOverviewNode {
+    id: string;
+    kind: InteractionOverviewNodeKind;
+    /** The interaction this node runs, inline (`interaction`) or by reference (`reference`). */
+    interaction?: string;
+    label?: string;
+}
+export interface InteractionOverviewEdge {
+    from: string;
+    to: string;
+    /** The condition on the branch, as the diagram writes it. */
+    condition?: string;
+}
+/**
+ * An interaction overview diagram as a model.
+ *
+ * The flow is what the diagram is: nodes and the edges between them. `interaction` and
+ * `reference` are kept apart because they are different facts - one is the interaction
+ * written here, the other is a name that points somewhere else and may not exist.
+ */
+export interface InteractionOverviewModelV1 {
+    schemaVersion: 1;
+    nodes: InteractionOverviewNode[];
+    edges: InteractionOverviewEdge[];
+    /** Ids an edge named that no node declaration introduced. */
+    undeclared?: string[];
+    narrative?: {
+        nodes?: Record<string, string>;
+    };
+}
+/**
+ * Validate a candidate model and normalize it.
+ *
+ * One initial node, and every node reachable from it: an overview whose flow starts nowhere
+ * is a drawing, not a flow. That is a refusal rather than a finding because every later
+ * check would be reading a graph with no entry.
+ */
+export declare function validateInteractionOverviewModel(input: unknown): InteractionOverviewModelV1;
+/**
+ * Render an interaction overview as Mermaid.
+ *
+ * Mermaid is the notation this family is drawn in, because the view is an activity graph
+ * and PlantUML's activity syntax is refused by this build (a structured flowchart language
+ * cannot carry a graph with merges or cycles without a while/if reconstruction). A Mermaid
+ * flowchart carries exactly what an overview is: nodes, labelled branches, and a start and
+ * an end.
+ *
+ * @param input - candidate `InteractionOverviewModelV1`.
+ * @param notation - only `mermaid` draws this family.
+ */
+export declare function renderInteractionOverview(input: unknown, notation: UmlNotation): UmlFamilyRender;
+export declare function parseInteractionOverview(_text: string, _notation: UmlNotation): UmlFamilyParse<InteractionOverviewModelV1>;
+export type InteractionOverviewFindingCode = 'UML069_OVERVIEW_NO_INITIAL' | 'UML070_OVERVIEW_NODE_UNREACHABLE' | 'UML071_OVERVIEW_DECISION_ONE_BRANCH' | 'UML072_OVERVIEW_REFERENCE_UNDECLARED' | 'UML073_OVERVIEW_NODE_WITHOUT_INTERACTION' | 'UML074_OVERVIEW_UNDOCUMENTED';
+export declare const INTERACTION_OVERVIEW_FINDING_CODES: readonly InteractionOverviewFindingCode[];
+/**
+ * What a reader would get wrong about an interaction overview.
+ *
+ * The overview's job is to say how the interactions fit together, so the checks are about
+ * the flow being a flow: one way in, every node on some path from it, a decision that
+ * actually decides. Whether the referenced interactions exist is a question about the other
+ * diagrams - this plugin holds no registry of them - so an undeclared reference is reported
+ * as a name nothing here can resolve, not as a missing interaction.
+ */
+export declare function reviewInteractionOverviewModel(model: InteractionOverviewModelV1, labels: Record<string, string>): UmlFamilyFinding[];
+/** The interaction overview family, as the engine's registry expects it. */
+export declare const interactionOverviewModule: UmlFamilyModule<InteractionOverviewModelV1>;

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

@@ -0,0 +1,112 @@
+/**
+ * The profile diagram module.
+ *
+ * A profile is a package that extends the metamodel: stereotypes, the metaclasses they
+ * extend, and the profiles applied to a package. That is a shape of its own, so it has
+ * its own model rather than being flattened into a class diagram.
+ *
+ * PlantUML draws one *approximately*: it has `metaclass` and `stereotype` elements and
+ * `class X <<stereotype>>`, and the relation set of its class diagram, but no `profile`
+ * keyword and no Profile/ProfileApplication element. The drawing is therefore one-way.
+ * Reading the text back would have to guess which `--|>` is a stereotype extending a
+ * metaclass and which is one stereotype specialising another — two different facts about
+ * the profile, drawn identically — so the parse is refused by name instead of inventing
+ * the one the reader cannot see. That refusal is the family table's `parseable: false`.
+ *
+ * @module model-everything-uml-profile
+ */
+import { type UmlNotation, type UmlFamilyModule, type UmlFamilyRender, type UmlFamilyFinding } from './uml-syntax.js';
+/** The profile itself: the package the stereotypes are defined in. */
+export interface ProfileSpec {
+    id: string;
+    label?: string;
+}
+export interface ProfileStereotype {
+    id: string;
+    /** Human-readable name, when the diagram gave one that differs from the id. */
+    label?: string;
+}
+/** `ExtensionEnd` multiplicity, as the specification spells it: `0..1` or `1`. */
+export type ProfileMultiplicity = '0..1' | '1';
+/** A stereotype extending a metaclass: the `Extension` of the metamodel. */
+export interface ProfileExtension {
+    stereotype: string;
+    metaclass: string;
+    /** The composite end's multiplicity. Absent when the diagram did not say. */
+    multiplicity?: ProfileMultiplicity;
+    /** A role name on the extension end, when the profile gave one. */
+    label?: string;
+}
+/** A profile made available to a package: `ProfileApplication`. */
+export interface ProfileApplication {
+    profile: string;
+    /** The package the profile applies to. */
+    applyTo: string;
+}
+/**
+ * A profile diagram as a model.
+ *
+ * `applications` is carried even though this build's renderer leaves it to the
+ * directives: PlantUML has no ProfileApplication element, and a profile whose
+ * application is not written down is a profile nobody can tell is in use.
+ */
+export interface ProfileModelV1 {
+    schemaVersion: 1;
+    profile: ProfileSpec;
+    stereotypes: ProfileStereotype[];
+    metaclasses: ProfileStereotype[];
+    extensions: ProfileExtension[];
+    applications: ProfileApplication[];
+    /** Stereotype-to-stereotype specialisation; a different fact from an extension. */
+    generalizations: Array<{
+        general: string;
+        specific: string;
+    }>;
+    /** Ids a relation named that no declaration introduced; the review reports them. */
+    undeclared?: string[];
+    narrative?: {
+        profile?: string;
+        stereotypes?: Record<string, string>;
+        metaclasses?: Record<string, string>;
+    };
+}
+/**
+ * Validate a candidate model and normalize it.
+ *
+ * The contract every family keeps: an undeclared key or a wrong type is a refusal with
+ * `UML_INPUT`, never a silently dropped field.
+ */
+export declare function validateProfileModel(input: unknown): ProfileModelV1;
+/**
+ * Render a profile as PlantUML.
+ *
+ * The drawing is the approximation the family table declares: stereotypes and
+ * metaclasses as the class diagram draws them, extensions and generalizations both as a
+ * `--|>` because the notation has no second arrow for the first. Everything the drawing
+ * cannot carry — which arrow is which, the extension multiplicity and role, the
+ * applications — is written as a directive, so the text is a faithful record of the
+ * model even though the picture is not.
+ *
+ * @param input - candidate `ProfileModelV1`.
+ * @param notation - only `plantuml` draws a profile; mermaid has no view of this family.
+ */
+export declare function renderProfile(input: unknown, notation: UmlNotation): UmlFamilyRender;
+export type ProfileFindingCode = 'UML050_PROFILE_NO_STEREOTYPES' | 'UML051_PROFILE_UNUSED_STEREOTYPE' | 'UML052_PROFILE_EXTENSION_MISSING' | 'UML053_PROFILE_GENERALIZATION_CYCLE' | 'UML054_PROFILE_UNDECLARED_REFERENCE' | 'UML055_PROFILE_APPLICATION_MISSING' | 'UML056_PROFILE_UNDOCUMENTED';
+export declare const PROFILE_FINDING_CODES: readonly ProfileFindingCode[];
+/**
+ * What a reader would get wrong about a profile.
+ *
+ * The checks read the model alone. Whether a profile is *right* for the metamodel it
+ * extends is a question about the specification being profiled, and this does not answer
+ * it: the codes below are about the profile being internally complete and readable.
+ */
+export declare function reviewProfileModel(model: ProfileModelV1, labels: Record<string, string>): UmlFamilyFinding[];
+/**
+ * The profile family, as the engine's registry expects it.
+ *
+ * `parse` refuses with the family table's own words. It has to exist because the module
+ * contract requires it, and it must refuse rather than return something: a parse would
+ * have to decide which `--|>` is an extension and which is a generalization, and the
+ * notation does not say.
+ */
+export declare const profileModule: UmlFamilyModule<ProfileModelV1>;

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

@@ -0,0 +1,53 @@
+/**
+ * The structure families: class, object, package, component and deployment diagrams.
+ *
+ * A structure diagram is not a machine and not a use case list: it is a graph of
+ * nodes and the edges between them. The five families differ in vocabulary, not in
+ * shape, so they share one module factory and one model.
+ *
+ * Parsing is not reimplemented here. `structure.ts` already reads this text as a
+ * dependency graph, and it is the single source for that reading: this module calls
+ * it, then gives the result the family's name. Reviewing does the same - the graph is
+ * rendered back and handed to `reviewStructure`, so a structure diagram reviewed
+ * through the UML front end and one reviewed through `uml_structure_verify`
+ * report the same defects with the same codes.
+ *
+ * @module model-everything-uml-structure
+ */
+import { type UmlNotation, type UmlFamilyModule, type UmlFamilyParse, type UmlFamilyRender, type UmlFamilyFinding } from './uml-syntax.js';
+export type StructureFamilyId = 'class' | 'object' | 'package' | 'component' | 'deployment';
+export interface StructureModelNode {
+    id: string;
+    /** The declaration the node came from: class, interface, component, node, ... */
+    kind: string;
+    label?: string;
+    /** The container this node was declared inside, when the diagram drew one. */
+    parent?: string;
+}
+export interface StructureModelEdge {
+    from: string;
+    to: string;
+    label?: string;
+}
+/** A structure diagram as a model: the nodes it declares and the edges it draws. */
+export interface StructureModelV1 {
+    schemaVersion: 1;
+    family: StructureFamilyId;
+    nodes: StructureModelNode[];
+    edges: StructureModelEdge[];
+}
+export declare function validateStructureModel(input: unknown, family: StructureFamilyId): StructureModelV1;
+export declare function parseStructureFamily(text: string, notation: UmlNotation, family: StructureFamilyId): UmlFamilyParse<StructureModelV1>;
+export declare function renderStructureFamily(input: unknown, notation: UmlNotation, family: StructureFamilyId): UmlFamilyRender;
+/**
+ * The review is the structure tool's, reached through a render.
+ *
+ * A structure diagram's defects are properties of its graph, and `reviewStructure`
+ * already checks them (isolated node, dangling endpoint, cycle, and the matrix rules
+ * when one is declared). Re-deriving them here would be a second implementation of
+ * the same checks, and the two would drift. So the model is rendered back and handed
+ * over, which also proves the round trip on the way.
+ */
+export declare function reviewStructureFamily(model: StructureModelV1, labels: Record<string, string>, notation: UmlNotation): UmlFamilyFinding[];
+/** One module per structure family: they differ in vocabulary, not in shape. */
+export declare function structureFamilyModule(family: StructureFamilyId): UmlFamilyModule<StructureModelV1>;

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

@@ -0,0 +1,296 @@
+/**
+ * The notation syntax engine.
+ *
+ * One place knows what Mermaid and PlantUML can spell, which UML 2.5 diagram type a
+ * piece of text is, and whether a requested (notation, family, action) cell exists at
+ * all. Family modules know what to do with the elements this engine finds.
+ *
+ * Before this module, detection fell through: any PlantUML text that was not a
+ * sequence diagram went to the state parser. A use case diagram drawn with
+ * `:Actor: --> (UseCase)` came back as a state machine with no finding, which is
+ * the false guarantee this plugin exists to prevent. Detection is now total. A text
+ * either names a family this engine knows, or it is refused by name.
+ *
+ * What lives here:
+ *   - the notation table: comment prefixes, headers, chrome and edge operators;
+ *   - the family table: all fourteen UML 2.5 diagram types, their group, and what each
+ *     notation can express for them;
+ *   - the capability decision: (notation, family, action) -> supported | refusal,
+ *     separate from whether this build implements the family (that is the registry's
+ *     job, in `uml.ts`);
+ *   - notation-agnostic lexical primitives: directives, line scanning, edge splitting,
+ *     identifier and label rules.
+ *
+ * What deliberately does not live here: family semantics. A family module turns the
+ * elements this engine finds into its own model, renders that model back, and reviews
+ * it. `uml-usecase.ts` is the first such module. The machine families (state,
+ * activity) and the trace family (sequence) predate the module contract and keep their
+ * own path in `uml.ts`.
+ *
+ * @module model-everything-uml-syntax
+ */
+/**
+ * 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);
+}
+export type UmlNotation = 'mermaid' | 'plantuml';
+export declare const UML_NOTATIONS: readonly UmlNotation[];
+export declare function isUmlNotation(value: unknown): value is UmlNotation;
+/** Mermaid node ids that cannot stand alone; the renderer aliases around them. */
+export declare const MERMAID_RESERVED_NODE_IDS: ReadonlySet<string>;
+/** Ids a notation can spell without an alias. */
+export declare const UML_PLAIN_ID: RegExp;
+/** Characters that would break a generated label, whichever notation is used. */
+export declare const UML_UNSAFE_LABEL: RegExp;
+/** The comment prefix each notation uses for its dsh-model-everything: directives. */
+export declare function commentPrefix(notation: UmlNotation): string;
+export declare function escapeRegExp(text: string): string;
+export type UmlFamilyId = 'state' | 'activity' | 'sequence' | 'use-case' | 'class' | 'object' | 'package' | 'component' | 'composite-structure' | 'deployment' | 'profile' | 'communication' | 'interaction-overview' | 'timing';
+/**
+ * How faithfully a notation expresses one UML diagram type.
+ *
+ * - `faithful`: the notation models this diagram type; a parse reconstructs it.
+ * - `approximate`: the notation can draw something in this area, but reading it
+ *   back would produce a model of a *different* diagram. Rendering is allowed with a
+ *   warning; parsing is refused.
+ * - `none`: the notation has no view of this diagram type at all.
+ */
+export type UmlFidelity = 'faithful' | 'approximate' | 'none';
+export interface UmlNotationSupport {
+    fidelity: UmlFidelity;
+    /** Header keywords that declare the family outright (Mermaid: `classDiagram`). */
+    headers?: readonly string[];
+    /** Declaration keywords the family owns (PlantUML: `actor`, `usecase`). */
+    declarations?: readonly string[];
+    /** Why the fidelity is what it is, in the words the refusal uses. */
+    note?: string;
+}
+export interface UmlFamilySpec {
+    id: UmlFamilyId;
+    /** English name of the UML 2.5 diagram type. */
+    name: string;
+    /** Chinese name, for the bilingual documentation. */
+    nameZh: string;
+    group: 'structure' | 'behaviour' | 'interaction';
+    /**
+     * True when a faithful parse of this family is a LogicModelV1 the verification
+     * engine can run. False for every structure family and for the trace families.
+     */
+    machine: boolean;
+    /**
+     * False when a parse could not reconstruct the diagram even in a faithful notation.
+     * A sequence diagram is a trace: it shows the paths that were walked, not the
+     * branches that were not.
+     */
+    parseable: boolean;
+    /**
+     * Whether this build can read the family back out of a notation that only approximates
+     * it. Absent means no.
+     *
+     * This is not derivable from the notation's fidelity. `fidelity` says how much of the
+     * specification the drawing carries; this says whether what the model *does* carry
+     * survives a round trip, which is a measurement, not a label. A composite structure is
+     * drawn approximately and reads back exactly - nesting, port direction and both
+     * connector ends are all spelled - while a profile is drawn approximately and cannot be
+     * read back at all. Refusing the first because the second is impossible would leave a
+     * working view switched off.
+     */
+    parseThroughApproximation?: boolean;
+    /** Why a parse is refused, when `parseable` is false. */
+    parseRefusal?: string;
+    /** Code the parse refusal carries; defaults to `UML_NOT_A_STATE_DIAGRAM`. */
+    parseRefusalCode?: string;
+    mermaid?: UmlNotationSupport;
+    plantuml?: UmlNotationSupport;
+}
+/**
+ * The family table. Order matters twice: a Mermaid header is matched in this order,
+ * and a PlantUML declaration keyword is too. The machine families come first because
+ * their headers are the most specific.
+ */
+export declare const UML_FAMILIES: readonly UmlFamilySpec[];
+export declare const UML_FAMILY_IDS: readonly UmlFamilyId[];
+export declare function isUmlFamilyId(value: unknown): value is UmlFamilyId;
+export declare function umlFamilySpec(id: UmlFamilyId): UmlFamilySpec;
+/** What one notation can do with one family. `none` when the table says nothing. */
+export declare function umlNotationSupport(notation: UmlNotation, family: UmlFamilyId): UmlNotationSupport;
+/**
+ * Mermaid headers that name something other than a UML diagram type. Recognizing them
+ * matters: the text must not be reported as "cannot tell whether this is Mermaid or
+ * PlantUML", and it must not be parsed as a state diagram, whose every line would be
+ * ignored or misread. ER, gantt, mindmap and the C4 family are not UML 2.5 diagrams.
+ */
+export declare const FOREIGN_MERMAID_FAMILIES: readonly string[];
+/** The non-UML Mermaid family this text declares, if any. */
+export declare function foreignMermaidFamily(text: string): string | undefined;
+/** Every Mermaid header this engine knows, for the "expected one of" message. */
+export declare function mermaidHeaderList(): string;
+export declare function detectUmlNotation(text: string): UmlNotation;
+export interface UmlFamilyDetection {
+    family: UmlFamilyId;
+    /** The header or keyword that decided it, for the report. */
+    evidence: string;
+}
+export declare function plantumlUseCaseSyntax(text: string): boolean;
+export declare function plantumlTimingSyntax(text: string): boolean;
+export declare function plantumlCompositeSyntax(text: string): boolean;
+export declare function plantumlErSyntax(text: string): boolean;
+export declare function plantumlCommunicationSyntax(text: string): boolean;
+export interface UmlDetectOptions {
+    /** The family a `dsh-model-everything:uml` directive declared, when the text carries one. */
+    hint?: UmlFamilyId;
+}
+/**
+ * Which UML diagram type this text is, in this notation.
+ *
+ * Total by construction: every branch either names a family or throws. A foreign
+ * Mermaid family (ER, gantt, mindmap, C4, ...) is refused by name, so the caller can
+ * report *what* the text is instead of blaming the notation.
+ */
+export declare function detectUmlFamily(text: string, notation: UmlNotation, options?: UmlDetectOptions): UmlFamilyDetection;
+/** The four actions the UML front end offers. */
+export type UmlIntentAction = 'render' | 'parse' | 'review' | 'labels';
+export type UmlCapability = {
+    ok: true;
+    warning?: string;
+} | {
+    ok: false;
+    errorCode: string;
+    message: string;
+};
+export interface UmlCapabilityOptions {
+    /**
+     * Whether this call needs a parse. A review of a *model* in a family the notation can
+     * only approximate does not, and refusing it for a reason that belongs to the diagram
+     * would be refusing the part that works.
+     */
+    requireParse?: boolean;
+}
+/**
+ * Whether this (notation, family, action) cell exists.
+ *
+ * This is the notation's answer, not this build's: a family the table says is faithful
+ * is still refused when no module implements it, and that refusal belongs to the
+ * registry (see `uml.ts`). Keeping the two apart is what lets the engine document
+ * all fourteen diagram types while the implementation lands family by family.
+ */
+export declare function umlCapability(notation: UmlNotation, family: UmlFamilyId, action: UmlIntentAction, options?: UmlCapabilityOptions): UmlCapability;
+/** `umlCapability`, as a throw. */
+export declare function assertUmlCapability(notation: UmlNotation, family: UmlFamilyId, action: UmlIntentAction): UmlCapability;
+export interface UmlFamilyParse<Model> {
+    model: Model;
+    /** Display labels found in the diagram, keyed by element id. */
+    labels: Record<string, string>;
+    warnings: string[];
+    /** Declarations the parser could not represent, with the line that carried them. */
+    discardedConstructs: Array<{
+        construct: string;
+        line: number;
+        text: string;
+    }>;
+    discardedEdges: number;
+}
+export interface UmlFamilyRenderOptions {
+    /** Cap on a trace length, for the families that render one. */
+    maxSteps: number;
+}
+export interface UmlFamilyRender {
+    primary: string;
+    warnings: string[];
+}
+export interface UmlFamilyFinding {
+    code: string;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    detail?: string;
+    evidence?: Record<string, unknown>;
+}
+/**
+ * What a family module must provide. The engine finds the elements; the module gives
+ * them meaning, draws them back, and says what a reader would get wrong.
+ */
+export interface UmlFamilyModule<Model> {
+    id: UmlFamilyId;
+    /**
+     * The notation this family is drawn in, when only one can draw it.
+     *
+     * Absent means "either, as the caller asks", which is true for most families. A family
+     * whose table gives one notation `none` has exactly one answer, and saying it here is
+     * what lets a review of a *model* render the family instead of reporting that the model
+     * cannot be drawn at all.
+     */
+    notation?: UmlNotation;
+    render(input: unknown, notation: UmlNotation, options: UmlFamilyRenderOptions): UmlFamilyRender;
+    parse(text: string, notation: UmlNotation): UmlFamilyParse<Model>;
+    /**
+     * The model in the family's own canonical shape, or undefined when the input is not one.
+     *
+     * Fidelity is checked by rendering a model and comparing what comes back with what went
+     * in. Where the parser necessarily normalizes - filling in a default the diagram always
+     * draws, or recording a drawn name as a label - comparing against the *raw* input reports
+     * the module's own convention as a mismatch. This is how a family says which model the
+     * comparison is about; a family that normalizes nothing can leave it out.
+     */
+    normalize?(input: unknown): Model | undefined;
+    /** Family findings for the review: what the diagram itself gets wrong. */
+    review?(model: Model, labels: Record<string, string>, notation: UmlNotation): UmlFamilyFinding[];
+}
+/** Marker every generated diagram carries; renderers ignore it, the parser uses it. */
+export declare const DIRECTIVE_NAMESPACE = "dsh-model-everything:";
+/** The directive body of a comment line, or null when the line is not a directive. */
+export declare function directiveBody(line: string, notation: UmlNotation): string | null;
+/** One directive line, in the notation's own comment syntax. */
+export declare function directiveLine(notation: UmlNotation, text: string): string;
+export interface UmlDirectives {
+    /** What the `uml v1` header declared, when it carried one. */
+    declared: {
+        notation?: string;
+        family?: string;
+        diagram?: string;
+    };
+    /** Every other directive, keyed by its first word, values in file order. */
+    values: Map<string, string[]>;
+    /** The lines that are not directives. */
+    body: string[];
+}
+/**
+ * Read the `dsh-model-everything:` directives out of a diagram.
+ *
+ * `diagram=` is the pre-family spelling and is still read: a file rendered by an
+ * earlier version must parse the same way it did.
+ */
+export declare function readUmlDirectives(lines: readonly string[], notation: UmlNotation): UmlDirectives;
+/** The family a rendered diagram declares, in either spelling. */
+export declare function declaredFamily(directives: UmlDirectives): UmlFamilyId | undefined;
+export interface UmlSourceLine {
+    /** 1-based line number in the source text. */
+    number: number;
+    /** The line, trimmed. */
+    text: string;
+}
+/**
+ * The content lines of a diagram: blank lines, comments and notation chrome removed,
+ * each with its source line number. Chrome is what a renderer needs and a reader does
+ * not: `@startuml`, `@enduml`, `direction`, `classDef`, `skinparam`,
+ * `scale`, `title`, `hide` and `autonumber`.
+ */
+export declare function umlSourceLines(text: string, notation: UmlNotation, skip?: RegExp): UmlSourceLine[];
+export interface UmlEdgeSplit {
+    from: string;
+    operator: string;
+    to: string;
+    label?: string;
+}
+/**
+ * Split one line into from / operator / to, with a trailing `: label` separated.
+ *
+ * The operator tables are the notation's, not the family's: a class diagram writes
+ * `A <|-- B` and a use case diagram writes `A --> B` in the same notation, and both
+ * come through here. Whether an operator *means* a dependency, an association or a
+ * generalization is the family module's call.
+ */
+export declare function splitUmlEdge(line: string, notation: UmlNotation): UmlEdgeSplit | undefined;