tree-sitter-coral

Native Tree-sitter grammar for Coral syntax tooling.

This package compiles from source during installation; it doesn't ship prebuilt binaries. Python is required on every supported native-build platform. Linux/Unix also needs make and a C/C++ toolchain; macOS needs Xcode Command Line Tools; Windows needs Visual Studio C++ build tools.

Before installing, npm 12 consumers must approve the native lifecycle scripts in the root package.json:

{
  "allowScripts": {
    "tree-sitter-coral": true,
    "tree-sitter": true
  }
}

Then install the exact grammar and peer versions verified for Coral 0.2.7:

npm install [email protected] [email protected]

import Parser from 'tree-sitter';
import Coral from 'tree-sitter-coral';

const parser = new Parser();
parser.setLanguage(Coral);
const tree = parser.parse('service "API" as api');
if (tree.rootNode.hasError) throw new Error(tree.rootNode.toString());

The grammar recognizes the Language 1.0 editor-tooling subset: graph data, nodes and bodies, edges with compact relationship ends, positions/pins, spatial constraints, route intent, and comments. Runtime parsing, reference resolution, semantic diagnostics, canonicalization, and repair remain owned by @coral-viz/language.

Edge attributes accept an optional relation, an optional line style, and then named attributes, with at least one entry. Empty [], [dashed, event], [dashed, dotted], [a, b], and [label: "x", dashed] produce syntax errors. [dashed], [event], ["dashed", dotted], and [dashed: "x"] are valid. The style words solid, dashed, and dotted remain ordinary identifiers outside bare attribute entries.

Compact annotations such as a (1 "owner" diamond+ nav) -> b (0..*) attach to the immediately preceding endpoint. The tree exposes source_end and target_end fields containing relationship_end nodes, whose parts are multiplicity, string, end_marker, and navigability (nav or nonav). Each part occurs at most once, in that order; other orders and repeated parts are syntax errors. A multiplicity bound is plain digits, so 1.0, 1e0, 01, and +1 are syntax errors. Marker fill suffixes must touch the marker name; fixed markers do not accept suffixes. Separate compact parts with spaces or tabs. Multiplicity ranges keep the number, .., and upper bound adjacent: 1..2, not 1 .. 2. An annotation stays on one line: line breaks and comments cannot separate its parentheses or parts. Quoted comment text and escaped newline text remain roles.

Quoted references are accepted on both sides of an edge, with or without a compact end, such as "q r" ("s") -> b.

This is syntax recognition, not complete runtime conformance. Repeated JSON keys are recognized for runtime duplicate diagnostics. The runtime also owns E1–E13 end validation, equal bounds written as a range (1..1), bounds above 9007199254740991, empty roles, reference resolution, and whether JSON end contents require a compact spelling.

For repository testing, build @coral-viz/language and this package first. npm run test:run -w tree-sitter-coral runs the syntax corpus and native/runtime compact-boundary parity tests.

See the published Tree-sitter reference.

Apache-2.0. See LICENSE.