bonecode 1.0.0 → 1.2.0

package/bone/output/rag/src/extensions.ts

@@ -1,350 +1,350 @@
-// Generated by BoneScript compiler.
-// Extension points: implement the functions below.
-// Code between sentinel comments is preserved on recompile.
-// DO NOT remove the sentinel comments.
-
-import * as fs from "fs";
-import * as path from "path";
-import * as crypto from "crypto";
-import { pool } from "./db";
-import { logger } from "./logger";
-import { counter } from "./metrics";
-import { v4 as uuid } from "uuid";
-
-// ─── Shared fetch helper (uses env-configured embedding endpoint) ─────────────
-
-async function embeddingFetch(body: object): Promise<Response> {
-  const baseUrl = process.env.EMBEDDING_BASE_URL || process.env.OPENAI_BASE_URL || "https://api.openai.com/v1";
-  const apiKey = process.env.EMBEDDING_API_KEY || process.env.OPENAI_API_KEY || "not-needed";
-  return fetch(`${baseUrl}/embeddings`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
-    body: JSON.stringify(body),
-  });
-}
-
-/**
- * Extension point: embed_text
- * STABLE: implementation required.
- */
-export async function embed_text(text: string, model: string): Promise<number[]> {
-  // <bonescript:ext:embed_text:begin>
-  const effectiveModel = model || process.env.EMBEDDING_MODEL || "text-embedding-nomic-embed-text-v1.5";
-  const r = await embeddingFetch({ model: effectiveModel, input: text });
-  if (!r.ok) throw new Error(`Embedding API error ${r.status}: ${await r.text()}`);
-  const data = await r.json() as any;
-  counter("rag.embed.single", { model: effectiveModel });
-  return data.data[0].embedding as number[];
-  // <bonescript:ext:embed_text:end>
-}
-
-/**
- * Extension point: embed_batch
- * STABLE: implementation required.
- */
-export async function embed_batch(texts: string[], model: string): Promise<number[][]> {
-  // <bonescript:ext:embed_batch:begin>
-  if (texts.length === 0) return [];
-  const effectiveModel = model || process.env.EMBEDDING_MODEL || "text-embedding-nomic-embed-text-v1.5";
-  const BATCH = 100;
-  const results: number[][] = [];
-  for (let i = 0; i < texts.length; i += BATCH) {
-    const batch = texts.slice(i, i + BATCH);
-    const r = await embeddingFetch({ model: effectiveModel, input: batch });
-    if (!r.ok) throw new Error(`Embedding batch API error ${r.status}: ${await r.text()}`);
-    const data = await r.json() as any;
-    const sorted = (data.data as any[]).sort((a, b) => a.index - b.index);
-    results.push(...sorted.map((d: any) => d.embedding as number[]));
-    counter("rag.embed.batch", { model: effectiveModel, count: String(batch.length) });
-  }
-  return results;
-  // <bonescript:ext:embed_batch:end>
-}
-
-/**
- * Extension point: chunk_file
- * STABLE: implementation required.
- */
-export function chunk_file(
-  file_path: string,
-  content: string,
-  strategy: string,
-  chunk_size: number,
-  overlap: number
-): Array<{ content: string; start_line: number; end_line: number; chunk_index: number; language?: string; symbol_name?: string; symbol_type?: string }> {
-  // <bonescript:ext:chunk_file:begin>
-  const language = detect_language(file_path);
-  const lines = content.split("\n");
-  const linesPerChunk = Math.max(10, Math.floor(chunk_size / 80));
-  const overlapLines = Math.max(0, Math.floor(overlap / 80));
-  const chunks: ReturnType<typeof chunk_file> = [];
-  let chunkIndex = 0;
-
-  // AST-aware: detect symbol boundaries for TS/JS/Python/Go
-  const symbolPatterns: Record<string, RegExp[]> = {
-    typescript: [/^(export\s+)?(async\s+)?function\s+(\w+)/, /^(export\s+)?(abstract\s+)?class\s+(\w+)/, /^(export\s+)?interface\s+(\w+)/, /^(export\s+)?const\s+(\w+)\s*=/],
-    javascript: [/^(export\s+)?(async\s+)?function\s+(\w+)/, /^(export\s+)?class\s+(\w+)/, /^(export\s+)?const\s+(\w+)\s*=/],
-    python: [/^(async\s+)?def\s+(\w+)/, /^class\s+(\w+)/],
-    go: [/^func\s+(\w+)/, /^type\s+(\w+)\s+struct/],
-  };
-
-  const patterns = strategy === "ast" ? (symbolPatterns[language] || []) : [];
-  let currentStart = 0;
-  let currentLines: string[] = [];
-  let currentSymbol: { name: string; type: string } | null = null;
-
-  const flush = () => {
-    const text = currentLines.join("\n").trim();
-    if (text.length > 0) {
-      chunks.push({
-        content: currentLines.join("\n"),
-        start_line: currentStart + 1,
-        end_line: currentStart + currentLines.length,
-        chunk_index: chunkIndex++,
-        language,
-        symbol_name: currentSymbol?.name,
-        symbol_type: currentSymbol?.type,
-      });
-    }
-  };
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    let isSymbolBoundary = false;
-    let symbolName = "";
-    let symbolType = "block";
-
-    for (const pat of patterns) {
-      const m = line.match(pat);
-      if (m) {
-        isSymbolBoundary = true;
-        symbolName = m[m.length - 1] || "";
-        symbolType = /function|def|func/.test(line) ? "function" : /class/.test(line) ? "class" : /interface/.test(line) ? "interface" : "variable";
-        break;
-      }
-    }
-
-    if (isSymbolBoundary && currentLines.length > 0) {
-      flush();
-      const overlapStart = Math.max(0, i - overlapLines);
-      currentStart = overlapStart;
-      currentLines = lines.slice(overlapStart, i);
-      currentSymbol = { name: symbolName, type: symbolType };
-    }
-
-    currentLines.push(line);
-
-    // Also split on size overflow
-    if (currentLines.join("\n").length > chunk_size && currentLines.length > 10) {
-      flush();
-      const overlapStart = Math.max(0, currentStart + currentLines.length - overlapLines);
-      currentStart = overlapStart;
-      currentLines = lines.slice(overlapStart, i + 1);
-      currentSymbol = null;
-    }
-  }
-
-  flush();
-
-  // Fallback: if no chunks produced, use line-based sliding window
-  if (chunks.length === 0) {
-    for (let i = 0; i < lines.length; i += linesPerChunk - overlapLines) {
-      const end = Math.min(i + linesPerChunk, lines.length);
-      const text = lines.slice(i, end).join("\n").trim();
-      if (text.length > 0) {
-        chunks.push({ content: lines.slice(i, end).join("\n"), start_line: i + 1, end_line: end, chunk_index: chunkIndex++, language });
-      }
-      if (end >= lines.length) break;
-    }
-  }
-
-  return chunks;
-  // <bonescript:ext:chunk_file:end>
-}
-
-/**
- * Extension point: hybrid_search
- * STABLE: implementation required.
- */
-export async function hybrid_search(
-  knowledge_base_id: string,
-  query_embedding: number[],
-  query_text: string,
-  filters: { language?: string; symbol_type?: string; file_path_pattern?: string },
-  limit: number
-): Promise<Array<{ chunk_id: string; file_path: string; content: string; start_line: number; end_line: number; language?: string; symbol_name?: string; symbol_type?: string; score: number }>> {
-  // <bonescript:ext:hybrid_search:begin>
-  const embStr = "[" + query_embedding.join(",") + "]";
-  const result = await pool.query(
-    "SELECT * FROM bonecode_hybrid_search($1, $2::vector, $3, $4, $5, $6)",
-    [knowledge_base_id, embStr, query_text, filters?.language || null, filters?.symbol_type || null, limit]
-  );
-  counter("rag.search.hybrid", { knowledge_base_id, results: String(result.rows.length) });
-  return result.rows.map((row: any) => ({
-    chunk_id: row.chunk_id,
-    file_path: row.file_path,
-    content: row.content,
-    start_line: Number(row.start_line),
-    end_line: Number(row.end_line),
-    language: row.language,
-    symbol_name: row.symbol_name,
-    symbol_type: row.symbol_type,
-    score: row.rrf_score,
-    vector_score: row.vector_score,
-    text_score: row.text_score,
-  }));
-  // <bonescript:ext:hybrid_search:end>
-}
-
-/**
- * Extension point: scan_directory
- * STABLE: implementation required.
- */
-export function scan_directory(
-  root_path: string,
-  ignore_patterns: string[]
-): string[] {
-  // <bonescript:ext:scan_directory:begin>
-  const DEFAULT_IGNORE = [
-    "node_modules", ".git", "dist", "build", ".next", "__pycache__",
-    ".venv", "venv", "target", "vendor", ".cache", "coverage",
-    ...(ignore_patterns || []),
-  ];
-  const SUPPORTED_EXTS = new Set([
-    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
-    ".py", ".go", ".rs", ".java", ".kt", ".cs", ".cpp", ".c", ".h",
-    ".rb", ".php", ".swift", ".scala", ".r", ".sql",
-    ".md", ".mdx", ".json", ".yaml", ".yml", ".toml",
-    ".graphql", ".gql", ".proto",
-  ]);
-  const MAX_FILE_SIZE = 500 * 1024; // 500KB
-
-  const results: string[] = [];
-
-  function walk(dir: string) {
-    let entries: fs.Dirent[];
-    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
-    catch { return; }
-
-    for (const entry of entries) {
-      if (DEFAULT_IGNORE.some(ig => entry.name === ig || entry.name.startsWith("."))) continue;
-      const fullPath = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        walk(fullPath);
-      } else if (entry.isFile()) {
-        const ext = path.extname(entry.name).toLowerCase();
-        if (!SUPPORTED_EXTS.has(ext)) continue;
-        try {
-          const stat = fs.statSync(fullPath);
-          if (stat.size > MAX_FILE_SIZE) continue;
-          results.push(fullPath);
-        } catch { continue; }
-      }
-    }
-  }
-
-  walk(root_path);
-  return results;
-  // <bonescript:ext:scan_directory:end>
-}
-
-/**
- * Extension point: detect_language
- * Optional.
- */
-export function detect_language(file_path: string): string {
-  // <bonescript:ext:detect_language:begin>
-  const ext = path.extname(file_path).toLowerCase();
-  const base = path.basename(file_path).toLowerCase();
-  if (base === "dockerfile") return "dockerfile";
-  if (base === "makefile") return "makefile";
-  const map: Record<string, string> = {
-    ".ts": "typescript", ".tsx": "typescript",
-    ".js": "javascript", ".jsx": "javascript", ".mjs": "javascript", ".cjs": "javascript",
-    ".py": "python", ".go": "go", ".rs": "rust", ".java": "java",
-    ".kt": "kotlin", ".cs": "csharp", ".cpp": "cpp", ".c": "c", ".h": "cpp",
-    ".rb": "ruby", ".php": "php", ".swift": "swift", ".scala": "scala",
-    ".sql": "sql", ".sh": "bash", ".bash": "bash",
-    ".md": "markdown", ".mdx": "markdown",
-    ".json": "json", ".yaml": "yaml", ".yml": "yaml", ".toml": "toml",
-    ".graphql": "graphql", ".gql": "graphql", ".proto": "protobuf",
-  };
-  return map[ext] || "text";
-  // <bonescript:ext:detect_language:end>
-}
-
-/**
- * Extension point: bulk_insert_chunks
- * STABLE: implementation required.
- * Inserts all chunks for a file in a single parameterized query.
- * Returns the number of chunks inserted.
- */
-export async function bulk_insert_chunks(chunks: Array<{
-  id: string;
-  code_file_id: string;
-  knowledge_base_id: string;
-  project_id: string;
-  content: string;
-  start_line: number;
-  end_line: number;
-  chunk_index: number;
-  language: string;
-  symbol_name?: string;
-  symbol_type?: string;
-  embedding?: number[];
-}>): Promise<number> {
-  // <bonescript:ext:bulk_insert_chunks:begin>
-  if (chunks.length === 0) return 0;
-
-  // Build a single multi-row INSERT for all chunks
-  const values: unknown[] = [];
-  const placeholders = chunks.map((c, i) => {
-    const base = i * 12;
-    const embStr = c.embedding ? "[" + c.embedding.join(",") + "]" : null;
-    values.push(
-      c.id, c.code_file_id, c.knowledge_base_id, c.project_id,
-      c.content, c.start_line, c.end_line, c.chunk_index,
-      c.language, c.symbol_name || null, c.symbol_type || null, embStr
-    );
-    return `($${base+1},$${base+2},$${base+3},$${base+4},$${base+5},$${base+6},$${base+7},$${base+8},$${base+9},$${base+10},$${base+11},$${base+12}::vector)`;
-  });
-
-  await pool.query(
-    `INSERT INTO code_chunks
-       (id, code_file_id, knowledge_base_id, project_id, content, start_line, end_line,
-        chunk_index, language, symbol_name, symbol_type, embedding)
-     VALUES ${placeholders.join(",")}
-     ON CONFLICT DO NOTHING`,
-    values
-  );
-
-  counter("rag.chunks.inserted", { count: String(chunks.length) });
-  return chunks.length;
-  // <bonescript:ext:bulk_insert_chunks:end>
-}
-
-/**
- * Extension point: read_file_async
- * STABLE: implementation required.
- * Reads a file and returns its content, hash, size, and mtime.
- */
-export async function read_file_async(file_path: string): Promise<{
-  content: string;
-  hash: string;
-  size: number;
-  mtime: string;
-} | null> {
-  // <bonescript:ext:read_file_async:begin>
-  const fsPromises = require("fs/promises");
-  try {
-    const [content, stat] = await Promise.all([
-      fsPromises.readFile(file_path, "utf-8"),
-      fsPromises.stat(file_path),
-    ]);
-    const hash = require("crypto").createHash("sha256").update(content).digest("hex");
-    return { content, hash, size: stat.size, mtime: new Date(stat.mtimeMs).toISOString() };
-  } catch {
-    return null; // File unreadable — skip
-  }
-  // <bonescript:ext:read_file_async:end>
-}
+// Generated by BoneScript compiler.
+// Extension points: implement the functions below.
+// Code between sentinel comments is preserved on recompile.
+// DO NOT remove the sentinel comments.
+
+import * as fs from "fs";
+import * as path from "path";
+import * as crypto from "crypto";
+import { pool } from "./db";
+import { logger } from "./logger";
+import { counter } from "./metrics";
+import { v4 as uuid } from "uuid";
+
+// ─── Shared fetch helper (uses env-configured embedding endpoint) ─────────────
+
+async function embeddingFetch(body: object): Promise<Response> {
+  const baseUrl = process.env.EMBEDDING_BASE_URL || process.env.OPENAI_BASE_URL || "https://api.openai.com/v1";
+  const apiKey = process.env.EMBEDDING_API_KEY || process.env.OPENAI_API_KEY || "not-needed";
+  return fetch(`${baseUrl}/embeddings`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+    body: JSON.stringify(body),
+  });
+}
+
+/**
+ * Extension point: embed_text
+ * STABLE: implementation required.
+ */
+export async function embed_text(text: string, model: string): Promise<number[]> {
+  // <bonescript:ext:embed_text:begin>
+  const effectiveModel = model || process.env.EMBEDDING_MODEL || "text-embedding-nomic-embed-text-v1.5";
+  const r = await embeddingFetch({ model: effectiveModel, input: text });
+  if (!r.ok) throw new Error(`Embedding API error ${r.status}: ${await r.text()}`);
+  const data = await r.json() as any;
+  counter("rag.embed.single", { model: effectiveModel });
+  return data.data[0].embedding as number[];
+  // <bonescript:ext:embed_text:end>
+}
+
+/**
+ * Extension point: embed_batch
+ * STABLE: implementation required.
+ */
+export async function embed_batch(texts: string[], model: string): Promise<number[][]> {
+  // <bonescript:ext:embed_batch:begin>
+  if (texts.length === 0) return [];
+  const effectiveModel = model || process.env.EMBEDDING_MODEL || "text-embedding-nomic-embed-text-v1.5";
+  const BATCH = 100;
+  const results: number[][] = [];
+  for (let i = 0; i < texts.length; i += BATCH) {
+    const batch = texts.slice(i, i + BATCH);
+    const r = await embeddingFetch({ model: effectiveModel, input: batch });
+    if (!r.ok) throw new Error(`Embedding batch API error ${r.status}: ${await r.text()}`);
+    const data = await r.json() as any;
+    const sorted = (data.data as any[]).sort((a, b) => a.index - b.index);
+    results.push(...sorted.map((d: any) => d.embedding as number[]));
+    counter("rag.embed.batch", { model: effectiveModel, count: String(batch.length) });
+  }
+  return results;
+  // <bonescript:ext:embed_batch:end>
+}
+
+/**
+ * Extension point: chunk_file
+ * STABLE: implementation required.
+ */
+export function chunk_file(
+  file_path: string,
+  content: string,
+  strategy: string,
+  chunk_size: number,
+  overlap: number
+): Array<{ content: string; start_line: number; end_line: number; chunk_index: number; language?: string; symbol_name?: string; symbol_type?: string }> {
+  // <bonescript:ext:chunk_file:begin>
+  const language = detect_language(file_path);
+  const lines = content.split("\n");
+  const linesPerChunk = Math.max(10, Math.floor(chunk_size / 80));
+  const overlapLines = Math.max(0, Math.floor(overlap / 80));
+  const chunks: ReturnType<typeof chunk_file> = [];
+  let chunkIndex = 0;
+
+  // AST-aware: detect symbol boundaries for TS/JS/Python/Go
+  const symbolPatterns: Record<string, RegExp[]> = {
+    typescript: [/^(export\s+)?(async\s+)?function\s+(\w+)/, /^(export\s+)?(abstract\s+)?class\s+(\w+)/, /^(export\s+)?interface\s+(\w+)/, /^(export\s+)?const\s+(\w+)\s*=/],
+    javascript: [/^(export\s+)?(async\s+)?function\s+(\w+)/, /^(export\s+)?class\s+(\w+)/, /^(export\s+)?const\s+(\w+)\s*=/],
+    python: [/^(async\s+)?def\s+(\w+)/, /^class\s+(\w+)/],
+    go: [/^func\s+(\w+)/, /^type\s+(\w+)\s+struct/],
+  };
+
+  const patterns = strategy === "ast" ? (symbolPatterns[language] || []) : [];
+  let currentStart = 0;
+  let currentLines: string[] = [];
+  let currentSymbol: { name: string; type: string } | null = null;
+
+  const flush = () => {
+    const text = currentLines.join("\n").trim();
+    if (text.length > 0) {
+      chunks.push({
+        content: currentLines.join("\n"),
+        start_line: currentStart + 1,
+        end_line: currentStart + currentLines.length,
+        chunk_index: chunkIndex++,
+        language,
+        symbol_name: currentSymbol?.name,
+        symbol_type: currentSymbol?.type,
+      });
+    }
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    let isSymbolBoundary = false;
+    let symbolName = "";
+    let symbolType = "block";
+
+    for (const pat of patterns) {
+      const m = line.match(pat);
+      if (m) {
+        isSymbolBoundary = true;
+        symbolName = m[m.length - 1] || "";
+        symbolType = /function|def|func/.test(line) ? "function" : /class/.test(line) ? "class" : /interface/.test(line) ? "interface" : "variable";
+        break;
+      }
+    }
+
+    if (isSymbolBoundary && currentLines.length > 0) {
+      flush();
+      const overlapStart = Math.max(0, i - overlapLines);
+      currentStart = overlapStart;
+      currentLines = lines.slice(overlapStart, i);
+      currentSymbol = { name: symbolName, type: symbolType };
+    }
+
+    currentLines.push(line);
+
+    // Also split on size overflow
+    if (currentLines.join("\n").length > chunk_size && currentLines.length > 10) {
+      flush();
+      const overlapStart = Math.max(0, currentStart + currentLines.length - overlapLines);
+      currentStart = overlapStart;
+      currentLines = lines.slice(overlapStart, i + 1);
+      currentSymbol = null;
+    }
+  }
+
+  flush();
+
+  // Fallback: if no chunks produced, use line-based sliding window
+  if (chunks.length === 0) {
+    for (let i = 0; i < lines.length; i += linesPerChunk - overlapLines) {
+      const end = Math.min(i + linesPerChunk, lines.length);
+      const text = lines.slice(i, end).join("\n").trim();
+      if (text.length > 0) {
+        chunks.push({ content: lines.slice(i, end).join("\n"), start_line: i + 1, end_line: end, chunk_index: chunkIndex++, language });
+      }
+      if (end >= lines.length) break;
+    }
+  }
+
+  return chunks;
+  // <bonescript:ext:chunk_file:end>
+}
+
+/**
+ * Extension point: hybrid_search
+ * STABLE: implementation required.
+ */
+export async function hybrid_search(
+  knowledge_base_id: string,
+  query_embedding: number[],
+  query_text: string,
+  filters: { language?: string; symbol_type?: string; file_path_pattern?: string },
+  limit: number
+): Promise<Array<{ chunk_id: string; file_path: string; content: string; start_line: number; end_line: number; language?: string; symbol_name?: string; symbol_type?: string; score: number }>> {
+  // <bonescript:ext:hybrid_search:begin>
+  const embStr = "[" + query_embedding.join(",") + "]";
+  const result = await pool.query(
+    "SELECT * FROM bonecode_hybrid_search($1, $2::vector, $3, $4, $5, $6)",
+    [knowledge_base_id, embStr, query_text, filters?.language || null, filters?.symbol_type || null, limit]
+  );
+  counter("rag.search.hybrid", { knowledge_base_id, results: String(result.rows.length) });
+  return result.rows.map((row: any) => ({
+    chunk_id: row.chunk_id,
+    file_path: row.file_path,
+    content: row.content,
+    start_line: Number(row.start_line),
+    end_line: Number(row.end_line),
+    language: row.language,
+    symbol_name: row.symbol_name,
+    symbol_type: row.symbol_type,
+    score: row.rrf_score,
+    vector_score: row.vector_score,
+    text_score: row.text_score,
+  }));
+  // <bonescript:ext:hybrid_search:end>
+}
+
+/**
+ * Extension point: scan_directory
+ * STABLE: implementation required.
+ */
+export function scan_directory(
+  root_path: string,
+  ignore_patterns: string[]
+): string[] {
+  // <bonescript:ext:scan_directory:begin>
+  const DEFAULT_IGNORE = [
+    "node_modules", ".git", "dist", "build", ".next", "__pycache__",
+    ".venv", "venv", "target", "vendor", ".cache", "coverage",
+    ...(ignore_patterns || []),
+  ];
+  const SUPPORTED_EXTS = new Set([
+    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+    ".py", ".go", ".rs", ".java", ".kt", ".cs", ".cpp", ".c", ".h",
+    ".rb", ".php", ".swift", ".scala", ".r", ".sql",
+    ".md", ".mdx", ".json", ".yaml", ".yml", ".toml",
+    ".graphql", ".gql", ".proto",
+  ]);
+  const MAX_FILE_SIZE = 500 * 1024; // 500KB
+
+  const results: string[] = [];
+
+  function walk(dir: string) {
+    let entries: fs.Dirent[];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    catch { return; }
+
+    for (const entry of entries) {
+      if (DEFAULT_IGNORE.some(ig => entry.name === ig || entry.name.startsWith("."))) continue;
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name).toLowerCase();
+        if (!SUPPORTED_EXTS.has(ext)) continue;
+        try {
+          const stat = fs.statSync(fullPath);
+          if (stat.size > MAX_FILE_SIZE) continue;
+          results.push(fullPath);
+        } catch { continue; }
+      }
+    }
+  }
+
+  walk(root_path);
+  return results;
+  // <bonescript:ext:scan_directory:end>
+}
+
+/**
+ * Extension point: detect_language
+ * Optional.
+ */
+export function detect_language(file_path: string): string {
+  // <bonescript:ext:detect_language:begin>
+  const ext = path.extname(file_path).toLowerCase();
+  const base = path.basename(file_path).toLowerCase();
+  if (base === "dockerfile") return "dockerfile";
+  if (base === "makefile") return "makefile";
+  const map: Record<string, string> = {
+    ".ts": "typescript", ".tsx": "typescript",
+    ".js": "javascript", ".jsx": "javascript", ".mjs": "javascript", ".cjs": "javascript",
+    ".py": "python", ".go": "go", ".rs": "rust", ".java": "java",
+    ".kt": "kotlin", ".cs": "csharp", ".cpp": "cpp", ".c": "c", ".h": "cpp",
+    ".rb": "ruby", ".php": "php", ".swift": "swift", ".scala": "scala",
+    ".sql": "sql", ".sh": "bash", ".bash": "bash",
+    ".md": "markdown", ".mdx": "markdown",
+    ".json": "json", ".yaml": "yaml", ".yml": "yaml", ".toml": "toml",
+    ".graphql": "graphql", ".gql": "graphql", ".proto": "protobuf",
+  };
+  return map[ext] || "text";
+  // <bonescript:ext:detect_language:end>
+}
+
+/**
+ * Extension point: bulk_insert_chunks
+ * STABLE: implementation required.
+ * Inserts all chunks for a file in a single parameterized query.
+ * Returns the number of chunks inserted.
+ */
+export async function bulk_insert_chunks(chunks: Array<{
+  id: string;
+  code_file_id: string;
+  knowledge_base_id: string;
+  project_id: string;
+  content: string;
+  start_line: number;
+  end_line: number;
+  chunk_index: number;
+  language: string;
+  symbol_name?: string;
+  symbol_type?: string;
+  embedding?: number[];
+}>): Promise<number> {
+  // <bonescript:ext:bulk_insert_chunks:begin>
+  if (chunks.length === 0) return 0;
+
+  // Build a single multi-row INSERT for all chunks
+  const values: unknown[] = [];
+  const placeholders = chunks.map((c, i) => {
+    const base = i * 12;
+    const embStr = c.embedding ? "[" + c.embedding.join(",") + "]" : null;
+    values.push(
+      c.id, c.code_file_id, c.knowledge_base_id, c.project_id,
+      c.content, c.start_line, c.end_line, c.chunk_index,
+      c.language, c.symbol_name || null, c.symbol_type || null, embStr
+    );
+    return `($${base+1},$${base+2},$${base+3},$${base+4},$${base+5},$${base+6},$${base+7},$${base+8},$${base+9},$${base+10},$${base+11},$${base+12}::vector)`;
+  });
+
+  await pool.query(
+    `INSERT INTO code_chunks
+       (id, code_file_id, knowledge_base_id, project_id, content, start_line, end_line,
+        chunk_index, language, symbol_name, symbol_type, embedding)
+     VALUES ${placeholders.join(",")}
+     ON CONFLICT DO NOTHING`,
+    values
+  );
+
+  counter("rag.chunks.inserted", { count: String(chunks.length) });
+  return chunks.length;
+  // <bonescript:ext:bulk_insert_chunks:end>
+}
+
+/**
+ * Extension point: read_file_async
+ * STABLE: implementation required.
+ * Reads a file and returns its content, hash, size, and mtime.
+ */
+export async function read_file_async(file_path: string): Promise<{
+  content: string;
+  hash: string;
+  size: number;
+  mtime: string;
+} | null> {
+  // <bonescript:ext:read_file_async:begin>
+  const fsPromises = require("fs/promises");
+  try {
+    const [content, stat] = await Promise.all([
+      fsPromises.readFile(file_path, "utf-8"),
+      fsPromises.stat(file_path),
+    ]);
+    const hash = require("crypto").createHash("sha256").update(content).digest("hex");
+    return { content, hash, size: stat.size, mtime: new Date(stat.mtimeMs).toISOString() };
+  } catch {
+    return null; // File unreadable — skip
+  }
+  // <bonescript:ext:read_file_async:end>
+}