@koppajs/koppajs-kpa-check

CLI diagnostics runner for KoppaJS .kpa files

Deterministic command-line diagnostics powered by the shared KoppaJS language layer.

Documentation · Language Core · Language Server · VS Code Extension · Issues

Table of Contents

1. Purpose
2. Repository Classification
3. Ownership Boundaries
4. Public Contract
5. Installation
6. Requirements
7. Usage
8. JSON Output
9. Exit Codes
10. Ecosystem Fit
11. Quality Baseline
12. Release Model
13. Architecture & Governance
14. Community & Contribution
15. License

---

Purpose

This repository exists to do one job well:

• accept explicit file and directory targets for .kpa analysis
• collect shared KoppaJS diagnostics outside editor or language-server hosts
• print stable, grep-friendly warning lines and explicit exit codes
• keep the CLI surface thin so language semantics continue to live in @koppajs/koppajs-language-core

It is not a parser fork, a formatter, or a replacement for the language server.

---

Repository Classification

• Repo type: CLI diagnostics package
• Runtime responsibility: filesystem target resolution, workspace-graph orchestration, output formatting, and process exit-code selection
• Build-time responsibility: compile the TypeScript package, emit declarations, and validate the repository quality gates
• UI surface: none
• Maturity level: v0 stabilization

---

Ownership Boundaries

• src/cli.ts owns executable startup only.
• src/runner.ts owns the diagnostics-runner contract: target resolution, ordering, language-core calls, output formatting, and exit codes.
• src/index.ts owns the minimal programmatic package export.
• src/test/unit/ owns unit and lightweight integration coverage for the runner.
• scripts/ owns repository-only quality guards.
• Root governance files and docs/ own the repository doctrine, specs, and quality baseline.

Language analysis rules, diagnostic messages, and workspace indexing remain the responsibility of @koppajs/koppajs-language-core.

---

Public Contract

The stable public surface of this repository is intentionally small:

• the kpa-check [targets...] executable
• kpa-check --help and kpa-check --version
• defaulting to the current working directory when no target is supplied
• rejecting any requested target that does not exist with exit code 2
• scanning all reachable .kpa files across the resolved target set
• printing diagnostics as path:line:character warning message
• emitting a single JSON document with --json
• returning exit code 0 for success, 1 for diagnostics, and 2 for invalid input
• the root package export runKpaCheck(argv, options?) plus its public runner types for programmatic reuse

The governing behavior spec is docs/specs/diagnostics-runner-contract.md.

---

Core Compatibility

This release line validates against:

• @koppajs/koppajs-language-core: ^0.1.4

The effective compatibility contract is the dependency range in package.json. The maintenance policy lives in docs/meta/version-compatibility.md.

---

Installation

Install the package into a workspace that should run local .kpa diagnostics:

npm install --save-dev @koppajs/koppajs-kpa-check

Run it without adding a custom wrapper:

npx kpa-check src

---

Requirements

For package consumers:

• Node.js >= 22

For local repository work:

• Node.js >= 22
• npm >= 10
• pnpm >= 9 (supported local alternative)

The maintainer default remains pinned to Node 22 through .nvmrc.

---

Usage

Installed command:

kpa-check src

Help:

kpa-check --help

Version:

kpa-check --version

Current working directory:

kpa-check

Multiple targets:

kpa-check src components/Page.kpa

Machine-readable JSON output:

kpa-check --json src

Programmatic usage:

import { runKpaCheck } from '@koppajs/koppajs-kpa-check';

const exitCode = runKpaCheck(['src']);

Programmatic JSON output:

import { runKpaCheck } from '@koppajs/koppajs-kpa-check';

const exitCode = runKpaCheck(['src'], {
  outputFormat: 'json',
});

---

JSON Output

--json writes exactly one JSON document to stdout for each invocation, including clean runs, diagnostics, help/version output, and invocation errors.

For diagnostics runs, the payload includes:

• kind, status, and exitCode
• cwd, requested targets, resolved targets, and missing targets
• a summary with checked-file and diagnostic counts
• a sorted diagnostics array with filePath, relativeFilePath, line, character, severity, message, and optional code / data

The current JSON severity is always warning, matching the text output format.

---

Exit Codes

• 0: all reachable .kpa files were checked and no diagnostics were found, or no .kpa files were reachable, or --help / --version completed
• 1: at least one diagnostic was emitted
• 2: the invocation itself was invalid, currently because at least one target path does not exist or an unknown/conflicting CLI option was provided

---

Ecosystem Fit

@koppajs/koppajs-kpa-check complements the rest of the KoppaJS language toolchain:

• @koppajs/koppajs-language-core owns parsing, indexing, and diagnostics
• @koppajs/koppajs-language-server exposes the same language layer through LSP
• editor integrations can use the language server for interactive workflows
• @koppajs/koppajs-kpa-check remains the narrow non-editor entry point for CI, scripts, and local validation

The package intentionally stays thin so diagnostics behavior evolves in one place.

---

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 test
• npm run build
• npm run test:dist
• npm run check
• npm run validate

The release candidate should also pass:

• npm run release:check

GitHub Actions runs npm run validate on Node.js 22 and 24 for pushes to main and develop and for pull requests. The same CI workflow also runs pnpm run validate on Node.js 22 and 24. Tagged releases rerun npm run validate and npm run release:check on the maintainer default from .nvmrc before publish.

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 through GitHub Actions.

• package.json defines the intended release version
• CHANGELOG.md records the release notes
• RELEASE.md defines the repository-specific release workflow
• .github/workflows/release.yml validates and publishes tagged releases

---

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/meta/repository-map.md
• docs/quality/README.md
• docs/quality/validation-baseline.md
• .github/workflows/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

---

Community & Contribution

Issues and pull requests are welcome:

https://github.com/koppajs/koppajs-kpa-check/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