@untangle-code/search 0.0.0-stage → 0.1.1

package/src/symbol-match.ts

@@ -0,0 +1,87 @@
+/**
+ * Exakte und nahe Symbolnamen-Treffer (dritter Abrufzweig).
+ *
+ * Der Nutzerfall aus vision.md §1d ist woertlich: „wenn ich nach ‚Funktion X'
+ * suche". Ein dichter Vektor kann einen exakten Namen verfehlen, weil er
+ * Bedeutung und nicht Zeichen vergleicht; BM25 kann ihn unter langen Rumpf-
+ * texten begraben. Der Symbolzweig ist deshalb kein Bonus auf einen anderen
+ * Zweig, sondern eine eigene Rangliste mit eigener Begruendung.
+ *
+ * Vier Stufen, absichtlich grob und vollstaendig dokumentiert (jede feinere
+ * Abstufung waere ein magisches Gewicht ohne Beleg):
+ *
+ * | Staerke | Bedingung |
+ * |---|---|
+ * | 1.00 | `symbol_name` ist zeichengleich mit dem Suchtext |
+ * | 0.80 | zeichengleich bis auf Gross-/Kleinschreibung |
+ * | 0.60 | `symbol_fqn` endet auf den Suchtext (`Service.charge`) |
+ * | 0.40 | alle Teilwoerter der Anfrage stecken im Namen (`getUser` ⊂ `getUserById`) |
+ */
+import { compareCodepoints } from "@untangle-code/domain";
+import type { CodeChunkPayloadV1 } from "@untangle-code/domain";
+
+import { identifierParts } from "./tokenize.js";
+
+/** Ergebnis eines Namensvergleichs. */
+export interface SymbolMatch {
+  strength: number;
+  /** Beleg fuer die Score-Zerlegung, z. B. `symbol_name == "charge"`. */
+  evidence: string;
+}
+
+/** Vergleicht den Suchtext mit den Namensfeldern eines Chunks. */
+export function matchSymbolName(
+  payload: CodeChunkPayloadV1,
+  queryText: string,
+): SymbolMatch | null {
+  const name = payload.symbol_name;
+  const query = queryText.trim();
+  if (query === "") {
+    return null;
+  }
+  if (name !== undefined && name === query) {
+    return { strength: 1, evidence: `symbol_name == "${name}"` };
+  }
+  if (name !== undefined && name.toLowerCase() === query.toLowerCase()) {
+    return { strength: 0.8, evidence: `symbol_name ~= "${name}" (case-insensitive)` };
+  }
+  const fqn = payload.symbol_fqn;
+  if (
+    fqn !== undefined &&
+    (fqn === query || fqn.endsWith(`.${query}`) || fqn.endsWith(`::${query}`))
+  ) {
+    return { strength: 0.6, evidence: `symbol_fqn "${fqn}" ends with "${query}"` };
+  }
+  if (name === undefined) {
+    return null;
+  }
+  const queryParts = identifierParts(query);
+  const nameParts = new Set(identifierParts(name));
+  if (queryParts.length > 0 && queryParts.every((part) => nameParts.has(part))) {
+    return { strength: 0.4, evidence: `symbol_name "${name}" contains all query parts` };
+  }
+  return null;
+}
+
+/**
+ * Kandidatenwerte fuer den Speicher-Filter auf `symbol_name`.
+ *
+ * Der Payload-Filter des Speichers kann nur exakte Werte vergleichen. Deshalb
+ * werden hier deterministisch die Schreibweisen erzeugt, die derselbe Name
+ * ueblicherweise hat: der Suchtext selbst, sein letztes Pfad-/FQN-Glied und —
+ * falls der Suchtext genau ein Wort ist — dieses Wort. Mehr NICHT: eine
+ * Kombinatorik ueber camelCase/snake_case-Varianten wuerde Treffer erfinden,
+ * die im Index gar nicht so heissen.
+ */
+export function symbolNameFilterCandidates(queryText: string): string[] {
+  const query = queryText.trim();
+  if (query === "") {
+    return [];
+  }
+  const candidates = new Set<string>([query]);
+  const lastSegment = query.split(/[.:#/]/u).at(-1);
+  if (lastSegment !== undefined && lastSegment !== "") {
+    candidates.add(lastSegment);
+  }
+  return [...candidates].sort(compareCodepoints);
+}

package/src/tokenize.ts

@@ -0,0 +1,213 @@
+/**
+ * Bezeichner-bewusste Tokenisierung fuer den lexikalischen Zweig
+ * (spec.md §13.2 Schritt 3: „Query normalisieren, ohne Identifier-Zeichen zu
+ * zerstoeren").
+ *
+ * Eine reine Wortgrenzen-Tokenisierung („alles ausser Buchstaben/Ziffern ist
+ * Trenner") zerlegt `get_user_by_id` korrekt, `getUserById` aber ueberhaupt
+ * nicht — dabei ist genau das der Fall, den der Nutzer meint, wenn er nach
+ * „Funktion X" sucht. Diese Tokenisierung liefert deshalb ZWEI Ebenen:
+ *
+ * 1. den ganzen, kleingeschriebenen Bezeichner (`getuserbyid`) — damit ein
+ *    exakter Namenstreffer den hoechsten lexikalischen Gewinn hat;
+ * 2. seine Teilwoerter (`get`, `user`, `by`, `id`) — damit ein Treffer auch
+ *    ueber Teilbegriffe gefunden wird.
+ *
+ * Beide Ebenen landen im selben Token-Bag. Das ist bewusst: BM25 belohnt
+ * dadurch einen Volltreffer zusaetzlich zu seinen Teilen, ohne dass es dafuer
+ * ein Sonderregelwerk im Ranker braucht.
+ *
+ * Alles hier ist reine Arithmetik ueber den Eingabetext — kein Locale, keine
+ * Zeit, kein Zufall (docs/BUILD_PLAN.md §3 „Determinismus").
+ */
+
+import { tokenizeIdentifiers } from "@untangle-code/domain";
+
+// Indexing, sparse queries and reranking must use one versioned token space.
+export { identifierParts, splitIdentifierRun, tokenizeIdentifiers } from "@untangle-code/domain";
+
+/**
+ * Funktionswoerter, die in frei formulierten Suchfragen fast nur die Form der
+ * Frage beschreiben. Sie als BM25-Begriffe zu werten bevorzugt lange Prosa,
+ * die ebenfalls oft "wo wird"/"how is" enthaelt, vor dem gesuchten Code.
+ *
+ * Die Liste ist absichtlich klein und enthaelt nur geschlossene grammatische
+ * Klassen in Deutsch und Englisch. Fachwoerter, Verben und Bezeichner werden
+ * nie als Stopwoerter geraten. Wenn eine Anfrage ausschliesslich daraus
+ * besteht, faellt {@link informativeQueryTokens} auf die Originaltokens
+ * zurueck, damit beispielsweise eine Symbolsuche nach `is` nicht verschwindet.
+ */
+const QUERY_STOP_WORDS = new Set([
+  "a",
+  "als",
+  "an",
+  "and",
+  "are",
+  "as",
+  "at",
+  "auf",
+  "aus",
+  "be",
+  "bei",
+  "by",
+  "das",
+  "dass",
+  "dem",
+  "den",
+  "der",
+  "des",
+  "die",
+  "does",
+  "ein",
+  "eine",
+  "einem",
+  "einen",
+  "einer",
+  "eines",
+  "es",
+  "for",
+  "from",
+  "für",
+  "fuer",
+  "how",
+  "im",
+  "in",
+  "into",
+  "is",
+  "ist",
+  "it",
+  "mit",
+  "of",
+  "on",
+  "or",
+  "sich",
+  "sind",
+  "that",
+  "the",
+  "this",
+  "to",
+  "und",
+  "von",
+  "was",
+  "wann",
+  "warum",
+  "werden",
+  "what",
+  "when",
+  "where",
+  "which",
+  "wie",
+  "wird",
+  "with",
+  "wo",
+  "wofür",
+  "wofuer",
+  "who",
+  "why",
+  "welche",
+  "welchem",
+  "welchen",
+  "welcher",
+  "welches",
+  "wer",
+  "zu",
+]);
+
+const UNAMBIGUOUS_GERMAN_QUESTION_OPENERS = new Set([
+  "warum",
+  "wann",
+  "welche",
+  "welchem",
+  "welchen",
+  "welcher",
+  "welches",
+  "wer",
+  "wie",
+  "wo",
+  "wofür",
+  "wofuer",
+]);
+
+const GERMAN_WAS_PREDICATES = new Set([
+  "bedeutet",
+  "geschieht",
+  "ist",
+  "passiert",
+  "sind",
+  "werden",
+  "wird",
+]);
+
+const GERMAN_INFLECTED_QUESTION_PRONOUNS = new Set([
+  "welche",
+  "welchem",
+  "welchen",
+  "welcher",
+  "welches",
+]);
+
+const GERMAN_GRAMMAR_MARKERS = new Set([
+  "das",
+  "dass",
+  "dem",
+  "den",
+  "der",
+  "des",
+  "die",
+  "ein",
+  "eine",
+  "einem",
+  "einen",
+  "einer",
+  "eines",
+  "ist",
+  "sich",
+  "und",
+  "von",
+  "werden",
+  "wird",
+  "zu",
+]);
+
+/**
+ * Tokenisiert eine frei formulierte Anfrage fuer den lexikalischen Rang und
+ * entfernt nur grammatische Fragehuelsen. Wiederholungen bleiben erhalten;
+ * der Aufrufer entscheidet wie beim normalen Token-Bag selbst, ob er daraus
+ * eine Menge oder Haeufigkeiten braucht.
+ */
+export function informativeQueryTokens(text: string): string[] {
+  const tokens = tokenizeIdentifiers(text);
+  const informative = tokens.filter((token) => !QUERY_STOP_WORDS.has(token));
+  return informative.length === 0 ? tokens : informative;
+}
+
+/**
+ * Erkennt die enge Form, fuer die der Benchmark einen systematischen
+ * Cross-Language-Konflikt belegt: eine deutsch formulierte Frage vor
+ * ueberwiegend englischen Codebezeichnern. Das ist bewusst KEINE allgemeine
+ * Spracherkennung. Eindeutige deutsche Fragewoerter reichen; das auch im
+ * Englischen vorkommende `was` braucht zwei weitere Grammatikmarker.
+ */
+export function isLikelyGermanQuestion(text: string): boolean {
+  const tokens = tokenizeIdentifiers(text);
+  const first = tokens[0];
+  if (first === undefined) {
+    return false;
+  }
+  return (
+    UNAMBIGUOUS_GERMAN_QUESTION_OPENERS.has(first) ||
+    (first === "in" && GERMAN_INFLECTED_QUESTION_PRONOUNS.has(tokens[1] ?? "")) ||
+    (first === "was" &&
+      (GERMAN_WAS_PREDICATES.has(tokens[1] ?? "") ||
+        new Set(tokens.filter((token) => GERMAN_GRAMMAR_MARKERS.has(token))).size >= 2))
+  );
+}
+
+/** Token-Haeufigkeiten als Map; Reihenfolge der Einfuegung ist Textreihenfolge. */
+export function termFrequencies(tokens: readonly string[]): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const token of tokens) {
+    counts.set(token, (counts.get(token) ?? 0) + 1);
+  }
+  return counts;
+}

package/src/types.ts

@@ -0,0 +1,206 @@
+/**
+ * Paket-eigene Vertraege des Abrufkerns.
+ *
+ * Grundsatz: Alles, was schon in `@untangle-code/domain` steht
+ * (`SearchRequestV1`, `SearchQueryV1`, `ScoreBreakdownV1`, `SearchHitV1`,
+ * `SearchResultSetV1`, `SkipLedgerEntryV1`, …), wird NICHT neu definiert,
+ * sondern verwendet. Hier stehen nur die Erweiterungen, die der Abrufkern
+ * zusaetzlich braucht und die die Werkzeuggrenze aus spec.md §13.1 bewusst
+ * nicht kennt:
+ *
+ * - Suchmodus (semantisch / lexikalisch / Symbolname / hybrid),
+ * - die grep-artigen Faehigkeiten (Nutzerwunsch A4),
+ * - Ausgabeformate und Sortierung,
+ * - der Komplexitaets-Bias (vision.md §1b: Komplexitaet ist ein Blickwinkel
+ *   auf dieselbe Frage, kein zweites Werkzeug).
+ */
+import type {
+  IndexFreshnessV1,
+  SearchAbstention,
+  SearchRequestV1,
+  SkipLedgerEntryV1,
+  ToolWarningV1,
+} from "@untangle-code/domain";
+
+/**
+ * Welche unabhaengigen Abruf- und Rankingzweige ausgefuehrt werden.
+ *
+ * - `hybrid` (Default): dicht + lexikalisch + exakter Symbolname, fusioniert;
+ * - `semantic`: nur der dichte Zweig;
+ * - `lexical`: nur BM25;
+ * - `symbol`: nur der exakte Symbolnamen-Abrufzweig.
+ *
+ * Lexikalische und Symbolsuche erzeugen kein Queryembedding. Ein
+ * eingeschraenkter Modus laesst die anderen Abrufzweige weg; Fusion und
+ * Score-Zerlegung bleiben dieselben. Genau deshalb
+ * bleibt ein `lexical`-Ergebnis mit einem `hybrid`-Ergebnis vergleichbar
+ * lesbar — es fehlen nur Bestandteile, es sind keine anderen.
+ */
+export const SEARCH_MODES = ["hybrid", "semantic", "lexical", "symbol"] as const;
+
+export type SearchMode = (typeof SEARCH_MODES)[number];
+
+// Aus dem Domain re-exportiert, damit Aufrufer nur EIN Paket brauchen.
+export { SEARCH_ABSTENTIONS } from "@untangle-code/domain";
+export type { SearchAbstention };
+
+/**
+ * Ausdrueckliche Bevorzugung einfacher oder komplexer Treffer (vision.md §1b).
+ *
+ * Default ist `none`. Das ist eine Entscheidung, keine Bequemlichkeit:
+ * Komplexitaet DARF die Rangfolge nicht stillschweigend verschieben. Wer sie
+ * einbezieht, bekommt dafuer einen sichtbaren `complexity_modifier` in der
+ * Score-Zerlegung.
+ */
+export const COMPLEXITY_BIASES = ["none", "prefer-simple", "prefer-complex"] as const;
+
+export type ComplexityBias = (typeof COMPLEXITY_BIASES)[number];
+
+/** Sortierschluessel der Trefferliste (Nutzerwunsch A4: „Sortierung"). */
+export const SEARCH_SORTS = [
+  "relevance",
+  "path",
+  "complexity-desc",
+  "complexity-asc",
+  "findability-asc",
+] as const;
+
+export type SearchSort = (typeof SEARCH_SORTS)[number];
+
+/** Ausgabeformate (Nutzerwunsch A4: „Text, JSON, JSONL"). */
+export const OUTPUT_FORMATS = ["text", "json", "jsonl"] as const;
+
+export type OutputFormat = (typeof OUTPUT_FORMATS)[number];
+
+/**
+ * Suchanfrage des Abrufkerns: die Spezifikationsform aus spec.md §13.1 plus
+ * die Erweiterungen dieses Pakets. Additiv — jede gueltige `SearchRequestV1`
+ * ist auch eine gueltige `UntangleSearchRequestV1`.
+ */
+export interface UntangleSearchRequestV1 extends SearchRequestV1 {
+  mode?: SearchMode;
+  /**
+   * Verhalten bei unzureichender Evidenz. Fehlt es, gilt `strict` — das ist
+   * byte-identisch zum Verhalten vor Welle 14, bis in beide Fingerprints.
+   */
+  abstention?: SearchAbstention;
+  /** Pfadmuster, die AUSGESCHLOSSEN werden (Gegenstueck zu `pathGlob`). */
+  pathExclude?: string[];
+  /** Chunk-Inhalt mitliefern; Default false (tokenarm fuer Agents). */
+  includeContent?: boolean;
+  complexityBias?: ComplexityBias;
+  sort?: SearchSort;
+  /** Nur Treffer mit Findability-Score <= diesem Wert (vision.md §1d). */
+  findabilityMaxScore?: number;
+  /** Nur Treffer mit Findability-Score >= diesem Wert. */
+  findabilityMinScore?: number;
+}
+
+/**
+ * Normalisierte Zusatzangaben — das Gegenstueck zu `SearchQueryV1` fuer die
+ * Felder, die dieses Paket ergaenzt. Alle Felder sind gesetzt (keine
+ * `undefined`-Faelle mehr), damit der Ausfuehrungspfad keine Defaults mehr
+ * erraten muss.
+ */
+export interface SearchQueryExtensionsV1 {
+  mode: SearchMode;
+  abstention: SearchAbstention;
+  pathExcludes: string[];
+  includeContent: boolean;
+  complexityBias: ComplexityBias;
+  sort: SearchSort;
+}
+
+// ---------------------------------------------------------------------------
+// grep-Modus (Nutzerwunsch A4)
+// ---------------------------------------------------------------------------
+
+/** Sortierung der grep-Treffer. */
+export const GREP_SORTS = ["path", "matches-desc"] as const;
+
+export type GrepSort = (typeof GREP_SORTS)[number];
+
+/**
+ * Regex-/Literalsuche ueber den INDEXIERTEN Inhalt.
+ *
+ * Wichtig fuer das Verstaendnis der Ergebnisse: gesucht wird im Index, nicht
+ * auf der Platte. Ein nicht indizierter oder wegen Groesse uebersprungener
+ * Inhalt kann hier nicht gefunden werden — deshalb traegt das Ergebnis den
+ * Skip-Ledger mit, statt schlicht „nichts gefunden" zu behaupten (E4).
+ */
+export interface GrepRequestV1 {
+  /** Suchmuster; regulaerer Ausdruck, wenn `regex` true ist, sonst Literal. */
+  pattern: string;
+  regex?: boolean;
+  caseSensitive?: boolean;
+  /** Nur ganze Woerter (Bezeichnergrenzen). */
+  wholeWord?: boolean;
+  workspaceId?: string;
+  repositories?: string[];
+  refs?: string[];
+  languages?: string[];
+  pathGlob?: string[];
+  pathExclude?: string[];
+  /** Kontextzeilen vor bzw. nach der Trefferzeile. */
+  contextLinesBefore?: number;
+  contextLinesAfter?: number;
+  /** Obergrenze der zurueckgegebenen Treffer insgesamt. */
+  maxMatches?: number;
+  /** Obergrenze je Datei; verhindert, dass eine Datei die Liste fuellt. */
+  maxMatchesPerFile?: number;
+  /**
+   * Obergrenze der durchsuchten Chunks. Schuetzt vor pathologischen
+   * Ausdruecken und riesigen Indizes; Ueberschreitung ist ein sichtbarer
+   * Abbruchgrund, kein stilles Kuerzen.
+   */
+  maxScannedChunks?: number;
+  sort?: GrepSort;
+}
+
+/** Eine Kontextzeile eines grep-Treffers. */
+export interface GrepContextLineV1 {
+  /** 1-basierte Zeilennummer in der Datei. */
+  line: number;
+  text: string;
+}
+
+/** Ein einzelner grep-Treffer mit Herkunft und Kontext. */
+export interface GrepMatchV1 {
+  repoId: string;
+  repoLabel: string;
+  refId: string;
+  refName: string;
+  commitSha?: string;
+  fileId: string;
+  /** „/"-normalisierter, repo-relativer Pfad. */
+  filePath: string;
+  language: string;
+  chunkId: string;
+  symbolName?: string;
+  /** 1-basierte Zeilennummer in der Datei. */
+  line: number;
+  /** 1-basierte Spalte des Treffers innerhalb der Zeile (UTF-16-Einheiten). */
+  column: number;
+  /** Der getroffene Text selbst. */
+  matchText: string;
+  /** Die vollstaendige Trefferzeile. */
+  lineText: string;
+  before: GrepContextLineV1[];
+  after: GrepContextLineV1[];
+}
+
+/** Ergebnis einer grep-Ausfuehrung. */
+export interface GrepResultSetV1 {
+  schemaVersion: 1;
+  indexFreshness?: IndexFreshnessV1;
+  pattern: string;
+  isRegex: boolean;
+  matches: GrepMatchV1[];
+  totalMatches: number;
+  /** True, wenn eine Grenze griff; dann ist `truncationReason` Pflicht (E4). */
+  truncated: boolean;
+  truncationReason?: "max_matches" | "max_matches_per_file" | "max_scanned_chunks";
+  scannedChunks: number;
+  skipped: SkipLedgerEntryV1[];
+  warnings: ToolWarningV1[];
+}