@7n/rules 1.0.0

package/scripts/lib/gha-workflow.mjs

@@ -0,0 +1,220 @@
+/**
+ * Допоміжні функції для аналізу GitHub Actions workflow (`.yml`) після структурного розбору YAML.
+ *
+ * Використовується в check-ga, check-js, check-text, check-style, check-npm-module замість
+ * пошуку підрядків у сирому тексті там, де важливі лише значення `uses:` та `run:` кроків.
+ *
+ * Для `run:` також виявляється shell-продовження рядка через `\\` перед переносом (антипатерн у ga.mdc).
+ */
+import { parse } from 'yaml'
+
+const CHECKOUT_V6_USES = 'actions/checkout@v6'
+const LOCAL_SETUP_BUN_DEPS_MARKER = './.github/actions/setup-bun-deps'
+const BUNX_OXLINT_FIX_RE = /bunx\s+oxlint[^\n]*--fix/u
+
+/**
+ * Парсить workflow YAML у звичайний об’єкт; при синтаксичній помилці — `null`.
+ * @param {string} content вміст файлу
+ * @returns {Record<string, unknown> | null} корінь документа або `null`
+ */
+export function parseWorkflowYaml(content) {
+  try {
+    const root = parse(content)
+    return root && typeof root === 'object' ? /** @type {Record<string, unknown>} */ (root) : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Збирає всі кроки з усіх jobs.
+ * @param {Record<string, unknown>} root корінь workflow
+ * @returns {{ jobId: string, stepIndex: number, step: Record<string, unknown> }[]} плоский список кроків з метаданими
+ */
+export function flattenWorkflowSteps(root) {
+  /** @type {{ jobId: string, stepIndex: number, step: Record<string, unknown> }[]} */
+  const out = []
+  for (const [jobId, job] of workflowJobsEntries(root)) {
+    const steps = workflowJobSteps(job)
+    for (const [stepIndex, step] of steps.entries()) {
+      out.push({ jobId, stepIndex, step })
+    }
+  }
+  return out
+}
+
+/**
+ * Значення `uses:` кроку.
+ * @param {Record<string, unknown>} step об’єкт одного елемента `steps`
+ * @returns {string} рядок `uses` або порожній рядок
+ */
+export function getStepUses(step) {
+  return typeof step.uses === 'string' ? step.uses : ''
+}
+
+/**
+ * Значення `run:` кроку (багаторядковий рядок або масив рядків у YAML).
+ * @param {Record<string, unknown>} step об’єкт одного елемента `steps`
+ * @returns {string} текст команди
+ */
+export function getStepRun(step) {
+  const r = step.run
+  if (typeof r === 'string') {
+    return r
+  }
+  if (Array.isArray(r)) {
+    return r.map(String).join('\n')
+  }
+  return ''
+}
+
+/**
+ * Чи є в `on.push.paths` (або `on.pull_request.paths`) елемент з точним значенням.
+ * @param {Record<string, unknown>} root корінь workflow
+ * @param {'push' | 'pull_request'} event ім’я ключа в `on`
+ * @param {string} exact очікуваний glob
+ * @returns {boolean} `true`, якщо шлях присутній у масиві `paths`
+ */
+export function eventPathsIncludeExact(root, event, exact) {
+  const on = root?.on
+  if (!on || typeof on !== 'object') {
+    return false
+  }
+  const ev = /** @type {Record<string, unknown>} */ (on)[event]
+  if (!ev || typeof ev !== 'object') {
+    return false
+  }
+  const paths = /** @type {Record<string, unknown>} */ (ev).paths
+  if (!Array.isArray(paths)) {
+    return false
+  }
+  return paths.includes(exact)
+}
+
+/**
+ * Перевірки для `lint-js.yml`: checkout@v6, persist-credentials, setup-bun-deps, run-команди.
+ * @param {Record<string, unknown> | null} root корінь workflow або `null` якщо parse не вдався
+ * @returns {{ ok: boolean, failures: string[] }} результат перевірки та список причин відмови
+ */
+export function verifyLintJsWorkflowStructure(root) {
+  if (!root) {
+    return { ok: false, failures: ['YAML не вдалося розібрати — перевір синтаксис workflow'] }
+  }
+
+  /** @type {string[]} */
+  const failures = []
+  const steps = flattenWorkflowSteps(root)
+  const usesList = steps.map(s => getStepUses(s.step))
+  const runBlob = steps.map(s => getStepRun(s.step)).join('\n')
+
+  if (usesList.every(u => !u.includes(CHECKOUT_V6_USES))) {
+    failures.push('немає кроку uses: actions/checkout@v6')
+  }
+
+  if (!hasCheckoutWithPersistCredentialsFalse(steps)) {
+    failures.push('checkout@v6 без with.persist-credentials: false')
+  }
+
+  if (usesList.every(u => !u.includes(LOCAL_SETUP_BUN_DEPS_MARKER))) {
+    failures.push('немає uses: ./.github/actions/setup-bun-deps')
+  }
+
+  if (!runBlob.includes('bunx oxlint')) {
+    failures.push('у run немає bunx oxlint')
+  }
+  if (!runBlob.includes('bunx eslint .')) {
+    failures.push('у run немає bunx eslint .')
+  }
+  if (!runBlob.includes('bunx jscpd .')) {
+    failures.push('у run немає bunx jscpd .')
+  }
+
+  appendCiFixFlagFailures(failures, steps)
+
+  return failures.length === 0 ? { ok: true, failures: [] } : { ok: false, failures }
+}
+
+/**
+ * Чи є в будь-якому `run` кроку підрядок (наприклад `n-rules lint text --no-fix`).
+ * @param {Record<string, unknown>} root корінь workflow
+ * @param {string} needle підрядок для пошуку
+ * @returns {boolean} `true`, якщо хоча б один `run` містить `needle`
+ */
+export function anyRunStepIncludes(root, needle) {
+  for (const { step } of flattenWorkflowSteps(root)) {
+    if (getStepRun(step).includes(needle)) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * Повертає jobs як список пар [jobId, job], якщо структура валідна.
+ * @param {Record<string, unknown>} root корінь workflow
+ * @returns {[string, Record<string, unknown>][]} список jobs
+ */
+function workflowJobsEntries(root) {
+  const jobs = root?.jobs
+  if (!jobs || typeof jobs !== 'object') {
+    return []
+  }
+  return Object.entries(jobs).flatMap(([jobId, job]) =>
+    job && typeof job === 'object' ? [[jobId, /** @type {Record<string, unknown>} */ (job)]] : []
+  )
+}
+
+/**
+ * Повертає валідні кроки job.
+ * @param {Record<string, unknown>} job job-об’єкт
+ * @returns {Record<string, unknown>[]} кроки job
+ */
+function workflowJobSteps(job) {
+  const steps = /** @type {{ steps?: unknown }} */ (job).steps
+  if (!Array.isArray(steps)) {
+    return []
+  }
+  return steps.flatMap(step =>
+    step && typeof step === 'object' ? [/** @type {Record<string, unknown>} */ (step)] : []
+  )
+}
+
+/**
+ * Чи є checkout@v6 з `persist-credentials: false`.
+ * @param {{ step: Record<string, unknown> }[]} steps кроки flattenWorkflowSteps
+ * @returns {boolean} true, якщо знайдено очікуваний checkout
+ */
+function hasCheckoutWithPersistCredentialsFalse(steps) {
+  for (const { step } of steps) {
+    const uses = getStepUses(step)
+    if (uses.includes(CHECKOUT_V6_USES)) {
+      const withObj = step.with
+      if (
+        withObj &&
+        typeof withObj === 'object' &&
+        /** @type {Record<string, unknown>} */ (withObj)['persist-credentials'] === false
+      ) {
+        return true
+      }
+    }
+  }
+  return false
+}
+
+/**
+ * Додає порушення для `--fix` у CI-кроках lint-js workflow.
+ * @param {string[]} failures акумулятор порушень
+ * @param {{ step: Record<string, unknown> }[]} steps кроки flattenWorkflowSteps
+ * @returns {void}
+ */
+function appendCiFixFlagFailures(failures, steps) {
+  for (const { step } of steps) {
+    const run = getStepRun(step)
+    if (BUNX_OXLINT_FIX_RE.test(run)) {
+      failures.push('у run є oxlint з --fix (у CI заборонено)')
+    }
+    if (run.includes('eslint --fix')) {
+      failures.push('у run є eslint --fix (у CI заборонено)')
+    }
+  }
+}

package/scripts/lib/inline-template-links.mjs

@@ -0,0 +1,108 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { basename, extname, join } from 'node:path'
+import { globby } from 'globby'
+
+const MD_LINK_RE = /\[([^\]]{1,200})\]\((\.\/[^)]{1,500})\)/g
+const TEMPLATE_SEGMENT_RE = /\/templates?\//
+/** Статичні regexp-літерали `^(.+)\.<slot>\.<ext>$` — без `RegExp(variable)`. */
+const SLOT_SUFFIX_RES = [/^(.+)\.snippet\.[^.]+$/, /^(.+)\.deny\.[^.]+$/, /^(.+)\.contains\.[^.]+$/]
+
+/**
+ * @param {string} filePath шлях до файлу
+ * @returns {string} назва мови для fenced-блока
+ */
+function langFromExt(filePath) {
+  const ext = extname(filePath)
+  if (ext === '.json') return 'json'
+  if (ext === '.toml') return 'toml'
+  if (ext === '.yml' || ext === '.yaml') return 'yaml'
+  return ''
+}
+
+// Strip `.<slot>.<ext>` suffix (slot ∈ snippet/deny/contains) to recover the
+// real target file name (e.g. `package.json.snippet.json` → `package.json`).
+/**
+ * @param {string} fileBasename базове ім'я template-файлу
+ * @returns {string} ім'я реального target-файлу
+ */
+function normalizeTargetName(fileBasename) {
+  for (const re of SLOT_SUFFIX_RES) {
+    const m = fileBasename.match(re)
+    if (m) return m[1]
+  }
+  return fileBasename
+}
+
+/**
+ * Finds markdown links whose path contains /template/ and replaces them with
+ * inline fenced blocks. Reads file from join(ruleDir, rel-path).
+ * Throws Error if a matched link target doesn't exist (fail loud — user must know).
+ * @param {string} text .mdc file contents
+ * @param {string} ruleDir absolute path to the rule directory (e.g. .../npm/rules/security/)
+ * @returns {Promise<string>} transformed text
+ */
+export async function inlineTemplateLinks(text, ruleDir) {
+  const matches = text
+    .matchAll(MD_LINK_RE)
+    .filter(m => TEMPLATE_SEGMENT_RE.test(m[2]))
+    .toArray()
+  if (matches.length === 0) return text
+
+  let result = text
+  for (const match of matches) {
+    const [fullMatch, , href] = match
+    // href starts with ./ (regex) and contains /template/ (filter above)
+    const relPath = href.slice(2) // strip leading ./
+    const absPath = join(ruleDir, relPath)
+
+    if (!existsSync(absPath)) {
+      throw new Error(`inlineTemplateLinks: file not found: ${absPath} (referenced from .mdc)`)
+    }
+
+    const raw = await readFile(absPath, 'utf8')
+    const contents = raw.trim()
+    const lang = langFromExt(absPath)
+    const targetName = normalizeTargetName(basename(absPath))
+    const replacement = `\`${targetName}\`:\n\n\`\`\`${lang}\n${contents}\n\`\`\``
+    result = result.replace(fullMatch, () => replacement)
+  }
+
+  return result
+}
+
+/**
+ * Appends all *.mdc files from concern subdirectories (those with concern.json).
+ * Concerns ordered alphabetically; files within each concern ordered alphabetically.
+ * @param {string} text rule content (after inlineTemplateLinks)
+ * @param {string} ruleDir absolute path to the rule directory
+ * @returns {Promise<string>} text with discovered concern docs appended
+ */
+export async function appendDiscoveredMdcFiles(text, ruleDir) {
+  const { readdir } = await import('node:fs/promises')
+  const sections = []
+
+  let entries
+  try {
+    entries = await readdir(ruleDir, { withFileTypes: true })
+  } catch {
+    return text
+  }
+
+  const concernDirs = entries
+    .filter(e => e.isDirectory() && !e.name.startsWith('.') && existsSync(join(ruleDir, e.name, 'concern.json')))
+    .map(e => e.name)
+    .toSorted()
+
+  for (const dir of concernDirs) {
+    const concernDir = join(ruleDir, dir)
+    const files = await globby('*.mdc', { cwd: concernDir, onlyFiles: true, gitignore: false })
+    for (const f of files.toSorted()) {
+      const raw = await readFile(join(concernDir, f), 'utf8')
+      sections.push(raw.trim())
+    }
+  }
+
+  if (sections.length === 0) return text
+  return text.trimEnd() + '\n\n' + sections.join('\n\n') + '\n'
+}

package/scripts/lib/lint-surface/codegen-opa-wrapper.mjs

@@ -0,0 +1,30 @@
+/**
+ * Хелпери для policy-concern detector-а (spec 2026-06-29 §Policy Codegen, ревізовано —
+ * див. ADR про пряму оцінку policy-concern-ів без generated `main.mjs`).
+ *
+ * `main.mjs` для чисто policy-concern-ів (rego/template) більше не потрібен: `detect.mjs`
+ * викликає `evaluatePolicyConcern` напряму з `concern.json`. Ручний (не-`@generated`)
+ * `main.mjs` лишається escape-hatch-ом для custom-detector-ів — `isGeneratedFile` дозволяє
+ * відрізнити старий codegen-артефакт від ручного файлу.
+ */
+const GENERATED_MARK = '// @generated — do not edit'
+
+/**
+ * @param {string} content вміст main.mjs.
+ * @returns {boolean} чи це (застарілий) згенерований, а не ручний файл.
+ */
+export function isGeneratedFile(content) {
+  return content.startsWith(GENERATED_MARK)
+}
+
+/**
+ * Чи policy.files резолвиться у конкретні таргети (single або walkGlob).
+ * Концерни без цього — або orchestrated parent-концерном (rego-бібліотека), або
+ * incomplete; напряму (без parent-оркестратора) оцінити такий concern не можна.
+ * @param {object|undefined} files об'єкт policy.files concern-а.
+ * @returns {boolean} true, якщо files резолвиться у конкретні таргети.
+ */
+export function hasResolvableFiles(files) {
+  if (!files || typeof files !== 'object') return false
+  return typeof files.single === 'string' || files.walkGlob !== undefined
+}

package/scripts/lib/lint-surface/collateral-veto.mjs

@@ -0,0 +1,55 @@
+/**
+ * Semantic-collateral veto для verdict-фази fix-pipeline
+ * (spec docs/specs/2026-06-26-pi-fix-engine-migration.md §12, addendum 2026-07-05).
+ *
+ * Клас collateral слабких локальних моделей: «виправляючи» правило, модель робить
+ * семантичну правку у сторонньому файлі, яка НЕ порушує жодного правила й тому
+ * проходить canonical re-detect (живий кейс App.vue: хардкод версії `'0.3.0'` з
+ * коментарем "we simulate it being available" замість наявного `await getVersion()`).
+ *
+ * Правило veto: rung не приймається, якщо він ЗМІНИВ наявний файл поза target-set
+ * порушення. Нові файли дозволені — легітимний клас (scaffold, доки поряд із кодом);
+ * їх однаково покриває re-check зачеплених файлів і rollback. Порожній target-set
+ * (whole-repo концерни без `file` у violations) → veto незастосовний (fail-open,
+ * повертає []) — свідомо, щоб не ламати концерни без file-атрибуції.
+ */
+import { realpathSync } from 'node:fs'
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
+
+/**
+ * realpath шляху з найкращих зусиль: для наявного — повний realpath; для ще-неіснуючого —
+ * realpath батьківської теки + basename; інакше — як є. Знімає розбіжність symlink-шляхів
+ * (macOS `/tmp` → `/private/tmp`) між snapshot-ключами і target-set (той самий патерн,
+ * що у write-guard llm-lib). Експортовано, щоб caller relativize-ив результати veto від
+ * так само нормалізованого cwd.
+ * @param {string} p шлях
+ * @returns {string} нормалізований абсолютний шлях
+ */
+export function realpathBestEffort(p) {
+  try {
+    return realpathSync(p)
+  } catch {
+    try {
+      return join(realpathSync(dirname(p)), basename(p))
+    } catch {
+      return p
+    }
+  }
+}
+
+/**
+ * Обчислює collateral-правки rung-а: наявні (на момент S1) файли, змінені поза
+ * target-set порушення. Runner на непорожньому результаті відхиляє clean-вердикт
+ * rung-а (rollback + feedback + телеметрія `kind:"collateral-veto"`).
+ * @param {{ modifiedExisting: string[], targetFiles: string[], cwd: string }} args
+ *   modifiedExisting — абсолютні шляхи наявних файлів, змінених відносно S1
+ *   (`snapshot.modifiedExisting()`); targetFiles — файли порушення
+ *   (`violations[].file ∪ item.files`), відносні до cwd або абсолютні.
+ * @returns {string[]} нормалізовані абсолютні шляхи відхилених правок; порожньо —
+ *   veto не спрацював (нема collateral або target-set невідомий)
+ */
+export function findCollateralEdits({ modifiedExisting, targetFiles, cwd }) {
+  const targets = new Set(targetFiles.map(f => realpathBestEffort(isAbsolute(f) ? f : resolve(cwd, f))))
+  if (targets.size === 0) return []
+  return modifiedExisting.map(p => realpathBestEffort(p)).filter(abs => !targets.has(abs))
+}

package/scripts/lib/lint-surface/default-worker.mjs

@@ -0,0 +1,67 @@
+/**
+ * Дефолтний LLM fix-worker unified lint surface: адаптер `runPiAgentFix` під контракт
+ * `fixWorker(violations, ctx) → { touchedFiles, telemetry? }`. Використовується central
+ * pipeline-ом, коли у concern-а немає власного `fix-worker.mjs`.
+ *
+ * Central rollback: pi write-guard міст через `onCapture = ctx.recordWrite` (pre-image
+ * у central snapshot ДО запису), тож rollback rung-а відкочує і LLM-правки. Worker —
+ * один attempt; success визначає canonical re-detect runner-а, не сам worker.
+ * @typedef {import('./types.mjs').FixWorkerFn} FixWorkerFn
+ */
+import { resolve } from 'node:path'
+import { env } from 'node:process'
+
+import { renderViolations } from './render.mjs'
+
+/**
+ * Anchored-edits профіль (Фаза A2). Дефолт `cloud` — за bench A/B 2026-07-11
+ * (docs/specs/2026-07-11-anchored-verify-bench-results.md): на cloud паритет
+ * коректності при ~+10% латентності = дешева страховка від collateral-класу;
+ * на local-4B протокол 9× повільніший на edit-фікстурі — off.
+ * Env `N_LLM_FIX_ANCHORED`: `1` — усі тири; `cloud` — лише не-local; `0` — вимкнено.
+ * @param {string|undefined} model "provider/model-id" рунга
+ * @param {(spec: string) => boolean} isLocal предикат local-моделі
+ * @returns {boolean} чи вмикати anchored-профіль для цього рунга
+ */
+export function anchoredEnabled(model, isLocal) {
+  const mode = env.N_LLM_FIX_ANCHORED ?? 'cloud'
+  if (mode === '1') return true
+  if (mode === 'cloud') return Boolean(model) && !isLocal(model)
+  return false
+}
+
+/** @type {FixWorkerFn} */
+export async function fixWorker(violations, ctx) {
+  // lazy import — тримає detect-шлях вільним від pi/oxc (read-only --no-fix не вантажить їх).
+  const [{ runAgentFix }, { isLocalModel }, { extractContext }] = await Promise.all([
+    import('@7n/llm-lib/agent-fix'),
+    import('@7n/llm-lib/model-tiers'),
+    import('../../utils/ast-extract.mjs')
+  ])
+  const violationText = renderViolations(violations)
+  // Target-set порушення → явний перелік у промпті (semantic-collateral guard §12,
+  // addendum 2026-07-05); verdict-veto runner-а звіряє фактичні правки з тим самим набором.
+  const targetFiles = [...new Set(violations.map(v => v.file).filter(Boolean))]
+  const res = await runAgentFix(ctx.ruleId, violationText, ctx.cwd, {
+    model: ctx.model,
+    tier: ctx.tier,
+    // Per-tier таймаут rung-а (ADR 260620-0556): без нього withTimeout у runAgentFix
+    // не влаштовує гонки і зависла cloud-SSE тримає весь lint (спостережено 1г41хв).
+    timeoutMs: ctx.timeoutMs,
+    feedback: ctx.feedback ?? null,
+    caller: `fix:${ctx.ruleId}/${ctx.concernId}:${ctx.tier}`,
+    recordWrite: ctx.recordWrite,
+    // Ланцюжок concern-а (fix-драбина) — рунг стає кроком ланцюжка.
+    chain: ctx.chain ?? null,
+    targetFiles,
+    // Evidence-гейт (Фаза A1): item-scoped canonical re-detect від runner-а — провал
+    // verify інʼєктиться фідбеком у ту саму pi-сесію замість одразу нового рунга.
+    verify: ctx.verify,
+    verifyMax: ctx.verifyMax,
+    anchoredEdits: anchoredEnabled(ctx.model, isLocalModel),
+    // n-rules-специфічний AST-екстрактор (oxc) — пакет цього дефолту не має.
+    deps: { astContext: p => extractContext(resolve(ctx.cwd, p)) }
+  })
+  if (res.error) throw new Error(res.error)
+  return { touchedFiles: res.touchedFiles ?? [], telemetry: res.telemetry ?? undefined }
+}

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

@@ -0,0 +1,169 @@
+/**
+ * Detect-крок unified lint surface: запуск одного concern-detector-а і нормалізація
+ * його `LintResult`. Detector — read-only; тут немає LLM, autofix чи мутацій дерева.
+ * @typedef {import('./types.mjs').LintContext} LintContext
+ * @typedef {import('./types.mjs').LintResult} LintResult
+ * @typedef {import('./types.mjs').LintViolation} LintViolation
+ * @typedef {import('./types.mjs').LintDiagnostic} LintDiagnostic
+ * @typedef {import('../concern-meta.mjs').ConcernMeta} ConcernMeta
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { hasResolvableFiles, isGeneratedFile } from './codegen-opa-wrapper.mjs'
+import { evaluatePolicyConcern } from './policy-lint-adapter.mjs'
+
+/**
+ * Сигнал, що detector кинув виняток / повернув невалідний результат → exit 2.
+ */
+export class DetectorError extends Error {
+  /**
+   * @param {string} ruleId id правила, у контексті якого стався збій
+   * @param {string} concernId id concern-а, у контексті якого стався збій
+   * @param {string} detail деталізація причини збою для повідомлення
+   */
+  constructor(ruleId, concernId, detail) {
+    super(`detector ${ruleId}/${concernId}: ${detail}`)
+    this.name = 'DetectorError'
+    this.ruleId = ruleId
+    this.concernId = concernId
+  }
+}
+
+/**
+ * Нормалізує одне порушення: домішує ruleId/concernId з ctx, валідує file-path.
+ * @param {unknown} raw сире порушення від detector-а
+ * @param {LintContext} ctx контекст лінту (джерело ruleId/concernId)
+ * @returns {LintViolation} нормалізоване порушення
+ */
+function normalizeViolation(raw, ctx) {
+  if (typeof raw !== 'object' || raw === null) {
+    throw new DetectorError(ctx.ruleId, ctx.concernId, "violation не є об'єктом")
+  }
+  const v = /** @type {Record<string, unknown>} */ (raw)
+  if (typeof v.reason !== 'string' || v.reason.length === 0) {
+    throw new DetectorError(ctx.ruleId, ctx.concernId, "violation.reason обов'язковий (непорожній string)")
+  }
+  if (typeof v.message !== 'string' || v.message.length === 0) {
+    throw new DetectorError(ctx.ruleId, ctx.concernId, "violation.message обов'язковий (непорожній string)")
+  }
+  let file
+  if (v.file !== undefined) {
+    if (typeof v.file !== 'string') {
+      throw new DetectorError(ctx.ruleId, ctx.concernId, 'violation.file має бути string')
+    }
+    if (v.file.startsWith('/') || v.file.split('/').includes('..')) {
+      throw new DetectorError(ctx.ruleId, ctx.concernId, `violation.file має бути posix-relative без "..": ${v.file}`)
+    }
+    file = v.file
+  }
+  const severity = v.severity === 'warn' ? 'warn' : 'error'
+  /** @type {LintViolation} */
+  const out = {
+    ruleId: ctx.ruleId,
+    concernId: ctx.concernId,
+    reason: v.reason,
+    message: v.message,
+    severity
+  }
+  if (file !== undefined) out.file = file
+  if (v.data !== undefined && typeof v.data === 'object' && v.data !== null) {
+    out.data = /** @type {Record<string, unknown>} */ (v.data)
+  }
+  return out
+}
+
+/**
+ * Нормалізує сирий результат detector-а.
+ * @param {unknown} raw сирий результат виклику lint()
+ * @param {LintContext} ctx контекст лінту (джерело ruleId/concernId)
+ * @returns {LintResult} нормалізований результат із violations (і diagnostics)
+ */
+function normalizeResult(raw, ctx) {
+  if (
+    typeof raw !== 'object' ||
+    raw === null ||
+    !Array.isArray(/** @type {Record<string, unknown>} */ (raw).violations)
+  ) {
+    throw new DetectorError(ctx.ruleId, ctx.concernId, 'lint() має повернути { violations: [...] }')
+  }
+  const r = /** @type {{ violations: unknown[], diagnostics?: unknown[] }} */ (raw)
+  const violations = r.violations.map(v => normalizeViolation(v, ctx))
+  /** @type {LintDiagnostic[]} */
+  let diagnostics = []
+  if (Array.isArray(r.diagnostics)) {
+    diagnostics = r.diagnostics
+      .filter(
+        d => d && typeof d === 'object' && typeof (/** @type {Record<string, unknown>} */ (d).message) === 'string'
+      )
+      .map(d => {
+        const dd = /** @type {{ level?: unknown, message: string }} */ (d)
+        return { level: dd.level === 'warn' ? 'warn' : 'info', message: dd.message }
+      })
+  }
+  return diagnostics.length > 0 ? { violations, diagnostics } : { violations }
+}
+
+/**
+ * Чи має concern ручний (не-`@generated`) `main.mjs`, що перекриває policy-adapter.
+ * @param {string} mainPath абсолютний шлях до `main.mjs` concern-а.
+ * @returns {boolean} true, якщо файл існує і не є codegen-артефактом.
+ */
+function hasHandWrittenMain(mainPath) {
+  if (!existsSync(mainPath)) return false
+  return !isGeneratedFile(readFileSync(mainPath, 'utf8'))
+}
+
+/**
+ * Запускає detector одного concern-а і нормалізує результат. Кидає `DetectorError`
+ * при будь-якій аномалії (→ exit 2).
+ *
+ * Чисті policy-concern-и (rego/template, без ручного `main.mjs`) оцінюються напряму
+ * через `evaluatePolicyConcern` з даних `concern.json` — генерований `main.mjs`
+ * для них не потрібен. Ручний (не-`@generated`) `main.mjs` — escape-hatch, він
+ * завжди має пріоритет. Concern-и без policy й без main.mjs — помилка конфігурації.
+ * @param {ConcernMeta} concern метадані concern-а, чий detector запускаємо
+ * @param {LintContext} ctx контекст лінту, що передається у lint()
+ * @returns {Promise<LintResult>} нормалізований результат detector-а
+ */
+export async function runConcernDetector(concern, ctx) {
+  const mainPath = join(concern.dir, 'main.mjs')
+
+  if (!hasHandWrittenMain(mainPath) && concern.policy && hasResolvableFiles(concern.policy.files)) {
+    let raw
+    try {
+      raw = await evaluatePolicyConcern(ctx, {
+        engine: concern.policy.engine,
+        policyDir: concern.dir,
+        files: concern.policy.files,
+        missingMessage: concern.policy.missingMessage
+      })
+    } catch (error) {
+      throw new DetectorError(ctx.ruleId, ctx.concernId, `policy-adapter кинув: ${error.message}`)
+    }
+    return normalizeResult(raw, ctx)
+  }
+
+  if (!existsSync(mainPath)) {
+    throw new DetectorError(ctx.ruleId, ctx.concernId, 'немає main.mjs')
+  }
+  let mod
+  try {
+    // file:// URL — інакше відносний шлях трактується як bare package specifier
+    // eslint-disable-next-line no-unsanitized/method
+    mod = await import(pathToFileURL(mainPath).href)
+  } catch (error) {
+    throw new DetectorError(ctx.ruleId, ctx.concernId, `import впав: ${error.message}`)
+  }
+  if (typeof mod.lint !== 'function') {
+    throw new DetectorError(ctx.ruleId, ctx.concernId, 'main.mjs не експортує lint(ctx)')
+  }
+  let raw
+  try {
+    raw = await mod.lint(ctx)
+  } catch (error) {
+    throw new DetectorError(ctx.ruleId, ctx.concernId, `lint() кинув: ${error.message}`)
+  }
+  return normalizeResult(raw, ctx)
+}