@shanyucoder/flowgrid 0.1.0

package/engines/cases/lib/screen-facet-coverage.mjs

@@ -0,0 +1,42 @@
+import { TEST_MATRIX_FACETS } from '../../spec/lib/testcase-matrix-facets.mjs'
+
+/**
+ * Per-screen union of testMatrix facets across multiple TC files.
+ * @param {Array<{ file: string; data: Record<string, unknown> }>} tcFiles
+ */
+export function auditScreenFacetCoverage(tcFiles, opts = {}) {
+  const strict = Boolean(opts.strict)
+  const byScreen = new Map()
+
+  for (const { file, data } of tcFiles) {
+    const screen = data.refs?.screen
+    if (!screen || typeof screen !== 'string') continue
+    if (!byScreen.has(screen)) byScreen.set(screen, { files: [], facets: new Set() })
+    const bucket = byScreen.get(screen)
+    bucket.files.push(file)
+    const matrix = Array.isArray(data.testMatrix) ? data.testMatrix : []
+    for (const row of matrix) {
+      if (row?.facet) bucket.facets.add(String(row.facet))
+    }
+  }
+
+  const gaps = []
+  for (const [screen, { files, facets }] of byScreen) {
+    for (const required of TEST_MATRIX_FACETS) {
+      if (!facets.has(required)) {
+        gaps.push({
+          code: 'TC_SCREEN_FACET_GAP',
+          severity: strict ? 'critical' : 'warning',
+          path: `screen.${screen}.facets.${required}`,
+          message: `Screen ${screen} missing testMatrix facet "${required}" across ${files.length} TC file(s).`,
+          suggestedFix: `Add a TC-* row with facet: ${required} or split matrix across files on same refs.screen.`,
+          category: 'screen-facets',
+          screen,
+          files,
+        })
+      }
+    }
+  }
+
+  return { gaps, screens: [...byScreen.keys()] }
+}

package/engines/cases/lib/validate-tc-schema.mjs

@@ -0,0 +1,61 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import Ajv2020 from 'ajv/dist/2020.js'
+import { parse } from 'yaml'
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..')
+
+export function resolveSchemaPath() {
+  if (process.env.FLOWGRID_TESTCASE_SCHEMA) {
+    return path.resolve(process.env.FLOWGRID_TESTCASE_SCHEMA)
+  }
+  return path.join(packageRoot, 'schemas', 'testcase.schema.json')
+}
+
+let compiled
+
+async function getValidator() {
+  if (!compiled) {
+    const schema = JSON.parse(await readFile(resolveSchemaPath(), 'utf8'))
+    compiled = new Ajv2020({ allErrors: true }).compile(schema)
+  }
+  return compiled
+}
+
+export function formatValidationError(rel, error) {
+  const location = error.instancePath
+    .split('/')
+    .filter(Boolean)
+    .map((part) => part.replaceAll('~1', '/').replaceAll('~0', '~'))
+    .join('.')
+  if (error.keyword === 'required') {
+    const field = [location, error.params.missingProperty].filter(Boolean).join('.')
+    return `${rel}: ${field} required`
+  }
+  return `${rel}${location ? `: ${location}` : ''}: ${error.message}`
+}
+
+/**
+ * @param {string} filePath absolute
+ * @param {string} projectRoot
+ */
+export async function validateTcFile(filePath, projectRoot) {
+  const rel = path.relative(projectRoot, filePath)
+  const validate = await getValidator()
+  let data
+  try {
+    data = parse(await readFile(filePath, 'utf8'))
+  } catch (e) {
+    return { ok: false, rel, data: null, errors: [`${rel}: YAML parse — ${e.message}`] }
+  }
+  if (!validate(data)) {
+    return {
+      ok: false,
+      rel,
+      data,
+      errors: (validate.errors ?? []).map((err) => formatValidationError(rel, err)),
+    }
+  }
+  return { ok: true, rel, data, errors: [] }
+}

package/engines/cases/publish.mjs

@@ -0,0 +1,4 @@
+import { writeGithubCatalog } from './lib/render-github-catalog.mjs'
+
+const catalog = writeGithubCatalog(process.cwd())
+console.log(`publish: ${catalog}`)

package/engines/cases/render-cases.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+/**
+ * Render tests hub case YAML → Markdown (member-first, locale-aware).
+ * Usage: pnpm cases:render
+ *        pnpm cases:render -- cases/W-AD-AUTH-001
+ */
+import { readdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { parse, stringify } from 'yaml'
+
+const root = process.cwd()
+const casesRoot = path.join(root, 'cases')
+const args = process.argv.slice(2).filter((a) => a !== '--')
+const only = args[0] ? path.resolve(root, args[0]) : null
+const MD_NONE = '_Không có_'
+
+async function loadLocale() {
+  const raw = await readFile(path.join(root, 'catalog/locale.yaml'), 'utf8')
+  const doc = parse(raw) ?? {}
+  const loc = doc.memberLocale || 'vi'
+  const headings = doc.headings?.[loc] || doc.headings?.vi || {}
+  return { loc, h: headings }
+}
+
+async function main() {
+  const locale = await loadLocale()
+  const files = await listCaseYaml(only ?? casesRoot)
+  let n = 0
+  for (const file of files) {
+    const data = parse(await readFile(file, 'utf8')) ?? {}
+    const out = path.join(path.dirname(file), `${path.basename(file).replace(/\.ya?ml$/i, '')}.md`)
+    await writeFile(out, renderCaseMarkdown(data, locale), 'utf8')
+    n++
+    console.log(`cases:render ${path.relative(root, out)}`)
+  }
+
+  // Ensure index.md exists for root and main sections
+  const sections = ['', 'cases', 'scenarios', 'plans']
+  for (const section of sections) {
+    const sectionPath = path.join(root, section)
+    const indexPath = path.join(sectionPath, 'index.md')
+    try {
+      if (await listEntries(sectionPath).then(e => e.length > 0)) {
+        try {
+          await readFile(indexPath, 'utf8')
+        } catch {
+          const title = section ? section.charAt(0).toUpperCase() + section.slice(1) : 'Home'
+          const content = `---\nlayout: home\n---\n\n# ${title}\n\nWelcome to ${title}.`
+          await writeFile(indexPath, content, 'utf8')
+          console.log(`cases:render created ${path.relative(root, indexPath)}`)
+        }
+      }
+    } catch {}
+  }
+
+  console.log(`cases:render: OK (${n} file(s))`)
+}
+
+function renderCaseMarkdown(tc, { h }) {
+  const shortTitle = tc.title || tc.name || tc.summary || 'case'
+  const title = tc.id ? `${tc.id}: ${shortTitle}` : shortTitle
+  const story = tc.story?.trim()
+  const coverage = Array.isArray(tc.coverage) ? tc.coverage.map((c) => `\`${c}\``).join(', ') : MD_NONE
+
+  const member = [
+    `# ${title}`,
+    '',
+    story || (tc.summary ? `> ${tc.summary}` : null),
+    tc.description ? `\n${tc.description}\n` : null,
+    story || tc.summary || tc.description ? '' : null,
+    `- **id:** \`${tc.id ?? ''}\``,
+    tc.module ? `- **Module:** \`${tc.module}\`` : null,
+    `- **${h.coverage || 'Coverage'}:** ${coverage}`,
+    tc.status ? `- **Status:** \`${tc.status}\`` : null,
+    tc.priority ? `- **Priority:** \`${tc.priority}\`` : null,
+    tc.refs?.scenario ? `- **Scenario:** \`${tc.refs.scenario}\`` : null,
+    tc.refs?.rule ? `- **Rule (docs):** \`${tc.refs.rule}\`` : null,
+    tc.tags?.length ? `- **Tags:** ${tc.tags.map(t => `\`${t}\``).join(', ')}` : null,
+    '',
+    `## ${h.preconditions || 'Preconditions'}`,
+    '',
+    bullets(tc.preconditions),
+    '',
+    `## ${h.steps || 'Steps'}`,
+    '',
+    stepsNarrative(tc),
+    '',
+    `## ${h.expected || 'Expected'}`,
+    '',
+    bullets(Array.isArray(tc.expected) ? tc.expected : tc.expected ? [tc.expected] : []),
+    '',
+    '<details>',
+    `<summary>${h.technical || 'Technical details'}</summary>`,
+    '',
+    `- **title (EN):** ${tc.title ?? ''}`,
+    tc.refs ? `- **refs:** \`${JSON.stringify(tc.refs)}\`` : null,
+    '',
+    `### ${h.testData || 'Test data'}`,
+    '',
+    code(tc.testData ?? tc.data),
+    '',
+    '### Steps (machine)',
+    '',
+    stepsMachine(tc.steps),
+    '',
+    '### Test IDs',
+    '',
+    bullets(tc.testIds?.required),
+    '',
+    tc.a11y ? '### a11y\n\n' + code(tc.a11y) : null,
+    '',
+    '</details>',
+    '',
+  ]
+
+  return member.filter((x) => x !== null).join('\n')
+}
+
+function stepsNarrative(tc) {
+  const steps = tc.steps || []
+  if (!steps.length) return MD_NONE
+  return steps
+    .map((step, i) => {
+      if (step.as || step.label) return `${i + 1}. ${step.as || step.label}`
+      if (step.action === 'goto') return `${i + 1}. Mở trang \`${step.path ?? ''}\``
+      if (step.action === 'fill') return `${i + 1}. Nhập vào \`${step.testId ?? 'field'}\``
+      if (step.action === 'click') return `${i + 1}. Bấm \`${step.testId ?? 'control'}\``
+      return `${i + 1}. ${step.action ?? 'step'}`
+    })
+    .join('\n')
+}
+
+function stepsMachine(items = []) {
+  if (!items?.length) return MD_NONE
+  return items
+    .map((step, i) => {
+      const parts = Object.entries(step)
+        .map(([k, v]) => `${k}: ${inline(v)}`)
+        .join(', ')
+      return `${i + 1}. ${parts}`
+    })
+    .join('\n')
+}
+
+function bullets(items = []) {
+  return items?.length ? items.map((i) => `- ${inline(i)}`).join('\n') : MD_NONE
+}
+
+function code(value) {
+  return `\`\`\`yaml\n${stringify(value ?? {}).trim()}\n\`\`\``
+}
+
+function inline(value) {
+  if (typeof value === 'string') return value
+  return `\`${JSON.stringify(value)}\``
+}
+
+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|SC|W|CMP)-.*\.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 []
+  }
+}
+
+main().catch((e) => {
+  console.error(e)
+  process.exit(1)
+})

package/engines/cases/vitepress/config.ts

@@ -0,0 +1,171 @@
+import { withMermaid } from 'vitepress-plugin-mermaid'
+import { defineConfig } from 'vitepress'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const projectRoot = process.cwd()
+
+function buildRecursiveSidebar(dirPath: string, urlPrefix: string): any[] {
+  if (!fs.existsSync(dirPath)) return []
+  try {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true })
+    const items: any[] = []
+
+    // Read files first (excluding index.md)
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'index.md') {
+        const filePath = path.join(dirPath, entry.name)
+        const nameWithoutExt = entry.name.replace(/\.md$/, '')
+        let title = nameWithoutExt
+        if (!/^(TC|SC)-/i.test(nameWithoutExt)) {
+          title = nameWithoutExt.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase())
+          try {
+            const content = fs.readFileSync(filePath, 'utf8')
+            const titleMatch = content.match(/^#\s+(.+)$/m)
+            if (titleMatch) title = titleMatch[1].trim()
+          } catch {}
+        }
+        items.push({
+          text: title,
+          link: `${urlPrefix}${nameWithoutExt}`
+        })
+      }
+    }
+
+    // Read directories
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (['code', 'ir', 'node_modules', '.git'].includes(entry.name)) continue
+        const subDirPath = path.join(dirPath, entry.name)
+        const indexPath = path.join(subDirPath, 'index.md')
+        let title = entry.name.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase())
+        let link = undefined
+
+        if (fs.existsSync(indexPath)) {
+          try {
+            const content = fs.readFileSync(indexPath, 'utf8')
+            const titleMatch = content.match(/^#\s+(.+)$/m)
+            if (titleMatch) title = titleMatch[1].trim()
+          } catch {}
+          link = `${urlPrefix}${entry.name}/`
+        }
+
+        const subItems = buildRecursiveSidebar(subDirPath, `${urlPrefix}${entry.name}/`)
+        
+        if (!link && subItems.length > 0) {
+          const firstLinkedItem = subItems.find((s: any) => s.link)
+          if (firstLinkedItem) {
+            link = firstLinkedItem.link
+          }
+        }
+
+        const item: any = { text: title }
+        if (link) item.link = link
+        if (subItems.length > 0) {
+          item.items = subItems
+          item.collapsed = true
+        }
+        
+        if (link || subItems.length > 0) {
+          items.push(item)
+        }
+      }
+    }
+
+    return items
+  } catch (e) {
+    return []
+  }
+}
+
+function getCasesSidebar(root: string) {
+  const casesDir = path.join(root, 'cases')
+  return buildRecursiveSidebar(casesDir, '/cases/')
+}
+
+function getScenariosSidebar(root: string) {
+  const scenariosDir = path.join(root, 'scenarios')
+  return buildRecursiveSidebar(scenariosDir, '/scenarios/')
+}
+
+function getPlansSidebar(root: string) {
+  const plansDir = path.join(root, 'plans')
+  return buildRecursiveSidebar(plansDir, '/plans/')
+}
+
+export default withMermaid(
+  defineConfig({
+    title: 'Test Plans & Cases',
+    description: 'Test hub documentation',
+    cleanUrls: true,
+    ignoreDeadLinks: true,
+    srcExclude: [
+      '**/node_modules/**',
+      '**/scripts/**',
+      '**/.cursor/**',
+      '**/package.json'
+    ],
+    mermaid: {
+      themeVariables: {
+        fontSize: '18px',
+      },
+      flowchart: {
+        useMaxWidth: true,
+        htmlLabels: true,
+        padding: 16,
+        nodeSpacing: 50,
+        rankSpacing: 60,
+      },
+      sequence: {
+        useMaxWidth: true,
+        diagramMarginX: 40,
+        diagramMarginY: 20,
+        actorMargin: 50,
+        boxMargin: 12,
+      },
+    },
+    vite: {
+      resolve: {
+        dedupe: ['vue', 'vitepress', 'vitepress-plugin-mermaid', 'vitepress-mermaid-renderer'],
+      },
+      optimizeDeps: {
+        include: [
+          'mermaid',
+          'dayjs',
+          'debug',
+          'cytoscape',
+          'cytoscape-cose-bilkent',
+          '@braintree/sanitize-url',
+        ],
+      },
+    },
+    themeConfig: {
+      nav: [
+        { text: 'Home', link: '/' },
+        { text: 'Scenarios', link: '/scenarios/' },
+        { text: 'Cases', link: '/cases/' },
+        { text: 'Plans', link: '/plans/' },
+      ],
+      sidebar: {
+        '/scenarios/': [
+          {
+            text: 'Scenarios',
+            items: getScenariosSidebar(projectRoot),
+          }
+        ],
+        '/cases/': [
+          {
+            text: 'Cases',
+            items: getCasesSidebar(projectRoot),
+          }
+        ],
+        '/plans/': [
+          {
+            text: 'Plans',
+            items: getPlansSidebar(projectRoot),
+          }
+        ]
+      },
+    },
+  }),
+)