@shanyucoder/flowgrid 0.1.0

package/engines/cases/gate.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * flowgrid cases:gate — schema + audit + bundle traceability + per-screen facets (+ optional SC coverage).
+ *
+ * Usage:
+ *   flowgrid cases:gate [--strict] [--docs-root path] [--json] [--no-coverage]
+ */
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { listCaseYamlUnderProject } from './lib/list-case-yaml.mjs'
+import { validateTcFile } from './lib/validate-tc-schema.mjs'
+import { resolveBundleFromScreen } from './lib/resolve-bundle-from-screen.mjs'
+import { auditTcTraceability } from './lib/audit-tc-traceability.mjs'
+import { auditScreenFacetCoverage } from './lib/screen-facet-coverage.mjs'
+import {
+  auditTestcaseTcFile,
+  isTestCaseArtifact,
+} from '../spec/lib/audit-testcase-tc.mjs'
+import { auditTestcasePlanContent } from '../spec/lib/audit-testcase-plan-gaps.mjs'
+import { auditTestcaseBundleCross } from '../spec/lib/audit-testcase-bundle-cross.mjs'
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..')
+
+function parseArgs(argv) {
+  let strict = false
+  let json = false
+  let noCoverage = false
+  let docsRoot = process.env.FLOWGRID_DOCS_ROOT || null
+  const positional = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--strict') strict = true
+    else if (a === '--json') json = true
+    else if (a === '--no-coverage') noCoverage = true
+    else if (a === '--docs-root' && argv[i + 1]) docsRoot = argv[++i]
+    else if (a === '--help' || a === '-h') positional.push('__help__')
+    else positional.push(a)
+  }
+  return { strict, json, noCoverage, docsRoot, projectRoot: positional[0] }
+}
+
+function gapBlocks(gap, strict) {
+  if (gap.severity === 'critical') return true
+  if (strict && (gap.severity === 'warning' || gap.severity === 'info')) return true
+  return false
+}
+
+async function main() {
+  const { strict, json, noCoverage, docsRoot, projectRoot: rootArg } = parseArgs(
+    process.argv.slice(2),
+  )
+  if (rootArg === '__help__') {
+    console.log(`Usage: flowgrid cases:gate [--strict] [--docs-root <docs-hub>] [--json] [--no-coverage]
+  Runs JSON Schema (v2), audit testcase, bundle traceability, per-screen matrix facets, and cases:coverage.`)
+    process.exit(0)
+  }
+
+  const projectRoot = path.resolve(rootArg || process.cwd())
+  const files = await listCaseYamlUnderProject(projectRoot)
+  const report = {
+    ok: true,
+    strict,
+    projectRoot,
+    docsRoot: docsRoot || process.env.FLOWGRID_DOCS_ROOT || null,
+    fileCount: files.length,
+    gaps: [],
+    files: [],
+  }
+
+  if (!files.length) {
+    report.gaps.push({
+      code: 'GATE_NO_TC_FILES',
+      severity: 'warning',
+      path: 'cases',
+      message: 'No TC-*.yaml under cases/.',
+      suggestedFix: 'Author testcase YAML under cases/ mirroring docs hub.',
+      category: 'gate',
+    })
+  }
+
+  const parsedForScreen = []
+
+  for (const file of files) {
+    const raw = await readFile(file, 'utf8')
+    const rel = path.relative(projectRoot, file)
+    const fileReport = { file: rel, schema: true, audit: true, bundle: null }
+
+    const schemaResult = await validateTcFile(file, projectRoot)
+    if (!schemaResult.ok) {
+      report.ok = false
+      fileReport.schema = false
+      for (const err of schemaResult.errors) {
+        report.gaps.push({
+          code: 'TC_SCHEMA_INVALID',
+          severity: 'critical',
+          path: rel,
+          message: err,
+          suggestedFix: 'Fix YAML to match schemas/testcase.schema.json (schemaVersion: 2).',
+          category: 'schema',
+        })
+      }
+    }
+
+    const data = schemaResult.data
+    if (data) parsedForScreen.push({ file: rel, data })
+
+    let auditReport
+    if (isTestCaseArtifact(file, raw)) {
+      auditReport = auditTestcaseTcFile(raw, file)
+    } else {
+      auditReport = auditTestcasePlanContent(raw, file)
+    }
+    for (const g of auditReport.gaps) {
+      if (gapBlocks(g, strict)) report.ok = false
+      report.gaps.push({ ...g, file: rel })
+    }
+
+    const screen = data?.refs?.screen
+    if (screen && typeof screen === 'string') {
+      const bundlePath = resolveBundleFromScreen(projectRoot, screen, { docsRoot })
+      if (bundlePath) {
+        fileReport.bundle = path.relative(projectRoot, bundlePath)
+        const bundleText = await readFile(bundlePath, 'utf8')
+        if (data && strict) {
+          const trace = auditTcTraceability(data, bundleText, {
+            strict: true,
+            bundlePath,
+          })
+          for (const g of trace.gaps) {
+            if (gapBlocks(g, strict)) report.ok = false
+            report.gaps.push({ ...g, file: rel, bundle: fileReport.bundle })
+          }
+        } else if (data) {
+          const trace = auditTcTraceability(data, bundleText, {
+            strict: false,
+            bundlePath,
+          })
+          for (const g of trace.gaps) {
+            if (gapBlocks(g, false) && g.severity === 'critical') report.ok = false
+            if (g.severity !== 'info' || strict) report.gaps.push({ ...g, file: rel, bundle: fileReport.bundle })
+          }
+          const cross = auditTestcaseBundleCross(bundleText, raw, bundlePath)
+          for (const g of cross.bundleCrossGaps) {
+            if (strict && gapBlocks({ ...g, severity: g.severity === 'info' ? 'warning' : g.severity }, strict)) {
+              report.ok = false
+            }
+            if (!strict || g.severity !== 'info') {
+              report.gaps.push({ ...g, file: rel, bundle: fileReport.bundle })
+            }
+          }
+        }
+      } else if (strict) {
+        report.ok = false
+        report.gaps.push({
+          code: 'GATE_BUNDLE_UNRESOLVED',
+          severity: 'critical',
+          path: rel,
+          message: `Could not resolve *.bundle.yaml for screen ${screen} (set --docs-root or FLOWGRID_DOCS_ROOT).`,
+          suggestedFix: 'Point docs hub root or pass --bundle manually on audit testcase.',
+          category: 'gate',
+        })
+      }
+    }
+
+    report.files.push(fileReport)
+  }
+
+  const screenFacets = auditScreenFacetCoverage(parsedForScreen, { strict })
+  for (const g of screenFacets.gaps) {
+    if (gapBlocks(g, strict)) report.ok = false
+    report.gaps.push(g)
+  }
+
+  if (!noCoverage && files.length) {
+    const cov = spawnSync(process.execPath, [path.join(packageRoot, 'engines/cases/check-coverage.mjs')], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+    })
+    if (cov.status !== 0) {
+      report.ok = false
+      report.gaps.push({
+        code: 'GATE_SC_COVERAGE_FAILED',
+        severity: strict ? 'critical' : 'warning',
+        path: 'scenarios',
+        message: (cov.stderr || cov.stdout || 'cases:coverage failed').trim().slice(0, 500),
+        suggestedFix: 'Align SC coverage_plan with TC coverage[] per scenario.',
+        category: 'sc-coverage',
+      })
+    }
+  }
+
+  report.criticalGaps = report.gaps.filter((g) => g.severity === 'critical').length
+  report.warningGaps = report.gaps.filter((g) => g.severity === 'warning').length
+
+  if (json) {
+    console.log(JSON.stringify(report, null, 2))
+  } else if (report.ok) {
+    console.log(`cases:gate OK (${files.length} TC file(s), strict=${strict})`)
+  } else {
+    console.error('cases:gate FAILED')
+    for (const g of report.gaps) {
+      console.error(`  [${g.severity}] ${g.code} ${g.file ? g.file + ' — ' : ''}${g.message}`)
+    }
+  }
+
+  process.exit(report.ok ? 0 : 1)
+}
+
+main().catch((e) => {
+  console.error('cases:gate FAILED')
+  console.error(`  - ${e.message}`)
+  process.exit(1)
+})

package/engines/cases/lib/audit-tc-traceability.mjs

@@ -0,0 +1,139 @@
+import { parseBundleTraceability } from './parse-bundle-traceability.mjs'
+
+/**
+ * Structured bundle ↔ TC traceability (schema traceability block).
+ * @param {Record<string, unknown>} tc — parsed TC YAML
+ * @param {string} bundleText
+ * @param {{ strict?: boolean; bundlePath?: string }} [opts]
+ */
+export function auditTcTraceability(tc, bundleText, opts = {}) {
+  const strict = Boolean(opts.strict)
+  const gaps = []
+  const bundle = parseBundleTraceability(bundleText)
+  const trace = tc.traceability && typeof tc.traceability === 'object' ? tc.traceability : {}
+  const screen = tc.refs?.screen
+
+  function add(code, severity, fieldPath, message, suggestedFix) {
+    gaps.push({
+      code,
+      severity,
+      path: fieldPath,
+      message,
+      suggestedFix,
+      category: 'traceability',
+    })
+  }
+
+  if (bundle.screenId && screen && bundle.screenId !== screen) {
+    add(
+      'TC_TRACE_SCREEN_MISMATCH',
+      'warning',
+      'traceability.bundleScreen',
+      `Bundle page-id ${bundle.screenId} differs from refs.screen ${screen}.`,
+      'Align bundle page-id with TC refs.screen or fix route.',
+    )
+  }
+
+  if (trace.bundleScreen && screen && trace.bundleScreen !== screen) {
+    add(
+      'TC_TRACE_BUNDLE_SCREEN_FIELD',
+      'critical',
+      'traceability.bundleScreen',
+      `traceability.bundleScreen must match refs.screen (${screen}).`,
+      `Set traceability.bundleScreen: ${screen}`,
+    )
+  }
+
+  const declaredScenarios = new Set(
+    (Array.isArray(trace.bundleScenarios) ? trace.bundleScenarios : []).map(String),
+  )
+  const declaredAc = new Set(
+    (Array.isArray(trace.acceptanceRefs) ? trace.acceptanceRefs : []).map(String),
+  )
+  const declaredActions = new Set(
+    (Array.isArray(trace.actionRefs) ? trace.actionRefs : []).map(String),
+  )
+
+  for (const { name, slug } of bundle.scenarios) {
+    const covered =
+      declaredScenarios.has(slug) ||
+      declaredScenarios.has(name) ||
+      (!strict && tcCoversScenarioLoose(tc, name))
+    if (!covered) {
+      add(
+        'TC_TRACE_SCENARIO_MISSING',
+        strict ? 'critical' : 'warning',
+        `traceability.bundleScenarios.${slug}`,
+        `Bundle scenario not traced: "${name}" (slug: ${slug}).`,
+        `Add "${slug}" to traceability.bundleScenarios[] (or full scenario name).`,
+      )
+    }
+  }
+
+  for (const { id, text } of bundle.acceptance) {
+    if (!declaredAc.has(id) && !(declaredAc.has(text) && text.length < 120)) {
+      const loose = !strict && String(tc.story || tc.summary || '').includes(text.slice(0, 24))
+      if (!loose) {
+        add(
+          'TC_TRACE_AC_MISSING',
+          strict ? 'critical' : 'info',
+          `traceability.acceptanceRefs.${id}`,
+          `Bundle acceptance ${id} not in traceability.acceptanceRefs.`,
+          `Add ${id} to traceability.acceptanceRefs[] (bundle line: "${text.slice(0, 60)}…").`,
+        )
+      }
+    }
+  }
+
+  for (const { id, hasOutcomes } of bundle.actions) {
+    if (!hasOutcomes) continue
+    const inMatrix = matrixMentionsAction(tc, id)
+    if (!declaredActions.has(id) && !inMatrix && strict) {
+      add(
+        'TC_TRACE_ACTION_MISSING',
+        'critical',
+        `traceability.actionRefs.${id}`,
+        `Design action ${id} with outcomes not listed in traceability.actionRefs.`,
+        `Add ${id} to traceability.actionRefs[] and cover in testMatrix.`,
+      )
+    } else if (!declaredActions.has(id) && !inMatrix && !strict) {
+      add(
+        'TC_TRACE_ACTION_MISSING',
+        'info',
+        `traceability.actionRefs.${id}`,
+        `Design action ${id} not explicitly traced.`,
+        `Add ${id} to traceability.actionRefs[].`,
+      )
+    }
+  }
+
+  if (strict && bundle.scenarios.length && !trace.bundleScenarios) {
+    add(
+      'TC_TRACE_BLOCK_REQUIRED',
+      'critical',
+      'traceability',
+      'strict gate requires traceability.bundleScenarios when bundle has userStories.scenarios.',
+      'Add traceability: { bundleScreen, bundleScenarios, acceptanceRefs, actionRefs }.',
+    )
+  }
+
+  return {
+    bundle: opts.bundlePath ?? null,
+    expected: {
+      scenarios: bundle.scenarios.map((s) => s.slug),
+      acceptance: bundle.acceptance.map((a) => a.id),
+      actions: bundle.actions.filter((a) => a.hasOutcomes).map((a) => a.id),
+    },
+    gaps,
+  }
+}
+
+function tcCoversScenarioLoose(tc, name) {
+  const blob = JSON.stringify(tc)
+  return blob.includes(name) || blob.toLowerCase().includes(name.slice(0, 20).toLowerCase())
+}
+
+function matrixMentionsAction(tc, actionId) {
+  const blob = JSON.stringify(tc.testMatrix ?? [])
+  return blob.includes(actionId) || blob.includes(actionId.replace('btn_', ''))
+}

package/engines/cases/lib/list-case-yaml.mjs

@@ -0,0 +1,27 @@
+import { readdir } from 'node:fs/promises'
+import path from 'node:path'
+
+export async function listCaseYaml(dir) {
+  const out = []
+  for (const entry of await listEntries(dir)) {
+    const p = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      out.push(...(await listCaseYaml(p)))
+      continue
+    }
+    if (entry.isFile() && /^TC-.*\.ya?ml$/i.test(entry.name)) out.push(p)
+  }
+  return out.sort()
+}
+
+async function listEntries(dir) {
+  try {
+    return await readdir(dir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+}
+
+export async function listCaseYamlUnderProject(projectRoot) {
+  return listCaseYaml(path.join(projectRoot, 'cases'))
+}

package/engines/cases/lib/parse-bundle-traceability.mjs

@@ -0,0 +1,77 @@
+/**
+ * Parse bundle YAML text into traceability inventory (light parse).
+ */
+
+export function scenarioToSlug(name) {
+  const paren = name.match(/\(([^)]+)\)/)
+  if (paren) {
+    const part = paren[1].split(/[/,&]/)[0].trim()
+    return part
+      .toLowerCase()
+      .replace(/[^\p{L}\p{N}\s-]/gu, '')
+      .replace(/\s+/g, '-')
+      .replace(/-+/g, '-')
+      .slice(0, 48)
+  }
+  return name
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s-]/gu, '')
+    .replace(/\s+/g, '-')
+    .slice(0, 48)
+}
+
+export function parseBundleTraceability(bundleText) {
+  const scenarios = []
+  const scenarioBlock = bundleText.match(
+    /scenarios:\s*([\s\S]*?)(?:\n\s{2}\w|\nacceptanceCriteria:|\n\w[\w-]*:)/,
+  )
+  if (scenarioBlock) {
+    for (const m of scenarioBlock[1].matchAll(/-?\s*name:\s*["']?([^"'\n]+)["']?/g)) {
+      const name = m[1].trim()
+      if (name) {
+        scenarios.push({ name, slug: scenarioToSlug(name) })
+      }
+    }
+  }
+
+  const acceptance = []
+  const acIdx = bundleText.indexOf('acceptanceCriteria:')
+  if (acIdx !== -1) {
+    const tail = bundleText.slice(acIdx)
+    const lines = tail.split('\n').slice(1)
+    let i = 0
+    for (const line of lines) {
+      if (/^\S/.test(line) && !line.startsWith(' ')) break
+      const item = line.match(/^\s*-\s*(.+)$/)
+      if (item) {
+        i += 1
+        let text = item[1].replace(/^["']|["']$/g, '').trim()
+        text = text.replace(/^\[\s*\]\s*/, '').trim()
+        if (text) {
+          acceptance.push({
+            id: `AC-${String(i).padStart(2, '0')}`,
+            text,
+          })
+        }
+      }
+    }
+  }
+
+  const actions = []
+  const actionsIdx = bundleText.indexOf('\n  actions:')
+  const searchFrom = actionsIdx !== -1 ? actionsIdx : bundleText.indexOf('actions:')
+  if (searchFrom !== -1) {
+    const slice = bundleText.slice(searchFrom)
+    for (const m of slice.matchAll(/\n\s*-?\s*id:\s*(btn_[\w]+)/g)) {
+      const id = m[1]
+      const chunk = slice.match(new RegExp(`id:\\s*${id}[\\s\\S]*?(?=\\n\\s*-?\\s*id:\\s*btn_|$)`))
+      const hasOutcomes = chunk && chunk[0].includes('outcomes:')
+      actions.push({ id, hasOutcomes })
+    }
+  }
+
+  const pageIdMatch = bundleText.match(/^page-id:\s*["']?([^"'\n]+)["']?/m)
+  const screenId = pageIdMatch?.[1]?.trim()
+
+  return { scenarios, acceptance, actions, screenId }
+}

package/engines/cases/lib/render-github-catalog.mjs

@@ -0,0 +1,141 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+const CATALOG_ROOTS = ['cases', 'scenarios', 'plans']
+
+const SKIP_NEST = new Set(['node_modules', '.git', 'code', 'dist', 'cache', 'registries', '.cursor'])
+
+const README_MARKER = '<!-- flowgrid-test-catalog -->'
+const README_END = '<!-- /flowgrid-test-catalog -->'
+const README_BLOCK = `${README_MARKER}
+**[Danh mục Testcase](CATALOG.md)**
+${README_END}
+`
+
+function posixRel(root, file) {
+  return path.relative(root, file).split(path.sep).join('/')
+}
+
+function mdTitle(file, fallback) {
+  try {
+    const text = readFileSync(file, 'utf8')
+    const m = text.match(/^#\s+(.+)$/m)
+    if (m) return m[1].trim()
+  } catch {
+    /* ignore */
+  }
+  return fallback
+}
+
+
+function listDir(dir) {
+  if (!existsSync(dir)) return []
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+}
+
+function walkTree(dir, root) {
+  const children = []
+  const entries = listDir(dir).sort((a, b) => a.name.localeCompare(b.name))
+  for (const ent of entries) {
+    const full = path.join(dir, ent.name)
+    if (ent.isDirectory()) {
+      if (SKIP_NEST.has(ent.name)) continue
+      const nested = walkTree(full, root)
+      const index = path.join(full, 'index.md')
+      const hasIndex = existsSync(index)
+      
+      let title = ent.name.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase())
+      if (hasIndex) {
+        const extracted = mdTitle(index, null)
+        if (extracted) title = extracted
+      }
+
+      if (!nested.length && !hasIndex) continue
+      children.push({
+        text: title,
+        href: hasIndex ? posixRel(root, index) : undefined,
+        children: nested,
+      })
+      continue
+    }
+    if (ent.isFile() && ent.name.endsWith('.md') && ent.name !== 'index.md' && ent.name !== 'CATALOG.md') {
+      const nameWithoutExt = ent.name.replace(/\.md$/, '')
+      let title = nameWithoutExt
+      if (!/^(TC|SC)-/i.test(nameWithoutExt)) {
+        title = nameWithoutExt.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase())
+        const extracted = mdTitle(full, null)
+        if (extracted) title = extracted
+      }
+      
+      children.push({
+        text: title,
+        href: posixRel(root, full),
+      })
+    }
+  }
+  return children
+}
+
+function renderTree(nodes, depth = 0) {
+  const pad = '  '.repeat(depth)
+  const lines = []
+  for (const node of nodes || []) {
+    const label = node.href ? `[${node.text}](${node.href})` : node.text
+    lines.push(`${pad}- ${label}`)
+    if (node.children?.length) lines.push(...renderTree(node.children, depth + 1))
+  }
+  return lines
+}
+
+export function writeGithubCatalog(root = process.cwd()) {
+  const hub = path.resolve(root)
+  mkdirSync(hub, { recursive: true })
+
+  const lines = [
+    '# Danh mục Testcase & Scenario',
+    '',
+    '_Sinh bởi `flowgrid tests:publish`. Click link để mở tài liệu. Không sửa tay._',
+    '',
+  ]
+
+  for (const name of CATALOG_ROOTS) {
+    const dir = path.join(hub, name)
+    const children = walkTree(dir, hub)
+    if (!children.length) continue
+    const index = path.join(dir, 'index.md')
+    const href = existsSync(index) ? posixRel(hub, index) : undefined
+    lines.push(...renderTree([{ text: cap(name), href, children }]), '')
+  }
+
+  const catalogPath = path.join(hub, 'CATALOG.md')
+  writeFileSync(catalogPath, `${lines.join('\n').trim()}\n`)
+  ensureReadmeCatalogLink(hub)
+  return catalogPath
+}
+
+function cap(name) {
+  return name.charAt(0).toUpperCase() + name.slice(1)
+}
+
+export function ensureReadmeCatalogLink(root) {
+  const readme = path.join(root, 'README.md')
+  const existing = existsSync(readme) ? readFileSync(readme, 'utf8') : '# Test Hub\n'
+  const rest = stripCatalogBlock(existing).replace(/^\s+/, '')
+  writeFileSync(readme, `${README_BLOCK}\n${rest}`.replace(/\n+$/, '\n'))
+}
+
+function stripCatalogBlock(text) {
+  const paired = /<!-- flowgrid-test-catalog -->[\s\S]*?<!-- \/flowgrid-test-catalog -->\n*/
+  if (paired.test(text)) return text.replace(paired, '')
+  if (text.includes(README_MARKER)) {
+    return (
+      text.slice(0, text.indexOf(README_MARKER)) +
+      text.slice(text.indexOf(README_MARKER)).replace(/^[\s\S]*?\n\n/, '')
+    )
+  }
+  return text
+}

package/engines/cases/lib/resolve-bundle-from-screen.mjs

@@ -0,0 +1,73 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { resolveHubId } from '../../testcase/runners/lib/resolve-hub-id.mjs'
+
+/**
+ * Resolve function *.bundle.yaml from docs hub using W-* screen id.
+ * @param {string} projectRoot — tests hub or FE repo root (for platform-repos)
+ * @param {string} screenId
+ * @param {{ docsRoot?: string }} [opts]
+ * @returns {string | null} absolute bundle path
+ */
+export function resolveBundleFromScreen(projectRoot, screenId, opts = {}) {
+  const prev = process.env.FLOWGRID_DOCS_ROOT
+  if (opts.docsRoot) {
+    process.env.FLOWGRID_DOCS_ROOT = path.resolve(opts.docsRoot)
+  }
+  try {
+    const resolved = resolveHubId(projectRoot, screenId, 'codegen')
+    const designPath = resolved.paths?.[0]
+    if (!designPath) return null
+    const featureDir = path.dirname(path.dirname(designPath))
+    if (!fs.existsSync(featureDir)) return null
+    const bundle = fs
+      .readdirSync(featureDir)
+      .find((f) => f.endsWith('.bundle.yaml'))
+    if (bundle) return path.join(featureDir, bundle)
+  } catch {
+    if (opts.docsRoot) {
+      return findBundleByScreenWalk(opts.docsRoot, screenId)
+    }
+  } finally {
+    if (opts.docsRoot) {
+      if (prev === undefined) delete process.env.FLOWGRID_DOCS_ROOT
+      else process.env.FLOWGRID_DOCS_ROOT = prev
+    }
+  }
+  return null
+}
+
+function findBundleByScreenWalk(docsRoot, screenId) {
+  const hits = []
+  const walk = (dir, depth) => {
+    if (depth > 12) return
+    let entries
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of entries) {
+      if (e.name.startsWith('.') || e.name === 'node_modules') continue
+      const full = path.join(dir, e.name)
+      if (e.isDirectory()) walk(full, depth + 1)
+      else if (e.name.endsWith('.bundle.yaml')) {
+        try {
+          const text = fs.readFileSync(full, 'utf8')
+          if (
+            text.includes(screenId) ||
+            new RegExp(`^page-id:\\s*["']?${screenId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'm').test(
+              text,
+            )
+          ) {
+            hits.push(full)
+          }
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+  }
+  walk(path.join(docsRoot, 'surfaces'), 0)
+  return hits[0] ?? null
+}