@7n/rules 1.0.0

package/rules/ci4/vscode_extensions/docs/index.md

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

package/rules/ci4/vscode_extensions/fix-vscode_extensions.mjs

@@ -0,0 +1 @@
+export { patterns } from '../../../scripts/lib/fix/vscode-ext-add.mjs'

package/rules/ci4/vscode_extensions/template/extensions.json.snippet.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["arr.marksman"]
+}

package/rules/ci4/vscode_extensions/vscode_extensions.mdc

@@ -0,0 +1,9 @@
+## Rego-gate: обовʼязкові розширення VSCode
+
+Rego-пакет: `ci4.vscode_extensions`
+
+Цільовий файл: `.vscode/extensions.json`
+
+Перевіряє, що кожен запис з `data.template.snippet.recommendations` присутній у `input.recommendations`. Канонічний шаблон надходить через `--data` у conftest: [extensions.json.snippet.json](./template/extensions.json.snippet.json)
+
+Додаткові розширення в масиві дозволені — deny лише на відсутність обовʼязкових.

package/rules/ci4/vscode_extensions/vscode_extensions.rego

@@ -0,0 +1,12 @@
+# Перевірка `.vscode/extensions.json` для ci4 (ci4.mdc).
+#
+# Канон надходить через --data: { "template": { "snippet": ... } }
+package ci4.vscode_extensions
+
+import rego.v1
+
+deny contains msg if {
+	some rec in data.template.snippet.recommendations
+	not rec in {r | some r in object.get(input, "recommendations", [])}
+	msg := sprintf(".vscode/extensions.json: recommendations має містити %q (ci4.mdc)", [rec])
+}

package/rules/doc-files/check/concern.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "lint": {
+    "scope": "per-file",
+    "glob": ["**/*.{js,mjs,ts,vue,py}"]
+  }
+}

package/rules/doc-files/check/docs/fix-check.md

@@ -0,0 +1,28 @@
+---
+type: JS Module
+title: fix-check.mjs
+resource: npm/rules/doc-files/check/fix-check.mjs
+docgen:
+  crc: 9a1d9107
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min
+  score: 100
+  issues: judge:inaccurate:0.97
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл реалізує детерміноване оновлення CRC-штампів у документації, що спрацьовує після виявлення розбіжності `crc-mismatch`. Механізм автоматично оновлює метадані документації, щоб фіксувати відповідність між зміненими джерелами та вже існуючим, незміненим контентом. Це забезпечує точну валідацію метаданих системи.
+
+## Поведінка
+
+1.  Перевіряється наявність вказівок на розбіжність CRC у документації.
+2.  Для документації, яка відповідає критеріям розбіжності CRC, але є цілісною, виконується детерміноване оновлення CRC в метаданих.
+3.  Операція включає аналіз якості документації, ініційована з використанням відповідних моделей.
+4.  Оновлена документація записується у файл, ідентифікований шляхом до документації, що відповідає розбіжності.
+5.  Повертається булеве значення, що вказує на те, чи було внесено зміни у документацію.
+
+## Гарантії поведінки
+
+- (специфічних машинно-виведених гарантій немає)

package/rules/doc-files/check/docs/fix-worker.md

@@ -0,0 +1,28 @@
+---
+type: JS Module
+title: fix-worker.mjs
+resource: npm/rules/doc-files/check/fix-worker.mjs
+docgen:
+  crc: 7611b2f9
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+---
+
+## Огляд
+
+Файл забезпечує генерацію застарілих або відсутніх файлових доків за допомогою docgen-pipeline (локальна/хмарна модель) через функцію fixWorker. Кожна згенерована дока реєструється як durable-write (самодостатній кінцевий стан зі свіжим CRC), тому rollback провального rung-а її не стирає, а великий беклог сходиться за кілька прогонів (issue nitra/cursor#16). Видалення сирітських доків лишається під звичайним rollback.
+
+## Поведінка
+
+1. Викликається `fixWorker`.
+2. Скануються файли для визначення застарілих документів (рукописні доки без docgen-frontmatter — не цілі).
+3. Якщо знайдені застарілі документи, кожна цільова дока реєструється durable через `ctx.recordDurableWrite` (fallback — `ctx.recordWrite`), а потім запускається генерація батчу через `runGenerationBatch`.
+4. Батч отримує м'який дедлайн — 80% від `ctx.timeoutMs` рунга: генерація сама зупиняється до backstop-таймауту, повертає частковий прогрес штатно й не лишає фонового батчу поверх наступного rung-а.
+5. Фільтруються порушення, що стосуються сирітських документів (вихідні файли видалені); pre-image кожного реєструється у `ctx.recordWrite`.
+6. Викликається `purgeOrphanedDocs` для видалення сирітських документів.
+7. Повертається результат зі списком зачеплених файлів.
+
+## Гарантії поведінки
+
+- Кожна записана дока — валідний фінальний стан (свіжий CRC; degraded теж валідна) — часткова робота не втрачається при таймауті/провалі rung-а.

package/rules/doc-files/check/docs/main.md

@@ -0,0 +1,32 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/doc-files/check/main.mjs
+docgen:
+  crc: 715702d3
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Lint-детектор concern-а `doc-files/check`: виявляє застарілі файлові доки (CRC-mismatch, відсутність, деградація) та «сирітські» доки, чиє джерело видалено. Виключно read-only детект — генерація й очистка живуть у `fix-worker.mjs` (docgen), не тут.
+
+## Поведінка
+
+1. `lint(ctx)`: у delta-режимі (`ctx.files` задано) змінені шляхи зводяться до множини вихідних кодових файлів — для зміненої `docs/*.md`-доки reverse-map-ом знаходиться її джерело у батьківській теці; без `ctx.files` — повний скан репо.
+2. Для кожного джерела перевіряється актуальність його доки (`describeFile`/`scanForDocFiles`); застаріла/відсутня дока → порушення з причиною (`reason`) і шляхом джерела.
+3. Окремо скануються «сирітські» доки (`scanOrphanedDocs`) — `docs/*.md`, чиє джерело видалено; кожна — порушення `orphaned-doc`.
+4. Повертається `LintResult` зі списком порушень — без жодних мутацій.
+
+## Публічний API
+
+collectStale — перелік застарілих доків: для `files` (delta) або всього репо (undefined);
+lint — детектор застарілих і сирітських файлових доків, повертає `{ violations }`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Fail-safe: помилка читання теки джерела дає `null`-reverse-map (джерело пропускається), не виняток.

package/rules/doc-files/check/fix-check.mjs

@@ -0,0 +1,45 @@
+/**
+ * T0-autofix doc-files/check — детермінований CRC-stamp для `crc-mismatch` доків
+ * (джерело змінилось, але дока актуальна → лише оновити CRC у frontmatter, без LLM).
+ * `missing`/`degraded`/`orphaned-doc` лишаються worker-у (генерація/очистка).
+ *
+ * Unified lint surface: structured violations; запускається ПЕРЕД fix-worker-ом.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+
+/** @type {import('../../../scripts/lib/lint-surface/types.mjs').T0Pattern[]} */
+export const patterns = [
+  {
+    id: 'doc-files-stamp-crc',
+    test: violations => violations.some(v => v.reason === 'crc-mismatch'),
+    apply: async (violations, ctx) => {
+      const { scanForDocFiles } = await import('../docgen-scan/main.mjs')
+      const { crc32, readDocModel, readDocQuality, stampDoc } = await import('../docgen-crc/main.mjs')
+      const { cwd } = ctx
+      /** @type {string[]} */
+      const touchedFiles = []
+
+      const staleFiles = scanForDocFiles(cwd).filter(f => f.stale && f.reason === 'crc-mismatch')
+      for (const file of staleFiles) {
+        const sourceAbs = join(cwd, file.sourcePath)
+        const docAbs = join(cwd, file.docPath)
+        if (!existsSync(docAbs)) continue // missing → worker, не T0
+        const { score, issues, judgeModel } = readDocQuality(docAbs)
+        const quality = score === null ? null : { score, issues, judge: judgeModel ? { model: judgeModel } : undefined }
+        const crc = crc32(readFileSync(sourceAbs))
+        ctx.recordWrite?.(docAbs)
+        mkdirSync(dirname(docAbs), { recursive: true })
+        writeFileSync(
+          docAbs,
+          stampDoc(readFileSync(docAbs, 'utf8'), file.sourcePath, crc, quality, readDocModel(docAbs))
+        )
+        touchedFiles.push(docAbs)
+      }
+
+      return touchedFiles.length > 0
+        ? { touchedFiles, message: `stamped CRC: ${touchedFiles.length} доки(ів)` }
+        : { touchedFiles: [] }
+    }
+  }
+]

package/rules/doc-files/check/fix-worker.mjs

@@ -0,0 +1,56 @@
+/**
+ * fix-worker doc-files/check (unified lint surface): генерує застарілі/відсутні файлові
+ * доки локальною/хмарною моделлю (docgen-pipeline) і чистить сирітські доки.
+ *
+ * Один attempt одного rung-а — tier/model беруться з ctx, success визначає canonical
+ * re-detect runner-а. Доки реєструються durable (`ctx.recordDurableWrite`): кожна
+ * записана дока — самодостатній кінцевий стан зі свіжим CRC (degraded теж валідна),
+ * тож rollback провального rung-а її не стирає, і великий беклог сходиться
+ * крок за кроком за кілька прогонів. Видалення сирітських док лишається під
+ * звичайним rollback (ctx.recordWrite).
+ * @typedef {import('../../../scripts/lib/lint-surface/types.mjs').FixWorkerFn} FixWorkerFn
+ */
+import { join } from 'node:path'
+
+/** Частка ctx.timeoutMs, після якої батч не стартує наступний файл (запас до backstop ×1.25). */
+const DEADLINE_FRACTION = 0.8
+
+/** @type {FixWorkerFn} */
+export async function fixWorker(violations, ctx) {
+  const { cwd } = ctx
+  const { scanForDocFiles } = await import('../docgen-scan/main.mjs')
+  const { runGenerationBatch, purgeOrphanedDocs } = await import('../docgen-files-batch/main.mjs')
+
+  /** @type {string[]} */
+  const touchedFiles = []
+  const recordDoc = ctx.recordDurableWrite ?? ctx.recordWrite
+
+  // Re-scan дає повні target-обʼєкти {sourcePath, docPath, reason, …}, що їх потребує
+  // runGenerationBatch (violation несе лише file+docPath).
+  const stale = scanForDocFiles(cwd).filter(f => f.stale)
+  if (stale.length > 0) {
+    for (const f of stale) {
+      const docAbs = join(cwd, f.docPath)
+      recordDoc?.(docAbs)
+      touchedFiles.push(docAbs)
+    }
+    // Deadline: батч сам зупиняється до backstop-таймауту рунга (fix timeout ×1.25) —
+    // повертає часткову роботу штатно, замість фонового батчу-зомбі поверх наступного rung-а.
+    const deadlineAt = ctx.timeoutMs ? Date.now() + Math.round(ctx.timeoutMs * DEADLINE_FRACTION) : null
+    await runGenerationBatch(stale, cwd, {
+      headline: `📄 doc-files: генерація ${stale.length} доки(ів)`,
+      model: ctx.model,
+      tier: ctx.tier,
+      deadlineAt
+    })
+  }
+
+  // Сирітські доки (source видалено) — записати pre-image для rollback, тоді purge.
+  const orphans = violations.filter(v => v.reason === 'orphaned-doc')
+  if (orphans.length > 0) {
+    for (const v of orphans) if (v.file) ctx.recordWrite?.(join(cwd, v.file))
+    purgeOrphanedDocs(cwd)
+  }
+
+  return { touchedFiles }
+}

package/rules/doc-files/check/main.mjs

@@ -0,0 +1,99 @@
+/**
+ * lint-поверхня doc-files: детект застарілих файлових документацій (per-file, з reverse-mapом).
+ */
+import { join, dirname, basename, extname } from 'node:path'
+import { existsSync, readdirSync } from 'node:fs'
+
+import { describeFile, isDocCandidate, isSourceFile, scanForDocFiles, scanOrphanedDocs } from '../docgen-scan/main.mjs'
+
+const DOC_MD_RE = /(?:^|\/)docs\/[^/]+\.md$/u
+
+/**
+ * Знаходить вихідний файл, якому належить доку.
+ * @param {string} cwd робочий каталог
+ * @param {string} docRel відносний шлях до .md-доки
+ * @returns {string|null} відносний шлях джерела або null
+ */
+function sourceForDoc(cwd, docRel) {
+  const docsDir = dirname(docRel)
+  const srcDir = dirname(docsDir)
+  const stem = basename(docRel, '.md')
+  let entries
+  try {
+    entries = readdirSync(join(cwd, srcDir), { withFileTypes: true })
+  } catch {
+    return null
+  }
+  for (const e of entries) {
+    if (!e.isFile() || !isSourceFile(e.name)) continue
+    if (basename(e.name, extname(e.name)) !== stem) continue
+    const rel = srcDir === '.' ? e.name : `${srcDir}/${e.name}`
+    if (isDocCandidate(cwd, rel)) return rel
+  }
+  return null
+}
+
+/**
+ * Зводить перелік змінених файлів до множини вихідних кодових файлів.
+ * @param {string[]} files змінені шляхи (джерела або .md-доки)
+ * @param {string} cwd робочий каталог
+ * @returns {string[]} відносні шляхи джерел
+ */
+function sourcesFromChanged(files, cwd) {
+  const out = new Set()
+  for (const raw of files) {
+    const rel = raw.split('\\').join('/')
+    if (DOC_MD_RE.test(rel)) {
+      const src = sourceForDoc(cwd, rel)
+      if (src) out.add(src)
+    } else if (isDocCandidate(cwd, rel) && existsSync(join(cwd, rel))) {
+      out.add(rel)
+    }
+  }
+  return [...out]
+}
+
+/**
+ * @param {string[]|undefined} files змінені шляхи; undefined → повний скан
+ * @param {string} cwd робочий каталог
+ * @returns {Array<{ sourcePath: string, docPath?: string, reason: string }>} застарілі доки
+ */
+export function collectStale(files, cwd) {
+  if (files === undefined) return scanForDocFiles(cwd).filter(f => f.stale)
+  const sources = sourcesFromChanged(files, cwd)
+  return sources.map(src => describeFile(cwd, src)).filter(f => f.stale)
+}
+
+/**
+ * Detector doc-files: застарілі (CRC-mismatch/missing/degraded) і сирітські файлові доки.
+ * Read-only — генерація/очистка у fix-worker.mjs (docgen), не тут.
+ * @param {import('../../../scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінту
+ * @returns {import('../../../scripts/lib/lint-surface/types.mjs').LintResult} перелік порушень
+ */
+export function lint(ctx) {
+  const { cwd, files } = ctx
+  /** @type {import('../../../scripts/lib/lint-surface/types.mjs').LintViolation[]} */
+  const violations = []
+
+  for (const f of collectStale(files, cwd)) {
+    violations.push(
+      /** @type {Partial<import('../../../scripts/lib/lint-surface/types.mjs').LintViolation>} */ ({
+        reason: f.reason || 'stale',
+        message: `документація застаріла/відсутня для ${f.sourcePath} (${f.reason})`,
+        file: f.sourcePath,
+        data: f.docPath ? { docPath: f.docPath } : undefined
+      })
+    )
+  }
+  for (const orphan of scanOrphanedDocs(cwd)) {
+    violations.push(
+      /** @type {Partial<import('../../../scripts/lib/lint-surface/types.mjs').LintViolation>} */ ({
+        reason: 'orphaned-doc',
+        message: `сирітський док (source видалено): ${orphan}`,
+        file: orphan
+      })
+    )
+  }
+
+  return { violations }
+}

package/rules/doc-files/docgen-crc/concern.json

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

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

@@ -0,0 +1,46 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/doc-files/docgen-crc/main.mjs
+docgen:
+  crc: bc1835c9
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Модуль забезпечує керування якістю, метаданими та актуальністю документації. Він дозволяє встановлювати мінімальний поріг якості за допомогою `QUALITY_THRESHOLD`, обчислювати та зчитувати контрольні суми (CRC32) за допомогою `crc32` та `readDocCrc`, а також парсити та генерувати метадані документації за допомогою `parseDocFrontmatter` та `buildDocFrontmatter`.
+
+## Поведінка
+
+Поведінка:
+QUALITY_THRESHOLD — Встановлює поріг якості документації, нижче якого доки вважаються неякісними.
+crc32 — Обчислює та повертає CRC32 вмісту у вигляді 8-символьного шестнадцяткового рядка.
+parseDocFrontmatter — Розбирає вміст markdown-файлу, виділяючи метадані з блоку frontmatter та повертаючи тіло документа.
+buildDocFrontmatter — Формує YAML-блок frontmatter, сумісний з OKF, для посилання на джерело та його метаданих.
+stampDoc — Генерує повний markdown-документ, вставляючи новостворений frontmatter у тіло документа.
+readDocCrc — Зчитує та повертає CRC32, збережений у frontmatter markdown-документа.
+readDocQuality — Зчитує зі frontmatter markdown-документа оцінку якості та пов'язані з нею помилки.
+readDocModel — Зчитує зі frontmatter markdown-документа ідентифікатор моделі, яка створила документ.
+readDocTier — Зчитує зі frontmatter markdown-документа рівень моделі-генератора.
+staleness — Визначає, чи застарілий markdown-документ порівняно з його вихідним джерелом за допомогою CRC32.
+
+## Публічний API
+
+QUALITY_THRESHOLD — визначає нижню межу якості документа; оцінки нижче цієї межі вважаються неякісними.
+crc32 — генерує хеш вмісту документа у 8-символьтному hex-форматі, використовуючи нативний модуль `node:zlib.crc32`.
+parseDocFrontmatter — витягує метадані з початку документа. Якщо метаданих немає, повертає порожні дані та вхідний текст.
+buildDocFrontmatter — створює блок метаданих, сумісний зі стандартом OKF. Він містить основні поля OKF та вкладений блок `docgen:` з інформацією про CRC, модель та якість.
+stampDoc — додає інформацію про створення або оновлення документа (наприклад, CRC та метки) до самого вмісту.
+readDocCrc — зчитує хеш документа з метаданих. Повертає `null`, якщо метадані відсутні або хеш не знайдено.
+readDocQuality — зчитує оцінку якості документа з його метаданих.
+readDocModel — зчитує назву моделі, яка генерувала документ, із метаданих. Повертає `null`, якщо це поле не визначено.
+readDocTier — зчитує рівень (tier) моделі-генератора з метаданих. Повертає `null`, якщо поле відсутнє.
+staleness — визначає, чи є документ актуальним порівняно з його джерелом. Позначає як `missing` (якщо документа немає), `crc-mismatch` (якщо хеш у документа не збігається з хешем джерела) або "свіжий" (інакше).
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -0,0 +1,207 @@
+/** @see ./docs/docgen-crc.md */
+import { existsSync, readFileSync } from 'node:fs'
+import { basename, extname } from 'node:path'
+import { crc32 as zlibCrc32 } from 'node:zlib'
+import { env } from 'node:process'
+
+/** Поріг degraded: дока зі `score` нижче вважається неякісною. */
+export const QUALITY_THRESHOLD = Number(env.N_CURSOR_DOC_FILES_THRESHOLD ?? 70) || 70
+
+/**
+ * CRC32 вмісту у hex (8 символів, з провідними нулями). Делегує у нативний
+ * `node:zlib.crc32` — без ручної бітової арифметики.
+ * @param {string|Buffer} input текст або байти джерела
+ * @returns {string} CRC32 у hex
+ */
+export function crc32(input) {
+  const buf = typeof input === 'string' ? Buffer.from(input, 'utf8') : input
+  return zlibCrc32(buf).toString(16).padStart(8, '0')
+}
+
+/** Провідний YAML-frontmatter-блок `---\n…\n---`. */
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/u
+const RESOURCE_RE = /^resource:[ \t]+(\S.*)$/mu
+const CRC_RE = /^[ \t]{0,8}crc:[ \t]{0,8}(.+)$/mu
+const MODEL_RE = /^[ \t]{0,8}model:[ \t]{0,8}(.+)$/mu
+const TIER_RE = /^[ \t]{0,8}tier:[ \t]{0,8}(.+)$/mu
+const SCORE_RE = /^[ \t]{0,8}score:[ \t]{0,8}(\d+)$/mu
+const ISSUES_RE = /^[ \t]{0,8}issues:[ \t]{0,8}(.+)$/mu
+const JUDGE_MODEL_RE = /^[ \t]{0,8}judgeModel:[ \t]{0,8}(.+)$/mu
+const LEADING_NEWLINES_RE = /^\n+/u
+const ISSUE_CODE_TAIL_RE = /[,:]$/u
+
+/**
+ * Парсить frontmatter файлової доки. Без блоку — `data:null` і `body` дорівнює входу.
+ * Поля `model`/`score`/`issues` опційні (back-compat зі старими доками): без них —
+ * `model:null`, `score:null`, `issues:[]`.
+ * @param {string} md вміст md-файлу
+ * @returns {{ data: { source: string|null, crc: string|null, model: string|null, tier: string|null, score: number|null, issues: string[], judgeModel: string|null }|null, body: string }} метадані + тіло без frontmatter
+ */
+export function parseDocFrontmatter(md) {
+  const match = md.match(FRONTMATTER_RE)
+  if (!match) return { data: null, body: md }
+  const block = match[1]
+  const scoreRaw = block.match(SCORE_RE)?.[1]
+  const issuesRaw = block.match(ISSUES_RE)?.[1]
+  const source = block.match(RESOURCE_RE)?.[1].trim() ?? null
+  return {
+    data: {
+      source,
+      crc: block.match(CRC_RE)?.[1].trim() ?? null,
+      model: block.match(MODEL_RE)?.[1].trim() ?? null,
+      tier: block.match(TIER_RE)?.[1].trim() ?? null,
+      score: scoreRaw === undefined ? null : Number(scoreRaw),
+      issues: issuesRaw
+        ? issuesRaw
+            .split(',')
+            .map(s => s.trim())
+            .filter(Boolean)
+        : [],
+      judgeModel: block.match(JUDGE_MODEL_RE)?.[1].trim() ?? null
+    },
+    body: md.slice(match[0].length)
+  }
+}
+
+/** Максимум кодів issues у frontmatter — це маркер, а не повний лог. */
+const MAX_ISSUE_CODES = 8
+
+/** OKF type для розширення файлу. */
+const EXT_TYPES = {
+  '.js': 'JS Module',
+  '.mjs': 'JS Module',
+  '.cjs': 'JS Module',
+  '.ts': 'TS Module',
+  '.vue': 'Vue Component',
+  '.py': 'Python Module',
+  '.rs': 'Rust Module'
+}
+
+/**
+ * OKF `type` для файлу-джерела за розширенням.
+ * @param {string} sourcePath відносний шлях джерела
+ * @returns {string} тип концепту
+ */
+function typeForSource(sourcePath) {
+  return EXT_TYPES[extname(sourcePath).toLowerCase()] ?? 'Source File'
+}
+
+/**
+ * Нормалізує issues до YAML-безпечних кодів: бере фрагмент до першого пробілу
+ * (зрізає людиночитні хвости помилок), відкидає порожні, обмежує кількість.
+ * @param {string[]} issues сирі issue-рядки від скорера
+ * @returns {string[]} коди без пробілів
+ */
+function issueCodes(issues) {
+  return issues
+    .map(i => String(i).split(' ', 1)[0].replace(ISSUE_CODE_TAIL_RE, ''))
+    .filter(Boolean)
+    .slice(0, MAX_ISSUE_CODES)
+}
+
+/**
+ * Будує OKF-сумісний frontmatter-блок: OKF-поля верхнього рівня + вкладений `docgen:`
+ * з CRC/model/quality. OKF-поля виводяться першими, щоб будь-який OKF-парсер міг їх
+ * читати незалежно від `docgen:`-простору назв.
+ * @param {string} source відносний шлях джерела
+ * @param {string} crc CRC32 джерела у hex
+ * @param {{ score: number, issues?: string[], judge?: {model?: string} }|null} [quality] det-оцінка доки; null — без полів якості
+ * @param {string|null} [model] повний id моделі-генератора; null — без поля `model`
+ * @param {string|null} [tier] tier моделі-генератора (`local-min`, `cloud-avg` тощо); null — без поля `tier`
+ * @returns {string} OKF-сумісний YAML frontmatter
+ */
+export function buildDocFrontmatter(source, crc, quality = null, model = null, tier = null) {
+  const okfLines = [`type: ${typeForSource(source)}`, `title: ${basename(source)}`, `resource: ${source}`]
+
+  // docgen namespace: лише CRC-механіка і quality (source перенесено у resource)
+  const docgenLines = [`crc: ${crc}`]
+  if (model) docgenLines.push(`model: ${model}`)
+  if (tier) docgenLines.push(`tier: ${tier}`)
+  if (quality && typeof quality.score === 'number') {
+    docgenLines.push(`score: ${quality.score}`)
+    const codes = issueCodes(quality.issues ?? [])
+    if (codes.length > 0) docgenLines.push(`issues: ${codes.join(',')}`)
+    if (quality.judge && quality.judge.model) docgenLines.push(`judgeModel: ${quality.judge.model}`)
+  }
+  const indented = docgenLines.map(l => '  ' + l).join('\n')
+  return `---\n${okfLines.join('\n')}\ndocgen:\n${indented}\n---\n`
+}
+
+const LEADING_H1_RE = /^# [^\n]*\n+/u
+
+/**
+ * (Пере)штампує frontmatter у md-доку: знімає наявний блок і додає свіжий.
+ * @param {string} md тіло доки (з frontmatter або без)
+ * @param {string} source відносний шлях джерела
+ * @param {string} crc CRC32 джерела у hex
+ * @param {{ score: number, issues?: string[], judge?: {model?: string} }|null} [quality] det-оцінка доки (+ опц. `judge.model` хмарного судді)
+ * @param {string|null} [model] повний id моделі-генератора; null — без поля `model`
+ * @param {string|null} [tier] тир моделі-генератора; null — без поля `tier`
+ * @returns {string} md зі свіжим frontmatter
+ */
+export function stampDoc(md, source, crc, quality = null, model = null, tier = null) {
+  const { body } = parseDocFrontmatter(md)
+  const cleanBody = body.replace(LEADING_NEWLINES_RE, '').replace(LEADING_H1_RE, '')
+  return `${buildDocFrontmatter(source, crc, quality, model, tier)}\n${cleanBody}`
+}
+
+/**
+ * CRC, збережений у frontmatter доки; `null` — доки немає або CRC відсутній.
+ * @param {string} docAbsPath абсолютний шлях md-доки
+ * @returns {string|null} CRC32 з frontmatter або null
+ */
+export function readDocCrc(docAbsPath) {
+  if (!existsSync(docAbsPath)) return null
+  return parseDocFrontmatter(readFileSync(docAbsPath, 'utf8')).data?.crc ?? null
+}
+
+/**
+ * Якість, збережена у frontmatter доки.
+ * @param {string} docAbsPath абсолютний шлях md-доки
+ * @returns {{ score: number|null, issues: string[], judgeModel: string|null }} `score:null` — доки немає або поле відсутнє; `judgeModel` — хмарна модель-суддя, що позначила док (або null)
+ */
+export function readDocQuality(docAbsPath) {
+  if (!existsSync(docAbsPath)) return { score: null, issues: [], judgeModel: null }
+  const data = parseDocFrontmatter(readFileSync(docAbsPath, 'utf8')).data
+  return {
+    score: data?.score ?? null,
+    issues: data?.issues ?? [],
+    judgeModel: data?.judgeModel ?? null
+  }
+}
+
+/**
+ * Модель-генератор, збережена у frontmatter доки; `null` — доки немає або поле відсутнє
+ * (старі доки до введення `model`).
+ * @param {string} docAbsPath абсолютний шлях md-доки
+ * @returns {string|null} повний id моделі або null
+ */
+export function readDocModel(docAbsPath) {
+  if (!existsSync(docAbsPath)) return null
+  return parseDocFrontmatter(readFileSync(docAbsPath, 'utf8')).data?.model ?? null
+}
+
+/**
+ * Tier моделі-генератора зі frontmatter доки; `null` — доки немає або поле відсутнє.
+ * @param {string} docAbsPath абсолютний шлях md-доки
+ * @returns {string|null} tier моделі з frontmatter або null
+ */
+export function readDocTier(docAbsPath) {
+  if (!existsSync(docAbsPath)) return null
+  return parseDocFrontmatter(readFileSync(docAbsPath, 'utf8')).data?.tier ?? null
+}
+
+/**
+ * Стан застарілості доки відносно її джерела.
+ * `missing` — доки немає; `crc-mismatch` — CRC джерела ≠ CRC у доці; інакше свіжа.
+ * @param {string} sourceAbsPath абсолютний шлях джерела
+ * @param {string} docAbsPath абсолютний шлях md-доки
+ * @returns {{ stale: boolean, reason: 'missing'|'crc-mismatch'|null }} стан застарілості
+ */
+export function staleness(sourceAbsPath, docAbsPath) {
+  const docCrc = readDocCrc(docAbsPath)
+  if (docCrc === null) return { stale: true, reason: 'missing' }
+  const srcCrc = crc32(readFileSync(sourceAbsPath))
+  if (srcCrc !== docCrc) return { stale: true, reason: 'crc-mismatch' }
+  return { stale: false, reason: null }
+}

package/rules/doc-files/docgen-extract/concern.json

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

package/rules/doc-files/docgen-extract/docs/main.md

@@ -0,0 +1,38 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/doc-files/docgen-extract/main.mjs
+docgen:
+  crc: 39c43eb9
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Екстрагує факти за допомогою функції `extractFacts`, звертаючись до мережі та використовуючи кешування в межах одного прогону. При цьому ігнорує каталоги, такі як `.github`, `.git`, `node_modules`, `base/`, `ua/` та `.firebase`.
+
+## Поведінка
+
+1. Аналізує вміст коду для створення детального набору фактів про файл.
+2. Визначає словник і визначає, чи є код написаний на JavaScript, TypeScript або TypeScript (ESM).
+3. Витягує загальний опис файлу, якщо він присутній у верхньому блоці коментарів.
+4. Визначає всі функції, які є публічно доступними (експортованими), разом із їхніми описами та параметрами.
+5. Класифікує імпорти на внутрішні, сторонні (npm) та вбудовані (stdlib).
+6. Визначає, чи є код:
+   - Стійким до винятків (catchesErrors).
+   - Здатним працювати без доступу до мережі (readOnly).
+   - Використовуючи механізми кешування (caches).
+   - Згодом повертаючи хибні значення у випадку помилки (returnsFalsyOnFail).
+7. Ігнорує шляхи, що відповідають шаблонам: .github, .git, node_modules, base/, ua/, .firebase.
+
+## Публічний API
+
+extractFacts — витягує з коду файлу список значущих тверджень (фактів).
+
+## Гарантії поведінки
+
+- Кешує результати в межах одного прогону.
+- Свідомо пропускає шляхи: `.github`, `.git`, `node_modules`, `base/`, `ua/`, `.firebase`.