@shanyucoder/flowgrid 0.1.0

package/engines/testcase/runners/lib/read-testcase.mjs

@@ -0,0 +1,179 @@
+import { readFile, readdir } from 'node:fs/promises'
+import path from 'node:path'
+import { parse } from 'yaml'
+import { resolveFeatureDir } from './read-spec.mjs'
+import { resolveHubId, resolveProjectRoot } from './resolve-hub-id.mjs'
+
+let docsEnrichmentWarningEmitted = false
+
+function warnDocsEnrichmentUnavailable(error) {
+  if (docsEnrichmentWarningEmitted) return
+  docsEnrichmentWarningEmitted = true
+  const reason = String(error?.message ?? error ?? 'docs hub input is unavailable').replace(/\s+/g, ' ')
+  console.warn(
+    `  warn: optional docs enrichment unavailable (${reason}); testcase generation continues without docs hub ir/design.yaml context. ` +
+      'Set FLOWGRID_DOCS_ROOT to a valid docs hub to enable enrichment.',
+  )
+}
+
+/**
+ * Normalize hub R3 cases for testcase:gen.
+ * Supports coverage[] (R3.2), testData→data, a11y / #e2e:a11y-wcag.
+ * @param {Record<string, unknown>} testcase
+ */
+export function normalizeTestcaseForGen(testcase) {
+  const out = { ...testcase }
+
+  if (Array.isArray(out.coverage) && out.coverage.length) {
+    out._coverage = [...out.coverage]
+  }
+
+  if (out.genType === 'e2e' || out.type === 'e2e') {
+    if (out.type && out.type !== 'e2e') out._taxonomyType = out.type
+    out.type = 'e2e'
+  } else if (out.type && out.type !== 'e2e') {
+    if (
+      out.genType === 'e2e' ||
+      out.refs?.screen ||
+      out.automation === 'automated' ||
+      out._coverage
+    ) {
+      out._taxonomyType = out.type
+      out.type = 'e2e'
+    }
+  }
+  if (!out.type && (out.genType === 'e2e' || out._coverage || out.refs?.screen)) {
+    out.type = 'e2e'
+  }
+  if (!out.type) out.type = 'e2e'
+
+  if (!out.feature && out.refs?.screen) {
+    out.feature = String(out.refs.screen).toLowerCase().replace(/_/g, '-')
+  }
+  if (!out.route) {
+    out.route = { path: '/login', auth: 'guest' }
+  }
+
+  if (!out.data && out.testData && typeof out.testData === 'object') {
+    out.data = out.testData
+  }
+
+  const needsA11y =
+    Boolean(out.a11y) ||
+    (Array.isArray(out.coverage) && out.coverage.includes('accessibility')) ||
+    (Array.isArray(out.tags) &&
+      out.tags.some((t) => String(t).includes('a11y-wcag') || String(t) === 'a11y'))
+
+  if (!out.tags) out.tags = ['#e2e:semantic-smoke']
+  else if (Array.isArray(out.tags) && !out.tags.some((t) => String(t).startsWith('#e2e'))) {
+    out.tags = [...out.tags, '#e2e:semantic-smoke']
+  }
+
+  if (needsA11y) {
+    const hasA11yTag = out.tags.some(
+      (t) => String(t).includes('a11y-wcag') || String(t) === '#e2e:a11y-wcag',
+    )
+    if (!hasA11yTag) out.tags = [...out.tags, '#e2e:a11y-wcag']
+
+    out.assertions = { ...(out.assertions || {}) }
+    out.assertions.semantic = { ...(out.assertions.semantic || {}) }
+    if (!Array.isArray(out.assertions.semantic.accessibility)) {
+      out.assertions.semantic.accessibility = ['toHaveNoA11yViolations']
+    }
+  }
+
+  if (typeof out.expected === 'string') {
+    out.expected = [out.expected]
+  }
+  if (!out.expected) out.expected = []
+  if (!out.assertions && out.testIds) {
+    out.assertions = {
+      semantic: {
+        ready: {
+          waitForTestIds: out.testIds.required ?? [],
+        },
+      },
+    }
+  }
+  if (!out.steps) out.steps = []
+  return out
+}
+
+/**
+ * Resolve optional ir/design.yaml from refs.screen for docs hub enrichment.
+ * @param {string} repoRoot
+ * @param {Record<string, unknown>} testcase
+ */
+async function loadDesignSpec(repoRoot, testcase) {
+  const screen = testcase.refs?.screen
+  if (!screen || typeof screen !== 'string') return { spec: null, specFile: null, featureDir: null }
+  try {
+    const resolved = resolveHubId(repoRoot, screen, 'codegen')
+    const abs = resolved.paths?.[0]
+    if (!abs) throw new Error(`No docs hub ir/design.yaml resolved for ${screen}`)
+    const raw = await readFile(abs, 'utf8')
+    const spec = parse(raw) ?? {}
+    return {
+      spec,
+      specFile: path.relative(repoRoot, abs),
+      featureDir: resolveFeatureDir(abs),
+    }
+  } catch (error) {
+    warnDocsEnrichmentUnavailable(error)
+    return { spec: null, specFile: null, featureDir: null }
+  }
+}
+
+/**
+ * @param {string} testcasePath
+ * @param {{ repoRoot?: string }} [opts]
+ */
+export async function readTestcaseFile(testcasePath, opts = {}) {
+  const repoRoot = opts.repoRoot ? path.resolve(opts.repoRoot) : process.cwd()
+  const absolute = path.resolve(testcasePath)
+  const raw = await readFile(absolute, 'utf8')
+  let testcase = parse(raw) ?? {}
+  testcase = normalizeTestcaseForGen(testcase)
+
+  if (!testcase.id) {
+    throw new Error(`Missing id in ${testcasePath}`)
+  }
+  // After normalize, type should be e2e for gen; taxonomy kept in _taxonomyType
+  if (testcase.type && testcase.type !== 'e2e') {
+    throw new Error(`testcase:gen only supports e2e gen — got "${testcase.type}" in ${testcasePath}`)
+  }
+
+  const design = await loadDesignSpec(repoRoot, testcase)
+  const casesDir = path.dirname(absolute)
+
+  return {
+    testcase,
+    testcaseFile: path.relative(repoRoot, absolute),
+    featureDir: path.relative(repoRoot, design.featureDir ?? casesDir),
+    specFile: design.specFile,
+    spec: design.spec,
+  }
+}
+
+/**
+ * List TC-*.yaml under the tests hub cases/{screenId}/ (prefer --id).
+ * @param {string} root FE repo root
+ * @param {string} screenId e.g. W-AD-AUTH-001
+ */
+export async function listFeatureTestcases(root, screenId) {
+  const testsRoot = process.env.FLOWGRID_TESTS_DOC ? path.resolve(process.env.FLOWGRID_TESTS_DOC) : resolveProjectRoot(root, 'tests')
+  const screenDir = path.join(testsRoot, 'cases', screenId)
+  const files = []
+  let entries = []
+  try {
+    entries = await readdir(screenDir, { withFileTypes: true })
+  } catch {
+    return files
+  }
+  for (const entry of entries) {
+    if (entry.isFile() && /^TC-.*\.ya?ml$/i.test(entry.name)) {
+      files.push(path.join(screenDir, entry.name))
+    }
+  }
+  return files.sort()
+}

package/engines/testcase/runners/lib/render.mjs

@@ -0,0 +1,18 @@
+import Handlebars from 'handlebars'
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..')
+const templatesDir = path.join(rootDir, 'templates')
+
+/**
+ * @param {string} templateRel
+ * @param {Record<string, unknown>} context
+ */
+export async function renderTemplate(templateRel, context) {
+  const templatePath = path.join(templatesDir, templateRel)
+  const source = await readFile(templatePath, 'utf8')
+  const template = Handlebars.compile(source, { noEscape: true })
+  return `${template(context).trim()}\n`
+}

package/engines/testcase/runners/lib/resolve-hub-id.mjs

@@ -0,0 +1,324 @@
+/**
+ * Resolve short hub IDs → filesystem paths (docs hub + tests hub).
+ * IDs: W-* | API-* | UI-* | CMP-* | FLOW-* | DEP-* | TC-* | SC-* | suite id (smoke, …)
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import path from 'node:path'
+
+function loadJson(file) {
+  if (!existsSync(file)) return null
+  return JSON.parse(readFileSync(file, 'utf8'))
+}
+
+function deepMerge(base, over) {
+  if (!over || typeof over !== 'object') return base
+  const out = { ...base }
+  for (const [k, v] of Object.entries(over)) {
+    if (v && typeof v === 'object' && !Array.isArray(v) && base[k] && typeof base[k] === 'object') {
+      out[k] = deepMerge(base[k], v)
+    } else out[k] = v
+  }
+  return out
+}
+
+export function findPlatformReposDir(startDir) {
+  let dir = path.resolve(startDir)
+  while (true) {
+    const file = path.join(dir, 'platform-repos.json')
+    if (existsSync(file)) return dir
+    const parent = path.dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+export function loadPlatformRepos(repoRoot) {
+  const dir = findPlatformReposDir(repoRoot)
+  if (!dir) throw new Error(`Missing platform-repos.json in ${repoRoot} or any parent directories`)
+  let doc = loadJson(path.join(dir, 'platform-repos.json'))
+  const local = loadJson(path.join(dir, 'platform-repos.local.json'))
+  if (local) doc = deepMerge(doc, local)
+  return doc
+}
+
+export function resolveProjectRoot(repoRoot, projectId) {
+  const dir = findPlatformReposDir(repoRoot) || repoRoot
+  let doc = loadJson(path.join(dir, 'platform-repos.json'))
+  if (!doc) throw new Error(`Missing platform-repos.json in ${repoRoot} or any parent directories`)
+  const local = loadJson(path.join(dir, 'platform-repos.local.json'))
+  if (local) doc = deepMerge(doc, local)
+
+  const proj = doc.projects?.[projectId]
+  if (!proj?.root) throw new Error(`Unknown project "${projectId}" in platform-repos.json`)
+  return path.resolve(dir, proj.root)
+}
+
+export function loadDocsIndex(docsRoot) {
+  const file = path.join(docsRoot, 'registries', 'docs-index.json')
+  const idx = loadJson(file)
+  if (!idx) throw new Error(`Missing ${file}`)
+  return idx
+}
+
+export function loadTestsIndex(testsRoot) {
+  const file = path.join(testsRoot, 'registries', 'tests-index.json')
+  const idx = loadJson(file)
+  if (!idx) {
+    return buildTestsIndexFallback(testsRoot)
+  }
+  return idx
+}
+
+/** Scan cases/ + suites/ when index missing */
+function buildTestsIndexFallback(testsRoot) {
+  const codeIds = {}
+  const casesDir = path.join(testsRoot, 'cases')
+  const suites = {}
+  if (existsSync(casesDir)) {
+    for (const screen of readdirSync(casesDir, { withFileTypes: true })) {
+      if (!screen.isDirectory() || screen.name.startsWith('.')) continue
+      const screenPath = path.join(casesDir, screen.name)
+      codeIds[screen.name] = path.relative(testsRoot, screenPath).split(path.sep).join('/')
+      for (const f of readdirSync(screenPath)) {
+        if (/^TC-.*\.ya?ml$/i.test(f)) {
+          const id = f.replace(/\.ya?ml$/i, '')
+          codeIds[id] = path.relative(testsRoot, path.join(screenPath, f)).split(path.sep).join('/')
+        }
+      }
+    }
+  }
+  const suitesDir = path.join(testsRoot, 'suites')
+  if (existsSync(suitesDir)) {
+    for (const f of readdirSync(suitesDir)) {
+      if (!f.endsWith('.yaml') && !f.endsWith('.yml')) continue
+      const raw = readFileSync(path.join(suitesDir, f), 'utf8')
+      const idMatch = raw.match(/^id:\s*(\S+)/m)
+      const sid = idMatch?.[1] || f.replace(/\.ya?ml$/i, '')
+      suites[sid] = path.relative(testsRoot, path.join(suitesDir, f)).split(path.sep).join('/')
+    }
+  }
+
+  const scenarios = {}
+  const scenariosDir = path.join(testsRoot, 'scenarios')
+  if (existsSync(scenariosDir)) {
+    for (const cmp of readdirSync(scenariosDir, { withFileTypes: true })) {
+      if (!cmp.isDirectory() || cmp.name.startsWith('.')) continue
+      const cmpPath = path.join(scenariosDir, cmp.name)
+      for (const f of readdirSync(cmpPath)) {
+        if (!/^SC-.*\.md$/i.test(f)) continue
+        const raw = readFileSync(path.join(cmpPath, f), 'utf8')
+        
+        const idMatch = raw.match(/^id:\s*(\S+)/m)
+        const sid = idMatch?.[1] || f.replace(/\.md$/i, '')
+        const capabilityMatch = raw.match(/^capability:\s*(\S+)/m)
+        const featureMatch = raw.match(/^feature:\s*(\S+)/m)
+        const screenMatch = raw.match(/^screen:\s*(\S+)/m)
+        
+        const caseMatches = [...raw.matchAll(/(TC-[\w-]+)/g)]
+        const cases = [...new Set(caseMatches.map(m => m[1]))]
+
+        scenarios[sid] = {
+          capability: capabilityMatch?.[1],
+          component: featureMatch?.[1] || cmp.name,
+          screen: screenMatch?.[1],
+          cases
+        }
+      }
+    }
+  }
+
+  return { version: 1, codeIds, suites, scenarios }
+}
+
+function absUnder(root, rel) {
+  if (!rel) return null
+  const abs = path.resolve(root, rel)
+  if (!existsSync(abs)) return null
+  return abs
+}
+
+function findFlowMarkdown(docsRoot, id) {
+  const catalog = path.join(docsRoot, 'architecture', '03-business-process', `${id}.md`)
+  if (existsSync(catalog)) return catalog
+  const hits = []
+  const walk = (dir) => {
+    if (!existsSync(dir)) return
+    for (const ent of readdirSync(dir, { withFileTypes: true })) {
+      if (ent.name.startsWith('.') || ent.name === 'node_modules') continue
+      const p = path.join(dir, ent.name)
+      if (ent.isDirectory()) {
+        walk(p)
+        continue
+      }
+      if (ent.name === `${id}.md` && p.split(path.sep).join('/').includes('/common/processes/')) {
+        hits.push(p)
+      }
+    }
+  }
+  walk(path.join(docsRoot, 'surfaces'))
+  return hits[0] ?? null
+}
+
+/** ir/design.yaml only. Missing file = incomplete split. */
+export function preferGenSpec(codeDir) {
+  if (!codeDir || !existsSync(codeDir)) return null
+  const design = path.join(codeDir, 'ir', 'design.yaml')
+  return existsSync(design) ? design : null
+}
+
+/**
+ * @param {string} repoRoot FE/BE code project
+ * @param {string} id
+ * @param {'codegen'|'testcase'} mode
+ * @returns {{ kind: string, id: string, paths: string[], notes: string[] }}
+ */
+export function resolveHubId(repoRoot, id, mode = 'testcase') {
+  if (!id || typeof id !== 'string') throw new Error('Missing --id')
+  const notes = []
+  let docs
+  let tests
+  const getDocsRoot = () =>
+    process.env.FLOWGRID_DOCS_ROOT
+      ? path.resolve(process.env.FLOWGRID_DOCS_ROOT)
+      : resolveProjectRoot(repoRoot, 'docs')
+  const getDocs = () => {
+    if (!docs) {
+      const root = getDocsRoot()
+      docs = { root, index: loadDocsIndex(root) }
+    }
+    return docs
+  }
+  const getTests = () => {
+    if (!tests) {
+      const root = process.env.FLOWGRID_TESTS_DOC
+        ? path.resolve(process.env.FLOWGRID_TESTS_DOC)
+        : resolveProjectRoot(repoRoot, 'tests')
+      tests = { root, index: loadTestsIndex(root) }
+    }
+    return tests
+  }
+
+  // FLOW-* before tests-hub lookup (no platform-repos required)
+  if (/^FLOW-/i.test(id)) {
+    if (mode === 'codegen') {
+      throw new Error(`FLOW is a process id, use SC-* or W-* (not ir/design.yaml)`)
+    }
+    const docsRoot = getDocsRoot()
+    const md = findFlowMarkdown(docsRoot, id)
+    if (!md) {
+      throw new Error(`Unknown FLOW ${id} — expected architecture/03-business-process/${id}.md or …/common/processes/${id}.md`)
+    }
+    notes.push(`flow markdown: ${path.relative(repoRoot, md)}`)
+    return { kind: 'flow', id, paths: [md], notes }
+  }
+
+  // Suite
+  const testcaseHub = mode === 'testcase' ? getTests() : null
+  if (testcaseHub?.index.suites?.[id]) {
+    const { root: testsRoot, index: testsIdx } = testcaseHub
+    const suitePath = absUnder(testsRoot, testsIdx.suites[id])
+    const raw = readFileSync(suitePath, 'utf8')
+    const caseIds = [...raw.matchAll(/^\s*-\s+(TC-[\w-]+)/gm)].map((m) => m[1])
+    const paths = []
+    for (const cid of caseIds) {
+      const rel = testsIdx.codeIds?.[cid]
+      const p = absUnder(testsRoot, rel)
+      if (p) paths.push(p)
+      else notes.push(`suite ${id}: missing case ${cid}`)
+    }
+    return { kind: 'suite', id, paths, notes, suitePath }
+  }
+
+  // TC-* file
+  if (/^TC-/i.test(id)) {
+    const { root: testsRoot, index: testsIdx } = getTests()
+    const rel = testsIdx.codeIds?.[id]
+    const p = absUnder(testsRoot, rel)
+    if (!p) throw new Error(`Unknown testcase id ${id} — update the tests hub registries/tests-index.json`)
+    return { kind: 'testcase', id, paths: [p], notes }
+  }
+
+  // Screen / API / UI code folder on docs
+  if (/^(W|API|UI)-/i.test(id) || /^[a-z]+-[a-z]+-\d{3}(-\d{2,3})+$/i.test(id)) {
+    if (mode === 'testcase') {
+      const { root: testsRoot, index: testsIdx } = getTests()
+      const screenRel = testsIdx.codeIds?.[id] || `cases/${id}`
+      const screenDir = absUnder(testsRoot, screenRel)
+      if (!screenDir) throw new Error(`No cases folder for ${id} in the tests hub`)
+      const paths = readdirSync(screenDir)
+        .filter((f) => /^TC-.*\.ya?ml$/i.test(f))
+        .map((f) => path.join(screenDir, f))
+        .sort()
+      if (!paths.length) throw new Error(`No TC-*.yaml under ${screenDir}`)
+      return { kind: 'screen-cases', id, paths, notes }
+    }
+    // codegen
+    const { root: docsRoot, index: docsIdx } = getDocs()
+    const rel = docsIdx.codeIds?.[id]
+    if (!rel) throw new Error(`Unknown code id ${id} in the docs hub registries/docs-index.json`)
+    const codeDir = absUnder(docsRoot, rel)
+    const spec = preferGenSpec(codeDir)
+    if (!spec) throw new Error(`No ir/design.yaml under ${rel}`)
+    notes.push(`codegen input: ${path.relative(repoRoot, spec)}`)
+    return { kind: 'code', id, paths: [spec], notes, codeDir }
+  }
+
+  // Module (e.g. CMP-ADM-001) → all code children
+  if (/^[A-Z]+-[A-Z]+-\d{3}$/i.test(id)) {
+    const { index: docsIdx } = getDocs()
+    const cmp = (docsIdx.modules || []).find(
+      (c) => c.id === id || c.id.startsWith(id) || (c.slug && id.toLowerCase().includes(c.slug)),
+    )
+    if (!cmp) throw new Error(`Unknown module ${id}`)
+    const paths = []
+    if (mode === 'testcase') {
+      for (const screen of cmp.screens || []) {
+        const sub = resolveHubId(repoRoot, screen, 'testcase')
+        paths.push(...sub.paths)
+        notes.push(...sub.notes)
+      }
+      return { kind: 'component-cases', id, paths, notes }
+    }
+    for (const screen of cmp.screens || []) {
+      try {
+        const sub = resolveHubId(repoRoot, screen, 'codegen')
+        paths.push(...sub.paths)
+        notes.push(...sub.notes)
+      } catch (e) {
+        notes.push(String(e.message || e))
+      }
+    }
+    for (const api of cmp.apis || []) {
+      notes.push(`skip API ${api} for FE codegen; design lives in docs hub`)
+    }
+    if (!paths.length) {
+      throw new Error(`CMP ${id}: no gen-ready W-* specs (need ir/design.yaml after /grill-dev + spec:split)`)
+    }
+    return { kind: 'component-code', id, paths, notes }
+  }
+
+
+
+  // SC-* scenario → cases listed in tests index
+  if (/^SC-/i.test(id)) {
+    const testsIdx = getTests().index
+    const sc = testsIdx.scenarios?.[id]
+    if (!sc?.cases?.length) {
+      throw new Error(`Unknown scenario ${id} — add scenarios.${id}.cases in tests-index.json`)
+    }
+    const paths = []
+    for (const cid of sc.cases) {
+      const sub = resolveHubId(repoRoot, cid, 'testcase')
+      paths.push(...sub.paths)
+    }
+    return { kind: 'scenario', id, paths, notes }
+  }
+
+  if (/^DEP-/i.test(id)) {
+    throw new Error(`DEP-* is architecture, not a codegen/testcase file id`)
+  }
+
+  throw new Error(
+    `Unrecognized id "${id}". Use W-|API-|UI-|FLOW-|DEP-|TC-|SC-* or hierarchical ID (e.g. cmp-adm-001-01-01), or module ID (CMP-ADM-001), or suite id (smoke, regression-auth).`,
+  )
+}

package/engines/testcase/runners/lib/semantic-plan.mjs

@@ -0,0 +1,178 @@
+import {
+  bundleIdsFromTags,
+  loadE2eTestRegistry,
+  resolveBundleMatchers,
+  skipMatchersFromTags
+} from './e2e-registry.mjs'
+
+const SECTION_KEYS = ['level1', 'layout', 'accessibility', 'designToken']
+
+/**
+ * @param {string} root
+ * @param {Record<string, unknown>} testcase
+ */
+export async function resolveSemanticPlan(root, testcase) {
+  const { registry } = await loadE2eTestRegistry(root)
+  const tags = testcase.tags ?? []
+  const semantic = testcase.assertions?.semantic ?? {}
+  const warnings = []
+
+  const skipMatchers = skipMatchersFromTags(tags, registry)
+  const bundleIds = bundleIdsFromTags(tags, registry)
+  const bundles = registry.bundles ?? {}
+  const matcherMeta = registry.matchers ?? {}
+
+  /** @type {string[]} */
+  const ordered = []
+
+  for (const bundleId of bundleIds) {
+    ordered.push(...resolveBundleMatchers(bundleId, bundles))
+  }
+
+  for (const key of SECTION_KEYS) {
+    const list = semantic[key]
+    if (Array.isArray(list)) {
+      ordered.push(...list.map(String))
+    }
+  }
+
+  const seen = new Set()
+  /** @type {string[]} */
+  const matchers = []
+  for (const name of ordered) {
+    if (skipMatchers.has(name)) continue
+    if (seen.has(name)) continue
+    const meta = matcherMeta[name]
+    if (!meta) {
+      warnings.push(`unknown semantic matcher "${name}" — add to registries/e2e-test.registry.json`)
+      continue
+    }
+    if (meta.status === 'planned') {
+      warnings.push(`semantic matcher "${name}" is planned — skipped in codegen`)
+      continue
+    }
+    seen.add(name)
+    matchers.push(name)
+  }
+
+  const semanticReady = semantic.ready ?? null
+  const rootTestId = semanticReady?.rootTestId ?? semantic.rootTestId ?? null
+  const tableTestId =
+    semantic.tableTestId ??
+    semanticReady?.waitForTestIds?.find((id) => String(id).includes('table')) ??
+    null
+
+  const layoutOptions = semantic.layoutOptions ?? {}
+  const skipOverlap = layoutOptions.skipOverlap === true
+  const a11y = testcase.a11y && typeof testcase.a11y === 'object' ? testcase.a11y : null
+
+  const matchersNeedingRoot = new Set([
+    'toHaveNoTextOverflow',
+    'toHaveNoElementOverlap',
+    'toHaveValidTableLayout',
+    'toMatchShadcnTableToken',
+  ])
+  if (matchers.some((name) => matchersNeedingRoot.has(name)) && !rootTestId) {
+    warnings.push(
+      'layout/table semantic matchers require assertions.semantic.ready.rootTestId (or semantic.rootTestId)',
+    )
+  }
+
+  if (matchers.includes('toHaveValidTableLayout') && !tableTestId) {
+    warnings.push('toHaveValidTableLayout requires semantic.tableTestId or waitForTestIds containing "table"')
+  }
+
+  const needsConsoleErrors = matchers.some(
+    (name) => matcherMeta[name]?.needsConsoleErrors === true
+  )
+  const useSemanticFixture = matchers.length > 0
+
+  const codegenLines = matchers
+    .map((name) => codegenMatcher(name, { rootTestId, tableTestId, skipOverlap, a11y }))
+    .filter(Boolean)
+
+  return {
+    semanticReady,
+    useSemanticFixture,
+    needsConsoleErrors,
+    semanticCodegenLines: codegenLines,
+    semanticMatchers: matchers,
+    rootTestId,
+    a11y,
+    warnings
+  }
+}
+
+/**
+ * @param {string} matcher
+ * @param {{
+ *   rootTestId: string | null,
+ *   tableTestId: string | null,
+ *   skipOverlap: boolean,
+ *   a11y?: Record<string, unknown> | null
+ * }} ctx
+ */
+function codegenMatcher(matcher, ctx) {
+  const { rootTestId, tableTestId, skipOverlap, a11y } = ctx
+  const a11yOptsLiteral = formatA11yOpts(a11y, rootTestId)
+  const include = rootTestId ? `[data-testid="${rootTestId}"]` : undefined
+  const rootLoc = rootTestId ? `page.getByTestId('${rootTestId}')` : 'page.locator("body")'
+  const scrollOpts = include ? `{ rootSelector: '${include}' }` : '{}'
+  const overflowOpts = `{ allowTruncate: true }`
+
+  switch (matcher) {
+    case 'toHaveNoConsoleErrors':
+      return 'await expect(page).toHaveNoConsoleErrors(consoleErrors)'
+    case 'toHaveNoHorizontalScroll':
+      return `await expect(page).toHaveNoHorizontalScroll(${scrollOpts})`
+    case 'toHaveNoBrokenImages':
+      return 'await expect(page).toHaveNoBrokenImages()'
+    case 'toHaveNoTextOverflow':
+      return `await expect(${rootLoc}).toHaveNoTextOverflow(${overflowOpts})`
+    case 'toHaveNoElementOverlap':
+      if (skipOverlap) return null
+      return `await expect(${rootLoc}).toHaveNoElementOverlap()`
+    case 'toHaveValidTableLayout':
+      if (!tableTestId) return null
+      return `await expect(page.getByTestId('${tableTestId}')).toHaveValidTableLayout()`
+    case 'toHaveNoA11yViolations':
+      return `await expect(page).toHaveNoA11yViolations(${a11yOptsLiteral})`
+    case 'toHaveValidAccessibleNames':
+      return `await expect(page).toHaveValidAccessibleNames(${a11yOptsLiteral})`
+    case 'toHaveValidAria':
+      return `await expect(page).toHaveValidAria(${a11yOptsLiteral})`
+    case 'toHaveAccessibleMedia':
+      return `await expect(page).toHaveAccessibleMedia(${a11yOptsLiteral})`
+    case 'toHaveReadableContrast':
+      return `await expect(page).toHaveReadableContrast(${a11yOptsLiteral})`
+    case 'toHaveValidDocumentSemantics':
+      return `await expect(page).toHaveValidDocumentSemantics(${a11yOptsLiteral})`
+    case 'toMatchShadcnTableToken':
+      if (!tableTestId) return null
+      return `await expect(page.getByTestId('${tableTestId}')).toMatchShadcnTableToken()`
+    default:
+      return null
+  }
+}
+
+/**
+ * Build Playwright expect a11y options from hub `a11y:` block.
+ * @param {Record<string, unknown> | null | undefined} a11y
+ * @param {string | null} rootTestId
+ */
+function formatA11yOpts(a11y, rootTestId) {
+  /** @type {Record<string, unknown>} */
+  const opts = {}
+  if (a11y?.include?.length) {
+    opts.include = Array.isArray(a11y.include) ? a11y.include[0] : a11y.include
+  } else if (rootTestId) {
+    opts.include = `[data-testid="${rootTestId}"]`
+  }
+  if (Array.isArray(a11y?.exclude) && a11y.exclude.length) opts.exclude = a11y.exclude
+  if (Array.isArray(a11y?.tags) && a11y.tags.length) opts.tags = a11y.tags
+  if (Array.isArray(a11y?.disableRules) && a11y.disableRules.length) {
+    opts.disableRules = a11y.disableRules
+  }
+  if (!Object.keys(opts).length) return '{}'
+  return JSON.stringify(opts)
+}