@7n/rules 1.26.0 → 1.27.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.27.0] - 2026-07-19
+
+### Added
+
+- LLM-ladder: окремий (більший) таймаут cloud-avg (N_CLOUD_AVG_FIX_TIMEOUT_MS, дефолт 180s) та concern-рівневий skipLocalTier (concern.json) — пропуск local-min/local-min-retry для concern-ів, де local-tier емпірично не встигає дати результат (js/eslint увімкнено за реальними даними прогону)
+
+### Changed
+
+- doc-files: ядро без вбудованих кодових розширень (фаза 5b spec lang-plugins-extraction) — перелік розширень, OKF-типи та мовні екстрактори (факти/юніти) приходять лише з декларацій активних lang-плагінів (contributes.docFiles.extensions + handler doc-files); JS-специфіка (extractFacts, units-js, мапа типів js/mjs/ts/vue) переїхала у @7n/rules-lang-js; без активного lang-плагіна скан не бачить джерел (graceful тиша)
+
+### Fixed
+
+- Червоний lint на main: дубльовані тести мосту auto-worktree (auto-worktree.test.mjs ↔ orchestrate.test.mjs) зібрано у спільний набір `describeAutoWorktreeBridge` (scripts/utils/tests/auto-worktree-suite.mjs); `tests/**` виключено з npm-tarball; `jscpd` (спавниться як `bunx jscpd`) додано в knip ignoreDependencies
+
 ## [1.26.0] - 2026-07-19
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.26.0",
+  "version": "1.27.0",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",
@@ -43,6 +43,7 @@
     "!**/*.test.mjs",
     "!**/*_test.rego",
     "!**/test-helpers.mjs",
+    "!**/tests/**",
     "!**/fixtures/**",
     "!**/__fixtures__/**"
   ],

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

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

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

@@ -67,24 +67,17 @@ export function parseDocFrontmatter(md) {
 /** Максимум кодів issues у frontmatter — це маркер, а не повний лог. */
 const MAX_ISSUE_CODES = 8
 
-/** OKF type для вбудованих розширень; мовні (`.rs`, `.py`) декларують lang-плагіни. */
-const EXT_TYPES = {
-  '.js': 'JS Module',
-  '.mjs': 'JS Module',
-  '.cjs': 'JS Module',
-  '.ts': 'TS Module',
-  '.vue': 'Vue Component'
-}
-
 /**
- * OKF `type` для файлу-джерела за розширенням (вбудовані + декларації
- * активних lang-плагінів).
+ * OKF `type` для файлу-джерела за розширенням — лише з декларацій активних
+ * lang-плагінів (`contributes.docFiles.extensions`: js/mjs/ts/vue — lang-js,
+ * `.rs`/`.py` — lang-rust/lang-python); вбудованих типів у ядрі немає
+ * (фаза 5b spec lang-plugins-extraction). Невідоме розширення → 'Source File'.
  * @param {string} sourcePath відносний шлях джерела
  * @returns {string} тип концепту
  */
 function typeForSource(sourcePath) {
   const ext = extname(sourcePath).toLowerCase()
-  return EXT_TYPES[ext] ?? pluginDocFilesExtensions(process.cwd())[ext] ?? 'Source File'
+  return pluginDocFilesExtensions(process.cwd())[ext] ?? 'Source File'
 }
 
 /**

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: 358294dc
+  crc: ed99ac58
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 

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

@@ -8,7 +8,6 @@ import { startChain } from '@7n/llm-lib/chain'
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 import { docPathForSource } from '../docgen-scan/main.mjs'
 import { loadDocFilesExtractors } from '../docgen-scan/lang-extensions.mjs'
-import { extractFacts } from '../docgen-extract/main.mjs'
 import { extractAnchors, anchorTokens } from '../docgen-extract-anchors/main.mjs'
 import { QUALITY_THRESHOLD } from '../docgen-crc/main.mjs'
 import { JUDGE_ENABLED, JUDGE_MODEL, detectRefusalFiller, judgeDoc, judgeFailsDoc } from '../docgen-judge/main.mjs'
@@ -507,11 +506,20 @@ export async function generateDoc(
       `docgen pre-send guard: джерело ~${estTokens} токенів > бюджет ${budget} (0.5× контексту) — Prompt too long, skip`
     )
   }
-  // Мовний екстрактор з lang-плагіна (напр. `.rs` у @7n/rules-lang-rust) має
-  // пріоритет; вбудований extractFacts покриває JS-екосистему, решта — whole-file.
+  // Факт-лист — лише від мовного екстрактора lang-плагіна (js/mjs/ts —
+  // lang-js, `.rs` — lang-rust); без екстрактора для розширення — whole-file
+  // шлях через `unsupported` (у ядрі вбудованих екстракторів немає, фаза 5b).
   const langExtractors = await loadDocFilesExtractors(process.cwd())
   const ext = `.${file.split('.').pop()}`.toLowerCase()
-  const facts = langExtractors.get(ext)?.extractFacts?.(src, file) ?? extractFacts(src, file)
+  const facts = langExtractors.get(ext)?.extractFacts?.(src, file) ?? {
+    relPath: file,
+    lang: ext.slice(1),
+    unsupported: true,
+    header: '',
+    exports: [],
+    imports: {},
+    markers: {}
+  }
   const t0 = Date.now()
   llmMeter = { calls: 0, ms: 0 }
   const chain = chainFactory({ kind: 'doc-generate', unit: facts.relPath, cwd: process.cwd() })

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

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-scan/main.mjs
 docgen:
-  crc: 66000db2
+  crc: 8729f94f
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.99
@@ -15,7 +15,7 @@ docgen:
 
 ## Поведінка
 
-isSourceFile визначає, чи є ім'я файлу кодовим джерелом для генерації документації, виключаючи файли тестів і файли декларацій типів.
+isSourceFile визначає, чи є ім'я файлу кодовим джерелом для генерації документації, виключаючи файли тестів і файли декларацій типів; перелік кодових розширень береться ВИКЛЮЧНО з декларацій активних lang-плагінів (`contributes.docFiles.extensions`: js/mjs/ts/vue — lang-js, `.rs`/`.py` — lang-rust/lang-python), у ядрі вбудованих розширень немає (фаза 5b) — без активного lang-плагіна скан не бачить жодного джерела.
 docPathForSource обчислює очікуваний шлях до markdown-документа для заданого кодового джерельного шляху, розміщуючи його у теці `docs` поруч із джерелом.
 isDocCandidate визначає, чи повинен файл підлягати документуванню, перевіряючи його тип, статус тесту, статус ігнорування та чи не є він частиною системних документації.
 describeFile описує кодовий файл, надаючи шлях джерела та шлях до відповідного документа, а також статус його застарілості за CRC. Якщо док-файл існує, але без `docgen:`-CRC у frontmatter (рукописна дока), файл позначається `foreign: true` і НЕ вважається застарілим — людський зміст рахується чинною документацією і мовчки не перезаписується (перезапис лише explicit `--overwrite` у batch-CLI).

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

@@ -7,13 +7,6 @@ import { isDocgenIgnored } from '../docgen-ignore/main.mjs'
 import { parseDocFrontmatter, readDocCrc, staleness } from '../docgen-crc/main.mjs'
 import { pluginDocFilesExtensions } from './lang-extensions.mjs'
 
-/**
- * Вбудовані кодові розширення, для яких генеруємо документацію. Мовні
- * розширення поза JS-екосистемою (`.rs`, `.py`) декларують lang-плагіни
- * (`n-rules.contributes.docFiles.extensions`) — див. lang-extensions.mjs.
- */
-const SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.ts', '.vue'])
-
 /** `*.test.*`, `*.spec.*`, `*.stories.*` — тести й Storybook CSF-файли, документувати не треба. */
 const TEST_FILE_RE = /\.(?:test|spec|stories)\.[^.]+$/u
 
@@ -29,18 +22,18 @@ function isSystemWideDocsRoot(root) {
 }
 
 /**
- * Чи є файл кодовим джерелом для документування. З `root` — враховує і
- * розширення активних lang-плагінів; без нього — лише вбудовані JS-екосистемні.
+ * Чи є файл кодовим джерелом для документування. Розширення декларують ЛИШЕ
+ * активні lang-плагіни (`n-rules.contributes.docFiles.extensions` — js/mjs/ts/vue
+ * дає `@7n/rules-lang-js`, .rs/.py — lang-rust/lang-python); у ядрі вбудованих
+ * розширень немає (фаза 5b spec lang-plugins-extraction).
  * @param {string} fileName базове ім'я файлу
- * @param {string} [root] корінь репозиторію (для плагінних розширень)
+ * @param {string} root корінь репозиторію (джерело плагінних розширень)
  * @returns {boolean} true — документуємо; false — пропускаємо
  */
 export function isSourceFile(fileName, root) {
   if (fileName.endsWith('.d.ts')) return false
   if (TEST_FILE_RE.test(fileName)) return false
-  const ext = extname(fileName)
-  if (SOURCE_EXTENSIONS.has(ext)) return true
-  return root !== undefined && ext in pluginDocFilesExtensions(root)
+  return extname(fileName) in pluginDocFilesExtensions(root)
 }
 
 /**

package/rules/js/eslint/concern.json

@@ -1,5 +1,6 @@
 {
   "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "skipLocalTier": true,
   "lint": {
     "scope": "per-file",
     "glob": ["**/*.{js,mjs,cjs,jsx,ts,tsx,vue}"]

package/schemas/concern.json

@@ -19,6 +19,10 @@
       ],
       "description": "Маршрутизація fix-движка. Усі мітки виконують детерміновану фазу T0; різниця — що після неї. `code` (дефолт, поле можна опускати) — джерельні порушення, які LLM може осмислено переписати → повна pi-agent-ladder (local→cloud) до чистого re-detect. `config` — canon/settings/tooling конфіг з єдиною правильною формою (jscpd/oxfmtrc/tooling/package_json/*_yml): фікс детермінований (T0/regen з канону), LLM лише вгадав би невалідне → після T0 fail-fast без ladder. `structural` — дублікати/розташування/структура (jscpd_duplicates/test-location/package-structure): авто-правка ризикована й потребує людського розсуду → після T0 fail-fast без ladder. config vs structural різняться мотивом пропуску (детермінований канон vs надто ризиковано) — для телеметрії й майбутнього routing."
     },
+    "skipLocalTier": {
+      "type": "boolean",
+      "description": "Дефолт `false` (поле можна опускати). `true` пропускає local-min/local-min-retry rung-и LLM-ladder-а для цього concern-а — перша спроба одразу йде на cloud-min. Для concern-ів, де local-tier (слабка локальна модель, короткий бюджет) емпірично майже завжди лише витрачає час rung-а без результату, перш ніж ladder однаково ескалює далі."
+    },
     "check": {
       "type": "boolean",
       "const": true,

package/scripts/lib/concern-meta.mjs

@@ -34,6 +34,10 @@ import { join } from 'node:path'
  * @property {PolicySurface|undefined} policy policy-поверхня concern-а (rego/template) або undefined.
  * @property {LintSurface|undefined} lint lint-поверхня concern-а або undefined.
  * @property {Fixability} fixability маршрутизація fix-движка (дефолт `code`): `config`/`structural` пропускають LLM-ladder.
+ * @property {boolean} skipLocalTier дефолт `false`: `true` пропускає local-min/local-min-retry rung-и
+ *   ladder-а — ladder одразу стартує з cloud-min. Для concern-ів, де local-tier емпірично не встигає
+ *   дати результат у межах свого бюджету (напр. js/eslint — 0/12 успіхів у реальному прогоні, лише
+ *   витрачений час).
  */
 
 /**
@@ -119,7 +123,16 @@ export async function readConcernMeta(concernDir, name) {
       ? raw.requires.capability
       : undefined
 
-  return { name, dir: concernDir, check, policy, lint, requiresCapability, fixability: parseFixability(raw.fixability) }
+  return {
+    name,
+    dir: concernDir,
+    check,
+    policy,
+    lint,
+    requiresCapability,
+    fixability: parseFixability(raw.fixability),
+    skipLocalTier: raw.skipLocalTier === true
+  }
 }
 
 /**

package/scripts/lib/docs/concern-meta.md

@@ -3,12 +3,8 @@ type: JS Module
 title: concern-meta.mjs
 resource: npm/scripts/lib/concern-meta.mjs
 docgen:
-  crc: 1675429b
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  tier: local-min
-  score: 100
-  issues: judge:inaccurate:0.97
-  judgeModel: openai-codex/gpt-5.4-mini
+  crc: ccc325b1
+  model: manual
 ---
 
 ## Огляд
@@ -21,6 +17,7 @@ docgen:
 readConcernMeta зчитує і перевіряє файл concern.json у вказаній директорії concern-а, повертаючи метадані або null, якщо файл відсутній чи не валідний.
 listConcerns сканує директорію правил і повертає список усіх знайдених concern-ів у алфавітному порядку, ігноруючи каталоги без concern.json.
 Нормалізований meta несе `fixability` (`code`|`config`|`structural`); невідоме/відсутнє значення зводиться до `code` — дефолт, за яким concern лишається eligible для LLM-fix-ladder.
+Нормалізований meta несе також `skipLocalTier` (boolean, дефолт `false`): `true` — concern пропускає local-min/local-min-retry rung-и LLM-ladder-а, перша спроба одразу йде на cloud-min. Для concern-ів, де local-tier емпірично майже завжди лише витрачає бюджет rung-а без результату (напр. `js/eslint`).
 
 ## Публічний API
 

package/scripts/lib/lint-surface/docs/ladder.md

@@ -3,10 +3,8 @@ type: JS Module
 title: ladder.mjs
 resource: npm/scripts/lib/lint-surface/ladder.mjs
 docgen:
-  crc: a5e45f08
-  model: openai-codex/gpt-5.5
-  score: 100
-  issues: judge:inaccurate:0.97
+  crc: f02de1a2
+  model: manual
 ---
 
 ## Огляд
@@ -17,7 +15,7 @@ docgen:
 
 - `DEFAULT_MAX_AVG` задає типовий ліміт звернень до середнього cloud-рівня за один прогін, щоб ескалація не витрачала надмірно дорогий ресурс.
 - `buildLadder` формує послідовність рівнів виправлення від локального мінімального до cloud-avg і відкидає недоступні рівні без моделі.
-- Кожен rung несе `timeoutMs` — per-tier таймаут виклику (ADR 260620-0556): локальні рівні 45s, хмарні 120s; override без зміни коду — env `N_LOCAL_FIX_TIMEOUT_MS` / `N_CLOUD_FIX_TIMEOUT_MS` (мс на ОДИН rung відповідного класу; невалідне значення → дефолт). Runner прокидає його worker-у через `FixContext`, щоб зависла LLM-сесія переривалась (runner додатково тримає backstop ×1.25), а ladder рухався далі. Це робочий важіль для повільної локальної моделі чи великої черги batch-концерну (doc-files ріже беклог під цей ліміт м'яким дедлайном).
+- Кожен rung несе `timeoutMs` — per-tier таймаут виклику (ADR 260620-0556): локальні рівні 45s, cloud-min 120s, cloud-avg 180s (окремий, більший дефолт — реальний прогін 2026-07-18 показав, що cloud-avg регулярно доводить concern майже до чистого re-detect, але спільний з cloud-min бюджет не лишав часу на verify, а наступного rung-а для повторної спроби нема); override без зміни коду — env `N_LOCAL_FIX_TIMEOUT_MS` / `N_CLOUD_FIX_TIMEOUT_MS` / `N_CLOUD_AVG_FIX_TIMEOUT_MS` (мс на ОДИН rung відповідного класу; невалідне значення → дефолт). Runner прокидає його worker-у через `FixContext`, щоб зависла LLM-сесія переривалась (runner додатково тримає backstop ×1.25), а ladder рухався далі. Це робочий важіль для повільної локальної моделі чи великої черги batch-концерну (doc-files ріже беклог під цей ліміт м'яким дедлайном).
 - `classifyFixError` визначає характер помилки виправлення: системна причина, транспортний збій або якісна невдача агента.
 - `decideAfterFailure` вирішує, чи продовжувати ескалацію після невдалого рівня, чи пропустити локальну модель, чи зупинити процес.
 

package/scripts/lib/lint-surface/docs/run-fix.md

@@ -3,8 +3,8 @@ type: JS Module
 title: run-fix.mjs
 resource: npm/scripts/lib/lint-surface/run-fix.mjs
 docgen:
-  crc: c4235855
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: 45965f7d
+  model: manual
 ---
 
 ## Огляд
@@ -23,6 +23,7 @@ Durable-write-и (issue nitra/cursor#16): worker отримує у `FixContext`
 MT-tail (Фаза B, спека 2026-07-11): коли лишився невиправлений хвіст (worst=1), `renderRemaining` повертає зібрані порушення, і вони матеріалізуються у вузли MT-графа через `materializeTail` (mt-tail.mjs). Єдиний гейт — onboarded-репо (наявність `.mt.json`); fail-open: MT недоступний або будь-яка помилка → лог, lint не падає.
 Distillation-телеметрія (Фаза C, §13 pi-migration): успішний agentic-рунг (canonical clean, без veto, з реальними правками у worker telemetry) пише запис `oldText→newText` у глобальний стор (`recordFixTelemetry`, `~/.n-rules/telemetry/<rule>/open/`) — корпус для маховика дистиляції T0. Best-effort; T0/ручні фікси не пишуться.
 Rollback на провалі re-detect-а: якщо canonical re-detect усередині rung-а сам кидає виняток (worker/LLM лишив файл синтаксично невалідним — детектор/conftest не може його розпарсити), `runRung` спершу відкочує `snapshot` до S1, і лише потім перекидає виняток далі — без цього зіпсований проміжний стан worker-а лишався б на диску назавжди (виняток абортує весь прогін до звичайного rollback-коду).
+skipLocalTier (concern-meta.mjs): `selectLadder` перед циклом ladder-а фільтрує з нього local-min/local-min-retry rung-и, якщо `item.entry.concern.skipLocalTier === true` — перша спроба одразу йде на cloud-min. Для concern-ів, де local-tier емпірично майже завжди лише витрачає бюджет rung-а без результату (виявлено на реальному прогоні 2026-07-18: 0/12 успіхів local-tier для `js/eslint`).
 
 ## Публічний API
 

package/scripts/lib/lint-surface/ladder.mjs

@@ -9,16 +9,25 @@ import { env } from 'node:process'
 // об'єктивно не закінчить важкий промпт за хвилини (curl 28), хмарний SSE без
 // таймауту здатен висіти годинами на ESTABLISHED TCP — драбина має рухатись далі.
 //
-// Override без зміни коду — env `N_LOCAL_FIX_TIMEOUT_MS` / `N_CLOUD_FIX_TIMEOUT_MS`:
-// мілісекунди на ОДИН rung відповідного класу (local-min/local-min-retry та
-// cloud-min/cloud-avg). Значення потрапляє worker-у як `ctx.timeoutMs` (внутрішній
-// abort LLM-виклику; batch-worker-и, як doc-files, ріжуть під нього беклог м'яким
-// дедлайном), а runner додатково тримає backstop ×1.25 навколо всього worker-виклику.
-// Робочий важіль для повільної локальної моделі чи великої черги batch-концерну:
-// підняти локальний таймаут понад вартість одного файлу. Невалідне значення
-// (NaN/0/порожньо) → дефолт.
+// Override без зміни коду — env `N_LOCAL_FIX_TIMEOUT_MS` / `N_CLOUD_FIX_TIMEOUT_MS` /
+// `N_CLOUD_AVG_FIX_TIMEOUT_MS`: мілісекунди на ОДИН rung відповідного класу
+// (local-min/local-min-retry, cloud-min, cloud-avg). Значення потрапляє worker-у як
+// `ctx.timeoutMs` (внутрішній abort LLM-виклику; batch-worker-и, як doc-files, ріжуть
+// під нього беклог м'яким дедлайном), а runner додатково тримає backstop ×1.25 навколо
+// всього worker-виклику. Робочий важіль для повільної локальної моделі чи великої черги
+// batch-концерну: підняти локальний таймаут понад вартість одного файлу. Невалідне
+// значення (NaN/0/порожньо) → дефолт.
+//
+// cloud-avg має ОКРЕМИЙ (більший за cloud-min) дефолт: реальний прогін
+// (2026-07-18, /ai run/yoga2, chainId 6f6b4fdca71aa0c5) показав, що cloud-avg
+// регулярно доводить concern до 1 залишкового порушення в межах спільного з
+// cloud-min бюджету, але verify (canonical re-detect) не встигає підтвердитись —
+// і весь прогрес відкочується, бо після cloud-avg немає наступного rung-а для
+// повторної спроби. cloud-avg — останній шанс ladder-а (і під DEFAULT_MAX_AVG-кепом),
+// тож дорожчий за нього бюджет виправдано менш економний, ніж cloud-min.
 const LOCAL_TIMEOUT_MS = Number(env.N_LOCAL_FIX_TIMEOUT_MS) || 45_000
 const CLOUD_TIMEOUT_MS = Number(env.N_CLOUD_FIX_TIMEOUT_MS) || 120_000
+const CLOUD_AVG_TIMEOUT_MS = Number(env.N_CLOUD_AVG_FIX_TIMEOUT_MS) || 180_000
 
 /** Дефолтний кеп на виклики cloud-avg за прогін (щоб ladder на N concern-ів не спалив avg). */
 export const DEFAULT_MAX_AVG = 3
@@ -59,7 +68,7 @@ export function buildLadder({ localMin, cloudMin, cloudAvg }) {
       timeoutMs: LOCAL_TIMEOUT_MS
     },
     { tier: 'cloud-min', model: cloudMin, feedback: true, local: false, isAvg: false, timeoutMs: CLOUD_TIMEOUT_MS },
-    { tier: 'cloud-avg', model: cloudAvg, feedback: true, local: false, isAvg: true, timeoutMs: CLOUD_TIMEOUT_MS }
+    { tier: 'cloud-avg', model: cloudAvg, feedback: true, local: false, isAvg: true, timeoutMs: CLOUD_AVG_TIMEOUT_MS }
   ].filter(r => r.model)
 }
 

package/scripts/lib/lint-surface/run-fix.mjs

@@ -440,6 +440,18 @@ function noteT0Phase(t0, chainExtra, touchedAbs) {
   }
 }
 
+/**
+ * Ladder concern-а: повний, або без local-tier rung-ів (`concern.skipLocalTier`) —
+ * concern-и, де local-min/local-min-retry емпірично не встигають дати результат
+ * у межах свого бюджету (concern-meta.mjs).
+ * @param {Rung[]} ladder Повний ladder pipeline-у.
+ * @param {import('../concern-meta.mjs').ConcernMeta} concern Concern-meta елемента плану.
+ * @returns {Rung[]} Ladder, застосовний до цього concern-а.
+ */
+function selectLadder(ladder, concern) {
+  return concern.skipLocalTier ? ladder.filter(rung => !rung.local) : ladder
+}
+
 /**
  * Тіло fix-pipeline одного concern-а (T0 → S1 → ladder); chain/chainExtra — акумулятори
  * телеметрії ланцюжка (володіє ними fixConcern-обгортка).
@@ -481,7 +493,8 @@ async function fixConcernCore(item, initialViolations, deps, chain, chainExtra,
 
   // ── Worker ladder ── concern-specific fix-worker.mjs, інакше дефолтний pi-agent worker.
   const worker = await resolveWorker(concernDir, deps.workerOverride)
-  if (!worker || ladder.length === 0) {
+  const effectiveLadder = selectLadder(ladder, item.entry.concern)
+  if (!worker || effectiveLadder.length === 0) {
     chainExtra.stop = 'no-worker'
     return false
   }
@@ -492,7 +505,7 @@ async function fixConcernCore(item, initialViolations, deps, chain, chainExtra,
   let violations = initialViolations
   const skipModels = new Set()
 
-  for (const rung of ladder) {
+  for (const rung of effectiveLadder) {
     if (skipModels.has(rung.model)) continue
     if (rung.isAvg && deps.avgRemaining() <= 0) {
       log(`  ⏭️  ${ruleId}/${concernName}: ${rung.tier} пропущено (avg-кеп вичерпано)\n`)

package/scripts/utils/docs/test-helpers.md

@@ -3,7 +3,7 @@ type: JS Module
 title: test-helpers.mjs
 resource: npm/scripts/utils/test-helpers.mjs
 docgen:
-  crc: 9af8ee18
+  crc: a01017b0
 ---
 
 ## Огляд
@@ -18,6 +18,7 @@ docgen:
 - `withBinStubInPath(bin, fn)` — створює тимчасовий каталог зі стабом `<bin>` (`<bin>.exe` на Windows), що завершується з кодом 0, додає каталог на початок `PATH` на час `fn`, потім відновлює `PATH` і прибирає стаб. Реальний бінарник не запускається: і машини без інструмента, і повільні мережево-залежні інструменти (наприклад, `kubescape`, який на старті тягне артефакти з хмарних API десятки секунд) отримують детермінований швидкий прогін.
 - `withShellcheckStubInPath(fn)` — спеціалізація `withBinStubInPath` для `shellcheck` (перевірки `check ga` на машинах без реального shellcheck).
 - `withBinRemovedFromPath(bin, fn)` — виконує `fn` із `PATH`, з якого прибрані всі каталоги з виконуваним `<bin>`; решта `PATH` (git, bun) лишається. На час `fn` виставляє `N_CURSOR_NO_AUTO_INSTALL=1`, щоб `ensureTool` не запускав реальний brew/scoop/curl-install. Для негативних тестів «fail, коли інструмента нема».
+- `installFakeLangJsPlugin(dir)` — кладе у tmp-репо фейковий `@7n/rules-lang-js` (маніфест із doc-files-розширеннями js/mjs/ts/vue у `node_modules`) і активує його через `.n-rules.json`. Після фази 5b ядро не має вбудованих кодових розширень — тестам doc-files без цього хелпера скан не бачить жодного джерела.
 
 ## Гарантії поведінки
 

package/skills/doc-files/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: doc-files
 description: >-
-  Обовʼязковий крок задачі (як lint): для кожного зміненого/нового кодового файлу (js/mjs/ts/vue вбудовано; rs/py — через lang-плагіни) JS-оркестрована генерація лаконічної поведінкової української md-документації у теку docs/ поряд із кодом, зі звіркою застарілості за CRC у frontmatter
+  Обовʼязковий крок задачі (як lint): для кожного зміненого/нового кодового файлу (розширення декларують lang-плагіни: js/mjs/ts/vue — lang-js, rs/py — lang-rust/lang-python) JS-оркестрована генерація лаконічної поведінкової української md-документації у теку docs/ поряд із кодом, зі звіркою застарілості за CRC у frontmatter
 version: '1.0'
 ---
 

package/skills/taze/js/docs/orchestrate.md

@@ -3,7 +3,7 @@ type: JS Module
 title: orchestrate.mjs
 resource: npm/skills/taze/js/orchestrate.mjs
 docgen:
-  crc: df10e67a
+  crc: c1bcfe63
   model: openai-codex/gpt-5.4-mini
   score: 100
   issues: judge:inaccurate:0.98

package/rules/doc-files/docgen-extract/concern.json

@@ -1,3 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json"
-}

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

@@ -1,38 +0,0 @@
----
-type: JS Module
-title: main.mjs
-resource: npm/rules/doc-files/docgen-extract/main.mjs
-docgen:
-  crc: a9332a80
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
-  issues: judge:inaccurate:0.99
-  judgeModel: openai-codex/gpt-5.4-mini
----
-
-## Огляд
-
-Екстрагує факти за допомогою функції `extractFacts`, звертаючись до мережі та використовуючи кешування в межах одного прогону. При цьому ігнорує каталоги, такі як `.github`, `.git`, `node_modules`, `base/`, `ua/` та `.firebase`.
-
-## Поведінка
-
-1. Аналізує вміст коду для створення детального набору фактів про файл.
-2. Визначає словник і визначає, чи є код написаний на JavaScript, TypeScript або TypeScript (ESM).
-3. Витягує загальний опис файлу, якщо він присутній у верхньому блоці коментарів.
-4. Визначає всі функції, які є публічно доступними (експортованими), разом із їхніми описами та параметрами.
-5. Класифікує імпорти на внутрішні, сторонні (npm) та вбудовані (stdlib).
-6. Визначає, чи є код:
-   - Стійким до винятків (catchesErrors).
-   - Здатним працювати без доступу до мережі (readOnly).
-   - Використовуючи механізми кешування (caches).
-   - Згодом повертаючи хибні значення у випадку помилки (returnsFalsyOnFail).
-7. Ігнорує шляхи, що відповідають шаблонам: .github, .git, node_modules, base/, ua/, .firebase.
-
-## Публічний API
-
-extractFacts — витягує з коду файлу список значущих тверджень (фактів).
-
-## Гарантії поведінки
-
-- Кешує результати в межах одного прогону.
-- Свідомо пропускає шляхи: `.github`, `.git`, `node_modules`, `base/`, `ua/`, `.firebase`.

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

@@ -1,275 +0,0 @@
-/** @see ./docs/docgen-extract.md */
-
-import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
-import { readFileSync } from 'node:fs'
-
-const BUILTIN_MODULES = new Set([
-  'fs',
-  'path',
-  'crypto',
-  'os',
-  'util',
-  'stream',
-  'events',
-  'http',
-  'https',
-  'url',
-  'child_process',
-  'process',
-  'assert',
-  'buffer',
-  'zlib',
-  'readline'
-])
-
-const JSDOC_OPEN_RE = /^\s*\/\*\*?/
-const JSDOC_CLOSE_RE = /\*\/\s*$/
-const STAR_PREFIX_RE = /^\s*\*?\s?/
-const PARAM_LINE_RE = /^@param[ \t]{1,8}(?:\{[^}]{0,200}\}[ \t]{1,8})?\[?([\w.]{1,80})\]?[ \t]{0,8}(.{0,400})$/
-const RETURNS_LINE_RE = /^@returns?[ \t]{1,8}(?:\{[^}]{0,200}\}[ \t]{1,8})?(.{0,400})$/
-const FILE_HEADER_RE = /^\s*\/\*\*([\s\S]*?)\*\//
-const PRECEDING_JSDOC_RE = /\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*$/
-const EXPORT_DECL_RE = /export\s+(?:async\s+)?(function|const|class)\s+(\w+)/g
-// Top-level function/class декларації (колонка 0) — для R6: службові функції,
-// які не експортуються, не мають протікати у Поведінку/API як «публічні».
-const TOP_FN_DECL_RE = /^(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function\*?|class)\s+(\w+)/gm
-const IMPORT_FROM_RE = /^import[ \t]{1,8}[\s\S]{0,300}?from\s{1,8}['"]([^'"]+)['"]/gm
-const NODE_PREFIX_RE = /^node:/
-const INTERNAL_IMPORT_RE = /import[ \t]{1,8}([^'"]{0,300}?)from[ \t]{1,8}['"]\.[^'"]{1,300}['"]/g
-const NAMED_BRACES_RE = /\{([^}]{1,400})\}/
-const IDENT_RE = /^[\w$]{1,80}$/
-const IMPORT_AS_RE = /[ \t]{1,8}as[ \t]{1,8}.{0,200}/
-const WRITE_FS_RE = /\b(writeFile|mkdir|rmdir|unlink|appendFile|createWriteStream|rm\()/
-const CATCH_RE = /catch\s*\(/
-const TRY_RE = /\btry\s*\{/
-// Falsy-return як «fail-safe» — лише коли воно в catch/error-гілці (інакше це
-// звичайний guard `if (!x) return null`, не обробка помилки). Уникає over-claim.
-const FALSY_RETURN_RE = /catch[\s\S]{0,400}?return\s+(false|null|''|"")/
-// Мережа: окрім явного fetch/http, ловимо абстраговані клієнти (graphql/db/rpc/
-// octokit/.request/.query). Хибний false-negative тут = небезпечна гарантія
-// «без мережі», тож свідомо схиляємось до over-detection (м'якший бік помилки).
-const NETWORK_RE =
-  /\bfetch\(|https?:\/\/|\bhttps?\.|axios|\bgot\(|graphql|\.request\(|\.query\(|\.mutate\(|octokit|node-fetch|undici|\bgrpc\b|websocket/i
-// Будь-який `throw` назовні → НЕ можна гарантувати «fail-safe / без винятків».
-const THROW_RE = /\bthrow\s/
-// Запис у БД / зовнішню мутацію → НЕ read-only (навіть якщо нема ФС-запису).
-// Розбито на кілька простіших патернів (та сама семантика через OR у `isMutation`),
-// щоб уникнути надмірної складності одного великого regex.
-const MUTATION_CALL_RE = /\b(insert|update|delete|upsert|drop|destroy|save)[A-Za-z]*\s*[(,]/
-const MUTATION_NAME_RE = /[Mm]utation\b|\bmut[A-Z]\w*/
-const MUTATION_METHOD_RE = /\.(save|create|update|delete|insert|destroy|mutate)\(/
-// Raw-SQL tagged-template виклики (напр. `pgWrite\`UPDATE ...\``) — DML-ключове
-// слово стоїть на початку тіла шаблону, не перед `(`, тож JS-орієнтовані
-// патерни вище його не ловлять. Сигнал мінімальний, але навмисний: тег-функція
-// (ідентифікатор впритул перед `` ` ``) + DML-keyword одразу після відкриття —
-// уникає false positive на звичайних рядках/коментарях, де немає теg-виклику.
-const SQL_TAGGED_MUTATION_RE = /\b\w+`\s*(?:UPDATE|INSERT|MERGE\s+INTO|DELETE\s+FROM|UPSERT)\b/i
-/**
- * @param {string} src вміст файлу
- * @returns {boolean} чи є ознаки мутації БД / зовнішнього стану
- */
-const isMutation = src =>
-  MUTATION_CALL_RE.test(src) ||
-  MUTATION_NAME_RE.test(src) ||
-  MUTATION_METHOD_RE.test(src) ||
-  SQL_TAGGED_MUTATION_RE.test(src)
-// Кеш — лише за ІМЕНОВАНИМ маркером (`cache`/`Cache`/`memoize`), не за будь-яким
-// `new Map()`: акумулятор (напр. `byPath = new Map()`) — не кеш, а хибна гарантія
-// «Кешує результати» гірша за пропуск (фабрикація > мовчання).
-const CACHE_RE = /cache|memoi[sz]e/i
-
-/**
- * Прибирає `/** *​/`-обрамлення й `*`-префікси, повертає чистий текст рядками.
- * @param {string} raw сирий JSDoc-блок з обрамленням
- * @returns {string} очищений текст без обрамлення й префіксів
- */
-function cleanJsDoc(raw) {
-  return raw
-    .replace(JSDOC_OPEN_RE, '')
-    .replace(JSDOC_CLOSE_RE, '')
-    .split('\n')
-    .map(l => l.replace(STAR_PREFIX_RE, '').trimEnd())
-    .join('\n')
-    .trim()
-}
-
-/**
- * Опис (без @-тегів) + параметри з `@param` як «name — опис».
- * @param {string} raw сирий JSDoc-блок
- * @returns {{desc:string, params:Array<{name:string, desc:string}>, ret:string}} розпарсений опис, параметри й опис повернення
- */
-function parseJsDoc(raw) {
-  const text = cleanJsDoc(raw)
-  const lines = text.split('\n')
-  const descLines = []
-  const params = []
-  let ret = ''
-  for (const l of lines) {
-    const pm = l.match(PARAM_LINE_RE)
-    if (pm) {
-      const desc = pm[2].trim()
-      // «опис.» — JSDoc-заглушка без сенсу; не тягнемо її як факт
-      params.push({ name: pm[1], desc: desc === 'опис.' ? '' : desc })
-      continue
-    }
-    const rm = l.match(RETURNS_LINE_RE)
-    if (rm) {
-      ret = rm[1].trim()
-      continue
-    }
-    if (l.startsWith('@')) continue
-    descLines.push(l)
-  }
-  return { desc: descLines.join('\n').trim(), params, ret }
-}
-
-/**
- * Провідний блок-коментар файлу (намір), якщо він перед першим import/кодом.
- * @param {string} src вміст файлу
- * @returns {string} текст header-коментаря або порожній рядок
- */
-function extractFileHeader(src) {
-  const m = src.match(FILE_HEADER_RE)
-  if (!m) return ''
-  // має бути на самому початку (до import/код)
-  if (src.slice(0, m.index).trim() !== '') return ''
-  return parseJsDoc(m[0]).desc
-}
-
-/**
- * Блок-коментар, що стоїть ВПРИТУЛ перед позицією (лише пробіли між ними).
- * `(?:(?!\*​/)[\s\S])*` гарантує, що тіло не містить `*​/`, тож захоплюється рівно один
- * найближчий блок — без жадібного «перестрибування» через імпорти/код.
- * @param {string} prefix вміст файлу до позиції експорту
- * @returns {string|null} JSDoc-блок або null якщо немає
- */
-function precedingJsDoc(prefix) {
-  const m = prefix.match(PRECEDING_JSDOC_RE)
-  return m ? m[0] : null
-}
-
-/**
- * Експорти + JSDoc, що безпосередньо передує кожному.
- * @param {string} src вміст файлу
- * @returns {Array<object>} список експортів із метаданими
- */
-function extractExports(src) {
-  const out = []
-  for (const m of src.matchAll(EXPORT_DECL_RE)) {
-    const [, kind, name] = m
-    const jsdocRaw = precedingJsDoc(src.slice(0, m.index))
-    out.push({ name, kind, ...(jsdocRaw ? parseJsDoc(jsdocRaw) : { desc: '', params: [], ret: '' }) })
-  }
-  return out
-}
-
-/**
- * Імпорти, класифіковані на stdlib / npm / internal.
- * @param {string} src вміст файлу
- * @returns {{stdlib:Array<string>, npm:Array<string>, internal:Array<string>}} розкласифіковані шляхи імпортів
- */
-function extractImports(src) {
-  const internal = new Set(),
-    npm = new Set(),
-    stdlib = new Set()
-  for (const m of src.matchAll(IMPORT_FROM_RE)) {
-    const s = m[1]
-    if (s.startsWith('node:') || BUILTIN_MODULES.has(s.split('/', 1)[0])) stdlib.add(s.replace(NODE_PREFIX_RE, ''))
-    else if (s.startsWith('.') || s.startsWith('/')) internal.add(s)
-    else npm.add(s)
-  }
-  return { stdlib: [...stdlib], npm: [...npm], internal: [...internal] }
-}
-
-/**
- * Імена символів, імпортованих із внутрішніх модулів — їх модель не має згадувати.
- * @param {string} src вміст файлу
- * @returns {Array<string>} список імен внутрішніх символів
- */
-function extractInternalSymbols(src) {
-  const out = new Set()
-  for (const m of src.matchAll(INTERNAL_IMPORT_RE)) {
-    const clause = m[1]
-    const named = clause.match(NAMED_BRACES_RE)
-    if (named) {
-      for (const n of named[1].split(',')) {
-        const name = n.replace(IMPORT_AS_RE, '').trim()
-        if (name) out.add(name)
-      }
-    }
-    const defName = clause.replace(NAMED_BRACES_RE, '').replaceAll(',', ' ').trim().split(' ', 1)[0]
-    if (defName && IDENT_RE.test(defName)) out.add(defName)
-  }
-  return [...out]
-}
-
-/**
- * Імена top-level функцій/класів, які НЕ експортуються (службові помічники).
- * Модель не має подавати їх як «публічні функції» у Поведінці/API (R6).
- * Const-стрілки свідомо не ловимо — менше false-positive на змістовних константах.
- * @param {string} src вміст файлу
- * @returns {Array<string>} список імен неекспортованих функцій/класів
- */
-function extractLocalSymbols(src) {
-  const exported = new Set(Array.from(src.matchAll(EXPORT_DECL_RE), m => m[2]))
-  const out = new Set()
-  for (const m of src.matchAll(TOP_FN_DECL_RE)) {
-    if (!exported.has(m[1])) out.add(m[1])
-  }
-  return [...out]
-}
-
-/**
- * Поведінкові маркери — евристики регулярками.
- * @param {string} src вміст файлу
- * @returns {object} набір прапорців-евристик
- */
-function extractMarkers(src) {
-  // помітні «пропуски»: dir/segment-літерали у фільтрах
-  const skips = new Set()
-  for (const lit of ['.github', '.git', 'node_modules', 'base/', 'ua/', '.firebase']) {
-    if (src.includes(`'${lit}`) || src.includes(`"${lit}`) || src.includes(`/${lit}`)) skips.add(lit)
-  }
-  return {
-    // «Фабрикація > мовчання»: прапорець true лише за high-confidence; інакше
-    // guaranteesFromMarkers/factsSummary його ОПУСКАЮТЬ (не стверджують протилежне).
-    readOnly: !WRITE_FS_RE.test(src) && !isMutation(src), // ні ФС-запису, ні DB-мутацій
-    catchesErrors: (CATCH_RE.test(src) || TRY_RE.test(src)) && !THROW_RE.test(src), // fail-safe лише якщо НЕ кидає
-    returnsFalsyOnFail: FALSY_RETURN_RE.test(src) && !THROW_RE.test(src),
-    network: NETWORK_RE.test(src),
-    caches: CACHE_RE.test(src),
-    skips: [...skips]
-  }
-}
-/**
- * Головний екстрактор: код файлу → факт-лист.
- * @param {string} src вміст файлу
- * @param {string} relPath шлях (для контексту/мови екстрактора)
- * @returns {{relPath:string, lang:string, header:string, exports:Array, imports:object, markers:object}} структура фактів про файл
- */
-export function extractFacts(src, relPath) {
-  const lang = relPath.split('.').pop()
-  if (!['js', 'mjs', 'ts'].includes(lang)) {
-    return { relPath, lang, unsupported: true, header: '', exports: [], imports: {}, markers: {} }
-  }
-  return {
-    relPath,
-    lang,
-    header: extractFileHeader(src),
-    exports: extractExports(src),
-    imports: extractImports(src),
-    internalSymbols: extractInternalSymbols(src),
-    localSymbols: extractLocalSymbols(src),
-    markers: extractMarkers(src)
-  }
-}
-
-// CLI для інспекції: node docgen-extract.mjs <file>
-if (isRunAsCli(import.meta.url)) {
-  const file = process.argv[2]
-  if (!file) {
-    throw new Error('Usage: node docgen-extract.mjs <file>')
-  }
-  const facts = extractFacts(readFileSync(file, 'utf8'), file)
-  console.log(JSON.stringify(facts, null, 2))
-}

package/rules/doc-files/units/concern.json

@@ -1,3 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json"
-}

package/rules/doc-files/units/docs/main.md

@@ -1,31 +0,0 @@
----
-type: JS Module
-title: main.mjs
-resource: npm/rules/doc-files/units/main.mjs
-docgen:
-  crc: 8acdefc1
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
-  issues: judge:inaccurate:0.98
-  judgeModel: openai-codex/gpt-5.4-mini
----
-
-## Огляд
-
-Цей файл забезпечує аналіз вмісту файлів різного мовного формату для вилучення інформації про юніти. Він обробляє вміст, визначаючи відповідний метод вилучення для JavaScript-подібних або Rust-файлів. Публічна функція `extractUnits` виконує механізм вилучення юнітних даних з коду.
-
-## Поведінка
-
-1. Метод `extractUnits` приймає вміст файлу та його відносний шлях.
-2. Визначається розширення файлу за його відносним шляхом.
-3. Якщо розширення відповідає JavaScript-подібним мовам (js, mjs, ts, jsx, tsx, cts, mts), викликається відповідна функція для вилучення юнітів на основі AST.
-4. Якщо розширення 'rs', викликається відповідна функція для вилучення юнітів шляхом парсингу за допомогою регулярних виразів та підрахунку блоків.
-5. Якщо розширення не підтримується або файл не може бути проаналізований, метод повертає null.
-
-## Публічний API
-
-- extractUnits — Витягує одиниці виміру, визначаючи метод аналізу на основі розширення файлу (від AST для JS/TS до простого пошуку для Vue/Py).
-
-## Гарантії поведінки
-
-- Read-only: не виконує операцій запису (ФС/БД).

package/rules/doc-files/units/main.mjs

@@ -1,19 +0,0 @@
-/** @see ./docs/units.md */
-
-import { extractUnitsJs } from '../units-js/main.mjs'
-
-const JS_EXT = new Set(['js', 'mjs', 'ts', 'jsx', 'tsx', 'cts', 'mts'])
-
-/**
- * Мовно-агностичний фасад юніт-шару. Диспатчить за розширенням:
- * js/mjs/ts → oxc AST; інші мови (rs — lang-плагін, extension-point
- * `doc-files`.extractUnits; vue/py) → null (whole-file шлях).
- * @param {string} src вміст файлу
- * @param {string} relPath шлях файлу
- * @returns {Array<object>|null} юніти або null, якщо мова ще не підтримана / файл не парситься
- */
-export function extractUnits(src, relPath) {
-  const ext = (relPath.split('.').pop() || '').toLowerCase()
-  if (JS_EXT.has(ext)) return extractUnitsJs(src, relPath)
-  return null
-}

package/rules/doc-files/units-js/concern.json

@@ -1,3 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json"
-}

package/rules/doc-files/units-js/docs/main.md

@@ -1,32 +0,0 @@
----
-type: JS Module
-title: main.mjs
-resource: npm/rules/doc-files/units-js/main.mjs
-docgen:
-  crc: 395188f4
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
-  issues: judge:inaccurate:0.99
-  judgeModel: openai-codex/gpt-5.4-mini
----
-
-## Огляд
-
-Будь ласка, надайте секцію «overview», яку необхідно переписати.
-
-## Поведінка
-
-1. Функція extractUnitsJs аналізує вміст файлу, щоб виявити ідентифіковані юніти (функції, класи, const-функції).
-2. Вона визначає, які юніти є експортованими та обробляє їх для включення до списку.
-3. Для кожного знайденого юніту вона витягує відповідний опис з JSDoc, що передує його оголошенню.
-4. Зібрана інформація про юніт включає його назву, тип (функція, клас, const), прапор експорту, діапазон у вихідному коді та повний вихідний код.
-5. Система виявляє всі виклики інших юнітів у тілі коду кожного юніта.
-6. В результаті повертається список об'єктів, де кожен об'єкт описує один юніт, і в якому вказано лише посилання на інші виявлені юніти.
-
-## Публічний API
-
-extractUnitsJs — знаходить та витягує на верхньому рівні логічні блоки (функції/класи/константи) з файлів JavaScript/TypeScript, які є частиною юніт-шару. Включає інформацію про експорт та взаємодії з іншими юнітами.
-
-## Гарантії поведінки
-
-- Read-only: не виконує операцій запису (ФС/БД).

package/rules/doc-files/units-js/main.mjs

@@ -1,141 +0,0 @@
-/** @see ./docs/units-js.md */
-
-import { parseProgramOrNull, walkAstWithAncestors } from '../../../scripts/utils/ast-scan-utils.mjs'
-
-// JSDoc-блок, що стоїть впритул перед позицією (лише пробіли між ними).
-const JSDOC_BEFORE_RE = /\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*$/
-const JSDOC_OPEN_RE = /^\s*\/\*\*?/
-const JSDOC_CLOSE_RE = /\*\/\s*$/
-const STAR_PREFIX_RE = /^\s*\*?\s?/
-
-/**
- * Очищає JSDoc від обрамлення `/** *​/` і `*`-префіксів.
- * @param {string} raw сирий блок або порожній рядок
- * @returns {string} текст опису без тегів-обрамлення
- */
-function cleanDoc(raw) {
-  if (!raw) return ''
-  return raw
-    .replace(JSDOC_OPEN_RE, '')
-    .replace(JSDOC_CLOSE_RE, '')
-    .split('\n')
-    .map(l => l.replace(STAR_PREFIX_RE, '').trimEnd())
-    .join('\n')
-    .trim()
-}
-
-/**
- * JSDoc, що передує позиції `start` у джерелі (або порожній рядок).
- * @param {string} src вміст файлу
- * @param {number} start зміщення початку декларації
- * @returns {string} очищений опис
- */
-function precedingDoc(src, start) {
-  const m = src.slice(0, start).match(JSDOC_BEFORE_RE)
-  return cleanDoc(m ? m[0] : '')
-}
-
-/**
- * Імʼя функції, що викликається (проста Identifier або `obj.method`).
- * @param {Record<string, unknown>} node CallExpression
- * @returns {string|null} імʼя callee або null
- */
-function calleeName(node) {
-  const c = node.callee
-  if (!c || typeof c !== 'object') return null
-  if (c.type === 'Identifier') return c.name
-  if (c.type === 'MemberExpression' && !c.computed && c.property?.type === 'Identifier') return c.property.name
-  return null
-}
-
-/**
- * Множина імен, що викликаються у тілі вузла (сирі callee — фільтрація на ребра
- * call-graph робиться у `extractUnitsJs` після збору всіх імен юнітів).
- * @param {unknown} node AST-вузол юніта
- * @returns {Set<string>} імена викликів
- */
-function collectCalls(node) {
-  const names = new Set()
-  walkAstWithAncestors(node, [], n => {
-    if (n.type !== 'CallExpression') {
-      return
-    }
-
-    const name = calleeName(n)
-    if (name) names.add(name)
-  })
-  return names
-}
-
-/**
- * Будує юніт із декларації, додає у `units`. Розпізнає function/class та
- * const-функції (`const x = () => {}` / `function expression`).
- * @param {Record<string, unknown>} decl декларація (function/class/variable)
- * @param {boolean} exported чи експортується
- * @param {number} docStart зміщення для пошуку JSDoc (зовнішній export-вузол)
- * @param {string} src вміст файлу
- * @param {Array<object>} units акумулятор
- * @returns {void}
- */
-function pushUnits(decl, exported, docStart, src, units) {
-  if (!decl || typeof decl !== 'object') return
-  const doc = precedingDoc(src, docStart)
-  if (decl.type === 'FunctionDeclaration' || decl.type === 'ClassDeclaration') {
-    const name = decl.id?.name
-    if (!name) return
-    units.push({
-      name,
-      kind: decl.type === 'ClassDeclaration' ? 'class' : 'function',
-      exported,
-      span: { start: decl.start, end: decl.end },
-      body: src.slice(decl.start, decl.end),
-      calls: collectCalls(decl),
-      doc
-    })
-    return
-  }
-  if (decl.type === 'VariableDeclaration') {
-    for (const d of decl.declarations ?? []) {
-      const init = d.init
-      const isFn = init && (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression')
-      if (!isFn || d.id?.type !== 'Identifier') continue
-      units.push({
-        name: d.id.name,
-        kind: 'const',
-        exported,
-        span: { start: init.start, end: init.end },
-        body: src.slice(init.start, init.end),
-        calls: collectCalls(init),
-        doc
-      })
-    }
-  }
-}
-
-/**
- * Юніт-шар для js/mjs/ts: top-level функції/класи/const-функції з тілом, JSDoc,
- * прапором експорту і ребрами call-graph (виклики ІНШИХ юнітів у тілі).
- * @param {string} src вміст файлу
- * @param {string} [relPath] шлях (для вибору мови oxc)
- * @returns {Array<{name:string, kind:string, exported:boolean, span:{start:number,end:number}, body:string, calls:string[], doc:string}>|null} юніти або null, якщо файл не парситься
- */
-export function extractUnitsJs(src, relPath = 'scan.ts') {
-  const program = parseProgramOrNull(src, relPath)
-  if (!program || !Array.isArray(program.body)) return null
-
-  const units = []
-  for (const node of program.body) {
-    const isExport =
-      (node.type === 'ExportNamedDeclaration' || node.type === 'ExportDefaultDeclaration') && node.declaration
-    if (isExport) {
-      pushUnits(node.declaration, true, node.start, src, units)
-    } else {
-      pushUnits(node, false, node.start, src, units)
-    }
-  }
-
-  // Ребра call-graph: лишаємо тільки виклики інших внутрішніх юнітів
-  const names = new Set(units.map(u => u.name))
-  for (const u of units) u.calls = [...u.calls].filter(n => names.has(n) && n !== u.name)
-  return units
-}