@keber/qa-framework 1.11.3 → 1.13.0

package/scripts/lib/claude-agents.js

@@ -0,0 +1,347 @@
+'use strict';
+
+/**
+ * scripts/lib/claude-agents.js - Generate .claude/agents/qa-*.md sprint-cycle subagents
+ *
+ * Optional ANALISIS/PLAN mode, gated by integrations.azureDevOps.sprintCycle.enabled in
+ * qa-framework.config.json. Claude Code only - subagents with per-agent tools/model
+ * frontmatter have no GitHub Copilot equivalent, so no .github/ counterpart is generated.
+ *
+ * Placeholders are resolved from the project config, falling back to neutral defaults
+ * when a field (or the whole config section) is absent.
+ *
+ * Template syntax:
+ *   {{NAME}}                         placeholder, replaced in a single pass (values are
+ *                                    inserted verbatim and never re-expanded)
+ *   {{#if FLAG}}...{{/if}}           kept only when FLAG is true (not nestable)
+ *   {{#unless FLAG}}...{{/unless}}   kept only when FLAG is false (not nestable)
+ *
+ * Any {{...}} token left after rendering is a template bug and throws.
+ *
+ * buildAgentContent() throws per agent, so callers can generate the agents that are
+ * valid, report the one that is not, and exit non-zero.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { laneTableFromConfig, DEFAULT_LANE_TABLE } = require('../../templates/automation-scaffold/scripts/lane-config');
+
+const AGENT_NAMES = [
+  'qa-analisis',
+  'qa-plan',
+  'qa-asesoria',
+  'qa-informe-resultados',
+  'qa-reporte-ejecucion',
+  'qa-investigador',
+];
+
+const DEFAULT_SPRINT_CYCLE = {
+  sprintDurationDays: 8,
+  manualTestingTimeboxDays: 2,
+  dateFormat: 'dd-mm-aaaa',
+  timezone: 'America/Santiago',
+  approvalThresholdPercent: 85,
+};
+
+const DEFAULT_TC_ID_PATTERN = 'TC-{MODULE}-{SUBMODULE}-{NUM}';
+const NOT_CONFIGURED = '(no configurado: ver qa/qa-framework.config.json)';
+
+const MCP_NAMESPACE_PATTERN = /^mcp__[A-Za-z0-9_-]+__$/;
+const DEFECT_ID_PREFIX_PATTERN = /^[A-Z0-9-]+$/;
+const DECIMAL_SEPARATORS = [',', '.'];
+
+// Playwright MCP tools granted to qa-investigador per lane namespace, in this order.
+const BROWSER_TOOLS = [
+  'browser_navigate',
+  'browser_snapshot',
+  'browser_click',
+  'browser_type',
+  'browser_fill_form',
+  'browser_select_option',
+  'browser_hover',
+  'browser_press_key',
+  'browser_wait_for',
+  'browser_evaluate',
+  'browser_network_requests',
+  'browser_console_messages',
+  'browser_take_screenshot',
+  'browser_find',
+  'browser_close',
+];
+
+const INVESTIGATOR_BASE_TOOLS = ['Read', 'Write', 'Edit', 'Grep', 'Glob', 'Bash'];
+
+const LOCALE_LANGUAGE_LABELS = {
+  es: 'espanol',
+  'es-cl': 'espanol de Chile',
+  'es-mx': 'espanol de Mexico',
+  'es-ar': 'espanol de Argentina',
+  en: 'English',
+};
+
+// Tokens whose value depends on the lane table. They are resolved only for templates
+// that use them, so an invalid lane config fails qa-investigador and nothing else.
+const LANE_TOKENS = ['{{INVESTIGATOR_TOOLS}}', '{{LANE_MCP_TABLE}}', 'HAS_MCP_LANES'];
+
+function isSprintCycleEnabled(config) {
+  return Boolean(config?.integrations?.azureDevOps?.sprintCycle?.enabled);
+}
+
+function resolveLocaleLanguageLabel(locale) {
+  if (!locale) return 'espanol';
+  return LOCALE_LANGUAGE_LABELS[locale.toLowerCase()] ?? locale;
+}
+
+function isValidApprovalThreshold(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 && value < 100;
+}
+
+function resolveApprovalThresholdPercent(sprintCycle) {
+  const value = sprintCycle.approvalThresholdPercent;
+  // Invalid values are reported by `qa-framework validate`; generation keeps the default.
+  return isValidApprovalThreshold(value) ? value : DEFAULT_SPRINT_CYCLE.approvalThresholdPercent;
+}
+
+function formatRatio(percent) {
+  // Rounded to strip binary float noise (e.g. 57 / 100), always with a dot.
+  return String(Number((percent / 100).toFixed(6)));
+}
+
+function resolveDecimalSeparator(config) {
+  const explicit = config?.conventions?.decimalSeparator;
+  if (DECIMAL_SEPARATORS.includes(explicit)) return explicit;
+  const locale = config?.conventions?.locale ?? config?.conventions?.language;
+  if (!locale) return ',';
+  return String(locale).toLowerCase().startsWith('es') ? ',' : '.';
+}
+
+function resolveDefectIdPrefix(config) {
+  const explicit = config?.conventions?.defectIdPrefix;
+  if (typeof explicit === 'string' && DEFECT_ID_PREFIX_PATTERN.test(explicit)) return explicit;
+  return config?.project?.name ? config.project.name.toUpperCase().replace(/[^A-Z0-9]/g, '-') : 'PROJ';
+}
+
+function resolveProjectField(value) {
+  if (typeof value !== 'string' || value.trim() === '' || value.includes('{{')) return NOT_CONFIGURED;
+  return value;
+}
+
+/**
+ * MCP-capable lanes in config order: [{ id, mcpNamespace }].
+ *
+ * Validation is delegated to laneTableFromConfig (the same reader the automation
+ * scaffold uses). Order comes from the config array, not from the table object,
+ * because numeric-like lane ids would otherwise be reordered by the JS engine.
+ * Throws on an invalid lane block or an mcpNamespace that is not a tool prefix.
+ */
+function resolveMcpLanes(config) {
+  const table = laneTableFromConfig(config);
+  if (table === DEFAULT_LANE_TABLE) return [];
+
+  const lanes = [];
+  for (const [index, entry] of config.parallelLanes.lanes.entries()) {
+    const lane = table[entry.id];
+    if (!lane || lane.mcpNamespace === null) continue;
+    if (!MCP_NAMESPACE_PATTERN.test(lane.mcpNamespace)) {
+      throw new Error(
+        `parallelLanes.lanes[${index}].mcpNamespace must match ${MCP_NAMESPACE_PATTERN} ` +
+          `(e.g. "mcp__playwright-qauser__"). Got: ${JSON.stringify(lane.mcpNamespace)}`
+      );
+    }
+    lanes.push({ id: entry.id, mcpNamespace: lane.mcpNamespace });
+  }
+  return lanes;
+}
+
+function buildLanePlaceholders(config) {
+  const mcpLanes = resolveMcpLanes(config);
+
+  const tools = [...INVESTIGATOR_BASE_TOOLS];
+  for (const { mcpNamespace } of mcpLanes) {
+    for (const tool of BROWSER_TOOLS) tools.push(`${mcpNamespace}${tool}`);
+  }
+
+  const tableLines = mcpLanes.length
+    ? [
+        '| Lane | Servidor MCP | Prefijo de herramientas |',
+        '| --- | --- | --- |',
+        ...mcpLanes.map(({ id, mcpNamespace }) =>
+          `| ${id} | ${mcpNamespace.replace(/^mcp__/, '').replace(/__$/, '')} | \`${mcpNamespace}\` |`
+        ),
+      ]
+    : [];
+
+  return {
+    placeholders: {
+      '{{INVESTIGATOR_TOOLS}}': tools.join(', '),
+      '{{LANE_MCP_TABLE}}': tableLines.join('\n'),
+    },
+    flags: { HAS_MCP_LANES: mcpLanes.length > 0 },
+  };
+}
+
+function buildPlaceholders(config) {
+  const sprintCycle = { ...DEFAULT_SPRINT_CYCLE, ...(config?.integrations?.azureDevOps?.sprintCycle ?? {}) };
+  const project = config?.project ?? {};
+  const approvalPercent = resolveApprovalThresholdPercent(sprintCycle);
+
+  return {
+    '{{PROJECT_NAME}}': project.name ?? '{{PROJECT_NAME}}',
+    '{{PROJECT_DISPLAY_NAME}}': project.displayName ?? project.name ?? '{{PROJECT_DISPLAY_NAME}}',
+    '{{SPRINT_DURATION_DAYS}}': String(sprintCycle.sprintDurationDays),
+    '{{MANUAL_TESTING_TIMEBOX_DAYS}}': String(sprintCycle.manualTestingTimeboxDays),
+    '{{DATE_FORMAT}}': sprintCycle.dateFormat,
+    '{{TIMEZONE}}': sprintCycle.timezone,
+    '{{LOCALE_LANGUAGE_LABEL}}': resolveLocaleLanguageLabel(config?.conventions?.locale ?? config?.conventions?.language),
+    '{{DEFECT_ID_PREFIX}}': resolveDefectIdPrefix(config),
+    '{{APPROVAL_THRESHOLD_PERCENT}}': String(approvalPercent).replace('.', resolveDecimalSeparator(config)),
+    '{{APPROVAL_THRESHOLD_RATIO}}': formatRatio(approvalPercent),
+    '{{DECIMAL_SEPARATOR}}': resolveDecimalSeparator(config),
+    '{{TC_ID_PATTERN}}': config?.conventions?.testCaseIdPattern || DEFAULT_TC_ID_PATTERN,
+    '{{QA_BASE_URL}}': resolveProjectField(project.qaBaseUrl),
+    '{{LOGIN_PATH}}': resolveProjectField(project.loginPath),
+    '{{TECH_STACK}}': resolveProjectField(project.techStack),
+  };
+}
+
+/**
+ * Renders conditional blocks, then placeholders, then guards against leftovers.
+ *
+ * A block whose opening and closing tags sit on their own lines is removed together
+ * with those lines, so dropping a block never leaves an extra blank line behind.
+ */
+function renderTemplate(template, placeholders, flags, agentName) {
+  let content = template;
+
+  for (const [keyword, keepWhen] of [['if', true], ['unless', false]]) {
+    const ownLine = new RegExp(
+      `^[ \\t]*\\{\\{#${keyword} ([A-Z0-9_]+)\\}\\}[ \\t]*\\r?\\n([\\s\\S]*?)^[ \\t]*\\{\\{\\/${keyword}\\}\\}[ \\t]*(?:\\r?\\n|$)`,
+      'gm'
+    );
+    const inline = new RegExp(`\\{\\{#${keyword} ([A-Z0-9_]+)\\}\\}([\\s\\S]*?)\\{\\{\\/${keyword}\\}\\}`, 'g');
+    const choose = (match, flag, body) => (Boolean(flags[flag]) === keepWhen ? body : '');
+    content = content.replace(ownLine, choose).replace(inline, choose);
+  }
+
+  const leftovers = new Set();
+  content = content.replace(/\{\{[#/]?[A-Za-z0-9_ ]+\}\}/g, (token) => {
+    if (Object.prototype.hasOwnProperty.call(placeholders, token)) return placeholders[token];
+    leftovers.add(token);
+    return token;
+  });
+
+  if (leftovers.size) {
+    throw new Error(
+      `Template for agent ${agentName} has unresolved tokens: ${[...leftovers].join(', ')}`
+    );
+  }
+  return content;
+}
+
+function buildAgentContent(agentName, templatesDir, config) {
+  const templatePath = path.join(templatesDir, 'agents', `${agentName}.md`);
+  try {
+    const template = fs.readFileSync(templatePath, 'utf8');
+    const placeholders = buildPlaceholders(config);
+    let flags = {};
+    if (LANE_TOKENS.some((token) => template.includes(token))) {
+      const lane = buildLanePlaceholders(config);
+      Object.assign(placeholders, lane.placeholders);
+      flags = lane.flags;
+    }
+    return renderTemplate(template, placeholders, flags, agentName);
+  } catch (err) {
+    if (err.message.startsWith(`Cannot generate agent ${agentName}`)) throw err;
+    throw new Error(`Cannot generate agent ${agentName}: ${err.message.replace(/^\[lane-config\] /, '')}`);
+  }
+}
+
+/**
+ * Renders every agent, never letting one failure stop the others.
+ * Returns [{ agentName, fileName, content }] or [{ agentName, fileName, error }].
+ */
+function renderAllAgents(templatesDir, config) {
+  return AGENT_NAMES.map((agentName) => {
+    const fileName = agentFileName(agentName);
+    try {
+      return { agentName, fileName, content: buildAgentContent(agentName, templatesDir, config) };
+    } catch (error) {
+      return { agentName, fileName, error };
+    }
+  });
+}
+
+/**
+ * Present-but-invalid values of the config keys the agents consume.
+ * Absent keys are never reported. Returns an array of messages.
+ */
+function validateAgentConfig(config) {
+  const errors = [];
+  const conventions = config?.conventions ?? {};
+  const sprintCycle = config?.integrations?.azureDevOps?.sprintCycle ?? {};
+
+  if ('approvalThresholdPercent' in sprintCycle && !isValidApprovalThreshold(sprintCycle.approvalThresholdPercent)) {
+    errors.push(
+      'integrations.azureDevOps.sprintCycle.approvalThresholdPercent must be a number greater than 0 and less than 100. ' +
+        `Got: ${JSON.stringify(sprintCycle.approvalThresholdPercent)}`
+    );
+  }
+  if ('decimalSeparator' in conventions && !DECIMAL_SEPARATORS.includes(conventions.decimalSeparator)) {
+    errors.push(`conventions.decimalSeparator must be "," or ".". Got: ${JSON.stringify(conventions.decimalSeparator)}`);
+  }
+  if (
+    'defectIdPrefix' in conventions &&
+    (typeof conventions.defectIdPrefix !== 'string' || !DEFECT_ID_PREFIX_PATTERN.test(conventions.defectIdPrefix))
+  ) {
+    errors.push(
+      `conventions.defectIdPrefix must match ${DEFECT_ID_PREFIX_PATTERN} (uppercase letters, digits, "-"). ` +
+        `Got: ${JSON.stringify(conventions.defectIdPrefix)}`
+    );
+  }
+
+  // Lanes are only checked when the generator actually consumes them: sprint agents on
+  // and a lane block that laneTableFromConfig does not short-circuit (enabled !== false).
+  // A disabled block, or a project without sprint agents, never fails validate here.
+  const block = config?.parallelLanes;
+  const lanesInUse =
+    isSprintCycleEnabled(config) && block !== undefined && block !== null && block.enabled !== false;
+  if (!lanesInUse) return errors;
+
+  const lanes = block.lanes;
+  if (Array.isArray(lanes)) {
+    lanes.forEach((lane, index) => {
+      const ns = lane && typeof lane === 'object' ? lane.mcpNamespace : undefined;
+      if (ns !== undefined && ns !== null && (typeof ns !== 'string' || !MCP_NAMESPACE_PATTERN.test(ns))) {
+        errors.push(
+          `parallelLanes.lanes[${index}].mcpNamespace must match ${MCP_NAMESPACE_PATTERN} or be null. Got: ${JSON.stringify(ns)}`
+        );
+      }
+    });
+  }
+  try {
+    laneTableFromConfig(config);
+  } catch (err) {
+    errors.push(`parallelLanes: ${err.message.replace(/^\[lane-config\] /, '')}`);
+  }
+
+  return errors;
+}
+
+function agentFileName(agentName) {
+  return `${agentName}.md`;
+}
+
+module.exports = {
+  AGENT_NAMES,
+  BROWSER_TOOLS,
+  DEFAULT_SPRINT_CYCLE,
+  isSprintCycleEnabled,
+  buildPlaceholders,
+  resolveMcpLanes,
+  renderTemplate,
+  buildAgentContent,
+  renderAllAgents,
+  validateAgentConfig,
+  agentFileName,
+};

package/scripts/lib/claude-commands.js

@@ -0,0 +1,56 @@
+'use strict';
+
+/**
+ * scripts/lib/claude-commands.js - Generate .claude/commands/qa-{name}.md thin wrappers
+ *
+ * Each generated command points back at the corresponding SKILL.md as the single
+ * source of truth (no content duplication, no drift). Skills are discovered
+ * dynamically from the filesystem, never hardcoded, so a newly added skill
+ * under skills/ is picked up automatically by init.js and upgrade.js.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Stage prerequisites mirrored from templates/qa-framework.instructions.md pipeline table.
+// Skills not listed here (e.g. a future addition) still get a valid command with no
+// prerequisite line, and this codebase does not need updating for the command to work.
+const STAGE_PREREQUISITES = {
+  'qa-module-analysis': 'Prerequisite: None - this is the first stage of the QA pipeline.',
+  'qa-spec-generation': 'Prerequisite: `00-inventory.md` exists.',
+  'qa-test-plan': 'Prerequisite: `05-test-scenarios.md` exists.',
+  'qa-test-cases': 'Prerequisite: Test plan exists.',
+  'qa-automation': 'Prerequisite: Specs approved, no PENDING-CODE.',
+  'qa-test-stabilization': 'Prerequisite: Failing or flaky tests exist in `qa/07-automation/e2e/`.',
+  'qa-maintenance': 'Prerequisite: Application change delivered.',
+  'qa-ado-integration': 'Prerequisite: ADO enabled in `qa/qa-framework.config.json`.',
+};
+
+function buildCommandContent(skillName) {
+  const prerequisite = STAGE_PREREQUISITES[skillName];
+  const lines = [
+    `Read the full skill at \`.github/skills/${skillName}/SKILL.md\` FIRST, then follow its instructions exactly.`,
+  ];
+  if (prerequisite) {
+    lines.push('', prerequisite);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function discoverSkillNames(skillsSrcDir) {
+  if (!fs.existsSync(skillsSrcDir)) return [];
+  return fs.readdirSync(skillsSrcDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function commandFileName(skillName) {
+  return `${skillName}.md`;
+}
+
+module.exports = {
+  buildCommandContent,
+  discoverSkillNames,
+  commandFileName,
+};

package/scripts/lib/module-keys.js

@@ -0,0 +1,54 @@
+'use strict';
+
+/**
+ * scripts/lib/module-keys.js - the one place that knows how a module or submodule
+ * key maps to a folder name.
+ *
+ * Two layouts coexist on purpose, and they are NOT the same string:
+ *
+ *   specs       qa/01-specifications/module-{name}/submodule-{name}/
+ *   automation  qa/07-automation/e2e/tests/{name}/{name}.spec.ts
+ *
+ * The prefixed form is what every skill under skills/, docs/folder-structure-guide.md
+ * and the "specPath" field of qa-framework.config.json declare. The bare form is what
+ * "automationPath" declares and what the live consuming projects actually contain.
+ * init.js used to write the bare form in both places, so a freshly scaffolded project
+ * violated the spec-path convention its own agent instructions impose.
+ *
+ * Both helpers are idempotent: a config that already spells the key as
+ * "module-suppliers" must not become "module-module-suppliers", and a key written
+ * bare must not lose a leading segment that merely looks like a prefix.
+ */
+
+/** Prefix `key` with `prefix-` unless it already carries it. */
+function withPrefix(prefix, key) {
+  const marker = `${prefix}-`;
+  return key.startsWith(marker) ? key : marker + key;
+}
+
+/** Strip a leading `prefix-` from `key` if present. */
+function withoutPrefix(prefix, key) {
+  const marker = `${prefix}-`;
+  return key.startsWith(marker) ? key.slice(marker.length) : key;
+}
+
+/** Folder name for a module's spec tree: module-{name}. */
+const moduleSpecDirName = key => withPrefix('module', key);
+
+/** Folder name for a submodule's spec tree: submodule-{name}. */
+const submoduleSpecDirName = key => withPrefix('submodule', key);
+
+/** Bare module name used by automation paths and TC ids. */
+const moduleBareName = key => withoutPrefix('module', key);
+
+/** Bare submodule name used by automation paths and TC ids. */
+const submoduleBareName = key => withoutPrefix('submodule', key);
+
+module.exports = {
+  withPrefix,
+  withoutPrefix,
+  moduleSpecDirName,
+  submoduleSpecDirName,
+  moduleBareName,
+  submoduleBareName,
+};

package/scripts/sync-version.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const rootDir = path.resolve(__dirname, '..');
+const pkg = require(path.join(rootDir, 'package.json'));
+const version = pkg.version;
+
+const targets = [
+  path.join(rootDir, 'README.md'),
+  path.join(rootDir, '.github', 'copilot-instructions.md'),
+];
+
+// qa-framework.config.json is published and is the template init.js copies into every
+// consuming project, where its frameworkVersion is injected into {{VERSION}} of the
+// generated agent instructions. Left out of this sync it silently drifted to 1.10.0
+// while the package shipped 1.12.0, so every fresh install told its agent the wrong
+// version. It is patched by field, not by the loose vX.Y.Z pattern used for prose.
+const jsonTargets = [
+  { file: path.join(rootDir, 'qa-framework.config.json'), field: 'frameworkVersion' },
+];
+
+// templates/qa-framework.instructions.md and templates/qa-framework.rules.md contain a
+// literal {{VERSION}} placeholder substituted by init.js/upgrade.js in the consumer
+// project at install/upgrade time. That placeholder is NOT a hardcoded version string
+// and must never be touched here.
+
+const versionPattern = /v\d+\.\d+\.\d+/;
+
+for (const { file: filePath, field } of jsonTargets) {
+  const original = fs.readFileSync(filePath, 'utf8');
+  const fieldPattern = new RegExp(
+    `("${field}"\\s*:\\s*")\\d+\\.\\d+\\.\\d+(")`
+  );
+
+  if (!fieldPattern.test(original)) {
+    throw new Error(`sync-version: no "${field}" version field in ${filePath}`);
+  }
+
+  const updated = original.replace(fieldPattern, `$1${version}$2`);
+
+  if (updated !== original) {
+    fs.writeFileSync(filePath, updated, 'utf8');
+    console.log(`sync-version: updated ${path.relative(rootDir, filePath)} ${field} -> ${version}`);
+  }
+}
+
+for (const filePath of targets) {
+  const original = fs.readFileSync(filePath, 'utf8');
+
+  if (!versionPattern.test(original)) {
+    throw new Error(`sync-version: no version string found in ${filePath}`);
+  }
+
+  const updated = original.replace(versionPattern, `v${version}`);
+
+  if (updated !== original) {
+    fs.writeFileSync(filePath, updated, 'utf8');
+    console.log(`sync-version: updated ${path.relative(rootDir, filePath)} -> v${version}`);
+  }
+}