@archora/core 1.1.0 → 1.3.0

package/src/analyzer/rsc.ts

@@ -6,14 +6,15 @@
 //      conventions (Next app/, Nuxt server/, SvelteKit `+server.ts`/
 //      `*.server.*`).
 //   2. `detectRscLeaks` - emits a `ContractViolation` (`kind: 'rsc-leak'`)
-//      for every static edge crossing a hard boundary (server importing
-//      client, client importing server-only).
+//      for every client->server boundary crossing: a direct edge, and a
+//      transitive one (client -> shared chain -> server), the classic
+//      barrel/re-export leak that fails the Next build.
 //
-// Directives win over conventions. A `'use client'` file in `app/` is
-// client. `server-only` / `client-only` packages are not modeled separately
-// here - the directive system covers the same cases for first-party code,
-// and we don't have a way to type-check third-party code without doing real
-// resolution.
+// Runtime classification precedence: directives (`'use client'` / `'use server'`)
+// win, then the `server-only` / `client-only` packages (Next's own poison-package
+// enforcement - an explicit, framework-independent runtime declaration), then
+// framework folder conventions. Passing server-only *data* as props into a client
+// component needs data-flow analysis and is out of scope (would be high-FP).
 
 import type { ContractViolation } from './contracts';
 import type { DependencyEdge, ModuleId, ModuleNode, ModuleRuntime, ParsedFile } from './types';
@@ -23,6 +24,10 @@ export interface ClassifyRuntimeInput {
   relPath: string;
   framework: Framework;
   directives?: ParsedFile['directives'];
+  /** File imports the `server-only` package (Next's poison package — throws if bundled for the client). */
+  importsServerOnly?: boolean;
+  /** File imports the `client-only` package. */
+  importsClientOnly?: boolean;
 }
 
 export function classifyModuleRuntime(input: ClassifyRuntimeInput): ModuleRuntime {
@@ -32,9 +37,14 @@ export function classifyModuleRuntime(input: ClassifyRuntimeInput): ModuleRuntim
     if (input.directives.includes('use client')) return 'client';
   }
 
+  // 2. `server-only` / `client-only` packages — an explicit runtime declaration,
+  //    framework-independent (this is Next RSC's own enforcement mechanism, not a convention).
+  if (input.importsServerOnly) return 'server';
+  if (input.importsClientOnly) return 'client';
+
   const path = input.relPath.replace(/\\/gu, '/');
 
-  // 2. SvelteKit conventions (work for any framework value because users
+  // 3. SvelteKit conventions (work for any framework value because users
   //    pin them by file name, not framework detection):
   //    - `+server.ts` / `+server.js` -> endpoint, server only
   //    - `*.server.ts` (and `+page.server.ts`, `+layout.server.ts`) -> server
@@ -45,7 +55,7 @@ export function classifyModuleRuntime(input: ClassifyRuntimeInput): ModuleRuntim
   if (/\.client\.[mc]?[jt]sx?$/u.test(path)) return 'client';
   if (/(^|\/)\+(?:page|layout)\.svelte$/u.test(path)) return 'client';
 
-  // 3. Framework-specific folder conventions.
+  // 4. Framework-specific folder conventions.
   if (input.framework === 'next') {
     // Next App Router: `app/` files are server components by default.
     // The 'use client' directive (handled above) opts a tree into client.
@@ -80,6 +90,7 @@ export function detectRscLeaks(input: DetectRscLeaksInput): ContractViolation[]
 
   const out: ContractViolation[] = [];
   let serial = 0;
+  const directLeaks = new Set<string>();
 
   for (const e of input.edges) {
     if (e.kind === 'type-only') continue;
@@ -88,6 +99,7 @@ export function detectRscLeaks(input: DetectRscLeaksInput): ContractViolation[]
     if (!from || !to) continue;
     const leak = classifyLeak(from.runtime ?? 'shared', to.runtime ?? 'shared');
     if (!leak) continue;
+    directLeaks.add(`${from.id}->${to.id}`);
     out.push({
       id: `rsc-leak:${serial++}:${e.from}\u0001${e.to}`,
       kind: 'rsc-leak',
@@ -98,6 +110,58 @@ export function detectRscLeaks(input: DetectRscLeaksInput): ContractViolation[]
       edge: { from: from.id, to: to.id, specifier: e.specifier },
     });
   }
+
+  // Transitive leaks: a client module pulls server-only code through a chain of
+  // shared modules (the classic barrel/re-export leak — in Next this is a build
+  // error, since the shared chain plus the server code lands in the client bundle).
+  // Walk from each client module through shared intermediates only; sink = server.
+  // Direct client→server edges are already handled above.
+  const adj = new Map<ModuleId, ModuleId[]>();
+  for (const e of input.edges) {
+    if (e.kind === 'type-only') continue;
+    let bucket = adj.get(e.from);
+    if (!bucket) {
+      bucket = [];
+      adj.set(e.from, bucket);
+    }
+    bucket.push(e.to);
+  }
+  const rt = (id: ModuleId): ModuleRuntime => moduleById.get(id)?.runtime ?? 'shared';
+  const seenTransitive = new Set<string>();
+  for (const c of input.modules) {
+    if ((c.runtime ?? 'shared') !== 'client') continue;
+    const visitedShared = new Set<ModuleId>();
+    const queue: ModuleId[] = [];
+    for (const to of adj.get(c.id) ?? []) {
+      if (rt(to) === 'shared' && !visitedShared.has(to)) {
+        visitedShared.add(to);
+        queue.push(to);
+      }
+    }
+    while (queue.length > 0) {
+      const node = queue.shift()!;
+      for (const to of adj.get(node) ?? []) {
+        const toRt = rt(to);
+        if (toRt === 'server') {
+          const key = `${c.id}->${to}`;
+          if (directLeaks.has(key) || seenTransitive.has(key)) continue;
+          seenTransitive.add(key);
+          out.push({
+            id: `rsc-leak:${serial++}:${key}`,
+            kind: 'rsc-leak',
+            ruleName: 'rsc-leak',
+            severity: 'error',
+            message: `client module "${c.id}" transitively imports server-only "${to}" through shared module(s)`,
+            modules: [c.id, to],
+            edge: { from: c.id, to, specifier: to },
+          });
+        } else if (toRt === 'shared' && !visitedShared.has(to)) {
+          visitedShared.add(to);
+          queue.push(to);
+        }
+      }
+    }
+  }
   return out;
 }
 

package/src/analyzer/sources/browserFsAccessFileSource.ts

@@ -8,7 +8,7 @@ export interface BrowserFsAccessFileSourceOptions {
   rootHandle: FileSystemDirectoryHandle;
   rootName?: string;
   onProgress?: (visited: number) => void;
-  /** Если true (по умолчанию) - не заходим в тест/storybook/cypress/playwright директории. */
+  /** If true (default) - skip test/storybook/cypress/playwright directories. */
   skipTestLikeDirs?: boolean;
   /** Read `.gitignore` from root and filter the listing. Default: true. */
   respectGitignore?: boolean;

package/src/analyzer/sources/nodeFsFileSource.ts

@@ -10,7 +10,7 @@ export interface NodeFsFileSourceOptions {
   rootPath: string;
   respectGitignore?: boolean;
   extraIgnore?: string[];
-  /** Если true (по умолчанию) - не заходим в тест/storybook/cypress/playwright директории. */
+  /** If true (default) - skip test/storybook/cypress/playwright directories. */
   skipTestLikeDirs?: boolean;
 }
 

package/src/analyzer/sources/tauriFileSource.ts

@@ -8,9 +8,9 @@ export interface TauriFileSourceOptions {
   rootPath: string;
   rootName?: string;
   invoke: TauriInvoke;
-  /** Дополнительные ignore-globs (gitignore-синтаксис), напр. ['*.test.ts']. */
+  /** Extra ignore globs (gitignore syntax), e.g. ['*.test.ts']. */
   extraIgnoreGlobs?: string[];
-  /** Жёсткий лимит размера читаемого файла, байт. По умолчанию 2 МБ. */
+  /** Hard limit on the size of a file to read, in bytes. Default 2 MB. */
   maxFileBytes?: number;
 }
 

package/src/analyzer/types.ts

@@ -401,6 +401,11 @@ export interface ParsedFile {
   directives?: ('use server' | 'use client')[];
   /** PascalCase component tags from <template>, resolved against the component registry in buildGraph. */
   templateRefs?: string[];
+  /**
+   * Identifiers called as a function (`foo(...)`, not `obj.foo(...)`).
+   * Used to resolve Nuxt auto-import composables in buildGraph.
+   */
+  callIdentifiers?: string[];
 }
 
 export type SignalSeverity = 'info' | 'low' | 'medium' | 'high' | 'critical';

package/src/git/__tests__/computeTemporalCoupling.test.ts

@@ -122,4 +122,28 @@ describe('computeTemporalCoupling', () => {
     expect(out[0]?.a).toBe('src/c.ts');
     expect(out[1]?.hidden).toBe(false);
   });
+
+  it('ranks a cross-boundary hidden coupling above an equally-strong same-folder one', () => {
+    const modules = ['features/auth/a.ts', 'entities/user/b.ts', 'shared/x.ts', 'shared/y.ts'].map(
+      mod,
+    );
+    const h = history([
+      commit('1', ['features/auth/a.ts', 'entities/user/b.ts']),
+      commit('2', ['features/auth/a.ts', 'entities/user/b.ts']),
+      commit('3', ['features/auth/a.ts', 'entities/user/b.ts']),
+      commit('4', ['shared/x.ts', 'shared/y.ts']),
+      commit('5', ['shared/x.ts', 'shared/y.ts']),
+      commit('6', ['shared/x.ts', 'shared/y.ts']),
+    ]);
+    const out = computeTemporalCoupling({ modules, edges: NO_EDGES, history: h });
+    expect(out).toHaveLength(2);
+    // Both are hidden, score 1.0, 3 co-occurrences — only the boundary differs.
+    const cross = out.find((c) => c.a === 'entities/user/b.ts' || c.b === 'entities/user/b.ts');
+    const same = out.find((c) => c.a === 'shared/x.ts' && c.b === 'shared/y.ts');
+    expect(cross?.crossBoundary).toBe(true);
+    expect(same?.crossBoundary).toBe(false);
+    expect(cross!.risk).toBeGreaterThan(same!.risk);
+    expect(out[0]).toBe(cross); // cross-boundary ranks first
+    expect(cross!.risk).toBeLessThanOrEqual(1);
+  });
 });

package/src/git/computeTemporalCoupling.ts

@@ -72,13 +72,15 @@ export function computeTemporalCoupling(input: ComputeTemporalCouplingInput): Te
     const score = Math.min(scoreA, scoreB);
     if (score < t.minScore) continue;
     const hidden = !staticPairs.has(key);
-    out.push({ a, b, coOccurrences: n, scoreA, scoreB, score, hidden });
+    const crossBoundary = topBoundary(a) !== topBoundary(b);
+    const risk = couplingRisk(score, n, hidden, crossBoundary);
+    out.push({ a, b, coOccurrences: n, scoreA, scoreB, score, hidden, crossBoundary, risk });
   }
 
-  // Hidden couplings first (most informative), then by score, then by
+  // By risk (encodes hidden + cross-boundary + evidence), then score, then
   // co-occurrences, then alphabetically — stable across runs.
   out.sort((x, y) => {
-    if (x.hidden !== y.hidden) return x.hidden ? -1 : 1;
+    if (y.risk !== x.risk) return y.risk - x.risk;
     if (y.score !== x.score) return y.score - x.score;
     if (y.coOccurrences !== x.coOccurrences) return y.coOccurrences - x.coOccurrences;
     return x.a.localeCompare(y.a) || x.b.localeCompare(y.b);
@@ -102,6 +104,31 @@ function collectTouchedModules(
   return [...touched].sort();
 }
 
+// Top-level module group: first path segment after an optional `src/`. Files
+// directly under the root share the '' group, so two of them are NOT cross-
+// boundary. For FSD this is the layer (features/entities/shared/...).
+function topBoundary(id: string): string {
+  const p = id.startsWith('src/') ? id.slice(4) : id;
+  const i = p.indexOf('/');
+  return i === -1 ? '' : p.slice(0, i);
+}
+
+// Actionability score. Strength (`score`) tempered by evidence volume, boosted
+// when the coupling is hidden (the static graph doesn't already reveal it) and
+// when it crosses a module boundary (missing-abstraction smell). Capped at 1.
+function couplingRisk(
+  score: number,
+  coOccurrences: number,
+  hidden: boolean,
+  crossBoundary: boolean,
+): number {
+  const evidence = Math.min(1, coOccurrences / 10);
+  let risk = score * (0.5 + 0.5 * evidence);
+  risk *= hidden ? 1.25 : 0.6;
+  if (hidden && crossBoundary) risk *= 1.15;
+  return Math.min(1, Math.round(risk * 1000) / 1000);
+}
+
 function collectStaticPairs(edges: DependencyEdge[]): Set<string> {
   const out = new Set<string>();
   for (const e of edges) {

package/src/git/types.ts

@@ -92,7 +92,7 @@ export interface TemporalCoupling {
   scoreA: number;
   /** `coOccurrences / commits(b)`. */
   scoreB: number;
-  /** `min(scoreA, scoreB)` — the symmetric, conservative score. Sorting key. */
+  /** `min(scoreA, scoreB)` — the symmetric, conservative score. */
   score: number;
   /**
    * True when there is no static import edge between `a` and `b` in either
@@ -100,6 +100,19 @@ export interface TemporalCoupling {
    * informative ones, because the static graph already exposes the rest.
    */
   hidden: boolean;
+  /**
+   * True when `a` and `b` live in different top-level module groups (FSD layer
+   * / first path segment). A hidden + cross-boundary coupling is the strongest
+   * "missing abstraction / leaky boundary" signal — and one a pure-git tool
+   * (no architecture model) cannot produce.
+   */
+  crossBoundary: boolean;
+  /**
+   * Actionability score (0..1): coupling strength tempered by evidence
+   * (`coOccurrences`), boosted when `hidden` and when `crossBoundary`. Primary
+   * sort key.
+   */
+  risk: number;
 }
 
 export interface TemporalCouplingThresholds {

package/src/search/__tests__/parseQuery.test.ts

@@ -2,65 +2,65 @@ import { describe, expect, it } from 'vitest';
 import { parseQuery, isEmpty } from '../parseQuery';
 
 describe('parseQuery', () => {
-  it('пустая строка → пустой query', () => {
+  it('empty string → empty query', () => {
     const q = parseQuery('');
     expect(q.free).toEqual([]);
     expect(q.prefixes).toEqual({});
     expect(isEmpty(q)).toBe(true);
   });
 
-  it('один free-token без префиксов', () => {
+  it('single free token without prefixes', () => {
     expect(parseQuery('useAuth')).toEqual({ free: ['useAuth'], prefixes: {} });
   });
 
-  it('один префикс path:', () => {
+  it('single path: prefix', () => {
     expect(parseQuery('path:src/features')).toEqual({
       free: [],
       prefixes: { path: ['src/features'] },
     });
   });
 
-  it('несколько префиксов разных ключей = AND-пересечение', () => {
+  it('several prefixes of different keys = AND intersection', () => {
     const q = parseQuery('kind:component path:auth');
     expect(q).toEqual({ free: [], prefixes: { kind: ['component'], path: ['auth'] } });
   });
 
-  it('несколько одинаковых префиксов = OR внутри ключа', () => {
+  it('several identical prefixes = OR within a key', () => {
     const q = parseQuery('kind:component kind:composable');
     expect(q.prefixes.kind).toEqual(['component', 'composable']);
   });
 
-  it('префикс + free-text смешаны', () => {
+  it('prefix + free-text mixed', () => {
     expect(parseQuery('useAuth kind:composable')).toEqual({
       free: ['useAuth'],
       prefixes: { kind: ['composable'] },
     });
   });
 
-  it('значение префикса в кавычках допускает пробелы', () => {
+  it('quoted prefix value allows spaces', () => {
     const q = parseQuery('path:"src/feature x"');
     expect(q.prefixes.path).toEqual(['src/feature x']);
   });
 
-  it('неизвестный префикс — фолбэк в free-text целиком', () => {
-    // `foo:bar` не известный prefix → токен целиком уходит в free
+  it('unknown prefix — falls back to free-text in full', () => {
+    // `foo:bar` is not a known prefix → the whole token goes to free
     expect(parseQuery('foo:bar')).toEqual({ free: ['foo:bar'], prefixes: {} });
   });
 
-  it('пустое значение префикса — игнорируется', () => {
-    // `kind:` без значения — не добавляет ключа
+  it('empty prefix value — ignored', () => {
+    // `kind:` with no value — does not add a key
     const q = parseQuery('kind: hello');
     expect(q.prefixes.kind).toBeUndefined();
     expect(q.free).toContain('hello');
   });
 
-  it('case-insensitive ключи, case-sensitive значения', () => {
+  it('case-insensitive keys, case-sensitive values', () => {
     const q = parseQuery('KIND:Component PATH:Auth');
     expect(q.prefixes.kind).toEqual(['Component']);
     expect(q.prefixes.path).toEqual(['Auth']);
   });
 
-  it('export / import префиксы работают', () => {
+  it('export / import prefixes work', () => {
     const q = parseQuery('export:useAuth import:react-query');
     expect(q.prefixes).toEqual({ export: ['useAuth'], import: ['react-query'] });
   });

package/src/search/__tests__/search.test.ts

@@ -1,7 +1,7 @@
-// search() работает на полностью искусственном ScanResult — нам важна
-// логика ранкера и префикс-фильтров, а не парсер. Минимально-валидный
-// fixture-builder ниже соблюдает форму типов, но не претендует на
-// семантическую полноту (нет цикл-/метрик-ссылок).
+// search() runs on a fully synthetic ScanResult — what matters is the ranker
+// and prefix-filter logic, not the parser. The minimally valid fixture
+// builder below honors the shape of the types but does not claim semantic
+// completeness (no cycle/metric cross-references).
 
 import { describe, expect, it } from 'vitest';
 import type {
@@ -96,30 +96,30 @@ const FIXTURE = buildScan([
 ]);
 
 describe('search', () => {
-  it('пустой query → пустая выдача', () => {
+  it('empty query → empty output', () => {
     expect(search(FIXTURE, '')).toEqual([]);
     expect(search(FIXTURE, '   ')).toEqual([]);
   });
 
-  it('export:useAuth находит composable', () => {
+  it('export:useAuth finds the composable', () => {
     const r = search(FIXTURE, 'export:useAuth');
     expect(r.map((x) => x.id)).toEqual(['src/features/auth/composables/useAuth.ts']);
     expect(r[0]!.matched).toContain('export');
     expect(r[0]!.highlights.export).toContain('useAuth');
   });
 
-  it('import:react-query находит модули с этим specifier', () => {
+  it('import:react-query finds modules with that specifier', () => {
     const r = search(FIXTURE, 'import:react-query');
     expect(r.map((x) => x.id)).toEqual(['src/features/checkout/CheckoutForm.vue']);
     expect(r[0]!.matched).toContain('import');
   });
 
-  it('kind:store фильтрует по типу', () => {
+  it('kind:store filters by kind', () => {
     const r = search(FIXTURE, 'kind:store');
     expect(r.map((x) => x.id)).toEqual(['src/stores/userStore.ts']);
   });
 
-  it('path:features ищет substring в path (case-insensitive)', () => {
+  it('path:features matches a substring in path (case-insensitive)', () => {
     const r = search(FIXTURE, 'path:Features');
     const ids = r.map((x) => x.id);
     expect(ids).toContain('src/features/auth/composables/useAuth.ts');
@@ -127,12 +127,12 @@ describe('search', () => {
     expect(ids).not.toContain('src/shared/lib/api.ts');
   });
 
-  it('AND-пересечение: kind:component path:auth', () => {
+  it('AND intersection: kind:component path:auth', () => {
     const r = search(FIXTURE, 'kind:component path:auth');
     expect(r.map((x) => x.id)).toEqual(['src/features/auth/AuthForm.vue']);
   });
 
-  it('OR внутри ключа: kind:component kind:composable', () => {
+  it('OR within a key: kind:component kind:composable', () => {
     const r = search(FIXTURE, 'kind:component kind:composable');
     const ids = new Set(r.map((x) => x.id));
     expect(ids.has('src/features/auth/AuthForm.vue')).toBe(true);
@@ -140,32 +140,32 @@ describe('search', () => {
     expect(ids.has('src/stores/userStore.ts')).toBe(false);
   });
 
-  it('free-text без префикса: ранкер находит совпадения по path и exports', () => {
+  it('free-text without a prefix: ranker finds matches by path and exports', () => {
     const r = search(FIXTURE, 'useAuth');
-    // useAuth.ts должен быть на верху (точное совпадение exports + basename)
+    // useAuth.ts must be at the top (exact exports match + basename)
     expect(r[0]!.id).toBe('src/features/auth/composables/useAuth.ts');
     expect(r[0]!.score).toBeGreaterThan(0.5);
   });
 
-  it('точное совпадение basename ранжируется выше substring-совпадения', () => {
+  it('exact basename match ranks above a substring match', () => {
     const r = search(FIXTURE, 'useAuth');
-    // useAuth.ts — basename match; AuthForm.vue — только path-substring
+    // useAuth.ts — basename match; AuthForm.vue — path substring only
     expect(r[0]!.id).toBe('src/features/auth/composables/useAuth.ts');
     const formIdx = r.findIndex((x) => x.id === 'src/features/auth/AuthForm.vue');
     if (formIdx > -1) expect(formIdx).toBeGreaterThan(0);
   });
 
-  it('limit обрезает выдачу', () => {
+  it('limit caps the output', () => {
     const r = search(FIXTURE, 'path:src', { limit: 2 });
     expect(r).toHaveLength(2);
   });
 
-  it('неизвестный kind не падает, просто не находит', () => {
+  it('unknown kind does not throw, just finds nothing', () => {
     expect(search(FIXTURE, 'kind:nonsense')).toEqual([]);
   });
 
-  it('SearchResult.matched может содержать несколько критериев одновременно', () => {
-    // useAuth: совпадает по export (через export:) и по path (через free-text)
+  it('SearchResult.matched may contain several criteria at once', () => {
+    // useAuth: matches by export (via export:) and by path (via free-text)
     const r = search(FIXTURE, 'export:useAuth auth');
     expect(r[0]!.matched).toEqual(expect.arrayContaining(['export', 'path']));
   });

package/src/search/index.ts

@@ -1,18 +1,18 @@
-// Глобальный поиск по `ScanResult` — без чтения файловой системы, только
-// по структурированным метаданным (modules + edges). Стратегия:
+// Global search over `ScanResult` — no filesystem reads, only structured
+// metadata (modules + edges). Strategy:
 //
-// 1. Парсим query (`parseQuery`).
-// 2. Для каждого префикса набираем set'ы ID-кандидатов; в финальный набор
-//    попадают только модули, прошедшие пересечение всех префиксов (AND).
-// 3. Поверх отфильтрованных модулей применяем free-text ранкинг
-//    (substring-match по path и exports) и сортируем по итоговому скору.
-// 4. Возвращаем разноимённые результаты с типом матча — UI рендерит pill-чипы
-//    «Path / Export / Import / Kind», поэтому каждому SearchResult нужно знать,
-//    почему он попал в выдачу.
+// 1. Parse the query (`parseQuery`).
+// 2. For each prefix collect sets of candidate IDs; only modules that pass
+//    the intersection of all prefixes (AND) make it into the final set.
+// 3. On top of the filtered modules apply free-text ranking (substring match
+//    over path and exports) and sort by the resulting score.
+// 4. Return results tagged with the match kind — the UI renders pill chips
+//    "Path / Export / Import / Kind", so each SearchResult must know why it
+//    ended up in the output.
 //
-// Не делаем: ripgrep по содержимому файлов, fuzzy-substring (типа
-// fzf-style scoring) — для path → modules.length обычно сотни, обычный
-// substring достаточен. Усложним, если появится сигнал «слишком шумно».
+// We do not: ripgrep over file contents, fuzzy substring (fzf-style scoring) —
+// for path → modules.length is usually in the hundreds, plain substring is
+// enough. We'll add complexity if a "too noisy" signal shows up.
 
 import type { ScanResult, ModuleId, ModuleKind } from '../analyzer/types';
 import { parseQuery, isEmpty, type ParsedQuery, type SearchPrefix } from './parseQuery';
@@ -24,20 +24,20 @@ export type MatchKind = 'path' | 'export' | 'import' | 'kind';
 export interface SearchResult {
   /** Module id (relative path). */
   id: ModuleId;
-  /** Какие критерии сработали — UI использует для подсветки чипов. */
+  /** Which criteria matched — the UI uses this to highlight chips. */
   matched: MatchKind[];
-  /** Score 0..1; 1 = идеальное соответствие, 0 = только prefix-фильтр прошёл. */
+  /** Score 0..1; 1 = perfect match, 0 = only the prefix filter passed. */
   score: number;
   /**
-   * Подсветочный hint для каждого совпавшего критерия — конкретные значения
-   * (имя экспорта, specifier импорта, kind). Используется панелью результатов
-   * для пояснения «почему этот модуль вылез на этот запрос».
+   * Highlight hint for each matched criterion — the concrete values
+   * (export name, import specifier, kind). Used by the results panel to
+   * explain "why this module surfaced for this query".
    */
   highlights: Partial<Record<MatchKind, string[]>>;
 }
 
 export interface SearchOptions {
-  /** Ограничить размер выдачи. По умолчанию 50 — типовой UI-overlay. */
+  /** Cap the output size. Defaults to 50 — a typical UI overlay. */
   limit?: number;
 }
 
@@ -54,17 +54,17 @@ export function search(
   const limit = options.limit ?? DEFAULT_LIMIT;
   const moduleIds = new Set(scan.modules.map((m) => m.id));
 
-  // 1. Префиксные фильтры выдают `Map<id, MatchKind[]> + highlights` —
-  // если префикс есть, попасть в выдачу можно только пройдя его.
+  // 1. Prefix filters yield `Map<id, MatchKind[]> + highlights` — if a prefix
+  // is present, a module can only reach the output by passing it.
   const prefixHits = collectPrefixHits(scan, parsed);
 
-  // Если есть префиксы — оставляем только модули, попавшие во все указанные.
+  // If there are prefixes — keep only modules that hit all of the given ones.
   const eligibleIds = applyPrefixIntersection(moduleIds, prefixHits, parsed.prefixes);
 
-  // 2. Free-text ранкинг. Если free пуст и префиксы есть — отдаём eligible
-  // как есть со скором 0.5 (нейтральный). Если free есть — считаем скор и
-  // отбрасываем модули, у которых ни один free-токен не сматчился, КОГДА
-  // префиксов нет; иначе free снижает скор, но не отсекает.
+  // 2. Free-text ranking. If free is empty and prefixes exist — return eligible
+  // as is with score 0.5 (neutral). If free is present — compute the score and
+  // drop modules where no free token matched WHEN there are no prefixes;
+  // otherwise free lowers the score but does not cut a module out.
   const results: SearchResult[] = [];
   for (const id of eligibleIds) {
     const module = scan.modules.find((m) => m.id === id);
@@ -72,7 +72,7 @@ export function search(
     const matched: MatchKind[] = [];
     const highlights: Partial<Record<MatchKind, string[]>> = {};
 
-    // соберём подтверждения от префикс-хитов
+    // collect confirmations from prefix hits
     for (const kind of ['path', 'export', 'import', 'kind'] as const) {
       const hit = prefixHits[kind].get(id);
       if (hit) {
@@ -95,7 +95,7 @@ export function search(
           (highlights.export ??= []).push(...f.matchedExports);
         }
       } else if (matched.length === 0) {
-        // Нет ни префикс-матча, ни free-матча: модуль вообще не попал.
+        // Neither a prefix match nor a free match: the module is out entirely.
         continue;
       }
     }
@@ -104,8 +104,8 @@ export function search(
     results.push({ id, matched, score, highlights });
   }
 
-  // 3. Сортировка: больший score → раньше; tiebreak по короче-путь → раньше
-  // (короткие пути обычно ближе к корню фичи, чем глубокие имплементации).
+  // 3. Sort: higher score → first; tiebreak by shorter path → first
+  // (short paths usually sit closer to a feature root than deep implementations).
   results.sort((a, b) => {
     if (b.score !== a.score) return b.score - a.score;
     return a.id.length - b.id.length;
@@ -157,7 +157,7 @@ function collectPrefixHits(scan: ScanResult, q: ParsedQuery): PrefixHits {
   }
 
   if (q.prefixes.import) {
-    // edges.specifier — оригинальная строка импорта; non-resolved тоже учитываем
+    // edges.specifier — the original import string; non-resolved are counted too
     const needles = q.prefixes.import;
     const matchedSpecifiersByModule = new Map<ModuleId, Set<string>>();
     for (const e of scan.edges) {
@@ -213,16 +213,16 @@ interface FreeTextMatch {
 }
 
 /**
- * Простой substring-ранкер. Не fuzzy: для типичной задачи «найди useAuth»
- * подстрока даёт стабильные результаты без шумовых матчей.
+ * Plain substring ranker. Not fuzzy: for the typical "find useAuth" task a
+ * substring gives stable results without noisy matches.
  *
- * Скоринг:
- * - Точное совпадение exports[i] === term: +0.5
+ * Scoring:
+ * - Exact match exports[i] === term: +0.5
  * - exports[i] contains term: +0.25
  * - basename(path) === term: +0.4
- * - path contains term: +0.2 (но в score раз — чтобы три совпадения не
- *   делали скор > 1)
- * Затем нормализуем в 0..1 по числу term'ов.
+ * - path contains term: +0.2 (but counted once in the score — so that three
+ *   matches don't push the score > 1)
+ * Then normalize to 0..1 by the number of terms.
  */
 function scoreFreeText(id: ModuleId, exports: readonly string[], terms: string[]): FreeTextMatch {
   let score = 0;
@@ -260,7 +260,7 @@ function scoreFreeText(id: ModuleId, exports: readonly string[], terms: string[]
     score += bestForTerm;
   }
 
-  // Нормализуем: максимум 0.5 за term — top score 1.0 при N term'ов.
+  // Normalize: max 0.5 per term — top score 1.0 with N terms.
   const normalized = terms.length > 0 ? Math.min(1, score / (terms.length * 0.5)) : 0;
   return {
     score: normalized,