@poleski/quality-tools 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @poleski/quality-tools
 
+## 0.2.0
+
+### Minor Changes
+
+- 5bab67a: Add an acceptance spec compiler that turns Gherkin-ish Markdown into Playwright tests.
+
 ## 0.1.4
 
 ### Patch Changes

package/README.md

@@ -24,6 +24,7 @@ pnpm add -D link:/absolute/path/to/quality-tools
 
 ```bash
 pnpm exec quality-tools organize .
+pnpm exec quality-tools acceptance compile --spec "tests/acceptance/specs/**/*.md" --steps "tests/acceptance/steps.ts" --out "tests/playwright/generated/acceptance.spec.ts"
 pnpm exec quality-tools boundaries . --strict
 pnpm exec quality-tools reachability . --strict
 pnpm exec quality-tools scrap ./tests
@@ -244,12 +245,15 @@ root, then falls back to the bundled base config.
 ## Other Tools
 
 ```bash
+pnpm exec quality-tools acceptance compile --spec "tests/acceptance/specs/**/*.md" --steps "tests/acceptance/steps.ts" --out "tests/playwright/generated/acceptance.spec.ts"
 pnpm exec quality-tools organize ./src
 pnpm exec quality-tools boundaries parser --strict
 pnpm exec quality-tools reachability parser --strict
 pnpm exec quality-tools scrap ./tests --strict
 ```
 
+- `acceptance` compiles human-authored Gherkin-ish Markdown specs into
+  executable Playwright specs that import host-owned step bindings.
 - `organize` checks directory size, depth, naming, barrels, and cohesion. Use
   `--write-baseline` and `--compare <path>` for baseline workflows.
 - `boundaries` checks configured layers, entrypoints, dead surfaces, and dead

package/dist/cli/main.js

@@ -1,5 +1,154 @@
 #!/usr/bin/env node
 
+// src/acceptance/command.ts
+import fs from "node:fs";
+import path from "node:path";
+import { glob } from "glob";
+
+// src/acceptance/parser.ts
+var FEATURE_PATTERN = /^#{0,6}\s*Feature:\s*(.+)$/;
+var SCENARIO_PATTERN = /^#{0,6}\s*Scenario:\s*(.+)$/;
+var STEP_PATTERN = /^(Given|When|Then|And|But)\s+(.+)$/;
+function parseAcceptanceMarkdown(markdown, sourcePath) {
+  const lines = markdown.split(/\r?\n/);
+  let feature;
+  const scenarios = [];
+  lines.forEach((rawLine, index) => {
+    const lineNumber = index + 1;
+    const line = rawLine.trim();
+    if (line === "") {
+      return;
+    }
+    const featureMatch = FEATURE_PATTERN.exec(line);
+    if (featureMatch) {
+      feature = {
+        name: featureMatch[1].trim(),
+        line: lineNumber
+      };
+      return;
+    }
+    const scenarioMatch = SCENARIO_PATTERN.exec(line);
+    if (scenarioMatch) {
+      scenarios.push({
+        name: scenarioMatch[1].trim(),
+        line: lineNumber,
+        steps: []
+      });
+      return;
+    }
+    const stepMatch = STEP_PATTERN.exec(line);
+    if (stepMatch) {
+      const scenario = scenarios.at(-1);
+      if (!scenario) {
+        throw new Error(`${sourcePath}:${lineNumber} Step appears before a Scenario`);
+      }
+      scenario.steps.push({
+        keyword: stepMatch[1],
+        text: stepMatch[2].trim(),
+        line: lineNumber
+      });
+    }
+  });
+  if (!feature) {
+    throw new Error(`${sourcePath}: Expected a Feature heading`);
+  }
+  if (scenarios.length === 0) {
+    throw new Error(`${sourcePath}: Expected at least one Scenario`);
+  }
+  const emptyScenario = scenarios.find((scenario) => scenario.steps.length === 0);
+  if (emptyScenario) {
+    throw new Error(`${sourcePath}:${emptyScenario.line} Scenario "${emptyScenario.name}" must contain at least one step`);
+  }
+  return {
+    sourcePath,
+    feature,
+    scenarios
+  };
+}
+
+// src/acceptance/playwright/generator.ts
+function generatePlaywrightAcceptanceSpec(documents, options) {
+  const sections = documents.flatMap((document) => generateDocumentSections(document));
+  return [
+    "/* Generated by quality-tools acceptance compile. Do not edit. */",
+    "/* eslint-disable playwright/expect-expect */",
+    "import { test } from '@playwright/test';",
+    `import { acceptanceSteps, createAcceptanceContext } from ${quote(options.stepsImportPath)};`,
+    "",
+    "type AcceptanceContext = Awaited<ReturnType<typeof createAcceptanceContext>> & { cleanup?: () => unknown | Promise<unknown> };",
+    "type AcceptanceRuntimeStep = { keyword: string; text: string; sourcePath: string; line: number };",
+    "type AcceptanceStepImplementation = (context: AcceptanceContext, step: AcceptanceRuntimeStep) => unknown | Promise<unknown>;",
+    "type AcceptanceStepRegistry = Record<string, AcceptanceStepImplementation>;",
+    "",
+    "async function runAcceptanceStep(",
+    "  context: AcceptanceContext,",
+    "  stepText: string,",
+    "  step: AcceptanceRuntimeStep",
+    "): Promise<void> {",
+    "  const registry = acceptanceSteps as AcceptanceStepRegistry;",
+    "  const implementation = registry[stepText] ?? registry[`${step.keyword} ${stepText}`];",
+    "",
+    "  if (!implementation) {",
+    '    throw new Error(`Missing acceptance step "${step.keyword} ${step.text}" at ${step.sourcePath}:${step.line}`);',
+    "  }",
+    "",
+    "  await implementation(context, step);",
+    "}",
+    "",
+    ...sections,
+    ""
+  ].join("\n");
+}
+function generateDocumentSections(document) {
+  const scenarios = document.scenarios.flatMap((scenario) => generateScenario(document.sourcePath, scenario));
+  return [
+    `test.describe(${quote(document.feature.name)}, () => {`,
+    ...indentLines(scenarios, 2),
+    "});",
+    ""
+  ];
+}
+function generateScenario(sourcePath, scenario) {
+  const steps = indentLines(scenario.steps.flatMap((step) => generateStep(sourcePath, step)), 4);
+  return [
+    `test(${quote(scenario.name)}, async ({}, testInfo) => {`,
+    "  const context = await createAcceptanceContext({",
+    "    testInfo,",
+    `    sourcePath: ${quote(sourcePath)},`,
+    `    scenario: ${quote(scenario.name)}`,
+    "  });",
+    "",
+    "  try {",
+    ...steps,
+    "  } finally {",
+    "    await context.cleanup?.();",
+    "  }",
+    "});"
+  ];
+}
+function generateStep(sourcePath, step) {
+  const label = `${step.keyword} ${step.text}`;
+  return [
+    `// ${sourcePath}:${step.line}`,
+    `await test.step(${quote(label)}, async () => {`,
+    `  await runAcceptanceStep(context, ${quote(step.text)}, {`,
+    `    keyword: ${quote(step.keyword)},`,
+    `    text: ${quote(step.text)},`,
+    `    sourcePath: ${quote(sourcePath)},`,
+    `    line: ${step.line}`,
+    "  });",
+    "});",
+    ""
+  ];
+}
+function quote(value) {
+  return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\r/g, "\\r").replace(/\n/g, "\\n")}'`;
+}
+function indentLines(lines, spaces) {
+  const prefix = " ".repeat(spaces);
+  return lines.map((line) => line === "" ? line : `${prefix}${line}`);
+}
+
 // src/shared/flagValue.ts
 function flagValue(args2, name) {
   const inlineFlag = args2.find((arg) => arg.startsWith(`${name}=`));
@@ -31,6 +180,83 @@ function cleanCliArgs(args2) {
   return args2.filter((arg) => arg !== "--");
 }
 
+// src/acceptance/command.ts
+async function runAcceptanceCli(rawArgs, options = {}) {
+  const args2 = cleanCliArgs(rawArgs);
+  const [command2, ...commandArgs] = args2;
+  if (command2 !== "compile") {
+    throw new Error("Usage: quality-tools acceptance compile --spec <glob> --steps <path> --out <path>");
+  }
+  await compileAcceptance(commandArgs, options.cwd ?? process.cwd());
+}
+async function compileAcceptance(args2, cwd) {
+  const options = parseCompileOptions(args2);
+  const specFiles = await findSpecFiles(cwd, options.specPatterns);
+  if (specFiles.length === 0) {
+    throw new Error(`No acceptance specs matched: ${options.specPatterns.join(", ")}`);
+  }
+  const documents = specFiles.map((specFile) => {
+    const source = fs.readFileSync(specFile, "utf8");
+    return parseAcceptanceMarkdown(source, toPosixPath(path.relative(cwd, specFile)));
+  });
+  const outPath = path.resolve(cwd, options.outPath);
+  const stepsImportPath = createStepsImportPath(outPath, path.resolve(cwd, options.stepsPath));
+  const generated = generatePlaywrightAcceptanceSpec(documents, { stepsImportPath });
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, generated);
+}
+function parseCompileOptions(args2) {
+  const specPatterns = collectFlagValues(args2, "--spec");
+  const stepsPath = requireFlagValue(args2, "--steps");
+  const outPath = requireFlagValue(args2, "--out");
+  if (specPatterns.length === 0) {
+    throw new Error("Missing required --spec <glob>");
+  }
+  return {
+    specPatterns,
+    stepsPath,
+    outPath
+  };
+}
+async function findSpecFiles(cwd, patterns) {
+  const files = await Promise.all(
+    patterns.map((pattern) => glob(pattern, { absolute: true, cwd, nodir: true }))
+  );
+  return files.flat().sort((left, right) => left.localeCompare(right));
+}
+function createStepsImportPath(outPath, stepsPath) {
+  const relativePath = toPosixPath(path.relative(path.dirname(outPath), stepsPath));
+  const extension = path.extname(relativePath);
+  const extensionlessPath = extension ? relativePath.slice(0, -extension.length) : relativePath;
+  if (extensionlessPath.startsWith(".")) {
+    return extensionlessPath;
+  }
+  return `./${extensionlessPath}`;
+}
+function collectFlagValues(args2, flag) {
+  const values = [];
+  args2.forEach((arg, index) => {
+    if (arg === flag) {
+      const value = args2[index + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error(`Missing value for ${flag}`);
+      }
+      values.push(value);
+    }
+  });
+  return values;
+}
+function requireFlagValue(args2, flag) {
+  const value = collectFlagValues(args2, flag).at(0);
+  if (!value) {
+    throw new Error(`Missing required ${flag} <path>`);
+  }
+  return value;
+}
+function toPosixPath(value) {
+  return value.split(path.sep).join(path.posix.sep);
+}
+
 // src/shared/resolve/repoRoot.ts
 import { resolve as resolve3 } from "node:path";
 
@@ -872,7 +1098,7 @@ function runBoundariesCli(rawArgs, dependencies = DEFAULT_DEPENDENCIES) {
 
 // src/crap/analysis/run.ts
 import { existsSync as existsSync6 } from "fs";
-import * as path2 from "path";
+import * as path3 from "path";
 
 // src/crap/analysis/calculate.ts
 function calculateCrap(complexity, coverage) {
@@ -998,7 +1224,7 @@ function extractFunctions(sourceFile) {
 
 // src/crap/analysis/fileSelection.ts
 import { readFileSync as readFileSync4 } from "fs";
-import * as path from "path";
+import * as path2 from "path";
 import * as ts7 from "typescript";
 function matchesFilterScope(relativePath, filterScope) {
   if (!filterScope) {
@@ -1010,7 +1236,7 @@ function matchesFilterScope(relativePath, filterScope) {
   return relativePath.startsWith(`${filterScope}/`);
 }
 function shouldIncludeFile(filePath, filterScope, repoRoot) {
-  const relativePath = toPosix(path.relative(repoRoot, filePath));
+  const relativePath = toPosix(path2.relative(repoRoot, filePath));
   if (!matchesFilterScope(relativePath, filterScope)) {
     return false;
   }
@@ -1022,7 +1248,7 @@ function shouldIncludeFile(filePath, filterScope, repoRoot) {
     repoRoot,
     workspacePackage.name,
     "crap",
-    toPosix(path.relative(workspacePackage.root, filePath))
+    toPosix(path2.relative(workspacePackage.root, filePath))
   );
 }
 function createSourceFile3(filePath) {
@@ -1058,7 +1284,7 @@ function analyzeCoverageEntry(filePath, fileCoverage, repoRoot, threshold) {
       complexity: fn.complexity,
       coverage: Math.round(coverage),
       crap: Math.round(crap * 100) / 100,
-      file: toPosix(path2.relative(repoRoot, fn.file)),
+      file: toPosix(path3.relative(repoRoot, fn.file)),
       line: fn.line,
       name: fn.name
     };
@@ -1181,11 +1407,11 @@ function createCoverageProfiles(repoRoot, target) {
 
 // src/crap/coverage/read.ts
 import { existsSync as existsSync7, readFileSync as readFileSync5 } from "fs";
-function readCoverageReport(path3) {
-  if (!existsSync7(path3)) {
-    throw new Error(`Coverage data not found: ${path3}`);
+function readCoverageReport(path4) {
+  if (!existsSync7(path4)) {
+    throw new Error(`Coverage data not found: ${path4}`);
   }
-  return JSON.parse(readFileSync5(path3, "utf-8"));
+  return JSON.parse(readFileSync5(path4, "utf-8"));
 }
 
 // src/crap/report.ts
@@ -1665,7 +1891,7 @@ function parseBareMutationTargetArg(args2) {
   }
   return void 0;
 }
-function collectFlagValues(args2, name) {
+function collectFlagValues2(args2, name) {
   const values = [];
   for (let index = 0; index < args2.length; index += 1) {
     const arg = args2[index];
@@ -1692,11 +1918,11 @@ function parseJsonStringArray(value, flagName) {
 }
 function mutationRunOptions(args2) {
   const mutateGlobs = [
-    ...collectFlagValues(args2, "--mutate-glob"),
+    ...collectFlagValues2(args2, "--mutate-glob"),
     ...parseJsonStringArray(flagValue(args2, "--mutate-globs-json"), "--mutate-globs-json")
   ];
   const testIncludes = [
-    ...collectFlagValues(args2, "--test-include"),
+    ...collectFlagValues2(args2, "--test-include"),
     ...parseJsonStringArray(flagValue(args2, "--test-includes-json"), "--test-includes-json")
   ];
   return {
@@ -2754,7 +2980,7 @@ function runReachabilityCli(rawArgs, dependencies = DEFAULT_DEPENDENCIES4) {
 }
 
 // src/scrap/analysis/pipeline/run.ts
-import * as fs from "fs";
+import * as fs2 from "fs";
 import * as ts25 from "typescript";
 
 // src/scrap/test/discovery/files.ts
@@ -4100,8 +4326,8 @@ function compareBlockSummaries(left, right) {
 
 // src/scrap/structure/blocks/groups.ts
 var BLOCK_SEPARATOR = "";
-function blockPathKey(path3) {
-  return path3.join(BLOCK_SEPARATOR);
+function blockPathKey(path4) {
+  return path4.join(BLOCK_SEPARATOR);
 }
 function blockPathFromKey(key) {
   return key.split(BLOCK_SEPARATOR);
@@ -4127,7 +4353,7 @@ function averageScore2(examples) {
 function countExamples2(examples, predicate) {
   return examples.filter(predicate).length;
 }
-function summarizeBlock(path3, examples) {
+function summarizeBlock(path4, examples) {
   const meanScore = averageScore2(examples);
   const maxScore2 = examples.reduce((max, example) => Math.max(max, example.score), 0);
   const hotExampleCount2 = countExamples2(examples, (example) => example.score >= 8);
@@ -4142,8 +4368,8 @@ function summarizeBlock(path3, examples) {
     hotExampleCount: hotExampleCount2,
     lowAssertionExampleCount: countExamples2(examples, (example) => example.assertionCount <= 1),
     maxScore: maxScore2,
-    name: path3[path3.length - 1],
-    path: path3,
+    name: path4[path4.length - 1],
+    path: path4,
     remediationMode: remediationMode(examples.length, meanScore, hotExampleCount2, maxScore2),
     zeroAssertionExampleCount: countExamples2(examples, (example) => example.assertionCount === 0)
   };
@@ -4521,7 +4747,7 @@ function analyzeScrapFile(sourceFile) {
 // src/scrap/analysis/pipeline/run.ts
 function analyzeScrap(target) {
   return discoverTestFiles(target).map((filePath) => {
-    const source = fs.readFileSync(filePath, "utf-8");
+    const source = fs2.readFileSync(filePath, "utf-8");
     const sourceFile = ts25.createSourceFile(
       filePath,
       source,
@@ -4677,8 +4903,8 @@ function resolveScrapPolicy(args2) {
 }
 
 // src/scrap/report/blocks/format.ts
-function formatBlockPath(path3) {
-  return path3.join(" > ");
+function formatBlockPath(path4) {
+  return path4.join(" > ");
 }
 function interestingBlocks(metric) {
   return metric.blockSummaries.filter((block) => block.remediationMode !== "STABLE").slice(0, 5);
@@ -4896,6 +5122,7 @@ function runScrapCli(rawArgs, dependencies = DEFAULT_DEPENDENCIES5) {
 
 // src/cli/main.ts
 var COMMANDS = {
+  acceptance: runAcceptanceCli,
   boundaries: runBoundariesCli,
   crap: runCrapCli,
   init: runInitCli,
@@ -4909,6 +5136,7 @@ function printHelp() {
 
 Commands:
   init          Create a starter quality.config.json
+  acceptance    Compile human-authored acceptance specs into executable tests
   organize     Check folder structure, naming, and cohesion
   boundaries   Check package/layer boundaries
   reachability Check dead surfaces and dead ends

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poleski/quality-tools",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "type": "module",
   "description": "Portable TypeScript quality checks for project structure, complexity, mutation, and test health",
   "license": "MIT",
@@ -47,6 +47,7 @@
     "changeset": "changeset",
     "cli": "tsx src/cli/main.ts",
     "quality-tools": "pnpm run cli",
+    "acceptance": "tsx src/cli/acceptance.ts",
     "boundaries": "tsx src/cli/boundaries.ts",
     "reachability": "tsx src/cli/reachability.ts",
     "crap": "tsx src/cli/crap.ts",