@7n/rules 1.0.0

package/rules/rust/toolchain_cache/main.mjs

@@ -0,0 +1,177 @@
+/**
+ * @see ./docs/main.md
+ *
+ * Read-only detector: у кожному `.github/workflows/*.yml` кожен job, що ставить
+ * Rust toolchain через `dtolnay/rust-toolchain@stable`, повинен мати
+ * `Swatinem/rust-cache@v2` десь пізніше у тому самому job-і (lint, coverage,
+ * Tauri release/build — незалежно від job-а чи файлу; rust.mdc). Якщо job також
+ * запускає `tauri-apps/tauri-action` і Cargo.toml лежить не в корені репо, а під
+ * `src-tauri/`, кеш-крок повинен мати `with.workspaces` на цей каталог.
+ *
+ * Текстовий (не YAML-AST) аналіз — навмисно, як `ga/workflows/main.mjs`: мінімізує
+ * diff і не залежить від того, чи canonical formatter зберігає коментарі при
+ * round-trip через YAML-парсер. Job-межа визначається через indentation:
+ * будь-який рядок з відступом меншим за відступ dash-а кроку означає вихід
+ * зі step-list-а (наступний job або кінець `jobs:`).
+ */
+import { existsSync } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+
+import { createViolationReporter } from '../../../scripts/lib/lint-surface/violation-reporter.mjs'
+
+export const MISSING_RUST_CACHE = 'missing-rust-cache'
+export const MISSING_RUST_CACHE_WORKSPACES = 'missing-rust-cache-workspaces'
+
+export const TOOLCHAIN_RE = /uses:\s*dtolnay\/rust-toolchain@/u
+export const CACHE_RE = /uses:\s*Swatinem\/rust-cache@/u
+const TAURI_ACTION_RE = /uses:\s*tauri-apps\/tauri-action@/u
+const WORKSPACES_KEY_RE = /^\s*workspaces\s*:/u
+
+/**
+ * Відступ рядка (кількість пробілів перед першим непробільним символом).
+ * @param {string} line рядок файла
+ * @returns {number} кількість пробілів відступу
+ */
+function indentOf(line) {
+  return line.length - line.trimStart().length
+}
+
+/**
+ * Дашова колонка кроку (`- uses: …`) з колонки `uses:`. Захист від негативного
+ * значення для нетипового форматування (dash не на тому ж рядку).
+ * @param {number} usesCol колонка підрядка `uses:`
+ * @returns {number} колонка dash-а (не менше 0)
+ */
+function dashColFor(usesCol) {
+  return Math.max(usesCol - 2, 0)
+}
+
+/**
+ * Один запис аналізу `dtolnay/rust-toolchain` кроку в межах його job-а (обмеженого
+ * indentation-dedent-ом, без явного YAML-парсу job-структури).
+ * @typedef {object} ToolchainStepScan
+ * @property {number} line індекс рядка кроку `dtolnay/rust-toolchain@…`
+ * @property {number} dashCol колонка dash-а кроку (рівень step-list-а job-а)
+ * @property {boolean} hasCache чи є `Swatinem/rust-cache@…` пізніше в тому самому job-і
+ * @property {number} cacheLine індекс рядка кеш-кроку (−1, якщо відсутній)
+ * @property {boolean} cacheHasWorkspaces чи кеш-крок вже має ключ `workspaces`
+ * @property {boolean} jobHasTauriAction чи job також викликає `tauri-apps/tauri-action`
+ */
+
+/**
+ * Сканує job від рядка ОДРАЗУ ПІСЛЯ toolchain-кроку до dedent-у: шукає перший
+ * `Swatinem/rust-cache@…` крок і чи job також викликає `tauri-apps/tauri-action`.
+ * @param {string[]} lines усі рядки файла
+ * @param {number} fromLine рядок, з якого починати сканування (i + 1)
+ * @param {number} dashCol колонка dash-а step-list-а job-а (межа dedent-у)
+ * @returns {{hasCache: boolean, cacheLine: number, jobHasTauriAction: boolean}} результат сканування job-а
+ */
+function scanJobForCache(lines, fromLine, dashCol) {
+  let hasCache = false
+  let cacheLine = -1
+  let jobHasTauriAction = false
+  for (let j = fromLine; j < lines.length; j++) {
+    const line = lines[j]
+    if (line.trim() === '') continue
+    if (indentOf(line) < dashCol) break // dedent → вийшли зі step-list-а цього job-а
+    if (!hasCache && CACHE_RE.test(line)) {
+      hasCache = true
+      cacheLine = j
+    }
+    if (TAURI_ACTION_RE.test(line)) jobHasTauriAction = true
+  }
+  return { hasCache, cacheLine, jobHasTauriAction }
+}
+
+/**
+ * Чи кеш-крок (`cacheLine`) уже має ключ `with.workspaces` у своєму блоці (до dedent-у).
+ * @param {string[]} lines усі рядки файла
+ * @param {number} cacheLine рядок кеш-кроку
+ * @param {number} dashCol колонка dash-а step-list-а job-а (межа dedent-у)
+ * @returns {boolean} true — ключ `workspaces` уже є
+ */
+function cacheStepHasWorkspaces(lines, cacheLine, dashCol) {
+  for (let j = cacheLine + 1; j < lines.length; j++) {
+    const line = lines[j]
+    if (line.trim() === '') continue
+    if (indentOf(line) < dashCol) break
+    if (WORKSPACES_KEY_RE.test(line)) return true
+  }
+  return false
+}
+
+/**
+ * Сканує вміст workflow-файла й повертає по одному запису на кожен
+ * `dtolnay/rust-toolchain@…` крок, з інформацією про cache-крок і tauri-action
+ * у тому самому job-і (обмежено indentation-dedent-ом).
+ * @param {string} content вміст workflow-файла
+ * @returns {ToolchainStepScan[]} записи аналізу
+ */
+export function scanToolchainSteps(content) {
+  const lines = content.split('\n')
+  /** @type {ToolchainStepScan[]} */
+  const out = []
+  for (let i = 0; i < lines.length; i++) {
+    const usesCol = lines[i].indexOf('uses:')
+    if (usesCol === -1 || !TOOLCHAIN_RE.test(lines[i])) continue
+    const dashCol = dashColFor(usesCol)
+    const { hasCache, cacheLine, jobHasTauriAction } = scanJobForCache(lines, i + 1, dashCol)
+    const cacheHasWorkspaces = hasCache && cacheStepHasWorkspaces(lines, cacheLine, dashCol)
+    out.push({ line: i, dashCol, hasCache, cacheLine, cacheHasWorkspaces, jobHasTauriAction })
+  }
+  return out
+}
+
+/**
+ * Каталог Rust-workspace-а для `Swatinem/rust-cache` `with.workspaces`, якщо
+ * `Cargo.toml` не в корені репо, а під `src-tauri/` (типовий Tauri-layout).
+ * `undefined`, якщо корінь репо вже є workspace-коренем (окремий крок не потрібен).
+ * @param {string} cwd корінь проєкту
+ * @returns {string|undefined} відносний шлях workspace-а або `undefined`
+ */
+export function tauriWorkspaceDir(cwd) {
+  if (existsSync(join(cwd, 'Cargo.toml'))) return
+  return existsSync(join(cwd, 'src-tauri', 'Cargo.toml')) ? 'src-tauri' : undefined
+}
+
+/**
+ * @param {import('../../../scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінт-прогону
+ * @returns {Promise<import('../../../scripts/lib/lint-surface/types.mjs').LintResult>} результат перевірки
+ */
+export async function lint(ctx) {
+  const cwd = ctx.cwd
+  const reporter = createViolationReporter(ctx)
+  const wfDir = join(cwd, '.github', 'workflows')
+  if (!existsSync(wfDir)) return reporter.result()
+
+  const workspaceDir = tauriWorkspaceDir(cwd)
+  const entries = await readdir(wfDir)
+  const workflowFiles = entries.filter(f => f.endsWith('.yml') || f.endsWith('.yaml'))
+
+  for (const name of workflowFiles) {
+    const abs = join(wfDir, name)
+    const rel = relative(cwd, abs)
+    const content = await readFile(abs, 'utf8')
+    for (const step of scanToolchainSteps(content)) {
+      if (!step.hasCache) {
+        reporter.fail(
+          `${rel}: job зі \`dtolnay/rust-toolchain@stable\` потребує \`Swatinem/rust-cache@v2\` одразу після (rust.mdc)`,
+          { reason: MISSING_RUST_CACHE, file: rel, data: { kind: MISSING_RUST_CACHE } }
+        )
+        continue
+      }
+      if (workspaceDir && step.jobHasTauriAction && !step.cacheHasWorkspaces) {
+        reporter.fail(
+          `${rel}: Swatinem/rust-cache@v2 у Tauri-job-і потребує \`with.workspaces: ${workspaceDir}\` (rust.mdc)`,
+          {
+            reason: MISSING_RUST_CACHE_WORKSPACES,
+            file: rel,
+            data: { kind: MISSING_RUST_CACHE_WORKSPACES, workspaceDir }
+          }
+        )
+      }
+    }
+  }
+  return reporter.result()
+}

package/rules/rust/toolchain_cache/toolchain_cache.mdc

@@ -0,0 +1,23 @@
+## Rust-cache після rust-toolchain — у будь-якому workflow
+
+Concern: `rust/toolchain_cache` (JS-detector, `main.mjs` — не rego)
+
+Цільові файли: `.github/workflows/*.yml`, `.github/workflows/*.yaml` (кожен файл окремо)
+
+У кожному job-і, що ставить Rust toolchain через `dtolnay/rust-toolchain@stable`
+(або будь-яку іншу версію), одразу після цього кроку має бути `Swatinem/rust-cache@v2` —
+незалежно від того, lint це, coverage чи release/build job, що збирає Tauri-додаток
+через `tauri-apps/tauri-action`. Без кешу CI щоразу заново качає весь cargo registry.
+
+Це узагальнення перевірки `rust/lint_rust_yml` (яка звіряє канонічний
+`.github/workflows/lint-rust.yml` цілком) — той concern лишається specific до
+lint-workflow, цей — universal per-job перевірка для решти workflow-файлів
+(coverage, release, будь-який кастомний).
+
+Якщо job також викликає `tauri-apps/tauri-action`, а `Cargo.toml` лежить не в
+корені репо, а під `<ws>/src-tauri/` (типовий Tauri-layout) — крок
+`Swatinem/rust-cache@v2` має мати `with.workspaces: <ws>/src-tauri`.
+
+Автофікс (`fix-toolchain_cache.mjs`, T0, `fixability: config`) вставляє відсутній
+крок одразу після `dtolnay/rust-toolchain@…` (і `with.workspaces`, де потрібно)
+текстовим splice-ом — зберігає формат/коментарі, ідемпотентно.

package/rules/rust/vscode_extensions/concern.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "policy": {
+    "files": {
+      "single": ".vscode/extensions.json",
+      "required": true
+    },
+    "missingMessage": ".vscode/extensions.json не існує — створи з recommendations \"rust-lang.rust-analyzer\" і \"tamasfe.even-better-toml\" (rust.mdc)"
+  }
+}

package/rules/rust/vscode_extensions/docs/fix-vscode_extensions.md

@@ -0,0 +1,25 @@
+---
+type: JS Module
+title: fix-vscode_extensions.mjs
+resource: npm/rules/rust/vscode_extensions/fix-vscode_extensions.mjs
+docgen:
+  crc: 3353fe17
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Надайте мені чорнетку секції "overview", яку потрібно переписати, щоб я міг застосувати ваші інструкції.
+
+## Поведінка
+
+1. Ініціалізує логіку для виправлення VS Code Extensions.
+2. Імпортує шаблони логіки для додавання до VS Code Extensions з файлу `../../../scripts/lib/fix/vscode-ext-add.mjs`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

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

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

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

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

@@ -0,0 +1 @@
+{ "recommendations": ["rust-lang.rust-analyzer", "tamasfe.even-better-toml"] }

package/rules/rust/vscode_extensions/vscode_extensions.mdc

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

package/rules/rust/vscode_extensions/vscode_extensions.rego

@@ -0,0 +1,15 @@
+# Перевірка `.vscode/extensions.json` для правила rust (rust.mdc).
+#
+# Канон надходить через --data: { "template": { "snippet": ... } }
+# Структура --data сформована з template/extensions.json.snippet.json.
+# Semantics: subset-of для recommendations — кожен з канону має бути присутнім,
+# інші екстеншени дозволені.
+package rust.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 (rust.mdc)", [rec])
+}

package/rules/security/docs/index.md

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

package/rules/security/lint_security_yml/concern.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "policy": {
+    "files": {
+      "single": ".github/workflows/lint-security.yml",
+      "required": true
+    },
+    "missingMessage": ".github/workflows/lint-security.yml не знайдено — створи за каноном security.mdc"
+  }
+}

package/rules/security/lint_security_yml/lint_security_yml.mdc

@@ -0,0 +1,7 @@
+## Наявність кроку TruffleHog у CI workflow
+
+Rego-пакет: `security.lint_security_yml`
+
+Цільові файли: `.github/workflows/lint-security.yml`
+
+Перевіряє, що серед `uses:` у workflow присутній крок `trufflesecurity/trufflehog@main`. Очікуваний перелік action-refs (не-`actions/*`) береться з `--data` через [lint-security.yml.snippet.yml](./template/lint-security.yml.snippet.yml). Універсальні кроки (`actions/*`) перевіряє `ga.workflow_common`.

package/rules/security/lint_security_yml/lint_security_yml.rego

@@ -0,0 +1,33 @@
+# Перевірка `.github/workflows/lint-security.yml` (security.mdc).
+#
+# Канон надходить через --data: { "template": { "snippet": ... } }, побудоване
+# з template/lint-security.yml.snippet.yml. З нього збирається перелік
+# `uses:` action-refs security-job (виключаючи універсальні `actions/*`, які
+# валідує `ga.workflow_common`).
+#
+# Структура каталогу збігається зі шляхом пакету (regal: directory-package-mismatch).
+package security.lint_security_yml
+
+import rego.v1
+
+# Очікувані action-uses із template (не-`actions/*`).
+expected_uses_blob := concat("\n", [u |
+	some step in data.template.snippet.jobs.security.steps
+	u := object.get(step, "uses", "")
+	u != ""
+	not startswith(u, "actions/")
+])
+
+# Усі `uses:` із input workflow.
+all_uses_text := concat("\n", [u |
+	some job in object.get(input, "jobs", {})
+	some step in object.get(job, "steps", [])
+	u := object.get(step, "uses", "")
+	u != ""
+])
+
+deny contains msg if {
+	expected_uses_blob != ""
+	not contains(all_uses_text, expected_uses_blob)
+	msg := sprintf("lint-security.yml: відсутній крок з uses %q (security.mdc)", [expected_uses_blob])
+}

package/rules/security/lint_security_yml/template/lint-security.yml.snippet.yml

@@ -0,0 +1,31 @@
+name: Lint Security
+
+on:
+  push:
+    branches:
+      - dev
+      - main
+
+  pull_request:
+    branches:
+      - dev
+      - main
+
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - uses: trufflesecurity/trufflehog@main
+        with:
+          extra_args: --results=verified,unknown

package/rules/security/main.json

@@ -0,0 +1 @@
+{ "auto": "завжди" }

package/rules/security/main.mdc

@@ -0,0 +1,15 @@
+---
+description: Локальний та CI-секюріті-лінт через TruffleHog — `.trufflehog-exclude`, канонічний placeholder `sample-secret` у прикладних файлах
+globs: "**/.trufflehog-exclude,**/package.json,**/.github/workflows/**/*.yml"
+alwaysApply: false
+version: '2.1'
+---
+
+Правило **security** забезпечує сканування секретів через [TruffleHog](https://github.com/trufflesecurity/trufflehog) локально та на CI, а також правильне використання placeholder-значень у прикладних файлах.
+
+## Перевірка
+
+`npx @7n/rules fix security`
+
+- [lint-security.yml.snippet.yml](./lint_security_yml/template/lint-security.yml.snippet.yml)
+- [package.json.deny.json](./package_json/template/package.json.deny.json)

package/rules/security/package_json/concern.json

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

package/rules/security/package_json/package_json.mdc

@@ -0,0 +1,7 @@
+## Заборона `trufflehog` у залежностях `package.json`
+
+Rego-пакет: `security.package_json`
+
+Цільові файли: `package.json`
+
+Перевіряє, що пакет `trufflehog` відсутній у `dependencies` та `devDependencies` — він є глобальним CLI і не має бути npm-залежністю. Список заборонених пакетів надходить через `--data` з [package.json.deny.json](./template/package.json.deny.json).

package/rules/security/package_json/package_json.rego

@@ -0,0 +1,19 @@
+# Перевірка `package.json` для правила security (security.mdc).
+# Канон надходить через --data: { "template": { "snippet": ..., "deny": ..., "contains": ... } }
+# Структура --data сформована з template/<target>.{snippet,deny,contains}.json концерну.
+package security.package_json
+
+import rego.v1
+
+# ── deny: жодного ключа з deny у dependencies/devDependencies ────────────────
+deny contains msg if {
+	some pkg, reason in data.template.deny.dependencies
+	pkg in object.keys(object.get(input, "dependencies", {}))
+	msg := sprintf("package.json: dependencies.%s — %s (security.mdc)", [pkg, reason])
+}
+
+deny contains msg if {
+	some pkg, reason in data.template.deny.devDependencies
+	pkg in object.keys(object.get(input, "devDependencies", {}))
+	msg := sprintf("package.json: devDependencies.%s — %s (security.mdc)", [pkg, reason])
+}

package/rules/security/package_json/template/package.json.deny.json

@@ -0,0 +1,4 @@
+{
+  "dependencies": { "trufflehog": "глобальний CLI — не додавай у dependencies" },
+  "devDependencies": { "trufflehog": "глобальний CLI — не додавай у devDependencies" }
+}

package/rules/security/sample_secret/concern.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "lint": {
+    "scope": "full",
+    "glob": [
+      "**/*.{example,sample,template,dist}",
+      "**/*.{example,sample,template}.*",
+      "**/{fixtures,fixture,__fixtures__}/**"
+    ]
+  }
+}

package/rules/security/sample_secret/docs/index.md

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

package/rules/security/sample_secret/docs/main.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/security/sample_secret/main.mjs
+docgen:
+  crc: 021a0a51
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 95
+  issues: anchor-miss:app.config.sample.json,judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+好的，請提供需要為之編寫文件相關的程式碼文件或上下文。我會根據您提供的「已知事實」、「錨點」和「行為 (ПОВЕДІНКА)」，撰寫出符合所有規範的「Огляд」部分。
+
+## Поведінка
+
+1. Викликається `main` для початку процесу.
+2. Збираються всі шляхи до файлів, які вважаються "прикладними" на основі їхнього імені та розташування у репозиторії.
+3. Для кожного знайденого прикладного файлу зчитується його вміст.
+4. Проходиться по кожному рядку вмісту файлу.
+5. Якщо рядок містить виявлений синтаксис для сирого секрету (`secret`), фіксується порушення, згадуючи його у контексті (security.mdc).
+6. Після обробки всіх файлів повертається відповідний код завершення, що інформує про наявність чи відсутність виявлених сирих секретів.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/rules/security/sample_secret/main.mjs

@@ -0,0 +1,80 @@
+/** @see ./docs/sample_secret.md */
+import { readFile } from 'node:fs/promises'
+import { relative, sep } from 'node:path'
+
+import { createViolationReporter } from '../../../scripts/lib/lint-surface/violation-reporter.mjs'
+import { walkDir } from '../../../scripts/utils/walkDir.mjs'
+
+/** Суфікс basename'а прикладного файлу (`config.example`, `.env.dist`). */
+const EXAMPLE_SUFFIX_RE = /\.(?:example|sample|template|dist)$/iu
+
+/** Infix у basename'і (`docker-compose.example.yml`, `app.config.sample.json`). */
+const EXAMPLE_INFIX_RE = /\.(?:example|sample|template)\./iu
+
+/** Сегмент шляху з фікстурами (`fixtures/`, `fixture/`, `__fixtures__/`). */
+const FIXTURE_DIR_RE = /(?:^|\/)(?:__fixtures__|fixtures?)(?:\/|$)/u
+
+/**
+ * Bare-`secret` у позиції значення: після `=`, `:` або `=>` (опційні лапки), а
+ * далі лише пробіли / завершальна пунктуація / коментар до кінця рядка. Прив'язка
+ * до `$` гарантує, що `secret` — увесь токен значення (`secret-key`, `secretValue`
+ * не матчаться); прив'язка до `[:=]` відсікає імена ключів (`client_secret`).
+ * Без урахування регістру символів.
+ */
+const VALUE_SECRET_RE = /[:=]>?\s*(['"]?)secret\1[\s,;}\])]*(?:(?:#|\/\/).*)?$/iu
+
+/**
+ * Чи є файл «прикладним» — таким, де `secret` очікувано є placeholder'ом.
+ * @param {string} relPosix відносний шлях від cwd у posix-форматі
+ * @returns {boolean} `true`, якщо файл треба сканувати
+ */
+function isExampleFile(relPosix) {
+  const base = relPosix.slice(relPosix.lastIndexOf('/') + 1)
+  return EXAMPLE_SUFFIX_RE.test(base) || EXAMPLE_INFIX_RE.test(base) || FIXTURE_DIR_RE.test(relPosix)
+}
+
+/**
+ * Перевіряє відповідність проєкту правилам security.mdc (sample-secret).
+ * @param {import('../../../scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінту
+ * @returns {Promise<import('../../../scripts/lib/lint-surface/types.mjs').LintResult>} результат лінту
+ */
+export async function lint(ctx) {
+  const cwd = ctx.cwd
+  const reporter = createViolationReporter(ctx)
+  const { pass, fail } = reporter
+
+  /** @type {Array<{ abs: string, rel: string }>} */
+  const examples = []
+  await walkDir(cwd, abs => {
+    const rel = relative(cwd, abs).split(sep).join('/')
+    if (isExampleFile(rel)) examples.push({ abs, rel })
+  })
+  examples.sort((a, b) => a.rel.localeCompare(b.rel))
+
+  if (examples.length === 0) {
+    pass('прикладних файлів не знайдено — placeholder перевіряти нема де')
+    return reporter.result()
+  }
+
+  let violations = 0
+  for (const { abs, rel } of examples) {
+    let content
+    try {
+      content = await readFile(abs, 'utf8')
+    } catch {
+      continue
+    }
+    const lines = content.split('\n')
+    for (const [i, line_] of lines.entries()) {
+      const line = line_.endsWith('\r') ? line_.slice(0, -1) : line_
+      if (!VALUE_SECRET_RE.test(line)) continue
+      violations++
+      fail(`${rel}:${i + 1}: \`${line.trim()}\` — заміни placeholder \`secret\` на \`sample-secret\` (security.mdc)`)
+    }
+  }
+
+  if (violations === 0) {
+    pass(`прикладні файли (${examples.length}) не містять bare \`secret\``)
+  }
+  return reporter.result()
+}

package/rules/security/sample_secret/sample_secret.mdc

@@ -0,0 +1,20 @@
+## Placeholder для секретів — `sample-secret`
+
+Фейкові credential-значення у **прикладних файлах** (`.env.example`, `.env.dist`, `*.example`, `*.sample`, `*.template`, вміст каталогів `fixtures/`) пиши як `sample-secret`, а не як bare `secret`.
+
+`sample-secret` містить підрядок `sample` із вшитого списку `DefaultFalsePositives` TruffleHog — таке значення сканер відсіює **гарантовано** й незалежно від версії. Bare `secret` наразі не фіксується сканером лише тому, що випадково присутнє у словнику `fp_words.txt`; це крихка поведінка, що залежить від версії інструмента.
+
+### Приклади
+
+- Правильно: `DB_PASSWORD=sample-secret`, `password: "sample-secret"`
+- Неправильно: `DB_PASSWORD=secret`, `password: "secret"`
+
+### Що перевіряється
+
+Перевіряється лише `secret` у позиції значення (після `=`, `:`, `=>`); імена ключів на кшталт `client_secret` не чіпаються.
+
+Concern `security.sample_secret` (`js/sample_secret.mjs`) сканує всі прикладні файли:
+
+- суфікс basename'а: `.example`, `.sample`, `.template`, `.dist`
+- інфікс у basename'і: `.example.`, `.sample.`, `.template.`
+- сегмент шляху: `fixtures/`, `fixture/`, `__fixtures__/`

package/rules/security/scan/concern.json

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

package/rules/security/scan/docs/index.md

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