@keber/qa-framework 1.11.3 → 1.12.0

package/scripts/check-spanish-accents.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+/**
+ * check-spanish-accents.js
+ *
+ * Fails when a Markdown file whose prose is Spanish carries no accented characters.
+ *
+ * Why this exists: a spec written as "Codigo" while the UI renders "Código" produces a
+ * page-object selector that never matches. In one project that cost 24 of 39 failing smoke
+ * tests and two wrong mitigations (raising a timeout, forcing HTTP/1.1) before the real
+ * cause was found, because the failure presents as a timeout, not as a text mismatch.
+ * Accent stripping is a defect, not a house style - and its measured incidence in
+ * agent-generated artifacts is high enough that honor-system compliance does not hold.
+ *
+ * The hard part is not detecting missing accents; it is deciding which files are Spanish.
+ * A naive "every .md must contain accents" rule fails every legitimately English artifact
+ * the framework ships. Counting Spanish marker words in raw text does not separate them
+ * either: an English document about a Spanish-language project quotes enough Spanish paths,
+ * identifiers and snippets to cross any absolute threshold that still catches short
+ * Spanish files.
+ *
+ * So this classifies on the density of Spanish function words in PROSE ONLY, after
+ * stripping fenced code, inline code, link targets, HTML tags and table pipes. English
+ * prose that merely cites Spanish identifiers scores low because those citations live in
+ * the stripped regions; real Spanish prose scores high because its function words are
+ * spread through the sentences themselves.
+ *
+ * Usage:
+ *   node scripts/check-spanish-accents.js <file|dir> [...]   check paths
+ *   node scripts/check-spanish-accents.js --staged           check staged .md files
+ *   node scripts/check-spanish-accents.js --report <paths>   print scores, never fail
+ *
+ * Exit codes: 0 = clean, 1 = at least one Spanish file has no accents, 2 = usage error.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+// Function words that are unavoidable in real Spanish prose and rare in English text.
+// Deliberately excludes "no", "a", "en", "es" and other tokens that collide with English
+// or with code, and excludes accented forms so a stripped file is not penalised twice.
+const MARKERS = [
+  'que', 'para', 'con', 'por', 'los', 'las', 'del', 'una', 'como', 'pero',
+  'este', 'esta', 'estos', 'estas', 'sin', 'sobre', 'desde', 'cuando', 'donde',
+  'cada', 'todo', 'todos', 'toda', 'todas', 'entre', 'hasta', 'porque', 'segun',
+  'debe', 'deben', 'ser', 'son', 'hay', 'muy', 'ya', 'si', 'lo', 'le', 'se',
+];
+
+const ACCENTED = /[áéíóúÁÉÍÓÚñÑüÜ]/;
+
+// A file is Spanish when at least this share of its prose words are Spanish markers.
+// Calibrated against this package's own corpus: Spanish agent templates land near 0.13,
+// English skill files and the FRAMEWORK-FIXES reports stay below 0.03.
+const DENSITY_THRESHOLD = 0.07;
+// Below this many prose words the density estimate is too noisy to act on.
+const MIN_PROSE_WORDS = 60;
+
+/** Remove every region where Spanish tokens are citations rather than prose. */
+function extractProse(markdown) {
+  return markdown
+    .replace(/^---\n[\s\S]*?\n---/, ' ')      // YAML frontmatter
+    .replace(/```[\s\S]*?```/g, ' ')          // fenced code
+    .replace(/~~~[\s\S]*?~~~/g, ' ')          // fenced code, alt syntax
+    .replace(/`[^`\n]*`/g, ' ')               // inline code
+    .replace(/\]\([^)]*\)/g, '] ')            // link targets, keep link text
+    .replace(/<[^>\n]*>/g, ' ')               // HTML tags and <placeholders>
+    .replace(/\{\{[^}]*\}\}/g, ' ')           // {{TEMPLATE_PLACEHOLDERS}}
+    .replace(/\|/g, ' ')                      // table pipes
+    .replace(/^\s{4,}\S.*$/gm, ' ')           // indented code blocks
+    .replace(/[A-Za-z0-9_.\-]+\/[A-Za-z0-9_./\-]+/g, ' ') // bare paths
+    .replace(/[#*_>[\]]/g, ' ');              // remaining markdown punctuation
+}
+
+function score(markdown) {
+  const prose = extractProse(markdown);
+  const words = prose.toLowerCase().match(/[a-zà-ÿ]+/g) || [];
+  const markers = words.filter((w) => MARKERS.includes(w)).length;
+  const density = words.length ? markers / words.length : 0;
+  return {
+    words: words.length,
+    markers,
+    density,
+    isSpanish: words.length >= MIN_PROSE_WORDS && density >= DENSITY_THRESHOLD,
+    hasAccents: ACCENTED.test(markdown),
+  };
+}
+
+function collect(target) {
+  const stat = fs.statSync(target);
+  if (stat.isFile()) return target.endsWith('.md') ? [target] : [];
+  return fs.readdirSync(target).flatMap((entry) => {
+    if (entry === 'node_modules' || entry === '.git') return [];
+    return collect(path.join(target, entry));
+  });
+}
+
+function stagedMarkdown() {
+  const out = execFileSync(
+    'git',
+    ['diff', '--cached', '--name-only', '--diff-filter=ACM', '--', '*.md'],
+    { encoding: 'utf8' }
+  );
+  return out.split('\n').map((s) => s.trim()).filter((s) => s && fs.existsSync(s));
+}
+
+function main(argv) {
+  const reportOnly = argv.includes('--report');
+  const args = argv.filter((a) => a !== '--report');
+
+  let files;
+  if (args.includes('--staged')) {
+    files = stagedMarkdown();
+  } else if (args.length) {
+    files = args.flatMap(collect);
+  } else {
+    console.error('usage: check-spanish-accents.js <file|dir>... | --staged [--report]');
+    return 2;
+  }
+
+  const failures = [];
+  for (const file of files) {
+    const result = score(fs.readFileSync(file, 'utf8'));
+    if (reportOnly) {
+      console.log(
+        `${result.isSpanish ? 'ES' : 'en'}  density=${result.density.toFixed(3)}  ` +
+        `words=${String(result.words).padStart(5)}  accents=${result.hasAccents ? 'yes' : 'NO '}  ${file}`
+      );
+    }
+    if (result.isSpanish && !result.hasAccents) failures.push({ file, ...result });
+  }
+
+  if (reportOnly) return 0;
+
+  if (failures.length) {
+    console.error('\nSpanish Markdown without accented characters:\n');
+    for (const f of failures) {
+      console.error(`  ${f.file}`);
+      console.error(
+        `    ${f.markers} Spanish markers in ${f.words} prose words ` +
+        `(density ${f.density.toFixed(3)}), 0 accented characters.`
+      );
+    }
+    console.error(
+      '\nSpanish prose must carry its accents: a spec saying "Codigo" does not match a UI' +
+      '\nthat renders "Código", and the resulting selector failure looks like a timeout.' +
+      '\nFix the orthography rather than bypassing this check.\n'
+    );
+    return 1;
+  }
+
+  console.log(`check-spanish-accents: ${files.length} file(s) checked, no violations.`);
+  return 0;
+}
+
+if (require.main === module) process.exit(main(process.argv.slice(2)));
+
+module.exports = { score, extractProse, MARKERS, DENSITY_THRESHOLD };

package/scripts/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * scripts/cli.js — keber/qa-framework CLI entry point
+ * scripts/cli.js - keber/qa-framework CLI entry point
  *
  * Usage:
  *   npx keber/qa-framework <command> [options]

package/scripts/generate.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * scripts/generate.js — Generate a qa artifact from a template
+ * scripts/generate.js - Generate a qa artifact from a template
  *
  * Usage:
  *   qa-framework generate <artifact> [options]
@@ -39,7 +39,7 @@ const outputDir     = getArg('--output')    ? path.resolve(process.cwd(), getArg
 const templateDir = path.resolve(__dirname, '..', 'templates');
 
 const ARTIFACTS = {
-  spec:             null,    // special — copies all 6 files
+  spec:             null,    // special - copies all 6 files
   'test-plan':      path.join(templateDir, 'test-plan.md'),
   'test-case':      path.join(templateDir, 'test-case.md'),
   'execution-report': path.join(templateDir, 'execution-report.md'),

package/scripts/init.js

@@ -15,6 +15,9 @@
 const fs   = require('fs');
 const path = require('path');
 
+const { buildCommandContent, discoverSkillNames, commandFileName } = require('./lib/claude-commands');
+const { AGENT_NAMES, isSprintCycleEnabled, buildAgentContent, agentFileName } = require('./lib/claude-agents');
+
 // --- Parse args ---
 const args            = process.argv.slice(2);
 const configFlag      = args.indexOf('--config');
@@ -126,7 +129,7 @@ if (fs.existsSync(qaReadmeTemplate)) {
 // --- qa/memory/INDEX.md ---
 const memoryDir = path.join(qaRoot, 'memory');
 writeIfMissing(path.join(memoryDir, 'INDEX.md'),
-`# Memory Index — ${config.project?.displayName ?? config.project?.name ?? 'Project'}
+`# Memory Index - ${config.project?.displayName ?? config.project?.name ?? 'Project'}
 
 > The agent reads this file first before loading any memory file.
 > Add a row here whenever you create or update a file in this directory.
@@ -146,7 +149,7 @@ for (const file of ['ci-pipeline-findings.md', 'e2e-stabilization-patterns.md',
 
 // --- 03-test-cases README (optional directory marker) ---
 writeIfMissing(path.join(qaRoot, '03-test-cases', 'README.md'),
-`# 03-test-cases/ — Optional Standalone Test Cases
+`# 03-test-cases/ - Optional Standalone Test Cases
 
 > **v1.7.0+:** The primary location for test cases (with detailed steps) is now
 > \`qa/02-test-plans/sprints/Sprint-{N}/Plan-de-Pruebas-{project}-Sprint-{N}-{module}.md\`.
@@ -198,7 +201,7 @@ for (const mod of modules) {
 
   for (const sub of submodules) {
     const subKey = sub.key ?? sub.name.toLowerCase().replace(/\s+/g, '-');
-    const subDir = path.join(qaRoot, moduleKey, subKey);
+    const subDir = path.join(qaRoot, '01-specifications', moduleKey, subKey);
     fs.mkdirSync(subDir, { recursive: true });
 
     for (const specFile of SPEC_FILES) {
@@ -245,6 +248,19 @@ for (const file of ['playwright.config.ts', 'global-setup.ts', '.env.example', '
     console.log(`  [created] ${path.relative(cwd, dest)}`);
   }
 }
+// Lane scripts: the lane lock plus its config reader and global-setup guards. Plain
+// CommonJS so they run as a CLI and stay testable with `node --test` without pulling
+// in a TypeScript test runner.
+const laneScriptsDir = path.join(e2eScaffoldDir, 'scripts');
+fs.mkdirSync(laneScriptsDir, { recursive: true });
+for (const file of ['lane-config.js', 'lane-lock.js', 'global-setup-guards.js']) {
+  const dest = path.join(laneScriptsDir, file);
+  if (!fs.existsSync(dest)) {
+    fs.copyFileSync(path.join(scaffoldSrc, 'scripts', file), dest);
+    console.log(`  [created] ${path.relative(cwd, dest)}`);
+  }
+}
+
 const fixturesDir = path.join(e2eScaffoldDir, 'fixtures');
 fs.mkdirSync(fixturesDir, { recursive: true });
 for (const file of ['auth.ts', 'test-helpers.ts', 'base.ts']) {
@@ -283,7 +299,7 @@ const adoDir = path.join(qaRoot, '08-azure-integration');
 writeIfMissing(path.join(adoDir, 'README.md'), `# ADO Integration\n\nSee keber/qa-framework integrations/ado-powershell/ for setup instructions.\n`);
 writeIfMissing(path.join(adoDir, 'module-registry.json'), JSON.stringify({ modules: [] }, null, 2));
 
-// --- Skills → .github/skills/ ---
+// --- Skills -> .github/skills/ ---
 const skillsSrc = path.resolve(__dirname, '..', 'skills');
 const skillsDest = path.join(cwd, '.github', 'skills');
 fs.mkdirSync(skillsDest, { recursive: true });
@@ -298,7 +314,7 @@ if (fs.existsSync(skillsSrc)) {
   }
 }
 
-// --- QA structure guide → qa/QA-STRUCTURE-GUIDE.md ---
+// --- QA structure guide -> qa/QA-STRUCTURE-GUIDE.md ---
 const structureGuideSrc  = path.resolve(__dirname, '..', 'docs', 'folder-structure-guide.md');
 const structureGuideDest = path.join(qaRoot, 'QA-STRUCTURE-GUIDE.md');
 if (fs.existsSync(structureGuideSrc)) {
@@ -314,7 +330,33 @@ const copilotInstrContent = fs.readFileSync(instrTemplatePath, 'utf8')
   .replace('{{VERSION}}', config.frameworkVersion ?? '1.0.0');
 writeIfMissing(copilotInstrPath, copilotInstrContent);
 
-// --- AGENT-NEXT-STEPS.md — readable by the agent after install ---
+// --- .claude/commands/qa-*.md - thin wrappers pointing at .github/skills/ ---
+const claudeCommandsDest = path.join(cwd, '.claude', 'commands');
+fs.mkdirSync(claudeCommandsDest, { recursive: true });
+for (const skillName of discoverSkillNames(skillsSrc)) {
+  writeIfMissing(path.join(claudeCommandsDest, commandFileName(skillName)), buildCommandContent(skillName));
+}
+
+// --- .claude/rules/qa-framework.md - always-loaded rules (Claude Code equivalent of applyTo: '**') ---
+const claudeRulesPath  = path.join(cwd, '.claude', 'rules', 'qa-framework.md');
+const rulesTemplatePath = path.resolve(__dirname, '..', 'templates', 'qa-framework.rules.md');
+const claudeRulesContent = fs.readFileSync(rulesTemplatePath, 'utf8')
+  .replace('{{VERSION}}', config.frameworkVersion ?? '1.0.0');
+writeIfMissing(claudeRulesPath, claudeRulesContent);
+
+// --- .claude/agents/qa-*.md - optional ANALISIS/PLAN sprint-cycle mode (Claude Code only) ---
+// Gated by integrations.azureDevOps.sprintCycle.enabled. No .github/ equivalent: Claude
+// Code subagents with per-agent tools/model frontmatter have no Copilot counterpart.
+if (isSprintCycleEnabled(config)) {
+  const templatesDir = path.resolve(__dirname, '..', 'templates');
+  const claudeAgentsDest = path.join(cwd, '.claude', 'agents');
+  fs.mkdirSync(claudeAgentsDest, { recursive: true });
+  for (const agentName of AGENT_NAMES) {
+    writeIfMissing(path.join(claudeAgentsDest, agentFileName(agentName)), buildAgentContent(agentName, templatesDir, config));
+  }
+}
+
+// --- AGENT-NEXT-STEPS.md - readable by the agent after install ---
 const nextStepsContent = `# ✅ @keber/qa-framework installed successfully
 
 > This file was generated automatically by the postinstall script.
@@ -324,6 +366,7 @@ const nextStepsContent = `# ✅ @keber/qa-framework installed successfully
 
 - \`qa/\` folder structure with spec templates and agent instructions
 - \`.github/instructions/qa-framework.instructions.md\` with QA agent behavior rules (framework-owned, safe to upgrade)
+- \`.claude/rules/qa-framework.md\` and \`.claude/commands/qa-*.md\` - equivalent Claude Code artifacts (framework-owned, safe to upgrade)
 
 ## Required next steps
 
@@ -362,12 +405,17 @@ const adoQaInstalledFinal = fs.existsSync(path.join(cwd, 'node_modules', '@keber
 const azureReporterInstalled = fs.existsSync(path.join(cwd, 'node_modules', '@alex_neo', 'playwright-azure-reporter'));
 
 console.log('');
-console.log('  @keber/qa-framework — scaffold complete');
+console.log('  @keber/qa-framework - scaffold complete');
 console.log('  ----------------------------------------');
 console.log('  Installed:');
 console.log('    qa/                    QA directory structure + spec templates');
 console.log('    .github/skills/        QA agent skills (8 stages)');
 console.log('    .github/instructions/  qa-framework.instructions.md');
+console.log('    .claude/commands/      qa-*.md (Claude Code slash commands)');
+console.log('    .claude/rules/         qa-framework.md (Claude Code always-loaded rules)');
+if (isSprintCycleEnabled(config)) {
+  console.log('    .claude/agents/        qa-analisis/qa-plan/qa-asesoria/qa-informe-resultados.md (ANALISIS/PLAN mode)');
+}
 console.log('');
 console.log('  Optional integrations:');
 if (playwrightInstalled) {

package/scripts/lib/claude-agents.js

@@ -0,0 +1,78 @@
+'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 config.integrations.azureDevOps.sprintCycle, falling back
+ * to neutral defaults when a field (or the whole config section) is absent.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const AGENT_NAMES = ['qa-analisis', 'qa-plan', 'qa-asesoria', 'qa-informe-resultados'];
+
+const DEFAULT_SPRINT_CYCLE = {
+  sprintDurationDays: 8,
+  manualTestingTimeboxDays: 2,
+  dateFormat: 'dd-mm-aaaa',
+  timezone: 'America/Santiago',
+};
+
+const LOCALE_LANGUAGE_LABELS = {
+  es: 'espanol',
+  'es-cl': 'espanol de Chile',
+  'es-mx': 'espanol de Mexico',
+  'es-ar': 'espanol de Argentina',
+  en: 'English',
+};
+
+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 buildPlaceholders(config) {
+  const sprintCycle = { ...DEFAULT_SPRINT_CYCLE, ...(config?.integrations?.azureDevOps?.sprintCycle ?? {}) };
+  const project = config?.project ?? {};
+
+  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}}': config?.project?.name ? config.project.name.toUpperCase().replace(/[^A-Z0-9]/g, '-') : 'PROJ',
+  };
+}
+
+function buildAgentContent(agentName, templatesDir, config) {
+  const templatePath = path.join(templatesDir, 'agents', `${agentName}.md`);
+  let content = fs.readFileSync(templatePath, 'utf8');
+  const placeholders = buildPlaceholders(config);
+  for (const [placeholder, value] of Object.entries(placeholders)) {
+    content = content.split(placeholder).join(value);
+  }
+  return content;
+}
+
+function agentFileName(agentName) {
+  return `${agentName}.md`;
+}
+
+module.exports = {
+  AGENT_NAMES,
+  isSprintCycleEnabled,
+  buildAgentContent,
+  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/sync-version.js

@@ -0,0 +1,36 @@
+#!/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'),
+];
+
+// 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 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}`);
+  }
+}