@nitra/cursor 1.13.1 → 1.13.8

package/rules/vue/vue.mdc

@@ -1,6 +1,6 @@
 ---
 description: Vue
-version: '1.8'
+version: '1.9'
 globs: "**/*.vue"
 alwaysApply: false
 ---
@@ -104,7 +104,20 @@ const additionalInstructions = `
 
 ### Тестування
 
-- **Unit / component:** **Vue Test Utils**; з **Vite** зручно **Vitest**.
+- **Unit:** **Bun Test Runner** (`bun test`) — використовуй його замість **Vitest**. API сумісне (`describe` / `it` / `expect` з `bun:test`), моки через `mock` і `mock.module`. У `package.json` тримай `"test": "bun test <шляхи>"`; не додавай `vitest`, `vitest.config.*` і пов’язані залежності.
+- **Component / DOM:** **Vue Test Utils** + **Bun Test Runner** з **happy-dom** як DOM-середовищем. Підключення — через `@happy-dom/global-registrator` у preload-файлі та `bunfig.toml`:
+
+```toml title="bunfig.toml"
+[test]
+preload = ["./test/happy-dom.preload.js"]
+```
+
+```js title="test/happy-dom.preload.js"
+import { GlobalRegistrator } from '@happy-dom/global-registrator'
+GlobalRegistrator.register()
+```
+
+`jsdom` не використовуй — happy-dom швидший і достатній для типових Vue-компонентних тестів.
 - **E2E:** **Playwright** змістовні сценарії користувацьких потоків.
 
 ### Інструменти (узгоджено з Vite і цим правилом)

package/scripts/ensure-nitra-cursor-dev-dependencies.mjs

@@ -1,10 +1,11 @@
 /**
- * Дописує `\@nitra/cursor` у `devDependencies` кореневого `package.json` проєкту, якщо пакет ще не
- * оголошено ні в `devDependencies`, ні в `dependencies`.
+ * Дописує `\@nitra/cursor` у `devDependencies` workspace-root `package.json` проєкту, якщо пакет ще
+ * не оголошено ні в `devDependencies`, ні в `dependencies`.
  *
  * Використовується CLI `n-cursor` при кожному запуску (`npx \@nitra/cursor`, зокрема `check`), щоб
  * команда `check` і скрипти з `node_modules/\@nitra/cursor/scripts/` були відтворювані після
- * `bun install` / `npm install`, а не лише з кешу npx.
+ * `bun install` / `npm install`, а не лише з кешу npx. Корінь визначається тільки за наявністю поля
+ * `workspaces` у `package.json` поруч із поточною директорією запуску.
  *
  * Версія діапазону: `^<version>` з поля `version` установленого пакету `\@nitra/cursor`.
  */
@@ -37,36 +38,55 @@ export async function readBundledPackageVersion() {
 }
 
 /**
- * Якщо в `root/package.json` немає `\@nitra/cursor` у `devDependencies` і `dependencies`, дописує
- * `devDependencies["\@nitra/cursor"]` зі значенням `^<bundledVersion>`.
- * @param {string} root абсолютний шлях кореня проєкту (зазвичай `process.cwd()`)
- * @param {{ bundledVersion?: string | null, silent?: boolean }} [options] `bundledVersion` — для тестів;
- *   `silent` — не писати в консоль при успішному оновленні
- * @returns {Promise<boolean>} `true`, якщо `package.json` змінено на диску
+ * Читає JSON-обʼєкт із диска.
+ * @param {string} path шлях до JSON-файлу
+ * @returns {Promise<Record<string, unknown> | null>} обʼєкт або `null`, якщо файл нечитабельний
  */
-export async function ensureNitraCursorInRootDevDependencies(root, options = {}) {
-  const pkgPath = join(root, 'package.json')
-  if (!existsSync(pkgPath)) {
-    return false
-  }
-
+async function readJsonObject(path) {
   let raw
   try {
-    raw = await readFile(pkgPath, 'utf8')
+    raw = await readFile(path, 'utf8')
   } catch {
-    return false
+    return null
   }
 
-  let pkg
   try {
-    pkg = JSON.parse(raw)
+    const value = JSON.parse(raw)
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null
   } catch {
-    return false
+    return null
   }
+}
 
-  if (pkg === null || typeof pkg !== 'object' || Array.isArray(pkg)) {
+/**
+ * Читає `package.json` поруч зі стартовою директорією, якщо це workspace-root.
+ * @param {string} startDir директорія, з якої запущено CLI
+ * @returns {Promise<{ path: string, pkg: Record<string, unknown> } | null>} workspace-root package або `null`
+ */
+async function readAdjacentWorkspaceRootPackageJson(startDir) {
+  const pkgPath = join(startDir, 'package.json')
+  if (!existsSync(pkgPath)) {
+    return null
+  }
+
+  const pkg = await readJsonObject(pkgPath)
+  return pkg && Object.hasOwn(pkg, 'workspaces') ? { path: pkgPath, pkg } : null
+}
+
+/**
+ * Якщо у workspace-root `package.json` немає `\@nitra/cursor` у `devDependencies` і `dependencies`,
+ * дописує `devDependencies["\@nitra/cursor"]` зі значенням `^<bundledVersion>`.
+ * @param {string} root стартова директорія проєкту (зазвичай `process.cwd()`)
+ * @param {{ bundledVersion?: string | null, silent?: boolean }} [options] `bundledVersion` — для тестів;
+ *   `silent` — не писати в консоль при успішному оновленні
+ * @returns {Promise<boolean>} `true`, якщо `package.json` змінено на диску
+ */
+export async function ensureNitraCursorInRootDevDependencies(root, options = {}) {
+  const workspaceRoot = await readAdjacentWorkspaceRootPackageJson(root)
+  if (!workspaceRoot) {
     return false
   }
+  const { path: pkgPath, pkg } = workspaceRoot
 
   const devDeps = pkg.devDependencies
   const deps = pkg.dependencies

package/scripts/utils/check-mdc-template-refs.mjs

@@ -0,0 +1,47 @@
+/**
+ * Returns list of template/ files that are NOT referenced in <id>.mdc as
+ * markdown link targets. Paths returned are relative to ruleDir.
+ *
+ * @param {string} ruleDir absolute path to npm/rules/<id>/
+ * @param {string} ruleId basename (e.g. "security")
+ * @returns {Promise<string[]>}
+ */
+import { existsSync } from 'node:fs'
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+
+async function walkTemplateDirs(ruleDir) {
+  const out = []
+  for (const kind of ['fix', 'policy']) {
+    const kindDir = join(ruleDir, kind)
+    if (!existsSync(kindDir)) continue
+    for (const concern of await readdir(kindDir)) {
+      const tpl = join(kindDir, concern, 'template')
+      if (!existsSync(tpl)) continue
+      if (!(await stat(tpl)).isDirectory()) continue
+      out.push(...(await collectFiles(tpl)))
+    }
+  }
+  return out.map(p => relative(ruleDir, p))
+}
+
+async function collectFiles(dir) {
+  const out = []
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) out.push(...(await collectFiles(full)))
+    else out.push(full)
+  }
+  return out
+}
+
+export async function findMissingMdcRefs(ruleDir, ruleId) {
+  const mdcPath = join(ruleDir, `${ruleId}.mdc`)
+  if (!existsSync(mdcPath)) return []
+  const mdc = await readFile(mdcPath, 'utf8')
+  const allFiles = await walkTemplateDirs(ruleDir)
+  return allFiles.filter(rel => {
+    // Match markdown link to ./<rel> or (<rel>) anywhere in the .mdc
+    return !mdc.includes(`./${rel}`) && !mdc.includes(`(${rel})`)
+  })
+}

package/scripts/utils/inline-template-links.mjs

@@ -0,0 +1,60 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { basename, extname, join } from 'node:path'
+
+const TEMPLATE_LINK_RE = /\[([^\]]+)\]\((\.\/[^)]*\/template\/[^)]+)\)/g
+const SLOTS = ['snippet', 'deny', 'contains']
+
+/** @param {string} filePath */
+function langFromExt(filePath) {
+  const ext = extname(filePath)
+  if (ext === '.json') return 'json'
+  if (ext === '.toml') return 'toml'
+  if (ext === '.yml' || ext === '.yaml') return 'yaml'
+  return ''
+}
+
+// Strip `.<slot>.<ext>` suffix (slot ∈ snippet/deny/contains) to recover the
+// real target file name (e.g. `package.json.snippet.json` → `package.json`).
+/** @param {string} fileBasename */
+function normalizeTargetName(fileBasename) {
+  for (const slot of SLOTS) {
+    const m = fileBasename.match(new RegExp(`^(.+)\\.${slot}\\.[^.]+$`))
+    if (m) return m[1]
+  }
+  return fileBasename
+}
+
+/**
+ * Finds markdown links whose path contains /template/ and replaces them with
+ * inline fenced blocks. Reads file from join(ruleDir, rel-path).
+ * Throws Error if a matched link target doesn't exist (fail loud — user must know).
+ *
+ * @param {string} text .mdc file contents
+ * @param {string} ruleDir absolute path to the rule directory (e.g. .../npm/rules/security/)
+ * @returns {Promise<string>} transformed text
+ */
+export async function inlineTemplateLinks(text, ruleDir) {
+  const matches = [...text.matchAll(TEMPLATE_LINK_RE)]
+  if (matches.length === 0) return text
+
+  let result = text
+  for (const match of matches) {
+    const [fullMatch, , href] = match
+    // href starts with ./ and contains /template/ — already guaranteed by regex
+    const relPath = href.slice(2) // strip leading ./
+    const absPath = join(ruleDir, relPath)
+
+    if (!existsSync(absPath)) {
+      throw new Error(`inlineTemplateLinks: file not found: ${absPath} (referenced from .mdc)`)
+    }
+
+    const contents = (await readFile(absPath, 'utf8')).trim()
+    const lang = langFromExt(absPath)
+    const targetName = normalizeTargetName(basename(absPath))
+    const replacement = `\`${targetName}\`:\n\n\`\`\`${lang}\n${contents}\n\`\`\``
+    result = result.replace(fullMatch, () => replacement)
+  }
+
+  return result
+}

package/scripts/utils/run-conftest-batch.mjs

@@ -15,7 +15,8 @@
  * робить для opa/regal).
  */
 import { spawnSync } from 'node:child_process'
-import { existsSync } from 'node:fs'
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -57,8 +58,30 @@ function failConftestMissing() {
  * @property {string} namespace повне імʼя rego-пакета (наприклад `abie.base_deployment_preem`)
  * @property {string[]} files список абсолютних шляхів файлів для перевірки (порожній — повертаємо порожньо)
  * @property {string[]} [extraArgs] додаткові аргументи для conftest (наприклад `--combine` для крос-документних правил)
+ * @property {object} [templateData] опціональне merged-дерево; серіалізується у JSON `{ "template": <data> }` і передається як `--data <tmpfile>` (cleanup після завершення)
  */
 
+/**
+ * Pure args builder for conftest test. Extracted for unit-testability.
+ * Preserves the existing args layout (files before -p; --output json --no-color
+ * for parseable output); inserts --data right after --namespace when provided.
+ * @param {{ policyAbs: string, namespace: string, files: string[], extraArgs: string[], tmpDataFile: string|null }} p
+ * @returns {string[]}
+ */
+export function buildConftestArgs(p) {
+  const args = [
+    'test',
+    ...p.files,
+    '-p',
+    p.policyAbs,
+    '--namespace',
+    p.namespace
+  ]
+  if (p.tmpDataFile) args.push('--data', p.tmpDataFile)
+  args.push('--output', 'json', '--no-color', ...p.extraArgs)
+  return args
+}
+
 /**
  * Виконує `conftest test` для всіх файлів одним спавном і повертає масив
  * порушень. Якщо `files` порожній — повертає `[]` без спавна. Якщо `conftest`
@@ -81,40 +104,44 @@ export function runConftestBatch(opts) {
   if (!existsSync(policyAbs)) {
     throw new Error(`runConftestBatch: rego-каталог не знайдено: ${policyAbs}`)
   }
-  const args = [
-    'test',
-    ...opts.files,
-    '-p',
-    policyAbs,
-    '--namespace',
-    opts.namespace,
-    '--output',
-    'json',
-    '--no-color',
-    ...(opts.extraArgs ?? [])
-  ]
-  const result = spawnSync(conftestBin, args, { encoding: 'utf8' })
-  if (result.error) {
-    throw result.error
+  let tmpDataDir = null
+  let tmpDataFile = null
+  if (opts.templateData) {
+    tmpDataDir = mkdtempSync(join(tmpdir(), 'n-cursor-tpl-'))
+    tmpDataFile = join(tmpDataDir, 'template-data.json')
+    writeFileSync(tmpDataFile, JSON.stringify({ template: opts.templateData }))
   }
-  // conftest exit 1 = є failures (це валідно для нас); >1 = справжня помилка.
-  if (result.status !== 0 && result.status !== 1) {
-    throw new Error(`conftest exit ${result.status}: ${(result.stderr || result.stdout || '').slice(0, 500)}`)
-  }
-  /** @type {Array<{ filename: string, namespace: string, failures?: Array<{ msg: string }> }>} */
-  let parsed
   try {
-    parsed = JSON.parse(result.stdout)
-  } catch {
-    throw new Error(`conftest stdout не парситься як JSON: ${(result.stdout || '').slice(0, 200)}`)
-  }
-  /** @type {ConftestViolation[]} */
-  const out = []
-  for (const entry of parsed) {
-    const failures = entry.failures ?? []
-    for (const f of failures) {
-      out.push({ filename: entry.filename, namespace: entry.namespace, message: f.msg })
+    const args = buildConftestArgs({
+      policyAbs,
+      namespace: opts.namespace,
+      files: opts.files,
+      extraArgs: opts.extraArgs ?? [],
+      tmpDataFile
+    })
+    const result = spawnSync(conftestBin, args, { encoding: 'utf8' })
+    if (result.error) throw result.error
+    // conftest exit 1 = є failures (це валідно для нас); >1 = справжня помилка.
+    if (result.status !== 0 && result.status !== 1) {
+      throw new Error(`conftest exit ${result.status}: ${(result.stderr || result.stdout || '').slice(0, 500)}`)
+    }
+    /** @type {Array<{ filename: string, namespace: string, failures?: Array<{ msg: string }> }>} */
+    let parsed
+    try {
+      parsed = JSON.parse(result.stdout)
+    } catch {
+      throw new Error(`conftest stdout не парситься як JSON: ${(result.stdout || '').slice(0, 200)}`)
+    }
+    /** @type {ConftestViolation[]} */
+    const out = []
+    for (const entry of parsed) {
+      const failures = entry.failures ?? []
+      for (const f of failures) {
+        out.push({ filename: entry.filename, namespace: entry.namespace, message: f.msg })
+      }
     }
+    return out
+  } finally {
+    if (tmpDataDir) rmSync(tmpDataDir, { recursive: true, force: true })
   }
-  return out
 }

package/scripts/utils/run-rule.mjs

@@ -15,9 +15,11 @@
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
+import { findMissingMdcRefs } from './check-mdc-template-refs.mjs'
 import { createCheckReporter } from './check-reporter.mjs'
 import { resolveTargetFiles } from './resolve-target-files.mjs'
 import { runConftestBatch } from './run-conftest-batch.mjs'
+import { resolveConcernTemplateData } from './template.mjs'
 
 const APPLIES_CONCERN_NAME = 'applies'
 
@@ -80,10 +82,13 @@ async function runPolicyConcern(bundledRulesDir, ruleId, concernName, walkCache)
   // Rego не дозволяє '-' в імені пакета, тому kebab-id у `.n-cursor.json:rules`
   // мапиться на snake у namespace. Файлова структура `rules/<id>/policy/` лишається kebab.
   const regoNamespace = `${ruleId.replaceAll('-', '_')}.${concernName}`
+  const concernAbsDir = join(bundledRulesDir, ruleId, 'policy', concernName)
+  const templateData = await resolveConcernTemplateData(concernAbsDir, target)
   const violations = runConftestBatch({
     policyDirRel: `${ruleId}/${concernName}`,
     namespace: regoNamespace,
-    files
+    files,
+    templateData
   })
   if (violations.length === 0) {
     reporter.pass(`${concernName}: ${files.length} файл(ів) OK (rego)`)
@@ -127,5 +132,15 @@ export async function runRule(rule, bundledRulesDir, walkCache) {
     if (code !== 0) totalCode = 1
   }
 
+  const ruleDir = join(bundledRulesDir, rule.id)
+  const missing = await findMissingMdcRefs(ruleDir, rule.id)
+  if (missing.length > 0) {
+    const reporter = createCheckReporter()
+    for (const rel of missing) {
+      reporter.fail(`${rule.id}.mdc: відсутнє markdown-посилання на template-файл ${rel}`)
+    }
+    if (reporter.getExitCode() !== 0) totalCode = 1
+  }
+
   return totalCode
 }

package/scripts/utils/template.mjs

@@ -0,0 +1,215 @@
+/**
+ * Reads template/ for a concern directory and returns a merged structure indexed
+ * by target basename. For each <target>, returns whichever of snippet/deny/contains
+ * exist (parsed in native format by extension).
+ *
+ * @param {string} concernDir absolute path to fix/<concern>/ or policy/<concern>/
+ * @returns {Promise<Record<string, { snippet?: any, deny?: any, contains?: any }>>}
+ */
+import { existsSync } from 'node:fs'
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { basename as _basename, extname, join, relative } from 'node:path'
+
+import { parse as parseToml } from 'smol-toml'
+
+const SLOTS = ['snippet', 'deny', 'contains']
+
+/** Parse file contents by extension; returns JS object for structured formats, string for text. */
+async function parseByExt(path) {
+  const raw = await readFile(path, 'utf8')
+  const ext = extname(path).toLowerCase()
+  if (ext === '.json' || ext === '.jsonc') return JSON.parse(stripJsonComments(raw))
+  if (ext === '.toml') return parseToml(raw)
+  if (ext === '.yml' || ext === '.yaml') {
+    const { parse: parseYaml } = await import('yaml')
+    return parseYaml(raw)
+  }
+  return raw // text-only
+}
+
+function stripJsonComments(s) {
+  // Minimal: strip // line comments and /* */ block comments. JSON-with-comments format.
+  return s.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '')
+}
+
+async function walk(dir, base = dir) {
+  const out = []
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) out.push(...(await walk(full, base)))
+    else out.push(relative(base, full))
+  }
+  return out
+}
+
+/**
+ * Parse "<target>.<slot>.<ext>" or "<target>" (text-only).
+ * Returns { target, slot } where slot is one of snippet|deny|contains|null (null = text-only target).
+ */
+function classifyTemplateFile(relPath) {
+  // Try ".<slot>." suffix detection
+  for (const slot of SLOTS) {
+    const m = relPath.match(new RegExp(`^(?<target>.+)\\.${slot}\\.[^.]+$`))
+    if (m?.groups?.target) return { target: m.groups.target, slot }
+  }
+  // No slot suffix → text-only canon for the literal target name
+  return { target: relPath, slot: null }
+}
+
+function formatPath(parts) {
+  return parts
+    .map(p => (typeof p === 'number' ? `[${p}]` : /^[a-zA-Z_$][\w$]*$/.test(p) ? p : JSON.stringify(p)))
+    .reduce((acc, p) => (acc === '' ? p : p.startsWith('[') ? acc + p : acc + '.' + p), '')
+}
+
+function quote(v) {
+  return typeof v === 'string' ? JSON.stringify(v) : String(v)
+}
+
+/**
+ * Deep subset-of check. Every leaf in `snippet` must equal same path in `actual`.
+ * Arrays in snippet: every element must be present in actual array.
+ * Returns array of violation messages.
+ */
+export function checkSnippet(actual, snippet, opts, path = []) {
+  if (snippet == null) return []
+  const { targetPath, source } = opts
+  const violations = []
+  if (Array.isArray(snippet)) {
+    if (!Array.isArray(actual)) {
+      violations.push(`${targetPath}: ${formatPath(path)} має бути масивом (${source})`)
+      return violations
+    }
+    for (const needle of snippet) {
+      const found = actual.some(a => JSON.stringify(a) === JSON.stringify(needle))
+      if (!found) {
+        violations.push(`${targetPath}: ${formatPath(path)} має містити ${quote(needle)} (${source})`)
+      }
+    }
+    return violations
+  }
+  if (snippet !== null && typeof snippet === 'object') {
+    if (actual == null || typeof actual !== 'object' || Array.isArray(actual)) {
+      violations.push(`${targetPath}: ${formatPath(path)} має бути об'єктом (${source})`)
+      return violations
+    }
+    for (const [k, v] of Object.entries(snippet)) {
+      violations.push(...checkSnippet(actual[k], v, opts, [...path, k]))
+    }
+    return violations
+  }
+  // Leaf (string/number/boolean)
+  if (actual !== snippet) {
+    violations.push(`${targetPath}: ${formatPath(path)} має бути ${quote(snippet)} (${source})`)
+  }
+  return violations
+}
+
+/**
+ * Walks deny tree; for any leaf path that exists in actual, returns violation
+ * with the deny's leaf string as reason.
+ */
+export function checkDeny(actual, deny, opts, path = []) {
+  if (deny == null) return []
+  const { targetPath, source } = opts
+  if (deny !== null && typeof deny === 'object' && !Array.isArray(deny)) {
+    const out = []
+    for (const [k, v] of Object.entries(deny)) {
+      const childActual = actual && typeof actual === 'object' ? actual[k] : undefined
+      out.push(...checkDeny(childActual, v, opts, [...path, k]))
+    }
+    return out
+  }
+  // Leaf reached — if actual has this path at all (any value), it's a violation
+  if (actual !== undefined) {
+    const reason = typeof deny === 'string' ? deny : 'заборонено'
+    return [`${targetPath}: ${formatPath(path)} — ${reason} (${source})`]
+  }
+  return []
+}
+
+/**
+ * For each leaf path that has an array of strings in `contains`, every string
+ * must appear as substring in the same path of `actual` (string leaf).
+ */
+export function checkContains(actual, contains, opts, path = []) {
+  if (contains == null) return []
+  const { targetPath, source } = opts
+  if (Array.isArray(contains)) {
+    const out = []
+    const haystack = typeof actual === 'string' ? actual : ''
+    for (const needle of contains) {
+      if (!haystack.includes(needle)) {
+        out.push(`${targetPath}: ${formatPath(path)} має містити ${quote(needle)} (${source})`)
+      }
+    }
+    return out
+  }
+  if (contains !== null && typeof contains === 'object') {
+    const out = []
+    for (const [k, v] of Object.entries(contains)) {
+      const childActual = actual && typeof actual === 'object' ? actual[k] : undefined
+      out.push(...checkContains(childActual, v, opts, [...path, k]))
+    }
+    return out
+  }
+  return []
+}
+
+/**
+ * For text-only targets (e.g. .stylelintignore): every non-empty, non-comment
+ * line in `template` must appear (trimmed) in `actual`.
+ */
+export function checkTextSubset(actual, template, opts) {
+  if (template == null) return []
+  const { targetPath, source } = opts
+  const actualLines = new Set(String(actual ?? '').split(/\r?\n/).map(l => l.trim()))
+  const out = []
+  for (const raw of String(template).split(/\r?\n/)) {
+    const line = raw.trim()
+    if (line === '' || line.startsWith('#')) continue
+    if (!actualLines.has(line)) {
+      out.push(`${targetPath}: відсутній рядок ${quote(line)} (${source})`)
+    }
+  }
+  return out
+}
+
+export async function loadTemplate(concernDir) {
+  const tplDir = join(concernDir, 'template')
+  if (!existsSync(tplDir)) return {}
+  if (!(await stat(tplDir)).isDirectory()) return {}
+  const files = await walk(tplDir)
+  const result = {}
+  for (const rel of files) {
+    const { target, slot } = classifyTemplateFile(rel)
+    if (!result[target]) result[target] = {}
+    const value = await parseByExt(join(tplDir, rel))
+    if (slot === null) result[target].snippet = value // text-only treated as snippet
+    else result[target][slot] = value
+  }
+  return result
+}
+
+/**
+ * Resolves which template[<target>] to pass for a concern, based on its target.json.
+ * For `single` targets — basename. For `walkGlob` — basename of first non-negated entry.
+ * @param {string} concernAbsDir absolute path to fix/<concern>/ or policy/<concern>/
+ * @param {{ files?: { single?: string, walkGlob?: string|string[] } }} targetJson parsed target.json
+ * @returns {Promise<object|undefined>} template tree for the resolved target basename, or undefined
+ */
+export async function resolveConcernTemplateData(concernAbsDir, targetJson) {
+  const tpl = await loadTemplate(concernAbsDir)
+  const single = targetJson?.files?.single
+  if (single) return tpl[_basename(single)]
+  const glob = targetJson?.files?.walkGlob
+  if (typeof glob === 'string') return tpl[_basename(glob.replace(/^!/, ''))]
+  if (Array.isArray(glob)) {
+    for (const g of glob) {
+      if (g.startsWith('!')) continue
+      const data = tpl[_basename(g)]
+      if (data) return data
+    }
+  }
+  return undefined
+}