@nitra/cursor 12.3.0 → 12.3.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [12.3.1] - 2026-06-20
+
+### Changed
+
+- npm-module конформність: module-level JSDoc → pointer (`/** @see ./docs/… */`) у docgen-crc/extract-anchors/files-batch/judge-measure, doc-files/lint, lint/orchestrate, doc-aggregate/docgen-ignore; doc-CRC перештамповано; eslint --fix-стан прийнято як канон
+
 ## [12.3.0] - 2026-06-19
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "12.3.0",
+  "version": "12.3.1",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",
@@ -68,4 +68,4 @@
     "skills": "skills",
     "extensions": ".pi-template/extensions"
   }
-}
+}

package/rules/doc-files/js/docgen-crc.mjs

@@ -1,34 +1,4 @@
-/**
- * CRC32 джерела + YAML-frontmatter файлової документації.
- *
- * Кожна файлова дока несе у frontmatter контрольну суму байтів джерела на момент
- * генерації. Це детермінований маркер застарілості: `crc32(поточне джерело)` звіряється
- * з `crc` у доці — розбіжність (або відсутня дока) означає, що дока відстала від коду.
- * CRC не залежить від git-стану (rebase, незакомічене, гілки), тож придатний і для
- * per-edit hook (бачить лише змінений файл), і для повного сканування.
- *
- * Degraded-маркер (ADR 260610-2228): якщо локальний конвеєр не дотягнув до порогу
- * якості, дока все одно пишеться, а frontmatter додатково несе `score` (det-оцінка)
- * та `issues` (коди проблем). CRC при цьому свіжий — Stop-гейт не блокує задачі через
- * слабкість моделі; борг видимий через `check --degraded` і автоматично доретраюється
- * наступним `gen` (рівно один раз на версію джерела — далі `retried: true` у frontmatter).
- *
- * Frontmatter — єдиний дозволений виняток із правила «чистий Markdown без HTML»:
- * це машинні метадані, не контент. Формат:
- *
- *   ---
- *   docgen:
- *     source: src/lib/foo.js
- *     crc: a3f1c9e0
- *     model: omlx/gemma-4-e4b-it-OptiQ-4bit
- *     score: 55
- *     issues: short-behavior,internal-name:bar
- *   ---
- *
- * `model` — повний id моделі-генератора (як повертає resolveModel, із префіксом
- * провайдера). Пасивна метадата: маркер «віку» доки за моделлю на додачу до CRC
- * джерела. На staleness НЕ впливає — звіряється лише `crc`.
- */
+/** @see ./docs/docgen-crc.md */
 import { existsSync, readFileSync } from 'node:fs'
 import { basename, extname } from 'node:path'
 import { crc32 as zlibCrc32 } from 'node:zlib'
@@ -173,6 +143,9 @@ export function buildDocFrontmatter(source, crc, quality = null, model = null) {
  */
 const LEADING_H1_RE = /^#[^\n]*\n+/u
 
+/**
+ *
+ */
 export function stampDoc(md, source, crc, quality = null, model = null) {
   const { body } = parseDocFrontmatter(md)
   const cleanBody = body.replace(LEADING_NEWLINES_RE, '').replace(LEADING_H1_RE, '')

package/rules/doc-files/js/docgen-extract-anchors.mjs

@@ -1,18 +1,4 @@
-/**
- * E1 (Fact-anchoring): детермінований витяг «анкорів» — конкретних фрагментів
- * з коду, які LLM зобовʼязана згадати в документації, щоб не зісковзнути на
- * generic-фрази.
- *
- * Категорії анкорів:
- *   - urls         : усі https?://… у вихідному коді
- *   - magicStrings : export const X = '…' з непорожнім value (≤120 символів)
- *   - errorMarkers : суфікси повідомлень про помилки виду `(rule.mdc)`
- *   - configRefs   : посилання на .json-конфіги проєкту (.n-cursor.json, …)
- *   - examples     : ```…```-блоки у file-header JSDoc (першому коментарі файла)
- *
- * Всі регулярки — на сирому src без AST: дешево, безпечно, без false-positive
- * критичної ваги (надмір — менша проблема, ніж пропуск).
- */
+/** @see ./docs/docgen-extract-anchors.md */
 
 const URL_RE = /https?:\/\/[^\s'"`)<>]+/g
 // Після обрізання template-частини URL має лишитися host (R10).

package/rules/doc-files/js/docgen-files-batch.mjs

@@ -1,15 +1,4 @@
-/**
- * JS-оркестрація генерації файлових док (local-only, ADR 260610-2228).
- *
- * Уся черга/батчинг/CRC-штамп живуть тут, а не в контексті моделі — тому
- * масовий перший прогін на сотні файлів не «заморює» агента. Конвеєр суто
- * локальний: жодних cloud-ескалацій; якщо det-score нижче порогу — дока все
- * одно пишеться з degraded-маркером (`score`/`issues` у frontmatter), а наступний
- * `gen` автоматично доретраює такі доки (один раз на версію джерела — далі `retried:true`).
- *
- * Перед масовим прогоном — health-check omlx: memory-guard зайнятої 8GB машини
- * означає «відклади прогін», а не сотні хибних «✗» у звіті.
- */
+/** @see ./docs/docgen-files-batch.md */
 import { readFileSync, readdirSync, mkdirSync, writeFileSync, existsSync, statSync } from 'node:fs'
 import { basename, dirname, join, relative } from 'node:path'
 

package/rules/doc-files/js/docgen-judge-measure.mjs

@@ -1,21 +1,4 @@
-#!/usr/bin/env node
-/**
- * docgen-judge-measure.mjs — Q4 офлайн-вимірювач (spec 2026-06-14-docgen-judge-design).
- *
- * Міряє false-positive rate детермінованого `scoreDoc`: серед доків, що ПРОЙШЛИ
- * (score ≥ threshold), який % сильна хмарна модель-суддя класифікує як
- * `generic`/`inaccurate`. Це число вирішує, чи будувати рантайм-judge-гейт.
- *
- * Генерація: локальна (N_LOCAL_MIN_MODEL, omlx/* → прямий HTTP) — реальний пайплайн.
- * Суддя: openai-codex/gpt-5.4-mini (сильніша хмара, ніж генератор — інакше вимір беззмістовний).
- * Обидва — через існуючий `../../../lib/llm.mjs callLlm` (маршрутизація за префіксом).
- *
- * Кеш на диску (за хешем контенту) → повторні прогони не регенерують і не пересуджують.
- *
- * Usage:
- *   node docgen-judge-measure.mjs <file1> <file2> ...
- *   MEASURE_CACHE=/tmp/x N_CLOUD_MIN_MODEL=openai-codex/gpt-5.4 node docgen-judge-measure.mjs ...
- */
+/** @see ./docs/docgen-judge-measure.md */
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
 import { createHash } from 'node:crypto'
 import { join } from 'node:path'
@@ -39,10 +22,16 @@ Prefer "inaccurate" over "generic" if any claim is wrong. Respond with ONLY a JS
 
 const sha = s => createHash('sha256').update(s).digest('hex').slice(0, 16)
 
+/**
+ *
+ */
 function cacheGet(key) {
   const p = join(CACHE_DIR, key + '.json')
   return existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : null
 }
+/**
+ *
+ */
 function cacheSet(key, val) {
   if (!existsSync(CACHE_DIR)) mkdirSync(CACHE_DIR, { recursive: true })
   writeFileSync(join(CACHE_DIR, key + '.json'), JSON.stringify(val))
@@ -83,6 +72,9 @@ function judgeCached(src, doc) {
   return { ...v, cached: false }
 }
 
+/**
+ *
+ */
 function main() {
   const files = process.argv.slice(2).filter(f => !f.startsWith('--'))
   if (!files.length) {

package/rules/doc-files/js/docs/docgen-crc.md

@@ -3,7 +3,7 @@ type: JS Module
 title: docgen-crc.mjs
 resource: npm/rules/doc-files/js/docgen-crc.mjs
 docgen:
-  crc: 6baf999b
+  crc: cca0a79f
 ---
 
 Детермінований маркер актуальності файлових док: контрольна сума джерела у frontmatter плюс опційний degraded-маркер якості. Єдине джерело правди про «дока свіжа/застаріла/неякісна» для генерації, перевірок і хуків.

package/rules/doc-files/js/docs/docgen-extract-anchors.md

@@ -3,7 +3,7 @@ type: JS Module
 title: docgen-extract-anchors.mjs
 resource: npm/rules/doc-files/js/docgen-extract-anchors.mjs
 docgen:
-  crc: 49749e9c
+  crc: b675f159
   score: 80
 ---
 

package/rules/doc-files/js/docs/docgen-files-batch.md

@@ -3,7 +3,7 @@ type: JS Module
 title: docgen-files-batch.mjs
 resource: npm/rules/doc-files/js/docgen-files-batch.mjs
 docgen:
-  crc: 975d6cfa
+  crc: 18c96a58
   score: 95
 ---
 

package/rules/doc-files/js/docs/docgen-judge-measure.md

@@ -3,7 +3,7 @@ type: JS Module
 title: docgen-judge-measure.mjs
 resource: npm/rules/doc-files/js/docgen-judge-measure.mjs
 docgen:
-  crc: 7f72e520
+  crc: e6e19732
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---

package/rules/doc-files/js/docs/lint.md

@@ -3,7 +3,7 @@ type: JS Module
 title: lint.mjs
 resource: npm/rules/doc-files/js/lint.mjs
 docgen:
-  crc: fcdc1c2a
+  crc: ca055f8f
   score: 100
 ---
 

package/rules/doc-files/js/lint.mjs

@@ -1,19 +1,4 @@
-/**
- * Адаптер агрегатора `n-cursor lint` для правила doc-files (opportunistic LLM-fix
- * tier, спека docs/specs/2026-06-15-opportunistic-llm-fix-tier.md).
- *
- * Quick-фаза отримує список змінених файлів і мапить їх у пари в **обидва** боки:
- *  - змінене **джерело** (`.js/.mjs/.ts/.vue/.py/.rs`) → перевірка його доки `<dir>/docs/<stem>.md`;
- *  - змінена/видалена **дока** (`<dir>/docs/<stem>.md`) → перевірка відповідного джерела
- *    (той самий stem у каталозі над текою `docs`).
- * Ci-фаза (files === undefined) проганяє повний скан дерева.
- *
- * Детект — `missing` ∪ `crc-mismatch` (детермінований CRC, 0 LLM-токенів); degraded не блокує.
- * Поведінка за осями (правило має `meta.json: llmFix:true`):
- *  - `readOnly` (CI/hook): **лише детект** — нуль мутацій/LLM, exit 1 на stale (детермінований гейт);
- *  - fix-by-default + omlx **піднято**: opportunistic-генерація stale-доків → re-detect → 0 якщо полагоджено;
- *  - fix-by-default + omlx **недоступно**: fix пропущено (повідомлення) + exit 1 — гейт тримається, без false-green.
- */
+/** @see ./docs/lint.md */
 import { join, dirname, basename, extname } from 'node:path'
 import { existsSync, readdirSync } from 'node:fs'
 

package/rules/lint/js/docs/orchestrate.md

@@ -3,7 +3,7 @@ type: JS Module
 title: orchestrate.mjs
 resource: npm/rules/lint/js/orchestrate.mjs
 docgen:
-  crc: 0f1d717c
+  crc: 0ab5b22c
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---

package/rules/lint/js/orchestrate.mjs

@@ -1,18 +1,4 @@
-/**
- * Оркестратор `n-cursor lint` — дві ортогональні осі (spec 2026-06-14-lint-rule-consolidation
- * + компаньйон 2026-06-14-lint-orchestrator-fix-readonly-unification):
- *  - **scope** (`--full`): default = дельта vs origin (лише `per-file` правила);
- *    `--full` = весь репо (`per-file` ∪ `full` правила);
- *  - **behavior** (`--read-only`): default = fix; `--read-only` = лише детект без мутацій.
- *
- * Data-driven: сканує `rules/<id>/meta.json` за полем `lint` (`per-file`|`full`),
- * викликає `rules/<id>/js/lint.mjs` → `lint(files, cwd, { readOnly })`:
- *  - default scope: `files` = змінені відносно origin (`collectChangedFilesSince`);
- *  - `--full`:      `files = undefined` — весь проєкт.
- * Порядок правил — алфавітний. Fail-fast **лише в `--read-only`** (CI/детект): перший
- * ненульовий код спиняє. У fix-режимі (default) ненульовий код НЕ спиняє — проганяємо всі
- * правила й доходимо до кроку виправлення (конформність-драбина), повертаючи найгірший код.
- */
+/** @see ./docs/orchestrate.md */
 import { existsSync, readdirSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'

package/rules/text/lint/cspell-fix.mjs

@@ -14,6 +14,7 @@
  * Гейт: валідні слова після дописування у словник зникають; нерозкласифіковані та
  * typo лишаються → cspell повертає !=0 → exit 1 (людина доправляє одруки вручну).
  */
+import { env } from 'node:process'
 import { spawnSync } from 'node:child_process'
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
@@ -27,7 +28,7 @@ const UNKNOWN_WORD_RE = /Unknown word \(([^)]+)\)/u
 const MAX_CLASSIFY_WORDS = 80
 
 /** Локальна fix-модель (рішення: єдиний knob `N_LOCAL_MIN_MODEL`). */
-const fixModel = () => process.env.N_LOCAL_MIN_MODEL || ''
+const fixModel = () => env.N_LOCAL_MIN_MODEL || ''
 
 /**
  * Запускає `cspell .` із захопленням виводу.

package/rules/text/lint/docs/cspell-fix.md

@@ -3,24 +3,30 @@ type: JS Module
 title: cspell-fix.mjs
 resource: npm/rules/text/lint/cspell-fix.mjs
 docgen:
-  crc: b5585e0f
+  crc: 7b40e8f9
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 90
+  score: 95
+  issues: anchor-miss:meta.json,judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Модуль інтегрує `cspell` у ланцюжок `lint-text` для виявлення орфографічних помилок. У режимі з можливістю виправлення, процес відбувається шляхом: детект (захоплення виводу) $\rightarrow$ групування знахідок по файлах $\rightarrow$ per-file `omlx-фікс` справжніх помилок (`llmLintFix`) $\rightarrow$ re-detect. У read-only режимі виконується лише детект, що гарантує нуль мутацій. Валідні терміни omlx залишаються, їх ловить повторний `cspell` (далі — у словник `@nitra/cspell-dict`).
+## Огляд
+
+Цей модуль інтегрує cspell у ланцюжок lint-text для класифікації невідомих слів згідно зі схемою omlx. Він витягує невідомі слова, класифікує їх за допомогою LLM (detect $\rightarrow$ omlx-класифікація) та автоматично дописує валідні терміни до словника `.cspell.json`. Нерозкласифіковані та ймовірні одруки залишаються для ручного рев'ю. Процес є read-only, оскільки він лише класифікує знахідки, а не переписує файли.
 
 ## Поведінка
 
-groupFindingsByFile групує вивід `cspell` за файлами, виділяючи знахідки.
-runCspellText запускає `cspell` для виявлення орфографічних помилок, а при вимкненому режимі читання виконує автоматичне виправлення помилок за допомогою зовнішнього інструменту для файлів, що містять справжні помилки, і повторно перевіряє файли.
+unknownWords витягує унікальні невідомі слова з виводу cspell.
+appendWordsToDict дописує класифіковані валідні слова до файлу .cspell.json, оновлюючи словник.
+runCspellText запускає cspell, класифікує знахідки за допомогою LLM (якщо увімкнено) та повторно перевіряє код, повертаючи 0 при чистоті або 1 при знахідках.
 
 ## Публічний API
 
-groupFindingsByFile — збирає знайдені помилки cspell у групи за файлами.
-runCspellText — виконує перевірку тексту за правилами cspell, застосовуючи автоматичне виправлення від omlx.
+unknownWords — Збирає унікальні слова, які не були знайдені у словнику cspell.
+appendWordsToDict — Додає зібрані слова до файлу `.cspell.json#words` у відсортованому та унікальному вигляді для перегляду у Git.
+runCspellText — Виконує перевірку тексту за допомогою cspell, класифікуючи слова та оновлюючи словник за новою схемою.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Не звертається до мережі.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/scripts/lib/adr/docs/normalize-cli.md

@@ -3,26 +3,27 @@ type: JS Module
 title: normalize-cli.mjs
 resource: npm/scripts/lib/adr/normalize-cli.mjs
 docgen:
-  crc: ce2f13af
+  crc: 63a18347
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 90
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Цей файл є CLI-обгорткою для локального ADR-нормалізатора (`n-cursor adr-normalize-local`). Він використовується скриптом `.claude/hooks/normalize-decisions.sh` як локальний бекенд для обробки батчу чернеток та списку чистих ADR. Обгортка зчитує шляхи до чернеток та параметри з аргументів командного рядка та змінних середовища, а потім проганяє `normalizePipeline`. Результатом роботи є вивід JSON-контракту з операціями у stdout, який парситься зовнішнім скриптом. Прогрес відображається у stderr.
+## Огляд
+
+Цей файл є CLI-обгорткою для локального нормалізатора ADR. Він зчитує шляхи до чернеток (`--batch <file>`) та список чистих ADR (`--clean <file>`), використовуючи директорію ADR (`--adr-dir <dir>`) для резолву шляхів. Обгортка запускає `normalizePipeline`, яка генерує JSON-контракт у форматі `{ "operations": [...] }` та виводить його у stdout для подальшого парсингу bash-скриптом. Прогрес та помилки записуються у stderr. Поведінка нормалізатора може бути змінена через змінні середовища: `ADR_NORMALIZE_ALLOW_CLOUD` контролює можливість хмарної ескалації, а `ADR_NORMALIZE_VOTES` визначає кількість голосів self-consistency для чистих ADR.
 
 ## Поведінка
 
-1. `runAdrNormalizeLocalCli` парсить вхідні аргументи для визначення шляху до чернеток батчу, списку чистих ADR та каталогу ADR.
-2. Якщо не надано файл батчу, `runAdrNormalizeLocalCli` виводить повідомлення про використання та завершує роботу з кодом помилки.
-3. `runAdrNormalizeLocalCli` зчитує шляхи до чернеток батчу з вказаного файлу.
-4. Для кожної чернетки `runAdrNormalizeLocalCli` зчитує вміст файлу, резолвячи шлях відносно каталогу ADR, і створює об'єкт чернетки.
-5. `runAdrNormalizeLocalCli` зчитує список назв чистих ADR з файлу, якщо він наданий.
-6. `runAdrNormalizeLocalCli` зчитує значення змінних середовища `ADR_NORMALIZE_ALLOW_CLOUD` та `ADR_NORMALIZE_VOTES` для визначення параметрів нормалізації.
-7. `runAdrNormalizeLocalCli` викликає логіку нормалізації, передаючи чернетки, список чистих ADR та параметри, при цьому прогрес виводиться у stderr.
-8. `runAdrNormalizeLocalCli` виводить кількість операцій та статистику нормалізації у stderr.
-9. `runAdrNormalizeLocalCli` виводить деталі рішень нормалізації у stderr.
-10. `runAdrNormalizeLocalCli` друкує JSON-об'єкт, що містить операції, у stdout.
-11. `runAdrNormalizeLocalCli` завершує роботу з кодом успіху.
+1. Викликати runAdrNormalizeLocalCli.
+2. Зчитувати список шляхів до чернеток батчу з файлу, вказаного через аргумент `--batch`.
+3. Зчитувати список імен чистих ADR (кандидатів до злиття) з файлу, вказаного через аргумент `--clean`, якщо він наданий.
+4. Визначати директорію ADR, використовуючи аргумент `--adr-dir` або за замовчуванням `cwd/docs/adr`.
+5. Зчитувати вміст кожної чернетки батчу, резолвя шляхи відносно `--adr-dir`.
+6. Зчитувати значення змінних середовища `ADR_NORMALIZE_ALLOW_CLOUD` та `ADR_NORMALIZE_VOTES`.
+7. Викликати внутрішній механізм нормалізації, передаючи зібрані чернетки, список чистих ADR, та конфігурацію, отриману з змінних середовища.
+8. Виводити інформацію про прогрес та статистику в stderr.
+9. Виводити JSON-об'єкт, що містить операції, у stdout.
 
 ## Публічний API
 
@@ -30,5 +31,4 @@ runAdrNormalizeLocalCli — запускає субкоманду, виводя
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Не звертається до мережі.
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/adr/normalize-cli.mjs

@@ -16,6 +16,7 @@
  *   ADR_NORMALIZE_ALLOW_CLOUD=1  дозволити хмарну ескалацію tier-каскаду (default off)
  *   ADR_NORMALIZE_VOTES=N        голосів self-consistency для clean-ребер (default 2)
  */
+import { env } from 'node:process'
 import { readFileSync } from 'node:fs'
 import { basename, isAbsolute, join } from 'node:path'
 import { normalizePipeline } from './normalize-pipeline.mjs'
@@ -57,8 +58,8 @@ export function runAdrNormalizeLocalCli(argv) {
   })
   const cleanList = args.clean ? readLines(args.clean).map((c) => basename(c)) : []
 
-  const allowCloud = process.env.ADR_NORMALIZE_ALLOW_CLOUD === '1'
-  const votes = Number(process.env.ADR_NORMALIZE_VOTES) || 2
+  const allowCloud = env.ADR_NORMALIZE_ALLOW_CLOUD === '1'
+  const votes = Number(env.ADR_NORMALIZE_VOTES) || 2
 
   const { operations, stats, trace } = normalizePipeline(drafts, cleanList, {
     allowCloud,

package/skills/doc-aggregate/js/docgen-ignore.mjs

@@ -1,9 +1,2 @@
-/**
- * Re-export спільного списку ignore-глобів із правила doc-files.
- *
- * Канонічне джерело — `npm/rules/doc-files/js/docgen-ignore.mjs`: скіл doc-aggregate
- * і правило doc-files мусять бачити однакове дерево кодових файлів, інакше агрегат
- * посилатиметься на файли без док (або навпаки). Залежність спрямована
- * doc-aggregate → doc-files за ADR про розбиття docgen.
- */
+/** @see ./docs/docgen-ignore.md */
 export * from '../../../rules/doc-files/js/docgen-ignore.mjs'

package/skills/doc-aggregate/js/docs/docgen-ignore.md

@@ -3,7 +3,7 @@ type: JS Module
 title: docgen-ignore.mjs
 resource: npm/skills/doc-aggregate/js/docgen-ignore.mjs
 docgen:
-  crc: 5faaffd0
+  crc: 3b579230
 ---
 
 Re-export спільного списку ignore-глобів зі скіла doc-files: обидва скіли документації (пофайлові доки й агрегати) мусять бачити однакове дерево кодових файлів, інакше агрегат посилатиметься на файли без док або навпаки.