@archora/core 1.1.0 → 2.0.0

package/src/git/computeTemporalCoupling.ts

@@ -30,7 +30,11 @@ const DEFAULTS: Required<TemporalCouplingThresholds> = {
   minCoOccurrences: 3,
   minScore: 0.5,
   maxPairs: 100,
-  commitFanOutCap: 50,
+  // Batch PRs (codegen bumps, "touch every composable" passes) co-change dozens
+  // of files at once and flood the raw list with same-group noise. A real
+  // architectural coupling shows up in small, focused commits, so cap fan-out
+  // tighter than a typical batch PR.
+  commitFanOutCap: 30,
 };
 
 export function computeTemporalCoupling(input: ComputeTemporalCouplingInput): TemporalCoupling[] {
@@ -72,13 +76,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 +108,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/index.ts

@@ -31,6 +31,11 @@ export {
   type FixPlanRepairGroup,
   type BuildFixPlanOptions,
 } from './report/buildFixPlan';
+export {
+  buildDeadCodeReport,
+  type DeadCodeReport,
+  type DeadCodeCandidate,
+} from './report/buildDeadCodeReport';
 export { diffScans, type ScanDiff, type ChangedModule, type ScanDiffSummary } from './diff/index';
 export { compileGlob } from './analyzer/discover';
 export {

package/src/report/__tests__/buildDeadCodeReport.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest';
+import { buildDeadCodeReport } from '../buildDeadCodeReport';
+import type { ScanResult } from '../../analyzer/types';
+
+describe('buildDeadCodeReport', () => {
+  it('returns candidates with correct groups and totalLoc, excluding non-qualifying modules', () => {
+    const scan = scanFixture();
+    const report = buildDeadCodeReport(scan);
+
+    // entry-kind, live module (fanIn>0), and test file must be excluded
+    const ids = report.candidates.map((c) => c.id);
+    expect(ids).not.toContain('src/app/main.ts');
+    expect(ids).not.toContain('src/features/active/model.ts');
+    expect(ids).not.toContain('src/utils/parse.test.ts');
+
+    // isolated source module and script-entry must be included
+    expect(ids).toContain('src/legacy/orphan.ts');
+    expect(ids).toContain('scripts/seed.mjs');
+
+    // groups
+    const orphan = report.candidates.find((c) => c.id === 'src/legacy/orphan.ts');
+    expect(orphan?.group).toBe('isolated');
+    expect(orphan?.loc).toBe(40);
+
+    const script = report.candidates.find((c) => c.id === 'scripts/seed.mjs');
+    expect(script?.group).toBe('script-entry');
+
+    // counts
+    expect(report.isolatedCount).toBe(1);
+    expect(report.scriptEntryCount).toBe(1);
+    expect(report.candidates).toHaveLength(2);
+
+    // totalLoc = sum of candidate locs
+    expect(report.totalLoc).toBe(40 + 8);
+
+    // sorted by loc desc
+    expect(report.candidates.map((c) => c.id)).toEqual([
+      'src/legacy/orphan.ts',
+      'scripts/seed.mjs',
+    ]);
+  });
+
+  it('returns an empty report when no dead modules exist', () => {
+    const report = buildDeadCodeReport({
+      ...scanFixture(),
+      modules: [mod('src/app/main.ts', 'entry', 20)],
+      metrics: {},
+    });
+    expect(report.candidates).toHaveLength(0);
+    expect(report.totalLoc).toBe(0);
+    expect(report.isolatedCount).toBe(0);
+    expect(report.scriptEntryCount).toBe(0);
+  });
+});
+
+function scanFixture(): ScanResult {
+  return {
+    project: { id: 'test', name: 'test', rootPath: '/repo', detectedFramework: 'generic' },
+    modules: [
+      mod('src/app/main.ts', 'entry', 15),
+      mod('src/features/active/model.ts', 'model', 30),
+      mod('src/legacy/orphan.ts', 'module', 40),
+      mod('scripts/seed.mjs', 'module', 8),
+      mod('src/utils/parse.test.ts', 'test', 20),
+    ],
+    edges: [],
+    cycles: [],
+    metrics: {
+      'src/app/main.ts': metric(1, 2),
+      'src/features/active/model.ts': metric(3, 1),
+      'src/legacy/orphan.ts': metric(0, 0),
+      'scripts/seed.mjs': metric(0, 0),
+      'src/utils/parse.test.ts': metric(0, 0),
+    },
+    hotZones: [],
+    layerViolations: [],
+    archDebt: {
+      score: 0,
+      grade: 'A',
+      breakdown: { cycles: 0, layerViolations: 0, hotZones: 0, coupling: 0 },
+    },
+    recommendations: [],
+    contractViolations: [],
+    scannedAt: '2026-06-21T00:00:00.000Z',
+    durationMs: 1,
+    warnings: [],
+  };
+}
+
+function mod(
+  id: string,
+  kind: ScanResult['modules'][number]['kind'],
+  loc: number,
+): ScanResult['modules'][number] {
+  return { id, absPath: `/repo/${id}`, kind, language: 'ts', loc, exports: [], isInfra: false };
+}
+
+function metric(fanIn: number, fanOut: number): ScanResult['metrics'][string] {
+  return {
+    fanIn,
+    fanOut,
+    instability: 0,
+    depth: 0,
+    inCycle: false,
+    couplingScore: 0,
+    hotnessScore: 0,
+  };
+}

package/src/report/buildDeadCodeReport.ts

@@ -0,0 +1,110 @@
+import type { ModuleId, ModuleNode, ScanResult } from '../analyzer/types';
+
+export interface DeadCodeCandidate {
+  id: ModuleId;
+  loc: number;
+  kind: ModuleNode['kind'];
+  group: 'isolated' | 'script-entry';
+  reason: string;
+}
+
+export interface DeadCodeReport {
+  candidates: DeadCodeCandidate[];
+  /** Sum of candidate loc — the reclaimable LOC estimate. */
+  totalLoc: number;
+  isolatedCount: number;
+  scriptEntryCount: number;
+}
+
+const DEAD_MODULE_REASON =
+  'No resolved imports connect this module to the analyzed dependency model.';
+
+export function buildDeadCodeReport(scan: ScanResult): DeadCodeReport {
+  const candidates: DeadCodeCandidate[] = [];
+
+  for (const module of scan.modules) {
+    if (!isReviewModule(module.id)) continue;
+    const metrics = scan.metrics[module.id];
+    const fanIn = metrics?.fanIn ?? 0;
+    const fanOut = metrics?.fanOut ?? 0;
+    if (
+      fanIn === 0 &&
+      fanOut === 0 &&
+      module.exports.length === 0 &&
+      module.kind !== 'entry' &&
+      module.kind !== 'test' &&
+      !module.isGenerated &&
+      !module.isInfra
+    ) {
+      candidates.push({
+        id: module.id,
+        loc: module.loc,
+        kind: module.kind,
+        group: isScriptEntryCandidate(module.id) ? 'script-entry' : 'isolated',
+        reason: DEAD_MODULE_REASON,
+      });
+    }
+  }
+
+  candidates.sort((a, b) => b.loc - a.loc || a.id.localeCompare(b.id));
+
+  const totalLoc = candidates.reduce((sum, c) => sum + c.loc, 0);
+  const isolatedCount = candidates.filter((c) => c.group === 'isolated').length;
+  const scriptEntryCount = candidates.filter((c) => c.group === 'script-entry').length;
+
+  return { candidates, totalLoc, isolatedCount, scriptEntryCount };
+}
+
+/**
+ * Repair action and verify text for an unreachable module finding.
+ * Shared with buildFixPlan so the two never diverge.
+ */
+export function unreachableRepair(id: ModuleId): {
+  action: string;
+  verify: string;
+  params: Record<string, unknown>;
+} {
+  if (isScriptEntryCandidate(id)) {
+    return {
+      action: `Treat ${id} as a script entry: add it to architecture entry configuration or exclude it from review scope; delete only after confirming no package script or CI job calls it.`,
+      verify:
+        'Run archora report . --format fix-plan after entry/exclude config and confirm this script is no longer a priority finding.',
+      params: { entryCandidate: 'script' },
+    };
+  }
+
+  return {
+    action:
+      'Check whether this file is dead code, dynamically loaded outside analyzer reach, or should be declared as an entry point.',
+    verify:
+      'Re-scan after deletion, ignore, or entry-point configuration and confirm the candidate is gone.',
+    params: {},
+  };
+}
+
+/**
+ * Matches modules that should go through architecture review.
+ * Excludes fixture directories and test files — same predicate as buildFixPlan.
+ */
+export function isReviewModule(id: ModuleId): boolean {
+  return !/(^|\/)(fixtures|test\/fixtures|__fixtures__|__tests__|__mocks__)(\/|$)|\.(test|spec)\./u.test(
+    id,
+  );
+}
+
+/**
+ * Heuristic: a file directly under a `scripts/` directory with a JS extension
+ * is likely a standalone Node script, not a dead module.
+ */
+export function isScriptEntryCandidate(id: ModuleId): boolean {
+  const normalized = id.replace(/\\/gu, '/');
+  let scriptsIndex = 0;
+  if (!normalized.startsWith('scripts/')) {
+    const nestedIndex = normalized.indexOf('/scripts/');
+    if (nestedIndex < 0) return false;
+    scriptsIndex = nestedIndex + 1;
+  }
+  const file = normalized.slice(scriptsIndex + 'scripts/'.length);
+  if (!file) return false;
+  return file.endsWith('.js') || file.endsWith('.cjs') || file.endsWith('.mjs');
+}

package/src/report/buildFixPlan.ts

@@ -1,4 +1,5 @@
 import type { ModuleId, ModuleNode, Recommendation, ScanResult } from '../analyzer/types';
+import { buildDeadCodeReport, isReviewModule, unreachableRepair } from './buildDeadCodeReport';
 
 export interface FixPlanFinding {
   type:
@@ -223,33 +224,19 @@ function buildPriorityFindings(scan: ScanResult, generated: Set<ModuleId>): FixP
     });
   }
 
-  for (const module of scan.modules) {
-    if (!isReviewModule(module.id)) continue;
-    const metrics = scan.metrics[module.id];
-    const fanIn = metrics?.fanIn ?? 0;
-    const fanOut = metrics?.fanOut ?? 0;
-    if (
-      fanIn === 0 &&
-      fanOut === 0 &&
-      module.exports.length === 0 &&
-      module.kind !== 'entry' &&
-      module.kind !== 'test' &&
-      !module.isGenerated &&
-      !module.isInfra
-    ) {
-      const repair = unreachableRepair(module.id);
-      findings.push({
-        type: 'unreachable-from-entries',
-        id: `${module.id}:unreachable`,
-        title: 'Unreachable module candidate',
-        weight: Math.min(70, 35 + module.loc / 10),
-        targets: [module.id],
-        reason: 'No resolved imports connect this module to the analyzed dependency model.',
-        action: repair.action,
-        verify: repair.verify,
-        params: { loc: module.loc, ...repair.params },
-      });
-    }
+  for (const candidate of buildDeadCodeReport(scan).candidates) {
+    const repair = unreachableRepair(candidate.id);
+    findings.push({
+      type: 'unreachable-from-entries',
+      id: `${candidate.id}:unreachable`,
+      title: 'Unreachable module candidate',
+      weight: Math.min(70, 35 + candidate.loc / 10),
+      targets: [candidate.id],
+      reason: candidate.reason,
+      action: repair.action,
+      verify: repair.verify,
+      params: { loc: candidate.loc, ...repair.params },
+    });
   }
 
   for (const violation of scan.contractViolations.slice(0, 50)) {
@@ -318,52 +305,10 @@ function buildPriorityFindings(scan: ScanResult, generated: Set<ModuleId>): FixP
     .slice(0, 100);
 }
 
-function isReviewModule(id: ModuleId): boolean {
-  return !/(^|\/)(fixtures|test\/fixtures|__fixtures__|__tests__|__mocks__)(\/|$)|\.(test|spec)\./u.test(
-    id,
-  );
-}
-
 function isLikelyGeneratedPath(id: ModuleId): boolean {
   return /(^|\/)(generated|__generated__|openapi|swagger|graphql-codegen)(\/|$)/iu.test(id);
 }
 
-function unreachableRepair(id: ModuleId): {
-  action: string;
-  verify: string;
-  params: Record<string, unknown>;
-} {
-  if (isScriptEntryCandidate(id)) {
-    return {
-      action: `Treat ${id} as a script entry: add it to architecture entry configuration or exclude it from review scope; delete only after confirming no package script or CI job calls it.`,
-      verify:
-        'Run archora report . --format fix-plan after entry/exclude config and confirm this script is no longer a priority finding.',
-      params: { entryCandidate: 'script' },
-    };
-  }
-
-  return {
-    action:
-      'Check whether this file is dead code, dynamically loaded outside analyzer reach, or should be declared as an entry point.',
-    verify:
-      'Re-scan after deletion, ignore, or entry-point configuration and confirm the candidate is gone.',
-    params: {},
-  };
-}
-
-function isScriptEntryCandidate(id: ModuleId): boolean {
-  const normalized = id.replace(/\\/gu, '/');
-  let scriptsIndex = 0;
-  if (!normalized.startsWith('scripts/')) {
-    const nestedIndex = normalized.indexOf('/scripts/');
-    if (nestedIndex < 0) return false;
-    scriptsIndex = nestedIndex + 1;
-  }
-  const file = normalized.slice(scriptsIndex + 'scripts/'.length);
-  if (!file) return false;
-  return file.endsWith('.js') || file.endsWith('.cjs') || file.endsWith('.mjs');
-}
-
 function barrelCycleRepair(
   scan: ScanResult,
   modules: readonly ModuleId[],

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']));
   });