@gmickel/gno 1.22.0 → 1.23.0

package/src/cli/program.ts

@@ -32,7 +32,9 @@ import { CliError } from "./errors";
 import {
   assertFormatSupported,
   CMD,
+  collectRepeatableValue,
   getDefaultLimit,
+  parseCliProjectAffinityOptions,
   parseOptionalFloat,
   parsePositiveInt,
 } from "./options";
@@ -594,6 +596,13 @@ function wireSearchCommands(program: Command): void {
     )
     .option("--tags-all <tags>", "require ALL tags (comma-separated)")
     .option("--tags-any <tags>", "require ANY tag (comma-separated)")
+    .option(
+      "--project-root <path>",
+      "trusted project root (repeatable; replaces cwd affinity)",
+      collectRepeatableValue,
+      []
+    )
+    .option("--no-project-affinity", "disable project-aware ranking")
     .option("--full", "include full content")
     .option("--line-numbers", "include line numbers in output")
     .option("--json", "JSON output")
@@ -641,6 +650,7 @@ function wireSearchCommands(program: Command): void {
           : getDefaultLimit(format);
       const categories = parseCsvValues(cmdOpts.category);
       const exclude = parseCsvValues(cmdOpts.exclude);
+      const projectAffinity = parseCliProjectAffinityOptions(cmdOpts);
 
       const { search, formatSearch } = await import("./commands/search");
       const result = await search(queryText, {
@@ -658,6 +668,7 @@ function wireSearchCommands(program: Command): void {
         exclude,
         tagsAll,
         tagsAny,
+        ...projectAffinity,
         full: Boolean(cmdOpts.full),
         lineNumbers: Boolean(cmdOpts.lineNumbers),
         json: format === "json",
@@ -714,6 +725,13 @@ function wireSearchCommands(program: Command): void {
     )
     .option("--tags-all <tags>", "require ALL tags (comma-separated)")
     .option("--tags-any <tags>", "require ANY tag (comma-separated)")
+    .option(
+      "--project-root <path>",
+      "trusted project root (repeatable; replaces cwd affinity)",
+      collectRepeatableValue,
+      []
+    )
+    .option("--no-project-affinity", "disable project-aware ranking")
     .option("--full", "include full content")
     .option("--line-numbers", "include line numbers in output")
     .option("--json", "JSON output")
@@ -759,6 +777,7 @@ function wireSearchCommands(program: Command): void {
         : getDefaultLimit(format);
       const categories = parseCsvValues(cmdOpts.category);
       const exclude = parseCsvValues(cmdOpts.exclude);
+      const projectAffinity = parseCliProjectAffinityOptions(cmdOpts);
 
       const { vsearch, formatVsearch } = await import("./commands/vsearch");
       const result = await vsearch(queryText, {
@@ -776,6 +795,7 @@ function wireSearchCommands(program: Command): void {
         exclude,
         tagsAll,
         tagsAny,
+        ...projectAffinity,
         full: Boolean(cmdOpts.full),
         lineNumbers: Boolean(cmdOpts.lineNumbers),
         json: format === "json",
@@ -827,6 +847,13 @@ function wireSearchCommands(program: Command): void {
     )
     .option("--tags-all <tags>", "require ALL tags (comma-separated)")
     .option("--tags-any <tags>", "require ANY tag (comma-separated)")
+    .option(
+      "--project-root <path>",
+      "trusted project root (repeatable; replaces cwd affinity)",
+      collectRepeatableValue,
+      []
+    )
+    .option("--no-project-affinity", "disable project-aware ranking")
     .option("--full", "include full content")
     .option("--line-numbers", "include line numbers in output")
     .option("--fast", "skip expansion and reranking (fastest, ~0.7s)")
@@ -931,6 +958,7 @@ function wireSearchCommands(program: Command): void {
         : undefined;
       const categories = parseCsvValues(cmdOpts.category);
       const exclude = parseCsvValues(cmdOpts.exclude);
+      const projectAffinity = parseCliProjectAffinityOptions(cmdOpts);
 
       const depthPolicy = resolveDepthPolicy({
         presetId: activePresetId,
@@ -960,6 +988,7 @@ function wireSearchCommands(program: Command): void {
           exclude,
           tagsAll,
           tagsAny,
+          ...projectAffinity,
           noExpand: depthPolicy.noExpand,
           noRerank: depthPolicy.noRerank,
           graph: Boolean(cmdOpts.graph),
@@ -995,6 +1024,7 @@ function wireSearchCommands(program: Command): void {
         exclude,
         tagsAll,
         tagsAny,
+        ...projectAffinity,
         full: Boolean(cmdOpts.full),
         lineNumbers: Boolean(cmdOpts.lineNumbers),
         noExpand: depthPolicy.noExpand,
@@ -1121,6 +1151,13 @@ function wireSearchCommands(program: Command): void {
     .option("--context-budget-bytes <num>", "verified Context byte budget")
     .option("--min-score <score>", "minimum retrieval score (0-1)")
     .option("--graph", "include bounded graph expansion")
+    .option(
+      "--project-root <path>",
+      "trusted project root (repeatable; replaces cwd affinity)",
+      collectRepeatableValue,
+      []
+    )
+    .option("--no-project-affinity", "disable project-aware ranking")
     .option("--show-sources", "show all retrieved sources (not just cited)")
     .option("--json", "JSON output")
     .option("--md", "Markdown output")
@@ -1169,6 +1206,7 @@ function wireSearchCommands(program: Command): void {
       }
       const categories = parseCsvValues(cmdOpts.category);
       const exclude = parseCsvValues(cmdOpts.exclude);
+      const projectAffinity = parseCliProjectAffinityOptions(cmdOpts);
 
       let queryModes: import("../pipeline/types").QueryModeInput[] | undefined;
       if (Array.isArray(cmdOpts.queryMode) && cmdOpts.queryMode.length > 0) {
@@ -1229,6 +1267,7 @@ function wireSearchCommands(program: Command): void {
         maxAnswerTokens,
         contextBudgetTokens,
         contextBudgetBytes,
+        ...projectAffinity,
         showSources,
         json: format === "json",
         md: format === "md",
@@ -1974,6 +2013,13 @@ function wireManagementCommands(program: Command): void {
     .option("--since <date>", "modified-at lower bound")
     .option("--until <date>", "modified-at upper bound")
     .option("--graph", "enable graph neighbor expansion")
+    .option(
+      "--project-root <path>",
+      "trusted project root (repeatable; replaces cwd affinity)",
+      collectRepeatableValue,
+      []
+    )
+    .option("--no-project-affinity", "disable project-aware ranking")
     .option("--fast", "use lexical-first fast retrieval")
     .option("--thorough", "use a wider retrieval pool")
     .option("-n, --limit <num>", "maximum retrieved results")
@@ -1991,6 +2037,7 @@ function wireManagementCommands(program: Command): void {
         throw new CliError("VALIDATION", "Choose either --fast or --thorough");
       }
       const globals = getGlobals();
+      const projectAffinity = parseCliProjectAffinityOptions(cmdOpts);
       const { contextBuild } = await import("./commands/context-build");
       let queryModes: import("../pipeline/types").QueryModeInput[] | undefined;
       if (Array.isArray(cmdOpts.queryMode) && cmdOpts.queryMode.length > 0) {
@@ -2022,6 +2069,7 @@ function wireManagementCommands(program: Command): void {
           true
         ),
         query: cmdOpts.query as string | undefined,
+        ...projectAffinity,
         queryModes,
         collections: cmdOpts.collection as string[],
         uriPrefix: cmdOpts.uriPrefix as string | undefined,

package/src/config/defaults.ts

@@ -4,7 +4,12 @@
  * @module src/config/defaults
  */
 
-import { CONFIG_VERSION, type Config, DEFAULT_FTS_TOKENIZER } from "./types";
+import {
+  CONFIG_VERSION,
+  type Config,
+  DEFAULT_FTS_TOKENIZER,
+  PROJECT_AFFINITY_MAX_CONTRIBUTION,
+} from "./types";
 
 /**
  * Create a default config object.
@@ -17,5 +22,9 @@ export function createDefaultConfig(): Config {
     collections: [],
     contexts: [],
     contentTypes: [],
+    projectAffinity: {
+      enabled: true,
+      contribution: PROJECT_AFFINITY_MAX_CONTRIBUTION,
+    },
   };
 }

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"
+  );
+};