@7n/rules 1.35.0 → 1.36.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.36.0] - 2026-07-20
+
+### Added
+
+- doc-files: секція «Публічний API» рендериться дослівно для експортів із JSDoc-описом (0 LLM-токенів, 0 перефразувань), LLM викликається лише на прогалини (без опису або зі stub-заглушкою «опис.»)
+
+### Changed
+
+- тестовий no-op touch README для перевірки npm-publish CI
+
+### Fixed
+
+- workspaces/resolve-js-root/package-manifest/tauri core_test_isolation: node:fs/promises#glob → Bun.Glob — платформна прогалина Node-compat шиму на self-hosted Linux Bun (export 'glob' відсутній), спостережено в @7n/rules-ci-azure lint job
+- hook під Node (npx): «detector changelog/consistency: import впав: Bun is not defined» — top-level `new Bun.Glob(...)` у workspaces.mjs/package-manifest.mjs валив import детектора; усі використання Bun.Glob (разом із resolve-js-root і tauri/core_test_isolation) переведені на runtime-нейтральний scanGlob (Bun.Glob під Bun, node:fs/promises#glob під Node)
+
 ## [1.35.0] - 2026-07-20
 
 ### Added

package/README.md

@@ -187,3 +187,4 @@ npm/rules/<id>/
 Консольна утиліта яка дозволить оновлювати в локальних GIT репозиторіях правила для cursor з можливістю наслідування правил від файлів в цьому репозиторії та забезпечення версійності правил для cursor.
 
 <!-- no-op: touch npm/** щоб retrigger-нути npm-publish CI для кореневого bun.lock-фіксу (без цього path-фільтр push-тригера не спрацьовує) -->
+<!-- no-op: тестовий touch npm/** для перевірки npm-publish CI (2026-07-20) -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.35.0",
+  "version": "1.36.0",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",

package/rules/changelog/lib/docs/package-manifest.md

@@ -3,7 +3,7 @@ type: JS Module
 title: package-manifest.mjs
 resource: npm/rules/changelog/lib/package-manifest.mjs
 docgen:
-  crc: 10bad2ce
+  crc: b6f24bb6
 ---
 
 Модуль `package-manifest.mjs` реалізує **уніфіковану абстракцію маніфесту пакета** для перевірок changelog у багатомовному монорепо. Він приховує відмінності між двома типами маніфестів:

package/rules/changelog/lib/package-manifest.mjs

@@ -3,11 +3,12 @@
  * або `pyproject.toml` (Python / PEP 621, Poetry).
  */
 import { existsSync } from 'node:fs'
-import { glob, readFile } from 'node:fs/promises'
+import { readFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'
 
 import { parse as parseToml } from 'smol-toml'
 
+import { scanGlob } from '../../../scripts/utils/glob-compat.mjs'
 import { getMonorepoPackageRootDirs, isIgnoredWorkspaceRoot } from '../../../scripts/lib/workspaces.mjs'
 
 /**
@@ -26,7 +27,6 @@ import { getMonorepoPackageRootDirs, isIgnoredWorkspaceRoot } from '../../../scr
  * @property {'major' | 'minor' | 'patch' | null} maxBump стеля для `n-rules release` (з `package.json#release.maxBump`); `null` — без обмеження
  */
 
-const PYPROJECT_GLOB_IGNORE = ['**/node_modules/**', '**/.git/**', '**/.venv/**', '**/venv/**']
 const VALID_MAX_BUMPS = new Set(['major', 'minor', 'patch'])
 
 /**
@@ -146,7 +146,7 @@ export async function getMonorepoProjectRootDirs(repoRoot = '.') {
     roots.add('.')
   }
 
-  for await (const relPy of glob('**/pyproject.toml', { cwd: repoRoot, ignore: PYPROJECT_GLOB_IGNORE })) {
+  for await (const relPy of scanGlob('**/pyproject.toml', repoRoot)) {
     const absDir = dirname(join(repoRoot, relPy))
     const relRoot = relative(repoRoot, absDir)
     const ws = relRoot === '' ? '.' : relRoot

package/rules/doc-files/docgen-gen/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-gen/main.mjs
 docgen:
-  crc: ed99ac58
+  crc: c9c9970b
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 

package/rules/doc-files/docgen-gen/main.mjs

@@ -17,7 +17,10 @@ import {
   overviewMessages,
   criticMessages,
   refineMessages,
-  guaranteesFromMarkers
+  guaranteesFromMarkers,
+  isApiGap,
+  renderApiLine,
+  apiGapMessages
 } from '../docgen-prompts/main.mjs'
 
 /** Облік LLM-викликів і часу в них у межах однієї генерації (скидається на старті generateDoc). */
@@ -338,15 +341,36 @@ async function critiqueRefineSection(sectionKey, draft, facts, anchors, model, t
 }
 
 /**
- * Чи треба refine для секції API: тільки якщо є >1 експорту і всі desc-и порожні
- * (саме там модель схильна писати «застосовує логіку до файлу»).
+ * Stage 1/3 (гібрид doc-files, ADR 260719-2155): «Публічний API» — покриті
+ * JSDoc-описом експорти рендеряться дослівно (`renderApiLine`, 0 токенів, 0
+ * галюцинацій), LLM викликається лише на прогалини (`isApiGap`). Якщо прогалин
+ * немає — секція збирається БЕЗ жодного LLM-виклику. Єдиний непокритий
+ * експорт (як і раніше) лишається описаним лише в Поведінці — окремого виклику
+ * на секцію з одного рядка не варте.
  * @param {object} facts факт-лист
- * @returns {boolean} true — секцію API варто прогнати через критика
+ * @param {object|null} anchors анкори файлу
+ * @param {string} model model-id
+ * @param {number} timeoutMs ліміт на LLM-виклик
+ * @param {number} [temperature] температура LLM-виклику (best-of-2 підвищує)
+ * @returns {Promise<string>} текст секції «Публічний API» (може бути порожнім рядком)
  */
-function apiNeedsRefine(facts) {
+export async function buildApiSection(facts, anchors, model, timeoutMs, temperature = 0.2) {
   const exps = facts.exports ?? []
-  if (exps.length <= 1) return false
-  return exps.every(e => !e.desc)
+  if (!exps.length) return ''
+  if (exps.length === 1 && isApiGap(exps[0])) return ''
+  const covered = exps.filter(e => !isApiGap(e))
+  const gap = exps.filter(isApiGap)
+  const coveredBlock = covered.map(e => renderApiLine(e)).join('\n')
+  if (!gap.length) return coveredBlock
+  let gapDraft = stripSignatures(
+    stripSection(await callLlm(apiGapMessages(gap, anchors), model, { timeoutMs, temperature }))
+  )
+  // E2: critique→refine лише коли ВСІ експорти — прогалина (там модель найбільш
+  // схильна зривати на generic-фрази без жодного JSDoc-«якоря» поруч).
+  if (gap.length === exps.length) {
+    gapDraft = await critiqueRefineSection('api', gapDraft, facts, anchors, model, timeoutMs)
+  }
+  return [coveredBlock, gapDraft].filter(Boolean).join('\n')
 }
 
 /**
@@ -407,15 +431,12 @@ async function orchestratedDoc(
   const anc = anchors ?? extractAnchors(src)
   // E3: «Гарантії» — детермінований шаблон з markers (0 LLM-запитів, 0 generic-фраз)
   sections.guarantees = guaranteesFromMarkers(facts)
-  // Спершу Поведінка (+API) — секції з фактажем
+  // Спершу Поведінка — єдина секція з кодом (sectionMessages повертає лише її)
   for (const s of sectionMessages(facts, src, anc, intent)) {
-    let draft = stripSignatures(stripSection(await callLlm(s.messages, model, { timeoutMs, temperature })))
-    // E2: critique→refine для API, коли всі описи порожні (модель зриває на generic)
-    if (s.key === 'api' && apiNeedsRefine(facts)) {
-      draft = await critiqueRefineSection(s.key, draft, facts, anc, model, timeoutMs)
-    }
-    sections[s.key] = draft
+    sections[s.key] = stripSignatures(stripSection(await callLlm(s.messages, model, { timeoutMs, temperature })))
   }
+  // Stage 1/3: «Публічний API» — покриті JSDoc експорти дослівно, LLM лише на прогалини
+  sections.api = await buildApiSection(facts, anc, model, timeoutMs, temperature)
   // R3: «Огляд» — ОСТАННІМ, узагальненням уже написаної Поведінки (не голого факт-листа)
   let overview = stripSignatures(
     stripSection(

package/rules/doc-files/docgen-prompts/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-prompts/main.mjs
 docgen:
-  crc: 3fbc97f2
+  crc: fb4d1242
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.99

package/rules/doc-files/docgen-prompts/main.mjs

@@ -65,12 +65,15 @@ function intentContext(intent) {
 /**
  * Секційні набори messages з МІНІМАЛЬНИМ контекстом під кожну секцію.
  * Код потрапляє лише в `behavior`; «Огляд» генерується окремо ОСТАННІМ
- * (`overviewMessages`) з уже написаної Поведінки — тут його немає.
+ * (`overviewMessages`) з уже написаної Поведінки — тут його немає. «Публічний
+ * API» сюди більше не входить (Stage 1/3, гібрид doc-files ADR 260719-2155):
+ * покриті JSDoc-описом експорти рендеряться дослівно без LLM (`renderApiLine`),
+ * LLM викликається лише на прогалини (`apiGapMessages`) — див. `isApiGap`.
  * @param {object} facts факт-лист про файл
  * @param {string} src вміст файлу
  * @param {object|null} [anchors] анкори файлу для обовʼязкового включення
  * @param {string|null} [intent] захищена секція «Призначення» як read-only контекст
- * @returns {Array<{key:string, messages:object[], numPredict:number}>} набір секційних промптів (behavior[, api])
+ * @returns {Array<{key:string, messages:object[], numPredict:number}>} набір секційних промптів (лише behavior)
  */
 export function sectionMessages(facts, src, anchors = null, intent = null) {
   const factsTxt = factsSummary(facts)
@@ -97,19 +100,50 @@ export function sectionMessages(facts, src, anchors = null, intent = null) {
       `Напиши вміст секції «Поведінка»: ${behaviorTask}.${onlyExports} Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex.${noInternal} Без заголовка, без додаткових ## чи # підзаголовків усередині секції.`
     )
   }
+  return [behavior]
+}
 
-  // API — лише список експортів (без коду)
-  if (!multi && !facts.exports?.some(e => e.desc)) return [behavior]
-  const list = facts.exports.map(e => `- ${e.name}: ${e.desc || '(сформулюй стисло з наміру файлу)'}`).join('\n')
-  const api = {
-    key: 'api',
-    numPredict: 320,
-    messages: msgs(
-      `${STYLE}${anch}`,
-      `Перепиши цей список як стислі маркери «назва — що робить», СВОЇМИ словами (не копіюй дослівно), без типів і сигнатур. Використовуй РІВНО ці назви, не додавай і не прибирай:\n${list}\nБез заголовка. Без generic-фраз «застосовує логіку», «перевіряє коректність» — пиши конкретно ЩО саме застосовує/перевіряє.`
-    )
-  }
-  return [behavior, api]
+// «опис.» — та сама JSDoc-заглушка без сенсу, яку lang-екстрактори (extractors.mjs)
+// вже відкидають при парсингу; тут — другий, незалежний gate на рівні facts.exports
+// (захист від прогалин, що прийшли з інших джерел фактів, напр. майбутніх мов).
+const STUB_DESC_RE = /^опис\.?$/i
+
+/**
+ * Stage 2 (gap-детект, 0 токенів): чи є опис експорту прогалиною — відсутній
+ * або JSDoc-заглушка без сенсу.
+ * @param {{desc?:string}} exp запис експорту з факт-листа
+ * @returns {boolean} true — опис потрібно синтезувати LLM (Stage 3)
+ */
+export function isApiGap(exp) {
+  const desc = (exp.desc ?? '').trim()
+  return !desc || STUB_DESC_RE.test(desc)
+}
+
+/**
+ * Stage 1 (скриптовий рендер, 0 токенів, 0 галюцинацій): дослівний рядок
+ * «Публічного API» з покритого JSDoc-описом експорту — без перефразування LLM.
+ * @param {{name:string, desc:string}} exp запис експорту з непорожнім desc
+ * @returns {string} рядок маркованого списку
+ */
+export function renderApiLine(exp) {
+  return `- ${exp.name} — ${exp.desc.trim()}`
+}
+
+/**
+ * Stage 3: messages ЛИШЕ для експортів-прогалин (без desc) — вужчий промпт,
+ * ніж попередній «переписати весь список своїми словами» (жодного контакту з
+ * уже покритими JSDoc експортами, 0 ризику спотворити авторський текст).
+ * @param {Array<{name:string}>} gapExports експорти без опису (isApiGap === true)
+ * @param {object|null} [anchors] анкори файлу
+ * @returns {Array<{role:string,content:string}>} messages-масив для LLM
+ */
+export function apiGapMessages(gapExports, anchors = null) {
+  const anch = anchorsBlock(anchors)
+  const list = gapExports.map(e => `- ${e.name}`).join('\n')
+  return msgs(
+    `${STYLE}${anch}`,
+    `Для кожної названої публічної функції напиши один рядок маркованого списку «назва — що робить», СВОЇМИ словами, без типів і сигнатур, РІВНО у цьому порядку й з РІВНО цими назвами:\n${list}\nБез заголовка. Без generic-фраз «застосовує логіку», «перевіряє коректність» — пиши конкретно ЩО саме застосовує/перевіряє.`
+  )
 }
 
 /**

package/rules/k8s/dremio_logging/dremio_logging.mdc

@@ -14,6 +14,7 @@ Rego-пакет: `k8s.dremio_logging`
 | `com.dremio.service.reflection.descriptor.MaterializationCache` |
 | `com.dremio.exec.planner.plancache.PlanCacheSynchronizer` |
 | `com.dremio.exec.planner.plancache.CacheRefresher` |
+| `com.dremio.sabot.exec.FragmentExecutors` (множина, пакет `exec` БЕЗ `fragment` — не плутати з `fragment.FragmentExecutor` вище) |
 
 **Чому:** ці loggerи (усі на одному `planning-cache-refresher` треді; підтверджено живою перевіркою в проді) пишуть INFO на кожен запит/фоновий цикл і домінують обсяг логів у Cloud Logging без діагностичної цінності понад WARN. Список фіксований — не розширюй «про запас»; нові loggerи — окремою ітерацією.
 
@@ -26,6 +27,7 @@ Rego-пакет: `k8s.dremio_logging`
 <logger name="com.dremio.service.reflection.descriptor.MaterializationCache" level="warn"/>
 <logger name="com.dremio.exec.planner.plancache.PlanCacheSynchronizer" level="warn"/>
 <logger name="com.dremio.exec.planner.plancache.CacheRefresher" level="warn"/>
+<logger name="com.dremio.sabot.exec.FragmentExecutors" level="warn"/>
 ```
 
 **Autofix:** відсутній (detection-only, як `hasura_httproute`) — XML-трансформ складніший за YAML `setIn`; T0-fix, за потреби, окремою ітерацією.

package/rules/k8s/dremio_logging/dremio_logging.rego

@@ -35,6 +35,10 @@ required_loggers := {
 	"com.dremio.service.reflection.descriptor.MaterializationCache",
 	"com.dremio.exec.planner.plancache.PlanCacheSynchronizer",
 	"com.dremio.exec.planner.plancache.CacheRefresher",
+	# NB: FragmentExecutors (множина, пакет exec, БЕЗ fragment) — окремий клас від
+	# fragment.FragmentExecutor вище, легко переплутати за назвою. Логує
+	# "Received remote fragment start instruction..." на кожен фрагмент.
+	"com.dremio.sabot.exec.FragmentExecutors",
 }
 
 # Рівні logback, що задовольняють вимогу «warn або строгіше».

package/rules/tauri/core_test_isolation/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/tauri/core_test_isolation/main.mjs
 docgen:
-  crc: f8cf8ea5
+  crc: cfb870f5
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: best-of-2:retry-won,judge:inaccurate:0.98

package/rules/tauri/core_test_isolation/main.mjs

@@ -7,11 +7,12 @@
  * ризикований (виділення крейту, перенесення коду) — лише репорт (core_test_isolation.mdc).
  */
 import { existsSync } from 'node:fs'
-import { glob, readFile } from 'node:fs/promises'
+import { readFile } from 'node:fs/promises'
 import { dirname, join, relative, resolve } from 'node:path'
 
 import { parse as parseToml } from 'smol-toml'
 
+import { scanGlob } from '../../../scripts/utils/glob-compat.mjs'
 import { createViolationReporter } from '../../../scripts/lib/lint-surface/violation-reporter.mjs'
 import { getMonorepoPackageRootDirs } from '../../../scripts/lib/workspaces.mjs'
 
@@ -65,7 +66,7 @@ async function resolveWorkspaceMemberDirs(srcTauriDir, members) {
   const found = new Set()
   for (const pattern of members) {
     if (pattern.includes('*')) {
-      for await (const rel of glob(pattern, { cwd: srcTauriDir })) {
+      for await (const rel of scanGlob(pattern, srcTauriDir)) {
         const abs = resolve(srcTauriDir, rel)
         if (existsSync(join(abs, 'Cargo.toml'))) found.add(abs)
       }
@@ -84,7 +85,7 @@ async function resolveWorkspaceMemberDirs(srcTauriDir, members) {
  * @returns {Promise<boolean>} true, якщо знайдено відповідний маркер
  */
 async function hasFakeLlmProviderMarker(crateDir) {
-  for await (const relPath of glob('**/*.rs', { cwd: crateDir })) {
+  for await (const relPath of scanGlob('**/*.rs', crateDir)) {
     if (relPath.includes('target/')) continue
     const content = await readFile(join(crateDir, relPath), 'utf8')
     if (FAKE_PROVIDER_RE.test(content)) return true

package/scripts/lib/docs/workspaces.md

@@ -3,7 +3,7 @@ type: JS Module
 title: workspaces.mjs
 resource: npm/scripts/lib/workspaces.mjs
 docgen:
-  crc: 995c1633
+  crc: 8382904f
 ---
 
 Цей файл визначає список кореневих каталогів пакетів у монорепо, використовуючи конфігурацію `workspaces` з `package.json`. Він використовується скриптами перевірки монорепо для ідентифікації всіх проектів, які потрібно перевірити. Результат повертається для подальшого використання в процесах перевірки та аналізу.
@@ -14,18 +14,18 @@ docgen:
 `normalizeWorkspacePattern`: Нормалізує воркспейс-патерн до POSIX-формату, видаляючи хвостові `/`.
 `normalizeWorkspacePatterns`: Перетворює значення `workspaces` в масив воркспейс-патернів.
 `getMonorepoPackageRootDirs`: Збирає список коренів пакетів воркспейсу з `package.json`.
-`WORKSPACE_GLOB_IGNORE`: Ігнорує каталоги `node_modules`, `.git`, `.venv` та `venv`.
+`WORKSPACE_IGNORED_DIRS`: Ігноровані каталоги `node_modules`, `.git`, `.venv` та `venv`.
 
 ## Публічний API
 
-- WORKSPACE_GLOB_IGNORE — Ігнорує шаблони workspace, що містять `*`, як визначено в `rules/changelog/js/consistency/package-manifest.mjs`.
+- WORKSPACE_IGNORED_DIRS — Теки, ігноровані при розгортанні workspace-патернів із `*` (узгоджено з `rules/changelog/lib/package-manifest.mjs`).
 - isIgnoredWorkspaceRoot — Визначає, чи слід виключити каталог з списку коренів workspace (не враховує `.`).
 - normalizeWorkspacePatterns — Перетворює поле `workspaces` з `package.json` на масив шляхів або glob-шаблонів.
 - getMonorepoPackageRootDirs — Повертає список кореневих каталогів пакетів, включаючи корінь репозиторію та всі пакети, визначені в `workspaces`.
 
 ## Гарантії поведінки
 
-- Повертає порожній список каталогів, якщо не знайдено жодного `package.json` у кореневому каталозі або в каталогах, що відповідають `WORKSPACE_GLOB_IGNORE`.
+- Повертає порожній список каталогів, якщо не знайдено жодного `package.json` у кореневому каталозі або в каталогах, що входять до `WORKSPACE_IGNORED_DIRS`.
 - Повертає `false` якщо не вдалося прочитати `package.json` у будь-якому з каталогів.
 - Не включає в список каталог `node_modules`.
 - Не включає в список каталог `.git`.

package/scripts/lib/workspaces.mjs

@@ -5,14 +5,16 @@
  * з `workspaces`, з урахуванням glob).
  */
 import { existsSync } from 'node:fs'
-import { glob, readFile } from 'node:fs/promises'
+import { readFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'
 
+import { scanGlob } from '../utils/glob-compat.mjs'
+
 const TRAILING_SLASH_RE = /\/$/
 const LEADING_DOTSLASH_RE = /^\.\//
 
-/** Glob-ігнор для workspace-патернів із `*` (узгоджено з `rules/changelog/js/consistency/package-manifest.mjs`). */
-export const WORKSPACE_GLOB_IGNORE = Object.freeze(['**/node_modules/**', '**/.git/**', '**/.venv/**', '**/venv/**'])
+/** Теки, ігноровані при розгортанні workspace-патернів із `*` (узгоджено з `rules/changelog/lib/package-manifest.mjs`). */
+export const WORKSPACE_IGNORED_DIRS = Object.freeze(['node_modules', '.git', '.venv', 'venv'])
 
 /**
  * Чи слід виключити каталог зі списку workspace-коренів (не стосується `.`).
@@ -23,7 +25,7 @@ export function isIgnoredWorkspaceRoot(ws) {
   if (ws === '.') return false
   const p = ws.replaceAll('\\', '/').replace(LEADING_DOTSLASH_RE, '')
   const segments = new Set(p.split('/'))
-  return segments.has('node_modules') || segments.has('.git') || segments.has('.venv') || segments.has('venv')
+  return WORKSPACE_IGNORED_DIRS.some(dir => segments.has(dir))
 }
 
 /**
@@ -49,10 +51,7 @@ function normalizeWorkspacePattern(pattern) {
 async function addWorkspaceRootsByPattern(roots, repoRoot, workspacePattern) {
   if (workspacePattern.includes('*')) {
     const globPat = `${workspacePattern}/package.json`
-    for await (const relPkgJsonPath of glob(globPat, {
-      cwd: repoRoot,
-      ignore: [...WORKSPACE_GLOB_IGNORE]
-    })) {
+    for await (const relPkgJsonPath of scanGlob(globPat, repoRoot)) {
       const absPkgJsonPath = join(repoRoot, relPkgJsonPath)
       const relRoot = relative(repoRoot, dirname(absPkgJsonPath))
       const ws = relRoot === '' ? '.' : relRoot

package/scripts/utils/docs/glob-compat.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: glob-compat.mjs
+resource: npm/scripts/utils/glob-compat.mjs
+docgen:
+  crc: a226a048
+  model: manual
+  tier: manual
+  score: 100
+---
+
+## Огляд
+
+Runtime-нейтральний glob-обхід для коду, що виконується і під Bun, і під Node. Потрібен, бо hook запускається через `npx` → Node, де глобал `Bun` не визначений (top-level `new Bun.Glob(...)` зривав import модуля-детектора), а прямий `node:fs/promises#glob` не працює на self-hosted Linux Bun 1.3.14, де Node-compat шим не надає export `glob`. Реалізація вибирається за середовищем виконання: `Bun.Glob` під Bun, `node:fs/promises#glob` під Node (гарантовано за `engines: node >=25`).
+
+## Публічний API
+
+- `scanGlob(pattern, cwd)` — async-генератор: ітерує відносні (до `cwd`) шляхи файлів, що відповідають glob-патерну (наприклад, `cf/*/package.json`).
+- `hasIgnoredPathSegment(relPath, ignoredDirs)` — чи містить відносний шлях сегмент зі службових тек (наприклад, `node_modules`), які glob-обхід має ігнорувати; еквівалент ignore-патернів `**/<dir>/**` по кожній теці з `ignoredDirs`. Розділювачі `\` нормалізуються до `/`.
+
+## Де використовується
+
+- `npm/scripts/lib/workspaces.mjs` — розгортання workspace-патернів із `*`.
+- `npm/scripts/utils/resolve-js-root.mjs` — резолв JS-roots за workspace-патернами.
+- `npm/rules/changelog/lib/package-manifest.mjs` — пошук `pyproject.toml` по репо.
+- `npm/rules/tauri/core_test_isolation/main.mjs` — glob-члени `[workspace] members` і обхід `**/*.rs`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Не фільтрує результати сам: ігнорування службових тек — відповідальність викликача (через `hasIgnoredPathSegment` або власні перевірки).

package/scripts/utils/docs/index.md

@@ -11,6 +11,7 @@ resource: npm/scripts/utils/
 | [ast-scan-utils.mjs](ast-scan-utils.md)                     | JS Module |
 | [ensure-gitignore-entries.mjs](ensure-gitignore-entries.md) | JS Module |
 | [find-package-json-paths.mjs](find-package-json-paths.md)   | JS Module |
+| [glob-compat.mjs](glob-compat.md)                           | JS Module |
 | [lock-cache-dir.mjs](lock-cache-dir.md)                     | JS Module |
 | [pass.mjs](pass.md)                                         | JS Module |
 | [resolve-cargo-manifest.mjs](resolve-cargo-manifest.md)     | JS Module |

package/scripts/utils/docs/resolve-js-root.md

@@ -3,7 +3,7 @@ type: JS Module
 title: resolve-js-root.mjs
 resource: npm/scripts/utils/resolve-js-root.mjs
 docgen:
-  crc: 5202013e
+  crc: 46c5af46
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---

package/scripts/utils/glob-compat.mjs

@@ -0,0 +1,36 @@
+/**
+ * Runtime-нейтральний glob-обхід для коду, що виконується і під Bun, і під Node
+ * (hook запускається через npx → Node, де глобал `Bun` не визначений, тож
+ * top-level `new Bun.Glob(...)` валить сам import модуля). Пряме
+ * `node:fs/promises#glob` теж не варіант: спостережено self-hosted Linux Bun
+ * 1.3.14, де Node-compat шим не надає export 'glob'. Тож вибір реалізації —
+ * за середовищем виконання: `Bun.Glob` під Bun, `node:fs/promises#glob` під
+ * Node (engines: node >=25).
+ */
+
+/**
+ * Ітерує відносні шляхи файлів за glob-патерном.
+ * @param {string} pattern glob-патерн (наприклад, `cf/*\/package.json`)
+ * @param {string} cwd корінь обходу
+ * @yields {string} кожен відносний шлях збігу
+ */
+export async function* scanGlob(pattern, cwd) {
+  if (typeof Bun !== 'undefined') {
+    yield* new Bun.Glob(pattern).scan({ cwd })
+    return
+  }
+  const { glob } = await import('node:fs/promises')
+  yield* glob(pattern, { cwd })
+}
+
+/**
+ * Чи містить відносний шлях сегмент зі службових тек, які glob-обхід має ігнорувати.
+ * Еквівалент колишніх ignore-патернів `**\/<dir>/**` по кожній теці з `ignoredDirs`.
+ * @param {string} relPath відносний шлях зі `scanGlob`
+ * @param {readonly string[]} ignoredDirs імена ігнорованих тек (наприклад, `node_modules`)
+ * @returns {boolean} true — шлях лежить в ігнорованій теці
+ */
+export function hasIgnoredPathSegment(relPath, ignoredDirs) {
+  const segments = relPath.replaceAll('\\', '/').split('/')
+  return ignoredDirs.some(dir => segments.includes(dir))
+}

package/scripts/utils/resolve-js-root.mjs

@@ -4,15 +4,17 @@
  * Спільна утиліта для coverage-провайдера js і test-концерну stryker_config (DRY).
  */
 import { existsSync } from 'node:fs'
-import { glob, readFile } from 'node:fs/promises'
+import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
-const WORKSPACE_GLOB_IGNORE = ['**/node_modules/**', '**/.git/**']
+import { hasIgnoredPathSegment, scanGlob } from './glob-compat.mjs'
+
+const WORKSPACE_IGNORED_DIRS = Object.freeze(['node_modules', '.git'])
 const PACKAGE_JSON_SUFFIX_RE = /[/\\]package\.json$/
 
 /**
  * Розгортає один workspace-патерн у список абсолютних шляхів каталогів з package.json.
- * Літеральні патерни перевіряються через existsSync; glob-патерни — через node:fs/promises#glob.
+ * Літеральні патерни перевіряються через existsSync; glob-патерни — через scanGlob.
  * @param {string} cwd корінь проєкту
  * @param {string} pattern workspace-патерн з package.json (наприклад, `app` або `cf/*`)
  * @returns {Promise<string[]>} абсолютні шляхи до workspace-каталогів
@@ -23,7 +25,8 @@ async function expandWorkspacePattern(cwd, pattern) {
     return existsSync(join(wsPath, 'package.json')) ? [wsPath] : []
   }
   const results = []
-  for await (const rel of glob(`${pattern}/package.json`, { cwd, exclude: WORKSPACE_GLOB_IGNORE })) {
+  for await (const rel of scanGlob(`${pattern}/package.json`, cwd)) {
+    if (hasIgnoredPathSegment(rel, WORKSPACE_IGNORED_DIRS)) continue
     const wsRel = rel.replace(PACKAGE_JSON_SUFFIX_RE, '')
     results.push(join(cwd, wsRel))
   }