Merge pull request #213 from SimplyLiz/develop

release: v9.1.0

Author: SimplyLiz

.gitignore

@@ -8,8 +8,10 @@ bin/
 /ckb
 /ckb-test
 /ckb-bench
+/ckb_fresh
 coverage.out
 *_test
+*.test
 *.scip
 
 # Registry / credential tokens

CHANGELOG.md

@@ -2,6 +2,82 @@
 
 All notable changes to CKB will be documented in this file.
 
+## [Unreleased]
+
+## [9.1.0] - 2026-04-16
+
+### Added
+
+- **LIP v2.1 utilisation** — three high-ROI LIP RPCs wired into the query
+  engine, gated on the handshake's `supported_messages`:
+  - `stream_context` (v2.1) → `explainFile` attaches up to 10
+    semantically-related symbols (2048-token budget) in `facts.related`.
+    New streaming transport reads N `symbol_info` frames + `end_stream`.
+  - `query_expansion` (v1.6) → `searchSymbols` expands ≤ 2-token queries
+    with up to 5 related terms before FTS5, recovering vocabulary-mismatch
+    recall without touching precision on compound queries.
+  - `explain_match` (v2.0) → semantic search hits carry up to two ranked
+    evidence chunks with line ranges, text, and per-chunk scores (top-5
+    hits, bounded round-trip cost).
+- **`lip.Handshake` runs on engine startup** and the daemon's
+  `supported_messages` list is stashed for feature gating
+  (`Engine.lipSupports`). Daemon version and supported-count logged.
+- **LIP index status probing** — `probeHandshake` now follows up with
+  `IndexStatus` and caches the result. New `Engine.LIPStatus()` returns
+  `{Reachable, IndexedFiles}` so consumers can distinguish "daemon down"
+  from "daemon up, nothing indexed."
+- **`ckb review` warns when LIP index is empty** — stderr advisory with
+  `lip index <repo>` command when daemon is reachable but has no content.
+  Suppressed in `--ci` to keep CI logs clean.
+- `NoAutoFetch` option on `SummarizePROptions` and `SummarizeDiffOptions`
+  for parity with `ReviewPROptions`.
+- Troubleshooting section in `docs/plans/review-cicd.md` covering shallow
+  CI clones, auth-failure remediation, air-gapped pipelines, and depth-0
+  checkout alternatives.
+- Auth-error detection on auto-fetch with clear remediation guidance.
+- `ckb review --no-auto-fetch` flag for air-gapped pipelines.
+- Test coverage for `GitAdapter.EnsureRef` — happy path, missing-ref
+  auto-fetch, unreachable origin, and empty-input guard.
+### Changed
+
+- **LIP health: push-driven, not polled** — Engine opens a long-lived
+  connection to the daemon at startup (`internal/lip/subscribe.go`) with
+  `index_changed` frames and per-ping `index_status` snapshots instead of
+  60 s TTL polling. Worst-case staleness drops from 60 s to ~3 s.
+- **`lipFileURI` path normalisation** — handles absolute paths and
+  already-prefixed `file://` URIs without producing malformed results.
+
+### Fixed
+
+- **Bug-pattern false positive on `sync.Mutex.Lock()`** — removed `"Lock"`
+  from `LikelyReturnsError` heuristic patterns; `sync.Mutex.Lock` returns
+  nothing and dominated real-world matches with false positives.
+- **`err` shadowing in `subscribe.go`** — four shadow sites eliminated by
+  reusing outer `err` or renaming to `pingErr`/`readErr` where scope
+  isolation requires it.
+
+- **LIP rerank: coherence gate + position-weighted seeding** (#209) — the
+  Fast-tier semantic rerank (`internal/query/lip_ranker.go`) used to average the
+  top-5 seed embeddings with uniform weight and always apply the result. When
+  the top-5 pointed in different directions the centroid collapsed toward zero
+  and amplified noise; when the top seed was strong the blend still diluted it.
+  Seeds are now L2-normalised and position-weighted (`1/(rank+1)`), the
+  resulting centroid norm is read as a coherence score in `[0, 1]`, and the
+  rerank falls back to pure lexical order when coherence is below
+  `MinCoherence` (default `0.35`). Blend weights, seed count, and threshold are
+  surfaced as `RerankConfig` so future tuning does not need to touch call
+  sites. Injected `embedBatchFn` makes the ranker unit-testable without a
+  running daemon.
+- **LIP rerank: gate on `!MixedModels`** (#208) — when the LIP index contains
+  vectors from more than one embedding model (e.g. partial re-index during a
+  model upgrade), cosine similarity across those vectors is mathematically
+  meaningless. `RerankWithLIP` and `SemanticSearchWithLIP` now consult a
+  cached `Engine.lipSemanticAvailable()` check (60 s TTL, single `IndexStatus`
+  RPC) and fall back to lexical ranking when the daemon is down or reports
+  `mixed_models`. A new `lip_mixed_models` degradation warning (70% capability)
+  surfaces in response metadata so users learn *why* results look weaker
+  instead of silently ranking on garbage.
+
 ## [9.0.1] - 2026-04-15
 
 ### Fixed

cmd/ckb-bench/version_test.go

@@ -45,6 +45,7 @@ var (
 	reviewMinReviewers       int
 	// New analyzer flags
 	reviewStaged             bool
+	reviewNoAutoFetch        bool
 	reviewScope              string
 	reviewMaxBlastRadius     int
 	reviewMaxFanOut          int
@@ -146,6 +147,7 @@ func init() {
 
 	// New analyzers
 	reviewCmd.Flags().BoolVar(&reviewStaged, "staged", false, "Review staged changes instead of branch diff")
+	reviewCmd.Flags().BoolVar(&reviewNoAutoFetch, "no-auto-fetch", false, "Disable automatic fetch of the base ref from origin when missing locally (for air-gapped CI)")
 	reviewCmd.Flags().StringVar(&reviewScope, "scope", "", "Filter to path prefix or symbol name")
 	reviewCmd.Flags().IntVar(&reviewMaxBlastRadius, "max-blast-radius", 0, "Maximum blast radius delta (0 = disabled)")
 	reviewCmd.Flags().IntVar(&reviewMaxFanOut, "max-fanout", 0, "Maximum fan-out / caller count (0 = disabled)")
@@ -225,11 +227,14 @@ func runReview(cmd *cobra.Command, args []string) {
 		Policy:     policy,
 		Checks:     reviewChecks,
 		SkipChecks: reviewSkipChecks,
-		Staged:     reviewStaged,
-		Scope:      scope,
-		LLM:        reviewLLM,
+		Staged:      reviewStaged,
+		Scope:       scope,
+		LLM:         reviewLLM,
+		NoAutoFetch: reviewNoAutoFetch,
 	}
 
+	warnIfLIPIndexEmpty(engine, repoRoot)
+
 	response, err := engine.ReviewPR(ctx, opts)
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "Error running review: %v\n", err)
@@ -311,6 +316,27 @@ func runReview(cmd *cobra.Command, args []string) {
 	}
 }
 
+// warnIfLIPIndexEmpty prints a stderr advisory when the LIP daemon is
+// reachable but has no content indexed. Semantic enrichment (stream_context,
+// query_expansion, explain_match) silently returns empty in that case, which
+// is indistinguishable from "feature disabled" from the user's side — so we
+// tell them and show the exact command to build the index.
+//
+// The warning goes to stderr so it doesn't pollute JSON/SARIF stdout that
+// CI pipelines parse. Suppressed in --ci mode to keep CI logs tight.
+func warnIfLIPIndexEmpty(engine *query.Engine, repoRoot string) {
+	if reviewCI {
+		return
+	}
+	s := engine.LIPStatus()
+	if !s.Reachable || s.IndexedFiles > 0 {
+		return
+	}
+	fmt.Fprintln(os.Stderr, "⚠ LIP daemon reachable but has no index for this workspace.")
+	fmt.Fprintln(os.Stderr, "  Semantic enrichment (related symbols, query expansion, explain-match) will be skipped.")
+	fmt.Fprintf(os.Stderr, "  Run:  lip index %s\n\n", repoRoot)
+}
+
 // --- Output Formatters ---
 
 func formatReviewHuman(resp *query.ReviewPRResponse) string {

cmd/ckb/review.go

@@ -673,6 +673,51 @@ jobs:
           sarif: true
 ```
 
+### Troubleshooting: Shallow CI Clones
+
+Azure Pipelines, GitHub Actions und GitLab machen standardmäßig einen
+**shallow, single-branch Checkout** — nur der PR-Branch landet lokal, der
+Base-Branch (z.B. `main`) fehlt. Vor 9.0.1 scheiterte `ckb review --base=main`
+dann mit `git command failed: exit status 128`.
+
+**Ab 9.0.1:** `ckb review` holt den fehlenden Base-Ref automatisch per
+`git fetch origin <branch>` von origin, sobald er lokal nicht auflösbar ist.
+In den meisten Pipelines funktioniert das ohne Änderung — der Auth-Token aus
+dem Checkout-Step wird wiederverwendet.
+
+**Wenn der Auto-Fetch fehlschlägt:**
+
+| Fehlermeldung | Ursache | Fix |
+|---|---|---|
+| `Authentication failed` / `could not read Username` / `401` / `403` | Checkout hat den Token nach dem Clone entfernt | Checkout-Step mit `persistCredentials: true` (Azure) oder `persist-credentials: true` (GitHub Actions) konfigurieren |
+| `Permission denied (publickey)` | SSH-Key nicht im Agent | SSH-Key zum CI-Agent hinzufügen oder HTTPS-Remote verwenden |
+| `couldn't find remote ref <X>` | Branch auf origin gelöscht oder falsch geschrieben | `--base` prüfen |
+
+**Air-gapped Pipelines:** In Umgebungen, wo Netzwerk-Calls ausserhalb des
+Checkout-Steps verboten sind, Auto-Fetch deaktivieren:
+
+```bash
+# Vor dem Review: Base-Ref explizit holen
+git fetch origin main:refs/heads/main
+ckb review --no-auto-fetch --base=main
+```
+
+**Alternative:** Shallow-Checkout ganz vermeiden. Für GitHub Actions:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+```
+
+Für Azure Pipelines:
+
+```yaml
+- checkout: self
+  fetchDepth: 0
+  persistCredentials: true
+```
+
 ## Phase 7: Baseline & Finding Lifecycle — `ckb review baseline`
 
 Inspiriert von Qodana, PVS-Studio und Trunk: Findings werden nicht nur als "da/nicht da" behandelt, sondern haben einen Lifecycle.

docs/plans/review-cicd.md

@@ -120,6 +120,46 @@ func (g *GitAdapter) Capabilities() []string {
 	}
 }
 
+// isAuthError returns true if the error looks like git failed to authenticate
+// against the remote. Used to give the user an actionable message instead of
+// a raw git stderr dump.
+func isAuthError(err error) bool {
+	if err == nil {
+		return false
+	}
+	s := strings.ToLower(err.Error())
+	for _, marker := range []string{
+		"authentication failed",
+		"could not read username",
+		"could not read password",
+		"terminal prompts disabled",
+		"403 forbidden",
+		"401 unauthorized",
+		"permission denied (publickey)",
+	} {
+		if strings.Contains(s, marker) {
+			return true
+		}
+	}
+	// "repository '...' not found" is typically an auth failure on private repos.
+	if strings.Contains(s, "repository") && strings.Contains(s, "not found") {
+		return true
+	}
+	return false
+}
+
+// VerifyRef returns nil iff ref resolves to a commit in the local repo.
+// Unlike EnsureRef it never fetches. Use when auto-fetch is disabled.
+func (g *GitAdapter) VerifyRef(ref string) error {
+	if ref == "" {
+		return fmt.Errorf("empty ref")
+	}
+	if _, err := g.executeGitCommand("rev-parse", "--verify", "--quiet", ref+"^{commit}"); err != nil {
+		return fmt.Errorf("ref %q not present locally (auto-fetch disabled)", ref)
+	}
+	return nil
+}
+
 // EnsureRef returns a locally-resolvable form of the given ref, fetching
 // from origin if needed. Handles shallow CI clones that only fetch the PR
 // branch (Azure Pipelines, GitHub Actions defaults, GitLab default, etc.) —
@@ -145,6 +185,11 @@ func (g *GitAdapter) EnsureRef(ref string) (string, error) {
 
 	g.logger.Info("Base ref not found locally; fetching from origin", "ref", ref, "branch", branch)
 	if _, err := g.executeGitCommand("fetch", "--no-tags", "origin", branch); err != nil {
+		if isAuthError(err) {
+			return "", fmt.Errorf("ref %q not found locally and fetching from origin failed due to missing credentials. "+
+				"Your CI checkout likely stripped the auth token — enable persistCredentials (Azure Pipelines, GitHub Actions) "+
+				"or run `ckb review --no-auto-fetch` with a pre-fetched base ref. Underlying error: %w", ref, err)
+		}
 		return "", fmt.Errorf("ref %q not found locally and `git fetch origin %s` failed: %w", ref, branch, err)
 	}