cgraphx 1.1.0 → 1.3.0

package/dist/search/related.js

@@ -0,0 +1,667 @@
+"use strict";
+/**
+ * Related-code search — find methods / classes / files with similar names
+ * across the project. Cross-class retrieval: where `context` shows you a
+ * method's siblings in the same class, `related` shows you its peers across
+ * the whole codebase.
+ *
+ * MVP similarity metric: name-based (camelCase token overlap + Levenshtein
+ * distance + substring match). No AST signature matching, no body-shape
+ * analysis — those are explicit non-goals per clarify-requirements.
+ *
+ * Input is multi-granular:
+ *   - `Class#method`        — method-level: find similar methods project-wide
+ *   - `Class`               — class-level: find similar class/interface names
+ *   - `path/to/file.java`   — file-level: find files with similar basenames
+ *   - bare `<name>`         — fuzzy method search (like calls callers mode)
+ *
+ * Output: top-K matches, similarity-ranked. Same essential/recommended/optional
+ * tiered budget as `calls` / `impact`.
+ *
+ * Isolation: lives under `src/search/`, imports nothing from the indexed
+ * pipeline. Reuses call-sites helpers (listJavaFamilyFiles, DEFAULT_EXCLUDE_DIRS).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PENALTY_GETTER_MISMATCH = exports.PENALTY_POJO_VS_DOMAIN = exports.GETTER_PREFIX = exports.POJO_RETURN_TYPES = void 0;
+exports.searchRelated = searchRelated;
+exports.nameSimilarity = nameSimilarity;
+exports.camelSplit = camelSplit;
+exports.levenshtein = levenshtein;
+exports.semanticPenalty = semanticPenalty;
+exports.extractMethodReturnType = extractMethodReturnType;
+exports.deriveQueryReturnType = deriveQueryReturnType;
+exports.applyRelatedTieredBudget = applyRelatedTieredBudget;
+exports.formatRelatedResult = formatRelatedResult;
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const grammars_1 = require("../extraction/grammars");
+const call_sites_1 = require("./call-sites");
+const ast_helpers_1 = require("./ast-helpers");
+// ---------------------------------------------------------------------------
+// Main entry
+// ---------------------------------------------------------------------------
+async function searchRelated(projectRoot, query, options = {}) {
+    const { topK = 20, budget = 4000, languages = ['java', 'kotlin'], excludeDirs = [], minScore = 20, } = options;
+    await (0, grammars_1.loadGrammarsForLanguages)(languages);
+    const excludeSet = new Set([...call_sites_1.DEFAULT_EXCLUDE_DIRS, ...excludeDirs]);
+    // 1. Detect query kind + extract normalized name
+    const { kind, queryName } = detectQueryKind(query);
+    // 2. Walk project files
+    const allFiles = await (0, call_sites_1.listJavaFamilyFiles)(projectRoot, excludeSet);
+    // 3. Collect candidates
+    const candidates = [];
+    for (const file of allFiles) {
+        let content;
+        try {
+            content = await fs_1.promises.readFile(file, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const relPath = path.relative(projectRoot, file).replace(/\\/g, '/');
+        if (kind === 'file') {
+            // File-level: compare basenames
+            const baseName = path.basename(file).replace(/\.(java|kt|kts)$/, '');
+            const ext = path.extname(file);
+            const score = nameSimilarity(queryName, baseName);
+            if (score.score >= minScore) {
+                candidates.push({
+                    kind: 'file',
+                    name: baseName + ext,
+                    qualifiedName: relPath,
+                    filePath: relPath,
+                    line: 1,
+                    enclosingClass: null,
+                    similarity: score.score,
+                    reason: score.reason,
+                    snippet: '',
+                });
+            }
+            continue;
+        }
+        // Method / class level — parse and walk AST
+        if (!content.includes(queryName.split(/(?=[A-Z])/)[0] ?? queryName))
+            continue;
+        const language = (0, grammars_1.detectLanguage)(file, content);
+        if (!languages.includes(language))
+            continue;
+        const parser = (0, grammars_1.getParser)(language);
+        if (!parser)
+            continue;
+        const tree = parser.parse(content);
+        if (!tree)
+            continue;
+        (0, ast_helpers_1.walkTree)(tree.rootNode, (node) => {
+            if (kind === 'method') {
+                if (node.type !== 'method_declaration' &&
+                    node.type !== 'constructor_declaration')
+                    return;
+                const nameNode = node.childForFieldName('name');
+                if (!nameNode)
+                    return;
+                const name = nameNode.text;
+                const score = nameSimilarity(queryName, name);
+                if (score.score < minScore)
+                    return;
+                const enclosing = findEnclosingClassName(node);
+                const enclosingReturnType = extractMethodReturnType(node, language);
+                candidates.push({
+                    kind: 'method',
+                    name,
+                    qualifiedName: enclosing ? `${enclosing}#${name}` : name,
+                    filePath: relPath,
+                    line: node.startPosition.row + 1,
+                    enclosingClass: enclosing,
+                    similarity: score.score,
+                    reason: score.reason,
+                    snippet: extractDeclarationSnippet(content, node),
+                    enclosingReturnType,
+                });
+            }
+            else if (kind === 'class') {
+                if (node.type !== 'class_declaration' &&
+                    node.type !== 'interface_declaration' &&
+                    node.type !== 'enum_declaration' &&
+                    node.type !== 'record_declaration')
+                    return;
+                const nameNode = node.childForFieldName('name');
+                if (!nameNode)
+                    return;
+                const name = nameNode.text;
+                const score = nameSimilarity(queryName, name);
+                if (score.score < minScore)
+                    return;
+                const kindMap = {
+                    class_declaration: 'class',
+                    interface_declaration: 'interface',
+                    enum_declaration: 'enum',
+                    record_declaration: 'record',
+                };
+                candidates.push({
+                    kind: kindMap[node.type] ?? 'class',
+                    name,
+                    qualifiedName: name,
+                    filePath: relPath,
+                    line: node.startPosition.row + 1,
+                    enclosingClass: null,
+                    similarity: score.score,
+                    reason: score.reason,
+                    snippet: extractDeclarationSnippet(content, node),
+                });
+            }
+        });
+    }
+    // 4. Apply semantic penalty (iteration-3 B-6 #6).
+    //    For method queries: derive the query's likely return type from same-name
+    //    candidates (most frequent), then penalize candidates whose return type
+    //    or name shape indicates a different intent (e.g. a String-returning getter
+    //    `getSceneNameWithCommit` shouldn't outrank a real domain-object method
+    //    `sceneCommitWithXxx`).
+    if (kind === 'method') {
+        const queryMethodReturnType = deriveQueryReturnType(candidates, queryName);
+        for (const c of candidates) {
+            const baseScore = c.similarity;
+            const penalty = semanticPenalty({ name: c.name, enclosingReturnType: c.enclosingReturnType }, { name: queryName, enclosingReturnType: queryMethodReturnType });
+            if (penalty < 0) {
+                const finalScore = Math.max(0, baseScore + penalty);
+                c.similarity = finalScore;
+                const penaltyParts = [];
+                if (c.enclosingReturnType &&
+                    exports.POJO_RETURN_TYPES.has(c.enclosingReturnType) &&
+                    queryMethodReturnType &&
+                    !exports.POJO_RETURN_TYPES.has(queryMethodReturnType)) {
+                    penaltyParts.push(`-${exports.PENALTY_POJO_VS_DOMAIN} POJO return (${c.enclosingReturnType}) vs domain (${queryMethodReturnType})`);
+                }
+                if (exports.GETTER_PREFIX.test(c.name) && !exports.GETTER_PREFIX.test(queryName)) {
+                    penaltyParts.push(`-${exports.PENALTY_GETTER_MISMATCH} getter prefix mismatch`);
+                }
+                c.reason = `${c.reason} · semantic penalty ${penalty} [${penaltyParts.join(', ')}] → ${finalScore}`;
+            }
+        }
+    }
+    // 5. Filter exact-self matches (the query itself shouldn't appear)
+    //    If query was `Class#method`, filter out the exact `Class#method` candidate.
+    const filtered = candidates.filter((c) => {
+        if (kind === 'method' && query.includes('#')) {
+            return c.qualifiedName !== query;
+        }
+        if (kind === 'class') {
+            // Don't return the class that matches the query exactly if there's only one
+            return true;
+        }
+        return true;
+    });
+    // 6. Sort by similarity desc, then by path depth asc, then by line
+    filtered.sort((a, b) => {
+        if (a.similarity !== b.similarity)
+            return b.similarity - a.similarity;
+        const da = a.filePath.split('/').length;
+        const db = b.filePath.split('/').length;
+        if (da !== db)
+            return da - db;
+        if (a.filePath !== b.filePath)
+            return a.filePath.localeCompare(b.filePath);
+        return a.line - b.line;
+    });
+    const belowMinScore = candidates.length - filtered.length;
+    const topMatches = filtered.slice(0, topK);
+    const pastTopK = filtered.length - topMatches.length;
+    // 7. Tiered budget
+    const { tiered, truncatedByBudget } = applyRelatedTieredBudget(topMatches, budget, { forceRecommended: options.withSnippet ?? false, forceOptional: options.full ?? false });
+    return {
+        query,
+        queryKind: kind,
+        queryName,
+        totalFound: filtered.length,
+        returned: tiered.length,
+        matches: tiered,
+        omitted: {
+            belowMinScore,
+            pastTopK,
+            truncatedByBudget,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Query kind detection
+// ---------------------------------------------------------------------------
+function detectQueryKind(query) {
+    // File path: contains `/` or `\` and ends with .java/.kt
+    if (/[/\\]/.test(query) && /\.(java|kt|kts)$/i.test(query)) {
+        return { kind: 'file', queryName: path.basename(query).replace(/\.(java|kt|kts)$/i, '') };
+    }
+    // Method: `Class#method` or `pkg.Class#method`
+    const hashIdx = query.indexOf('#');
+    if (hashIdx >= 0) {
+        return { kind: 'method', queryName: query.slice(hashIdx + 1) };
+    }
+    // File basename without path
+    if (/\.(java|kt|kts)$/i.test(query)) {
+        return { kind: 'file', queryName: query.replace(/\.(java|kt|kts)$/i, '') };
+    }
+    // Class: starts with uppercase letter, single token (no dots)
+    if (/^[A-Z][a-zA-Z0-9_]*$/.test(query)) {
+        return { kind: 'class', queryName: query };
+    }
+    // Default: method (bare name search)
+    return { kind: 'method', queryName: query };
+}
+/**
+ * Score name similarity 0-100. Higher = more similar.
+ *
+ * Heuristics (first match wins):
+ *   exact match (different class)             → 100
+ *   query is exact prefix of candidate        → 85  (createOrder vs createOrderAsync)
+ *   candidate is exact prefix of query        → 75
+ *   all query tokens appear in candidate      → 75  (camelCase token overlap)
+ *   some query tokens match exactly           → 30 + 10 * overlap
+ *   Levenshtein distance ≤ 2                  → 60 - dist * 10
+ *   substring match (one contains the other)  → 40
+ *   Levenshtein distance ≤ 5                  → 25
+ *   else                                      → 0
+ */
+function nameSimilarity(query, candidate) {
+    if (!query || !candidate)
+        return { score: 0, reason: 'empty' };
+    const q = query.toLowerCase();
+    const c = candidate.toLowerCase();
+    // Exact match
+    if (q === c)
+        return { score: 100, reason: 'exact name match' };
+    // Prefix
+    if (c.startsWith(q)) {
+        const extra = candidate.length - query.length;
+        return { score: Math.max(70, 95 - extra * 2), reason: `candidate extends query (+${extra} chars)` };
+    }
+    if (q.startsWith(c)) {
+        const extra = query.length - candidate.length;
+        return { score: Math.max(60, 85 - extra * 2), reason: `query extends candidate (+${extra} chars)` };
+    }
+    // Token overlap (camelCase split)
+    const qTokens = camelSplit(query);
+    const cTokens = camelSplit(candidate);
+    if (qTokens.length > 0 && cTokens.length > 0) {
+        const qSet = new Set(qTokens.map((t) => t.toLowerCase()));
+        const cSet = new Set(cTokens.map((t) => t.toLowerCase()));
+        const intersection = [...qSet].filter((t) => cSet.has(t));
+        if (intersection.length === qSet.size && qSet.size > 0) {
+            // All query tokens are in candidate
+            return {
+                score: 70,
+                reason: `all ${qSet.size} query token${qSet.size === 1 ? '' : 's'} in candidate`,
+            };
+        }
+        if (intersection.length > 0) {
+            return {
+                score: 30 + intersection.length * 10,
+                reason: `${intersection.length}/${qSet.size} query tokens match (${intersection.join(',')})`,
+            };
+        }
+    }
+    // Levenshtein distance
+    const dist = levenshtein(q, c);
+    if (dist <= 2 && Math.max(q.length, c.length) >= 4) {
+        return { score: 60 - dist * 10, reason: `Levenshtein distance ${dist}` };
+    }
+    // Substring
+    if (c.includes(q) || q.includes(c)) {
+        return { score: 40, reason: 'substring match' };
+    }
+    if (dist <= 5) {
+        return { score: 25, reason: `Levenshtein distance ${dist}` };
+    }
+    return { score: 0, reason: 'no similarity' };
+}
+/**
+ * Split camelCase / PascalCase identifier into lowercase tokens.
+ * `createOrderAsync` → ['create', 'Order', 'Async']
+ * `OrderService` → ['Order', 'Service']
+ * `ICustomerOrderService` → ['ICustomer', 'Order', 'Service']
+ *   (note: leading `I` is preserved; we don't strip interface-prefix here)
+ */
+function camelSplit(s) {
+    // Split at uppercase letters (camelCase boundaries), keep the uppercase letter
+    const parts = s.split(/(?=[A-Z])/).filter((p) => p.length > 0);
+    return parts;
+}
+/**
+ * Standard Levenshtein distance (no early termination — names are short).
+ */
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const prev = new Array(b.length + 1);
+    const curr = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            const insertCost = (curr[j - 1] ?? 0) + 1;
+            const deleteCost = (prev[j] ?? 0) + 1;
+            const substCost = (prev[j - 1] ?? 0) + cost;
+            curr[j] = Math.min(insertCost, deleteCost, substCost);
+        }
+        for (let j = 0; j <= b.length; j++)
+            prev[j] = curr[j] ?? 0;
+    }
+    return prev[b.length] ?? 0;
+}
+// ---------------------------------------------------------------------------
+// Semantic penalty (iteration-3 B-6 #6)
+// ---------------------------------------------------------------------------
+//
+// `nameSimilarity` ranks methods by name shape alone — so a getter that returns
+// a String (`getSceneNameWithCommit`) can tie a real domain method that returns
+// a business object (`sceneGroupCommit` → `CreateCustomerOrderRspVo`) when both
+// share the query's tokens. `semanticPenalty` adds a non-positive adjustment on
+// top of the base nameSimilarity score to push those shape-matched-but-semantically
+// different candidates below real variants.
+//
+// Two independent rules, applied additively:
+//   1. POJO-vs-domain mismatch: candidate returns a POJO (String/Integer/…)
+//      but the query returns a domain object → -PENALTY_POJO_VS_DOMAIN
+//   2. Getter-prefix mismatch: candidate name starts with get/is/has but the
+//      query doesn't → -PENALTY_GETTER_MISMATCH
+//
+// Worst case both rules fire (-35 with default values). Final score is always
+// clamped to >= 0 at the call site.
+/**
+ * POJO / primitive-ish return types. A candidate whose enclosing method returns
+ * one of these is likely a simple accessor/converter, not the business method
+ * the query is after. Add more here if probe shows new patterns.
+ */
+exports.POJO_RETURN_TYPES = new Set([
+    'String', 'Integer', 'Long', 'Boolean', 'void', 'Float', 'Double',
+    'Object', 'Optional', 'int', 'long', 'boolean', 'float', 'double',
+]);
+/** Candidate name starts with `get`/`is`/`has` followed by an uppercase letter. */
+exports.GETTER_PREFIX = /^(get|is|has)[A-Z]/;
+/** Penalty values. Tunable range per plan: -20/-15 (initial) → -25/-20 (max). */
+exports.PENALTY_POJO_VS_DOMAIN = -20;
+exports.PENALTY_GETTER_MISMATCH = -15;
+/**
+ * Returns a non-positive penalty. Higher absolute value = more penalty.
+ *
+ * Rule 1: candidate returns POJO but query returns domain object → -20
+ * Rule 2: candidate starts with get/is/has but query doesn't → -15
+ * Rules stack (worst case -35 with defaults).
+ *
+ * Pure function — no I/O, no AST. Safe to unit-test directly.
+ */
+function semanticPenalty(candidate, queryMethod) {
+    let penalty = 0;
+    // Rule 1: POJO vs domain mismatch.
+    if (candidate.enclosingReturnType &&
+        exports.POJO_RETURN_TYPES.has(candidate.enclosingReturnType) &&
+        queryMethod.enclosingReturnType &&
+        !exports.POJO_RETURN_TYPES.has(queryMethod.enclosingReturnType)) {
+        penalty += exports.PENALTY_POJO_VS_DOMAIN;
+    }
+    // Rule 2: getter prefix on candidate but not on query.
+    if (exports.GETTER_PREFIX.test(candidate.name) &&
+        !exports.GETTER_PREFIX.test(queryMethod.name)) {
+        penalty += exports.PENALTY_GETTER_MISMATCH;
+    }
+    return penalty;
+}
+/**
+ * Extract a method's declared return type from its AST node.
+ *
+ * Java `method_declaration`: read the `type` field (tree-sitter-java exposes
+ *   this for explicit return types). Constructors have no return type → undefined.
+ * Kotlin `function_declaration`: scan children for the `:` token, then take the
+ *   following type node's text. Omitted return type (Unit inferred) → undefined.
+ *
+ * Returns undefined for unknown node shapes (defensive — caller skips penalty).
+ */
+function extractMethodReturnType(node, language) {
+    if (language === 'java') {
+        if (node.type !== 'method_declaration')
+            return undefined;
+        // tree-sitter-java exposes the return type via the `type` field for explicit
+        // types. Constructors (`constructor_declaration`) have no `type` field.
+        const typeNode = node.childForFieldName('type');
+        if (!typeNode)
+            return undefined;
+        // For generic types like `List<String>`, normalize to the raw type name.
+        return normalizeReturnType(typeNode.text);
+    }
+    if (language === 'kotlin') {
+        if (node.type !== 'function_declaration')
+            return undefined;
+        // Kotlin function_declaration children: fun, simple_identifier (name),
+        // function_value_parameters, [:], [user_type], function_body.
+        // Scan for the `:` separator; the return type follows it.
+        const children = node.children;
+        for (let i = 0; i < children.length - 1; i++) {
+            const c = children[i];
+            if (c && c.type === ':' && children[i + 1]) {
+                return normalizeReturnType(children[i + 1].text);
+            }
+        }
+        return undefined; // No explicit return type (Unit inferred).
+    }
+    return undefined;
+}
+/**
+ * Normalize a raw return-type string: strip generics (`List<String>` → `List`),
+ * strip array brackets (`String[]` → `String`), trim whitespace.
+ */
+function normalizeReturnType(raw) {
+    let t = raw.trim();
+    // Strip generics.
+    const genIdx = t.indexOf('<');
+    if (genIdx > 0)
+        t = t.slice(0, genIdx);
+    // Strip array brackets.
+    t = t.replace(/[\[\]]/g, '').trim();
+    return t;
+}
+/**
+ * Derive the query method's likely return type from collected candidates.
+ *
+ * Strategy: among same-name candidates (name === queryName), pick the most
+ * frequent non-undefined return type. This is a heuristic — we assume the
+ * query method exists in the codebase and its return type appears in the
+ * candidate set. Returns undefined if no same-name candidate has a return type.
+ */
+function deriveQueryReturnType(candidates, queryName) {
+    const counts = new Map();
+    for (const c of candidates) {
+        if (c.name === queryName && c.enclosingReturnType) {
+            counts.set(c.enclosingReturnType, (counts.get(c.enclosingReturnType) ?? 0) + 1);
+        }
+    }
+    if (counts.size === 0)
+        return undefined;
+    let best;
+    let bestCount = -1;
+    for (const [rt, count] of counts) {
+        if (count > bestCount) {
+            best = rt;
+            bestCount = count;
+        }
+    }
+    return best;
+}
+// ---------------------------------------------------------------------------
+// AST helpers
+// ---------------------------------------------------------------------------
+function findEnclosingClassName(node) {
+    let cur = node.parent;
+    while (cur) {
+        if (cur.type === 'class_declaration' ||
+            cur.type === 'interface_declaration' ||
+            cur.type === 'enum_declaration' ||
+            cur.type === 'record_declaration') {
+            const name = cur.childForFieldName('name')?.text;
+            if (name)
+                return name;
+        }
+        cur = cur.parent;
+    }
+    return null;
+}
+function extractDeclarationSnippet(content, node) {
+    const startRow = node.startPosition.row;
+    const lines = content.split('\n');
+    // Take the declaration start + 1-2 lines (signature usually fits in 1-3 lines)
+    const end = Math.min(startRow + 3, lines.length);
+    return lines.slice(startRow, end).join('\n').trim();
+}
+// ---------------------------------------------------------------------------
+// Tiered budget (same shape as calls — essential / recommended / optional)
+// ---------------------------------------------------------------------------
+const TIER_ESSENTIAL_COST = 40;
+const TIER_RECOMMENDED_ADDITIONAL = 120;
+const TIER_OPTIONAL_ADDITIONAL = 400;
+function applyRelatedTieredBudget(matches, budget, opts = {}) {
+    let count = 0;
+    let used = 0;
+    for (let i = 0; i < matches.length; i++) {
+        if (used + TIER_ESSENTIAL_COST > budget && count > 0)
+            break;
+        used += TIER_ESSENTIAL_COST;
+        count++;
+    }
+    const truncatedByBudget = matches.length - count;
+    const tiered = matches.slice(0, count).map((m) => ({ ...m, tier: 'essential' }));
+    if (opts.forceOptional) {
+        for (const m of tiered)
+            m.tier = 'optional';
+        return { tiered, truncatedByBudget };
+    }
+    if (opts.forceRecommended) {
+        for (const m of tiered)
+            m.tier = 'recommended';
+        return { tiered, truncatedByBudget };
+    }
+    let remaining = budget - used;
+    for (const m of tiered) {
+        if (remaining >= TIER_RECOMMENDED_ADDITIONAL) {
+            m.tier = 'recommended';
+            remaining -= TIER_RECOMMENDED_ADDITIONAL;
+        }
+    }
+    for (const m of tiered) {
+        if (m.tier !== 'recommended')
+            continue;
+        if (remaining >= TIER_OPTIONAL_ADDITIONAL) {
+            m.tier = 'optional';
+            remaining -= TIER_OPTIONAL_ADDITIONAL;
+        }
+    }
+    return { tiered, truncatedByBudget };
+}
+// ---------------------------------------------------------------------------
+// Formatter (CLI markdown)
+// ---------------------------------------------------------------------------
+function formatRelatedResult(result, options) {
+    const lines = [];
+    lines.push(`**Related to \`${result.queryName}\` (${result.queryKind})** — ${result.totalFound} match${result.totalFound === 1 ? '' : 'es'}, returning ${result.returned}`);
+    if (result.matches.length === 0) {
+        lines.push('');
+        lines.push(`_No matches above the similarity threshold. Try a broader query, or lower the threshold with \`--min-score 10\`._`);
+        return lines.join('\n');
+    }
+    // Group by similarity bucket for scanability
+    const buckets = new Map();
+    for (const m of result.matches) {
+        let bucket;
+        if (m.similarity >= 80)
+            bucket = '🟢 Strong match (≥80)';
+        else if (m.similarity >= 50)
+            bucket = '🟡 Moderate match (50-79)';
+        else if (m.similarity >= 30)
+            bucket = '⚪ Weak match (30-49)';
+        else
+            bucket = '🗄️ Fuzzy match (<30)';
+        const arr = buckets.get(bucket) ?? [];
+        arr.push(m);
+        buckets.set(bucket, arr);
+    }
+    const bucketOrder = [
+        '🟢 Strong match (≥80)',
+        '🟡 Moderate match (50-79)',
+        '⚪ Weak match (30-49)',
+        '🗄️ Fuzzy match (<30)',
+    ];
+    for (const bucket of bucketOrder) {
+        const items = buckets.get(bucket);
+        if (!items || items.length === 0)
+            continue;
+        lines.push('');
+        lines.push(`### ${bucket}`);
+        for (const m of items) {
+            const kindTag = m.kind === 'method' ? '' : ` [${m.kind}]`;
+            const enclosingTag = m.enclosingClass ? ` _in ${m.enclosingClass}_` : '';
+            lines.push(`- **${m.name}**${kindTag} (score ${m.similarity}) \`${m.filePath}:${m.line}\`${enclosingTag}`);
+            lines.push(`  _${m.reason}_`);
+            if (m.tier === 'recommended' || m.tier === 'optional') {
+                if (m.snippet) {
+                    const snippetLines = m.snippet.split('\n').slice(0, 3);
+                    for (const sl of snippetLines) {
+                        lines.push(`  > ${sl}`);
+                    }
+                }
+            }
+            if (options?.explain) {
+                lines.push(`  _score: +${m.similarity} similarity (${m.reason}) = ${m.similarity}_`);
+            }
+        }
+    }
+    // Omitted summary
+    const o = result.omitted;
+    const omittedParts = [];
+    if (o.belowMinScore > 0)
+        omittedParts.push(`${o.belowMinScore} below min-score`);
+    if (o.pastTopK > 0)
+        omittedParts.push(`${o.pastTopK} past topK`);
+    if (o.truncatedByBudget > 0)
+        omittedParts.push(`${o.truncatedByBudget} truncated by budget`);
+    if (omittedParts.length > 0) {
+        lines.push('');
+        lines.push(`_Omitted: ${omittedParts.join(' · ')}_`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=related.js.map