@7n/rules 1.0.0

package/scripts/lib/lint-surface/mt-run-node.mjs

@@ -0,0 +1,206 @@
+/**
+ * B2 — executor-міст: виконання fix-вузла MT нашим pi-harness (Фаза B, spec
+ * docs/specs/2026-07-11-phase-b-lint-mt-adapter-dev-design.md).
+ *
+ * MT-runner (node_executor, `@7n/mt`#29) спавнить цю команду замість вбудованого
+ * Claude-шляху для actor=agent вузлів. Контракт (з #29):
+ *   - argv[0] / `MT_NODE_DIR` = директорія вузла (task.md + a.md);
+ *   - `MT_WORKTREE` = дерево, у якому застосовувати зміни (cwd фіксу);
+ *   - `MT_MODEL_TIER` = MIM|AVG|MAX (дублює a.md);
+ *   - stdout = JSON `{applied, touchedFiles}`; exit 0 → MT ганяє `## Check` і
+ *     синтезує fact; ненульовий → failed-run.
+ * MT володіє claim/lease, worktree-ізоляцією, budget/timeout, `## Check`, publish;
+ * екзекутор ЛИШЕ «застосуй зміни» нашим тир-каноном (omlx/pi-тири llm-lib).
+ *
+ * Екзекутор НЕ re-detect-ить: canonical-гейт — `## Check` за MT. violation-текст
+ * будується з контракту вузла (task.md ## Task + target-файли), агент читає файли
+ * й правило сам. Чисте ядро (парсинг контракту, tier-мапінг) — тестовне; fix
+ * інжектується через `deps`.
+ */
+
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { env } from 'node:process'
+
+/** MT model_tier → llm-lib tier-label (для resolveModel/thinkingLevel). */
+const TIER_MAP = { MIM: 'min', AVG: 'avg', MAX: 'max' }
+
+/** Маркер `## Check`-команди (індексний пошук — без regex-backtracking). */
+const CHECK_MARKER = 'lint --no-fix'
+/** Розділювач токенів команди. */
+const RE_TOKEN_SPLIT = /\s+/
+/** Рядок target-файлу в `## Inputs` (`- \`path\``). */
+const RE_INPUT_FILE = /^- `([^`]+)`/
+
+/**
+ * Витягує правило з `## Check`-команди вузла. Правило — ОСТАННІЙ токен рядка
+ * (перед ним можуть стояти флаги на кшталт `--cwd ../..`, які додає
+ * buildCheckCommand, бо MT ганяє `## Check` із node-dir). Токен-флаг (`-…`)
+ * останнім бути не може — тоді правило відсутнє.
+ * @param {string} taskMd вміст task.md
+ * @returns {string|null} id правила або null
+ */
+function parseRule(taskMd) {
+  const idx = taskMd.indexOf(CHECK_MARKER)
+  if (idx === -1) return null
+  const eol = taskMd.indexOf('\n', idx)
+  const rest = taskMd.slice(idx + CHECK_MARKER.length, eol === -1 ? undefined : eol).trim()
+  const tokens = rest.length > 0 ? rest.split(RE_TOKEN_SPLIT) : []
+  const last = tokens.at(-1)
+  return last && !last.startsWith('-') ? last : null
+}
+
+/**
+ * Витягує target-файли з секції Inputs (bullet-рядки з path у backtick-ах).
+ * @param {string} taskMd вміст task.md
+ * @returns {string[]} перелік файлів (whole-repo маркер відкидається)
+ */
+function parseTargetFiles(taskMd) {
+  const idx = taskMd.indexOf('## Inputs')
+  if (idx === -1) return []
+  const section = taskMd.slice(idx)
+  const files = []
+  for (const line of section.split('\n')) {
+    const m = RE_INPUT_FILE.exec(line.trim())
+    if (m && !m[1].startsWith('(')) files.push(m[1])
+  }
+  return files
+}
+
+/**
+ * Парсить контракт вузла з task.md.
+ * @param {string} taskMd вміст task.md
+ * @returns {{ rule: string|null, targetFiles: string[], taskText: string }} контракт
+ */
+export function parseNodeContract(taskMd) {
+  const taskIdx = taskMd.indexOf('## Task')
+  const doneIdx = taskMd.indexOf('## Done when')
+  const end = doneIdx === -1 ? taskMd.length : doneIdx
+  const taskText = taskIdx === -1 ? '' : taskMd.slice(taskIdx + '## Task'.length, end).trim()
+  return { rule: parseRule(taskMd), targetFiles: parseTargetFiles(taskMd), taskText }
+}
+
+/**
+ * MT model_tier → llm-lib tier-label. Невідоме/відсутнє → 'avg'.
+ * @param {string|undefined} mtTier MIM|AVG|MAX
+ * @returns {'min'|'avg'|'max'} tier-label
+ */
+export function resolveTierLabel(mtTier) {
+  return TIER_MAP[String(mtTier ?? '').toUpperCase()] ?? 'avg'
+}
+
+/**
+ * Будує violation-текст для агента з контракту вузла (без re-detect —
+ * canonical-гейт лишається за MT `## Check`).
+ * @param {{ rule: string|null, targetFiles: string[], taskText: string }} contract контракт
+ * @returns {string} опис проблеми для runAgentFix
+ */
+export function buildViolationText(contract) {
+  const parts = [contract.taskText || `Порушення правила ${contract.rule ?? '(невідоме)'}.`]
+  if (contract.targetFiles.length > 0) {
+    parts.push(`Target-файли: ${contract.targetFiles.join(', ')}.`)
+  }
+  return parts.join('\n')
+}
+
+/**
+ * Дефолтний fix через pi-harness (lazy import — тримає top-level pi-free).
+ * Успішний фікс пише запис у глобальний distillation-стор (Фаза C, §13
+ * pi-migration): MT-вузли живлять той самий корпус oldText→newText, що й
+ * інлайн-драбина — крос-репо маховик T0 не розрізняє шлях фіксу.
+ * @param {{ rule: string, violation: string, cwd: string, tier: string, targetFiles: string[] }} args параметри
+ * @returns {Promise<{ applied: boolean, touchedFiles: string[], error: string|null }>} результат
+ */
+async function defaultFix({ rule, violation, cwd, tier, targetFiles }) {
+  const [{ runAgentFix }, { resolveModel }] = await Promise.all([
+    import('@7n/llm-lib/agent-fix'),
+    import('@7n/llm-lib/model-tiers')
+  ])
+  const model = resolveModel(tier)
+  const res = await runAgentFix(rule, violation, cwd, {
+    model,
+    tier,
+    targetFiles,
+    caller: `mt-run-node:${rule}`
+  })
+  await recordNodeFixTelemetry({ rule, tier, model, cwd, res })
+  return { applied: res.applied, touchedFiles: res.touchedFiles ?? [], error: res.error }
+}
+
+/**
+ * Пише успішний MT-фікс у глобальний distillation-стор (Фаза C). Лише applied без
+ * error і з реальними правками; best-effort (стор сам ковтає IO-помилки).
+ * @param {{ rule: string, tier: string, model: string|undefined, cwd: string,
+ *   res: { applied: boolean, error: string|null, telemetry?: object|null },
+ *   record?: (r: object) => object|null }} args контекст (record — інʼєкція для тестів)
+ * @returns {Promise<void>} нічого не повертає
+ */
+export async function recordNodeFixTelemetry({ rule, tier, model, cwd, res, record }) {
+  const edits = res.telemetry?.edits
+  if (!res.applied || res.error || !Array.isArray(edits) || edits.length === 0) return
+  let rec = record
+  if (!rec) {
+    const mod = await import('@7n/llm-lib/telemetry-store')
+    rec = mod.recordFixTelemetry
+  }
+  rec({
+    rule,
+    rung: `mt-${tier}`,
+    model,
+    cwd,
+    edits,
+    verifyAttempts: res.telemetry?.verifyAttempts?.length ?? 0,
+    anchoredEdits: res.telemetry?.anchoredEdits ?? false
+  })
+}
+
+/**
+ * Виконує один MT-вузол: парсить контракт, застосовує фікс нашим harness у worktree.
+ * @param {{ nodeDir: string, worktree: string, mtTier?: string,
+ *   deps?: { readFile?: (p: string) => string, fix?: typeof defaultFix } }} args параметри
+ * @returns {Promise<{ applied: boolean, touchedFiles: string[], error: string|null }>} результат для stdout
+ */
+export async function runNode({ nodeDir, worktree, mtTier, deps = {} }) {
+  const read = deps.readFile ?? (p => readFileSync(p, 'utf8'))
+  const fix = deps.fix ?? defaultFix
+
+  let taskMd
+  try {
+    taskMd = read(join(nodeDir, 'task.md'))
+  } catch (error) {
+    return { applied: false, touchedFiles: [], error: `не прочитано task.md: ${error.message}` }
+  }
+  const contract = parseNodeContract(taskMd)
+  if (!contract.rule) return { applied: false, touchedFiles: [], error: 'не знайдено правило у ## Check' }
+
+  const tier = resolveTierLabel(mtTier)
+  return await fix({
+    rule: contract.rule,
+    violation: buildViolationText(contract),
+    cwd: worktree,
+    tier,
+    targetFiles: contract.targetFiles
+  })
+}
+
+/**
+ * CLI-ентрі node_executor: argv[0]=node-dir; env MT_WORKTREE/MT_MODEL_TIER.
+ * Друкує JSON `{applied, touchedFiles}` у stdout; повертає exit-код (0 — успіх
+ * виконання, MT далі ганяє `## Check`; 1 — помилка екзекутора).
+ * @param {string[]} argv аргументи (без node/script)
+ * @param {{ env?: Record<string, string|undefined>, out?: (s: string) => void, run?: typeof runNode }} [deps] інʼєкції
+ * @returns {Promise<number>} exit-код
+ */
+export async function runNodeCli(argv, deps = {}) {
+  const e = deps.env ?? env
+  const out = deps.out ?? (s => process.stdout.write(s))
+  const run = deps.run ?? runNode
+  const nodeDir = argv[0] ?? e.MT_NODE_DIR
+  if (!nodeDir) {
+    out(`${JSON.stringify({ applied: false, touchedFiles: [], error: 'не задано node-dir (argv/MT_NODE_DIR)' })}\n`)
+    return 1
+  }
+  const res = await run({ nodeDir, worktree: e.MT_WORKTREE ?? nodeDir, mtTier: e.MT_MODEL_TIER })
+  out(`${JSON.stringify({ applied: res.applied, touchedFiles: res.touchedFiles })}\n`)
+  return res.error ? 1 : 0
+}

package/scripts/lib/lint-surface/policy-lint-adapter.mjs

@@ -0,0 +1,101 @@
+/**
+ * Policy → detector adapter. Перетворює policy-поверхню concern-а (Rego через conftest
+ * або template deep-subset) на unified `LintResult`. Generated `main.mjs` policy-concern-а
+ * викликає саме цю функцію (spec 2026-06-29 §Policy Codegen).
+ *
+ * Переоформлює перевірену логіку run-rule.mjs у структуровані violations — НЕ дублює її:
+ * та сама `resolveTargetFiles` / `runConftestBatch` / template-checks.
+ * @typedef {import('./types.mjs').LintContext} LintContext
+ * @typedef {import('./types.mjs').LintResult} LintResult
+ * @typedef {import('./types.mjs').LintViolation} LintViolation
+ * @typedef {import('./types.mjs').PolicySurface} PolicySurface
+ */
+import { relative } from 'node:path'
+
+import { resolveTargetFiles } from '../resolve-target-files.mjs'
+import { runConftestBatch } from '../run-conftest-batch.mjs'
+import {
+  checkContains,
+  checkDeny,
+  checkSnippet,
+  checkTextSubset,
+  parseByExt,
+  resolveConcernTemplateData
+} from '../template.mjs'
+
+/**
+ * posix-relative шлях від cwd (для LintViolation.file).
+ * @param {string} abs Абсолютний шлях до файлу.
+ * @param {string} cwd Корінь, відносно якого рахувати шлях.
+ * @returns {string} Posix-relative шлях (або сам `abs`, якщо relative порожній).
+ */
+function toRel(abs, cwd) {
+  return (relative(cwd, abs) || abs).split('\\').join('/')
+}
+
+/**
+ * @param {LintContext} ctx Контекст лінту (`cwd`, `ruleId`, `concernId`).
+ * @param {object} cfg Конфіг оцінки policy-concern-а.
+ * @param {'rego'|'template'} cfg.engine Рушій перевірки: Rego (conftest) або template deep-subset.
+ * @param {string} cfg.policyDir Абсолютний шлях до теки concern-а.
+ * @param {PolicySurface['files']} cfg.files Target-семантика (які файли перевіряти).
+ * @param {string} [cfg.missingMessage] Повідомлення, коли обовʼязковий single-файл відсутній.
+ * @returns {Promise<LintResult>} Уніфікований результат лінту зі списком violations.
+ */
+export async function evaluatePolicyConcern(ctx, cfg) {
+  const { cwd, ruleId, concernId } = ctx
+  /** @type {LintViolation[]} */
+  const violations = []
+  /**
+   * Додає violation до акумулятора.
+   * @param {string} reason Машинний код причини порушення.
+   * @param {string} message Людиночитане повідомлення.
+   * @param {string} [file] Relative-шлях до файлу-порушника (опційно).
+   * @returns {void}
+   */
+  const add = (reason, message, file) => {
+    const v = { ruleId, concernId, reason, message, severity: 'error' }
+    if (file) v.file = file
+    violations.push(/** @type {LintViolation} */ (v))
+  }
+
+  const files = await resolveTargetFiles(cfg.files, cwd, new Map())
+  if (files.length === 0) {
+    if (cfg.files.required && cfg.files.single) {
+      const msg = cfg.missingMessage ?? `${cfg.files.single} не існує — створи згідно main.mdc (${ruleId}/${concernId})`
+      add('policy-file-missing', msg, cfg.files.single)
+    }
+    return { violations }
+  }
+
+  if (cfg.engine === 'template') {
+    const data = await resolveConcernTemplateData(cfg.policyDir, { files: cfg.files, check: 'template' })
+    if (!data) return { violations } // немає сніпета → нічого перевіряти
+    for (const file of files) {
+      const rel = toRel(file, cwd)
+      const actual = await parseByExt(file)
+      const opts = { targetPath: rel, source: 'main.mdc' }
+      const msgs = [
+        ...(typeof data.snippet === 'string'
+          ? checkTextSubset(actual, data.snippet, opts)
+          : checkSnippet(actual, data.snippet, opts)),
+        ...checkDeny(actual, data.deny, opts),
+        ...checkContains(actual, data.contains, opts)
+      ]
+      for (const m of msgs) add('policy-template-mismatch', m, rel)
+    }
+    return { violations }
+  }
+
+  // Rego
+  const namespace = `${ruleId.replaceAll('-', '_')}.${concernId}`
+  const templateData = await resolveConcernTemplateData(cfg.policyDir, { files: cfg.files })
+  const denies = runConftestBatch({
+    policyDirRel: `${ruleId}/${concernId}`,
+    namespace,
+    files,
+    templateData
+  })
+  for (const d of denies) add('policy-deny', d.message, d.filename ? toRel(d.filename, cwd) : undefined)
+  return { violations }
+}

package/scripts/lib/lint-surface/policy-test-step.mjs

@@ -0,0 +1,149 @@
+/**
+ * Policy source test-step (spec 2026-06-29 §Policy Unit Tests).
+ *
+ * `<concern>_test.rego` — це source-validation policy-concern-а (НЕ окремий consumer
+ * detector і НЕ четверта surface). Runner знаходить policy.engine:'rego' concern-и з
+ * `<concern>_test.rego` іганяє `conftest verify` по їх теці; failures нормалізує у
+ * `LintViolation { reason: 'rego-unit-test-failed' }`.
+ *
+ * Запуск (зі специфікації): у `lint --no-fix --full`, або в delta якщо змінився
+ * concern.json/.rego/_test.rego/template/ концерну; перед policy codegen/evaluate.
+ * @typedef {import('./types.mjs').LintViolation} LintViolation
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+import { readConcernMeta } from '../concern-meta.mjs'
+import { resolveCmd } from '../../utils/resolve-cmd.mjs'
+
+/**
+ * Дефолтний раннер conftest verify. Інжектиться у тестах.
+ * @param {string} concernDir тека concern-а для conftest verify.
+ * @returns {{ ok: boolean, failures: Array<{ name: string, msg: string }>, skipped?: boolean }} результат прогону: успіх, перелік провалів, skipped якщо conftest відсутній.
+ */
+function defaultRunner(concernDir) {
+  const conftest = resolveCmd('conftest')
+  if (!conftest) return { ok: true, failures: [], skipped: true }
+  const r = spawnSync(conftest, ['verify', '-p', concernDir, '--output', 'json', '--no-color'], {
+    encoding: 'utf8'
+  })
+  if (r.status === 0) return { ok: true, failures: [] }
+  /** @type {Array<{ name: string, msg: string }>} */
+  const failures = []
+  try {
+    const parsed = JSON.parse(r.stdout || '[]')
+    for (const entry of parsed) {
+      for (const f of entry.failures ?? []) failures.push({ name: entry.namespace ?? 'test', msg: f.msg ?? String(f) })
+    }
+  } catch {
+    failures.push({ name: 'conftest', msg: (r.stderr || r.stdout || 'conftest verify failed').trim().slice(0, 300) })
+  }
+  return { ok: failures.length === 0, failures }
+}
+
+/**
+ * Чи має concern policy.engine:'rego' + `<concern>_test.rego`.
+ * @param {string} concernDir тека concern-а.
+ * @param {string} concernName назва concern-а.
+ * @returns {Promise<boolean>} true, якщо concern rego-двигуна має `<concern>_test.rego`.
+ */
+async function hasRegoTests(concernDir, concernName) {
+  if (!existsSync(join(concernDir, `${concernName}_test.rego`))) return false
+  const meta = await readConcernMeta(concernDir, concernName)
+  return Boolean(meta?.policy && meta.policy.engine === 'rego')
+}
+
+/**
+ * @typedef {(concernDir: string) => { ok: boolean, failures: Array<{ name: string, msg: string }>, skipped?: boolean }} PolicyTestRunner
+ */
+
+/**
+ * Прогін одного rego-concern-а: запуск runner-а й нормалізація failures у violations.
+ * @param {string} ruleName назва rule-а (= ruleId).
+ * @param {string} concernName назва concern-а.
+ * @param {string} concernDir тека concern-а.
+ * @param {string} cwd для posix-relative file у violation.
+ * @param {PolicyTestRunner} runner раннер conftest verify.
+ * @returns {{ violations: LintViolation[], skipped: boolean, ran: boolean }} violations concern-а, skipped-прапорець і чи був прогін.
+ */
+function runConcernTests(ruleName, concernName, concernDir, cwd, runner) {
+  const res = runner(concernDir)
+  if (res.skipped) return { violations: [], skipped: true, ran: false }
+  const testRel = (relative(cwd, join(concernDir, `${concernName}_test.rego`)) || `${concernName}_test.rego`)
+    .split('\\')
+    .join('/')
+  /** @type {LintViolation[]} */
+  const violations = res.failures.map(f => ({
+    ruleId: ruleName,
+    concernId: concernName,
+    reason: 'rego-unit-test-failed',
+    message: `${concernName}_test.rego: ${f.name} — ${f.msg}`,
+    file: testRel,
+    severity: 'error',
+    data: { engine: 'conftest' }
+  }))
+  return { violations, skipped: false, ran: true }
+}
+
+/**
+ * Прогін усіх rego-concern-ів одного rule-а.
+ * @param {string} ruleName назва rule-а.
+ * @param {string} ruleDir тека rule-а.
+ * @param {string} cwd для posix-relative file у violation.
+ * @param {PolicyTestRunner} runner раннер conftest verify.
+ * @returns {Promise<{ violations: LintViolation[], skipped: boolean, ran: number }>} violations rule-а, skipped-прапорець і кількість прогонів.
+ */
+async function runRuleTests(ruleName, ruleDir, cwd, runner) {
+  /** @type {LintViolation[]} */
+  const violations = []
+  let skipped = false
+  let ran = 0
+  for (const concernName of readdirSync(ruleDir).toSorted()) {
+    if (concernName.startsWith('.')) continue
+    const concernDir = join(ruleDir, concernName)
+    if (!statSync(concernDir).isDirectory()) continue
+    if (!(await hasRegoTests(concernDir, concernName))) continue
+
+    const res = runConcernTests(ruleName, concernName, concernDir, cwd, runner)
+    if (res.skipped) {
+      skipped = true
+      continue
+    }
+    if (res.ran) ran++
+    violations.push(...res.violations)
+  }
+  return { violations, skipped, ran }
+}
+
+/**
+ * Запускає policy unit-tests по всіх (або вибраних) rego-concern-ах.
+ * @param {string} rulesDir коренева тека rule-ів.
+ * @param {string} cwd для posix-relative file у violation.
+ * @param {object} [opts] опції запуску.
+ * @param {string[]} [opts.rules] обмежити цими rule-id.
+ * @param {PolicyTestRunner} [opts.runner] інжектований раннер (для тестів).
+ * @returns {Promise<{ violations: LintViolation[], skipped: boolean, ran: number }>} порушення, прапорець skipped і кількість прогонів.
+ */
+export async function runPolicyUnitTests(rulesDir, cwd, opts = {}) {
+  const runner = opts.runner ?? defaultRunner
+  const ruleFilter = Array.isArray(opts.rules) && opts.rules.length > 0 ? new Set(opts.rules) : null
+  /** @type {LintViolation[]} */
+  const violations = []
+  let skipped = false
+  let ran = 0
+
+  if (!existsSync(rulesDir)) return { violations, skipped, ran }
+  for (const ruleName of readdirSync(rulesDir).toSorted()) {
+    if (ruleName.startsWith('.')) continue
+    if (ruleFilter && !ruleFilter.has(ruleName)) continue
+    const ruleDir = join(rulesDir, ruleName)
+    if (!statSync(ruleDir).isDirectory()) continue
+
+    const res = await runRuleTests(ruleName, ruleDir, cwd, runner)
+    if (res.skipped) skipped = true
+    ran += res.ran
+    violations.push(...res.violations)
+  }
+  return { violations, skipped, ran }
+}

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

@@ -0,0 +1,198 @@
+/**
+ * Спільний ProgressReporter для довгих lint/fix-прогонів unified lint surface
+ * (spec docs/specs/2026-07-03-lint-progress-bar-design.md; канон — scripts.mdc
+ * «Прогрес довгих lint/fix-прогонів»).
+ *
+ * Гібридна одиниця прогресу: монотонний бар по концернах (total відомий з плану
+ * детекції) + тикер порушень «знайдено / виправлено». Семантика лічильників
+ * «не бреше вниз»: re-detect, що відкрив нові порушення (маскування,
+ * standalone-T0), збільшує `found`, а не ховається.
+ *
+ * TTY-розгалуження авто: isTTY → однорядковий бар (`cli-progress` MultiBar;
+ * решта виводу — через обгорнутий `log`, який друкує над баром); не-TTY (CI,
+ * hooks, пайпи) → append-only рядок зведення на кожну оброблену одиницю,
+ * без ANSI.
+ */
+import cliProgress from 'cli-progress'
+
+/** Ширина смуги бара в символах. */
+const BAR_WIDTH = 20
+
+/**
+ * Рендерить один рядок прогресу — спільний формат для TTY-бара цього reporter-а
+ * та для прогресу чужого прогону, який показує процес у черзі
+ * (`lint-lock.mjs` читає знімок зі стан-файлу і показує його тим самим рядком).
+ * @param {{ done: number, total: number, found: number, fixed: number, current: string, unitLabel?: string, withFixed?: boolean }} snap знімок прогресу
+ * @returns {string} готовий рядок бара
+ */
+export function renderProgressLine(snap) {
+  const unitLabel = snap.unitLabel ?? 'концернів'
+  const progress = snap.total > 0 ? Math.min(1, snap.done / snap.total) : 0
+  const filled = Math.round(progress * BAR_WIDTH)
+  const bar = '█'.repeat(filled) + '░'.repeat(BAR_WIDTH - filled)
+  const ticker = (snap.withFixed ?? true) ? ` · знайдено ${snap.found} · виправлено ${snap.fixed}` : ''
+  return `[${bar}] ${snap.done}/${snap.total} ${unitLabel}${ticker} · ${snap.current}`
+}
+
+/**
+ * Кастомний formatter (функція, не format-рядок): дефолтний formatter cli-progress
+ * тягне CJS `require('string-width')`, який під bun-хойстингом отримує ESM-only v8
+ * і падає (`_stringWidth is not a function`). Функція-formatter обходить його повністю.
+ * @param {object} _options опції бара (не використовуються — символи фіксовані в renderProgressLine)
+ * @param {object} params стан бара (value/total/progress)
+ * @param {object} payload наш payload (unitLabel/found/fixed/current/withFixed)
+ * @returns {string} готовий рядок бара
+ */
+function formatBar(_options, params, payload) {
+  return renderProgressLine({
+    done: params.value,
+    total: params.total,
+    found: payload.found,
+    fixed: payload.fixed,
+    current: payload.current,
+    unitLabel: payload.unitLabel,
+    withFixed: payload.withFixed
+  })
+}
+
+/**
+ * @typedef {object} ProgressReporter
+ * @property {(s: string) => void} log обгорнутий логер: у TTY друкує над баром, інакше — прямий
+ * @property {(label: string, tier?: string) => void} concernStart оновити суфікс поточної одиниці
+ * @property {(key: string, count: number) => void} detectSnapshot знімок detect/re-detect (кількість порушень)
+ * @property {(key: string) => void} concernDone одиницю оброблено (закриту чи ні) — бар +1
+ * @property {() => { done: number, total: number, found: number, fixed: number }} summary поточні лічильники
+ * @property {() => void} stop фінальний render і звільнення TTY-рядка
+ */
+
+/**
+ * Створює reporter. `total` — кількість одиниць (концернів/файлів) з плану.
+ * @param {object} opts опції
+ * @param {number} opts.total загальна кількість одиниць прогону
+ * @param {(s: string) => void} opts.log базовий логер (типово process.stdout.write)
+ * @param {boolean} [opts.isTTY] явний override TTY-режиму; типово process.stdout.isTTY
+ * @param {string} [opts.unitLabel] підпис одиниці в барі (типово 'концернів')
+ * @param {boolean} [opts.withFixed] чи показувати тикер «знайдено/виправлено» (типово true)
+ * @param {(snap: { done: number, total: number, found: number, fixed: number, current: string }) => void} [opts.onUpdate] колбек на кожну зміну стану — для публікації прогресу назовні (черга lint)
+ * @param {boolean} [opts.appendInNonTTY] чи друкувати append-рядки ⏱ у не-TTY (типово true); false — «мовчазний» reporter лише для onUpdate-публікації
+ * @returns {ProgressReporter} reporter
+ */
+export function createProgressReporter(opts) {
+  const { total } = opts
+  const baseLog = opts.log
+  const isTTY = opts.isTTY ?? process.stdout.isTTY === true
+  const unitLabel = opts.unitLabel ?? 'концернів'
+  const withFixed = opts.withFixed !== false
+  const appendInNonTTY = opts.appendInNonTTY !== false
+
+  /** @type {Map<string, { found: number, remaining: number }>} */
+  const counters = new Map()
+  let done = 0
+  let current = '…'
+
+  /**
+   * Пер-ключ стан лічильників (лениве створення).
+   * @param {string} key ключ одиниці (`rule/concern` або шлях файлу)
+   * @returns {{ found: number, remaining: number }} стан
+   */
+  function stateFor(key) {
+    let s = counters.get(key)
+    if (!s) {
+      s = { found: 0, remaining: 0 }
+      counters.set(key, s)
+    }
+    return s
+  }
+
+  /**
+   * Агрегує тикер по всіх ключах.
+   * @returns {{ found: number, fixed: number }} суми
+   */
+  function tally() {
+    let found = 0
+    let fixed = 0
+    for (const s of counters.values()) {
+      found += s.found
+      fixed += s.found - s.remaining
+    }
+    return { found, fixed }
+  }
+
+  /** @type {import('cli-progress').MultiBar|null} */
+  let multibar = null
+  /** @type {import('cli-progress').SingleBar|null} */
+  let bar = null
+  if (isTTY && total > 0) {
+    multibar = new cliProgress.MultiBar(
+      {
+        format: formatBar,
+        clearOnComplete: true,
+        hideCursor: true,
+        barCompleteChar: '█',
+        barIncompleteChar: '░'
+      },
+      cliProgress.Presets.shades_classic
+    )
+    bar = multibar.create(total, 0, { unitLabel, withFixed, found: 0, fixed: 0, current })
+  }
+
+  /** Перемальовує бар актуальним payload-ом (TTY) і публікує знімок назовні. */
+  function redraw() {
+    const { found, fixed } = tally()
+    opts.onUpdate?.({ done, total, found, fixed, current })
+    if (!bar) return
+    bar.update(done, { unitLabel, withFixed, found, fixed, current })
+  }
+
+  return {
+    log: s => {
+      // multibar.log вимагає рядок із \n наприкінці — інакше рве перемальовування.
+      if (multibar) multibar.log(s.endsWith('\n') ? s : `${s}\n`)
+      else baseLog(s)
+    },
+
+    concernStart: (label, tier) => {
+      current = tier ? `${label} (${tier})` : label
+      redraw()
+    },
+
+    detectSnapshot: (key, count) => {
+      const s = stateFor(key)
+      // found «не бреше вниз»: якщо re-detect показав більше, ніж (remaining + вже
+      // зафіксовані виправлення), — found росте (маскування, standalone-T0).
+      const fixedPrev = s.found - s.remaining
+      s.found = Math.max(s.found, count + fixedPrev)
+      s.remaining = count
+      redraw()
+    },
+
+    concernDone: key => {
+      done += 1
+      // Одиниця без жодного знімка (порожній концерн) — ключ все одно матеріалізується,
+      // щоб summary().found був повним.
+      stateFor(key)
+      redraw()
+      if (!bar && appendInNonTTY) {
+        const { found, fixed } = tally()
+        const ticker = withFixed ? ` · знайдено ${found} · виправлено ${fixed}` : ''
+        baseLog(`  ⏱ ${done}/${total} ${unitLabel}${ticker}\n`)
+      }
+    },
+
+    summary: () => {
+      const { found, fixed } = tally()
+      return { done, total, found, fixed }
+    },
+
+    stop: () => {
+      if (!multibar) {
+        return
+      }
+
+      redraw()
+      multibar.stop()
+      multibar = null
+      bar = null
+    }
+  }
+}