Skip to content

Repository navigation

CONTRIBUTING.md

Latest commit

 

History

History
197 lines (144 loc) · 7.88 KB

CONTRIBUTING.md

File metadata and controls

197 lines (144 loc) · 7.88 KB
Raw

CONTRIBUTING.md

Note: We are not accepting contributions at this moment. Feel free to post an issue if you have feedback or suggestions.

Development Setup

Prerequisites

  • SWI-Prolog >= 9.0 on PATH (or KIBI_SWIPL pointing at it). A source checkout does not carry the bundled runtime that published packages ship, so install it yourself (see docs/install.md)
  • Bun (latest)
  • Git

Installation

bun install

Project Structure

packages/
  core/       # Prolog KB core (kb.pl, schema/*.pl)
  cli/        # Node.js CLI (commands, extractors, Prolog wrapper)
  mcp/        # MCP server (stdio, JSON-RPC)
  vscode/     # VS Code extension (TreeView)
tests/
  integration/  # End-to-end tests
  benchmarks/   # Performance benchmarks

Maintainer docs

These are internal working documents, not user-facing product docs:

  • Brand guide — visual identity for the logo, HTML report, and badge

Testing

Unit Tests (TypeScript/CLI)

bun run test                       # Project test pipeline (unit + packed local e2e)
bun run test:unit                  # All unit tests (packages/*)
bun test packages/cli/             # CLI tests only
bun test packages/mcp/             # MCP tests only

Integration Tests

bash ./scripts/run-integration-tests.sh

Prolog Tests (plunit)

swipl -g "load_test_files([]),run_tests" -t halt packages/core/tests/kb.plt
swipl -g "load_test_files([]),run_tests" -t halt packages/core/tests/schema.plt

Dogfooding Kibi in another repository

To try unreleased changes in a separate consumer repository, pack the workspace into local tarballs and install those instead of the npm releases. You need Bun for the build and pack steps.

  1. Build every package from the Kibi checkout: 
    bun run build
  2. Pack the publishable packages into one directory (each package's prepack rebuilds it, so the tarballs carry fresh dist/ output): 
    bun run pack:all -- --destination /tmp/kibi-tarballs
  3. In the consumer repository, depend on the tarballs and override the transitive Kibi packages so they resolve to the same local builds instead of npm. With npm: 
    {
  "devDependencies": {
    "kibi-cli": "file:/tmp/kibi-tarballs/kibi-cli-<version>.tgz",
    "kibi-mcp": "file:/tmp/kibi-tarballs/kibi-mcp-<version>.tgz"
  },
  "overrides": {
    "kibi-core": "file:/tmp/kibi-tarballs/kibi-core-<version>.tgz",
    "kibi-runtime": "file:/tmp/kibi-tarballs/kibi-runtime-<version>.tgz",
    "kibi-plugin-sdk": "file:/tmp/kibi-tarballs/kibi-plugin-sdk-<version>.tgz",
    "kibi-plugin-builtin": "file:/tmp/kibi-tarballs/kibi-plugin-builtin-<version>.tgz",
    "kibi-swipl": "file:/tmp/kibi-tarballs/kibi-swipl-<version>.tgz"
  }
}
    Then run npm install and check npx --no-install kibi --version. Add agent-host packages (kibi-opencode, kibi-codex, ...) the same way when you need them.

The SWI-Prolog platform packages (kibi-swipl-linux-x64-gnu, kibi-swipl-darwin-arm64, ...) are not packed: their binaries are only populated at release time. The local kibi-swipl tarball pins them to exact versions, which the consumer installs from npm, so the pinned platform version must already be published.

Benchmarks

Run performance benchmarks:

bun run tests/benchmarks/sync.bench.ts
bun run tests/benchmarks/query.bench.ts
bun run tests/benchmarks/mcp-latency.bench.ts

Code Style

  • Formatting and linting use Biome.
  • Run lint: bun run check
  • Run format: bun run format

Running CI Locally

To simulate CI steps:

  1. Install SWI-Prolog (via apt-get or package manager). CI itself runs the pipeline-built bundle for most jobs and a system install for ci-integration; see docs/swipl-build.md
  2. Install Bun
  3. Run bun install
  4. Run bun run test
  5. Run integration tests and benchmarks as above

Commit Message Conventions

Use the following prefixes:

  • feat(scope): description — New feature
  • fix(scope): description — Bug fix
  • docs(scope): description — Documentation changes
  • test(scope): description — Test changes
  • chore(scope): description — Build/config changes

Pull Request Guidelines

  • All tests pass (bun run test)
  • Code passes linting (bun run check)
  • Integration tests pass (bash ./scripts/run-integration-tests.sh)
  • Documentation updated if needed
  • Tests added for new features
  • Commit messages follow conventions

KB Modeling Note

When documenting issues or workarounds in the KB:

  • Use fact with fact_kind: observation or meta for bug records and workaround notes (non-blocking lane)
  • Use flag only for actual runtime/config gates (not for bug records)
  • Strict facts (subject, property_value) drive contradiction checks. domain-contradictions applies only to strict lane. strict-fact-shape is a canonical blocking check. Schema 7 migration encodes legacy polarity-only property values as typed boolean facts.
  • Use flag only for actual runtime/config gates (not for bug records)
  • See Entity Schema and AGENTS.md for the canonical entity-choice guidance

Clear, practical, and ready for contributors.

Staged Symbol Traceability: Contributor Guidelines

To help maintain traceability between code and requirements, all new or modified code symbols (functions, classes, modules) must be linked to at least one documented requirement before commit.

How to add requirement links to new code

When you add or change a function, class, or module, include a comment with the requirement ID(s) it implements. Example:

export function myFunc() { } // implements REQ-cli-gc

For multiple requirements:

export class MyClass { } // implements REQ-cli-gc, REQ-cli-check

This applies to TypeScript (.ts, .tsx) and JavaScript (.js, .jsx) files by default.

How the pre-commit hook works

If you ran kibi init, a pre-commit hook will automatically check your staged changes. The hook enforces two hard gates:

  1. Symbol traceability: New or modified symbols must be linked to a requirement via // implements REQ-<area>-<behavior> directives. If any staged symbol lacks a requirement link, the commit is blocked.

  2. Kibi impact evidence for behavior changes: Behavior-changing source edits must include staged Kibi impact evidence — either updated KB entity markdown under .kb/ (requirements, scenarios, tests, facts, ADRs, flags, events) or a refreshed .kb/symbols.yaml when symbol coordinates change. Test-only edits (tests/, *.test.*, *.spec.*) and docs-only edits (.md) are exempt.

If kibi check --staged reports kibi_impact_evidence_missing or symbols_manifest_stale, resolve by:

  • Querying Kibi via MCP before behavior changes
  • Staging relevant KB entity docs or symbol manifest changes
  • Running kibi check --staged to verify

The hook also blocks commits when .kb/symbols.yaml has unstaged changes. Stage and commit the refreshed manifest with the code or documentation change that caused it.

You can test your staged changes manually with:

npx kibi check --staged

For more details, see the "Staged Symbol Traceability" section in the README.

If you ran kibi init, a pre-commit hook will automatically check your staged changes for missing requirement links. If any new or modified symbols are not linked to a requirement, your commit will be blocked with an error message. To proceed, add the appropriate implements REQ-<area>-<behavior> directive to your code.

The hook also blocks commits when .kb/symbols.yaml has unstaged changes. Stage and commit the refreshed manifest with the code or documentation change that caused it.

You can test your staged changes manually with:

npx kibi check --staged

For more details, see the "Staged Symbol Traceability" section in the README.