@levnikolaevich/hex-line-mcp 1.3.1 → 1.3.3

package/lib/graph-enrich.mjs

@@ -1,30 +1,32 @@
 /**
  * Graph enrichment for hex-line tools.
  *
- * Reads .codegraph/index.db (created by hex-graph-mcp) in readonly mode.
- * Provides symbol annotations for outline, read_file, grep_search, edit_file.
+ * Reads .codegraph/index.db (created by hex-graph-mcp) in readonly mode via a
+ * small explicit compatibility contract:
+ * - hex_line_contract
+ * - hex_line_symbol_annotations
+ * - hex_line_call_edges
  *
- * Lazy singleton: DB opened once per session, reused across calls.
- * Graceful fallback: if better-sqlite3 or DB missing → returns null silently.
+ * Graceful fallback: if better-sqlite3, contract views, or DB are missing,
+ * enrichment is disabled silently for that project.
  */
 
 import { existsSync } from "node:fs";
 import { join, dirname, relative } from "node:path";
 import { createRequire } from "node:module";
 
-let _db = null;
-
-let _unavailable = false;
+const HEX_LINE_CONTRACT_VERSION = 1;
+const _dbs = new Map();
+let _driverUnavailable = false;
 
 /**
  * Get readonly graph DB for a project root.
- * Returns null if DB missing or better-sqlite3 not installed.
+ * Returns null if DB missing or contract unavailable.
  * @param {string} filePath - any file path inside the project
  * @returns {object|null} better-sqlite3 Database instance or null
  */
 export function getGraphDB(filePath) {
-    if (_unavailable) return null;
-    if (_db) return _db;
+    if (_driverUnavailable) return null;
 
     try {
         const projectRoot = findProjectRoot(filePath);
@@ -32,18 +34,46 @@ export function getGraphDB(filePath) {
 
         const dbPath = join(projectRoot, ".codegraph", "index.db");
         if (!existsSync(dbPath)) return null;
+        if (_dbs.has(dbPath)) return _dbs.get(dbPath);
 
         const require = createRequire(import.meta.url);
         const Database = require("better-sqlite3");
-        _db = new Database(dbPath, { readonly: true });
-
-        return _db;
+        const db = new Database(dbPath, { readonly: true });
+        if (!validateHexLineContract(db)) {
+            db.close();
+            return null;
+        }
+        _dbs.set(dbPath, db);
+        return db;
     } catch {
-        _unavailable = true;
+        _driverUnavailable = true;
         return null;
     }
 }
 
+/**
+ * Test helper: close cached DB handles so each test can start clean.
+ */
+export function _resetGraphDBCache() {
+    for (const db of _dbs.values()) {
+        try { db.close(); } catch { /* ignore */ }
+    }
+    _dbs.clear();
+    _driverUnavailable = false;
+}
+
+function validateHexLineContract(db) {
+    try {
+        const contract = db.prepare("SELECT contract_version FROM hex_line_contract LIMIT 1").get();
+        if (!contract || contract.contract_version !== HEX_LINE_CONTRACT_VERSION) return false;
+        db.prepare("SELECT node_id, file, line_start, line_end, display_name, kind, callees, callers FROM hex_line_symbol_annotations LIMIT 1").all();
+        db.prepare("SELECT source_id, target_id, source_file, source_line, source_display_name, target_file, target_line, target_display_name FROM hex_line_call_edges LIMIT 1").all();
+        return true;
+    } catch {
+        return false;
+    }
+}
+
 /**
  * Get [N↓ M↑] annotation for a symbol.
  * @param {object} db - better-sqlite3 instance
@@ -54,19 +84,12 @@ export function getGraphDB(filePath) {
 export function symbolAnnotation(db, file, name) {
     try {
         const node = db.prepare(
-            "SELECT id FROM nodes WHERE file = ? AND name = ? AND kind != 'import' LIMIT 1"
+            "SELECT callees, callers FROM hex_line_symbol_annotations WHERE file = ? AND name = ? LIMIT 1"
         ).get(file, name);
         if (!node) return null;
 
-        const callees = db.prepare(
-            "SELECT COUNT(*) as c FROM edges WHERE source_id = ? AND kind = 'calls'"
-        ).get(node.id).c;
-        const callers = db.prepare(
-            "SELECT COUNT(*) as c FROM edges WHERE target_id = ? AND kind = 'calls'"
-        ).get(node.id).c;
-
-        if (callees === 0 && callers === 0) return null;
-        return `[${callees}\u2193 ${callers}\u2191]`;
+        if (node.callees === 0 && node.callers === 0) return null;
+        return `[${node.callees}\u2193 ${node.callers}\u2191]`;
     } catch {
         return null;
     }
@@ -81,42 +104,39 @@ export function symbolAnnotation(db, file, name) {
 export function fileAnnotations(db, file) {
     try {
         const nodes = db.prepare(
-            "SELECT id, name, kind FROM nodes WHERE file = ? AND kind != 'import' ORDER BY line_start"
+            `SELECT display_name, kind, callees, callers
+             FROM hex_line_symbol_annotations
+             WHERE file = ?
+             ORDER BY line_start`
         ).all(file);
 
-        const result = [];
-        for (const node of nodes) {
-            const callees = db.prepare(
-                "SELECT COUNT(*) as c FROM edges WHERE source_id = ? AND kind = 'calls'"
-            ).get(node.id).c;
-            const callers = db.prepare(
-                "SELECT COUNT(*) as c FROM edges WHERE target_id = ? AND kind = 'calls'"
-            ).get(node.id).c;
-            result.push({
-                name: node.name,
-                kind: node.kind,
-                callees,
-                callers,
-            });
-        }
-        return result;
+        return nodes.map((node) => ({
+            name: node.display_name,
+            kind: node.kind,
+            callees: node.callees,
+            callers: node.callers,
+        }));
     } catch {
         return [];
     }
 }
 
 /**
- * Blast radius: symbols affected by changes in given line range.
+ * Call impact: callers affected by changes in given line range.
  * @param {object} db
  * @param {string} file - relative file path
  * @param {number} startLine
  * @param {number} endLine
  * @returns {Array<{name, file, line}>} affected symbols (max 10)
  */
-export function blastRadius(db, file, startLine, endLine) {
+export function callImpact(db, file, startLine, endLine) {
     try {
         const modified = db.prepare(
-            "SELECT id, name FROM nodes WHERE file = ? AND kind != 'import' AND line_start <= ? AND line_end >= ?"
+            `SELECT node_id
+             FROM hex_line_symbol_annotations
+             WHERE file = ?
+               AND line_start <= ?
+               AND line_end >= ?`
         ).all(file, endLine, startLine);
 
         if (modified.length === 0) return [];
@@ -126,14 +146,16 @@ export function blastRadius(db, file, startLine, endLine) {
 
         for (const node of modified) {
             const dependents = db.prepare(
-                "SELECT n.name, n.file, n.line_start FROM edges e JOIN nodes n ON n.id = e.source_id WHERE e.target_id = ? AND e.kind = 'calls'"
-            ).all(node.id);
+                `SELECT source_display_name AS name, source_file AS file, source_line AS line
+                 FROM hex_line_call_edges
+                 WHERE target_id = ?`
+            ).all(node.node_id);
 
             for (const dep of dependents) {
                 const key = `${dep.file}:${dep.name}`;
                 if (!seen.has(key) && dep.file !== file) {
                     seen.add(key);
-                    affected.push({ name: dep.name, file: dep.file, line: dep.line_start });
+                    affected.push({ name: dep.name, file: dep.file, line: dep.line });
                 }
             }
         }
@@ -154,21 +176,17 @@ export function blastRadius(db, file, startLine, endLine) {
 export function matchAnnotation(db, file, line) {
     try {
         const node = db.prepare(
-            "SELECT id, name, kind FROM nodes WHERE file = ? AND kind != 'import' AND line_start <= ? AND line_end >= ? LIMIT 1"
+            `SELECT display_name, kind, callees, callers
+             FROM hex_line_symbol_annotations
+             WHERE file = ? AND line_start <= ? AND line_end >= ?
+             ORDER BY line_start DESC
+             LIMIT 1`
         ).get(file, line, line);
         if (!node) return null;
 
         const kindShort = { function: "fn", class: "cls", method: "mtd", variable: "var" }[node.kind] || node.kind;
-
-        const callees = db.prepare(
-            "SELECT COUNT(*) as c FROM edges WHERE source_id = ? AND kind = 'calls'"
-        ).get(node.id).c;
-        const callers = db.prepare(
-            "SELECT COUNT(*) as c FROM edges WHERE target_id = ? AND kind = 'calls'"
-        ).get(node.id).c;
-
-        if (callees === 0 && callers === 0) return `[${kindShort}]`;
-        return `[${kindShort} ${callees}\u2193 ${callers}\u2191]`;
+        if (node.callees === 0 && node.callers === 0) return `[${kindShort}]`;
+        return `[${kindShort} ${node.callees}\u2193 ${node.callers}\u2191]`;
     } catch {
         return null;
     }

package/lib/hash.mjs

@@ -1,109 +1 @@
-/**
- * FNV-1a hashing for hash-verified file editing.
- *
- * 2-char tags from 32-symbol alphabet,
- * range checksums as FNV-1a accumulator over line hashes.
- *
- * Line format: {tag}.{lineNum}\t{content}
- * Range checksum: checksum: {startLine}-{endLine}:{8hex}
- */
-
-const FNV_OFFSET = 0x811c9dc5;
-const FNV_PRIME = 0x01000193;
-
-// 32 symbols — bitwise & 0x1f (power of 2, no division)
-const TAG_CHARS = "abcdefghijklmnopqrstuvwxyz234567";
-
-/**
- * FNV-1a 32-bit hash of a string (UTF-8 encoded).
- * Whitespace is normalized (collapsed) before hashing.
- */
-export function fnv1a(str) {
-    // Normalize: strip trailing \r, collapse whitespace
-    const normalized = str.replace(/\r$/, "").replace(/\s+/g, "");
-    let h = FNV_OFFSET;
-    for (let i = 0; i < normalized.length; i++) {
-        let code = normalized.charCodeAt(i);
-        // Handle surrogate pairs for codepoints > U+FFFF
-        if (code >= 0xd800 && code <= 0xdbff && i + 1 < normalized.length) {
-            const lo = normalized.charCodeAt(i + 1);
-            if (lo >= 0xdc00 && lo <= 0xdfff) {
-                code = ((code - 0xd800) << 10) + (lo - 0xdc00) + 0x10000;
-                i++;
-            }
-        }
-        // Encode as UTF-8 bytes and feed to FNV-1a
-        if (code < 0x80) {
-            h = Math.imul(h ^ code, FNV_PRIME) >>> 0;
-        } else if (code < 0x800) {
-            h = Math.imul(h ^ (0xc0 | (code >> 6)), FNV_PRIME) >>> 0;
-            h = Math.imul(h ^ (0x80 | (code & 0x3f)), FNV_PRIME) >>> 0;
-        } else if (code < 0x10000) {
-            h = Math.imul(h ^ (0xe0 | (code >> 12)), FNV_PRIME) >>> 0;
-            h = Math.imul(h ^ (0x80 | ((code >> 6) & 0x3f)), FNV_PRIME) >>> 0;
-            h = Math.imul(h ^ (0x80 | (code & 0x3f)), FNV_PRIME) >>> 0;
-        } else {
-            h = Math.imul(h ^ (0xf0 | (code >> 18)), FNV_PRIME) >>> 0;
-            h = Math.imul(h ^ (0x80 | ((code >> 12) & 0x3f)), FNV_PRIME) >>> 0;
-            h = Math.imul(h ^ (0x80 | ((code >> 6) & 0x3f)), FNV_PRIME) >>> 0;
-            h = Math.imul(h ^ (0x80 | (code & 0x3f)), FNV_PRIME) >>> 0;
-        }
-    }
-    return h;
-}
-
-/**
- * 2-character tag from 32-bit hash.
- * Uses bits 0-4 and 8-12 for two characters from TAG_CHARS.
- */
-export function lineTag(hash32) {
-    return TAG_CHARS[hash32 & 0x1f] + TAG_CHARS[(hash32 >>> 8) & 0x1f];
-}
-
-/**
- * Compute tag for a line's content.
- */
-export function hashLine(content) {
-    return lineTag(fnv1a(content));
-}
-
-/**
- * Format a line with hash prefix: {tag}.{lineNum}\t{content}
- */
-export function formatLine(lineNum, content) {
-    return `${hashLine(content)}.${lineNum}\t${content}`;
-}
-
-/**
- * Range checksum: FNV-1a accumulator over line hashes (little-endian bytes).
- * Returns "{startLine}-{endLine}:{8hex}".
- */
-export function rangeChecksum(lineHashes, startLine, endLine) {
-    let acc = FNV_OFFSET;
-    for (const h of lineHashes) {
-        // Feed 4 bytes of each 32-bit hash in little-endian order
-        acc = Math.imul(acc ^ (h & 0xff), FNV_PRIME) >>> 0;
-        acc = Math.imul(acc ^ ((h >>> 8) & 0xff), FNV_PRIME) >>> 0;
-        acc = Math.imul(acc ^ ((h >>> 16) & 0xff), FNV_PRIME) >>> 0;
-        acc = Math.imul(acc ^ ((h >>> 24) & 0xff), FNV_PRIME) >>> 0;
-    }
-    return `${startLine}-${endLine}:${acc.toString(16).padStart(8, "0")}`;
-}
-
-/**
- * Parse a line reference: "ab.12" → { tag: "ab", line: 12 }
- */
-export function parseRef(ref) {
-    const m = ref.trim().match(/^([a-z2-7]{2})\.(\d+)$/);
-    if (!m) throw new Error(`Bad ref: "${ref}". Expected "ab.12" (tag.lineNum)`);
-    return { tag: m[1], line: parseInt(m[2], 10) };
-}
-
-/**
- * Parse a range checksum: "1-50:f7e2a1b0" → { start: 1, end: 50, hex: "f7e2a1b0" }
- */
-export function parseChecksum(cs) {
-    const m = cs.trim().match(/^(\d+)-(\d+):([0-9a-f]{8})$/);
-    if (!m) throw new Error(`Bad checksum: "${cs}". Expected "1-50:f7e2a1b0"`);
-    return { start: parseInt(m[1], 10), end: parseInt(m[2], 10), hex: m[3] };
-}
+export * from "@levnikolaevich/hex-common/text-protocol/hash";

package/lib/info.mjs

@@ -82,7 +82,7 @@ export function fileInfo(filePath) {
     const timeStr = `Modified: ${mtime.toISOString().replace("T", " ").slice(0, 19)} (${relativeTime(mtime)})`;
 
     return [
-        `File: ${filePath}`,
+        `File: ${normalized}`,
         sizeStr,
         timeStr,
         `Type: ${typeName}`,

package/lib/normalize.mjs

@@ -1,106 +1 @@
-/**
- * Output normalization and smart truncation.
- * Based on shared/references/output_normalization.md patterns.
- *
- * - Normalizes runtime values (IPs, timestamps, UUIDs, large numbers)
- * - Deduplicates identical normalized lines with (xN) counts
- * - Smart truncation: first N + last N lines with gap indicator
- */
-
-// Normalization patterns (applied in order)
-const NORM_RULES = [
-    [/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "<UUID>"],
-    [/\d{4}-\d{2}-\d{2}\s\d{2}:\d{2}:\d{2}/g, "<TS>"],
-    [/\d{2}-\d{2}-\d{4}\s\d{2}:\d{2}:\d{2}/g, "<TS>"],
-    [/\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}(:\d+)?/g, "<IP>"],
-    [/\/[0-9a-f]{8,}/gi, "/<ID>"],
-    [/\b\d{3,}(?=\b|[a-zA-Z])/g, "<N>"],
-    [/trace_id=[0-9a-fA-F]{1,8}/g, "trace_id=<TRACE>"],
-];
-
-/**
- * Normalize a single line by replacing runtime-specific values.
- */
-function normalizeLine(line) {
-    let result = line;
-    for (const [rx, repl] of NORM_RULES) {
-        result = result.replace(rx, repl);
-    }
-    return result;
-}
-
-/**
- * Deduplicate lines: group identical normalized lines, append (xN).
- *
- * @param {string[]} lines - raw output lines
- * @returns {string[]} deduplicated lines
- */
-export function deduplicateLines(lines) {
-    const groups = new Map();
-    const order = [];
-
-    for (const line of lines) {
-        const norm = normalizeLine(line);
-        if (groups.has(norm)) {
-            groups.get(norm).count++;
-        } else {
-            const entry = { representative: line, count: 1 };
-            groups.set(norm, entry);
-            order.push(norm);
-        }
-    }
-
-    // Sort by count descending (stable within same count)
-    order.sort((a, b) => groups.get(b).count - groups.get(a).count);
-
-    return order.map((norm) => {
-        const { representative, count } = groups.get(norm);
-        return count > 1 ? `${representative}  (x${count})` : representative;
-    });
-}
-
-/**
- * Smart truncation: keep first N + last N lines with gap indicator.
- *
- * @param {string} text - full output text
- * @param {number} [headLines=40] - lines to keep from start
- * @param {number} [tailLines=20] - lines to keep from end
- * @returns {string} truncated text
- */
-export function smartTruncate(text, headLines = 40, tailLines = 20) {
-    const lines = text.split("\n");
-    const total = lines.length;
-    const maxLines = headLines + tailLines;
-
-    if (total <= maxLines) return text;
-
-    const head = lines.slice(0, headLines);
-    const tail = lines.slice(total - tailLines);
-    const skipped = total - maxLines;
-
-    return [
-        ...head,
-        `\n--- ${skipped} lines omitted ---\n`,
-        ...tail,
-    ].join("\n");
-}
-
-/**
- * Full normalization pipeline: normalize -> deduplicate -> truncate.
- *
- * @param {string} text - raw output
- * @param {object} [opts]
- * @param {boolean} [opts.deduplicate=true]
- * @param {number} [opts.headLines=40]
- * @param {number} [opts.tailLines=20]
- * @returns {string}
- */
-export function normalizeOutput(text, opts = {}) {
-    const { deduplicate = true, headLines = 40, tailLines = 20 } = opts;
-    const lines = text.split("\n");
-
-    const processed = deduplicate ? deduplicateLines(lines) : lines;
-    const result = processed.join("\n");
-
-    return smartTruncate(result, headLines, tailLines);
-}
+export * from "@levnikolaevich/hex-common/output/normalize";

package/lib/outline.mjs

@@ -2,74 +2,39 @@
  * AST-based file outline via tree-sitter WASM.
  *
  * Returns structural overview: functions, classes, interfaces with line ranges.
- * 10-20 lines instead of 500 → 95% token reduction.
+ * 10-20 lines instead of 500 -> 95% token reduction.
  * Output maps directly to read_file ranges.
  */
 
-import { readFileSync } from "node:fs";
-import { resolve, extname } from "node:path";
-import { validatePath } from "./security.mjs";
+import { extname } from "node:path";
+import { getParser, getLanguage } from "@levnikolaevich/hex-common/parser/tree-sitter";
+import { grammarForExtension, supportedExtensions } from "@levnikolaevich/hex-common/parser/languages";
+import { readUtf8Normalized } from "@levnikolaevich/hex-common/text/file-text";
+import { validatePath, normalizePath } from "./security.mjs";
 import { getGraphDB, symbolAnnotation, getRelativePath } from "./graph-enrich.mjs";
 
-// Language configs: extension → { grammar, outline, skip, recurse }
 const LANG_CONFIGS = {
-    ".js":   { grammar: "javascript", outline: ["function_declaration", "class_declaration", "variable_declaration", "export_statement", "lexical_declaration"], skip: ["import_statement"], recurse: ["class_body"] },
-    ".mjs":  { grammar: "javascript", outline: ["function_declaration", "class_declaration", "variable_declaration", "export_statement", "lexical_declaration"], skip: ["import_statement"], recurse: ["class_body"] },
-    ".jsx":  { grammar: "javascript", outline: ["function_declaration", "class_declaration", "variable_declaration", "export_statement", "lexical_declaration"], skip: ["import_statement"], recurse: ["class_body"] },
-    ".ts":   { grammar: "typescript", outline: ["function_declaration", "class_declaration", "interface_declaration", "type_alias_declaration", "enum_declaration", "variable_declaration", "export_statement", "lexical_declaration"], skip: ["import_statement"], recurse: ["class_body"] },
-    ".tsx":  { grammar: "tsx", outline: ["function_declaration", "class_declaration", "interface_declaration", "type_alias_declaration", "enum_declaration", "variable_declaration", "export_statement", "lexical_declaration"], skip: ["import_statement"], recurse: ["class_body"] },
-    ".py":   { grammar: "python", outline: ["function_definition", "class_definition", "decorated_definition"], skip: ["import_statement", "import_from_statement"], recurse: ["class_body", "block"] },
-    ".go":   { grammar: "go", outline: ["function_declaration", "method_declaration", "type_declaration"], skip: ["import_declaration"], recurse: [] },
-    ".rs":   { grammar: "rust", outline: ["function_item", "struct_item", "enum_item", "impl_item", "trait_item", "const_item", "static_item"], skip: ["use_declaration"], recurse: ["impl_item"] },
-    ".java": { grammar: "java", outline: ["class_declaration", "interface_declaration", "method_declaration", "enum_declaration"], skip: ["import_declaration"], recurse: ["class_body"] },
-    ".c":    { grammar: "c", outline: ["function_definition", "struct_specifier", "enum_specifier", "type_definition"], skip: ["preproc_include"], recurse: [] },
-    ".h":    { grammar: "c", outline: ["function_definition", "struct_specifier", "enum_specifier", "type_definition"], skip: ["preproc_include"], recurse: [] },
-    ".cpp":  { grammar: "cpp", outline: ["function_definition", "class_specifier", "struct_specifier", "namespace_definition"], skip: ["preproc_include"], recurse: ["class_specifier"] },
-    ".cs":   { grammar: "c_sharp", outline: ["class_declaration", "interface_declaration", "method_declaration", "namespace_declaration"], skip: ["using_directive"], recurse: ["class_body"] },
-    ".rb":   { grammar: "ruby", outline: ["method", "class", "module"], skip: ["require", "require_relative"], recurse: ["class", "module"] },
-    ".php":  { grammar: "php", outline: ["function_definition", "class_declaration", "method_declaration"], skip: ["namespace_use_declaration"], recurse: ["class_body"] },
-    ".kt":   { grammar: "kotlin", outline: ["function_declaration", "class_declaration", "object_declaration"], skip: ["import_header"], recurse: ["class_body"] },
-    ".swift": { grammar: "swift", outline: ["function_declaration", "class_declaration", "struct_declaration", "protocol_declaration"], skip: ["import_declaration"], recurse: ["class_body"] },
-    ".sh":   { grammar: "bash", outline: ["function_definition"], skip: [], recurse: [] },
-    ".bash": { grammar: "bash", outline: ["function_definition"], skip: [], recurse: [] },
+    ".js":   { outline: ["function_declaration", "class_declaration", "variable_declaration", "export_statement", "lexical_declaration"], skip: ["import_statement"], recurse: ["class_body"] },
+    ".mjs":  { outline: ["function_declaration", "class_declaration", "variable_declaration", "export_statement", "lexical_declaration"], skip: ["import_statement"], recurse: ["class_body"] },
+    ".jsx":  { outline: ["function_declaration", "class_declaration", "variable_declaration", "export_statement", "lexical_declaration"], skip: ["import_statement"], recurse: ["class_body"] },
+    ".ts":   { outline: ["function_declaration", "class_declaration", "interface_declaration", "type_alias_declaration", "enum_declaration", "variable_declaration", "export_statement", "lexical_declaration"], skip: ["import_statement"], recurse: ["class_body"] },
+    ".tsx":  { outline: ["function_declaration", "class_declaration", "interface_declaration", "type_alias_declaration", "enum_declaration", "variable_declaration", "export_statement", "lexical_declaration"], skip: ["import_statement"], recurse: ["class_body"] },
+    ".py":   { outline: ["function_definition", "class_definition", "decorated_definition"], skip: ["import_statement", "import_from_statement"], recurse: ["class_body", "block"] },
+    ".go":   { outline: ["function_declaration", "method_declaration", "type_declaration"], skip: ["import_declaration"], recurse: [] },
+    ".rs":   { outline: ["function_item", "struct_item", "enum_item", "impl_item", "trait_item", "const_item", "static_item"], skip: ["use_declaration"], recurse: ["impl_item"] },
+    ".java": { outline: ["class_declaration", "interface_declaration", "method_declaration", "enum_declaration"], skip: ["import_declaration"], recurse: ["class_body"] },
+    ".c":    { outline: ["function_definition", "struct_specifier", "enum_specifier", "type_definition"], skip: ["preproc_include"], recurse: [] },
+    ".h":    { outline: ["function_definition", "struct_specifier", "enum_specifier", "type_definition"], skip: ["preproc_include"], recurse: [] },
+    ".cpp":  { outline: ["function_definition", "class_specifier", "struct_specifier", "namespace_definition"], skip: ["preproc_include"], recurse: ["class_specifier"] },
+    ".cs":   { outline: ["class_declaration", "interface_declaration", "method_declaration", "namespace_declaration"], skip: ["using_directive"], recurse: ["class_body"] },
+    ".rb":   { outline: ["method", "class", "module"], skip: ["require", "require_relative"], recurse: ["class", "module"] },
+    ".php":  { outline: ["function_definition", "class_declaration", "method_declaration"], skip: ["namespace_use_declaration"], recurse: ["class_body"] },
+    ".kt":   { outline: ["function_declaration", "class_declaration", "object_declaration"], skip: ["import_header"], recurse: ["class_body"] },
+    ".swift": { outline: ["function_declaration", "class_declaration", "struct_declaration", "protocol_declaration"], skip: ["import_declaration"], recurse: ["class_body"] },
+    ".sh":   { outline: ["function_definition"], skip: [], recurse: [] },
+    ".bash": { outline: ["function_definition"], skip: [], recurse: [] },
 };
 
-// Parser cache (init once)
-let _parser = null;
-const _langCache = new Map();
-
-async function getParser() {
-    if (_parser) return _parser;
-    try {
-        const { Parser } = await import("web-tree-sitter");
-        await Parser.init();
-        _parser = new Parser();
-        return _parser;
-    } catch (e) {
-        throw new Error(`tree-sitter init failed: ${e.message}. Run: cd mcp/hex-line-mcp && npm install`);
-    }
-}
-
-async function getLanguage(grammar) {
-    if (_langCache.has(grammar)) return _langCache.get(grammar);
-    await getParser(); // ensure init
-    try {
-        const { Language } = await import("web-tree-sitter");
-        const { createRequire } = await import("node:module");
-        const require = createRequire(import.meta.url);
-        // Absolute path for Windows compatibility (Gemini finding #3)
-        const wasmPath = resolve(require.resolve("tree-sitter-wasms/package.json"), "..", "out", `tree-sitter-${grammar}.wasm`);
-        const lang = await Language.load(wasmPath);
-        _langCache.set(grammar, lang);
-        return lang;
-    } catch (e) {
-        throw new Error(`Language "${grammar}" not available: ${e.message}`);
-    }
-}
-
-/**
- * Extract structural outline entries from AST.
- */
 function extractOutline(rootNode, config, sourceLines) {
     const entries = [];
     const skipTypes = new Set(config.skip);
@@ -87,7 +52,6 @@ function extractOutline(rootNode, config, sourceLines) {
 
             if (outlineTypes.has(type)) {
                 const firstLine = sourceLines[startLine - 1] || "";
-                // Extract symbol name for graph annotation
                 const nameMatch = firstLine.match(/(?:function|class|interface|type|enum|struct|def|fn|pub\s+fn)\s+(\w+)|(?:const|let|var|export\s+(?:const|let|var|function|class))\s+(\w+)/);
                 const name = nameMatch ? (nameMatch[1] || nameMatch[2]) : null;
 
@@ -99,18 +63,14 @@ function extractOutline(rootNode, config, sourceLines) {
                     name,
                 });
 
-                // Recurse into class/struct bodies
                 for (let j = 0; j < child.childCount; j++) {
                     const sub = child.child(j);
-                    if (recurseTypes.has(sub.type)) {
-                        walk(sub, depth + 1);
-                    }
+                    if (recurseTypes.has(sub.type)) walk(sub, depth + 1);
                 }
             }
         }
     }
 
-    // Collect skipped ranges for summary
     const skippedRanges = [];
     for (let i = 0; i < rootNode.childCount; i++) {
         const child = rootNode.child(i);
@@ -126,23 +86,16 @@ function extractOutline(rootNode, config, sourceLines) {
     return { entries, skippedRanges };
 }
 
-/**
- * Parse content string into outline entries.
- * Reusable core — no file I/O, no validatePath.
- *
- * @param {string} content  Source text (LF-normalized)
- * @param {string} ext      Lowercase extension including dot (e.g. ".mjs")
- * @returns {Promise<{entries: Array, skippedRanges: Array} | null>}  null if unsupported ext
- */
 export async function outlineFromContent(content, ext) {
     const config = LANG_CONFIGS[ext];
-    if (!config) return null;
+    const grammar = grammarForExtension(ext);
+    if (!config || !grammar) return null;
 
     const sourceLines = content.split("\n");
 
     let lang;
     try {
-        lang = await getLanguage(config.grammar);
+        lang = await getLanguage(grammar);
     } catch (e) {
         throw new Error(`Outline error: ${e.message}`);
     }
@@ -153,9 +106,6 @@ export async function outlineFromContent(content, ext) {
     return extractOutline(tree.rootNode, config, sourceLines);
 }
 
-/**
- * Format outline entries into display string.
- */
 function formatOutline(entries, skippedRanges, sourceLineCount, db, relFile) {
     const lines = [];
 
@@ -178,21 +128,16 @@ function formatOutline(entries, skippedRanges, sourceLineCount, db, relFile) {
     return lines.join("\n");
 }
 
-/**
- * Generate file outline.
- *
- * @param {string} filePath
- * @returns {Promise<string>} formatted outline
- */
 export async function fileOutline(filePath) {
+    filePath = normalizePath(filePath);
     const real = validatePath(filePath);
     const ext = extname(real).toLowerCase();
 
     if (!LANG_CONFIGS[ext]) {
-        return `Outline unavailable for ${ext} files. Use read_file directly for non-code files (markdown, config, text). Supported code extensions: ${Object.keys(LANG_CONFIGS).join(", ")}`;
+        return `Outline unavailable for ${ext} files. Use read_file directly for non-code files (markdown, config, text). Supported code extensions: ${supportedExtensions().join(", ")}`;
     }
 
-    const content = readFileSync(real, "utf-8").replace(/\r\n/g, "\n");
+    const content = readUtf8Normalized(real);
     const result = await outlineFromContent(content, ext);
     const db = getGraphDB(real);
     const relFile = db ? getRelativePath(real) : null;