@koppajs/koppajs-language-core

v0.1.4

Published

19 days ago

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

0High
0Medium
0Low

koppajs

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:

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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme