feat: ship Compass Code Graph v1

.gitattributes

@@ -1 +1,3 @@
 crates/compass-cli/assets/vendor/pierre-diffs-v1.2.12.js -whitespace
+crates/compass-output/assets/viewer/graph.js -whitespace
+crates/compass-cli/assets/compass-skill/** text eol=lf

.github/workflows/compass-ci.yml

@@ -19,6 +19,27 @@ defaults:
     working-directory: .
 
 jobs:
+  code-graph-v1-fixtures:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: "24.13.1"
+          cache: npm
+      - name: Install pinned Rust toolchain
+        uses: dtolnay/rust-toolchain@2c7215f132e9ebf062739d9130488b56d53c060c # master
+        with:
+          toolchain: 1.97.1
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        with:
+          workspaces: .
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+      - name: Qualify Compass code graph v1
+        run: ./scripts/qualify_code_graph_v1.sh --fixtures-only
+
   javascript-and-vscode:
     runs-on: ubuntu-24.04
     steps:
@@ -81,7 +102,10 @@ jobs:
         run: cargo nextest run --workspace --lib --bins --locked
 
       - name: Verify publishable crate archives
-        run: cargo package --workspace --locked --no-verify
+        run: |
+          cargo package --workspace --locked --no-verify \
+            --exclude compass-transcribe \
+            --exclude compass-whisper
 
       - name: Verify cargo install and standalone launch
         shell: bash
@@ -140,6 +164,11 @@ jobs:
       - name: Native tests
         run: cargo test --workspace --lib --bins --locked --target ${{ matrix.target }}
 
+      - name: Code graph deterministic publication and SQLite recovery
+        run: |
+          cargo test -p compass-core --test code_graph_v1_determinism --locked --target ${{ matrix.target }}
+          cargo test -p compass-query --test index_recovery --locked --target ${{ matrix.target }}
+
       - name: Test PowerShell installer
         if: runner.os == 'Windows'
         shell: pwsh
@@ -148,6 +177,26 @@ jobs:
           ./scripts/test_install_ps1.ps1 `
             -CompassBinary "target/${{ matrix.target }}/release/compass.exe"
 
+  code-graph-client-platforms:
+    strategy:
+      fail-fast: false
+      matrix:
+        runner: [ubuntu-24.04, macos-15, windows-2025]
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: "24.13.1"
+          cache: npm
+      - run: npm ci
+      - name: Source containment and process cancellation
+        run: >-
+          npm exec -w editors/vscode --
+          vitest run
+          src/views/sourceResolution.test.ts
+          src/cli/processManager.test.ts
+
   dependency-audit:
     runs-on: ubuntu-24.04
     steps:

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+- Introduce the first supported Compass code graph contract,
+  `compass.graph/1`, as a strict versioned NetworkX-compatible multigraph with
+  structural, framework, enterprise, messaging, job, schema, configuration,
+  and database kinds.
+- Add explicit `routes_to` bindings for supported server and file-routing
+  frameworks, preserving middleware order and attributable heuristic wiring.
+- Add the shared `compass.query/1` search, callers, callees, impact, explore,
+  and node-trail contract across CLI, MCP, the viewer, and VS Code.
+- Hard-cut over graph persistence: artifacts without `compass.graph/1` are not
+  loaded through an adapter. Run `compass update` to rebuild them.
 - Correct C function identities by resolving the callable declarator before
   generic declaration names, including macro-heavy SQLite declarations.
 - Preserve repeated Markdown sections and rationale entries as distinct

Cargo.toml

@@ -31,7 +31,7 @@ members = [
     "vendor/compass-tree-sitter-language-pack",
 ]
 resolver = "3"
-exclude = ["fuzz"]
+exclude = ["fuzz", "vendor/gemm-common"]
 
 [workspace.package]
 version = "0.1.10"
@@ -71,6 +71,8 @@ oxidize-pdf = { version = "4.1.1", default-features = false, features = ["compre
 ctrlc = "3.5.2"
 strsim = "0.11"
 rayon = "1"
+rusqlite = { version = "0.31.0", features = ["bundled", "modern_sqlite"] }
+rustix = { version = "1.1", features = ["fs"] }
 rand = "0.8.7"
 realfft = "3.5.0"
 regex = "1"
@@ -125,3 +127,6 @@ codegen-units = 1
 lto = "thin"
 panic = "abort"
 strip = "symbols"
+
+[patch.crates-io]
+gemm-common = { path = "vendor/gemm-common" }

Makefile

@@ -129,6 +129,10 @@ test-product: ## Run the Compass CLI product contract
 test-release-scripts: ## Test packaging and download installer scripts
 	sh scripts/test_release_scripts.sh
 
+.PHONY: qualify-code-graph-v1
+qualify-code-graph-v1: ## Run the complete Compass code graph v1 fixture release gate
+	./scripts/qualify_code_graph_v1.sh --fixtures-only
+
 # ── Lint & Format ──────────────────────────────────────────────────
 
 .PHONY: fmt

crates/compass-analysis/Cargo.toml

@@ -12,8 +12,8 @@ keywords.workspace = true
 categories.workspace = true
 
 [dependencies]
-compass-ir = { path = "../compass-ir" }
-compass-model = { path = "../compass-model" }
+compass-ir = { path = "../compass-ir", version = "0.1.4" }
+compass-model = { path = "../compass-model", version = "0.1.4" }
 rayon.workspace = true
 serde.workspace = true
 sha2.workspace = true

crates/compass-analysis/src/universal_call_graph.rs

@@ -595,11 +595,7 @@ fn coverage(
 }
 
 fn line(node: &NodeRecord, key: &str) -> Option<u64> {
-    node.attributes.get(key).and_then(|value| {
-        value
-            .as_u64()
-            .or_else(|| value.as_i64().and_then(|value| value.try_into().ok()))
-    })
+    node.unsigned(key)
 }
 
 fn source_line(location: &str) -> Option<u64> {

crates/compass-cargo/src/lib.rs

@@ -105,11 +105,26 @@ pub fn introspect_cargo(root: &Path) -> Result<CargoGraph, CargoIntrospectionErr
             id: manifest.id.clone(),
             attributes: Map::from_iter([
                 ("label".to_owned(), Value::String(name.clone())),
+                ("name".to_owned(), Value::String(name.clone())),
+                ("qualified_name".to_owned(), Value::String(name.clone())),
+                (
+                    "symbol_kind".to_owned(),
+                    Value::String("package".to_owned()),
+                ),
+                ("file_type".to_owned(), Value::String("code".to_owned())),
+                ("language".to_owned(), Value::String("rust".to_owned())),
                 (
                     "source_file".to_owned(),
                     Value::String(relative_posix(&manifest.path, &root)?),
                 ),
                 ("source_location".to_owned(), Value::String("L1".to_owned())),
+                ("line_start".to_owned(), Value::from(1)),
+                ("line_end".to_owned(), Value::from(1)),
+                ("_origin".to_owned(), Value::String("ast".to_owned())),
+                (
+                    "extractor".to_owned(),
+                    Value::String("compass.cargo".to_owned()),
+                ),
             ]),
         });
     }
@@ -141,7 +156,7 @@ pub fn introspect_cargo(root: &Path) -> Result<CargoGraph, CargoIntrospectionErr
                 attributes: Map::from_iter([
                     (
                         "relation".to_owned(),
-                        Value::String("crate_depends_on".to_owned()),
+                        Value::String("depends_on".to_owned()),
                     ),
                     (
                         "context".to_owned(),
@@ -154,6 +169,11 @@ pub fn introspect_cargo(root: &Path) -> Result<CargoGraph, CargoIntrospectionErr
                     ),
                     ("source_file".to_owned(), Value::String(source_file.clone())),
                     ("source_location".to_owned(), Value::String("L1".to_owned())),
+                    ("_origin".to_owned(), Value::String("ast".to_owned())),
+                    (
+                        "extractor".to_owned(),
+                        Value::String("compass.cargo".to_owned()),
+                    ),
                 ]),
             });
         }

crates/compass-cli/assets/compass-skill/references/command-reference.md

@@ -8,6 +8,14 @@ whether a Compass capability is covered by the installed skill. Run
 
 - `compass capabilities`: report versioned, read-only machine contracts for
   editor and automation integrations.
+- `compass search`: find typed symbols by name using the local FTS index.
+- `compass callers`: list direct typed call-graph predecessors.
+- `compass callees`: list direct typed call-graph successors.
+- `compass impact`: compute bounded transitive change impact, excluding
+  heuristic evidence unless explicitly requested.
+- `compass explore`: return related source grouped by file plus connecting
+  paths in one bounded response.
+- `compass node`: show an attributable evidence trail between two symbols.
 - `compass call-graph`: trace bounded callers, callees, or both from a source
   position or structural symbol, with optional Program IR enrichment.
 - `compass query`: natural-language graph traversal or deterministic CompassQL.

crates/compass-cli/assets/compass-skill/references/query.md

@@ -32,12 +32,25 @@ compass query "authentication flow" --at HEAD~20
 ## Focused graph operations
 
 ```bash
+compass search PaymentGateway
+compass callers PaymentGateway.charge
+compass callees CheckoutController.create
+compass impact authorizePayment --max-depth 3
+compass explore CheckoutController PaymentGateway --root .
+compass node route:/checkout CheckoutController.create
 compass explain PaymentGateway
 compass path CheckoutHandler PaymentGateway
 compass affected authorizePayment --depth 3
 compass tree
 ```
 
+- `search` resolves typed symbols by exact or fuzzy name.
+- `callers` and `callees` walk one attributable call-graph hop.
+- `impact` traverses a bounded transitive radius and excludes heuristic
+  evidence by default.
+- `explore` returns related source and paths together under source and response
+  byte limits.
+- `node` exposes the evidence trail and provenance between two symbols.
 - `explain` reports a matched node and connected context.
 - `path` reports the shortest known graph route; preserve relation direction.
 - `affected` follows impact relations and returns a review candidate set.

crates/compass-cli/build.rs

@@ -25,6 +25,10 @@ fn collect(root: &Path, directory: &Path, files: &mut Vec<PathBuf>) -> io::Resul
     Ok(())
 }
 
+fn canonical_text(input: &str) -> String {
+    input.replace("\r\n", "\n").replace('\r', "\n")
+}
+
 fn main() -> Result<(), Box<dyn std::error::Error>> {
     println!(
         "cargo:rustc-env=COMPASS_BUILD_TARGET={}",
@@ -45,17 +49,24 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     for directory in ["compass-skill", "compass-integrations"] {
         collect(&root, &root.join(directory), &mut files)?;
     }
+    let output = PathBuf::from(env::var("OUT_DIR")?);
+    let embedded_root = output.join("install-assets");
     let mut generated = String::from("static EMBEDDED_ASSETS: &[EmbeddedAsset] = &[\n");
     for relative in files {
         let source = root.join(&relative);
+        let embedded = embedded_root.join(&relative);
+        if let Some(parent) = embedded.parent() {
+            fs::create_dir_all(parent)?;
+        }
+        let body = fs::read_to_string(&source)?;
+        fs::write(&embedded, canonical_text(&body))?;
         generated.push_str(&format!(
             "    EmbeddedAsset {{ path: {:?}, bytes: include_bytes!({:?}) }},\n",
             relative.to_string_lossy().replace('\\', "/"),
-            source
+            embedded
         ));
     }
     generated.push_str("];\n");
-    let output = PathBuf::from(env::var("OUT_DIR")?);
     fs::write(output.join("install_assets.rs"), generated)?;
     Ok(())
 }