opencodekit 0.23.1 → 0.23.3

package/dist/template/.opencode/plugin/codesearch.ts

@@ -0,0 +1,730 @@
+/**
+ * Csearch Plugin — Multi-Keyword Code Chunk Search with BM25 Ranking
+ *
+ * Bridges natural language queries to structural code chunk retrieval.
+ * The agent's LLM provides semantic query expansion; this tool provides
+ * broad multi-keyword retrieval with function-level chunk extraction
+ * and BM25 relevance ranking.
+ *
+ * Design philosophy:
+ *   - Zero infrastructure: no embeddings, no vector DB, no network
+ *   - Built-in `grep` handles exact-pattern search; this fills the gap for
+ *     multi-keyword discovery with ranked results
+ *   - Function-level chunk extraction returns complete code units, not fragments
+ *   - BM25 scoring provides principled relevance ranking
+ *   - AbortSignal-aware: respects OpenCode's cancellation like built-in grep
+ *   - Glob filter: matches built-in grep's flexibility
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { tool } from "@opencode-ai/plugin/tool";
+import type { Plugin } from "@opencode-ai/plugin";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A single match from ripgrep output */
+interface RawMatch {
+  file: string;
+  line: number;
+  text: string;
+}
+
+/** A code chunk: a function/class body or relevant snippet extracted from a file */
+interface CodeChunk {
+  file: string;
+  relPath: string;
+  startLine: number;
+  endLine: number;
+  text: string;
+  matchedKeywords: string[];
+  score: number;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const TIMEOUT_MS = 15_000;
+const MAX_BUFFER = 8 * 1024 * 1024;
+
+/** Run a command and return output. Returns empty on non-zero exit. */
+function run(cmd: string, args: string[], cwd?: string): { stdout: string; code: number } {
+  try {
+    const result = execFileSync(cmd, args, {
+      encoding: "utf-8" as const,
+      timeout: TIMEOUT_MS,
+      maxBuffer: MAX_BUFFER,
+      cwd: cwd ?? process.cwd(),
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { stdout: result as string, code: 0 };
+  } catch {
+    return { stdout: "", code: 1 };
+  }
+}
+
+/**
+ * Split a query into search keywords.
+ *
+ * Strategy:
+ * 1. Split by whitespace
+ * 2. Split camelCase identifiers into constituent words
+ * 3. Deduplicate
+ *
+ * The agent is expected to provide specific, relevant keywords directly.
+ * Stop words are not stripped — the agent controls query quality.
+ */
+function expandQuery(query: string): string[] {
+  const keywords = new Set<string>();
+  const rawParts = query.trim().split(/\s+/);
+
+  for (const part of rawParts) {
+    if (part.length === 0) continue;
+
+    // Add whole token (useful for exact symbol names like validateToken)
+    keywords.add(part);
+
+    // Split camelCase: "validateToken" → "validate", "Token"
+    const camelParts = part.split(/(?<=[a-z])(?=[A-Z])/);
+    for (const c of camelParts) {
+      const cleaned = c.toLowerCase().replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, "");
+      if (cleaned.length > 1 && cleaned !== part.toLowerCase()) {
+        keywords.add(cleaned);
+      }
+    }
+  }
+
+  return Array.from(keywords);
+}
+
+/** Parse ripgrep output into structured matches. */
+function parseMatches(raw: string): RawMatch[] {
+  const results: RawMatch[] = [];
+  for (const line of raw.split("\n").filter(Boolean)) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const file = line.slice(0, colonIdx);
+    const rest = line.slice(colonIdx + 1);
+    const lineBreak = rest.indexOf(":");
+    const lineNum = lineBreak > 0 ? parseInt(rest.slice(0, lineBreak), 10) : NaN;
+    const text =
+      lineBreak > 0
+        ? rest
+            .slice(lineBreak + 1)
+            .trim()
+            .slice(0, 200)
+        : rest.trim().slice(0, 200);
+    if (!isNaN(lineNum)) {
+      results.push({ file, line: lineNum, text });
+    }
+  }
+  return results;
+}
+
+/**
+ * Run a single keyword search via ripgrep.
+ * All file type detection is left to rg's built-in binary detection + .gitignore.
+ */
+function searchKeyword(
+  keyword: string,
+  scopeDir: string,
+  limit: number,
+  signal?: AbortSignal,
+  glob?: string,
+): RawMatch[] {
+  if (signal?.aborted) return [];
+
+  const rgArgs: string[] = [
+    "--no-heading",
+    "--line-number",
+    "--color",
+    "never",
+    "-F",
+    "-i",
+    "--max-count",
+    String(limit),
+  ];
+  if (glob) {
+    rgArgs.push("--glob", glob);
+  }
+  rgArgs.push("--", keyword, scopeDir);
+
+  const result = run("rg", rgArgs);
+  return parseMatches(result.stdout);
+}
+
+// ---------------------------------------------------------------------------
+// Code Chunk Extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Pattern-based function/class/interface/enum declaration detection.
+ * Covers the common patterns in TypeScript/JavaScript.
+ */
+const DECLARATION_PATTERNS = [
+  // function name(  or  export function name(  or  async function name(
+  /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s+\*?(?:\s*\w+\s*)?[<(]/,
+  // class Name  or  export default class Name  or  abstract class Name
+  /^\s*(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+\w+/,
+  // interface Name
+  /^\s*(?:export\s+)?interface\s+\w+/,
+  // type Name =
+  /^\s*(?:export\s+)?type\s+\w+\s*=/,
+  // enum Name
+  /^\s*(?:export\s+)?enum\s+\w+/,
+  // const name = (args) => {  or  const name: Type = (args) => {
+  /^\s*(?:export\s+)?(?:const|let|var)\s+\w+\s*(?::\s*\w+\s*)?=\s*(?:async\s+)?\(.*\)\s*(?::\s*\w+\s*)?=>\s*\{/,
+  // const name = function ...
+  /^\s*(?:export\s+)?(?:const|let|var)\s+\w+\s*=\s*(?:async\s+)?function\b/,
+  // get/set accessors
+  /^\s*(?:get|set)\s+\w+\s*\(/,
+];
+
+/** Check if a line contains a known declaration keyword that opens a block */
+function isDeclarationLine(line: string): boolean {
+  return DECLARATION_PATTERNS.some((p) => p.test(line));
+}
+
+/**
+ * Check if a line looks like a method declaration inside a class.
+ * e.g., `methodName(params) {` or `methodName<T>(params): Type {`
+ */
+function isMethodLine(line: string): boolean {
+  const trimmed = line.trim();
+  if (!trimmed.endsWith("{")) return false;
+  // Must match: word, optional generics, parens, optional return type, opening brace
+  if (!/^\w+\s*(?:<[^>]*>)?\s*\(/.test(trimmed)) return false;
+  // Exclude control flow keywords
+  if (/^(if|for|while|switch|catch|return|throw|import|export)\b/.test(trimmed)) return false;
+  return true;
+}
+
+/** Count occurrences of a character in a string */
+function countChar(s: string, ch: string): number {
+  let count = 0;
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === ch) count++;
+  }
+  return count;
+}
+
+/**
+ * Find the closing brace for a block starting at `startIdx`.
+ * Returns the index of the line containing the matching closing brace.
+ */
+function findBlockEnd(lines: string[], startIdx: number): number {
+  let depth = 0;
+  let started = false;
+  let inBlockComment = false;
+
+  for (let i = startIdx; i < lines.length; i++) {
+    let line = lines[i];
+
+    // Skip lines entirely inside a /* */ block comment
+    if (inBlockComment) {
+      const endIdx = line.indexOf("*/");
+      if (endIdx !== -1) {
+        inBlockComment = false;
+        line = line.slice(endIdx + 2);
+      } else {
+        continue;
+      }
+    }
+
+    // Remove string literals before counting braces in them
+    line = line
+      .replace(/"(?:[^"\\]|\\.)*"/g, "") // double-quoted strings
+      .replace(/'(?:[^'\\]|\\.)*'/g, "") // single-quoted strings
+      .replace(/`(?:[^`\\]|\\.)*`/g, ""); // template literals
+
+    // Remove //-style single-line comments
+    line = line.replace(/\/\/.*$/, "");
+
+    // Handle /* */ block comments that start and end on the same line
+    line = line.replace(/\/\*.*?\*\//g, "");
+
+    // Handle /* that opened on this line and spans forward
+    const blockStartIdx = line.indexOf("/*");
+    if (blockStartIdx !== -1) {
+      inBlockComment = true;
+      line = line.slice(0, blockStartIdx);
+    }
+
+    const opens = countChar(line, "{");
+    const closes = countChar(line, "}");
+    if (opens > 0 || closes > 0) started = true;
+    depth += opens - closes;
+    if (started && depth === 0) return i;
+  }
+  return lines.length - 1;
+}
+
+/**
+ * For a match at `targetLine` (1-based), find the enclosing function/class
+ * declaration and extract it as a chunk. Returns null if no enclosing
+ * declaration is found (e.g., the match is in file-level code).
+ */
+function extractEnclosingChunk(
+  fileLines: string[],
+  targetLine: number,
+): { startLine: number; endLine: number; text: string } | null {
+  const targetIdx = targetLine - 1; // convert to 0-based
+
+  // Scan upward from target to find enclosing declaration
+  for (let i = targetIdx; i >= 0; i--) {
+    const line = fileLines[i];
+
+    // If we hit a closing brace at start of line, we crossed a
+    // function boundary going upward. Stop — the match is not inside
+    // a function body we can cleanly extract.
+    const trimmedStart = line.trimStart();
+    if (trimmedStart.startsWith("}") && i < targetIdx) {
+      break;
+    }
+
+    if (isDeclarationLine(line) || isMethodLine(line)) {
+      // Check if this line opens a block — the opening brace may be on
+      // the same line (e.g., `function foo() {`) or a subsequent line
+      // (e.g., `function foo(\n  ...\n): Result {`).
+      let braceBalance = 0;
+      for (let j = i; j < fileLines.length; j++) {
+        braceBalance += countChar(fileLines[j], "{") - countChar(fileLines[j], "}");
+        if (braceBalance > 0) break;
+        if (j - i > 20) break; // safety limit
+      }
+      const hasArrow = line.includes("=>");
+
+      if (braceBalance > 0 || hasArrow) {
+        const endLine = findBlockEnd(fileLines, i);
+        const text = fileLines.slice(i, endLine + 1).join("\n");
+        return { startLine: i + 1, endLine: endLine + 1, text };
+      }
+    }
+  }
+
+  // Also try if the match line itself is a declaration
+  const line = fileLines[targetIdx];
+  if (isDeclarationLine(line) || isMethodLine(line)) {
+    let braceBalance = 0;
+    for (let j = targetIdx; j < fileLines.length; j++) {
+      braceBalance += countChar(fileLines[j], "{") - countChar(fileLines[j], "}");
+      if (braceBalance > 0) break;
+      if (j - targetIdx > 20) break;
+    }
+    const hasArrow = line.includes("=>");
+
+    if (braceBalance > 0 || hasArrow) {
+      const endLine = findBlockEnd(fileLines, targetIdx);
+      const text = fileLines.slice(targetIdx, endLine + 1).join("\n");
+      return { startLine: targetIdx + 1, endLine: endLine + 1, text };
+    }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// BM25 Ranking
+// ---------------------------------------------------------------------------
+
+const BM25_K1 = 1.5;
+const BM25_B = 0.75;
+
+/**
+ * Compute BM25 score for a single chunk.
+ *
+ * @param chunkText - the text of the code chunk
+ * @param keywords - all search keywords
+ * @param keywordFreqInChunk - map of keyword → frequency in this chunk
+ * @param keywordDocCount - map of keyword → number of chunks containing it
+ * @param totalChunks - total number of candidate chunks
+ * @param avgChunkLen - average chunk length in words
+ */
+function bm25Score(
+  chunkText: string,
+  keywords: string[],
+  keywordFreqInChunk: Map<string, number>,
+  keywordDocCount: Map<string, number>,
+  totalChunks: number,
+  avgChunkLen: number,
+): number {
+  const docLen = chunkText.split(/\s+/).length;
+  let score = 0;
+
+  for (const kw of keywords) {
+    const tf = keywordFreqInChunk.get(kw) ?? 0;
+    if (tf === 0) continue;
+
+    const df = keywordDocCount.get(kw) ?? 1;
+    const idf = Math.log((totalChunks - df + 0.5) / (df + 0.5) + 1);
+
+    score +=
+      idf *
+      ((tf * (BM25_K1 + 1)) / (tf + BM25_K1 * (1 - BM25_B + BM25_B * (docLen / avgChunkLen))));
+  }
+
+  return score;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+
+export const CsearchPlugin: Plugin = async () => {
+  return {
+    tool: {
+      csearch: tool({
+        description: `Search codebase by multiple keywords and return ranked function-level code chunks.
+
+Like ripgrep, this respects .gitignore — node_modules, dist/, and other ignored directories are automatically excluded.
+
+How it works:
+  - Provide specific search keywords separated by spaces
+  - Each keyword is searched independently via ripgrep
+  - Results are grouped into function/class-level code chunks
+  - Chunks are ranked by BM25 relevance (best match first)
+
+Key differences from grep:
+  - grep: exact pattern match, returns single lines → use when you know the symbol name
+  - csearch: multi-keyword, returns complete function bodies → use for discovery
+
+Best practices:
+  - Instead of "how is auth handled", provide: "auth token login session middleware"
+  - Instead of "db queries", provide: "database query insert select connection pool"
+  - Include synonyms: "user authentication" → "user auth login token session"
+
+Returns chunks with file paths, line ranges, and complete source code.`,
+        args: {
+          query: tool.schema
+            .string()
+            .describe(
+              "Space-separated search keywords. Be specific: 'auth token login jwt' not 'security stuff'. Include synonyms where relevant.",
+            ),
+          scope: tool.schema
+            .string()
+            .optional()
+            .describe(
+              "Subdirectory to search within (e.g., 'src/', 'packages/') — defaults to project root",
+            ),
+          glob: tool.schema
+            .string()
+            .optional()
+            .describe("Optional glob pattern to filter file types, e.g. '*.ts' or '**/*.test.ts'."),
+          max_results: tool.schema
+            .number()
+            .optional()
+            .describe("Maximum chunks to return (default: 15, max: 30)"),
+        },
+        execute: async (args, context) => {
+          const query = String(args.query ?? "").trim();
+          if (!query) return "query is required.";
+
+          const scopeArg = args.scope ? String(args.scope).trim() : "";
+          const scopeDir = scopeArg ? path.resolve(context.directory, scopeArg) : context.directory;
+          const maxResults = Math.min(args.max_results ?? 15, 30);
+          const glob = args.glob ? String(args.glob).trim() : undefined;
+          const signal = context.abort;
+
+          if (!existsSync(scopeDir)) {
+            return `Scope directory not found: ${scopeArg || "."}`;
+          }
+
+          // Ensure ripgrep is available
+          try {
+            execFileSync("rg", ["--version"], {
+              encoding: "utf-8" as const,
+              timeout: 2000,
+              stdio: "ignore",
+            });
+          } catch {
+            return (
+              `ripgrep (rg) is required but not found — install it with:\n` +
+              `  brew install rg\n\n` +
+              `rg powers the built-in grep and glob tools too; it's part of OpenCode's standard toolchain.`
+            );
+          }
+
+          // 1. Expand query into individual keywords
+          const keywords = expandQuery(query);
+
+          if (keywords.length === 0) {
+            return `No search keywords extracted from: "${query}"`;
+          }
+
+          // 2. Search each keyword via ripgrep
+          const perKeywordLimit = Math.ceil(maxResults * 3); // generous per-keyword cap
+          const rawMatches: RawMatch[] = [];
+          const matchKeywordMap = new Map<string, string[]>(); // "file:line" → keywords
+          let abortedEarly = false;
+
+          for (const keyword of keywords) {
+            if (signal?.aborted) {
+              abortedEarly = true;
+              break;
+            }
+
+            const matches = searchKeyword(keyword, scopeDir, perKeywordLimit, signal, glob);
+
+            for (const m of matches) {
+              const key = `${m.file}:${m.line}`;
+              const existing = matchKeywordMap.get(key);
+              if (existing) {
+                if (!existing.includes(keyword)) existing.push(keyword);
+              } else {
+                matchKeywordMap.set(key, [keyword]);
+                rawMatches.push(m);
+              }
+            }
+          }
+
+          if (rawMatches.length === 0) {
+            const prefix = abortedEarly ? "Search was cancelled before completing.\n" : "";
+            return (
+              prefix +
+              `No results found for keywords: ${keywords.join(", ")}\n\n` +
+              `Tips:\n` +
+              `  - Use broader terms\n` +
+              `  - Use grep(pattern: "...") with exact symbol names if you know them\n` +
+              `  - Check if the scope is correct (current: ${scopeArg || "project root"})`
+            );
+          }
+
+          // 3. Group matches by file
+          const fileMatches = new Map<string, RawMatch[]>();
+          for (const m of rawMatches) {
+            const existing = fileMatches.get(m.file);
+            if (existing) existing.push(m);
+            else fileMatches.set(m.file, [m]);
+          }
+
+          // 4. Extract code chunks from each matched file
+          const chunks: CodeChunk[] = [];
+          const keywordDocCount = new Map<string, number>(); // keyword → chunks containing it
+
+          for (const [filePath, matches] of fileMatches) {
+            const absPath = path.resolve(context.directory, filePath);
+            let fileLines: string[];
+            try {
+              const content = readFileSync(absPath, "utf-8");
+              fileLines = content.split("\n");
+            } catch {
+              // Skip files we can't read
+              continue;
+            }
+
+            // Sort matches by line number for stable processing
+            matches.sort((a, b) => a.line - b.line);
+
+            // Track which lines we've already assigned to a chunk
+            const assignedLines = new Set<number>();
+
+            for (const m of matches) {
+              if (assignedLines.has(m.line)) continue;
+
+              const chunk = extractEnclosingChunk(fileLines, m.line);
+
+              if (chunk) {
+                // Check if this chunk overlaps with an already-found chunk
+                const overlaps = chunks.some(
+                  (c) => c.file === filePath && c.startLine === chunk.startLine,
+                );
+                if (overlaps) {
+                  assignedLines.add(m.line);
+                  continue;
+                }
+
+                const matchedKeywords = matchKeywordMap.get(`${filePath}:${m.line}`) ?? [];
+
+                // Collect all matched keywords for this chunk
+                const chunkKeywords = new Set(matchedKeywords);
+                for (const other of matches) {
+                  if (other.line === m.line) continue;
+                  if (other.line >= chunk.startLine && other.line <= chunk.endLine) {
+                    const otherKws = matchKeywordMap.get(`${filePath}:${other.line}`) ?? [];
+                    for (const kw of otherKws) chunkKeywords.add(kw);
+                    assignedLines.add(other.line);
+                  }
+                }
+
+                const kwArr = Array.from(chunkKeywords);
+                const relPath = path.relative(context.directory, filePath);
+
+                // Count which chunks contain each keyword (for IDF)
+                for (const kw of kwArr) {
+                  keywordDocCount.set(kw, (keywordDocCount.get(kw) ?? 0) + 1);
+                }
+
+                chunks.push({
+                  file: filePath,
+                  relPath,
+                  startLine: chunk.startLine,
+                  endLine: chunk.endLine,
+                  text: chunk.text,
+                  matchedKeywords: kwArr,
+                  score: 0, // computed below
+                });
+
+                assignedLines.add(m.line);
+              } else {
+                // No enclosing function found — create a minimal chunk from context lines
+                const relPath = path.relative(context.directory, filePath);
+                const matchedKeywords = matchKeywordMap.get(`${filePath}:${m.line}`) ?? [];
+                const contextStart = Math.max(0, m.line - 4);
+                const contextEnd = Math.min(fileLines.length, m.line + 3);
+                const contextText = fileLines.slice(contextStart, contextEnd).join("\n");
+
+                for (const kw of matchedKeywords) {
+                  keywordDocCount.set(kw, (keywordDocCount.get(kw) ?? 0) + 1);
+                }
+
+                chunks.push({
+                  file: filePath,
+                  relPath,
+                  startLine: contextStart + 1,
+                  endLine: contextEnd,
+                  text: contextText,
+                  matchedKeywords,
+                  score: 0,
+                });
+
+                assignedLines.add(m.line);
+              }
+            }
+          }
+
+          if (chunks.length === 0) {
+            return "No code chunks could be extracted from the matched files.";
+          }
+
+          // 5. BM25 score all chunks
+          const totalChunks = chunks.length;
+          const avgChunkLen =
+            chunks.reduce((sum, c) => sum + c.text.split(/\s+/).length, 0) / totalChunks;
+
+          for (const chunk of chunks) {
+            // Count keyword frequency IN this chunk
+            const kwFreq = new Map<string, number>();
+            const lowerChunk = chunk.text.toLowerCase();
+            for (const kw of chunk.matchedKeywords) {
+              // Count occurrences of the keyword as a word boundary match
+              const escaped = kw.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+              const regex = new RegExp(`\\b${escaped}\\b`, "gi");
+              const matches_arr = lowerChunk.match(regex);
+              const count = matches_arr ? matches_arr.length : 0;
+              kwFreq.set(kw, count);
+            }
+
+            chunk.score = bm25Score(
+              chunk.text,
+              keywords,
+              kwFreq,
+              keywordDocCount,
+              totalChunks,
+              avgChunkLen,
+            );
+          }
+
+          // 6. Sort by BM25 score descending
+          chunks.sort((a, b) => b.score - a.score);
+
+          // 7. Return top-N chunks
+          const topChunks = chunks.slice(0, maxResults);
+
+          const output: string[] = [
+            `# Csearch: ${query}`,
+            `Keywords: ${keywords.join(", ")}`,
+            `Found ${plural(chunks.length, "chunk")} across ${plural(fileMatches.size, "file")}`,
+            `Showing top ${topChunks.length} ${abortedEarly ? "(partial — search cancelled) " : ""}`,
+            "",
+          ];
+
+          // Group by file
+          const fileGroups = new Map<string, CodeChunk[]>();
+          for (const chunk of topChunks) {
+            const existing = fileGroups.get(chunk.relPath);
+            if (existing) existing.push(chunk);
+            else fileGroups.set(chunk.relPath, [chunk]);
+          }
+
+          for (const [filePath, fileChunks] of fileGroups) {
+            output.push(`## ${filePath} — ${plural(fileChunks.length, "chunk")}`);
+            output.push("");
+
+            for (const chunk of fileChunks) {
+              const name = guessChunkName(chunk.text, chunk.startLine);
+              output.push(
+                `### ${name} (L${chunk.startLine}-L${chunk.endLine}) — score: ${chunk.score.toFixed(1)}, keywords: [${chunk.matchedKeywords.join(", ")}]`,
+              );
+              output.push("```typescript");
+              output.push(chunk.text);
+              output.push("```");
+              output.push("");
+            }
+          }
+
+          output.push(
+            `> Next: drill into a chunk with srcwalk_read({ path: "${topChunks[0]?.relPath ?? "file.ts"}:${topChunks[0]?.startLine ?? 1}" })`,
+          );
+          output.push(`> Next: search exact symbol names with grep({ pattern: "symbolName" })`);
+
+          return output.join("\n");
+        },
+      }),
+    },
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Formatting Helpers
+// ---------------------------------------------------------------------------
+
+function plural(n: number, word: string): string {
+  if (n === 1) return `${n} ${word}`;
+  if (
+    word.endsWith("ch") ||
+    word.endsWith("s") ||
+    word.endsWith("sh") ||
+    word.endsWith("x") ||
+    word.endsWith("z")
+  ) {
+    return `${n} ${word}es`;
+  }
+  if (
+    word.endsWith("y") &&
+    word.length > 1 &&
+    !["a", "e", "i", "o", "u"].includes(word[word.length - 2])
+  ) {
+    return `${n} ${word.slice(0, -1)}ies`;
+  }
+  return `${n} ${word}s`;
+}
+
+/**
+ * Guess the name of a code chunk from its first lines.
+ * Used to label chunks in the output.
+ */
+function guessChunkName(text: string, startLine: number): string {
+  const firstLine = text.split("\n")[0]?.trim() ?? "";
+  // Extract name from: function name( ... export function name( ... class name
+  const fnMatch = firstLine.match(/(?:function|class|interface|type|enum)\s+(\w+)/);
+  if (fnMatch) return fnMatch[1]!;
+
+  // Extract from: const name = ( ... export const name = ( ...
+  const constMatch = firstLine.match(/(?:export\s+)?(?:const|let|var)\s+(\w+)/);
+  if (constMatch) return constMatch[1]!;
+
+  // Method or getter/setter
+  const methodMatch = firstLine.match(/^\s*(get|set)\s+(\w+)/);
+  if (methodMatch) return `${methodMatch[1]!} ${methodMatch[2]!}`;
+
+  const methodName = firstLine.match(/^\s*(\w+)\s*\(/);
+  if (methodName) return methodName[1]!;
+
+  return `chunk at L${startLine}`;
+}
+
+export default CsearchPlugin;