Crate comindly_core 

comindly’s engine: cross-repo code intelligence as a library. Indexing runs as an async, cancellable pipeline with structured events; everything a call needs is passed in.

One module per stage: model (SCIP identity, symbols and edges) → parse (tree-sitter) → git (incremental) → resolve (cross-repo binding) → index (LanceDB) → graph → embed and search → llm (summaries, walkthroughs) → ledger (why code is as it is).

Modules

answers

What the read commands answer, computed the same way on this machine and on a server, so a command run with --server prints what a local run would.

checks

Compiled constraint checks: forbid [<edge-kind>] from <sel> to <sel> and forbid dep <pkg> [<ver>], where a selector is <glob over repo/path>[::<glob over name>].

configvals

Values from a repo’s YAML config files (config*.yml, settings*.yml, application*.yml), kept as facts so settings paths the code cannot resolve (config.task_queue.queue) still name their queue, bucket or URL.

context

What a call into core needs, passed in rather than looked up: where the index lives, the settings it runs with, the LLM, where events go, and when to stop.

conventions

Conventions engine: measured coding conventions per repo, with support counts, central exemplars and counterexamples, mined from facts and the graph. An LLM may phrase them; it never invents them. Conventions shared by several repos form the org baseline.

docstore

One settings document in a LanceDB table: each save is a new table version, recording who changed it and when, and a save based on an older version is refused.

embed

Comindly embed — local static embeddings for semantic code search.

eval

Graph-quality evaluation: compare resolved edges against a gold set (expected.toml).

events

What core reports while it works: steps, results, warnings and progress, as structured events. The CLI renders them in the terminal; a server keeps them with the job, streams them to the app and writes them to its log.

facts

Per-file syntactic facts the parser extracts and the resolver binds: imports, references (as dotted paths) and type hints. Scope ids are rendered GlobalSymbolIds.

git

comindly-git — git change detection for incremental indexing.

graph

Comindly graph — the query layer a coding agent actually consumes.

hosting

Lists the repositories of a GitHub organisation or user, or a GitLab group (with subgroups), so they can be picked and cloned. Works with github.com, GitHub Enterprise, gitlab.com and self-hosted GitLab.

index

Comindly index — the versioned LanceDB store (local dir or S3).

infra

Terraform: queues, topics and buckets a repo declares or looks up, and which queues subscribe to which topics. Becomes contract facts on the .tf file’s symbol.

lang

Per-language syntax adapters. The generic walk in crate::parse asks each question of the file’s language; adding a language means implementing LangSpec for its grammar.

ledger

Reasoning ledger: why code is the way it is — decisions, failed attempts, constraints — as typed, symbol-anchored, append-only records in the user’s own store (<index-dir>/_ledger/inbox/<uuid>-<hash>.json, written create-only so writers never clash). Status (active, moved, stale, orphaned, superseded, retracted) is derived at read time.

llm

Comindly LLM enrichment — per-symbol summaries, symbol-aware query generation, and a repo style guide, via Rig (provider-agnostic: OpenAI by default; any OpenAI-compatible endpoint via COMINDLY_LLM_BASE_URL; Bedrock/Vertex/others can be added behind cargo features).

manifests

Packages and versions from manifests and lockfiles: what each repo publishes and depends on, so internal dependencies map to the repo that publishes them (and version skew shows).

model

Comindly core domain model.

packages

Importable module names for repo files: Python source roots (pyproject.toml, src/ layout) and TS/JS packages (package.json name + entry point).

parse

Comindly parse — tree-sitter extraction of symbols, the Contains hierarchy and per-file facts.

pipeline

Indexing: check out repositories, parse and bind them across repositories, persist the graph, then the optional steps (search embeddings, summaries, style guides, flow walkthroughs). Async and cancellable; CPU-heavy work runs on the blocking pool; progress goes to the context’s reporter. LLM output is saved as it is written and reused while its input is unchanged, so an interrupted run continues where it stopped.

preflight

Preflight: before a change lands, what the team already knows about the code it touches — recorded constraints and dead ends, contracts other services rely on, blast radius, and directories that usually change together but are missing from the change.

recipes

Recipes from history: when commits add code in a directory, which other directories change with it (“adding a route also touches models/ and tests/api/”), with an exemplar commit.

resolve

Comindly resolve — bind per-file facts to definitions, within and across repos.

rt

Running async code from synchronous callers (CLI commands, the terminal UI, blocking-pool work): one shared runtime for the process, never one per call.

scip

SCIP ingestion: compiler-grade definitions and references attached to per-file facts.

search

Hybrid code search: native LanceDB retrieval (BM25 + vector via RRF) followed by comindly’s code-aware rerank — definition/exact-name boosts, structured path penalties, LLM-query recall boost, and a dependency-graph centrality signal no pure search tool has.

signing

Optional SSH signatures on ledger records, with the key developers already sign git commits with (ssh-keygen -Y, namespace comindly-ledger). A signature that does not verify against allowed_signers drops the record to T0; unsigned records are unaffected.

sources

File contents of the indexed commit, kept in the index so code can be shown without a checkout.

storage

Index storage at any location LanceDB opens: a folder, s3://, gs:// or az://. Credentials, region and endpoint come from the platform’s own environment, never from comindly.

styleguide

Evidence for the multi-pass LLM style-guide synthesis.

team

Team settings, stored with the index (<index>/_team, a versioned LanceDB table) so everyone using it runs the same LLM, embedding model and LLM steps. No secrets: each member’s API key comes from their own credentials file or environment.

view

What the apps show of an index — graph, contracts, ledger, conventions, dependencies — read once.

worktree

comindly’s own checkout of each repository’s default branch: a detached git worktree under ~/.cache/comindly/worktrees, so indexing never touches your working folder or branches. Uses the git command, so your SSH keys and credential helpers apply.