syntax-map-mcp 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.1.9 - 2026-05-07
+
+- 잘못된 인덱스 검색 옵션 오류 메시지에 실제 입력값을 포함하도록 개선했습니다.
+- 인덱스 검색 옵션의 `limit`, `contextBefore`, `contextAfter` 범위를 분석 계층에서도 검증하도록 했습니다.
+- 인덱스 저장 실패 시 tool failure 응답 shape를 검증하는 테스트를 추가했습니다.
+- 주요 인덱스 도구의 `structuredContent` 응답 shape를 검증하는 테스트를 추가했습니다.
+- `get_index_status` 응답에 stale 파일별 이유(`changed`, `missing`)를 반환하는 `staleReasons`를 추가했습니다.
+- SQLite 인덱스 DB에 schema version metadata를 저장하고, 호환되지 않는 기존 인덱스는 자동 재생성하도록 했습니다.
+
 ## 0.1.8 - 2026-05-07
 
 - `docs/tools.md`의 도구 목록이 실제 MCP `listTools()` 응답과 일치하는지 검증하도록 했습니다.

package/dist/analysis/index.js

@@ -7,6 +7,10 @@ import { runTreeSitterQuery } from './query.js';
 import { referenceQueryForLanguage } from './references.js';
 const INDEX_DIRECTORY = '.syntax-map-mcp';
 const INDEX_FILE = 'index.sqlite';
+const INDEX_SCHEMA_VERSION = 1;
+const DEFAULT_SEARCH_LIMIT = 50;
+const MAX_SEARCH_LIMIT = 500;
+const MAX_CONTEXT_LINES = 10;
 function indexPathForWorkspace(workspace) {
     return path.join(workspace.root, INDEX_DIRECTORY, INDEX_FILE);
 }
@@ -19,15 +23,49 @@ function failure(message) {
         }
     };
 }
+async function createDatabase() {
+    const SQL = await initSqlJs();
+    return new SQL.Database();
+}
 async function openDatabase(indexPath) {
     const SQL = await initSqlJs();
     try {
         const data = await readFile(indexPath);
-        return new SQL.Database(data);
+        return { database: new SQL.Database(data), exists: true };
     }
     catch {
-        return new SQL.Database();
+        return { database: new SQL.Database(), exists: false };
+    }
+}
+function tableExists(database, tableName) {
+    const result = database.exec("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?", [tableName])[0];
+    return result !== undefined && result.values.length > 0;
+}
+function storedSchemaVersion(database) {
+    if (!tableExists(database, 'metadata')) {
+        return undefined;
+    }
+    const result = database.exec('SELECT value FROM metadata WHERE key = ?', ['schema_version'])[0];
+    const value = result?.values[0]?.[0];
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const version = Number(value);
+    return Number.isInteger(version) ? version : undefined;
+}
+function hasCurrentSchemaVersion(database) {
+    return storedSchemaVersion(database) === INDEX_SCHEMA_VERSION;
+}
+async function openCompatibleDatabase(indexPath) {
+    let { database, exists } = await openDatabase(indexPath);
+    let reset = false;
+    if (exists && !hasCurrentSchemaVersion(database)) {
+        database.close();
+        await rm(indexPath, { force: true });
+        database = await createDatabase();
+        reset = true;
     }
+    return { database, reset };
 }
 async function saveDatabase(database, indexPath) {
     await mkdir(path.dirname(indexPath), { recursive: true });
@@ -81,7 +119,17 @@ function initSchema(database) {
     CREATE INDEX IF NOT EXISTS symbols_name_idx ON symbols(name);
     CREATE INDEX IF NOT EXISTS symbols_kind_idx ON symbols(kind);
     CREATE INDEX IF NOT EXISTS reference_captures_name_idx ON reference_captures(name);
+
+    CREATE TABLE IF NOT EXISTS metadata (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
   `);
+    database.run(`
+      INSERT INTO metadata (key, value)
+      VALUES ('schema_version', ?)
+      ON CONFLICT(key) DO UPDATE SET value = excluded.value
+    `, [String(INDEX_SCHEMA_VERSION)]);
 }
 function selectStoredFiles(database) {
     const rows = database.exec('SELECT path, size, mtime_ms, parse_status FROM files');
@@ -106,29 +154,38 @@ function isCurrent(stored, current) {
         stored.size === current.size &&
         stored.mtimeMs === current.mtimeMs);
 }
-async function countStaleFiles(workspace, database) {
+async function collectStaleReasons(workspace, database) {
     const storedFiles = selectStoredFiles(database);
     const currentFiles = await workspace.listSourceFiles();
     const currentPaths = new Set(currentFiles.map(file => file.relativePath));
-    let staleFiles = 0;
+    const staleReasons = [];
     for (const file of currentFiles) {
         if (!isCurrent(storedFiles.get(file.relativePath), file)) {
-            staleFiles += 1;
+            staleReasons.push({
+                path: file.relativePath,
+                reason: 'changed'
+            });
         }
     }
     for (const storedPath of storedFiles.keys()) {
         if (!currentPaths.has(storedPath)) {
-            staleFiles += 1;
+            staleReasons.push({
+                path: storedPath,
+                reason: 'missing'
+            });
         }
     }
-    return staleFiles;
+    return staleReasons.sort((left, right) => left.path.localeCompare(right.path));
+}
+async function countStaleFiles(workspace, database) {
+    return (await collectStaleReasons(workspace, database)).length;
 }
 async function openIndexForRead(workspace, input) {
     const indexPath = indexPathForWorkspace(workspace);
-    let database = await openDatabase(indexPath);
+    let { database, reset } = await openCompatibleDatabase(indexPath);
     initSchema(database);
     const initialStaleFiles = await countStaleFiles(workspace, database);
-    if (!input.refreshIfStale || initialStaleFiles === 0) {
+    if (!reset && (!input.refreshIfStale || initialStaleFiles === 0)) {
         return {
             database,
             indexPath,
@@ -142,7 +199,7 @@ async function openIndexForRead(workspace, input) {
     if (!refreshedIndex.ok) {
         throw new Error(refreshedIndex.error.message);
     }
-    database = await openDatabase(indexPath);
+    database = (await openCompatibleDatabase(indexPath)).database;
     initSchema(database);
     const staleFiles = await countStaleFiles(workspace, database);
     return {
@@ -253,6 +310,18 @@ function sqlLikePattern(query) {
 function rowValue(row, key) {
     return row[key];
 }
+function assertIntegerRange(name, value, min, max) {
+    if (value === undefined)
+        return;
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw new Error(`${name} must be an integer between ${min} and ${max} (received ${String(value)})`);
+    }
+}
+function validateSearchOptions(input) {
+    assertIntegerRange('limit', input.limit, 1, MAX_SEARCH_LIMIT);
+    assertIntegerRange('contextBefore', input.contextBefore, 0, MAX_CONTEXT_LINES);
+    assertIntegerRange('contextAfter', input.contextAfter, 0, MAX_CONTEXT_LINES);
+}
 function snippetDetails(path, language, text, row, options) {
     if (text === undefined)
         return { snippet: '' };
@@ -289,7 +358,7 @@ function previewMarkdown(filePath, language, row, snippet, context) {
 }
 export async function indexWorkspace(workspace) {
     const indexPath = indexPathForWorkspace(workspace);
-    const database = await openDatabase(indexPath);
+    const { database } = await openCompatibleDatabase(indexPath);
     try {
         initSchema(database);
         const currentFiles = await workspace.listSourceFiles();
@@ -372,6 +441,7 @@ export async function indexWorkspace(workspace) {
             indexedFiles,
             skippedFiles,
             removedFiles,
+            schemaVersion: INDEX_SCHEMA_VERSION,
             symbols: scalarCount(database, 'SELECT COUNT(*) FROM symbols'),
             references: scalarCount(database, 'SELECT COUNT(*) FROM reference_captures')
         };
@@ -386,6 +456,7 @@ export async function indexWorkspace(workspace) {
 export async function findIndexedDefinitions(workspace, input) {
     let readState;
     try {
+        validateSearchOptions(input);
         readState = await openIndexForRead(workspace, input);
         const { database } = readState;
         const where = ['name = ?'];
@@ -394,7 +465,7 @@ export async function findIndexedDefinitions(workspace, input) {
             where.push(`kind IN (${input.kinds.map(() => '?').join(', ')})`);
             params.push(...input.kinds);
         }
-        const limit = input.limit ?? 50;
+        const limit = input.limit ?? DEFAULT_SEARCH_LIMIT;
         params.push(limit);
         const statement = database.prepare(`
         SELECT
@@ -485,9 +556,10 @@ export async function findIndexedDefinitions(workspace, input) {
 export async function findIndexedReferences(workspace, input) {
     let readState;
     try {
+        validateSearchOptions(input);
         readState = await openIndexForRead(workspace, input);
         const { database } = readState;
-        const limit = input.limit ?? 50;
+        const limit = input.limit ?? DEFAULT_SEARCH_LIMIT;
         const statement = database.prepare(`
         SELECT
           file_path,
@@ -552,6 +624,7 @@ export async function findIndexedReferences(workspace, input) {
 export async function searchSymbols(workspace, input) {
     let readState;
     try {
+        validateSearchOptions(input);
         readState = await openIndexForRead(workspace, input);
         const { database } = readState;
         const where = ['name LIKE ? ESCAPE "\\"'];
@@ -560,7 +633,7 @@ export async function searchSymbols(workspace, input) {
             where.push(`kind IN (${input.kinds.map(() => '?').join(', ')})`);
             params.push(...input.kinds);
         }
-        const limit = input.limit ?? 50;
+        const limit = input.limit ?? DEFAULT_SEARCH_LIMIT;
         params.push(limit);
         const statement = database.prepare(`
         SELECT
@@ -650,17 +723,19 @@ export async function searchSymbols(workspace, input) {
 }
 export async function getIndexStatus(workspace) {
     const indexPath = indexPathForWorkspace(workspace);
-    const database = await openDatabase(indexPath);
+    const { database } = await openCompatibleDatabase(indexPath);
     try {
         initSchema(database);
-        const staleFiles = await countStaleFiles(workspace, database);
+        const staleReasons = await collectStaleReasons(workspace, database);
         return {
             ok: true,
             indexPath,
+            schemaVersion: INDEX_SCHEMA_VERSION,
             indexedFiles: scalarCount(database, 'SELECT COUNT(*) FROM files WHERE parse_status = "ok"'),
             symbols: scalarCount(database, 'SELECT COUNT(*) FROM symbols'),
             references: scalarCount(database, 'SELECT COUNT(*) FROM reference_captures'),
-            staleFiles
+            staleFiles: staleReasons.length,
+            staleReasons
         };
     }
     catch (error) {

package/docs/tools.md

@@ -215,6 +215,7 @@ syntax-map-mcp의 주요 MCP 도구 입력과 응답 예시입니다. 응답 예
 ```json
 {
   "ok": true,
+  "schemaVersion": 1,
   "indexedFiles": 12,
   "symbols": 84,
   "references": 231,
@@ -331,10 +332,21 @@ syntax-map-mcp의 주요 MCP 도구 입력과 응답 예시입니다. 응답 예
 ```json
 {
   "ok": true,
+  "schemaVersion": 1,
   "indexedFiles": 12,
   "symbols": 84,
   "references": 231,
-  "staleFiles": 0
+  "staleFiles": 2,
+  "staleReasons": [
+    {
+      "path": "src/users.ts",
+      "reason": "changed"
+    },
+    {
+      "path": "src/old.ts",
+      "reason": "missing"
+    }
+  ]
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntax-map-mcp",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Tree-sitter based code analysis MCP server",
   "license": "MIT",
   "type": "module",