micro-models-agent 2.11.0 → 2.13.1

package/dist/modules/indexer/map-select.js

@@ -1,6 +1,6 @@
 import { toForwardSlash } from "../../tools/path-utils";
 import { isCodeLanguage } from "./symbols";
-/** Lockfiles and generated manifests: no structural value in the map. */
+/** Локфайлы и генерированные манифесты: структурной ценности в карте нет. */
 const NOISE_BASENAMES = new Set([
     "package-lock.json",
     "bun.lock",
@@ -12,6 +12,7 @@ const NOISE_BASENAMES = new Set([
     "composer.lock",
     "poetry.lock",
 ]);
+/** True, если файл — локфайловый шум (не попадает в карту). */
 export function isNoiseFile(file) {
     const base = toForwardSlash(file.path).split("/").pop()?.toLowerCase() ?? "";
     return NOISE_BASENAMES.has(base);
@@ -24,7 +25,7 @@ function isTestFile(path) {
         path.includes("__tests__/") ||
         /\.(test|spec)\.[a-z0-9]+$/i.test(path));
 }
-/** Lower rank = more useful for understanding the project structure. */
+/** Ниже ранг — полезнее для понимания структуры проекта. */
 function rank(file) {
     const path = toForwardSlash(file.path).toLowerCase();
     if (isTestFile(path))
@@ -33,13 +34,13 @@ function rank(file) {
         return 0;
     return 2;
 }
-/** Top-level segment of a path (`src/core/x.ts` → `src`; root file → its name). */
+/** Верхний сегмент пути (`src/core/x.ts` → `src`; файл корня → его имя). */
 function topDir(path) {
     const normalized = toForwardSlash(path);
     const slash = normalized.indexOf("/");
     return slash >= 0 ? normalized.slice(0, slash) : normalized;
 }
-/** How many source-code files live under each top-level directory. */
+/** Сколько файлов исходного кода под каждым верхнеуровневым каталогом. */
 function codeCountByTopDir(files) {
     const counts = new Map();
     for (const file of files) {
@@ -51,19 +52,18 @@ function codeCountByTopDir(files) {
     return counts;
 }
 /**
- * Pick the files to list in the project-map prompt block.
+ * Выбирает файлы для блока карты проекта в промпте.
  *
- * The index is built by an arbitrary `readdir` walk, so a naive
- * `files.slice(0, N)` can end up listing only docs, config and tests while the
- * actual source tree (`src/`) never appears — the model then sees a "project
- * map" with no code in it. The selection:
- *   1. drops lockfile noise,
- *   2. ranks source before tests, tests before docs/config,
- *   3. within a rank, puts directories with the most source files first (the
- *      densest code root is almost always the real source tree — no directory
- *      names hardcoded),
- *   4. then shallower paths, then alphabetical — deterministic so the block
- *      does not change between turns and the prefix KV-cache survives.
+ * Индекс строится произвольным обходом `readdir`, так что наивный
+ * `files.slice(0, N)` может перечислить одни доки, конфиги и тесты, а реальное
+ * дерево исходников (`src/`) не показать — модель увидит "карту проекта" без
+ * кода. Отбор:
+ *   1. выкидывает локфайловый шум,
+ *   2. ранжирует исходники выше тестов, тесты выше доков/конфигов,
+ *   3. внутри ранга первыми — каталоги с плотнейшим кодом (плотнейший корень
+ *      почти всегда настоящее дерево исходников — имён каталогов не захардкожено),
+ *   4. затем мельче пути, затем алфавит — детерминированно, чтобы блок не
+ *      менялся между ходами и выживал префиксный KV-кэш.
  */
 export function selectMapFiles(files, max) {
     const codeByDir = codeCountByTopDir(files);

package/dist/modules/indexer/module.js

@@ -1,3 +1,4 @@
+// Модуль индексатора: построение карты проекта, тул project_map, вотчер.
 import { dirname } from "path";
 import { Indexer } from "./walker";
 import { IndexCache } from "./cache";
@@ -6,20 +7,29 @@ import { buildProjectProfileLine } from "./project-profile";
 import { t } from "../../i18n/index";
 import { toForwardSlash } from "../../tools/path-utils";
 import { estimateTokens } from "../../llm/token-counter";
-/** Max files listed in the project-map prompt block (code first; see map-select). */
+/** Макс. файлов в блоке карты проекта (сначала код; см. map-select). */
 const MAP_FILE_LIMIT = 80;
+/** Модуль индексатора: кэш, карта проекта для промпта, тул project_map, вотчер. */
 export class IndexerModule {
     name = "indexer";
     indexer;
     cache;
     baseDir;
     index = null;
+    statsCache = null;
     rebuildTimeout = null;
     constructor(opts) {
         this.baseDir = opts.baseDir;
         this.indexer = new Indexer(opts.baseDir);
-        this.cache = new IndexCache(opts.cacheDir);
+        // Привязываем кэш к корню проекта + текущей сигнатуре дерева, чтобы протухший
+        // `index-cache.json` (файлы добавлены/удалены/правлены после обхода) не
+        // утёк устаревшей картой в системный промпт, а перестроился.
+        this.cache = new IndexCache(opts.cacheDir, {
+            root: opts.baseDir,
+            signature: () => this.indexer.scanSignature(),
+        });
     }
+    /** Строит индекс (кэш → обход), null при неустранимой ошибке. */
     async buildIndex() {
         if (this.index)
             return this.index;
@@ -38,11 +48,13 @@ export class IndexerModule {
             return null;
         }
     }
+    /** Принудительно перестраивает индекс (сброс кэша + обход). */
     async refresh() {
         this.cache.invalidate();
         this.index = null;
         return this.buildIndex();
     }
+    /** Ищет файлы по подстроке пути/экспорта (пусто без индекса). */
     find(query) {
         if (!this.index)
             return [];
@@ -52,7 +64,7 @@ export class IndexerModule {
             return path.includes(q) || f.exports.some((e) => e.toLowerCase().includes(q));
         });
     }
-    /** Human/model-readable result of a `find` query (shared by the tool and `mma map`). */
+    /** Человеко/модельно-читаемый результат `find` (общий для тула и `mma map`). */
     formatFind(query) {
         const matches = this.find(query);
         if (matches.length === 0) {
@@ -67,10 +79,11 @@ export class IndexerModule {
             .join("\n");
         return t("indexer.find_results", { count: matches.length, results: lines });
     }
-    /** The exact project-map text injected into the system prompt (null if not indexed). */
+    /** Точный текст карты проекта для системного промпта (null без индекса). */
     getPromptMap() {
         return this.index ? this.formatMap(this.index) : null;
     }
+    /** Подписка на изменения файлов с дебаунсом перестройки (best-effort). */
     watch() {
         this.unwatch();
         try {
@@ -85,9 +98,10 @@ export class IndexerModule {
             });
         }
         catch {
-            // Watching is best-effort; manual refresh still works.
+            // Вотчинг best-effort; ручной refresh всё равно работает.
         }
     }
+    /** Отписывается от вотчера и чистит дебаунс-таймер. */
     unwatch() {
         if (this.rebuildTimeout) {
             clearTimeout(this.rebuildTimeout);
@@ -95,6 +109,7 @@ export class IndexerModule {
         }
         this.indexer.unwatch();
     }
+    /** Блок системного промпта с картой проекта (null без индекса). */
     getSystemPromptBlock() {
         if (!this.index)
             return null;
@@ -107,9 +122,30 @@ export class IndexerModule {
             kind: "project-map",
         };
     }
+    /**
+     * Компактная статистика карты для сайдбара хоста (`null` до конца обхода).
+     * Кэшируется на объект индекса, чтобы поллинг `/api/state` не ререндерил
+     * всю карту.
+     */
+    stats() {
+        if (!this.index)
+            return null;
+        if (this.statsCache && this.statsCache.index === this.index)
+            return this.statsCache.value;
+        const symbols = this.index.files.reduce((n, f) => n + f.exports.length, 0);
+        const value = {
+            files: this.index.files.length,
+            symbols,
+            tokens: this.estimateTokens(this.formatMap(this.index)),
+        };
+        this.statsCache = { index: this.index, value };
+        return value;
+    }
+    /** Определения тулов модуля (project_map). */
     getToolDefinitions() {
         return [this.createProjectMapTool()];
     }
+    /** Плагин модуля: индекс + вотчер на старт сессии, отписка на конец. */
     getPlugin() {
         return {
             name: "indexer",
@@ -147,18 +183,17 @@ export class IndexerModule {
             ...(stackLine ? [stackLine] : []),
             `${t("indexer.top_directories")}: ${topDirs}`,
             ...(duplicates.length > 0 ? [t("indexer.duplicates", { names: duplicates.join(", ") })] : []),
-            `${t("indexer.files")}:` + (fileLines.length > 0 ? "" : " " + t("indexer.empty")),
+            `${t("indexer.files")}:${fileLines.length > 0 ? "" : ` ${t("indexer.empty")}`}`,
             ...fileLines,
             more,
         ].join("\n");
     }
     /**
-     * Find files that share a basename across different extensions in the same
-     * directory (e.g. `ProductCard.js` + `ProductCard.tsx`). This is a purely
-     * structural fact about the file tree — a stale transpiled twin may shadow
-     * the real source at build time. Flagging it is not task classification, so
-     * it does not violate the no-keyword-matching rule; the model decides what
-     * to do with the information.
+     * Находит файлы с общим basename при разных расширениях в одном каталоге
+     * (напр. `ProductCard.js` + `ProductCard.tsx`). Чисто структурный факт дерева —
+     * протухший транспилированный близнец может затенять реальный исходник на
+     * сборке. Подсветить его — не классификация задач, правило no-keyword-matching
+     * не нарушает; что делать с информацией — решает модель.
      */
     findDuplicateBasenames(result) {
         const byDir = {};

package/dist/modules/indexer/project-profile.js

@@ -1,3 +1,4 @@
+// Профиль проекта: чтение манифеста (package.json/pyproject/Cargo/go.mod) в одну строку.
 import { readFileSync, existsSync } from "fs";
 import { join } from "path";
 import { t } from "../../i18n/index";
@@ -12,7 +13,7 @@ const MAX_DEPS = 5;
 const MAX_DEV_DEPS = 3;
 const MAX_SCRIPTS = 3;
 /**
- * Find the first existing manifest in priority order (best-effort, root only).
+ * Находит первый существующий манифест по приоритету (best-effort, только корень).
  */
 export function detectManifest(baseDir) {
     for (const manifest of MANIFEST_ORDER) {
@@ -21,7 +22,7 @@ export function detectManifest(baseDir) {
     }
     return null;
 }
-/** Strip version specifiers from a manifest dependency entry. */
+/** Чистит спеки версий из записи зависимости манифеста (имя без версии). */
 function cleanDependency(entry) {
     let name = entry.trim();
     const eq = name.indexOf("=");
@@ -135,8 +136,8 @@ function readRequirements(baseDir) {
     }
 }
 /**
- * Read a compact project profile from the workspace manifest (best-effort).
- * Returns null when no readable manifest is present.
+ * Читает компактный профиль проекта из манифеста (best-effort).
+ * Null, если читаемого манифеста нет.
  */
 export function readProjectProfile(baseDir) {
     const manifest = detectManifest(baseDir);
@@ -157,7 +158,7 @@ export function readProjectProfile(baseDir) {
             return null;
     }
 }
-/** One-line stack-neutral summary of the project profile. */
+/** Однострочная стек-нейтральная сводка профиля проекта. */
 export function formatProjectProfile(profile) {
     const parts = [];
     if (profile.deps.length > 0) {
@@ -174,8 +175,8 @@ export function formatProjectProfile(profile) {
     return `[Stack: ${profile.runtime}${name} — ${parts.join(" | ")}]`;
 }
 /**
- * Convenience: detect + read + format in one call. Returns null when the
- * workspace has no readable manifest.
+ * Удобно: detect + read + format одним вызовом. Null, если в проекте нет
+ * читаемого манифеста.
  */
 export function buildProjectProfileLine(baseDir) {
     const profile = readProjectProfile(baseDir);

package/dist/modules/indexer/symbols.js

@@ -1,16 +1,16 @@
 /**
- * Language registry and symbol extraction for the project index.
+ * Реестр языков и извлечение символов для индекса проекта.
  *
- * Adding a language = one entry in `RULES` + one or more extensions in
- * `EXT_TO_LANGUAGE`. Each rule declares whether the language is source code
- * (used for map ranking) and how to pull public/exported symbol names out of
- * a file. Extraction is regex-based on purpose (no parser dependency): it is
- * cheap, runs on every indexed file, and only needs enough structure to make
- * the project map useful — not a full AST.
+ * Новый язык = одна запись в `RULES` + одно или больше расширений в
+ * `EXT_TO_LANGUAGE`. Каждое правило объявляет, код ли это (для ранжирования
+ * карты) и как тянуть публичные/экспортные имена из файла. Извлечение
+ * regex-based осознанно (без зависимости от парсера): дёшево, гоняется на
+ * каждом индексируемом файле, и структуры хватает для полезности карты —
+ * полный AST не нужен.
  */
-/** Cap per file so a single generated file cannot blow up the map. */
+/** Кап на файл: один генерированный файл не раздувает карту. */
 export const MAX_SYMBOLS_PER_FILE = 40;
-/** Unique preserved-order names. */
+/** Уникальные имена с сохранением порядка. */
 function dedupe(names) {
     const seen = new Set();
     const out = [];
@@ -22,7 +22,7 @@ function dedupe(names) {
     }
     return out;
 }
-/** Collect captured group 1 from a list of global (multiline) regexes. */
+/** Собирает группу 1 совпадений по списку глобальных (многострочных) regex'ов. */
 function collect(content, patterns) {
     const names = [];
     for (const re of patterns) {
@@ -37,7 +37,7 @@ function collect(content, patterns) {
     }
     return names;
 }
-/** Names from `export { a, b as c }` / `export type { X }` clauses. */
+/** Имена из клауз `export { a, b as c }` / `export type { X }`. */
 function collectExportClauses(content) {
     const names = [];
     const re = /export\s+(?:type\s+)?\{([^}]*)\}/g;
@@ -168,22 +168,22 @@ const EXT_TO_LANGUAGE = {
     ".scss": "css",
     ".less": "css",
 };
-/** Language id for a file extension (lowercase, with dot), or null if not indexed. */
+/** Id языка по расширению (lowercase, с точкой), или null если не индексируем. */
 export function languageIdForExt(ext) {
     return EXT_TO_LANGUAGE[ext.toLowerCase()] ?? null;
 }
-/** True when the language is source code (affects project-map ranking). */
+/** True, если язык — исходный код (влияет на ранжирование карты). */
 export function isCodeLanguage(languageId) {
     return RULES[languageId]?.code ?? false;
 }
-/** Extract public/exported symbol names from file content. */
+/** Извлекает публичные/экспортные имена символов из содержимого файла. */
 export function extractSymbols(content, languageId) {
     const rule = RULES[languageId];
     if (!rule)
         return [];
     return dedupe(rule.extract(content)).slice(0, MAX_SYMBOLS_PER_FILE);
 }
-/** All indexed extensions (for docs/tests). */
+/** Все индексируемые расширения (для доков/тестов). */
 export function indexedExtensions() {
     return Object.keys(EXT_TO_LANGUAGE).sort();
 }

package/dist/modules/indexer/walker.js

@@ -1,14 +1,16 @@
-import { readdirSync, readFileSync, statSync, lstatSync, existsSync, watch } from "fs";
+// Обход дерева проекта: индекс файлов с символами, вотчер, сигнатура дерева.
+import { readdirSync, readFileSync, statSync, lstatSync, existsSync, watch, } from "fs";
+import { createHash } from "node:crypto";
 import { join, relative, extname } from "path";
 import { Logger } from "../../logger/app-logger";
 import { languageIdForExt, extractSymbols } from "./symbols";
 import { t } from "../../i18n/index";
 const logger = new Logger("warn", "indexer");
 /**
- * Directories that never hold project source but would flood the index:
- * VCS/build output, package caches and virtual environments across
- * ecosystems (Node, Python, Rust, Go/PHP/Ruby, JVM, .NET, Apple, IDE).
- * Stored lowercase — matching is case-insensitive (Windows/macOS).
+ * Каталоги, где исходников проекта не бывает, но индекс бы утонул:
+ * VCS/артефакты сборки, кэши пакетов и виртуалки всех экосистем
+ * (Node, Python, Rust, Go/PHP/Ruby, JVM, .NET, Apple, IDE).
+ * Хранятся в lowercase — сравнение регистронезависимо (Windows/macOS).
  */
 const IGNORE_DIRS = new Set([
     // VCS / MMA
@@ -16,7 +18,13 @@ const IGNORE_DIRS = new Set([
     ".hg",
     ".svn",
     ".mma",
-    // Node / JS bundlers
+    // Каталоги dev/agent/тулинга MMA — не исходники проекта (зеркало .gitignore:
+    // карта dev-чекаута не тонет в тестовых песочницах / агентском скратче).
+    "_testing",
+    ".superpowers",
+    ".opencode",
+    ".fallow",
+    // Node / JS-бандлеры
     "node_modules",
     "dist",
     "build",
@@ -51,22 +59,45 @@ const IGNORE_DIRS = new Set([
     // Apple
     "pods",
     "deriveddata",
-    // IDE / editor
+    // IDE / редакторы
     ".idea",
     ".vscode",
 ]);
-/** True when a directory name is ignored (case-insensitive). */
+/** True, если имя каталога игнорируется (регистронезависимо). */
 export function isIgnoredDirName(name) {
     return IGNORE_DIRS.has(name.toLowerCase());
 }
+/** Локфайлы — генерированы, не исходники проекта. */
+const IGNORE_FILE_NAMES = new Set([
+    "package-lock.json",
+    "bun.lock",
+    "bun.lockb",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    // Вендоренные веб-бандлы (минифицированы; их символы — шум).
+    "hljs.js",
+    "smd.js",
+]);
+/** Семейства конфигов/бейзлайнов тулинга — не исходники проекта. */
+const IGNORE_FILE_PREFIXES = [".fallow"];
+/** True, если имя файла игнорируется (регистронезависимый префикс/точное совпадение). */
+export function isIgnoredFileName(name) {
+    const lower = name.toLowerCase();
+    return (IGNORE_FILE_NAMES.has(lower) ||
+        lower.endsWith(".min.js") ||
+        IGNORE_FILE_PREFIXES.some((p) => lower.startsWith(p)));
+}
 /**
- * True when any path SEGMENT is an ignored directory. Segment-based (not a
- * substring) so short names like `env`/`out`/`obj` do not black out
- * `environment.ts` or `about/`.
+ * True, если ЛЮБОЙ СЕГМЕНТ пути — игнорируемый каталог. Посегментно (не
+ * подстрока): короткие имена `env`/`out`/`obj` не должны вычёркивать
+ * `environment.ts` или `about/`.
  */
 function isIgnoredPath(filename) {
-    return filename.split(/[\\/]/).some((segment) => isIgnoredDirName(segment));
+    const segments = filename.split(/[\\/]/);
+    const base = segments[segments.length - 1] ?? "";
+    return segments.some((segment) => isIgnoredDirName(segment)) || isIgnoredFileName(base);
 }
+/** Индексер: обход исходников, вотчер, сигнатура дерева, сводка. */
 export class Indexer {
     baseDir;
     MAX_FILES = 1000;
@@ -74,22 +105,91 @@ export class Indexer {
     constructor(baseDir) {
         this.baseDir = baseDir;
     }
+    /** Подписка на изменения дерева (игнорируемые пути не пробрасываются). */
     watch(callback) {
-        this.watcher = watch(this.baseDir, { recursive: true }, (event, filename) => {
+        const handler = (event, filename) => {
             if (filename && !isIgnoredPath(filename)) {
                 callback(event, filename);
             }
-        });
+        };
+        try {
+            // Рекурсивный вотч работает на macOS/Windows; на Linux опция игнорируется
+            // или бросает в зависимости от сборки Node — ниже фолбэк.
+            this.watcher = watch(this.baseDir, { recursive: true }, handler);
+        }
+        catch {
+            this.watcher = this.watchNonRecursive(handler);
+        }
     }
+    /**
+     * Linux-фолбэк: `fs.watch(recursive)` только для macOS/Windows, поэтому
+     * смотрим каждый неигнорируемый подкаталог отдельно (нерекурсивно).
+     * Best-effort: подкаталоги, созданные после `watch()`, требуют ручного refresh.
+     */
+    watchNonRecursive(callback) {
+        const watchers = [];
+        const collectDirs = (dir, out) => {
+            let entries;
+            try {
+                entries = readdirSync(dir);
+            }
+            catch {
+                return;
+            }
+            out.push(dir);
+            for (const entry of entries) {
+                const fullPath = join(dir, entry);
+                try {
+                    const lst = lstatSync(fullPath, { throwIfNoEntry: false });
+                    if (!lst || lst.isSymbolicLink())
+                        continue;
+                    if (statSync(fullPath).isDirectory() && !isIgnoredDirName(entry)) {
+                        collectDirs(fullPath, out);
+                    }
+                }
+                catch {
+                    // Нечитаемая запись — пропускаем, идём по остальным.
+                }
+            }
+        };
+        const dirs = [];
+        collectDirs(this.baseDir, dirs);
+        for (const dir of dirs) {
+            try {
+                watchers.push(watch(dir, callback));
+            }
+            catch (e) {
+                logger.warn(`watch failed for ${dir}: ${e.message}`);
+            }
+        }
+        if (watchers.length === 0) {
+            logger.warn("file watcher unavailable: no directories could be watched");
+        }
+        return watchers;
+    }
+    /** Отписывается от вотчера. */
     unwatch() {
         if (this.watcher) {
-            this.watcher.close();
+            const all = Array.isArray(this.watcher) ? this.watcher : [this.watcher];
+            for (const w of all) {
+                try {
+                    w.close();
+                }
+                catch {
+                    // Уже закрыт — нечего делать.
+                }
+            }
             this.watcher = null;
         }
     }
-    async walk() {
-        const files = [];
-        let totalSize = 0;
+    /**
+     * Обходит каждый индексируемый исходник под `baseDir` и зовёт `visit` с
+     * полным путём, относительным путём, id языка и stat. Уважает `MAX_FILES` и
+     * `IGNORE_DIRS`; содержимое НЕ читает — `walk()` читает его для извлечения
+     * символов, а `scanSignature()` пользуется только stat. Общий, чтобы оба
+     * прохода видели ровно то же множество файлов.
+     */
+    eachSourceFile(visit) {
         let count = 0;
         const walkDir = (dir) => {
             if (!existsSync(dir))
@@ -106,9 +206,9 @@ export class Indexer {
                     return;
                 const fullPath = join(dir, entry);
                 const relPath = relative(this.baseDir, fullPath);
-                // Per-entry isolation: a file deleted (or unreadable) between readdir
-                // and stat must not kill the whole walk. Symlinks are skipped — they
-                // can point outside the project or create directory cycles.
+                // Изоляция на запись: файл, удалённый (или нечитаемый) между readdir
+                // и stat, не должен убивать весь обход. Симлинки пропускаем — могут
+                // вести наружу или образовывать циклы каталогов.
                 try {
                     const lst = lstatSync(fullPath, { throwIfNoEntry: false });
                     if (!lst || lst.isSymbolicLink())
@@ -120,27 +220,57 @@ export class Indexer {
                         }
                     }
                     else if (stat.isFile()) {
-                        const ext = extname(entry).toLowerCase();
-                        const language = languageIdForExt(ext);
+                        if (isIgnoredFileName(entry))
+                            continue;
+                        const language = languageIdForExt(extname(entry).toLowerCase());
                         if (language) {
-                            const content = readFileSync(fullPath, "utf-8");
-                            const exports = extractSymbols(content, language);
-                            files.push({ path: relPath, language, exports, size: stat.size });
-                            totalSize += stat.size;
+                            visit(fullPath, relPath, language, stat);
                             count++;
                         }
                     }
                 }
                 catch (e) {
-                    // Entry vanished or is unreadable — skip it, keep indexing the rest.
+                    // Запись пропала или нечитаема — пропускаем, индексируем остальные.
                     logger.warn(t("env.index_skip_unreadable", { path: relPath }), { error: String(e) });
-                    continue;
                 }
             }
         };
         walkDir(this.baseDir);
+    }
+    /** Полный обход: читает файлы, извлекает символы. Нечитаемые пропускает. */
+    async walk() {
+        const files = [];
+        let totalSize = 0;
+        this.eachSourceFile((fullPath, relPath, language, stat) => {
+            try {
+                const content = readFileSync(fullPath, "utf-8");
+                const exports = extractSymbols(content, language);
+                files.push({ path: relPath, language, exports, size: stat.size });
+                totalSize += stat.size;
+            }
+            catch (e) {
+                // Чтение упало после успешного stat — пропускаем файл, берём остальные.
+                logger.warn(t("env.index_skip_unreadable", { path: relPath }), { error: String(e) });
+            }
+        });
         return { files, totalSize };
     }
+    /**
+     * Дешёвый бесконтентный отпечаток индексируемого дерева: отсортированные
+     * `path\0size\0mtimeMs`, хешированные SHA-1. `IndexCache` хранит его и
+     * пересчитывает на load, отбраковывая протухший `index-cache.json` (файл
+     * добавлен/удалён/правлен после обхода — сигнатура меняется). Только stat,
+     * без чтения файлов — куда дешевле полного обхода.
+     */
+    scanSignature() {
+        const parts = [];
+        this.eachSourceFile((_fullPath, relPath, _language, stat) => {
+            parts.push(`${relPath}\u0000${stat.size}\u0000${Math.floor(stat.mtimeMs)}`);
+        });
+        parts.sort();
+        return createHash("sha1").update(parts.join("\n")).digest("hex");
+    }
+    /** Однострочная сводка индекса (файлы, размер, языки). */
     summarize(result) {
         const byLang = {};
         for (const f of result.files) {