@nitra/cursor 12.8.3 → 12.8.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/bin/n-cursor.js +3 -2
  3. package/package.json +1 -1
  4. package/rules/abie/js/env_dns.mdc +33 -0
  5. package/rules/abie/js/firebase_hosting.mdc +3 -0
  6. package/rules/abie/js/hc_pairing.mdc +23 -0
  7. package/rules/abie/js/ua_http_route.mdc +47 -0
  8. package/rules/abie/js/ua_node_selector.mdc +27 -0
  9. package/rules/abie/main.mdc +53 -0
  10. package/rules/doc-files/js/docs/index.md +15 -15
  11. package/rules/js/docs/index.md +3 -3
  12. package/rules/js/docs/main.md +7 -7
  13. package/rules/js/js/docs/check.md +12 -16
  14. package/rules/js/js/docs/index.md +4 -4
  15. package/rules/js/js/docs/tooling.md +8 -8
  16. package/rules/js/js/docs/utils_imports.md +22 -200
  17. package/rules/npm-module/js/docs/index.md +5 -5
  18. package/rules/npm-module/js/docs/rule_meta.md +13 -13
  19. package/rules/npm-module/js/docs/skill_meta.md +19 -9
  20. package/rules/npm-module/js/rule_meta.mjs +9 -9
  21. package/rules/npm-module/js/skill_meta.mjs +6 -6
  22. package/rules/test/js/docs/index.md +7 -7
  23. package/rules/test/js/docs/stryker_config.md +18 -35
  24. package/rules/test/js/docs/vitest-config-pool-forks.md +20 -12
  25. package/schemas/v8r-catalog.json +4 -4
  26. package/scripts/docs/index.md +16 -16
  27. package/scripts/docs/sync-setup-bun-deps-action.md +14 -14
  28. package/scripts/lib/check-mdc-template-refs.mjs +2 -2
  29. package/scripts/lib/docs/check-mdc-template-refs.md +12 -214
  30. package/scripts/lib/docs/index.md +36 -36
  31. package/scripts/lib/docs/inline-template-links.md +13 -293
  32. package/scripts/lib/docs/mirror-parity.md +18 -157
  33. package/scripts/lib/docs/rule-meta.md +19 -22
  34. package/scripts/lib/docs/run-rule.md +11 -11
  35. package/scripts/lib/docs/skill-meta.md +17 -19
  36. package/scripts/lib/docs/timing-summary.md +7 -7
  37. package/scripts/lib/inline-template-links.mjs +31 -0
  38. package/scripts/lib/mirror-parity.mjs +6 -4
  39. package/scripts/lib/rule-meta.mjs +1 -1
  40. package/scripts/lib/run-rule.mjs +4 -4
  41. package/scripts/lib/skill-meta.mjs +1 -1
  42. package/scripts/utils/docs/index.md +14 -14
  43. package/scripts/utils/docs/resolve-js-root.md +12 -13
  44. package/types/bin/n-cursor.d.ts +1 -1
  45. package/rules/abie/abie.mdc +0 -181
  46. /package/rules/abie/{meta.json → main.json} +0 -0
  47. /package/rules/adr/{meta.json → main.json} +0 -0
  48. /package/rules/adr/{adr.mdc → main.mdc} +0 -0
  49. /package/rules/bun/{meta.json → main.json} +0 -0
  50. /package/rules/bun/{bun.mdc → main.mdc} +0 -0
  51. /package/rules/capacitor/{meta.json → main.json} +0 -0
  52. /package/rules/capacitor/{capacitor.mdc → main.mdc} +0 -0
  53. /package/rules/changelog/{meta.json → main.json} +0 -0
  54. /package/rules/changelog/{changelog.mdc → main.mdc} +0 -0
  55. /package/rules/ci4/{meta.json → main.json} +0 -0
  56. /package/rules/ci4/{ci4.mdc → main.mdc} +0 -0
  57. /package/rules/doc-files/{meta.json → main.json} +0 -0
  58. /package/rules/doc-files/{doc-files.mdc → main.mdc} +0 -0
  59. /package/rules/docker/{meta.json → main.json} +0 -0
  60. /package/rules/docker/{docker.mdc → main.mdc} +0 -0
  61. /package/rules/efes/{meta.json → main.json} +0 -0
  62. /package/rules/efes/{efes.mdc → main.mdc} +0 -0
  63. /package/rules/feedback/{meta.json → main.json} +0 -0
  64. /package/rules/feedback/{feedback.mdc → main.mdc} +0 -0
  65. /package/rules/ga/{meta.json → main.json} +0 -0
  66. /package/rules/ga/{ga.mdc → main.mdc} +0 -0
  67. /package/rules/graphql/{meta.json → main.json} +0 -0
  68. /package/rules/graphql/{graphql.mdc → main.mdc} +0 -0
  69. /package/rules/hasura/{meta.json → main.json} +0 -0
  70. /package/rules/hasura/{hasura.mdc → main.mdc} +0 -0
  71. /package/rules/image-avif/{meta.json → main.json} +0 -0
  72. /package/rules/image-avif/{image-avif.mdc → main.mdc} +0 -0
  73. /package/rules/image-compress/{meta.json → main.json} +0 -0
  74. /package/rules/image-compress/{image-compress.mdc → main.mdc} +0 -0
  75. /package/rules/js/{meta.json → main.json} +0 -0
  76. /package/rules/js/{js.mdc → main.mdc} +0 -0
  77. /package/rules/js-bun-db/{meta.json → main.json} +0 -0
  78. /package/rules/js-bun-db/{js-bun-db.mdc → main.mdc} +0 -0
  79. /package/rules/js-bun-redis/{meta.json → main.json} +0 -0
  80. /package/rules/js-bun-redis/{js-bun-redis.mdc → main.mdc} +0 -0
  81. /package/rules/js-mssql/{meta.json → main.json} +0 -0
  82. /package/rules/js-mssql/{js-mssql.mdc → main.mdc} +0 -0
  83. /package/rules/js-run/{meta.json → main.json} +0 -0
  84. /package/rules/js-run/{js-run.mdc → main.mdc} +0 -0
  85. /package/rules/k8s/{meta.json → main.json} +0 -0
  86. /package/rules/k8s/{k8s.mdc → main.mdc} +0 -0
  87. /package/rules/nginx-default-tpl/{meta.json → main.json} +0 -0
  88. /package/rules/nginx-default-tpl/{nginx-default-tpl.mdc → main.mdc} +0 -0
  89. /package/rules/npm-module/{meta.json → main.json} +0 -0
  90. /package/rules/npm-module/{npm-module.mdc → main.mdc} +0 -0
  91. /package/rules/php/{meta.json → main.json} +0 -0
  92. /package/rules/php/{php.mdc → main.mdc} +0 -0
  93. /package/rules/python/{meta.json → main.json} +0 -0
  94. /package/rules/python/{python.mdc → main.mdc} +0 -0
  95. /package/rules/rego/{meta.json → main.json} +0 -0
  96. /package/rules/rego/{rego.mdc → main.mdc} +0 -0
  97. /package/rules/release/{meta.json → main.json} +0 -0
  98. /package/rules/release/{release.mdc → main.mdc} +0 -0
  99. /package/rules/rust/{meta.json → main.json} +0 -0
  100. /package/rules/rust/{rust.mdc → main.mdc} +0 -0
  101. /package/rules/security/{meta.json → main.json} +0 -0
  102. /package/rules/security/{security.mdc → main.mdc} +0 -0
  103. /package/rules/style/{meta.json → main.json} +0 -0
  104. /package/rules/style/{style.mdc → main.mdc} +0 -0
  105. /package/rules/tauri/{meta.json → main.json} +0 -0
  106. /package/rules/tauri/{tauri.mdc → main.mdc} +0 -0
  107. /package/rules/test/{meta.json → main.json} +0 -0
  108. /package/rules/test/{test.mdc → main.mdc} +0 -0
  109. /package/rules/text/{meta.json → main.json} +0 -0
  110. /package/rules/text/{text.mdc → main.mdc} +0 -0
  111. /package/rules/tool-surface/{meta.json → main.json} +0 -0
  112. /package/rules/tool-surface/{tool-surface.mdc → main.mdc} +0 -0
  113. /package/rules/vue/{meta.json → main.json} +0 -0
  114. /package/rules/vue/{vue.mdc → main.mdc} +0 -0
  115. /package/rules/worktree/{meta.json → main.json} +0 -0
  116. /package/rules/worktree/{worktree.mdc → main.mdc} +0 -0
  117. /package/skills/adr-normalize/{meta.json → main.json} +0 -0
  118. /package/skills/coverage-fix/{meta.json → main.json} +0 -0
  119. /package/skills/doc-aggregate/{meta.json → main.json} +0 -0
  120. /package/skills/doc-files/{meta.json → main.json} +0 -0
  121. /package/skills/lint/{meta.json → main.json} +0 -0
  122. /package/skills/llm-patch/{meta.json → main.json} +0 -0
  123. /package/skills/publish-telegram/{meta.json → main.json} +0 -0
  124. /package/skills/start-check/{meta.json → main.json} +0 -0
  125. /package/skills/taze/{meta.json → main.json} +0 -0
@@ -28,14 +28,14 @@
28
28
  },
29
29
  {
30
30
  "name": "n-cursor skill meta",
31
- "description": "Маніфест skill-пакета n-cursor (npm/skills/<id>/meta.json) — назва, тригери, дозволи",
32
- "fileMatch": ["npm/skills/*/meta.json"],
31
+ "description": "Маніфест skill-пакета n-cursor (npm/skills/<id>/main.json) — назва, тригери, дозволи",
32
+ "fileMatch": ["npm/skills/*/main.json"],
33
33
  "url": "https://unpkg.com/@nitra/cursor/schemas/skill-meta.json"
34
34
  },
35
35
  {
36
36
  "name": "n-cursor rule meta",
37
- "description": "Маніфест rule-пакета n-cursor (npm/rules/<id>/meta.json) — назва, опис, версія правила",
38
- "fileMatch": ["npm/rules/*/meta.json"],
37
+ "description": "Маніфест rule-пакета n-cursor (npm/rules/<id>/main.json) — назва, опис, версія правила",
38
+ "fileMatch": ["npm/rules/*/main.json"],
39
39
  "url": "https://unpkg.com/@nitra/cursor/schemas/rule-meta.json"
40
40
  }
41
41
  ]
@@ -6,20 +6,20 @@ resource: npm/scripts/
6
6
 
7
7
  # npm/scripts
8
8
 
9
- | Файл | Тип |
10
- | ----------------------------------------------------------------------------------- | --------- |
11
- | [auto-rules.mjs](auto-rules.md) | JS Module |
12
- | [auto-skills.mjs](auto-skills.md) | JS Module |
13
- | [build-agents-commands.mjs](build-agents-commands.md) | JS Module |
14
- | [cli-entry.mjs](cli-entry.md) | JS Module |
15
- | [coverage-fix-extract.mjs](coverage-fix-extract.md) | JS Module |
16
- | [coverage-fix.mjs](coverage-fix.md) | JS Module |
9
+ | Файл | Тип |
10
+ |---|---|
11
+ | [auto-rules.mjs](auto-rules.md) | JS Module |
12
+ | [auto-skills.mjs](auto-skills.md) | JS Module |
13
+ | [build-agents-commands.mjs](build-agents-commands.md) | JS Module |
14
+ | [cli-entry.mjs](cli-entry.md) | JS Module |
15
+ | [coverage-fix-extract.mjs](coverage-fix-extract.md) | JS Module |
16
+ | [coverage-fix.mjs](coverage-fix.md) | JS Module |
17
17
  | [ensure-nitra-cursor-dev-dependencies.mjs](ensure-nitra-cursor-dev-dependencies.md) | JS Module |
18
- | [post-tool-use-check.mjs](post-tool-use-check.md) | JS Module |
19
- | [post-tool-use-fix.mjs](post-tool-use-fix.md) | JS Module |
20
- | [rename-yaml-extensions.mjs](rename-yaml-extensions.md) | JS Module |
21
- | [skills-cli.mjs](skills-cli.md) | JS Module |
22
- | [sync-claude-config.mjs](sync-claude-config.md) | JS Module |
23
- | [sync-setup-bun-deps-action.mjs](sync-setup-bun-deps-action.md) | JS Module |
24
- | [upgrade-nitra-cursor-and-install.mjs](upgrade-nitra-cursor-and-install.md) | JS Module |
25
- | [worktree-cli.mjs](worktree-cli.md) | JS Module |
18
+ | [post-tool-use-check.mjs](post-tool-use-check.md) | JS Module |
19
+ | [post-tool-use-fix.mjs](post-tool-use-fix.md) | JS Module |
20
+ | [rename-yaml-extensions.mjs](rename-yaml-extensions.md) | JS Module |
21
+ | [skills-cli.mjs](skills-cli.md) | JS Module |
22
+ | [sync-claude-config.mjs](sync-claude-config.md) | JS Module |
23
+ | [sync-setup-bun-deps-action.mjs](sync-setup-bun-deps-action.md) | JS Module |
24
+ | [upgrade-nitra-cursor-and-install.mjs](upgrade-nitra-cursor-and-install.md) | JS Module |
25
+ | [worktree-cli.mjs](worktree-cli.md) | JS Module |
@@ -3,28 +3,28 @@ type: JS Module
3
3
  title: sync-setup-bun-deps-action.mjs
4
4
  resource: npm/scripts/sync-setup-bun-deps-action.mjs
5
5
  docgen:
6
- crc: 098d7209
6
+ crc: 327991b2
7
+ model: omlx/gemma-4-e4b-it-OptiQ-4bit
8
+ score: 100
7
9
  ---
8
10
 
9
- Файл містить конфігурацію GitHub Action `setup-bun-deps`, яка автоматично встановлює залежності проєкту Bun. Він використовується workflow для підготовки середовища проєкту, забезпечуючи узгодженість та спрощуючи виконання тестів та інших завдань, що потребують Bun. Це дозволяє workflow, що використовує `actions/checkout@v6`, безпосередньо використовувати action, не потребуючи додаткової конфігурації.
11
+ ## Огляд
12
+
13
+ Копіює composite GitHub Action `setup-bun-deps` з каталогу `github-actions/setup-bun-deps/` у корені tarball пакету `@nitra/cursor` у цільовий репозиторій за шлях `.github/actions/setup-bun-deps/action.yml`. Це забезпечує можливість для workflow з правил `ga`, `js` або `text` викликати цей action для налаштування залежностей Bun одразу після виконання `actions/checkout@v6`.
10
14
 
11
15
  ## Поведінка
12
16
 
13
- 1. Перевіряє наявність шаблону composite action `action.yml` у каталозі `github-actions/setup-bun-deps/` всередині кореня пакету `@nitra/cursor`.
14
- 2. Якщо шаблон не знайдено, кидає помилку, вказуючи очікуваний шлях та пропонуючи перевстановити пакет.
15
- 3. Створює каталог `.github/actions/setup-bun-deps` у цільовому репозиторії, якщо його не існує.
16
- 4. Зчитує вміст файлу `action.yml` з джерела.
17
- 5. Записує вміст `action.yml` у файл `action.yml` у цільовому репозиторії. Додає новий рядок в кінці файлу, якщо потрібно.
18
- 6. Повертає об'єкт, що містить інформацію про успішність запису та повний шлях до створеного файлу.
17
+ 1. Перевіряє наявність шаблону composite action у корені встановленого пакету `@nitra/cursor`.
18
+ 2. Створює необхідну директорію у корені цільового репозиторію для розміщення composite action.
19
+ 3. Зчитує вміст шаблону composite action з кореня встановленого пакету.
20
+ 4. Записує вміст шаблону composite action у цільовий шлях у корені репозиторію.
21
+ 5. Повертає підтвердження успішного запису та повний шлях до файлу.
22
+ 6. Не перевіряє шляхи `.github` чи `.git`.
19
23
 
20
24
  ## Публічний API
21
25
 
22
- syncSetupBunDepsAction — Створює файл з залежностями Bun, використовуючи корінь пакета `@nitra/cursor`.
26
+ syncSetupBunDepsAction — фіксує у `projectRoot` композитну дію, що вказує на корінь встановленого `@nitra/cursor`.
23
27
 
24
28
  ## Гарантії поведінки
25
29
 
26
- - Копіює файл `action.yml` з каталогу `github-actions/setup-bun-deps/` у каталог `.github/actions/setup-bun-deps/`.
27
- - Забезпечує доступність action `setup-bun-deps` для workflow, що використовує `actions/checkout@v6`.
28
- - Використовує `npx @nitra/cursor` для ініціалізації action.
29
- - Не враховує наявність checkout runner.
30
- - Не має кешування.
30
+ - Свідомо пропускає шляхи: `.github`, `.git`.
@@ -45,8 +45,8 @@ async function collectFiles(dir) {
45
45
  * @param {string} ruleId basename правила (напр. "security")
46
46
  * @returns {Promise<string[]>} відносні шляхи template-файлів без посилань у .mdc
47
47
  */
48
- export async function findMissingMdcRefs(ruleDir, ruleId) {
49
- const mdcPath = join(ruleDir, `${ruleId}.mdc`)
48
+ export async function findMissingMdcRefs(ruleDir) {
49
+ const mdcPath = join(ruleDir, 'main.mdc')
50
50
  if (!existsSync(mdcPath)) return []
51
51
  const mdc = await readFile(mdcPath, 'utf8')
52
52
  const allFiles = await walkTemplateDirs(ruleDir)
@@ -3,224 +3,22 @@ type: JS Module
3
3
  title: check-mdc-template-refs.mjs
4
4
  resource: npm/scripts/lib/check-mdc-template-refs.mjs
5
5
  docgen:
6
- crc: 17b81322
6
+ crc: c116210e
7
+ model: omlx/gemma-4-e4b-it-OptiQ-4bit
8
+ score: 100
7
9
  ---
8
10
 
9
- Модуль `check-mdc-template-refs.mjs` — це невелика утиліта, призначена для перевірки цілісності посилань між файлом правила `<id>.mdc` та шаблонами, що лежать у підкаталогах `template/` цього самого правила. Він обходить структуру каталогів правила (`fix/<concern>/template/`, `policy/<concern>/template/`), збирає всі знайдені файли й порівнює їхні відносні шляхи з вмістом основного файлу правила `<id>.mdc`. Результатом є перелік шаблонних файлів, на які у `.mdc` немає жодного markdown-посилання, тобто «осиротілі» (orphaned) шаблони.
11
+ ## Огляд
10
12
 
11
- Типовий контекст застосування: модуль використовується в утилітах перевірки/лінтингу правил репозиторію (`npm/rules/<id>/`), де `.mdc`-файл описує правило людською мовою й має посилатися на свої шаблони. Якщо шаблон існує, але не згаданий у `.mdc`, цей модуль повідомить про нього, щоб супровідник правила або додав посилання, або видалив зайвий шаблон.
13
+ Визначає список файлів шаблонів, що знаходяться у каталогах `fix` та `policy`, які не є цільовими посиланнями у файлі `<id>.mdc` як markdown link targets. Це дозволяє ідентифікувати ресурси шаблонів, які не були згадані в контексті правила.
12
14
 
13
- Модуль повністю асинхронний (використовує `node:fs/promises`), стандартної залежності від сторонніх бібліотек не має, працює у середовищі Node.js (а також сумісне з Bun) як ES-модуль (`.mjs`).
15
+ ## Поведінка
14
16
 
15
- ## Експорти / API
17
+ 1. Збирає абсолютні шляхи всіх файлів, що знаходяться у каталогах `template` всередині підкаталогів `fix` та `policy` у вказаному каталозі правила.
18
+ 2. Зчитує вміст файлу `main.mdc` у каталозі правила.
19
+ 3. Фільтрує зібрані шляхи, залишаючи лише ті, які не з'являються у вмісті `main.mdc` у вигляді посилання Markdown (`./<шлях>` або ``).
20
+ 4. Повертає відносні шляхи цих незгаданих шаблонних файлів відносно каталогу правила.
16
21
 
17
- Модуль експортує єдину функцію:
22
+ ## Гарантії поведінки
18
23
 
19
- - `findMissingMdcRefs(ruleDir, ruleId)` публічний експорт (`export async function`).
20
-
21
- Дві внутрішні (не експортовані) допоміжні функції:
22
-
23
- - `walkTemplateDirs(ruleDir)` — обходить підкаталоги `fix/*/template/` і `policy/*/template/`.
24
- - `collectFiles(dir)` — рекурсивно збирає всі файли в заданому каталозі.
25
-
26
- Імпорти з ядра Node:
27
-
28
- - `existsSync` з `node:fs` — синхронна перевірка існування шляху.
29
- - `readdir`, `readFile`, `stat` з `node:fs/promises` — асинхронні операції з файловою системою.
30
- - `join`, `relative` з `node:path` — нормалізація та побудова шляхів.
31
-
32
- ## Функції
33
-
34
- ### findMissingMdcRefs
35
-
36
- Сигнатура:
37
-
38
- ```
39
- export async function findMissingMdcRefs(ruleDir, ruleId): Promise<string[]>
40
- ```
41
-
42
- Параметри:
43
-
44
- - `ruleDir` — `string`, абсолютний шлях до каталогу правила (за конвенцією `npm/rules/<id>/`).
45
- - `ruleId` — `string`, basename правила (наприклад, `"security"`). Використовується для побудови імені `.mdc`-файлу: `${ruleId}.mdc`.
46
-
47
- Що робить:
48
-
49
- 1. Будує очікуваний шлях до файлу правила: `mdcPath = join(ruleDir, `${ruleId}.mdc`)`.
50
- 2. Якщо файл `.mdc` не існує — повертає порожній масив `[]` (нічого перевіряти).
51
- 3. Читає текст `.mdc` у пам'ять як UTF-8 рядок.
52
- 4. Викликає `walkTemplateDirs(ruleDir)`, щоб отримати масив усіх файлів із `template/`-каталогів правила (як шляхи, відносні до `ruleDir`).
53
- 5. Фільтрує отриманий масив, залишаючи лише ті файли, посилань на які НЕ виявлено в тексті `.mdc`. Перевірка наявності посилання — підрядкова: файл вважається «посиланим», якщо в тексті `.mdc` зустрічається будь-яке з двох вкраплень:
54
- - `./<rel>` — типова форма markdown-посилання `[label](./path)`.
55
- - `(<rel>)` — також зловить голу форму `(path)` у круглих дужках.
56
-
57
- Повертає:
58
-
59
- - `Promise<string[]>` — масив відносних шляхів (відносно `ruleDir`) файлів шаблонів, на які в `.mdc` немає посилання.
60
-
61
- Side effects:
62
-
63
- - Виключно read-only доступ до файлової системи: `existsSync`, `readFile`, `readdir`, `stat`. Файли або каталоги не створюються, не змінюються, не видаляються.
64
- - Не виводить нічого в `stdout`/`stderr`. Не має побічних ефектів на process state.
65
-
66
- Помилки:
67
-
68
- - Може кинути помилку, якщо `readFile`/`readdir`/`stat` зазнають невдачі з причин, відмінних від «файл не існує» (наприклад, права доступу). Перед читанням існування `mdcPath` перевіряється явно, тому відсутність `.mdc` помилки не дає.
69
-
70
- ### walkTemplateDirs (внутрішня)
71
-
72
- Сигнатура:
73
-
74
- ```
75
- async function walkTemplateDirs(ruleDir): Promise<string[]>
76
- ```
77
-
78
- Параметри:
79
-
80
- - `ruleDir` — `string`, абсолютний шлях до каталогу правила.
81
-
82
- Що робить:
83
-
84
- 1. Ітерується по двох жорстко закодованих «kind»-категоріях: `'fix'` та `'policy'`.
85
- 2. Для кожного `kind` будує шлях `kindDir = join(ruleDir, kind)`. Якщо такого каталогу немає — пропускає.
86
- 3. Для кожного `concern` (підкаталога або файлу всередині `kindDir`, який повертає `readdir`) будує шлях `tpl = join(kindDir, concern, 'template')`.
87
- 4. Якщо `tpl` не існує — пропускає. Якщо існує, але не є каталогом (`stat(tpl).isDirectory() === false`) — також пропускає.
88
- 5. Викликає `collectFiles(tpl)` для рекурсивного збору всіх файлів і додає їх до результуючого масиву.
89
- 6. На виході перетворює абсолютні шляхи у шляхи, відносні до `ruleDir` (`relative(ruleDir, p)`).
90
-
91
- Повертає:
92
-
93
- - `Promise<string[]>` — відносні (від `ruleDir`) шляхи всіх файлів у `fix/*/template/` і `policy/*/template/`.
94
-
95
- Side effects:
96
-
97
- - Лише read-only ФС-операції.
98
-
99
- Примітка: значення `readdir(kindDir)` (без `withFileTypes`) повертає масив імен і файлів, і каталогів. Перевірка `existsSync(tpl)` та `stat(tpl).isDirectory()` коректно відсіює випадки, коли `concern` — це файл, а не каталог.
100
-
101
- ### collectFiles (внутрішня)
102
-
103
- Сигнатура:
104
-
105
- ```
106
- async function collectFiles(dir): Promise<string[]>
107
- ```
108
-
109
- Параметри:
110
-
111
- - `dir` — `string`, абсолютний шлях каталогу, який треба обійти.
112
-
113
- Що робить:
114
-
115
- 1. Викликає `readdir(dir, { withFileTypes: true })` і отримує `Dirent[]`.
116
- 2. Для кожного запису будує повний шлях `full = join(dir, entry.name)`.
117
- 3. Якщо запис — каталог (`entry.isDirectory()`), рекурсивно занурюється в нього й приєднує знайдене до результату.
118
- 4. Якщо запис — файл (або symlink/інше, що НЕ каталог), додає `full` як є.
119
-
120
- Повертає:
121
-
122
- - `Promise<string[]>` — абсолютні шляхи всіх файлів усередині `dir` (з усіх рівнів вкладеності).
123
-
124
- Side effects:
125
-
126
- - Read-only обхід ФС.
127
-
128
- Зауваження щодо поведінки: символьні посилання й сокети не каталогізуються як директорії (`isDirectory()` поверне `false`), отже потрапляють у список як «файли». Гранична глибина рекурсії не обмежена — для зацикленої структури symlinks теоретично можливе нескінченне занурення; на практиці шаблонні каталоги правил такого не мають.
129
-
130
- ## Залежності
131
-
132
- Стандартна бібліотека Node.js (ESM):
133
-
134
- - `node:fs` — `existsSync` (синхронна перевірка існування).
135
- - `node:fs/promises` — `readdir`, `readFile`, `stat` (асинхронні ФС-операції).
136
- - `node:path` — `join`, `relative` (нормалізація шляхів).
137
-
138
- Зовнішніх npm-залежностей немає. Модуль не використовує жодних глобальних змінних, конфігів, env-vars чи CLI-аргументів. Не звертається до мережі.
139
-
140
- Передумови оточення:
141
-
142
- - Node.js версія, що підтримує ES Modules (`.mjs`) і `node:`-protocol-imports (Node 14+; на практиці Node 18+/Bun).
143
- - Доступ на читання до каталогу `ruleDir` та його підкаталогів.
144
-
145
- ## Потік виконання / Використання
146
-
147
- ### Очікувана структура каталогу правила
148
-
149
- Модуль розрахований на конвенцію розкладки правил:
150
-
151
- ```
152
- <ruleDir>/
153
- <ruleId>.mdc ← текст правила з markdown-посиланнями
154
- fix/
155
- <concern-A>/
156
- template/
157
- file1.ext
158
- nested/file2.ext
159
- <concern-B>/
160
- template/
161
- ...
162
- policy/
163
- <concern-C>/
164
- template/
165
- ...
166
- ```
167
-
168
- Перелічуються лише файли всередині `fix/*/template/` і `policy/*/template/`. Будь-який інший контент (`check-*.mjs`, `README`, інші підкаталоги) ігнорується.
169
-
170
- ### Алгоритм у двох словах
171
-
172
- 1. Зібрати всі файли з `fix/*/template/` і `policy/*/template/`, перетворити у відносні шляхи від `ruleDir`.
173
- 2. Прочитати `<ruleId>.mdc`.
174
- 3. Для кожного відносного шляху перевірити, чи зустрічається в тексті `.mdc` хоча б одна з форм `./<rel>` або `(<rel>)`. Якщо НЕ зустрічається — додати у вихідний список.
175
-
176
- ### Типове використання
177
-
178
- ```js
179
- import { findMissingMdcRefs } from './check-mdc-template-refs.mjs'
180
-
181
- const missing = await findMissingMdcRefs('/abs/path/to/npm/rules/security', 'security')
182
- if (missing.length > 0) {
183
- console.error('Orphaned template files (no markdown link in .mdc):')
184
- for (const rel of missing) console.error(` - ${rel}`)
185
- process.exit(1)
186
- }
187
- ```
188
-
189
- Цей виклик часто є частиною check-скрипта правила (`check-<id>.mjs`) або агрегованого валідатора, який обходить усі правила репозиторію.
190
-
191
- ### Граничні випадки
192
-
193
- - `.mdc` відсутній — повертається `[]`. Це навмисно: правило без `.mdc` не валідуємо «на покинуті шаблони».
194
- - Каталоги `fix/`, `policy/`, `template/` відсутні — обходяться silent, результат для них порожній.
195
- - Шаблонів немає взагалі — повертається `[]`.
196
- - `.mdc` посилається на шаблон, якого фізично немає, — цей сценарій модуль НЕ перевіряє (зворотний напрям перевірки тут не реалізовано).
197
- - Перевірка посилань — підрядкова, без парсингу markdown. Якщо файл містить `./foo/bar.md` як випадковий збіг у документації, шаблон `foo/bar.md` буде вважатися посиланим, навіть якщо це не власне markdown-link. На практиці це не проблема, бо шляхи всередині `template/` достатньо унікальні.
198
- - Сепаратор шляхів — платформозалежний (`path.join`/`path.relative` використовують `\` на Windows). Усередині `.mdc` посилання, як правило, пишуть зі слешем `/` — на Windows це може давати хибно-позитивні результати (тобто файл буде вважатися «без посилання»). У цільовому оточенні (macOS/Linux/Docker) проблема не виникає.
199
-
200
- ### Складність
201
-
202
- - Час: O(N + M), де N — сумарна кількість файлів у `template/`-каталогах, а M — довжина тексту `.mdc` (через `String.prototype.includes`, що виконується для кожного з N файлів двічі).
203
- - Пам'ять: лінійна щодо розміру `.mdc` плюс масиву шляхів.
204
-
205
- ## Rebuild Test
206
-
207
- Файл `check-mdc-template-refs.mjs` можна повністю відновити, дотримуючись опису вище, якщо забезпечити такі властивості:
208
-
209
- 1. ES-модуль (`.mjs`), без `default export`. Єдиний `export` — `async function findMissingMdcRefs(ruleDir, ruleId)`.
210
- 2. Імпорти лише з `node:fs` (`existsSync`), `node:fs/promises` (`readdir`, `readFile`, `stat`) і `node:path` (`join`, `relative`).
211
- 3. Дві внутрішні async-функції: `walkTemplateDirs(ruleDir)` та `collectFiles(dir)`.
212
- 4. `walkTemplateDirs` ітерується по двох категоріях у фіксованому порядку: спочатку `'fix'`, потім `'policy'`. Пропускає неіснуючі `kindDir`. Для кожного `concern` перевіряє існування й те, що `template` — каталог; у разі успіху делегує до `collectFiles`. На виході конвертує абсолютні шляхи у відносні від `ruleDir`.
213
- 5. `collectFiles` використовує `readdir(dir, { withFileTypes: true })`, рекурсивно занурюється тільки в каталоги, інші записи додає в результат як абсолютні шляхи.
214
- 6. `findMissingMdcRefs` спочатку перевіряє існування `<ruleId>.mdc`, читає його у UTF-8, отримує всі файли через `walkTemplateDirs`, потім фільтрує, залишаючи лише ті `rel`, для яких у тексті `.mdc` ОДНОЧАСНО немає `./<rel>` і немає `(<rel>)` (логічне AND через подвійне заперечення з `||` під `!`).
215
- 7. Поведінка строго read-only: жодних запитів у мережу, жодного запису на диск, жодного консольного виводу.
216
- 8. Повертає `Promise<string[]>`, відносні шляхи (з POSIX/платформозалежним сепаратором у міру `path.relative`).
217
-
218
- Тестові сценарії для smoke-перевірки:
219
-
220
- - Каталог без `.mdc` → `[]`.
221
- - `.mdc` є, але `fix/`, `policy/` відсутні → `[]`.
222
- - `fix/x/template/a.txt` існує, у `.mdc` згадано `./fix/x/template/a.txt` → `[]`.
223
- - Той самий шаблон, але `.mdc` посилається як `(fix/x/template/a.txt)` (без `./`) → `[]`.
224
- - Той самий шаблон, але в `.mdc` посилання немає → `['fix/x/template/a.txt']`.
225
- - Вкладений `fix/x/template/sub/b.txt`, посилання немає → містить `'fix/x/template/sub/b.txt'`.
226
- - Запис `concern`, що насправді є файлом, а не каталогом → пропускається без помилки.
24
+ - Read-only: не виконує операцій запису (ФС/БД).
@@ -6,40 +6,40 @@ resource: npm/scripts/lib/
6
6
 
7
7
  # npm/scripts/lib
8
8
 
9
- | Файл | Тип |
10
- | --------------------------------------------------------------------------- | --------- |
11
- | [assert-project-root.mjs](assert-project-root.md) | JS Module |
12
- | [changed-files.mjs](changed-files.md) | JS Module |
13
- | [check-mdc-template-refs.mjs](check-mdc-template-refs.md) | JS Module |
14
- | [check-reporter.mjs](check-reporter.md) | JS Module |
15
- | [diff-added-lines.mjs](diff-added-lines.md) | JS Module |
9
+ | Файл | Тип |
10
+ |---|---|
11
+ | [assert-project-root.mjs](assert-project-root.md) | JS Module |
12
+ | [changed-files.mjs](changed-files.md) | JS Module |
13
+ | [check-mdc-template-refs.mjs](check-mdc-template-refs.md) | JS Module |
14
+ | [check-reporter.mjs](check-reporter.md) | JS Module |
15
+ | [diff-added-lines.mjs](diff-added-lines.md) | JS Module |
16
16
  | [discover-check-rules-from-cursor.mjs](discover-check-rules-from-cursor.md) | JS Module |
17
- | [discover-checkable-rules.mjs](discover-checkable-rules.md) | JS Module |
18
- | [ensure-tool.mjs](ensure-tool.md) | JS Module |
19
- | [generated-markdown.mjs](generated-markdown.md) | JS Module |
20
- | [gha-workflow.mjs](gha-workflow.md) | JS Module |
21
- | [inline-template-links.mjs](inline-template-links.md) | JS Module |
22
- | [list-project-rules-mdc.mjs](list-project-rules-mdc.md) | JS Module |
23
- | [list-rule-ids.mjs](list-rule-ids.md) | JS Module |
24
- | [load-cursor-config.mjs](load-cursor-config.md) | JS Module |
25
- | [mirror-parity.mjs](mirror-parity.md) | JS Module |
26
- | [read-n-cursor-config-lite.mjs](read-n-cursor-config-lite.md) | JS Module |
27
- | [resolve-target-files.mjs](resolve-target-files.md) | JS Module |
28
- | [root-notice.mjs](root-notice.md) | JS Module |
29
- | [rule-meta-helpers.mjs](rule-meta-helpers.md) | JS Module |
30
- | [rule-meta.mjs](rule-meta.md) | JS Module |
31
- | [rule-predicates.mjs](rule-predicates.md) | JS Module |
32
- | [run-conftest-batch.mjs](run-conftest-batch.md) | JS Module |
33
- | [run-lint-step.mjs](run-lint-step.md) | JS Module |
34
- | [run-lint.mjs](run-lint.md) | JS Module |
35
- | [run-rule-cli.mjs](run-rule-cli.md) | JS Module |
36
- | [run-rule.mjs](run-rule.md) | JS Module |
37
- | [run-standard-lint.mjs](run-standard-lint.md) | JS Module |
38
- | [run-standard-rule.mjs](run-standard-rule.md) | JS Module |
39
- | [skill-meta.mjs](skill-meta.md) | JS Module |
40
- | [sync-gitignore-worktree.mjs](sync-gitignore-worktree.md) | JS Module |
41
- | [template.mjs](template.md) | JS Module |
42
- | [timing-summary.mjs](timing-summary.md) | JS Module |
43
- | [workspaces.mjs](workspaces.md) | JS Module |
44
- | [worktree-notice.mjs](worktree-notice.md) | JS Module |
45
- | [worktree.mjs](worktree.md) | JS Module |
17
+ | [discover-checkable-rules.mjs](discover-checkable-rules.md) | JS Module |
18
+ | [ensure-tool.mjs](ensure-tool.md) | JS Module |
19
+ | [generated-markdown.mjs](generated-markdown.md) | JS Module |
20
+ | [gha-workflow.mjs](gha-workflow.md) | JS Module |
21
+ | [inline-template-links.mjs](inline-template-links.md) | JS Module |
22
+ | [list-project-rules-mdc.mjs](list-project-rules-mdc.md) | JS Module |
23
+ | [list-rule-ids.mjs](list-rule-ids.md) | JS Module |
24
+ | [load-cursor-config.mjs](load-cursor-config.md) | JS Module |
25
+ | [mirror-parity.mjs](mirror-parity.md) | JS Module |
26
+ | [read-n-cursor-config-lite.mjs](read-n-cursor-config-lite.md) | JS Module |
27
+ | [resolve-target-files.mjs](resolve-target-files.md) | JS Module |
28
+ | [root-notice.mjs](root-notice.md) | JS Module |
29
+ | [rule-meta-helpers.mjs](rule-meta-helpers.md) | JS Module |
30
+ | [rule-meta.mjs](rule-meta.md) | JS Module |
31
+ | [rule-predicates.mjs](rule-predicates.md) | JS Module |
32
+ | [run-conftest-batch.mjs](run-conftest-batch.md) | JS Module |
33
+ | [run-lint-step.mjs](run-lint-step.md) | JS Module |
34
+ | [run-lint.mjs](run-lint.md) | JS Module |
35
+ | [run-rule-cli.mjs](run-rule-cli.md) | JS Module |
36
+ | [run-rule.mjs](run-rule.md) | JS Module |
37
+ | [run-standard-lint.mjs](run-standard-lint.md) | JS Module |
38
+ | [run-standard-rule.mjs](run-standard-rule.md) | JS Module |
39
+ | [skill-meta.mjs](skill-meta.md) | JS Module |
40
+ | [sync-gitignore-worktree.mjs](sync-gitignore-worktree.md) | JS Module |
41
+ | [template.mjs](template.md) | JS Module |
42
+ | [timing-summary.mjs](timing-summary.md) | JS Module |
43
+ | [workspaces.mjs](workspaces.md) | JS Module |
44
+ | [worktree-notice.mjs](worktree-notice.md) | JS Module |
45
+ | [worktree.mjs](worktree.md) | JS Module |