@7n/rules 1.27.0 → 1.28.0

package/rules/npm-module/package_structure/main.mjs

@@ -1,515 +0,0 @@
-/** @see ./docs/package_structure.md */
-import { existsSync } from 'node:fs'
-import { readFile, stat } from 'node:fs/promises'
-import { join, sep } from 'node:path'
-
-import { parseSync } from 'oxc-parser'
-
-import {
-  dynamicImportModule,
-  langFromPath,
-  requireCallModule,
-  walkAstWithAncestors
-} from '../../../scripts/utils/ast-scan-utils.mjs'
-import { createViolationReporter } from '../../../scripts/lib/lint-surface/violation-reporter.mjs'
-import { loadCursorIgnorePaths } from '../../../scripts/lib/load-cursor-config.mjs'
-import { walkDir } from '../../../scripts/utils/walkDir.mjs'
-
-/** Файл проєкту TypeScript для emit без каталогу `src` (див. npm-module.mdc) */
-const EMIT_TYPES_CONFIG = 'npm/tsconfig.emit-types.json'
-
-/** Каталоги, які за конвенцією тримають тести / фікстури і не повинні публікуватися. */
-const TEST_DIR_NAMES = new Set(['tests', '__tests__', 'fixtures', '__fixtures__', 'spec', 'test'])
-
-/**
- * Імена файлів за патернами test/spec (тільки basename, без path). Rego
- * (`*_test.rego`) свідомо не входить: за конвенцією conftest юніт-тест лежить
- * поруч з полісі у тому самому `package` — і це дозволений виняток усередині
- * опублікованого `policy/`-каталогу (npm-module.mdc).
- * @param {string} cwd корінь репозиторію
- */
-const TEST_FILE_PATTERNS = [/^.+\.(test|spec)\.[cm]?[jt]sx?$/iu]
-
-/** Розширення, у яких ловимо імпорти test-фреймворків. */
-const JS_LIKE_EXT_RE = /\.[cm]?[jt]sx?$/iu
-
-/** Імпорти/require/dynamic-import, які видають test-файл. */
-const TEST_FRAMEWORK_MODULES = new Set([
-  'bun:test',
-  'node:test',
-  'vitest',
-  '@jest/globals',
-  'jest',
-  'mocha',
-  'ava',
-  'tap',
-  'tape'
-])
-
-/** Символи у glob-сегменті, які треба екранувати для RegExp (без `*` / `?` — їх обробляємо окремо). */
-const REGEX_SPECIAL_IN_GLOB = new Set(['.', '+', '^', '$', '{', '}', '(', ')', '|', '[', ']', '\\'])
-
-/** Збіги для post-обробки glob → regex після злиття сегментів через `/` (див. `globToRegex`). */
-const GLOBSTAR_LEADING_RE = /^__GLOBSTAR__\//u
-const GLOBSTAR_TRAILING_RE = /\/__GLOBSTAR__$/u
-
-/**
- * Чи є під `npm/src` хоча б один `.js` (рекурсивно).
- * @param {string} cwd корінь репозиторію
- * @param {string[]} [ignorePaths] абсолютні шляхи каталогів, повністю виключених з обходу
- * @returns {Promise<boolean>} `true`, якщо знайдено хоча б один `.js`
- */
-async function npmSrcTreeHasJsFile(cwd, ignorePaths = []) {
-  const root = join(cwd, 'npm/src')
-  if (!existsSync(root)) {
-    return false
-  }
-  let found = false
-  await walkDir(
-    root,
-    p => {
-      if (p.endsWith('.js')) {
-        found = true
-      }
-    },
-    ignorePaths
-  )
-  return found
-}
-
-/**
- * Знаходить текстовий вміст конфігурації hk для перевірки npm-module.
- * @returns {Promise<{ path: string, text: string } | null>} знайдений файл або `null`
- * @param {string} cwd корінь репозиторію
- */
-async function readHkConfig(cwd) {
-  const candidates = ['hk.pkl', '.config/hk.pkl']
-  for (const p of candidates) {
-    const abs = join(cwd, p)
-    if (existsSync(abs)) {
-      const text = await readFile(abs, 'utf8')
-      return { path: p, text }
-    }
-  }
-  return null
-}
-
-/**
- * Підрядки для hk при layout з каталогом `npm/src` і glob `src` + `.js` у команді (див. npm-module.mdc).
- * @param {string} hkText текст конфігурації hk
- * @returns {string[]} відсутні фрагменти
- */
-function missingHkSrcLayoutFragments(hkText) {
-  const need = [
-    '["pre-commit"]',
-    'bunx -p typescript tsc',
-    'src/**/*.js',
-    '--declaration',
-    '--allowJs',
-    '--emitDeclarationOnly',
-    '--outDir types',
-    '--skipLibCheck'
-  ]
-  return need.filter(s => !hkText.includes(s))
-}
-
-/**
- * Підрядки для hk при layout з `tsconfig.emit-types.json` (див. npm-module.mdc).
- * @param {string} hkText текст конфігурації hk
- * @returns {string[]} відсутні фрагменти
- */
-function missingHkEmitTypesConfigFragments(hkText) {
-  const need = ['["pre-commit"]', 'bunx -p typescript tsc', 'tsconfig.emit-types.json']
-  return need.filter(s => !hkText.includes(s))
-}
-
-/**
- * Застаріла інвокація команди `check`, прибраної в v14 (уніфікована поверхня `lint`).
- * Матч на підрядок "check changelog" незалежно від того, яким бінарем/шляхом викликано.
- */
-const DEPRECATED_CHECK_CHANGELOG_RE = /\bcheck\s+changelog\b/u
-
-/**
- * Підрядки канонічного кроку `npm-changelog` у hk.pkl (fix-only, autofix через env
- * `N_RULES_CHANGELOG_AUTOFIX=1`; сам крок ставить change-файл у git-індекс, `stage`
- * не потрібен). Див. npm-module.mdc.
- * @param {string} hkText текст конфігурації hk
- * @returns {string[]} відсутні фрагменти
- */
-function missingHkNpmChangelogFragments(hkText) {
-  const need = ['["npm-changelog"]', 'N_RULES_CHANGELOG_AUTOFIX=1', 'lint changelog']
-  return need.filter(s => !hkText.includes(s))
-}
-
-/**
- * Шлях на дискі до файлу з поля `types` у `npm/package.json` (значення на кшталт `./types/bin/x.d.ts`).
- * @param {string} typesField значення поля `types` з `package.json`
- * @returns {string | null} абсолютний шлях або `null`
- */
-function npmTypesFileFromPackageField(typesField) {
-  if (typeof typesField !== 'string' || !typesField.startsWith('./types/')) {
-    return null
-  }
-  const rel = typesField.slice(2)
-  return join('npm', rel)
-}
-
-/**
- * Перевіряє наявність на диску файлу зі значення `types` у `npm/package.json`
- * (cross-file: JSON-поле + FS). Структуру самого поля валідує
- * `npm/policy/npm_module/npm_package_json/`; тут — лише чи файл реально існує.
- * @param {boolean} useSrcJsLayout чи використовується layout з npm/src
- * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @param {(msg: string) => void} failFn callback при помилці
- * @param {string} cwd корінь репозиторію
- */
-async function checkNpmPackageJson(useSrcJsLayout, passFn, failFn, cwd) {
-  const npmPkgPath = join(cwd, 'npm/package.json')
-  if (!existsSync(npmPkgPath)) return
-  const npmPkg = JSON.parse(await readFile(npmPkgPath, 'utf8'))
-  const typesField = npmPkg.types
-
-  const typesRel = useSrcJsLayout ? join('npm', 'types', 'index.d.ts') : npmTypesFileFromPackageField(typesField)
-  const missingTypesMsg = useSrcJsLayout
-    ? `Відсутній ${join('npm', 'types', 'index.d.ts')} (згенеруй tsc з npm-module.mdc)`
-    : `Файл для поля types не знайдено або шлях не під ./types/ — ${String(typesField)}`
-  if (typesRel && existsSync(join(cwd, typesRel))) {
-    passFn(`${typesRel} існує`)
-  } else {
-    failFn(missingTypesMsg)
-  }
-}
-
-/**
- * FS-existence для `npm/tsconfig.emit-types.json` (структуру `compilerOptions`
- * валідує `npm/policy/npm_module/emit_types_config/`).
- * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @param {(msg: string) => void} failFn callback при помилці
- * @param {string} cwd корінь репозиторію
- */
-function checkEmitTypesConfig(passFn, failFn, cwd) {
-  if (!existsSync(join(cwd, EMIT_TYPES_CONFIG))) {
-    failFn(
-      `Без .js під npm/src потрібен ${EMIT_TYPES_CONFIG} (див. npm-module.mdc: emit через tsconfig, без штучного src/index.js)`
-    )
-    return
-  }
-  passFn(`${EMIT_TYPES_CONFIG} є (структуру перевіряє npx @7n/rules fix → npm_module.emit_types_config)`)
-}
-
-/**
- * FS-existence для `npm-publish.yml` workflow. Поля workflow (`on.push.paths`,
- * `branches`, `id-token: write`, JS-DevTools/npm-publish step) валідує
- * `npm/policy/npm_module/npm_publish_yml/`.
- * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @param {(msg: string) => void} failFn callback при виявленому порушенні
- * @param {string} cwd корінь репозиторію
- */
-function checkPublishWorkflow(passFn, failFn, cwd) {
-  const publishWf = '.github/workflows/npm-publish.yml'
-  if (existsSync(join(cwd, publishWf))) {
-    passFn(`${publishWf} є (структуру перевіряє npx @7n/rules fix → npm_module.npm_publish_yml)`)
-  } else {
-    failFn(`Відсутній ${publishWf} (npm-module.mdc: npm publish)`)
-  }
-}
-
-/**
- * Перетворює glob-патерн (як у npm `files` чи `meta.json:auto.glob`) у `RegExp`
- * з якорями `^` / `$`. Підтримує globstar (нуль або більше сегментів), `*`
- * (символи без `/`), `?` (один символ без `/`) і brace-альтернативи `{a,b,c}`
- * (наприклад `*.{png,jpg,svg}` → `(?:png|jpg|svg)`). Клас `[…]` не
- * підтримується — у негативних патернах `files` цього достатньо.
- * @param {string} glob posix-шлях у glob-нотації
- * @returns {RegExp} `RegExp` з якорями `^` / `$`
- */
-export function globToRegex(glob) {
-  const parts = glob.split('/')
-  const tokens = parts.map(p => {
-    if (p === '**') return '__GLOBSTAR__'
-    let out = ''
-    let braceDepth = 0
-    for (const c of p) {
-      switch (c) {
-        case '*': {
-          out += '[^/]*'
-          continue
-        }
-        case '?': {
-          out += '[^/]'
-          continue
-        }
-        case '{': {
-          out += '(?:'
-          braceDepth++
-          continue
-        }
-        case '}': {
-          if (braceDepth > 0) {
-            out += ')'
-            braceDepth--
-            continue
-          }
-          break
-        }
-        case ',': {
-          if (braceDepth > 0) {
-            out += '|'
-            continue
-          }
-          break
-        }
-        default: {
-          break
-        }
-      }
-      out += REGEX_SPECIAL_IN_GLOB.has(c) ? `\\${c}` : c
-    }
-    return out
-  })
-  let re = tokens.join('/')
-  re = re.replaceAll('/__GLOBSTAR__/', '(?:/.*/|/)')
-  re = re.replace(GLOBSTAR_LEADING_RE, '(?:.*/)?')
-  re = re.replace(GLOBSTAR_TRAILING_RE, '(?:/.*)?')
-  re = re.replaceAll('__GLOBSTAR__', '.*')
-  // Дозволено: уся функція існує саме для конструкції RegExp з glob-pattern
-  // у `files` (значення з npm/package.json, не від кінцевого користувача), і
-  // спецсимволи вже екрановано через `REGEX_SPECIAL_IN_GLOB` вище.
-  return new RegExp(`^${re}$`, 'u')
-}
-
-/**
- * Збирає список файлів, що потраплять у tarball, виходячи з `files` у
- * `npm/package.json`. Підтримує позитивні patterns (директорії або файли) і
- * негативні (`!…`). Шляхи повертаються у posix-формі, відносно `npm/`.
- * Не пробує дублювати всю логіку `npm pack` (license/readme/тощо) — тут лише
- * простір імен `files`, бо саме його сканує check.
- * @param {string[]} filesField значення поля `files`
- * @returns {Promise<string[]>} відсортовані posix-шляхи без `npm/` префікса
- * @param {string} cwd корінь репозиторію
- */
-async function collectPublishedFiles(filesField, cwd) {
-  const positives = filesField.filter(p => typeof p === 'string' && !p.startsWith('!'))
-  const negatives = filesField.filter(p => typeof p === 'string' && p.startsWith('!')).map(p => globToRegex(p.slice(1)))
-  /** @type {Set<string>} */
-  const collected = new Set()
-  const npmRoot = join(cwd, 'npm')
-  for (const entry of positives) {
-    const fullPath = join(npmRoot, entry)
-    if (!existsSync(fullPath)) continue
-    const s = await stat(fullPath)
-    if (s.isFile()) {
-      collected.add(entry)
-      continue
-    }
-    if (!s.isDirectory()) continue
-    await walkDir(fullPath, p => {
-      const rel = p
-        .slice(npmRoot.length + 1)
-        .split(sep)
-        .join('/')
-      collected.add(rel)
-    })
-  }
-  const filtered = [...collected].filter(rel => negatives.every(re => !re.test(rel)))
-  filtered.sort()
-  return filtered
-}
-
-/**
- * Чи є у файлі імпорт/require/dynamic-import з модуля тест-фреймворку.
- * Парсимо через oxc-parser (як `bunyan-imports`/`redis-imports`). При помилці
- * парсингу повертаємо `null` — це не наш checker для синтаксису.
- * @param {string} content повний текст файлу
- * @param {string} virtualPath шлях для вибору `lang`
- * @returns {string | null} модуль, через який видно тест, або `null`
- */
-export function findTestFrameworkImport(content, virtualPath) {
-  const lang = langFromPath(virtualPath)
-  let result
-  try {
-    result = parseSync(virtualPath, content, { lang, sourceType: 'module' })
-  } catch {
-    return null
-  }
-  if (result.errors?.length) return null
-  for (const imp of result.module?.staticImports ?? []) {
-    const mod = imp.moduleRequest?.value
-    if (typeof mod === 'string' && TEST_FRAMEWORK_MODULES.has(mod)) return mod
-  }
-  /** @type {string | null} */
-  let found = null
-  walkAstWithAncestors(result.program, [], node => {
-    if (found) return
-    const reqMod = requireCallModule(node)
-    if (reqMod && TEST_FRAMEWORK_MODULES.has(reqMod)) {
-      found = reqMod
-      return
-    }
-    const dynMod = dynamicImportModule(node)
-    if (dynMod && TEST_FRAMEWORK_MODULES.has(dynMod)) {
-      found = dynMod
-    }
-  })
-  return found
-}
-
-/**
- * Класифікує опублікований файл як test/fixture, якщо хоча б одна з ознак:
- * (1) у шляху є каталог із `TEST_DIR_NAMES`; (2) basename відповідає
- * `TEST_FILE_PATTERNS`; (3) для JS/TS-розширень — імпорт test-фреймворку.
- *
- * Carve-out: для шляху `rules/<rule-name>/...` сегмент `<rule-name>` (індекс 1)
- * — це ім'я правила, а не каталог. Зокрема, правило з id `test` (або `tests`)
- * описує конвенцію розміщення тестів і саме по собі не є test-fixture'ом.
- * Подальші сегменти (наприклад, `rules/<r>/js/<c>/tests/`) продовжують перевірятись.
- * @param {string} relPath posix-шлях відносно `npm/`
- * @returns {Promise<string | null>} причина порушення або `null`
- * @param {string} [cwd] корінь репозиторію
- */
-export async function classifyPublishedFileAsTest(relPath, cwd = process.cwd()) {
-  const segments = relPath.split('/')
-  const base = segments.at(-1)
-  const dirs = segments.slice(0, -1)
-  const testDir = dirs.find((seg, idx) => {
-    if (idx === 1 && dirs[0] === 'rules') {
-      return false
-    }
-    return TEST_DIR_NAMES.has(seg.toLowerCase())
-  })
-  if (testDir) return `test-style каталог "${testDir}/"`
-  if (TEST_FILE_PATTERNS.some(re => re.test(base))) return `test-style ім'я файлу`
-  if (JS_LIKE_EXT_RE.test(base)) {
-    const content = await readFile(join(cwd, 'npm', relPath), 'utf8')
-    const mod = findTestFrameworkImport(content, relPath)
-    if (mod) return `імпорт test-фреймворку "${mod}"`
-  }
-  return null
-}
-
-/**
- * Для всіх файлів, що потрапили б у tarball (positive `files` мінус negative
- * patterns), забороняє test-style каталоги/імена/імпорти. Так пакет лишається
- * компактним і не везе користувачам тести й фікстури.
- * @param {(msg: string) => void} pass callback при успіху
- * @param {(msg: string) => void} fail callback при порушенні
- * @returns {Promise<void>}
- * @param {string} cwd корінь репозиторію
- */
-async function checkNoTestsInPublishedFiles(pass, fail, cwd) {
-  if (!existsSync(join(cwd, 'npm/package.json'))) return
-  const pkg = JSON.parse(await readFile(join(cwd, 'npm/package.json'), 'utf8'))
-  if (!Array.isArray(pkg.files)) return
-  const files = await collectPublishedFiles(pkg.files, cwd)
-  /** @type {{ file: string, reason: string }[]} */
-  const violations = []
-  for (const rel of files) {
-    const reason = await classifyPublishedFileAsTest(rel, cwd)
-    if (reason) violations.push({ file: rel, reason })
-  }
-  if (violations.length === 0) {
-    pass(`npm/: усі ${files.length} опублікованих файли без тестів і fixtures`)
-    return
-  }
-  for (const v of violations) {
-    fail(
-      `npm/${v.file}: ${v.reason} — додай у "files" у npm/package.json негативний glob, ` +
-        'що виключає цей файл з tarball (наприклад "!**/*.test.mjs", "!**/fixtures/**", "!**/*_test.rego") (npm-module.mdc)'
-    )
-  }
-}
-
-/**
- * Перевіряє базову структуру монорепо: наявність каталогу `npm/` і
- * `npm/package.json`. Поле `workspaces ∋ "npm"` у кореневому `package.json`
- * валідує `npm/policy/npm_module/root_package_json/`.
- * @param {(msg: string) => void} pass callback при успішній перевірці
- * @param {(msg: string) => void} fail callback при помилці
- * @param {string} cwd корінь репозиторію
- */
-async function checkNpmModuleBasicStructure(pass, fail, cwd) {
-  if (existsSync(join(cwd, 'package.json'))) {
-    pass('package.json існує')
-  } else {
-    fail('package.json не існує')
-  }
-
-  const npmDir = join(cwd, 'npm')
-  if (existsSync(npmDir)) {
-    const s = await stat(npmDir)
-    if (s.isDirectory()) {
-      pass('npm/ директорія існує')
-    } else {
-      fail('npm має бути директорією')
-    }
-  } else {
-    fail('npm/ директорія не існує')
-  }
-
-  if (existsSync(join(cwd, 'npm/package.json'))) {
-    pass('npm/package.json існує')
-  } else {
-    fail('npm/package.json не існує — створи package.json для npm модуля')
-  }
-}
-
-/**
- * Перевіряє відповідність проєкту правилам npm-module.mdc
- * @param {import('../../../scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінту
- * @returns {Promise<import('../../../scripts/lib/lint-surface/types.mjs').LintResult>} результат лінту
- */
-export async function lint(ctx) {
-  const cwd = ctx.cwd
-  const reporter = createViolationReporter(ctx)
-  const { pass, fail } = reporter
-
-  await checkNpmModuleBasicStructure(pass, fail, cwd)
-  await checkNoTestsInPublishedFiles(pass, fail, cwd)
-
-  const ignorePaths = await loadCursorIgnorePaths(cwd)
-  const useSrcJsLayout = await npmSrcTreeHasJsFile(cwd, ignorePaths)
-
-  await checkNpmPackageJson(useSrcJsLayout, pass, fail, cwd)
-
-  if (!useSrcJsLayout) {
-    await checkEmitTypesConfig(pass, fail, cwd)
-  }
-
-  const layoutLabel = useSrcJsLayout ? 'layout src' : 'tsconfig emit-types'
-  const hk = await readHkConfig(cwd)
-  if (hk) {
-    pass(`${hk.path} існує`)
-    const missing = useSrcJsLayout ? missingHkSrcLayoutFragments(hk.text) : missingHkEmitTypesConfigFragments(hk.text)
-    if (missing.length === 0) {
-      pass(`${hk.path}: pre-commit містить очікуваний виклик tsc (${layoutLabel})`)
-    } else {
-      fail(`${hk.path}: онови pre-commit крок (npm-module.mdc); не знайдено: ${missing.join(', ')}`)
-    }
-
-    if (DEPRECATED_CHECK_CHANGELOG_RE.test(hk.text)) {
-      fail(
-        `${hk.path}: крок містить застарілий виклик "check changelog" — команду \`check\` прибрано в v14 ` +
-          '(уніфікована поверхня `lint`). Заміни на "npx @7n/rules lint changelog" (npm-module.mdc)'
-      )
-    } else {
-      const missingChangelogStep = missingHkNpmChangelogFragments(hk.text)
-      if (missingChangelogStep.length === 0) {
-        pass(`${hk.path}: pre-commit містить крок npm-changelog (npm-module.mdc)`)
-      } else {
-        fail(`${hk.path}: онови крок npm-changelog (npm-module.mdc); не знайдено: ${missingChangelogStep.join(', ')}`)
-      }
-    }
-  } else {
-    fail('Очікується hk.pkl або .config/hk.pkl з pre-commit і tsc (npm-module.mdc)')
-  }
-
-  if (existsSync(join(cwd, '.github/workflows'))) {
-    pass('.github/workflows/ існує')
-  } else {
-    fail('.github/workflows/ не існує')
-  }
-
-  await checkPublishWorkflow(pass, fail, cwd)
-
-  return reporter.result()
-}

package/rules/npm-module/package_structure/package_structure.mdc

@@ -1,63 +0,0 @@
-## Структура монорепо та компактний пакет
-
-Bun monorepo: workspace **`npm/`**, кореневий **`package.json`**, **`.github/workflows/`**; опційно **`demo/`**.
-
-Мета — **максимально компактний** опублікований пакет: у npm потрапляє тільки те, що потрібно під час `require`/`import` користувачем.
-
-- **`"files"` обовʼязковий** у `npm/package.json` як **whitelist** того, що публікується (без `"files"` npm пакує майже все — це антипатерн для цього правила).
-- **Тести й фікстури не публікуються — через негативні glob-патерни у `"files"`.** Тести можна (і зазвичай зручніше) тримати **поруч з кодом** усередині шляхів, перелічених у `"files"` (наприклад `*.test.mjs` поруч з модулем чи `fixtures/` під `rules/<id>/js/`). Щоб вони не потрапляли у tarball, `"files"` **обовʼязково має містити негативні glob-патерни**, що їх виключають. Покрий усі форми тестового: фреймворк-тести (`bun:test`, `node:test`, `vitest`, `@jest/globals`, `mocha`, …), test-style каталоги (`tests/`, `__tests__/`, `fixtures/`, `__fixtures__/`, `spec/`, `test/`), файли за патернами `*.test.*` / `*.spec.*`. Орієнтовний набір: `"!**/*.test.*"`, `"!**/*.spec.*"`, `"!**/test-helpers.*"`, `"!**/fixtures/**"`, `"!**/__tests__/**"`. **Rego (`*_test.rego`):** за конвенцією conftest юніт-тест лежить поруч з полісі у тому самому `package` — `*_test.rego` усередині опублікованого `policy/` дозволені; якщо потрібна максимальна компактність, додай `"!**/*_test.rego"` явно (як у самому `@7n/rules`).
-- **Лише runtime-залежності у `npm/package.json`.** `devDependencies` тримай у **кореневому** `package.json` монорепо — тоді `npm install @nitra/<pkg>` не тягне інструментарій, потрібний лише для розробки самого пакета.
-
-Перевірки JS (`package_structure.mjs`):
-
-- Наявність `package.json`, `npm/`, `npm/package.json`.
-- Walk шляхів з `"files"` з застосуванням негативних patterns і скан залишку на тест-патерни (walking + AST). Якщо після застосування негативних patterns у tarball лишається test-style файл — `check` падає з вказівкою, який саме негативний glob треба додати у `"files"`.
-
-## TypeScript declaration (`npm/types`)
-
-Файл **`npm/package.json`** має містити **`"types"`** (шлях до головного `.d.ts` або `.d.mts` під **`./types/…`**) і запис **`"types"`** у **`files`**, щоб npm публікував декларації.
-
-Генерація — через **`tsc`** і **`bunx -p typescript`** (окремий пакет **`typescript`** у `devDependencies` не потрібен).
-
-### Варіант A: є вихідний **`.js`** під **`npm/src/`**
-
-Якщо під **`npm/src`** (рекурсивно) є хоча б один файл **`.js`**:
-
-- **`"types": "./types/index.d.ts"`**;
-- у **hk** на **`pre-commit`** з каталогу **`npm/`** викликай:
-
-```bash
-bunx -p typescript tsc src/**/*.js --declaration --allowJs --emitDeclarationOnly --outDir types --skipLibCheck
-```
-
-Якщо glob не розгортається — **`bash -O globstar`** або **`include`** у **`tsconfig`** з тими самими **`compilerOptions`**.
-
-### Варіант B: немає **`npm/src/**/*.js`** (наприклад лише **`bin/`**, **`scripts/**/*.mjs`**)
-
-Не створюй штучний **`src/index.js`**. Замість цього:
-
-1. Додай **`npm/tsconfig.emit-types.json`** з **`include`** на реальні шляхи (`.js` / `.mjs`), **`compilerOptions`**: **`allowJs`**, **`declaration`**, **`emitDeclarationOnly`**, **`outDir`: `"types"`**, **`skipLibCheck`**: **`true`** (за потреби **`rootDir`**, **`module`**, **`moduleResolution`**).
-2. Після першого **`tsc`** подивись, який **`.d.ts`** / **`.d.mts`** відповідає публічному API, і вкажи його в **`types`** (наприклад **`./types/bin/cli.d.ts`**).
-3. У **hk** на **`pre-commit`** з **`npm/`** викликай **`tsc -p tsconfig.emit-types.json`**. Якщо через імпорти **TypeScript** все одно згенерує зайві **`.d.mts`** у **`types/`**, після **`tsc`** обрізай дерево до потрібного entrypoint (наприклад залиш лише **`types/bin/n-rules.d.ts`** через **`find`**), щоб у пакеті не збирались декларації внутрішніх модулів.
-
-Файл **`tsconfig.emit-types.json`** тримай у репозиторії для **hk** / локальної генерації; у **`files`** його не додавай, якщо не хочеш публікувати його на **npm**.
-
-## Git hooks: hk + pre-commit
-
-У корені репозиторію — **`hk.pkl`** (або **`.config/hk.pkl`**) з **`["pre-commit"]`** і командою з відповідного варіанту (A або B) вище.
-
-Після додавання **`hk.pkl`**: **`hk install`**.
-
-## npm publish
-
-**`npm-publish.yml`:** push у **`main`**, **`on.push.paths`** з **`npm/**`**, **`JS-DevTools/npm-publish@v4.1.5`**, **`with.package: npm/package.json`**, **`permissions.id-token: write`** (OIDC на npm).
-
-Workflow робить **release + publish** одним job (`release-publish`): крок **`Release (bump + CHANGELOG + tag)`** (`bunx n-rules release` — агрегує change-файли, bump `version`, генерує секцію `CHANGELOG.md`, ставить git-тег) виконується **перед** публікацією. Тому потрібні **`permissions.contents: write`** і **`persist-credentials: true`** з **`fetch-depth: 0`** на `checkout` (release пушить commit-back версії та тег), а також локальний composite **`./.github/actions/setup-bun-deps`** і крок `Configure git identity`. Це узгоджено з **`n-changelog`**: `version`/`CHANGELOG.md` змінює лише `n-rules release` у CI на `main`. Програмна перевірка (`npm_module.npm_publish_yml`) звіряє **весь канонічний сніпет** напряму (`target.json:"check":"template"`, generic deep-subset): усі поля й кроки сніпета (`on.push.paths`/`branches`, `concurrency`, `permissions.contents/id-token`, `checkout` з `persist-credentials/fetch-depth`, `setup-bun-deps`, `Configure git identity`, `Release`, publish-крок) **обовʼязкові**; зайві кроки/поля дозволені (subset-of), масиви матчаться за наявністю (порядок кроків не важить). Сніпет — єдине джерело істини: його редагування одразу змінює enforce, без правок rego й без міграторів.
-
-- Канон: [npm-publish.yml.snippet.yml](./policy/npm_publish_yml/template/npm-publish.yml.snippet.yml)
-
-## Канонічні конфіги
-
-- Кореневий `package.json` (workspaces): [package.json.snippet.json](./policy/root_package_json/template/package.json.snippet.json)
-- `npm/package.json` (whitelist `files` обовʼязково має містити `types`): [package.json.snippet.json](./policy/npm_package_json/template/package.json.snippet.json)
-- `npm/tsconfig.emit-types.json` (canonical `compilerOptions` для emit-types): [tsconfig.emit-types.json.snippet.json](./policy/emit_types_config/template/tsconfig.emit-types.json.snippet.json)

package/rules/npm-module/root_package_json/concern.json

@@ -1,9 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
-  "fixability": "config",
-  "policy": {
-    "files": {
-      "single": "package.json"
-    }
-  }
-}

package/rules/npm-module/root_package_json/docs/fix-root_package_json.md

@@ -1,26 +0,0 @@
----
-type: JS Module
-title: fix-root_package_json.mjs
-resource: npm/rules/npm-module/root_package_json/fix-root_package_json.mjs
-docgen:
-  crc: 8181dffe
-  model: openai-codex/gpt-5.4-mini
-  tier: cloud-min
-  score: 100
-  issues: judge:inaccurate:0.97
-  judgeModel: openai-codex/gpt-5.4-mini
----
-
-## Огляд
-
-`patterns` перевіряє кореневий `package.json` на відповідність еталонному шаблону npm-module і використовується для контролю очікуваної структури цього конфіга. Публічна функція: `patterns`. Конфіг, на який спирається код: `package.json`.
-
-## Поведінка
-
-1. `patterns` визначає набір правил, які звіряють кореневий `package.json` з еталонним шаблоном для npm-module.
-2. Кожне правило в цьому наборі націлене на `package.json` і використовується для вирівнювання кореневого конфіга з очікуваною структурою проєкту.
-3. `patterns` потрібен, щоб централізовано підтримувати однаковий формат root `package.json` у межах цього типу пакета.
-
-## Гарантії поведінки
-
-- Read-only: не виконує операцій запису (ФС/БД).

package/rules/npm-module/root_package_json/docs/index.md

@@ -1,9 +0,0 @@
----
-type: Directory Index
-title: npm/rules/npm-module/root_package_json
-resource: npm/rules/npm-module/root_package_json/
----
-
-| Файл                                                  | Тип       |
-| ----------------------------------------------------- | --------- |
-| [fix-root_package_json.mjs](fix-root_package_json.md) | JS Module |

package/rules/npm-module/root_package_json/fix-root_package_json.mjs

@@ -1,5 +0,0 @@
-import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
-
-export const patterns = [
-  createTemplateFixPattern({ id: 'npm-module-root_package_json-template', targetPath: 'package.json' })
-]