@nitra/cursor 3.10.0 → 3.12.0

package/scripts/dispatcher/trace.mjs

@@ -7,12 +7,20 @@
  * FS-доступ (`readdir`/`readFile`/`exists`) ін'єктується — тестується без диска.
  */
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 import { cwd as processCwd } from 'node:process'
 
-/** Поля-лінки у front-matter, що утворюють ланцюг. */
+/** Поля-лінки у front-matter (порядок відображення). */
 const LINK_FIELDS = ['adr', 'spec', 'plan', 'flow', 'change', 'task']
 
+/**
+ * Інформаційні лінк-поля: показуються, але їх відсутність НЕ є розривом ланцюга.
+ * `flow` вказує на runtime-стан `.worktrees/<branch>.flow.json` — gitignored, поза
+ * `docs/`, існує лише під час задачі; у чистому checkout/CI його нема ніколи, тож
+ * рахувати його розривом — хибний сигнал. Решта полів — ланки ланцюга (breaking).
+ */
+const INFO_LINK_FIELDS = new Set(['flow'])
+
 /** Каталоги з traceable-артефактами. */
 const DIRS = ['docs/tasks', 'docs/specs', 'docs/plans', 'docs/adr']
 
@@ -52,20 +60,40 @@ function isSimpleKey(key) {
 
 /**
  * Будує аналіз: для кожного артефакту — його лінки зі статусом ok/розрив.
+ * `breaking` — чи відсутність цього лінка рве ланцюг (chain-поля) чи лише
+ * інформаційна (`flow` → runtime-стан).
  * @param {{ file: string, fm: Record<string, string | null> }[]} artifacts артефакти з front-matter
- * @param {(target: string) => boolean} exists чи існує цільовий файл лінка
- * @returns {{ file: string, kind: string | null, id: string | null, status: string | null, links: { field: string, target: string, ok: boolean }[] }[]} аналіз
+ * @param {(target: string, artifactFile: string) => boolean} resolve чи резолвиться лінк (відносно артефакту/кореня)
+ * @returns {{ file: string, kind: string | null, id: string | null, status: string | null, links: { field: string, target: string, ok: boolean, breaking: boolean }[] }[]} аналіз
  */
-export function analyze(artifacts, exists) {
+export function analyze(artifacts, resolve) {
   return artifacts.map(({ file, fm }) => ({
     file,
     kind: fm.kind ?? null,
     id: fm.id ?? null,
     status: fm.status ?? null,
-    links: LINK_FIELDS.filter(f => fm[f]).map(f => ({ field: f, target: fm[f], ok: exists(fm[f]) }))
+    links: LINK_FIELDS.filter(f => fm[f]).map(f => ({
+      field: f,
+      target: fm[f],
+      ok: resolve(fm[f], file),
+      breaking: !INFO_LINK_FIELDS.has(f)
+    }))
   }))
 }
 
+/**
+ * Чи резолвиться лінк: спершу відносно теки артефакту (конвенція доків `../specs/…`),
+ * далі fallback на root-relative (`docs/specs/…`). Обидві форми вважаються валідними.
+ * @param {string} root корінь репо
+ * @param {string} artifactFile rel-шлях артефакту (напр. `docs/plans/x.md`)
+ * @param {string} target значення лінка
+ * @param {(absPath: string) => boolean} exists перевірка існування
+ * @returns {boolean} чи знайдено цільовий файл
+ */
+function resolveLink(root, artifactFile, target, exists) {
+  return exists(join(root, dirname(artifactFile), target)) || exists(join(root, target))
+}
+
 /**
  * Текстовий рендер аналізу.
  * @param {object[]} analysis результат `analyze`
@@ -77,14 +105,24 @@ export function render(analysis) {
   for (const a of analysis) {
     lines.push(`${a.kind ?? '?'} · ${a.id ?? a.file} [${a.status ?? '—'}]`)
     for (const l of a.links) {
-      const mark = l.ok ? '→' : '✗'
-      const note = l.ok ? '' : ' (РОЗРИВ — файл відсутній)'
-      lines.push(`   ${mark} ${l.field}: ${l.target}${note}`)
+      lines.push(`   ${renderLink(l)}`)
     }
   }
   return lines.join('\n')
 }
 
+/**
+ * Рядок одного лінка: `→` ok; `✗ … (РОЗРИВ)` — нерезолвлене chain-поле;
+ * `~ … (не рве ланцюг)` — нерезолвлене інформаційне поле (`flow`, runtime-стан).
+ * @param {{ field: string, target: string, ok: boolean, breaking: boolean }} l лінк
+ * @returns {string} рядок
+ */
+function renderLink(l) {
+  if (l.ok) return `→ ${l.field}: ${l.target}`
+  if (l.breaking) return `✗ ${l.field}: ${l.target} (РОЗРИВ — файл відсутній)`
+  return `~ ${l.field}: ${l.target} (runtime-стан — не рве ланцюг)`
+}
+
 /**
  * CLI `n-cursor trace [--json]`. Повертає 1, якщо є розриви ланцюга.
  * @param {string[]} args аргументи
@@ -108,7 +146,8 @@ export function runTraceCli(args, deps = {}) {
     }
   }
 
-  const analysis = analyze(artifacts, target => exists(join(root, target)))
+  const analysis = analyze(artifacts, (target, file) => resolveLink(root, file, target, exists))
   log(args.includes('--json') ? JSON.stringify(analysis, null, 2) : render(analysis))
-  return analysis.some(a => a.links.some(l => !l.ok)) ? 1 : 0
+  // Розрив ланцюга — лише нерезолвлене chain-поле; нерезолвлений `flow` (runtime-стан) не рахуємо.
+  return analysis.some(a => a.links.some(l => l.breaking && !l.ok)) ? 1 : 0
 }

package/scripts/lib/changed-files.mjs

@@ -28,3 +28,31 @@ export function collectChangedFiles(cwd = process.cwd()) {
   const untracked = gitLines(['ls-files', '--others', '--exclude-standard'], cwd)
   return [...new Set([...modified, ...untracked])]
 }
+
+/**
+ * Список змінених + untracked файлів **відносно базового комміту**.
+ *
+ * `git diff <base>` (без `..`/`...`, без `HEAD`) порівнює base-комміт із поточним
+ * **робочим деревом** — тобто однаково ловить і закомічене від base, і staged, і
+ * незакомічені модифікації. Це гарантує однакову поведінку незалежно від того, чи
+ * зміни вже закомічені у worktree (потрібно для flow-турнікета, де executor комітить
+ * кожен крок). Без `base` — fallback на `collectChangedFiles` (робоче дерево vs HEAD).
+ * @param {string|null} [base] базовий комміт (`metadata.base_commit` зі стану flow)
+ * @param {string} [cwd] корінь репо
+ * @returns {string[]} унікальні шляхи (без видалених)
+ */
+export function collectChangedFilesSince(base, cwd = process.cwd()) {
+  if (!base) return collectChangedFiles(cwd)
+  // Fail-closed: недосяжний base (rebase/force-update/shallow prune) інакше дав би `git diff`
+  // exit 128 → порожній список → gate мовчки пройшов би без перевірки. Краще явна помилка.
+  const verify = spawnSync('git', ['rev-parse', '--verify', '--quiet', `${base}^{commit}`], { cwd, encoding: 'utf8' })
+  if (verify.status !== 0 || verify.error) {
+    throw new Error(
+      `collectChangedFilesSince: base-комміт «${base}» недосяжний у ${cwd} ` +
+        '(rebase/force-update?) — coverage --changed не може визначити scope'
+    )
+  }
+  const changed = gitLines(['diff', base, '--name-only', '--diff-filter=ACMR'], cwd)
+  const untracked = gitLines(['ls-files', '--others', '--exclude-standard'], cwd)
+  return [...new Set([...changed, ...untracked])]
+}