@archora/core 1.1.0

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

@@ -0,0 +1,172 @@
+// search() работает на полностью искусственном ScanResult — нам важна
+// логика ранкера и префикс-фильтров, а не парсер. Минимально-валидный
+// fixture-builder ниже соблюдает форму типов, но не претендует на
+// семантическую полноту (нет цикл-/метрик-ссылок).
+
+import { describe, expect, it } from 'vitest';
+import type {
+  ScanResult,
+  ModuleNode,
+  DependencyEdge,
+  ModuleId,
+  ModuleKind,
+} from '../../analyzer/types';
+import { search } from '../index';
+
+interface ModuleSpec {
+  id: ModuleId;
+  kind?: ModuleKind;
+  exports?: string[];
+  imports?: { to?: string; specifier: string }[];
+}
+
+function buildScan(modules: ModuleSpec[]): ScanResult {
+  const moduleNodes: ModuleNode[] = modules.map((m) => ({
+    id: m.id,
+    absPath: m.id,
+    kind: m.kind ?? 'unknown',
+    language: 'ts',
+    loc: 1,
+    exports: m.exports ?? [],
+    isInfra: false,
+  }));
+  const edges: DependencyEdge[] = [];
+  for (const m of modules) {
+    for (const i of m.imports ?? []) {
+      edges.push({
+        from: m.id,
+        to: i.to ?? '',
+        kind: 'static',
+        specifier: i.specifier,
+        resolved: Boolean(i.to),
+      });
+    }
+  }
+  const metrics = Object.fromEntries(
+    moduleNodes.map((m) => [
+      m.id,
+      {
+        fanIn: 0,
+        fanOut: 0,
+        instability: 0,
+        depth: 0,
+        inCycle: false,
+        couplingScore: 0,
+        hotnessScore: 0,
+      },
+    ]),
+  );
+  return {
+    project: {
+      id: 'p',
+      name: 'p',
+      rootPath: '/p',
+      detectedFramework: 'unknown',
+    },
+    modules: moduleNodes,
+    edges,
+    cycles: [],
+    metrics,
+    hotZones: [],
+    layerViolations: [],
+    archDebt: {
+      score: 0,
+      grade: 'A',
+      breakdown: { cycles: 0, layerViolations: 0, hotZones: 0, coupling: 0 },
+    },
+    recommendations: [],
+    contractViolations: [],
+    scannedAt: new Date().toISOString(),
+    durationMs: 0,
+    warnings: [],
+  };
+}
+
+const FIXTURE = buildScan([
+  { id: 'src/features/auth/composables/useAuth.ts', kind: 'composable', exports: ['useAuth'] },
+  { id: 'src/features/auth/AuthForm.vue', kind: 'component', exports: ['default'] },
+  {
+    id: 'src/features/checkout/CheckoutForm.vue',
+    kind: 'component',
+    exports: ['default'],
+    imports: [{ specifier: 'react-query' }, { specifier: '@/features/auth' }],
+  },
+  { id: 'src/shared/lib/api.ts', kind: 'util', exports: ['api', 'apiClient'] },
+  { id: 'src/stores/userStore.ts', kind: 'store', exports: ['useUserStore'] },
+]);
+
+describe('search', () => {
+  it('пустой query → пустая выдача', () => {
+    expect(search(FIXTURE, '')).toEqual([]);
+    expect(search(FIXTURE, '   ')).toEqual([]);
+  });
+
+  it('export:useAuth находит 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', () => {
+    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 фильтрует по типу', () => {
+    const r = search(FIXTURE, 'kind:store');
+    expect(r.map((x) => x.id)).toEqual(['src/stores/userStore.ts']);
+  });
+
+  it('path:features ищет substring в 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');
+    expect(ids).toContain('src/features/checkout/CheckoutForm.vue');
+    expect(ids).not.toContain('src/shared/lib/api.ts');
+  });
+
+  it('AND-пересечение: 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', () => {
+    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);
+    expect(ids.has('src/features/auth/composables/useAuth.ts')).toBe(true);
+    expect(ids.has('src/stores/userStore.ts')).toBe(false);
+  });
+
+  it('free-text без префикса: ранкер находит совпадения по path и exports', () => {
+    const r = search(FIXTURE, 'useAuth');
+    // useAuth.ts должен быть на верху (точное совпадение exports + basename)
+    expect(r[0]!.id).toBe('src/features/auth/composables/useAuth.ts');
+    expect(r[0]!.score).toBeGreaterThan(0.5);
+  });
+
+  it('точное совпадение basename ранжируется выше substring-совпадения', () => {
+    const r = search(FIXTURE, 'useAuth');
+    // useAuth.ts — basename match; AuthForm.vue — только path-substring
+    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 обрезает выдачу', () => {
+    const r = search(FIXTURE, 'path:src', { limit: 2 });
+    expect(r).toHaveLength(2);
+  });
+
+  it('неизвестный kind не падает, просто не находит', () => {
+    expect(search(FIXTURE, 'kind:nonsense')).toEqual([]);
+  });
+
+  it('SearchResult.matched может содержать несколько критериев одновременно', () => {
+    // useAuth: совпадает по export (через export:) и по path (через free-text)
+    const r = search(FIXTURE, 'export:useAuth auth');
+    expect(r[0]!.matched).toEqual(expect.arrayContaining(['export', 'path']));
+  });
+});

package/src/search/index.ts

@@ -0,0 +1,281 @@
+// Глобальный поиск по `ScanResult` — без чтения файловой системы, только
+// по структурированным метаданным (modules + edges). Стратегия:
+//
+// 1. Парсим query (`parseQuery`).
+// 2. Для каждого префикса набираем set'ы ID-кандидатов; в финальный набор
+//    попадают только модули, прошедшие пересечение всех префиксов (AND).
+// 3. Поверх отфильтрованных модулей применяем free-text ранкинг
+//    (substring-match по path и exports) и сортируем по итоговому скору.
+// 4. Возвращаем разноимённые результаты с типом матча — UI рендерит pill-чипы
+//    «Path / Export / Import / Kind», поэтому каждому SearchResult нужно знать,
+//    почему он попал в выдачу.
+//
+// Не делаем: ripgrep по содержимому файлов, fuzzy-substring (типа
+// fzf-style scoring) — для path → modules.length обычно сотни, обычный
+// substring достаточен. Усложним, если появится сигнал «слишком шумно».
+
+import type { ScanResult, ModuleId, ModuleKind } from '../analyzer/types';
+import { parseQuery, isEmpty, type ParsedQuery, type SearchPrefix } from './parseQuery';
+
+export type { SearchPrefix, ParsedQuery } from './parseQuery';
+
+export type MatchKind = 'path' | 'export' | 'import' | 'kind';
+
+export interface SearchResult {
+  /** Module id (relative path). */
+  id: ModuleId;
+  /** Какие критерии сработали — UI использует для подсветки чипов. */
+  matched: MatchKind[];
+  /** Score 0..1; 1 = идеальное соответствие, 0 = только prefix-фильтр прошёл. */
+  score: number;
+  /**
+   * Подсветочный hint для каждого совпавшего критерия — конкретные значения
+   * (имя экспорта, specifier импорта, kind). Используется панелью результатов
+   * для пояснения «почему этот модуль вылез на этот запрос».
+   */
+  highlights: Partial<Record<MatchKind, string[]>>;
+}
+
+export interface SearchOptions {
+  /** Ограничить размер выдачи. По умолчанию 50 — типовой UI-overlay. */
+  limit?: number;
+}
+
+const DEFAULT_LIMIT = 50;
+
+export function search(
+  scan: ScanResult,
+  query: string,
+  options: SearchOptions = {},
+): SearchResult[] {
+  const parsed = parseQuery(query);
+  if (isEmpty(parsed)) return [];
+
+  const limit = options.limit ?? DEFAULT_LIMIT;
+  const moduleIds = new Set(scan.modules.map((m) => m.id));
+
+  // 1. Префиксные фильтры выдают `Map<id, MatchKind[]> + highlights` —
+  // если префикс есть, попасть в выдачу можно только пройдя его.
+  const prefixHits = collectPrefixHits(scan, parsed);
+
+  // Если есть префиксы — оставляем только модули, попавшие во все указанные.
+  const eligibleIds = applyPrefixIntersection(moduleIds, prefixHits, parsed.prefixes);
+
+  // 2. Free-text ранкинг. Если free пуст и префиксы есть — отдаём eligible
+  // как есть со скором 0.5 (нейтральный). Если free есть — считаем скор и
+  // отбрасываем модули, у которых ни один free-токен не сматчился, КОГДА
+  // префиксов нет; иначе free снижает скор, но не отсекает.
+  const results: SearchResult[] = [];
+  for (const id of eligibleIds) {
+    const module = scan.modules.find((m) => m.id === id);
+    if (!module) continue;
+    const matched: MatchKind[] = [];
+    const highlights: Partial<Record<MatchKind, string[]>> = {};
+
+    // соберём подтверждения от префикс-хитов
+    for (const kind of ['path', 'export', 'import', 'kind'] as const) {
+      const hit = prefixHits[kind].get(id);
+      if (hit) {
+        matched.push(kind);
+        highlights[kind] = hit;
+      }
+    }
+
+    let freeScore = 0;
+    if (parsed.free.length > 0) {
+      const f = scoreFreeText(module.id, module.exports, parsed.free);
+      freeScore = f.score;
+      if (f.score > 0) {
+        if (f.matchedPath && !matched.includes('path')) {
+          matched.push('path');
+          (highlights.path ??= []).push(...f.matchedPathTerms);
+        }
+        if (f.matchedExports.length > 0 && !matched.includes('export')) {
+          matched.push('export');
+          (highlights.export ??= []).push(...f.matchedExports);
+        }
+      } else if (matched.length === 0) {
+        // Нет ни префикс-матча, ни free-матча: модуль вообще не попал.
+        continue;
+      }
+    }
+
+    const score = parsed.free.length === 0 ? 0.5 : freeScore || 0.5;
+    results.push({ id, matched, score, highlights });
+  }
+
+  // 3. Сортировка: больший score → раньше; tiebreak по короче-путь → раньше
+  // (короткие пути обычно ближе к корню фичи, чем глубокие имплементации).
+  results.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    return a.id.length - b.id.length;
+  });
+
+  return results.slice(0, limit);
+}
+
+// ─── helpers ──────────────────────────────────────────────────────────────────
+
+interface PrefixHits {
+  path: Map<ModuleId, string[]>;
+  export: Map<ModuleId, string[]>;
+  import: Map<ModuleId, string[]>;
+  kind: Map<ModuleId, string[]>;
+}
+
+function collectPrefixHits(scan: ScanResult, q: ParsedQuery): PrefixHits {
+  const out: PrefixHits = {
+    path: new Map(),
+    export: new Map(),
+    import: new Map(),
+    kind: new Map(),
+  };
+
+  if (q.prefixes.path) {
+    const needles = q.prefixes.path.map((s) => s.toLowerCase());
+    for (const m of scan.modules) {
+      const id = m.id.toLowerCase();
+      const matched = needles.filter((n) => id.includes(n));
+      if (matched.length > 0) out.path.set(m.id, matched);
+    }
+  }
+
+  if (q.prefixes.export) {
+    const needles = q.prefixes.export;
+    for (const m of scan.modules) {
+      const matched: string[] = [];
+      for (const e of m.exports) {
+        for (const n of needles) {
+          if (e === n || e.includes(n)) {
+            matched.push(e);
+            break;
+          }
+        }
+      }
+      if (matched.length > 0) out.export.set(m.id, matched);
+    }
+  }
+
+  if (q.prefixes.import) {
+    // edges.specifier — оригинальная строка импорта; non-resolved тоже учитываем
+    const needles = q.prefixes.import;
+    const matchedSpecifiersByModule = new Map<ModuleId, Set<string>>();
+    for (const e of scan.edges) {
+      for (const n of needles) {
+        const spec = e.specifier;
+        if (spec === n || spec.includes(n)) {
+          let s = matchedSpecifiersByModule.get(e.from);
+          if (!s) {
+            s = new Set();
+            matchedSpecifiersByModule.set(e.from, s);
+          }
+          s.add(spec);
+          break;
+        }
+      }
+    }
+    for (const [id, set] of matchedSpecifiersByModule) {
+      out.import.set(id, [...set]);
+    }
+  }
+
+  if (q.prefixes.kind) {
+    const needles = new Set(q.prefixes.kind.map((s) => s.toLowerCase() as ModuleKind));
+    for (const m of scan.modules) {
+      if (needles.has(m.kind)) out.kind.set(m.id, [m.kind]);
+    }
+  }
+
+  return out;
+}
+
+function applyPrefixIntersection(
+  all: Set<ModuleId>,
+  hits: PrefixHits,
+  prefixes: ParsedQuery['prefixes'],
+): Set<ModuleId> {
+  let result = all;
+  for (const key of ['path', 'export', 'import', 'kind'] as const) {
+    if (!prefixes[key as SearchPrefix]) continue;
+    const subset = hits[key];
+    const next = new Set<ModuleId>();
+    for (const id of result) if (subset.has(id)) next.add(id);
+    result = next;
+  }
+  return result;
+}
+
+interface FreeTextMatch {
+  score: number;
+  matchedPath: boolean;
+  matchedPathTerms: string[];
+  matchedExports: string[];
+}
+
+/**
+ * Простой substring-ранкер. Не fuzzy: для типичной задачи «найди useAuth»
+ * подстрока даёт стабильные результаты без шумовых матчей.
+ *
+ * Скоринг:
+ * - Точное совпадение 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'ов.
+ */
+function scoreFreeText(id: ModuleId, exports: readonly string[], terms: string[]): FreeTextMatch {
+  let score = 0;
+  let matchedPath = false;
+  const matchedPathTerms: string[] = [];
+  const matchedExports = new Set<string>();
+  const idLower = id.toLowerCase();
+  const baseName = basenameLower(id);
+
+  for (const rawTerm of terms) {
+    const term = rawTerm.toLowerCase();
+    let bestForTerm = 0;
+
+    for (const e of exports) {
+      const eLower = e.toLowerCase();
+      if (eLower === term) {
+        bestForTerm = Math.max(bestForTerm, 0.5);
+        matchedExports.add(e);
+      } else if (eLower.includes(term)) {
+        bestForTerm = Math.max(bestForTerm, 0.25);
+        matchedExports.add(e);
+      }
+    }
+
+    if (baseName === term) {
+      bestForTerm = Math.max(bestForTerm, 0.4);
+      matchedPath = true;
+      matchedPathTerms.push(rawTerm);
+    } else if (idLower.includes(term)) {
+      bestForTerm = Math.max(bestForTerm, 0.2);
+      matchedPath = true;
+      matchedPathTerms.push(rawTerm);
+    }
+
+    score += bestForTerm;
+  }
+
+  // Нормализуем: максимум 0.5 за term — top score 1.0 при N term'ов.
+  const normalized = terms.length > 0 ? Math.min(1, score / (terms.length * 0.5)) : 0;
+  return {
+    score: normalized,
+    matchedPath,
+    matchedPathTerms: [...new Set(matchedPathTerms)],
+    matchedExports: [...matchedExports],
+  };
+}
+
+function basenameLower(p: string): string {
+  const i = p.lastIndexOf('/');
+  const base = i === -1 ? p : p.slice(i + 1);
+  // strip extension for path-equality match
+  const dot = base.lastIndexOf('.');
+  return (dot === -1 ? base : base.slice(0, dot)).toLowerCase();
+}
+
+export { parseQuery, isEmpty } from './parseQuery';

package/src/search/parseQuery.ts

@@ -0,0 +1,75 @@
+// Парсер query-строки для глобального поиска. Поддерживает префиксы
+// `path:`, `export:`, `import:`, `kind:`, разделяемые пробелами; всё, что
+// без префикса — free-text токены, которые ранкер использует одновременно
+// по path и exports.
+//
+// Несколько префиксов в одной строке = AND-пересечение
+// (`kind:component path:auth` → component-модули, у которых path содержит auth).
+// Несколько одинаковых префиксов = OR внутри ключа
+// (`kind:component kind:composable` → component ИЛИ composable).
+//
+// Значения префиксов могут содержать кавычки, чтобы пробелы не дробили токен:
+// `path:"src/feature x"`. Кавычки внутри значения не поддерживаются — это
+// query-строка, а не shell-парсер.
+
+export type SearchPrefix = 'path' | 'export' | 'import' | 'kind';
+
+export interface ParsedQuery {
+  /** Свободные токены без префикса. Пустой массив, если все — префиксированы. */
+  free: string[];
+  /** Значения, сгруппированные по ключу. Пустой объект → нет префиксов. */
+  prefixes: Partial<Record<SearchPrefix, string[]>>;
+}
+
+const PREFIXES: ReadonlySet<string> = new Set(['path', 'export', 'import', 'kind']);
+
+export function parseQuery(input: string): ParsedQuery {
+  const result: ParsedQuery = { free: [], prefixes: {} };
+  const tokens = tokenize(input);
+  for (const tok of tokens) {
+    const colon = tok.indexOf(':');
+    if (colon > 0) {
+      const key = tok.slice(0, colon).toLowerCase();
+      const value = tok.slice(colon + 1);
+      if (PREFIXES.has(key) && value.length > 0) {
+        const k = key as SearchPrefix;
+        const bucket = (result.prefixes[k] ??= []);
+        bucket.push(value);
+        continue;
+      }
+    }
+    if (tok.length > 0) result.free.push(tok);
+  }
+  return result;
+}
+
+/**
+ * Tokenize while respecting double-quoted spans so users can search for
+ * paths/exports containing spaces (rare but real, e.g. fixture names).
+ */
+function tokenize(input: string): string[] {
+  const out: string[] = [];
+  let buf = '';
+  let inQuotes = false;
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i]!;
+    if (ch === '"') {
+      inQuotes = !inQuotes;
+      continue;
+    }
+    if (!inQuotes && (ch === ' ' || ch === '\t' || ch === '\n')) {
+      if (buf.length > 0) {
+        out.push(buf);
+        buf = '';
+      }
+      continue;
+    }
+    buf += ch;
+  }
+  if (buf.length > 0) out.push(buf);
+  return out;
+}
+
+export function isEmpty(q: ParsedQuery): boolean {
+  return q.free.length === 0 && Object.keys(q.prefixes).length === 0;
+}