@untangle-code/search 0.0.0-stage → 0.1.0

package/src/format.ts

@@ -0,0 +1,228 @@
+/**
+ * Ausgabeformate (Nutzerwunsch A4: „Text, JSON, JSONL").
+ *
+ * Drei Formate, drei Zwecke:
+ *
+ * - `text` — fuer Menschen im Terminal. Eine Zeile Kopf je Treffer, darunter
+ *   die Score-Zerlegung in Klartext. Die Zerlegung ist hier KEIN Debug-Anhang,
+ *   sondern der eigentliche Mehrwert: sie beantwortet „warum steht das oben?".
+ * - `json` — ein Dokument, vollstaendig, mit Ledger und Warnungen. Fuer
+ *   Werkzeuge, die das Ganze wollen.
+ * - `jsonl` — eine Zeile je Treffer, streambar. Fuer Agents und Pipes.
+ *   Die erste Zeile ist ein Kopfsatz mit Anfrage-Fingerabdruck, Warnungen und
+ *   Ledger — sonst wuerde beim Streamen genau die Information verloren gehen,
+ *   die E4 sichtbar machen soll.
+ *
+ * Alle drei sind deterministisch: gleiche Ergebnismenge, gleiche Bytes.
+ */
+import type {
+  ScoreComponentV1,
+  SearchGraphRelationsV1,
+  SearchHitV1,
+  SearchResultSetV1,
+} from "@untangle-code/domain";
+
+import type { GrepResultSetV1, OutputFormat } from "./types.js";
+
+/** Formatiert eine Zahl mit fester Stellenzahl — stabil ueber Plattformen. */
+function fixed(value: number, digits = 4): string {
+  return value.toFixed(digits);
+}
+
+function formatComponent(component: ScoreComponentV1): string {
+  const sign = component.contribution < 0 ? "-" : "+";
+  const evidence = component.evidence === undefined ? "" : `  [${component.evidence}]`;
+  return `      ${sign} ${component.kind} = ${fixed(Math.abs(component.contribution))} (raw ${fixed(component.rawValue)} x weight ${fixed(component.weight)})${evidence}`;
+}
+
+/** Kompakte, aber vollstaendige Textdarstellung einer begrenzten Graphfacette. */
+export function formatSearchGraphRelationsAsText(
+  label: "context" | "linked",
+  value: SearchGraphRelationsV1,
+): string[] {
+  const lines = value.relations.map((relation) => {
+    const arrow = relation.direction === "incoming" ? "<-" : "->";
+    const symbol = relation.symbol === undefined ? "" : ` symbol=${relation.symbol.id}`;
+    return (
+      `      ${label} ${arrow} ${relation.repoId}@${relation.refId} ` +
+      `${relation.path} file=${relation.fileId}${symbol} ` +
+      `edge=${relation.edgeId} kind=${relation.edgeKind} crossRepository=${String(relation.crossRepository)}`
+    );
+  });
+  for (const omission of value.omissions) {
+    lines.push(
+      `      ${label} omitted ${omission.reason} x${String(omission.count)}: ${omission.detail}`,
+    );
+  }
+  return lines;
+}
+
+/** Eine Trefferzeile plus Score-Zerlegung im Textformat. */
+export function formatHitAsText(hit: SearchHitV1): string {
+  const lines: string[] = [];
+  const symbol =
+    hit.symbolName === undefined ? "" : ` ${hit.symbolKind ?? "symbol"} ${hit.symbolName}`;
+  lines.push(
+    `${String(hit.rank).padStart(3, " ")}. ${fixed(hit.score.final)}  ${hit.repoLabel}@${hit.refName} ${hit.filePath}:${hit.range.startLine}-${hit.range.endLine}${symbol}`,
+  );
+  if (hit.complexity?.cognitive !== undefined) {
+    lines.push(`      complexity: cognitive ${hit.complexity.cognitive}`);
+  }
+  if (hit.findability !== undefined) {
+    lines.push(
+      `      findability: ${fixed(hit.findability.score, 2)} (heuristic${hit.findability.primaryCause === undefined ? "" : `, ${hit.findability.primaryCause}`})`,
+    );
+  }
+  lines.push("      why:");
+  for (const component of hit.score.components) {
+    lines.push(formatComponent(component));
+  }
+  if (hit.score.clamped) {
+    lines.push(`      clamped: ${hit.score.clampReason ?? ""}`);
+  }
+  if (hit.relatedFragments.length > 0) {
+    lines.push(
+      `      related fragments: ${hit.relatedFragments.map((fragment) => `${fragment.chunkKind}@${fragment.startLine}`).join(", ")}`,
+    );
+  }
+  if (hit.graphContext !== undefined) {
+    lines.push(...formatSearchGraphRelationsAsText("context", hit.graphContext));
+  }
+  if (hit.linkedSymbols !== undefined) {
+    lines.push(...formatSearchGraphRelationsAsText("linked", hit.linkedSymbols));
+  }
+  if (hit.contentOmittedReason !== undefined) {
+    lines.push(`      content omitted: ${hit.contentOmittedReason}`);
+  }
+  if (hit.content !== undefined) {
+    for (const line of hit.content.split("\n")) {
+      lines.push(`      | ${line}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/** Formatiert eine ganze Ergebnismenge. */
+export function formatSearchResultSet(set: SearchResultSetV1, format: OutputFormat): string {
+  if (format === "json") {
+    return JSON.stringify(set, null, 2);
+  }
+  if (format === "jsonl") {
+    const header = {
+      kind: "header" as const,
+      queryFingerprint: set.queryFingerprint,
+      ...(set.indexFreshness === undefined ? {} : { indexFreshness: set.indexFreshness }),
+      query: set.query,
+      profileSeparation: set.profileSeparation,
+      totalHits: set.totalHits,
+      warnings: set.warnings,
+      skipped: set.skipped,
+    };
+    const lines = [JSON.stringify(header)];
+    for (const group of set.groups) {
+      for (const hit of group.hits) {
+        lines.push(
+          JSON.stringify({ kind: "hit", embeddingProfileId: group.embeddingProfileId, hit }),
+        );
+      }
+    }
+    return lines.join("\n");
+  }
+
+  const lines: string[] = [];
+  lines.push(`query: ${set.query.text}`);
+  lines.push(`fingerprint: ${set.queryFingerprint}`);
+  if (set.profileSeparation) {
+    lines.push(
+      `NOTE: ${set.groups.length} embedding profiles — scores are comparable only within a group (spec.md §13.4)`,
+    );
+  }
+  for (const group of set.groups) {
+    lines.push("");
+    lines.push(`profile ${group.embeddingProfileId} (repos: ${group.repoIds.join(", ")})`);
+    for (const caveat of group.caveats) {
+      lines.push(`  caveat: ${caveat}`);
+    }
+    // Das Verdikt kommt aus der Entscheidung, nie aus der Listenlaenge. Ein
+    // blosses „(no hits)" waere bei einer Ablehnung eine Tatsachenbehauptung
+    // ueber den Code: es GAB Kandidaten, die Policy hat sie verworfen.
+    const verdict = group.relevanceDecision;
+    if (verdict?.status === "rejected") {
+      lines.push(
+        `  (relevance policy ${verdict.calibrationId ?? "unknown"} judged the evidence ` +
+          `insufficient: ${verdict.basis}; abstention=${verdict.abstention})`,
+      );
+    }
+    if (group.hits.length === 0 && verdict?.status !== "rejected") {
+      lines.push("  (no hits)");
+    }
+    for (const hit of group.hits) {
+      lines.push(formatHitAsText(hit));
+    }
+  }
+  if (set.warnings.length > 0) {
+    lines.push("");
+    lines.push("warnings:");
+    for (const warning of set.warnings) {
+      lines.push(`  ${warning.code}: ${warning.message}`);
+    }
+  }
+  if (set.skipped.length > 0) {
+    lines.push("");
+    lines.push(`skipped (${set.skipped.length}) — nothing is dropped silently:`);
+    for (const entry of set.skipped) {
+      lines.push(
+        `  ${entry.reason} ${entry.subjectKind} ${entry.subjectId ?? entry.path ?? ""}: ${entry.detail}`,
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
+/** Formatiert grep-Treffer. */
+export function formatGrepResultSet(set: GrepResultSetV1, format: OutputFormat): string {
+  if (format === "json") {
+    return JSON.stringify(set, null, 2);
+  }
+  if (format === "jsonl") {
+    const header = {
+      kind: "header" as const,
+      pattern: set.pattern,
+      ...(set.indexFreshness === undefined ? {} : { indexFreshness: set.indexFreshness }),
+      isRegex: set.isRegex,
+      totalMatches: set.totalMatches,
+      truncated: set.truncated,
+      ...(set.truncationReason === undefined ? {} : { truncationReason: set.truncationReason }),
+      scannedChunks: set.scannedChunks,
+      warnings: set.warnings,
+      skipped: set.skipped,
+    };
+    return [header, ...set.matches.map((match) => ({ kind: "match" as const, match }))]
+      .map((entry) => JSON.stringify(entry))
+      .join("\n");
+  }
+
+  const lines: string[] = [];
+  for (const match of set.matches) {
+    for (const context of match.before) {
+      lines.push(`${match.filePath}-${context.line}- ${context.text}`);
+    }
+    lines.push(`${match.filePath}:${match.line}:${match.column}: ${match.lineText}`);
+    for (const context of match.after) {
+      lines.push(`${match.filePath}-${context.line}- ${context.text}`);
+    }
+    if (match.before.length > 0 || match.after.length > 0) {
+      lines.push("--");
+    }
+  }
+  lines.push(
+    `${set.totalMatches} match(es) in ${set.scannedChunks} scanned chunk(s)${set.truncated ? ` — TRUNCATED (${set.truncationReason ?? "unknown"})` : ""}`,
+  );
+  if (set.skipped.length > 0) {
+    lines.push(`skipped (${set.skipped.length}):`);
+    for (const entry of set.skipped) {
+      lines.push(`  ${entry.reason} ${entry.subjectId ?? entry.path ?? ""}: ${entry.detail}`);
+    }
+  }
+  return lines.join("\n");
+}

package/src/fusion.ts

@@ -0,0 +1,121 @@
+/**
+ * Fusion der drei Ranglisten (spec.md §13.2 Schritt 6, §13.4).
+ *
+ * Verfahren: gewichtete Reciprocal Rank Fusion.
+ *
+ *     rrf(d) = Σ_zweig  w_zweig / (k + rang_zweig(d))
+ *
+ * WARUM RRF UND NICHT EINE SCORE-SUMME: Cosine-Aehnlichkeit, BM25 und eine
+ * Namensuebereinstimmung leben in drei verschiedenen Wertebereichen. Sie zu
+ * addieren hiesse, sie stillschweigend gleich zu skalieren. RRF benutzt nur
+ * die RANGFOLGE jedes Zweigs und ist damit gegen die Skala jedes einzelnen
+ * Zweigs unempfindlich — dieselbe Eigenschaft, wegen der spec.md §13.4 RRF
+ * als einziges Fusionsverfahren fuer v1 festlegt.
+ *
+ * WARUM k = 60: der Wert aus der RRF-Originalarbeit (Cormack, Clarke,
+ * Buettcher 2009), seither die uebliche Voreinstellung — unter anderem in
+ * Qdrants eigener RRF-Implementierung, gegen die dieser Abrufkern austauschbar
+ * bleiben soll. Grosses k daempft den Vorsprung der ersten Plaetze, kleines k
+ * ueberhoeht ihn; 60 ist der dokumentierte Mittelweg, nicht ein geratener.
+ *
+ * WARUM DIE ZWEIGGEWICHTE SO GEWAEHLT SIND:
+ * - dicht 1.0 und lexikalisch 1.0 — die beiden Abrufzweige sind gleichwertig;
+ *   welcher besser ist, haengt an der Anfrage (Absichtsfrage vs. Bezeichner),
+ *   und genau deshalb werden beide gefragt;
+ * - Symbolname 0.5 — der Zweig ist eine PRAEZISIONS-, keine Abrufquelle. Ein
+ *   exakter Namenstreffer wird zusaetzlich als `exact_symbol_boost` belohnt
+ *   (spec.md §13.3). Mit vollem Gewicht in der Fusion UND vollem Boost
+ *   wuerde derselbe Beleg doppelt zaehlen; das halbe Gewicht ist der
+ *   ausdrueckliche Abschlag dafuer.
+ */
+import { compareCodepoints } from "@untangle-code/domain";
+
+/** Glaettungskonstante der RRF-Formel (siehe Modulkommentar). */
+export const RRF_K = 60;
+
+/** Voreingestellte Zweiggewichte (siehe Modulkommentar). */
+export const DEFAULT_BRANCH_WEIGHTS = {
+  dense: 1,
+  lexical: 1,
+  symbol: 0.5,
+} as const;
+
+export type FusionBranch = keyof typeof DEFAULT_BRANCH_WEIGHTS;
+
+/** Eine Rangliste eines Zweigs: IDs, bester zuerst. */
+export interface FusionInput {
+  branch: FusionBranch;
+  /** IDs in Rangfolge; Position 0 ist Rang 1. */
+  rankedIds: readonly string[];
+}
+
+export interface FusionResult {
+  id: string;
+  /** Roher RRF-Wert. */
+  rrf: number;
+  /** Auf [0, 1] normalisierter RRF-Wert (siehe {@link maximumRrf}). */
+  normalized: number;
+  /** Beitragende Zweige mit ihrem 1-basierten Rang. */
+  ranks: Partial<Record<FusionBranch, number>>;
+  /** Wirksame Gewichte der beteiligten Zweige (fuer die Score-Evidenz). */
+  weights?: Partial<Record<FusionBranch, number>>;
+}
+
+export type BranchWeights = Record<FusionBranch, number>;
+
+/**
+ * Der groesstmoegliche RRF-Wert: jeder beteiligte Zweig auf Rang 1.
+ *
+ * Damit wird auf [0, 1] normalisiert, OHNE durch den Maximalwert der aktuellen
+ * Trefferliste zu teilen. Das ist der Unterschied zwischen „dieser Treffer ist
+ * gut" und „dieser Treffer war der beste, den wir hatten": eine Normalisierung
+ * am Listenmaximum gaebe dem besten Treffer immer 1.0, auch wenn er schlecht
+ * ist — und die Findability-Diagnose (vision.md §1d) braucht genau diesen
+ * Unterschied.
+ */
+export function maximumRrf(branches: readonly FusionBranch[], weights: BranchWeights): number {
+  const uniqueBranches = [...new Set(branches)];
+  return uniqueBranches.reduce((sum, branch) => sum + weights[branch] / (RRF_K + 1), 0);
+}
+
+/**
+ * Fusioniert die Ranglisten. Ein Kandidat, der in einem Zweig nicht vorkommt,
+ * bekommt von diesem Zweig schlicht keinen Beitrag — er wird nicht bestraft.
+ *
+ * Die Ausgabe ist absteigend nach RRF sortiert, bei Gleichstand nach
+ * Codepoints der ID (deterministisch).
+ */
+export function fuseRankings(
+  inputs: readonly FusionInput[],
+  weights: BranchWeights = { ...DEFAULT_BRANCH_WEIGHTS },
+): FusionResult[] {
+  const accumulator = new Map<
+    string,
+    { rrf: number; ranks: Partial<Record<FusionBranch, number>> }
+  >();
+  for (const input of inputs) {
+    const weight = weights[input.branch];
+    input.rankedIds.forEach((id, index) => {
+      const rank = index + 1;
+      const entry = accumulator.get(id) ?? { rrf: 0, ranks: {} };
+      entry.rrf += weight / (RRF_K + rank);
+      entry.ranks[input.branch] = rank;
+      accumulator.set(id, entry);
+    });
+  }
+  const maximum = maximumRrf(
+    inputs.map((input) => input.branch),
+    weights,
+  );
+  const results: FusionResult[] = [...accumulator.entries()].map(([id, entry]) => ({
+    id,
+    rrf: entry.rrf,
+    normalized: maximum === 0 ? 0 : entry.rrf / maximum,
+    ranks: entry.ranks,
+    weights: Object.fromEntries(
+      [...new Set(inputs.map((input) => input.branch))].map((branch) => [branch, weights[branch]]),
+    ),
+  }));
+  results.sort((a, b) => (a.rrf === b.rrf ? compareCodepoints(a.id, b.id) : b.rrf - a.rrf));
+  return results;
+}

package/src/glob.ts

@@ -0,0 +1,151 @@
+/**
+ * Deterministischer Glob-Abgleich fuer Pfad-Ein- und -Ausschluss
+ * (Nutzerwunsch A4: „Pfad-Ein-/Ausschluss" wie ein grep-Werkzeug).
+ *
+ * Warum eine eigene, kleine Implementierung statt einer Bibliothek: der
+ * Abgleich muss auf „/"-normalisierten, repo-relativen Pfaden arbeiten
+ * (spec.md §5.2), darf keine Dateisystemzugriffe machen (wir globben ueber
+ * INDIZIERTE Pfade, nicht ueber die Platte) und muss auf jeder Maschine
+ * dieselbe Antwort geben. Die unterstuetzte Teilmenge ist bewusst klein und
+ * hier vollstaendig dokumentiert:
+ *
+ * | Muster   | Bedeutung |
+ * |---|---|
+ * | `?`      | genau ein Zeichen, aber nie `/` |
+ * | `*`      | beliebig viele Zeichen, aber nie `/` |
+ * | `**`     | beliebig viele Zeichen inklusive `/` |
+ * | `[abc]`  | eine Zeichenklasse, `[!abc]`/`[^abc]` negiert |
+ * | sonst    | Literal |
+ *
+ * Ein Muster ohne `/` wird zusaetzlich gegen den BASENAMEN geprueft, damit
+ * `*.ts` das tut, was jeder erwartet, ohne dass der Nutzer `**\/*.ts`
+ * schreiben muss. Diese Bequemlichkeit ist eine bewusste Entscheidung und in
+ * der README als solche vermerkt.
+ */
+
+/** Wandelt ein Glob-Muster in einen verankerten regulaeren Ausdruck. */
+export function globToRegExp(pattern: string): RegExp {
+  let source = "^";
+  let index = 0;
+  while (index < pattern.length) {
+    const char = pattern[index] as string;
+    if (char === "*") {
+      const isDouble = pattern[index + 1] === "*";
+      if (isDouble) {
+        // `a/**/b` soll auch `a/b` treffen: der Schraegstrich hinter `**`
+        // wird optional mitgeschluckt.
+        if (pattern[index + 2] === "/") {
+          source += "(?:.*/)?";
+          index += 3;
+          continue;
+        }
+        source += ".*";
+        index += 2;
+        continue;
+      }
+      source += "[^/]*";
+      index += 1;
+      continue;
+    }
+    if (char === "?") {
+      source += "[^/]";
+      index += 1;
+      continue;
+    }
+    if (char === "[") {
+      const close = pattern.indexOf("]", index + 1);
+      if (close === -1) {
+        // Unpaarige Klammer ist ein Literal, kein Fehler — ein Suchmuster
+        // darf nicht daran scheitern, dass jemand `[` im Pfad meint.
+        source += "\\[";
+        index += 1;
+        continue;
+      }
+      const body = pattern.slice(index + 1, close);
+      const negated = body.startsWith("!") || body.startsWith("^");
+      const content = negated ? body.slice(1) : body;
+      source += `[${negated ? "^" : ""}${content.replace(/[\\\]]/g, "\\$&")}]`;
+      index = close + 1;
+      continue;
+    }
+    source += char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    index += 1;
+  }
+  source += "$";
+  try {
+    return new RegExp(source, "u");
+  } catch (error) {
+    // Ein fehlerhaftes Muster ist ein EINGABEFEHLER des Nutzers. Ohne diesen
+    // Rahmen wandert der rohe `SyntaxError` durch den Abgleich bis in ein
+    // catch, das ihn als Speicherausfall verbucht — der Nutzer bekaeme dann
+    // „Provider nicht verfuegbar" fuer sein eigenes Zeichenklassenmuster.
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`glob pattern "${pattern}" is not a valid pattern: ${message}`);
+  }
+}
+
+/**
+ * Prueft eine Musterliste, BEVOR sie benutzt wird.
+ *
+ * Warum vorab und nicht erst beim Abgleich: der Abgleich laeuft je Kandidat,
+ * tief in der Auswertung. Ein Fehler dort trifft eine Stelle, die ihn nur noch
+ * als „dieses Ziel hat nicht geantwortet" deuten kann. Vorab geprueft, ist er
+ * das, was er ist: eine abgelehnte Anfrage mit benanntem Muster.
+ */
+export function assertValidGlobPatterns(patterns: readonly string[], label: string): void {
+  for (const pattern of patterns) {
+    try {
+      globToRegExp(normalizeGlobPath(pattern));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`search query field "${label}" contains an invalid pattern: ${message}`);
+    }
+  }
+}
+
+/** Kanonisiert einen Pfad fuer den Abgleich: Backslashes zu `/`, kein `./`. */
+export function normalizeGlobPath(path: string): string {
+  const slashed = path.replace(/\\/g, "/");
+  return slashed.startsWith("./") ? slashed.slice(2) : slashed;
+}
+
+/** True, wenn `path` auf `pattern` passt (siehe Modulkommentar). */
+export function matchesGlob(path: string, pattern: string): boolean {
+  const normalizedPath = normalizeGlobPath(path);
+  const normalizedPattern = normalizeGlobPath(pattern);
+  const expression = globToRegExp(normalizedPattern);
+  if (expression.test(normalizedPath)) {
+    return true;
+  }
+  if (!normalizedPattern.includes("/")) {
+    const basename = normalizedPath.slice(normalizedPath.lastIndexOf("/") + 1);
+    return expression.test(basename);
+  }
+  return false;
+}
+
+/** True, wenn `path` auf mindestens eines der Muster passt. */
+export function matchesAnyGlob(path: string, patterns: readonly string[]): boolean {
+  return patterns.some((pattern) => matchesGlob(path, pattern));
+}
+
+/**
+ * Entscheidet ueber Ein-/Ausschluss eines Pfades.
+ *
+ * - leere Einschlussliste heisst „alles einschliessen" (wie in SearchFiltersV1
+ *   dokumentiert: eine leere Liste ist kein Filter);
+ * - Ausschluss gewinnt immer gegen Einschluss.
+ */
+export function isPathSelected(
+  path: string,
+  include: readonly string[],
+  exclude: readonly string[],
+): boolean {
+  if (exclude.length > 0 && matchesAnyGlob(path, exclude)) {
+    return false;
+  }
+  if (include.length === 0) {
+    return true;
+  }
+  return matchesAnyGlob(path, include);
+}