Skip to content

Contributing to OntoCode / OntoIndex

Thank you for contributing. This repository contains:

  • OntoIndex — Rust crates under crates/ (ontoindex CLI, ontoindex-lsp)
  • OntoCode — VS Code extension under extension/
  • Specs — product and architecture docs under docs/design/ (DEPENDENCY_MATRIX.md for external crates)
  • User guides — install, SQL, and LSP API under docs/

The root Cargo package ontocode is unpublished and hosts workspace integration tests (tests/).

Prerequisites

  • Rust 1.88+ (see rust-version in Cargo.toml)
  • Node.js 20 (extension CI)
  • npm (extension build)

Build and test

Rust (full workspace)

cargo build --workspace
cargo test --workspace
cargo fmt --all
cargo clippy --workspace --all-targets --all-features -- -D warnings

Build the language server binary:

cargo build -p ontoindex-lsp --bins

Run CLI smoke commands against fixtures:

cargo run -- query fixtures "SELECT * FROM classes"
cargo run -- validate fixtures

cargo run -- uses the workspace default member ontoindex-cli (binary name: ontoindex).

Extension

cd extension
npm ci
npm run compile
npm test

Extension tests expect a built ontoindex-lsp binary. From the repo root:

cargo build -p ontoindex-lsp --bins
cd extension
export ONTOINDEX_LSP_BIN="$(pwd)/../target/debug/ontoindex-lsp"
npm test

F5 / Run Extension: Open the extension/ folder in VS Code, build LSP (cargo build -p ontoindex-lsp --bins), optionally set ontocode.lspPath to your debug binary, then launch Run Extension.

LSP integration smoke test (workspace crate):

cargo test -p ontocode --test lsp_smoke
cargo test -p ontocode --test lsp_reasoner

VS Code E2E matrix (separate workflow): see .github/workflows/extension-vscode-e2e.yml. Run locally with @vscode/test-electron after packaging the extension.

Full extension packaging (bundles LSP for current platform):

./scripts/package-extension.sh

Golden snapshots

Some tests compare query output to committed snapshots. To update:

ONTOINDEX_UPDATE_GOLDEN=1 cargo test golden_classes

Review the diff in tests/golden/snapshots/ before committing.

Examples

cargo run -p ontocode --example index_and_query

Documentation site (MkDocs / Read the Docs)

pip install -r docs/requirements.txt   # Python 3.12 in CI
mkdocs serve
mkdocs build --strict   # CI uses this; must pass with no warnings
./scripts/check-doc-versions.sh   # README / RTD / extension version sync

Open http://127.0.0.1:8000. Configuration: mkdocs.yml on GitHub, .readthedocs.yaml on GitHub.

Pull requests

  1. Fork and branch from main.
  2. Keep changes focused; match existing style and naming.
  3. Run Rust and extension tests locally (CI runs both).
  4. Update docs when behavior or public API changes (README.md, docs/, CHANGELOG.md, docs/changelog.md as appropriate). On release, follow the checklist in releasing.md.
  5. For spec changes, label whether they describe implemented vs planned behavior (see lsp-api.md as a model).

Documentation conventions

Audience Where to write
New users (install, SQL, LSP) docs/
Product vision, roadmap, ADRs docs/design/
Architecture decisions docs/design/adr/ only (do not add adrs/)
Extension settings and commands extension/README.md

Read the Docs URLs

Canonical base: https://ontocode-vs.readthedocs.io/en/latest/ (project slug ontocode-vs).

Link type Example
VS Code extension path .../guides/vscode-extension/
Rust & CLI path .../guides/rust-crates/
Page path Trailing slash, no .md — e.g. .../guides/reasoner/ not .../reasoner.md

mkdocs.yml site_url stays at project root (https://ontocode-vs.readthedocs.io/); all user-facing links in READMEs use /en/latest/.

Adding dependencies

Before adding a Rust crate dependency:

  1. Check DEPENDENCY_MATRIX.md — prefer listed crates over new alternatives.
  2. Follow ADR-0016 — ontoindex-* crates are facades, not reimplementations.
  3. Update DEPENDENCY_MATRIX and LICENSES.md if the crate is new or uses a non-MIT/Apache license.
  4. Pin in workspace [workspace.dependencies] in root Cargo.toml.

Code of conduct

See CODE_OF_CONDUCT.md.

Security

Report vulnerabilities per SECURITY.md — please do not open public issues for security reports.