@relgeo/language-service

v0.5.1

Published

25 days ago

Language intelligence (completions, diagnostics, schema) for the RelGeo DSL

0High
0Medium
0Low

agusmade

relgeo lsp language-service codemirror json-schema

RelGeo Language Service

Intelligence layer untuk DSL RelGeo.

Package ini mengikuti kontrak aktif RelGeo DSL v0.5, yang disajikan melalui website pada /docs/language-spec/.

Metadata package @relgeo/language-service saat ini adalah 0.5.0, pada compatibility line RelGeo DSL v0.5. Patch release dapat bergerak mandiri; perubahan kontrak bahasa akan dinaikkan bersama ke line berikutnya.

Status packaging saat ini:

package ini adalah library surface untuk editor intelligence
package publik tersedia melalui npm sebagai @relgeo/language-service
workspace root tetap dipakai untuk integrasi dan verifikasi lintas-repo

Pakai package ini jika Anda ingin:

menambahkan completion, diagnostics, atau schema ke editor RelGeo
membangun IDE ringan, extension editor, atau embedding authoring surface
menjaga editor tetap selaras dengan kontrak bahasa aktif

Jika yang Anda butuhkan berbeda:

gunakan @relgeo/core untuk runtime parse/resolve
gunakan relgeo-playground bila Anda ingin aplikasi interaktif yang sudah jadi

@relgeo/language-service menyediakan fitur editor pintar seperti auto-completion, diagnostics (linting), dan JSON Schema untuk dokumen RelGeo.

Package ini dirancang agar editor dapat memahami RelGeo sebagai sebuah typed geometry language, bukan sekadar YAML biasa.

Artinya, package ini tetap netral terhadap surface editor:

bisa dipakai oleh browser IDE yang ringan
bisa dipakai oleh workbench lokal yang lebih kaya
tidak mendefinisikan preference UX salah satu surface

Dokumen terkait:

kontrak bahasa aktif: RelGeo DSL v0.5, disajikan melalui website pada /docs/language-spec/
dokumentasi publik dan contoh penggunaan: relgeo.github.io

Philosophy

RelGeo sejak awal dirancang sebagai:

relation-first
deterministic
geometry-aware
completion-oriented

Karena itu, editor support bukan fitur tambahan opsional.

Language service diposisikan sebagai bagian penting dari pengalaman penggunaan RelGeo:

membantu penulisan DSL
menjaga validitas geometri
memberikan semantic guidance
membantu generasi kode oleh LLM
menjaga struktur dokumen tetap konsisten

Features

Context-Aware Auto Completion

Completion engine memahami konteks YAML dan struktur semantik RelGeo.

Contoh kemampuan:

object type suggestions
field suggestions
geometry query suggestions
anchor suggestions
placement suggestions
transform suggestions
path segment suggestions
tangent/intersection helpers

Contoh:

objects:
  panel:
    type: rect
    size: [120, 80]

  label:
    type: text
    place:
      centerX: panel.

Editor akan menyarankan:

centerX
centerY
left
right
top
bottom
center

Geometry-Aware Diagnostics

Diagnostics tidak hanya memeriksa syntax YAML.

Language service juga menggunakan validator dari @relgeo/core untuk mendeteksi:

circular dependency
invalid anchors
over-constrained geometry
under-constrained geometry
invalid intersections
invalid path closure
invalid tangent construction
invalid offset operations

Contoh error:

MULTIPLE_INTERSECTIONS
PATH_NOT_CLOSED
UNKNOWN_REFERENCE
CIRCULAR_DEPENDENCY

JSON Schema

Package menyediakan JSON Schema bawaan untuk:

VS Code YAML validation
Monaco Editor
CodeMirror integrations
tooling eksternal

Schema selalu diarahkan agar sinkron dengan semantic contract dari @relgeo/core.

Typed Geometry Semantics

Language service memahami primitive dan semantic contract RelGeo:

point
line
rect
circle
arc
quadratic
cubic
path
polygon
text
group
clone

Termasuk:

9-point anchors
query functions
path holes
fillet/chamfer
tangent relations
generalized intersection

Editor Agnostic

Package tidak terikat pada editor tertentu.

Dapat digunakan pada:

CodeMirror
Monaco Editor
VS Code Extension
custom playground
embedded browser editor

Installation

Dalam monorepo ini:

pnpm install

Jika suatu saat package ini dipublikasikan terpisah, surface install-nya ditargetkan tetap berbentuk library integration package.

npm install @relgeo/language-service

[!IMPORTANT] Package ini membutuhkan @relgeo/core.

Architecture

flowchart TD
    A[RelGeo Document]
    --> B[Parser]
    --> C[Semantic Analysis]
    --> D[Completion Engine]
    --> E[Diagnostics Engine]
    --> F[Editor Integration]

Basic Usage

import { RelGeoLanguageService } from '@relgeo/language-service';

const langService = new RelGeoLanguageService();

const diagnostics = langService.getDiagnostics(code);

const completions = langService.getCompletions(code, {
  line: 10,
  character: 5,
});

Integrating with CodeMirror 6

import { RelGeoLanguageService } from '@relgeo/language-service';
import { linter } from '@codemirror/lint';
import { autocompletion } from '@codemirror/autocomplete';

const langService = new RelGeoLanguageService();

// Diagnostics
const relgeoLinter = linter((view) => {
  const code = view.state.doc.toString();

  const diagnostics = langService.getDiagnostics(code);

  return diagnostics.map((d) => ({
    from: 0,
    to: code.length,
    severity: 'error',
    message: d.message,
  }));
});

// Auto Completion
const relgeoAutocompletion = autocompletion({
  override: [
    (context) => {
      const code = context.state.doc.toString();
      const line = context.state.doc.lineAt(context.pos);

      const completions = langService.getCompletions(code, {
        line: line.number - 1,
        character: context.pos - line.from,
      });

      return {
        from: context.pos,
        options: completions.map((c) => ({
          label: c.label,
          type: 'keyword',
          detail: c.documentation as string,
        })),
      };
    },
  ],
});

API Reference