qa-flowkit 0.4.0-alpha.0

package/.qa-ai/scripts/sync-agent-adapters.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import {
+  commaList,
+  copyDirSafe,
+  manifestEntry,
+  manifestPath,
+  parseArgs,
+  pathExists,
+  recordManifestEntries,
+  relativeTo,
+  logHeader
+} from './lib/utils.mjs';
+
+const cwd = process.cwd();
+const args = parseArgs(process.argv);
+const force = Boolean(args.force);
+const adaptersRoot = path.join(cwd, '.qa-ai', 'adapters');
+
+const adapterMap = {
+  generic: { source: 'generic', target: '.' },
+  claude: { source: 'claude', target: '.claude' },
+  codex: { source: 'codex', target: '.codex' },
+  opencode: { source: 'opencode', target: '.opencode' },
+  cline: { source: 'cline', target: '.' },
+  continue: { source: 'continue', target: '.continue' },
+  aider: { source: 'aider', target: '.' },
+  goose: { source: 'goose', target: '.goose' },
+  gemini: { source: 'gemini', target: '.' }
+};
+
+function printHelp() {
+  console.log(`Usage: node .qa-ai/scripts/sync-agent-adapters.mjs [options]
+
+Options:
+  --adapters <list>  Comma-separated adapters to sync, or "all" (default: all)
+  --adapter <name>   Repeatable single adapter name
+  --force            Overwrite existing adapter files
+  --help             Show this help
+
+Supported adapters: ${Object.keys(adapterMap).join(', ')}
+`);
+}
+
+function selectedAdapterNames() {
+  const requested = [...commaList(args.adapters), ...commaList(args.adapter)].map((name) => name.toLowerCase());
+  if (requested.length === 0 || requested.includes('all')) return Object.keys(adapterMap);
+  if (requested.includes('none')) return [];
+  return [...new Set(requested)];
+}
+
+async function main() {
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  logHeader('Sync agent adapters');
+  const names = selectedAdapterNames();
+  const unknown = names.filter((name) => !(name in adapterMap));
+  if (unknown.length > 0) {
+    console.error(`Unknown adapter(s): ${unknown.join(', ')}`);
+    console.error(`Supported adapters: ${Object.keys(adapterMap).join(', ')}`);
+    process.exit(1);
+  }
+
+  if (names.length === 0) {
+    console.log('No adapters selected.');
+    return;
+  }
+
+  let missing = 0;
+  const manifestEntries = [];
+  for (const name of names) {
+    const adapter = adapterMap[name];
+    const source = path.join(adaptersRoot, adapter.source);
+    const target = path.join(cwd, adapter.target);
+
+    if (!await pathExists(source)) {
+      missing += 1;
+      console.log(`[FAIL] Adapter ${name}: missing template ${relativeTo(cwd, source)}`);
+      continue;
+    }
+
+    const results = await copyDirSafe(source, target, { force });
+    const dirResults = results.filter((result) => result.type === 'dir' && result.created);
+    const fileResults = results.filter((result) => result.type === 'file');
+    console.log(`Adapter ${name}:`);
+    for (const result of dirResults) {
+      console.log(`  created ${relativeTo(cwd, result.path)}`);
+      manifestEntries.push(await manifestEntry(cwd, result.path, {
+        type: 'dir',
+        category: 'adapter',
+        source: `adapter:${name}`
+      }));
+    }
+    for (const result of fileResults) {
+      console.log(`  ${result.copied ? 'copied ' : 'skipped'} ${relativeTo(cwd, result.path)}`);
+      if (result.copied) {
+        manifestEntries.push(await manifestEntry(cwd, result.path, {
+          type: 'file',
+          category: 'adapter',
+          source: `adapter:${name}`
+        }));
+      }
+    }
+  }
+
+  if (missing > 0) {
+    console.log(`\nFAILED - ${missing} adapter template(s) missing.`);
+    process.exit(1);
+  }
+
+  const manifest = await recordManifestEntries(cwd, manifestEntries);
+  if (manifest) console.log(`\nupdated ${relativeTo(cwd, manifestPath(cwd))}`);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/.qa-ai/scripts/test-validators.mjs

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { inspectQaWorkflow, normalizeQaTrack } from './lib/qa-next-steps.mjs';
+import { validateReleaseGateData } from './lib/release-gate.mjs';
+import { validateTestDesignProposal, validateTestDesignSystem } from './lib/test-design.mjs';
+import { parseMarkdownTable } from './lib/markdown-table.mjs';
+import { validateTestManagementMapping } from './lib/test-management-mapping.mjs';
+
+function assertIncludes(haystack, needle) {
+  assert.ok(
+    haystack.some((item) => item.includes(needle)),
+    `Expected an error containing: ${needle}\nActual errors:\n${haystack.join('\n')}`
+  );
+}
+
+function testValidTable() {
+  const result = parseMarkdownTable([
+    '| ID | Proposed action | Approval status |',
+    '|---|---|---|',
+    '| TC-001 | Propose create | Pending approval |',
+    ''
+  ].join('\n'), {
+    label: 'Sync plan table',
+    requiredColumns: ['ID', 'Proposed action', 'Approval status']
+  });
+
+  assert.deepEqual(result.errors, []);
+  assert.deepEqual(result.header, ['ID', 'Proposed action', 'Approval status']);
+  assert.equal(result.rows.length, 1);
+  assert.equal(result.rows[0].values.id, 'TC-001');
+  assert.equal(result.rows[0].values['proposed action'], 'Propose create');
+  assert.equal(result.rows[0].values['approval status'], 'Pending approval');
+}
+
+function testMissingSeparator() {
+  const result = parseMarkdownTable([
+    '| ID | Proposed action |',
+    '| TC-001 | Propose create |',
+    ''
+  ].join('\n'), {
+    label: 'Sync plan table',
+    requiredColumns: ['ID']
+  });
+
+  assertIncludes(result.errors, 'must have a Markdown separator row');
+}
+
+function testMissingRequiredColumn() {
+  const result = parseMarkdownTable([
+    '| ID | Proposed action |',
+    '|---|---|',
+    '| TC-001 | Propose create |',
+    ''
+  ].join('\n'), {
+    label: 'Sync plan table',
+    requiredColumns: ['ID', 'Approval status']
+  });
+
+  assertIncludes(result.errors, 'missing required column "Approval status"');
+}
+
+function testWrongCellCount() {
+  const result = parseMarkdownTable([
+    '| ID | Proposed action |',
+    '|---|---|',
+    '| TC-001 | Propose create | Extra |',
+    ''
+  ].join('\n'), {
+    label: 'Sync plan table'
+  });
+
+  assertIncludes(result.errors, 'row has 3 cell(s), expected 2');
+}
+
+function testEmptyRow() {
+  const result = parseMarkdownTable([
+    '| ID | Proposed action |',
+    '|---|---|',
+    '|  |  |',
+    ''
+  ].join('\n'), {
+    label: 'Sync plan table'
+  });
+
+  assertIncludes(result.errors, 'row is empty');
+}
+
+function testEmptyMappingIsValid() {
+  assert.deepEqual(validateTestManagementMapping({}, { source: 'mapping.json' }), []);
+}
+
+function testValidMappingEntry() {
+  const errors = validateTestManagementMapping({
+    'TC-001': {
+      externalId: 'C123',
+      section: 'Login',
+      suite: 'Regression',
+      status: 'planned',
+      lastReviewedAt: '2026-05-25',
+      notes: 'Created from QA FlowKit proposal.'
+    }
+  }, { source: 'mapping.json' });
+
+  assert.deepEqual(errors, []);
+}
+
+function testMappingEntryMustBeObject() {
+  const errors = validateTestManagementMapping({
+    'TC-001': 'C123'
+  }, { source: 'mapping.json' });
+
+  assertIncludes(errors, 'entry "TC-001" must be an object');
+}
+
+function testMappingRejectsUnsupportedField() {
+  const errors = validateTestManagementMapping({
+    'TC-001': {
+      externalId: 'C123',
+      owner: 'qa'
+    }
+  }, { source: 'mapping.json' });
+
+  assertIncludes(errors, 'unsupported field "owner"');
+}
+
+function testMappingRejectsDuplicateExternalId() {
+  const errors = validateTestManagementMapping({
+    'TC-001': { externalId: 'C123' },
+    'TC-002': { externalId: 'C123' }
+  }, { source: 'mapping.json' });
+
+  assertIncludes(errors, 'externalId "C123" is used by both');
+}
+
+function testMappingRejectsSecretLikeFields() {
+  const errors = validateTestManagementMapping({
+    'TC-001': {
+      externalId: 'C123',
+      apiToken: 'github_pat_1234567890abcdefghijklmnop'
+    }
+  }, { source: 'mapping.json' });
+
+  assertIncludes(errors, 'unsupported field "apiToken"');
+  assertIncludes(errors, 'appears to contain a secret');
+}
+
+async function testMappingTemplateIsValid() {
+  const templatePath = path.resolve('.qa-ai/templates/test-management-mapping.template.json');
+  const parsed = JSON.parse(await fs.readFile(templatePath, 'utf8'));
+  assert.deepEqual(validateTestManagementMapping(parsed, { source: 'test-management-mapping.template.json' }), []);
+}
+
+function testNormalizeQaTrack() {
+  assert.equal(normalizeQaTrack('fast'), 'quick');
+  assert.equal(normalizeQaTrack('enterprise'), 'enterprise');
+  assert.equal(normalizeQaTrack('unknown-value'), 'standard');
+}
+
+async function testQaHelpWithoutConfig() {
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'qa-ai-help-'));
+  const report = await inspectQaWorkflow(tempDir);
+  assert.equal(report.initialized, false);
+  assert.ok(report.recommendations.some((item) => item.command.includes('init.mjs')));
+}
+
+function testReleaseGatePass() {
+  const result = validateReleaseGateData({
+    decision: 'PASS',
+    approver: 'QA Lead',
+    coverage_summary: 'All validators passed.',
+    open_risks: ['None documented'],
+    evidence_paths: ['qa-ai-output/traceability-matrix.md', 'qa-ai-output/pr-summary.md']
+  });
+  assert.deepEqual(result.errors, []);
+  assert.equal(result.decision, 'PASS');
+}
+
+function testReleaseGatePendingCanBeAllowed() {
+  const draft = {
+    decision: 'PENDING',
+    coverage_summary: 'Draft review in progress.',
+    open_risks: ['Pending QA lead review'],
+    evidence_paths: ['qa-ai-output/pr-summary.md']
+  };
+
+  assert.notEqual(validateReleaseGateData(draft).errors.length, 0);
+  assert.deepEqual(validateReleaseGateData(draft, { allowPending: true }).errors, []);
+}
+
+function testTestDesignSystemSections() {
+  const valid = validateTestDesignSystem(`# System Test Design\n${[
+    '## Scope',
+    '## Architecture alignment',
+    '## Testability risks',
+    '## Cross-RF coverage strategy',
+    '## Shared fixtures and data',
+    '## Non-functional focus',
+    '## Open questions'
+  ].join('\n\n')}\n`);
+  assert.equal(valid.ok, true);
+  const invalid = validateTestDesignSystem('# System Test Design\n## Scope\n');
+  assert.equal(invalid.ok, false);
+}
+
+function testSpanishTestDesignSections() {
+  const system = validateTestDesignSystem(`# Diseno de pruebas de sistema\n${[
+    '## Alcance',
+    '## Alineacion con arquitectura',
+    '## Riesgos de testabilidad',
+    '## Estrategia de cobertura entre RFs',
+    '## Fixtures y datos compartidos',
+    '## Enfoque no funcional',
+    '## Preguntas abiertas'
+  ].join('\n\n')}\n`);
+  assert.equal(system.ok, true);
+
+  const proposal = validateTestDesignProposal(`# Propuesta de diseno de pruebas\n${[
+    '## RF oficial',
+    'RF-101',
+    '## Alcance',
+    '## Pruebas propuestas',
+    '## Pruebas existentes para reutilizar',
+    '## Pruebas existentes que requieren modificacion',
+    '## Nuevas pruebas a crear',
+    '## Ambiguedades que requieren decision del usuario',
+    '## Solicitud de aprobacion'
+  ].join('\n\n')}\n`);
+  assert.equal(proposal.ok, true);
+}
+
+function testTestDesignProposalSections() {
+  const valid = validateTestDesignProposal(`# Test Design Proposal\n${[
+    '## Official RF ID',
+    'RF-101',
+    '## Scope',
+    '## Proposed tests',
+    '## Existing tests to reuse',
+    '## Existing tests requiring modification',
+    '## New tests to create',
+    '## Ambiguities requiring user decision',
+    '## Approval request'
+  ].join('\n\n')}\n`);
+  assert.equal(valid.ok, true);
+}
+
+function testReleaseGateWaivedRequiresApprover() {
+  const result = validateReleaseGateData({
+    decision: 'WAIVED',
+    coverage_summary: 'Partial coverage accepted.',
+    open_risks: ['Known gap in API tests'],
+    evidence_paths: ['qa-ai-output/pr-summary.md']
+  });
+  assert.ok(result.errors.some((error) => error.includes('approver')));
+  assert.ok(result.errors.some((error) => error.includes('waived_reason')));
+}
+
+async function testQaHelpQuickTrackPendingGherkin() {
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'qa-ai-help-'));
+  await fs.mkdir(path.join(tempDir, '.qa-ai'), { recursive: true });
+  await fs.mkdir(path.join(tempDir, 'qa-ai-output'), { recursive: true });
+  await fs.writeFile(
+    path.join(tempDir, 'qa-ai.config.yaml'),
+    [
+      'project:',
+      '  qaTrack: quick',
+      'knowledge:',
+      '  enabled: false',
+      'tools:',
+      '  testManagement: none',
+      '  issueTracker: none',
+      'automation:',
+      '  ui:',
+      '    framework: none',
+      '  api:',
+      '    framework: none',
+      'gherkin:',
+      '  featurePath: features',
+      'traceability:',
+      '  matrixPath: qa-ai-output/traceability-matrix.md',
+      ''
+    ].join('\n'),
+    'utf8'
+  );
+  await fs.writeFile(
+    path.join(tempDir, 'qa-ai-output', 'requirement-analysis.md'),
+    '# Requirement Analysis\n',
+    'utf8'
+  );
+  await fs.writeFile(
+    path.join(tempDir, 'qa-ai-output', 'normalized-requirements.md'),
+    '# Normalized Requirements\n',
+    'utf8'
+  );
+
+  const report = await inspectQaWorkflow(tempDir);
+  assert.equal(report.track, 'quick');
+  assert.ok(!report.pendingPhaseIds.includes('tm-coverage'));
+  assert.ok(!report.pendingPhaseIds.includes('feasibility'));
+  assert.equal(report.pendingPhaseIds[0], 'gherkin');
+  assert.ok(report.recommendations.some((item) => item.title.includes('Gherkin')));
+}
+
+async function main() {
+  testNormalizeQaTrack();
+  testTestDesignSystemSections();
+  testTestDesignProposalSections();
+  testSpanishTestDesignSections();
+  testReleaseGatePass();
+  testReleaseGatePendingCanBeAllowed();
+  testReleaseGateWaivedRequiresApprover();
+  await testQaHelpWithoutConfig();
+  await testQaHelpQuickTrackPendingGherkin();
+  testValidTable();
+  testMissingSeparator();
+  testMissingRequiredColumn();
+  testWrongCellCount();
+  testEmptyRow();
+  testEmptyMappingIsValid();
+  testValidMappingEntry();
+  testMappingEntryMustBeObject();
+  testMappingRejectsUnsupportedField();
+  testMappingRejectsDuplicateExternalId();
+  testMappingRejectsSecretLikeFields();
+  await testMappingTemplateIsValid();
+  console.log('Validator unit tests passed.');
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/.qa-ai/scripts/validate-active-specialists.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import {
+  activeSpecialists,
+  specialistCatalog
+} from './lib/project-config.mjs';
+import {
+  loadQaAiConfig,
+  logHeader,
+  parseArgs,
+  pathExists,
+  readText,
+  relativeTo,
+  resolveRepoPath
+} from './lib/utils.mjs';
+
+const cwd = process.cwd();
+const args = parseArgs(process.argv);
+
+function printHelp() {
+  console.log(`Usage: node .qa-ai/scripts/validate-active-specialists.mjs [options]
+
+Options:
+  --allow-missing  Return success when qa-ai.config.yaml or active.md is missing
+  --help           Show this help
+`);
+}
+
+function listedSpecialistIds(content) {
+  return content
+    .split(/\r?\n/)
+    .map((line) => line.match(/^\s*-\s+`([^`]+)`:/)?.[1])
+    .filter(Boolean)
+    .sort();
+}
+
+function uniqueSorted(values) {
+  return [...new Set(values)].sort();
+}
+
+async function main() {
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  logHeader('QA AI active specialists validator');
+  const configInfo = await loadQaAiConfig(cwd);
+  const activePath = resolveRepoPath(cwd, '.qa-ai/agents/specialists/active.md', {
+    label: 'active specialists index'
+  });
+
+  if (!configInfo.exists) {
+    console.log('No qa-ai.config.yaml found.');
+    if (args['allow-missing']) return;
+    console.log('\nFAILED - active specialist validation requires qa-ai.config.yaml.');
+    process.exit(1);
+  }
+
+  if (!await pathExists(activePath)) {
+    console.log('No active specialists index found at .qa-ai/agents/specialists/active.md.');
+    if (args['allow-missing']) return;
+    console.log('\nFAILED - run init or config import to generate active specialists.');
+    process.exit(1);
+  }
+
+  const expected = activeSpecialists(configInfo.data).map(([id]) => id).sort();
+  const actual = listedSpecialistIds(await readText(activePath));
+  const errors = [];
+
+  for (const id of expected.filter((id) => !actual.includes(id))) {
+    errors.push(`Missing active specialist: ${id}`);
+  }
+  for (const id of actual.filter((id) => !expected.includes(id))) {
+    errors.push(`Stale active specialist: ${id}`);
+  }
+  for (const id of actual) {
+    if (!(id in specialistCatalog)) {
+      errors.push(`Unknown active specialist: ${id}`);
+      continue;
+    }
+    const sourcePath = resolveRepoPath(cwd, `.qa-ai/agents/specialists/available/${id}.md`, {
+      label: `specialist source "${id}"`
+    });
+    if (!await pathExists(sourcePath)) {
+      errors.push(`Missing specialist source for ${id}: ${relativeTo(cwd, sourcePath)}`);
+    }
+  }
+
+  if (uniqueSorted(actual).length !== actual.length) {
+    errors.push('Duplicate specialist entries found in active.md.');
+  }
+
+  if (errors.length > 0) {
+    for (const error of errors) console.log(`[FAIL] ${error}`);
+    console.log(`\nFAILED - ${errors.length} active specialist validation error(s).`);
+    process.exit(1);
+  }
+
+  console.log(`[PASS] ${relativeTo(cwd, activePath)} matches qa-ai.config.yaml.`);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});