@koppajs/koppajs-language-core

Shared language primitives, semantic service, and workspace graph for KoppaJS

Parser, diagnostics, template semantics, and workspace analysis in one editor-agnostic package.

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

Table of Contents

1. Purpose
2. Ownership Boundaries
3. Public Contract
4. Usage
5. Ecosystem Fit
6. Quality Baseline
7. Release Model
8. Architecture & Governance
9. Community & Contribution
10. License

---

Purpose

This repository exists to centralize the reusable language behavior for KoppaJS files:

• block parsing and document modeling
• structural and semantic diagnostics
• template expression and component analysis
• workspace symbol discovery and dependency tracking
• a service facade for completions, hover, definitions, references, rename, and code actions

---

Ownership Boundaries

This package owns:

• runtime language logic for .kpa documents
• TypeScript-backed semantic analysis for template expressions
• filesystem-backed workspace indexing and component dependency tracking
• the published root module contract in src/index.ts

This package does not own:

• editor transport layers such as LSP or VS Code integration
• CLI presentation or process orchestration
• file watching daemons
• formatting, code generation, or compilation of .kpa files
• browser UI or Playwright-driven workflows

---

Public Contract

The published npm surface is a single root entry point defined by package.json exports["."] and implemented in src/index.ts. There are no public subpath exports.

That root entry point intentionally groups the runtime contract into a few explicit families:

• structural document primitives such as parseKpaDocument, getBlockAtOffset, createLineStarts, createLocatedRange, and offsetToPosition
• diagnostics entry points such as collectKpaDiagnosticsFromDocument, collectKpaDiagnosticsFromText, and kpaDiagnosticCodes
• template analysis helpers covering expressions, local references, imported components, workspace-registered components, and TypeScript-backed template semantics
• workspace and project-config runtime helpers including KpaWorkspaceIndex, KpaWorkspaceGraph, and config-resolution cache controls
• the high-level KpaLanguageService facade

The exact runtime value exports are locked by src/test/unit/publicApi.test.ts, and the root-only package manifest boundary is locked by src/test/unit/packageMetadata.test.ts. Lower-level files that are not re-exported from the root module, such as src/diagnosticsEngine.ts, are internal compatibility shims for repository use and are not part of the published package entry point.

---

Usage

import {
  KpaLanguageService,
  collectKpaDiagnosticsFromText,
  parseKpaDocument,
} from '@koppajs/koppajs-language-core';

const text = [
  '[template]',
  '  <div>{{count}}</div>',
  '[/template]',
  '',
  '[ts]',
  '  const count = 1;',
  '[/ts]',
].join('\n');

const document = parseKpaDocument(text);
const { diagnostics } = collectKpaDiagnosticsFromText(text);

const service = new KpaLanguageService();
service.openDocument('file:///workspace/Counter.kpa', text);

const completions = service.getCompletions(
  'file:///workspace/Counter.kpa',
  text.indexOf('count') + 1,
);

---

Ecosystem Fit

This repository is a KoppaJS core package. It is intended to sit below language-server, editor-adapter, and CLI packages so those packages can share one source of truth for .kpa language behavior.

The package is runtime code, not build tooling. It executes in Node.js, requires Node.js >=22, and uses synchronous filesystem access where workspace indexing requires deterministic reads.

---

Quality Baseline

The enforced repository checks are:

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

GitHub Actions runs npm run validate on Node.js 22 and 24 for pushes to main and develop and for pull requests. Tagged releases rerun npm run validate and npm run release:check on Node.js 22 before publish, and only continue when the git tag version matches package.json.

npm run check:docs includes both the governed root-document contract and a semantic consistency check that keeps version, workflow, and quality-gate claims aligned with the actual repository state.

---

Release Model

Releases are manual and tag-driven. The release candidate is prepared on develop, moved through a release/* branch into main, tagged on main as vX.Y.Z, and then published by GitHub Actions. After a successful release, main is merged back into develop.

The repository-specific release contract lives in RELEASE.md. Release notes are tracked in CHANGELOG.md.

---

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/meta/README.md
• docs/architecture/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 repository guards before committing:

npm run check:docs
npm run check:meta

---

Community & Contribution

Issues and pull requests are welcome:

https://github.com/koppajs/koppajs-language-core/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