@shanyucoder/flowgrid 0.1.0

package/engines/spec/lib/audit-testcase-plan-gaps.mjs

@@ -0,0 +1,131 @@
+/**
+ * Legacy multi-case test **plan** files (*.test.yaml, qa-item.yaml with testcases:).
+ * Prefer cases/TC-*.yaml — see audit-testcase-tc.mjs.
+ */
+
+export function auditTestcasePlanContent(rawText, filePath) {
+  const gaps = [];
+
+  function addGap(code, severity, fieldPath, message, suggestedFix, extra = {}) {
+    gaps.push({
+      code,
+      severity,
+      path: fieldPath,
+      message,
+      suggestedFix,
+      category: 'plan',
+      ...extra,
+    });
+  }
+
+  if (!rawText.includes('testcases:') && !rawText.includes('cases:') && !rawText.includes('scenarios:')) {
+    addGap(
+      'TC_MISSING_CASES_LIST',
+      'critical',
+      'testcases',
+      'Missing testcases array in plan file.',
+      'Declare testcases[] array with id, title, scenarioRef, steps, and expectedResult — or author cases/**/TC-*.yaml instead.',
+    );
+  }
+
+  addGap(
+    'TC_LEGACY_PLAN_FORMAT',
+    'info',
+    'artifact',
+    'Plan-style test YAML is legacy; new work must use cases/**/TC-*.yaml (schemaVersion: 2).',
+    'Split into per-screen TC-*.yaml files and run flowgrid cases:check.',
+  );
+
+  if (!rawText.includes('Initial Load') && !rawText.includes('init') && !rawText.includes('initial')) {
+    addGap(
+      'TC_MISSING_INITIAL_LOAD',
+      'warning',
+      'testcases.initial_load',
+      'Missing testcase for Initial Load & Data Hydration scenario.',
+      'Add testcase verifying initial page fetch, role permission check, skeleton/empty states.',
+    );
+  }
+
+  if (!rawText.includes('Validation') && !rawText.includes('invalid') && !rawText.includes('validation')) {
+    addGap(
+      'TC_MISSING_VALIDATION_CASE',
+      'warning',
+      'testcases.validation',
+      'Missing testcase for Input & Inline Validation scenarios.',
+      'Add testcase verifying invalid field formats, required field omissions, and boundary errors.',
+    );
+  }
+
+  if (!rawText.includes('Happy Path') && !rawText.includes('success') && !rawText.includes('successful')) {
+    addGap(
+      'TC_MISSING_HAPPY_PATH',
+      'warning',
+      'testcases.happy_path',
+      'Missing testcase for Successful Submission (Happy Path).',
+      'Add testcase verifying valid form submission, button locking against double-submit, and redirect.',
+    );
+  }
+
+  if (!rawText.includes('409') && !rawText.includes('500') && !rawText.includes('exception') && !rawText.includes('error')) {
+    addGap(
+      'TC_MISSING_EXCEPTION_CASE',
+      'warning',
+      'testcases.exceptions',
+      'Missing testcase for Exception Handling (409 Conflict, 5xx Server Error, Timeout).',
+      'Add testcase verifying network failure handling, session expiration, and form state draft preservation.',
+    );
+  }
+
+  if (!rawText.includes('boundary') && !rawText.includes('Boundary') && !rawText.includes('min') && !rawText.includes('max')) {
+    addGap(
+      'TC_MISSING_BOUNDARY_MATRIX',
+      'warning',
+      'testcases.boundary',
+      'Missing Boundary Value Analysis test matrix (min-1, min, normal, max, max+1).',
+      'Add testcase checking boundary limits for numeric/text input fields.',
+    );
+  }
+
+  if (!rawText.includes('double') && !rawText.includes('concurrency') && !rawText.includes('lock')) {
+    addGap(
+      'TC_MISSING_DOUBLE_SUBMIT',
+      'warning',
+      'testcases.concurrency',
+      'Missing testcase for Double Submit prevention and Concurrency control.',
+      'Add testcase checking submit button disabling upon click and optimistic locking conflict handling.',
+    );
+  }
+
+  if (!rawText.includes('RBAC') && !rawText.includes('permission') && !rawText.includes('role')) {
+    addGap(
+      'TC_MISSING_RBAC_CASE',
+      'warning',
+      'testcases.rbac',
+      'Missing testcase for Access Control & Role-Based Access (RBAC).',
+      'Add testcase verifying role-specific UI visibility and unauthorized action blocking.',
+    );
+  }
+
+  if (!rawText.includes('empty') && !rawText.includes('Empty') && !rawText.includes('no data')) {
+    addGap(
+      'TC_MISSING_EMPTY_STATE',
+      'info',
+      'testcases.empty_state',
+      'Missing testcase for Empty State handling (empty data table, empty list).',
+      'Add testcase verifying UI rendering when no records are returned.',
+    );
+  }
+
+  return finalizeReport(gaps, filePath);
+}
+
+function finalizeReport(gaps, filePath) {
+  return {
+    file: filePath,
+    totalGaps: gaps.length,
+    criticalGaps: gaps.filter((g) => g.severity === 'critical').length,
+    warningGaps: gaps.filter((g) => g.severity === 'warning').length,
+    infoGaps: gaps.filter((g) => g.severity === 'info').length,
+    gaps,
+  };
+}

package/engines/spec/lib/audit-testcase-tc.mjs

@@ -0,0 +1,182 @@
+/**
+ * Audit a single cases/TC-*.yaml file (schemaVersion 2 shape).
+ */
+
+import path from 'path';
+import { TEST_MATRIX_FACETS } from './testcase-matrix-facets.mjs';
+
+export function isTestCaseArtifact(filePath, rawText) {
+  const base = path.basename(filePath);
+  if (/^TC-.*\.ya?ml$/i.test(base)) return true;
+  if (/^id:\s*TC-[A-Z0-9-]+/m.test(rawText) && rawText.includes('testMatrix:')) return true;
+  return false;
+}
+
+function extractTestMatrixFacets(rawText) {
+  const facets = new Set();
+  const idx = rawText.indexOf('testMatrix:');
+  if (idx === -1) return facets;
+  const tail = rawText.slice(idx);
+  const end = tail.search(/\n[a-zA-Z][\w]*:\s*(\n|\S)/);
+  const block = end > 0 ? tail.slice(0, end) : tail.slice(0, 8000);
+  for (const m of block.matchAll(/facet:\s*["']?([\w_]+)["']?/g)) {
+    facets.add(m[1]);
+  }
+  return facets;
+}
+
+function hasNonEmptySteps(rawText) {
+  if (!rawText.includes('steps:')) return false;
+  const m = rawText.match(/steps:\s*\n((?:[ \t]+-\s+.+\n?)+)/);
+  if (!m) return false;
+  return m[1].split('\n').some((line) => /^\s+-\s+\S/.test(line));
+}
+
+function readSchemaVersion(rawText) {
+  const m = rawText.match(/^schemaVersion:\s*(\d+)/m);
+  return m ? Number(m[1]) : null;
+}
+
+export function auditTestcaseTcFile(rawText, filePath) {
+  const gaps = [];
+
+  function addGap(code, severity, fieldPath, message, suggestedFix, extra = {}) {
+    gaps.push({
+      code,
+      severity,
+      path: fieldPath,
+      message,
+      suggestedFix,
+      category: 'tc-file',
+      ...extra,
+    });
+  }
+
+  const schemaVersion = readSchemaVersion(rawText);
+  if (schemaVersion !== 2) {
+    addGap(
+      'TC_SCHEMA_NOT_V2',
+      'critical',
+      'schemaVersion',
+      'TC file must declare schemaVersion: 2 for release gate compatibility.',
+      'Add schemaVersion: 2 at top of file and complete testMatrix facets.',
+    );
+  }
+
+  if (!/^id:\s*TC-[A-Z0-9-]+/m.test(rawText)) {
+    addGap(
+      'TC_MISSING_ID',
+      'critical',
+      'id',
+      'Missing or invalid id (expected pattern TC-…).',
+      'Set id: TC-<FEATURE>-<NN> at document root.',
+    );
+  }
+
+  if (!/refs:\s*\n[\s\S]*?screen:\s*(W|API|UI)-/m.test(rawText)) {
+    addGap(
+      'TC_MISSING_REFS_SCREEN',
+      'critical',
+      'refs.screen',
+      'Missing refs.screen (W-* / API-* / UI-*).',
+      'Declare refs.screen matching docs hub page-id.',
+    );
+  }
+
+  if (!rawText.includes('testMatrix:')) {
+    addGap(
+      'TC_MISSING_TEST_MATRIX',
+      'critical',
+      'testMatrix',
+      'Missing testMatrix array (required for schemaVersion 2).',
+      'Add testMatrix[] rows with facet, description, input, expected per /testcase skill.',
+    );
+  } else {
+    const facets = extractTestMatrixFacets(rawText);
+    for (const required of TEST_MATRIX_FACETS) {
+      if (!facets.has(required)) {
+        addGap(
+          'TC_MATRIX_MISSING_FACET',
+          'critical',
+          `testMatrix.facet.${required}`,
+          `testMatrix missing required facet "${required}".`,
+          `Add a testMatrix row with facet: ${required}.`,
+        );
+      }
+    }
+    const unknown = [...facets].filter((f) => !TEST_MATRIX_FACETS.includes(f));
+    for (const bad of unknown) {
+      addGap(
+        'TC_MATRIX_UNKNOWN_FACET',
+        'warning',
+        `testMatrix.facet.${bad}`,
+        `Unknown testMatrix facet "${bad}".`,
+        `Use one of: ${TEST_MATRIX_FACETS.join(', ')}.`,
+      );
+    }
+  }
+
+  if (!hasNonEmptySteps(rawText)) {
+    addGap(
+      'TC_MISSING_STEPS',
+      'critical',
+      'steps',
+      'Missing non-empty steps[] (min 1 step).',
+      'Add steps[] with executable UI actions for E2E gen.',
+    );
+  }
+
+  if (!rawText.includes('testIds:') || !/testIds:[\s\S]*required:/m.test(rawText)) {
+    addGap(
+      'TC_MISSING_TEST_IDS',
+      'warning',
+      'testIds.required',
+      'Missing testIds.required[] for Playwright selectors.',
+      'Mirror design testId / data-testid inventory from bundle ir/design.',
+    );
+  }
+
+  const facets = extractTestMatrixFacets(rawText);
+  if (facets.has('negative_duplicate') && !rawText.includes('409') && !/status:\s*409/.test(rawText)) {
+    addGap(
+      'TC_MATRIX_409_ASSERTION',
+      'warning',
+      'testMatrix.negative_duplicate',
+      'negative_duplicate row should assert HTTP 409 or conflict outcome.',
+      'Set expected.status: 409 or explicit conflict message in matrix expected block.',
+    );
+  }
+
+  if (
+    !rawText.includes('story:') &&
+    !rawText.includes('summary:') &&
+    !rawText.match(/description:\s*["'].{20,}/)
+  ) {
+    addGap(
+      'TC_THIN_BUSINESS_STORY',
+      'warning',
+      'story',
+      'Missing rich story/summary for business context.',
+      'Add multi-line story: or summary: per /testcase skill.',
+    );
+  }
+
+  return {
+    file: filePath,
+    artifactKind: 'tc-file',
+    schemaVersion,
+    matrixFacets: [...extractTestMatrixFacets(rawText)],
+    totalGaps: gaps.length,
+    criticalGaps: gaps.filter((g) => g.severity === 'critical').length,
+    warningGaps: gaps.filter((g) => g.severity === 'warning').length,
+    infoGaps: gaps.filter((g) => g.severity === 'info').length,
+    gaps,
+  };
+}
+
+export function auditTestcaseTcFileFromPath(filePath, rawText) {
+  if (!isTestCaseArtifact(filePath, rawText)) {
+    return null;
+  }
+  return auditTestcaseTcFile(rawText, filePath);
+}

package/engines/spec/lib/audit-ux-affordance.mjs

@@ -0,0 +1,269 @@
+/**
+ * UX affordance gap checks (deterministic), aligned with flowgrid-ux-common / ux-common-patterns.
+ * Merged into `audit spec` as gaps[] / confirms[] (codes UX_* / CONFIRM_UX_*).
+ */
+
+function has(text, keyword) {
+  return text.includes(keyword);
+}
+
+function hasAny(text, keywords) {
+  return keywords.some((k) => text.includes(k));
+}
+
+function isListType(type) {
+  return type === 'list' || type === 'admin-crud';
+}
+
+function isDetailType(type) {
+  return type === 'detail';
+}
+
+function isAuthType(type) {
+  return type === 'auth' || type === 'change-password';
+}
+
+function hasDeleteIntent(rawText) {
+  if (has(rawText, '#pattern: delete-flow') || has(rawText, 'delete-flow')) {
+    return hasAny(rawText, ['btn_delete', 'bulkDelete', 'Delete', 'delete']);
+  }
+  return hasAny(rawText, [
+    'btn_delete',
+    'bulkDelete',
+    'bulk_delete',
+    'Batch Delete',
+    'kind: delete',
+    'action: delete',
+    'label: Delete',
+    'Delete Selected',
+    'rowActions:',
+  ]) && hasAny(rawText, ['delete', 'Delete']);
+}
+
+function deleteFlowDocumented(rawText) {
+  return hasAny(rawText, [
+    '#pattern: delete-flow',
+    'delete-flow',
+    'common-delete-flow',
+    'confirmDialog',
+    'confirmDialog:',
+    'confirmation:',
+    'AlertDialog',
+    'confirm-dialog',
+  ]);
+}
+
+function deleteResultDocumented(rawText) {
+  return hasAny(rawText, [
+    'resultDialog',
+    'result-dialog',
+    'successDialog',
+    'errorDialog',
+    'acknowledge',
+    'result dialog',
+  ]);
+}
+
+/**
+ * @param {string} rawText
+ * @param {string} pageType
+ * @returns {{ gaps: object[], confirms: object[] }}
+ */
+export function auditUxAffordance(rawText, pageType) {
+  const gaps = [];
+  const confirms = [];
+
+  function addGap(code, severity, fieldPath, message, suggestedFix, suggestedStoryPatch) {
+    gaps.push({
+      code,
+      severity,
+      type: 'gap',
+      category: 'ux',
+      path: fieldPath,
+      message,
+      suggestedFix,
+      ...(suggestedStoryPatch ? { suggestedStoryPatch } : {}),
+    });
+  }
+
+  function addConfirm(code, fieldPath, question, options, defaultRecommend, suggestedStoryPatch) {
+    confirms.push({
+      code,
+      type: 'confirm',
+      category: 'ux',
+      path: fieldPath,
+      question,
+      options: options || [],
+      defaultRecommend: defaultRecommend ?? 0,
+      ...(suggestedStoryPatch ? { suggestedStoryPatch } : {}),
+    });
+  }
+
+  // --- Delete flow (§11 ux-common-patterns) ---
+  if (hasDeleteIntent(rawText)) {
+    if (!deleteFlowDocumented(rawText)) {
+      addGap(
+        'UX_GAP_DELETE_CONFIRM',
+        'warning',
+        'design.actions[].interactionControl.confirmDialog',
+        'Delete action present but no blocking confirm (AlertDialog / delete-flow pattern).',
+        'Add #pattern: delete-flow and confirmDialog on delete/bulk-delete actions (flowgrid-ux-common).',
+        {
+          scenario: 'Affordances UX chuẩn portal (UX — khi áp dụng)',
+          step:
+            'Trước khi xóa, hệ thống hiển thị hộp thoại xác nhận chặn; người dùng chọn Hủy hoặc Xóa rõ ràng.',
+          acceptance:
+            '[ ] Xóa bản ghi yêu cầu xác nhận trước khi gọi API.',
+        },
+      );
+    }
+    const toastOnlyDelete =
+      hasAny(rawText, ['toast', 'Toast']) &&
+      !deleteResultDocumented(rawText) &&
+      !hasAny(rawText, ['dialog', 'Dialog', 'modal', 'Modal']);
+    if (toastOnlyDelete && hasDeleteIntent(rawText)) {
+      addGap(
+        'UX_GAP_DELETE_RESULT_DIALOG',
+        'warning',
+        'design.actions[].outcomes.onSuccess',
+        'Delete flow appears toast-only; UX rule requires acknowledge result dialog after delete API.',
+        'Declare result dialog on success/error for delete — not toast-only (ux-common-patterns §11).',
+        {
+          scenario: 'Affordances UX chuẩn portal (UX — khi áp dụng)',
+          step:
+            'Sau API xóa, hộp thoại kết quả (thành công hoặc lỗi) bắt người dùng bấm Đóng/Xác nhận — không chỉ toast.',
+          acceptance: '[ ] Sau delete, phản hồi qua result dialog, không toast-only.',
+        },
+      );
+    } else if (!deleteResultDocumented(rawText) && has(rawText, 'outcomes:')) {
+      addConfirm(
+        'CONFIRM_UX_DELETE_RESULT',
+        'design.actions[].outcomes',
+        'After delete API, how should success/error be shown?',
+        [
+          '(Recommended) Blocking result dialog — user must acknowledge',
+          'Inline alert under page title',
+          'Toast only (requires explicit member override / tech debt)',
+        ],
+        0,
+      );
+    }
+  }
+
+  // --- Disabled affordance (§7) ---
+  if (
+    (has(rawText, 'preconditions:') || has(rawText, 'disabledWhen') || has(rawText, 'disabled:')) &&
+    !has(rawText, 'disabledReason')
+  ) {
+    addGap(
+      'UX_GAP_DISABLED_REASON',
+      'warning',
+      'design.actions[].preconditions.disabledReason',
+      'Disabled or conditional actions lack disabledReason (non-obvious disable needs explanation).',
+      'Add disabledReason and/or badge/tooltip affordance per ux-common-patterns §7.',
+      {
+        scenario: 'Affordances UX chuẩn portal (UX — khi áp dụng)',
+        step:
+          'Khi nút/hành động bị khóa, giao diện giải thích lý do (badge, chip hoặc tooltip).',
+        acceptance: '[ ] Hành động disabled có lý do hiển thị cho người dùng.',
+      },
+    );
+  }
+
+  // --- List DSL mapping (§2–6) ---
+  if (isListType(pageType) && has(rawText, 'columns:')) {
+    if (!hasAny(rawText, ['#shell:', '#pattern:', 'DataListPage', 'CRUD'])) {
+      addConfirm(
+        'CONFIRM_UX_LIST_DSL',
+        'design.shell / design.patterns',
+        'List screen has columns but no DSL shell/pattern tags — map to registry?',
+        [
+          '(Recommended) #shell: DataListPage + #pattern: CRUD',
+          'Partial DSL — specify tags in handoff',
+          'Log as Tech Debt (Pending)',
+        ],
+        0,
+      );
+    }
+  }
+
+  // --- Status chip (§9) ---
+  if ((isListType(pageType) || isDetailType(pageType)) && has(rawText, 'columns:')) {
+    const hasStatusCol =
+      /key:\s*status\b/i.test(rawText) ||
+      /title:.*\bStatus\b/i.test(rawText) ||
+      has(rawText, 'status:');
+    const hasChipRender = hasAny(rawText, [
+      'render: chip',
+      '#render: chip',
+      'status-chip',
+      'StatusChip',
+      'badge',
+      'chip',
+    ]);
+    if (hasStatusCol && !hasChipRender) {
+      addConfirm(
+        'CONFIRM_UX_STATUS_CHIP',
+        'spec.ui.list.columns[].render',
+        'Should status be shown as a semantic chip/badge (not plain text)?',
+        [
+          '(Recommended) Yes — chip with label + semantic color',
+          'Plain text only',
+          'Log as Tech Debt (Pending)',
+        ],
+        0,
+      );
+    }
+  }
+
+  // --- Breadcrumb drill-down (§3) — detail without trail ---
+  if (isDetailType(pageType) && !isAuthType(pageType) && !has(rawText, 'breadcrumb:')) {
+    addConfirm(
+      'CONFIRM_UX_BREADCRUMB_DETAIL',
+      'design.nav.breadcrumb',
+      'Detail screen without breadcrumb — add hierarchy trail or contextual back?',
+      [
+        '(Recommended) Breadcrumb trail (module > record)',
+        'Back button + title only',
+        'No hierarchy (log tech debt if deep links exist)',
+      ],
+      0,
+    );
+  }
+
+  // --- Search/filter when pagination implies server list (§4) ---
+  if (isListType(pageType) && has(rawText, 'pagination:') && !has(rawText, 'filters:')) {
+    addConfirm(
+      'CONFIRM_UX_FILTER_WITH_PAGINATION',
+      'spec.ui.list.filters',
+      'Paginated list without filters block — add search/filter?',
+      [
+        '(Recommended) Keyword search + key filters',
+        'Search only',
+        'No filters (document rationale)',
+      ],
+      0,
+    );
+  }
+
+  // --- Import CSV feedback (§15) ---
+  if (hasAny(rawText, ['Import CSV', 'importCsv', 'import-csv', 'CSV import', 'uploadCsv'])) {
+    if (!hasAny(rawText, ['importResult', 'import:', 'onSuccess', 'onBusinessErrors'])) {
+      addGap(
+        'UX_GAP_IMPORT_FEEDBACK',
+        'warning',
+        'spec.ui.import.outcomes',
+        'CSV import mentioned but no import result / outcome feedback path.',
+        'Declare validate → confirm → result flow with error row handling (ux-common-patterns §15).',
+        {
+          scenario: 'Affordances UX chuẩn portal (UX — khi áp dụng)',
+          step:
+            'Import: chọn file → kiểm tra → xác nhận → màn hình kết quả; lỗi theo dòng có thể tải log.',
+          acceptance: '[ ] Import CSV có báo kết quả rõ, không im lặng khi lỗi.',
+        },
+      );
+    }
+  }
+
+  return { gaps, confirms };
+}