@7n/rules 1.0.0

package/scripts/sync-setup-bun-deps-action.mjs

@@ -0,0 +1,36 @@
+/**
+ * Копіює composite GitHub Action `setup-bun-deps` з установленого пакету `@7n/rules`
+ * у цільовий репозиторій (`.github/actions/setup-bun-deps/action.yml`).
+ *
+ * Використовується CLI `npx \@7n/rules`, щоб workflows з правил `ga` / `js` / `text`
+ * могли одразу викликати `uses: ./.github/actions/setup-bun-deps` після кроку `actions/checkout@v6` (без checkout runner не знайде action.yml).
+ *
+ * Джерело: каталог `github-actions/setup-bun-deps/` у корені tarball пакету (поруч із `mdc/`, `bin/`).
+ */
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/** Відносний шлях до `action.yml` всередині кореня пакету */
+const RELATIVE_BUNDLED_ACTION = join('github-actions', 'setup-bun-deps', 'action.yml')
+
+/** Відносний шлях призначення у проєкті-клієнті */
+const RELATIVE_DEST_ACTION = join('.github', 'actions', 'setup-bun-deps', 'action.yml')
+
+/**
+ * Записує у `projectRoot` composite action з `bundledPackageRoot` (корінь установленого `@7n/rules`).
+ * @param {string} projectRoot абсолютний шлях до кореня цільового репозиторію
+ * @param {string} bundledPackageRoot абсолютний шлях до кореня пакету (теки з `mdc/`, `github-actions/`)
+ * @returns {Promise<{ written: boolean, destPath: string }>} чи був запис і повний шлях файлу
+ */
+export async function syncSetupBunDepsAction(projectRoot, bundledPackageRoot) {
+  const srcPath = join(bundledPackageRoot, RELATIVE_BUNDLED_ACTION)
+  if (!existsSync(srcPath)) {
+    throw new Error(`Не знайдено шаблон composite action.\nОчікуваний шлях: ${srcPath}\nПеревстановіть @7n/rules.`)
+  }
+  const destPath = join(projectRoot, RELATIVE_DEST_ACTION)
+  await mkdir(join(projectRoot, '.github', 'actions', 'setup-bun-deps'), { recursive: true })
+  const content = await readFile(srcPath, 'utf8')
+  await writeFile(destPath, content.endsWith('\n') ? content : `${content}\n`, 'utf8')
+  return { written: true, destPath }
+}

package/scripts/update-blue-oak.mjs

@@ -0,0 +1,50 @@
+/**
+ * Оновлює вбудований snapshot Blue Oak Council license list.
+ *
+ * Fetching: https://blueoakcouncil.org/list.json
+ * Виводить: npm/data/blue-oak.json — SPDX-ідентифікатори рівнів Model+Gold+Silver+Bronze.
+ *
+ * Запуск (вручну, у \@7n/rules):
+ *   bun npm/scripts/update-blue-oak.mjs
+ *
+ * Коли запускати:
+ *   - При апгрейді \@7n/rules (n-taze або вручну) — Blue Oak список змінюється рідко,
+ *     але нові permissive ліцензії зʼявляються раз на кілька місяців;
+ *   - Якщо проєкт падає на license-check через ліцензію якої нема в списку,
+ *     а вона точно permissive — спочатку перевір, чи вона в Bronze+ на blueoakcouncil.org.
+ *
+ * Lead-рівень (найгірший, GPL-compatible) — навмисно виключений.
+ */
+import { writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const BLUE_OAK_URL = 'https://blueoakcouncil.org/list.json'
+const OUT_PATH = join(dirname(dirname(fileURLToPath(import.meta.url))), 'data', 'blue-oak.json')
+const KEEP_RATINGS = new Set(['Model', 'Gold', 'Silver', 'Bronze'])
+
+console.log(`⬇  Fetching ${BLUE_OAK_URL} …`)
+const res = await fetch(BLUE_OAK_URL)
+if (!res.ok) {
+  throw new Error(`✗ HTTP ${res.status}`)
+}
+
+/** @type {{ version: string, ratings: Array<{ name: string, licenses: Array<{ id: string, name: string, url: string }> }> }} */
+const data = await res.json()
+
+const bronzeAndAbove = []
+for (const rating of data.ratings) {
+  if (KEEP_RATINGS.has(rating.name)) {
+    bronzeAndAbove.push(...rating.licenses.map(l => l.id))
+  }
+}
+
+const out = {
+  version: data.version,
+  source: BLUE_OAK_URL,
+  bronzeAndAbove
+}
+
+writeFileSync(OUT_PATH, JSON.stringify(out, null, 2) + '\n', 'utf8')
+console.log(`✓ ${OUT_PATH}`)
+console.log(`  version=${out.version}  bronzeAndAbove=${bronzeAndAbove.length} licenses`)

package/scripts/upgrade-n-rules-and-install.mjs

@@ -0,0 +1,264 @@
+/**
+ * Перед синхронізацією правил CLI підтягує останню опубліковану версію `@7n/rules` з npm registry
+ * у кореневий `package.json` і запускає `bun i` у корені проєкту.
+ *
+ * Якщо залежність уже задана через `workspace:`, `file:`, `link:` тощо, запис у registry не
+ * змінюється і `bun i` не викликається — так зберігається робота монорепо та сценаріїв з `workspace:`, `file:` чи `link:`.
+ *
+ * Міграція перейменування: якщо у package.json ще оголошено legacy-пакет `@nitra/cursor`
+ * (а `@7n/rules` немає), запис переноситься на нову назву в тій самій секції.
+ *
+ * Після встановлення повертається шлях до `node_modules/@7n/rules`, якщо каталог з
+ * `package.json` існує; інакше — fallback (корінь пакету поточного процесу CLI, наприклад кеш npx).
+ */
+
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { existsSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const PACKAGE_NAME = '@7n/rules'
+const LEGACY_PACKAGE_NAME = '@nitra/cursor'
+const NPM_LATEST_URL = 'https://registry.npmjs.org/@7n/rules/latest'
+
+const execFileAsync = promisify(execFile)
+
+const WORKSPACE_RE = /^workspace:/i
+const FILE_RE = /^file:/i
+const LINK_RE = /^link:/i
+const PORTAL_RE = /^portal:/i
+const GIT_RE = /^git(\+|:\/\/)/i
+const NPM_PROTO_RE = /^npm:/i
+const HTTP_RE = /^https?:\/\//i
+
+/**
+ * Чи не можна безпечно підставити semver з npm замість поточного специфікатора залежності.
+ * @param {string} specifier значення з package.json
+ * @returns {boolean} true — залишити як є (монорепо, git, tarball тощо)
+ */
+export function shouldSkipNpmVersionUpgrade(specifier) {
+  const s = String(specifier).trim()
+  if (!s) {
+    return true
+  }
+  if (WORKSPACE_RE.test(s)) {
+    return true
+  }
+  if (FILE_RE.test(s)) {
+    return true
+  }
+  if (LINK_RE.test(s)) {
+    return true
+  }
+  if (PORTAL_RE.test(s)) {
+    return true
+  }
+  if (GIT_RE.test(s)) {
+    return true
+  }
+  if (NPM_PROTO_RE.test(s)) {
+    return true
+  }
+  if (HTTP_RE.test(s)) {
+    return true
+  }
+  return Boolean(s.startsWith('./') || s.startsWith('../'))
+}
+
+/**
+ * Остання версія пакета з npm (поле `version` у JSON dist-tag `latest`).
+ * @returns {Promise<string>} semver без префікса `^`
+ */
+export async function fetchLatestNRulesVersionFromNpm() {
+  const res = await fetch(NPM_LATEST_URL, {
+    headers: { accept: 'application/json' }
+  })
+  if (!res.ok) {
+    throw new Error(`npm registry: ${res.status} ${res.statusText} для ${PACKAGE_NAME}`)
+  }
+  const data = await res.json()
+  if (!data || typeof data.version !== 'string' || !data.version.trim()) {
+    throw new Error(`npm registry: у відповіді для ${PACKAGE_NAME} немає поля version`)
+  }
+  return data.version.trim()
+}
+
+/**
+ * Версія з package.json вказаного кореня пакету (fallback, коли registry недоступний).
+ * @param {string} packageRoot корінь пакету поточного процесу CLI
+ * @returns {Promise<string | null>} semver або null, якщо файл нечитабельний
+ */
+async function readPackageVersionSafe(packageRoot) {
+  try {
+    const pkg = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'))
+    return typeof pkg?.version === 'string' && pkg.version.trim() ? pkg.version.trim() : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Шлях до встановленого пакета в `node_modules` або fallback.
+ * @param {string} projectRoot корінь репозиторію
+ * @param {string} fallbackPackageRoot корінь пакету з поточного процесу
+ * @returns {string} абсолютний шлях до каталогу з `mdc/`, `scripts/` тощо
+ */
+export function resolveInstalledPackageRoot(projectRoot, fallbackPackageRoot) {
+  const installed = join(projectRoot, 'node_modules', PACKAGE_NAME)
+  if (existsSync(join(installed, 'package.json'))) {
+    return installed
+  }
+  return fallbackPackageRoot
+}
+
+/**
+ * Запускає `bun i` у вказаному каталозі з виводом у поточний stdio.
+ * @param {string} projectRoot cwd для процесу
+ * @returns {Promise<void>} завершується після успішного `bun i`
+ */
+async function runBunInstall(projectRoot) {
+  try {
+    await execFileAsync('bun', ['i'], { cwd: projectRoot, stdio: 'inherit' })
+  } catch (error) {
+    const exitCode = typeof error?.code === 'number' ? error.code : null
+    if (exitCode !== null && exitCode !== 0) {
+      throw new Error(`bun i завершився з кодом ${exitCode}`, { cause: error })
+    }
+    throw error
+  }
+}
+
+/**
+ * Міграція перейменування: переносить `@nitra/cursor` → `@7n/rules` у тій самій секції
+ * package.json (devDependencies або dependencies), якщо нова назва ще не оголошена.
+ * @param {Record<string, unknown>} pkg вміст package.json (мутується in-place)
+ * @returns {boolean} true, якщо запис перенесено
+ */
+export function migrateLegacyDependencyName(pkg) {
+  let migrated = false
+  for (const section of ['devDependencies', 'dependencies']) {
+    const deps = pkg[section]
+    if (!deps || typeof deps !== 'object' || Array.isArray(deps)) {
+      continue
+    }
+    if (!(LEGACY_PACKAGE_NAME in deps) || typeof deps[LEGACY_PACKAGE_NAME] !== 'string') {
+      continue
+    }
+    if (!(PACKAGE_NAME in deps)) {
+      deps[PACKAGE_NAME] = deps[LEGACY_PACKAGE_NAME]
+    }
+    delete deps[LEGACY_PACKAGE_NAME]
+    migrated = true
+  }
+  return migrated
+}
+
+/**
+ * Де зараз оголошено `@7n/rules` у package.json.
+ * @param {Record<string, unknown>} pkg вміст package.json як об'єкт після читання JSON
+ * @returns {{ section: 'devDependencies' | 'dependencies', value: string } | null} секція та специфікатор або null, якщо залежності немає
+ */
+function findNRulesDependency(pkg) {
+  const dev = pkg.devDependencies
+  if (dev && typeof dev === 'object' && !Array.isArray(dev) && PACKAGE_NAME in dev) {
+    const value = dev[PACKAGE_NAME]
+    if (typeof value === 'string') {
+      return { section: 'devDependencies', value }
+    }
+  }
+  const deps = pkg.dependencies
+  if (deps && typeof deps === 'object' && !Array.isArray(deps) && PACKAGE_NAME in deps) {
+    const value = deps[PACKAGE_NAME]
+    if (typeof value === 'string') {
+      return { section: 'dependencies', value }
+    }
+  }
+  return null
+}
+
+/**
+ * Оновлює `@7n/rules` до `^<latest>` з npm (якщо дозволено специфікатором), виконує `bun i`,
+ * повертає корінь пакету для читання `mdc/` та інших файлів синхронізації.
+ * @param {string} projectRoot корінь цільового репозиторію (`cwd()`)
+ * @param {string} fallbackPackageRoot корінь пакету з `import.meta.url` (кеш npx або workspace)
+ * @returns {Promise<string>} абсолютний шлях до кореня `@7n/rules` для копіювання файлів
+ */
+export async function upgradeNRulesToLatestAndBunInstall(projectRoot, fallbackPackageRoot) {
+  const pkgPath = join(projectRoot, 'package.json')
+  if (!existsSync(pkgPath)) {
+    return resolveInstalledPackageRoot(projectRoot, fallbackPackageRoot)
+  }
+
+  let raw
+  try {
+    raw = await readFile(pkgPath, 'utf8')
+  } catch {
+    return resolveInstalledPackageRoot(projectRoot, fallbackPackageRoot)
+  }
+
+  let pkg
+  try {
+    pkg = JSON.parse(raw)
+  } catch {
+    return resolveInstalledPackageRoot(projectRoot, fallbackPackageRoot)
+  }
+
+  if (pkg === null || typeof pkg !== 'object' || Array.isArray(pkg)) {
+    return resolveInstalledPackageRoot(projectRoot, fallbackPackageRoot)
+  }
+
+  if (migrateLegacyDependencyName(pkg)) {
+    await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8')
+    console.log(`📝 Мігровано ${LEGACY_PACKAGE_NAME} → ${PACKAGE_NAME} у package.json\n`)
+  }
+
+  const found = findNRulesDependency(pkg)
+
+  if (found && shouldSkipNpmVersionUpgrade(found.value)) {
+    console.log(`⏭️  ${PACKAGE_NAME}: специфікатор «${found.value}» — без оновлення з npm та без bun i\n`)
+    return resolveInstalledPackageRoot(projectRoot, fallbackPackageRoot)
+  }
+
+  let latest
+  try {
+    latest = await fetchLatestNRulesVersionFromNpm()
+  } catch (error) {
+    // До першої публікації @7n/rules registry віддає 404 — fallback на версію пакету поточного процесу
+    latest = await readPackageVersionSafe(fallbackPackageRoot)
+    if (!latest) {
+      throw error
+    }
+    console.log(`⚠️  npm registry недоступний для ${PACKAGE_NAME} — використовую bundled-версію ${latest}\n`)
+  }
+  const desired = `^${latest}`
+
+  if (!found) {
+    if (!pkg.devDependencies || typeof pkg.devDependencies !== 'object' || Array.isArray(pkg.devDependencies)) {
+      pkg.devDependencies = {}
+    }
+    pkg.devDependencies[PACKAGE_NAME] = desired
+    await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8')
+    console.log(`📝 Додано ${PACKAGE_NAME}@${desired} у devDependencies (остання з npm)\n`)
+    await runBunInstall(projectRoot)
+    console.log(`📦 Виконано bun i у корені проєкту\n`)
+    return resolveInstalledPackageRoot(projectRoot, fallbackPackageRoot)
+  }
+
+  if (found.value === desired) {
+    console.log(`📌 ${PACKAGE_NAME} уже ${desired} у package.json — виконуємо bun i\n`)
+  } else {
+    if (found.section === 'devDependencies') {
+      pkg.devDependencies[PACKAGE_NAME] = desired
+    } else {
+      pkg.dependencies[PACKAGE_NAME] = desired
+    }
+    await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8')
+    console.log(`📝 Оновлено ${PACKAGE_NAME} → ${desired} у package.json\n`)
+  }
+
+  await runBunInstall(projectRoot)
+  console.log(`📦 Виконано bun i у корені проєкту\n`)
+
+  return resolveInstalledPackageRoot(projectRoot, fallbackPackageRoot)
+}

package/scripts/utils/apply-to-files.mjs

@@ -0,0 +1,36 @@
+/**
+ * Спільний helper для T0-фіксерів (`fix-*.mjs`): застосовує текстовий трансформер до
+ * унікальних файлів зі списку violations і пише зміни. Раніше дублювався окремо в
+ * `rust/toolchain_cache`, `tauri/linux_deps`, `ga/workflows` (jscpd-клон).
+ */
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * @param {import('../lib/lint-surface/types.mjs').LintViolation[]} violations порушення (джерело переліку файлів)
+ * @param {import('../lib/lint-surface/types.mjs').LintContext} ctx контекст лінту (cwd, recordWrite)
+ * @param {(file: string) => (content: string) => string|null} transformerFor
+ *   фабрика трансформера для конкретного relative-file (дає доступ до per-file даних)
+ * @returns {string[]} абсолютні шляхи змінених файлів
+ */
+export function applyToFiles(violations, ctx, transformerFor) {
+  const files = [...new Set(violations.map(v => v.file).filter(Boolean))]
+  /** @type {string[]} */
+  const touchedFiles = []
+  for (const rel of files) {
+    const abs = join(ctx.cwd, rel)
+    let content
+    try {
+      content = readFileSync(abs, 'utf8')
+    } catch {
+      continue
+    }
+    const next = transformerFor(rel)(content)
+    if (next && next !== content) {
+      ctx.recordWrite?.(abs)
+      writeFileSync(abs, next)
+      touchedFiles.push(abs)
+    }
+  }
+  return touchedFiles
+}

package/scripts/utils/ast-extract.mjs

@@ -0,0 +1,149 @@
+/** @see ./docs/ast-extract.md */
+
+/**
+ * Generic AST-facts extractor для `ast_facts`-tool fix-engine (§3б спеки pi-migration).
+ *
+ * Дає агенту структурований зріз файлу (`imports` / `exports` / `topLevelFunctions`)
+ * замість сирого вмісту — скорочує redundant read-turns на слабкій локальній моделі.
+ * Використовується як **generic fallback**, коли правило не має власного
+ * `rules/<id>/js/_ast-context.mjs`.
+ *
+ * Парсинг — через спільний `parseProgramOrNull` (oxc). Будь-яка помилка (read/parse)
+ * деградує до `{ error, imports:[], exports:[], topLevelFunctions:[] }`, щоб агент
+ * продовжив із тим, що має (контракт §3б: fallback до голого вмісту).
+ */
+
+import { readFileSync } from 'node:fs'
+import { parseProgramOrNull } from './ast-scan-utils.mjs'
+
+/**
+ * Порожній результат із причиною (read/parse fail).
+ * @param {string} error причина деградації
+ * @returns {{ error: string, imports: [], exports: [], topLevelFunctions: [] }} порожній зріз із причиною
+ */
+function empty(error) {
+  return { error, imports: [], exports: [], topLevelFunctions: [] }
+}
+
+/**
+ * Чи init-вираз — функція (для `export const f = () => …`).
+ * @param {unknown} node init-вузол оголошення змінної
+ * @returns {boolean} true якщо вузол — arrow/function expression
+ */
+function isFunctionInit(node) {
+  return !!node && (node.type === 'ArrowFunctionExpression' || node.type === 'FunctionExpression')
+}
+
+/**
+ * Обробляє `ImportDeclaration`: додає `{ source, names }` до акумулятора `imports`.
+ * @param {unknown} node вузол import-декларації
+ * @param {Array<{source: string, names: string[]}>} imports акумулятор import-ів
+ * @returns {void}
+ */
+function handleImport(node, imports) {
+  imports.push({
+    source: node.source?.value ?? '',
+    names: (node.specifiers ?? []).map(s => s.local?.name).filter(Boolean)
+  })
+}
+
+/**
+ * Обробляє `declaration` частину `ExportNamedDeclaration` (function/class/interface/const).
+ * @param {unknown} d вузол declaration (може бути null для re-export без declaration)
+ * @param {string[]} exports акумулятор імен exports
+ * @param {string[]} topLevelFunctions акумулятор імен top-level функцій
+ * @returns {void}
+ */
+function handleExportedDeclaration(d, exports, topLevelFunctions) {
+  if (d?.type === 'FunctionDeclaration' && d.id?.name) {
+    exports.push(d.id.name)
+    topLevelFunctions.push(d.id.name)
+  } else if ((d?.type === 'ClassDeclaration' || d?.type === 'TSInterfaceDeclaration') && d.id?.name) {
+    exports.push(d.id.name)
+  } else if (d?.type === 'VariableDeclaration') {
+    for (const decl of d.declarations ?? []) {
+      if (!decl.id?.name) continue
+      exports.push(decl.id.name)
+      if (isFunctionInit(decl.init)) topLevelFunctions.push(decl.id.name)
+    }
+  }
+}
+
+/**
+ * Обробляє `ExportNamedDeclaration`: declaration-частину + re-export specifiers.
+ * @param {unknown} node вузол named-export
+ * @param {string[]} exports акумулятор імен exports
+ * @param {string[]} topLevelFunctions акумулятор імен top-level функцій
+ * @returns {void}
+ */
+function handleExportNamed(node, exports, topLevelFunctions) {
+  handleExportedDeclaration(node.declaration, exports, topLevelFunctions)
+  for (const spec of node.specifiers ?? []) {
+    if (spec.exported?.name) exports.push(spec.exported.name)
+  }
+}
+
+/**
+ * Витягає AST-факти з вихідного коду (без файлового IO — для тестів і reuse).
+ * @param {string} content вихідний код
+ * @param {string} virtualPath шлях (визначає мову js/ts/jsx/tsx)
+ * @returns {{ imports: Array<{source: string, names: string[]}>, exports: string[], topLevelFunctions: string[], error?: string }} факти
+ */
+export function extractContextFromSource(content, virtualPath) {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return empty('parse failed')
+
+  const imports = []
+  const exports = []
+  const topLevelFunctions = []
+
+  for (const node of program.body ?? []) {
+    switch (node?.type) {
+      case 'ImportDeclaration': {
+        handleImport(node, imports)
+        break
+      }
+
+      case 'FunctionDeclaration': {
+        if (node.id?.name) topLevelFunctions.push(node.id.name)
+        break
+      }
+
+      case 'ExportNamedDeclaration': {
+        handleExportNamed(node, exports, topLevelFunctions)
+        break
+      }
+
+      case 'ExportDefaultDeclaration': {
+        exports.push('default')
+        break
+      }
+
+      case 'ExportAllDeclaration': {
+        exports.push(node.exported?.name ?? '*')
+        break
+      }
+
+      default: {
+        break
+      }
+    }
+  }
+
+  return { imports, exports, topLevelFunctions }
+}
+
+/**
+ * Читає файл і витягає AST-факти. Read-помилка → `{ error, … }` (не кидає).
+ * @param {string} filePath абсолютний/відносний шлях до файлу
+ * @returns {{ imports: Array<{source: string, names: string[]}>, exports: string[], topLevelFunctions: string[], error?: string }} факти
+ */
+export function extractContext(filePath) {
+  let content
+  try {
+    content = readFileSync(filePath, 'utf8')
+  } catch (error) {
+    return empty(`read failed: ${error.message}`)
+  }
+  return extractContextFromSource(content, filePath)
+}