@7n/rules 1.0.0

package/rules/npm-module/emit_types_config/emit_types_config.rego

@@ -0,0 +1,28 @@
+# Перевірка `npm/tsconfig.emit-types.json` (npm-module.mdc).
+#
+# Канон надходить через --data: { "template": { "snippet": ... } }
+# Структура --data сформована з template/tsconfig.emit-types.json.snippet.json.
+# Snippet — 2-рівнева мапа (section → key → expected). Walker такий самий,
+# як для ga.vscode_settings / bun.bunfig.
+package npm_module.emit_types_config
+
+import rego.v1
+
+# Leaf-by-leaf: коли section присутня й обʼєкт.
+deny contains msg if {
+	some section, expected_inner in data.template.snippet
+	inner := object.get(input, section, {})
+	is_object(inner)
+	some leaf_key, expected_value in expected_inner
+	actual := object.get(inner, leaf_key, null)
+	actual != expected_value
+	msg := sprintf("npm/tsconfig.emit-types.json: %s.%s має бути %v (npm-module.mdc)", [section, leaf_key, expected_value])
+}
+
+# Section відсутня (null) або не обʼєкт.
+deny contains msg if {
+	some section in object.keys(data.template.snippet)
+	raw := object.get(input, section, null)
+	not is_object(raw)
+	msg := sprintf("npm/tsconfig.emit-types.json: відсутній %s (npm-module.mdc)", [section])
+}

package/rules/npm-module/emit_types_config/template/tsconfig.emit-types.json.snippet.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "types",
+    "skipLibCheck": true
+  }
+}

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

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "lint": { "scope": "full", "glob": ["npm/rules/**/js/**/*.mjs", "npm/skills/**/js/**/*.mjs"] }
+}

package/rules/npm-module/header_doc_pointer/docs/main.md

@@ -0,0 +1,40 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/npm-module/header_doc_pointer/main.mjs
+docgen:
+  crc: ab65b5d3
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл забезпечує валідацію відповідності конвенціям документації для файлів правил, розташованих у директорії `.cursor/rules/`, та файлів навичок у `.cursor/skills/`. Він сканує кодову базу у директорії `js/` для пошуку файлів документації, перевіряючи, чи не перевищує JSDoc-блок довжину одного рядка для опису поведінки кожного файлу правила або навички.
+
+## Поведінка
+
+Поведінка:
+
+1. Викликається `main`.
+2. Створюється репортер.
+3. Для сегментів `npm/rules` та `npm/skills` сканується кожен піддиректорія правил або скілів.
+4. Для кожної піддиректорії перевіряється її каталог `js/`.
+5. У каталозі `js/` скануються всі файли з розширенням `.mjs`, окрім тестів.
+6. Для кожного знайденого файлу:
+   а. Визначається відповідний файл документації у `docs/`, використовуючи ім'я без розширення.
+   б. Якщо такий файл документації існує, аналізується перше заголовочне JSDoc-блоку у коді.
+   в. Якщо JSDoc-блок відсутній, перехід до наступного файлу.
+   г. Якщо JSDoc-блок присутній, рахується кількість непустіших рядків у його тілі, ігноруючи відступ.
+   д. Якщо ця кількість перевищує один, це реєструється як порушення, оскільки документ повинен лише посилатися на поведінку.
+7. Після обробки всіх файлів повертається код виходу репортера.
+
+## Публічний API
+
+main — сканує файли правил у директоріях `npm/rules/*\/js/*.mjs` та `npm/skills/*\/js/*.mjs`, а також керує генерацією документації, посилаючись на існуючі файли `docs/<stem>.md`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -0,0 +1,18 @@
+## Module-level JSDoc як pointer
+
+Якщо поряд із `js/<stem>.mjs` є файл `js/docs/<stem>.md` — module-level JSDoc у `.mjs` має бути **pointer** (не більше одного непорожнього рядка), а не повноцінний наратив.
+
+Логіка перевірки (`header_doc_pointer.mjs`):
+
+- Сканується перший JSDoc-блок (`/** … */`) до першого `import`/`export` у файлі.
+- Підраховуються непорожні рядки тіла (після зрізання `*`-відступу).
+- Якщо їх більше одного — `check` падає з повідомленням про те, що `docs/<stem>.md` вже описує поведінку і module-level JSDoc має залишатись коротким.
+
+**Покриття:** `npm/rules/*/js/*.mjs` і `npm/skills/*/js/*.mjs` (не тестові файли `*.test.mjs`). Якщо `docs/<stem>.md` відсутня — обмежень на довжину JSDoc немає.
+
+**Приклад правильного pointer-JSDoc:**
+
+```js
+/** @see ./docs/package_structure.md */
+import { existsSync } from 'node:fs'
+```

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

@@ -0,0 +1,131 @@
+/** Контракт: ./docs/header_doc_pointer.md */
+import { existsSync } from 'node:fs'
+import { readFile, readdir } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+
+import { createViolationReporter } from '../../../scripts/lib/lint-surface/violation-reporter.mjs'
+
+/** Перший JSDoc-блок у файлі (не-жадібний). */
+const MODULE_JSDOC_RE = /\/\*\*[\s\S]*?\*\//
+
+/**
+ * `import` або `export` на початку рядка — межа між module-level і body.
+ * Regex, не AST: нас цікавить тільки текстова позиція, не семантика JS.
+ */
+const CODE_START_RE = /^(?:import|export)\b/m
+
+const NON_WHITESPACE_RE = /\S/
+const STAR_INDENT_RE = /^\s*\*\s?/
+
+/**
+ * Кількість непорожніх рядків між `/**` і `*\/` (після зрізання `*`-відступу).
+ * @param {string} block повний текст JSDoc-блоку з обрамленням
+ * @returns {number} кількість непорожніх рядків у тілі
+ */
+function contentLineCount(block) {
+  return block
+    .split('\n')
+    .slice(1, -1)
+    .filter(l => NON_WHITESPACE_RE.test(l.replace(STAR_INDENT_RE, ''))).length
+}
+
+/**
+ * Повертає module-level JSDoc або `null`, якщо його немає.
+ * @param {string} source вміст mjs-файлу
+ * @returns {string|null} текст module-level JSDoc-блоку або null
+ */
+function moduleJsDoc(source) {
+  const codeStart = CODE_START_RE.exec(source)
+  const prefix = codeStart ? source.slice(0, codeStart.index) : source
+  const m = MODULE_JSDOC_RE.exec(prefix)
+  return m ? m[0] : null
+}
+
+/**
+ * Чи `.mjs`-файл, що не є тестом (`*.test.mjs`).
+ * @param {import('node:fs').Dirent} fileEntry запис каталогу
+ * @returns {boolean} true для звичайних source-файлів
+ */
+function isSourceMjs(fileEntry) {
+  return fileEntry.isFile() && fileEntry.name.endsWith('.mjs') && !fileEntry.name.endsWith('.test.mjs')
+}
+
+/**
+ * Перевіряє один source-файл: якщо поряд є `docs/<stem>.md` і module-level JSDoc
+ * містить >1 непорожній рядок — репортить порушення.
+ * @param {string} jsDir каталог `js/`
+ * @param {import('node:fs').Dirent} fileEntry запис файлу
+ * @param {string} cwd корінь репозиторію
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер
+ * @returns {Promise<void>}
+ */
+async function checkSourceFile(jsDir, fileEntry, cwd, reporter) {
+  const stem = basename(fileEntry.name, '.mjs')
+  const docsPath = join(jsDir, 'docs', `${stem}.md`)
+  if (!existsSync(docsPath)) return
+
+  const filePath = join(jsDir, fileEntry.name)
+  const source = await readFile(filePath, 'utf8')
+  const block = moduleJsDoc(source)
+  if (!block) return
+
+  const count = contentLineCount(block)
+  if (count > 1) {
+    reporter.fail(
+      `${filePath.slice(cwd.length + 1)}: docs/${stem}.md вже описує поведінку — module-level JSDoc має бути pointer (≤1 рядок, зараз ${count})`
+    )
+  }
+}
+
+/**
+ * Перевіряє всі source-файли в одному `js/`-каталозі правила/скіла.
+ * @param {string} jsDir каталог `js/`
+ * @param {string} cwd корінь репозиторію
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер
+ * @returns {Promise<void>}
+ */
+async function checkJsDir(jsDir, cwd, reporter) {
+  for (const fileEntry of await readdir(jsDir, { withFileTypes: true })) {
+    if (!isSourceMjs(fileEntry)) continue
+    await checkSourceFile(jsDir, fileEntry, cwd, reporter)
+  }
+}
+
+/**
+ * Перевіряє один base-сегмент (`npm/rules` чи `npm/skills`): обходить піддиректорії
+ * правил/скілів і їхні `js/`-каталоги.
+ * @param {string} absBase абсолютний шлях до base-сегмента
+ * @param {string} cwd корінь репозиторію
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер
+ * @returns {Promise<void>}
+ */
+async function checkBaseSegment(absBase, cwd, reporter) {
+  for (const ruleEntry of await readdir(absBase, { withFileTypes: true })) {
+    if (!ruleEntry.isDirectory() || ruleEntry.name.startsWith('.')) continue
+
+    const jsDir = join(absBase, ruleEntry.name, 'js')
+    if (!existsSync(jsDir)) continue
+
+    await checkJsDir(jsDir, cwd, reporter)
+  }
+}
+
+/**
+ * Сканує `npm/rules/*\/js/*.mjs` і `npm/skills/*\/js/*.mjs`.
+ * Якщо поряд існує `docs/<stem>.md` — module-level JSDoc має бути pointer (≤1 рядок),
+ * а не наратив; якщо docs немає — без обмежень.
+ * @param {import('../../../scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінту (cwd, репортер).
+ * @returns {Promise<import('../../../scripts/lib/lint-surface/types.mjs').LintResult>} результат перевірки з pass/fail.
+ */
+export async function lint(ctx) {
+  const cwd = ctx.cwd
+  const reporter = createViolationReporter(ctx)
+
+  for (const baseSegment of ['npm/rules', 'npm/skills']) {
+    const absBase = join(cwd, baseSegment)
+    if (!existsSync(absBase)) continue
+    await checkBaseSegment(absBase, cwd, reporter)
+  }
+
+  return reporter.result()
+}

package/rules/npm-module/main.json

@@ -0,0 +1 @@
+{ "auto": { "glob": "npm/**" } }

package/rules/npm-module/main.mdc

@@ -0,0 +1,38 @@
+---
+description: Оформлення репозиторію для npm модуля
+globs: "npm/**,**/package.json,**/hk.pkl,.github/workflows/npm-publish.yml,**/tsconfig*.json"
+alwaysApply: false
+version: '1.14'
+---
+
+Bun monorepo: workspace **`npm/`**, кореневий **`package.json`**, **`.github/workflows/`**; опційно **`demo/`**.
+
+## Версія та CHANGELOG
+
+Версію (`version` у **`npm/package.json`**) і **`npm/CHANGELOG.md`** **не редагуй вручну** — навіть для hotfix. Єдиний артефакт зміни — **change-файл** (`npx @7n/n ch [--bump <major|minor|patch>] [--section <Added|Changed|Fixed|Removed>] [--message "<…>"]`); bump `version` і генерацію секції CHANGELOG робить `n-rules release` у CI на `main`. Будь-який ручний bump `version` поза CI завалює `check changelog` — навіть із change-файлом.
+
+Повна модель (база порівняння, інверсія шляхів, формат CHANGELOG, post-release-інваріант «верхня секція CHANGELOG == `version`») — у **`n-changelog.mdc`** (джерело істини). Це правило їй підпорядковане й власних інструкцій bump/CHANGELOG не дублює.
+
+### Канонічний крок `npm-changelog` у hk.pkl
+
+У v14 команду `check` прибрано (уніфікована поверхня `lint`) — виклик `npx @7n/rules check changelog` у hk.pkl **завалить** кожен коміт з `❌ Невідома команда: check`. Канонічний pre-commit-крок (hk `amends hk@1.42.0`):
+
+```pkl
+["npm-changelog"] {
+    glob = List("npm/**")
+    check_first = false
+    fix = "N_RULES_CHANGELOG_AUTOFIX=1 bun ./npm/bin/n-rules.js lint changelog"
+}
+```
+
+Лише `fix` (без `check`): env-прапорець `N_RULES_CHANGELOG_AUTOFIX=1` вмикає autofix-режим — за відсутності change-файлу правило само створює його (`patch`/`Changed`, subject останнього коміту) і одразу ставить у git-індекс (`git add`) через `writeChange`/`reportOrFixMissingChangeFile`. Тому додатковий `stage = List("npm/.changes/**")` у цьому wiring **не потрібен** — індексація вже всередині JS-кроку. `package_structure` (`npx @7n/rules lint npm-module`) валідує цей крок: fail на застарілий `check changelog` і fail, якщо кроку `npm-changelog` немає взагалі.
+
+## Швидкий gate через conftest
+
+Rego-пакети (запускаються через `npx @7n/rules fix`):
+
+- `npm_module.npm_publish_yml` — template-driven перевірка `.github/workflows/npm-publish.yml` (deep-subset: усі обовʼязкові поля й кроки з канонічного сніпету).
+- [package.json.snippet.json](./npm_package_json/template/package.json.snippet.json)
+- [npm-publish.yml.snippet.yml](./npm_publish_yml/template/npm-publish.yml.snippet.yml)
+- [package.json.snippet.json](./root_package_json/template/package.json.snippet.json)
+- [tsconfig.emit-types.json.snippet.json](./emit_types_config/template/tsconfig.emit-types.json.snippet.json)

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

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

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

@@ -0,0 +1,57 @@
+## Rego-gate: валідація `npm/package.json`
+
+Rego-пакет: `npm-module.npm_package_json`
+
+Цільовий файл: `npm/package.json`
+
+### Що перевіряється
+
+**Поле `types`** (логіка в rego, не template-driven):
+
+- Має відповідати патерну `./types/index.d.ts` або `./types/<назва>.d.ts|.d.mts`.
+- Шляхи поза директорією `types/` або з іншими розширеннями (`.ts` без `.d`) — deny.
+
+**Поле `files`** (частково template-driven):
+
+- Обовʼязкове, має бути непорожнім масивом.
+- Subset-of перевірка: кожне значення з канонічного сніпету має бути присутнє у `files`. За замовчуванням — `"types"` обовʼязковий.
+
+**Поле `devDependencies`** (inverse-pattern, логіка в rego):
+
+- Не публікуються користувачам пакета — має бути відсутнє або порожнє `{}`.
+- Наявність будь-яких devDeps → deny з переліком залежностей. Dev-інструментарій переноситься у кореневий `package.json`; CLI-тули, які пакет спавнить через `bunx` у репозиторіях-споживачах (пінінг версій), — у `dependencies` (кореневе bun-правило `package_json` такі пакети в root devDeps не пускає).
+
+Канонічний сніпет `files`: [package.json.snippet.json](./template/package.json.snippet.json)
+
+FS-перевірки (наявність файлу зі шляху `types`, скан tarball на тест-патерни) — у JS-перевірці, не тут.
+
+### Приклади
+
+✓ Правильно:
+
+```json
+{
+  "name": "@7n/rules",
+  "types": "./types/bin/n-rules.d.ts",
+  "files": ["types", "mdc", "bin", "CHANGELOG.md"],
+  "dependencies": { "oxc-parser": "^0.128.0" }
+}
+```
+
+✗ Неправильно — `types` поза директорією `types/`:
+
+```json
+{ "types": "./dist/index.d.ts" }
+```
+
+✗ Неправильно — `files` без `"types"`:
+
+```json
+{ "files": ["bin", "mdc"] }
+```
+
+✗ Неправильно — наявні `devDependencies`:
+
+```json
+{ "devDependencies": { "@7n/rules": "^1.0.0" } }
+```

package/rules/npm-module/npm_package_json/npm_package_json.rego

@@ -0,0 +1,73 @@
+# Порт перевірок `npm/package.json` (npm-module.mdc).
+#
+# Канон надходить через --data: { "template": { "snippet": ... } }
+# Структура --data сформована з template/package.json.snippet.json
+# (snippet-array subset-of для whitelist `files`).
+#
+# Логіка, що ЛИШАЄТЬСЯ у rego (inverse-patterns, не виносяться у template):
+#  - форма поля `types` (regex pattern: `./types/index.d.ts` або `./types/<…>.d.ts|.d.mts`);
+#  - `devDependencies` мають бути відсутні або порожні (inverse-pattern — заборона будь-яких).
+#
+# FS-перевірки (наявність файлу зі шляху `types`, скан tarball на тест-патерни) — у JS.
+package npm_module.npm_package_json
+
+import rego.v1
+
+types_field_template := concat(" ", [
+	"npm/package.json: поле \"types\" має бути \"./types/index.d.ts\"",
+	"або \"./types/<…>.d.ts|.d.mts\" (зараз: %v) (npm-module.mdc)",
+])
+
+dev_deps_template := concat(" ", [
+	"npm/package.json: \"devDependencies\" не публікуються користувачам пакета —",
+	"dev-інструментарій перенеси у кореневий package.json, а CLI-тули, які пакет",
+	"спавнить через bunx у споживачів, — у \"dependencies\": %v (npm-module.mdc)",
+])
+
+# ── deny: types (regex — лишається в rego) ───────────────────────────────
+
+deny contains msg if {
+	types_field := object.get(input, "types", "")
+	not valid_types_field(types_field)
+	msg := sprintf(types_field_template, [types_field])
+}
+
+# ── deny: files має існувати та бути масивом ─────────────────────────────
+
+deny contains msg if {
+	not is_array(object.get(input, "files", null))
+	msg := "npm/package.json: обовʼязковий whitelist \"files\" (без нього npm пакує майже все) (npm-module.mdc)"
+}
+
+deny contains msg if {
+	is_array(input.files)
+	count(input.files) == 0
+	msg := "npm/package.json: масив \"files\" не повинен бути порожнім (npm-module.mdc: компактний пакет)"
+}
+
+# ── deny: files subset-of з template (template-driven) ──────────────────
+
+deny contains msg if {
+	some field, expected_values in data.template.snippet
+	is_array(object.get(input, field, null))
+	count(input[field]) > 0
+	actual_set := {v | some v in input[field]}
+	some required in expected_values
+	not required in actual_set
+	msg := sprintf("npm/package.json: масив \"%s\" має містити %q (npm-module.mdc)", [field, required])
+}
+
+# ── deny: devDependencies (inverse-pattern, лишається в rego) ────────────
+
+deny contains msg if {
+	dev := object.get(input, "devDependencies", {})
+	count(dev) > 0
+	names := concat(", ", sort([n | some n, _ in dev]))
+	msg := sprintf(dev_deps_template, [names])
+}
+
+# ── helpers ────────────────────────────────────────────────────────────────
+
+valid_types_field("./types/index.d.ts")
+
+valid_types_field(t) if regex.match(`^\./types/.+\.d\.(ts|mts)$`, t)

package/rules/npm-module/npm_package_json/template/package.json.snippet.json

@@ -0,0 +1 @@
+{ "files": ["types"] }

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

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "policy": {
+    "files": {
+      "single": ".github/workflows/npm-publish.yml"
+    },
+    "check": "template"
+  }
+}

package/rules/npm-module/npm_publish_yml/template/npm-publish.yml.snippet.yml

@@ -0,0 +1,49 @@
+name: npm-publish
+
+on:
+  push:
+    paths:
+      - 'npm/**'
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  release-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # commit-back версії + git-тег
+      id-token: write # КРИТИЧНО для OIDC!
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - uses: ./.github/actions/setup-bun-deps
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '24' # includes npm@11.6.0
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Configure git identity + push auth
+        # persist-credentials лишається false (ga-rule, безпека): checkout не зберігає токен.
+        # Release робить commit-back `git push`, тож даємо job-scoped ephemeral GITHUB_TOKEN
+        # явно через remote-url (а не persisted у git config усього прогону).
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git remote set-url origin "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git"
+
+      - name: Release (bump + CHANGELOG + tag)
+        run: bunx n-rules release
+
+      - name: Publish package
+        uses: JS-DevTools/npm-publish@v4.1.5
+        with:
+          package: npm/package.json

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

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "structural",
+  "lint": { "scope": "full", "glob": ["**/*"] }
+}

package/rules/npm-module/package_structure/docs/main.md

@@ -0,0 +1,37 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/npm-module/package_structure/main.mjs
+docgen:
+  crc: 321b552d
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 85
+  issues: anchor-miss:(npm-module.mdc),surzhik,judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Компонент валідує відповідність проєкту стандартам, визначеним у `npm-module.mdc`, аналізуючи конфігурації (`tsconfig.emit-types.json`, `package.json`, `meta.json`). Він виконує логіку, зокрема через функції `globToRegex`, `findTestFrameworkImport`, `classifyPublishedFileAsTest` та `main`, обробляючи помилки за принципом fail-safe, ніколи не кидаючи винятків назовні. Процес роботи є read-only, і він свідомо ігнорує каталоги `.github` та `.git` під час аналізу.
+
+## Поведінка
+
+Поведінка:
+globToRegex перетворює glob-патерн у регулярний вираз з якорями початку та кінця, підтримуючи globstar, `*`, `?` та brace-альтернативи; ігнорує шляхи з `.github` та `.git`.
+findTestFrameworkImport шукає у вмісті файлу імпорти або виклики, які вказують на використання тестових фреймворків.
+classifyPublishedFileAsTest визначає, чи вважається певний опублікований файл тестовим або фікстурою на основі назви, каталогу або імпортів.
+main виконує повну перевірку відповідності проєкту конвенціям npm-module.mdc, аналізуючи структуру, конфігурації та файли, і виводить статус проходження перевірок.
+
+## Публічний API
+
+globToRegex — перетворює шаблон пошуку файлів у регулярний вираз, забезпечуючи коректне зіставлення шляхів.
+findTestFrameworkImport — виявляє, чи використовується у файлі механізм імпорту тест-фреймворку.
+classifyPublishedFileAsTest — визначає, чи повинен вважатися опублікований файл тестом або фікстурою, ґрунтуючись на його шляху та вмісті.
+main — забезпечує дотримання проєкту всіх вимог, визначених у конвенціях, описаних у npm-module.mdc.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.
+- Свідомо пропускає шляхи: `.github`, `.git`.