@gmickel/gno 1.22.0 → 1.23.0

package/src/core/project-affinity.ts

@@ -0,0 +1,330 @@
+/**
+ * Trusted project-root resolution for project-aware retrieval affinity.
+ *
+ * This module resolves local roots only. Remote hints remain opaque and never
+ * trigger filesystem probes. Returned metadata is path-redacted; ranking is a
+ * separate concern.
+ *
+ * @module src/core/project-affinity
+ */
+
+// node:fs/promises for directory stat/realpath (no Bun directory equivalent)
+import { realpath, stat } from "node:fs/promises";
+// node:path for path utilities (no Bun path utils)
+import { dirname, join, relative, sep } from "node:path";
+
+import type {
+  Collection,
+  ProjectAffinityInput,
+  ProjectAffinityRoot,
+  TrustedProjectRootSource,
+} from "../config/types";
+
+import { isCanonicalPathContained } from "./validation";
+
+export type ProjectAffinityZeroReason =
+  | "no_collection_match"
+  | "root_unavailable"
+  | "untrusted_remote_hint";
+
+export type ProjectAffinityRelation =
+  | "collection_contains_root"
+  | "exact"
+  | "root_contains_collection";
+
+export interface ProjectAffinityMatch {
+  collection: string;
+  collectionAlias: string;
+  distance: number;
+  relation: ProjectAffinityRelation;
+  rootAlias: string;
+  source: TrustedProjectRootSource;
+}
+
+export interface ProjectAffinityRootMetadata {
+  collectionAliases: string[];
+  reason: ProjectAffinityZeroReason | null;
+  repositoryRootDiscovered: boolean;
+  rootAlias: string;
+  source: ProjectAffinityRoot["source"];
+  status: "matched" | "zero";
+}
+
+export interface ProjectAffinityResolution {
+  matches: ProjectAffinityMatch[];
+  roots: ProjectAffinityRootMetadata[];
+}
+
+export interface ProjectAffinityResolverDependencies {
+  canonicalizePath: (path: string) => Promise<string>;
+  discoverRepositoryRoot: (path: string) => Promise<string | null>;
+}
+
+/**
+ * Trust is supplied by the invoking surface, never inferred from payload data.
+ */
+export interface ProjectAffinityResolverContext {
+  channel: "local" | "remote";
+}
+
+interface CanonicalCollection {
+  alias: string;
+  name: string;
+  path: string;
+}
+
+interface CanonicalTrustedRoot {
+  path: string;
+  repositoryRootDiscovered: boolean;
+  rootAlias: string;
+  source: TrustedProjectRootSource;
+}
+
+const alias = (namespace: "collection" | "root", value: string): string => {
+  const hash = new Bun.CryptoHasher("sha256")
+    .update(`${namespace}\0${value}`)
+    .digest("hex")
+    .slice(0, 12);
+  return `${namespace}_${hash}`;
+};
+
+const defaultCanonicalizePath = (path: string): Promise<string> =>
+  realpath(path);
+
+const isDirectoryOrFile = async (path: string): Promise<boolean> => {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const defaultDiscoverRepositoryRoot = async (
+  startingPath: string
+): Promise<string | null> => {
+  let current = startingPath;
+  while (true) {
+    if (await isDirectoryOrFile(join(current, ".git"))) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+};
+
+const pathDistance = (parent: string, child: string): number => {
+  const nestedPath = relative(parent, child);
+  if (nestedPath === "") {
+    return 0;
+  }
+  return nestedPath.split(sep).filter(Boolean).length;
+};
+
+const describeRelationship = (
+  collectionPath: string,
+  rootPath: string
+): Pick<ProjectAffinityMatch, "distance" | "relation"> | null => {
+  if (collectionPath === rootPath) {
+    return { distance: 0, relation: "exact" };
+  }
+  if (isCanonicalPathContained(collectionPath, rootPath)) {
+    return {
+      distance: pathDistance(collectionPath, rootPath),
+      relation: "collection_contains_root",
+    };
+  }
+  if (isCanonicalPathContained(rootPath, collectionPath)) {
+    return {
+      distance: pathDistance(rootPath, collectionPath),
+      relation: "root_contains_collection",
+    };
+  }
+  return null;
+};
+
+const canonicalizeCollections = async (
+  collections: readonly Collection[],
+  canonicalizePath: ProjectAffinityResolverDependencies["canonicalizePath"]
+): Promise<CanonicalCollection[]> => {
+  const resolved = await Promise.all(
+    collections.map(async (collection): Promise<CanonicalCollection | null> => {
+      try {
+        const path = await canonicalizePath(collection.path);
+        return {
+          alias: alias("collection", collection.name),
+          name: collection.name,
+          path,
+        };
+      } catch {
+        return null;
+      }
+    })
+  );
+  return resolved
+    .filter((collection): collection is CanonicalCollection =>
+      Boolean(collection)
+    )
+    .sort((left, right) => left.name.localeCompare(right.name));
+};
+
+const canonicalizeTrustedRoot = async (
+  root: Extract<ProjectAffinityRoot, { path: string }>,
+  dependencies: ProjectAffinityResolverDependencies
+): Promise<CanonicalTrustedRoot | null> => {
+  let canonicalPath: string;
+  try {
+    canonicalPath = await dependencies.canonicalizePath(root.path);
+  } catch {
+    return null;
+  }
+
+  let repositoryRootDiscovered = false;
+  if (root.source === "cli_cwd" || root.source === "cli_worktree") {
+    let discovered: string | null = null;
+    try {
+      discovered = await dependencies.discoverRepositoryRoot(canonicalPath);
+    } catch {
+      // Repository discovery is opportunistic; the trusted canonical cwd
+      // remains a valid affinity root when discovery is unavailable.
+    }
+    if (discovered) {
+      try {
+        canonicalPath = await dependencies.canonicalizePath(discovered);
+        repositoryRootDiscovered = true;
+      } catch {
+        return null;
+      }
+    }
+  }
+
+  return {
+    path: canonicalPath,
+    repositoryRootDiscovered,
+    rootAlias: alias("root", canonicalPath),
+    source: root.source,
+  };
+};
+
+const zeroMetadata = (
+  root: ProjectAffinityRoot,
+  reason: ProjectAffinityZeroReason,
+  source: ProjectAffinityRoot["source"] = root.source
+): ProjectAffinityRootMetadata => ({
+  collectionAliases: [],
+  reason,
+  repositoryRootDiscovered: false,
+  rootAlias: alias(
+    "root",
+    root.source === "remote_hint" ? root.hint : root.path
+  ),
+  source,
+  status: "zero",
+});
+
+const relationOrder: Record<ProjectAffinityRelation, number> = {
+  exact: 0,
+  collection_contains_root: 1,
+  root_contains_collection: 2,
+};
+
+const compareMatches = (
+  left: ProjectAffinityMatch,
+  right: ProjectAffinityMatch
+): number =>
+  relationOrder[left.relation] - relationOrder[right.relation] ||
+  left.distance - right.distance ||
+  left.collection.localeCompare(right.collection) ||
+  left.rootAlias.localeCompare(right.rootAlias);
+
+export async function resolveProjectAffinity(
+  input: ProjectAffinityInput,
+  collections: readonly Collection[],
+  context: ProjectAffinityResolverContext,
+  overrides: Partial<ProjectAffinityResolverDependencies> = {}
+): Promise<ProjectAffinityResolution> {
+  if (context.channel === "remote") {
+    return {
+      matches: [],
+      roots: input.roots.map((root) =>
+        zeroMetadata(root, "untrusted_remote_hint", "remote_hint")
+      ),
+    };
+  }
+
+  const dependencies: ProjectAffinityResolverDependencies = {
+    canonicalizePath: overrides.canonicalizePath ?? defaultCanonicalizePath,
+    discoverRepositoryRoot:
+      overrides.discoverRepositoryRoot ?? defaultDiscoverRepositoryRoot,
+  };
+  const trustedRoots = input.roots.filter(
+    (root): root is Extract<ProjectAffinityRoot, { path: string }> =>
+      root.source !== "remote_hint"
+  );
+  const canonicalCollections =
+    trustedRoots.length === 0
+      ? []
+      : await canonicalizeCollections(
+          collections,
+          dependencies.canonicalizePath
+        );
+  const matches: ProjectAffinityMatch[] = [];
+  const roots: ProjectAffinityRootMetadata[] = [];
+
+  for (const root of input.roots) {
+    if (root.source === "remote_hint") {
+      roots.push(zeroMetadata(root, "untrusted_remote_hint"));
+      continue;
+    }
+
+    const canonicalRoot = await canonicalizeTrustedRoot(root, dependencies);
+    if (!canonicalRoot) {
+      roots.push(zeroMetadata(root, "root_unavailable"));
+      continue;
+    }
+
+    const rootMatches = canonicalCollections
+      .map((collection): ProjectAffinityMatch | null => {
+        const relationship = describeRelationship(
+          collection.path,
+          canonicalRoot.path
+        );
+        return relationship
+          ? {
+              collection: collection.name,
+              collectionAlias: collection.alias,
+              rootAlias: canonicalRoot.rootAlias,
+              source: canonicalRoot.source,
+              ...relationship,
+            }
+          : null;
+      })
+      .filter((match): match is ProjectAffinityMatch => Boolean(match))
+      .sort(compareMatches);
+
+    if (rootMatches.length === 0) {
+      roots.push({
+        ...zeroMetadata(root, "no_collection_match"),
+        repositoryRootDiscovered: canonicalRoot.repositoryRootDiscovered,
+        rootAlias: canonicalRoot.rootAlias,
+      });
+      continue;
+    }
+
+    matches.push(...rootMatches);
+    roots.push({
+      collectionAliases: rootMatches.map((match) => match.collectionAlias),
+      reason: null,
+      repositoryRootDiscovered: canonicalRoot.repositoryRootDiscovered,
+      rootAlias: canonicalRoot.rootAlias,
+      source: root.source,
+      status: "matched",
+    });
+  }
+
+  matches.sort(compareMatches);
+  return { matches, roots };
+}

package/src/core/validation.ts

@@ -9,7 +9,7 @@ import { realpath } from "node:fs/promises";
 // node:os for homedir (no Bun os utils)
 import { homedir } from "node:os";
 // node:path for path utils (no Bun path utils)
-import { isAbsolute, join, posix as pathPosix } from "node:path";
+import { isAbsolute, join, posix as pathPosix, relative, sep } from "node:path";
 
 import { toAbsolutePath } from "../config/paths";
 
@@ -58,6 +58,25 @@ export function validateRelPath(relPath: string): string {
   return normalized;
 }
 
+/**
+ * Return whether candidate is equal to or nested beneath parent.
+ *
+ * Inputs must already be canonical absolute paths. `relative()` keeps this
+ * segment-safe, unlike string-prefix checks (`/project` vs `/project-old`).
+ */
+export function isCanonicalPathContained(
+  parent: string,
+  candidate: string
+): boolean {
+  const relativePath = relative(parent, candidate);
+  return (
+    relativePath === "" ||
+    (relativePath !== ".." &&
+      !relativePath.startsWith(`..${sep}`) &&
+      !isAbsolute(relativePath))
+  );
+}
+
 export async function validateCollectionRoot(
   inputPath: string
 ): Promise<string> {

package/src/mcp/tools/ask.ts

@@ -8,6 +8,7 @@ import type { ToolContext } from "../server";
 import type { ToolResult } from "./index";
 
 import { buildVerifiedAsk } from "../../app/verified-ask";
+import { resolveRemoteProjectAffinity } from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
   retrievalTraceFilters,
@@ -30,6 +31,7 @@ const queryModeSchema = z
 export const askInputSchema = z
   .object({
     query: z.string().trim().min(1),
+    projectHints: z.array(z.string()).max(16).optional(),
     verify: z.literal(true),
     collection: z.string().optional(),
     limit: z.number().int().min(1).max(100).default(5),
@@ -153,8 +155,14 @@ export const handleAsk = (
       );
       if (!normalized.ok) throw new Error(normalized.error.message);
       const query = normalized.value.query;
+      const { projectHints, ...askInput } = args;
+      const projectAffinity = await resolveRemoteProjectAffinity(
+        context.config,
+        projectHints
+      );
       const options = {
-        ...args,
+        ...askInput,
+        projectAffinity,
         queryModes:
           normalized.value.queryModes.length > 0
             ? normalized.value.queryModes
@@ -210,6 +218,7 @@ export const handleAsk = (
           embedPort: modelPorts.embedPort,
           rerankPort: modelPorts.rerankPort,
           genPort: modelPorts.genPort,
+          projectAffinity,
           traceSession,
         });
         const finished = await traceSession?.finish(

package/src/mcp/tools/context.ts

@@ -25,6 +25,11 @@ import {
   parseContextVerifySurfaceInput,
 } from "../../app/context-surface";
 import { createNonTtyProgressRenderer } from "../../cli/progress";
+import { ContextCapsuleContractError } from "../../core/context-capsule";
+import {
+  ProjectAffinityInputError,
+  resolveRemoteProjectAffinity,
+} from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
   startRetrievalTraceRequest,
@@ -224,6 +229,18 @@ export const handleContext = (
       null;
     let traceSession: RetrievalTraceSession | undefined;
     try {
+      let projectAffinity;
+      try {
+        projectAffinity = await resolveRemoteProjectAffinity(
+          context.config,
+          parsed.projectHints
+        );
+      } catch (error) {
+        if (error instanceof ProjectAffinityInputError) {
+          throw new ContextCapsuleContractError("invalid_input", error.message);
+        }
+        throw error;
+      }
       const traceStart = await startRetrievalTraceRequest({
         store: context.store,
         config: context.config,
@@ -261,6 +278,7 @@ export const handleContext = (
         vectorIndex: modelPorts?.vectorIndex ?? null,
         embedPort: modelPorts?.embedPort ?? null,
         rerankPort: modelPorts?.rerankPort ?? null,
+        projectAffinity,
         traceSession,
       });
       const finalized = await traceSession?.finish("completed");

package/src/mcp/tools/index.ts

@@ -131,13 +131,22 @@ export const MCP_WRITE_TOOL_NAMES = new Set([
 // Shared Input Schemas
 // ─────────────────────────────────────────────────────────────────────────────
 
-const searchInputSchema = z.object({
+const projectHintsInputSchema = z
+  .array(z.string())
+  .max(16)
+  .optional()
+  .describe(
+    "Opaque caller project hints for cross-surface parity; remote hints never inspect server paths"
+  );
+
+export const searchInputSchema = z.object({
   query: z
     .string()
     .min(1, "Query cannot be empty")
     .describe(
       "Exact keyword, identifier, filename, error text, or phrase to match with BM25"
     ),
+  projectHints: projectHintsInputSchema,
   collection: z
     .string()
     .optional()
@@ -378,13 +387,14 @@ const duplicateNoteInputSchema = z.object({
   name: z.string().optional(),
 });
 
-const vsearchInputSchema = z.object({
+export const vsearchInputSchema = z.object({
   query: z
     .string()
     .min(1, "Query cannot be empty")
     .describe(
       "Natural-language concept to match semantically; use gno_search for exact error text or identifiers"
     ),
+  projectHints: projectHintsInputSchema,
   collection: z
     .string()
     .optional()
@@ -455,6 +465,7 @@ export const queryInputSchema = z.object({
     .describe(
       "Primary user query; combine with intent or queryModes for ambiguous requests"
     ),
+  projectHints: projectHintsInputSchema,
   collection: z
     .string()
     .optional()

package/src/mcp/tools/query.ts

@@ -26,6 +26,7 @@ import {
   normalizeContentTypes,
 } from "../../config";
 import { resolveDepthPolicy } from "../../core/depth-policy";
+import { resolveRemoteProjectAffinity } from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
   retrievalTraceFilters,
@@ -49,6 +50,7 @@ import { normalizeTagFilters, runTool, type ToolResult } from "./index";
 
 interface QueryInput {
   query: string;
+  projectHints?: string[];
   collection?: string;
   limit?: number;
   minScore?: number;
@@ -227,6 +229,10 @@ export function handleQuery(
         hasStructuredModes,
       });
       const { noExpand, noRerank } = depthPolicy;
+      const projectAffinity = await resolveRemoteProjectAffinity(
+        ctx.config,
+        args.projectHints
+      );
       const expandUri =
         !noExpand && !hasStructuredModes
           ? resolveModelUri(ctx.config, "expand", undefined, args.collection)
@@ -253,6 +259,7 @@ export function handleQuery(
         queryModes,
         tagsAll: normalizeTagFilters(args.tagsAll),
         tagsAny: normalizeTagFilters(args.tagsAny),
+        projectAffinity,
       };
 
       try {
@@ -440,6 +447,10 @@ export function handleQueryDiagnose(
           hasStructuredModes,
         });
         const { noExpand, noRerank } = depthPolicy;
+        const projectAffinity = await resolveRemoteProjectAffinity(
+          ctx.config,
+          args.projectHints
+        );
 
         if (!args.fast) {
           const embedResult = await llm.createEmbeddingPort(embedUri, {
@@ -524,6 +535,7 @@ export function handleQueryDiagnose(
           queryModes,
           tagsAll: normalizeTagFilters(args.tagsAll),
           tagsAny: normalizeTagFilters(args.tagsAny),
+          projectAffinity,
           contentTypeRules,
           contentTypeRulesFingerprint:
             fingerprintContentTypeRules(contentTypeRules),

package/src/mcp/tools/search.ts

@@ -11,6 +11,7 @@ import type { SearchResult, SearchResults } from "../../pipeline/types";
 import type { ToolContext } from "../server";
 
 import { decorateUriForIndex, parseUri } from "../../app/constants";
+import { resolveRemoteProjectAffinity } from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
   retrievalTraceFilters,
@@ -22,6 +23,7 @@ import { normalizeTagFilters, runTool, type ToolResult } from "./index";
 
 interface SearchInput {
   query: string;
+  projectHints?: string[];
   collection?: string;
   limit?: number;
   minScore?: number;
@@ -113,6 +115,10 @@ export function handleSearch(
         }
       }
 
+      const projectAffinity = await resolveRemoteProjectAffinity(
+        ctx.config,
+        args.projectHints
+      );
       const options = {
         limit: args.limit ?? 5,
         minScore: args.minScore,
@@ -126,6 +132,7 @@ export function handleSearch(
         author: args.author,
         tagsAll: normalizeTagFilters(args.tagsAll),
         tagsAny: normalizeTagFilters(args.tagsAny),
+        projectAffinity,
       };
       let traceSession: RetrievalTraceSession | undefined;
       try {

package/src/mcp/tools/vsearch.ts

@@ -12,6 +12,7 @@ import type { ToolContext } from "../server";
 
 import { decorateUriForIndex, parseUri } from "../../app/constants";
 import { createNonTtyProgressRenderer } from "../../cli/progress";
+import { resolveRemoteProjectAffinity } from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
   retrievalTraceFilters,
@@ -34,6 +35,7 @@ import { normalizeTagFilters, runTool, type ToolResult } from "./index";
 
 interface VsearchInput {
   query: string;
+  projectHints?: string[];
   collection?: string;
   limit?: number;
   minScore?: number;
@@ -135,6 +137,10 @@ export function handleVsearch(
         undefined,
         args.collection
       );
+      const projectAffinity = await resolveRemoteProjectAffinity(
+        ctx.config,
+        args.projectHints
+      );
       const options = {
         limit: args.limit ?? 5,
         minScore: args.minScore,
@@ -147,6 +153,7 @@ export function handleVsearch(
         author: args.author,
         tagsAll: normalizeTagFilters(args.tagsAll),
         tagsAny: normalizeTagFilters(args.tagsAny),
+        projectAffinity,
       };
       let traceSession: RetrievalTraceSession | undefined;
       const traceStart = await startRetrievalTraceRequest({

package/src/pipeline/diagnose.ts

@@ -19,6 +19,12 @@ import { resolveDocRef } from "../core/ref-parser";
 import { err, ok } from "../store/types";
 import { evaluateQueryTargetFilters } from "./filters";
 import { searchHybrid } from "./hybrid";
+import {
+  getProjectAffinityMetadata,
+  type ProjectAffinityScoringInput,
+  type ProjectAffinityScoreMetadata,
+  scoreProjectAffinity,
+} from "./project-affinity";
 
 export type QueryDiagnoseTargetStatus =
   | "not_found"
@@ -46,7 +52,7 @@ export interface QueryDiagnoseStage {
 }
 
 export interface QueryDiagnoseResult {
-  schemaVersion: "1.0";
+  schemaVersion: "1.0" | "1.1";
   query: string;
   target: {
     ref: string;
@@ -65,6 +71,7 @@ export interface QueryDiagnoseResult {
     filterReasons: string[];
   };
   stages: QueryDiagnoseStage[];
+  affinity?: ProjectAffinityScoreMetadata;
   chunk: {
     seq: number | null;
     startLine: number | null;
@@ -155,6 +162,15 @@ function findTargetCandidate(
   );
 }
 
+const hasTrustedProjectAffinityInput = (
+  input: ProjectAffinityScoringInput | undefined
+): boolean =>
+  input?.enabled !== false &&
+  Boolean(
+    input?.resolution.matches.length ||
+    input?.resolution.roots.some((root) => root.source !== "remote_hint")
+  );
+
 export async function diagnoseQueryTarget(
   deps: HybridSearchDeps,
   query: string,
@@ -276,8 +292,28 @@ export async function diagnoseQueryTarget(
     chunks.find((chunk) => chunk.seq === firstMatched?.seq) ??
     chunks[0] ??
     null;
+  const targetResult = searchResult.value.results.find(
+    (result) => result.uri === doc.uri
+  );
+  const lastMatched = trace?.stages
+    .toReversed()
+    .flatMap((stage) => stage.candidates)
+    .find(
+      (candidate) =>
+        candidate.mirrorHash === doc.mirrorHash && targetSeqs.has(candidate.seq)
+    );
+  const affinity =
+    (targetResult ? getProjectAffinityMetadata(targetResult) : undefined) ??
+    (lastMatched && options.projectAffinity
+      ? scoreProjectAffinity(
+          lastMatched.score,
+          doc.collection,
+          options.projectAffinity,
+          { kind: "hybrid_blended", score: lastMatched.score }
+        )
+      : null);
 
-  return ok({
+  const baseResult: QueryDiagnoseResult = {
     ...buildBaseResult(query, options.target, "diagnosed", doc, {
       graphHints,
       chunkCount: chunks.length,
@@ -298,5 +334,14 @@ export async function diagnoseQueryTarget(
       totalResults: searchResult.value.meta.totalResults,
       queryModes: searchResult.value.meta.queryModes,
     },
-  });
+  };
+  return ok(
+    affinity && hasTrustedProjectAffinityInput(options.projectAffinity)
+      ? {
+          ...baseResult,
+          schemaVersion: "1.1",
+          affinity,
+        }
+      : baseResult
+  );
 }