@7n/rules-lang-js 0.3.1 → 0.4.1

package/rules/js/eslint/main.mjs

@@ -0,0 +1,115 @@
+/**
+ * lint-поверхня js/eslint: read-only detector (oxlint + eslint). Fix (oxlint --fix /
+ * eslint --fix) — окремий T0 `fix-eslint.mjs` (детермінований), не в detector-і.
+ */
+import { resolve, relative } from 'node:path'
+
+import { ESLint } from 'eslint'
+
+import { addedLinesByFile } from '@7n/rules/scripts/lib/diff-added-lines.mjs'
+import { spawnAsync } from '@7n/rules/scripts/utils/spawn-async.mjs'
+import { WORKTREE_CHECKOUT_GLOBS } from '@7n/rules/scripts/utils/walkDir.mjs'
+import { classifyFindings, eslintResultsToFindings, parseOxlint } from '../lint-findings/main.mjs'
+
+const JS_EXT_RE = /\.(?:mjs|cjs|js|jsx|ts|tsx|vue)$/u
+
+/**
+ * @param {string[]} files список шляхів
+ * @returns {string[]} лише JS-подібні файли
+ */
+export function filterJsFiles(files) {
+  return files.filter(f => JS_EXT_RE.test(f))
+}
+
+/**
+ * Async (не блокує event loop) — детектор може виконуватись у parallel lane `detectAll()`
+ * (ADR 260716-1354).
+ * @param {string[]} args аргументи запуску oxlint
+ * @param {string} cwd робочий каталог
+ * @returns {Promise<{ status: number, stdout: string, stderr: string }>} код завершення, stdout і stderr процесу
+ */
+async function runOxlintJson(args, cwd) {
+  const r = await spawnAsync('bunx', args, { cwd })
+  return { status: typeof r.exitCode === 'number' ? r.exitCode : 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' }
+}
+
+/**
+ * Finding → LintViolation.
+ * @param {{ file: string, line: number, rule: string, message: string, tool: string }} f знахідка лінтера
+ * @param {string} cwd робочий каталог
+ * @param {'error'|'warn'} severity рівень порушення
+ * @returns {import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintViolation} нормалізоване порушення
+ */
+function toViolation(f, cwd, severity) {
+  return /** @type {import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintViolation} */ ({
+    reason: f.rule || `${f.tool}-error`,
+    message: `${f.message} (${f.tool})`,
+    file: relative(cwd, f.file).split('\\').join('/'),
+    severity,
+    data: { line: f.line, tool: f.tool }
+  })
+}
+
+/**
+ * Збирає findings (oxlint json + eslint read-only) по заданих файлах або всьому проєкту.
+ * @param {string[]|null} js null → весь проєкт
+ * @param {string} cwd робочий каталог
+ * @returns {Promise<Array<{ file: string, line: number, rule: string, message: string, tool: string }>>} зібрані знахідки oxlint+eslint
+ */
+async function collectFindings(js, cwd) {
+  // warnIgnored:false — файли з delta, що матчать ignore-патерни конфігу, не є порушеннями.
+  // overrideConfig лише з ignores → global ignores: worktree-чекаути (.worktrees/,
+  // .claude/worktrees/) — копії репо, споживацький eslint-конфіг їх не виключає.
+  const eslint = new ESLint({ cwd, warnIgnored: false, overrideConfig: { ignores: WORKTREE_CHECKOUT_GLOBS } })
+  const esResults = await eslint.lintFiles(js === null ? [cwd] : js.map(f => resolve(cwd, f)))
+  const es = eslintResultsToFindings(esResults)
+
+  const worktreeIgnoreArgs = WORKTREE_CHECKOUT_GLOBS.map(g => `--ignore-pattern=${g}`)
+  const oxArgs =
+    js === null
+      ? ['oxlint', '--format=json', ...worktreeIgnoreArgs]
+      : ['oxlint', '--format=json', ...worktreeIgnoreArgs, ...js]
+  const oxRes = await runOxlintJson(oxArgs, cwd)
+  const ox = parseOxlint(oxRes.stdout)
+  if (ox === null && oxRes.status !== 0) {
+    // Хвости stdout/stderr — інакше на CI причина крашу (OOM, конфіг, версія) невидима.
+    const tail = [oxRes.stderr, oxRes.stdout]
+      .map(t => t.trim().slice(-500))
+      .filter(t => t !== '')
+      .join('\n--- stdout: ')
+    const suffix = tail === '' ? '' : `\n${tail}`
+    throw new Error(
+      `oxlint завершився з помилкою (exit ${oxRes.status}, не lint-порушення) — json не розпарсено${suffix}`
+    )
+  }
+  return [...(ox ?? []), ...es]
+}
+
+/**
+ * Detector js/eslint: per-file (classify introduced/pre-existing) або full-project.
+ * @param {import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінту
+ * @returns {Promise<import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintResult>} перелік порушень
+ */
+export async function lint(ctx) {
+  const { cwd, files } = ctx
+
+  if (files === undefined) {
+    const findings = await collectFindings(null, cwd)
+    return { violations: findings.map(f => toViolation(f, cwd, 'error')) }
+  }
+
+  const js = filterJsFiles(files)
+  if (js.length === 0) return { violations: [] }
+
+  const findings = await collectFindings(js, cwd)
+  if (findings.length === 0) return { violations: [] }
+
+  // introduced (на доданих рядках) → error; pre-existing → warn.
+  const classified = classifyFindings(findings, addedLinesByFile(js, cwd), cwd)
+  return {
+    violations: [
+      ...classified.introduced.map(f => toViolation(f, cwd, 'error')),
+      ...classified.preExisting.map(f => toViolation(f, cwd, 'warn'))
+    ]
+  }
+}

package/rules/js/file-extensions/concern.json

@@ -0,0 +1,3 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json"
+}

package/rules/js/file-extensions/file-extensions.mdc

@@ -0,0 +1,12 @@
+## Розширення нових файлів — `.mjs` / `.cjs`, не `.js`
+
+**Нові** JS-файли створюй з явним розширенням модуля:
+
+- **`.mjs`** — для ESM (типовий випадок);
+- **`.cjs`** — для CommonJS, де він справді потрібен.
+
+Голий **`.js`** для нового файлу **заборонено**. Розширення `.js` інтерпретується як ESM чи CJS лише за полем `package.json#type`, тож той самий файл читається по-різному залежно від пакета. Явне `.mjs`/`.cjs` робить тип модуля однозначним **без читання `package.json`** — навіть якщо `type` зміниться або файл перемістять в інший пакет. Це доповнює вимогу `"type": "module"` у [package_json.mdc](../package_json/package_json.mdc): `type` лишається каноном для всього дерева, а розширення нового файлу прибирає залежність від нього.
+
+Стосується **backend і frontend** — будь-який новий вихідний файл: `src/`, тести `*.test.*`, `scripts/`, `src/conn/` тощо.
+
+**Існуючі `.js` лишаються як є** — масово перейменовувати не треба; це конвенція для нового коду. Автоматичної перевірки тут немає: stateless-скан не відрізнить новий файл від існуючого, тож `.js` нікого не фейлить.

package/rules/js/jscpd_config/concern.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "policy": {
+    "files": {
+      "single": ".jscpd.json",
+      "required": true
+    },
+    "missingMessage": ".jscpd.json не існує — створи з полями згідно js.mdc"
+  }
+}

package/rules/js/jscpd_config/docs/fix-jscpd_config.md

@@ -0,0 +1,25 @@
+---
+type: JS Module
+title: fix-jscpd_config.mjs
+resource: plugins/lang-js/rules/js/jscpd_config/fix-jscpd_config.mjs
+docgen:
+  crc: 9c058fae
+  model: openai-codex/gpt-5.4-mini
+  score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+`patterns` визначає узгоджені з правилами проєкту зміни для `.jscpd.json` і слугує централізованим орієнтиром для того, що саме має бути виправлено в цьому конфігу.
+
+## Поведінка
+
+1. `patterns` формує перелік правил для уніфікації шаблонного конфіга проєкту.
+2. Кожне правило орієнтується на конфіг `.jscpd.json`, щоб тримати його в узгодженому, очікуваному форматі.
+3. `patterns` потрібен для централізованого опису того, що саме має бути виправлено в `.jscpd.json`, без ручного втручання в інші файли чи артефакти.
+4. `patterns` не змінює файлову систему або базу даних і працює лише як опис набору правок для цього конфіга.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/js/jscpd_config/docs/index.md

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

package/rules/js/jscpd_config/fix-jscpd_config.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '@7n/rules/scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'js-jscpd_config-template', targetPath: '.jscpd.json' })]

package/rules/js/jscpd_config/jscpd_config.mdc

@@ -0,0 +1,42 @@
+## Rego-gate `.jscpd.json`
+
+Rego-пакет: `js_lint.jscpd`
+
+Цільовий файл: `.jscpd.json` у корені проєкту.
+
+Що перевіряється:
+
+- `gitignore` — точна відповідність (`true`)
+- `exitCode` — точна відповідність (`1`)
+- `reporters` — subset-of: масив має містити всі елементи з канону (`["console"]`)
+- `minLines` — число, значення >= канонічного порогу (`25`); більше дозволено
+
+Канон-snippet: [.jscpd.json.snippet.json](./template/.jscpd.json.snippet.json)
+
+### Ігнорування `.claude/worktrees/`
+
+Каталог `.claude/worktrees/` (робочі копії, які Claude Code створює через **superpowers:using-git-worktrees**) має ігноруватися:
+
+- додай `.claude/worktrees/` у кореневий `.gitignore` (штатне місце для не-комітних робочих копій);
+- у `.jscpd.json` додай `.claude/worktrees/**` у `ignore` як страховку на випадок запуску без `gitignore: true`.
+
+Без цього jscpd сканує паралельну копію репо в worktree і фіксує самозбіги між дзеркальними файлами.
+
+```text title=".gitignore (фрагмент)"
+.claude/worktrees/
+```
+
+### Ігнорування `**/CHANGELOG.md`
+
+`**/CHANGELOG.md` у каноні `ignore`: release-журнали різних пакетів структурно повторюються (заголовки `## [x.y.z] - YYYY-MM-DD`, секції `### Added / Changed / Fixed` за Keep a Changelog), і `jscpd` за `minLines: 25` фіксує їх як клон — це false positive. Без цього в монорепо легко зловити критичний `bun run lint` на парі CHANGELOG-ів довжиною від ~25 рядків.
+
+### Рефакторинг vs конфіг
+
+Коли **jscpd** знаходить клони, спочатку зменшуй дублювання кодом, а не конфігом.
+
+- **Рефакторинг:** винеси спільні фрагменти в функції, модулі, утиліти, composables/hooks, спільні компоненти або базові типи — залежно від контексту.
+- **Структура:** якщо одна й та сама логіка розмазана між файлами чи пакетами, запропонуй зміну структури (наприклад, спільний модуль, `shared/`, внутрішній пакет у monorepo), щоб була **одна канонічна реалізація** і повторні місця лише викликали її.
+
+Розширення `ignore` чи завищення `minLines` лише щоб прибрати звіт — не заміна рефакторингу для справжніх клонів. Якщо збіг **семантично випадковий** (генерований код, формальні шаблони без спільної логіки), після оцінки допустимо точковий `ignore` або зміна порогу — з коротким обґрунтуванням.
+
+Перед рефакторингом перевір чи є тести на блоки які підлягають зміні (Bun.test для js, playwright для vue). Якщо тестів немає або вони не покривають — спочатку створи їх, перевір що вони відпрацьовують коректно, потім роби рефакторинг і ще раз запускай тести.

package/rules/js/jscpd_config/jscpd_config.rego

@@ -0,0 +1,44 @@
+# Перевірка `.jscpd.json` (js.mdc).
+#
+# Канон надходить через --data: { "template": { "snippet": ... } }
+# Структура --data сформована з template/.jscpd.json.snippet.json.
+# Особливості:
+#  - `reporters` — subset-of (масив string)
+#  - `minLines` — >= expected (semantic: дозволяється більше, не менше)
+#  - `gitignore`/`exitCode` — exact match
+package js.jscpd_config
+
+import rego.v1
+
+# Top-level scalar leafs (exact match) для gitignore + exitCode.
+deny contains msg if {
+	some key, expected_value in data.template.snippet
+	key != "minLines"
+	not is_array(expected_value)
+	actual := object.get(input, key, null)
+	actual != expected_value
+	msg := sprintf(".jscpd.json має містити \"%s\": %v (js.mdc)", [key, expected_value])
+}
+
+# Array subset-of для reporters.
+deny contains msg if {
+	some field, expected_values in data.template.snippet
+	is_array(expected_values)
+	actual_set := {v | some v in object.get(input, field, [])}
+	some required in expected_values
+	not required in actual_set
+	msg := sprintf(".jscpd.json має містити \"%s\": [\"%s\"] (js.mdc)", [field, required])
+}
+
+# minLines: must be number and >= expected.
+deny contains msg if {
+	expected := data.template.snippet.minLines
+	actual := object.get(input, "minLines", null)
+	not is_valid_min_lines(actual, expected)
+	msg := sprintf(".jscpd.json має містити \"minLines\" як число >= %d (js.mdc)", [expected])
+}
+
+is_valid_min_lines(actual, expected) if {
+	is_number(actual)
+	actual >= expected
+}

package/rules/js/jscpd_config/template/.jscpd.json.snippet.json

@@ -0,0 +1,7 @@
+{
+  "gitignore": true,
+  "exitCode": 1,
+  "reporters": ["console"],
+  "minLines": 25,
+  "ignore": [".claude/worktrees/**", "**/dist/**", "**/CHANGELOG.md"]
+}

package/rules/js/jscpd_duplicates/concern.json

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

package/rules/js/jscpd_duplicates/docs/main.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: main.mjs
+resource: plugins/lang-js/rules/js/jscpd_duplicates/main.mjs
+docgen:
+  crc: 0a9e3d15
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Публічна функція `lint` аналізує вихідний код у вказаному кореневому каталозі, використовуючи `jscpd`, щоб виявляти дублікати та інші порушення стилю і логіки коду. Функція повертає код виходу, який інформує про успішне завершення аналізу чи виявлення проблем.
+
+## Поведінка
+
+1. Викликається функція `lint`, яка ініціює перевірку коду у вказаному кореневому каталозі з метою виявлення дублікатів.
+2. Процес аналізу виконується за допомогою `jscpd` у середовищі `bunx`.
+3. Функція повертає код завершення процесу: 0 у разі успішного виконання (без знайдених проблем) або інше число, що вказує на помилки.
+
+## Публічний API
+
+lint — виявляє дублікати коду за допомогою `bunx jscpd` у файлах JavaScript/JSCPD.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/js/jscpd_duplicates/main.mjs

@@ -0,0 +1,69 @@
+/**
+ * lint-поверхня js/jscpd_duplicates: read-only detector дублікатів коду (`jscpd`).
+ * Кожен клон → одне порушення (anchored на `firstFile`), із посиланням на `secondFile`
+ * у `data`. JSON-звіт пишеться у системний tmp (поза репо) — дерево не мутується.
+ */
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { spawnAsync } from '@7n/rules/scripts/utils/spawn-async.mjs'
+
+/**
+ * @typedef {{ name: string, start: number, end: number }} JscpdFileRef
+ * @typedef {{ firstFile: JscpdFileRef, secondFile: JscpdFileRef, lines: number, format: string }} JscpdClone
+ */
+
+/**
+ * Один клон → LintViolation.
+ * @param {JscpdClone} clone дубльований фрагмент
+ * @returns {import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintViolation} нормалізоване порушення
+ */
+function cloneToViolation(clone) {
+  const a = clone.firstFile
+  const b = clone.secondFile
+  const aLoc = `${a.name}:${a.start}-${a.end}`
+  const bLoc = `${b.name}:${b.start}-${b.end}`
+  return /** @type {import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintViolation} */ ({
+    reason: 'duplicate-clone',
+    message: `jscpd: дубльований фрагмент (${clone.lines} рядків, ${clone.format}) ${aLoc} ↔ ${bLoc}`,
+    file: a.name,
+    data: {
+      line: a.start,
+      lines: clone.lines,
+      format: clone.format,
+      first: { file: a.name, start: a.start, end: a.end },
+      second: { file: b.name, start: b.start, end: b.end }
+    }
+  })
+}
+
+/**
+ * Detector js/jscpd_duplicates: дублікати коду через `jscpd` (read-only). Async (не блокує
+ * event loop) — детектор може виконуватись у parallel lane `detectAll()` (ADR 260716-1354).
+ * @param {import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінту
+ * @returns {Promise<import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintResult>} перелік порушень
+ */
+export async function lint(ctx) {
+  const cwd = ctx.cwd
+  const outDir = mkdtempSync(join(tmpdir(), 'jscpd-'))
+  try {
+    const r = await spawnAsync('bunx', ['jscpd', '.', '--reporters', 'json', '--output', outDir, '--silent'], { cwd })
+    let report
+    try {
+      report = JSON.parse(readFileSync(join(outDir, 'jscpd-report.json'), 'utf8'))
+    } catch {
+      // jscpd не зміг сформувати звіт (інструмент відсутній / краш) — пропускаємо
+      const detail = `${r.stdout ?? ''}${r.stderr ?? ''}`.trim().slice(0, 500)
+      const suffix = detail ? `: ${detail}` : ''
+      return {
+        violations: [],
+        diagnostics: [{ level: 'warn', message: `jscpd: не вдалося прочитати JSON-звіт${suffix}` }]
+      }
+    }
+    const clones = Array.isArray(report.duplicates) ? report.duplicates : []
+    return { violations: clones.map(clone => cloneToViolation(clone)) }
+  } finally {
+    rmSync(outDir, { recursive: true, force: true })
+  }
+}

package/rules/js/knip/concern.json

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

package/rules/js/knip/docs/main.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: main.mjs
+resource: plugins/lang-js/rules/js/knip/main.mjs
+docgen:
+  crc: e46cd90b
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Lint-поверхня `js/knip`: read-only detector невикористаних залежностей, експортів і файлів через programmatic API knip. Кожен knip-issue стає одним порушенням (`reason` = тип issue, `file`/`line` де доступні); звіт рендерить runner, сам детектор нічого не друкує і не мутує (без `--fix`).
+
+## Поведінка
+
+- `lint(ctx)` будує опції knip (`createOptions` з dist-каталогу пакета — внутрішній util не експортується через `exports`), глушить TTY-прогрес поза `ctx.verbose` і жене `knipMain`.
+- Кожен issue з `results.issues` нормалізується у violation: `message` = `knip: <тип> \`<символ>\` — <файл:рядок>`, `severity` warn/error за knip.
+- Вбудований ігнор пакетів екосистеми n-rules: unused dependency/devDependency-issue на `@7n/rules` та `@7n/rules-*` (lang-/ci-плагіни) відкидається — їх ставить і веде сам `npx @7n/rules`, код споживача їх не імпортує, тож у кожному consumer-репо це було б хибне спрацювання. Інші типи issue (files, exports) на ці пакети НЕ ігноруються.
+
+## Публічний API
+
+- lint — детектор js/knip: повертає `{ violations }` з нормалізованими knip-issue.
+- isNRulesPackageIssue — чи є issue хибним спрацюванням на пакет екосистеми n-rules (експортовано для тестів).
+
+## Гарантії поведінки
+
+- Read-only: knip запускається без `--fix`, жодних мутацій ФС/БД.
+- Не друкує звіт — рендеринг на боці runner-а.

package/rules/js/knip/knip.mdc

@@ -0,0 +1,15 @@
+## `knip.json` — аналіз невикористаних залежностей та експортів
+
+Залежнісний аналіз (knip — невикористані залежності/експорти, `knip.json` канон) крос-файловий; запускається як частина `npx @7n/rules lint js`.
+
+У корені проєкту має бути **`knip.json`**, який стартує з канонічного baseline з пакета `@7n/rules` — файл [`knip-canonical.json`](../tooling/data/tooling/knip-canonical.json). Канон покриває типові false-positives для наших правил:
+
+- `entry` зі CLI-конфігами (eslint, stylelint, oxlint, jscpd, markdownlint-cli2, `commitlint`);
+- `project` для `**/*.{js,mjs,cjs,jsx,ts,tsx,mts,cts}`;
+- `ignore` для `**/__fixtures__/**`;
+- `ignoreDependencies` для пакетів, посилання на які є лише в не-JS-конфігах (`@nitra/cspell-dict`, `/@cspell\/dict-.+/`, `graphql`);
+- `ignoreBinaries` для CLI, які канон вимагає викликати через `npx`/`bunx` і яких заборонено додавати в `devDependencies` (`actionlint`, `cspell`, `eslint`, `git-ai`, `jscpd`, `markdownlint-cli2`, `oxfmt`, `oxlint`, `shellcheck`, `uvx`, `v8r`, `zizmor`).
+
+Якщо `knip.json` відсутній — `npx @7n/rules lint js` (концерн `js/check`) копіює канон у корінь проєкту як side effect детектора, ще до фази LLM-фіксів. Після створення модифікуй файл під свій проєкт як завгодно: перевіряємо лише наявність, зміст подальших змін не валідується.
+
+Пакет `knip` окремо в `devDependencies` не додавай — `bunx knip` тягне його ad-hoc, як oxlint/eslint/jscpd.

package/rules/js/knip/main.mjs

@@ -0,0 +1,89 @@
+/**
+ * lint-поверхня js/knip: read-only detector невикористаних залежностей/експортів/файлів.
+ * Кожен knip-issue → одне порушення (reason = тип issue, file/line де доступні). Жодних
+ * мутацій (knip запускається без `--fix`) і жодного друку звіту — рендерить runner.
+ */
+import { createRequire } from 'node:module'
+import { dirname, join, relative } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { main as knipMain } from 'knip'
+
+// Пакети екосистеми n-rules (ядро і lang-/ci-плагіни): їх ставить і веде сам
+// `npx @7n/rules` як devDependency, код споживача їх не імпортує — knip завжди
+// вважав би їх unused. Вбудований ігнор знімає хибне спрацювання у ВСІХ consumer-репо без
+// правки їхніх knip.json (канон ignoreDependencies покриває лише свіжі копії).
+const N_RULES_PKG_RE = /^@7n\/rules(-.+)?$/u
+
+/**
+ * Чи є issue хибним спрацюванням на пакет екосистеми n-rules (unused dependency/devDependency).
+ * @param {{ type: string, symbol?: string }} issue knip-issue
+ * @returns {boolean} true — ігноруємо
+ */
+export function isNRulesPackageIssue(issue) {
+  return (
+    (issue.type === 'dependencies' || issue.type === 'devDependencies') &&
+    typeof issue.symbol === 'string' &&
+    N_RULES_PKG_RE.test(issue.symbol)
+  )
+}
+
+/**
+ * Один knip-issue → LintViolation.
+ * @param {{ type: string, filePath?: string, symbol?: string, symbolType?: string, line?: number, col?: number, severity?: string }} issue knip-issue
+ * @param {string} cwd робочий каталог
+ * @returns {import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintViolation} нормалізоване порушення
+ */
+function issueToViolation(issue, cwd) {
+  const abs = issue.filePath
+  const file = abs ? relative(cwd, abs).split('\\').join('/') : undefined
+  const lineSuffix = issue.line ? `:${issue.line}` : ''
+  const where = file ? `${file}${lineSuffix}` : '<unknown>'
+  const symbolType = issue.symbolType ? ` (${issue.symbolType})` : ''
+  const sym = issue.symbol ? ` \`${issue.symbol}\`${symbolType}` : ''
+  /** @type {Partial<import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintViolation>} */
+  const v = {
+    reason: issue.type || 'knip-issue',
+    message: `knip: ${issue.type}${sym} — ${where}`,
+    severity: issue.severity === 'warn' ? 'warn' : 'error',
+    data: { line: issue.line, col: issue.col, symbol: issue.symbol, type: issue.type }
+  }
+  if (file) v.file = file
+  return v
+}
+
+/**
+ * Detector js/knip: невикористані deps/exports/files через programmatic API knip (read-only).
+ * @param {import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінту
+ * @returns {Promise<import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintResult>} перелік порушень
+ */
+export async function lint(ctx) {
+  const cwd = ctx.cwd
+
+  // knip-package не експортує внутрішні util-и через "exports" — резолвимо dist-каталог
+  // від головного entry і імпортуємо `create-options` за абсолютним file:// URL.
+  const require = createRequire(import.meta.url)
+  const distDir = dirname(require.resolve('knip'))
+  // eslint-disable-next-line no-unsanitized/method -- URL from resolved package path, not user input
+  const { createOptions } = await import(pathToFileURL(join(distDir, 'util/create-options.js')).href)
+
+  // knip вмикає власний прогрес-репортер ("Analyzing workspace …") автоматично в TTY,
+  // незалежно від наших verbose-прапорців — глушимо його поза `--verbose`, щоб не
+  // засмічувати вивід `lint --full`.
+  const options = await createOptions({ cwd, isDisableConfigHints: true, isShowProgress: ctx.verbose === true })
+  const results = await knipMain(options)
+
+  /** @type {import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintViolation[]} */
+  const violations = []
+  // results.issues: { <type>: { <file>: { <key>: Issue } } }
+  for (const byFile of Object.values(results.issues)) {
+    for (const byKey of Object.values(byFile)) {
+      for (const issue of Object.values(byKey)) {
+        const typed = /** @type {Parameters<typeof issueToViolation>[0]} */ (issue)
+        if (isNRulesPackageIssue(typed)) continue
+        violations.push(issueToViolation(typed, cwd))
+      }
+    }
+  }
+  return { violations }
+}

package/rules/js/lint-findings/concern.json

@@ -0,0 +1,3 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json"
+}

package/rules/js/lint-findings/docs/main.md

@@ -0,0 +1,40 @@
+---
+type: JS Module
+title: main.mjs
+resource: plugins/lang-js/rules/js/lint-findings/main.mjs
+docgen:
+  crc: dc58119b
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Ось оновлений текст секції «overview» відповідно до ваших вимог:
+
+Ця система надає можливості для аналізу логіки та виявлення помилок на основі результатів відмінних лінтерів. Доступні функції включають `parseOxlint` та `parseEslint` для парсингу результатів. Далі, `eslintResultsToFindings` перетворює ці результати у стандартизовані знахідки, які потім класифікуються за допомогою `classifyFindings`. Фінальне представлення цих знахідок здійснюється функцією `renderFindings`. Усі операції є read-only та не взаємодіють з файловою системою чи базою даних. Система працює з принципом fail-safe, тобто перехоплює можливі помилки і, замість викидання винятку, повертає порожнє значення, наприклад, `null`.
+
+## Поведінка
+
+Поведінка:
+parseOxlint: Парсить вивід `oxlint` у форматі JSON, повертаючи список знайдених порушень або `null` у разі непарсибельного JSON.
+parseEslint: Парсить вивід `eslint` у форматі JSON, повертаючи список знайдених порушень або `null` у разі непарсибельного JSON.
+eslintResultsToFindings: Конвертує результати, отримані з API `eslint.lintFiles`, у нормалізований список знайдених порушень.
+classifyFindings: Класифікує знайдені порушення на "внесено цією зміною" або "борг файлу" на основі інформації про додані рядки у файлі.
+renderFindings: Форматує класифіковані порушення у текстовий звіт, розділяючи внесені та існуючі проблеми.
+
+## Публічний API
+
+parseOxlint — отримує результат парсингу Oxlint, повертаючи `null`, якщо вивід інструмента не може бути інтерпретований як JSON.
+parseEslint — отримує результат парсингу Eslint, повертаючи `null`, якщо вивід інструмента не може бути інтерпретований як JSON.
+eslintResultsToFindings — перетворює детальні звіти з ESLint у стандартизований формат знахідок.
+classifyFindings — розрізняє знахідки, які виникли через додані рядки, від тих, що були присутні до змін.
+renderFindings — створює зведений звіт, відображаючи нові знахідки (🆕 introduced) та існуючий технічний борг (🗄 pre-existing).
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.