@7n/test 0.9.0 → 0.10.0

package/src/lib/ast-analyze.mjs

@@ -0,0 +1,287 @@
+/**
+ * Static analysis of JS/ESM source files via oxc (rollup/parseAst).
+ *
+ * Extracts:
+ *  - externalMocks — exact vi.mock() lines with shapes derived from import usage
+ *  - exportedNames — names of exported symbols
+ *  - internalNames — non-exported top-level declarations
+ *  - hasSideEffects — top-level call expressions (e.g. checkEnv([...]))
+ *  - envReads — process.env / env.KEY accesses (for vi.stubEnv hints)
+ *  - usesFetch — whether source calls fetch()
+ */
+import { parseAstAsync } from 'rollup/parseAst'
+
+const FETCH_CALL_RE = /\bfetch\s*\(/
+
+// ---------------------------------------------------------------------------
+// AST walker
+// ---------------------------------------------------------------------------
+
+/**
+ * Обходить AST та викликає callback для кожного вузла.
+ * @param {unknown} node AST-вузол або значення вузла
+ * @param {(node: Record<string, unknown>) => void} fn callback для кожного вузла
+ * @returns {void}
+ */
+function walk(node, fn) {
+  if (!node || typeof node !== 'object') return
+  fn(/** @type {Record<string, unknown>} */ (node))
+  for (const val of Object.values(node)) {
+    if (Array.isArray(val)) {
+      for (const child of val) walk(child, fn)
+    } else if (val && typeof val === 'object' && val.type) {
+      walk(val, fn)
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Mock shape derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Collects all member-access chains for a binding name.
+ * log.error(x)   → ['error']
+ * log             → []   (direct call/use)
+ * @param {unknown} ast parsed AST
+ * @param {string} binding import binding name
+ * @returns {string[][]} member-access chains for the binding
+ */
+function collectUsagePaths(ast, binding) {
+  const paths = []
+  walk(ast, node => {
+    if (node.type === 'CallExpression' && node.callee?.type === 'Identifier' && node.callee.name === binding) {
+      paths.push([])
+      return
+    }
+    if (node.type === 'MemberExpression' && !node.computed) {
+      const chain = []
+      let cur = node
+      while (cur?.type === 'MemberExpression' && !cur.computed) {
+        chain.unshift(cur.property?.name ?? '')
+        cur = cur.object
+      }
+      if (cur?.type === 'Identifier' && cur.name === binding) {
+        paths.push(chain)
+      }
+    }
+  })
+  return paths
+}
+
+/**
+ * Builds a nested shape object from usage paths.
+ * [['error'], ['warn']] → { error: 'vi.fn()', warn: 'vi.fn()' }
+ * [[]]                  → 'vi.fn()'  (direct call)
+ * @param {string[][]} paths usage chains for one binding
+ * @returns {string | Record<string, unknown>} mock shape
+ */
+function buildShape(paths) {
+  if (!paths.length || paths.some(p => p.length === 0)) return 'vi.fn()'
+  const shape = {}
+  for (const path of paths) {
+    let obj = shape
+    for (let i = 0; i < path.length - 1; i++) {
+      if (!obj[path[i]] || typeof obj[path[i]] === 'string') obj[path[i]] = {}
+      obj = obj[path[i]]
+    }
+    const last = path.at(-1)
+    if (!obj[last]) obj[last] = 'vi.fn()'
+  }
+  return shape
+}
+
+/**
+ * Serializes a mock shape back to formatted JS object text.
+ * @param {string | Record<string, unknown>} shape mock shape tree
+ * @param {number} depth indentation depth
+ * @returns {string} formatted JS object text
+ */
+function serializeShape(shape, depth = 0) {
+  if (shape === 'vi.fn()') return 'vi.fn()'
+  const pad = '  '.repeat(depth + 1)
+  const close = '  '.repeat(depth)
+  const entries = Object.entries(shape).map(([k, v]) => `${pad}${k}: ${serializeShape(v, depth + 1)}`)
+  return `{
+${entries.join(',\n')}
+${close}}`
+}
+
+// ---------------------------------------------------------------------------
+// Env reads
+// ---------------------------------------------------------------------------
+
+/**
+ * Collects env keys read as `env.KEY` or `process.env.KEY`.
+ * @param {unknown} ast parsed AST
+ * @returns {string[]} unique env keys
+ */
+function collectEnvReads(ast) {
+  const keys = new Set()
+  walk(ast, node => {
+    // env.KEY or process.env.KEY
+    if (
+      node.type === 'MemberExpression' &&
+      !node.computed &&
+      node.object?.type === 'Identifier' &&
+      (node.object.name === 'env' || node.object.name === 'process')
+    ) {
+      const prop = node.property?.name
+      if (prop === 'env') return // process.env itself, not a key
+      if (node.object.name === 'env' && prop) {
+        keys.add(prop)
+      }
+    }
+    if (
+      node.type === 'MemberExpression' &&
+      !node.computed &&
+      node.object?.type === 'MemberExpression' &&
+      node.object.object?.name === 'process' &&
+      node.object.property?.name === 'env' &&
+      node.property?.name
+    ) {
+      keys.add(node.property.name)
+    }
+  })
+  return [...keys]
+}
+
+/**
+ * Maps import bindings to package names.
+ * @param {unknown} ast parsed AST
+ * @returns {Map<string, string>} binding → package map
+ */
+function collectBindingToPkg(ast) {
+  const bindingToPkg = new Map()
+  for (const node of ast.body) {
+    if (node.type !== 'ImportDeclaration') continue
+    const pkg = node.source.value
+    if (pkg.startsWith('node:') || pkg.startsWith('.')) continue
+    for (const spec of node.specifiers ?? []) {
+      bindingToPkg.set(spec.local.name, pkg)
+    }
+  }
+  return bindingToPkg
+}
+
+/**
+ * Collects mock shapes for every package based on binding usage.
+ * @param {unknown} ast parsed AST
+ * @param {Map<string, string>} bindingToPkg binding → package map
+ * @returns {Map<string, Record<string, string | Record<string, unknown>>>} package shapes
+ */
+function collectPackageShapes(ast, bindingToPkg) {
+  const pkgShapes = new Map()
+  for (const [binding, pkg] of bindingToPkg) {
+    const paths = collectUsagePaths(ast, binding)
+    const shape = buildShape(paths)
+    if (!pkgShapes.has(pkg)) pkgShapes.set(pkg, {})
+    pkgShapes.get(pkg)[binding] = shape
+  }
+  return pkgShapes
+}
+
+/**
+ * Converts package shapes to `vi.mock(...)` lines.
+ * @param {Map<string, Record<string, string | Record<string, unknown>>>} pkgShapes package shapes
+ * @returns {Array<{pkg: string, mockLine: string}>} mock line definitions
+ */
+function collectExternalMocks(pkgShapes) {
+  const externalMocks = []
+  for (const [pkg, bindings] of pkgShapes) {
+    const shape =
+      Object.keys(bindings).length === 1 && Object.values(bindings)[0] === 'vi.fn()'
+        ? `{ ${Object.keys(bindings)[0]}: vi.fn() }`
+        : serializeShape(bindings)
+    externalMocks.push({ pkg, mockLine: `vi.mock("${pkg}", () => (${shape}))` })
+  }
+  return externalMocks
+}
+
+/**
+ * Collects explicitly exported top-level names.
+ * @param {unknown} ast parsed AST
+ * @returns {string[]} exported names
+ */
+function collectExportedNames(ast) {
+  const exportedNames = []
+  for (const node of ast.body) {
+    if (node.type !== 'ExportNamedDeclaration' || !node.declaration) continue
+    if (node.declaration.type === 'VariableDeclaration') {
+      exportedNames.push(...node.declaration.declarations.map(d => d.id?.name).filter(Boolean))
+    } else if (node.declaration.id?.name) {
+      exportedNames.push(node.declaration.id.name)
+    }
+  }
+  return exportedNames
+}
+
+/**
+ * Collects non-exported top-level declarations.
+ * @param {unknown} ast parsed AST
+ * @returns {string[]} internal names
+ */
+function collectInternalNames(ast) {
+  const internalNames = []
+  for (const node of ast.body) {
+    if (node.type === 'VariableDeclaration') {
+      internalNames.push(...node.declarations.map(d => d.id?.name).filter(Boolean))
+    } else if (node.type === 'FunctionDeclaration' && node.id?.name) {
+      internalNames.push(node.id.name)
+    }
+  }
+  return internalNames
+}
+
+/**
+ * Detects top-level call expressions.
+ * @param {unknown} ast parsed AST
+ * @returns {boolean} true when module has top-level side effects
+ */
+function hasTopLevelSideEffects(ast) {
+  return ast.body.some(n => n.type === 'ExpressionStatement' && n.expression?.type === 'CallExpression')
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Analyses ESM source and returns structured info for test generation.
+ * @param {string} source JS/ESM source text
+ * @returns {Promise<{
+ *   externalMocks: Array<{pkg: string, mockLine: string}>,
+ *   exportedNames: string[],
+ *   internalNames: string[],
+ *   hasSideEffects: boolean,
+ *   envReads: string[],
+ *   usesFetch: boolean,
+ * }>} структуровані дані аналізу модуля
+ */
+export async function analyzeModule(source) {
+  let ast
+  try {
+    ast = await parseAstAsync(source)
+  } catch {
+    return {
+      externalMocks: [],
+      exportedNames: [],
+      internalNames: [],
+      hasSideEffects: false,
+      envReads: [],
+      usesFetch: false
+    }
+  }
+
+  const bindingToPkg = collectBindingToPkg(ast)
+  const pkgShapes = collectPackageShapes(ast, bindingToPkg)
+
+  return {
+    externalMocks: collectExternalMocks(pkgShapes),
+    exportedNames: collectExportedNames(ast),
+    internalNames: collectInternalNames(ast),
+    hasSideEffects: hasTopLevelSideEffects(ast),
+    envReads: collectEnvReads(ast),
+    usesFetch: FETCH_CALL_RE.test(source)
+  }
+}

package/src/lib/docs/ast-analyze.md

@@ -0,0 +1,45 @@
+---
+type: JS Module
+title: ast-analyze.mjs
+resource: npm/src/lib/ast-analyze.mjs
+docgen:
+  crc: 7e4d00fc
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей модуль виконує статичний аналіз файлів JS/ESM за допомогою oxc. Він витягує точні рядки `vi.mock` та відповідні форми (shapes) на основі використання імпорту, зіставляє експортовані та внутрішні символи, визначає побічні ефекти, читання змінних середовища (`process.env`/`env.KEY`) та використання `fetch` у коді.
+
+## Поведінка
+
+1. Викликає функцію analyzeModule для аналізу коду.
+2. Парсить вхідний код за допомогою rollup/parseAst. У разі помилки парсингу повертає структуру з порожніми значеннями для всіх полів.
+3. Визначає прив'язки імпортів, зіставляючи їх з зовнішніми пакетами.
+4. Для кожної прив'язки аналізує всі шляхи використання, щоб побудувати структуру заглушки (mock shape).
+5. Формує список `externalMocks` у вигляді рядків `vi.mock` на основі виявлених заглушок.
+6. Сканує тіло коду, щоб зібрати назви всіх символів, які явно експортуються.
+7. Сканує тіло коду, щоб зібрати назви усіх оголошень верхнього рівня (змінних чи функцій), які не є експортованими.
+8. Перевіряє наявність виразів виклику на верхньому рівні, щоб визначити, чи є у модулі побічні ефекти.
+9. Збирає всі ключі, які зчитуються з середовища (`env` або `process.env`).
+10. Перевіряє вихідний код на наявність викликів `fetch`.
+11. Повертає об'єкт, що містить результати: `externalMocks`, `exportedNames`, `internalNames`, `hasSideEffects`, `envReads`, та `usesFetch`.
+
+## Публічний API
+
+analyzeModule — аналізує вихідний код ESM та повертає структуровану інформацію для створення тестів.
+
+externalMocks — масив об'єктів, що містить необхідні моки для зовнішніх пакетів, включаючи сам рядок моку.
+exportedNames — список назв, які експортуються із модуля.
+internalNames — список внутрішніх (неекспортованих) назв елементів у модулі.
+hasSideEffects — булеве значення, що вказує на наявність побічних ефектів у модулі.
+envReads — список змінних середовища, які зчитує модуль.
+usesFetch — булеве значення, що вказує на використання функції `fetch` у модулі.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/src/lib/docs/index.md

@@ -0,0 +1,14 @@
+---
+type: Directory Index
+title: npm/src/lib
+resource: npm/src/lib/
+---
+
+# npm/src/lib
+
+| Файл                                  | Тип       |
+| ------------------------------------- | --------- |
+| [ast-analyze.mjs](ast-analyze.md)     | JS Module |
+| [pi-client.mjs](pi-client.md)         | JS Module |
+| [runtime-probe.mjs](runtime-probe.md) | JS Module |
+| [vitest-shim.mjs](vitest-shim.md)     | JS Module |

package/src/lib/docs/pi-client.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: pi-client.mjs
+resource: npm/src/lib/pi-client.mjs
+docgen:
+  crc: 4649ce83
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей модуль надає прямий, інпроцесний програмний інтерфейс для взаємодії з агентами pi SDK, замінюючи синхронні виклики зовнішнього процесу. Він реалізує два режими роботи: текстовий режим, де функція `callText` повертає рядок на основі текстового запиту без активації інструментів, та режим агента, де функція `callAgent` активує кодові інструменти для прямого внесення змін у файли у заданій робочій директорії. Зверніть увагу, що у цьому інтерфейсі відсутній механізм кешування.
+
+## Поведінка
+
+callText відправляє текстовий запит до моделі pi та повертає текстову відповідь.
+callAgent відправляє завдання до агента pi з активними інструментами кодування та виконує зміни у файлах у вказаній директорії.
+
+## Публічний API
+
+callText — надсилає одноразовий запит у текстовому режимі, не використовуючи інструменти, і повертає відповідь, зчитуючи конфігурацію з ~/.pi/.
+callAgent — надсилає запит у режимі агента, надаючи доступ до повного набору інструментів кодування (читання, запис, bash, редагування); агент сам створює тестові файли.
+
+## Гарантії поведінки
+
+- (специфічних машинно-виведених гарантій немає)

package/src/lib/docs/runtime-probe.md

@@ -0,0 +1,36 @@
+---
+type: JS Module
+title: runtime-probe.mjs
+resource: npm/src/lib/runtime-probe.mjs
+docgen:
+  crc: 31dd4fd6
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл проводить runtime probing експортованих функцій через чотири стратегії: `probeModule` викликає кожен експорт з граничними примітивами для отримання фактичних вихідних даних; `probeFetchCalls` перехоплює глобальні HTTP-запити, щоб фіксувати реальні URL та ініціалізацію для кожного експорту; `probeTimeVariants` запускає кожен експорт у фіксовані часові вікна ([0,9,14,22]) для виявлення чутливих до часу змін; а `probeHelpers` витягує неекспортовані допоміжні функції з вихідного коду для визначення їхніх фактичних форм виходу. Усі стратегії мають принцип best-effort: у разі будь-якої помилки вони повертають порожнє значення, не викидаючи винятків. Функціонал не залежить від кешування.
+
+## Поведінка
+
+Поведінка:
+probeModule викликає кожен експортований функціонал з граничними примітивами, щоб визначити фактичні вихідні дані.
+probeFetchCalls перехоплює глобальний запит `fetch` та збирає реальні URL та ініціалізацію для кожного експортованого функціоналу.
+probeTimeVariants виконує кожен експортований функціонал у різні години доби та доповідає про ті, чий вихід залежить від часу.
+probeHelpers витягує внутрішні допоміжні функції з коду та викликає їх з загальними комбінаціями параметрів для виявлення фактичних форм виходу.
+
+## Публічний API
+
+probeModule — Виявляє функції, експортовані модулем, за допомогою їх запуску в дочірньому процесі.
+probeFetchCalls — Перехоплює глобальний виклик `fetch` і виконує кожну експортовану асинхронну функцію з різними аргументами, щоб фіксувати фактичний URL та ініціалізацію, які вона конструює.
+probeTimeVariants — Запускає кожну експортовану функцію у різний час доби. Повідомляє про функції, чий результат змінюється залежно від години.
+probeHelpers — Витягує неекспортовані допоміжні функції з вихідного коду та викликає їх із загальними комбінаціями параметрів, щоб модель штучного інтелекту бачила фактичну форму виводу замість припущення.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/src/lib/docs/vitest-shim.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: vitest-shim.mjs
+resource: npm/src/lib/vitest-shim.mjs
+docgen:
+  crc: 5d7aaaf0
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.97
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей файл надає спільні утиліти для тестування на основі Vitest. Він дозволяє виконувати тести у цільових проектах, де Vitest не встановлений локально, оскільки використовується Vitest, вбудований у `@7n/test`. Механізм конфігурації (залежить від `package.json`) забезпечує обхід будь-яких помилок завантаження конфігурації у цільовому проекті. Публічні функції включають `VITEST_BIN`, `VITEST_SHIM_CONFIG` та `ensureVitestShim`.
+
+## Поведінка
+
+VITEST_BIN — Абсолютний шлях до вбудованого виконуваного файлу Vitest.
+VITEST_SHIM_CONFIG — Абсолютний шлях до тимчасового файлу конфігурації Vitest, що забезпечує роботу збірки без встановлення Vitest у цільовому проекті.
+ensureVitestShim — Гарантує існування файлу конфігурації Vitest, записуючи мінімальний конфіг у тимчасову директорію, ігноруючи шляхи до `node_modules`.
+
+## Публічний API
+
+VITEST_BIN — Шлях до виконуваного файлу Vitest, скомпільованого для використання.
+VITEST_SHIM_CONFIG — Мінімальна конфігурація Vitest, яку створюють у тимчасовій директорії ОС, щоб імпортований скомпільований Vitest міг отримати доступ до нього.
+ensureVitestShim — Гарантує існування файлу конфігурації шиму (повторне виконання не змінює стан).
+
+## Гарантії поведінки
+
+- Свідомо пропускає шляхи: `node_modules`.

package/src/lib/pi-client.mjs

@@ -6,7 +6,14 @@
  *   callText(prompt, model?)  — text-only, no tools, returns string
  *   callAgent(prompt, cwd)    — coding tools enabled, writes files directly
  */
-import { createAgentSession, SessionManager } from '@earendil-works/pi-coding-agent'
+import { createAgentSession, SessionManager, ModelRegistry, AuthStorage } from '@earendil-works/pi-coding-agent'
+
+let _registry = null
+async function getRegistry() {
+  if (_registry) return _registry
+  _registry = ModelRegistry.create(AuthStorage.create())
+  return _registry
+}
 
 /**
  * Sends a single prompt to pi in text mode (no tools) and returns the response.
@@ -23,8 +30,16 @@ export async function callText(prompt, opts = {}) {
   const sessionOpts = {
     tools: [],
     sessionManager: SessionManager.inMemory(cwd),
-    cwd,
-    ...(opts.model ? { model: opts.model } : {})
+    cwd
+  }
+  if (opts.model) {
+    const registry = await getRegistry()
+    const slashIdx = opts.model.indexOf('/')
+    const provider = slashIdx >= 0 ? opts.model.slice(0, slashIdx) : null
+    const modelId = slashIdx >= 0 ? opts.model.slice(slashIdx + 1) : opts.model
+    const resolved = provider ? registry.find(provider, modelId) : null
+    sessionOpts.modelRegistry = registry
+    sessionOpts.model = resolved ?? opts.model
   }
   const { session } = await createAgentSession(sessionOpts)