linework 0.0.2

The linework protocol: line-keyed, two-wave code paint and facts — engine-neutral types and the Limner trait binding language intelligence to editors
Documentation
  • Coverage
  • 60%
    27 out of 45 items documented1 out of 16 items with examples
  • Size
  • Source code size: 18.8 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 704.5 kB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 3s Average build duration of successful builds.
  • all releases: 3s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • mgraves/qana
    0 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • mgraves

linework

An engine-neutral protocol for binding language intelligence to a code editor. Line-keyed, two-wave code paint plus on-demand facts, behind one trait an editor widget can be generic over.

Zero dependencies. This crate knows nothing about any particular parser, language runtime, or editor.

[dependencies]
linework = "0.0.1"

What it is for

An editor that wants syntax colouring, go-to-definition and inline hints normally couples itself to whatever produces them. Swap the engine and the widget is rewritten; support a second language and the widget grows a second integration.

linework is the seam. One side implements [Limner]; the other consumes it. Neither needs the other's types:

   your editor widget  ──►  dyn Limner  ◄──  your intelligence engine
      (consumes)                                  (implements)

The shape, and why

Paint is line-keyed. Each line is a vector of Runs — 4-byte cells {len, style, mods} tiling that line's bytes exactly. Runs are line-relative, so a line that merely shifts down re-emits nothing. Editing line 3 of a 10,000-line file does not repaint 9,997 unchanged lines.

Paint is two-wave. style is the lexical class, available synchronously with a keystroke from the damaged lines alone. mods carries semantic bits — definition, resolved or unresolved reference, exported, foreign, typed — that arrive later and never change a style. Refinement is strictly additive, so the first frame is already correct and nothing flickers as understanding deepens.

A delta names only what changed. A PaintDelta carries a spliced window of lines plus semantic-only repaints by line number. That repaint set is the edit's semantic blast radius, made explicit rather than guessed at.

Facts are lookups, not requests. FactCard answers "what is this name" — definition site, problem, display type, namespace — against warm state. Hints carry inline decorations.

The trait

pub trait Limner {
    fn open(&mut self, text: &str) -> Paint;
    fn edit(&mut self, edit: &LineEdit) -> PaintDelta;
    fn facts(&mut self, offset: u32) -> Option<FactCard>;
    fn hints(&mut self) -> Vec<Hint>;
    fn legend(&self) -> Vec<String>;
    fn text(&mut self) -> String;
}

legend() names the style classes by index, so the editor maps indices to its own theme and the engine never speaks in colours.

Conventions

  • Offsets and lengths are bytes of UTF-8 text. Consumers that index by character (ropes, for instance) convert at the boundary.
  • The wire form is the memory form, little-endian — see encode_lines / decode_lines. Decoding is bounds checks, not parsing, so the protocol crosses a process boundary without a serialisation format.

Status

Pre-1.0 and evolving. The types are small and the surface is deliberately narrow, but expect breaking changes before 1.0. Pin an exact version.

Licence

MIT OR Apache-2.0, at your option.