@coral-viz/language 0.2.3

package/LICENSE

@@ -0,0 +1,4 @@
+Copyright 2026 Coral contributors
+
+Licensed under the Apache License, Version 2.0. You may obtain a copy at
+https://www.apache.org/licenses/LICENSE-2.0

package/README.md

@@ -0,0 +1,5 @@
+# @coral-viz/language
+
+Portable Coral DSL parsing, deterministic printing, and Mermaid, DOT, and
+PlantUML import. See the [Coral repository](https://github.com/coreyt/coral)
+for usage and release documentation.

package/dist/diagnostics.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Diagnostics channel (R-011).
+ *
+ * Parsers, importers and the printer report what they could not represent, not
+ * only what stopped them. One builder constructs every `ParseResult`, so the
+ * relationship between `diagnostics`, `errors` and `success` is structural
+ * rather than a convention repeated at nineteen construction sites.
+ */
+import type { GraphIR, ParseError, ParseResult } from './types.js';
+export type DiagnosticSeverity = 'error' | 'warning' | 'info';
+/**
+ * A source location.
+ *
+ * Named `SourcePosition` rather than `Position` because `Position` is already
+ * re-exported from `@graph-ir/core` as the `{ x, y }` of node geometry.
+ */
+export interface SourcePosition {
+    line: number;
+    column: number;
+    offset: number;
+}
+/** The IR element a loss attaches to, when one is known. */
+export interface DiagnosticSubject {
+    kind: 'node' | 'edge' | 'graph';
+    id: string;
+}
+/**
+ * A diagnostic with no inherent source location — what the printer produces,
+ * since a graph has no line numbers.
+ */
+export interface Diagnostic {
+    severity: DiagnosticSeverity;
+    /** `<producer>.<construct>.<disposition>`; the construct may itself be dotted. */
+    code: string;
+    message: string;
+    position?: SourcePosition;
+    /** Verbatim source slice that was dropped or degraded. */
+    source?: string;
+    subject?: DiagnosticSubject;
+    hint?: string;
+}
+/**
+ * A diagnostic from a parser, which always knows where it is.
+ *
+ * Extends `ParseError` as well as `Diagnostic` and mirrors `position` into the
+ * flat `line`/`column`/`offset` fields, because `ParseError` is flat and the
+ * derived `errors` view must stay assignable to `ParseError[]` without a cast
+ * while remaining element-identical to the entries in `diagnostics`.
+ */
+export interface ParseDiagnostic extends Diagnostic, ParseError {
+    position: SourcePosition;
+}
+/** Options for constructing a single parse diagnostic. */
+export interface ParseDiagnosticInput {
+    severity: DiagnosticSeverity;
+    code: string;
+    message: string;
+    position: SourcePosition;
+    source?: string;
+    subject?: DiagnosticSubject;
+    hint?: string;
+}
+/**
+ * Build a parse diagnostic, mirroring the position into the flat fields.
+ *
+ * This is the only place a `ParseDiagnostic` is constructed, so the mirror
+ * cannot drift from the nested position.
+ */
+export declare function parseDiagnostic(input: ParseDiagnosticInput): ParseDiagnostic;
+/** Build a printer diagnostic, which carries no position. */
+export declare function printDiagnostic(input: Omit<Diagnostic, 'position'>): Diagnostic;
+/**
+ * Construct a `ParseResult` from accumulated diagnostics.
+ *
+ * `success` is derived from the absence of errors, so a warning never fails a
+ * parse; `errors` is the error-severity view of `diagnostics`, element-identical
+ * and in the same order; both arrays are frozen so neither can be desynchronised
+ * from the other.
+ */
+export declare function finishParse(diagnostics: ParseDiagnostic[], graph?: GraphIR): ParseResult;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEnE,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAChC,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAgB,SAAQ,UAAU,EAAE,UAAU;IAC7D,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED,0DAA0D;AAC1D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,eAAe,CAc5E;AAED,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,GAAG,UAAU,CAE/E;AAWD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,eAAe,EAAE,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW,CAWxF"}

package/dist/diagnostics.js

@@ -0,0 +1,59 @@
+/**
+ * Diagnostics channel (R-011).
+ *
+ * Parsers, importers and the printer report what they could not represent, not
+ * only what stopped them. One builder constructs every `ParseResult`, so the
+ * relationship between `diagnostics`, `errors` and `success` is structural
+ * rather than a convention repeated at nineteen construction sites.
+ */
+/**
+ * Build a parse diagnostic, mirroring the position into the flat fields.
+ *
+ * This is the only place a `ParseDiagnostic` is constructed, so the mirror
+ * cannot drift from the nested position.
+ */
+export function parseDiagnostic(input) {
+    const { position } = input;
+    return {
+        severity: input.severity,
+        code: input.code,
+        message: input.message,
+        position,
+        line: position.line,
+        column: position.column,
+        offset: position.offset,
+        ...(input.source !== undefined ? { source: input.source } : {}),
+        ...(input.subject !== undefined ? { subject: input.subject } : {}),
+        ...(input.hint !== undefined ? { hint: input.hint } : {}),
+    };
+}
+/** Build a printer diagnostic, which carries no position. */
+export function printDiagnostic(input) {
+    return { ...input };
+}
+/** Order by line, then column, then offset. */
+function bySourcePosition(a, b) {
+    return (a.position.line - b.position.line ||
+        a.position.column - b.position.column ||
+        a.position.offset - b.position.offset);
+}
+/**
+ * Construct a `ParseResult` from accumulated diagnostics.
+ *
+ * `success` is derived from the absence of errors, so a warning never fails a
+ * parse; `errors` is the error-severity view of `diagnostics`, element-identical
+ * and in the same order; both arrays are frozen so neither can be desynchronised
+ * from the other.
+ */
+export function finishParse(diagnostics, graph) {
+    const ordered = Object.freeze([...diagnostics].sort(bySourcePosition));
+    const errors = Object.freeze(ordered.filter((d) => d.severity === 'error'));
+    const success = errors.length === 0;
+    return {
+        success,
+        ...(graph !== undefined ? { graph } : {}),
+        errors: errors,
+        diagnostics: ordered,
+    };
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA+DH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAA2B;IACzD,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IAC3B,OAAO;QACL,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,QAAQ;QACR,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1D,CAAC;AACJ,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,eAAe,CAAC,KAAmC;IACjE,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;AACtB,CAAC;AAED,+CAA+C;AAC/C,SAAS,gBAAgB,CAAC,CAAkB,EAAE,CAAkB;IAC9D,OAAO,CACL,CAAC,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI;QACjC,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM;QACrC,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,CACtC,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,WAA8B,EAAE,KAAe;IACzE,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACvE,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC;IAEpC,OAAO;QACL,OAAO;QACP,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,MAAM,EAAE,MAAiC;QACzC,WAAW,EAAE,OAAuC;KACrD,CAAC;AACJ,CAAC"}

package/dist/formats/dot.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Graphviz DOT Importer
+ *
+ * Converts Graphviz DOT syntax to Graph-IR.
+ * Supports: digraph, graph, subgraph/cluster
+ *
+ * DOT syntax reference:
+ * - digraph G { A -> B; }
+ * - graph G { A -- B; }
+ * - Node attributes: A [label="Label", shape=box];
+ * - Edge attributes: A -> B [label="flow"];
+ * - Clusters: subgraph cluster_name { ... }
+ */
+import type { ParseResult } from '../types.js';
+export interface DotParseOptions {
+    graphId?: string;
+    graphName?: string;
+}
+/**
+ * Parse Graphviz DOT syntax into Graph-IR
+ */
+export declare function parseDot(source: string, options?: DotParseOptions): ParseResult;
+//# sourceMappingURL=dot.d.ts.map

package/dist/formats/dot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dot.d.ts","sourceRoot":"","sources":["../../src/formats/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAIV,WAAW,EAGZ,MAAM,aAAa,CAAC;AAQrB,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAkCD;;GAEG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,eAAoB,GAC5B,WAAW,CAsEb"}