@gmickel/gno 1.21.0 → 1.23.0

package/src/config/types.ts

@@ -115,6 +115,74 @@ export const CollectionSchema = z.object({
 export type Collection = z.infer<typeof CollectionSchema>;
 export type CollectionModelOverrides = NonNullable<Collection["models"]>;
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Project Affinity Input
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const TrustedProjectRootSourceSchema = z.enum([
+  "cli_cwd",
+  "cli_explicit",
+  "cli_worktree",
+]);
+export type TrustedProjectRootSource = z.infer<
+  typeof TrustedProjectRootSourceSchema
+>;
+
+export const LocalProjectAffinityRootSchema = z.object({
+  source: TrustedProjectRootSourceSchema,
+  path: z.string().min(1),
+});
+export type LocalProjectAffinityRoot = z.infer<
+  typeof LocalProjectAffinityRootSchema
+>;
+
+export const RemoteProjectAffinityRootSchema = z.object({
+  source: z.literal("remote_hint"),
+  hint: z.string().min(1),
+});
+export type RemoteProjectAffinityRoot = z.infer<
+  typeof RemoteProjectAffinityRootSchema
+>;
+
+export const ProjectAffinityRootSchema = z.discriminatedUnion("source", [
+  LocalProjectAffinityRootSchema,
+  RemoteProjectAffinityRootSchema,
+]);
+export type ProjectAffinityRoot = z.infer<typeof ProjectAffinityRootSchema>;
+
+export const LocalProjectAffinityInputSchema = z.object({
+  roots: z.array(LocalProjectAffinityRootSchema).max(16).default([]),
+});
+export type LocalProjectAffinityInput = z.infer<
+  typeof LocalProjectAffinityInputSchema
+>;
+
+export const RemoteProjectAffinityInputSchema = z.object({
+  roots: z.array(RemoteProjectAffinityRootSchema).max(16).default([]),
+});
+export type RemoteProjectAffinityInput = z.infer<
+  typeof RemoteProjectAffinityInputSchema
+>;
+
+export const ProjectAffinityInputSchema = z.object({
+  roots: z.array(ProjectAffinityRootSchema).max(16).default([]),
+});
+export type ProjectAffinityInput = z.infer<typeof ProjectAffinityInputSchema>;
+
+export const PROJECT_AFFINITY_MAX_CONTRIBUTION = 0.03;
+export const AUXILIARY_RANKING_MAX_CONTRIBUTION = 0.08;
+
+export const ProjectAffinityConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  contribution: z
+    .number()
+    .finite()
+    .min(0)
+    .max(PROJECT_AFFINITY_MAX_CONTRIBUTION)
+    .default(PROJECT_AFFINITY_MAX_CONTRIBUTION),
+});
+export type ProjectAffinityConfig = z.infer<typeof ProjectAffinityConfigSchema>;
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Context Schema
 // ─────────────────────────────────────────────────────────────────────────────
@@ -342,6 +410,9 @@ export const ConfigSchema = z.object({
 
   /** Private local retrieval trace recording. Absent means recording off. */
   retrievalTraces: RetrievalTraceConfigSchema.optional(),
+
+  /** Bounded project-aware retrieval affinity. */
+  projectAffinity: ProjectAffinityConfigSchema.optional(),
 });
 
 export type Config = Omit<z.infer<typeof ConfigSchema>, "contentTypes"> & {

package/src/core/project-affinity-surface.ts

@@ -0,0 +1,114 @@
+/**
+ * Shared trust boundary for caller-supplied project affinity.
+ *
+ * Raw roots and hints stop here. Retrieval pipelines receive only the resolved,
+ * redaction-safe scoring input.
+ *
+ * @module src/core/project-affinity-surface
+ */
+
+import type { Config, ProjectAffinityInput } from "../config/types";
+import type { ProjectAffinityScoringInput } from "../pipeline/project-affinity";
+
+import { resolveProjectAffinity } from "./project-affinity";
+
+export const MAX_PROJECT_AFFINITY_INPUTS = 16;
+
+export interface CliProjectAffinityRequest {
+  projectAffinityDisabled?: boolean;
+  projectRoots?: string[];
+}
+
+export class ProjectAffinityInputError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ProjectAffinityInputError";
+  }
+}
+
+const compareCodeUnits = (left: string, right: string): number =>
+  left < right ? -1 : left > right ? 1 : 0;
+
+export const normalizeProjectAffinityValues = (
+  values: readonly string[] | undefined,
+  label: "project hints" | "project roots"
+): string[] => {
+  if (values === undefined) return [];
+  if (
+    !Array.isArray(values) ||
+    values.length > MAX_PROJECT_AFFINITY_INPUTS ||
+    values.some((value) => typeof value !== "string")
+  ) {
+    throw new ProjectAffinityInputError(
+      `${label} must contain at most ${MAX_PROJECT_AFFINITY_INPUTS} strings`
+    );
+  }
+  const normalized = [
+    ...new Set(values.map((value) => value.normalize("NFC").trim())),
+  ].sort(compareCodeUnits);
+  if (normalized.some((value) => value.length === 0)) {
+    throw new ProjectAffinityInputError(
+      `${label} must not contain empty values`
+    );
+  }
+  return normalized;
+};
+
+const scoringInput = async (
+  input: ProjectAffinityInput,
+  config: Config,
+  channel: "local" | "remote"
+): Promise<ProjectAffinityScoringInput> => ({
+  enabled: config.projectAffinity?.enabled,
+  contribution: config.projectAffinity?.contribution,
+  resolution: await resolveProjectAffinity(input, config.collections, {
+    channel,
+  }),
+});
+
+export const resolveCliProjectAffinity = async (
+  config: Config,
+  options: {
+    cwd: string;
+    disabled?: boolean;
+    projectRoots?: readonly string[];
+  }
+): Promise<ProjectAffinityScoringInput | undefined> => {
+  const projectRoots = normalizeProjectAffinityValues(
+    options.projectRoots,
+    "project roots"
+  );
+  if (options.disabled && projectRoots.length > 0) {
+    throw new ProjectAffinityInputError(
+      "--no-project-affinity cannot be combined with --project-root"
+    );
+  }
+  if (options.disabled || config.projectAffinity?.enabled === false) return;
+
+  const roots =
+    projectRoots.length > 0
+      ? projectRoots.map((path) => ({
+          path,
+          source: "cli_explicit" as const,
+        }))
+      : [{ path: options.cwd, source: "cli_cwd" as const }];
+  return scoringInput({ roots }, config, "local");
+};
+
+export const resolveRemoteProjectAffinity = async (
+  config: Config,
+  projectHints: readonly string[] | undefined
+): Promise<ProjectAffinityScoringInput | undefined> => {
+  const hints = normalizeProjectAffinityValues(projectHints, "project hints");
+  if (hints.length === 0 || config.projectAffinity?.enabled === false) return;
+  return scoringInput(
+    {
+      roots: hints.map((hint) => ({
+        hint,
+        source: "remote_hint" as const,
+      })),
+    },
+    config,
+    "remote"
+  );
+};

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()