@gmickel/gno 1.26.0 → 1.27.0

package/src/mcp/tools/status.ts

@@ -7,6 +7,7 @@
 import type { IndexStatus } from "../../store/types";
 import type { ToolContext } from "../server";
 
+import { buildContentTypeBoostStatus } from "../../config/content-types";
 import { resolveModelUri } from "../../llm/registry";
 import { createStandaloneResidentStatus } from "../../serve/resident-status";
 import { runTool, type ToolResult } from "./index";
@@ -87,6 +88,9 @@ export function handleStatus(
       return {
         ...result.value,
         configPath: ctx.actualConfigPath,
+        contentTypeBoost: buildContentTypeBoostStatus(
+          ctx.config.contentTypes ?? []
+        ),
         resident:
           ctx.getResidentStatus?.() ?? createStandaloneResidentStatus("stdio"),
       };

package/src/pipeline/content-type-boost.ts

@@ -0,0 +1,264 @@
+/**
+ * Bounded content-type scoring composed with trusted project affinity.
+ *
+ * @module src/pipeline/content-type-boost
+ */
+
+import type { NormalizedContentTypeRule } from "../config/content-types";
+import type { ProjectAffinityScoringInput } from "./project-affinity";
+import type { SearchResult } from "./types";
+
+import {
+  fingerprintContentTypeRules,
+  resolveContentTypeRule,
+} from "../config/content-types";
+import {
+  CONTENT_TYPE_SEARCH_BOOST_MAX,
+  CONTENT_TYPE_SEARCH_BOOST_MIN,
+  CONTENT_TYPE_SEARCH_BOOST_NEUTRAL,
+} from "../config/types";
+import {
+  applyAuxiliaryScore,
+  hasProjectAffinity,
+  SEARCH_RESULT_AFFINITY_METADATA,
+  scoreProjectAffinity,
+  type ProjectAffinityScoreMetadata,
+} from "./project-affinity";
+
+export const CONTENT_TYPE_MAX_CONTRIBUTION = 0.05;
+
+export interface ContentTypeBoostScoreMetadata {
+  baseScore: number;
+  cappedContribution: number;
+  combinedAuxiliaryApplied: number;
+  combinedAuxiliaryCap: number;
+  combinedAuxiliaryRequested: number;
+  configuredFactor: number;
+  contentType: string;
+  finalScore: number;
+  rawContribution: number;
+  rawScore: number;
+  rawScoreKind: ProjectAffinityScoreMetadata["rawScoreKind"];
+  ruleSource: "configured-id" | "prefix";
+  rulesFingerprint: string;
+}
+
+export interface AuxiliaryScoreResult {
+  contentTypeBoost?: ContentTypeBoostScoreMetadata;
+  projectAffinity: ProjectAffinityScoreMetadata;
+}
+
+export const SEARCH_RESULT_CONTENT_TYPE_BOOST_METADATA = Symbol(
+  "gno.searchResultContentTypeBoostMetadata"
+);
+
+const clamp = (value: number, min: number, max: number): number =>
+  Math.min(max, Math.max(min, value));
+
+const rankingFingerprints = new WeakMap<
+  readonly NormalizedContentTypeRule[],
+  string
+>();
+
+const rankingFingerprint = (
+  rules: readonly NormalizedContentTypeRule[] | undefined
+): string => {
+  if (!rules) return fingerprintContentTypeRules([]);
+  const cached = rankingFingerprints.get(rules);
+  if (cached) return cached;
+  const fingerprint = fingerprintContentTypeRules([...rules]);
+  rankingFingerprints.set(rules, fingerprint);
+  return fingerprint;
+};
+
+/** Map the supported factor range continuously onto the contribution range. */
+export function contentTypeBoostContribution(factor: number): {
+  raw: number;
+  capped: number;
+} {
+  const raw =
+    factor >= CONTENT_TYPE_SEARCH_BOOST_NEUTRAL
+      ? ((factor - CONTENT_TYPE_SEARCH_BOOST_NEUTRAL) /
+          (CONTENT_TYPE_SEARCH_BOOST_MAX - CONTENT_TYPE_SEARCH_BOOST_NEUTRAL)) *
+        CONTENT_TYPE_MAX_CONTRIBUTION
+      : ((factor - CONTENT_TYPE_SEARCH_BOOST_NEUTRAL) /
+          (CONTENT_TYPE_SEARCH_BOOST_NEUTRAL - CONTENT_TYPE_SEARCH_BOOST_MIN)) *
+        CONTENT_TYPE_MAX_CONTRIBUTION;
+  return {
+    raw,
+    capped: clamp(
+      raw,
+      -CONTENT_TYPE_MAX_CONTRIBUTION,
+      CONTENT_TYPE_MAX_CONTRIBUTION
+    ),
+  };
+}
+
+export function hasContentTypeBoost(
+  rules: readonly NormalizedContentTypeRule[] | undefined
+): boolean {
+  return Boolean(
+    rules?.some(
+      (rule) => rule.searchBoost !== CONTENT_TYPE_SEARCH_BOOST_NEUTRAL
+    )
+  );
+}
+
+export function hasAuxiliaryRanking(
+  projectAffinity: ProjectAffinityScoringInput | undefined,
+  rules: readonly NormalizedContentTypeRule[] | undefined
+): boolean {
+  return hasProjectAffinity(projectAffinity) || hasContentTypeBoost(rules);
+}
+
+export function scoreContentTypeBoost(
+  baseScore: number,
+  contentType: string | undefined,
+  contentTypeSource: string | null | undefined,
+  relativePath: string,
+  collection: string,
+  rules: readonly NormalizedContentTypeRule[] | undefined,
+  projectAffinity: ProjectAffinityScoringInput | undefined,
+  raw: {
+    kind: ProjectAffinityScoreMetadata["rawScoreKind"];
+    score: number;
+  } = { kind: "normalized", score: baseScore }
+): AuxiliaryScoreResult {
+  const configuredId =
+    contentTypeSource === "frontmatter-type" ||
+    contentTypeSource === "frontmatter"
+      ? contentType
+      : undefined;
+  const resolution = resolveContentTypeRule(
+    configuredId,
+    relativePath,
+    rules ? [...rules] : []
+  );
+  const factor =
+    resolution?.rule.searchBoost ?? CONTENT_TYPE_SEARCH_BOOST_NEUTRAL;
+  const contribution = contentTypeBoostContribution(factor);
+  const projectScore = scoreProjectAffinity(
+    baseScore,
+    collection,
+    projectAffinity,
+    raw
+  );
+  const combined = applyAuxiliaryScore(baseScore, [
+    projectScore.affinityRequested,
+    contribution.capped,
+  ]);
+  const compositeProjectScore: ProjectAffinityScoreMetadata = {
+    ...projectScore,
+    combinedAuxiliaryApplied: combined.applied,
+    combinedAuxiliaryRequested: combined.requested,
+    finalBlendedScore: combined.finalScore,
+    finalScore: combined.finalScore,
+  };
+
+  if (!resolution || factor === CONTENT_TYPE_SEARCH_BOOST_NEUTRAL) {
+    return { projectAffinity: compositeProjectScore };
+  }
+
+  return {
+    projectAffinity: compositeProjectScore,
+    contentTypeBoost: {
+      baseScore,
+      cappedContribution: contribution.capped,
+      combinedAuxiliaryApplied: compositeProjectScore.combinedAuxiliaryApplied,
+      combinedAuxiliaryCap: compositeProjectScore.combinedAuxiliaryCap,
+      combinedAuxiliaryRequested:
+        compositeProjectScore.combinedAuxiliaryRequested,
+      configuredFactor: factor,
+      contentType: resolution.rule.id,
+      finalScore: compositeProjectScore.finalScore,
+      rawContribution: contribution.raw,
+      rawScore: raw.score,
+      rawScoreKind: raw.kind,
+      ruleSource: resolution.source,
+      rulesFingerprint: rankingFingerprint(rules),
+    },
+  };
+}
+
+export function attachAuxiliaryScoreMetadata(
+  result: SearchResult,
+  scored: AuxiliaryScoreResult,
+  finalScore: number,
+  includeProjectAffinity = false
+): SearchResult {
+  const projectAffinity = {
+    ...scored.projectAffinity,
+    finalBlendedScore: finalScore,
+    finalScore,
+  };
+  result.score = finalScore;
+  if (includeProjectAffinity) {
+    Object.defineProperty(result, SEARCH_RESULT_AFFINITY_METADATA, {
+      configurable: true,
+      enumerable: false,
+      value: projectAffinity,
+      writable: true,
+    });
+  }
+  if (scored.contentTypeBoost) {
+    Object.defineProperty(result, SEARCH_RESULT_CONTENT_TYPE_BOOST_METADATA, {
+      configurable: true,
+      enumerable: false,
+      value: { ...scored.contentTypeBoost, finalScore },
+      writable: true,
+    });
+  }
+  return result;
+}
+
+export function applyContentTypeBoost(
+  result: SearchResult,
+  collection: string,
+  rules: readonly NormalizedContentTypeRule[] | undefined,
+  projectAffinity: ProjectAffinityScoringInput | undefined,
+  contentTypeSource?: string | null,
+  raw?: {
+    kind: ProjectAffinityScoreMetadata["rawScoreKind"];
+    score: number;
+  }
+): SearchResult {
+  const scored = scoreContentTypeBoost(
+    result.score,
+    result.contentType,
+    contentTypeSource,
+    result.source.relPath,
+    collection,
+    rules,
+    projectAffinity,
+    raw
+  );
+  const affinityActive = hasProjectAffinity(projectAffinity);
+  if (!(scored.contentTypeBoost || affinityActive)) return result;
+  return attachAuxiliaryScoreMetadata(
+    result,
+    scored,
+    scored.projectAffinity.finalScore,
+    affinityActive
+  );
+}
+
+export function getContentTypeBoostMetadata(
+  result: SearchResult
+): ContentTypeBoostScoreMetadata | undefined {
+  return (
+    result as SearchResult & {
+      [SEARCH_RESULT_CONTENT_TYPE_BOOST_METADATA]?: ContentTypeBoostScoreMetadata;
+    }
+  )[SEARCH_RESULT_CONTENT_TYPE_BOOST_METADATA];
+}
+
+export function sortByFinalScoreStable(results: SearchResult[]): void {
+  const originalRank = new Map(
+    results.map((result, index) => [result, index] as const)
+  );
+  results.sort(
+    (left, right) =>
+      right.score - left.score ||
+      (originalRank.get(left) ?? 0) - (originalRank.get(right) ?? 0)
+  );
+}

package/src/pipeline/diagnose.ts

@@ -14,16 +14,23 @@ import type {
   QueryDiagnoseTraceCandidate,
 } from "./types";
 
-import { fingerprintContentTypeRules } from "../config";
+import {
+  fingerprintContentTypeMetadataRules,
+  normalizeContentTypes,
+} from "../config";
 import { resolveDocRef } from "../core/ref-parser";
 import { err, ok } from "../store/types";
+import {
+  getContentTypeBoostMetadata,
+  scoreContentTypeBoost,
+  type ContentTypeBoostScoreMetadata,
+} from "./content-type-boost";
 import { evaluateQueryTargetFilters } from "./filters";
 import { searchHybrid } from "./hybrid";
 import {
   getProjectAffinityMetadata,
   type ProjectAffinityScoringInput,
   type ProjectAffinityScoreMetadata,
-  scoreProjectAffinity,
 } from "./project-affinity";
 
 export type QueryDiagnoseTargetStatus =
@@ -52,7 +59,7 @@ export interface QueryDiagnoseStage {
 }
 
 export interface QueryDiagnoseResult {
-  schemaVersion: "1.0" | "1.1";
+  schemaVersion: "1.0" | "1.1" | "1.2";
   query: string;
   target: {
     ref: string;
@@ -72,6 +79,7 @@ export interface QueryDiagnoseResult {
   };
   stages: QueryDiagnoseStage[];
   affinity?: ProjectAffinityScoreMetadata;
+  contentTypeBoost?: ContentTypeBoostScoreMetadata;
   chunk: {
     seq: number | null;
     startLine: number | null;
@@ -182,9 +190,12 @@ export async function diagnoseQueryTarget(
   }
 
   const doc = resolved.doc;
-  const rules = options.contentTypeRules ?? [];
+  const rules =
+    options.contentTypeRules ??
+    normalizeContentTypes(deps.config.contentTypes ?? []).rules;
   const expectedFingerprint =
-    options.contentTypeRulesFingerprint ?? fingerprintContentTypeRules(rules);
+    options.contentTypeRulesFingerprint ??
+    fingerprintContentTypeMetadataRules(rules);
   const fingerprintMatches = doc.contentTypeRulesFingerprint
     ? doc.contentTypeRulesFingerprint === expectedFingerprint
     : null;
@@ -302,16 +313,24 @@ export async function diagnoseQueryTarget(
       (candidate) =>
         candidate.mirrorHash === doc.mirrorHash && targetSeqs.has(candidate.seq)
     );
+  const fallbackScore = lastMatched
+    ? scoreContentTypeBoost(
+        lastMatched.score,
+        doc.contentType ?? undefined,
+        doc.contentTypeSource,
+        doc.relPath,
+        doc.collection,
+        rules,
+        options.projectAffinity,
+        { kind: "hybrid_blended", score: lastMatched.score }
+      )
+    : undefined;
   const affinity =
     (targetResult ? getProjectAffinityMetadata(targetResult) : undefined) ??
-    (lastMatched && options.projectAffinity
-      ? scoreProjectAffinity(
-          lastMatched.score,
-          doc.collection,
-          options.projectAffinity,
-          { kind: "hybrid_blended", score: lastMatched.score }
-        )
-      : null);
+    (options.projectAffinity ? fallbackScore?.projectAffinity : undefined);
+  const contentTypeBoost =
+    (targetResult ? getContentTypeBoostMetadata(targetResult) : undefined) ??
+    fallbackScore?.contentTypeBoost;
 
   const baseResult: QueryDiagnoseResult = {
     ...buildBaseResult(query, options.target, "diagnosed", doc, {
@@ -335,13 +354,21 @@ export async function diagnoseQueryTarget(
       queryModes: searchResult.value.meta.queryModes,
     },
   };
-  return ok(
+  const trustedAffinity =
     affinity && hasTrustedProjectAffinityInput(options.projectAffinity)
-      ? {
-          ...baseResult,
-          schemaVersion: "1.1",
-          affinity,
-        }
+      ? affinity
+      : undefined;
+  if (contentTypeBoost) {
+    return ok({
+      ...baseResult,
+      schemaVersion: "1.2",
+      ...(trustedAffinity ? { affinity: trustedAffinity } : {}),
+      contentTypeBoost,
+    });
+  }
+  return ok(
+    trustedAffinity
+      ? { ...baseResult, schemaVersion: "1.1", affinity: trustedAffinity }
       : baseResult
   );
 }

package/src/pipeline/explain.ts

@@ -14,6 +14,8 @@ import type {
   SearchResult,
 } from "./types";
 
+import { getContentTypeBoostMetadata } from "./content-type-boost";
+import { getProjectAffinityMetadata } from "./project-affinity";
 import { SEARCH_RESULT_PLANNER_METADATA } from "./types";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -39,7 +41,8 @@ export function formatResultExplain(results: ExplainResult[]): string {
       r.bm25Score !== undefined ||
       r.vecScore !== undefined ||
       r.rerankScore !== undefined ||
-      r.projectAffinity !== undefined
+      r.projectAffinity !== undefined ||
+      r.contentTypeBoost !== undefined
     ) {
       msg += " (";
       if (r.fusionScore !== undefined) {
@@ -69,6 +72,12 @@ export function formatResultExplain(results: ExplainResult[]): string {
         }
         msg += `raw=${r.projectAffinity.rawScoreKind}:${r.projectAffinity.rawScore.toFixed(3)}, base=${r.projectAffinity.baseScore.toFixed(3)}, affinity=${r.projectAffinity.affinityApplied.toFixed(3)}/${r.projectAffinity.affinityRequested.toFixed(3)}, auxiliary=${r.projectAffinity.combinedAuxiliaryApplied.toFixed(3)}/${r.projectAffinity.combinedAuxiliaryCap.toFixed(3)}, collection=${r.projectAffinity.collectionAlias}, root=${r.projectAffinity.rootAlias}, source=${r.projectAffinity.source}, final=${r.projectAffinity.finalScore.toFixed(3)}`;
       }
+      if (r.contentTypeBoost) {
+        if (msg.at(-1) !== "(") {
+          msg += ", ";
+        }
+        msg += `contentType=${r.contentTypeBoost.contentType}, factor=${r.contentTypeBoost.configuredFactor.toFixed(3)}, rawBoost=${r.contentTypeBoost.rawContribution.toFixed(3)}, cappedBoost=${r.contentTypeBoost.cappedContribution.toFixed(3)}, auxiliary=${r.contentTypeBoost.combinedAuxiliaryApplied.toFixed(3)}/${r.contentTypeBoost.combinedAuxiliaryCap.toFixed(3)}, source=${r.contentTypeBoost.ruleSource}, final=${r.contentTypeBoost.finalScore.toFixed(3)}`;
+      }
       msg += ")";
     }
     lines.push(`[explain] result ${r.rank}: ${r.docid} ${msg}`);
@@ -227,7 +236,11 @@ export function buildExplainResults(
           entry.mirrorHash === result.conversion?.mirrorHash &&
           entry.seq === (planner?.retrievalSeq ?? planner?.seq)
       );
-      return buildExplainResult(result.docid, result.score, index, candidate);
+      return {
+        ...buildExplainResult(result.docid, result.score, index, candidate),
+        projectAffinity: getProjectAffinityMetadata(result),
+        contentTypeBoost: getContentTypeBoostMetadata(result),
+      };
     });
   }
   return candidates.slice(0, 20).map((candidate, index) => {