@gmickel/gno 1.25.1 → 1.27.0

package/src/ingestion/walker.ts

@@ -20,6 +20,7 @@ import {
 import type { SkippedEntry, WalkConfig, WalkEntry, WalkerPort } from "./types";
 
 import { SUPPORTED_EXTENSIONS } from "../converters/mime";
+import { matchesCollectionExclusion } from "../core/path-rules";
 
 /**
  * Regex to detect dangerous patterns with parent directory traversal.
@@ -51,6 +52,70 @@ function validatePattern(pattern: string): string | null {
   return null;
 }
 
+/**
+ * Split GNO's canonical whole-pattern union into independently scannable Bun
+ * globs. Bun.Glob.match() accepts a leading `{a,b}` union, but scan() does not.
+ * Nested braces remain part of each child glob; escaped outer commas become
+ * literal commas again before scanning.
+ */
+function scanPatterns(pattern: string): string[] {
+  if (!(pattern.startsWith("{") && pattern.endsWith("}"))) return [pattern];
+
+  const patterns: string[] = [];
+  let branch = "";
+  let depth = 0;
+  let bracketDepth = 0;
+  for (let index = 0; index < pattern.length; index += 1) {
+    const character = pattern[index];
+    if (
+      character === "\\" &&
+      pattern[index + 1] === "," &&
+      depth === 1 &&
+      bracketDepth === 0
+    ) {
+      branch += ",";
+      index += 1;
+      continue;
+    }
+    if (character === "[" && bracketDepth === 0) {
+      bracketDepth = 1;
+      branch += character;
+      continue;
+    }
+    if (character === "]" && bracketDepth > 0) {
+      bracketDepth = 0;
+      branch += character;
+      continue;
+    }
+    if (bracketDepth > 0) {
+      branch += character;
+      continue;
+    }
+    if (character === "{") {
+      depth += 1;
+      if (depth > 1) branch += character;
+      continue;
+    }
+    if (character === "}") {
+      depth -= 1;
+      if (depth < 0 || (depth === 0 && index !== pattern.length - 1)) {
+        return [pattern];
+      }
+      if (depth > 0) branch += character;
+      continue;
+    }
+    if (character === "," && depth === 1) {
+      patterns.push(branch);
+      branch = "";
+      continue;
+    }
+    branch += character;
+  }
+  if (depth !== 0 || bracketDepth !== 0) return [pattern];
+  patterns.push(branch);
+  return patterns;
+}
+
 /**
  * Compute safe relative path from root to file.
  * Returns null if file is outside root (security check).
@@ -77,36 +142,6 @@ async function safeRelPath(
   }
 }
 
-/**
- * Check if a path matches any exclude pattern.
- *
- * Exclude semantics (component-based matching):
- * - Patterns match against path components (directory/file names)
- * - "node_modules" matches any path containing "node_modules" as a component
- * - ".git" matches ".git" directory at any level
- * - Patterns are NOT globs - they match exact component names
- *
- * Examples:
- * - exclude: [".git"] matches "foo/.git/bar" but not "foo/.github/..."
- * - exclude: ["dist"] matches "dist/bundle.js" and "src/dist/output.js"
- */
-function matchesExclude(relPath: string, excludes: string[]): boolean {
-  const parts = relPath.split("/");
-
-  for (const pattern of excludes) {
-    // Check if any path component matches exactly
-    if (parts.includes(pattern)) {
-      return true;
-    }
-    // Check if path starts with pattern
-    if (relPath.startsWith(`${pattern}/`)) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
 /**
  * Check if a file extension matches the include list.
  * Include list contains extensions like ".md" or "md" (normalized).
@@ -145,10 +180,12 @@ export class FileWalker implements WalkerPort {
     const entries: WalkEntry[] = [];
     const skipped: SkippedEntry[] = [];
 
-    // Validate pattern for security
-    const patternError = validatePattern(config.pattern);
-    if (patternError) {
-      throw new Error(`Invalid glob pattern: ${patternError}`);
+    const patterns = scanPatterns(config.pattern);
+    for (const pattern of patterns) {
+      const patternError = validatePattern(pattern);
+      if (patternError) {
+        throw new Error(`Invalid glob pattern: ${patternError}`);
+      }
     }
 
     // Resolve root to real path for consistent comparison
@@ -161,16 +198,20 @@ export class FileWalker implements WalkerPort {
       return { entries: [], skipped: [] };
     }
 
-    const glob = new Bun.Glob(config.pattern);
-
-    for await (const match of glob.scan({
-      cwd: rootReal,
-      absolute: true,
-      onlyFiles: true,
-      followSymlinks: false,
-    })) {
-      const absPath = normalizePath(match);
+    const matches = new Set<string>();
+    for (const pattern of patterns) {
+      const glob = new Bun.Glob(pattern);
+      for await (const match of glob.scan({
+        cwd: rootReal,
+        absolute: true,
+        onlyFiles: true,
+        followSymlinks: false,
+      })) {
+        matches.add(normalizePath(match));
+      }
+    }
 
+    for (const absPath of [...matches].sort()) {
       // Security: Compute safe relative path (validates file is within root)
       const relPath = await safeRelPath(rootReal, absPath);
       if (relPath === null) {
@@ -179,7 +220,7 @@ export class FileWalker implements WalkerPort {
       }
 
       // Check exclude patterns
-      if (matchesExclude(relPath, config.exclude)) {
+      if (matchesCollectionExclusion(relPath, config.exclude)) {
         skipped.push({
           absPath,
           relPath,

package/src/llm/cache.ts

@@ -527,6 +527,27 @@ export class ModelCache {
     return cached !== null;
   }
 
+  /**
+   * Read-only availability probe for inspection commands.
+   *
+   * Unlike isCached(), this never repairs manifest entries or removes invalid
+   * files. It is safe for commands whose contract forbids local mutation.
+   */
+  async isCachedReadOnly(uri: string): Promise<boolean> {
+    const parsed = parseModelUri(uri);
+    if (!parsed.ok) return false;
+    if (parsed.value.scheme === "file") {
+      const validation = await validateGgufFile(parsed.value.file, uri, "user");
+      return validation.ok;
+    }
+
+    const manifest = await this.readManifestFromDisk();
+    const entry = manifest.models.find((model) => model.uri === uri);
+    if (!entry || !(await this.fileExists(entry.path))) return false;
+    const validation = await validateGgufFile(entry.path, uri, "cache");
+    return validation.ok;
+  }
+
   /**
    * Get cached/available path for a URI.
    * For file: URIs, returns path if file exists.

package/src/mcp/tools/ask.ts

@@ -50,6 +50,7 @@ export const askInputSchema = z
     graph: z.boolean().optional(),
     noGraph: z.boolean().optional(),
     noRerank: z.boolean().optional(),
+    explain: z.boolean().optional(),
     maxAnswerTokens: z.number().int().positive().optional(),
     contextBudgetTokens: z.number().int().positive().optional(),
     contextBudgetBytes: z.number().int().positive().optional(),

package/src/mcp/tools/index.ts

@@ -562,6 +562,10 @@ export const queryInputSchema = z.object({
     .boolean()
     .optional()
     .describe("Enable bounded one-hop graph neighbor expansion"),
+  explain: z
+    .boolean()
+    .optional()
+    .describe("Include deterministic stage and per-result scoring metadata"),
   tagsAll: z.array(z.string()).optional().describe("Require ALL of these tags"),
   tagsAny: z.array(z.string()).optional().describe("Require ANY of these tags"),
 });

package/src/mcp/tools/query.ts

@@ -22,7 +22,7 @@ import type { ToolContext } from "../server";
 import { decorateUriForIndex, parseUri } from "../../app/constants";
 import { createNonTtyProgressRenderer } from "../../cli/progress";
 import {
-  fingerprintContentTypeRules,
+  fingerprintContentTypeMetadataRules,
   normalizeContentTypes,
 } from "../../config";
 import { resolveDepthPolicy } from "../../core/depth-policy";
@@ -71,6 +71,7 @@ interface QueryInput {
   graph?: boolean;
   tagsAll?: string[];
   tagsAny?: string[];
+  explain?: boolean;
 }
 
 interface QueryDiagnoseInput extends QueryInput {
@@ -260,6 +261,7 @@ export function handleQuery(
         tagsAll: normalizeTagFilters(args.tagsAll),
         tagsAny: normalizeTagFilters(args.tagsAny),
         projectAffinity,
+        explain: args.explain,
       };
 
       try {
@@ -538,7 +540,7 @@ export function handleQueryDiagnose(
           projectAffinity,
           contentTypeRules,
           contentTypeRulesFingerprint:
-            fingerprintContentTypeRules(contentTypeRules),
+            fingerprintContentTypeMetadataRules(contentTypeRules),
         });
 
         if (!result.ok) {

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 { normalizeContentTypes } from "../../config";
 import { resolveRemoteProjectAffinity } from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
@@ -133,6 +134,8 @@ export function handleSearch(
         tagsAll: normalizeTagFilters(args.tagsAll),
         tagsAny: normalizeTagFilters(args.tagsAny),
         projectAffinity,
+        contentTypeRules: normalizeContentTypes(ctx.config.contentTypes ?? [])
+          .rules,
       };
       let traceSession: RetrievalTraceSession | undefined;
       try {

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