@koppajs/koppajs-language-server

Language Server Protocol adapter for KoppaJS language tooling

A thin LSP transport that exposes the shared KoppaJS language layer to editors.

Documentation · Language Core · VS Code Extension · KPA Check · Issues

Table of Contents

1. Purpose
2. Repository Classification
3. Ownership Boundaries
4. Public Contract
5. Usage
6. Local Development
7. Ecosystem Fit
8. Architecture & Governance
9. Community & Contribution
10. License

---

Purpose

@koppajs/koppajs-language-server exposes KoppaJS semantic editor features through the Language Server Protocol. It is a thin adapter over @koppajs/koppajs-language-core, not the owner of parsing, diagnostics rules, or editor-specific UX.

---

Repository Classification

• Type: standalone package
• Runtime responsibility: host a Node-based LSP server for .kpa analysis
• Build-time responsibility: compile TypeScript, emit declarations, and run repository quality gates
• UI surface: none
• Maturity: pre-1.0, intentionally narrow

---

Ownership Boundaries

This repository owns:

• LSP capability declaration
• request and notification wiring
• mapping between KoppaJS language-core data and LSP types
• workspace-root collection/update and watched-file invalidation handoff

This repository does not own:

• .kpa parsing or semantic analysis
• editor activation, snippets, or UI behavior
• CLI diagnostics
• package publication/versioning for @koppajs/koppajs-language-core

---

Public Contract

The public surface is intentionally small:

• consumers run the compiled dist/server.js module as an LSP server process
• the server supports completions, diagnostics, hover, definition, references, prepare rename, rename, quick fixes, document symbols, and workspace symbols
• diagnostics are emitted as warnings with source koppa-diagnostics
• only quick-fix code actions are advertised
• workspace roots are derived only from file: workspace URIs
• when the client supports dynamic watched-file registration, the server registers .kpa, JS/TS, and tsconfig.json/jsconfig.json watchers
• file-based workspace-folder changes update the active roots and refresh open document diagnostics
• watched-file invalidation conservatively refreshes open-document diagnostics
• non-file watched changes are ignored

This package does not expose a stable library API beyond the executable server module path.

---

Usage

Example vscode-languageclient wiring:

import { createRequire } from 'node:module';
import { LanguageClient, TransportKind } from 'vscode-languageclient/node';

const require = createRequire(import.meta.url);
const serverModule = require.resolve('@koppajs/koppajs-language-server');

const client = new LanguageClient(
  'koppajsLanguageServer',
  'KoppaJS Language Server',
  {
    run: { module: serverModule, transport: TransportKind.ipc },
    debug: { module: serverModule, transport: TransportKind.ipc },
  },
  {
    documentSelector: [{ language: 'kpa', scheme: 'file' }],
  },
);

await client.start();

---

Local Development

The repository consumes the published @koppajs/koppajs-language-core@^0.1.4 package directly from npm.

Requirements:

• Node.js >= 22
• npm >= 10

Maintainer default:

• .nvmrc pins Node.js 22 for local work
• .npmrc enforces engine compatibility during install

CI validates the repository on Node.js 22 and Node.js 24.

Common commands:

• npm run check:docs
• npm run check:meta
• npm run format
• npm run format:check
• npm run lint
• npm run typecheck
• npm run build
• npm test
• npm run release:check
• npm run validate

Compatibility policy:

• docs/meta/version-compatibility.md

---

Ecosystem Fit

This package sits between the editor client and the shared language semantics:

• @koppajs/koppajs-language-core owns parsing, diagnostics, symbol extraction, and semantic analysis, including workspace component discovery through explicit Core.take(...) registrations and the canonical .kpa component contract shared with @koppajs/koppajs-core and @koppajs/koppajs-vite-plugin
• @koppajs/koppajs-language-server exposes that shared truth over LSP
• editor clients such as koppajs-vscode-extension should remain thin adapters on top of this package

---

Architecture & Governance

Project intent, contributor rules, and documentation contracts live in the local repo meta layer:

• AI_CONSTITUTION.md
• ARCHITECTURE.md
• DECISION_HIERARCHY.md
• DEVELOPMENT_RULES.md
• TESTING_STRATEGY.md
• RELEASE.md
• ROADMAP.md
• CHANGELOG.md
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• docs/specs/README.md
• docs/specs/repository-documentation-contract.md
• docs/architecture/README.md
• docs/meta/README.md
• docs/quality/README.md

The file-shape contract for README.md, CHANGELOG.md, CODE_OF_CONDUCT.md, and CONTRIBUTING.md is defined in docs/specs/repository-documentation-contract.md.

Run the local document guard before committing:

npm run check:docs
npm run check:meta

---

Community & Contribution

Issues and pull requests are welcome:

https://github.com/koppajs/koppajs-language-server/issues

Contributor workflow details live in CONTRIBUTING.md.

Community expectations live in CODE_OF_CONDUCT.md.

---

License

Apache License 2.0 — © 2026 KoppaJS, Bastian Bensch