@nitra/cursor 10.0.0 → 10.0.1
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.
- package/CHANGELOG.md +6 -0
- package/package.json +1 -1
- package/rules/lint/docs/fix.md +27 -0
- package/rules/lint/js/docs/orchestrate.md +12 -10
- package/rules/text/lint/docs/cspell-fix.md +28 -0
- package/rules/text/lint/docs/lint.md +24 -212
- package/scripts/lib/docs/list-project-rules-mdc.md +28 -0
- package/scripts/lib/fix/docs/llm-fix-apply.md +31 -0
- package/scripts/lib/fix/docs/llm-lint-fix.md +33 -0
- package/scripts/lib/fix/docs/llm-worker.md +11 -15
- package/scripts/lib/fix/docs/orchestrator.md +11 -28
- package/scripts/lib/fix/docs/run-fix-check.md +34 -0
- package/scripts/lib/fix/docs/t0.md +12 -20
package/CHANGELOG.md
CHANGED
package/package.json
CHANGED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
---
|
|
2
|
+
docgen:
|
|
3
|
+
source: npm/rules/lint/fix.mjs
|
|
4
|
+
crc: f85a9e1d
|
|
5
|
+
model: omlx/gemma-4-e4b-it-OptiQ-4bit
|
|
6
|
+
score: 100
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# fix.mjs
|
|
10
|
+
|
|
11
|
+
## Огляд
|
|
12
|
+
|
|
13
|
+
Модуль забезпечує виконання логіки, визначеної правилом. Він ініціює виконання правила через публічну функцію `run`.
|
|
14
|
+
|
|
15
|
+
## Поведінка
|
|
16
|
+
|
|
17
|
+
1. Викликати функцію `run` для виконання логіки правила.
|
|
18
|
+
2. Якщо код виконується як CLI, викликати функцію для запуску правила через CLI.
|
|
19
|
+
|
|
20
|
+
## Публічний API
|
|
21
|
+
|
|
22
|
+
run — виконує правило `lint` в lint-оркестраторі. Якщо правило не містить перевірок (concern-ів/policy), то `run` не робить нічого (no-op), оскільки не знаходить жодних concern-ів.
|
|
23
|
+
|
|
24
|
+
## Гарантії поведінки
|
|
25
|
+
|
|
26
|
+
- Read-only: файл не виконує операцій запису у файлову систему.
|
|
27
|
+
- Не звертається до мережі.
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
docgen:
|
|
3
|
-
source: rules/lint/js/orchestrate.mjs
|
|
4
|
-
crc:
|
|
3
|
+
source: npm/rules/lint/js/orchestrate.mjs
|
|
4
|
+
crc: 2e5db1e7
|
|
5
|
+
model: omlx/gemma-4-e4b-it-OptiQ-4bit
|
|
5
6
|
score: 100
|
|
6
7
|
---
|
|
7
8
|
|
|
@@ -9,20 +10,21 @@ docgen:
|
|
|
9
10
|
|
|
10
11
|
## Огляд
|
|
11
12
|
|
|
12
|
-
|
|
13
|
+
Оркестратор `n-cursor lint` визначає, які правила лінтування застосовувати, керуючись двома ортогональними осями: консолідацією правил та уніфікацією режиму `readonly`. Вибір правил відбувається на основі конфігурацій, зокрема файлів `meta.json`, які визначають обсяг дії (`per-file` чи `full`) для кожного правила. Запуск лінтування може сканувати лише змінені файли відносно origin (за замовчуванням) або весь репозиторій при використанні прапорця `--full`.
|
|
13
14
|
|
|
14
15
|
## Поведінка
|
|
15
16
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
runLint
|
|
20
|
-
Запускає lint-оркестрацію
|
|
17
|
+
Поведінка
|
|
18
|
+
selectLintRules вибирає і сортує ідентифікатори правил на основі їхнього обсягу дії (`per-file` або `full`) та прапорця `--full`.
|
|
19
|
+
runLint запускає оркестрацію лінтування: або виконує перевірку конформності для заданих правил, або ітерує по алфавітно відсортованих правилах, запускаючи лінтер для змінених файлів (за замовчуванням), або виконує перевірку конформності всього репозиторію при використанні прапорця `--full`.
|
|
21
20
|
|
|
22
21
|
## Публічний API
|
|
23
22
|
|
|
24
|
-
selectLintRules — Вибирає
|
|
25
|
-
runLint — Запускає
|
|
23
|
+
selectLintRules — Вибирає ідентифікатори правил для контексту в алфавітному порядку.
|
|
24
|
+
runLint — Запускає процес лінтування.
|
|
25
|
+
full — Сканує весь репозиторій порівняно з початковим станом.
|
|
26
|
+
readOnly — Виявляє проблеми без внесення змін.
|
|
27
|
+
rules — Перевіряє лише відповідність заданого набору правил, ігноруючи повне сканування.
|
|
26
28
|
|
|
27
29
|
## Гарантії поведінки
|
|
28
30
|
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
---
|
|
2
|
+
docgen:
|
|
3
|
+
source: npm/rules/text/lint/cspell-fix.mjs
|
|
4
|
+
crc: 3ce66d8a
|
|
5
|
+
model: omlx/gemma-4-e4b-it-OptiQ-4bit
|
|
6
|
+
score: 90
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# cspell-fix.mjs
|
|
10
|
+
|
|
11
|
+
## Огляд
|
|
12
|
+
|
|
13
|
+
Модуль інтегрує `cspell` у ланцюжок `lint-text` для виявлення орфографічних помилок. У режимі з можливістю виправлення, процес відбувається шляхом: детект (захоплення виводу) $\rightarrow$ групування знахідок по файлах $\rightarrow$ per-file `omlx-фікс` справжніх помилок (`llmLintFix`) $\rightarrow$ re-detect. У read-only режимі виконується лише детект, що гарантує нуль мутацій. Валідні терміни omlx залишаються, їх ловить повторний `cspell` (далі — у словник `@nitra/cspell-dict`).
|
|
14
|
+
|
|
15
|
+
## Поведінка
|
|
16
|
+
|
|
17
|
+
groupFindingsByFile групує вивід `cspell` за файлами, виділяючи знахідки.
|
|
18
|
+
runCspellText запускає `cspell` для виявлення орфографічних помилок, а при вимкненому режимі читання виконує автоматичне виправлення помилок за допомогою зовнішнього інструменту для файлів, що містять справжні помилки, і повторно перевіряє файли.
|
|
19
|
+
|
|
20
|
+
## Публічний API
|
|
21
|
+
|
|
22
|
+
groupFindingsByFile — збирає знайдені помилки cspell у групи за файлами.
|
|
23
|
+
runCspellText — виконує перевірку тексту за правилами cspell, застосовуючи автоматичне виправлення від omlx.
|
|
24
|
+
|
|
25
|
+
## Гарантії поведінки
|
|
26
|
+
|
|
27
|
+
- Read-only: файл не виконує операцій запису у файлову систему.
|
|
28
|
+
- Не звертається до мережі.
|
|
@@ -1,226 +1,38 @@
|
|
|
1
1
|
---
|
|
2
2
|
docgen:
|
|
3
3
|
source: npm/rules/text/lint/lint.mjs
|
|
4
|
-
crc:
|
|
4
|
+
crc: d475ffbb
|
|
5
|
+
model: omlx/gemma-4-e4b-it-OptiQ-4bit
|
|
6
|
+
score: 90
|
|
5
7
|
---
|
|
6
8
|
|
|
7
|
-
#
|
|
9
|
+
# lint.mjs
|
|
8
10
|
|
|
9
11
|
## Огляд
|
|
10
12
|
|
|
11
|
-
|
|
13
|
+
runLintTextCli надає CLI-обгортку для послідовного лінтингу текстових файлів (text.mdc). Обгортка автоматично встановлює необхідні інструменти (`shellcheck`, `dotenv-linter`) через `ensureTool` перед виконанням ланцюжка перевірок. Ланцюжок включає: перевірку правопису (`cspell`), аналіз скриптів (`shellcheck`), перевірку конфігураційних файлів (`dotenv-linter`), форматування Markdown (`markdownlint-cli2`) та валідацію схем (`v8r`). При виявленні першого ненульового коду в ланцюжку, цей код повертається як код виходу, і подальші кроки не виконуються. runLintTextCli експортується для використання як підкоманда `lint-text` з `bin/n-cursor.js`.
|
|
12
14
|
|
|
13
|
-
|
|
15
|
+
## Поведінка
|
|
14
16
|
|
|
15
|
-
1.
|
|
16
|
-
2.
|
|
17
|
-
3.
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
17
|
+
1. Викликається `runLintTextCli` для запуску процесу лінтингу.
|
|
18
|
+
2. Якщо передано опцію для режиму лише перевірки, всі кроки виконуються без автоматичного виправлення.
|
|
19
|
+
3. Перед виконанням лінтингу автоматично встановлюються необхідні інструменти (`shellcheck`, `dotenv-linter`).
|
|
20
|
+
4. Перевіряється наявність інструменту `patch` для можливого автоматичного виправлення помилок `shellcheck`.
|
|
21
|
+
5. Виконується перевірка правопису за допомогою `cspell`.
|
|
22
|
+
6. Виконується автоматичне виправлення та фінальна перевірка скриптів `.sh` за допомогою `shellcheck`.
|
|
23
|
+
7. Виконується автоматичне виправлення та фінальна перевірка файлів `.env*` за допомогою `dotenv-linter`.
|
|
24
|
+
8. Виконується автоматичне виправлення файлів Markdown (`.md`, `.mdc`) за допомогою `markdownlint-cli2`.
|
|
25
|
+
9. Виконується валідація схем для файлів JSON, JSON5, YAML, YML, TOML за допомогою `v8r`.
|
|
26
|
+
10. Якщо будь-який крок повертає ненульовий код, виконання зупиняється, і повертається код цього першого невдалого кроку.
|
|
27
|
+
11. У разі успішного виконання всіх кроків повертається код 0.
|
|
28
|
+
12. У разі відсутності необхідних бінарників, `runLintTextCli` виводить повідомлення про помилку з інструкціями щодо встановлення (text.mdc).
|
|
24
29
|
|
|
25
|
-
|
|
30
|
+
## Публічний API
|
|
26
31
|
|
|
27
|
-
|
|
32
|
+
runLintTextCli — Виконує лінтинг тексту через командний інтерфейс, синхронізуючи доступ за допомогою блокування та усуваючи дублікати на основі стану Git-дерева. (text.mdc)
|
|
28
33
|
|
|
29
|
-
##
|
|
34
|
+
## Гарантії поведінки
|
|
30
35
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
Інші ідентифікатори модуля (`PATCH_PREFLIGHT`, `resolvePreflightBin`, `printPreflightMissingMessage`, `preflight`, `runLintTextSteps`) — внутрішні; не експортуються і не призначені для зовнішнього використання.
|
|
36
|
-
|
|
37
|
-
## Функції
|
|
38
|
-
|
|
39
|
-
### `resolvePreflightBin(dep)`
|
|
40
|
-
|
|
41
|
-
Шукає шлях до бінарника `dep.bin` у `PATH`. На Windows (`process.platform === 'win32'`) додатково перебирає альтернативні імена з `dep.winBins` (наприклад, для випадків з `.exe`/`.cmd` варіаціями).
|
|
42
|
-
|
|
43
|
-
- Сигнатура: `function resolvePreflightBin(dep: PreflightDep): string | null`
|
|
44
|
-
- Параметри:
|
|
45
|
-
- `dep` — опис залежності з canon-списку preflight-перевірок (тип `PreflightDep`).
|
|
46
|
-
- Повертає: абсолютний шлях до знайденого бінарника або `null`, якщо бінарник не знайдено.
|
|
47
|
-
- Side effects: відсутні (виклик `resolveCmd` лише читає `PATH`, не модифікує процес).
|
|
48
|
-
|
|
49
|
-
### `printPreflightMissingMessage(dep)`
|
|
50
|
-
|
|
51
|
-
Друкує stderr-повідомлення про відсутній бінарник: рядок-маркер з іменем, пояснення наслідків, install-команди і посилання на правило `text.mdc`.
|
|
52
|
-
|
|
53
|
-
- Сигнатура: `function printPreflightMissingMessage(dep: PreflightDep): void`
|
|
54
|
-
- Параметри:
|
|
55
|
-
- `dep` — опис залежності, джерело пояснення (`dep.explanation`) та install-команд (`dep.install`).
|
|
56
|
-
- Повертає: нічого (`undefined`).
|
|
57
|
-
- Side effects: виводить кілька рядків у `console.error` (stderr). Структура виводу:
|
|
58
|
-
- `❌ <bin> не знайдено в PATH.`
|
|
59
|
-
- відступний рядок з `dep.explanation`;
|
|
60
|
-
- заголовок ` Встанови:`;
|
|
61
|
-
- по рядку для кожного елемента `dep.install`;
|
|
62
|
-
- підказку ` Деталі: text.mdc → секція про lint-text.`
|
|
63
|
-
|
|
64
|
-
### `preflight(dep)`
|
|
65
|
-
|
|
66
|
-
Виконує preflight-перевірку наявності бінарника й сигналізує результат через консоль.
|
|
67
|
-
|
|
68
|
-
- Сигнатура: `function preflight(dep: PreflightDep): boolean`
|
|
69
|
-
- Параметри:
|
|
70
|
-
- `dep` — опис залежності для перевірки в `PATH`.
|
|
71
|
-
- Повертає: `true`, якщо бінарник знайдено; `false`, якщо відсутній.
|
|
72
|
-
- Side effects:
|
|
73
|
-
- На pass-шляху друкує `dep.successMsg` у `console.log`;
|
|
74
|
-
- На fail-шляху викликає `printPreflightMissingMessage(dep)` (вивід у `console.error`).
|
|
75
|
-
|
|
76
|
-
### `runLintTextSteps()`
|
|
77
|
-
|
|
78
|
-
Внутрішня функція, що послідовно прокручує всі кроки `lint-text` без захоплення локу (лок забезпечується зовнішньою обгорткою `runStandardLint`).
|
|
79
|
-
|
|
80
|
-
- Сигнатура: `function runLintTextSteps(): number`
|
|
81
|
-
- Параметри: немає.
|
|
82
|
-
- Повертає: `0`, якщо всі кроки успішні; інакше — exit-код першого кроку, що повернув ненульове значення.
|
|
83
|
-
- Алгоритм:
|
|
84
|
-
1. `ensureTool('shellcheck')` — авто-встановлення `shellcheck`; кидає виключення на провал (поширюється як exit `1` через зовнішній `runStandardLint`).
|
|
85
|
-
2. `ensureTool('dotenv-linter')` — те саме для `dotenv-linter`.
|
|
86
|
-
3. `preflight(PATCH_PREFLIGHT)` — hint-only перевірка `patch`; якщо `patch` відсутній — повертає `1` без подальших спроб.
|
|
87
|
-
4. `runLintStep('cspell', 'npx', ['cspell', '.'])` — `cspell .` через `npx`; ранній return при ненульовому коді.
|
|
88
|
-
5. Друк заголовку `▶ shellcheck (авто-фікс + фінальна перевірка *.sh)` і виклик `runShellcheckText()`; ранній return при ненульовому коді.
|
|
89
|
-
6. Друк заголовку `▶ dotenv-linter (авто-фікс + фінальна перевірка .env*)` і виклик `runDotenvLinter()`; ранній return при ненульовому коді.
|
|
90
|
-
7. `runLintStep('markdownlint', 'bunx', ['markdownlint-cli2', '--fix', '**/*.md', '**/*.mdc'])` — авто-фікс Markdown; ранній return при ненульовому коді.
|
|
91
|
-
8. Друк заголовку `▶ v8r (schema-валідація json/json5/yaml/yml/toml)` і повернення результату `runV8rWithGlobs()` як підсумкового exit-коду.
|
|
92
|
-
- Side effects: записує лог-рядки у `stdout`; запускає дочірні процеси через `runLintStep` / `ensureTool` / спеціалізовані обгортки; модифікує файлову систему через авто-фікс-кроки (`shellcheck -f diff` + `patch -p1`, `dotenv-linter --fix`, `markdownlint-cli2 --fix`).
|
|
93
|
-
|
|
94
|
-
### `runLintTextCli` (експорт)
|
|
95
|
-
|
|
96
|
-
Публічна CLI-форма команди.
|
|
97
|
-
|
|
98
|
-
- Сигнатура: `const runLintTextCli: () => Promise<number>`
|
|
99
|
-
- Параметри: немає.
|
|
100
|
-
- Повертає: `Promise<number>` — фінальний exit-код прогону (після lock + дедупу).
|
|
101
|
-
- Реалізація: делегує до `runStandardLint(import.meta.dirname, () => runLintTextSteps())`, тобто:
|
|
102
|
-
- `runStandardLint` бере лок з ім'ям, похідним від директорії скрипту (`import.meta.dirname`);
|
|
103
|
-
- дедуплікує запуски за станом git-дерева (якщо нічого не змінилося з попереднього успішного прогону — повторного виконання не буде);
|
|
104
|
-
- всередині локу викликає `runLintTextSteps()`.
|
|
105
|
-
- Side effects: лок-файл, лог-рядки, дочірні процеси (через внутрішній `runLintTextSteps`).
|
|
106
|
-
|
|
107
|
-
## Типи
|
|
108
|
-
|
|
109
|
-
### `PreflightDep`
|
|
110
|
-
|
|
111
|
-
Опис однієї залежності preflight-блоку. Визначений локальним JSDoc `@typedef`-ом.
|
|
112
|
-
|
|
113
|
-
| Поле | Тип | Опис |
|
|
114
|
-
| ------------- | ----------------- | ---------------------------------------------------------------------------- |
|
|
115
|
-
| `bin` | `string` | Ім'я виконуваного файлу (POSIX-варіант). |
|
|
116
|
-
| `winBins` | `string[]` (опц.) | Альтернативні імена бінарника на Windows. |
|
|
117
|
-
| `explanation` | `string` | Наслідки відсутності бінарника (для людино-зрозумілого stderr-повідомлення). |
|
|
118
|
-
| `install` | `string[]` | Команди встановлення, по одному рядку на спосіб/платформу. |
|
|
119
|
-
| `successMsg` | `string` | Повідомлення для `console.log` на pass-шляху preflight. |
|
|
120
|
-
|
|
121
|
-
## Константи
|
|
122
|
-
|
|
123
|
-
### `PATCH_PREFLIGHT`
|
|
124
|
-
|
|
125
|
-
Єдиний об'єкт типу `PreflightDep`, що описує системний `patch` як hint-only залежність:
|
|
126
|
-
|
|
127
|
-
- `bin: 'patch'`;
|
|
128
|
-
- `explanation: 'Без `patch` не застосуються авто-виправлення shellcheck (`shellcheck -f diff`+`patch -p1`).'` (зібраний через `[...].join('\n ')` з одного елемента; результат — рівно одна логічна підказка з відступом сумісним з шаблоном виводу `printPreflightMissingMessage`);
|
|
129
|
-
- `install`:
|
|
130
|
-
- `'macOS: зазвичай уже є в системі'`;
|
|
131
|
-
- `'Debian/Ubuntu: sudo apt-get install -y patch'`;
|
|
132
|
-
- `successMsg: '✅ patch знайдено в PATH — shellcheck auto-fix працюватиме'`.
|
|
133
|
-
|
|
134
|
-
`winBins` не задано — на Windows для `patch` шукається лише власне ім'я.
|
|
135
|
-
|
|
136
|
-
## Залежності
|
|
137
|
-
|
|
138
|
-
### Зовнішні модулі (Node built-ins)
|
|
139
|
-
|
|
140
|
-
- `node:process` — імпортується іменована змінна `platform` для детекції Windows у `resolvePreflightBin`.
|
|
141
|
-
|
|
142
|
-
### Внутрішні модулі (відносні імпорти)
|
|
143
|
-
|
|
144
|
-
| Модуль | Що використовується |
|
|
145
|
-
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
146
|
-
| `../../../scripts/lib/run-lint-step.mjs` | `runLintStep` — обгортка для запуску одного кроку лінту з префіксованим логом і нормалізованим exit-кодом. Використовується для `cspell` і `markdownlint`. |
|
|
147
|
-
| `../../../scripts/utils/resolve-cmd.mjs` | `resolveCmd` — пошук бінарника в `PATH`. Викликається з `resolvePreflightBin`. |
|
|
148
|
-
| `../../../scripts/lib/run-standard-lint.mjs` | `runStandardLint` — каноном обгортка `lint-*`: серіалізація через `withLock` + дедуп за станом git-дерева. Викликається з `runLintTextCli`. |
|
|
149
|
-
| `../../../scripts/lib/ensure-tool.mjs` | `ensureTool` — авто-встановлення бінарників (brew/scoop/GitHub Release). Викликається для `shellcheck` і `dotenv-linter` на початку `runLintTextSteps`. |
|
|
150
|
-
| `./run-dotenv-linter.mjs` | `runDotenvLinter` — авто-фікс + фінальна перевірка `.env*`. |
|
|
151
|
-
| `./run-shellcheck.mjs` | `runShellcheckText` — авто-фікс + фінальна перевірка `*.sh` через `shellcheck`. |
|
|
152
|
-
| `./run-v8r.mjs` | `runV8rWithGlobs` — schema-валідація `json/json5/yaml/yml/toml`. |
|
|
153
|
-
|
|
154
|
-
### Зовнішні CLI-інструменти (запускаються як дочірні процеси)
|
|
155
|
-
|
|
156
|
-
- `npx cspell .` — перевірка правопису (зі словником `@nitra/cspell-dict`).
|
|
157
|
-
- `shellcheck` — статичний аналізатор `*.sh` (передвстановлюється `ensureTool`).
|
|
158
|
-
- `dotenv-linter` — лінтер `.env*` (передвстановлюється `ensureTool`).
|
|
159
|
-
- `patch` — потрібен для `shellcheck -f diff | patch -p1` (hint-only, не встановлюється авто).
|
|
160
|
-
- `bunx markdownlint-cli2 --fix '**/*.md' '**/*.mdc'` — авто-фікс Markdown.
|
|
161
|
-
- `v8r` — schema-валідація конфігів (через `runV8rWithGlobs`).
|
|
162
|
-
|
|
163
|
-
### Правила-довідники
|
|
164
|
-
|
|
165
|
-
- `.cursor/rules/text.mdc` (`text.mdc`) — канонічний опис набору `lint-text`.
|
|
166
|
-
- `.cursor/rules/scripts.mdc` — секція «Серіалізація важких CLI-команд», що описує патерн `runStandardLint`/`withLock`.
|
|
167
|
-
|
|
168
|
-
## Потік виконання / Використання
|
|
169
|
-
|
|
170
|
-
### Виклик з CLI
|
|
171
|
-
|
|
172
|
-
Файл експортує `runLintTextCli`, який підключається з `bin/n-cursor.js` як підкоманда `lint-text`. Очікувана схема виклику:
|
|
173
|
-
|
|
174
|
-
```bash
|
|
175
|
-
n-cursor lint-text
|
|
176
|
-
```
|
|
177
|
-
|
|
178
|
-
Команда повертає exit-код процесу, рівний фінальному коду повернення з `runLintTextCli`.
|
|
179
|
-
|
|
180
|
-
### Послідовність кроків (happy path)
|
|
181
|
-
|
|
182
|
-
1. Зовнішній `runStandardLint` намагається взяти лок `lint-text`. Якщо лок вже зайнятий або стан git-дерева не змінився — прогон може дедуплікуватися або зачекати.
|
|
183
|
-
2. Всередині локу викликається `runLintTextSteps()`:
|
|
184
|
-
1. `ensureTool('shellcheck')` — авто-встановлення (на CI/локально).
|
|
185
|
-
2. `ensureTool('dotenv-linter')` — те саме.
|
|
186
|
-
3. `preflight(PATCH_PREFLIGHT)` — друкує `✅ patch знайдено в PATH — shellcheck auto-fix працюватиме` або hint про встановлення.
|
|
187
|
-
4. `cspell .` — друк префіксованих логів через `runLintStep`.
|
|
188
|
-
5. `▶ shellcheck (авто-фікс + фінальна перевірка *.sh)` → `runShellcheckText()`.
|
|
189
|
-
6. `▶ dotenv-linter (авто-фікс + фінальна перевірка .env*)` → `runDotenvLinter()`.
|
|
190
|
-
7. `markdownlint-cli2 --fix '**/*.md' '**/*.mdc'` через `bunx`.
|
|
191
|
-
8. `▶ v8r (schema-валідація json/json5/yaml/yml/toml)` → `runV8rWithGlobs()`; повертає його результат.
|
|
192
|
-
3. `runStandardLint` повертає підсумковий exit-код як `Promise<number>`.
|
|
193
|
-
|
|
194
|
-
### Семантика помилок
|
|
195
|
-
|
|
196
|
-
- Якщо `ensureTool` падає (не вдалося встановити `shellcheck` або `dotenv-linter`) — викидає виключення, яке поширюється з `runLintTextSteps` і обробляється на верхньому рівні (`runStandardLint`) як exit `1`.
|
|
197
|
-
- Якщо `patch` відсутній — `preflight` повертає `false`, `runLintTextSteps` повертає `1` ще до запуску `cspell`.
|
|
198
|
-
- Будь-який наступний крок (`cspell`, `shellcheck`, `dotenv-linter`, `markdownlint`, `v8r`), який повернув ненульовий код, припиняє ланцюжок: цей код повертається з `runLintTextSteps` і далі з `runLintTextCli`.
|
|
199
|
-
|
|
200
|
-
### Приклад використання у скрипті (Node)
|
|
201
|
-
|
|
202
|
-
```js
|
|
203
|
-
import { runLintTextCli } from './lint.mjs'
|
|
204
|
-
|
|
205
|
-
const code = await runLintTextCli()
|
|
206
|
-
process.exit(code)
|
|
207
|
-
```
|
|
208
|
-
|
|
209
|
-
### Побічні ефекти на файлову систему
|
|
210
|
-
|
|
211
|
-
Кроки `runShellcheckText`, `runDotenvLinter`, `markdownlint-cli2 --fix` і потенційно `v8r` можуть модифікувати файли (авто-фікс). Це штатна поведінка `lint-text` — після прогону можливі правки в робочому дереві.
|
|
212
|
-
|
|
213
|
-
## Rebuild Test
|
|
214
|
-
|
|
215
|
-
З цієї документації можна відновити поведінку модуля:
|
|
216
|
-
|
|
217
|
-
- Один експорт — асинхронна функція `runLintTextCli()` без параметрів, повертає `Promise<number>` (exit-код).
|
|
218
|
-
- Реалізація `runLintTextCli`: `() => runStandardLint(import.meta.dirname, () => runLintTextSteps())`.
|
|
219
|
-
- `runLintTextSteps()` синхронно:
|
|
220
|
-
1. викликає `ensureTool('shellcheck')` і `ensureTool('dotenv-linter')`;
|
|
221
|
-
2. виконує `preflight(PATCH_PREFLIGHT)` і повертає `1`, якщо `patch` відсутній;
|
|
222
|
-
3. послідовно запускає кроки `cspell` → `runShellcheckText` → `runDotenvLinter` → `markdownlint-cli2 --fix '**/*.md' '**/*.mdc'` → `runV8rWithGlobs`, друкуючи відповідні `▶`-заголовки перед shellcheck/dotenv/v8r;
|
|
223
|
-
4. ранній return на першому ненульовому коді; інакше повертає результат `runV8rWithGlobs()`.
|
|
224
|
-
- Допоміжні функції: `resolvePreflightBin` (з підтримкою `winBins` на Windows), `printPreflightMissingMessage` (формат stderr-повідомлення), `preflight` (об'єднання resolve+print і друк `successMsg` на pass).
|
|
225
|
-
- Константа `PATCH_PREFLIGHT` з полями `bin/explanation/install/successMsg` (без `winBins`).
|
|
226
|
-
- Залежності: `node:process` (`platform`); локальні модулі `run-lint-step`, `resolve-cmd`, `run-standard-lint`, `ensure-tool`, `run-dotenv-linter`, `run-shellcheck`, `run-v8r`.
|
|
36
|
+
- Read-only: файл не виконує операцій запису у файлову систему.
|
|
37
|
+
- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
|
|
38
|
+
- Не звертається до мережі.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
---
|
|
2
|
+
docgen:
|
|
3
|
+
source: npm/scripts/lib/list-project-rules-mdc.mjs
|
|
4
|
+
crc: e17e0855
|
|
5
|
+
model: omlx/gemma-4-e4b-it-OptiQ-4bit
|
|
6
|
+
score: 100
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# list-project-rules-mdc.mjs
|
|
10
|
+
|
|
11
|
+
## Огляд
|
|
12
|
+
|
|
13
|
+
Експортує константу CURSOR_RULES_DIR, яка вказує на каталог правил у проєкті-споживачі. Надає функцію для отримання відсортованого списку всіх файлів правил `.mdc` з цього каталогу.
|
|
14
|
+
|
|
15
|
+
## Поведінка
|
|
16
|
+
|
|
17
|
+
CURSOR_RULES_DIR — Вказує на каталог правил у проєкті-споживачі.
|
|
18
|
+
listProjectRulesMdcFiles — Повертає відсортований список імен файлів з розширенням `.mdc` у каталозі правил проєкту, або порожній масив, якщо каталог не існує.
|
|
19
|
+
|
|
20
|
+
## Публічний API
|
|
21
|
+
|
|
22
|
+
CURSOR_RULES_DIR — Шлях до каталогу правил у проєкті-споживачі.
|
|
23
|
+
listProjectRulesMdcFiles — Збирає список файлів MDC, що містять правила проєкту.
|
|
24
|
+
|
|
25
|
+
## Гарантії поведінки
|
|
26
|
+
|
|
27
|
+
- Read-only: файл не виконує операцій запису у файлову систему.
|
|
28
|
+
- Не звертається до мережі.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
---
|
|
2
|
+
docgen:
|
|
3
|
+
source: npm/scripts/lib/fix/llm-fix-apply.mjs
|
|
4
|
+
crc: 80befb00
|
|
5
|
+
model: omlx/gemma-4-e4b-it-OptiQ-4bit
|
|
6
|
+
score: 100
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# llm-fix-apply.mjs
|
|
10
|
+
|
|
11
|
+
## Огляд
|
|
12
|
+
|
|
13
|
+
Модуль є спільним ядром для застосування виправлень, згенерованих LLM, використовуючи конформні (`llm-worker.mjs`) та інструментальні (`llm-lint-fix.mjs`) механізми для уникнення дублювання логіки парсингу та застосування змін. Він парсить структуровану відповідь моделі, що містить список змін у форматі `{changes:[{path,content}]}`. Далі, він зчитує вміст файлів, зазначених у цих змінах, та застосовує оновлений вміст до відповідних файлів. Усі операції реалізовані з механізмом fail-safe: при невдачах функції повертають значення помилки (false/null/Err) замість викидання винятків.
|
|
14
|
+
|
|
15
|
+
## Поведінка
|
|
16
|
+
|
|
17
|
+
parseChangesResponse парсить сирий текст відповіді моделі, щоб витягнути структуру змін у форматі патчу або повернути null у разі невдачі парсингу.
|
|
18
|
+
readFilesForFix зчитує вміст файлів, зазначених у списку відносних шляхів, відносно кореня проєкту, повертаючи список об'єктів з шляхом та вмістом або null для неіснуючих файлів.
|
|
19
|
+
applyChanges записує нові вмісти в файли, використовуючи наданий список змін, відносно кореня проєкту, повертаючи статус успіху або помилки.
|
|
20
|
+
|
|
21
|
+
## Публічний API
|
|
22
|
+
|
|
23
|
+
parseChangesResponse — витягує структуру змін із JSON-відповіді моделі.
|
|
24
|
+
readFilesForFix — зчитує вміст файлів за заданими шляхами для використання у запиті.
|
|
25
|
+
applyChanges — замінює вміст файлів на нові дані, отримані у змінних змін.
|
|
26
|
+
|
|
27
|
+
## Гарантії поведінки
|
|
28
|
+
|
|
29
|
+
- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
|
|
30
|
+
- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
|
|
31
|
+
- Не звертається до мережі.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
---
|
|
2
|
+
docgen:
|
|
3
|
+
source: npm/scripts/lib/fix/llm-lint-fix.mjs
|
|
4
|
+
crc: de4439e9
|
|
5
|
+
model: omlx/gemma-4-e4b-it-OptiQ-4bit
|
|
6
|
+
score: 90
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# llm-lint-fix.mjs
|
|
10
|
+
|
|
11
|
+
## Огляд
|
|
12
|
+
|
|
13
|
+
Модуль реалізує механізм `omlx-фікс` для обробки знахідок лінтера, що стосуються `detect-only` тулів, які не мають нативного механізму виправлення (відповідно до `lint-orchestrator-fix-readonly`). Він зчитує уражені файли, ініціює запит до моделі через `callLlm` (маршрутизація через `omlx/<model>` з фолбеком каскаду), щоб отримати пропоновані зміни. Ці зміни застосовуються до файлової системи за допомогою спільного ядра `llm-fix-apply`.
|
|
14
|
+
|
|
15
|
+
## Поведінка
|
|
16
|
+
|
|
17
|
+
1. Зчитує вміст файлів, зазначених у `filePaths`, використовуючи `projectRoot`.
|
|
18
|
+
2. Формує детальний запит для моделі, включаючи назву тула, інструкцію, сирий вивід знахідок та вміст зчитаних файлів.
|
|
19
|
+
3. Надсилає сформований запит до моделі для отримання виправлень.
|
|
20
|
+
4. Парсить відповідь моделі для вилучення пропонованих змін.
|
|
21
|
+
5. Перевіряє, чи містить відповідь помилку або не містить жодних змін.
|
|
22
|
+
6. Застосовує вилучені зміни до файлової системи, використовуючи `projectRoot`.
|
|
23
|
+
7. Повертає результат виконання `llmLintFix`, що включає статус успіху, можливу помилку або список шляхів, які були успішно виправлені.
|
|
24
|
+
|
|
25
|
+
## Публічний API
|
|
26
|
+
|
|
27
|
+
llmLintFix — автоматично виправляє помилки, знайдені лінтером, використовуючи omlx.
|
|
28
|
+
|
|
29
|
+
## Гарантії поведінки
|
|
30
|
+
|
|
31
|
+
- Read-only: файл не виконує операцій запису у файлову систему.
|
|
32
|
+
- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
|
|
33
|
+
- Не звертається до мережі.
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
docgen:
|
|
3
|
-
source: npm/
|
|
4
|
-
crc:
|
|
3
|
+
source: npm/scripts/lib/fix/llm-worker.mjs
|
|
4
|
+
crc: 00730451
|
|
5
|
+
model: omlx/gemma-4-e4b-it-OptiQ-4bit
|
|
5
6
|
score: 100
|
|
6
7
|
---
|
|
7
8
|
|
|
@@ -9,27 +10,22 @@ docgen:
|
|
|
9
10
|
|
|
10
11
|
## Огляд
|
|
11
12
|
|
|
12
|
-
|
|
13
|
+
Модуль визначає моделі для стандартних та складних виправлень коду. Він надає функції для ініціалізації моделей (`MODEL`, `MODEL_HEAVY`) та для виконання роботи з мовною моделлю (`runLlmWorker`), застосовуючи згенеровані зміни до файлів проєкту.
|
|
13
14
|
|
|
14
15
|
## Поведінка
|
|
15
16
|
|
|
16
|
-
MODEL
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
MODEL_HEAVY
|
|
20
|
-
Визначає модель для важкої ескалації.
|
|
21
|
-
|
|
22
|
-
runLlmWorker
|
|
23
|
-
Виправляє одне правило порушення через LLM.
|
|
17
|
+
MODEL визначає модель за замовчуванням для виправлення, використовуючи змінну середовища або значення за замовчуванням.
|
|
18
|
+
MODEL_HEAVY визначає модель для важких виправлень, використовуючи змінну середовища або значення за замовчуванням.
|
|
19
|
+
runLlmWorker виправляє одне правило-порушення, викликаючи LLM для генерації змін, а потім застосовує ці зміни до файлів проєкту.
|
|
24
20
|
|
|
25
21
|
## Публічний API
|
|
26
22
|
|
|
27
|
-
MODEL —
|
|
28
|
-
MODEL_HEAVY —
|
|
29
|
-
runLlmWorker — Виправляє одне порушення
|
|
23
|
+
MODEL — Основна модель для обробки даних.
|
|
24
|
+
MODEL_HEAVY — Важка модель для складних обчислень.
|
|
25
|
+
runLlmWorker — Виправляє одне порушення правила, використовуючи шаблон C1.
|
|
30
26
|
|
|
31
27
|
## Гарантії поведінки
|
|
32
28
|
|
|
29
|
+
- Read-only: файл не виконує операцій запису у файлову систему.
|
|
33
30
|
- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
|
|
34
|
-
- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
|
|
35
31
|
- Не звертається до мережі.
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
docgen:
|
|
3
|
-
source: npm/
|
|
4
|
-
crc:
|
|
3
|
+
source: npm/scripts/lib/fix/orchestrator.mjs
|
|
4
|
+
crc: 3a66072d
|
|
5
|
+
model: omlx/gemma-4-e4b-it-OptiQ-4bit
|
|
5
6
|
score: 100
|
|
6
7
|
---
|
|
7
8
|
|
|
@@ -9,37 +10,19 @@ docgen:
|
|
|
9
10
|
|
|
10
11
|
## Огляд
|
|
11
12
|
|
|
12
|
-
runOrchestratorCli
|
|
13
|
-
Запускає ітеративний цикл для перевірки набору правил. Проходить через кроки T0-auto та T1, взаємодіючи з LLM-воркерами. Завершує роботу, перевіряючи, чи всі правила виконані, повертаючи нуль або одиницю залежно від кінцевого стану.
|
|
13
|
+
Модуль керує процесом валідації та виправлення правил. Він ініціює перевірку всіх правил. Якщо виявлено порушення, процес ітеративно застосовує детермінований механізм виправлення (T0) та виправлення на основі великої мовної моделі (T1) до невирішених правил. Цей цикл повторюється до досягнення стану, коли всі правила відповідають вимогам, або до перевищення встановленого ліміту ітерацій. Функція `runOrchestratorCli` запускає цей процес.
|
|
14
14
|
|
|
15
15
|
## Поведінка
|
|
16
16
|
|
|
17
|
-
1.
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
Перевіряє наявність помилок
|
|
25
|
-
3. Ітеративний цикл
|
|
26
|
-
Повторює ітерації до максимального ліміту
|
|
27
|
-
Виконує крок T0-auto
|
|
28
|
-
Перевіряє кількість провалів після кроку T0
|
|
29
|
-
Якщо провалів немає, завершує цикл
|
|
30
|
-
Виконує крок T1
|
|
31
|
-
Запускає роботу з LLM-воркерами для кожного правила
|
|
32
|
-
Збільшує лічильник провалів для невдалих правил
|
|
33
|
-
Перевіряє стан після LLM
|
|
34
|
-
Перевіряє наявність невирішених правил
|
|
35
|
-
4. Завершення
|
|
36
|
-
Перевіряє, чи всі правила вирішено
|
|
37
|
-
Повертає нуль у разі чистого стану
|
|
38
|
-
Повертає одиницю у разі невирішеного стану
|
|
17
|
+
1. `runOrchestratorCli` виконує початкову перевірку всіх правил. Якщо порушень немає, процес завершується успішно.
|
|
18
|
+
2. Якщо порушення виявлено, ініціюється ітеративний цикл до максимальної кількості ітерацій.
|
|
19
|
+
3. На кожній ітерації виконується детермінований фікс (крок T0). Це зменшує кількість правил, що потребують подальшої обробки.
|
|
20
|
+
4. Якщо після кроку T0 залишилися невирішені правила, виконується LLM-фікс (крок T1). Для кожного невирішеного правила застосовується відповідна модель, яка може ескалуватися при повторних провалах.
|
|
21
|
+
5. Після LLM-фіксу виконується повторна перевірка всіх правил.
|
|
22
|
+
6. Якщо після перевірки всі правила чисті, процес завершується успішно.
|
|
23
|
+
7. Якщо після завершення всіх ітерацій залишаються невирішені правила, процес завершується з позначкою про невирішені проблеми.
|
|
39
24
|
|
|
40
25
|
## Гарантії поведінки
|
|
41
26
|
|
|
42
27
|
- Read-only: файл не виконує операцій запису у файлову систему.
|
|
43
|
-
- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
|
|
44
|
-
- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
|
|
45
28
|
- Не звертається до мережі.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
docgen:
|
|
3
|
+
source: npm/scripts/lib/fix/run-fix-check.mjs
|
|
4
|
+
crc: 2a0e5f0a
|
|
5
|
+
model: omlx/gemma-4-e4b-it-OptiQ-4bit
|
|
6
|
+
score: 100
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# run-fix-check.mjs
|
|
10
|
+
|
|
11
|
+
## Огляд
|
|
12
|
+
|
|
13
|
+
Викликає конформність-фазу `lint` (read-only), движок (`orchestrator.mjs`, `t0.mjs`) та PostToolUse-хук. Перевірка конформності виконується як пряма функція, без зовнішньої обгортки через `subprocess`. Ізоляція на рівні кожного правила зберігається: кожен файл `rules/<id>/fix.mjs` все ще запускається окремим процесом `bun` (включаючи завантаження конфігурації, whitelist та ізоляцію від збоїв).
|
|
14
|
+
|
|
15
|
+
## Поведінка
|
|
16
|
+
|
|
17
|
+
1. Визначається наявність інструменту `conftest`.
|
|
18
|
+
2. Отримується список усіх доступних ідентифікаторів правил з каталогу правил.
|
|
19
|
+
3. Визначається список ідентифікаторів правил для прогону:
|
|
20
|
+
а. Якщо надано явний список правил, перевіряється, чи всі ці правила доступні.
|
|
21
|
+
б. Якщо явний список не надано, скануються файли `.cursor/rules/*.mdc` у корені проєкту. На основі знайдених файлів визначається список правил для прогону.
|
|
22
|
+
4. Якщо визначено ідентифікатори правил для прогону, для кожного ідентифікатора запускається окремий процес `bun` з файлом `fix.mjs` відповідного правила.
|
|
23
|
+
5. Захоплюється вивід кожного процесу.
|
|
24
|
+
6. Підраховується загальна кількість правил, що не пройшли перевірку.
|
|
25
|
+
7. Повертається результат, що містить загальну кількість перевірених правил, кількість невдалих перевірок та детальний список результатів для кожного правила.
|
|
26
|
+
|
|
27
|
+
## Публічний API
|
|
28
|
+
|
|
29
|
+
runFixCheck — Визначає відповідність коду заданим правилам, виконуючи перевірку без внесення змін.
|
|
30
|
+
|
|
31
|
+
## Гарантії поведінки
|
|
32
|
+
|
|
33
|
+
- Read-only: файл не виконує операцій запису у файлову систему.
|
|
34
|
+
- Не звертається до мережі.
|
|
@@ -1,37 +1,29 @@
|
|
|
1
1
|
---
|
|
2
2
|
docgen:
|
|
3
|
-
source: npm/
|
|
4
|
-
crc:
|
|
5
|
-
|
|
3
|
+
source: npm/scripts/lib/fix/t0.mjs
|
|
4
|
+
crc: 0321ecc1
|
|
5
|
+
model: omlx/gemma-4-e4b-it-OptiQ-4bit
|
|
6
|
+
score: 100
|
|
6
7
|
---
|
|
7
8
|
|
|
8
9
|
# t0.mjs
|
|
9
10
|
|
|
10
11
|
## Огляд
|
|
11
12
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
filterT0AutoRules фільтрує список правил, для яких присутній хоча б один T0-auto паттерн.
|
|
15
|
-
|
|
16
|
-
runT0AutoCli запускає перевірку, застосовує T0-auto до провальних правил, виводить результат та перевіряє стан через check-gate.
|
|
13
|
+
Модуль керує автоматичним застосуванням паттернів до правил для виправлення виводів порушень. Він визначає, які автоматичні паттерни можуть бути застосовані до правил, використовуючи `filterT0AutoRules`, і запускає повний процес виправлення для всіх відповідних правил через `applyT0Auto` та `runT0AutoCli`. Код працює у режимі fail-safe, перехоплюючи помилки та не викидаючи винятків назовні. Робота модуля залежить від конфігурацій `extensions.json` та `package-lock.json`.
|
|
17
14
|
|
|
18
15
|
## Поведінка
|
|
19
16
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
Фільтрує список правил, для яких існує хоча б один T0-auto паттерн
|
|
25
|
-
|
|
26
|
-
runT0AutoCli
|
|
27
|
-
Запускає перевірку, застосовує T0-auto до провальних правил, виводить результат та перевіряє стан через check-gate
|
|
17
|
+
Поведінка
|
|
18
|
+
applyT0Auto застосовує визначені автоматичні паттерни до одного виводу порушення, щоб виправити його.
|
|
19
|
+
filterT0AutoRules повертає список ідентифікаторів правил, для яких існують відповідні автоматичні паттерни.
|
|
20
|
+
runT0AutoCli запускає процес виправлення T0-автоматично для всіх провальних правил, застосовуючи паттерни, повторно перевіряючи стан і виводячи підсумок.
|
|
28
21
|
|
|
29
22
|
## Публічний API
|
|
30
23
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
- Запускає `fix --json`, застосовує T0-auto до кожного порушення, повторно перевіряє check-gate, виводить звіт.
|
|
24
|
+
applyT0Auto — Впроваджує всі шаблони T0-auto до одного результату виявлених проблем.
|
|
25
|
+
filterT0AutoRules — Визначає, які правила мають хоча б один шаблон T0-auto, виходячи з результату `fix --json`.
|
|
26
|
+
runT0AutoCli — Запускає команду `n-cursor fix-t0 [rule...]`, виконує `fix --json`, застосовує T0-auto до кожної проблеми, повторно перевіряє check-gate та надає звіт.
|
|
35
27
|
|
|
36
28
|
## Гарантії поведінки
|
|
37
29
|
|