qa-flowkit 0.4.0-alpha.0

package/.qa-ai/scripts/validate-test-design.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+import { validateTestDesignProposal, validateTestDesignSystem } from './lib/test-design.mjs';
+import {
+  getConfigValue,
+  loadQaAiConfig,
+  logHeader,
+  parseArgs,
+  pathExists,
+  readText,
+  resolveRepoPath
+} from './lib/utils.mjs';
+
+const cwd = process.cwd();
+const args = parseArgs(process.argv);
+
+function printHelp() {
+  console.log(`Usage: node .qa-ai/scripts/validate-test-design.mjs [options]
+
+Options:
+  --system-path <file>   Override system test design path
+  --proposal-path <file> Override per-RF proposal path
+  --allow-missing        Return success when files are missing
+  --require-rf-id        Fail when RF IDs are not mentioned in the proposal
+  --help                 Show this help
+
+Validates qa-ai-output/test-design-system.md and test-design-proposal.md structure.
+`);
+}
+
+async function validateFile(cwd, filePath, validator, options = {}) {
+  const absolute = resolveRepoPath(cwd, filePath, { label: 'test design file' });
+  if (!await pathExists(absolute)) {
+    if (options.allowMissing) {
+      return { ok: true, skipped: true, path: filePath, errors: [] };
+    }
+    return { ok: false, skipped: false, path: filePath, errors: [`Test design file not found: ${filePath}`] };
+  }
+
+  const content = await readText(absolute);
+  const result = validator(content, options.validatorOptions || {});
+  const errors = result.errors.map((error) => `${filePath}: ${error}`);
+  return { ok: result.ok, skipped: false, path: filePath, errors };
+}
+
+export async function validateTestDesignArtifacts(cwd, options = {}) {
+  const configInfo = await loadQaAiConfig(cwd);
+  const config = configInfo.data || {};
+  const systemPath =
+    options.systemPath ||
+    getConfigValue(config, 'testDesign.systemPath', 'qa-ai-output/test-design-system.md');
+  const proposalPath =
+    options.proposalPath ||
+    getConfigValue(config, 'testDesign.proposalPath', 'qa-ai-output/test-design-proposal.md');
+
+  const allowMissing = Boolean(options.allowMissing);
+  const validatorOptions = {
+    requireOfficialRfId: Boolean(options.requireRfId)
+  };
+
+  const system = await validateFile(cwd, systemPath, validateTestDesignSystem, {
+    allowMissing,
+    validatorOptions
+  });
+  const proposal = await validateFile(cwd, proposalPath, validateTestDesignProposal, {
+    allowMissing,
+    validatorOptions
+  });
+
+  const errors = [...system.errors, ...proposal.errors];
+  return {
+    ok: errors.length === 0,
+    system,
+    proposal,
+    errors
+  };
+}
+
+async function main() {
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  logHeader('QA AI test design validator');
+  const result = await validateTestDesignArtifacts(cwd, {
+    systemPath: args['system-path'],
+    proposalPath: args['proposal-path'],
+    allowMissing: Boolean(args['allow-missing']),
+    requireRfId: Boolean(args['require-rf-id'])
+  });
+
+  if (result.system.skipped) {
+    console.log('SKIP - system test design file not found.');
+  } else if (result.system.ok) {
+    console.log(`PASS - ${result.system.path}`);
+  }
+
+  if (result.proposal.skipped) {
+    console.log('SKIP - per-RF test design proposal not found.');
+  } else if (result.proposal.ok) {
+    console.log(`PASS - ${result.proposal.path}`);
+  }
+
+  if (result.errors.length > 0) {
+    for (const error of result.errors) {
+      console.error(`FAIL - ${error}`);
+    }
+    process.exit(1);
+  }
+
+  console.log('\nVALID - test design artifacts passed validation.');
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/.qa-ai/scripts/validate-traceability.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { normalizeColumn, parseMarkdownTable } from './lib/markdown-table.mjs';
+import {
+  getConfigValue,
+  listFilesRecursive,
+  loadQaAiConfig,
+  logHeader,
+  parseArgs,
+  pathExists,
+  readText,
+  relativeTo,
+  resolveRepoPath
+} from './lib/utils.mjs';
+
+const cwd = process.cwd();
+const args = parseArgs(process.argv);
+const idPattern = /\b(?:RF|TC|TEST|QA)[-_ ]?[A-Z0-9]+\b/gi;
+const caseIdPattern = /\b(?:TC|TEST|QA)[-_ ]?[A-Z0-9]+\b/gi;
+const requiredColumns = [
+  'Requirement Source',
+  'RF',
+  'Feature File',
+  'Test Management Case ID',
+  'Type',
+  'Priority',
+  'Automation Status'
+];
+
+function printHelp() {
+  console.log(`Usage: node .qa-ai/scripts/validate-traceability.mjs [options]
+
+Options:
+  --path <file>     Override configured traceability matrix path
+  --features <dir>  Override configured feature root
+  --allow-empty     Return success when no .feature files exist
+  --allow-missing   Return success when the traceability matrix is missing
+  --help            Show this help
+
+Validates feature identifier coverage, traceability matrix table shape and duplicate test case or feature-file rows.
+`);
+}
+
+function normalizeId(value) {
+  return String(value || '').replace(/\s+/g, '-').toUpperCase();
+}
+
+function idsFromText(value) {
+  return [...String(value || '').matchAll(idPattern)].map((match) => normalizeId(match[0]));
+}
+
+function caseIdsFromText(value) {
+  return [...String(value || '').matchAll(caseIdPattern)].map((match) => normalizeId(match[0]));
+}
+
+function parseMatrix(content) {
+  const table = parseMarkdownTable(content, {
+    label: 'Traceability matrix',
+    requiredColumns
+  });
+  const errors = [...table.errors];
+  const rows = [];
+  for (const row of table.rows) {
+    const ids = [...new Set(idsFromText(row.cells.join(' ')))].sort();
+    const caseIds = [...new Set(caseIdsFromText(row.cells.join(' ')))].sort();
+    if (ids.length === 0) {
+      errors.push(`Line ${row.line}: row must include at least one RF/test identifier.`);
+    }
+    rows.push({ ...row, ids, caseIds });
+  }
+
+  return { errors, rows, header: table.header };
+}
+
+function duplicateMatrixErrors(rows) {
+  const errors = [];
+  const byCaseId = new Map();
+  const byFeatureFile = new Map();
+
+  for (const row of rows) {
+    for (const id of row.caseIds) {
+      const current = byCaseId.get(id) || [];
+      current.push(row.line);
+      byCaseId.set(id, current);
+    }
+
+    const featureFile = String(row.values[normalizeColumn('Feature File')] || '').trim();
+    if (featureFile) {
+      const normalizedFeatureFile = featureFile.replaceAll('\\', '/').toLowerCase();
+      const current = byFeatureFile.get(normalizedFeatureFile) || [];
+      current.push(row.line);
+      byFeatureFile.set(normalizedFeatureFile, current);
+    }
+  }
+
+  for (const [id, lines] of byCaseId.entries()) {
+    if (lines.length > 1) errors.push(`Identifier ${id} appears in multiple traceability rows: ${lines.join(', ')}.`);
+  }
+  for (const [featureFile, lines] of byFeatureFile.entries()) {
+    if (lines.length > 1) errors.push(`Feature file ${featureFile} appears in multiple traceability rows: ${lines.join(', ')}.`);
+  }
+
+  return errors;
+}
+
+async function featureIds(featureRootPath) {
+  const files = await listFilesRecursive(featureRootPath, (filePath) => filePath.endsWith('.feature'));
+  const entries = [];
+  for (const file of files) {
+    const content = await fs.readFile(file, 'utf8');
+    const ids = new Set([
+      ...idsFromText(path.basename(file, '.feature')),
+      ...idsFromText(content)
+    ]);
+    entries.push({
+      file,
+      ids: [...ids].sort()
+    });
+  }
+  return entries;
+}
+
+async function main() {
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  logHeader('QA AI traceability validator');
+  const configInfo = await loadQaAiConfig(cwd);
+  const featureRoot = args.features || getConfigValue(configInfo.data, 'gherkin.featurePath', 'features');
+  const matrixPath = args.path || getConfigValue(configInfo.data, 'traceability.matrixPath', 'qa-ai-output/traceability-matrix.md');
+  const featureRootPath = resolveRepoPath(cwd, featureRoot, { label: 'feature root' });
+  const matrixFilePath = resolveRepoPath(cwd, matrixPath, { label: 'traceability matrix' });
+  const features = await featureIds(featureRootPath);
+
+  if (features.length === 0) {
+    console.log(`No .feature files found under ${featureRoot}.`);
+    if (args['allow-empty']) return;
+    console.log('\nFAILED - no feature files found. Pass --allow-empty when this is expected.');
+    process.exit(1);
+  }
+
+  if (!await pathExists(matrixFilePath)) {
+    console.log(`Traceability matrix not found at ${matrixPath}.`);
+    if (args['allow-missing']) return;
+    console.log('\nFAILED - create the traceability matrix or pass --allow-missing.');
+    process.exit(1);
+  }
+
+  const rawMatrixContent = await readText(matrixFilePath);
+  const matrix = parseMatrix(rawMatrixContent);
+  const matrixContent = normalizeId(rawMatrixContent);
+  const errors = [];
+  errors.push(...matrix.errors);
+  errors.push(...duplicateMatrixErrors(matrix.rows));
+
+  for (const feature of features) {
+    if (feature.ids.length === 0) {
+      errors.push(`${relativeTo(cwd, feature.file)} has no RF/test identifiers to trace.`);
+      continue;
+    }
+    for (const id of feature.ids) {
+      if (!matrixContent.includes(id)) {
+        errors.push(`${relativeTo(cwd, feature.file)} identifier ${id} is missing from ${matrixPath}.`);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    for (const error of errors) console.log(`[FAIL] ${error}`);
+    console.log(`\nFAILED - ${errors.length} traceability validation error(s).`);
+    process.exit(1);
+  }
+
+  console.log(`[PASS] ${matrixPath} covers identifiers from ${features.length} feature file(s).`);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/.qa-ai/templates/automation-feasibility-report.template.md

@@ -0,0 +1,21 @@
+# Automation Feasibility Report
+
+## Automatable tests
+
+## Manual tests
+
+## Partially automatable tests
+
+## Blocked tests
+
+## Required framework support
+
+## Required test data
+
+## Required selectors
+
+## Required mocks/stubs
+
+## Risks
+
+## Proposed implementation

package/.qa-ai/templates/automation-implementation-plan.template.md

@@ -0,0 +1,23 @@
+# Automation Implementation Plan
+
+## Tests to automate
+
+## New files
+
+## Existing files to modify
+
+## Page objects
+
+## Helpers
+
+## Fixtures and data
+
+## API clients
+
+## Risks
+
+## Execution plan
+
+## Approval request
+
+Do you approve implementing the proposed automation changes?

package/.qa-ai/templates/feature.template

@@ -0,0 +1,13 @@
+@priority:<critical|high|medium|low> @type:<functional|integration|e2e|api|accessibility|compatibility|manual> @manual:<true|false>
+Feature: <RF-ID> - <Feature title>
+  As a <role>
+  I want <capability>
+  So that <business value>
+
+  Acceptance Criteria:
+    - <acceptance criterion>
+
+  Scenario: <RF-ID> - <Scenario title>
+    Given <precondition>
+    When <action>
+    Then <expected result>

package/.qa-ai/templates/jira-automation-task.template.md

@@ -0,0 +1,25 @@
+# Automation Task Template
+
+## Title
+
+Automate QA test cases for <RF-ID> - <Feature name>
+
+## Description
+
+The following QA test cases have been identified as technically automatable but could not be implemented during the current flow.
+
+## Test cases
+
+- <Test ID> - <Title>
+
+## Reason
+
+- Missing stable test data / environment / credentials / framework support.
+
+## Acceptance Criteria
+
+- Automated tests are implemented using the configured framework.
+- Tests follow repository conventions.
+- Tests are linked to corresponding test management cases where available.
+- Tests can be executed locally or in CI.
+- Traceability matrix is updated.

package/.qa-ai/templates/pr-template.md

@@ -0,0 +1,60 @@
+# Summary
+
+This PR adds QA test design and automation coverage for <Requirement / RF>.
+
+## Sources
+
+- Requirement source:
+- PRD:
+- Supporting documentation:
+- Attachments:
+
+## Test Design
+
+Added feature files:
+
+- 
+
+## Test Management
+
+Created cases:
+
+- 
+
+Reused cases:
+
+- 
+
+Cases requiring future review:
+
+- 
+
+## Automation
+
+Automated tests added:
+
+- 
+
+Manual tests:
+
+- 
+
+Pending automation:
+
+- 
+
+## Traceability
+
+Updated:
+
+- `qa-ai-output/traceability-matrix.md`
+
+## Execution status
+
+- Executed locally: Yes/No
+- Executed in CI: Yes/No
+- First manual execution required: Yes/No
+
+## Risks / Notes
+
+- 

package/.qa-ai/templates/release-gate.template.yaml

@@ -0,0 +1,16 @@
+# Release gate — proposal-first record for go/no-go decisions.
+# QA FlowKit does not perform external writes. Update this file after validators and review.
+
+decision: PENDING
+approver: ""
+recordedAt: ""
+coverage_summary: |
+  Summarize traceability coverage, validator results and test-management sync status.
+open_risks:
+  - Document any blocking or residual risks, or state "None documented" for PASS.
+evidence_paths:
+  - qa-ai-output/traceability-matrix.md
+  - qa-ai-output/pr-summary.md
+waived_reason: ""
+notes: |
+  Required human approval before production release. Use WAIVED only with explicit approver and reason.

package/.qa-ai/templates/requirement-analysis.template.md

@@ -0,0 +1,17 @@
+# Requirement Analysis
+
+## Main source
+
+## Complementary sources
+
+## Functional scope
+
+## Acceptance Criteria
+
+## Inferred Acceptance Criteria
+
+## Ambiguities
+
+## Out of scope
+
+## QA impact

package/.qa-ai/templates/test-design-proposal.template.md

@@ -0,0 +1,26 @@
+# Test Design Proposal (per RF / epic)
+
+> Per-RF or per-epic test cases. For system-wide strategy see `qa-ai-output/test-design-system.md` (standard and enterprise tracks).
+
+## Official RF ID
+
+<!-- Required before final .feature generation -->
+
+## Scope
+
+## Proposed tests
+
+| RF | CA | Test ID | Title | Type | Priority | Manual | Action |
+|---|---|---|---|---|---|---|---|
+
+## Existing tests to reuse
+
+## Existing tests requiring modification
+
+## New tests to create
+
+## Ambiguities requiring user decision
+
+## Approval request
+
+Do you approve generating the proposed `.feature` files?

package/.qa-ai/templates/test-design-system.template.md

@@ -0,0 +1,15 @@
+# System Test Design
+
+## Scope
+
+## Architecture alignment
+
+## Testability risks
+
+## Cross-RF coverage strategy
+
+## Shared fixtures and data
+
+## Non-functional focus
+
+## Open questions

package/.qa-ai/templates/test-management-mapping.template.json

@@ -0,0 +1,18 @@
+{
+  "TC-001": {
+    "externalId": "C123",
+    "section": "Login",
+    "suite": "Regression",
+    "status": "planned",
+    "lastReviewedAt": "2026-05-25",
+    "notes": "Example only. Do not store secrets, tokens or credentials in this file."
+  },
+  "features/functional/RF-101-TC-001-login.feature": {
+    "externalId": "C124",
+    "section": "Login",
+    "suite": "Regression",
+    "status": "planned",
+    "lastReviewedAt": "2026-05-25",
+    "notes": "Alternative key style using the feature file path. Use either ID keys or feature-path keys consistently."
+  }
+}

package/.qa-ai/templates/testrail-coverage-analysis.template.md

@@ -0,0 +1,17 @@
+# Test Management Coverage Analysis
+
+## Test management project
+
+## Existing matching tests
+
+## Valid existing tests
+
+## Tests requiring update
+
+## Missing tests
+
+## Potential duplicates
+
+## Proposed test management sections
+
+## Recommendation

package/.qa-ai/templates/testrail-sync-plan.template.md

@@ -0,0 +1,22 @@
+# Test Management Sync Plan
+
+## Project
+
+## Sections to create
+
+## New cases to create
+
+## Existing cases to keep
+
+## Existing cases requiring changes
+
+## Cases requiring user decision
+
+| ID | Proposed action | Approval status | Target section | Notes |
+|---|---|---|---|---|
+
+## Impact
+
+## Approval request
+
+Do you approve the proposed test management synchronization?

package/.qa-ai/templates/traceability-matrix.template.md

@@ -0,0 +1,4 @@
+# Traceability Matrix
+
+| Requirement Source | RF | CA | Feature File | Test Management Case ID | Type | Priority | Automation Status | Automation File |
+|---|---|---|---|---|---|---|---|---|

package/.qa-ai/workflows/automation-analysis.md

@@ -0,0 +1,23 @@
+# Automation Analysis Workflow
+
+Classify approved test cases by automation feasibility and propose implementation.
+
+## Classification
+
+- `automatable`: valuable and technically possible now.
+- `manual`: should remain manual for business or operational reasons.
+- `partial`: useful coverage can be automated, but manual checks remain.
+- `blocked`: automatable in principle, but blocked by data, environment, selectors or framework support.
+- `not-automatable`: unsuitable for UI/API automation.
+
+## Output
+
+Update `qa-ai-output/automation-feasibility-report.md` with:
+
+- Feature/test IDs.
+- Recommended framework from `qa-ai.config.yaml`.
+- Required test data, selectors, mocks, clients or schemas.
+- Risks and blockers.
+- Pending configured issue tracker task drafts when automation cannot be implemented now.
+
+Do not write automation code until `qa-ai-output/automation-implementation-plan.md` is approved.

package/.qa-ai/workflows/cleanup.md

@@ -0,0 +1,52 @@
+# Cleanup Workflow
+
+Use this workflow when a user wants to inspect or remove files generated by `node .qa-ai/scripts/init.mjs` or `node .qa-ai/scripts/sync-agent-adapters.mjs`.
+
+## Safety model
+
+- Cleanup is manifest-based.
+- The manifest lives at `.qa-ai/state/init-manifest.json`.
+- Default cleanup is a dry-run and deletes nothing.
+- `--force` is required before any file or directory is removed.
+- Tracked files are protected by SHA-256 hashes.
+- Modified tracked files are skipped unless `--include-modified` is explicitly passed.
+- Directories are removed only when they are tracked and empty.
+- The `.qa-ai/` framework folder is not removed by the clean command.
+
+## Commands
+
+Preview all tracked cleanup actions:
+
+```bash
+node .qa-ai/scripts/clean.mjs
+```
+
+Remove generated docs/config files that still match the manifest:
+
+```bash
+node .qa-ai/scripts/clean.mjs --generated --force
+```
+
+Remove generated adapter files and empty adapter directories:
+
+```bash
+node .qa-ai/scripts/clean.mjs --adapters --empty-dirs --force
+```
+
+Remove all tracked unchanged files and empty directories:
+
+```bash
+node .qa-ai/scripts/clean.mjs --all --force
+```
+
+Remove the manifest after all entries have been cleaned:
+
+```bash
+node .qa-ai/scripts/clean.mjs --all --force --prune-state
+```
+
+## What not to do
+
+- Do not manually delete broad project folders when the manifest is available.
+- Do not use `--include-modified` unless the user explicitly wants to discard local edits to generated files.
+- Do not clean configured external tool data; the MVP has no external write cleanup.