@7n/rules 1.0.0

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

@@ -0,0 +1,50 @@
+/**
+ * Єдиний renderer unified lint surface. Detector-и НЕ друкують основний violation-report —
+ * вони повертають `LintResult`, а runner рендерить тут. Це гарантує однаковий вигляд
+ * для всіх concern-ів і єдину точку форматування.
+ * @typedef {import('./types.mjs').LintViolation} LintViolation
+ * @typedef {import('./types.mjs').LintDiagnostic} LintDiagnostic
+ */
+
+/**
+ * @param {LintViolation} v порушення для форматування у рядок.
+ * @returns {string} відформатований рядок порушення.
+ */
+function formatViolation(v) {
+  const mark = v.severity === 'warn' ? '⚠' : '❌'
+  const loc = v.file ? ` → ${v.file}` : ''
+  return `  ${mark} ${v.ruleId}/${v.concernId}${loc} (${v.reason}): ${v.message}`
+}
+
+/**
+ * Рендерить порушення згруповані за concern-ом. Повертає текст (не друкує сам).
+ * @param {LintViolation[]} violations перелік порушень для рендеру.
+ * @returns {string} згрупований текст порушень (порожній рядок, якщо їх немає).
+ */
+export function renderViolations(violations) {
+  if (violations.length === 0) return ''
+  /** @type {Map<string, LintViolation[]>} */
+  const byConcern = new Map()
+  for (const v of violations) {
+    const key = `${v.ruleId}/${v.concernId}`
+    const arr = byConcern.get(key)
+    if (arr) arr.push(v)
+    else byConcern.set(key, [v])
+  }
+  const blocks = []
+  for (const [key, vs] of byConcern) {
+    blocks.push(`${key} — ${vs.length} порушення:`)
+    for (const v of vs) blocks.push(formatViolation(v))
+  }
+  return blocks.join('\n') + '\n'
+}
+
+/**
+ * Рендерить diagnostics (тех. інфа) — лише у verbose.
+ * @param {LintDiagnostic[]} diagnostics перелік diagnostics для рендеру.
+ * @returns {string} текст diagnostics (порожній рядок, якщо їх немає).
+ */
+export function renderDiagnostics(diagnostics) {
+  if (diagnostics.length === 0) return ''
+  return diagnostics.map(d => `  ${d.level === 'warn' ? '⚠' : 'ℹ'} ${d.message}`).join('\n') + '\n'
+}

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

@@ -0,0 +1,314 @@
+/**
+ * Detect-only оркестратор unified lint surface (`n-rules lint --no-fix`).
+ *
+ * Discovery → scope-selection → `lint(ctx)` per concern → нормалізовані violations.
+ * Без мутацій, без LLM. Fix-pipeline (T0 + ladder) обгортає цей модуль і споживає
+ * його violations; сам detect ніколи не пише в дерево.
+ * @typedef {import('./types.mjs').LintContext} LintContext
+ * @typedef {import('./types.mjs').LintViolation} LintViolation
+ * @typedef {import('../concern-meta.mjs').ConcernMeta} ConcernMeta
+ * @typedef {{ ruleId: string, concern: ConcernMeta }} LintEntry
+ */
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import picomatch from 'picomatch'
+
+import { listConcerns } from '../concern-meta.mjs'
+import { collectChangedFilesSince, resolveChangedBase } from '../changed-files.mjs'
+import { readNRulesConfigLite, isRuleEnabled } from '../read-n-rules-config-lite.mjs'
+import { runConcernDetector, DetectorError } from './detect.mjs'
+import { renderViolations, renderDiagnostics } from './render.mjs'
+import { createProgressReporter } from './progress.mjs'
+
+// Цей файл: npm/scripts/lib/lint-surface/run-detectors.mjs → PACKAGE_ROOT = npm (4 dirname угору).
+export const DEFAULT_RULES_DIR = join(dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url))))), 'rules')
+
+/**
+ * Похідна lint-поверхня для policy-concern-а (коли немає явного `lint` блоку).
+ * scope=full; glob із policy.files — щоб delta-режим тригерив concern на зміні таргета.
+ * @param {import('../concern-meta.mjs').PolicySurface} policy policy-поверхня concern-а.
+ * @returns {import('../concern-meta.mjs').LintSurface} похідна lint-поверхня (scope=full).
+ */
+function deriveLintFromPolicy(policy) {
+  const f = policy.files ?? {}
+  /** @type {string[]} */
+  let glob = []
+  if (typeof f.single === 'string') glob = [f.single]
+  else if (Array.isArray(f.walkGlob)) glob = f.walkGlob
+  else if (typeof f.walkGlob === 'string') glob = [f.walkGlob]
+  return { scope: 'full', glob }
+}
+
+/**
+ * Concern → виконуваний detector-entry. Concern із явним `lint` бере його;
+ * policy-concern без `lint` отримує похідну поверхню (детектор = generated main.mjs).
+ * @param {ConcernMeta} c вхідний concern.
+ * @returns {ConcernMeta|null} концерн із гарантованим `lint`, або null якщо не виконуваний
+ */
+function asDetectorConcern(c) {
+  if (c.lint !== undefined) return c
+  // policy-concern → standalone detector лише якщо files резолвиться (single/walkGlob);
+  // без цього concern — rego-бібліотека для parent-orchestrator-а, не самостійний detector.
+  if (c.policy !== undefined) {
+    const f = c.policy.files
+    const resolvable = f && typeof f === 'object' && (typeof f.single === 'string' || f.walkGlob !== undefined)
+    if (resolvable) return { ...c, lint: deriveLintFromPolicy(c.policy) }
+  }
+  return null
+}
+
+/**
+ * Скан усіх concern-ів-detector-ів у `rulesDir` (із lint-поверхнею або policy).
+ * @param {string} rulesDir корінь із правилами.
+ * @returns {Promise<Record<string, ConcernMeta[]>>} concerns згруповані за rule-id.
+ */
+async function readLintConcernsByRule(rulesDir) {
+  const { readdir } = await import('node:fs/promises')
+  const { join } = await import('node:path')
+  /** @type {Record<string, ConcernMeta[]>} */
+  const out = {}
+  let entries
+  try {
+    entries = await readdir(rulesDir, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const e of entries) {
+    if (!e.isDirectory() || e.name.startsWith('.')) continue
+    const listed = await listConcerns(join(rulesDir, e.name))
+    const concerns = listed.map(c => asDetectorConcern(c)).filter(Boolean)
+    if (concerns.length > 0) out[e.name] = /** @type {ConcernMeta[]} */ (concerns)
+  }
+  return out
+}
+
+/**
+ * Активні rule-id з `.n-rules.json` (для delta/full режимів).
+ * @param {Record<string, ConcernMeta[]>} byRule concerns згруповані за rule-id.
+ * @param {string} cwd робоча директорія прогону.
+ * @returns {Promise<string[]>} перелік активних rule-id.
+ */
+async function enabledRuleIds(byRule, cwd) {
+  const config = await readNRulesConfigLite(cwd)
+  if (!config.exists) return []
+  return Object.keys(byRule).filter(id => isRuleEnabled(config, id))
+}
+
+/**
+ * @param {LintEntry[]} entries вхідні lint-entries.
+ * @returns {LintEntry[]} стабільний алфавітний порядок
+ */
+function sortEntries(entries) {
+  return entries.toSorted((a, b) => a.ruleId.localeCompare(b.ruleId) || a.concern.name.localeCompare(b.concern.name))
+}
+
+/**
+ * @typedef {{ entry: LintEntry, files: string[]|undefined }} PlanItem
+ */
+
+/**
+ * Будує план прогону для заданих опцій (discovery + scope-table).
+ * Спільне джерело для detect-only і fix-pipeline.
+ * @param {object} opts опції прогону.
+ * @param {string} opts.rulesDir корінь із правилами.
+ * @param {string} opts.cwd робоча директорія прогону.
+ * @param {boolean} [opts.full] whole-repo режим (усі enabled-concerns).
+ * @param {string[]} [opts.rules] scoped rule-id (порожній → delta/full).
+ * @param {string[]|null} [opts.files] явний перелік файлів або null.
+ * @returns {Promise<PlanItem[]>} впорядкований план прогону.
+ */
+export async function buildDetectPlan(opts) {
+  const byRule = await readLintConcernsByRule(opts.rulesDir ?? DEFAULT_RULES_DIR)
+  return buildPlan({
+    byRule,
+    full: opts.full === true,
+    rules: Array.isArray(opts.rules) ? opts.rules : [],
+    explicitFiles: Array.isArray(opts.files) ? opts.files : null,
+    cwd: opts.cwd
+  })
+}
+
+/**
+ * scoped-режим: усі lint-concerns названих правил, whole-repo.
+ * @param {Record<string, ConcernMeta[]>} byRule concerns згруповані за rule-id.
+ * @param {string[]} rules scoped rule-id.
+ * @returns {PlanItem[]} впорядкований план (за ruleId).
+ */
+function buildScopedPlan(byRule, rules) {
+  const plan = []
+  for (const ruleId of rules) {
+    for (const concern of byRule[ruleId] ?? []) plan.push({ entry: { ruleId, concern }, files: undefined })
+  }
+  return plan.toSorted((a, b) => a.entry.ruleId.localeCompare(b.entry.ruleId))
+}
+
+/**
+ * full-режим: усі per-file + full concerns enabled-правил, whole-repo.
+ * @param {Record<string, ConcernMeta[]>} byRule concerns згруповані за rule-id.
+ * @param {Set<string>} enabledSet активні rule-id.
+ * @returns {PlanItem[]} впорядкований план (whole-repo для кожного entry).
+ */
+function buildFullPlan(byRule, enabledSet) {
+  /** @type {LintEntry[]} */
+  const entries = []
+  for (const [ruleId, concerns] of Object.entries(byRule)) {
+    if (!enabledSet.has(ruleId)) continue
+    for (const concern of concerns) entries.push({ ruleId, concern })
+  }
+  return sortEntries(entries).map(entry => ({ entry, files: undefined }))
+}
+
+/**
+ * Планує один concern у delta/explicit-files режимі за його lint.scope.
+ * @param {string} ruleId rule-id concern-а.
+ * @param {ConcernMeta} concern concern із lint-поверхнею.
+ * @param {string[]} changed перелік змінених файлів.
+ * @returns {PlanItem|null} plan-item concern-а або null, якщо concern не тригериться.
+ */
+function planConcernForDelta(ruleId, concern, changed) {
+  const { scope, glob } = concern.lint
+  const isMatch = glob.length > 0 ? picomatch(glob, { dot: true }) : () => false
+  if (scope === 'per-file') {
+    const files = glob.length > 0 ? changed.filter(f => isMatch(f)) : changed
+    return files.length > 0 ? { entry: { ruleId, concern }, files } : null
+  }
+  // full: запускається whole-repo лише якщо glob ∩ changed ≠ ∅
+  if (glob.length > 0 && changed.some(f => isMatch(f))) {
+    return { entry: { ruleId, concern }, files: undefined }
+  }
+  return null
+}
+
+/**
+ * delta/explicit-files режим: concern-и enabled-правил, зіставлені зі зміненими файлами.
+ * @param {Record<string, ConcernMeta[]>} byRule concerns згруповані за rule-id.
+ * @param {Set<string>} enabledSet активні rule-id.
+ * @param {string[]} changed перелік змінених файлів.
+ * @returns {PlanItem[]} впорядкований план (за ruleId, потім concern.name).
+ */
+function buildDeltaPlan(byRule, enabledSet, changed) {
+  /** @type {PlanItem[]} */
+  const plan = []
+  for (const [ruleId, concerns] of Object.entries(byRule)) {
+    if (!enabledSet.has(ruleId)) continue
+    for (const concern of concerns) {
+      const item = planConcernForDelta(ruleId, concern, changed)
+      if (item) plan.push(item)
+    }
+  }
+  return plan.toSorted(
+    (a, b) => a.entry.ruleId.localeCompare(b.entry.ruleId) || a.entry.concern.name.localeCompare(b.entry.concern.name)
+  )
+}
+
+/**
+ * Будує план: список entries + чи кожен запускається whole-repo (files=undefined)
+ * чи per-file (files=[...]). Реалізує таблицю lint.scope зі специфікації.
+ * @param {object} args аргументи побудови плану.
+ * @param {Record<string, ConcernMeta[]>} args.byRule concerns згруповані за rule-id.
+ * @param {boolean} args.full whole-repo режим.
+ * @param {string[]} args.rules scoped rule-id (порожній → delta/full).
+ * @param {string[]|null} args.explicitFiles явний перелік файлів або null.
+ * @param {string} args.cwd робоча директорія прогону.
+ * @returns {Promise<PlanItem[]>} впорядкований план прогону.
+ */
+async function buildPlan({ byRule, full, rules, explicitFiles, cwd }) {
+  // scoped: усі lint-concerns названих правил, whole-repo
+  if (rules.length > 0) return buildScopedPlan(byRule, rules)
+
+  const enabled = await enabledRuleIds(byRule, cwd)
+  const enabledSet = new Set(enabled)
+
+  // full: усі per-file + full concerns enabled-правил, whole-repo
+  if (full && explicitFiles === null) return buildFullPlan(byRule, enabledSet)
+
+  // delta / explicit-files
+  const changed = explicitFiles ?? (await collectChangedFilesSince(await resolveChangedBase(cwd), cwd))
+  return buildDeltaPlan(byRule, enabledSet, changed)
+}
+
+/**
+ * Запускає detect-only прохід. Повертає всі violations і похідний exitCode.
+ * @param {object} opts опції прогону.
+ * @param {string} opts.rulesDir корінь із правилами.
+ * @param {string} opts.cwd робоча директорія прогону.
+ * @param {boolean} [opts.full] whole-repo режим.
+ * @param {string[]} [opts.rules] scoped rule-id (порожній → delta/full).
+ * @param {string[]|null} [opts.files] явний перелік файлів або null.
+ * @param {boolean} [opts.verbose] докладний лог прогону.
+ * @param {(s: string) => void} [opts.log] функція логування.
+ * @param {boolean} [opts.isTTY] override TTY-режиму ProgressReporter (тести); типово isTTY stdout.
+ * @param {(snap: object) => void} [opts.onProgress] публікація знімків прогресу назовні (черга lint --full).
+ * @returns {Promise<{ violations: LintViolation[], exitCode: 0|1|2, ran: LintEntry[] }>} violations, exitCode і виконані entries.
+ */
+export async function detectAll(opts) {
+  const rulesDir = opts.rulesDir ?? DEFAULT_RULES_DIR
+  const { cwd } = opts
+  const full = opts.full === true
+  const rules = Array.isArray(opts.rules) ? opts.rules : []
+  const explicitFiles = Array.isArray(opts.files) ? opts.files : null
+  const verbose = opts.verbose === true
+  const baseLog = opts.log ?? (s => process.stdout.write(s))
+
+  const byRule = await readLintConcernsByRule(rulesDir)
+  const plan = await buildPlan({ byRule, full, rules, explicitFiles, cwd })
+
+  // Detect-only бар — ЛИШЕ в TTY (без тикера «виправлено»). У не-TTY (hooks, CI-gate,
+  // пайпи) append-рядки ⏱ на кожен концерн засмітили б вивід кожного PostToolUse-хука,
+  // тож там reporter створюється лише за наявності onProgress і «мовчазним»
+  // (appendInNonTTY: false) — publisher черги (--full) отримує знімки без шуму.
+  const isTTY = opts.isTTY ?? process.stdout.isTTY === true
+  const progress =
+    isTTY || opts.onProgress
+      ? createProgressReporter({
+          total: plan.length,
+          log: baseLog,
+          isTTY,
+          withFixed: false,
+          onUpdate: opts.onProgress,
+          appendInNonTTY: false
+        })
+      : null
+  const log = progress ? progress.log : baseLog
+
+  /** @type {LintViolation[]} */
+  const allViolations = []
+  /** @type {LintEntry[]} */
+  const ran = []
+
+  try {
+    for (const { entry, files } of plan) {
+      /** @type {LintContext} */
+      const ctx = { cwd, ruleId: entry.ruleId, concernId: entry.concern.name, files, verbose }
+      const key = `${entry.ruleId}/${entry.concern.name}`
+      progress?.concernStart(key)
+      if (verbose) {
+        const countStr = files === undefined ? 'весь репо' : `${files.length} файл(ів)`
+        log(`  🔍 ${key}  [${entry.concern.lint.scope}]  → ${countStr}\n`)
+      }
+      let result
+      try {
+        result = await runConcernDetector(entry.concern, ctx)
+      } catch (error) {
+        if (error instanceof DetectorError) {
+          log(`💥 ${error.message}\n`)
+          return { violations: allViolations, exitCode: 2, ran }
+        }
+        throw error
+      }
+      ran.push(entry)
+      allViolations.push(...result.violations)
+      progress?.detectSnapshot(key, result.violations.length)
+      progress?.concernDone(key)
+      if (verbose && result.diagnostics && result.diagnostics.length > 0) {
+        log(renderDiagnostics(result.diagnostics))
+      }
+    }
+  } finally {
+    progress?.stop()
+  }
+
+  if (allViolations.length > 0) baseLog(renderViolations(allViolations))
+  return { violations: allViolations, exitCode: allViolations.length > 0 ? 1 : 0, ran }
+}