diff --git a/README.md b/README.md index 0b7ee246..f4980208 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,24 @@ # Compass -**A fast, local-first knowledge graph for understanding codebases.** - -Compass turns source code and project artifacts into a graph you can search, -query, visualize, compare across Git history, and share with development tools. +
+

Understand the shape of a codebase before you change it.

+

Compass is a local-first Rust workbench for architecture maps, dependency paths, impact analysis, and Git history.

+

+ Get started · + Documentation · + Roadmap · + VS Code extension · + Releases +

+
+ +

+ CI status + Latest release + MIT or Apache-2.0 license +

+ +Compass turns source code and project artifacts into a directed, queryable knowledge graph. It gives people and coding assistants a shared map of symbols, files, communities, relationships, and evidence. ```text large codebase @@ -18,83 +33,10 @@ large codebase less searching, smaller context, traceable evidence ``` -[Get started](docs/getting-started.md) · -[Read the documentation](docs/README.md) · -[Explore the roadmap](docs/roadmap.md) · -[View releases](https://github.com/crabbuild/compass/releases) - -Use Compass inside your editor with the first-party -[Compass Codegraph extension for VS Code](https://marketplace.visualstudio.com/items?itemName=crabbuild.crabbuild-compass-vscode). -See the [VS Code extension guide](docs/guides/vscode.md) for current graphs, -cursor-rooted call graphs, architecture flow, queries, and exact Git evolution. - -## Put Compass in your daily loop - -Use Compass first as a local context layer for coding assistants. Build the graph, install the agent integration, and keep the graph synchronized while you work: - -```bash -compass init -compass install -compass watch -``` - -Run `compass watch` in a second terminal. For a focused task, an installed -assistant starts with `compass query ""`. On a first session or broad -repository orientation, it reads only the bounded **Agent Orientation** at the -start of `compass-out/GRAPH_REPORT.md`, then runs a focused query. It checks -direction, ambiguity, completeness, truncation, and pagination before opening -only the cited source needed to verify its answer. - -Inside a Git repository, `compass install` detects supported assistants and always includes the portable Agent Skills integration. Confirm that the intended host appears under `Selected`. If it does not, select one or more platforms explicitly: - -```bash -compass install --platform codex -compass install --platform codex --platform claude -compass install --all --dry-run -``` - -See [Connect a coding assistant](#connect-a-coding-assistant) for supported agents, explicit platform selection, upgrades, and uninstall. - -### Review the graph yourself - -Human graph exploration is optional. Run `compass export html`, or choose **Open Code Graph** in VS Code, when you want to inspect the architecture directly: - -![High-level Compass workspace graph with package dependencies and subsystem filters](docs/assets/screenshots/code-graph-workspace-overview.png) - -*Start at the package map, filter by subsystem, then select any node to inspect its dependencies and source.* - -```bash -compass export html - -# Put several perspectives in one self-contained page. -compass export html \ - --code-graph \ - --architecture-graph \ - --call-graph checkout \ - --impact-graph checkout -``` - -Refresh the browser after a build, or reopen the graph in VS Code. - -The exported page and VS Code graph use the same workbench shell. Switch among -requested code, call, impact, affected, architecture, history, and artifact -lenses without losing the snapshot context. Use the graph from the right -sidebar: - -1. Search for a symbol or file. -2. Select a node to inspect its source, signature, community, evidence, and relationships. -3. Open the source card, or double-click a located node, to jump to the exact code. -4. Filter communities or change the layout when you need a different level of detail. - -The graph toolbar includes an exploration panel for isolating a selected -1–4-hop neighborhood, following incoming, outgoing, or both edge directions, -adjusting layout spacing, and showing a navigable minimap. Press `?` in the -graph to see camera and exploration keyboard shortcuts. - -Right-click inside a function in VS Code to open callers, callees, impact, related symbols, or a path. - ## What Compass gives you +Compass covers the path from repository orientation to verified automation: + | Need | Compass capability | | --- | --- | | Understand an unfamiliar repository | Communities, architecture reports, god-node detection, and interactive HTML | @@ -105,265 +47,243 @@ Right-click inside a function in VS Code to open callers, callees, impact, relat | Give assistants focused context | Native skills, hooks, MCP serving, and compact graph queries | | Connect other tools | Graph JSON, GraphML, SVG, Wiki, Obsidian, Neo4j, FalkorDB, and other exports | -Structural extraction and graph queries run locally. They do not require -Python, embeddings, a vector database, model credentials, or runtime parser -downloads. - -## How it works - -![Compass graph construction and query pipeline](docs/assets/diagrams/graph-pipeline.svg) - -Compass discovers project files, extracts entities and relationships, resolves -cross-file references, analyzes the resulting graph, and publishes one -consistent snapshot. - -```text -function / class / file / document / schema object node -CALLS / IMPORTS_FROM / USES / CONTAINS relationship -dense group of related nodes community -direct / resolved / uncertain evidence provenance -``` - -Relationships retain their direction, source location, and provenance: - -```text -CheckoutHandler - | - +-- CALLS [EXTRACTED] --> authorizePayment() - | | - | +-- USES --> PaymentGateway - | - +-- CALLS [INFERRED] --> reserveInventory() -``` - -Read [How Compass works](docs/concepts/how-it-works.md) for the complete -pipeline and [Graph model](docs/concepts/graph-model.md) for the data model. - -## Project lineage - -Compass is inspired by and modeled after -[Graphify](https://github.com/Graphify-Labs/graphify). Graphify established the -core workflow: extract a codebase into a knowledge graph, analyze its -communities, and use focused graph queries to navigate complex projects. - -Compass gives explicit credit to that foundation, but it is now an independent -product with its own implementation, commands, configuration, artifacts, and -test suite. Compass does not execute or depend on Graphify. - -### Compass capabilities - -| Area | Compass extension | +Structural extraction and graph queries run locally. They do not require Python, embeddings, a vector database, model credentials, or runtime parser downloads. + +## See the graph before you open every file + +Compass exports a self-contained workbench. Move from a repository map to subsystem flow, call evidence, or bounded dependency neighborhoods without changing snapshots. + + + + + + + + + + +
+ Compass architecture map of the ripgrep repository with subsystem call direction and source details +
Architecture map · ripgrep
Subsystem boundaries, call direction, and source-backed details. + 		+ Compass code graph of the CLI11 repository with community filters and minimap +
Repository map · CLI11
Large-scale structure with communities, filters, and a minimap. +
+ Compass bounded call graph centered on ripgrep SearchWorker search +
Call graph · ripgrep
Follow callers, callees, direction, depth, and evidence coverage. + 		+ Compass dependency lens for the ripgrep repository with community filters +
Dependency lens · ripgrep
Inspect bounded relationships while keeping the surrounding context visible. +
+ +These are real Compass exports from public repositories, not product mockups: [BurntSushi/ripgrep](https://github.com/BurntSushi/ripgrep/tree/435f59fc4b43af3ab32f34d53fa34978f393fe52) and [CLIUtils/CLI11](https://github.com/CLIUtils/CLI11/tree/60492bddb50422f32cfa33c1365b96ebee4205ca). Counts and visible symbols reflect those exact revisions and will change as the projects evolve. + +## Find the answer at the right scale + +| Question | Compass surface | | --- | --- | -| Runtime | One native Rust executable with no Python or Graphify dependency | -| Exact queries | CompassQL, a deterministic and bounded read-only openCypher subset | -| Versioned graphs | Immutable realizations for exact commits, historical queries, exports, and diffs | -| Incremental operation | Reuses compatible unchanged extraction work and atomically publishes graph plus manifest | -| Query safety | Explicit row, path, expansion, memory, and time limits | -| Native distribution | Linked parsers and native implementations for supported graph, media, database, and service boundaries | +| Where does this subsystem live? | Communities, architecture flow, ownership, and source details | +| Which areas need attention first? | Communities, architecture reports, god-node detection, and interactive HTML | +| What calls this function? | Bounded caller and callee graphs with direction and depth controls | +| What could this change affect? | Reverse dependency paths, affected nodes, and evidence limits | +| Which files belong to this workflow? | Search, explanations, paths, and relationship filters | +| How do I automate structural checks? | Deterministic, read-only [CompassQL](docs/COMPASSQL.md) with JSON and JSONL output | +| What changed between revisions? | Immutable historical graphs and semantic diffs over exact Git commits | +| How do assistants stay focused? | Native skills, hooks, MCP serving, and compact graph queries | +| How do I share the result? | VS Code, self-contained HTML, JSON, GraphML, SVG, Wiki, Obsidian, Neo4j, FalkorDB, and MCP integrations | -See [Compatibility](COMPATIBILITY.md) for Compass-owned contracts and -[Migration from Graphify](MIGRATION.md) for the one-time hard cutover. +## Start with one repository -## Performance - -Compass performance is qualified against Compass-owned baselines while -preserving graph correctness and deterministic output. Read -[Performance qualification](PERFORMANCE.md) for the evidence policy and -benchmark commands. - -## Quick start - -### 1. Install +### Install the CLI -On macOS or Linux (Apple Silicon/ARM64 or Intel/AMD64): +On macOS or Linux, use the installer for Apple Silicon or Intel and AMD systems: ```bash curl --proto '=https' --tlsv1.2 -LsSf \ https://github.com/crabbuild/compass/releases/latest/download/install.sh | sh ``` -On Windows x64 or ARM64, run the checksum-verifying PowerShell installer: +On Windows, use the installer for x64 or ARM64 systems: ```powershell irm https://github.com/crabbuild/compass/releases/latest/download/install.ps1 | iex ``` -For an offline install, download the matching archive and `.sha256` file from -the [latest release](https://github.com/crabbuild/compass/releases/latest), -verify the checksum, extract it, and add the directory containing `compass.exe` -to `PATH`. +For an offline install, download the matching archive and `.sha256` file from the [latest release](https://github.com/crabbuild/compass/releases/latest), verify the checksum, extract the archive, and add the directory to `PATH`. -Or build from source with the pinned Rust 1.97.1+ toolchain: +To build from source, use the pinned Rust 1.97.1 or newer toolchain: ```bash git clone https://github.com/crabbuild/compass.git cd compass -make install -``` - -`make install` uses an existing `~/.cargo/bin`, otherwise it creates and uses -`~/.local/bin`. To choose another location, run -`make install BINDIR="$HOME/bin"`. - -You can also install directly through Cargo: - -```bash cargo install --locked --path crates/compass-cli --bin compass ``` -Upgrade any installed Compass executable to the latest stable release with: +You can also use the repository installer: ```bash -compass upgrade +make install ``` -Compass reads a bounded static release manifest, verifies the selected -archive's size and SHA-256 digest, and checks the staged executable's version -before replacing the running executable. The upgrade path does not use the -rate-limited GitHub REST API. If no newer release is available, it exits -successfully and reports that the installed version is already the latest. - -### 2. Install the VS Code extension (optional) - -After installing the Compass CLI, install -[Compass Codegraph from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=crabbuild.crabbuild-compass-vscode) -by selecting **Install** on its Marketplace page. You can also install it from -a terminal: +`make install` uses `~/.cargo/bin` when it exists. Otherwise, it creates and uses `~/.local/bin`. Set `BINDIR` when you want a different destination: ```bash -code --install-extension crabbuild.crabbuild-compass-vscode +make install BINDIR="$HOME/bin" ``` -Open your repository in VS Code. The extension detects the installed Compass -CLI and guides you to initialize the repository from the Compass sidebar. +Upgrade an installed Compass executable with `compass upgrade`. + +Compass reads a bounded static release manifest, verifies the selected archive size and SHA-256 digest, and checks the staged executable version before replacement. The upgrade path does not use the rate-limited GitHub REST API. When no newer release exists, the command exits successfully and reports the installed version. -### 3. Initialize and build a local graph +### Build the first graph ```bash cd your-project compass init ``` -`compass init` previews the eligible corpus, saves project scope in -`.compass/config.toml`, and performs the first structural build. For automation -or a focused monorepo scope: +`compass init` previews the eligible corpus, saves the project scope in `.compass/config.toml`, and performs the first structural build. Compass writes a coherent snapshot under `compass-out/`. + +For a focused monorepo scope, pass include and exclude patterns during initialization: ```bash compass init . --include src --include 'services/*/src' --exclude '**/generated/**' --yes ``` -After setup, `compass update` and `compass watch` automatically reuse the -saved scope. - -Compass writes: - ```text compass-out/ ├── graph.json machine-readable graph ├── GRAPH_REPORT.md architecture and community summary -├── orientation.json versioned Agent Orientation from the same graph generation +├── orientation.json bounded orientation for assistants ├── graph.html interactive visualization when size permits ├── manifest.json incremental build state -├── snapshots/ coherent retained build snapshots +├── snapshots/ retained coherent build snapshots ├── current-snapshot selected snapshot identifier └── store/ SQLite query index when enabled ``` -### 4. Ask useful questions +After setup, `compass update` and `compass watch` reuse the saved scope automatically. + +Keep the graph current while you work: + +```bash +compass watch +``` + +Run `compass watch` in a second terminal. It reuses the saved scope and refreshes the graph as files change. + +### Put Compass in your daily loop + +Use Compass as a local context layer for coding assistants. The complete loop is: + +```bash +compass init +compass install +compass watch +``` + +Run `compass watch` in a second terminal. For a focused task, an installed assistant starts with `compass query "your_question_here"`. For a first session or broad repository orientation, it reads the bounded Agent Orientation at the start of `compass-out/GRAPH_REPORT.md`, then runs a focused query. + +### Ask a focused question ```bash compass query "where is authentication enforced?" compass query "where is authentication enforced?" --text-budget 8000 -compass query "where is authentication enforced?" --cursor '' +compass query "where is authentication enforced?" --cursor 'query_cursor_token' compass explain TokenVerifier compass path ApiHandler TokenVerifier compass affected TokenVerifier --depth 3 ``` -These commands read the saved graph and do not call a model. -Plain natural `query` uses bounded structured discovery. Its text projection -pages whole deterministic entries with `--text-budget N` (2,000 by default). -Follow `next=` with the unchanged semantic question and options until -`next=none`; the presentation-only text budget may change between pages. The -cursor fails if semantic inputs, the selected graph, or the semantic result -changed. `--traverse`, `--budget`, and `--page` retain the -legacy traversal contract; CompassQL is unchanged. +These commands read the saved graph locally. Results are bounded, read-only, and tied to graph evidence instead of a model-generated guess. -## Compass-specific workflows +Plain-language `query` uses bounded structured discovery. Its text projection returns complete deterministic entries within the `--text-budget` value, which defaults to 2,000. Follow `next=query_cursor_token` with the unchanged question and options until `next=none`. -### Query exact graph patterns with CompassQL +The cursor fails when semantic inputs, the selected graph, or the semantic result changes. The `--traverse`, `--budget`, and `--page` options retain the legacy traversal contract; CompassQL uses its own versioned contract. + +### Open the workbench ```bash -compass query --cql \ - "MATCH (caller)-[:CALLS]->(target) - WHERE target.label = 'authorizePayment()' - RETURN caller.id, target.id - LIMIT 20" \ - --format json +compass export html ``` -CompassQL is deterministic, read-only, parameterized, and resource-bounded. -See the [language contract](docs/COMPASSQL.md) and -[support matrix](docs/COMPASSQL_SUPPORT.md). - -### Travel through graph history +Build several perspectives into one self-contained page: ```bash -compass history enable --code-only -compass history build main -compass history build HEAD --profile-from main -compass query "authentication" --at HEAD~20 -compass diff main HEAD -compass diff main HEAD --format html --output semantic-diff.html +symbol_id="your_symbol_id" +compass export html \ + --code-graph \ + --architecture-graph \ + --call-graph "$symbol_id" \ + --impact-graph "$symbol_id" ``` -Historical builds use exact Git commits and immutable extraction -fingerprints. Current and historical graphs can be queried, compared, and -exported without putting generated graph data into Git. Semantic diff leads -with likely breaks, behavior changes, affected callers/modules, and test -evidence; use `--all` to expand routine symbol churn. -Default text output reports any findings beyond its display budget; use -`--limit N` to raise that budget or `--all` for exhaustive output. -HTML output is a self-contained interactive reviewer report with semantic -findings, an enhanced unified/split source diff, and a changed-subgraph view -with exhaustive node/edge delta lists. The source view is rendered by the -pinned `@pierre/diffs` library and retains the exact Git patch as an offline -fallback. HTML output requires an explicit `--output` path. +The same workbench is available through the [Compass Codegraph extension for VS Code](https://marketplace.visualstudio.com/items?itemName=crabbuild.crabbuild-compass-vscode). Search for a symbol or file, select a node, inspect its evidence and relationships, then open the exact source location. + +The exported page and VS Code graph use the same workbench shell. Switch among code, call, impact, affected, architecture, history, and artifact views without losing the snapshot context. + +Use this sequence when you explore a graph: + +1. Search for a symbol or file. +2. Select a node to inspect its source, signature, community, evidence, and relationships. +3. Open the source card, or double-click a located node, to jump to the exact code. +4. Filter communities or change the layout when you need a different level of detail. + +The graph toolbar includes an exploration panel for isolating a selected neighborhood up to four hops deep. Follow incoming, outgoing, or both edge directions, adjust layout spacing, and use the minimap to keep your place. Press `?` in the graph to see camera and exploration shortcuts. + +In VS Code, right-click inside a function to open callers, callees, impact, related symbols, or a path. + +## Keep it local and traceable + +Compass is built for teams that need useful structure without handing a repository to a remote service. + +| Principle | What it means in practice | +| --- | --- | +| Native by default | Structural extraction and graph queries run in one Rust executable. They do not require Python, embeddings, a vector database, model credentials, or runtime parser downloads. | +| Evidence first | Relationships retain direction, source anchors, and provenance. Ambiguous matches remain visible as uncertainty. | +| Bounded by design | Query rows, paths, expansions, memory, and time stay within explicit limits. A limit is reported as a limit, not an empty result. | +| History without rewriting | Historical realizations use exact Git commits and immutable fingerprints. Current and past graphs can be queried, exported, and compared. | + +Optional semantic workflows use a configured provider only when you select them. Read [Security and privacy](docs/design/security-and-privacy.md) before processing sensitive repositories. + +## Connect your existing tools -Read the [versioned history guide](docs/guides/versioned-history.md) and -[storage design](docs/design/storage-and-history.md). +### VS Code -### Connect a coding assistant +Install [Compass Codegraph](https://marketplace.visualstudio.com/items?itemName=crabbuild.crabbuild-compass-vscode), open a repository, and use the Compass sidebar to initialize or open the graph. Cursor-rooted call graphs, architecture flow, queries, and Git evolution use the same snapshot model. + +Read the [VS Code extension guide](docs/guides/vscode.md) for current graphs, cursor-rooted call graphs, architecture flow, queries, and exact Git evolution. You can also install the extension from a terminal: ```bash -compass install +code --install-extension crabbuild.crabbuild-compass-vscode ``` -Inside a Git repository, Compass detects installed coding agents and configures -them at the repository root. Codex, Gemini CLI, OpenCode, Copilot, and generic -Agent Skills clients share one portable `.agents/skills/compass` package; -Claude Code, Kiro, and Cline use their native skill roots. Use repeatable -`--platform` flags when you want explicit selection: +### Coding assistants + +Install the portable Agent Skills integration or a host-specific adapter from the repository root: ```bash +compass install compass install --platform codex compass install --platform codex --platform claude compass install --all --dry-run compass install --user --format json ``` -Check `Selected` in the command output. If it lists only `agents`, Compass did -not detect a host-specific adapter. An explicit `--platform` selection bypasses -detection. Start a new assistant session after installation. In Codex, review -and trust the hook under `/hooks`; in Gemini CLI, run `/skills reload`. +Inside a Git repository, `compass install` detects supported coding agents at the repository root and always includes the portable Agent Skills integration. Codex, Gemini CLI, OpenCode, Copilot, and generic Agent Skills clients share `.agents/skills/compass`; Claude Code, Kiro, and Cline use their native skill roots. + +Check `Selected` in the command output: + +1. If your intended host appears, start a new assistant session. +2. If the output lists only `agents`, use an explicit `--platform` selection. +3. In Codex, review and trust the hook under `/hooks`. +4. In Gemini CLI, run `/skills reload` after installation. -The skill teaches assistants to keep `compass watch` in a second terminal (or -use `compass update .` as a reported fallback), run a focused query first, and -open only cited source. For first-session or broad orientation it reads only -the bounded Agent Orientation at the start of `GRAPH_REPORT.md`, then queries. -It inspects direction, ambiguity, graph completeness, domain truncation, and -pagination; ambiguous seeds are retried by exact node ID. Installation does -not build a graph. +An explicit platform selection bypasses host detection. Installation configures the integration but does not build a graph. + +The integration starts with a bounded orientation or focused query, checks completeness and ambiguity, and opens only the cited source needed for verification. It uses `compass watch` in a second terminal, or reports `compass update .` as a refresh fallback. + +For a first session or broad repository orientation, the assistant reads only the bounded Agent Orientation at the start of `GRAPH_REPORT.md`, then runs a focused query. It checks direction, ambiguity, graph completeness, domain truncation, and pagination. Ambiguous seeds are retried by exact node ID. ```text focused task ───────────────> focused query @@ -373,71 +293,159 @@ first/broad orientation ────> bounded Agent Orientation ──> focused inspect completion and the smallest cited source set ``` -See [Assistant setup](docs/guides/assistant-setup.md) for supported platforms, -scope, strict mode, upgrades, and uninstall. +Read the [assistant setup guide](docs/guides/assistant-setup.md) for supported platforms, scope, strict mode, upgrades, and uninstall. + +### Graph exports and Model Context Protocol (MCP) + +Use `compass export` for machine-readable graph JSON, GraphML, SVG, Wiki, Obsidian, Neo4j, and FalkorDB workflows. Use [`compass serve`](docs/guides/integrating-compass.md) when you want graph resources and tools inside a compatible MCP client. -### Inspect program behavior with evidence +Inspect the supported transports and authentication options before starting a server: + +```bash +compass serve --help +``` -Native `init`, `update`, `extract`, and `watch` builds publish the structural graph by -default. Pass `--program` when a scenario needs `program.json`, the optional -language-neutral Program IR containing functions, conservative basic blocks, -operations, call candidates, capability coverage, provenance, and derived -summaries; `--program-artifact` also enables it. The offline-first pipeline -combines Tree-sitter syntax evidence for Rust and TypeScript-family languages -with any SCIP indexes already on disk. Compass does not invoke an indexer, -compiler, language server, model, or network service to build this artifact. +The MCP surface exposes bounded graph resources and tools through the same local snapshot used by the CLI and VS Code. Read the [integration guide](docs/guides/integrating-compass.md) for transport setup, health checks, and client configuration. -Schema `http://crab.build/compass/v1` reports each capability as `complete`, -`partial`, `indeterminate`, or `failed`, with machine-readable reasons for -every non-complete state. Unresolved calls are retained as uncertainty and are -never treated as proof that no downstream target exists. +### Program evidence + +Structural graphs are the default. Add the optional language-neutral Program Intermediate Representation (Program IR) when a workflow needs functions, conservative basic blocks, operations, call candidates, capability coverage, or derived summaries: + +```bash +compass update . --program +compass program summary +compass program coverage +compass program functions --language rust --name build +``` + +Native `init`, `update`, `extract`, and `watch` builds publish the structural graph by default. Pass `--program` when a workflow needs `program.json`; repeat `--program-artifact` to add offline evidence artifacts. + +The offline-first pipeline combines Tree-sitter syntax evidence for Rust and TypeScript-family languages with any Source Code Intelligence Protocol (SCIP) indexes already on disk. Compass does not invoke an indexer, compiler, language server, model, or network service to build this artifact. + +The schema `http://crab.build/compass/v1` reports each capability as `complete`, `partial`, `indeterminate`, or `failed`. Each non-complete state includes machine-readable reasons. Unresolved calls remain uncertainty; Compass never treats them as proof that no downstream target exists. Inspect or query the current artifact without custom JSON scripts: ```bash +symbol_id="your_symbol_id" compass program summary compass program coverage compass program functions --language rust --name build -compass program show -compass program callers +compass program show "$symbol_id" +compass program callers "$symbol_id" compass program explain-call src/lib.rs:240 compass program query \ "MATCH (f) WHERE f.kind = 'program_function' RETURN f LIMIT 20" ``` -Supply additional offline evidence with repeatable -`--program-artifact path/to/index.scip` options. Decoded indexes are cached by -artifact digest, while freshness and normalization are invalidated per indexed -document. +Decoded indexes are cached by artifact digest. Freshness and normalization are invalidated per indexed document. Supply additional offline evidence with repeatable `--program-artifact path/to/index.scip` options. + +## Compare history, not memory + +```bash +compass history enable --code-only +compass history build main +compass history build HEAD --profile-from main +compass query "authentication" --at HEAD~20 +compass diff main HEAD +compass diff main HEAD --format html --output semantic-diff.html +``` + +Historical builds use exact Git commits and immutable extraction fingerprints. Current and historical graphs can be queried, compared, and exported without putting generated graph data into Git. + +`compass diff` surfaces likely breaks, behavior changes, affected callers and modules, test evidence, and known limitations in one offline report. Use `--all` to include routine symbol churn. Use `--limit number_of_findings` to raise the text display budget. + +HTML output is a self-contained interactive reviewer report. It includes semantic findings, an enhanced unified and split source diff, and a changed-subgraph view with exhaustive node and edge delta lists. The source view uses the pinned `@pierre/diffs` library and retains the exact Git patch as an offline fallback. HTML output requires an explicit `--output` path. + +Read the [versioned history guide](docs/guides/versioned-history.md) and [storage design](docs/design/storage-and-history.md) for retention, profiles, and compatibility details. + +## Performance + +Compass maintains qualified performance baselines while preserving deterministic graph output and correctness. See [Performance qualification](PERFORMANCE.md) for the evidence policy and benchmark commands. + +## How it works + +![Compass graph construction and query pipeline](docs/assets/diagrams/graph-pipeline.svg) + +Compass discovers project files, extracts entities and relationships, resolves cross-file references, analyzes communities, and publishes one consistent snapshot. + +```text +function / class / file / document / schema object → node +CALLS / IMPORTS_FROM / USES / CONTAINS → relationship +dense group of related nodes → community +direct / resolved / uncertain evidence → provenance +``` + +The graph keeps relationship direction, source location, and provenance together: + +```text +CheckoutHandler + | + +-- CALLS [EXTRACTED] --> authorizePayment() + | | + | +-- USES --> PaymentGateway + | + +-- CALLS [INFERRED] --> reserveInventory() +``` + +Read [How Compass works](docs/concepts/how-it-works.md) for the full pipeline and [Graph model](docs/concepts/graph-model.md) for the data contract. -## Structural and semantic modes +## Query exact graph patterns with CompassQL -Choose the smallest mode that answers your question: +CompassQL is a deterministic, read-only, parameterized, and resource-bounded openCypher subset: -| Command | Network behavior | Best for | +```bash +compass query --cql \ + "MATCH (caller)-[:CALLS]->(target) + WHERE target.label = 'authorizePayment()' + RETURN caller.id, target.id + LIMIT 20" \ + --format json +``` + +Read the [language contract](docs/COMPASSQL.md) and [support matrix](docs/COMPASSQL_SUPPORT.md) for syntax, limits, and machine-readable output. + +## Choose the smallest mode that answers the question + +| Command | Network behavior | Best use | | --- | --- | --- | | `compass update .` | Local only | Normal source-code graph updates | | `compass extract . --code-only` | Local only | Explicit no-model extraction | | `compass extract . --code-only --cargo` | Local only | Code plus Cargo dependency edges | -| `compass extract docs --backend …` | Uses the configured provider | Semantic facts from supported documents and media | +| `compass extract docs --backend …` | Configured provider | Semantic facts from supported documents and media | + +Compass gives explicit control over optional provider boundaries. Structural graph building remains local-first and independent of those providers. + +## Project lineage and compatibility + +Compass is inspired by and modeled after [Graphify](https://github.com/Graphify-Labs/graphify), which established the workflow of extracting a codebase into a knowledge graph, analyzing communities, and querying focused context. + +Compass is now an independent product with its own Rust implementation, commands, configuration, artifacts, and test suite. It does not execute or depend on Graphify. + +### Compass capabilities + +| Area | What Compass does | +| --- | --- | +| Runtime | Runs structural extraction and graph queries in one native Rust executable | +| Exact queries | Provides CompassQL, a deterministic and bounded read-only openCypher subset | +| Versioned graphs | Keeps immutable realizations for exact commits, historical queries, exports, and diffs | +| Incremental operation | Reuses compatible unchanged extraction work and atomically publishes graph plus manifest | +| Query safety | Enforces explicit row, path, expansion, memory, and time limits | +| Native distribution | Links parsers and native implementations for supported graph, media, database, and service boundaries | -Semantic extraction is optional. Compass contacts a model provider only when -you select a provider-backed workflow. Read -[Security and privacy](docs/design/security-and-privacy.md) before processing -sensitive repositories. +Read [Compatibility](COMPATIBILITY.md) for Compass-owned contracts and [Migration from Graphify](MIGRATION.md) for the one-time hard cutover. -## Find the right document +## Find your next page | You are… | Start here | | --- | --- | | Evaluating Compass | [Getting started](docs/getting-started.md) → [How it works](docs/concepts/how-it-works.md) | -| Using or integrating Compass | [Guides](docs/README.md#complete-a-task) → [Cookbook](docs/cookbook/README.md) | +| Using or integrating Compass | [Documentation hub](docs/README.md) → [Cookbook](docs/cookbook/README.md) | | Extending the Rust workspace | [Architecture](docs/design/architecture.md) → [Workspace tour](docs/implementation/workspace-tour.md) | | Looking up an interface | [Commands](docs/reference/commands.md) → [Outputs](docs/reference/outputs.md) | -| Tracking future direction | [Available, planned, and aspirational roadmap](docs/roadmap.md) | +| Tracking future direction | [Roadmap](docs/roadmap.md) | -The [documentation hub](docs/README.md) links every concept, guide, design, -implementation note, recipe, and reference. +The [documentation hub](docs/README.md) links every concept, guide, design, implementation note, recipe, and reference. Start with the [guides](docs/README.md#complete-a-task) when you have a concrete task to complete. ## Community and contributing @@ -448,13 +456,8 @@ implementation note, recipe, and reference. | Security vulnerability | [Private vulnerability reporting](https://github.com/crabbuild/compass/security/advisories/new) | | Code or documentation contribution | [Contributing guide](CONTRIBUTING.md) | -Development checks, architecture boundaries, and contribution expectations are -documented in [CONTRIBUTING.md](CONTRIBUTING.md). Support and disclosure -boundaries live in [SUPPORT.md](SUPPORT.md) and [SECURITY.md](SECURITY.md). +Development checks and architecture boundaries live in [CONTRIBUTING.md](CONTRIBUTING.md). Support and disclosure boundaries live in [SUPPORT.md](SUPPORT.md) and [SECURITY.md](SECURITY.md). ## License -Compass's original work is dual-licensed under -[MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE). -Third-party components retain their original licenses; see -[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). +Compass's original work is dual-licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE). Third-party components retain their original licenses; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). diff --git a/docs/assets/screenshots/readme-cli11-code-graph.png b/docs/assets/screenshots/readme-cli11-code-graph.png new file mode 100644 index 00000000..87543324 Binary files /dev/null and b/docs/assets/screenshots/readme-cli11-code-graph.png differ diff --git a/docs/assets/screenshots/readme-ripgrep-architecture.png b/docs/assets/screenshots/readme-ripgrep-architecture.png new file mode 100644 index 00000000..ac025d6e Binary files /dev/null and b/docs/assets/screenshots/readme-ripgrep-architecture.png differ diff --git a/docs/assets/screenshots/readme-ripgrep-call-graph.png b/docs/assets/screenshots/readme-ripgrep-call-graph.png new file mode 100644 index 00000000..b02996f2 Binary files /dev/null and b/docs/assets/screenshots/readme-ripgrep-call-graph.png differ diff --git a/docs/assets/screenshots/readme-ripgrep-dependencies.png b/docs/assets/screenshots/readme-ripgrep-dependencies.png new file mode 100644 index 00000000..aadcd6a7 Binary files /dev/null and b/docs/assets/screenshots/readme-ripgrep-dependencies.png differ